From: kimhj.kim Date: Mon, 6 Jul 2015 09:56:14 +0000 (+0900) Subject: LB reviewed with UI guide sepacation X-Git-Tag: tizen_3.0/TD_SYNC/20161201~737 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=6e40517a6f6a127b3fd48e71a1fe45be4ecc7578;p=sdk%2Fonline-doc.git LB reviewed with UI guide sepacation Change-Id: I68392a2364576622b7f7a537ea07972fee923add Signed-off-by: kimhj.kim --- diff --git a/org.tizen.devtools/.project b/org.tizen.devtools/.project index a35a122..543c836 100644 --- a/org.tizen.devtools/.project +++ b/org.tizen.devtools/.project @@ -1,22 +1,22 @@ - - - org.tizen.devtools_2.4.0 - - - - - - org.eclipse.pde.ManifestBuilder - - - - - org.eclipse.pde.SchemaBuilder - - - - - - org.eclipse.pde.PluginNature - - + + + org.tizen.devtools_2.4.0 + + + + + + org.eclipse.pde.ManifestBuilder + + + + + org.eclipse.pde.SchemaBuilder + + + + + + org.eclipse.pde.PluginNature + + diff --git a/org.tizen.devtools/META-INF/MANIFEST.MF b/org.tizen.devtools/META-INF/MANIFEST.MF index bf52ba8..a0f882c 100644 --- a/org.tizen.devtools/META-INF/MANIFEST.MF +++ b/org.tizen.devtools/META-INF/MANIFEST.MF @@ -1,7 +1,7 @@ -Manifest-Version: 1.0 -Bundle-ManifestVersion: 1 -Bundle-Name: Tizen Tools -Bundle-SymbolicName: org.tizen.devtools;singleton=true -Bundle-Version: 2.4.0 -Bundle-Vendor: The Linux Foundation - +Manifest-Version: 1.0 +Bundle-ManifestVersion: 1 +Bundle-Name: Tizen Tools +Bundle-SymbolicName: org.tizen.devtools;singleton=true +Bundle-Version: 2.4.0 +Bundle-Vendor: The Linux Foundation + diff --git a/org.tizen.devtools/build.properties b/org.tizen.devtools/build.properties index 5c90a0d..2becf8e 100644 --- a/org.tizen.devtools/build.properties +++ b/org.tizen.devtools/build.properties @@ -1,8 +1,8 @@ -bin.includes = plugin.xml,\ - META-INF/,\ - html/,\ - build.properties,\ - .project,\ - about.html,\ - index.xml - +bin.includes = plugin.xml,\ + META-INF/,\ + html/,\ + build.properties,\ + .project,\ + about.html,\ + index.xml + diff --git a/org.tizen.devtools/html/common_tools/certificate_registration.htm b/org.tizen.devtools/html/common_tools/certificate_registration.htm index b9c60fc..38ed441 100644 --- a/org.tizen.devtools/html/common_tools/certificate_registration.htm +++ b/org.tizen.devtools/html/common_tools/certificate_registration.htm @@ -1,66 +1,66 @@ - - - - - - - - - - - - - - Certificate Registration - - - - - -
-
- -
-
-

Mobile Web Wearable Web Mobile native Wearable native

-
- -

Certificate Registration

-

To build and debug projects, to run projects as applications on an Emulator, dynamic analyzer, or external devices, to create packages, or to launch applications, you must register an author certificate in the Tizen IDE.

-

To register an author certificate:

-
    -
  1. In the Tizen IDE, go to Window > Preferences > Tizen SDK > Security Profiles.
  2. -
  3. To add a signed profile, click Add in the Profiles panel.
  4. -
  5. Click Generate in the Author Certificate panel to generate an author certificate, if you do not have one.
  6. -
  7. In the Author Certificate panel, click Edit to set the author certificate path and password.
  8. -
-

To change distributor certificates, select a table item and then click Edit in the Distributor Certificate panel.

-

The first distributor certificate is required and the default information is filled automatically when a profile is created. The second distributor certificate is optional and is used only for special purposes. In general, you are not required to modify distributor certificates.

- -

Figure: Security Profiles

- -

Security Profiles

- - - -
- -Go to top - - - - - - - + + + + + + + + + + + + + + Certificate Registration + + + + + +
+
+ +
+
+

Mobile Web Wearable Web Mobile native Wearable native

+
+ +

Certificate Registration

+

To build and debug projects, to run projects as applications on an Emulator, dynamic analyzer, or external devices, to create packages, or to launch applications, you must register an author certificate in the Tizen IDE.

+

To register an author certificate:

+
    +
  1. In the Tizen IDE, go to Window > Preferences > Tizen SDK > Security Profiles.
  2. +
  3. To add a signed profile, click Add in the Profiles panel.
  4. +
  5. Click Generate in the Author Certificate panel to generate an author certificate, if you do not have one.
  6. +
  7. In the Author Certificate panel, click Edit to set the author certificate path and password.
  8. +
+

To change distributor certificates, select a table item and then click Edit in the Distributor Certificate panel.

+

The first distributor certificate is required and the default information is filled automatically when a profile is created. The second distributor certificate is optional and is used only for special purposes. In general, you are not required to modify distributor certificates.

+ +

Figure: Security Profiles

+ +

Security Profiles

+ + + +
+ +Go to top + + + + + + + diff --git a/org.tizen.devtools/html/common_tools/connection_explorer.htm b/org.tizen.devtools/html/common_tools/connection_explorer.htm index ba98ea7..40468d5 100644 --- a/org.tizen.devtools/html/common_tools/connection_explorer.htm +++ b/org.tizen.devtools/html/common_tools/connection_explorer.htm @@ -1,108 +1,108 @@ - - - - - - - - - - - - - - Connection Explorer View - - - - - -
- -

Connection Explorer View

- -

You can test Tizen applications with connected devices by using the following alternative ways:

-
    -
  • Testing applications on a physical device connected to the host system.
  • -
  • Testing them on an Emulator that emulates a real device as a software component installed on the host computer.
  • -
  • A list of connected devices is available in the Connection Explorer view after connecting a device or launching a Tizen Emulator with a tree view.
- -

The Connection Explorer view shows the devices connected to the system. It provides the following actions for using connected devices:

-
    -
  • Show connected devices
  • -
  • Provide file operations on connected devices
  • -
  • Send or receive files between the Project Explorer view and Connection Explorer view by dragging and dropping them between the views
  • -
  • Explore the file system on connected devices
  • -
  • Launch the Emulator Manager to handle the Emulator with multi-instances
  • -
-

Figure: Connection Explorer view

-

Connection Explorer view

- -

Testing with a Target Device

-

You can test your application by running and debugging it on a real target device:

-
    -
  • Connect your device to the host system by using a USB connector. The device icon (Device icon) is displayed in the Connection Explorer view.
  • -
  • Select the device in the Connection Explorer view. It is ready to be run and used to test your project.
- -

Testing with the Emulator

-

You can test your application by running and debugging it on the Emulator.

-

To start the Emulator, click the Emulator Manager icon on the toolbar, select the Emulator in the Emulator Manager, and click Launch.

- -

The Emulator icon (Emulator icon) is displayed in the Connection Explorer view, and the Emulator is ready for testing the application.

- - -

Transferring Files with Connected Devices

- -

You can transfer files between the connected devices and the host system:

-
    -
  • To transfer a file from a connected device to the host file system, pull the selected file to the desired host system path. -
  • -
  • To transfer a file from the host file system to a connected device, push the selected file to the desired connected device path. -
- -

Setting Preferences

-

You can set the following Connection Explorer preferences:

-
    -
  • Change the Emulator Manager path
  • -
  • Set the file transfer timeout value
  • -
- -

To set the Connection Explorer preferences, right-click the project and select Preferences > Tizen SDK > Tools > Connection Explorer.

- - - - -
- -Go to top - - - - - - - + + + + + + + + + + + + + + Connection Explorer View + + + + + +
+ +

Connection Explorer View

+ +

You can test Tizen applications with connected devices by using the following alternative ways:

+
    +
  • Testing applications on a physical device connected to the host system.
  • +
  • Testing them on an Emulator that emulates a real device as a software component installed on the host computer.
  • +
  • A list of connected devices is available in the Connection Explorer view after connecting a device or launching a Tizen Emulator with a tree view.
+ +

The Connection Explorer view shows the devices connected to the system. It provides the following actions for using connected devices:

+
    +
  • Show connected devices
  • +
  • Provide file operations on connected devices
  • +
  • Send or receive files between the Project Explorer view and Connection Explorer view by dragging and dropping them between the views
  • +
  • Explore the file system on connected devices
  • +
  • Launch the Emulator Manager to handle the Emulator with multi-instances
  • +
+

Figure: Connection Explorer view

+

Connection Explorer view

+ +

Testing with a Target Device

+

You can test your application by running and debugging it on a real target device:

+
    +
  • Connect your device to the host system by using a USB connector. The device icon (Device icon) is displayed in the Connection Explorer view.
  • +
  • Select the device in the Connection Explorer view. It is ready to be run and used to test your project.
+ +

Testing with the Emulator

+

You can test your application by running and debugging it on the Emulator.

+

To start the Emulator, click the Emulator Manager icon on the toolbar, select the Emulator in the Emulator Manager, and click Launch.

+ +

The Emulator icon (Emulator icon) is displayed in the Connection Explorer view, and the Emulator is ready for testing the application.

+ + +

Transferring Files with Connected Devices

+ +

You can transfer files between the connected devices and the host system:

+
    +
  • To transfer a file from a connected device to the host file system, pull the selected file to the desired host system path. +
  • +
  • To transfer a file from the host file system to a connected device, push the selected file to the desired connected device path. +
+ +

Setting Preferences

+

You can set the following Connection Explorer preferences:

+
    +
  • Change the Emulator Manager path
  • +
  • Set the file transfer timeout value
  • +
+ +

To set the Connection Explorer preferences, right-click the project and select Preferences > Tizen SDK > Tools > Connection Explorer.

+ + + + +
+ +Go to top + + + + + + + diff --git a/org.tizen.devtools/html/common_tools/emulator.htm b/org.tizen.devtools/html/common_tools/emulator.htm index 15f3b54..90031a1 100644 --- a/org.tizen.devtools/html/common_tools/emulator.htm +++ b/org.tizen.devtools/html/common_tools/emulator.htm @@ -1,1614 +1,1624 @@ - - - - - - - - - - - - - - Emulator - - - - - - -
- -

Emulator

- -

The Tizen SDK includes a virtual device Emulator. The Emulator provides the full stacks of the Tizen platform so that you can test Tizen applications before deploying them to the real target device. The Emulator is based on the open source QEMU project and comprises virtual CPU, memory, and various peripherals. Currently, the Tizen SDK only supports the x86 machine architecture for guest. You can use the Emulator Manager to create and launch a Virtual Machine instance. You can communicate with the Emulator instance using the Smart Development Bridge (SDB).

- -

The main features of the Emulator are:

-
    -
  • Providing full system emulation, including CPU, memory, and peripheral devices
  • -
  • Simulating events with the Emulator Control Panel
  • -
  • Accelerating guest operations using host CPU or GPU
  • -
- -

For more information see Supported Features.

- -

Using the Emulator

- -

To run applications on the Emulator:

- -
    -
  1. Start the Emulator through the Emulator Manager. -

    You can launch the Emulator from both the Emulator Manager and the command line. If you are using the command line, you can modify the start-up options.

  2. -
  3. While running the Emulator, you can use the control keys and context menu or the Emulator Control Panel to control the Emulator. You can use extended features while running applications, such as a shared directory, multi-point touch, and a Webcam.
  4. -
- -

Emulator Manager

- -

To start the Emulator quickly:

-
    -
  1. Start the Emulator Manager -
      -
    • By using the Desktop or Start menu: -
      - - - - - - - - - - - - - - - - - - -
      LinuxWindowsMacOS
      Desktop > Applications > Emulator ManagerStart > All Programs > Tizen SDK > Emulator ManagerFinder > Applications > Tizen SDK > Emulator Manager
      linux shortcut windows shortcut macos shortcut
      -
    • -
    • By using the Tizen IDE: Connection Explorer > Emulator Manager Icon -

                                          - Launch -
    • -
    -
  2. -
  3. Select your preferred profile tab, such as mobile or wearable.
  4. -
  5. Select Create New and click Confirm.
  6. -
  7. Click the Launch button ( Launch ) or press the ENTER keyboard key.
  8. -
  9. To stop the Emulator, right-click the Emulator and select Close.
  10. -
- - -

Figure: Emulator Manager

-

Emulator Manager

- - - - - - - - - - -
Note
To run the application faster, switch on CPU VT and GPU. If CPU VT is disabled, check the Using Hardware Virtualization section for more information. If GPU is disabled, install the latest vendor-provided graphic driver.
- -

You can also create a new virtual machine (VM) with the Emulator Manager CLI.

- -

The created VM is added under the current tab. The name of tab, <Profile>, refers to the image profile. You can create a VM by using a custom image in Base Image of the detail view. The background color of a custom VM is blue.

- -

You can also export a base image of the VM and manipulate the VM:

-
    -
  • To create a VM, select Create New and click Confirm.
  • -
  • To create a base image of a VM, select the VM and Export as, and enter a name and location for the base image.
  • -
  • To modify a VM, click the Modify icon ( Modify icon ), make the appropriate changes, and click Confirm.
  • -
  • To delete a VM, click Delete or press the DELETE keyboard key (fn + Delete in Mac OS® X).
  • -
  • To launch a VM, click the Launch button ( Launch ) or press the ENTER keyboard key.
  • -
- - -

Virtual Machine

-

A virtual machine (VM) is a set of hardware options including the file system image. The Emulator Manager controls the virtual machines. When you launch the Emulator, you can specify the VM that you want to customize. Each VM has its own Emulator file system image. In other words, different VMs have different states of Emulators.

- - - - - - - - - - -
Note
If you update the EMULATOR_IMAGE package on Tizen SDK Install Manager, existing VMs are not launched properly as the Base Image file is modified. To use the existing VMs after updating, the Emulator Manager provides the 'creating a base image' feature through the Export as button. With this functionality, you can keep the existing VMs in the new Base Image.
- -

You can set the following VM details:

-
    -
  • Name -

    The following rules apply for naming a VM:

    -
      -
    • The length of the name must be at most 20 characters.
    • -
    • Different VMs must not have the same name.
    • -
    • Only the following characters are accepted: -, _, 0-9, a - z, and A - Z
    • -
  • - -
  • Base Image -

    You can use the default base image. You can also change the base image and choose another image when you create a VM by clicking Create New under the "mobile-custom/wearable-custom" tab folder. This new VM is added under the "each custom" group. The correct image file extension of the custom base image is .x86.

  • - -
  • Display Resolution -

    Note that the following resolution has its own default display density.

    -
      -
    • Mobile -
        -
      • 480 x 800 (WVGA)
      • -
      • 540 x 960 (qHD)
      • -
      • 720 x 1280 (HD)
      • -
    • -
    • Wearable -
        -
      • 320 x 320
      • -
      • 360 x 360
      • -
      • 360 x 480
      • -
    • -
    -
  • - -
  • Display Density -

    DPI (Dots Per Inch) value of the Emulator. The DPI depends on the display resolution.

    -
      -
    • Mobile -
        -
      • 233 (480 x 800)
      • -
      • 220 (540 x 960)
      • -
      • 306 (720 x 1280)
      • -
    • -
    • Wearable -
        -
      • 316 (320 x 320)
      • -
      • 302 (360 x 360)
      • -
      • 300 (360 x 480)
      • -
    • -
    -
  • - -
  • Skin -

    The VM UI style. Select 1 or more of the available skins. The skin depends on the display resolution.

  • - -
  • Processors -

    The number of CPUs.

  • - - -
  • RAM Size -

    The RAM size.

    - - - - - - - - - - - -
    Note
    In Windows®, only the 512 MB size is available.
    - -
      -
    • 512 MB
    • -
    • 768 MB
    • -
    • 1024 MB
    • -
  • - -
  • File Sharing -

    You can share a directory between the host PC and the Emulator. If you want to use this feature, set the value to ON and define the input directory to share in the directory field. For more information, see Sharing a Directory.

  • - -
  • CPU VT -

    The Emulator supports hardware virtualization. It is kvm on Ubuntu and HAX on Windows®. If the host CPU supports hardware virtualization and a hardware virtualization module is installed, you can change this value. For more information, see Using Hardware Virtualization.

  • - -
  • GPU -

    The Emulator supports hardware OpenGL® acceleration. If the host graphic card driver supports hardware acceleration and you select ON, the feature operates properly. Otherwise, do not try to make the Emulator support hardware acceleration. If the GPU option is enabled, the rendering performance of the video player or camera can degrade.

    -
  • - -
  • Advanced Option -

    You can attach and detach devices.

    -
      -
    • Mobile -
        -
      • Sensor: accelerometer, gyroscope, geo-magnetic, proximity, light, haptic, pressure, ultraviolet, heartbeat rate meter
      • -
      • Device: camera, battery
      • -
      • Jack: ear jack, charger, USB
      • -
    • -
    • Wearable -
        -
      • Sensor: accelerometer, gyroscope, geomagnetic, proximity, light, haptic, pressure, ultraviolet, heartbeat rate meter
      • -
      • Device: camera, battery
      • -
      • Jack: charger, USB
      • -
    • -
    -
  • - -
- -

Emulator Manager CLI

- -

You can create, modify, delete, and list your VMs through the command line interface commands. The CLI binary is located in:

-
    -
  • In Linux: -

    <TIZEN_SDK>/tools/emulator/bin/em-cli

  • -
  • In Windows®: -

    <TIZEN_SDK>\tools\emulator\bin\em-cli.bat

  • -
- -

For more information, see the CLI help messages.

- -

Figure: Emulator Manager command line

-

Emulator Manager command line

- - -

Using Hardware Virtualization

- -

To run the application faster, the Tizen x86 Emulator exploits KVM (Kernel-based Virtual Machine in Linux) or HAX (Hardware Accelerated eXecution in Windows® and Mac OS® X) with HW virtualization support.

-

If the CPU VT is disabled in the Detail view on the Emulator Manager, check the following prerequisites and install KVM or HAX.

- - -

Prerequisites

- -

To use HW virtualization, you need:

- -
    -
  • In Linux: -

    To use KVM, you need a processor that supports HW virtualization. Both Intel and AMD have developed those extensions for their processors (Intel VT-x/AMD-V). Check whether the CPU supports HW virtualization with the following command:

    -
    -$egrep -c '(vmx|svm)' /proc/cpuinfo
    - -

    If the output of the command is 0, the CPU does not support HW virtualization. Otherwise, it does.

    -

    The HW virtualization feature can also be disabled on the BIOS setting; check the setting and enable it if you need the feature.

  • - -
  • In Windows®: -

    To use HAX, you need Intel VT-x-supported CPU, and you must enable the NX-related setting in the PC BIOS.

  • - -
  • In Mac OS® X: -

    To use HAX, install EFI-related updates on your Intel-based Mac system. For more information, see EFI and SMC firmware updates for Intel-based Macs.

  • -
- - -

Installing KVM or HAX

- -

To install KVM or HAX:

- -
    -
  • In Linux: -

    No installation is required for KVM.

    -
  • -
  • In Windows® and Mac OS® X: -

    The HAXM driver is installed during the Tizen SDK installation. See the installation manual on the Tizen developer site.

    - - - - - - - - - - -
    Note
    -

    If the installation fails with a VT-related message, check the CPU feature and BIOS settings. If the installation fails with an NX-related message, enable NX (or PAE and DEP) -related item in the BIOS. In addition, make sure that the operating system supports the NX feature (for more information, see MSDN).

    -
- -

No configuration is required for KVM or HAX.

- - -

Running the Emulator

-

To run the Emulator with HW virtualization support in the Emulator Manager, set the CPU VT field to ON. The field is disabled if your system cannot support HW virtualization.

-

You can also run the Emulator with HW virtualization support from the command line, by including the -enable-kvm (in Linux) or -enable-hax (in Windows® and Mac OS® X) option in the start-up command.

- - -

Emulator Control Keys and Menu

- -

The Tizen Emulator provides a variety of control keys and menus.

- -

Profile-specific Skin

-

The profile-specific skin has a real device-shaped image frame, and its hardware keys are on the main window skin. You can configure the profile-specific skin.

- - -

Figure: Profile-specific skin Emulator

- -

Profile-specific skin Emulator Mobile Profile-specific skin Emulator Wearable O Profile-specific skin Emulator Wearable

- -

General Purpose Skin

-

The image of the general purpose skin is generated by nine-patch image processing. The Emulator skin frame has the same appearance on every state of resolution, scale, or rotation. Unlike the profile-specific skin, the layout of the general purpose skin is not configurable.

- -
    -
  • Key window -

    The key window displays an independent hardware key input window, which can be moved to any position on the screen or docked to the left or right side of the main window. If the key window is docked with the main window, both windows can be moved together on the screen.

    -
  • -
  • Pair tag -

    The pair tag indicates that the Emulator main window and key window are in a pair. This tag is activated when the key window is open. The pair tag color changes every time the Emulator boot occurs.

    -
  • -
- -

The following figure illustrates the general purpose skin Emulator.

- -

Figure: General purpose skin Emulator

-

General purpose skin Emulator Mobile General purpose skin Emulator Wearable

- - - -

Control Keys

-

The following keys are available on the Emulator:

-
    -
  • Menu (mobile only) -

    When you tap, it opens a list of options available for the current screen.

    -
  • -
  • Home (mobile only) -

    If you long press the Home key, the Task switcher application appears as in a real device.

    -
  • -
  • Back (mobile only) -

    When you tap, it returns to the previous screen.

    -
  • -
  • Power -

    You can power off the display by clicking the Power key in most general situations. - Sometimes, the display does not power off though you click the Power key. - This is to guarantee the operation of a current application, such as the Stopwatch in the Clock App. - If you click Power or Home key again, the display is powered on.

    -
  • -
  • Volume Up and Volume Down (mobile only) -

    You can control the volume with the Volume Up and Volume Down keys.

    -
  • -
- - - - -

You can access the context menu by right-clicking on the Emulator. In the menu, you can select:

- -
    -
  • Emulator name (the top row in the menu) -

    Display the Detailed Info window, showing the Shortcut Info and VM Info tabs. The Shortcut Info tab lists the Emulator keyboard shortcuts and the VM Info tab defines the virtual machine details.

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Table: VM Info tab
    FeatureDescription
    VM NameVM name
    Skin NameSkin name
    CPUCPU architecture
    RAM SizeRAM size (MB)
    Display ResolutionTarget display resolution
    Display DensityDPI (Dots Per Inch)
    Directory SharingWhether host directory sharing is used
    File Shared PathPath to the shared host directory
    CPU VirtualizationWhether hardware virtualization is supported
    GPU VirtualizationWhether GPU virtualization is supported
    Image Path 1Target image path
    Image Path 2Swap image path
    Log PathEmulator log file path
    -
  • - -
  • Always On Top -

    Select this option to keep the Emulator window on top of other windows.

    - - - - - - - - - - -
    Note
    The Always On Top feature is not supported in Mac OS® X.
    -
  • -
  • Rotate -

    Select either Portrait, Landscape, Reverse Portrait, or Reverse Landscape as the orientation of the Emulator.

  • - -
  • Scale (mobile only) -

    Scale the size of the Emulator between 1x, 1/2x (default), 3/4x, and 1/4x.

  • - -
  • Advanced > Controller -

    Show or hide the controller window.

    - - - - - - - - - -
    Note
    The Controller menu is not supported in the profile-specific skin.
  • -
  • Advanced > Screenshot -

    Capture a screenshot of the Emulator.

  • - -
  • Advanced > About -

    Display the Emulator version, build time, and git version.

  • - -
  • Advanced > Force Close -

    Force the Emulator to exit. Since force stopping the Emulator can cause problems, use the Close option to exit the Emulator. Use Force Close only when absolutely necessary.

  • - -
  • Shell -

    Open a Smart Development Bridge (SDB) shell command window.

  • - -
  • Control Panel -

    Help to control or monitor the state of the Emulator dynamically.

  • - -
  • Close -

    Exit the Emulator.

  • - -
- - - - - - - - - - -
Note
In Ubuntu, you need to change a global GNOME setting to view the menu icons: -
    -
  1. In the command console, execute the gconf-editor command.
  2. -
  3. In the tree, navigate to desktop > gnome > interface.
  4. -
  5. Enable the menus_have_icons option.
  6. -
-
- - -

Emulator Control Panel

- -

You can execute the Emulator Control Panel (ECP) by selecting Control Panel on the Context Menu after the Emulator is successfully launched. You can control and monitor the state of the Emulator dynamically.

-

The main features of ECP:

-
    - -
  • Device Manager -

    The following table lists the Device Manager features and their availability on different profiles.

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Table: Device Manager features
    FeatureMobileWearableDescription
    Device TreeYesNoThe Device Tree is a data structure for describing hardware. - You can see the device information that actually loaded in the main system bus. - It shows a simple tree structure of nodes and properties. Nodes are generally a device or another bus. - Properties are key-value pairs where the value can either be empty or contain an arbitrary byte stream.
    NetworkYesYesYou can view a network device list and control the user network. - To forward a remote or local port to an inside port of the Emulator, click Add port–forwarding, - enter values in text boxes, and click Apply port–forwarding.
    Host Directory SharingYesYesThe specified host directory is mounted to /mnt/host to share resources. Therefore, the file transfer is possible through the host directory sharing feature without using the sdb utility.
  • - -
  • App Manager -

    The following table lists the App Manager features and their availability on different profiles.

    - - - - - - - - - - - - - - - - - - - - -
    Table: App Manager features
    FeatureMobileWearableDescription
    UninstallerNoYesYou can see user-installed applications and uninstall them.
    -
  • - - -
  • Event Injector -

    The following table lists the Event Injector features and their availability on different profiles.

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Table: Event Injector features
    FeatureMobileWearableDescription
    BatteryYesYesYou can set the battery level using the Level slider. - To set the charger status to connected or disconnected, select the appropriate Charger radio button.
    RSSIYesNoYou can set the remote signal strength using the level bar.
    Sensor3-Axis SensorYesYesYou can inject user acceleration, magnetic, and gyroscope values using slider bars or text input.
    LightYesYesYou can inject a lux value into light sensor. - If you set brightness as auto, then display will be changed by injecting light value.
    ProximityYesYesYou can inject the presence of nearby objects.
    PressureYesYesYou can inject a hPa value into the pressure sensor.
    UltravioletYesYesYou can inject an ultraviolet index.
    Heart Rate MonitorYesYesYou can inject the heart rate and peek-to-peek time in milliseconds.
    Ear JackYesNo You can inject adding or removing headset.
    GestureNoYesYou can inject flick up (menu button) or flick down (back button) events in the wearable profile.
    USBYesYesYou can add or remove a USB device by setting the USB device setting to the connected or disconnected state.
    SD CardYesNoYou can inject a 4, 8, 16, or 32G SD card.
    LocationYesYesYou can inject a latitude and longitude values using a map, manually, or from a log file.
    TelephonyYesYesYou can make and receive a call through the Call tab. You can also send and receive SMS messages through the SMS tab.
    MemoryYesYesYou can set the low memory status using the radio buttons.
    -
  • -
- -

Various keyboard shortcuts are available to execute ECP tasks.

- - -

Emulator Control Panel CLI

- -

You can control and monitor the Tizen Emulator by using ECP CLI instead of the ECP UI tool. The ECP CLI supports all the functionalities of the ECP UI. The CLI binary is located at:

-
    -
  • In Linux: -

    <TIZEN_SDK>/tools/emulator/bin/ecp-cli

  • -
  • In Windows®: -

    <TIZEN_SDK>\tools\emulator\bin\ecp-cli.bat

  • -
- -

You can use the CLI in a session mode or shell mode:

-
  • Session mode -

    You can access this mode by running the binary without any parameters. The mode keeps a session until it is exited. You can exit by entering the exit command.

  • -
  • Shell mode -

    This mode is used for one-time message handling.

-

Figure: Session and shell modes

-

Session and shell modes

- -

In Linux, the bash-based auto-completion is used with the TAB button.

- -

The following tables list the supported commands of the ECP CLI.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Table: CLI common commands
CommandSyntaxDescription
helphelp [device]To get help, type the command as help. For more a specific device help, use the device parameter.
keycodekeycode <key-code> [period|press|release]To enter a key code for a mobile device: -
  • 114: volume down
  • -
  • 115: volume up
  • -
  • 139: HOME
  • -
  • 158: BACK
  • -
  • 169: MENU
hmphmp <hmp command>Access the QEMU human monitor protocol commands. For a list of provided commands, enter the ecp-cli hmp help command.
qmpqmp <qmp command>Access the QEMU monitoring protocol. The commands are handled in the JSON format, and do not require { "execute": "qmp_capabilities" } to be in the control mode. -

In the shell mode, the shell does not support the double quotation mark (") as an argument. For the JSON arguments, use \" (back space + double quotation mark) instead.

hdshds mount <host path> <guest path>Enable the host directory sharing feature between the specified <host path> and the Emulator's <guest path>. The specified path must be a folder, not a file.
hds unmount <id>Unmount the mounted host directory sharing path. The id is the HDS ID and you can get it from the hds status command.
hds statusShow the current host directory sharing status.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Table: CLI profile commands
DeviceCommandMobileWearableSyntax
calldialYesNocall dial <number>
hidden-dialcall hidden-dial <number>
connectcall connect
disconnectcall disconnect <call id>
statuscall status
smssendYesNosms send <number> <text>
set statussms set <available | unavailable>
statussms status
mms_statussms mms_status
locationsetYesYeslocation set <longitude> <latitude>
statuslocation status
stoplocation stop
filelocation file <file-path>
batterylevelYesYesbattery level <percent>
chargerbattery charger <on | off>
statusbattery status
earjacksetYesNoearjack set <3wire | 4wire | off>
statusearjack status
usbsetYesYesusb set <on | off>
statususb status
rssisetYesNorssi set <0~4>
statusrssi status
SD cardattachYesNosdcard attach <sdcard_[ 4 | 8 | 16 | 32 ]G>
detachsdcard detach <sdcard_[ 4 | 8 | 16 | 32 ]G>
statussdcard status
sensoraccelerometerYesYessensor accelerometer <x> <y> <z>
gyroscopesensor gyroscope <x> <y> <z>
magneticsensor magnetic <x> <y> <z>
proximitysensor proximity <value>
lightsensor light <value>
pressuresensor pressure <level>
uvsensor uv <level>
hrmsensor hrm <level>
statussensor status [sensor]
filesensor file <sensor> <path>
- - -

Supported Features

- -

The Emulator provides various virtual H/W, media formats, codecs and OpenGL® ES acceleration. For better performance of the OpenGL® ES support, the Tizen Emulator exploits the latest feature of the graphic driver, so always install the latest vendor-provided graphic driver. The Emulator, however, has some limitations and differences compared to physical target devices.

- -

The following table lists the basic features supported in the Emulator.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Table: Supported Emulator features
FeatureDetailStatusNotes
Skin

Skins are fitted to the screen resolution:

-
    -
  • Mobile -
    • WVGA (480 x 800, default)
    • -
    • qHD (540 x 960)
    • -
    • HD (720 x 1280)
    • -
    -
  • -
  • Wearable -
    • 320 x 320
    • -
    • 360 x 360 (default)
    • -
    • 360 x 480
    • -
    -
  • -
- - -

4 orientation modes are supported:

-
    -
  • Portrait (default), landscape, reverse portrait, and reverse landscape
- -
Supported2 skin layout types are supported: -
    -
  • Profile-specific skin
  • -
  • General purpose skin
  • -
TouchMaru touchscreen deviceSupportedMulti-touch is supported.
KeyHW keys, host keyboard, and SW keypadSupportedThe host keyboard is not supported for the Wearable Emulator.
Rotary360 levels of clockwise or counter-clockwise rotationSupported-
DisplayVGA card with 100 levels of brightness controlSupported-
OpenGL® ESCompatible with OpenGL® ES 1.1 and 2.0 -

OpenGL® ES API pass-through via PCI

-
Supported -The OpenGL® ES 1.1 functionality is not guaranteed on the Emulator, unless the graphics hardware of your computer supports OpenGL® 1.5. -

The OpenGL® ES 2.0 functionality is not guaranteed on the Emulator, unless the graphics hardware of your computer supports OpenGL® 2.1.

-

The host machine must support OpenGL® 1.4.

SoundAC97 deviceSupportedAudio in: -
    -
  • Make sure that the input volume of the microphone is enough to record your voice or songs on the host machine.
  • - -
  • On Windows® 7, inject the microphone into the host machine before starting the Emulator.
- -

Audio out:

-
    -
  • On Windows® 7, enable at least 1 audio out device before starting the Emulator. Make sure that the volume icon in the tray is not disabled.
  • -
  • While the Emulator is running, do not disable the audio out device, as it can lock the audio system of the guest platform.
-
Network connectionVirtioSupportedRaw socket protocol, such as ICMP, is not supported.
Emulator Control PanelThe Emulator Control Panel (ECP) supports different features depending on the deice profile: -
    -
  • Mobile -
      -
    • Device Manager: Device Tree, Network, Host Directory Sharing
    • -
    • Event Injector: Battery, RSSI, 3-Axis Sensor, Light, Proximity, Pressure, Ultraviolet, Heart Rate Monitor, Motion, Ear Jack, USB, SDCard, Location, Telephony
    • -
    -
  • -
  • Wearable -
      -
    • Device Manager: Network, Host Directory Sharing
    • -
    • App Manager: Uninstaller
    • -
    • Event Injector: Battery, 3-Axis Sensor, Light, Proximity, Pedometer, Pressure, Ultraviolet, Heart Rate Monitor, Gesture, USB
    • -
    -
  • -
- -
SupportedThe Emulator Control Panel is a standalone tool, which replaces the Event Injector. It helps to control and monitor the Emulator features, and can be launched from the Emulator context menu.
Camera

Virtual camera device connecting a host machine's Webcam

-

Support: preview, capture, and record

-

Image format: YUYV, I420, and YV12

-

Attributes: brightness and contrast

-

Resolution: 160 x 120, 176 x 144, 320 x 240, 352 x 288, and 640 x 480

-

Video resolution: 1280 x 720 for the WVGA, 320 x 240 for the WQVGA, and 640 x 480 for the HVGA devices.

-

The supported video codecs are MPEG-4, H.263, H.264, and VC-1 for both encoding and decoding.

-
SupportedWhile recording a video using the Emulator, an audio-video synchronization error can occur depending on your computer hardware and performance.
Bluetooth-Not supported-
Wi-Fi-Not supported-
Wi-Fi Direct™-Not supported-
- -

OpenGL® ES Acceleration Support

- -

For the Emulator to support OpenGL® ES acceleration, you need:

-
    -
  • Graphics chipset driver that supports OpenGL® 1.4 installed on the host machine
  • -
  • All chipset vendors and driver versions available to support the OpenGL® 1.4 standard
  • -
- - - - - - - - - - - - -
Note
Emulator supports only ES 1.1, ES 2.0, and EGL™ 1.4 versions.
- -

Differences between the Emulator and Target

- -

The following tables describe the differences between a real target device and the Emulator. For more detailed information, see the differences in:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Table: Comparison summary
CategorySubjectPhysical targetEmulator
Development environmentTargetBuy a target device or reference board (by model)Download the SDK (multi-profile and multi-model support)
NetworkNeed BluetoothOnly the network environment
Target connectionUSBIPC (TCP/UDP)
Source and package managementSource and package for targetSource and package for the Emulator
Host Directory SharingNot supportedSupported
PortabilityScreen resolutionFixedConfigurable
RAM, storage sizeFixedConfigurable
2D and 3D acceleration APIGPU-dependentGPU-independent (common set)
CP, telephonyFully supportedPartially supported (only SMS and voice call)
Wi-FiFully supportedPartially supported (using ethernet)
SensorFully supportedPartially supported (using the Emulator Control Panel)
PnP, external connectionFully supportedPartially supported (using the Emulator Control Panel)
CameraFully supportedPartially supported (preview, capture, recording, contrast, and brightness)
Vibration, hapticFully supportedNot supported
BluetoothFully supportedNot supported
PerformanceCPU performanceMobile CPUDesktop CPU (with hardware virtualization)
GPU performanceReal GPUDesktop GPU (relatively slow)
I/O performanceReal HW I/OEmulated I/O (relatively slow)
- -

Input System

- - - - - - - - - - - - - - - - - - - - - - - - - -
Table: Input differences
CategoryPhysical targetEmulator
Touch screen panelReal device and driverVirtual (VirtIO) device and driver
Host keyboard and hardware keyReal device and driverVirtual (VirtIO) device and driver
- -

Graphics and display

- - - - - - - - - - - - - - - - - - - - - - - - - - -
Table: Graphics and display differences
CategoryPhysical targetEmulator
Framebuffer deviceDisplay controller in the processorVirtual VGA card
Backlight controlLDI (LCD Driver IC) commandAdditional virtual device and driver
- -

Virtual Sensor (Emulator Control Panel)

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Table: Virtual sensor differences
CategoryPhysical targetEmulator
SensorAccelerationReceives the actual acceleration value of the device.Receives the virtual acceleration value through the Emulator Control Panel. -

If the Emulator orientation is portrait, the acceleration values are approximately 0, -9.81, and 0 degrees.

GyroReceives the actual gyroscope value of the device.Receives the virtual gyroscope value through the Emulator Control Panel.
GeomagneticReceives the actual geomagnetic value of the device.Receives the virtual geomagnetic value through the Emulator Control Panel. -

If the Emulator orientation is portrait, the y axis points to true north and the magnetic tesla values are 1, 0, and -10 degrees.

ProximityReceives the actual proximity value of the device.Receives the virtual proximity value through the Emulator Control Panel. -

You can register an event handler for the proximity sensor and test it with the Emulator Control Panel. However, the screen does not power off during the event because the Emulator does not connect to the power manager.

-
LightReceives the actual ambient light value of the device.Receives the virtual ambient light value through the Emulator Control Panel. -

You can register an event handler for the light sensor and test it with the Emulator Control Panel. However, in order to test the screen brightness change, the brightness setting must be automatic in the setting application.

-
PressureReceives the actual pressure value of the device.Receives the virtual actual pressure value through the Emulator Control Panel. -
UltravioletReceives the actual ultraviolet value of the device.Receives the virtual actual ultraviolet value through the Emulator Control Panel. -
Heart Rate MonitorReceives the actual heart rate and peak-to-peak values of the device.Receives the virtual actual heart rate and peak-to-peak values through the Emulator Control Panel. -
DeviceBatteryReceives the actual battery value of the device.Receives the virtual battery value through the Emulator Control Panel. -

You can change the battery level and the charger connection status.

-
EarjackReceives the actual earjack connection event of the device.Receives the earjack connection event through the Emulator Control Panel. -

You can select a 3-wire or 4-wire connection, or set the earjack as disconnected.

-
USBReceives the actual USB connection event of the device.Receives the USB connection event through the Emulator Control Panel.
RSSIReceives the actual RSSI value of the device.Receives the virtual RSSI value through the Emulator Control Panel.
LocationLogSupported by lbsFW.Receives the virtual GPS log file through the Emulator Control Panel. -

You can use a log file of the NMEA format.

-
ManualNot supported.Receives the virtual longitude and latitude values through the Emulator Control Panel.
MapNot supported.Receives the virtual longitude, latitude, altitude, and horizontal accuracy values through the Emulator Control Panel map.
AutoReceives the actual GPS coordinates of the device.Not supported.
- - -

Telephony

- - - - - - - - - - - - - - - - - - - - - - - -
Table: Telephony differences
CategoryPhysical targetEmulator
TelephonyCallCalls and video calls are supported.Call waiting, outgoing call barring, and voice calls with the Emulator Control Panel are supported. -

Video calls, call forwarding, incoming call barring, and Emulator-to-Emulator calls are not supported.

SMSSMS messaging is supported.SMS messaging with the Emulator Control Panel is supported. -

Sending Emulator-to-Emulator SMS messages is not supported.

- - -

Power Management

- - - - - - - - - - - - - - - - - - - - - - - - -
Table: Power management differences
ModePhysical targetEmulator
Display on/offDisplay controller in the processorInternal emulation
Power offPower management in the processorACPI (Advanced Configuration and Power Interface)
- - -

Supported Media Formats and Codecs

- - - - - - - - - - - - - - - - - - -
Table: Media format and codec differences
CategoryPhysical targetEmulator
DecoderFLACSupportedNot supported
- - - - - -
- -Go to top - - - - - - - + + + + + + + + + + + + + + Emulator + + + + + + +
+ +

Emulator

+ +

The Tizen SDK includes a virtual device Emulator. The Emulator provides the full stacks of the Tizen platform so that you can test Tizen applications before deploying them to the real target device. The Emulator is based on the open source QEMU project and comprises virtual CPU, memory, and various peripherals. Currently, the Tizen SDK only supports the x86 machine architecture for guest. You can use the Emulator Manager to create and launch a Virtual Machine instance. You can communicate with the Emulator instance using the Smart Development Bridge (SDB).

+ +

The main features of the Emulator are:

+
    +
  • Providing full system emulation, including CPU, memory, and peripheral devices
  • +
  • Simulating events with the Emulator Control Panel
  • +
  • Accelerating guest operations using host CPU or GPU
  • +
+ +

For more information see Supported Features.

+ +

Using the Emulator

+ +

To run applications on the Emulator:

+ +
    +
  1. Start the Emulator through the Emulator Manager. +

    You can launch the Emulator from both the Emulator Manager and the command line. If you are using the command line, you can modify the start-up options.

  2. +
  3. While running the Emulator, you can use the control keys and context menu or the Emulator Control Panel to control the Emulator. You can use extended features while running applications, such as a shared directory, multi-point touch, and a Webcam.
  4. +
+ +

Emulator Manager

+ +

To start the Emulator quickly:

+
    +
  1. Start the Emulator Manager: +
      +
    • By using the Desktop or Start menu, go to: + + + + + + + + + + + + + + +
      UbuntuWindows®Mac OS®
      Desktop > Applications > Emulator Manager: +

      Ubuntu shortcut

      Start > All Programs > Tizen SDK > Emulator Manager: +

      Windows shortcut

      Finder > Applications > Tizen SDK > Emulator Manager: +

      Mac OS shortcut

      +
    • +
    • By using the Tizen IDE, click the Emulator Manager icon in the Connection Explorer view: +

      Launch

      +
    • +
    +
  2. +
  3. Select your preferred profile tab, such as mobile or wearable.
  4. +
  5. Select Create New and click Confirm.
  6. +
  7. Click the Launch button ( Launch ) or press the ENTER keyboard key.
  8. +
  9. To stop the Emulator, right-click the Emulator and select Close.
  10. +
+ + +

Figure: Emulator Manager

+

Emulator Manager

+ + + + + + + + + + +
Note
To run the application faster, switch on CPU VT and GPU. If CPU VT is disabled, check the Using Hardware Virtualization section for more information. If GPU is disabled, install the latest vendor-provided graphic driver.
+ +

You can also create a new virtual machine (VM) with the Emulator Manager CLI.

+ +

The created VM is added under the current tab. The name of tab, <Profile>, refers to the image profile. You can create a VM by using a custom image in Base Image of the detail view. The background color of a custom VM is blue.

+ +

You can also export a base image of the VM and manipulate the VM:

+
    +
  • To create a VM, select Create New and click Confirm.
  • +
  • To create a base image of a VM, select the VM and Export as, and enter a name and location for the base image.
  • +
  • To modify a VM, click the Modify icon ( Modify icon ), make the appropriate changes, and click Confirm.
  • +
  • To delete a VM, click Delete or press the DELETE keyboard key (fn + Delete in Mac OS® X).
  • +
  • To launch a VM, click the Launch button ( Launch ) or press the ENTER keyboard key.
  • +
+ + +

Virtual Machine

+

A virtual machine (VM) is a set of hardware options including the file system image. The Emulator Manager controls the virtual machines. When you launch the Emulator, you can specify the VM that you want to customize. Each VM has its own Emulator file system image. In other words, different VMs have different states of Emulators.

+ + + + + + + + + + +
Note
If you update the EMULATOR_IMAGE package on Tizen SDK Install Manager, existing VMs are not launched properly as the Base Image file is modified. To use the existing VMs after updating, the Emulator Manager provides the 'creating a base image' feature through the Export as button. With this functionality, you can keep the existing VMs in the new Base Image.
+ +

You can set the following VM details:

+
    +
  • Name +

    The following rules apply for naming a VM:

    +
      +
    • The length of the name must be at most 20 characters.
    • +
    • Different VMs must not have the same name.
    • +
    • Only the following characters are accepted: -, _, 0-9, a - z, and A - Z
    • +
  • + +
  • Base Image +

    You can use the default base image. You can also change the base image and choose another image when you create a VM by clicking Create New under the "mobile-custom/wearable-custom" tab folder. This new VM is added under the "each custom" group. The correct image file extension of the custom base image is .x86.

  • + +
  • Display Resolution +

    Note that the following resolution has its own default display density.

    +
      +
    • Mobile +
        +
      • 480 x 800 (WVGA)
      • +
      • 540 x 960 (qHD)
      • +
      • 720 x 1280 (HD)
      • +
    • +
    • Wearable +
        +
      • 320 x 320
      • +
      • 360 x 360
      • +
      • 360 x 480
      • +
    • +
    +
  • + +
  • Display Density +

    DPI (Dots Per Inch) value of the Emulator. The DPI depends on the display resolution.

    +
      +
    • Mobile +
        +
      • 233 (480 x 800)
      • +
      • 220 (540 x 960)
      • +
      • 306 (720 x 1280)
      • +
    • +
    • Wearable +
        +
      • 316 (320 x 320)
      • +
      • 302 (360 x 360)
      • +
      • 300 (360 x 480)
      • +
    • +
    +
  • + +
  • Skin +

    The VM UI style. Select 1 or more of the available skins. The skin depends on the display resolution.

  • + +
  • Processors +

    The number of CPUs.

  • + + +
  • RAM Size +

    The RAM size.

    + + + + + + + + + + + +
    Note
    In Windows®, only the 512 MB size is available.
    + +
      +
    • 512 MB
    • +
    • 768 MB
    • +
    • 1024 MB
    • +
  • + +
  • File Sharing +

    You can share a directory between the host PC and the Emulator. If you want to use this feature, set the value to ON and define the input directory to share in the directory field. For more information, see Sharing a Directory.

  • + +
  • CPU VT +

    The Emulator supports hardware virtualization. It is kvm on Ubuntu and HAX on Windows®. If the host CPU supports hardware virtualization and a hardware virtualization module is installed, you can change this value. For more information, see Using Hardware Virtualization.

  • + +
  • GPU +

    The Emulator supports hardware OpenGL® acceleration. If the host graphic card driver supports hardware acceleration and you select ON, the feature operates properly. Otherwise, do not try to make the Emulator support hardware acceleration. If the GPU option is enabled, the rendering performance of the video player or camera can degrade.

    +
  • + +
  • Advanced Option +

    You can attach and detach devices.

    +
      +
    • Mobile +
        +
      • Sensor: accelerometer, gyroscope, geo-magnetic, proximity, light, haptic, pressure, ultraviolet, heartbeat rate meter
      • +
      • Device: camera, battery
      • +
      • Jack: ear jack, charger, USB
      • +
    • +
    • Wearable +
        +
      • Sensor: accelerometer, gyroscope, geomagnetic, proximity, light, haptic, pressure, ultraviolet, heartbeat rate meter
      • +
      • Device: camera, battery
      • +
      • Jack: charger, USB
      • +
    • +
    +
  • + +
+ +

Emulator Manager CLI

+ +

You can create, modify, delete, and list your VMs through the command line interface commands. The CLI binary is located in:

+
    +
  • In Linux: +

    <TIZEN_SDK>/tools/emulator/bin/em-cli

  • +
  • In Windows®: +

    <TIZEN_SDK>\tools\emulator\bin\em-cli.bat

  • +
+ +

For more information, see the CLI help messages.

+ +

Figure: Emulator Manager command line

+

Emulator Manager command line

+ + +

Using Hardware Virtualization

+ +

To run the application faster, the Tizen x86 Emulator exploits KVM (Kernel-based Virtual Machine in Linux) or HAX (Hardware Accelerated eXecution in Windows® and Mac OS® X) with HW virtualization support.

+

If the CPU VT is disabled in the Detail view on the Emulator Manager, check the following prerequisites and install KVM or HAX.

+ + +

Prerequisites

+ +

To use HW virtualization, you need:

+ +
    +
  • In Linux: +

    To use KVM, you need a processor that supports HW virtualization. Both Intel and AMD have developed those extensions for their processors (Intel VT-x/AMD-V). Check whether the CPU supports HW virtualization with the following command:

    +
    +$egrep -c '(vmx|svm)' /proc/cpuinfo
    + +

    If the output of the command is 0, the CPU does not support HW virtualization. Otherwise, it does.

    +

    The HW virtualization feature can also be disabled on the BIOS setting; check the setting and enable it if you need the feature.

  • + +
  • In Windows®: +

    To use HAX, you need Intel VT-x-supported CPU, and you must enable the NX-related setting in the PC BIOS.

  • + +
  • In Mac OS® X: +

    To use HAX, install EFI-related updates on your Intel-based Mac system. For more information, see EFI and SMC firmware updates for Intel-based Macs.

  • +
+ + +

Installing KVM or HAX

+ +

To install KVM or HAX:

+ +
    +
  • In Linux: +

    No installation is required for KVM.

    +
  • +
  • In Windows® and Mac OS® X: +

    The HAXM driver is installed during the Tizen SDK installation. See the installation manual on the Tizen developer site.

    + + + + + + + + + + +
    Note
    +

    If the installation fails with a VT-related message, check the CPU feature and BIOS settings. If the installation fails with an NX-related message, enable NX (or PAE and DEP) -related item in the BIOS. In addition, make sure that the operating system supports the NX feature (for more information, see MSDN).

    +
+ +

No configuration is required for KVM or HAX.

+ + +

Running the Emulator

+

To run the Emulator with HW virtualization support in the Emulator Manager, set the CPU VT field to ON. The field is disabled if your system cannot support HW virtualization.

+

You can also run the Emulator with HW virtualization support from the command line, by including the -enable-kvm (in Linux) or -enable-hax (in Windows® and Mac OS® X) option in the start-up command.

+ + +

Emulator Control Keys and Menu

+ +

The Tizen Emulator provides a variety of control keys and menus.

+ +

Profile-specific Skin

+

The profile-specific skin has a real device-shaped image frame, and its hardware keys are on the main window skin. You can configure the profile-specific skin.

+ + +

Figure: Profile-specific skin Emulator

+ +

Profile-specific skin Emulator Mobile Profile-specific skin Emulator Wearable O Profile-specific skin Emulator Wearable

+ +

General Purpose Skin

+

The image of the general purpose skin is generated by nine-patch image processing. The Emulator skin frame has the same appearance on every state of resolution, scale, or rotation. Unlike the profile-specific skin, the layout of the general purpose skin is not configurable.

+ +
    +
  • Key window +

    The key window displays an independent hardware key input window, which can be moved to any position on the screen or docked to the left or right side of the main window. If the key window is docked with the main window, both windows can be moved together on the screen.

    +
  • +
  • Pair tag +

    The pair tag indicates that the Emulator main window and key window are in a pair. This tag is activated when the key window is open. The pair tag color changes every time the Emulator boot occurs.

    +
  • +
+ +

The following figure illustrates the general purpose skin Emulator.

+ +

Figure: General purpose skin Emulator

+

General purpose skin Emulator Mobile General purpose skin Emulator Wearable

+ + + +

Control Keys

+

The following keys are available on the Emulator:

+
    +
  • Menu (mobile only) +

    When you tap, it opens a list of options available for the current screen.

    +
  • +
  • Home (mobile only) +

    If you long press the Home key, the Task switcher application appears as in a real device.

    +
  • +
  • Back (mobile only) +

    When you tap, it returns to the previous screen.

    +
  • +
  • Power +

    You can power off the display by clicking the Power key in most general situations. + Sometimes, the display does not power off though you click the Power key. + This is to guarantee the operation of a current application, such as the Stopwatch in the Clock App. + If you click Power or Home key again, the display is powered on.

    +
  • +
  • Volume Up and Volume Down (mobile only) +

    You can control the volume with the Volume Up and Volume Down keys.

    +
  • +
+ + + + +

You can access the context menu by right-clicking on the Emulator. In the menu, you can select:

+ +
    +
  • Emulator name (the top row in the menu) +

    Display the Detailed Info window, showing the Shortcut Info and VM Info tabs. The Shortcut Info tab lists the Emulator keyboard shortcuts and the VM Info tab defines the virtual machine details.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Table: VM Info tab
    FeatureDescription
    VM NameVM name
    Skin NameSkin name
    CPUCPU architecture
    RAM SizeRAM size (MB)
    Display ResolutionTarget display resolution
    Display DensityDPI (Dots Per Inch)
    Directory SharingWhether host directory sharing is used
    File Shared PathPath to the shared host directory
    CPU VirtualizationWhether hardware virtualization is supported
    GPU VirtualizationWhether GPU virtualization is supported
    Image Path 1Target image path
    Image Path 2Swap image path
    Log PathEmulator log file path
    +
  • + +
  • Always On Top +

    Select this option to keep the Emulator window on top of other windows.

    + + + + + + + + + + +
    Note
    The Always On Top feature is not supported in Mac OS® X.
    +
  • +
  • Rotate +

    Select either Portrait, Landscape, Reverse Portrait, or Reverse Landscape as the orientation of the Emulator.

  • + +
  • Scale (mobile only) +

    Scale the size of the Emulator between 1x, 1/2x (default), 3/4x, and 1/4x.

  • + +
  • Advanced > Controller +

    Show or hide the controller window.

    + + + + + + + + + +
    Note
    The Controller menu is not supported in the profile-specific skin.
  • +
  • Advanced > Screenshot +

    Capture a screenshot of the Emulator.

  • + +
  • Advanced > About +

    Display the Emulator version, build time, and git version.

  • + +
  • Advanced > Force Close +

    Force the Emulator to exit. Since force stopping the Emulator can cause problems, use the Close option to exit the Emulator. Use Force Close only when absolutely necessary.

  • + +
  • Shell +

    Open a Smart Development Bridge (SDB) shell command window.

  • + +
  • Control Panel +

    Help to control or monitor the state of the Emulator dynamically.

  • + +
  • Close +

    Exit the Emulator.

  • + +
+ + + + + + + + + + +
Note
In Ubuntu, you need to change a global GNOME setting to view the menu icons: +
    +
  1. In the command console, execute the gconf-editor command.
  2. +
  3. In the tree, navigate to desktop > gnome > interface.
  4. +
  5. Enable the menus_have_icons option.
  6. +
+
+ + +

Emulator Control Panel

+ +

You can execute the Emulator Control Panel (ECP) by selecting Control Panel on the Context Menu after the Emulator is successfully launched. You can control and monitor the state of the Emulator dynamically.

+

The main features of ECP:

+
    + +
  • Device Manager +

    The following table lists the Device Manager features and their availability on different profiles.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Table: Device Manager features
    FeatureMobileWearableDescription
    Device TreeYesNoThe Device Tree is a data structure for describing hardware. + You can see the device information that actually loaded in the main system bus. + It shows a simple tree structure of nodes and properties. Nodes are generally a device or another bus. + Properties are key-value pairs where the value can either be empty or contain an arbitrary byte stream.
    NetworkYesYesYou can view a network device list and control the user network. + To forward a remote or local port to an inside port of the Emulator, click Add port–forwarding, + enter values in text boxes, and click Apply port–forwarding.
    Host Directory SharingYesYesThe specified host directory is mounted to /mnt/host to share resources. Therefore, the file transfer is possible through the host directory sharing feature without using the sdb utility.
  • + +
  • App Manager +

    The following table lists the App Manager features and their availability on different profiles.

    + + + + + + + + + + + + + + + + + + + + +
    Table: App Manager features
    FeatureMobileWearableDescription
    UninstallerNoYesYou can see user-installed applications and uninstall them.
    +
  • + + +
  • Event Injector +

    The following table lists the Event Injector features and their availability on different profiles.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Table: Event Injector features
    FeatureMobileWearableDescription
    BatteryYesYesYou can set the battery level using the Level slider. + To set the charger status to connected or disconnected, select the appropriate Charger radio button.
    RSSIYesNoYou can set the remote signal strength using the level bar.
    Sensor3-Axis SensorYesYesYou can inject user acceleration, magnetic, and gyroscope values using slider bars or text input.
    LightYesYesYou can inject a lux value into light sensor. + If you set brightness as auto, then display will be changed by injecting light value.
    ProximityYesYesYou can inject the presence of nearby objects.
    PressureYesYesYou can inject a hPa value into the pressure sensor.
    UltravioletYesYesYou can inject an ultraviolet index.
    Heart Rate MonitorYesYesYou can inject the heart rate and peek-to-peek time in milliseconds.
    Ear JackYesNo You can inject adding or removing headset.
    GestureNoYesYou can inject flick up (menu button) or flick down (back button) events in the wearable profile.
    USBYesYesYou can add or remove a USB device by setting the USB device setting to the connected or disconnected state.
    SD CardYesNoYou can inject a 4, 8, 16, or 32G SD card.
    LocationYesYesYou can inject latitude and longitude values using a map, manually, or from a log file.
    TelephonyYesYesYou can make and receive a call through the Call tab. You can also send and receive SMS messages through the SMS tab.
    MemoryYesYesYou can set the low memory status using the radio buttons.
    +
  • +
+ +

Various keyboard shortcuts are available to execute ECP tasks.

+ + +

Emulator Control Panel CLI

+ +

You can control and monitor the Tizen Emulator by using ECP CLI instead of the ECP UI tool. The ECP CLI supports all the functionalities of the ECP UI. The CLI binary is located at:

+
    +
  • In Linux: +

    <TIZEN_SDK>/tools/emulator/bin/ecp-cli

  • +
  • In Windows®: +

    <TIZEN_SDK>\tools\emulator\bin\ecp-cli.bat

  • +
+ +

You can use the CLI in a session mode or shell mode:

+
  • Session mode +

    You can access this mode by running the binary without any parameters. The mode keeps a session until it is exited. You can exit by entering the exit command.

  • +
  • Shell mode +

    This mode is used for one-time message handling.

+

Figure: Session and shell modes

+

Session and shell modes

+ +

In Linux, the bash-based auto-completion is used with the TAB button.

+ +

The following tables list the supported commands of the ECP CLI.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table: CLI common commands
CommandSyntaxDescription
helphelp [device]To get help, type the command as help. For more a specific device help, use the device parameter.
keycodekeycode <key-code> [period|press|release]To enter a key code for a mobile device: +
  • 114: volume down
  • +
  • 115: volume up
  • +
  • 139: HOME
  • +
  • 158: BACK
  • +
  • 169: MENU
hmphmp <hmp command>Access the QEMU human monitor protocol commands. For a list of provided commands, enter the ecp-cli hmp help command.
qmpqmp <qmp command>Access the QEMU monitoring protocol. The commands are handled in the JSON format, and do not require { "execute": "qmp_capabilities" } to be in the control mode. +

In the shell mode, the shell does not support the double quotation mark (") as an argument. For the JSON arguments, use \" (back space + double quotation mark) instead.

hdshds mount <host path> <guest path>Enable the host directory sharing feature between the specified <host path> and the Emulator's <guest path>. The specified path must be a folder, not a file.
hds unmount <id>Unmount the mounted host directory sharing path. The id is the HDS ID and you can get it from the hds status command.
hds statusShow the current host directory sharing status.
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table: CLI profile commands
DeviceCommandMobileWearableSyntax
calldialYesNocall dial <number>
hidden-dialcall hidden-dial <number>
connectcall connect
disconnectcall disconnect <call id>
statuscall status
smssendYesNosms send <number> <text>
set statussms set <available | unavailable>
statussms status
mms_statussms mms_status
locationsetYesYeslocation set <longitude> <latitude>
statuslocation status
stoplocation stop
filelocation file <file-path>
batterylevelYesYesbattery level <percent>
chargerbattery charger <on | off>
statusbattery status
earjacksetYesNoearjack set <3wire | 4wire | off>
statusearjack status
usbsetYesYesusb set <on | off>
statususb status
rssisetYesNorssi set <0~4>
statusrssi status
SD cardattachYesNosdcard attach <sdcard_[ 4 | 8 | 16 | 32 ]G>
detachsdcard detach <sdcard_[ 4 | 8 | 16 | 32 ]G>
statussdcard status
sensoraccelerometerYesYessensor accelerometer <x> <y> <z>
gyroscopesensor gyroscope <x> <y> <z>
magneticsensor magnetic <x> <y> <z>
proximitysensor proximity <value>
lightsensor light <value>
pressuresensor pressure <level>
uvsensor uv <level>
hrmsensor hrm <level>
statussensor status [sensor]
filesensor file <sensor> <path>
low_memorysetYesYeslow_memory set <hard-warning | soft-warning | normal>
statuslow_memory status
+ + +

Supported Features

+ +

The Emulator provides various virtual H/W, media formats, codecs and OpenGL® ES acceleration. For better performance of the OpenGL® ES support, the Tizen Emulator exploits the latest feature of the graphic driver, so always install the latest vendor-provided graphic driver. The Emulator, however, has some limitations and differences compared to physical target devices.

+ +

The following table lists the basic features supported in the Emulator.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table: Supported Emulator features
FeatureDetailStatusNotes
Skin

Skins are fitted to the screen resolution:

+
    +
  • Mobile +
    • WVGA (480 x 800, default)
    • +
    • qHD (540 x 960)
    • +
    • HD (720 x 1280)
    • +
    +
  • +
  • Wearable +
    • 320 x 320
    • +
    • 360 x 360 (default)
    • +
    • 360 x 480
    • +
    +
  • +
+ + +

4 orientation modes are supported:

+
    +
  • Portrait (default), landscape, reverse portrait, and reverse landscape
+ +
Supported2 skin layout types are supported: +
    +
  • Profile-specific skin
  • +
  • General purpose skin
  • +
TouchMaru touchscreen deviceSupportedMulti-touch is supported.
KeyHW keys, host keyboard, and SW keypadSupportedThe host keyboard is not supported for the Wearable Emulator.
Rotary360 levels of clockwise or counter-clockwise rotationSupported-
DisplayVGA card with 100 levels of brightness controlSupported-
OpenGL® ESCompatible with OpenGL® ES 1.1 and 2.0 +

OpenGL® ES API pass-through via PCI

+
Supported +The OpenGL® ES 1.1 functionality is not guaranteed on the Emulator, unless the graphics hardware of your computer supports OpenGL® 1.5. +

The OpenGL® ES 2.0 functionality is not guaranteed on the Emulator, unless the graphics hardware of your computer supports OpenGL® 2.1.

+

The host machine must support OpenGL® 1.4.

SoundAC97 deviceSupportedAudio in: +
    +
  • Make sure that the input volume of the microphone is enough to record your voice or songs on the host machine.
  • + +
  • On Windows® 7, inject the microphone into the host machine before starting the Emulator.
+ +

Audio out:

+
    +
  • On Windows® 7, enable at least 1 audio out device before starting the Emulator. Make sure that the volume icon in the tray is not disabled.
  • +
  • While the Emulator is running, do not disable the audio out device, as it can lock the audio system of the guest platform.
+
Network connectionVirtioSupportedRaw socket protocol, such as ICMP, is not supported.
Emulator Control PanelThe Emulator Control Panel (ECP) supports different features depending on the deice profile: +
    +
  • Mobile +
      +
    • Device Manager: Device Tree, Network, Host Directory Sharing
    • +
    • Event Injector: Battery, RSSI, 3-Axis Sensor, Light, Proximity, Pressure, Ultraviolet, Heart Rate Monitor, Motion, Ear Jack, USB, SDCard, Location, Telephony
    • +
    +
  • +
  • Wearable +
      +
    • Device Manager: Network, Host Directory Sharing
    • +
    • App Manager: Uninstaller
    • +
    • Event Injector: Battery, 3-Axis Sensor, Light, Proximity, Pedometer, Pressure, Ultraviolet, Heart Rate Monitor, Gesture, USB
    • +
    +
  • +
+ +
SupportedThe Emulator Control Panel is a standalone tool, which replaces the Event Injector. It helps to control and monitor the Emulator features, and can be launched from the Emulator context menu.
Camera

Virtual camera device connecting a host machine's Webcam

+

Support: preview, capture, and record

+

Image format: YUYV, I420, and YV12

+

Attributes: brightness and contrast

+

Resolution: 160 x 120, 176 x 144, 320 x 240, 352 x 288, and 640 x 480

+

Video resolution: 1280 x 720 for the WVGA, 320 x 240 for the WQVGA, and 640 x 480 for the HVGA devices.

+

The supported video codecs are MPEG-4, H.263, H.264, and VC-1 for both encoding and decoding.

+
SupportedWhile recording a video using the Emulator, an audio-video synchronization error can occur depending on your computer hardware and performance.
Bluetooth-Not supported-
Wi-Fi-Not supported-
Wi-Fi Direct™-Not supported-
+ +

OpenGL® ES Acceleration Support

+ +

For the Emulator to support OpenGL® ES acceleration, you need:

+
    +
  • Graphics chipset driver that supports OpenGL® 1.4 installed on the host machine
  • +
  • All chipset vendors and driver versions available to support the OpenGL® 1.4 standard
  • +
+ + + + + + + + + + + + +
Note
Emulator supports only ES 1.1, ES 2.0, and EGL™ 1.4 versions.
+ +

Differences Between the Emulator and Target

+ +

The following tables describe the differences between a real target device and the Emulator. For more detailed information, see the differences in:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table: Comparison summary
CategorySubjectPhysical targetEmulator
Development environmentTargetBuy a target device or reference board (by model)Download the SDK (multi-profile and multi-model support)
NetworkNeed BluetoothOnly the network environment
Target connectionUSBIPC (TCP/UDP)
Source and package managementSource and package for targetSource and package for the Emulator
Host Directory SharingNot supportedSupported
PortabilityScreen resolutionFixedConfigurable
RAM, storage sizeFixedConfigurable
2D and 3D acceleration APIGPU-dependentGPU-independent (common set)
CP, telephonyFully supportedPartially supported (only SMS and voice call)
Wi-FiFully supportedPartially supported (using ethernet)
SensorFully supportedPartially supported (using the Emulator Control Panel)
PnP, external connectionFully supportedPartially supported (using the Emulator Control Panel)
CameraFully supportedPartially supported (preview, capture, recording, contrast, and brightness)
Vibration, hapticFully supportedNot supported
BluetoothFully supportedNot supported
PerformanceCPU performanceMobile CPUDesktop CPU (with hardware virtualization)
GPU performanceReal GPUDesktop GPU (relatively slow)
I/O performanceReal HW I/OEmulated I/O (relatively slow)
+ +

Input System

+ + + + + + + + + + + + + + + + + + + + + + + + + +
Table: Input differences
CategoryPhysical targetEmulator
Touch screen panelReal device and driverVirtual (VirtIO) device and driver
Host keyboard and hardware keyReal device and driverVirtual (VirtIO) device and driver
+ +

Graphics and display

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table: Graphics and display differences
CategoryPhysical targetEmulator
Framebuffer deviceDisplay controller in the processorVirtual VGA card
Backlight controlLDI (LCD Driver IC) commandAdditional virtual device and driver
+ +

Virtual Sensor (Emulator Control Panel)

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table: Virtual sensor differences
CategoryPhysical targetEmulator
SensorAccelerationReceives the actual acceleration value of the device.Receives the virtual acceleration value through the Emulator Control Panel. +

If the Emulator orientation is portrait, the acceleration values are approximately 0, -9.81, and 0 degrees.

GyroReceives the actual gyroscope value of the device.Receives the virtual gyroscope value through the Emulator Control Panel.
GeomagneticReceives the actual geomagnetic value of the device.Receives the virtual geomagnetic value through the Emulator Control Panel. +

If the Emulator orientation is portrait, the y axis points to true north and the magnetic tesla values are 1, 0, and -10 degrees.

ProximityReceives the actual proximity value of the device.Receives the virtual proximity value through the Emulator Control Panel. +

You can register an event handler for the proximity sensor and test it with the Emulator Control Panel. However, the screen does not power off during the event because the Emulator does not connect to the power manager.

+
LightReceives the actual ambient light value of the device.Receives the virtual ambient light value through the Emulator Control Panel. +

You can register an event handler for the light sensor and test it with the Emulator Control Panel. However, in order to test the screen brightness change, the brightness setting must be automatic in the setting application.

+
PressureReceives the actual pressure value of the device.Receives the virtual actual pressure value through the Emulator Control Panel. +
UltravioletReceives the actual ultraviolet value of the device.Receives the virtual actual ultraviolet value through the Emulator Control Panel. +
Heart Rate MonitorReceives the actual heart rate and peak-to-peak values of the device.Receives the virtual actual heart rate and peak-to-peak values through the Emulator Control Panel. +
DeviceBatteryReceives the actual battery value of the device.Receives the virtual battery value through the Emulator Control Panel. +

You can change the battery level and the charger connection status.

+
EarjackReceives the actual earjack connection event of the device.Receives the earjack connection event through the Emulator Control Panel. +

You can select a 3-wire or 4-wire connection, or set the earjack as disconnected.

+
USBReceives the actual USB connection event of the device.Receives the USB connection event through the Emulator Control Panel.
RSSIReceives the actual RSSI value of the device.Receives the virtual RSSI value through the Emulator Control Panel.
LocationLogSupported by lbsFW.Receives the virtual GPS log file through the Emulator Control Panel. +

You can use a log file of the NMEA format.

+
ManualNot supported.Receives the virtual longitude and latitude values through the Emulator Control Panel.
MapNot supported.Receives the virtual longitude, latitude, altitude, and horizontal accuracy values through the Emulator Control Panel map.
AutoReceives the actual GPS coordinates of the device.Not supported.
+ + +

Telephony

+ + + + + + + + + + + + + + + + + + + + + + + +
Table: Telephony differences
CategoryPhysical targetEmulator
TelephonyCallCalls and video calls are supported.Call waiting, outgoing call barring, and voice calls with the Emulator Control Panel are supported. +

Video calls, call forwarding, incoming call barring, and Emulator-to-Emulator calls are not supported.

SMSSMS messaging is supported.SMS messaging with the Emulator Control Panel is supported. +

Sending Emulator-to-Emulator SMS messages is not supported.

+ + +

Power Management

+ + + + + + + + + + + + + + + + + + + + + + + + +
Table: Power management differences
ModePhysical targetEmulator
Display on/offDisplay controller in the processorInternal emulation
Power offPower management in the processorACPI (Advanced Configuration and Power Interface)
+ + +

Supported Media Formats and Codecs

+ + + + + + + + + + + + + + + + + + +
Table: Media format and codec differences
CategoryPhysical targetEmulator
DecoderFLACSupportedNot supported
+ + + + + +
+ +Go to top + + + + + + + diff --git a/org.tizen.devtools/html/common_tools/event_injec.htm b/org.tizen.devtools/html/common_tools/event_injec.htm index d508719..634ff47 100644 --- a/org.tizen.devtools/html/common_tools/event_injec.htm +++ b/org.tizen.devtools/html/common_tools/event_injec.htm @@ -1,305 +1,305 @@ - - - - - - - - - - - - - - Event Injector - - - - - -
- -

Event Injector

- -

In the Emulator Control Panel (ECP), you can inject various types of events.

- -

Providing Device Data

- -

The Emulator Control Panel (ECP) can be used to simulate device data, such as the battery level, adding or removing a ear jack (headset) or USB device, setting RSSI (remote signal strength indicator) information, and attaching and detaching the SD card in the Device tab:

- -
    - -
  • Setting the battery level -

    In the Battery tab, set the battery level using the Level slider. To set the charger status to connected or disconnected, select the appropriate Charger radio button.

  • - - -
  • Adding or removing an ear jack -

    In the EarJack tab, select the ear jack setting:

    -
      -
    • 3 Wire
    • -
    • 4 Wire
    • -
    • Disconnect
    • -
  • - -
  • Adding or removing a USB device -

    In the USB tab, set the USB device setting to the connected or disconnected state.

    -
  • - -
  • Setting the RSSI information -

    In the RSSI tab, set the RSSI information level using the Level slider.

  • - - -
  • Attaching and detaching the SD card -

    In the SD Card tab, select the 4G, 8G, 16G, or 32G SD card and attach it to the Emulator at runtime.

    - - - - - - - - - - - -
    Note
    The same SD card cannot be attached to multiple Emulators at the same time.
- -

The device information set using the ECP is reflected on the indicator bar of the device.

- - -

Providing Location Data

- -

The Emulator Control Panel (ECP) can be used to provide imitated responses to location data requests by loading GPS log files, manually entering location coordinates, or injecting markers directly on the map in the Location tab:

- -
  • Loading a GPS log file -

    In the Log section, select the pre-logged GPS data file (NMEA183 format) and click Inject Log to send the location data to the Emulator.

  • - -
  • Manually entering location coordinates -

    In the Manual section, enter the coordinates and click Inject Location to send the location data to the Emulator. The range of the latitude, longitude, altitude, and horizontal accuracy is from -90 to 90, -180 to 180, -300 to 100000, and 0 to 100000, respectively.

  • - - -
  • Injecting markers on the map -

    In the Map section, right-click the desired map locations and click Inject Markers to send the location data to the Emulator.

    -
- -

Providing NFC Data

- -

The Emulator Control Panel (ECP) can be used to test the near-field communication (NFC) features, such as NFC data exchange format (NDEF) events, NFC tag detection, and peer-to-peer (P2P) data connections in the NFC tab.

- - - - - - - - - - - -
Note
The Event Injector view sends only NFC-related events to the Emulator. There is no actual information exchange between the Event Injector and Emulator. Therefore, for features such as writing information to an NFC tag, the Emulator simply displays a success message.
- - -

Creating NDEF Messages

-

An NDEF message contains one or more NDEF records.

- -

In the NDEF Message section:

-
    -
  1. Select the record type name format.
  2. -
  3. Enter the record type name, ID, and payload.
  4. -
  5. Click Add. -

    You can add multiple NDEF records as required in the NDEF message.

  6. -
-

Click Edit or Remove to modify or delete a selected record.

- -

Attaching and Detaching NFC Tags

- -

In the NFC Tag section:

-
    -
  1. Select the tag type.
  2. -
  3. Click Tag Attach. -

    If the NDEF records list is not empty, an NDEF message is created using this list and the attach message is sent to the Emulator with the NDEF message.

  4. -
  5. When the tag operation is finished, click Tag Detach.
  6. -
- -

Creating a P2P data Connection

- -

In the Peer to Peer section:

-
    -
  1. To send the Emulator the discovered state of the new device, click P2P Discovered.
  2. -
  3. To send the Emulator an NDEF message, click P2P Send.
  4. -
  5. To send the Emulator the detached state of the connected device, click P2P Detached.
  6. -
- - -

Providing Sensor Data

-

The Emulator Control Panel (ECP) can be used to imitate user actions, such as shaking, throwing, and tilting the device. You can generate -single sensor events, or design sensor profiles for different sensors, containing sensor data that describes a series -of sensor events.

- -

The sensor profiles have a simple data structure and are stored in TXT files. The sensor data can be input in the specified data structure from the 3-axis, light, proximity, pressure, ultraviolet, or HRM sensors.

-

The sensor profiles are of 2 types:

-
    -
  • With timestamp -

    The Emulator tries to inject each item at its specified time. Events are discarded if they violate certain - performance, resource, or logic limits.

  • -
  • Without timestamp -

    The Emulator injects each item without any specific time considerations. - Profile data is not discarded.

  • -
- -

Controlling 3-axis Sensors

-

The ECP can be used to adjust the acceleration, magnetic, and gyro sensors of the Emulator in the Event Injector > Sensor > 3-Axis Sensors tab.

- -

On the GUI subtab, you can select which sensors are active, and you can move the Emulator using the 3 axis sliders or the direction buttons (Portrait, Landscape, Reverse Portrait, and Reverse Landscape). The Emulator image shows the current position of the Emulator.

- -

To better control the movement, select the With axis check box to see the axes in the Emulator image. You can also fix the y- or z-axis by selecting the X/Z or X/Y radio button, respectively. To change the Emulator accelerator value in the direction of the movement, select the Move radio button.

- -

To adjust the individual sensors:

- -
    -
  • Acceleration sensor: -

    This sensor is used to control the acceleration values along the coordinate axes. If the Emulator is standing, the y axis gets the acceleration value -1g as gravitational acceleration.

    - -

    To change the acceleration value manually, use the sliders on the Acceleration subtab to set a value between -2 and 2 g.

    -

    You can input a log file with up to 5 repeats for the acceleration sensor. The log file format is: "milliseconds, x, y, z".

  • - - - -
  • Magnetic sensor: -

    This sensor is used to control the Emulator's magnetic tesla value along the coordinate axes. If the Emulator is standing, the magnetic tesla value is set by heading for real north (azimuth 0).

    - -

    To change the magnetic tesla value manually, use the sliders on the Magnetic subtab to set a value between -2000 and 2000 uT.

    -

    You can input a log file with up to 5 repeats for the magnetic sensor. The log file format is: "milliseconds, x, y, z".

  • - - -
  • Gyro sensor: -

    This sensor is used to control the Emulator's rotation angle per second along the coordinate axes.

    - -

    To change the gyro value manually, use the sliders on the Gyro subtab to set a value between -10 and 10 rad.

    -

    You can input a log file with up to 5 repeats for the gyro sensor. The log file format is: "milliseconds, x, y, z".

  • -
- - -

Controlling Other Sensors

- -

You can control the light, proximity, pressure, ultraviolet, and HRM sensor of the Emulator under the Event Injector > Sensor tab:

- -
  • -

    To control the light sensor, set the Lux value in the Light tab. The range of this value is from 0 to 65535.

  • - -
  • To control the proximity sensor, set it on or off in the Proximity tab.

  • - -
  • To control the pressure sensor, set the hPa (Hectopascal) value in the Pressure tab. The range of this value is from 260 to 1260.

  • - -
  • To control the ultraviolet sensor, use the slider in the Ultraviolet tab. The unit is UV index and the range of this value is from 0 to 15.0.

  • - -
  • To control the HRM (Heart Rate Monitor) sensor, use the sliders in the Heart Rate Monitor tab. You can set the Heart Rate value between 0 and 220, and the Peek-to-Peek value between 0 and 5000.

  • - -
- -

Providing Telephony Features

- -

The Emulator Control Panel (ECP) can be used to generate incoming calls and messages in the Telephony tab.

- -

Generating Incoming Calls

-

Incoming calls are generated in the Event Injector > Telephony > Call tab.

- - - - - - - - - - -
Note
A Mobile Termination (MT) call is made from the Event Injector view to the Emulator. A Mobile Origination (MO) call is made from the Emulator to the Event Injector view using the phone application of the Emulator.
- -

To make an MT call:

-
    -
  1. Enter the phone number you want to imitate the call from.
  2. -
  3. Click Connect.
  4. -
  5. To hide the phone number on the Emulator, select the Hidden option.

    -

    The caller ID on the Emulator is set to "Unknown".

  6. -
- -

To make an MO call, use the Emulator's phone application:

-
    -
  1. To ready the Emulator for the connection, click Alert.
  2. -
  3. To ready the Emulator for the call, click Connect.
  4. -
- - -

Generating Messages

-

SMS messages are generated in the Event Injector > Telephony > Messaging tab. After sending a message, your application waits for the asynchronous send status message. You can generate this status report for SMS messages using the same Messaging tab.

- -

To generate an SMS message:

-
    -
  1. Enter the sender phone number you want to imitate.
  2. -
  3. Enter the message body text and click Send Msg.
  4. -
- -

To generate status reports, set the sending status value for the SMS message:

-
    -
  • SMS OK (Success)
  • -
  • SMS Not Available
  • -
- -

You can also generate MMS message status reports. To generate MMS status reports, set the sending status value for the MMS message:

-
    -
  • MMS OK (Success)
  • -
  • MMS Failure
  • -
- -

Providing Memory Data

- -

The Emulator Control Panel (ECP) can be used to simulate low memory status in the Memory tab.

- -

Set the low memory status using the radio buttons:

-
    -
  • Hard-Warning (40 MB and under)
  • -
  • Soft-Warning (60 MB and under)
  • -
  • Normal (sufficient)
  • -
- - - - - - -
- -Go to top - - - - - - + + + + + + + + + + + + + + Event Injector + + + + + +
+ +

Event Injector

+ +

In the Emulator Control Panel (ECP), you can inject various types of events.

+ +

Providing Device Data

+ +

The Emulator Control Panel (ECP) can be used to simulate device data, such as the battery level, adding or removing a ear jack (headset) or USB device, setting RSSI (remote signal strength indicator) information, and attaching and detaching the SD card in the Device tab:

+ +
    + +
  • Setting the battery level +

    In the Battery tab, set the battery level using the Level slider. To set the charger status to connected or disconnected, select the appropriate Charger radio button.

  • + + +
  • Adding or removing an ear jack +

    In the EarJack tab, select the ear jack setting:

    +
      +
    • 3 Wire
    • +
    • 4 Wire
    • +
    • Disconnect
    • +
  • + +
  • Adding or removing a USB device +

    In the USB tab, set the USB device setting to the connected or disconnected state.

    +
  • + +
  • Setting the RSSI information +

    In the RSSI tab, set the RSSI information level using the Level slider.

  • + + +
  • Attaching and detaching the SD card +

    In the SD Card tab, select the 4G, 8G, 16G, or 32G SD card and attach it to the Emulator at runtime.

    + + + + + + + + + + + +
    Note
    The same SD card cannot be attached to multiple Emulators at the same time.
+ +

The device information set using the ECP is reflected on the indicator bar of the device.

+ + +

Providing Location Data

+ +

The Emulator Control Panel (ECP) can be used to provide imitated responses to location data requests by loading GPS log files, manually entering location coordinates, or injecting markers directly on the map in the Location tab:

+ +
  • Loading a GPS log file +

    In the Log section, select the pre-logged GPS data file (NMEA183 format) and click Inject Log to send the location data to the Emulator.

  • + +
  • Manually entering location coordinates +

    In the Manual section, enter the coordinates and click Inject Location to send the location data to the Emulator. The range of the latitude, longitude, altitude, and horizontal accuracy is from -90 to 90, -180 to 180, -300 to 100000, and 0 to 100000, respectively.

  • + + +
  • Injecting markers on the map +

    In the Map section, right-click the desired map locations and click Inject Markers to send the location data to the Emulator.

    +
+ +

Providing NFC Data

+ +

The Emulator Control Panel (ECP) can be used to test the near-field communication (NFC) features, such as NFC data exchange format (NDEF) events, NFC tag detection, and peer-to-peer (P2P) data connections in the NFC tab.

+ + + + + + + + + + + +
Note
The Event Injector view sends only NFC-related events to the Emulator. There is no actual information exchange between the Event Injector and Emulator. Therefore, for features such as writing information to an NFC tag, the Emulator simply displays a success message.
+ + +

Creating NDEF Messages

+

An NDEF message contains one or more NDEF records.

+ +

In the NDEF Message section:

+
    +
  1. Select the record type name format.
  2. +
  3. Enter the record type name, ID, and payload.
  4. +
  5. Click Add. +

    You can add multiple NDEF records as required in the NDEF message.

  6. +
+

Click Edit or Remove to modify or delete a selected record.

+ +

Attaching and Detaching NFC Tags

+ +

In the NFC Tag section:

+
    +
  1. Select the tag type.
  2. +
  3. Click Tag Attach. +

    If the NDEF records list is not empty, an NDEF message is created using this list and the attach message is sent to the Emulator with the NDEF message.

  4. +
  5. When the tag operation is finished, click Tag Detach.
  6. +
+ +

Creating a P2P data Connection

+ +

In the Peer to Peer section:

+
    +
  1. To send the Emulator the discovered state of the new device, click P2P Discovered.
  2. +
  3. To send the Emulator an NDEF message, click P2P Send.
  4. +
  5. To send the Emulator the detached state of the connected device, click P2P Detached.
  6. +
+ + +

Providing Sensor Data

+

The Emulator Control Panel (ECP) can be used to imitate user actions, such as shaking, throwing, and tilting the device. You can generate +single sensor events, or design sensor profiles for different sensors, containing sensor data that describes a series +of sensor events.

+ +

The sensor profiles have a simple data structure and are stored in TXT files. The sensor data can be input in the specified data structure from the 3-axis, light, proximity, pressure, ultraviolet, or HRM sensors.

+

The sensor profiles are of 2 types:

+
    +
  • With timestamp +

    The Emulator tries to inject each item at its specified time. Events are discarded if they violate certain + performance, resource, or logic limits.

  • +
  • Without timestamp +

    The Emulator injects each item without any specific time considerations. + Profile data is not discarded.

  • +
+ +

Controlling 3-axis Sensors

+

The ECP can be used to adjust the acceleration, magnetic, and gyro sensors of the Emulator in the Event Injector > Sensor > 3-Axis Sensors tab.

+ +

On the GUI subtab, you can select which sensors are active, and you can move the Emulator using the 3 axis sliders or the direction buttons (Portrait, Landscape, Reverse Portrait, and Reverse Landscape). The Emulator image shows the current position of the Emulator.

+ +

To better control the movement, select the With axis check box to see the axes in the Emulator image. You can also fix the y- or z-axis by selecting the X/Z or X/Y radio button, respectively. To change the Emulator accelerator value in the direction of the movement, select the Move radio button.

+ +

To adjust the individual sensors:

+ +
    +
  • Acceleration sensor: +

    This sensor is used to control the acceleration values along the coordinate axes. If the Emulator is standing, the y axis gets the acceleration value -1g as gravitational acceleration.

    + +

    To change the acceleration value manually, use the sliders on the Acceleration subtab to set a value between -2 and 2 g.

    +

    You can input a log file with up to 5 repeats for the acceleration sensor. The log file format is: "milliseconds, x, y, z".

  • + + + +
  • Magnetic sensor: +

    This sensor is used to control the Emulator's magnetic tesla value along the coordinate axes. If the Emulator is standing, the magnetic tesla value is set by heading for real north (azimuth 0).

    + +

    To change the magnetic tesla value manually, use the sliders on the Magnetic subtab to set a value between -2000 and 2000 uT.

    +

    You can input a log file with up to 5 repeats for the magnetic sensor. The log file format is: "milliseconds, x, y, z".

  • + + +
  • Gyro sensor: +

    This sensor is used to control the Emulator's rotation angle per second along the coordinate axes.

    + +

    To change the gyro value manually, use the sliders on the Gyro subtab to set a value between -10 and 10 rad.

    +

    You can input a log file with up to 5 repeats for the gyro sensor. The log file format is: "milliseconds, x, y, z".

  • +
+ + +

Controlling Other Sensors

+ +

You can control the light, proximity, pressure, ultraviolet, and HRM sensor of the Emulator under the Event Injector > Sensor tab:

+ +
  • +

    To control the light sensor, set the Lux value in the Light tab. The range of this value is from 0 to 65535.

  • + +
  • To control the proximity sensor, set it on or off in the Proximity tab.

  • + +
  • To control the pressure sensor, set the hPa (Hectopascal) value in the Pressure tab. The range of this value is from 260 to 1260.

  • + +
  • To control the ultraviolet sensor, use the slider in the Ultraviolet tab. The unit is UV index and the range of this value is from 0 to 15.0.

  • + +
  • To control the HRM (Heart Rate Monitor) sensor, use the sliders in the Heart Rate Monitor tab. You can set the Heart Rate value between 0 and 220, and the Peek-to-Peek value between 0 and 5000.

  • + +
+ +

Providing Telephony Features

+ +

The Emulator Control Panel (ECP) can be used to generate incoming calls and messages in the Telephony tab.

+ +

Generating Incoming Calls

+

Incoming calls are generated in the Event Injector > Telephony > Call tab.

+ + + + + + + + + + +
Note
A Mobile Termination (MT) call is made from the Event Injector view to the Emulator. A Mobile Origination (MO) call is made from the Emulator to the Event Injector view using the phone application of the Emulator.
+ +

To make an MT call:

+
    +
  1. Enter the phone number you want to imitate the call from.
  2. +
  3. Click Connect.
  4. +
  5. To hide the phone number on the Emulator, select the Hidden option.

    +

    The caller ID on the Emulator is set to "Unknown".

  6. +
+ +

To make an MO call, use the Emulator's phone application:

+
    +
  1. To ready the Emulator for the connection, click Alert.
  2. +
  3. To ready the Emulator for the call, click Connect.
  4. +
+ + +

Generating Messages

+

SMS messages are generated in the Event Injector > Telephony > Messaging tab. After sending a message, your application waits for the asynchronous send status message. You can generate this status report for SMS messages using the same Messaging tab.

+ +

To generate an SMS message:

+
    +
  1. Enter the sender phone number you want to imitate.
  2. +
  3. Enter the message body text and click Send Msg.
  4. +
+ +

To generate status reports, set the sending status value for the SMS message:

+
    +
  • SMS OK (Success)
  • +
  • SMS Not Available
  • +
+ +

You can also generate MMS message status reports. To generate MMS status reports, set the sending status value for the MMS message:

+
    +
  • MMS OK (Success)
  • +
  • MMS Failure
  • +
+ +

Providing Memory Data

+ +

The Emulator Control Panel (ECP) can be used to simulate low memory status in the Memory tab.

+ +

Set the low memory status using the radio buttons:

+
    +
  • Hard-Warning (40 MB and under)
  • +
  • Soft-Warning (60 MB and under)
  • +
  • Normal (sufficient)
  • +
+ + + + + + +
+ +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.devtools/html/common_tools/keyboard_shortcuts.htm b/org.tizen.devtools/html/common_tools/keyboard_shortcuts.htm index 660688f..789b0bd 100644 --- a/org.tizen.devtools/html/common_tools/keyboard_shortcuts.htm +++ b/org.tizen.devtools/html/common_tools/keyboard_shortcuts.htm @@ -1,1383 +1,1383 @@ - - - - - - - - - - - - - - Keyboard Shortcuts - - - - - -
-

Keyboard Shortcuts

- -

The following symbols are used to define the supported operating system for each shortcut:

-
    -
  • windows: Windows®

  • -
  • ubuntu: Ubuntu

  • -
  • mac: Mac OS®

  • -
- -

Connection Explorer

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
CommandSupportShortcut
Deletewindows ubuntu macDelete
Renamewindows_symbolubuntu macF2
Refreshwindows ubuntu macF5
Propertywindows ubuntu macAlt+Enter
- -

Build and Run

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
CommandSupportShortcut
Build allwindows ubuntu Ctrl+B
maccommand+B
Make target buildwindows ubuntu macShift+F9
Rebuild last targetwindows ubuntu macF9
Build projectwindows ubuntu macF10
Run last launchedwindows ubuntu Ctrl+F11
maccommand+F11
- -

Debug

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
CommandSupportShortcut
Step intowindows ubuntu macF5
Step overwindows ubuntu macF6
Step returnwindows ubuntu macF7
Resumewindows ubuntu macF8
Debugwindows ubuntu Ctrl+F11
maccommand+F11
Debug last launchedwindows ubuntu macF11
Toggle breakpointwindows ubuntu Ctrl+Shift+B
maccommand+Shift+B
- -

Content Assist

- - - - - - - - - - - - - - - - -
CommandSupportShortcut
Content assistwindows ubuntu macCtrl+Space
- -

Project Management

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
CommandSupportShortcut
New project and file using the Wizardwindows ubuntu Ctrl+N
maccommand+N
New project and filewindows ubuntu Ctrl+Alt+N
maccommand+Alt+N
Open resourcewindows ubuntu Ctrl+Shift+R
maccommand+Shift+R
Propertieswindows ubuntu macAlt+Enter
Savewindows ubuntu Ctrl+S
maccommand+S
Save allwindows ubuntu Ctrl+Shift+S
maccommand+Shift+S
Closewindows ubuntu Ctrl+W
maccommand+W
Close allwindows ubuntu Ctrl+Shift+W
maccommand+Shift+W
Refreshwindows ubuntu macF5
Renamewindows ubuntu macF2
- -

Editor

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
CommandSupportShortcut
Find and replacewindows ubuntu Ctrl+F
maccommand+F
Quick fixwindows ubuntu Ctrl+1
maccommand+1
Redowindows ubuntu Ctrl+Z
maccommand+Shift+Z
Undowindows ubuntu Ctrl+Z
maccommand+Z
Go to linewindows ubuntu Ctrl+L
maccommand+L
Delete linewindows ubuntu Ctrl+D
maccommand+D
Go to matching bracketwindows ubuntu Ctrl+Shift+P
maccommand+Shift+P
Move lines downwindows ubuntu macAlt+arrow_down
Move lines upwindows ubuntu macAlt+arrow_up
Show tooltipwindows ubuntu macF2
Open declarationwindows ubuntu macF3
Open type hierarchywindows ubuntu macF4
Open typewindows ubuntu Ctrl+Shift+T
maccommand+Shift+T
To lower casewindows ubuntu Ctrl+Shift+Y
maccommand+Shift+Y
To upper casewindows ubuntu Ctrl+Shift+Z
maccommand+Shift+Z
Correct indentationwindows ubuntu Ctrl+I
maccommand+I
Formatwindows ubuntu Ctrl+Shift+F
maccommand+Shift+F
Add/remove commentwindows ubuntu Ctrl+/
maccommand+/
Add/remove block commentwindows ubuntu Ctrl+Shift+/
maccommand+Shift+/
- -

Refactor

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
CommandSupportShortcut
Rename-refactoringwindows ubuntu Alt+Shift+R
maccommand+Alt+R
Move-refactoringwindows ubuntu Alt+Shift+V
maccommand+Alt+V
Change method signaturewindows ubuntu Alt+Shift+C
maccommand+Alt+C
Extract methodwindows ubuntu Alt+Shift+M
maccommand+Alt+M
Extract local variablewindows ubuntu Alt+Shift+L
maccommand+Alt+L
- -

Native IDE

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
CommandSupportShortcut
Insert snippetwindows ubuntu Ctrl+Shift+I
maccommand+Shift+I
New launch configurationwindows ubuntu Alt+Shift+F12
macmac+F12
Forward launch historywindows ubuntu Alt+Shift+[
macmac+[
Backward launch historywindows ubuntu Alt+Shift+]
macmac+]
- -

Web IDE

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
CommandSupportShortcut
HTML editorVertical layoutwindows ubuntu Ctrl+Shift+F9
maccommand+Shift+F9
Graphical designerwindows ubuntu Ctrl+Shift+F10
maccommand+Shift+F10
Horizontal layoutwindows ubuntu Ctrl+Shift+F11
maccommand+Shift+F11
Source codewindows ubuntu Ctrl+Shift+F12
maccommand+Shift+F12
Previewwindows ubuntu Ctrl+4
maccommand+4
Code minifierwindows ubuntu Ctrl+5
maccommand+5
Code beautifierwindows ubuntu Ctrl+6
maccommand+6
Assignment tracing - nextwindows ubuntu Ctrl+]
maccommand+]
Assignment tracing - previouswindows ubuntu Ctrl+[
maccommand+[
- -

Dynamic Analyzer

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
CommandSupportShortcut
About Tizen Dynamic Analyzerwindows ubuntu macF1
Configurationwindows ubuntu macF2
Enable the source view of the toolbarwindows ubuntu macF3
Select the Timeline tabwindows ubuntu Ctrl+1
maccommand+1
Select the File tabwindows ubuntu Ctrl+2
maccommand+2
Select the Thread tabwindows ubuntu Ctrl+3
maccommand+3
Select the User Interface tabwindows ubuntu Ctrl+4
maccommand+4
Select the Summary tabwindows ubuntu Ctrl+5
maccommand+5
Select the Range tabwindows ubuntu Ctrl+6
maccommand+6
Start/stop tracewindows ubuntu Ctrl+g
maccommand+g
Open tracewindows ubuntu Ctrl+o
maccommand+o
Save tracewindows ubuntu Ctrl+s
maccommand+s
Replaywindows ubuntu Ctrl+p
maccommand+p
Toggle the range information between create and removewindows ubuntu Ctrl+r
maccommand+r
Open the search dialog boxwindows ubuntu Ctrl+f
maccommand+f
Delete the saved file of the open trace dialog boxwindows ubuntu Delete
macfn+Delete
- -

Emulator Manager

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
CommandSupportShortcut
Delete virtual machinewindows ubuntu Delete
macfn+Delete
Launch virtual machinewindows ubuntu macEnter
Select virtual machinewindows ubuntu macArrow key
- -

Emulator

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
CommandSupportShortcut
Always on Topwindows ubuntu macCtrl+F2
Closewindows ubuntu macF4
Control Panelwindows ubuntu macCtrl+F6
Detailed Infowindows ubuntu macCtrl+F1
Force Closewindows ubuntu macCtrl+F4
Rotate nextwindows ubuntu macCtrl+Num+9
Rotate prevwindows ubuntu macCtrl+Num+7
Scale nextwindows ubuntu macCtrl+F10
Scale prevwindows ubuntu macCtrl+F9
Screen Shotwindows ubuntu macCtrl+F7
Shellwindows ubuntu macCtrl+F5
Homewindows ubuntu macF1
Menuwindows ubuntu macF2
Powerwindows ubuntu macF3
Volume +windows ubuntu macCtrl+Num++
Volume -windows ubuntu macCtrl+Num+-
- - -

Emulator Control Panel (ECP)

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
CommandSupportShortcut
Common
Device Treewindows ubuntu macAlt+D
Networkwindows ubuntu macAlt+N
Uninstallerwindows ubuntu macAlt+U
HDS (Host Directory Sharing)windows ubuntu macAlt+H
Upper menu focus movementwindows ubuntu macUp
Underneath menu focus movementwindows ubuntu macDown
Collapse tree menuwindows ubuntu macLeft
Expand tree menuwindows ubuntu macRight
Move focus to next controlwindows ubuntu macTab
Move focus to previous controlwindows ubuntu macShift + Tab
Menu selectionwindows ubuntu macEnter
Mobile
Batterywindows ubuntu macAlt+B
RSSIwindows ubuntu macAlt+R
3-Axis sensorwindows ubuntu macAlt+A
Lightwindows ubuntu macAlt+I
Proximitywindows ubuntu macAlt+X
Pressurewindows ubuntu macAlt+E
Ultravioletwindows ubuntu macAlt+V
Heart Rate Monitorwindows ubuntu macAlt+M
Ear Jackwindows ubuntu macAlt+K
USBwindows ubuntu macAlt+S
SD Cardwindows ubuntu macAlt+D
Locationwindows ubuntu macAlt+L
Telephonywindows ubuntu macAlt+T
Memorywindows ubuntu macAlt+O
Wearable
Batterywindows ubuntu macAlt+B
3-Axis sensorwindows ubuntu macAlt+A
Lightwindows ubuntu macAlt+I
Proximitywindows ubuntu macAlt+X
Pressurewindows ubuntu macAlt+E
Ultravioletwindows ubuntu macAlt+V
Heart Rate Monitorwindows ubuntu macAlt+M
Touch gesturewindows ubuntu macAlt+G
USBwindows ubuntu macAlt+S
Memorywindows ubuntu macAlt+O
- - -

Enventor

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
CommandSupportShortcut

Close the menu

ubuntu

Esc

Show shortcut keys

ubuntu

F1

Save the file

ubuntu

F3

Show or hide the line numbers

ubuntu

F5

Show or hide the tool bar

ubuntu

F9

Show or hide the console view

ubuntu

F10

Show or hide the status bar

ubuntu

F11

Show the configuration setting window

ubuntu

F12

Quick save and compile EDC

ubuntu

Ctrl+S

Enable or disable auto indentation

ubuntu

Ctrl+I

Enable or disable auto completion

ubuntu

Ctrl+O

Show or hide virtual images to visualize SWALLOW part objects

ubuntu

Ctrl+W

Enable or disable part object highlighting

ubuntu

Ctrl+H

Enable or disable full text view

ubuntu

Ctrl+Left

Enable or disable full live view

ubuntu

Ctrl+Right

Enable or disable full console view

ubuntu

Ctrl+Up

Enable or disable full live/text view

ubuntu

Ctrl+Down

Insert default template code

ubuntu

Ctrl+T

Enable or disable LiveEdit function

ubuntu

Ctrl+E

View scale up/bigger font size

ubuntu

Ctrl+Mouse wheel up

View scale down/smaller font size

ubuntu

Ctrl+Mouse wheel down

Insert part template code: Textblock

ubuntu

Ctrl+Shift+B

Insert part template code: Image

ubuntu

Ctrl+Shift+I

Insert part template code: Rectangle

ubuntu

Ctrl+Shift+R

Insert part template code: Text

ubuntu

Ctrl+Shift+T

Insert part template code: Spacer

ubuntu

Ctrl+Shift+S

Insert part template code: Swallow

ubuntu

Ctrl+Shift+W

Select all the text

ubuntu

Ctrl+A

Select the word

ubuntu

Ctrl+Double-click

Undo text changes

ubuntu

Ctrl+Z

Redo text changes

ubuntu

Ctrl+R

Copy selected text

ubuntu

Ctrl+C

Paste copied text

ubuntu

Ctrl+V

Cut selected text

ubuntu

Ctrl+X

Delete a current line

ubuntu

Ctrl+D

Find and replace the given word

ubuntu

Ctrl+F

Go to the given line

ubuntu

Ctrl+L

Go to the top line

ubuntu

Ctrl+Home

Go to the bottom line

ubuntu

Ctrl+End

- - - - -
- -Go to top - - - - - - - + + + + + + + + + + + + + + Keyboard Shortcuts + + + + + +
+

Keyboard Shortcuts

+ +

The following symbols are used to define the supported operating system for each shortcut:

+
    +
  • windows: Windows®

  • +
  • ubuntu: Ubuntu

  • +
  • mac: Mac OS®

  • +
+ +

Connection Explorer

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandSupportShortcut
Deletewindows ubuntu macDelete
Renamewindows_symbolubuntu macF2
Refreshwindows ubuntu macF5
Propertywindows ubuntu macAlt+Enter
+ +

Build and Run

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandSupportShortcut
Build allwindows ubuntu Ctrl+B
maccommand+B
Make target buildwindows ubuntu macShift+F9
Rebuild last targetwindows ubuntu macF9
Build projectwindows ubuntu macF10
Run last launchedwindows ubuntu Ctrl+F11
maccommand+F11
+ +

Debug

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandSupportShortcut
Step intowindows ubuntu macF5
Step overwindows ubuntu macF6
Step returnwindows ubuntu macF7
Resumewindows ubuntu macF8
Debugwindows ubuntu Ctrl+F11
maccommand+F11
Debug last launchedwindows ubuntu macF11
Toggle breakpointwindows ubuntu Ctrl+Shift+B
maccommand+Shift+B
+ +

Content Assist

+ + + + + + + + + + + + + + + + +
CommandSupportShortcut
Content assistwindows ubuntu macCtrl+Space
+ +

Project Management

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandSupportShortcut
New project and file using the Wizardwindows ubuntu Ctrl+N
maccommand+N
New project and filewindows ubuntu Ctrl+Alt+N
maccommand+Alt+N
Open resourcewindows ubuntu Ctrl+Shift+R
maccommand+Shift+R
Propertieswindows ubuntu macAlt+Enter
Savewindows ubuntu Ctrl+S
maccommand+S
Save allwindows ubuntu Ctrl+Shift+S
maccommand+Shift+S
Closewindows ubuntu Ctrl+W
maccommand+W
Close allwindows ubuntu Ctrl+Shift+W
maccommand+Shift+W
Refreshwindows ubuntu macF5
Renamewindows ubuntu macF2
+ +

Editor

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandSupportShortcut
Find and replacewindows ubuntu Ctrl+F
maccommand+F
Quick fixwindows ubuntu Ctrl+1
maccommand+1
Redowindows ubuntu Ctrl+Z
maccommand+Shift+Z
Undowindows ubuntu Ctrl+Z
maccommand+Z
Go to linewindows ubuntu Ctrl+L
maccommand+L
Delete linewindows ubuntu Ctrl+D
maccommand+D
Go to matching bracketwindows ubuntu Ctrl+Shift+P
maccommand+Shift+P
Move lines downwindows ubuntu macAlt+arrow_down
Move lines upwindows ubuntu macAlt+arrow_up
Show tooltipwindows ubuntu macF2
Open declarationwindows ubuntu macF3
Open type hierarchywindows ubuntu macF4
Open typewindows ubuntu Ctrl+Shift+T
maccommand+Shift+T
To lower casewindows ubuntu Ctrl+Shift+Y
maccommand+Shift+Y
To upper casewindows ubuntu Ctrl+Shift+Z
maccommand+Shift+Z
Correct indentationwindows ubuntu Ctrl+I
maccommand+I
Formatwindows ubuntu Ctrl+Shift+F
maccommand+Shift+F
Add/remove commentwindows ubuntu Ctrl+/
maccommand+/
Add/remove block commentwindows ubuntu Ctrl+Shift+/
maccommand+Shift+/
+ +

Refactor

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandSupportShortcut
Rename-refactoringwindows ubuntu Alt+Shift+R
maccommand+Alt+R
Move-refactoringwindows ubuntu Alt+Shift+V
maccommand+Alt+V
Change method signaturewindows ubuntu Alt+Shift+C
maccommand+Alt+C
Extract methodwindows ubuntu Alt+Shift+M
maccommand+Alt+M
Extract local variablewindows ubuntu Alt+Shift+L
maccommand+Alt+L
+ +

Native IDE

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandSupportShortcut
Insert snippetwindows ubuntu Ctrl+Shift+I
maccommand+Shift+I
New launch configurationwindows ubuntu Alt+Shift+F12
macmac+F12
Forward launch historywindows ubuntu Alt+Shift+[
macmac+[
Backward launch historywindows ubuntu Alt+Shift+]
macmac+]
+ +

Web IDE

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandSupportShortcut
HTML editorVertical layoutwindows ubuntu Ctrl+Shift+F9
maccommand+Shift+F9
Graphical designerwindows ubuntu Ctrl+Shift+F10
maccommand+Shift+F10
Horizontal layoutwindows ubuntu Ctrl+Shift+F11
maccommand+Shift+F11
Source codewindows ubuntu Ctrl+Shift+F12
maccommand+Shift+F12
Previewwindows ubuntu Ctrl+4
maccommand+4
Code minifierwindows ubuntu Ctrl+5
maccommand+5
Code beautifierwindows ubuntu Ctrl+6
maccommand+6
Assignment tracing - nextwindows ubuntu Ctrl+]
maccommand+]
Assignment tracing - previouswindows ubuntu Ctrl+[
maccommand+[
+ +

Dynamic Analyzer

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandSupportShortcut
About Tizen Dynamic Analyzerwindows ubuntu macF1
Configurationwindows ubuntu macF2
Enable the source view of the toolbarwindows ubuntu macF3
Select the Timeline tabwindows ubuntu Ctrl+1
maccommand+1
Select the File tabwindows ubuntu Ctrl+2
maccommand+2
Select the Thread tabwindows ubuntu Ctrl+3
maccommand+3
Select the User Interface tabwindows ubuntu Ctrl+4
maccommand+4
Select the Summary tabwindows ubuntu Ctrl+5
maccommand+5
Select the Range tabwindows ubuntu Ctrl+6
maccommand+6
Start/stop tracewindows ubuntu Ctrl+g
maccommand+g
Open tracewindows ubuntu Ctrl+o
maccommand+o
Save tracewindows ubuntu Ctrl+s
maccommand+s
Replaywindows ubuntu Ctrl+p
maccommand+p
Toggle the range information between create and removewindows ubuntu Ctrl+r
maccommand+r
Open the search dialog boxwindows ubuntu Ctrl+f
maccommand+f
Delete the saved file of the open trace dialog boxwindows ubuntu Delete
macfn+Delete
+ +

Emulator Manager

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandSupportShortcut
Delete virtual machinewindows ubuntu Delete
macfn+Delete
Launch virtual machinewindows ubuntu macEnter
Select virtual machinewindows ubuntu macArrow key
+ +

Emulator

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandSupportShortcut
Always on Topwindows ubuntu macCtrl+F2
Closewindows ubuntu macF4
Control Panelwindows ubuntu macCtrl+F6
Detailed Infowindows ubuntu macCtrl+F1
Force Closewindows ubuntu macCtrl+F4
Rotate nextwindows ubuntu macCtrl+Num+9
Rotate prevwindows ubuntu macCtrl+Num+7
Scale nextwindows ubuntu macCtrl+F10
Scale prevwindows ubuntu macCtrl+F9
Screen Shotwindows ubuntu macCtrl+F7
Shellwindows ubuntu macCtrl+F5
Homewindows ubuntu macF1
Menuwindows ubuntu macF2
Powerwindows ubuntu macF3
Volume +windows ubuntu macCtrl+Num++
Volume -windows ubuntu macCtrl+Num+-
+ + +

Emulator Control Panel (ECP)

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandSupportShortcut
Common
Device Treewindows ubuntu macAlt+D
Networkwindows ubuntu macAlt+N
Uninstallerwindows ubuntu macAlt+U
HDS (Host Directory Sharing)windows ubuntu macAlt+H
Upper menu focus movementwindows ubuntu macUp
Underneath menu focus movementwindows ubuntu macDown
Collapse tree menuwindows ubuntu macLeft
Expand tree menuwindows ubuntu macRight
Move focus to next controlwindows ubuntu macTab
Move focus to previous controlwindows ubuntu macShift + Tab
Menu selectionwindows ubuntu macEnter
Mobile
Batterywindows ubuntu macAlt+B
RSSIwindows ubuntu macAlt+R
3-Axis sensorwindows ubuntu macAlt+A
Lightwindows ubuntu macAlt+I
Proximitywindows ubuntu macAlt+X
Pressurewindows ubuntu macAlt+E
Ultravioletwindows ubuntu macAlt+V
Heart Rate Monitorwindows ubuntu macAlt+M
Ear Jackwindows ubuntu macAlt+K
USBwindows ubuntu macAlt+S
SD Cardwindows ubuntu macAlt+D
Locationwindows ubuntu macAlt+L
Telephonywindows ubuntu macAlt+T
Memorywindows ubuntu macAlt+O
Wearable
Batterywindows ubuntu macAlt+B
3-Axis sensorwindows ubuntu macAlt+A
Lightwindows ubuntu macAlt+I
Proximitywindows ubuntu macAlt+X
Pressurewindows ubuntu macAlt+E
Ultravioletwindows ubuntu macAlt+V
Heart Rate Monitorwindows ubuntu macAlt+M
Touch gesturewindows ubuntu macAlt+G
USBwindows ubuntu macAlt+S
Memorywindows ubuntu macAlt+O
+ + +

Enventor

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandSupportShortcut

Close the menu

ubuntu

Esc

Show shortcut keys

ubuntu

F1

Save the file

ubuntu

F3

Show or hide the line numbers

ubuntu

F5

Show or hide the tool bar

ubuntu

F9

Show or hide the console view

ubuntu

F10

Show or hide the status bar

ubuntu

F11

Show the configuration setting window

ubuntu

F12

Quick save and compile EDC

ubuntu

Ctrl+S

Enable or disable auto indentation

ubuntu

Ctrl+I

Enable or disable auto completion

ubuntu

Ctrl+O

Show or hide virtual images to visualize SWALLOW part objects

ubuntu

Ctrl+W

Enable or disable part object highlighting

ubuntu

Ctrl+H

Enable or disable full text view

ubuntu

Ctrl+Left

Enable or disable full live view

ubuntu

Ctrl+Right

Enable or disable full console view

ubuntu

Ctrl+Up

Enable or disable full live/text view

ubuntu

Ctrl+Down

Insert default template code

ubuntu

Ctrl+T

Enable or disable LiveEdit function

ubuntu

Ctrl+E

View scale up/bigger font size

ubuntu

Ctrl+Mouse wheel up

View scale down/smaller font size

ubuntu

Ctrl+Mouse wheel down

Insert part template code: Textblock

ubuntu

Ctrl+Shift+B

Insert part template code: Image

ubuntu

Ctrl+Shift+I

Insert part template code: Rectangle

ubuntu

Ctrl+Shift+R

Insert part template code: Text

ubuntu

Ctrl+Shift+T

Insert part template code: Spacer

ubuntu

Ctrl+Shift+S

Insert part template code: Swallow

ubuntu

Ctrl+Shift+W

Select all the text

ubuntu

Ctrl+A

Select the word

ubuntu

Ctrl+Double-click

Undo text changes

ubuntu

Ctrl+Z

Redo text changes

ubuntu

Ctrl+R

Copy selected text

ubuntu

Ctrl+C

Paste copied text

ubuntu

Ctrl+V

Cut selected text

ubuntu

Ctrl+X

Delete a current line

ubuntu

Ctrl+D

Find and replace the given word

ubuntu

Ctrl+F

Go to the given line

ubuntu

Ctrl+L

Go to the top line

ubuntu

Ctrl+Home

Go to the bottom line

ubuntu

Ctrl+End

+ + + + +
+ +Go to top + + + + + + + diff --git a/org.tizen.devtools/html/common_tools/log_view.htm b/org.tizen.devtools/html/common_tools/log_view.htm index 4ab0452..292c999 100644 --- a/org.tizen.devtools/html/common_tools/log_view.htm +++ b/org.tizen.devtools/html/common_tools/log_view.htm @@ -1,68 +1,68 @@ - - - - - - - - - - - - - - Log View - - - - -
-
- -
-
-

Mobile Web Wearable Web Mobile native Wearable native

-
- -

Log View

- -

While the application is running in the Emulator or target device, the IDE's Log view shows the log, debug, and exception messages. If the Log view is not visible, open it by selecting Window > Show View > Log from the IDE menu.

- -

In the Log view, you can:

-
    -
  • Work with LogTabs -

    Each device has at least 1 default LogTab associated with it. If a device is connected, the default LogTab is not editable or removable. However, you can add additional LogTabs with more filtering options. Additional LogTabs are editable and removable.

    -
  • -
  • Filter log messages by using the V, D, I, W, E, and F buttons to show only specific log message types (verbose, debug, info, warning, error, and fatal).
  • -
  • Search for logs by selecting the field (Pid, Tag, or Message) to be searched from the drop-down list, and entering the keyword. Multiple keywords must be separated by a space and a comma.
  • -
  • Export a log by clicking Export the log and saving current log messages from the Log view as a log file on the host system.
  • -
  • Remove all log messages from the Log view by clicking Clear the log.
  • - -
- -

You can create logs in the native framework using the methods defined in the log macros.

- - - - -
- -Go to top - - - - - - - + + + + + + + + + + + + + + Log View + + + + +
+
+ +
+
+

Mobile Web Wearable Web Mobile native Wearable native

+
+ +

Log View

+ +

While the application is running in the Emulator or target device, the IDE's Log view shows the log, debug, and exception messages. If the Log view is not visible, open it by selecting Window > Show View > Log from the IDE menu.

+ +

In the Log view, you can:

+
    +
  • Work with LogTabs +

    Each device has at least 1 default LogTab associated with it. If a device is connected, the default LogTab is not editable or removable. However, you can add additional LogTabs with more filtering options. Additional LogTabs are editable and removable.

    +
  • +
  • Filter log messages by using the V, D, I, W, E, and F buttons to show only specific log message types (verbose, debug, info, warning, error, and fatal).
  • +
  • Search for logs by selecting the field (Pid, Tag, or Message) to be searched from the drop-down list, and entering the keyword. Multiple keywords must be separated by a space and a comma.
  • +
  • Export a log by clicking Export the log and saving current log messages from the Log view as a log file on the host system.
  • +
  • Remove all log messages from the Log view by clicking Clear the log.
  • + +
+ +

You can create logs in the native framework using the methods defined in the log macros.

+ + + + +
+ +Go to top + + + + + + + diff --git a/org.tizen.devtools/html/common_tools/project_explorer.htm b/org.tizen.devtools/html/common_tools/project_explorer.htm index 28363c8..edf8703 100644 --- a/org.tizen.devtools/html/common_tools/project_explorer.htm +++ b/org.tizen.devtools/html/common_tools/project_explorer.htm @@ -1,63 +1,63 @@ - - - - - - - - - - - - - - Project Explorer View - - - -
-
- -
-
-

Mobile Web Wearable Web Mobile native Wearable native

-
- -

Project Explorer View

-

The Project Explorer view provides a hierarchical view of all resources in the workspace. You can open files for editing or select resources for operations, such as building, packaging, signing, or validating an application.

- -

The following figure shows and example of the Project Explorer view with a Web application.

- -

Figure: Project Explorer view

- -

Project Explorer view

- - - - - - - -
- -Go to top - - - - - - + + + + + + + + + + + + + + Project Explorer View + + + +
+
+ +
+
+

Mobile Web Wearable Web Mobile native Wearable native

+
+ +

Project Explorer View

+

The Project Explorer view provides a hierarchical view of all resources in the workspace. You can open files for editing or select resources for operations, such as building, packaging, signing, or validating an application.

+ +

The following figure shows and example of the Project Explorer view with a Web application.

+ +

Figure: Project Explorer view

+ +

Project Explorer view

+ + + + + + + +
+ +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.devtools/html/common_tools/smart_dev_bridge.htm b/org.tizen.devtools/html/common_tools/smart_dev_bridge.htm index 14c79e5..fdf4bb9 100644 --- a/org.tizen.devtools/html/common_tools/smart_dev_bridge.htm +++ b/org.tizen.devtools/html/common_tools/smart_dev_bridge.htm @@ -1,302 +1,302 @@ - - - - - - - - - - - - - - Smart Development Bridge - - - - -
-
-

Mobile Web Wearable Web Mobile native Wearable native

-
- -
-

Content

- -
-
- -
- -

Smart Development Bridge

- -

The Smart Development Bridge (SDB) is a device management tool included in the Tizen SDK:

-
    -
  • The SDB manages multiple device connections. You can list connected devices and send a command to a specific device with a serial number that is created by the SDB.
  • -
  • The SDB supplies basic commands for application development, such as file transfer, remote shell command, port forwarding for a debugger, viewing, filtering, and controlling device log output.
  • -
  • The SDB also includes the Emulator.
  • -
- -

To use the SDB:

-
    -
  1. To use the SDB in a target device, set the device to the SDB mode by going to Settings > More system settings > Developer options > USB debugging in the device menu.
  2. -
  3. Run the SDB with a shell using the following command: -
    $ sdb [option] <command> [parameters]
    - -

    Where [option] can be:

    -
      -
    • -d: Directs the command to the only connected USB device and return an error if more than one USB device is present.
    • -
    • -e: Direct the command to the only running Emulator and return an error if more than one Emulator is present.
    • -
    • -s <serial number>: Direct the command to the USB device or Emulator with the defined serial number. -

      If multiple Emulator or device instances are running, you need to specify a target instance in the SDB command.

      -
    • -
    • devices: List all connected devices. -

      Before issuing SDB commands, it is helpful to know which Emulator or device instances are connected to the SDB server. In response to this command option, the SDB prints the serial number (a string created by the SDB to uniquely identify an Emulator or device instance) and connection status for each connected device. The connection status can be offline (the instance is not connected to the SDB or is not responding) or device (the instance is connected to the SDB server).

      -

      The following snippet shows an example of the command output:

      -
      $ sdb devices
      -List of devices attached 
      -emulator-26100 device myemulator1
      -emulator-26200 device myemulator2
      -$
      -
      - - -
    • -
    -

    For more information about the available commands and their parameters (<command> [parameters]), see SDB Commands.

    -
  4. -
  5. To stop the SDB server, use the kill-server command. -

    If the SDB does not respond to a command, try to terminate and restart it to resolve the problem. You can restart the server after stopping it by issuing any SDB command.

    -
  6. -
- - -

SDB Commands

- -

The following table lists the commands available for the Smart Development Bridge (SDB).

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Table: SDB commands
CommandDescription
sdb devicesList all connected devices.
sdb connect <host>[:<port>]Connect to a device through TCP/IP.
sdb disconnect <host>[:<port>]Disconnect from a TCP/IP device. -

Port 26101 is used by default if no port number is specified. Using this command with no additional arguments disconnects from all connected TCP/IP devices.

sdb push <local> <remote> [-with-utf8]Copy a file or directory recursively to the device's data file. -

The <local> and <remote> parameters refer to the paths to the target files or directories on the development machine (local) and the device instance (remote). The following command shows an example:

-

The [-with-utf8] parameter creates the remote file with the UTF-8 character encoding.

-
$ sdb push data.txt /opt/apps/org.tizen.hellotizen/data/data.txt
-
sdb pull <remote> [<local>]Copy a file or directory recursively from the device's data file. -

The <remote> and <local> parameters refer to the paths to the target files or directories on the device instance (remote) and the development machine (local). The following command shows an example:

-
$ sdb pull /opt/apps/org.tizen.hellotizen/data/data.txt data.txt
sdb shellRun a remote shell interactively by dropping into a remote shell on an Emulator or device instance. -

To exit the remote shell, press Ctrl+D or use the exit command to end the shell session.

-
sdb shell <command>Run a remote shell command without entering the SDB remote shell on the device. The following commands are available:

ls, rm, mv, cd, mkdir, cp, touch, echo, tar, grep, cat, chmod, rpm, find, uname, netstat, and killall

sdb dlog [option] [<filter-spec>]View and follow the content of the device log buffers. -

To view the log output in your development computer or from a remote SDB shell, use the sdb dlog or dlogutil command, respectively.

- -

The [<filter-spec>] parameter defines the tag of interest (the system component from which the message originates) and the minimum level of priority to report for that tag. The format is tag:priority, and multiple filters must be separated with a space. The available priorities (from lowest to highest) are V (Verbose), D (Debug), I (Info), W (Warning), E (Error), and F (Fatal).

- -

For example, to view all log messages of the info priority in addition to the MyApp tag messages of the debug priority, use the following command:

- -
$ sdb dlog MyApp:D *:E
- - -

For more information about the command options, see Controlling Log Output.

-
sdb install <path_to_tpk>

Push the tpk package file to the device and install it.

-

The <path_to_tpk> parameter defines to the path to the tpk file. The following command shows an example:

-
$ sdb install /home/tizen/ko983dw33q-1.0.0-i386.tpk
-
sdb uninstall <appid>

Uninstall the application from the device.

-

The <appid> parameter defines the application ID of the application. The following command shows an example:

-
$ sdb uninstall ko983dw33q
-
sdb forward <local> <remote>Set up arbitrary port forwarding of requests from a specific host port to a different port on a device instance. -

The format for the <local> and <remote> parameters is tcp:<port>. The following example shows how to forward requests from host port 26102 to device port 9999:

-
$ sdb forward tcp:26102 tcp:9999
- -

After setting up port forwarding, development tools between the device and host can work remotely. For example, gdb in a host/gdbserver in a device, and gdbserver in a device open with the tcp:9999 port:

-
$ sdb shell gdbserver:9999 hellotizen
- -

gdb in a host connects to localhost:26102

-
$ gdb hellotizen ... (gdb) target remote localhost:26102
- - -
sdb helpShow the help message.
sdb versionShow the version number.
sdb start-serverStart the server if it is not running.
sdb kill-serverStop the server if it is running.
sdb get-statePrint the target device connection status: device of offline.
sdb get-serialnoPrint the serial number of the target device.
sdb status-windowContinuously print the connection status for a specified device.
sdb root <on|off>Switch between the root and developer account mode. -

The on value sets the root mode and the off value sets the developer account mode.

- -

Controlling Log Output

- -

The following list defines the available options for the sdb dlog and logutil commands:

-
    -
  • -b <buffer> -

    Alternate log buffer. The main buffer is used as a default buffer.

    -
  • - -
  • -c -

    Clear the entire log and exit.

    -
  • - -
  • -d -

    Dump the log and exit.

    -
  • - -
  • -f <filename> -

    Write the log to the <filename> file. The default file is stdout.

    -
  • - -
  • -g -

    Print the size of the specified log buffer and exit.

    -
  • - -
  • -n <count> -

    Set the maximum number of rotated logs to <count>. The default value is 4. This option also requires the -r option.

    -
  • - -
  • -r <Kbytes> -

    Rotate the log file every <Kbytes> of output. The default value is 16. This option also requires the -f option.

    -
  • - -
  • -s -

    Set the default filter to silent.

    -
  • - -
  • -v <format> -

    Set the output format for log messages.

    -

    You can define which metadata fields (such as tag and priority) are included in log messages by setting one of the following output formats:

    -
      -
    • brief: Displays the priority/tag and PID of the originating process. This is the default format.
    • -
    • process: Displays the PID only.
    • -
    • tag: Displays the priority/tag only.
    • -
    • thread: Displays the process:thread and priority/tag only.
    • -
    • raw: Displays the raw log message, with no other metadata fields.
    • -
    • time: Displays the date, invocation time, priority/tag, and PID of the originating process.
    • -
    • long: Displays all metadata fields and separate messages with a blank line.
    • -
    - -
  • -
- - - - - - -
- -Go to top - - - - - - + + + + + + + + + + + + + + Smart Development Bridge + + + + +
+
+

Mobile Web Wearable Web Mobile native Wearable native

+
+ +
+

Content

+ +
+
+ +
+ +

Smart Development Bridge

+ +

The Smart Development Bridge (SDB) is a device management tool included in the Tizen SDK:

+
    +
  • The SDB manages multiple device connections. You can list connected devices and send a command to a specific device with a serial number that is created by the SDB.
  • +
  • The SDB supplies basic commands for application development, such as file transfer, remote shell command, port forwarding for a debugger, viewing, filtering, and controlling device log output.
  • +
  • The SDB also includes the Emulator.
  • +
+ +

To use the SDB:

+
    +
  1. To use the SDB in a target device, set the device to the SDB mode by going to Settings > More system settings > Developer options > USB debugging in the device menu.
  2. +
  3. Run the SDB with a shell using the following command: +
    $ sdb [option] <command> [parameters]
    + +

    Where [option] can be:

    +
      +
    • -d: Directs the command to the only connected USB device and return an error if more than one USB device is present.
    • +
    • -e: Direct the command to the only running Emulator and return an error if more than one Emulator is present.
    • +
    • -s <serial number>: Direct the command to the USB device or Emulator with the defined serial number. +

      If multiple Emulator or device instances are running, you need to specify a target instance in the SDB command.

      +
    • +
    • devices: List all connected devices. +

      Before issuing SDB commands, it is helpful to know which Emulator or device instances are connected to the SDB server. In response to this command option, the SDB prints the serial number (a string created by the SDB to uniquely identify an Emulator or device instance) and connection status for each connected device. The connection status can be offline (the instance is not connected to the SDB or is not responding) or device (the instance is connected to the SDB server).

      +

      The following snippet shows an example of the command output:

      +
      $ sdb devices
      +List of devices attached 
      +emulator-26100 device myemulator1
      +emulator-26200 device myemulator2
      +$
      +
      + + +
    • +
    +

    For more information about the available commands and their parameters (<command> [parameters]), see SDB Commands.

    +
  4. +
  5. To stop the SDB server, use the kill-server command. +

    If the SDB does not respond to a command, try to terminate and restart it to resolve the problem. You can restart the server after stopping it by issuing any SDB command.

    +
  6. +
+ + +

SDB Commands

+ +

The following table lists the commands available for the Smart Development Bridge (SDB).

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table: SDB commands
CommandDescription
sdb devicesList all connected devices.
sdb connect <host>[:<port>]Connect to a device through TCP/IP.
sdb disconnect <host>[:<port>]Disconnect from a TCP/IP device. +

Port 26101 is used by default if no port number is specified. Using this command with no additional arguments disconnects from all connected TCP/IP devices.

sdb push <local> <remote> [-with-utf8]Copy a file or directory recursively to the device's data file. +

The <local> and <remote> parameters refer to the paths to the target files or directories on the development machine (local) and the device instance (remote). The following command shows an example:

+

The [-with-utf8] parameter creates the remote file with the UTF-8 character encoding.

+
$ sdb push data.txt /opt/apps/org.tizen.hellotizen/data/data.txt
+
sdb pull <remote> [<local>]Copy a file or directory recursively from the device's data file. +

The <remote> and <local> parameters refer to the paths to the target files or directories on the device instance (remote) and the development machine (local). The following command shows an example:

+
$ sdb pull /opt/apps/org.tizen.hellotizen/data/data.txt data.txt
sdb shellRun a remote shell interactively by dropping into a remote shell on an Emulator or device instance. +

To exit the remote shell, press Ctrl+D or use the exit command to end the shell session.

+
sdb shell <command>Run a remote shell command without entering the SDB remote shell on the device. The following commands are available:

ls, rm, mv, cd, mkdir, cp, touch, echo, tar, grep, cat, chmod, rpm, find, uname, netstat, and killall

sdb dlog [option] [<filter-spec>]View and follow the content of the device log buffers. +

To view the log output in your development computer or from a remote SDB shell, use the sdb dlog or dlogutil command, respectively.

+ +

The [<filter-spec>] parameter defines the tag of interest (the system component from which the message originates) and the minimum level of priority to report for that tag. The format is tag:priority, and multiple filters must be separated with a space. The available priorities (from lowest to highest) are V (Verbose), D (Debug), I (Info), W (Warning), E (Error), and F (Fatal).

+ +

For example, to view all log messages of the info priority in addition to the MyApp tag messages of the debug priority, use the following command:

+ +
$ sdb dlog MyApp:D *:E
+ + +

For more information about the command options, see Controlling Log Output.

+
sdb install <path_to_tpk>

Push the tpk package file to the device and install it.

+

The <path_to_tpk> parameter defines to the path to the tpk file. The following command shows an example:

+
$ sdb install /home/tizen/ko983dw33q-1.0.0-i386.tpk
+
sdb uninstall <appid>

Uninstall the application from the device.

+

The <appid> parameter defines the application ID of the application. The following command shows an example:

+
$ sdb uninstall ko983dw33q
+
sdb forward <local> <remote>Set up arbitrary port forwarding of requests from a specific host port to a different port on a device instance. +

The format for the <local> and <remote> parameters is tcp:<port>. The following example shows how to forward requests from host port 26102 to device port 9999:

+
$ sdb forward tcp:26102 tcp:9999
+ +

After setting up port forwarding, development tools between the device and host can work remotely. For example, gdb in a host/gdbserver in a device, and gdbserver in a device open with the tcp:9999 port:

+
$ sdb shell gdbserver:9999 hellotizen
+ +

gdb in a host connects to localhost:26102

+
$ gdb hellotizen ... (gdb) target remote localhost:26102
+ + +
sdb helpShow the help message.
sdb versionShow the version number.
sdb start-serverStart the server if it is not running.
sdb kill-serverStop the server if it is running.
sdb get-statePrint the target device connection status: device of offline.
sdb get-serialnoPrint the serial number of the target device.
sdb status-windowContinuously print the connection status for a specified device.
sdb root <on|off>Switch between the root and developer account mode. +

The on value sets the root mode and the off value sets the developer account mode.

+ +

Controlling Log Output

+ +

The following list defines the available options for the sdb dlog and logutil commands:

+
    +
  • -b <buffer> +

    Alternate log buffer. The main buffer is used as a default buffer.

    +
  • + +
  • -c +

    Clear the entire log and exit.

    +
  • + +
  • -d +

    Dump the log and exit.

    +
  • + +
  • -f <filename> +

    Write the log to the <filename> file. The default file is stdout.

    +
  • + +
  • -g +

    Print the size of the specified log buffer and exit.

    +
  • + +
  • -n <count> +

    Set the maximum number of rotated logs to <count>. The default value is 4. This option also requires the -r option.

    +
  • + +
  • -r <Kbytes> +

    Rotate the log file every <Kbytes> of output. The default value is 16. This option also requires the -f option.

    +
  • + +
  • -s +

    Set the default filter to silent.

    +
  • + +
  • -v <format> +

    Set the output format for log messages.

    +

    You can define which metadata fields (such as tag and priority) are included in log messages by setting one of the following output formats:

    +
      +
    • brief: Displays the priority/tag and PID of the originating process. This is the default format.
    • +
    • process: Displays the PID only.
    • +
    • tag: Displays the priority/tag only.
    • +
    • thread: Displays the process:thread and priority/tag only.
    • +
    • raw: Displays the raw log message, with no other metadata fields.
    • +
    • time: Displays the date, invocation time, priority/tag, and PID of the originating process.
    • +
    • long: Displays all metadata fields and separate messages with a blank line.
    • +
    + +
  • +
+ + + + + + +
+ +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.devtools/html/css/snippet.css b/org.tizen.devtools/html/css/snippet.css index f880409..2be1b1f 100644 --- a/org.tizen.devtools/html/css/snippet.css +++ b/org.tizen.devtools/html/css/snippet.css @@ -1,52 +1,52 @@ -/* Pretty printing styles. Used with prettify.js. */ - -/* SPAN elements with the classes below are added by prettyprint. */ -.pln { color: #000 } /* plain text */ - -@media screen { - .str { color: #793AFF } /* string content */ - .kwd { color: #7F0055 } /* a keyword */ - .com { color: green} /* a comment */ - .typ { color: #1C1C1C } /* a type name */ - .lit { color: black } /* a literal value */ - /* punctuation, lisp open bracket, lisp close bracket */ - .pun, .opn, .clo { color: #1C1C1C} - .tag { color: #008 } /* a markup tag name */ - .atn { color: #606 } /* a markup attribute name */ - .atv { color: #080 } /* a markup attribute value */ - .dec, .var { color: #606 } /* a declaration; a variable name */ - .fun { color: red } /* a function name */ -} - -/* Use higher contrast and text-weight for printable form. */ -@media print, projection { - .str { color: #060 } - .kwd { color: #006; font-weight: bold } - .com { color: #600; font-style: italic } - .typ { color: #404; font-weight: bold } - .lit { color: #044 } - .pun, .opn, .clo { color: #440 } - .tag { color: #006; font-weight: bold } - .atn { color: #404 } - .atv { color: #060 } -} - -/* Put a border around prettyprinted code snippets. */ -pre.prettyprint { overflow: auto; padding: 2px; border: 1px solid #888 } - -/* Specify class=linenums on a pre to get line numbering */ -ol.linenums { margin-top: 0; margin-bottom: 0 } /* IE indents via margin-left */ -li.L0, -li.L1, -li.L2, -li.L3, -li.L5, -li.L6, -li.L7, -li.L8 { list-style-type: none } -/* Alternate shading for lines */ -li.L1, -li.L3, -li.L5, -li.L7, -li.L9 { background: #eee } +/* Pretty printing styles. Used with prettify.js. */ + +/* SPAN elements with the classes below are added by prettyprint. */ +.pln { color: #000 } /* plain text */ + +@media screen { + .str { color: #793AFF } /* string content */ + .kwd { color: #7F0055 } /* a keyword */ + .com { color: green} /* a comment */ + .typ { color: #1C1C1C } /* a type name */ + .lit { color: black } /* a literal value */ + /* punctuation, lisp open bracket, lisp close bracket */ + .pun, .opn, .clo { color: #1C1C1C} + .tag { color: #008 } /* a markup tag name */ + .atn { color: #606 } /* a markup attribute name */ + .atv { color: #080 } /* a markup attribute value */ + .dec, .var { color: #606 } /* a declaration; a variable name */ + .fun { color: red } /* a function name */ +} + +/* Use higher contrast and text-weight for printable form. */ +@media print, projection { + .str { color: #060 } + .kwd { color: #006; font-weight: bold } + .com { color: #600; font-style: italic } + .typ { color: #404; font-weight: bold } + .lit { color: #044 } + .pun, .opn, .clo { color: #440 } + .tag { color: #006; font-weight: bold } + .atn { color: #404 } + .atv { color: #060 } +} + +/* Put a border around prettyprinted code snippets. */ +pre.prettyprint { overflow: auto; padding: 2px; border: 1px solid #888 } + +/* Specify class=linenums on a pre to get line numbering */ +ol.linenums { margin-top: 0; margin-bottom: 0 } /* IE indents via margin-left */ +li.L0, +li.L1, +li.L2, +li.L3, +li.L5, +li.L6, +li.L7, +li.L8 { list-style-type: none } +/* Alternate shading for lines */ +li.L1, +li.L3, +li.L5, +li.L7, +li.L9 { background: #eee } diff --git a/org.tizen.devtools/html/css/styles.css b/org.tizen.devtools/html/css/styles.css index 4c8f5a8..ad7ebcb 100644 --- a/org.tizen.devtools/html/css/styles.css +++ b/org.tizen.devtools/html/css/styles.css @@ -1,756 +1,756 @@ -@charset "utf-8"; - -body { - background: white; - color: #1C1C1C; - margin-right: 20px; - margin-left: 20px; - font-size: 9pt; - font-weight: normal; - font-family: Arial, Helvetica, sans-serif; -} - -h1, h2, h3, h4, h5, h6, p, table, td, caption, th, ol, dl, dd, dt, footer { - font-family: Arial, Verdana, Helvetica, sans-serif - } - -/* Set default font to 9 pt */ -table, div, p, dl, td, caption, th, ul, ol, li, dd, dt, pre, code { - font-size: 9pt; -} - -pre, code { - font-family: "Courier New", Courier, monospace; - border: 1px solid #719cc7; - margin: 6px 1.5px; - padding: 1px 1px 1px 1px; - font-weight: normal; - font-style: normal; -} - -h1 {font-size: 24pt; color: #0E437D;} -h2 {font-size: 18pt; color: #0E437D;} -h3 {font-size: 14pt; color: #1C1C1C;} -h4 {font-size: 12pt; color: #1C1C1C;} -h5 {font-size: 10pt; color: #1C1C1C;} - -h1, h2, h3, h4, h5 { - font-weight: bold; - font-style: normal; - line-height: normal; - margin-top: 16pt; -} - -caption, p.caption { - font-size: 9pt; - color: #1C1C1C; - font-weight: bold; - text-align: left; - margin-top: 20px; - margin-bottom: 0px; -} - -ol { - margin-bottom: 20px; -} - -ul ul , ol ul, ul ol, ol ol{ - margin-top: 10px; -} - -ul li, ol li { - margin-bottom: 10px; -} - -ol.tutorstep li { - border-top: 2px solid #719cc7; - list-style-position: inside; - font-weight: bold; - margin-top: 30px; - margin-left: -20px; - padding-top: 3px; - font-size: 12pt; -} - -ol.tutorstep li p{ - font-size: 9pt; - font-weight: normal; - margin-top: 10px; -} - -ol.tutorstep ol li, ol.tutorstep li ol li, ol.tutorstep li ul li { - font-size: 9pt; - list-style-position: outside; - margin-left: 0px; - font-weight: normal; -} - -ol.tutorstep ol li p, ol.tutorstep ul li p { - font-size: 9pt; - font-weight: normal; - margin-top: 5px; -} - -ol li p, ul li p { - font-size: 9pt; - font-weight: normal; - margin-bottom: 2px; - margin-top: 2px; -} - -ol ol , ol.tutorstep ol{ - font-size: 9pt; - font-weight: normal; - list-style-type: lower-alpha; - color: #1C1C1C; - border-style: none; - margin-top: 10px; -} - -ol.tutorstep ul { - margin-top: 10px; - font-size: 9pt; -} - -ol ol li, ol ul li, ol.tutorstep ol li, ol.tutorstep ul li { - border-style: none; - margin-top: 5px; - font-size: 9pt; -} - -ul { - font-size: 9pt; - font-weight: normal; - color: #1C1C1C; -} - - -/* End of font face declarations */ - -/* Set table borders and heading row background */ -table { - border: 0px; - border-collapse: collapse; - width: 100%; - margin-top: 20px; - margin-bottom: 20px; - background: white; -} - -th { - border-top: 2px solid #719cc7; - border-right: 1px solid #c6d9f1; - border-left: 1px solid #c6d9f1; - background-color: #f3f7fb; - padding: 4px; - color: #719cc7; - font-size: 9pt; - font-weight: bold; -} - -td { - border: 1px solid #c6d9f1; - vertical-align:top; - padding: 3px 20px 5px 20px; - } - -td.middle { - border: 1px solid #c6d9f1; - vertical-align:middle; - padding: 3px 20px 5px 20px; - } - -/* Notes stand out using a light top & bottom borders with yellow background */ -table.note { - border-top: 2px solid #719cc7; - border-left: 0px; - border-right: 0px; - width: 100%; -} - -tr.note { - text-align: left; -} - -th.note { - text-align: left; - background-color: #ddd9c3; - background-image: note.gif; - border-top: 2px solid #719cc7; - border-bottom:1px solid #719cc7; - border-right: none; - -} - -td.note, p.note { - background-color: #eeece1; - color: #1C1C1C; - padding: 5px; - margin-top:12px; - margin-bottom:12px; - border: none; -} - -/* Figure titles are centered and bolded */ -p.figure , ol.tutorstep li p.figure, ol.tutorstep ol li p.figure, ol.tutorstep ul li p.figure { - text-align: center; - font-weight: bold; -} - -/* Red background and white text for things that need fixing before release */ -.fix { - background-color: red; - font-weight: bold; - color: white; - } - -/* Classes for creating collapsible content */ -#banner { - padding: 8px 4px 8px 4px; - /* top right bottom left */ - border: 1px solid #7f7f7f; - width: 100%; - background-image: url("banner.png"); - text-align: left; - font-weight: bold; - font-size: 9pt; - color: #ffffff; -} - -#toc-navigation {width: 20%; position: fixed; right: 17px; top: 0; bottom: 51px; /* overflow: auto; *//* min-width: 200px; *//* background: white; */z-index: 100;padding-top: 10px;/* padding-bottom: 88px; */margin-bottom: 89px;} -#toc {padding: 0px 20px 5px 20px; /* border: 2px solid #567a9c; */ border-radius: 15px;position: absolute;top: 78px;bottom: 9px;overflow: auto;/* margin-bottom: 5px; */padding-bottom: 5px;border-bottom: 3px transparent solid;margin-left: 5px;} -#main {width: 75%; height: 90%;} -#container {width:100%;} -#container #contents {padding:0px 0 20px; overflow: auto;position: fixed;top: 0;bottom: 0;margin-bottom: 64px;right: 200px;left: 20px;} -body.no-toc #container #contents {right: 0;padding-right:30px;} -body.no-toc #toc-navigation {width: auto;} -body.no-toc .top {right: 19px; /* float:none; */ width: 28px;} -body.no-toc #profile {float: right;right: -32px;} -body.no-toc #profile p {padding: 0; margin: 0;} -#container #contents:after {content: "."; display: block; height: 20px; clear: both; visibility: hidden;} - #container #contents>.content {/* width:75%; */min-width: 600px;/* right: 300px; *//* position: fixed; */padding-right: 5px;} - #container #contents>.content>.cont { margin-bottom:80px; padding-bottom:80px; } - -.devicespecs-util {float:right; margin-top:25px;} - .devicespecs-util ul.dutil {margin:0; padding-bottom:0; height: 11px; list-style-type:none;} - .devicespecs-util ul.dutil:after {content: "."; display: block; height: 0px; clear: both; visibility: hidden;} - .devicespecs-util ul.dutil li {float:left; margin-right:8px; padding-right:8px; background:url('../images/bg_util_bar.gif') no-repeat right center; color:#666;} - .devicespecs-util ul.dutil li.none {margin-right:0; padding-right:0; background-image:none;} - .devicespecs-util ul.dutil li a { font-size:11px; color:#666; line-height: 11px;} - .devicespecs-util ul.dutil li a:hover { color:#222; } - .devicespecs-util ul.dutil li a:active { color:#222; } - -ul.devicespecifications {clear:both; width:100%; margin:0; padding: 0;} -ul.devicespecifications > li { width:100%; margin-top:0; padding-left:0; list-style-type:none; border:1px solid #799cd3; padding: 5px 0px 5px 0px;} -ul.devicespecifications li div.devicespec-con {width:90%; margin:10px 0 20px 0; padding:0 14px; font-size: 13px;} -ul.devicespecifications li div.devicespec-tit {/*height:22px;*/ padding-right: 71px; background-color:#ffffff; position: relative;} - ul.devicespecifications li div.devicespec-tit .items-tit { /*float:left;*/ margin:0 0 0 14px; padding:0; color:#567a9c; line-height: 22px; font-size: 14px; font-style:normal; font-weight: bold;} - - ul.devicespecifications li div.devicespec-tit .items-tit-h2 { /*float:left;*/ margin: 0px 0px 0px 14px; padding:0; line-height: 22px; font-size: 18pt; color: #0E437D; font-style:normal; font-weight: bold;} - ul.devicespecifications li div.devicespec-tit .items-tit-h3 { /*float:left;*/ margin:0 0 0 14px; padding:0; line-height: 22px; font-size: 14pt; color: #1C1C1C; font-style:normal; font-weight: bold;} - ul.devicespecifications li div.devicespec-tit .items-tit-h4 { /*float:left;*/ margin:0 0 0 14px; padding:0; line-height: 22px; font-size: 12pt; color: #1C1C1C; font-style:normal; font-weight: bold;} - - ul.devicespecifications li div.devicespec-tit > span {position: absolute; top: 0; right:0;background:#416cbb; display:block; height:22px; margin-right:0; border-left: solid 1px #7a9bd4; } - ul.devicespecifications li div.devicespec-tit > span a.bt-arr {display:block; width: 55px; height:15px; margin-left:0; padding-top:5px; padding-left: 14px; text-align:left; background: url('../images/ico_arr_hidden.gif') 46px 9px no-repeat;} - ul.devicespecifications li div.devicespec-tit > span a.bt-arr em {display:inline-block; height: 14px; line-height:11px; font-size:11px; color:#fff; font-style:normal; margin-right: 8px;} - ul.devicespecifications li div.devicespec-tit > span * {vertical-align:middle;} - - ul.devicespecifications li div.devicespec-con ul.con-list { width:100%; } - ul.devicespecifications li div.devicespec-con ul.con-list li {line-height: 18px; margin:0; padding:0 0 0 7px; background: url("../images/ico_bullet_2_7.gif") 0 8px no-repeat; } - -.ul.ul, .ul.ul li {margin-bottom: 10px; list-style-type: disc; border: none;} -.ul.ul ul, .ul.ul ul li, .ol.ol ul, .ol.ol ul li {list-style-type: circle;} -.ol.ol, .ol.ol li {list-style-type: decimal; border: none;} -.ol.ol ol, .ol.ol ol li, .ul.ul ol, .ul.ul ol li {list-style-type: lower-alpha;} - -.static-cont {width:100%; margin-bottom:40px;} - -.top {text-align: right;} -.toc, ul.toc{ - margin: 10px 0px 0px 0px; - padding-left: 13px; - list-style: disc; - font-size: 9pt; - line-height: 115%; - } - -.toc-title { - font-size: 12pt; - color: #0E437D; - font-weight: bold; - font-style: normal; - line-height: normal; - margin-top: 16pt; -} - -a.top { - display:block; - float: right; - position:fixed; - width: 28px; - height:89px; - bottom:50px; - z-index: 101; - right: 19%; - } - -a img {border: 0;} - -/* Footer includes space and a gray line above */ -#footer { - position: fixed; - /* width: 100%; */ - bottom: 0px; - text-align: center; - border-top: 1px solid #CCCCCC; - background-color: #FFFFFF; - left: 21px; right: 21px; -} - -.footer {font-size: 8pt;} - -caption { - font-size: 9pt; - color: #1C1C1C; - font-weight: bold; - text-align: center; - margin-top: 20px; - margin-bottom: 0px; -} - -div.qindex, div.navpath, div.navtab{ - background-color: #e8eef2; - border: 1px solid #84b0c7; - text-align: center; - margin: 2px; - padding: 2px; -} - -div.qindex, div.navpath { - width: 100%; - line-height: 140%; -} - -div.navtab { - margin-right: 15px; -} - -/* @group Link Styling */ - -a:link { - color: #719cc7; - text-decoration: underline; - font-weight: bold; -} - -a:hover { - color: #0e437d; -} - -a:visited { - text-decoration: underline; - color: #719cc7; - font-weight: bold; -} - -a.qindex { - font-weight: bold; - padding: 2px; -} - -a.qindex:hover { - text-decoration: underline; - color: #0e437d; - padding: 2px; -} - -a.qindex:visited { - text-decoration: underline; - font-weight: bold; - color: #719cc7; - padding: 2px; -} - -a.qindexHL { - text-decoration: underline; - font-weight: bold; - background-color: #6666cc; - color: #ffffff; - padding: 2px 6px; - border: 1px double #9295C2; -} - -a.qindexHL:hover { - text-decoration: none; - background-color: #6666cc; - color: #ffffff; - padding: 2px 6px; -} - -dl.el { - margin-left: -1cm -} - -.fragment { - font-family: monospace, fixed; - font-size: 105%; -} - -pre.fragment { - border: 1px solid #CCCCCC; - background-color: #f5f5f5; - padding: 4px 6px; - margin: 4px 8px 4px 2px; -} - -div.fragment { - border: 1px solid #CCCCCC; - background-color: #f5f5f5; - padding: 6px; -} - -div.ah { - background-color: black; - font-weight: bold; - color: #ffffff; - margin-bottom: 3px; - margin-top: 3px -} - -td.md { - background-color: #f5f5f5; - font-weight: bold; -} - -td.mdname1 { - background-color: #f5f5f5; - font-weight: bold; - color: #602020; -} - -td.mdname { - background-color: #f5f5f5; - font-weight: bold; - color: #602020; - width: 600px; -} - -div.groupHeader { - margin-left: 16px; - margin-top: 12px; - margin-bottom: 6px; - font-weight: bold; -} - -div.groupText { - margin-left: 16px; - font-style: italic; -} - -td.indexkey { - background-color: #eeeeff; - font-weight: bold; - border: 1px solid #CCCCCC; - margin: 2px 0px 2px 0; - padding: 2px 10px; -} - -td.indexvalue { - background-color: #eeeeff; - border: 1px solid #CCCCCC; - padding: 2px 10px; - margin: 2px 0px; -} - -tr.memlist { - background-color: #f0f0f0; -} - -p.formulaDsp { - text-align: center; -} - -img.formulaDsp { -} - -img.formulaInl { - vertical-align: middle; -} - -/* @group Code Colorization */ - -span.keyword { color: #008000 } -span.keywordtype { color: #604020 } -span.keywordflow { color: #e08000 } -span.comment { color: #800000 } -span.preprocessor { color: #806020 } -span.stringliteral { color: #002080 } -span.charliteral { color: #008080 } -span.vhdldigit { color: #ff00ff } -span.vhdlchar { color: #000000 } -span.vhdlkeyword { color: #700070 } -span.vhdllogic { color: #ff0000 } - -.mdTable { - border: 1px solid #868686; - background-color: #F4F4FB; -} - -.mdRow { - padding: 8px 10px; -} - -/* @group Member Descriptions */ - -.mdescLeft, .mdescRight, -.memItemLeft, .memItemRight, -.memTemplItemLeft, .memTemplItemRight, .memTemplParams { - background-color: #F4F4F4A; - border: none; - margin: 4px; - padding: 3px 8px 4px 8px; -} - -.mdescLeft, .mdescRight { - padding: 0px 8px 4px 8px; - color: #555; -} - -.memItemLeft, .memItemRight, .memTemplParams { - border-top: 1px solid #DBDBDB; -} - -.memTemplParams { - color: #606060; -} - -/* @end */ - -/* @group Member Details */ - -/* Styles for detailed member documentation */ - -.memtemplate { - font-size: 80%; - color: #606060; - font-weight: normal; - margin-left: 3px; -} - -.memnav { - background-color: #eeeeff; - border: 1px solid #84b0c7; - text-align: center; - margin: 2px; - margin-right: 15px; - padding: 2px; -} - -.memitem { - padding: 0; -} - -.memname { - white-space: nowrap; - font-weight: bold; -} - -.memproto, .memdoc { - border: 1px solid #9BBCDD; -} - -.memproto { - padding: 0; - background-color: #D5E2EF; - font-weight: bold; - -webkit-border-top-left-radius: 8px; - -webkit-border-top-right-radius: 8px; - -moz-border-radius-topleft: 8px; - -moz-border-radius-topright: 8px; -} - -.memdoc { - padding: 2px 5px; - background-color: #eef3f5; - border-top-width: 0; - -webkit-border-bottom-left-radius: 8px; - -webkit-border-bottom-right-radius: 8px; - -moz-border-radius-bottomleft: 8px; - -moz-border-radius-bottomright: 8px; -} - -.memdoc p, .memdoc dl, .memdoc ul { - margin: 6px 0; -} - -.paramkey { - text-align: right; -} - -.paramtype { - white-space: nowrap; -} - -.paramname { - color: #853E0E; - white-space: nowrap; -} -.paramname em { - font-style: normal; -} - -/* @end */ - -.search { color: #003399; - font-weight: bold; -} - -form.search { - margin-bottom: 0px; - margin-top: 0px; -} - -input.search { font-size: 75%; - color: #000080; - font-weight: normal; - background-color: #eeeeff; -} - -td.tiny { - font-size: 75%; -} - -.highlight { - background-color:#E2E2FF; -} - -/*---------- ide-eclipse Styles ---------*/ -.sh_ide-eclipse{font-family: "Courier New", Courier, monospace; - margin: 0px 0px; - padding: -30px -30px -30px -30px; - font-weight: normal; - font-style: normal;} -.sh_ide-eclipse .sh_sourceCode{background-color:#fff;color:#000;font-weight:normal;font-style:normal;} -.sh_ide-eclipse .sh_sourceCode .sh_keyword{color:#7f0055;font-weight:bold;font-style:normal;} -.sh_ide-eclipse .sh_sourceCode .sh_type{color:#7f0055;font-weight:bold;font-style:normal;} -/*.sh_ide-eclipse .sh_sourceCode .sh_string{color:#00f;font-weight:normal;font-style:normal;}*/ -.sh_ide-eclipse .sh_sourceCode .sh_string{color:#2A00FF;font-weight:normal;font-style:normal;} - -.sh_ide-eclipse .sh_sourceCode .sh_regexp{color:#00f;font-weight:normal;font-style:normal;} -.sh_ide-eclipse .sh_sourceCode .sh_specialchar{color:#00f;font-weight:normal;font-style:normal;} -.sh_ide-eclipse .sh_sourceCode .sh_comment{color:#238E23;font-weight:normal;font-style:normal;} -.sh_ide-eclipse .sh_sourceCode .sh_number{color:#000;font-weight:normal;font-style:normal;} -.sh_ide-eclipse .sh_sourceCode .sh_preproc{color:#3f5fbf;font-weight:normal;font-style:normal;} -.sh_ide-eclipse .sh_sourceCode .sh_function{color:#000;font-weight:normal;font-style:normal;} -.sh_ide-eclipse .sh_sourceCode .sh_url{color:#00f;font-weight:normal;font-style:normal;} -.sh_ide-eclipse .sh_sourceCode .sh_date{color:#7f0055;font-weight:bold;font-style:normal;} -.sh_ide-eclipse .sh_sourceCode .sh_time{color:#7f0055;font-weight:bold;font-style:normal;} -.sh_ide-eclipse .sh_sourceCode .sh_file{color:#7f0055;font-weight:bold;font-style:normal;} -.sh_ide-eclipse .sh_sourceCode .sh_ip{color:#00f;font-weight:normal;font-style:normal;} -.sh_ide-eclipse .sh_sourceCode .sh_name{color:#00f;font-weight:normal;font-style:normal;} -.sh_ide-eclipse .sh_sourceCode .sh_variable{color:#7f0055;font-weight:bold;font-style:normal;} -.sh_ide-eclipse .sh_sourceCode .sh_oldfile{color:#00f;font-weight:normal;font-style:normal;} -.sh_ide-eclipse .sh_sourceCode .sh_newfile{color:#00f;font-weight:normal;font-style:normal;} -.sh_ide-eclipse .sh_sourceCode .sh_difflines{color:#7f0055;font-weight:bold;font-style:normal;} -.sh_ide-eclipse .sh_sourceCode .sh_selector{color:#7f0055;font-weight:bold;font-style:normal;} -.sh_ide-eclipse .sh_sourceCode .sh_property{color:#7f0055;font-weight:bold;font-style:normal;} -.sh_ide-eclipse .sh_sourceCode .sh_value{color:#00f;font-weight:normal;font-style:normal;} -.sh_ide-eclipse .sh_sourceCode .sh_unknown{font-family: "Courier New", Courier, monospace;} - -/*------------- STYLE FOR NAMES FROM XML FILE -------------*/ -.sh_styleFromXML{color:#800000;font-weight:bold;} -/*-------------------------------------------------------*/ - -/*-------- Snippet Base Styles ----------*/ -.snippet-wrap {position:relative;} -*:first-child+html .snippet-wrap {display:inline-block;} -* html .snippet-wrap {display:inline-block;} -.snippet-reveal{text-decoration:underline;} -.snippet-wrap .snippet-menu, .snippet-wrap .snippet-hide {position:absolute; top:-99999px; right:15px; font-size:.9em;z-index:1;background-color:transparent;} -.snippet-wrap .snippet-hide {top:auto; bottom:1px;} -*:first-child+html .snippet-wrap .snippet-hide {bottom:1px;} -* html .snippet-wrap .snippet-hide {bottom:1px;} -.snippet-wrap .snippet-menu pre, .snippet-wrap .snippet-hide pre {background-color:transparent; margin:1; padding:0;} -.snippet-wrap .snippet-menu a, .snippet-wrap .snippet-hide a {padding:1px; text-decoration:underline;} -.snippet-wrap pre.sh_sourceCode{padding:1px;line-height:120%;overflow:auto;position:relative; --moz-border-radius:0px; --webkit-border-radius:0px; -border-radius:0px; -box-shadow: 1px 1px px #000; --moz-box-shadow: 2px 2px 1px #000; --webkit-box-shadow: 1px 1px 1px #000;} -.snippet-wrap pre.snippet-textonly {padding:1em;} -*:first-child+html .snippet-wrap pre.snippet-formatted {padding:0.5em 0.5em;} -* html .snippet-wrap pre.snippet-formatted {padding:0em 0.3em;} -.snippet-reveal pre.sh_sourceCode {padding:0em 0em; text-align:right;} -.snippet-wrap .snippet-num li{padding-left:2px;} -.snippet-wrap .snippet-no-num{list-style:none; padding:0em 0em; margin:0;} -.snippet-wrap .snippet-no-num li {list-style:none; padding-left:0;} -.snippet-wrap .snippet-num {margin:1em 0 1em 1em; padding-left:2px;} -.snippet-wrap .snippet-num li {list-style:decimal-leading-zero outside none;} -.snippet-wrap .snippet-no-num li.box {padding:0 6px; margin-left:-6px;} -.snippet-wrap .snippet-num li.box {border:1px solid; list-style-position:inside; margin-left:0px; padding-left:2px;} -*:first-child+html .snippet-wrap .snippet-num li.box {margin-left:-2px;} -* html .snippet-wrap .snippet-num li.box {margin-left:-2px;} -.snippet-wrap li.box-top {border-width:0px 0px 0 !important;} -.snippet-wrap li.box-bot {border-width:0 0px 0px !important;} -.snippet-wrap li.box-mid {border-width:0 0px !important;} -.snippet-wrap .snippet-num li .box-sp {width:10px; display:inline-block;} -*:first-child+html .snippet-wrap .snippet-num li .box-sp {width:20px;} -* html .snippet-wrap .snippet-num li .box-sp {width:2px;} -.snippet-wrap .snippet-no-num li.box {border:1px solid;} -.snippet-wrap .snippet-no-num li .box-sp {display:none;} - -/* Layout fixing */ -.clfix:after {content: "."; display: block; height: 0px; clear: both; visibility: hidden;} -.clfix {display: inline-block;} -.clfix {display: block;} -* html .clfix {height: 1%;} /* Hides from IE-mac */ -.clfix {zoom:1;} /*for IE 5.5-7*/ - -.fl {float:left !important;} -.fr {float:right !important;} -.cl {clear:both;} -.rel {position:relative;} -.abs {position:absolute;} -.ac {text-align:center !important;} -.ar {text-align:right !important;} -.al {text-align:left !important;} -.at {vertical-align:top !important;} -.am {vertical-align:middle !important;} -.ab {vertical-align:bottom;} -.hand {cursor:pointer;} -.bgnone {background:none !important;} -.brnone {border:none !important;} -.b {font-weight:bold !important;} -.n {font-weight:normal !important;} -.invisible{display:block; overflow:hidden; visibility:hidden; width:0; height:0; margin:0; font-size:0; line-height:0;} -.mt5 {margin-top:5px !important;} -/* //Layout fixing */ - -@media print { .hide, .show { display: none; }} - -div#profile { - position: relative; -} -#profile p { - text-align: right; -} - -div#toc_border { - border: 2px solid rgb(86, 122, 156); border-top-left-radius: 15px; border-top-right-radius: 15px; border-bottom-right-radius: 15px; border-bottom-left-radius: 15px; height: 565px; -} - -#contents li { - padding-top: 3px; - margin-top: 5px; - /* overflow: auto; */ -} - -p { - /* overflow: auto; */ -} - -div.table { - /* overflow: auto; */ +@charset "utf-8"; + +body { + background: white; + color: #1C1C1C; + margin-right: 20px; + margin-left: 20px; + font-size: 9pt; + font-weight: normal; + font-family: Arial, Helvetica, sans-serif; +} + +h1, h2, h3, h4, h5, h6, p, table, td, caption, th, ol, dl, dd, dt, footer { + font-family: Arial, Verdana, Helvetica, sans-serif + } + +/* Set default font to 9 pt */ +table, div, p, dl, td, caption, th, ul, ol, li, dd, dt, pre, code { + font-size: 9pt; +} + +pre, code { + font-family: "Courier New", Courier, monospace; + border: 1px solid #719cc7; + margin: 6px 1.5px; + padding: 1px 1px 1px 1px; + font-weight: normal; + font-style: normal; +} + +h1 {font-size: 24pt; color: #0E437D;} +h2 {font-size: 18pt; color: #0E437D;} +h3 {font-size: 14pt; color: #1C1C1C;} +h4 {font-size: 12pt; color: #1C1C1C;} +h5 {font-size: 10pt; color: #1C1C1C;} + +h1, h2, h3, h4, h5 { + font-weight: bold; + font-style: normal; + line-height: normal; + margin-top: 16pt; +} + +caption, p.caption { + font-size: 9pt; + color: #1C1C1C; + font-weight: bold; + text-align: left; + margin-top: 20px; + margin-bottom: 0px; +} + +ol { + margin-bottom: 20px; +} + +ul ul , ol ul, ul ol, ol ol{ + margin-top: 10px; +} + +ul li, ol li { + margin-bottom: 10px; +} + +ol.tutorstep li { + border-top: 2px solid #719cc7; + list-style-position: inside; + font-weight: bold; + margin-top: 30px; + margin-left: -20px; + padding-top: 3px; + font-size: 12pt; +} + +ol.tutorstep li p{ + font-size: 9pt; + font-weight: normal; + margin-top: 10px; +} + +ol.tutorstep ol li, ol.tutorstep li ol li, ol.tutorstep li ul li { + font-size: 9pt; + list-style-position: outside; + margin-left: 0px; + font-weight: normal; +} + +ol.tutorstep ol li p, ol.tutorstep ul li p { + font-size: 9pt; + font-weight: normal; + margin-top: 5px; +} + +ol li p, ul li p { + font-size: 9pt; + font-weight: normal; + margin-bottom: 2px; + margin-top: 2px; +} + +ol ol , ol.tutorstep ol{ + font-size: 9pt; + font-weight: normal; + list-style-type: lower-alpha; + color: #1C1C1C; + border-style: none; + margin-top: 10px; +} + +ol.tutorstep ul { + margin-top: 10px; + font-size: 9pt; +} + +ol ol li, ol ul li, ol.tutorstep ol li, ol.tutorstep ul li { + border-style: none; + margin-top: 5px; + font-size: 9pt; +} + +ul { + font-size: 9pt; + font-weight: normal; + color: #1C1C1C; +} + + +/* End of font face declarations */ + +/* Set table borders and heading row background */ +table { + border: 0px; + border-collapse: collapse; + width: 100%; + margin-top: 20px; + margin-bottom: 20px; + background: white; +} + +th { + border-top: 2px solid #719cc7; + border-right: 1px solid #c6d9f1; + border-left: 1px solid #c6d9f1; + background-color: #f3f7fb; + padding: 4px; + color: #719cc7; + font-size: 9pt; + font-weight: bold; +} + +td { + border: 1px solid #c6d9f1; + vertical-align:top; + padding: 3px 20px 5px 20px; + } + +td.middle { + border: 1px solid #c6d9f1; + vertical-align:middle; + padding: 3px 20px 5px 20px; + } + +/* Notes stand out using a light top & bottom borders with yellow background */ +table.note { + border-top: 2px solid #719cc7; + border-left: 0px; + border-right: 0px; + width: 100%; +} + +tr.note { + text-align: left; +} + +th.note { + text-align: left; + background-color: #ddd9c3; + background-image: note.gif; + border-top: 2px solid #719cc7; + border-bottom:1px solid #719cc7; + border-right: none; + +} + +td.note, p.note { + background-color: #eeece1; + color: #1C1C1C; + padding: 5px; + margin-top:12px; + margin-bottom:12px; + border: none; +} + +/* Figure titles are centered and bolded */ +p.figure , ol.tutorstep li p.figure, ol.tutorstep ol li p.figure, ol.tutorstep ul li p.figure { + text-align: center; + font-weight: bold; +} + +/* Red background and white text for things that need fixing before release */ +.fix { + background-color: red; + font-weight: bold; + color: white; + } + +/* Classes for creating collapsible content */ +#banner { + padding: 8px 4px 8px 4px; + /* top right bottom left */ + border: 1px solid #7f7f7f; + width: 100%; + background-image: url("banner.png"); + text-align: left; + font-weight: bold; + font-size: 9pt; + color: #ffffff; +} + +#toc-navigation {width: 20%; position: fixed; right: 17px; top: 0; bottom: 51px; /* overflow: auto; *//* min-width: 200px; *//* background: white; */z-index: 100;padding-top: 10px;/* padding-bottom: 88px; */margin-bottom: 89px;} +#toc {padding: 0px 20px 5px 20px; /* border: 2px solid #567a9c; */ border-radius: 15px;position: absolute;top: 78px;bottom: 9px;overflow: auto;/* margin-bottom: 5px; */padding-bottom: 5px;border-bottom: 3px transparent solid;margin-left: 5px;} +#main {width: 75%; height: 90%;} +#container {width:100%;} +#container #contents {padding:0px 0 20px; overflow: auto;position: fixed;top: 0;bottom: 0;margin-bottom: 64px;right: 200px;left: 20px;} +body.no-toc #container #contents {right: 0;padding-right:30px;} +body.no-toc #toc-navigation {width: auto;} +body.no-toc .top {right: 19px; /* float:none; */ width: 28px;} +body.no-toc #profile {float: right;right: -32px;} +body.no-toc #profile p {padding: 0; margin: 0;} +#container #contents:after {content: "."; display: block; height: 20px; clear: both; visibility: hidden;} + #container #contents>.content {/* width:75%; */min-width: 600px;/* right: 300px; *//* position: fixed; */padding-right: 5px;} + #container #contents>.content>.cont { margin-bottom:80px; padding-bottom:80px; } + +.devicespecs-util {float:right; margin-top:25px;} + .devicespecs-util ul.dutil {margin:0; padding-bottom:0; height: 11px; list-style-type:none;} + .devicespecs-util ul.dutil:after {content: "."; display: block; height: 0px; clear: both; visibility: hidden;} + .devicespecs-util ul.dutil li {float:left; margin-right:8px; padding-right:8px; background:url('../images/bg_util_bar.gif') no-repeat right center; color:#666;} + .devicespecs-util ul.dutil li.none {margin-right:0; padding-right:0; background-image:none;} + .devicespecs-util ul.dutil li a { font-size:11px; color:#666; line-height: 11px;} + .devicespecs-util ul.dutil li a:hover { color:#222; } + .devicespecs-util ul.dutil li a:active { color:#222; } + +ul.devicespecifications {clear:both; width:100%; margin:0; padding: 0;} +ul.devicespecifications > li { width:100%; margin-top:0; padding-left:0; list-style-type:none; border:1px solid #799cd3; padding: 5px 0px 5px 0px;} +ul.devicespecifications li div.devicespec-con {width:90%; margin:10px 0 20px 0; padding:0 14px; font-size: 13px;} +ul.devicespecifications li div.devicespec-tit {/*height:22px;*/ padding-right: 71px; background-color:#ffffff; position: relative;} + ul.devicespecifications li div.devicespec-tit .items-tit { /*float:left;*/ margin:0 0 0 14px; padding:0; color:#567a9c; line-height: 22px; font-size: 14px; font-style:normal; font-weight: bold;} + + ul.devicespecifications li div.devicespec-tit .items-tit-h2 { /*float:left;*/ margin: 0px 0px 0px 14px; padding:0; line-height: 22px; font-size: 18pt; color: #0E437D; font-style:normal; font-weight: bold;} + ul.devicespecifications li div.devicespec-tit .items-tit-h3 { /*float:left;*/ margin:0 0 0 14px; padding:0; line-height: 22px; font-size: 14pt; color: #1C1C1C; font-style:normal; font-weight: bold;} + ul.devicespecifications li div.devicespec-tit .items-tit-h4 { /*float:left;*/ margin:0 0 0 14px; padding:0; line-height: 22px; font-size: 12pt; color: #1C1C1C; font-style:normal; font-weight: bold;} + + ul.devicespecifications li div.devicespec-tit > span {position: absolute; top: 0; right:0;background:#416cbb; display:block; height:22px; margin-right:0; border-left: solid 1px #7a9bd4; } + ul.devicespecifications li div.devicespec-tit > span a.bt-arr {display:block; width: 55px; height:15px; margin-left:0; padding-top:5px; padding-left: 14px; text-align:left; background: url('../images/ico_arr_hidden.gif') 46px 9px no-repeat;} + ul.devicespecifications li div.devicespec-tit > span a.bt-arr em {display:inline-block; height: 14px; line-height:11px; font-size:11px; color:#fff; font-style:normal; margin-right: 8px;} + ul.devicespecifications li div.devicespec-tit > span * {vertical-align:middle;} + + ul.devicespecifications li div.devicespec-con ul.con-list { width:100%; } + ul.devicespecifications li div.devicespec-con ul.con-list li {line-height: 18px; margin:0; padding:0 0 0 7px; background: url("../images/ico_bullet_2_7.gif") 0 8px no-repeat; } + +.ul.ul, .ul.ul li {margin-bottom: 10px; list-style-type: disc; border: none;} +.ul.ul ul, .ul.ul ul li, .ol.ol ul, .ol.ol ul li {list-style-type: circle;} +.ol.ol, .ol.ol li {list-style-type: decimal; border: none;} +.ol.ol ol, .ol.ol ol li, .ul.ul ol, .ul.ul ol li {list-style-type: lower-alpha;} + +.static-cont {width:100%; margin-bottom:40px;} + +.top {text-align: right;} +.toc, ul.toc{ + margin: 10px 0px 0px 0px; + padding-left: 13px; + list-style: disc; + font-size: 9pt; + line-height: 115%; + } + +.toc-title { + font-size: 12pt; + color: #0E437D; + font-weight: bold; + font-style: normal; + line-height: normal; + margin-top: 16pt; +} + +a.top { + display:block; + float: right; + position:fixed; + width: 28px; + height:89px; + bottom:50px; + z-index: 101; + right: 19%; + } + +a img {border: 0;} + +/* Footer includes space and a gray line above */ +#footer { + position: fixed; + /* width: 100%; */ + bottom: 0px; + text-align: center; + border-top: 1px solid #CCCCCC; + background-color: #FFFFFF; + left: 21px; right: 21px; +} + +.footer {font-size: 8pt;} + +caption { + font-size: 9pt; + color: #1C1C1C; + font-weight: bold; + text-align: center; + margin-top: 20px; + margin-bottom: 0px; +} + +div.qindex, div.navpath, div.navtab{ + background-color: #e8eef2; + border: 1px solid #84b0c7; + text-align: center; + margin: 2px; + padding: 2px; +} + +div.qindex, div.navpath { + width: 100%; + line-height: 140%; +} + +div.navtab { + margin-right: 15px; +} + +/* @group Link Styling */ + +a:link { + color: #719cc7; + text-decoration: underline; + font-weight: bold; +} + +a:hover { + color: #0e437d; +} + +a:visited { + text-decoration: underline; + color: #719cc7; + font-weight: bold; +} + +a.qindex { + font-weight: bold; + padding: 2px; +} + +a.qindex:hover { + text-decoration: underline; + color: #0e437d; + padding: 2px; +} + +a.qindex:visited { + text-decoration: underline; + font-weight: bold; + color: #719cc7; + padding: 2px; +} + +a.qindexHL { + text-decoration: underline; + font-weight: bold; + background-color: #6666cc; + color: #ffffff; + padding: 2px 6px; + border: 1px double #9295C2; +} + +a.qindexHL:hover { + text-decoration: none; + background-color: #6666cc; + color: #ffffff; + padding: 2px 6px; +} + +dl.el { + margin-left: -1cm +} + +.fragment { + font-family: monospace, fixed; + font-size: 105%; +} + +pre.fragment { + border: 1px solid #CCCCCC; + background-color: #f5f5f5; + padding: 4px 6px; + margin: 4px 8px 4px 2px; +} + +div.fragment { + border: 1px solid #CCCCCC; + background-color: #f5f5f5; + padding: 6px; +} + +div.ah { + background-color: black; + font-weight: bold; + color: #ffffff; + margin-bottom: 3px; + margin-top: 3px +} + +td.md { + background-color: #f5f5f5; + font-weight: bold; +} + +td.mdname1 { + background-color: #f5f5f5; + font-weight: bold; + color: #602020; +} + +td.mdname { + background-color: #f5f5f5; + font-weight: bold; + color: #602020; + width: 600px; +} + +div.groupHeader { + margin-left: 16px; + margin-top: 12px; + margin-bottom: 6px; + font-weight: bold; +} + +div.groupText { + margin-left: 16px; + font-style: italic; +} + +td.indexkey { + background-color: #eeeeff; + font-weight: bold; + border: 1px solid #CCCCCC; + margin: 2px 0px 2px 0; + padding: 2px 10px; +} + +td.indexvalue { + background-color: #eeeeff; + border: 1px solid #CCCCCC; + padding: 2px 10px; + margin: 2px 0px; +} + +tr.memlist { + background-color: #f0f0f0; +} + +p.formulaDsp { + text-align: center; +} + +img.formulaDsp { +} + +img.formulaInl { + vertical-align: middle; +} + +/* @group Code Colorization */ + +span.keyword { color: #008000 } +span.keywordtype { color: #604020 } +span.keywordflow { color: #e08000 } +span.comment { color: #800000 } +span.preprocessor { color: #806020 } +span.stringliteral { color: #002080 } +span.charliteral { color: #008080 } +span.vhdldigit { color: #ff00ff } +span.vhdlchar { color: #000000 } +span.vhdlkeyword { color: #700070 } +span.vhdllogic { color: #ff0000 } + +.mdTable { + border: 1px solid #868686; + background-color: #F4F4FB; +} + +.mdRow { + padding: 8px 10px; +} + +/* @group Member Descriptions */ + +.mdescLeft, .mdescRight, +.memItemLeft, .memItemRight, +.memTemplItemLeft, .memTemplItemRight, .memTemplParams { + background-color: #F4F4F4A; + border: none; + margin: 4px; + padding: 3px 8px 4px 8px; +} + +.mdescLeft, .mdescRight { + padding: 0px 8px 4px 8px; + color: #555; +} + +.memItemLeft, .memItemRight, .memTemplParams { + border-top: 1px solid #DBDBDB; +} + +.memTemplParams { + color: #606060; +} + +/* @end */ + +/* @group Member Details */ + +/* Styles for detailed member documentation */ + +.memtemplate { + font-size: 80%; + color: #606060; + font-weight: normal; + margin-left: 3px; +} + +.memnav { + background-color: #eeeeff; + border: 1px solid #84b0c7; + text-align: center; + margin: 2px; + margin-right: 15px; + padding: 2px; +} + +.memitem { + padding: 0; +} + +.memname { + white-space: nowrap; + font-weight: bold; +} + +.memproto, .memdoc { + border: 1px solid #9BBCDD; +} + +.memproto { + padding: 0; + background-color: #D5E2EF; + font-weight: bold; + -webkit-border-top-left-radius: 8px; + -webkit-border-top-right-radius: 8px; + -moz-border-radius-topleft: 8px; + -moz-border-radius-topright: 8px; +} + +.memdoc { + padding: 2px 5px; + background-color: #eef3f5; + border-top-width: 0; + -webkit-border-bottom-left-radius: 8px; + -webkit-border-bottom-right-radius: 8px; + -moz-border-radius-bottomleft: 8px; + -moz-border-radius-bottomright: 8px; +} + +.memdoc p, .memdoc dl, .memdoc ul { + margin: 6px 0; +} + +.paramkey { + text-align: right; +} + +.paramtype { + white-space: nowrap; +} + +.paramname { + color: #853E0E; + white-space: nowrap; +} +.paramname em { + font-style: normal; +} + +/* @end */ + +.search { color: #003399; + font-weight: bold; +} + +form.search { + margin-bottom: 0px; + margin-top: 0px; +} + +input.search { font-size: 75%; + color: #000080; + font-weight: normal; + background-color: #eeeeff; +} + +td.tiny { + font-size: 75%; +} + +.highlight { + background-color:#E2E2FF; +} + +/*---------- ide-eclipse Styles ---------*/ +.sh_ide-eclipse{font-family: "Courier New", Courier, monospace; + margin: 0px 0px; + padding: -30px -30px -30px -30px; + font-weight: normal; + font-style: normal;} +.sh_ide-eclipse .sh_sourceCode{background-color:#fff;color:#000;font-weight:normal;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_keyword{color:#7f0055;font-weight:bold;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_type{color:#7f0055;font-weight:bold;font-style:normal;} +/*.sh_ide-eclipse .sh_sourceCode .sh_string{color:#00f;font-weight:normal;font-style:normal;}*/ +.sh_ide-eclipse .sh_sourceCode .sh_string{color:#2A00FF;font-weight:normal;font-style:normal;} + +.sh_ide-eclipse .sh_sourceCode .sh_regexp{color:#00f;font-weight:normal;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_specialchar{color:#00f;font-weight:normal;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_comment{color:#238E23;font-weight:normal;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_number{color:#000;font-weight:normal;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_preproc{color:#3f5fbf;font-weight:normal;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_function{color:#000;font-weight:normal;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_url{color:#00f;font-weight:normal;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_date{color:#7f0055;font-weight:bold;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_time{color:#7f0055;font-weight:bold;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_file{color:#7f0055;font-weight:bold;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_ip{color:#00f;font-weight:normal;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_name{color:#00f;font-weight:normal;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_variable{color:#7f0055;font-weight:bold;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_oldfile{color:#00f;font-weight:normal;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_newfile{color:#00f;font-weight:normal;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_difflines{color:#7f0055;font-weight:bold;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_selector{color:#7f0055;font-weight:bold;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_property{color:#7f0055;font-weight:bold;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_value{color:#00f;font-weight:normal;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_unknown{font-family: "Courier New", Courier, monospace;} + +/*------------- STYLE FOR NAMES FROM XML FILE -------------*/ +.sh_styleFromXML{color:#800000;font-weight:bold;} +/*-------------------------------------------------------*/ + +/*-------- Snippet Base Styles ----------*/ +.snippet-wrap {position:relative;} +*:first-child+html .snippet-wrap {display:inline-block;} +* html .snippet-wrap {display:inline-block;} +.snippet-reveal{text-decoration:underline;} +.snippet-wrap .snippet-menu, .snippet-wrap .snippet-hide {position:absolute; top:-99999px; right:15px; font-size:.9em;z-index:1;background-color:transparent;} +.snippet-wrap .snippet-hide {top:auto; bottom:1px;} +*:first-child+html .snippet-wrap .snippet-hide {bottom:1px;} +* html .snippet-wrap .snippet-hide {bottom:1px;} +.snippet-wrap .snippet-menu pre, .snippet-wrap .snippet-hide pre {background-color:transparent; margin:1; padding:0;} +.snippet-wrap .snippet-menu a, .snippet-wrap .snippet-hide a {padding:1px; text-decoration:underline;} +.snippet-wrap pre.sh_sourceCode{padding:1px;line-height:120%;overflow:auto;position:relative; +-moz-border-radius:0px; +-webkit-border-radius:0px; +border-radius:0px; +box-shadow: 1px 1px px #000; +-moz-box-shadow: 2px 2px 1px #000; +-webkit-box-shadow: 1px 1px 1px #000;} +.snippet-wrap pre.snippet-textonly {padding:1em;} +*:first-child+html .snippet-wrap pre.snippet-formatted {padding:0.5em 0.5em;} +* html .snippet-wrap pre.snippet-formatted {padding:0em 0.3em;} +.snippet-reveal pre.sh_sourceCode {padding:0em 0em; text-align:right;} +.snippet-wrap .snippet-num li{padding-left:2px;} +.snippet-wrap .snippet-no-num{list-style:none; padding:0em 0em; margin:0;} +.snippet-wrap .snippet-no-num li {list-style:none; padding-left:0;} +.snippet-wrap .snippet-num {margin:1em 0 1em 1em; padding-left:2px;} +.snippet-wrap .snippet-num li {list-style:decimal-leading-zero outside none;} +.snippet-wrap .snippet-no-num li.box {padding:0 6px; margin-left:-6px;} +.snippet-wrap .snippet-num li.box {border:1px solid; list-style-position:inside; margin-left:0px; padding-left:2px;} +*:first-child+html .snippet-wrap .snippet-num li.box {margin-left:-2px;} +* html .snippet-wrap .snippet-num li.box {margin-left:-2px;} +.snippet-wrap li.box-top {border-width:0px 0px 0 !important;} +.snippet-wrap li.box-bot {border-width:0 0px 0px !important;} +.snippet-wrap li.box-mid {border-width:0 0px !important;} +.snippet-wrap .snippet-num li .box-sp {width:10px; display:inline-block;} +*:first-child+html .snippet-wrap .snippet-num li .box-sp {width:20px;} +* html .snippet-wrap .snippet-num li .box-sp {width:2px;} +.snippet-wrap .snippet-no-num li.box {border:1px solid;} +.snippet-wrap .snippet-no-num li .box-sp {display:none;} + +/* Layout fixing */ +.clfix:after {content: "."; display: block; height: 0px; clear: both; visibility: hidden;} +.clfix {display: inline-block;} +.clfix {display: block;} +* html .clfix {height: 1%;} /* Hides from IE-mac */ +.clfix {zoom:1;} /*for IE 5.5-7*/ + +.fl {float:left !important;} +.fr {float:right !important;} +.cl {clear:both;} +.rel {position:relative;} +.abs {position:absolute;} +.ac {text-align:center !important;} +.ar {text-align:right !important;} +.al {text-align:left !important;} +.at {vertical-align:top !important;} +.am {vertical-align:middle !important;} +.ab {vertical-align:bottom;} +.hand {cursor:pointer;} +.bgnone {background:none !important;} +.brnone {border:none !important;} +.b {font-weight:bold !important;} +.n {font-weight:normal !important;} +.invisible{display:block; overflow:hidden; visibility:hidden; width:0; height:0; margin:0; font-size:0; line-height:0;} +.mt5 {margin-top:5px !important;} +/* //Layout fixing */ + +@media print { .hide, .show { display: none; }} + +div#profile { + position: relative; +} +#profile p { + text-align: right; +} + +div#toc_border { + border: 2px solid rgb(86, 122, 156); border-top-left-radius: 15px; border-top-right-radius: 15px; border-bottom-right-radius: 15px; border-bottom-left-radius: 15px; height: 565px; +} + +#contents li { + padding-top: 3px; + margin-top: 5px; + /* overflow: auto; */ +} + +p { + /* overflow: auto; */ +} + +div.table { + /* overflow: auto; */ } \ No newline at end of file diff --git a/org.tizen.devtools/html/images/Thumbs.db b/org.tizen.devtools/html/images/Thumbs.db new file mode 100644 index 0000000..02e945d Binary files /dev/null and b/org.tizen.devtools/html/images/Thumbs.db differ diff --git a/org.tizen.devtools/html/images/emulator_bridge_architecture.png b/org.tizen.devtools/html/images/emulator_bridge_architecture.png old mode 100755 new mode 100644 diff --git a/org.tizen.devtools/html/images/emulator_general_mobile.png b/org.tizen.devtools/html/images/emulator_general_mobile.png old mode 100755 new mode 100644 diff --git a/org.tizen.devtools/html/images/emulator_general_wearable.png b/org.tizen.devtools/html/images/emulator_general_wearable.png old mode 100755 new mode 100644 diff --git a/org.tizen.devtools/html/images/emulator_manager_ide.png b/org.tizen.devtools/html/images/emulator_manager_ide.png index e562b8c..410b513 100644 Binary files a/org.tizen.devtools/html/images/emulator_manager_ide.png and b/org.tizen.devtools/html/images/emulator_manager_ide.png differ diff --git a/org.tizen.devtools/html/images/emulator_nat_architecture.png b/org.tizen.devtools/html/images/emulator_nat_architecture.png old mode 100755 new mode 100644 diff --git a/org.tizen.devtools/html/images/features.png b/org.tizen.devtools/html/images/features.png old mode 100755 new mode 100644 diff --git a/org.tizen.devtools/html/images/manifest.png b/org.tizen.devtools/html/images/manifest.png old mode 100755 new mode 100644 diff --git a/org.tizen.devtools/html/images/privilege.png b/org.tizen.devtools/html/images/privilege.png old mode 100755 new mode 100644 diff --git a/org.tizen.devtools/html/images/ui_builder_1.png b/org.tizen.devtools/html/images/ui_builder_1.png deleted file mode 100644 index 8871bbb..0000000 Binary files a/org.tizen.devtools/html/images/ui_builder_1.png and /dev/null differ diff --git a/org.tizen.devtools/html/native_tools/manifest_elements_n.htm b/org.tizen.devtools/html/native_tools/manifest_elements_n.htm index 9007a67..818f26b 100644 --- a/org.tizen.devtools/html/native_tools/manifest_elements_n.htm +++ b/org.tizen.devtools/html/native_tools/manifest_elements_n.htm @@ -1,399 +1,363 @@ - - - - - - - - - - - - - - Additional Manifest Text Editor Elements - - - - - - -
-

Additional Manifest Text Editor Elements

- -

<app-control> Element

-

The <app-control> element represents Tizen application control configuration information.

- - - - - - - - -
-<app-control> element

Tizen application control configuration information.

-

For more information on the relationship between the elements, see the element hierarchy.

Occurrences:

-
    -
  • 1 or more (optional)
  • -
-

Expected children:

- - - - - - - - - - - - - - - - - -
Child elementOccurrences
<operation>1 or more (optional)
<uri>1 or more (optional)
<mime>1 or more (optional)
-
- - - - - - - -
-<operation> element

Operation type of the application control.

-

Attributes:

-
    -
  • http://tizen.org/appcontrol/operation/call
  • -
  • http://tizen.org/appcontrol/operation/compose
  • -
  • http://tizen.org/appcontrol/operation/create_content
  • -
  • http://tizen.org/appcontrol/operation/dial
  • -
  • http://tizen.org/appcontrol/operation/pick
  • -
  • http://tizen.org/appcontrol/operation/multi_share
  • -
  • http://tizen.org/appcontrol/operation/share
  • -
  • http://tizen.org/appcontrol/operation/view
  • -
-
- - - - - - - - -
-<uri> element

URI scheme of the application control.

-

Attributes:

-
    -
  • URI scheme string
  • -
-
- - - - - - - -
-<mime> element

MIME type of the application control.

-

Attributes:

-
    -
  • MIME type string
  • -
-
-

For example:

-
<app-control>
-   <operation name="http://tizen.org/appcontrol/operation/compose"/>
-   <uri name="testuristring"/>
-   <mime name="application/pdf"/>
-</app-control>
-
- -

<datacontrol> Element

-

The <datacontrol> element represents configuration information for the Tizen data controls.

- - - - - - - - -
-<datacontrol> element

Set of configuration information for the Tizen data controls.

-

For more information on the relationship between the elements, see the element hierarchy.

Occurrences:

-
    -
  • 1 or more (optional)
  • -
-

Attributes:

- -
- - - - - - - -
-providerid attribute

ID of the data control provider.

-

Expected value:

-
    -
  • String
  • -
-
- - - - - - - -
-access attribute

Access mode of the data control.

-

Expected value:

-
    -
  • String
  • -
-
- - - - - - - -
-type attribute

Type of the data control.

-

Expected value:

-
    -
  • String
  • -
-
-

For example:

-
<datacontrol access="WriteOnly" providerid="http://uiapp.com/datacontrol/provider/uiapp" type="Sql"/>
-
- -

<icon> Element

-

The <icon> element represents the icon relative or absolute file path for the Tizen application.

- - - - - - - - - - - -
-<icon> element

Represents the icon relative or absolute file path.

-

For more information on the relationship between the elements, see the element hierarchy.

Occurrences:

-
    -
  • 1 (optional)
  • -
-
-

Expected value:

-
    -
  • Icon path
  • -
-
-

For example:

-
-<icon>testicon.png</icon>
-
- - -

<label> Element

-

The <label> element represents the label value for the Tizen application.

- - - - - - - - - - - -
-<label> element

Set of human readable names for the Tizen application according to the language.

-

For more information on the relationship between the elements, see the element hierarchy.

Occurrences:

-
    -
  • 1 or more (optional)
  • -
-
-

Attributes:

- -

Expected value:

-
    -
  • Label value in string
  • -
-
- - - - - - - -
-xml:lang attribute

Language of the label.

-

Expected value:

-
    -
  • "<2-letter lowercase language code (ISO 639-1)>-<2-letter lowercase country code (ISO 3166-1 alpha-2)>"
  • -
-
-

For example:

-
-<label>testlabel</label>
-<label xml:lang="en-gb">testlabel</label>
-
- -

<metadata> Element

-

The <metadata> element represents user-defined key-value pairs for the application.

- - - - - - - - -
-<metadata> element

User-defined key-value pairs for the application.

-

For more information on the relationship between the elements, see the element hierarchy.

Occurrences:

-
    -
  • 1 or more (optional)
  • -
-

Attributes:

- -
- - - - - - - -
-key attribute

Key of metadata.

-

Expected value:

-
    -
  • String
  • -
-
- - - - - - - -
-value attribute

Value of metadata.

-

Expected value:

-
    -
  • String
  • -
-
-

For example:

-
<metadata key="testkey" value="testvalue"/>
-
- -

<background-category>

-

The <background-category> element represents category of the application running on the background.

-
- - - - - - -
-<background-category> element

Category of the application that allowed running on the background

-

For more information on the relationship between the elements, see the element hierarchy.

Occurrences:

-
    -
  • 1 or more (optional)
  • -
-

Attributes:

- -
-
- - - - - - -
-value attribute

Value of background category

-

Expected value:

-
    -
  • String
  • -
-
-

For example:

<background-category value="download"/>
-
- - - -
- -Go to top - - - - - - - - + + + + + + + + + + + + + + Additional Manifest Text Editor Elements + + + + + + +
+

Additional Manifest Text Editor Elements

+ +

<app-control> Element

+

The <app-control> element represents Tizen application control configuration information.

+ + + + + + + + +
+<app-control> element

Tizen application control configuration information.

+

For more information on the relationship between the elements, see the element hierarchy.

Occurrences:

+
    +
  • 1 or more (optional)
  • +
+

Expected children:

+ + + + + + + + + + + + + + + + + +
Child elementOccurrences
<operation>1 or more (optional)
<uri>1 or more (optional)
<mime>1 or more (optional)
+
+ + + + + + + +
+<operation> element

Operation type of the application control.

+

Attributes:

+
    +
  • http://tizen.org/appcontrol/operation/call
  • +
  • http://tizen.org/appcontrol/operation/compose
  • +
  • http://tizen.org/appcontrol/operation/create_content
  • +
  • http://tizen.org/appcontrol/operation/dial
  • +
  • http://tizen.org/appcontrol/operation/pick
  • +
  • http://tizen.org/appcontrol/operation/multi_share
  • +
  • http://tizen.org/appcontrol/operation/share
  • +
  • http://tizen.org/appcontrol/operation/view
  • +
+
+ + + + + + + + +
+<uri> element

URI scheme of the application control.

+

Attributes:

+
    +
  • URI scheme string
  • +
+
+ + + + + + + +
+<mime> element

MIME type of the application control.

+

Attributes:

+
    +
  • MIME type string
  • +
+
+

For example:

+
<app-control>
+   <operation name="http://tizen.org/appcontrol/operation/compose"/>
+   <uri name="testuristring"/>
+   <mime name="application/pdf"/>
+</app-control>
+
+ +

<datacontrol> Element

+

The <datacontrol> element represents configuration information for the Tizen data controls.

+ + + + + + + + +
+<datacontrol> element

Set of configuration information for the Tizen data controls.

+

For more information on the relationship between the elements, see the element hierarchy.

Occurrences:

+
    +
  • 1 or more (optional)
  • +
+

Attributes:

+ +
+ + + + + + + +
+providerid attribute

ID of the data control provider.

+

Expected value:

+
    +
  • String
  • +
+
+ + + + + + + +
+access attribute

Access mode of the data control.

+

Expected value:

+
    +
  • String
  • +
+
+ + + + + + + +
+type attribute

Type of the data control.

+

Expected value:

+
    +
  • String
  • +
+
+

For example:

+
<datacontrol access="WriteOnly" providerid="http://uiapp.com/datacontrol/provider/uiapp" type="Sql"/>
+
+ +

<icon> Element

+

The <icon> element represents the icon relative or absolute file path for the Tizen application.

+ + + + + + + + + + + +
+<icon> element

Represents the icon relative or absolute file path.

+

For more information on the relationship between the elements, see the element hierarchy.

Occurrences:

+
    +
  • 1 (optional)
  • +
+
+

Expected value:

+
    +
  • Icon path
  • +
+
+

For example:

+
+<icon>testicon.png</icon>
+
+ + +

<label> Element

+

The <label> element represents the label value for the Tizen application.

+ + + + + + + + + + + +
+<label> element

Set of human readable names for the Tizen application according to the language.

+

For more information on the relationship between the elements, see the element hierarchy.

Occurrences:

+
    +
  • 1 or more (optional)
  • +
+
+

Attributes:

+ +

Expected value:

+
    +
  • Label value in string
  • +
+
+ + + + + + + +
+xml:lang attribute

Language of the label.

+

Expected value:

+
    +
  • "<2-letter lowercase language code (ISO 639-1)>-<2-letter lowercase country code (ISO 3166-1 alpha-2)>"
  • +
+
+

For example:

+
+<label>testlabel</label>
+<label xml:lang="en-gb">testlabel</label>
+
+ +

<metadata> Element

+

The <metadata> element represents user-defined key-value pairs for the application.

+ + + + + + + + +
+<metadata> element

User-defined key-value pairs for the application.

+

For more information on the relationship between the elements, see the element hierarchy.

Occurrences:

+
    +
  • 1 or more (optional)
  • +
+

Attributes:

+ +
+ + + + + + + +
+key attribute

Key of metadata.

+

Expected value:

+
    +
  • String
  • +
+
+ + + + + + + +
+value attribute

Value of metadata.

+

Expected value:

+
    +
  • String
  • +
+
+

For example:

+
<metadata key="testkey" value="testvalue"/>
+
+ + + + +
+ +Go to top + + + + + + + + diff --git a/org.tizen.devtools/html/native_tools/manifest_text_editor_n.htm b/org.tizen.devtools/html/native_tools/manifest_text_editor_n.htm index 04965e6..a4174bc 100644 --- a/org.tizen.devtools/html/native_tools/manifest_text_editor_n.htm +++ b/org.tizen.devtools/html/native_tools/manifest_text_editor_n.htm @@ -175,12 +175,6 @@ - - - <background-category> - - - <ui-application> @@ -235,12 +229,6 @@ - - - <background-category> - - - <account> @@ -630,10 +618,6 @@ <datacontrol> 1 or more (optional) - -<background-category> - 1 or more (optional) -

Attributes:

-

The following guides apply in mobile applications only:

+

The following guides apply in mobile applications only:

  • Download

    Enables you to download files from the Internet and monitor the download progress and status.

diff --git a/org.tizen.guides/html/native/content/download_n.htm b/org.tizen.guides/html/native/content/download_n.htm index e771827..e85e247 100644 --- a/org.tizen.guides/html/native/content/download_n.htm +++ b/org.tizen.guides/html/native/content/download_n.htm @@ -1,148 +1,148 @@ - - - - - - - - - - - - - Download - - - - - -
- -

Download

-

You can create and manage one or more download requests. Tizen allows you to create a new download process, configure the download URL or destination, and launch the process.

- - - - - - - - - - -
Note
This feature is supported in mobile applications only.
- -

Download States

- -

The following figure illustrates the download states (such as READY and DOWNLOADING), and API functions (such as download_start()) which cause transitions between those states. Functions can be called only from specific states. Every possible scenario must be handled in the code to avoid undefined behavior in the application.

- - -

Figure: Download states

-

Download states

- -

The following table defines the download state enumerator values.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- Table: Download state enumerator values -
Enumerator valueDescription
DOWNLOAD_STATE_NONEDefault value.
DOWNLOAD_STATE_READYReady to download.
DOWNLOAD_STATE_QUEUEDQueued to start downloading.
DOWNLOAD_STATE_DOWNLOADINGDownload is currently running.
DOWNLOAD_STATE_PAUSEDDownload is waiting to resume.
DOWNLOAD_STATE_COMPLETEDDownload is complete.
DOWNLOAD_STATE_FAILEDDownload failed.
DOWNLOAD_STATE_CANCELEDDownload was cancelled by the user.
- -

The following figure illustrates the user scenario for the download.

- - -

Figure: User scenario

-

User scenario

- -

Stopping and Destroying a Download

- -

The download_cancel() function can be used to stop downloading a file. The function changes the download state to DOWNLOAD_STATE_CANCELED. From this state, the download_start() function can be called to restart the download.

- -

The download_destroy() function can be called to unload all data concerning a download_id handle from the memory. The download_id handle is stored for 48 hours (even if the device is powered off), unless the download_destroy() is called.

- - - - - -
- -Go to top - - - - - - + + + + + + + + + + + + + Download + + + + + +
+ +

Download

+

You can create and manage one or more download requests. Tizen allows you to create a new download process, configure the download URL or destination, and launch the process.

+ + + + + + + + + + +
Note
This feature is supported in mobile applications only.
+ +

Download States

+ +

The following figure illustrates the download states (such as READY and DOWNLOADING), and API functions (such as download_start()) which cause transitions between those states. Functions can be called only from specific states. Every possible scenario must be handled in the code to avoid undefined behavior in the application.

+ + +

Figure: Download states

+

Download states

+ +

The following table defines the download state enumerator values.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Table: Download state enumerator values +
Enumerator valueDescription
DOWNLOAD_STATE_NONEDefault value.
DOWNLOAD_STATE_READYReady to download.
DOWNLOAD_STATE_QUEUEDQueued to start downloading.
DOWNLOAD_STATE_DOWNLOADINGDownload is currently running.
DOWNLOAD_STATE_PAUSEDDownload is waiting to resume.
DOWNLOAD_STATE_COMPLETEDDownload is complete.
DOWNLOAD_STATE_FAILEDDownload failed.
DOWNLOAD_STATE_CANCELEDDownload was cancelled by the user.
+ +

The following figure illustrates the user scenario for the download.

+ + +

Figure: User scenario

+

User scenario

+ +

Stopping and Destroying a Download

+ +

The download_cancel() function can be used to stop downloading a file. The function changes the download state to DOWNLOAD_STATE_CANCELED. From this state, the download_start() function can be called to restart the download.

+ +

The download_destroy() function can be called to unload all data concerning a download_id handle from the memory. The download_id handle is stored for 48 hours (even if the device is powered off), unless the download_destroy() is called.

+ + + + + +
+ +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/native/content/media_content_n.htm b/org.tizen.guides/html/native/content/media_content_n.htm index 5798c59..f739372 100644 --- a/org.tizen.guides/html/native/content/media_content_n.htm +++ b/org.tizen.guides/html/native/content/media_content_n.htm @@ -1,432 +1,432 @@ - - - - - - - - - - - - - Media Content - - - - - -
- -

Media Content

- -

You can get information about media content from the metadata in the content, such as an ID3 or MP4 tag. You can obtain or update data from the media database, which stores metadata for the media files (such as images, videos, and audio) in the device.

- -

Figure: Media content of the device

-

Media content of the device

- -

The media files are updated using an application (by calling the Content API) or a media scanner. When updating the files in the media scanner, the following limitations apply:

-
  • SD card insertion and removal: Media files are updated only in the SD card.
  • -
  • Rebooting the device: Media files are updated in the internal memory and SD card in the device.
- -

Media content is available to only use the files located in the specific paths. You can get the paths by using the int storage_get_directory(int storage_id, storage_directory_e type, char **path); function. For more information, see the Storage API (in mobile and wearable applications).

- - -

The main features of the Content module include:

-
    -
  • Media content -

    To obtain information from the media database, make sure you are connected to it. When the connection is no longer needed, remember to disconnect from the media database.

    -

    You can update database details due to file (or directory) creation or deletion. If a received file (or directory) does not exist in the file system, it is removed from the database.

    -

    You can also set an alarm to get notifications of media database changes.

  • -
  • Media information -

    You can update the media database due to file creation, deletion, or update in the device.

  • -
  • Media bookmarks -

    You can manage a bookmark of the video and audio files.

  • -
  • Media playlists -

    You can add or delete a playlist of the video and audio files, and add media files to a created playlist.

  • -
  • Media tags -

    You can get tag information of the media files.

  • -
  • Media albums -

    You can manage an album of the audio file.

  • -
  • Mapping MIME types -

    You can map a file's MIME types to file extensions and vice versa.

  • -
- -

You can also manage downloads, for example, create a new download process, configure the download URL or destination, and launch the process.

- -

Getting Media Information

-

You can get the media data from the media database using the media_info_foreach_media_from_db() function.

-

After that, you can get the general information of media and specific information of each media type.

- -

The following tables list the information available about the media files.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- Table: General information -
Metadata nameDescription
Media IDID of the media content
File pathPath of the media content
Display nameDisplay name of the media content
Media typeThe media type of the media content
Mime typeMime type of the media content
SizeFile size of the media content
Added timeThe time the media content was added in the database
Modified timeThe last modification time of the media content
TimelineThe time the media content was created
You can use this value to sort the content.
Thumbnail pathPath of the stored thumbnail image of the media content
DescriptionDescription of the media content
LongitudeLongitude of the media content
LatitudeLatitude of the media content
AltitudeAltitude of the media content
WeatherWeather information of the media content
RatingRating of the media content
FavoriteFavorite of the media content
AuthorThe author of the media content
ProviderProvider of the media content
Content nameContent name of the media content
TitleTitle of the media content
CategoryCategory of the media content
Location tagLocation tag of the media content
Age ratingAge rating of the media content
KeywordKeyword of the media content
Is DRMCheck flag for DRM content
Storage typeStorage type of the media content
Played countPlayed count of the media content
Played timeLast played time of the media content
Played positionLast played position of the media content
- -

For metadata of an audio file, call the media_info_get_audio() function with the media handle.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- Table: Audio metadata (only for audio files) -
Metadata nameDescription
Media IDMedia ID of the audio content
This value is same as the media ID in general information
AlbumAlbum information of the audio content
ArtistArtist of the audio content
Album ArtistAlbum artist of the audio content
The artist and album artist can be the same.
GenreGenre of the audio content
ComposerComposer of the audio content
YearThe year the audio content was created
Recorded dateThe date the audio content was recorded
CopyrightCopyright information of the audio content
Track numberTrack number of the audio content
Bit rateBit rate of the audio content
Bit per sampleBit per sample of the audio content
The bit per sample is the same as the sample format.
The sample format is the number of digits in the digital representation of each sample.
Sample rateSample rate of the audio content
ChannelChannel information of the audio content
DurationDuration of the audio content
- -

For metadata of an image file, call the media_info_get_image() function with the media handle.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- Table: Image metadata (only for image files) -
Metadata nameDescription
Media IDMedia ID of the image
This value is the same as the media ID in the general information.
WidthWidth of the image
HeightHeight of the image
Exposure timeExposure time of the image
F-numberF-number of the image
ISOISO information of the image
ModelModel name of the image
OrientationOrientation information of the image
Date takenThe time the image was created
You can get this information from the EXIF tag.
If there is no EXIF tag for the image, set the created time in the file system.
Is burstshotCheck flag for a burst shot of the image
The burst shot is a continuous shooting mode.
Burstshot IDID of a burst shot image
Assign the same ID to the burst shooting mode.
-

For metadata of a video file, call withmedia_info_get_video() function with the media handle.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- Table: Video metadata (only for video files) -
Metadata nameDescription
Media IDThe media ID of the video content
This value is same with media ID of general information
AlbumAlbum of the video content
ArtistArtist of the video content
Album artistAlbum artist of the video content
GenreGenre of the video content
ComposerMedia composer of the video content
YearThe year the video content was created
Recorded dateThe date the video content was recorded
CopyrightCopyright of the video content
Track numberTrack number of the video content
Bit rateBit rate of the video content
DurationDuration of the video content
WidthWidth of the video content
HeightHeight of the video content
- - - -
- -Go to top - - - - - - + + + + + + + + + + + + + Media Content + + + + + +
+ +

Media Content

+ +

You can get information about media content from the metadata in the content, such as an ID3 or MP4 tag. You can obtain or update data from the media database, which stores metadata for the media files (such as images, videos, and audio) in the device.

+ +

Figure: Media content of the device

+

Media content of the device

+ +

The media files are updated using an application (by calling the Content API) or a media scanner. When updating the files in the media scanner, the following limitations apply:

+
  • SD card insertion and removal: Media files are updated only in the SD card.
  • +
  • Rebooting the device: Media files are updated in the internal memory and SD card in the device.
+ +

Media content is available to only use the files located in the specific paths. You can get the paths by using the int storage_get_directory(int storage_id, storage_directory_e type, char **path); function. For more information, see the Storage API (in mobile and wearable applications).

+ + +

The main features of the Content module include:

+
    +
  • Media content +

    To obtain information from the media database, make sure you are connected to it. When the connection is no longer needed, remember to disconnect from the media database.

    +

    You can update database details due to file (or directory) creation or deletion. If a received file (or directory) does not exist in the file system, it is removed from the database.

    +

    You can also set an alarm to get notifications of media database changes.

  • +
  • Media information +

    You can update the media database due to file creation, deletion, or update in the device.

  • +
  • Media bookmarks +

    You can manage a bookmark of the video and audio files.

  • +
  • Media playlists +

    You can add or delete a playlist of the video and audio files, and add media files to a created playlist.

  • +
  • Media tags +

    You can get tag information of the media files.

  • +
  • Media albums +

    You can manage an album of the audio file.

  • +
  • Mapping MIME types +

    You can map a file's MIME types to file extensions and vice versa.

  • +
+ +

You can also manage downloads, for example, create a new download process, configure the download URL or destination, and launch the process.

+ +

Getting Media Information

+

You can get the media data from the media database using the media_info_foreach_media_from_db() function.

+

After that, you can get the general information of media and specific information of each media type.

+ +

The following tables list the information available about the media files.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Table: General information +
Metadata nameDescription
Media IDID of the media content
File pathPath of the media content
Display nameDisplay name of the media content
Media typeThe media type of the media content
Mime typeMime type of the media content
SizeFile size of the media content
Added timeThe time the media content was added in the database
Modified timeThe last modification time of the media content
TimelineThe time the media content was created
You can use this value to sort the content.
Thumbnail pathPath of the stored thumbnail image of the media content
DescriptionDescription of the media content
LongitudeLongitude of the media content
LatitudeLatitude of the media content
AltitudeAltitude of the media content
WeatherWeather information of the media content
RatingRating of the media content
FavoriteFavorite of the media content
AuthorThe author of the media content
ProviderProvider of the media content
Content nameContent name of the media content
TitleTitle of the media content
CategoryCategory of the media content
Location tagLocation tag of the media content
Age ratingAge rating of the media content
KeywordKeyword of the media content
Is DRMCheck flag for DRM content
Storage typeStorage type of the media content
Played countPlayed count of the media content
Played timeLast played time of the media content
Played positionLast played position of the media content
+ +

For metadata of an audio file, call the media_info_get_audio() function with the media handle.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Table: Audio metadata (only for audio files) +
Metadata nameDescription
Media IDMedia ID of the audio content
This value is same as the media ID in general information
AlbumAlbum information of the audio content
ArtistArtist of the audio content
Album ArtistAlbum artist of the audio content
The artist and album artist can be the same.
GenreGenre of the audio content
ComposerComposer of the audio content
YearThe year the audio content was created
Recorded dateThe date the audio content was recorded
CopyrightCopyright information of the audio content
Track numberTrack number of the audio content
Bit rateBit rate of the audio content
Bit per sampleBit per sample of the audio content
The bit per sample is the same as the sample format.
The sample format is the number of digits in the digital representation of each sample.
Sample rateSample rate of the audio content
ChannelChannel information of the audio content
DurationDuration of the audio content
+ +

For metadata of an image file, call the media_info_get_image() function with the media handle.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Table: Image metadata (only for image files) +
Metadata nameDescription
Media IDMedia ID of the image
This value is the same as the media ID in the general information.
WidthWidth of the image
HeightHeight of the image
Exposure timeExposure time of the image
F-numberF-number of the image
ISOISO information of the image
ModelModel name of the image
OrientationOrientation information of the image
Date takenThe time the image was created
You can get this information from the EXIF tag.
If there is no EXIF tag for the image, set the created time in the file system.
Is burstshotCheck flag for a burst shot of the image
The burst shot is a continuous shooting mode.
Burstshot IDID of a burst shot image
Assign the same ID to the burst shooting mode.
+

For metadata of a video file, call withmedia_info_get_video() function with the media handle.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Table: Video metadata (only for video files) +
Metadata nameDescription
Media IDThe media ID of the video content
This value is same with media ID of general information
AlbumAlbum of the video content
ArtistArtist of the video content
Album artistAlbum artist of the video content
GenreGenre of the video content
ComposerMedia composer of the video content
YearThe year the video content was created
Recorded dateThe date the video content was recorded
CopyrightCopyright of the video content
Track numberTrack number of the video content
Bit rateBit rate of the video content
DurationDuration of the video content
WidthWidth of the video content
HeightHeight of the video content
+ + + +
+ +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/native/content/mime_type_n.htm b/org.tizen.guides/html/native/content/mime_type_n.htm index e1b909c..5c37a57 100644 --- a/org.tizen.guides/html/native/content/mime_type_n.htm +++ b/org.tizen.guides/html/native/content/mime_type_n.htm @@ -1,67 +1,69 @@ - - - - - - - - - - - - - MIME Type - - - - - -
- -

MIME Type

- -

The main features of the MIME Type API include:

- -
  • Getting the MIME type -

    To get a MIME type for a file extension, use the mime_type_get_mime_type() function. The MIME type is 'application/octet-stream', if the given file extension is not associated with any specific file format.

  • - -
  • Getting associated extensions -

    To get a list of extensions associated, for example, with an image or a JPEG MIME type, use the mime_type_get_file_extension() function.

- - - - -
- -Go to top - - - - - - - + + + + + + + + + + + + + MIME Type + + + + + +
+ +

MIME Type

+ +

You can retrieve various information related to the MIME type.

+ +

The main features of the MIME Type API include:

+ +
  • Getting the MIME type +

    To get a MIME type for a file extension, use the mime_type_get_mime_type() function. The MIME type is 'application/octet-stream', if the given file extension is not associated with any specific file format.

  • + +
  • Getting associated extensions +

    To get a list of extensions associated, for example, with an image or a JPEG MIME type, use the mime_type_get_file_extension() function.

+ + + + +
+ +Go to top + + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/native/context/activity_recognition_n.htm b/org.tizen.guides/html/native/context/activity_recognition_n.htm index bbcd18f..0c24403 100644 --- a/org.tizen.guides/html/native/context/activity_recognition_n.htm +++ b/org.tizen.guides/html/native/context/activity_recognition_n.htm @@ -1,72 +1,72 @@ - - - - - - - - - - - - - Activity Recognition - - - - - -
- - -

Activity Recognition

- - -

The activity recognizer can detect walking and running activity. It also recognizes the stationary state and activities on a moving vehicle.

- - - - - - - - - - -
Note
You can test the activity recognition functionality only on a target device. The Emulator does not support this feature.
- - - -
- -Go to top - - - - - + + + + + + + + + + + + + Activity Recognition + + + + + +
+ + +

Activity Recognition

+ + +

The activity recognizer can detect walking and running activity. It also recognizes the stationary state and activities on a moving vehicle.

+ + + + + + + + + + +
Note
You can test the activity recognition functionality only on a target device. The Emulator does not support this feature.
+ + + +
+ +Go to top + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/native/context/context_guide_n.htm b/org.tizen.guides/html/native/context/context_guide_n.htm index fdbac12..e51fe3f 100644 --- a/org.tizen.guides/html/native/context/context_guide_n.htm +++ b/org.tizen.guides/html/native/context/context_guide_n.htm @@ -1,79 +1,79 @@ - - - - - - - - - - - - - Context - - - - - -
- - -

Context

- -

Context features include recognizing activities and gestures, triggering tasks by contextual events and conditions, and getting usage profiles on the device.

- -

The main context features are:

- - -

The following guides apply in mobile applications only:

-
    -
  • Contextual Trigger -

    Enables you to compose rules to trigger a task based on contextual events and conditions.

  • -
  • Contextual History -

    Enables you to get usage profiles, such as information about frequently used applications.

  • -
- - - - - - -
- -Go to top - - - - - + + + + + + + + + + + + + Context + + + + + +
+ + +

Context

+ +

Context features include recognizing activities and gestures, triggering tasks by contextual events and conditions, and getting usage profiles on the device.

+ +

The main context features are:

+ + +

The following guides apply in mobile applications only:

+
    +
  • Contextual Trigger +

    Enables you to compose rules to trigger a task based on contextual events and conditions.

  • +
  • Contextual History +

    Enables you to get usage profiles, such as information about frequently used applications.

  • +
+ + + + + + +
+ +Go to top + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/native/context/gesture_recognition_n.htm b/org.tizen.guides/html/native/context/gesture_recognition_n.htm index d5c547a..1b38559 100644 --- a/org.tizen.guides/html/native/context/gesture_recognition_n.htm +++ b/org.tizen.guides/html/native/context/gesture_recognition_n.htm @@ -1,123 +1,123 @@ - - - - - - - - - - - - - Gesture Recognition - - - - - -
- - -

Gesture Recognition

- -

With gesture recognition, you can receive notifications about different device movement patterns, identify device states, and trigger events when the sensor data meets predefined conditions. In some cases, you can also listen to different states (started, in-progress, and ended).

- - - - - - - - - - -
Note
You can test the gesture recognition functionality only on a target device. The Emulator does not support this feature.
- -

The following gesture events are supported in Tizen devices:

- -
    -
  • Double-tap -

    The device is tapped twice.

    -
  • -
  • Move to ear -

    The device is moved near to an ear. The event is detected using the acceleration and proximity sensors.

    -

    Figure: Move-to-ear event

    -

    Move-to-ear event

  • -
  • No move -

    The device is not moved for a while.

  • -
  • Pick-up -

    The device is picked up.

  • -
  • Shake -

    The device is quickly moved back and forth.

    -

    Figure: Shake event

    -

    Shake event

  • -
  • Snap -

    The device is moved along a particular axis.

    -

    Figure: Axes of the device

    -

    Axes of the device

    -

    The movement is measured with 6 discrete events: +X, -X, +Y, -Y, +Z, and -Z:

    -
    • With the display in the portrait mode, the +X, -X, +Z, and -Z snaps are active.
    • -
    • With the display in the landscape mode, the +Y, -Y, +Z, and -Z snaps are active.
    -

    Figure: Snap events +X, +Y, and +Z

    -

    Snap events +X, +Y, and +Z

    - - - - - - - - - -
    Note
    The snap motion does not operate correctly if the device is tilted improperly. For example, the device must be held straight in a portrait mode for best accuracy. Similarly, when the device is tilted 90 degrees along the Z axis from the above position (+X or -X points to the earth), the snap motion in a landscape mode works best. This means that when a user lies down holding the device, the snap motion may not work accurately.
    -
  • -
  • Tilt -

    The device is tilted. The event provides changes of the slopes on the X and Y axes, not the current angle of each axis.

    -

    Figure: Tilt event

    -

    Tilt event

  • -
  • Turn face down -

    The device is turned over and the screen is facing downwards.

    -

    Figure: Face-down event

    -

    Face-down event

  • -
  • Wrist up -

    The event occurs when wrist-up gesture is performed (in case of a watch device).

    -

    Figure: Wrist-up event

    -

    Wrist-up event

  • -
- - - -
- -Go to top - - - - - + + + + + + + + + + + + + Gesture Recognition + + + + + +
+ + +

Gesture Recognition

+ +

With gesture recognition, you can receive notifications about different device movement patterns, identify device states, and trigger events when the sensor data meets predefined conditions. In some cases, you can also listen to different states (started, in-progress, and ended).

+ + + + + + + + + + +
Note
You can test the gesture recognition functionality only on a target device. The Emulator does not support this feature.
+ +

The following gesture events are supported in Tizen devices:

+ +
    +
  • Double-tap +

    The device is tapped twice.

    +
  • +
  • Move to ear +

    The device is moved near to an ear. The event is detected using the acceleration and proximity sensors.

    +

    Figure: Move-to-ear event

    +

    Move-to-ear event

  • +
  • No move +

    The device is not moved for a while.

  • +
  • Pick-up +

    The device is picked up.

  • +
  • Shake +

    The device is quickly moved back and forth.

    +

    Figure: Shake event

    +

    Shake event

  • +
  • Snap +

    The device is moved along a particular axis.

    +

    Figure: Axes of the device

    +

    Axes of the device

    +

    The movement is measured with 6 discrete events: +X, -X, +Y, -Y, +Z, and -Z:

    +
    • With the display in the portrait mode, the +X, -X, +Z, and -Z snaps are active.
    • +
    • With the display in the landscape mode, the +Y, -Y, +Z, and -Z snaps are active.
    +

    Figure: Snap events +X, +Y, and +Z

    +

    Snap events +X, +Y, and +Z

    + + + + + + + + + +
    Note
    The snap motion does not operate correctly if the device is tilted improperly. For example, the device must be held straight in a portrait mode for best accuracy. Similarly, when the device is tilted 90 degrees along the Z axis from the above position (+X or -X points to the earth), the snap motion in a landscape mode works best. This means that when a user lies down holding the device, the snap motion may not work accurately.
    +
  • +
  • Tilt +

    The device is tilted. The event provides changes of the slopes on the X and Y axes, not the current angle of each axis.

    +

    Figure: Tilt event

    +

    Tilt event

  • +
  • Turn face down +

    The device is turned over and the screen is facing downwards.

    +

    Figure: Face-down event

    +

    Face-down event

  • +
  • Wrist up +

    The event occurs when wrist-up gesture is performed (in case of a watch device).

    +

    Figure: Wrist-up event

    +

    Wrist-up event

  • +
+ + + +
+ +Go to top + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/native/context/history_n.htm b/org.tizen.guides/html/native/context/history_n.htm index 90a1596..abb4866 100644 --- a/org.tizen.guides/html/native/context/history_n.htm +++ b/org.tizen.guides/html/native/context/history_n.htm @@ -50,7 +50,7 @@ -

The Contextual History API provides history data about application usage, media playback, communications, and device settings. When an application reads each type of history data, the application can set filters to specify the necessary statistics. The following example shows how to get information about the 5 most frequently used applications from the last 30 days.

+

The Contextual History API provides history data about application usage, media playback, communications, and device settings. When an application reads each type of history data, the application must set filters (mandatory and optional) to specify the necessary statistics. The following example shows how to get information about the 5 most frequently used applications from the last 30 days.

 // Setting filter key and values
 context_history_filter_set_int(filter, CONTEXT_HISTORY_FILTER_RESULT_SIZE, 5);
@@ -65,7 +65,7 @@ Once the context_hist
 
 

History Data Types

-

Through contextual history, you can mainly retrieve statistics for 3 categories of usages logs, including application usage, media playback, and communications. The following table summarizes the available history data types and required privileges.

+

Through contextual history, you can mainly retrieve statistics for 3 types of usages logs, including application usage, media playback, and communications. The following table summarizes the available history data types and required privileges.

@@ -154,7 +154,7 @@ Once the context_hist - @@ -174,12 +174,6 @@ Once the context_hist - - - + + + + + + diff --git a/org.tizen.guides/html/native/graphics/cairo_n.htm b/org.tizen.guides/html/native/graphics/cairo_n.htm index 525d272..a49f437 100644 --- a/org.tizen.guides/html/native/graphics/cairo_n.htm +++ b/org.tizen.guides/html/native/graphics/cairo_n.htm @@ -1,179 +1,179 @@ - - - - - - - - - - - - - Cairo - - - - - -
- -

Cairo

- -

Cairo is an open source library for 2D vector graphics with support for multiple output devices. In Tizen, Cairo can support output to 2 different backends, such as the image and evas-gl (similar to gl) backend. This guide explains how you can link the Cairo image backend with Evas (in mobile and wearable applications), so that Cairo can draw on the image surface and an Evas object can get the image data from the Cairo image buffer.

- - -

Creating an Evas_Object Image

- -

Cairo and Evas have completely different concepts:

-
  • Evas knows the state of each object on the screen and manipulates the state. So when you create, for example, a rectangle with the evas_object_rectangle_add() function, it is not rendered on the screen when the function is called. In the rendering stage, the rectangle can be overlaid by an opaque image and never be rendered on the canvas.
  • -
  • Cairo draws as a person on a paper sheet. Once something is drawn on the Cairo surface, it is rendered on the screen.
- -

First, as shown in the following code snippet, you can define the appdata structure, which contains all the pointers to the objects to be manipulated:

- -
-typedef struct appdata 
-{
-   Evas_Object *win;
-   Evas_Object *img;
-   cairo_surface_t *surface;
-   cairo_t *cairo;
-   unsigned char *pixels;
-} appdata_s;
-
- -

To create a new Evas_Object image, use the evas_object_image_add() function. The image object can be used for displaying as pixels on the screen:

- -
-appdata_s * ad;
-ad->win = elm_win_util_standard_add(PACKAGE, PACKAGE);
-evas_object_show(ad->win);
-ad->img = evas_object_image_add(evas_object_evas_get(ad->win));
-evas_object_show(ad->img);
-
- - - -

You can now create a Cairo image surface for the provided pixel and other data by using the cairo_image_surface_create_for_data() function. The pixel data is a pointer to a buffer supplied by the application in which you want to write content.

-

The size of the row stride is called by the cairo_format_stride_for_width() function. The function provides a stride value that respects all alignment requirements of the accelerated image-rendering code within Cairo.

- -
-int row_stride = cairo_format_stride_for_width(CAIRO_FORMAT_ARGB32, WIDTH);
-ad->pixels = (unsigned char *) calloc(sizeof(unsigned char) * row_stride * HEIGHT, 1);
-ad->surface = cairo_image_surface_create_for_data(ad->pixels,CAIRO_FORMAT_ARGB32, WIDTH, HEIGHT, row_stride);
-
- -

To create the Cairo context used for all operations, use the following code.

-
-cairo = cairo_create(ad->surface);
-
- -

Associate the pixels (as raw data) to given image object. The pixels must be of the same size and colorspace as the image object.

-
-evas_object_image_data_set(ad->img, ad->pixels);
-
- -

Once you finish painting by using Cairo, Evas renders a particular rectangular region to be redrawn on the screen:

-
-evas_object_image_data_update_add(ad->img, 0, 0, WIDTH, HEIGHT);
-
- -

Drawing with Cairo

- -

Before drawing a line, set the current line width or color as a style. For example, you can set the line width as 2 and the line color as opaque red:

-
-cairo_set_line_width(ad->cairo, 2);
-cairo_set_source_rgba(ad->cairo, 1.0, 0.0, 0.0, 1.0);
- -

You can draw various lines:

-
    -
  • To set the start position with a user-specific offset, use the cairo_translate() function. It modifies the current transformation matrix (CTM) by translating the user-space origin by (x, y).

    -
    -cairo_translate(ad->cairo, 40, 40);
  • - -
  • Cairo uses a connect-the-dots style system when creating a path. To draw a line between 2 points (100,100 and 200,150) on the surface, use the cairo_move_to() and cairo_line_to() functions:

    -
    -cairo_move_to(ad->cairo, 100, 100);
    -cairo_line_to(ad->cairo, 200, 150);
  • - -
  • To draw a line from the endpoint of the current path, use the cairo_rel_line_to() function. The offset by (dx, dy) must be specified as (100, -50).

    -
    -cairo_rel_line_to(ad->cairo, 100, -50);
  • - -
  • To draw a circular arc of the given radius (100 * sqrt(2)) to the current path, use the cairo_arc() function.

    -

    The arc is centered at (200, 200), begins at angle1 (-0.25 * M_PI) and proceeds in the direction of increasing angles to end at angle2 (0.25 * M_PI). If angle2 is less than angle1, it is progressively increased by 2*M_PI until it is greater than angle1.

    -
    -cairo_arc(ad->cairo, 200, 200, 100 * sqrt(2), -0.25 * M_PI, 0.25 * M_PI);
  • - -
  • To draw a cubic Bézier spline to the path from the end position of the previous path, use the cairo_rel_curve_to() function. You can use the points offset by (-100, -50) and (-100, 50) as the control points. After the call, the current point is offset by (-200, 0).

    -
    -cairo_rel_curve_to(ad->cairo, -100, -50, -100, 50, -200, 0);
  • - -
  • You can add a line segment to the path from the current point to the beginning of the current sub-path. After this call, the current point is at the joined endpoint of the sub-path. The cairo_close_path() function differs from simply calling the cairo_line_to() function with the equivalent coordinate in the case of stroking: there is a line join connecting the final and initial segments of the sub-path.

    -
    -cairo_close_path(ad->cairo);
  • - -
  • To create a rectangle, use the cairo_rectangle() function. This call draws a rectangle with 400 px in width and height from point (0, 0).

    -
    -cairo_rectangle(ad->cairo, 0, 0, 400, 400);
  • - -
  • To stroke the paths, use the cairo_stroke() function. It is a drawing operator that strokes the current path according to the current line width, line join, line cap, and dash settings. After the function call, the current path is cleared from the cairo context.

    -
    -cairo_stroke(ad->cairo);
  • - -
  • To ensure that any pending Cairo operation are drawn, use the cairo_surface_flush() function after finishing the Cairo drawing:

    - -
    -cairo_surface_flush(ad->surface);
- -

You need to destroy Cairo objects before terminating your application:

-
-cairo_destroy(ad->cairo);
-cairo_surface_destroy(ad->surface);
- -

Figure: Drawing paths and a rectangle with Cairo

-

Drawing paths and a rectangle with Cairo

- - - - -
- -Go to top - - - - - - + + + + + + + + + + + + + Cairo + + + + + +
+ +

Cairo

+ +

Cairo is an open source library for 2D vector graphics with support for multiple output devices. In Tizen, Cairo can support output to 2 different backends, such as the image and evas-gl (similar to gl) backend. This guide explains how you can link the Cairo image backend with Evas (in mobile and wearable applications), so that Cairo can draw on the image surface and an Evas object can get the image data from the Cairo image buffer.

+ + +

Creating an Evas_Object Image

+ +

Cairo and Evas have completely different concepts:

+
  • Evas knows the state of each object on the screen and manipulates the state. So when you create, for example, a rectangle with the evas_object_rectangle_add() function, it is not rendered on the screen when the function is called. In the rendering stage, the rectangle can be overlaid by an opaque image and never be rendered on the canvas.
  • +
  • Cairo draws as a person on a paper sheet. Once something is drawn on the Cairo surface, it is rendered on the screen.
+ +

First, as shown in the following code snippet, you can define the appdata structure, which contains all the pointers to the objects to be manipulated:

+ +
+typedef struct appdata 
+{
+   Evas_Object *win;
+   Evas_Object *img;
+   cairo_surface_t *surface;
+   cairo_t *cairo;
+   unsigned char *pixels;
+} appdata_s;
+
+ +

To create a new Evas_Object image, use the evas_object_image_add() function. The image object can be used for displaying as pixels on the screen:

+ +
+appdata_s * ad;
+ad->win = elm_win_util_standard_add(PACKAGE, PACKAGE);
+evas_object_show(ad->win);
+ad->img = evas_object_image_add(evas_object_evas_get(ad->win));
+evas_object_show(ad->img);
+
+ + + +

You can now create a Cairo image surface for the provided pixel and other data by using the cairo_image_surface_create_for_data() function. The pixel data is a pointer to a buffer supplied by the application in which you want to write content.

+

The size of the row stride is called by the cairo_format_stride_for_width() function. The function provides a stride value that respects all alignment requirements of the accelerated image-rendering code within Cairo.

+ +
+int row_stride = cairo_format_stride_for_width(CAIRO_FORMAT_ARGB32, WIDTH);
+ad->pixels = (unsigned char *) calloc(sizeof(unsigned char) * row_stride * HEIGHT, 1);
+ad->surface = cairo_image_surface_create_for_data(ad->pixels,CAIRO_FORMAT_ARGB32, WIDTH, HEIGHT, row_stride);
+
+ +

To create the Cairo context used for all operations, use the following code.

+
+cairo = cairo_create(ad->surface);
+
+ +

Associate the pixels (as raw data) to given image object. The pixels must be of the same size and colorspace as the image object.

+
+evas_object_image_data_set(ad->img, ad->pixels);
+
+ +

Once you finish painting by using Cairo, Evas renders a particular rectangular region to be redrawn on the screen:

+
+evas_object_image_data_update_add(ad->img, 0, 0, WIDTH, HEIGHT);
+
+ +

Drawing with Cairo

+ +

Before drawing a line, set the current line width or color as a style. For example, you can set the line width as 2 and the line color as opaque red:

+
+cairo_set_line_width(ad->cairo, 2);
+cairo_set_source_rgba(ad->cairo, 1.0, 0.0, 0.0, 1.0);
+ +

You can draw various lines:

+
    +
  • To set the start position with a user-specific offset, use the cairo_translate() function. It modifies the current transformation matrix (CTM) by translating the user-space origin by (x, y).

    +
    +cairo_translate(ad->cairo, 40, 40);
  • + +
  • Cairo uses a connect-the-dots style system when creating a path. To draw a line between 2 points (100,100 and 200,150) on the surface, use the cairo_move_to() and cairo_line_to() functions:

    +
    +cairo_move_to(ad->cairo, 100, 100);
    +cairo_line_to(ad->cairo, 200, 150);
  • + +
  • To draw a line from the endpoint of the current path, use the cairo_rel_line_to() function. The offset by (dx, dy) must be specified as (100, -50).

    +
    +cairo_rel_line_to(ad->cairo, 100, -50);
  • + +
  • To draw a circular arc of the given radius (100 * sqrt(2)) to the current path, use the cairo_arc() function.

    +

    The arc is centered at (200, 200), begins at angle1 (-0.25 * M_PI) and proceeds in the direction of increasing angles to end at angle2 (0.25 * M_PI). If angle2 is less than angle1, it is progressively increased by 2*M_PI until it is greater than angle1.

    +
    +cairo_arc(ad->cairo, 200, 200, 100 * sqrt(2), -0.25 * M_PI, 0.25 * M_PI);
  • + +
  • To draw a cubic Bézier spline to the path from the end position of the previous path, use the cairo_rel_curve_to() function. You can use the points offset by (-100, -50) and (-100, 50) as the control points. After the call, the current point is offset by (-200, 0).

    +
    +cairo_rel_curve_to(ad->cairo, -100, -50, -100, 50, -200, 0);
  • + +
  • You can add a line segment to the path from the current point to the beginning of the current sub-path. After this call, the current point is at the joined endpoint of the sub-path. The cairo_close_path() function differs from simply calling the cairo_line_to() function with the equivalent coordinate in the case of stroking: there is a line join connecting the final and initial segments of the sub-path.

    +
    +cairo_close_path(ad->cairo);
  • + +
  • To create a rectangle, use the cairo_rectangle() function. This call draws a rectangle with 400 px in width and height from point (0, 0).

    +
    +cairo_rectangle(ad->cairo, 0, 0, 400, 400);
  • + +
  • To stroke the paths, use the cairo_stroke() function. It is a drawing operator that strokes the current path according to the current line width, line join, line cap, and dash settings. After the function call, the current path is cleared from the cairo context.

    +
    +cairo_stroke(ad->cairo);
  • + +
  • To ensure that any pending Cairo operation are drawn, use the cairo_surface_flush() function after finishing the Cairo drawing:

    + +
    +cairo_surface_flush(ad->surface);
+ +

You need to destroy Cairo objects before terminating your application:

+
+cairo_destroy(ad->cairo);
+cairo_surface_destroy(ad->surface);
+ +

Figure: Drawing paths and a rectangle with Cairo

+

Drawing paths and a rectangle with Cairo

+ + + + +
+ +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/native/graphics/graphics_guide_n.htm b/org.tizen.guides/html/native/graphics/graphics_guide_n.htm index 0dcb928..d84feb9 100644 --- a/org.tizen.guides/html/native/graphics/graphics_guide_n.htm +++ b/org.tizen.guides/html/native/graphics/graphics_guide_n.htm @@ -1,67 +1,67 @@ - - - - - - - - - - - - - Graphics - - - - - -
- -

Graphics

-

Graphics features include using OpenGL ES in various ways, and handling vector graphics and graphic buffers.

-

The main graphics features are:

-
    -
  • OpenGL ES

    Enables you to create OpenGL ES applications in Tizen with the EGL layer.

  • -
  • TBM Surface

    Provides Tizen Buffer Manager (TBM) surface functions for the graphic buffer in Tizen.

  • -
  • Cairo

    Allows you to use Cairo to draw on the image surface and Evas objects to get the image data.

  • - -
- - - - -
- -Go to top - - - - - - + + + + + + + + + + + + + Graphics + + + + + +
+ +

Graphics

+

Graphics features include using OpenGL ES in various ways, and handling vector graphics and graphic buffers.

+

The main graphics features are:

+
    +
  • OpenGL ES

    Enables you to create OpenGL ES applications in Tizen with the EGL layer.

  • +
  • TBM Surface

    Provides Tizen Buffer Manager (TBM) surface functions for the graphic buffer in Tizen.

  • +
  • Cairo

    Allows you to use Cairo to draw on the image surface and Evas objects to get the image data.

  • + +
+ + + + +
+ +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/native/graphics/opengles_n.htm b/org.tizen.guides/html/native/graphics/opengles_n.htm index 466ce70..60060f7 100644 --- a/org.tizen.guides/html/native/graphics/opengles_n.htm +++ b/org.tizen.guides/html/native/graphics/opengles_n.htm @@ -1,450 +1,450 @@ - - - - - - - - - - - - - OpenGL ES - - - - - -
- -

OpenGL ES

- -

The OpenGL ES overview shows the interaction among Graphics subsystems, OpenGL ES, and EGL defined by the Khronos Group.

- -

OpenGL ES is a standard specification defining a cross-language, cross-platform OpenGL ES API (in mobile and wearable applications) for writing applications that produce 2D and 3D computer graphics. OpenGL ES 1.1 and 2.0 are supported in Tizen 2.3. (OpenGL ES 3.0 will be supported in the next Tizen version.)

- -

EGL is an adhesive layer between OpenGL ES and the underlying native platform window system. EGL communicates with the Window system to get information on the application window, creates the drawing surface, and manages rendering context and resources.

- -

Figure: OpenGL ES structure

-

OpenGL® ES structure

- -

OpenGL ES in Tizen

- -

Building an OpenGL ES application in Tizen requires knowledge about designing UI applications with EFL.

- -

Tizen native applications do not depend on the Window system, because the Window system is an internal Tizen module, which can be enhanced or replaced. EFL provides a method that draws the OpenGL ES content and encapsulates the EGL and the native Window system.

- -

Figure: OpenGL ES and EFL

-

OpenGL® ES and EFL

- -

A GLView creates a drawable GL surface for the application, and sets up all the required callbacks. The application can use GLView with various UI components, such as toolbar or button.

- -

GLView internally uses EvasGL. It is an abstraction layer on top of EGL, which provides the necessary features for most applications in a platform-independent way. Since the goal of EvasGL is to abstract the underlying platform, only a subset of the features can be used by applications.

- -

Using GLView is recommended for usual OpenGL ES programs, such as 3D game applications. But if you need pbuffer surface or extension functions, you have to understand EvasGL.

- -

EvasGL vs. GLView

- -

While it is possible to create an OpenGL application by just using EvasGL, it could be difficult to comprehend due to the low-level nature of these APIs. However, it enables detailed operations.

- -

GLView Programming Guide

- -

Setting up an OpenGL ES Surface

- -

The easiest way to use OpenGL ES within a Tizen application is to rely on the GLView component.

- -

GLView is a simple Elementary UI component that sets up an OpenGL ES target surface and a context, and allows you to embed it in any Tizen application. GLView is basically a wrapper around EvasGL, the OpenGL-ES/EGL abstraction layer of EFL.

- -

To create a basic application:

- -

To develop a GL application, you have to call elm_config_accel_preference_set before creating a window. It makes an application to use GPU. To use the Direct Rendering mode, you have to set the same option values (depth, stencil, and MSAA) to a rendering engine and a GLView object. You can set the option values to a rendering engine using the elm_config_accel_preference_set() function and to a GLView object using the elm_glview_mode_set() function. If the GLView object option values are bigger or higher than the rendering engine's, the Direct Rendering mode is disabled.

- -

First, you should declare the global variable using ELEMENTARY_GLVIEW_GLOBAL_DEFINE(), then create a GLView object and use ELEMENTARY_GLVIEW_GLOBAL_USE(glview). Now, you can call GL functions.

- -
-#include <app.h>
-#include <Elementary_GL_Helpers.h>
-
-ELEMENTARY_GLVIEW_GLOBAL_DEFINE()
-
-typedef struct appdata 
-{
-   Evas_Object *win;
-   Evas_Object *glview;
-   unsigned int program;
-   unsigned int vtx_shader;
-   unsigned int fgmt_shader;
-   unsigned int vbo;
-} appdata_s;
-
-static Evas_Object *glview_create(Evas_Object *win);
-static void glview_start(Evas_Object *glview);
-
-// GLView callback functions
-static void draw_gl(Evas_Object *obj);
-static void init_gl(Evas_Object *obj);
-static void resize_gl(Evas_Object *obj);
-static void del_gl(Evas_Object *obj);
-
-static bool app_create(void *data) 
-{
-   appdata_s *ad = data;
-   elm_config_accel_preference_set("gl");
-   ad->win = elm_win_util_standard_add("GLView example", "GLView example");
-   evas_object_show(ad->win);
-   ad->glview = ad->glview_create(ad->win);
-   ELEMENTARY_GLVIEW_GLOBAL_USE(ad->glview);
-   glview_start(ad->glview);
-
-   return true;
-}
- -

Add the OpenGL ES view to the application:

- -
-// This is the GL initialization function
-static Evas_Object *glview_create(Evas_Object *win)
-{
-   Evas_Object *glview;
-
-   // This creates the UI component itself
-   glview = elm_glview_add(win);
-   elm_win_resize_object_add(win, glview);
-
-   // Request a surface with Depth and Stencil support (default buffer sizes)
-   elm_glview_mode_set(glview, ELM_GLVIEW_DEPTH | ELM_GLVIEW_STENCIL);
-
-   // Set the basic policies to handle the view transparently
-   elm_glview_resize_policy_set(glview, ELM_GLVIEW_RESIZE_POLICY_RECREATE);
-   elm_glview_render_policy_set(glview, ELM_GLVIEW_RENDER_POLICY_ON_DEMAND);
-
-   // Set the 4 main callbacks
-   elm_glview_init_func_set(glview, init_gl);
-   elm_glview_del_func_set(glview, del_gl);
-   elm_glview_render_func_set(glview, draw_gl);
-   elm_glview_resize_func_set(glview, resize_gl);
-
-   // Finally show this view
-   evas_object_size_hint_min_set(glview, 250, 250);
-   evas_object_show(glview);
-
-   return glview;
-}
- -

Setting up the Callbacks

- -

To set up callbacks:

- -
    -
  1. Callback for initialization -

    The initialization callback will be called when the GLView is created, after a valid openGL ES context and surface are created. Initialization, resizing, drawing, and deleting callback are called in the main loop.

    - -
    -// GL Init function
    -static void init_gl(Evas_Object *glview)
    -{
    -   glClearColor(0, 0, 0, 0);
    -   glClear(GL_COLOR_BUFFER_BIT);
    -
    -   // Do any form of OpenGL ES initialization here
    -   // init_shaders();
    -   // init_vertices();
    -}
    -
  2. -
  3. Callback for resizing -

    The resize callback is called whenever the GLView component is resized. A common action to take here is to reset the viewport.

    - -
    -// GLView resize function
    -static void resize_gl(Evas_Object *glview)
    -{
    -   int w, h;
    -   elm_glview_size_get(glview, &w, &h);
    -   glViewport(0, 0, w, h);
    -}
    -
  4. -
  5. Callback for drawing -

    The drawing callback is called whenever a new frame has to be drawn. The exact moment when this function is called depends on the policy.

    - -
    -elm_glview_render_policy_set(glview, ELM_GLVIEW_RENDER_POLICY_ON_DEMAND);
    - -

    Another policy is ELM_GLVIEW_POLICY_ALWAYS, which requests render always even when it is not visible. So on demand policy is probably what you are looking for. The application can now draw anything using GL primitives when this callback is triggered. All draw operations are restricted to the surface of the GLView object previously created.

    - -
    -// GL draw callback
    -static void draw_gl(Evas_Object *glview)
    -{
    -   // Paint it blue
    -   glClearColor(0.2, 0.2, 0.6, 1.0);
    -   glClear(GL_COLOR_BUFFER_BIT);
    -
    -   // The usual OpenGL ES draw commands come here
    -   // draw_scene();
    -}
    -
  6. -
  7. Callback for deleting -

    The delete callback is triggered when the GLView is being destroyed, from the main loop, and no other callback can be called on the same object afterwards.

    - -
    -// Delete GLView callback
    -static void del_gl(Evas_Object *glview)
    -{
    -   // Destroy all the OpenGL ES resources here
    -   // destroy_shaders();
    -   // destroy_objects();
    -}
    -
  8. -
  9. Add an animator. -

    The application above is technically working but the scene does not get updated unless the frame is marked as dirty. Game applications might need to use an animator to obtain continuous update of the scenes. Here is an example for a default update refresh rate:

    - -
    -static Eina_Bool anim_cb(void *data)
    -{
    -   Evas_Object *glview = data;
    -   elm_glview_changed_set(glview);
    -
    -   return ECORE_CALLBACK_RENEW;
    -}
    -
    -static void glview_start(Evas_Object *glview)
    -{
    -   ecore_animator_add(anim_cb, glview);
    -}
    - -

    Any other event can be used to refresh the view, for example user input if the view need to be updated.

    -
  10. -
- -
Table: History data types and required privileges
Description
+ All types CONTEXT_HISTORY_FILTER_TIME_SPAN
- All types EXCEPT: -

CONTEXT_HISTORY_COMMON_SETTING_FOR_APP

-

CONTEXT_HISTORY_COMMON_SETTING_FOR_MUSIC

-

CONTEXT_HISTORY_COMMON_SETTING_FOR_VIDEO

-
CONTEXT_HISTORY_FILTER_RESULT_SIZE Integer @@ -207,27 +201,36 @@ Once the context_hist
+ CONTEXT_HISTORY_PEAK_TIME_FOR_APP -

CONTEXT_HISTORY_COMMON_SETTING_FOR_APP +

CONTEXT_HISTORY_PEAK_TIME_FOR_MUSIC

+

CONTEXT_HISTORY_PEAK_TIME_FOR_VIDEO

CONTEXT_HISTORY_FILTER_APP_ID String - Use this filter to compute the peak time (or the common settings) for a specific application. Without this filter, the peak time (or the common setting) is computed from the usage history of all applications. + Use the CONTEXT_HISTORY_PEAK_TIME_FOR_APP filter to compute the peak time for a specific application. Without this filter, the peak time is computed from the usage history of all applications. +

In case of the peak time for music or video playbacks, these filters can be used to restrict the application that is used to play the media contents. Without this filter, playback logs from all applications are used to get the statistics.

For more information on the application IDs, see the Application Framework guide.

- CONTEXT_HISTORY_PEAK_TIME_FOR_APP -

CONTEXT_HISTORY_PEAK_TIME_FOR_MUSIC -

CONTEXT_HISTORY_PEAK_TIME_FOR_VIDEO -

CONTEXT_HISTORY_FILTER_DAY_OF_WEEK Integer - Use this filter to get usage patterns on weekdays or weekends. The filter value can be either CONTEXT_HISTORY_FILTER_DAY_OF_WEEK_WEEKDAYS, CONTEXT_HISTORY_FILTER_DAY_OF_WEEK_WEEKENDS, or CONTEXT_HISTORY_FILTER_DAY_OF_WEEK_ALL. By default, data from both weekdays and weekends are used if this filter is not set. + Use this filter to get application usage patterns on weekdays or weekends. The filter value can be either CONTEXT_HISTORY_FILTER_DAY_OF_WEEK_WEEKDAYS, CONTEXT_HISTORY_FILTER_DAY_OF_WEEK_WEEKENDS, or CONTEXT_HISTORY_FILTER_DAY_OF_WEEK_ALL. By default, data from both weekdays and weekends are used if this filter is not set. +
CONTEXT_HISTORY_COMMON_SETTING_FOR_APP +

CONTEXT_HISTORY_COMMON_SETTING_FOR_MUSIC

+

CONTEXT_HISTORY_COMMON_SETTING_FOR_VIDEO

+
CONTEXT_HISTORY_FILTER_APP_IDString + Use this filter to retrieve the most common setting values for a specific application. +

In case of music or video playback history, this filter can be used to get the common setting values when listening to music or watching videos using a specific application.

- - - - - - - - -
Note
Since the Evas rendering engine uses its own GL context internally, the application has to call the gl functions inside the 4 GLView callback functions (initialization, resizing, drawing, deleting) to be guaranteed rendering correctness.
- - -

While GLView is an abstraction above EvasGL, it is possible to use EvasGL directly for more low-level and advanced features, such as:

- -
    -
  • Creating new contexts
  • -
  • Creating new surfaces
  • -
  • Creating PBuffer surfaces
  • -
  • Calling extensions
  • -
- -

For all those reasons, a direct access to the EvasGL object is required. When you use GLView, you can use the following code:

- -
-Evas_GL *evgl = elm_glview_evas_gl_get(glview);
-// Then it is possible to call any evas_gl function with it, for example:
-Evas_GL_Context *ctx = evas_gl_current_context_get(evgl);
-Evas_GL_Surface *pbuf = evas_gl_pbuffer_surface_create(evgl, cfg, w, h, NULL);
- - - - - - - - - - - -
Note
Do not destroy the EvasGL object. Its life-cycle is defined by the GLView object.
- -

EvasGL Programming Guide

- -

This guide assumes that the application uses EvasGL directly instead of using the GLView. (If the application uses a GLView, EvasGL is created internally.)

- -

Declaration of EvasGL Objects

- -

This is how to define the application data structure to hold all the objects for your EvasGL application:

- -
    -
  • Evas_Object *win: Application window.
  • -
  • Evas_Object *img: OpenGL ES canvas.
  • -
  • Evas_GL *evasgl: EvasGL Object for rendering gl in Evas.
  • -
  • Evas_GL_API *glapi: EvasGL API object that contains the GL APIs to be used in Evas GL.
  • -
  • Evas_GL_Context *ctx: EvasGL Context object, a GL rendering context in Evas GL.
  • -
  • Evas_GL_Surface *sfc: EvasGL Surface object, a GL rendering target in Evas GL.
  • -
  • Evas_GL_Config *cfg: EvasGL Surface configuration object for surface creation.
  • -
- -
-typedef struct appdata 
-{
-   Evas_Object *win;
-   Evas_Object *img;
-
-   Evas_GL *evasgl;
-   Evas_GL_API *glapi;
-   Evas_GL_Context *ctx;
-   Evas_GL_Surface *sfc;
-   Evas_GL_Config *cfg;
-
-   unsigned int program;
-   unsigned int vtx_shader;
-   unsigned int fgmt_shader;
-   unsigned int vbo;
-} appdata_s;
- -

Creating EvasGL

- -

We can create our EvasGL handler using evas_gl_new(Evas * e). This initializer takes the Evas canvas that OpenGL ES is to be used on as a parameter. When developing an application with Elementary, we can use the canvas of our window:

- -
-ad->win = elm_win_util_standard_add("Evas_GL Example", "Evas_GL Example");
-ad->evasgl = evas_gl_new(evas_object_evas_get(ad->win));
- -

To free the memory allocated to this handler, use evas_gl_free(Evas_GL *evas_gl).

- -

Getting OpenGL ES APIs

- -

You can get the API for rendering OpenGL ES with evas_gl_api_get(Evas_GL *evas_gl_). This function returns a structure that contains all the OpenGL ES functions you can use to render in Evas. These functions consist of all the standard OpenGL ES2.0 functions and any extra ones Evas has decided to provide in addition. If you have your code ported to OpenGL ES 2.0, it is easy to render to Evas. (OpenGL ES 3.0 will be supported in the next Tizen version.)

- -
-ad->glapi = evas_gl_api_get(ad->evasgl);
- -

Creating a Surface

- -

We must allocate a new config object to fill it out using evas_gl_config_new(). As long as Evas creates a config object for the user, it takes care of the backward compatibility issue. Once we have our config object, we can specify the surface settings:

- -
-appdata_s *ad;
-ad->cfg = evas_gl_config_new();
-ad->cfg->color_format = EVAS_GL_RGBA_8888; // Surface Color Format
-ad->cfg->depth_bits = EVAS_GL_DEPTH_BIT_24; // Surface Depth Format
-ad->cfg->stencil_bits = EVAS_GL_STENCIL_NONE; // Surface Stencil Format
-ad->cfg->options_bits = EVAS_GL_OPTIONS_NONE; // Configuration options (here, no extra options)
- -

Once we have configured the surface behavior, we must initialize the surface using evas_gl_surface_create(Evas_GL* evas_gl, Evas_GL_Config * cfg, int w, int h). This function takes the given Evas_GL object as the first parameter and the pixel format, and configuration of the rendering surface as the second parameter. The last two parameters are the width and height of the surface, which we recover directly from the window.

- -
-Evas_Coord w, h;
-evas_object_geometry_get(ad->win, NULL, NULL, &w, &h);
-ad->sfc = evas_gl_surface_create(ad->evasgl, ad->cfg, w, h);
- -

To manually delete a GL surface, use evas_gl_surface_destroy(Evas_GL *evas_gl, Evas_GL_Surface *surf).

- -

Creating Context

- -

Here, we create a context for Evas_GL using evas_gl_context_create(Evas_GL * evas_gl, Evas_GL_Context * share_ctx). You can merge the context with a higher context definition you must pass as a second parameter.

- -
-ad->ctx = evas_gl_context_create(ad->evasgl, NULL);
- -

To delete the context later, use evas_gl_context_destroy(Evas_GL *evas_gl, Evas_GL_Context *ctx). To delete the entire configuration object, use evas_gl_config_free(Evas_GL_Config *cfg) instead.

- -

Callbacks

- -

Now that we have configured the EvasGL environment, we declare a UI component in which all the OpenGL ES transformation takes place. In the example below, we selected the image component because it provides callbacks that allow us to play with the mouse events and coordinates, and we set up an image object that inherits the size of the parent window.

- -
-ad->img = evas_object_image_filled_add(evas_object_evas_get(ad->win));
- -

We define the "OpenGL ES main loop" function that is called every time the program attempts to have pixels from the image. We put all the OpenGL ES statements in charge of rendering the scene in this callback.

- -
-evas_object_image_pixels_get_callback_set(ad->img, img_pixels_get_cb, ad);
- -

To define a function that takes care of the drawing using EvasGL (called the OpenGL ES main loop), use:

- -
-static void
-img_pixels_get_cb(void *data, Evas_Object *obj)
-{
-   appdata_s *ad = data;
-   Evas_GL_API *gl = ad->glapi;
-
-   // Rendering process
-   evas_gl_make_current(ad->evasgl, ad->sfc, ad->ctx);
-   // Paint it blue
-   gl->glClearColor(0.2, 0.2, 0.6, 1.0);
-   gl->glClear(GL_COLOR_BUFFER_BIT);
-   // The usual OpenGL ES draw commands come here
-   // draw_scene();
-}
- -

At every tick, we must set the given context as a current context for the given surface using evas_gl_make_current(Evas_GL *evas_gl, Evas_GL_Surface *surf, Evas_GL_Context *ctx).

- -

You can use the Ecore_Animator to define the OpenGL ES main loop. To do so, create a callback that is called on every animation tick. This animation callback is used only to mark the image as "dirty", meaning that it needs an update next time Evas renders. It calls the pixel get callback that redraws the scene.

- -
-static Eina_Bool
-animate_cb(void *data)
-{
-   Evas_Object *img = data;
-   evas_object_image_pixels_dirty_set(img, EINA_TRUE);
-
-   return ECORE_CALLBACK_RENEW;
-}
-
-ecore_animator_add(animate_cb, ad->img);
- -

You can define several other callbacks that have an impact on the drawing depending on the mouse, resize, and deletion events.

- -
-evas_object_event_callback_add(ad->img, EVAS_CALLBACK_DEL, img_del_cb, ad);
-evas_object_event_callback_add(ad->img, EVAS_CALLBACK_MOUSE_DOWN, mouse_down_cb, ad);
-evas_object_event_callback_add(ad->img, EVAS_CALLBACK_MOUSE_UP, mouse_up_cb, ad);
-evas_object_event_callback_add(ad->img, EVAS_CALLBACK_MOUSE_MOVE, mouse_move_cb, ad);
-evas_object_event_callback_add(ad->win, EVAS_CALLBACK_RESIZE, win_resize_cb, ad);
- -

Setting a Surface into the Image Object

- -

We can also fill in the native Surface information from the given EvasGL surface. For example, to adapt the surface to the target image when the size of the canvas changes, use the following code.

- -
-Evas_Native_Surface ns;
-evas_gl_native_surface_get(ad->evasgl, ad->sfc, &ns);
-evas_object_image_native_surface_set(ad->img, &ns);
- - - - - - -Go to top - - - - - - + + + + + + + + + + + + + OpenGL ES + + + + + +
+ +

OpenGL ES

+ +

The OpenGL ES overview shows the interaction among Graphics subsystems, OpenGL ES, and EGL defined by the Khronos Group.

+ +

OpenGL ES is a standard specification defining a cross-language, cross-platform OpenGL ES API (in mobile and wearable applications) for writing applications that produce 2D and 3D computer graphics. OpenGL ES 1.1 and 2.0 are supported in Tizen 2.3. (OpenGL ES 3.0 will be supported in the next Tizen version.)

+ +

EGL is an adhesive layer between OpenGL ES and the underlying native platform window system. EGL communicates with the Window system to get information on the application window, creates the drawing surface, and manages rendering context and resources.

+ +

Figure: OpenGL ES structure

+

OpenGL® ES structure

+ +

OpenGL ES in Tizen

+ +

Building an OpenGL ES application in Tizen requires knowledge about designing UI applications with EFL.

+ +

Tizen native applications do not depend on the Window system, because the Window system is an internal Tizen module, which can be enhanced or replaced. EFL provides a method that draws the OpenGL ES content and encapsulates the EGL and the native Window system.

+ +

Figure: OpenGL ES and EFL

+

OpenGL® ES and EFL

+ +

A GLView creates a drawable GL surface for the application, and sets up all the required callbacks. The application can use GLView with various UI components, such as toolbar or button.

+ +

GLView internally uses EvasGL. It is an abstraction layer on top of EGL, which provides the necessary features for most applications in a platform-independent way. Since the goal of EvasGL is to abstract the underlying platform, only a subset of the features can be used by applications.

+ +

Using GLView is recommended for usual OpenGL ES programs, such as 3D game applications. But if you need pbuffer surface or extension functions, you have to understand EvasGL.

+ +

EvasGL vs. GLView

+ +

While it is possible to create an OpenGL application by just using EvasGL, it could be difficult to comprehend due to the low-level nature of these APIs. However, it enables detailed operations.

+ +

GLView Programming Guide

+ +

Setting up an OpenGL ES Surface

+ +

The easiest way to use OpenGL ES within a Tizen application is to rely on the GLView component.

+ +

GLView is a simple Elementary UI component that sets up an OpenGL ES target surface and a context, and allows you to embed it in any Tizen application. GLView is basically a wrapper around EvasGL, the OpenGL-ES/EGL abstraction layer of EFL.

+ +

To create a basic application:

+ +

To develop a GL application, you have to call elm_config_accel_preference_set before creating a window. It makes an application to use GPU. To use the Direct Rendering mode, you have to set the same option values (depth, stencil, and MSAA) to a rendering engine and a GLView object. You can set the option values to a rendering engine using the elm_config_accel_preference_set() function and to a GLView object using the elm_glview_mode_set() function. If the GLView object option values are bigger or higher than the rendering engine's, the Direct Rendering mode is disabled.

+ +

First, you should declare the global variable using ELEMENTARY_GLVIEW_GLOBAL_DEFINE(), then create a GLView object and use ELEMENTARY_GLVIEW_GLOBAL_USE(glview). Now, you can call GL functions.

+ +
+#include <app.h>
+#include <Elementary_GL_Helpers.h>
+
+ELEMENTARY_GLVIEW_GLOBAL_DEFINE()
+
+typedef struct appdata 
+{
+   Evas_Object *win;
+   Evas_Object *glview;
+   unsigned int program;
+   unsigned int vtx_shader;
+   unsigned int fgmt_shader;
+   unsigned int vbo;
+} appdata_s;
+
+static Evas_Object *glview_create(Evas_Object *win);
+static void glview_start(Evas_Object *glview);
+
+// GLView callback functions
+static void draw_gl(Evas_Object *obj);
+static void init_gl(Evas_Object *obj);
+static void resize_gl(Evas_Object *obj);
+static void del_gl(Evas_Object *obj);
+
+static bool app_create(void *data) 
+{
+   appdata_s *ad = data;
+   elm_config_accel_preference_set("gl");
+   ad->win = elm_win_util_standard_add("GLView example", "GLView example");
+   evas_object_show(ad->win);
+   ad->glview = ad->glview_create(ad->win);
+   ELEMENTARY_GLVIEW_GLOBAL_USE(ad->glview);
+   glview_start(ad->glview);
+
+   return true;
+}
+ +

Add the OpenGL ES view to the application:

+ +
+// This is the GL initialization function
+static Evas_Object *glview_create(Evas_Object *win)
+{
+   Evas_Object *glview;
+
+   // This creates the UI component itself
+   glview = elm_glview_add(win);
+   elm_win_resize_object_add(win, glview);
+
+   // Request a surface with Depth and Stencil support (default buffer sizes)
+   elm_glview_mode_set(glview, ELM_GLVIEW_DEPTH | ELM_GLVIEW_STENCIL);
+
+   // Set the basic policies to handle the view transparently
+   elm_glview_resize_policy_set(glview, ELM_GLVIEW_RESIZE_POLICY_RECREATE);
+   elm_glview_render_policy_set(glview, ELM_GLVIEW_RENDER_POLICY_ON_DEMAND);
+
+   // Set the 4 main callbacks
+   elm_glview_init_func_set(glview, init_gl);
+   elm_glview_del_func_set(glview, del_gl);
+   elm_glview_render_func_set(glview, draw_gl);
+   elm_glview_resize_func_set(glview, resize_gl);
+
+   // Finally show this view
+   evas_object_size_hint_min_set(glview, 250, 250);
+   evas_object_show(glview);
+
+   return glview;
+}
+ +

Setting up the Callbacks

+ +

To set up callbacks:

+ +
    +
  1. Callback for initialization +

    The initialization callback will be called when the GLView is created, after a valid openGL ES context and surface are created. Initialization, resizing, drawing, and deleting callback are called in the main loop.

    + +
    +// GL Init function
    +static void init_gl(Evas_Object *glview)
    +{
    +   glClearColor(0, 0, 0, 0);
    +   glClear(GL_COLOR_BUFFER_BIT);
    +
    +   // Do any form of OpenGL ES initialization here
    +   // init_shaders();
    +   // init_vertices();
    +}
    +
  2. +
  3. Callback for resizing +

    The resize callback is called whenever the GLView component is resized. A common action to take here is to reset the viewport.

    + +
    +// GLView resize function
    +static void resize_gl(Evas_Object *glview)
    +{
    +   int w, h;
    +   elm_glview_size_get(glview, &w, &h);
    +   glViewport(0, 0, w, h);
    +}
    +
  4. +
  5. Callback for drawing +

    The drawing callback is called whenever a new frame has to be drawn. The exact moment when this function is called depends on the policy.

    + +
    +elm_glview_render_policy_set(glview, ELM_GLVIEW_RENDER_POLICY_ON_DEMAND);
    + +

    Another policy is ELM_GLVIEW_POLICY_ALWAYS, which requests render always even when it is not visible. So on demand policy is probably what you are looking for. The application can now draw anything using GL primitives when this callback is triggered. All draw operations are restricted to the surface of the GLView object previously created.

    + +
    +// GL draw callback
    +static void draw_gl(Evas_Object *glview)
    +{
    +   // Paint it blue
    +   glClearColor(0.2, 0.2, 0.6, 1.0);
    +   glClear(GL_COLOR_BUFFER_BIT);
    +
    +   // The usual OpenGL ES draw commands come here
    +   // draw_scene();
    +}
    +
  6. +
  7. Callback for deleting +

    The delete callback is triggered when the GLView is being destroyed, from the main loop, and no other callback can be called on the same object afterwards.

    + +
    +// Delete GLView callback
    +static void del_gl(Evas_Object *glview)
    +{
    +   // Destroy all the OpenGL ES resources here
    +   // destroy_shaders();
    +   // destroy_objects();
    +}
    +
  8. +
  9. Add an animator. +

    The application above is technically working but the scene does not get updated unless the frame is marked as dirty. Game applications might need to use an animator to obtain continuous update of the scenes. Here is an example for a default update refresh rate:

    + +
    +static Eina_Bool anim_cb(void *data)
    +{
    +   Evas_Object *glview = data;
    +   elm_glview_changed_set(glview);
    +
    +   return ECORE_CALLBACK_RENEW;
    +}
    +
    +static void glview_start(Evas_Object *glview)
    +{
    +   ecore_animator_add(anim_cb, glview);
    +}
    + +

    Any other event can be used to refresh the view, for example user input if the view need to be updated.

    +
  10. +
+ + + + + + + + + + +
Note
Since the Evas rendering engine uses its own GL context internally, the application has to call the gl functions inside the 4 GLView callback functions (initialization, resizing, drawing, deleting) to be guaranteed rendering correctness.
+ + +

While GLView is an abstraction above EvasGL, it is possible to use EvasGL directly for more low-level and advanced features, such as:

+ +
    +
  • Creating new contexts
  • +
  • Creating new surfaces
  • +
  • Creating PBuffer surfaces
  • +
  • Calling extensions
  • +
+ +

For all those reasons, a direct access to the EvasGL object is required. When you use GLView, you can use the following code:

+ +
+Evas_GL *evgl = elm_glview_evas_gl_get(glview);
+// Then it is possible to call any evas_gl function with it, for example:
+Evas_GL_Context *ctx = evas_gl_current_context_get(evgl);
+Evas_GL_Surface *pbuf = evas_gl_pbuffer_surface_create(evgl, cfg, w, h, NULL);
+ + + + + + + + + + + +
Note
Do not destroy the EvasGL object. Its life-cycle is defined by the GLView object.
+ +

EvasGL Programming Guide

+ +

This guide assumes that the application uses EvasGL directly instead of using the GLView. (If the application uses a GLView, EvasGL is created internally.)

+ +

Declaration of EvasGL Objects

+ +

This is how to define the application data structure to hold all the objects for your EvasGL application:

+ +
    +
  • Evas_Object *win: Application window.
  • +
  • Evas_Object *img: OpenGL ES canvas.
  • +
  • Evas_GL *evasgl: EvasGL Object for rendering gl in Evas.
  • +
  • Evas_GL_API *glapi: EvasGL API object that contains the GL APIs to be used in Evas GL.
  • +
  • Evas_GL_Context *ctx: EvasGL Context object, a GL rendering context in Evas GL.
  • +
  • Evas_GL_Surface *sfc: EvasGL Surface object, a GL rendering target in Evas GL.
  • +
  • Evas_GL_Config *cfg: EvasGL Surface configuration object for surface creation.
  • +
+ +
+typedef struct appdata 
+{
+   Evas_Object *win;
+   Evas_Object *img;
+
+   Evas_GL *evasgl;
+   Evas_GL_API *glapi;
+   Evas_GL_Context *ctx;
+   Evas_GL_Surface *sfc;
+   Evas_GL_Config *cfg;
+
+   unsigned int program;
+   unsigned int vtx_shader;
+   unsigned int fgmt_shader;
+   unsigned int vbo;
+} appdata_s;
+ +

Creating EvasGL

+ +

We can create our EvasGL handler using evas_gl_new(Evas * e). This initializer takes the Evas canvas that OpenGL ES is to be used on as a parameter. When developing an application with Elementary, we can use the canvas of our window:

+ +
+ad->win = elm_win_util_standard_add("Evas_GL Example", "Evas_GL Example");
+ad->evasgl = evas_gl_new(evas_object_evas_get(ad->win));
+ +

To free the memory allocated to this handler, use evas_gl_free(Evas_GL *evas_gl).

+ +

Getting OpenGL ES APIs

+ +

You can get the API for rendering OpenGL ES with evas_gl_api_get(Evas_GL *evas_gl_). This function returns a structure that contains all the OpenGL ES functions you can use to render in Evas. These functions consist of all the standard OpenGL ES2.0 functions and any extra ones Evas has decided to provide in addition. If you have your code ported to OpenGL ES 2.0, it is easy to render to Evas. (OpenGL ES 3.0 will be supported in the next Tizen version.)

+ +
+ad->glapi = evas_gl_api_get(ad->evasgl);
+ +

Creating a Surface

+ +

We must allocate a new config object to fill it out using evas_gl_config_new(). As long as Evas creates a config object for the user, it takes care of the backward compatibility issue. Once we have our config object, we can specify the surface settings:

+ +
+appdata_s *ad;
+ad->cfg = evas_gl_config_new();
+ad->cfg->color_format = EVAS_GL_RGBA_8888; // Surface Color Format
+ad->cfg->depth_bits = EVAS_GL_DEPTH_BIT_24; // Surface Depth Format
+ad->cfg->stencil_bits = EVAS_GL_STENCIL_NONE; // Surface Stencil Format
+ad->cfg->options_bits = EVAS_GL_OPTIONS_NONE; // Configuration options (here, no extra options)
+ +

Once we have configured the surface behavior, we must initialize the surface using evas_gl_surface_create(Evas_GL* evas_gl, Evas_GL_Config * cfg, int w, int h). This function takes the given Evas_GL object as the first parameter and the pixel format, and configuration of the rendering surface as the second parameter. The last two parameters are the width and height of the surface, which we recover directly from the window.

+ +
+Evas_Coord w, h;
+evas_object_geometry_get(ad->win, NULL, NULL, &w, &h);
+ad->sfc = evas_gl_surface_create(ad->evasgl, ad->cfg, w, h);
+ +

To manually delete a GL surface, use evas_gl_surface_destroy(Evas_GL *evas_gl, Evas_GL_Surface *surf).

+ +

Creating Context

+ +

Here, we create a context for Evas_GL using evas_gl_context_create(Evas_GL * evas_gl, Evas_GL_Context * share_ctx). You can merge the context with a higher context definition you must pass as a second parameter.

+ +
+ad->ctx = evas_gl_context_create(ad->evasgl, NULL);
+ +

To delete the context later, use evas_gl_context_destroy(Evas_GL *evas_gl, Evas_GL_Context *ctx). To delete the entire configuration object, use evas_gl_config_free(Evas_GL_Config *cfg) instead.

+ +

Callbacks

+ +

Now that we have configured the EvasGL environment, we declare a UI component in which all the OpenGL ES transformation takes place. In the example below, we selected the image component because it provides callbacks that allow us to play with the mouse events and coordinates, and we set up an image object that inherits the size of the parent window.

+ +
+ad->img = evas_object_image_filled_add(evas_object_evas_get(ad->win));
+ +

We define the "OpenGL ES main loop" function that is called every time the program attempts to have pixels from the image. We put all the OpenGL ES statements in charge of rendering the scene in this callback.

+ +
+evas_object_image_pixels_get_callback_set(ad->img, img_pixels_get_cb, ad);
+ +

To define a function that takes care of the drawing using EvasGL (called the OpenGL ES main loop), use:

+ +
+static void
+img_pixels_get_cb(void *data, Evas_Object *obj)
+{
+   appdata_s *ad = data;
+   Evas_GL_API *gl = ad->glapi;
+
+   // Rendering process
+   evas_gl_make_current(ad->evasgl, ad->sfc, ad->ctx);
+   // Paint it blue
+   gl->glClearColor(0.2, 0.2, 0.6, 1.0);
+   gl->glClear(GL_COLOR_BUFFER_BIT);
+   // The usual OpenGL ES draw commands come here
+   // draw_scene();
+}
+ +

At every tick, we must set the given context as a current context for the given surface using evas_gl_make_current(Evas_GL *evas_gl, Evas_GL_Surface *surf, Evas_GL_Context *ctx).

+ +

You can use the Ecore_Animator to define the OpenGL ES main loop. To do so, create a callback that is called on every animation tick. This animation callback is used only to mark the image as "dirty", meaning that it needs an update next time Evas renders. It calls the pixel get callback that redraws the scene.

+ +
+static Eina_Bool
+animate_cb(void *data)
+{
+   Evas_Object *img = data;
+   evas_object_image_pixels_dirty_set(img, EINA_TRUE);
+
+   return ECORE_CALLBACK_RENEW;
+}
+
+ecore_animator_add(animate_cb, ad->img);
+ +

You can define several other callbacks that have an impact on the drawing depending on the mouse, resize, and deletion events.

+ +
+evas_object_event_callback_add(ad->img, EVAS_CALLBACK_DEL, img_del_cb, ad);
+evas_object_event_callback_add(ad->img, EVAS_CALLBACK_MOUSE_DOWN, mouse_down_cb, ad);
+evas_object_event_callback_add(ad->img, EVAS_CALLBACK_MOUSE_UP, mouse_up_cb, ad);
+evas_object_event_callback_add(ad->img, EVAS_CALLBACK_MOUSE_MOVE, mouse_move_cb, ad);
+evas_object_event_callback_add(ad->win, EVAS_CALLBACK_RESIZE, win_resize_cb, ad);
+ +

Setting a Surface into the Image Object

+ +

We can also fill in the native Surface information from the given EvasGL surface. For example, to adapt the surface to the target image when the size of the canvas changes, use the following code.

+ +
+Evas_Native_Surface ns;
+evas_gl_native_surface_get(ad->evasgl, ad->sfc, &ns);
+evas_object_image_native_surface_set(ad->img, &ns);
+ + + + +
+ +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/native/graphics/tbm_n.htm b/org.tizen.guides/html/native/graphics/tbm_n.htm index 61525ea..f3cb78d 100644 --- a/org.tizen.guides/html/native/graphics/tbm_n.htm +++ b/org.tizen.guides/html/native/graphics/tbm_n.htm @@ -1,136 +1,136 @@ - - - - - - - - - - - - - TBM Surface - - - - - -
- - -

TBM Surface

- -

The Tizen Buffer Manager (TBM) surface provides functions for the graphic buffer in Tizen. It provides the abstraction interface for the graphic buffer and the user interface for the TBM surface. It supports the RGB and YUV graphic formats, as well as multiple plane graphic buffers.

- -

The TBM surface provides the following main features:

-
    -
  • Creating a surface with defined width, height, and format
  • -
  • Getting a format list
  • -
  • Accessing the surface
  • -
  • Getting surface and plane information
  • -
- -

The TBM surface provides various format typedefs. However, check that the system supports the graphic format in question.

- -

Get surface and plane information using the tbm_surface_map() or the tbm_surface_get_info() function. The information of surface is assigned in the struct of tbm_surface_info_s.

- -

Get a plane pointer in the surface and store data in the low level graphic buffer using the pointer of each plane.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- Table: Surface information -
InformationDescription
widthSurface width
heightSurface height
bppSurface BPP
sizeSurface size
num_planesNumber of planes
- - - - - - - - - - - - - - - - - - - - - - - - - -
- Table: Plane information -
InformationDescription
sizePlane size
offsetPlane offset
stridePlane stride
ptrPlane pointer
- - - - -
- -Go to top - - - - - - + + + + + + + + + + + + + TBM Surface + + + + + +
+ + +

TBM Surface

+ +

The Tizen Buffer Manager (TBM) surface provides functions for the graphic buffer in Tizen. It provides the abstraction interface for the graphic buffer and the user interface for the TBM surface. It supports the RGB and YUV graphic formats, as well as multiple plane graphic buffers.

+ +

The TBM surface provides the following main features:

+
    +
  • Creating a surface with defined width, height, and format
  • +
  • Getting a format list
  • +
  • Accessing the surface
  • +
  • Getting surface and plane information
  • +
+ +

The TBM surface provides various format typedefs. However, check that the system supports the graphic format in question.

+ +

Get surface and plane information using the tbm_surface_map() or the tbm_surface_get_info() function. The information of surface is assigned in the struct of tbm_surface_info_s.

+ +

Get a plane pointer in the surface and store data in the low level graphic buffer using the pointer of each plane.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Table: Surface information +
InformationDescription
widthSurface width
heightSurface height
bppSurface BPP
sizeSurface size
num_planesNumber of planes
+ + + + + + + + + + + + + + + + + + + + + + + + + +
+ Table: Plane information +
InformationDescription
sizePlane size
offsetPlane offset
stridePlane stride
ptrPlane pointer
+ + + + +
+ +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/native/guides_n.htm b/org.tizen.guides/html/native/guides_n.htm index e9b2fac..08e1cdf 100644 --- a/org.tizen.guides/html/native/guides_n.htm +++ b/org.tizen.guides/html/native/guides_n.htm @@ -76,7 +76,7 @@

For information about features not implemented by a specific API:

    -
  • Porting in mobile applications only +
  • Porting in mobile applications only

    Enables you to port your current 2.2.1 native API-based applications to the new 2.3 native API.

diff --git a/org.tizen.guides/html/native/location/location_guide_n.htm b/org.tizen.guides/html/native/location/location_guide_n.htm index 56f32a0..59cd731 100644 --- a/org.tizen.guides/html/native/location/location_guide_n.htm +++ b/org.tizen.guides/html/native/location/location_guide_n.htm @@ -1,75 +1,75 @@ - - - - - - - - - - - - - Location - - - - - -
- - -

Location

-

Location features include access to the device positioning capabilities.

- -

The main location features are:

-
    -
  • Location -

    Provides the geographical location of the device.

  • -
- - -

The following guides apply in mobile applications only:

-
    -
  • Geofence -

    Allows you to create and use geofences.

  • -
  • Maps Service -

    Allows you to create and use the maps services, such as geocoder, place searching, and routing.

  • -
- - - - -
- -Go to top - - - - - + + + + + + + + + + + + + Location + + + + + +
+ + +

Location

+

Location features include access to the device positioning capabilities.

+ +

The main location features are:

+
    +
  • Location +

    Provides the geographical location of the device.

  • +
+ + +

The following guides apply in mobile applications only:

+
    +
  • Geofence +

    Allows you to create and use geofences.

  • +
  • Maps Service +

    Allows you to create and use the maps services, such as geocoder, place searching, and routing.

  • +
+ + + + +
+ +Go to top + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/native/messaging/email_n.htm b/org.tizen.guides/html/native/messaging/email_n.htm index a647c6e..1ae9a57 100644 --- a/org.tizen.guides/html/native/messaging/email_n.htm +++ b/org.tizen.guides/html/native/messaging/email_n.htm @@ -1,86 +1,86 @@ - - - - - - - - - - - - - Email - - - -
-
-

Mobile native

-
- -
-

Related Info

- -
-
- -
- -

Email

-

Email is a method of exchanging digital messages. Email systems are based on a store-and-forward model, in which email server computer systems accept, forward, deliver, and store messages on behalf of users, who only need to connect to the email infrastructure, typically an email server, with a network-enabled device for the duration of a message submission or retrieval.

- - - - - - - - - - -
Note
This feature is supported in mobile applications only.
- -

Email provides features for composing, saving, and sending email messages using an SMTP (SMTP used for sending emails through the Internet is described in the RFC5321/5322 standards). It provides services to applications that make use of the email service.

- -

The Email API can be utilized by any component in the application layer which facilitates the end user to perform email messaging. For example, the Email APIs can be invoked by a multimedia module when the user wants to send a media file through email, or by an email application when the user tries to send an email message.

- -

Figure: Email service architecture

-

Email service architecture

- - -

The main features of the Email API include:

- -
  • Preparing email messages: set the subject, body, and recipients of the message, and the file path for any attachments.
  • -
  • Sending email messages.
  • -
  • Registering a callback function to be notified of the message status.
- -

Email sending is asynchronous and the application must not wait for the result. The process can be slow (connections must be established), and even if the mail server is not available a message sending is not a failure if a spooling mechanism exists. Use the callback function to receive the status when the message has been sent.

-

Note that once the email_send_message() function is called, the message content is out of the application's control. Even if the message appears not to have finished sending, it can no longer be modified.

- - - -
- -Go to top - - - - - - + + + + + + + + + + + + + Email + + + +
+
+

Mobile native

+
+ +
+

Related Info

+ +
+
+ +
+ +

Email

+

Email is a method of exchanging digital messages. Email systems are based on a store-and-forward model, in which email server computer systems accept, forward, deliver, and store messages on behalf of users, who only need to connect to the email infrastructure, typically an email server, with a network-enabled device for the duration of a message submission or retrieval.

+ + + + + + + + + + +
Note
This feature is supported in mobile applications only.
+ +

Email provides features for composing, saving, and sending email messages using an SMTP (SMTP used for sending emails through the Internet is described in the RFC5321/5322 standards). It provides services to applications that make use of the email service.

+ +

The Email API can be utilized by any component in the application layer which facilitates the end user to perform email messaging. For example, the Email APIs can be invoked by a multimedia module when the user wants to send a media file through email, or by an email application when the user tries to send an email message.

+ +

Figure: Email service architecture

+

Email service architecture

+ + +

The main features of the Email API include:

+ +
  • Preparing email messages: set the subject, body, and recipients of the message, and the file path for any attachments.
  • +
  • Sending email messages.
  • +
  • Registering a callback function to be notified of the message status.
+ +

Email sending is asynchronous and the application must not wait for the result. The process can be slow (connections must be established), and even if the mail server is not available a message sending is not a failure if a spooling mechanism exists. Use the callback function to receive the status when the message has been sent.

+

Note that once the email_send_message() function is called, the message content is out of the application's control. Even if the message appears not to have finished sending, it can no longer be modified.

+ + + +
+ +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/native/messaging/messages_n.htm b/org.tizen.guides/html/native/messaging/messages_n.htm index 63acb27..321ab8d 100644 --- a/org.tizen.guides/html/native/messaging/messages_n.htm +++ b/org.tizen.guides/html/native/messaging/messages_n.htm @@ -1,70 +1,70 @@ - - - - - - - - - - - - - Messages - - - - - -
-

Messages

- -

Tizen provides you with access to the device messaging capabilities, including sending SMS and MMS messages.

- -

The main messaging features include:

-
  • Text messaging (SMS) -

    You can create a message, send it, and receive the sent status. You can also receive incoming messages, and search for messages within a message list.

  • -
  • Multimedia messaging (MMS) -

    You can create and send MMS messages. An image, audio, video, vCard, vCalendar, or a combination of them is supported as an attachment type in MMS messages. An image or audio attachment cannot be combined with video attachments.

  • -
  • Messaging notifications -

    You can register and unregister callback functions to be notified when an outgoing message is successfully sent or an incoming message has been received.

- -

The sent status of SMS and MMS can be checked asynchronously. You receive a separate status report for each SMS recipient, and one status report regardless of the number of MMS recipients.

- - - - -
- -Go to top - - - - - - + + + + + + + + + + + + + Messages + + + + + +
+

Messages

+ +

Tizen provides you with access to the device messaging capabilities, including sending SMS and MMS messages.

+ +

The main messaging features include:

+
  • Text messaging (SMS) +

    You can create a message, send it, and receive the sent status. You can also receive incoming messages, and search for messages within a message list.

  • +
  • Multimedia messaging (MMS) +

    You can create and send MMS messages. An image, audio, video, vCard, vCalendar, or a combination of them is supported as an attachment type in MMS messages. An image or audio attachment cannot be combined with video attachments.

  • +
  • Messaging notifications +

    You can register and unregister callback functions to be notified when an outgoing message is successfully sent or an incoming message has been received.

+ +

The sent status of SMS and MMS can be checked asynchronously. You receive a separate status report for each SMS recipient, and one status report regardless of the number of MMS recipients.

+ + + + +
+ +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/native/messaging/messaging_guide_n.htm b/org.tizen.guides/html/native/messaging/messaging_guide_n.htm index 6d5f543..a4c4311 100644 --- a/org.tizen.guides/html/native/messaging/messaging_guide_n.htm +++ b/org.tizen.guides/html/native/messaging/messaging_guide_n.htm @@ -1,69 +1,69 @@ - - - - - - - - - - - - - Messaging - - - - - -
-

Messaging

-

Messaging features include access to the device messaging capabilities.

- -

The main messaging features are:

-
    -
  • Messages

    Provides you with access to the device text and multimedia messaging capabilities.

  • -
  • Push

    Allows you to push events from an application server to your application on a Tizen device.

  • -
-

The following guides apply in mobile applications only:

-
    -
  • Email

    Allows you to create and send emails.

  • -
- - - - -
- -Go to top - - - - - - + + + + + + + + + + + + + Messaging + + + + + +
+

Messaging

+

Messaging features include access to the device messaging capabilities.

+ +

The main messaging features are:

+
    +
  • Messages

    Provides you with access to the device text and multimedia messaging capabilities.

  • +
  • Push

    Allows you to push events from an application server to your application on a Tizen device.

  • +
+

The following guides apply in mobile applications only:

+
    +
  • Email

    Allows you to create and send emails.

  • +
+ + + + +
+ +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/native/messaging/push_n.htm b/org.tizen.guides/html/native/messaging/push_n.htm index 4d3b7b6..0b9a195 100644 --- a/org.tizen.guides/html/native/messaging/push_n.htm +++ b/org.tizen.guides/html/native/messaging/push_n.htm @@ -1,144 +1,144 @@ - - - - - - - - - - - - - Push - - - - - -
-

Push

- -

Push enables you to push events from an application server to your application on a Tizen device.

-

Figure: Push messaging service

-

Push messaging service

-

Once your application is successfully registered in the push server through the push daemon on the device, your application server can send push messages to the application in that particular device.

-

When a push message arrives when the application is running, it is automatically delivered to the application. If not, the daemon makes a sound or vibrates and adds a ticker or a badge notification to notify the user. By touching this notification, the user can check the message. The application server may send a message with a LAUNCH option. In this case, the daemon forcibly launches the application and hands over the message to the application as an app control.

- -

To use the push messaging service, the application needs the permission to access Tizen push server. Request the permission from the Tizen push service team by email (push.tizen@samsung.com), including the information listed in the following table. When the team approves your request, you receive a push app ID corresponding to your package ID.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Table: Request form details
Developer information

Email address

Your email address to receive the approval response.

Last name

Your last name.

First name

Your first name.

Country

Your country of residence.

Application information

Package ID

The ID of the application package that uses the push messaging service. The package ID can be obtained from the .xml file in the Tizen SDK.

Application name

Name of the application that uses the push service.

Testing purpose

Yes or no. If you request the service for testing purposes only, the duration of the push service is limited to 3 weeks.

Purpose of the push notification usage

Description of how you plan to use the push service, including the situations in which you want to use it.

App launch date

Application launch date in the YYYY/MM/DD format.
For example: 2012/08/01.

Service area / country

Service area (such as Asia, Africa, America, or Europe) or the country where the application is used.

Daily push requests

Estimated total number of daily notifications.

Transactions per second

Estimated peak number of transactions per second (the recommendation is below 100).

- -

Service Architecture

-

The following figure illustrates the service architecture of the Tizen push messaging service.

-

Figure: Service architecture

-

Service architecture

-

The following steps illustrate a typical scenario for using the push messaging service on a Tizen device:

-
    -
  1. The application on the device registers for the push messaging service.
  2. -
  3. The device establishes a push session with the Tizen Server.

    The push session is managed by the Tizen server and device platform, so there is no need to create any code to manage it within the application.

  4. -
  5. If the registration succeeds, the application receives a registration ID, which is a unique key for identifying the device and routing the push message.

    The application delivers the identifier to the application server.

  6. -
  7. When the application server needs to send a push message to the application, it calls the Tizen server's open API.

    A text message of up to 1024 bytes can be sent in a push message. If the application needs to download a large amount of data, the application server sends a link to the data in the push message.

  8. -
  9. The Tizen Server routes the push message to the target device with a given registration ID.
  10. -
  11. The application receives the push message.
  12. -
- - - -
- -Go to top - - - - - - + + + + + + + + + + + + + Push + + + + + +
+

Push

+ +

Push enables you to push events from an application server to your application on a Tizen device.

+

Figure: Push messaging service

+

Push messaging service

+

Once your application is successfully registered in the push server through the push daemon on the device, your application server can send push messages to the application in that particular device.

+

When a push message arrives when the application is running, it is automatically delivered to the application. If not, the daemon makes a sound or vibrates and adds a ticker or a badge notification to notify the user. By touching this notification, the user can check the message. The application server may send a message with a LAUNCH option. In this case, the daemon forcibly launches the application and hands over the message to the application as an app control.

+ +

To use the push messaging service, the application needs the permission to access Tizen push server. Request the permission from the Tizen push service team by email (push.tizen@samsung.com), including the information listed in the following table. When the team approves your request, you receive a push app ID corresponding to your package ID.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table: Request form details
Developer information

Email address

Your email address to receive the approval response.

Last name

Your last name.

First name

Your first name.

Country

Your country of residence.

Application information

Package ID

The ID of the application package that uses the push messaging service. The package ID can be obtained from the .xml file in the Tizen SDK.

Application name

Name of the application that uses the push service.

Testing purpose

Yes or no. If you request the service for testing purposes only, the duration of the push service is limited to 3 weeks.

Purpose of the push notification usage

Description of how you plan to use the push service, including the situations in which you want to use it.

App launch date

Application launch date in the YYYY/MM/DD format.
For example: 2012/08/01.

Service area / country

Service area (such as Asia, Africa, America, or Europe) or the country where the application is used.

Daily push requests

Estimated total number of daily notifications.

Transactions per second

Estimated peak number of transactions per second (the recommendation is below 100).

+ +

Service Architecture

+

The following figure illustrates the service architecture of the Tizen push messaging service.

+

Figure: Service architecture

+

Service architecture

+

The following steps illustrate a typical scenario for using the push messaging service on a Tizen device:

+
    +
  1. The application on the device registers for the push messaging service.
  2. +
  3. The device establishes a push session with the Tizen Server.

    The push session is managed by the Tizen server and device platform, so there is no need to create any code to manage it within the application.

  4. +
  5. If the registration succeeds, the application receives a registration ID, which is a unique key for identifying the device and routing the push message.

    The application delivers the identifier to the application server.

  6. +
  7. When the application server needs to send a push message to the application, it calls the Tizen server's open API.

    A text message of up to 1024 bytes can be sent in a push message. If the application needs to download a large amount of data, the application server sends a link to the data in the push message.

  8. +
  9. The Tizen Server routes the push message to the target device with a given registration ID.
  10. +
  11. The application receives the push message.
  12. +
+ + + +
+ +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/native/multimedia/audio_io_n.htm b/org.tizen.guides/html/native/multimedia/audio_io_n.htm index 1464735..c01d19b 100644 --- a/org.tizen.guides/html/native/multimedia/audio_io_n.htm +++ b/org.tizen.guides/html/native/multimedia/audio_io_n.htm @@ -1,159 +1,159 @@ - - - - - - - - - - - - - Audio I/O - - - - - -
-

Audio I/O

- -

Audio I/O enables your application to manage various media handles.

-

The main features of the Audio I/O API include:

- - -

Recording Uncompressed Audio

-

The Pulse Code Modulated (PCM) data contains non-compressed audio. The Audio Input API (in mobile and wearable applications) enables your application to record such data from a microphone type input device.

-

Audio data is captured periodically, so to receive the audio PCM data from the input device, you must implement the audio input interface to notify the application of audio data events, such as the end of filling audio data.

-

Before recording audio, you must define the following PCM data settings:

-
    -
  • Input device type: -
      -
    • Microphone
    • -
  • -
  • Audio channels: -
      -
    • Mono (1 channel)
    • -
    • Stereo (2 channels)
    • -
  • -
  • Audio sample type: -
      -
    • Unsigned 8-bit PCM
    • -
    • Signed 16-bit little endian PCM
    • -
  • -
  • Audio sample rate: -
      -
    • 8000 ~ 48000 Hz
    • -
  • -
-

To minimize the overhead of the audio input API, use the optimal channel type, sample type and sampling rate, which can be retrieved using the audio_in_get_channel(), audio_in_get_sample_type() and audio_in_get_sample_rate() functions, respectively.

- - -

The following figures illustrate the general audio input states, and how the state changes when the audio input is interrupted by the system.

-

Figure: Audio input states

-

Audio input states

-

Figure: Audio input states when interrupted by system

-

Audio input states when interrupted by system

- - -

Playing Uncompressed Audio

-

The Pulse Code Modulated (PCM) data contains non-compressed audio. The Audio Output API (in mobile and wearable applications) enables your application to play such data using output devices.

-

To play the audio PCM data, the application must call the audio_out_create() function to initialize the audio output handle.

-

Before playing audio, your application must define the following PCM data settings:

-
    -
  • Audio channels: -
      -
    • Mono (1 channel)
    • -
    • Stereo (2 channels)
    • -
  • -
  • Audio sample type: -
      -
    • Unsigned 8-bit PCM
    • -
    • Signed 16-bit little endian PCM
    • -
  • -
  • Audio sample rate: -
      -
    • 8000 ~ 48000 Hz
    • -
  • -
- -

The following figures illustrate the general audio output states, and how the state changes when the audio output is interrupted by the system.

-

Figure: Audio output states

-

Audio output states

-

Figure: Audio output states when interrupted by system

-

Audio output states when interrupted by system

- -

Using Audio Output

-

For supporting various low-end Tizen devices, the application must follow certain guidelines:

-
    -
  • Do not use multiple instances of the Audio Output excessively. -

    Using excessive multiple instances of the Audio Output has a negative effect on the application, because the audio data processing for re-sampling and mixing imposes a heavy burden on the system.

  • -
  • Use device-preferred PCM format. -
      - -
    • To reduce the processing overhead, use the target device-preferred PCM format (for example, use 16-bit little endian, 44.1 kHz, stereo for Wave and Wave M).

    • -
    • Using the preferred format reduces internal operations, such as converting audio samples from mono to stereo or re-sampling audio frequency to fit the target device's input sample rate.

    • -
  • -
  • Do not call the Audio Output functions too frequently. -
      -
    • The Audio Output functions require more time while repeated in the order of audio_out_create() > audio_out_prepare() > audio_out_unprepare() > audio_out_destroy(). Therefore, keep the frequency of calling these functions to a minimum. Note that the audio_out_prepare() and audio_out_unprepare() functions are much faster than audio_out_create() and audio_out_destroy().

    • -
  • -
  • Reduce event delay and remove glitches. -
      -
    • The Audio Output API works recursively with events. The smaller the buffer size, the more often are events generated. If you use the Audio Output API with the smallest buffer and other resources (for example, a timer or sensor), the application is negatively influenced by the delay of the event. To prevent problems, set the write buffer size properly based on the other resources you need.

    • -
    • To guarantee the working events of the Audio Output API independently, an instance of the Audio Output API needs to be created and worked on the event thread.

    • -
  • -
  • Use double-buffering. -
      -
    • Use the double buffering mechanism to reduce latency. The mechanism works by first writing data twice before starting. After starting, whenever the listener (event) is called, you can write additional data.

    • -
  • -
- - - - -
- -Go to top - - - - - - + + + + + + + + + + + + + Audio I/O + + + + + +
+

Audio I/O

+ +

Audio I/O enables your application to manage various media handles.

+

The main features of the Audio I/O API include:

+ + +

Recording Uncompressed Audio

+

The Pulse Code Modulated (PCM) data contains non-compressed audio. The Audio Input API (in mobile and wearable applications) enables your application to record such data from a microphone type input device.

+

Audio data is captured periodically, so to receive the audio PCM data from the input device, you must implement the audio input interface to notify the application of audio data events, such as the end of filling audio data.

+

Before recording audio, you must define the following PCM data settings:

+
    +
  • Input device type: +
      +
    • Microphone
    • +
  • +
  • Audio channels: +
      +
    • Mono (1 channel)
    • +
    • Stereo (2 channels)
    • +
  • +
  • Audio sample type: +
      +
    • Unsigned 8-bit PCM
    • +
    • Signed 16-bit little endian PCM
    • +
  • +
  • Audio sample rate: +
      +
    • 8000 ~ 48000 Hz
    • +
  • +
+

To minimize the overhead of the audio input API, use the optimal channel type, sample type and sampling rate, which can be retrieved using the audio_in_get_channel(), audio_in_get_sample_type() and audio_in_get_sample_rate() functions, respectively.

+ + +

The following figures illustrate the general audio input states, and how the state changes when the audio input is interrupted by the system.

+

Figure: Audio input states

+

Audio input states

+

Figure: Audio input states when interrupted by system

+

Audio input states when interrupted by system

+ + +

Playing Uncompressed Audio

+

The Pulse Code Modulated (PCM) data contains non-compressed audio. The Audio Output API (in mobile and wearable applications) enables your application to play such data using output devices.

+

To play the audio PCM data, the application must call the audio_out_create() function to initialize the audio output handle.

+

Before playing audio, your application must define the following PCM data settings:

+
    +
  • Audio channels: +
      +
    • Mono (1 channel)
    • +
    • Stereo (2 channels)
    • +
  • +
  • Audio sample type: +
      +
    • Unsigned 8-bit PCM
    • +
    • Signed 16-bit little endian PCM
    • +
  • +
  • Audio sample rate: +
      +
    • 8000 ~ 48000 Hz
    • +
  • +
+ +

The following figures illustrate the general audio output states, and how the state changes when the audio output is interrupted by the system.

+

Figure: Audio output states

+

Audio output states

+

Figure: Audio output states when interrupted by system

+

Audio output states when interrupted by system

+ +

Using Audio Output

+

For supporting various low-end Tizen devices, the application must follow certain guidelines:

+
    +
  • Do not use multiple instances of the Audio Output excessively. +

    Using excessive multiple instances of the Audio Output has a negative effect on the application, because the audio data processing for re-sampling and mixing imposes a heavy burden on the system.

  • +
  • Use device-preferred PCM format. +
      + +
    • To reduce the processing overhead, use the target device-preferred PCM format (for example, use 16-bit little endian, 44.1 kHz, stereo for Wave and Wave M).

    • +
    • Using the preferred format reduces internal operations, such as converting audio samples from mono to stereo or re-sampling audio frequency to fit the target device's input sample rate.

    • +
  • +
  • Do not call the Audio Output functions too frequently. +
      +
    • The Audio Output functions require more time while repeated in the order of audio_out_create() > audio_out_prepare() > audio_out_unprepare() > audio_out_destroy(). Therefore, keep the frequency of calling these functions to a minimum. Note that the audio_out_prepare() and audio_out_unprepare() functions are much faster than audio_out_create() and audio_out_destroy().

    • +
  • +
  • Reduce event delay and remove glitches. +
      +
    • The Audio Output API works recursively with events. The smaller the buffer size, the more often are events generated. If you use the Audio Output API with the smallest buffer and other resources (for example, a timer or sensor), the application is negatively influenced by the delay of the event. To prevent problems, set the write buffer size properly based on the other resources you need.

    • +
    • To guarantee the working events of the Audio Output API independently, an instance of the Audio Output API needs to be created and worked on the event thread.

    • +
  • +
  • Use double-buffering. +
      +
    • Use the double buffering mechanism to reduce latency. The mechanism works by first writing data twice before starting. After starting, whenever the listener (event) is called, you can write additional data.

    • +
  • +
+ + + + +
+ +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/native/multimedia/camera_n.htm b/org.tizen.guides/html/native/multimedia/camera_n.htm index 65f191c..d1eff57 100644 --- a/org.tizen.guides/html/native/multimedia/camera_n.htm +++ b/org.tizen.guides/html/native/multimedia/camera_n.htm @@ -1,109 +1,109 @@ - - - - - - - - - - - - - Camera - - - - - -
-

Camera

- -

Tizen offers basic camera features, including preview and capture. It allows you to capture still images with the device's internal camera and keep images on your target device.

- -

Figure: Camera image examples

-

Camera image examples

- -

The main features of the Camera API include:

-
    -
  • Preview images in real time -
      -
    • Support for several pixel formats, such as NV12, NV12T, NV16, NV21, YUYV, UYVY, and YUV420P
    • -
    • Preview at the frame rate
    • -
    • Rotate and flip the preview
    • -
  • -
  • Capture and save images
  • -
  • Control the following camera settings: -
      -
    • Contrast
    • -
    • Exposure
    • -
    • Brightness
    • -
    • Effects
    • -
    • ISO
    • -
    • White balance
    • -
    • Zoom
    • -
    • Flash
    • -
    • Focus
    • -
    • Metering
    • -
    • EXIF tag (geo, orientation, software info and description)
    • -
    • Scene mode, HDR, theater
    • -
    • Image quality
    • -
  • -
- -

Depending on the camera device type, the device can support different orientations, resolutions, or preview and capture formats. You can obtain this information from the device using the camera_foreach_supported_preview_resolution(), camera_foreach_supported_preview_format(), or other camera_foreach_supported_xxx() functions.

- -

Since devices can have multiple camera sensors with different capabilities, create a Camera with a proper camera_device_e value, determining which camera sensor is used. Usually the primary sensor is located on the back side and the secondary sensor on the front side of the device. Once the camera sensor is selected, the selected sensor starts working.

- - - - - - - - - -
Note
Simultaneous use of multiple camera sensors is not allowed.

The target device often supports more functionalities than the Emulator.

The behavior of the shutter sound can differ according to the legislation of each country.

- -

The following figure illustrates the camera state changes in the normal mode:

-

Figure: Camera states in the normal mode

-

Camera states in the normal mode

- -

To display the camera preview, use the StartPreview() function.

- - - -
- -Go to top - - - - - - + + + + + + + + + + + + + Camera + + + + + +
+

Camera

+ +

Tizen offers basic camera features, including preview and capture. It allows you to capture still images with the device's internal camera and keep images on your target device.

+ +

Figure: Camera image examples

+

Camera image examples

+ +

The main features of the Camera API include:

+
    +
  • Preview images in real time +
      +
    • Support for several pixel formats, such as NV12, NV12T, NV16, NV21, YUYV, UYVY, and YUV420P
    • +
    • Preview at the frame rate
    • +
    • Rotate and flip the preview
    • +
  • +
  • Capture and save images
  • +
  • Control the following camera settings: +
      +
    • Contrast
    • +
    • Exposure
    • +
    • Brightness
    • +
    • Effects
    • +
    • ISO
    • +
    • White balance
    • +
    • Zoom
    • +
    • Flash
    • +
    • Focus
    • +
    • Metering
    • +
    • EXIF tag (geo, orientation, software info and description)
    • +
    • Scene mode, HDR, theater
    • +
    • Image quality
    • +
  • +
+ +

Depending on the camera device type, the device can support different orientations, resolutions, or preview and capture formats. You can obtain this information from the device using the camera_foreach_supported_preview_resolution(), camera_foreach_supported_preview_format(), or other camera_foreach_supported_xxx() functions.

+ +

Since devices can have multiple camera sensors with different capabilities, create a Camera with a proper camera_device_e value, determining which camera sensor is used. Usually the primary sensor is located on the back side and the secondary sensor on the front side of the device. Once the camera sensor is selected, the selected sensor starts working.

+ + + + + + + + + +
Note
Simultaneous use of multiple camera sensors is not allowed.

The target device often supports more functionalities than the Emulator.

The behavior of the shutter sound can differ according to the legislation of each country.

+ +

The following figure illustrates the camera state changes in the normal mode:

+

Figure: Camera states in the normal mode

+

Camera states in the normal mode

+ +

To display the camera preview, use the StartPreview() function.

+ + + +
+ +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/native/multimedia/image_util_n.htm b/org.tizen.guides/html/native/multimedia/image_util_n.htm index 481d65c..519f941 100644 --- a/org.tizen.guides/html/native/multimedia/image_util_n.htm +++ b/org.tizen.guides/html/native/multimedia/image_util_n.htm @@ -1,228 +1,228 @@ - - - - - - - - - - - - - Image Util - - - - - -
-

Image Util

- -

Tizen offers the following image processing features:

- -
    -
  • Conversion -

    You can change the colorspace format. The following tables define the supported formats.

    - - - - - - - - - - - - - - - - - - - - - - - -
    - Table: RGB pixel formats -
    LabelFOURCC in hexBits per pixelDescription
    RGB0x324247521, 4, 8, 16, 24, 32Alias for BI_RGB
    RGBA0x4142475216, 32Raw RGB with alpha. Sample precision and packing is arbitrary and determined using bit masks for each component, as for BI_BITFIELDS.
    - - - - - - - - - - - - - - - - - - - - - - - -
    - Table: Packed YUV formats -
    LabelFOURCC in hexBits per pixelDescription
    UYVY0x5956595516YUV 4:2:2 (Y sample at every pixel, U and V sampled at every second pixel horizontally on each line). A macropixel contains 2 pixels in 1 u_int32.
    YUYV0x5659555916Duplicate of YUY2.
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    - Table: Planar YUV formats -
    LabelFOURCC in hexBits per pixelDescription
    YV160x36315659168-bit Y plane followed by 8-bit 2x1 subsampled V and U planes.
    YV120x32315659128-bit Y plane followed by 8-bit 2x2 subsampled V and U planes.
    I4200x30323449128-bit Y plane followed by 8-bit 2x2 subsampled U and V planes.
    NV120x3231564E128-bit Y plane followed by an interleaved U/V plane with 2x2 subsampling.
    NV210x3132564E12As NV12 with U and V reversed in the interleaved plane.
    -
  • -
  • Resizing -

    You can change the image resolution.

  • -
  • Rotation -

    You can change the image angle around the x or y axis.

  • -
  • Crop -

    You can remove the outer parts of an image or change the aspect ratio.

- - -

You can decode and encode images with the following formats:

- -
  • Bitmap formats: -
    • YUV420, YUV422, RGB888, RGBA8888, BGRA8888, ARGB8888
  • -
  • Input image formats for decoding: -
    • Only JPEG is supported when using image util
  • -
  • Output image formats for encoding: -
    • JPEG
    • -
    • Quality vs. size - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      - Table: Quality and size comparison -
      ImageQualitySize (bytes)Compression ratioDescription
      Highest quality imageHighest quality (Q = 100)83,2612.6:1Extremely minor artifacts
      High quality imageHigh quality (Q = 50)15,13815:1Initial signs of subimage artifacts
      Medium quality imageMedium quality (Q = 25)9,55323:1Stronger artifacts; loss of high-frequency information
      Low quality imageLow quality (Q = 10)4,78746:1Severe high frequency loss; artifacts on subimage boundaries ("macroblocking") are obvious
      Lowest quality imageLowest quality
      -
- - - -
- -Go to top - - - - - - + + + + + + + + + + + + + Image Util + + + + + +
+

Image Util

+ +

Tizen offers the following image processing features:

+ +
    +
  • Conversion +

    You can change the colorspace format. The following tables define the supported formats.

    + + + + + + + + + + + + + + + + + + + + + + + +
    + Table: RGB pixel formats +
    LabelFOURCC in hexBits per pixelDescription
    RGB0x324247521, 4, 8, 16, 24, 32Alias for BI_RGB
    RGBA0x4142475216, 32Raw RGB with alpha. Sample precision and packing is arbitrary and determined using bit masks for each component, as for BI_BITFIELDS.
    + + + + + + + + + + + + + + + + + + + + + + + +
    + Table: Packed YUV formats +
    LabelFOURCC in hexBits per pixelDescription
    UYVY0x5956595516YUV 4:2:2 (Y sample at every pixel, U and V sampled at every second pixel horizontally on each line). A macropixel contains 2 pixels in 1 u_int32.
    YUYV0x5659555916Duplicate of YUY2.
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + Table: Planar YUV formats +
    LabelFOURCC in hexBits per pixelDescription
    YV160x36315659168-bit Y plane followed by 8-bit 2x1 subsampled V and U planes.
    YV120x32315659128-bit Y plane followed by 8-bit 2x2 subsampled V and U planes.
    I4200x30323449128-bit Y plane followed by 8-bit 2x2 subsampled U and V planes.
    NV120x3231564E128-bit Y plane followed by an interleaved U/V plane with 2x2 subsampling.
    NV210x3132564E12As NV12 with U and V reversed in the interleaved plane.
    +
  • +
  • Resizing +

    You can change the image resolution.

  • +
  • Rotation +

    You can change the image angle around the x or y axis.

  • +
  • Crop +

    You can remove the outer parts of an image or change the aspect ratio.

+ + +

You can decode and encode images with the following formats:

+ +
  • Bitmap formats: +
    • YUV420, YUV422, RGB888, RGBA8888, BGRA8888, ARGB8888
  • +
  • Input image formats for decoding: +
    • Only JPEG is supported when using image util
  • +
  • Output image formats for encoding: +
    • JPEG
    • +
    • Quality vs. size + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      + Table: Quality and size comparison +
      ImageQualitySize (bytes)Compression ratioDescription
      Highest quality imageHighest quality (Q = 100)83,2612.6:1Extremely minor artifacts
      High quality imageHigh quality (Q = 50)15,13815:1Initial signs of subimage artifacts
      Medium quality imageMedium quality (Q = 25)9,55323:1Stronger artifacts; loss of high-frequency information
      Low quality imageLow quality (Q = 10)4,78746:1Severe high frequency loss; artifacts on subimage boundaries ("macroblocking") are obvious
      Lowest quality imageLowest quality
      +
+ + + +
+ +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/native/multimedia/media_codecs_n.htm b/org.tizen.guides/html/native/multimedia/media_codecs_n.htm index ed8fda8..d600b8a 100644 --- a/org.tizen.guides/html/native/multimedia/media_codecs_n.htm +++ b/org.tizen.guides/html/native/multimedia/media_codecs_n.htm @@ -1,75 +1,75 @@ - - - - - - - - - - - - - Media Codec - - - - - -
-

Media Codec

- -

Media codec provides interfaces for encoding and decoding audio and video data.

- -

To use codecs:

- -
  1. Create a handle for the codec instance with the mediacodec_create() function. After a successful handle creation, your system can use the codec.

  2. - -
  3. Set the codec configuration with the mediacodec_set_codec(), and mediacodec_set_vdec_info() or mediacodec_set_venc_info() functions.

    -

    You can also prepare for the available ready state with the mediacodec_prepare() function.

  4. - -
  5. Decode and encode with the mediacodec_process_input() and mediacodec_get_output() functions.

- -

A single MediaCodec instance handles 1 specific type of data (such as aac audio or H.264 video), and can encode or decode. The codec operates on "raw" data, so strip off any file headers (such as ID3 tags).

- - -

The following figures illustrate the general media state changes.

-

Figure: Media state changes

-

Media state changes

- - - -
- -Go to top - - - - - - + + + + + + + + + + + + + Media Codec + + + + + +
+

Media Codec

+ +

Media codec provides interfaces for encoding and decoding audio and video data.

+ +

To use codecs:

+ +
  1. Create a handle for the codec instance with the mediacodec_create() function. After a successful handle creation, your system can use the codec.

  2. + +
  3. Set the codec configuration with the mediacodec_set_codec(), and mediacodec_set_vdec_info() or mediacodec_set_venc_info() functions.

    +

    You can also prepare for the available ready state with the mediacodec_prepare() function.

  4. + +
  5. Decode and encode with the mediacodec_process_input() and mediacodec_get_output() functions.

+ +

A single MediaCodec instance handles 1 specific type of data (such as aac audio or H.264 video), and can encode or decode. The codec operates on "raw" data, so strip off any file headers (such as ID3 tags).

+ + +

The following figures illustrate the general media state changes.

+

Figure: Media state changes

+

Media state changes

+ + + +
+ +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/native/multimedia/media_tools_n.htm b/org.tizen.guides/html/native/multimedia/media_tools_n.htm index 99b2046..46fae74 100644 --- a/org.tizen.guides/html/native/multimedia/media_tools_n.htm +++ b/org.tizen.guides/html/native/multimedia/media_tools_n.htm @@ -1,165 +1,165 @@ - - - - - - - - - - - - - Media Tool - - - - - -
-

Media Tool

- -

Media tool enables your application to manage various media handles.

-

The main features of the Media Tool API include:

-
    -
  • Creating the media_format_h handle to specify video or audio information.

    -

    You can set and get video or audio information using the media_format_h handle.

  • -
  • Creating the media_packet_h handle to include metadata (such as pts, dts, and duration) and allocate a buffer to the heap or TBM surface.

    -

    You can set and get the metadata using the created media_packet_h handle. Some media_packet_h metadata are NOT filled after creating the media_packet_h handle: pts, dts, duration, extradata, codec data, codec data size, and buffer flags.

    -
  • -
- - -

The media_format_h handle is created by the caller, who can set and get the video or audio information. The media_format_h handle creates the media_packet_h handle and allocates the buffer. The caller can set and get the metadata with the media_packet_h handle.

- -

The following table describes the reference count design of the media_format_h handle.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- Table: Media format handle reference count design -
FunctionReference count numberDescription
media_format_h fmt1, fmt2, tmp;
-media_packet_h pkt1, pkt2;
-media_format_create(&fmt1);
fmt1: 1Define the media_format_h and media_packet_h handles. -

Create the fmt1 handle and set the media_format_video_mime() or media_format_audio_mime() function.

media_packet_create(&pkt1, fmt1);fmt1: 2After the media_packet_create() function, you must use the media_format_unref() function, because the media_packet_create() function increases the media_format_h reference count.
media_format_unref(fmt1);fmt1: 1If the ref_count is 1, the fmt1 is currently owned by the pkt1 only.
media_packet_copy(pkt1, &pkt2);fmt1: 2Copy the pkt1 metadata to pkt2, except the allocated buffer and buffer size. pkt2 refers to fmt1, and fmt1 ref_count is increased.
media_packet_get_format(pkt1, &tmp);fmt1: 3fmt1 ref_count is increased by the media_packet_get_format() function.
media_format_set_video_mime(tmp, ...);fmt1: 3If you try to modify the fmt1 data (call the media_format_set_video_mime() function) for fmt1 (=tmp), the ref_count is bigger than 1, and fmt1 cannot be modified. -

To modify the fmt1 data, call the media_format_make_writable() function.

media_format_make_writable(tmp, &fmt2);fmt1: 2
- fmt2: 1
If called, the tmp (fmt1) ref_count is decreased. Creates the fmt2 handle and copies the fmt1 data to fmt2.
media_format_set_video_mime(fmt2, ...);fmt1: 2
- fmt2: 1
fmt2 ref_count is 1, which means that you can modify the fmt2 data.
media_packet_set_format(pkt2, fmt2);fmt1: 2 -
- fmt2: 2
Set the modified fmt2 to the pkt2 handle. You must call the media_format_unref(fmt2) function.
media_format_unref(tmp);fmt1: 1 -
- fmt2: 2
You must call this function because of the media_packet_get_format(pkt1, &tmp) function call.
media_format_unref(fmt2);fmt1: 1
- fmt2: 1
You must call this function because of the media_packet_set_format(pkt2, fmt2) function call.
media_packet_destroy(pkt1);fmt1: 1 > finalize
- fmt2: 1
If you destroy the pkt1 handle, the fmt1 ref_count is decreased. If the ref_count becomes 0, fmt1 is freed.
media_packet_destroy(pkt2);fmt1: 1 > finalize
- fmt2: 0 > finalize
If you destroy the pkt2 handle, the fmt2 ref_count is decreased. If the ref_count becomes 0, fmt2 is freed.
- - - - -
- -Go to top - - - - - - + + + + + + + + + + + + + Media Tool + + + + + +
+

Media Tool

+ +

Media tool enables your application to manage various media handles.

+

The main features of the Media Tool API include:

+
    +
  • Creating the media_format_h handle to specify video or audio information.

    +

    You can set and get video or audio information using the media_format_h handle.

  • +
  • Creating the media_packet_h handle to include metadata (such as pts, dts, and duration) and allocate a buffer to the heap or TBM surface.

    +

    You can set and get the metadata using the created media_packet_h handle. Some media_packet_h metadata are NOT filled after creating the media_packet_h handle: pts, dts, duration, extradata, codec data, codec data size, and buffer flags.

    +
  • +
+ + +

The media_format_h handle is created by the caller, who can set and get the video or audio information. The media_format_h handle creates the media_packet_h handle and allocates the buffer. The caller can set and get the metadata with the media_packet_h handle.

+ +

The following table describes the reference count design of the media_format_h handle.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Table: Media format handle reference count design +
FunctionReference count numberDescription
media_format_h fmt1, fmt2, tmp;
+media_packet_h pkt1, pkt2;
+media_format_create(&fmt1);
fmt1: 1Define the media_format_h and media_packet_h handles. +

Create the fmt1 handle and set the media_format_video_mime() or media_format_audio_mime() function.

media_packet_create(&pkt1, fmt1);fmt1: 2After the media_packet_create() function, you must use the media_format_unref() function, because the media_packet_create() function increases the media_format_h reference count.
media_format_unref(fmt1);fmt1: 1If the ref_count is 1, the fmt1 is currently owned by the pkt1 only.
media_packet_copy(pkt1, &pkt2);fmt1: 2Copy the pkt1 metadata to pkt2, except the allocated buffer and buffer size. pkt2 refers to fmt1, and fmt1 ref_count is increased.
media_packet_get_format(pkt1, &tmp);fmt1: 3fmt1 ref_count is increased by the media_packet_get_format() function.
media_format_set_video_mime(tmp, ...);fmt1: 3If you try to modify the fmt1 data (call the media_format_set_video_mime() function) for fmt1 (=tmp), the ref_count is bigger than 1, and fmt1 cannot be modified. +

To modify the fmt1 data, call the media_format_make_writable() function.

media_format_make_writable(tmp, &fmt2);fmt1: 2
+ fmt2: 1
If called, the tmp (fmt1) ref_count is decreased. Creates the fmt2 handle and copies the fmt1 data to fmt2.
media_format_set_video_mime(fmt2, ...);fmt1: 2
+ fmt2: 1
fmt2 ref_count is 1, which means that you can modify the fmt2 data.
media_packet_set_format(pkt2, fmt2);fmt1: 2 +
+ fmt2: 2
Set the modified fmt2 to the pkt2 handle. You must call the media_format_unref(fmt2) function.
media_format_unref(tmp);fmt1: 1 +
+ fmt2: 2
You must call this function because of the media_packet_get_format(pkt1, &tmp) function call.
media_format_unref(fmt2);fmt1: 1
+ fmt2: 1
You must call this function because of the media_packet_set_format(pkt2, fmt2) function call.
media_packet_destroy(pkt1);fmt1: 1 > finalize
+ fmt2: 1
If you destroy the pkt1 handle, the fmt1 ref_count is decreased. If the ref_count becomes 0, fmt1 is freed.
media_packet_destroy(pkt2);fmt1: 1 > finalize
+ fmt2: 0 > finalize
If you destroy the pkt2 handle, the fmt2 ref_count is decreased. If the ref_count becomes 0, fmt2 is freed.
+ + + + +
+ +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/native/multimedia/metadata_extractor_n.htm b/org.tizen.guides/html/native/multimedia/metadata_extractor_n.htm index b3f0469..ad6e406 100644 --- a/org.tizen.guides/html/native/multimedia/metadata_extractor_n.htm +++ b/org.tizen.guides/html/native/multimedia/metadata_extractor_n.htm @@ -1,207 +1,207 @@ - - - - - - - - - - - - - Metadata Extractor - - - - - -
- -

Metadata Extractor

-

Media files, such as mp3 and mp4 files, contain metadata. Metadata extractor enables you to extract metadata from the media files.

- -

Figure: Getting metadata

-

Getting metadata

- -

The metadata extractor can only be used with video and audio files only. It is not supported in the image files.

-

The following table lists the extractable metadata.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- Table: Metadata extractor attributes -
AttributeDescription
METADATA_DURATIONDuration of the content
METADATA_VIDEO_BITRATEBitrate of the video content
METADATA_VIDEO_FPSFPS of the video content
METADATA_VIDEO_WIDTHWidth of the video content
METADATA_VIDEO_HEIGHTHeight of the video content
METADATA_HAS_VIDEOWhether the content has video stream
METADATA_AUDIO_BITRATEBitrate of the audio content
METADATA_AUDIO_CHANNELSChannel of the audio content
METADATA_AUDIO_SAMPLERATESample rate of the audio content
METADATA_AUDIO_BITPERSAMPLEBit per sample of the audio content
METADATA_HAS_AUDIOWhether the content has audio stream
METADATA_ARTISTArtist of the content
METADATA_TITLETitle of the content
METADATA_ALBUMAlbum of the content
METADATA_ALBUM_ARTISTAlbum artist of the content
METADATA_GENREGenre of the content
METADATA_AUTHORAuthor of the content
METADATA_COPYRIGHTCopyright of the content
METADATA_DATEDate of the content
METADATA_DESCRIPTIONDescription of the content
METADATA_COMMENTComment about the content
METADATA_TRACK_NUMTrack number of the content
METADATA_CLASSIFICATIONClassification of the content
METADATA_RATINGRating of the content
METADATA_LONGITUDELongitude of the content
METADATA_LATITUDELatitude of the content
METADATA_ALTITUDEAltitude of the content
METADATA_CONDUCTORConductor of the content
METADATA_UNSYNCLYRICSAsynchronous lyrics of the content
METADATA_SYNCLYRICS_NUMSynchronous lyrics of the content
METADATA_RECDATERecorded date of the content
METADATA_ROTATEOrientation of the content
- - - - - -
- -Go to top - - - - - - + + + + + + + + + + + + + Metadata Extractor + + + + + +
+ +

Metadata Extractor

+

Media files, such as mp3 and mp4 files, contain metadata. Metadata extractor enables you to extract metadata from the media files.

+ +

Figure: Getting metadata

+

Getting metadata

+ +

The metadata extractor can only be used with video and audio files only. It is not supported in the image files.

+

The following table lists the extractable metadata.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Table: Metadata extractor attributes +
AttributeDescription
METADATA_DURATIONDuration of the content
METADATA_VIDEO_BITRATEBitrate of the video content
METADATA_VIDEO_FPSFPS of the video content
METADATA_VIDEO_WIDTHWidth of the video content
METADATA_VIDEO_HEIGHTHeight of the video content
METADATA_HAS_VIDEOWhether the content has video stream
METADATA_AUDIO_BITRATEBitrate of the audio content
METADATA_AUDIO_CHANNELSChannel of the audio content
METADATA_AUDIO_SAMPLERATESample rate of the audio content
METADATA_AUDIO_BITPERSAMPLEBit per sample of the audio content
METADATA_HAS_AUDIOWhether the content has audio stream
METADATA_ARTISTArtist of the content
METADATA_TITLETitle of the content
METADATA_ALBUMAlbum of the content
METADATA_ALBUM_ARTISTAlbum artist of the content
METADATA_GENREGenre of the content
METADATA_AUTHORAuthor of the content
METADATA_COPYRIGHTCopyright of the content
METADATA_DATEDate of the content
METADATA_DESCRIPTIONDescription of the content
METADATA_COMMENTComment about the content
METADATA_TRACK_NUMTrack number of the content
METADATA_CLASSIFICATIONClassification of the content
METADATA_RATINGRating of the content
METADATA_LONGITUDELongitude of the content
METADATA_LATITUDELatitude of the content
METADATA_ALTITUDEAltitude of the content
METADATA_CONDUCTORConductor of the content
METADATA_UNSYNCLYRICSAsynchronous lyrics of the content
METADATA_SYNCLYRICS_NUMSynchronous lyrics of the content
METADATA_RECDATERecorded date of the content
METADATA_ROTATEOrientation of the content
+ + + + + +
+ +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/native/multimedia/multimedia_guide_n.htm b/org.tizen.guides/html/native/multimedia/multimedia_guide_n.htm index 5a8c0b4..c7d342a 100644 --- a/org.tizen.guides/html/native/multimedia/multimedia_guide_n.htm +++ b/org.tizen.guides/html/native/multimedia/multimedia_guide_n.htm @@ -1,99 +1,99 @@ - - - - - - - - - - - - - Multimedia - - - - -
-

Multimedia

-

Multimedia features capture and play or display still images, video, and sounds.

-

The main multimedia features are:

-
    -
  • Audio I/O -

    Enables you to record and play uncompressed PCM audio data.

  • -
  • Camera -

    Enables you to launch the camera and control or adjust camera sensors of the device to preview or capture still images.

  • -
  • Image Util -

    Enables you to view and process (decode, encode, convert, and compress) bitmap images in the JPEG format.

  • -
  • Media Codec -

    Enables you to use codecs to encode and decode video and audio data.

  • -
  • Media Controller -

    Enables you to communicate between the media controller server and the media controller client.

  • Media Tool -

    Enables you to use media tools to manage various media handles.

  • -
  • Media Vision -

    Enables you to use create and read barcodes.

  • -
  • Metadata Editor -

    Enables you to edit the metadata of several popular audio formats.

  • -
  • Metadata Extractor

    Enables you to extract metadata from the media files.

  • -
  • Player -

    Enables you to play audio and manage the state of the media player.

  • -
  • Radio -

    Enables you to control the radio hardware on your system.

  • -
  • Recorder -

    Enables you to record audio data to a file with compressed or uncompressed format and generate compressed video files with video data from camera and audio data from audio input device.

  • -
  • Thumbnail Util -

    Enables you to create a thumbnail from an input media file.

  • -
  • Tone Player -

    Enables you to play tones.

  • -
  • WAV Player -

    Enables you to play WAV files.

  • -
  • Sound Manager -

    Enables you to control the audio behavior of your application.

  • -
  • Screen Mirroring Sink -

    Enables you to mirror the device screen and sound to another device wirelessly.

  • -
- -

The following guides apply in mobile applications only:

-
    -
  • Video Util -

    Enables you to use video transcoding features, such as multi-format codec and output format.

  • -
- - - - -
- -Go to top - - - - - - + + + + + + + + + + + + + Multimedia + + + + +
+

Multimedia

+

Multimedia features capture and play or display still images, video, and sounds.

+

The main multimedia features are:

+
    +
  • Audio I/O +

    Enables you to record and play uncompressed PCM audio data.

  • +
  • Camera +

    Enables you to launch the camera and control or adjust camera sensors of the device to preview or capture still images.

  • +
  • Image Util +

    Enables you to view and process (decode, encode, convert, and compress) bitmap images in the JPEG format.

  • +
  • Media Codec +

    Enables you to use codecs to encode and decode video and audio data.

  • +
  • Media Controller +

    Enables you to communicate between the media controller server and the media controller client.

  • Media Tool +

    Enables you to use media tools to manage various media handles.

  • +
  • Media Vision +

    Enables you to use create and read barcodes.

  • +
  • Metadata Editor +

    Enables you to edit the metadata of several popular audio formats.

  • +
  • Metadata Extractor

    Enables you to extract metadata from the media files.

  • +
  • Player +

    Enables you to play audio and manage the state of the media player.

  • +
  • Radio +

    Enables you to control the radio hardware on your system.

  • +
  • Recorder +

    Enables you to record audio data to a file with compressed or uncompressed format and generate compressed video files with video data from camera and audio data from audio input device.

  • +
  • Thumbnail Util +

    Enables you to create a thumbnail from an input media file.

  • +
  • Tone Player +

    Enables you to play tones.

  • +
  • WAV Player +

    Enables you to play WAV files.

  • +
  • Sound Manager +

    Enables you to control the audio behavior of your application.

  • +
+ +

The following guides apply in mobile applications only:

+
    +
  • Screen Mirroring Sink +

    Enables you to mirror the device screen and sound to another device wirelessly.

  • +
  • Video Util +

    Enables you to use video transcoding features, such as multi-format codec and output format.

  • +
+ + + + +
+ +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/native/multimedia/player_n.htm b/org.tizen.guides/html/native/multimedia/player_n.htm index 97a8858..b1dbac0 100644 --- a/org.tizen.guides/html/native/multimedia/player_n.htm +++ b/org.tizen.guides/html/native/multimedia/player_n.htm @@ -1,191 +1,191 @@ - - - - - - - - - - - - - Player - - - - -
-

Player

-

You can play audio, video, and tones in your application.

-

The main player features are:

- - -

The Player API (in mobile and wearable applications) enables your application to play video and sound. It supports 3 content formats: file, network stream, and memory. It also provides the following features:

- -
  • Operating general controls for the audio or video content, such as play, pause, resume, and stop
  • -
  • Moving the audio or video content based on time
  • -
  • Controlling the volume of the audio or video content based on each instance
  • -
  • Looping the audio or video content
  • -
  • Getting information of the audio or video content
  • -
  • Playing multiple audio streams
- -

The maximum count of a player instance is limited by the system and multimedia resources. The maximum count is a system-wide count and it can be applied depending on the CPU model, CPU speed, CPU core number, CPU load from other applications, and the available memory. Thus, the exact count can be smaller than the maximum count, in which case the prepare functions fail. A reasonable working player count is under 10.

-

The player works based on the audio session manager policy. This means that an application can be interrupted by another application if a resource is in conflict or it has an audio policy rule to follow. You can change the session's property directly by using the Sound Manager API (in mobile and wearable applications).

-

The callback interface specifies the functions used to notify the player status during playback events. Since the player engine works asynchronously, you must implement this listener to ensure that the player flows correctly. When each player operation is completed, an event is generated, and the player_completed_cb() function is called. If an error occurs in the player engine, you are notified if you have registered the player_error_cb() callback.

-

If the player state is changed to ready, the multimedia resource is available and you can get content information of the media. You can also get content information in a playing state in some cases of playback streaming.

- - -

Handling Audio

-

Tizen enables your application to play audio and provides controlling functions for using audio resources. The resources can be media files stored on the device or they can be streamed from a streaming server (defined with a URI) through the network.

- -

The audio formats your application can use include MP3, AAC, WMA, M4A, 3GA, WAV, and AMR. The available formats depend on the target device.

- - -

The player_interrupted_cb() function is called when an application is interrupted by another application. The player is paused or moved to an idle state according to the audio policy. You must check the state of the current instance and take appropriate action. If the player is changed to a paused state due to an interruption, the PLAYER_INTERRUPTED_COMPLETED can be called at the end of the interruption. For example, if the application is interrupted by a call, alarm, or notification, the completed message is posted. However, no messages are posted if the interruption has other causes. Make sure you handle the application accordingly when audio switching occurs between various applications.

- -

Multiple instances of the player can be used to play several audio data streams concurrently. This means that your application can play multiple uncompressed audio files at the same time.

- -

The following figure illustrates the general player state changes:

-

Figure: Player state changes

-

Player state changes

-

The following figure illustrates what happens when the player gets interrupted by the system:

-

Figure: Player states when interrupted by system

-

Player states when interrupted by system

- -

Handling Video

-

Tizen enables your application to play video, and it uses its own user surface. The surface requires a drawing area, so you have to get an overlay region and set it to the player instance to display the drawing area:

-
    -
  1. Get the overlay region or Evas from the Graphics module. -

    You can display video on a UI layer with the Evas object as well as on an overlay layer.

  2. -
  3. Create the player instance.
  4. -
  5. Set the surface type and display a handle to the player using the player_set_display() function.
  6. -
-

The video formats your application can use include:

-
    -
  • WMV, ASF, MP4, 3GP, AVI, MKV, OGG -

    The available formats depend on the target device.

  • -
- -

In case of a video interruption, the state can be READY due to the resource restriction in the system.

- -

The following figure illustrates what happens when the player gets interrupted by the system.

-

Figure: Player states when interrupted by system

-

Player states when interrupted by system

-

Features

-The main features of the Player API include: -
    -
  • Player -

    Use the Player API to control audio and video stream.

    -

    After changing to the READY state, properties such as volume, sound type, latency mode, mute mode, and looping mode can be adjusted.

    -

    To learn about these features, see the Player Tutorial.

    -
  • -
  • Display -

    Use the Display API to play video stream.

    -

    After changing to the IDLE state, create the display handle and set the display type.

    -

    To learn about these features, see the Setting Display Parameters.

    -
  • -
  • Stream Info -

    Use the Stream Info API to play video stream.

    -

    After changing to the READY state, you can retrieve stream information.

    -

    To learn about these features, see the Getting Stream Information.

    -
  • - -
  • Audio Effect -

    Use the Audio Effect API to set and get the audio effect.

    -

    After changing to the IDLE state, you can adjust the audio effect.

    -
  • -
  • Subtitle -

    Use the Subtitle API to read the subtitle track.

    -

    After changing to the READY state, the subtitle can be read.

    -

    To learn about these features, see the Inserting Subtitles.

    -
  • -
- -

Streaming Playback

-

You can set specific URLs for streaming media playback by using the player_set_uri() function.

-

Both Hypertext Transfer Protocol (HTTP) and Real Time Streaming Protocol (RTSP) protocols support streaming media playback. The HTTP request header supports the playback of both complete and download-in-progress media files. The index table (atoms) must be moved in front of the file for progressive download.

- -

In case of HTTP streaming, buffering can happen when the player is prepared. You can get the status using the player_set_buffering_cb() function.

- -

Streaming Protocol Features

-

The following table lists the streaming protocol features supported by the player.

- - - - - - - - - - - - - - - - - - - - - - - -
- Table: Supported streaming protocol features -
Streaming protocolSupported feature
Hypertext Transfer Protocol (HTTP)HTTP Streaming
HTTP Live Streaming
HTTP Progressive Download Play
Real Time Streaming Protocol (RTSP)RTSP Streaming
- - - -
- -Go to top - - - - - - + + + + + + + + + + + + + Player + + + + +
+

Player

+

You can play audio, video, and tones in your application.

+

The main player features are:

+ + +

The Player API (in mobile and wearable applications) enables your application to play video and sound. It supports 3 content formats: file, network stream, and memory. It also provides the following features:

+ +
  • Operating general controls for the audio or video content, such as play, pause, resume, and stop
  • +
  • Moving the audio or video content based on time
  • +
  • Controlling the volume of the audio or video content based on each instance
  • +
  • Looping the audio or video content
  • +
  • Getting information of the audio or video content
  • +
  • Playing multiple audio streams
+ +

The maximum count of a player instance is limited by the system and multimedia resources. The maximum count is a system-wide count and it can be applied depending on the CPU model, CPU speed, CPU core number, CPU load from other applications, and the available memory. Thus, the exact count can be smaller than the maximum count, in which case the prepare functions fail. A reasonable working player count is under 10.

+

The player works based on the audio session manager policy. This means that an application can be interrupted by another application if a resource is in conflict or it has an audio policy rule to follow. You can change the session's property directly by using the Sound Manager API (in mobile and wearable applications).

+

The callback interface specifies the functions used to notify the player status during playback events. Since the player engine works asynchronously, you must implement this listener to ensure that the player flows correctly. When each player operation is completed, an event is generated, and the player_completed_cb() function is called. If an error occurs in the player engine, you are notified if you have registered the player_error_cb() callback.

+

If the player state is changed to ready, the multimedia resource is available and you can get content information of the media. You can also get content information in a playing state in some cases of playback streaming.

+ + +

Handling Audio

+

Tizen enables your application to play audio and provides controlling functions for using audio resources. The resources can be media files stored on the device or they can be streamed from a streaming server (defined with a URI) through the network.

+ +

The audio formats your application can use include MP3, AAC, WMA, M4A, 3GA, WAV, and AMR. The available formats depend on the target device.

+ + +

The player_interrupted_cb() function is called when an application is interrupted by another application. The player is paused or moved to an idle state according to the audio policy. You must check the state of the current instance and take appropriate action. If the player is changed to a paused state due to an interruption, the PLAYER_INTERRUPTED_COMPLETED can be called at the end of the interruption. For example, if the application is interrupted by a call, alarm, or notification, the completed message is posted. However, no messages are posted if the interruption has other causes. Make sure you handle the application accordingly when audio switching occurs between various applications.

+ +

Multiple instances of the player can be used to play several audio data streams concurrently. This means that your application can play multiple uncompressed audio files at the same time.

+ +

The following figure illustrates the general player state changes:

+

Figure: Player state changes

+

Player state changes

+

The following figure illustrates what happens when the player gets interrupted by the system:

+

Figure: Player states when interrupted by system

+

Player states when interrupted by system

+ +

Handling Video

+

Tizen enables your application to play video, and it uses its own user surface. The surface requires a drawing area, so you have to get an overlay region and set it to the player instance to display the drawing area:

+
    +
  1. Get the overlay region or Evas from the Graphics module. +

    You can display video on a UI layer with the Evas object as well as on an overlay layer.

  2. +
  3. Create the player instance.
  4. +
  5. Set the surface type and display a handle to the player using the player_set_display() function.
  6. +
+

The video formats your application can use include:

+
    +
  • WMV, ASF, MP4, 3GP, AVI, MKV, OGG +

    The available formats depend on the target device.

  • +
+ +

In case of a video interruption, the state can be READY due to the resource restriction in the system.

+ +

The following figure illustrates what happens when the player gets interrupted by the system.

+

Figure: Player states when interrupted by system

+

Player states when interrupted by system

+

Features

+The main features of the Player API include: +
    +
  • Player +

    Use the Player API to control audio and video stream.

    +

    After changing to the READY state, properties such as volume, sound type, latency mode, mute mode, and looping mode can be adjusted.

    +

    To learn about these features, see the Player Tutorial.

    +
  • +
  • Display +

    Use the Display API to play video stream.

    +

    After changing to the IDLE state, create the display handle and set the display type.

    +

    To learn about these features, see the Setting Display Parameters.

    +
  • +
  • Stream Info +

    Use the Stream Info API to play video stream.

    +

    After changing to the READY state, you can retrieve stream information.

    +

    To learn about these features, see the Getting Stream Information.

    +
  • + +
  • Audio Effect +

    Use the Audio Effect API to set and get the audio effect.

    +

    After changing to the IDLE state, you can adjust the audio effect.

    +
  • +
  • Subtitle +

    Use the Subtitle API to read the subtitle track.

    +

    After changing to the READY state, the subtitle can be read.

    +

    To learn about these features, see the Inserting Subtitles.

    +
  • +
+ +

Streaming Playback

+

You can set specific URLs for streaming media playback by using the player_set_uri() function.

+

Both Hypertext Transfer Protocol (HTTP) and Real Time Streaming Protocol (RTSP) protocols support streaming media playback. The HTTP request header supports the playback of both complete and download-in-progress media files. The index table (atoms) must be moved in front of the file for progressive download.

+ +

In case of HTTP streaming, buffering can happen when the player is prepared. You can get the status using the player_set_buffering_cb() function.

+ +

Streaming Protocol Features

+

The following table lists the streaming protocol features supported by the player.

+ + + + + + + + + + + + + + + + + + + + + + + +
+ Table: Supported streaming protocol features +
Streaming protocolSupported feature
Hypertext Transfer Protocol (HTTP)HTTP Streaming
HTTP Live Streaming
HTTP Progressive Download Play
Real Time Streaming Protocol (RTSP)RTSP Streaming
+ + + +
+ +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/native/multimedia/radio_n.htm b/org.tizen.guides/html/native/multimedia/radio_n.htm index 3add0fb..7319310 100644 --- a/org.tizen.guides/html/native/multimedia/radio_n.htm +++ b/org.tizen.guides/html/native/multimedia/radio_n.htm @@ -1,76 +1,76 @@ - - - - - - - - - - - - - Radio - - - - - -
-

Radio

- -

Tizen provides functions for controlling radio hardware on your system.

- -

The main features of the Radio API include:

- -
    -
  • Switching the radio on and off
  • -
  • Seeking radio frequency
  • -
  • Scanning radio signals
  • -
  • Setting the state of the radio
  • -
- -

A handle for radio instance is created using the radio_create() function. A successful creation of the handle requires a radio tuner. You can switch the radio on and off using the radio_start() and radio_stop() functions. Select the radio frequency using the radio_set_frequency() function or radio_seek_up() and radio_seek_down() functions.

- -

The Radio API allows only one instance at the time. Radio playback can be interrupted by another radio application.

- -

The following figure illustrates the general radio state changes.

- -

Figure: Radio state changes

-

Radio state changes

- - -
- -Go to top - - - - - - + + + + + + + + + + + + + Radio + + + + + +
+

Radio

+ +

Tizen provides functions for controlling radio hardware on your system.

+ +

The main features of the Radio API include:

+ +
    +
  • Switching the radio on and off
  • +
  • Seeking radio frequency
  • +
  • Scanning radio signals
  • +
  • Setting the state of the radio
  • +
+ +

A handle for radio instance is created using the radio_create() function. A successful creation of the handle requires a radio tuner. You can switch the radio on and off using the radio_start() and radio_stop() functions. Select the radio frequency using the radio_set_frequency() function or radio_seek_up() and radio_seek_down() functions.

+ +

The Radio API allows only one instance at the time. Radio playback can be interrupted by another radio application.

+ +

The following figure illustrates the general radio state changes.

+ +

Figure: Radio state changes

+

Radio state changes

+ + +
+ +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/native/multimedia/recorder_n.htm b/org.tizen.guides/html/native/multimedia/recorder_n.htm index 4f9a14a..b3e54b7 100644 --- a/org.tizen.guides/html/native/multimedia/recorder_n.htm +++ b/org.tizen.guides/html/native/multimedia/recorder_n.htm @@ -1,94 +1,94 @@ - - - - - - - - - - - - - Recorder - - - - - -
-

Recorder

- -

Tizen offers basic recorder features, including an audio and video recorder.

- -

The main features of the Recorder API include:

-
    -
  • Basic recording functionalities (record, stop, pause, cancel, and mute). -
  • -
  • Setting the maximum recording time and size
  • -
  • Controlling the system volume level
  • -
- -

The following file formats are supported:

-
    -
  • Video: mp4 and 3gp
  • -
  • Audio: m4a and amr
  • -
-

Valid input sources consist of internal and external microphones and a camera. The used input audio or video source depends on the currently connected audio path and camera module of the device. The operations of the Recorder APIs can work in asynchronous mode, which means that callbacks are required to pass an event notification to the application. The recorder APIs in the video recorder serve as the interface with the hardware. Input is processed through that handle.

- -

During testing, you can use the Emulator to imitate audio or video recording, as long as your computer has a proper input source device.

- -

The following figure illustrates the general recorder state changes.

-

Figure: Recorder states

-

Recorder states

- - - - - - - - - - -
Note
While running applications on the Emulator, audio-video synchronization errors can occur due to the computer performance.
- - - -
- -Go to top - - - - - - + + + + + + + + + + + + + Recorder + + + + + +
+

Recorder

+ +

Tizen offers basic recorder features, including an audio and video recorder.

+ +

The main features of the Recorder API include:

+
    +
  • Basic recording functionalities (record, stop, pause, cancel, and mute). +
  • +
  • Setting the maximum recording time and size
  • +
  • Controlling the system volume level
  • +
+ +

The following file formats are supported:

+
    +
  • Video: mp4 and 3gp
  • +
  • Audio: m4a and amr
  • +
+

Valid input sources consist of internal and external microphones and a camera. The used input audio or video source depends on the currently connected audio path and camera module of the device. The operations of the Recorder APIs can work in asynchronous mode, which means that callbacks are required to pass an event notification to the application. The recorder APIs in the video recorder serve as the interface with the hardware. Input is processed through that handle.

+ +

During testing, you can use the Emulator to imitate audio or video recording, as long as your computer has a proper input source device.

+ +

The following figure illustrates the general recorder state changes.

+

Figure: Recorder states

+

Recorder states

+ + + + + + + + + + +
Note
While running applications on the Emulator, audio-video synchronization errors can occur due to the computer performance.
+ + + +
+ +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/native/multimedia/screen_mirroring_n.htm b/org.tizen.guides/html/native/multimedia/screen_mirroring_n.htm old mode 100755 new mode 100644 index 2cb4135..d8deaad --- a/org.tizen.guides/html/native/multimedia/screen_mirroring_n.htm +++ b/org.tizen.guides/html/native/multimedia/screen_mirroring_n.htm @@ -16,7 +16,7 @@ @@ -33,6 +32,18 @@

Screen Mirroring Sink

You can mirror the device screen and sound to another device wirelessly using the screen mirroring feature. It follows the Wi-Fi Display Technical Specification and supports the feature as a sink, which receives shared data from a source device that supports the Wi-Fi Display, and displays it.

+ + + + + + + + + + +
Note
This feature is supported in mobile applications only.
+

The main features of the Screen Mirroring Sink API include:

  • Managing the connection to the screen mirroring source diff --git a/org.tizen.guides/html/native/multimedia/sound_manager_n.htm b/org.tizen.guides/html/native/multimedia/sound_manager_n.htm index 8ce710a..3bee14b 100644 --- a/org.tizen.guides/html/native/multimedia/sound_manager_n.htm +++ b/org.tizen.guides/html/native/multimedia/sound_manager_n.htm @@ -1,121 +1,121 @@ - - - - - - - - - - - - - Sound Manager - - - - - -
    -

    Sound Manager

    - -

    The sound manager allows you to control the audio behavior of your application.

    - -

    The main features of the Sound Manager API include:

    - -
      -
    • Volume control -

      Control the output volume by managing the sound type and its volume level.

    • - -
    • Sound session types -

      Set the sound session type, which specifies the behavior of your application sound across the system.

    • - -
    • Sound device query -

      Using the query functions, you can get various information, such as the state of the sound devices.

    • -
    - -

    Volume Control

    - -

    You can manage the volume level of a particular sound type. With the Sound Manager API, you can set and get a volume level and a maximum volume level of a particular sound type.

    - -

    Normally, if there is an active output stream, the sound_manager_get_current_sound_type() function returns the sound type of that stream, and if not, it returns an error message. However, you can set a particular sound type as current using the sound_manager_set_current_sound_type() function. This enables other applications, such as a volume application, to manage the volume level of the particular sound type even though it is not currently playing.

    - - - - - - - - - - -
    Note
    Setting the current sound type affects the entire system. When no longer needed, unset the current sound type using the sound_manager_unset_current_sound_type() function.
    - -

    Sound Session Types

    - -

    The Sound Manager API offers 5 different sound session types: media, alarm, notification, emergency and VOIP. According to these types, your application's audio works in a specific way to mix with sounds of other applications or to respond to an audio interruption made by another application.

    - -

    The alarm, notification, emergency, and VOIP sessions are prioritized over the media session. For example, when an alarm is activated while you are playing a media file, the system pauses the media session, and the alarm session gets the permission to play its sound.

    - -

    You can set options for how to start a new media session or respond to an audio interruption during an active media session using the sound_session_option_for_start_e (in mobile and wearable applications) and sound_session_option_for_during_play_e (in mobile and wearable applications) enumerators. A media session is not able to interrupt or block the other types of sound sessions, no matter what options you have set.

    - -

    You can also set options for resuming the media session when the interruption ends by using the sound_session_option_for_resumption_e enumerator (in mobile and wearable applications). The sound system notifies the media session when the interruption ends, and you are able to resume your session.

    - -

    Sound Device Query

    -

    The audio behavior of your application must differ in accordance with the various sound devices that are connected.

    - -

    Use the sound_manager_get_current_device_list() function to get the list handle of the currently connected sound devices. With the sequential search of this device list, you can get the device handle of each device on the list. You can use the sound_manager_get_next_device() and sound_manager_get_prev_device() functions for a sequential search of the device list.

    - -

    With the device handle, you can query the sound device information with the following functions:

    -
    • sound_manger_get_device_type(): To get the device type.
    • -
    • sound_manager_get_device_io_direction(): To get the device IO direction.
    • -
    • sound_manager_get_device_id(): To get the device ID.
    • -
    • sound_manager_get_device_name(): To get the device name.
    • -
    • sound_manager_get_device_state(): To get the device state.
    - -

    To get a notification when the sound device connection or information has changed, register the sound_manager_set_device_connected_cb() and sound_manager_set_device_information_changed_cb() callbacks. The initial state of the connected sound device is deactivated.

    - -

    When getting a sound device list or setting callbacks, use the sound_device_mask_e enumerator (in mobile and wearable applications) to specify the sound devices that you want. With a combination of the masks, you can to narrow down the sound devices to those you actually need.

    - - - -
    - -Go to top - - - - - - + + + + + + + + + + + + + Sound Manager + + + + + +
    +

    Sound Manager

    + +

    The sound manager allows you to control the audio behavior of your application.

    + +

    The main features of the Sound Manager API include:

    + +
      +
    • Volume control +

      Control the output volume by managing the sound type and its volume level.

    • + +
    • Sound session types +

      Set the sound session type, which specifies the behavior of your application sound across the system.

    • + +
    • Sound device query +

      Using the query functions, you can get various information, such as the state of the sound devices.

    • +
    + +

    Volume Control

    + +

    You can manage the volume level of a particular sound type. With the Sound Manager API, you can set and get a volume level and a maximum volume level of a particular sound type.

    + +

    Normally, if there is an active output stream, the sound_manager_get_current_sound_type() function returns the sound type of that stream, and if not, it returns an error message. However, you can set a particular sound type as current using the sound_manager_set_current_sound_type() function. This enables other applications, such as a volume application, to manage the volume level of the particular sound type even though it is not currently playing.

    + + + + + + + + + + +
    Note
    Setting the current sound type affects the entire system. When no longer needed, unset the current sound type using the sound_manager_unset_current_sound_type() function.
    + +

    Sound Session Types

    + +

    The Sound Manager API offers 5 different sound session types: media, alarm, notification, emergency and VOIP. According to these types, your application's audio works in a specific way to mix with sounds of other applications or to respond to an audio interruption made by another application.

    + +

    The alarm, notification, emergency, and VOIP sessions are prioritized over the media session. For example, when an alarm is activated while you are playing a media file, the system pauses the media session, and the alarm session gets the permission to play its sound.

    + +

    You can set options for how to start a new media session or respond to an audio interruption during an active media session using the sound_session_option_for_start_e (in mobile and wearable applications) and sound_session_option_for_during_play_e (in mobile and wearable applications) enumerators. A media session is not able to interrupt or block the other types of sound sessions, no matter what options you have set.

    + +

    You can also set options for resuming the media session when the interruption ends by using the sound_session_option_for_resumption_e enumerator (in mobile and wearable applications). The sound system notifies the media session when the interruption ends, and you are able to resume your session.

    + +

    Sound Device Query

    +

    The audio behavior of your application must differ in accordance with the various sound devices that are connected.

    + +

    Use the sound_manager_get_current_device_list() function to get the list handle of the currently connected sound devices. With the sequential search of this device list, you can get the device handle of each device on the list. You can use the sound_manager_get_next_device() and sound_manager_get_prev_device() functions for a sequential search of the device list.

    + +

    With the device handle, you can query the sound device information with the following functions:

    +
    • sound_manger_get_device_type(): To get the device type.
    • +
    • sound_manager_get_device_io_direction(): To get the device IO direction.
    • +
    • sound_manager_get_device_id(): To get the device ID.
    • +
    • sound_manager_get_device_name(): To get the device name.
    • +
    • sound_manager_get_device_state(): To get the device state.
    + +

    To get a notification when the sound device connection or information has changed, register the sound_manager_set_device_connected_cb() and sound_manager_set_device_information_changed_cb() callbacks. The initial state of the connected sound device is deactivated.

    + +

    When getting a sound device list or setting callbacks, use the sound_device_mask_e enumerator (in mobile and wearable applications) to specify the sound devices that you want. With a combination of the masks, you can to narrow down the sound devices to those you actually need.

    + + + +
    + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/native/multimedia/tone_player_n.htm b/org.tizen.guides/html/native/multimedia/tone_player_n.htm index 4576ef1..86089ab 100644 --- a/org.tizen.guides/html/native/multimedia/tone_player_n.htm +++ b/org.tizen.guides/html/native/multimedia/tone_player_n.htm @@ -1,69 +1,69 @@ - - - - - - - - - - - - - Tone Player - - - - - -
    -

    Tone Player

    - -

    Tizen enables your application to play a tone or a list of tones.

    -

    You can generate tones in 2 ways:

    -
      -
    • Specify the frequency values. You can specify either 1 or 2 frequencies.

    • -
    • Use a DTMF (Dual Tone Multi Frequency) preset frequency value of the tone_type_e.

    • -
    - -

    The following figures illustrate the general tone player states, and how the state changes when your application calls the Tone player API.

    -

    Figure: Tone player states

    -

    Tone player states

    - - - - -
    - -Go to top - - - - - - + + + + + + + + + + + + + Tone Player + + + + + +
    +

    Tone Player

    + +

    Tizen enables your application to play a tone or a list of tones.

    +

    You can generate tones in 2 ways:

    +
      +
    • Specify the frequency values. You can specify either 1 or 2 frequencies.

    • +
    • Use a DTMF (Dual Tone Multi Frequency) preset frequency value of the tone_type_e.

    • +
    + +

    The following figures illustrate the general tone player states, and how the state changes when your application calls the Tone player API.

    +

    Figure: Tone player states

    +

    Tone player states

    + + + + +
    + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/native/multimedia/video_util_n.htm b/org.tizen.guides/html/native/multimedia/video_util_n.htm index bb09088..51f91dd 100644 --- a/org.tizen.guides/html/native/multimedia/video_util_n.htm +++ b/org.tizen.guides/html/native/multimedia/video_util_n.htm @@ -1,171 +1,171 @@ - - - - - - - - - - - - - Video Util - - - -
    -
    -

    Mobile native

    -
    - - -
    - -
    -

    Video Util

    - -

    Tizen offers the following video transcoding features:

    - -
    • Make container and codec type changes -

      Content compatibility is supported between same devices.

    • -
    • Make scale and frame rate changes -

      Since video file size and format changes are possible, there is attachment flexibility for email, MMS, and SMS messaging. You can also extract a thumbnail from certain video chapters, and chapter previews are available.

    • -
    • Trim -

      A trim chapter is available in the video editor.

    - - - - - - - - - - -
    Note
    This feature is supported in mobile applications only.
    - -

    The following figure shows the result of the video file size change (due to scaling and container and codec format change).

    - -

    Figure: Transcoder

    -

    Transcoder

    - - -

    The following table lists the supported audio and video codecs (decoder).

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Table: Decoders
    Audio codecVideo codec
    AAC LCMPEG-1
    AAC+MPEG-4 part 2
    Enhanced AAC+H.263
    MP3H.264
    WMA7 / 8VC-1 (WMV9)
    WAVOn2 VP3
    VorbisTheora
    AMR-NB
    AMR-WB
    - -

    The following table lists the supported audio and video codecs (encoder).

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Table: Encoders
    Audio codecVideo codec
    AAC LCMPEG-1
    VorbisMPEG-4 part 2
    AMR-NBH.263
    H.264
    VC-1 (WMV9)
    On2 VP3
    Theora
    - - - - -
    - -Go to top - - - - - - + + + + + + + + + + + + + Video Util + + + +
    +
    +

    Mobile native

    +
    + + +
    + +
    +

    Video Util

    + +

    Tizen offers the following video transcoding features:

    + +
    • Make container and codec type changes +

      Content compatibility is supported between same devices.

    • +
    • Make scale and frame rate changes +

      Since video file size and format changes are possible, there is attachment flexibility for email, MMS, and SMS messaging. You can also extract a thumbnail from certain video chapters, and chapter previews are available.

    • +
    • Trim +

      A trim chapter is available in the video editor.

    + + + + + + + + + + +
    Note
    This feature is supported in mobile applications only.
    + +

    The following figure shows the result of the video file size change (due to scaling and container and codec format change).

    + +

    Figure: Transcoder

    +

    Transcoder

    + + +

    The following table lists the supported audio and video codecs (decoder).

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Table: Decoders
    Audio codecVideo codec
    AAC LCMPEG-1
    AAC+MPEG-4 part 2
    Enhanced AAC+H.263
    MP3H.264
    WMA7 / 8VC-1 (WMV9)
    WAVOn2 VP3
    VorbisTheora
    AMR-NB
    AMR-WB
    + +

    The following table lists the supported audio and video codecs (encoder).

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Table: Encoders
    Audio codecVideo codec
    AAC LCMPEG-1
    VorbisMPEG-4 part 2
    AMR-NBH.263
    H.264
    VC-1 (WMV9)
    On2 VP3
    Theora
    + + + + +
    + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/native/multimedia/wav_player_n.htm b/org.tizen.guides/html/native/multimedia/wav_player_n.htm index dcf5875..bff16d6 100644 --- a/org.tizen.guides/html/native/multimedia/wav_player_n.htm +++ b/org.tizen.guides/html/native/multimedia/wav_player_n.htm @@ -1,85 +1,85 @@ - - - - - - - - - - - - - WAV Player - - - - - -
    -

    WAV Player

    - -

    Tizen enables your application to play audio in 1 of 2 ways:

    -
      -
    • Audio player AppControl

      When using the audio application control, the device standard media player application is launched to play audio.

    • -
    • wav player header

      When using the wav player header, your application uses its own user interface.

    • -
    -

    The WAV Player API provides controlling functions for using audio resources. The resources can be a media file stored in the device.

    -

    Use the WAV Player API to enable your application to play audio and control playback. The audio features of this API include:

    -
      -
    • Playing audio media from local files
    • -
    • Controlling playback using play and stop
    • -
    - -

    The audio formats your application can use with the WAV Player API include:

    -
      -
    • WAV, OGG
    • -
    -

    Most operations of the WAV Player API work in synchronous mode The WAV Player API requires a callback to notify the application of the operational status of the player. The callback must be implemented and passed to stop the WAV playback.

    -

    Multiple instances of the wav player can be used to play several audio data streams concurrently. This means that your application can play multiple uncompressed audio files, such as WAV, at the same time.

    -

    The most common audio uses of the WAV Player API include:

    -
      -
    • Playing an audio file and controlling the playback
    • -
    • Handling player controls
    • -
    - -

    The following figure illustrates the general WAV player state changes.

    -

    Figure: WAV player state changes

    -

    WAV player state changes

    - - - -
    - -Go to top - - - - - - + + + + + + + + + + + + + WAV Player + + + + + +
    +

    WAV Player

    + +

    Tizen enables your application to play audio in 1 of 2 ways:

    +
      +
    • Audio player AppControl

      When using the audio application control, the device standard media player application is launched to play audio.

    • +
    • wav player header

      When using the wav player header, your application uses its own user interface.

    • +
    +

    The WAV Player API provides controlling functions for using audio resources. The resources can be a media file stored in the device.

    +

    Use the WAV Player API to enable your application to play audio and control playback. The audio features of this API include:

    +
      +
    • Playing audio media from local files
    • +
    • Controlling playback using play and stop
    • +
    + +

    The audio formats your application can use with the WAV Player API include:

    +
      +
    • WAV, OGG
    • +
    +

    Most operations of the WAV Player API work in synchronous mode The WAV Player API requires a callback to notify the application of the operational status of the player. The callback must be implemented and passed to stop the WAV playback.

    +

    Multiple instances of the wav player can be used to play several audio data streams concurrently. This means that your application can play multiple uncompressed audio files, such as WAV, at the same time.

    +

    The most common audio uses of the WAV Player API include:

    +
      +
    • Playing an audio file and controlling the playback
    • +
    • Handling player controls
    • +
    + +

    The following figure illustrates the general WAV player state changes.

    +

    Figure: WAV player state changes

    +

    WAV player state changes

    + + + +
    + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/native/network/bluetooth_n.htm b/org.tizen.guides/html/native/network/bluetooth_n.htm index 5b4df2b..66fd95e 100644 --- a/org.tizen.guides/html/native/network/bluetooth_n.htm +++ b/org.tizen.guides/html/native/network/bluetooth_n.htm @@ -1,99 +1,99 @@ - - - - - - - - - - - - - Bluetooth - - - - - -
    -

    Bluetooth

    - -

    Tizen enables you to use Bluetooth functionalities, such as managing the local Bluetooth adapter, bonding, and exchanging data between Bluetooth-enabled devices. The Bluetooth standard provides a peer-to-peer (P2P) data exchange functionality over short distance between compliant devices.

    -

    The main features of the Bluetooth API include:

    - -
      -
    • Managing the local Bluetooth adapter -

      The Bluetooth Adapter API (in mobile and wearable applications) provides functions for setting up Bluetooth and discovering other devices. The API is used to control the Bluetooth adapter: you must enable the adapter before any other Bluetooth actions, and when you no longer need it, disable it to save device power.

      -

      You can control the visibility of the device, meaning whether its name appears to others searching for Bluetooth devices. In addition, you discover neighboring Bluetooth devices. This process is asynchronous, so you must build and hold the list of devices in the neighborhood.

      -
    • -
    • Discovering devices -

      The Bluetooth Device API (in mobile and wearable applications) provides functions for managing bonds with other devices and searching for supported services. The API is used to handle the connection with other devices and to search for services available on remote devices.

      -

      You can discover other Bluetooth devices. The device discovery process can retrieve multiple types of Bluetooth devices, such as printers, mobile phones, and headphones.

      -
    • -
    • Creating a bonding with a Bluetooth device -

      You can create a bonding with another device. The bonding allows the 2 devices to establish a connection.

      -

      Connected devices exchange keys needed for encrypted communication, but each connection has to be approved by the latest application user. You can also set authorization of other devices. Authorized devices are connected automatically without the latest user being asked for authorization.

      -
    • -
    • Connecting to and exchanging data with a Bluetooth device using a Bluetooth socket -

      The Bluetooth Socket API (in mobile and wearable applications) provides functions for managing connections to other devices and exchanging data. The API is used for exchanging data between 2 Bluetooth devices, where your device can have the role both of a server (service provider) and client (service user). The connection creation process differs based on the role. After the connection is established, the processes for exchanging data and disconnecting are the same for both roles.

      -

      When you attempt to open a connection to another device, a Service Discovery Protocol (SDP) look-up is performed on the device, and the protocol and channel to be used for the connection are determined. If a connection is established and the socket is opened successfully, a BluetoothSocket instance with an open state is returned. The socket is subsequently used for exchanging data between the connected devices.

      -
    • -
    • Connecting to audio devices with Bluetooth -

      Connect to Bluetooth audio devices, such as headset, hand-free, and headphone.

    • -
    • Handling attributes with Bluetooth GATT -

      The Bluetooth GATT API (in mobile and wearable applications) provides functions for discovering, reading, and modifying attributes.

      -

      As a client, you can connect to and use a specific service on the server device. Once the connection is established, the client can manage the service attributes.

    • -
    • Connecting to health devices with Bluetooth HDP -

      Manage connections to health devices and exchange data.

    • -
    • Connecting to devices with Bluetooth HID -

      Connect to a Bluetooth HID, such as a keyboard or mouse.

    • -
    • Sending and receiving objects with the Bluetooth OPP client and server -

      Push and accept objects, such as pictures.

    • -
    • Exchanging data with Bluetooth LE -

      The Bluetooth LE Adapter API (in mobile and wearable applications) provides functions for managing the Bluetooth Low Energy (BLE) connections with other BLE devices and exchanging data between them.

      -

      You can control the visibility of the BLE device, meaning whether its name appears to others searching for BLE devices. In addition, you discover neighboring BLE devices. This process is asynchronous, so you must build and hold the list of devices in the neighborhood.

      -
    • -
    • Controlling remote audio and video devices with Bluetooth AVRCP -

      The Bluetooth AVRCP feature (in mobile and wearable applications) provides functions for remotely controlling audio and video devices.

      -

      Bluetooth AVRCP is used with A2DP. You can handle remote controls (such as play, pause, stop, equalizer, repeat, shuffle, and scan) through AVRCP.

    • -
    - -

    Bluetooth use is based on profiles. Tizen Bluetooth features support the Audio, GATT, HDP, HID, and OPP client and server profiles.

    - - - -
    - -Go to top - - - - - - + + + + + + + + + + + + + Bluetooth + + + + + +
    +

    Bluetooth

    + +

    Tizen enables you to use Bluetooth functionalities, such as managing the local Bluetooth adapter, bonding, and exchanging data between Bluetooth-enabled devices. The Bluetooth standard provides a peer-to-peer (P2P) data exchange functionality over short distance between compliant devices.

    +

    The main features of the Bluetooth API include:

    + +
      +
    • Managing the local Bluetooth adapter +

      The Bluetooth Adapter API (in mobile and wearable applications) provides functions for setting up Bluetooth and discovering other devices. The API is used to control the Bluetooth adapter: you must enable the adapter before any other Bluetooth actions, and when you no longer need it, disable it to save device power.

      +

      You can control the visibility of the device, meaning whether its name appears to others searching for Bluetooth devices. In addition, you discover neighboring Bluetooth devices. This process is asynchronous, so you must build and hold the list of devices in the neighborhood.

      +
    • +
    • Discovering devices +

      The Bluetooth Device API (in mobile and wearable applications) provides functions for managing bonds with other devices and searching for supported services. The API is used to handle the connection with other devices and to search for services available on remote devices.

      +

      You can discover other Bluetooth devices. The device discovery process can retrieve multiple types of Bluetooth devices, such as printers, mobile phones, and headphones.

      +
    • +
    • Creating a bonding with a Bluetooth device +

      You can create a bonding with another device. The bonding allows the 2 devices to establish a connection.

      +

      Connected devices exchange keys needed for encrypted communication, but each connection has to be approved by the latest application user. You can also set authorization of other devices. Authorized devices are connected automatically without the latest user being asked for authorization.

      +
    • +
    • Connecting to and exchanging data with a Bluetooth device using a Bluetooth socket +

      The Bluetooth Socket API (in mobile and wearable applications) provides functions for managing connections to other devices and exchanging data. The API is used for exchanging data between 2 Bluetooth devices, where your device can have the role both of a server (service provider) and client (service user). The connection creation process differs based on the role. After the connection is established, the processes for exchanging data and disconnecting are the same for both roles.

      +

      When you attempt to open a connection to another device, a Service Discovery Protocol (SDP) look-up is performed on the device, and the protocol and channel to be used for the connection are determined. If a connection is established and the socket is opened successfully, a BluetoothSocket instance with an open state is returned. The socket is subsequently used for exchanging data between the connected devices.

      +
    • +
    • Connecting to audio devices with Bluetooth +

      Connect to Bluetooth audio devices, such as headset, hand-free, and headphone.

    • +
    • Handling attributes with Bluetooth GATT +

      The Bluetooth GATT API (in mobile and wearable applications) provides functions for discovering, reading, and modifying attributes.

      +

      As a client, you can connect to and use a specific service on the server device. Once the connection is established, the client can manage the service attributes.

    • +
    • Connecting to health devices with Bluetooth HDP +

      Manage connections to health devices and exchange data.

    • +
    • Connecting to devices with Bluetooth HID +

      Connect to a Bluetooth HID, such as a keyboard or mouse.

    • +
    • Sending and receiving objects with the Bluetooth OPP client and server +

      Push and accept objects, such as pictures.

    • +
    • Exchanging data with Bluetooth LE +

      The Bluetooth LE Adapter API (in mobile and wearable applications) provides functions for managing the Bluetooth Low Energy (BLE) connections with other BLE devices and exchanging data between them.

      +

      You can control the visibility of the BLE device, meaning whether its name appears to others searching for BLE devices. In addition, you discover neighboring BLE devices. This process is asynchronous, so you must build and hold the list of devices in the neighborhood.

      +
    • +
    • Controlling remote audio and video devices with Bluetooth AVRCP +

      The Bluetooth AVRCP feature (in mobile and wearable applications) provides functions for remotely controlling audio and video devices.

      +

      Bluetooth AVRCP is used with A2DP. You can handle remote controls (such as play, pause, stop, equalizer, repeat, shuffle, and scan) through AVRCP.

    • +
    + +

    Bluetooth use is based on profiles. Tizen Bluetooth features support the Audio, GATT, HDP, HID, and OPP client and server profiles.

    + + + +
    + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/native/network/connection_n.htm b/org.tizen.guides/html/native/network/connection_n.htm index f48d866..5a8141f 100644 --- a/org.tizen.guides/html/native/network/connection_n.htm +++ b/org.tizen.guides/html/native/network/connection_n.htm @@ -1,309 +1,309 @@ - - - - - - - - - - - - - Connection - - - - - -
    -

    Connection

    - -

    The connection features enable you to create a network connection and perform various operations over the connection. The application can access connection details, such as the IP address, proxy information, gateway information, and connection statistics.

    - - - - - - - - - - -
    Note
    Within the Network Programming Guide, the term "network" refers to IP network connections. For information on telephony connections, see the Telephony guide.
    - -

    Connection Manager

    -

    The Connection Manager API (in mobile and wearable applications) provides functions for managing data connections. It allows you to get a state of the connection interface such as Bluetooth, cellular, and Wi-Fi. It also contains functions for getting the IP address, proxy information, and gateway information.

    - -

    The Connection Manager API is related with libcurl and sockets. After a network connection is established, you can create a socket on the kernel Linux stack to be used directly or by libcurl or any other network library. If you want to create a socket directly without libcurl, you must check whether you are using the IPv4 or IPv6 environment, and create an applicable IP socket.

    - -

    The Connection Manager provides the following typedefs and enumerators for managing data connections:

    - -
    • connection_h -

      Connection handle for all connection functions. To use the Connection Manager API, first create a connection handle using the connection_create() function. Afterwards, you can obtain network information.

    • -
    • connection_profile_h -

      Profile handle, which provides information according to the connection type.

    • -
    • Connection state enumerators -

      One of the following states is returned by the connection_get_[interface]_state() function:

      -
      • connection_bt_state_e
      • -
      • connection_cellular_state_e
      • -
      • connection_wifi_state_e
      -

      The Connection Manager supports getting the connection state for Bluetooth, cellular and Wi-Fi.

    • -
    • connection_address_family_e -

      Enumeration for the address family. It provides IPv4 and IPv6. You can use it as a parameter when you get the IP address of the current connection or proxy.

    - -

    Connection Profile

    -

    The Connection Profile API (in mobile and wearable applications) provides functions for mapping a connection profile. It allows you to use a connection_profile_h handle for getting details about the connection.

    - -

    Each profile is defined by a set of configuration information defined in the connection_profile_h handle. The profile provides different information according to the connection type (such as Bluetooth, cellular, ethernet, and Wi-Fi).

    - -

    The following tables define the available profile information, which you can get using the connection_profile_get_*() function.

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    - Table: Common information -
    InformationDescription
    Profile typeProfile type indicating the network connection type
    Profile IDUnique profile ID; when you create a new profile, this value is determined
    Profile nameProfile name associated with the profile ID
    Profile stateProfile state, such as disconnected, association, configuration, or connected
    DNS addressDNS address; you can get the first and second DNS address
    Gateway addressGateway address
    Subnet maskSubnet mask
    Proxy addressProxy address
    Proxy typeProxy method, such as direct or auto
    Network interface nameName of the network interface, such as eth0 or pdp0
    IP addressIP address
    IP configuration typeIP address configuration type, such as static, dynamic, auto, or fixed
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    - Table: Profile-specific information for Wi-Fi -
    InformationDescription
    EssidExtended service set identifier
    BssidBasic service set identifier
    Encryption typeType for encryption modes, such as WEP, TKIP, AES or TKIP/AES mixed
    FrequencyFrequency (in MHz)
    Max speedMaximum speed (in Mbps)
    Passphrase requiredPassphrase compulsion
    WPS supportedWPS (Wi-Fi Protected Setup) support
    Security typeWi-Fi security type; supports WEP, WPA-PSK, WPA2-PSK, and EAP
    RssiReceived signal strength indication
    - - - - - - - - - - - - - - - - - - - - - - - - - -
    - Table: Profile-specific information for cellular -
    InformationDescription
    APNAccess Point Name
    Cellular authentication infoAuthentication information, including user name and password
    Cellular home URLHome URL
    Service typeCellular service type
    - - -

    Connection Statistics

    - -

    Use the Connection Statistics API (in mobile and wearable applications) to gather and reset statistics on the network usage, such as the amount of sent or received data. The statistics also provide functions for getting the cumulative size of packets sent or received since the last reset based on the operation mode, such as packet switching (PS).

    - - - - - - - - - - -
    Note
    Only Wi-Fi and cellular connections are supported in the statistics.
    - -

    The following table lists the connection type constants.

    - - - - - - - - - - - - - - - - - -
    - Table: Connection type constants -
    ConstantDescription
    CONNECTION_TYPE_WIFIWi-Fi type
    CONNECTION_TYPE_CELLULARCellular type
    - -

    The following table lists the statistics constants.

    - - - - - - - - - - - - - - - - - - - - - - - - -
    - Table: Statistics constants -
    ConstantDescription
    CONNECTION_STATISTICS_TYPE_LAST_RECEIVED_DATALast received data
    CONNECTION_STATISTICS_TYPE_LAST_SENT_DATALast sent data
    CONNECTION_STATISTICS_TYPE_TOTAL_RECEIVED_DATATotal received data
    CONNECTION_STATISTICS_TYPE_TOTAL_SENT_DATATotal sent data
    - -

    Use the connection_reset_statistics() function to re-initialize the statistics.

    - - - - -
    - -Go to top - - - - - - + + + + + + + + + + + + + Connection + + + + + +
    +

    Connection

    + +

    The connection features enable you to create a network connection and perform various operations over the connection. The application can access connection details, such as the IP address, proxy information, gateway information, and connection statistics.

    + + + + + + + + + + +
    Note
    Within the Network Programming Guide, the term "network" refers to IP network connections. For information on telephony connections, see the Telephony guide.
    + +

    Connection Manager

    +

    The Connection Manager API (in mobile and wearable applications) provides functions for managing data connections. It allows you to get a state of the connection interface such as Bluetooth, cellular, and Wi-Fi. It also contains functions for getting the IP address, proxy information, and gateway information.

    + +

    The Connection Manager API is related with libcurl and sockets. After a network connection is established, you can create a socket on the kernel Linux stack to be used directly or by libcurl or any other network library. If you want to create a socket directly without libcurl, you must check whether you are using the IPv4 or IPv6 environment, and create an applicable IP socket.

    + +

    The Connection Manager provides the following typedefs and enumerators for managing data connections:

    + +
    • connection_h +

      Connection handle for all connection functions. To use the Connection Manager API, first create a connection handle using the connection_create() function. Afterwards, you can obtain network information.

    • +
    • connection_profile_h +

      Profile handle, which provides information according to the connection type.

    • +
    • Connection state enumerators +

      One of the following states is returned by the connection_get_[interface]_state() function:

      +
      • connection_bt_state_e
      • +
      • connection_cellular_state_e
      • +
      • connection_wifi_state_e
      +

      The Connection Manager supports getting the connection state for Bluetooth, cellular and Wi-Fi.

    • +
    • connection_address_family_e +

      Enumeration for the address family. It provides IPv4 and IPv6. You can use it as a parameter when you get the IP address of the current connection or proxy.

    + +

    Connection Profile

    +

    The Connection Profile API (in mobile and wearable applications) provides functions for mapping a connection profile. It allows you to use a connection_profile_h handle for getting details about the connection.

    + +

    Each profile is defined by a set of configuration information defined in the connection_profile_h handle. The profile provides different information according to the connection type (such as Bluetooth, cellular, ethernet, and Wi-Fi).

    + +

    The following tables define the available profile information, which you can get using the connection_profile_get_*() function.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + Table: Common information +
    InformationDescription
    Profile typeProfile type indicating the network connection type
    Profile IDUnique profile ID; when you create a new profile, this value is determined
    Profile nameProfile name associated with the profile ID
    Profile stateProfile state, such as disconnected, association, configuration, or connected
    DNS addressDNS address; you can get the first and second DNS address
    Gateway addressGateway address
    Subnet maskSubnet mask
    Proxy addressProxy address
    Proxy typeProxy method, such as direct or auto
    Network interface nameName of the network interface, such as eth0 or pdp0
    IP addressIP address
    IP configuration typeIP address configuration type, such as static, dynamic, auto, or fixed
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + Table: Profile-specific information for Wi-Fi +
    InformationDescription
    EssidExtended service set identifier
    BssidBasic service set identifier
    Encryption typeType for encryption modes, such as WEP, TKIP, AES or TKIP/AES mixed
    FrequencyFrequency (in MHz)
    Max speedMaximum speed (in Mbps)
    Passphrase requiredPassphrase compulsion
    WPS supportedWPS (Wi-Fi Protected Setup) support
    Security typeWi-Fi security type; supports WEP, WPA-PSK, WPA2-PSK, and EAP
    RssiReceived signal strength indication
    + + + + + + + + + + + + + + + + + + + + + + + + + +
    + Table: Profile-specific information for cellular +
    InformationDescription
    APNAccess Point Name
    Cellular authentication infoAuthentication information, including user name and password
    Cellular home URLHome URL
    Service typeCellular service type
    + + +

    Connection Statistics

    + +

    Use the Connection Statistics API (in mobile and wearable applications) to gather and reset statistics on the network usage, such as the amount of sent or received data. The statistics also provide functions for getting the cumulative size of packets sent or received since the last reset based on the operation mode, such as packet switching (PS).

    + + + + + + + + + + +
    Note
    Only Wi-Fi and cellular connections are supported in the statistics.
    + +

    The following table lists the connection type constants.

    + + + + + + + + + + + + + + + + + +
    + Table: Connection type constants +
    ConstantDescription
    CONNECTION_TYPE_WIFIWi-Fi type
    CONNECTION_TYPE_CELLULARCellular type
    + +

    The following table lists the statistics constants.

    + + + + + + + + + + + + + + + + + + + + + + + + +
    + Table: Statistics constants +
    ConstantDescription
    CONNECTION_STATISTICS_TYPE_LAST_RECEIVED_DATALast received data
    CONNECTION_STATISTICS_TYPE_LAST_SENT_DATALast sent data
    CONNECTION_STATISTICS_TYPE_TOTAL_RECEIVED_DATATotal received data
    CONNECTION_STATISTICS_TYPE_TOTAL_SENT_DATATotal sent data
    + +

    Use the connection_reset_statistics() function to re-initialize the statistics.

    + + + + +
    + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/native/network/network_guide_n.htm b/org.tizen.guides/html/native/network/network_guide_n.htm index 442d745..3094b7d 100644 --- a/org.tizen.guides/html/native/network/network_guide_n.htm +++ b/org.tizen.guides/html/native/network/network_guide_n.htm @@ -1,71 +1,71 @@ - - - - - - - - - - - - - Network - - - - - -
    -

    Network

    -

    Network features include information on how your application can send data to networks and other applications, and receive data back from them.

    - -

    The main network features are:

    -
      -
    • Connection

      Enables you to get information about the connected network, set up and configure network connections, and track information, such as sent and received size.

    • -
    • Bluetooth

      Enables you to use Bluetooth functionalities, such as managing the local Bluetooth adapter, bonding, and exchanging data between Bluetooth-enabled devices.

    • -
    • NFC

      Enables you to use Near Field Communication (NFC) functionalities, such as reading and writing tags, and emulating a smart card.

    • -
    • SmartCard

      Enables you to access secure elements (SE) through smart card features.

    • -
    • Wi-Fi

      Enables you to connect to a Wireless Local Area Network (WLAN) and transfer data over the network.

    • -
    -

    The following guides apply in mobile applications only:

    -
      -
    • Wi-Fi Direct

      Enables you to connect to Wi-Fi Direct™ devices and manage Wi-Fi Direct™ connections.

    • -
    - - - -
    - -Go to top - - - - - - + + + + + + + + + + + + + Network + + + + + +
    +

    Network

    +

    Network features include information on how your application can send data to networks and other applications, and receive data back from them.

    + +

    The main network features are:

    +
      +
    • Connection

      Enables you to get information about the connected network, set up and configure network connections, and track information, such as sent and received size.

    • +
    • Bluetooth

      Enables you to use Bluetooth functionalities, such as managing the local Bluetooth adapter, bonding, and exchanging data between Bluetooth-enabled devices.

    • +
    • NFC

      Enables you to use Near Field Communication (NFC) functionalities, such as reading and writing tags, and emulating a smart card.

    • +
    • SmartCard

      Enables you to access secure elements (SE) through smart card features.

    • +
    • Wi-Fi

      Enables you to connect to a Wireless Local Area Network (WLAN) and transfer data over the network.

    • +
    +

    The following guides apply in mobile applications only:

    +
      +
    • Wi-Fi Direct

      Enables you to connect to Wi-Fi Direct™ devices and manage Wi-Fi Direct™ connections.

    • +
    + + + +
    + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/native/network/nfc_n.htm b/org.tizen.guides/html/native/network/nfc_n.htm index f1055bc..77c0b17 100644 --- a/org.tizen.guides/html/native/network/nfc_n.htm +++ b/org.tizen.guides/html/native/network/nfc_n.htm @@ -1,175 +1,175 @@ - - - - - - - - - - - - - NFC - - - - - -
    -

    NFC

    - -

    Tizen enables you to use Near Field Communication (NFC) functionalities, such as reading and writing tags, and emulating a smart card. NFC is an international standard that specifies an interface and a protocol for simple wireless interconnection of closely coupled devices. For more information, see the NFC Forum.

    - -

    The main features of the NFC API include:

    - -
      -
    • NFC management -

      The Manager API (in mobile and wearable applications) provides functions, for example, for:

      -
        -
      • Initializing and deinitializing NFC
      • -
      • Enabling and disabling NFC
      • -
      • Setting callbacks for NFC events
      • -
      • Managing NFC connections
      • -
      -
    • -
    • NDEF support - -

      The NFC Data Exchange Format (NDEF) is a packet message format used in the reader/writer and peer-to-peer modes.

      - -

      The NDEF API (in mobile and wearable applications) provides functions for:

      - -
        -
      • Creating NDEF records
      • -
      • Retrieving a specific field of an NDEF record
      • -
      • Creating NDEF messages
      • -
      • Inserting and removing NDEF records to and from an NDEF message
      • -
      -
    • -
    • Reader/writer mode -

      The TAG API (in mobile and wearable applications) provides functions, for example, for:

      - -
        -
      • Retrieving the tag type
      • -
      • Reading an NDEF message from a tag
      • -
      • Writing an NDEF message to a tag
      • -
      • Formatting a tag for using NDEF
      • -
      • Handling type-specific tag operations (currently only MIFARE)
      • -
      -
    • -
    • Peer-to-peer mode -

      The Peer to Peer API (in mobile and wearable applications) provides functions for:

      - -
        -
      • Sending an NDEF message to a peer device
      • -
      • Receiving an NDEF message from a peer device
      • -
      -
    • -
    • Card emulation mode -

      The card emulation mode allows an NFC device to function as a smart card. The mode provides access to secure elements (SEs).

      -

      The NFC controller in the device routes all data from the reader directly to the secure element, and an applet handles all of the data in the SE. The user does not participate at all in the operation.

      - -

      Figure: Traditional card emulation

      -

      Traditional card emulation

      - -

      The Card Emulation API (in mobile and wearable applications) provides functions for:

      - -
        -
      • Enabling and disabling the card emulation mode
      • -
      • Retrieving the card emulation status
      • -
      • Opening and closing a secure element
      • -
      • Sending an application protocol data unit (APDU) to a secure element
      • -
      • Retrieving an Answer To Reset (ATR) from a secure element
      • -
      - - - - - - - - - - -
      Note
      Pay attention to the following: -
      • Secure element access is not supported in Tizen 2.3. The Card Emulation API of Tizen 2.3 only supports enabling and disabling the NFC card emulation mode, and retrieving the card emulation status.
      • -
      • Security problems can occur in some Card Emulation APIs. The security level can be determined by the manufacturer usage. If a security issue occurs, contact the product manufacturer. For more information on the security levels, see the GSMA specification.
      -
      -
    • -
    • Host-based card emulation (HCE) -

      HCE is on-device technology that permits a phone to perform card emulation on an NFC-enabled device without relying on access to a secure element (SE). The data is routed to the user space on which Tizen applications reside, instead of routing the data to a secure element.

      - -

      Figure: Card emulation with HCE

      -

      Card emulation with HCE

      -

      HCE allows you to create your own card emulation system and bypass the SE. This approach brings 2 advantages:

      - -
        -
      • In case of UICC type SE, the mobile service provider is involved in the card emulation behavior. With HCE, you are free from the provider influence.
      • -
      • You do not need SE hardware chips within the device.
      - -

      The understand HCE behavior, mainly how data is internally routed to the correct application, consider how Tizen handles NFC routing:

      - -
      1. Assume that the user has an HCE application or installs one. -

        The application has a "AID" value, which is stored in NFC routing table (blue arrow in the following figure).

      2. -
      3. When the NFC reader attempts card emulation, the NFC controller checks the routing table to find the application to which the data is sent for emulation (red arrows in the following figure).
      4. -
      5. When the application is uninstalled, the AID value is deleted from the routing table.
      - -

      Figure: HCE routing

      -

      HCE routing

      -
    • -
    - -

    NFC applications can be launched by a card emulation transaction using the application control functionalities. NFC devices can communicate with the point of sales (POS) terminals using the card emulation functionality to, for example, make a payment.

    -

    If an application control with a following operation is defined in the configuration file and an event caused by the card emulation functionality occurs, the NFC application is launched:

    -
      -
    • http://tizen.org/appcontrol/operation/nfc/transaction -

      A transaction caused by the card emulation functionality occurs.

      -
    • -
    • http://tizen.org/appcontrol/operation/nfc/card_emulation/default_changed -

      The user selects a default wallet in Tap&Pay.

      -
    • -
    • http://tizen.org/appcontrol/operation/nfc/card_emulation/host_apdu_service -

      A host APDU service (HCE) APDU event occurs.

      -
    • -
    • http://tizen.org/appcontrol/operation/nfc/card_emulation/off_host_apdu_service -

      An off-host APDU service (eSE, UICC) APDU event occurs.

      -
    • -
    - - - - -
    - -Go to top - - - - - - + + + + + + + + + + + + + NFC + + + + + +
    +

    NFC

    + +

    Tizen enables you to use Near Field Communication (NFC) functionalities, such as reading and writing tags, and emulating a smart card. NFC is an international standard that specifies an interface and a protocol for simple wireless interconnection of closely coupled devices. For more information, see the NFC Forum.

    + +

    The main features of the NFC API include:

    + +
      +
    • NFC management +

      The Manager API (in mobile and wearable applications) provides functions, for example, for:

      +
        +
      • Initializing and deinitializing NFC
      • +
      • Enabling and disabling NFC
      • +
      • Setting callbacks for NFC events
      • +
      • Managing NFC connections
      • +
      +
    • +
    • NDEF support + +

      The NFC Data Exchange Format (NDEF) is a packet message format used in the reader/writer and peer-to-peer modes.

      + +

      The NDEF API (in mobile and wearable applications) provides functions for:

      + +
        +
      • Creating NDEF records
      • +
      • Retrieving a specific field of an NDEF record
      • +
      • Creating NDEF messages
      • +
      • Inserting and removing NDEF records to and from an NDEF message
      • +
      +
    • +
    • Reader/writer mode +

      The TAG API (in mobile and wearable applications) provides functions, for example, for:

      + +
        +
      • Retrieving the tag type
      • +
      • Reading an NDEF message from a tag
      • +
      • Writing an NDEF message to a tag
      • +
      • Formatting a tag for using NDEF
      • +
      • Handling type-specific tag operations (currently only MIFARE)
      • +
      +
    • +
    • Peer-to-peer mode +

      The Peer to Peer API (in mobile and wearable applications) provides functions for:

      + +
        +
      • Sending an NDEF message to a peer device
      • +
      • Receiving an NDEF message from a peer device
      • +
      +
    • +
    • Card emulation mode +

      The card emulation mode allows an NFC device to function as a smart card. The mode provides access to secure elements (SEs).

      +

      The NFC controller in the device routes all data from the reader directly to the secure element, and an applet handles all of the data in the SE. The user does not participate at all in the operation.

      + +

      Figure: Traditional card emulation

      +

      Traditional card emulation

      + +

      The Card Emulation API (in mobile and wearable applications) provides functions for:

      + +
        +
      • Enabling and disabling the card emulation mode
      • +
      • Retrieving the card emulation status
      • +
      • Opening and closing a secure element
      • +
      • Sending an application protocol data unit (APDU) to a secure element
      • +
      • Retrieving an Answer To Reset (ATR) from a secure element
      • +
      + + + + + + + + + + +
      Note
      Pay attention to the following: +
      • Secure element access is not supported in Tizen 2.3. The Card Emulation API of Tizen 2.3 only supports enabling and disabling the NFC card emulation mode, and retrieving the card emulation status.
      • +
      • Security problems can occur in some Card Emulation APIs. The security level can be determined by the manufacturer usage. If a security issue occurs, contact the product manufacturer. For more information on the security levels, see the GSMA specification.
      +
      +
    • +
    • Host-based card emulation (HCE) +

      HCE is on-device technology that permits a phone to perform card emulation on an NFC-enabled device without relying on access to a secure element (SE). The data is routed to the user space on which Tizen applications reside, instead of routing the data to a secure element.

      + +

      Figure: Card emulation with HCE

      +

      Card emulation with HCE

      +

      HCE allows you to create your own card emulation system and bypass the SE. This approach brings 2 advantages:

      + +
        +
      • In case of UICC type SE, the mobile service provider is involved in the card emulation behavior. With HCE, you are free from the provider influence.
      • +
      • You do not need SE hardware chips within the device.
      + +

      The understand HCE behavior, mainly how data is internally routed to the correct application, consider how Tizen handles NFC routing:

      + +
      1. Assume that the user has an HCE application or installs one. +

        The application has a "AID" value, which is stored in NFC routing table (blue arrow in the following figure).

      2. +
      3. When the NFC reader attempts card emulation, the NFC controller checks the routing table to find the application to which the data is sent for emulation (red arrows in the following figure).
      4. +
      5. When the application is uninstalled, the AID value is deleted from the routing table.
      + +

      Figure: HCE routing

      +

      HCE routing

      +
    • +
    + +

    NFC applications can be launched by a card emulation transaction using the application control functionalities. NFC devices can communicate with the point of sales (POS) terminals using the card emulation functionality to, for example, make a payment.

    +

    If an application control with a following operation is defined in the configuration file and an event caused by the card emulation functionality occurs, the NFC application is launched:

    +
      +
    • http://tizen.org/appcontrol/operation/nfc/transaction +

      A transaction caused by the card emulation functionality occurs.

      +
    • +
    • http://tizen.org/appcontrol/operation/nfc/card_emulation/default_changed +

      The user selects a default wallet in Tap&Pay.

      +
    • +
    • http://tizen.org/appcontrol/operation/nfc/card_emulation/host_apdu_service +

      A host APDU service (HCE) APDU event occurs.

      +
    • +
    • http://tizen.org/appcontrol/operation/nfc/card_emulation/off_host_apdu_service +

      An off-host APDU service (eSE, UICC) APDU event occurs.

      +
    • +
    + + + + +
    + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/native/network/smartcard_n.htm b/org.tizen.guides/html/native/network/smartcard_n.htm index 071b94f..6acc7fc 100644 --- a/org.tizen.guides/html/native/network/smartcard_n.htm +++ b/org.tizen.guides/html/native/network/smartcard_n.htm @@ -1,89 +1,89 @@ - - - - - - - - - - - - - SmartCard - - - - - -
    -

    SmartCard

    - -

    Tizen enables you to use smart card functionalities, such as accessing a secure element (SE). Before using the SmartCard API, make sure you have a secure element on the device. The smart card service allow you to open a session on an SE, open a channel to the applet in the SE, send a command to the channel, and finally receive a response to the command.

    - -

    The main components of the SmartCard API include:

    - -
      -
    • SE service -

      The SE Service API (in mobile and wearable applications) allows you to initialize and deinitialize the smart card features, and get the available readers. The SE service functions as a connector to the SE framework system.

      -
    • -
    • Reader -

      The Reader API (in mobile and wearable applications) allows you to access the SE connected with the selected reader. You can get the reader name and open and close sessions.

      -
    • -
    • Session -

      A session is an open connection between an application on the device and a SE. The Session API (in mobile and wearable applications) allows you to open and close basic and logical channels, and get ATR (answer to reset).

      -
    • -
    • Channel -

      A channel is an open connection between an application on the device and an applet on the SE. The Channel API (in mobile and wearable applications) allows you to close channels and transmit application protocol data units (APDU).

      -
    • -
    - -

    The following figure illustrates the smart card service architecture in Tizen. The smart card service sends and receives data through the terminal of each SE.

    -

    Figure: Smart card service architecture

    -

    Smart card service architecture

    - -

    The SmartCard API is a reference implementation of the SIMalliance Open Mobile 3.0 API specification that enables Tizen applications to communicate with secure elements. For more information, see the SimAlliance. The Tizen implementation differs from the original as follows:

    - -
    • Only the transport layer is provided. There is no service layer support in Tizen.
    • -
    • The "get version" function does not exist. In Tizen, version management is not performed through a function.
    • -
    • Allocation style differs dramatically. -The Open Mobile API can facilitate the memory management by calling the API twice (for an example, see section 6.3.1, Usage pattern, in the SIMalliance Open Mobile 3.0 API specification). However, Tizen SmartCard API does not follow this allocation style.
    • -
    • For the SE Service object management, Tizen provides functions for initialization and deinitialization.
    - - - - -
    - -Go to top - - - - - - + + + + + + + + + + + + + SmartCard + + + + + +
    +

    SmartCard

    + +

    Tizen enables you to use smart card functionalities, such as accessing a secure element (SE). Before using the SmartCard API, make sure you have a secure element on the device. The smart card service allow you to open a session on an SE, open a channel to the applet in the SE, send a command to the channel, and finally receive a response to the command.

    + +

    The main components of the SmartCard API include:

    + +
      +
    • SE service +

      The SE Service API (in mobile and wearable applications) allows you to initialize and deinitialize the smart card features, and get the available readers. The SE service functions as a connector to the SE framework system.

      +
    • +
    • Reader +

      The Reader API (in mobile and wearable applications) allows you to access the SE connected with the selected reader. You can get the reader name and open and close sessions.

      +
    • +
    • Session +

      A session is an open connection between an application on the device and a SE. The Session API (in mobile and wearable applications) allows you to open and close basic and logical channels, and get ATR (answer to reset).

      +
    • +
    • Channel +

      A channel is an open connection between an application on the device and an applet on the SE. The Channel API (in mobile and wearable applications) allows you to close channels and transmit application protocol data units (APDU).

      +
    • +
    + +

    The following figure illustrates the smart card service architecture in Tizen. The smart card service sends and receives data through the terminal of each SE.

    +

    Figure: Smart card service architecture

    +

    Smart card service architecture

    + +

    The SmartCard API is a reference implementation of the SIMalliance Open Mobile 3.0 API specification that enables Tizen applications to communicate with secure elements. For more information, see the SimAlliance. The Tizen implementation differs from the original as follows:

    + +
    • Only the transport layer is provided. There is no service layer support in Tizen.
    • +
    • The "get version" function does not exist. In Tizen, version management is not performed through a function.
    • +
    • Allocation style differs dramatically. +The Open Mobile API can facilitate the memory management by calling the API twice (for an example, see section 6.3.1, Usage pattern, in the SIMalliance Open Mobile 3.0 API specification). However, Tizen SmartCard API does not follow this allocation style.
    • +
    • For the SE Service object management, Tizen provides functions for initialization and deinitialization.
    + + + + +
    + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/native/network/wifi_direct_n.htm b/org.tizen.guides/html/native/network/wifi_direct_n.htm index ca256c0..d51697b 100644 --- a/org.tizen.guides/html/native/network/wifi_direct_n.htm +++ b/org.tizen.guides/html/native/network/wifi_direct_n.htm @@ -1,92 +1,92 @@ - - - - - - - - - - - - - Wi-Fi Direct - - - -
    -
    -

    Mobile native

    -
    - - -
    - -
    -

    Wi-Fi Direct

    - -

    Wi-Fi Direct™ (synonym for Wi-Fi P2P (Peer-to-Peer)) is a technology that allows you to find nearby Wi-Fi Direct™ devices and form a Wi-Fi Direct™ group to communicate over a peer-to-peer link without wireless access points (base stations) in the infrastructure mode.

    - - - - - - - - - - -
    Note
    This feature is supported in mobile applications only.
    - -

    In a Wi-Fi Direct™ group, the group owner works as an access point in the Wi-Fi infrastructure mode and the other devices join the group as clients. A group can be created either by negotiation between 2 devices or in an autonomous mode by a single group owner device. In a negotiation-based group creation, 2 devices compete based on the group owner intent value and the higher intent device becomes a group owner, while the other device becomes a group client. In an autonomous group creation, a device becomes a group owner by itself without any group client.

    - -

    A Wi-Fi Direct™ device can join an existing group by associating itself with the group owner, as long as the allowed number of clients is not exceeded.

    - -

    The main features of the Wi-FI Direct™ include:

    -
      -
    • Activating and deactivating a local Wi-Fi Direct™ device.
    • -
    • Discovering Wi-Fi Direct™ peer devices and showing Wi-Fi Direct™ peer device information.
    • -
    • Connecting to a specific Wi-Fi Direct™ device and disconnecting from a specific Wi-Fi Direct™ device.
    • -
    • Creating a Wi-Fi Direct™ group, and manage group.
    • -
    - - - - - - - - - - -
    Note
    You can test the Wi-Fi Direct™ functionality only on target devices. The Emulator currently does not support this feature.
    - - - -
    - -Go to top - - - - - - + + + + + + + + + + + + + Wi-Fi Direct + + + +
    +
    +

    Mobile native

    +
    + + +
    + +
    +

    Wi-Fi Direct

    + +

    Wi-Fi Direct™ (synonym for Wi-Fi P2P (Peer-to-Peer)) is a technology that allows you to find nearby Wi-Fi Direct™ devices and form a Wi-Fi Direct™ group to communicate over a peer-to-peer link without wireless access points (base stations) in the infrastructure mode.

    + + + + + + + + + + +
    Note
    This feature is supported in mobile applications only.
    + +

    In a Wi-Fi Direct™ group, the group owner works as an access point in the Wi-Fi infrastructure mode and the other devices join the group as clients. A group can be created either by negotiation between 2 devices or in an autonomous mode by a single group owner device. In a negotiation-based group creation, 2 devices compete based on the group owner intent value and the higher intent device becomes a group owner, while the other device becomes a group client. In an autonomous group creation, a device becomes a group owner by itself without any group client.

    + +

    A Wi-Fi Direct™ device can join an existing group by associating itself with the group owner, as long as the allowed number of clients is not exceeded.

    + +

    The main features of the Wi-FI Direct™ include:

    +
      +
    • Activating and deactivating a local Wi-Fi Direct™ device.
    • +
    • Discovering Wi-Fi Direct™ peer devices and showing Wi-Fi Direct™ peer device information.
    • +
    • Connecting to a specific Wi-Fi Direct™ device and disconnecting from a specific Wi-Fi Direct™ device.
    • +
    • Creating a Wi-Fi Direct™ group, and manage group.
    • +
    + + + + + + + + + + +
    Note
    You can test the Wi-Fi Direct™ functionality only on target devices. The Emulator currently does not support this feature.
    + + + +
    + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/native/network/wifi_n.htm b/org.tizen.guides/html/native/network/wifi_n.htm index 1b1e66a..8c4ab8b 100644 --- a/org.tizen.guides/html/native/network/wifi_n.htm +++ b/org.tizen.guides/html/native/network/wifi_n.htm @@ -1,280 +1,280 @@ - - - - - - - - - - - - - Wi-Fi - - - - - -
    -

    Wi-Fi

    - -

    Tizen allows your application to connect to a Wireless Local Area Network (WLAN) and transfer data over the network. The Wi-Fi Manager enables your application to activate and deactivate a local Wi-Fi device, and to connect to a WLAN network in the infrastructure mode.

    -

    The main features of the Wi-Fi API include:

    -
    • Wi-Fi device and connection management using the Wi-Fi Manager
    • -
    • Access point management -

      You can manage the Wi-Fi account and security information.

      -

      The infrastructure mode is used to connect to a wireless local area network (WLAN). The infrastructure mode requires a wireless access point. To connect to a WLAN, a client must be configured to use the same service set identifier (SSID) as the access point.

    • -
    • Wi-Fi state monitoring using the Wi-Fi Monitor
    • -
    - - - - - - - - - - -
    Note
    You can test the Wi-Fi functionality only on a target device. The Emulator does not support this feature.
    - - -

    Wi-Fi Manager

    - -

    The Tizen Wi-Fi Manager API (in mobile and wearable applications) provides functions for managing Wi-Fi connection.

    -

    Using the Wi-Fi Manager, you can implement features that allow the users of your application to:

    - -
    • Activate and deactivate a Wi-Fi device -

      You can activate and deactivate a local Wi-Fi device using the wifi_activate() and wifi_deactivate() functions. Both functions have a callback function as the first parameter. The callback function is called after the activation or deactivation is completed. You can use the NULL value, if you want no notifications.

      -
    • -
    • Connect to an access point -

      You can connect to an access point asynchronously using the wifi_connect() function.

      -
    • -
    • Scan the access points -

      To scan access points, use the wifi_scan() and wifi_foreach_found_aps() functions.

      -

      The wifi_scan() function starts the scan asynchronously. When the scan is finished, a callback function is called. The wifi_foreach_found_aps() function allows you to get the result of the scan. It also invokes a callback function.

    - - -

    Access Point

    - -

    The Access Point API (in mobile and wearable applications) provides functions for managing access points (AP). You need to create an AP handle (wifi_ap_h) for using the API functions.

    - -

    The Access Point API supports the following main features:

    -
    • Creating and destroying an AP handle
    • -
    • Getting the network information
    • -
    • Getting the security information
    - -

    The following table lists the network information details you can access with the Network Information API (in mobile and wearable applications).

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    - Table: Network information details -
    InformationDescription
    BssidBasic service set identifier
    Connection stateConnection state
    DNS addressDNS address
    EssidExtended service set identifier
    FrequencyFrequency (in MHz)
    IP addressIP address
    IP config typeNet IP configuration type
    Max speedMaximum speed (in Mbps)
    Proxy addressProxy address
    Proxy typeProxy method type
    RssiReceived signal strength indication
    Subnet maskSubnet mask
    - - -

    The following table lists the security information details you can access with the Security Information API (in mobile and wearable applications).

    - - - - - - - - - - - - - - - - - - - - - - - - -
    - Table: Security information details -
    InformationDescription
    Encryption typeWi-Fi encryption type, used in the infrastructure and ad-hoc mode
    Security typeWi-Fi security type
    Passphrase requiredWhether the passphrase is required
    WPS supportedWhether the WPS (Wi-Fi Protected Setup) is supported
    - -

    You can also obtain the EAP information listed in the following table.

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    - Table: EAP information details -
    InformationDescription
    Authentication typeType of EAP phase2 authentication of Wi-Fi
    CA certificateEAP CA certificate (valid only if the EAP type is TLS)
    Client CertificateEAP client certificate (valid only if the EAP type is TLS)
    PassphraseEAP passphrase (valid if the EAP type is PEAP or TTLS)
    Private key fileEAP private key file (valid only if the EAP type is TLS)
    EAP typeEAP type of Wi-Fi
    - -

    Wi-Fi Monitor

    - -

    The Wi-Fi Monitor API (in mobile and wearable applications) provides functions for monitoring the Wi-Fi connection state.

    - -

    The Wi-Fi Monitor allows you to get the state of the Wi-Fi connection. The state can be:

    - -
    • WIFI_CONNECTION_STATE_FAILURE -

      Connection failed.

    • -
    • WIFI_CONNECTION_STATE_DISCONNECTED -

      Disconnected.

    • -
    • WIFI_CONNECTION_STATE_ASSOCIATION -

      Association.

    • -
    • WIFI_CONNECTION_STATE_CONFIGURATION -

      Configuration.

    • -
    • WIFI_CONNECTION_STATE_CONNECTED -

      Connected.

    - -

    The Wi-Fi Monitor also allows monitoring the changes in Wi-Fi. With the Wi-Fi Monitor, you can register callback functions, which notify you when Wi-Fi properties change. The property changes resulting in notifications are listed in the following table.

    - - - - - - - - - - - - - - - - - - - - - -
    - Table: Property changes -
    Change inDescription
    Connection stateThe callback is called when the connection state is changed.
    Device stateThe callback is called when the device state changes.
    RSSI levelThe callback is called when the RSSI of the connected Wi-Fi changes.
    - - - -
    - -Go to top - - - - - - + + + + + + + + + + + + + Wi-Fi + + + + + +
    +

    Wi-Fi

    + +

    Tizen allows your application to connect to a Wireless Local Area Network (WLAN) and transfer data over the network. The Wi-Fi Manager enables your application to activate and deactivate a local Wi-Fi device, and to connect to a WLAN network in the infrastructure mode.

    +

    The main features of the Wi-Fi API include:

    +
    • Wi-Fi device and connection management using the Wi-Fi Manager
    • +
    • Access point management +

      You can manage the Wi-Fi account and security information.

      +

      The infrastructure mode is used to connect to a wireless local area network (WLAN). The infrastructure mode requires a wireless access point. To connect to a WLAN, a client must be configured to use the same service set identifier (SSID) as the access point.

    • +
    • Wi-Fi state monitoring using the Wi-Fi Monitor
    • +
    + + + + + + + + + + +
    Note
    You can test the Wi-Fi functionality only on a target device. The Emulator does not support this feature.
    + + +

    Wi-Fi Manager

    + +

    The Tizen Wi-Fi Manager API (in mobile and wearable applications) provides functions for managing Wi-Fi connection.

    +

    Using the Wi-Fi Manager, you can implement features that allow the users of your application to:

    + +
    • Activate and deactivate a Wi-Fi device +

      You can activate and deactivate a local Wi-Fi device using the wifi_activate() and wifi_deactivate() functions. Both functions have a callback function as the first parameter. The callback function is called after the activation or deactivation is completed. You can use the NULL value, if you want no notifications.

      +
    • +
    • Connect to an access point +

      You can connect to an access point asynchronously using the wifi_connect() function.

      +
    • +
    • Scan the access points +

      To scan access points, use the wifi_scan() and wifi_foreach_found_aps() functions.

      +

      The wifi_scan() function starts the scan asynchronously. When the scan is finished, a callback function is called. The wifi_foreach_found_aps() function allows you to get the result of the scan. It also invokes a callback function.

    + + +

    Access Point

    + +

    The Access Point API (in mobile and wearable applications) provides functions for managing access points (AP). You need to create an AP handle (wifi_ap_h) for using the API functions.

    + +

    The Access Point API supports the following main features:

    +
    • Creating and destroying an AP handle
    • +
    • Getting the network information
    • +
    • Getting the security information
    + +

    The following table lists the network information details you can access with the Network Information API (in mobile and wearable applications).

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + Table: Network information details +
    InformationDescription
    BssidBasic service set identifier
    Connection stateConnection state
    DNS addressDNS address
    EssidExtended service set identifier
    FrequencyFrequency (in MHz)
    IP addressIP address
    IP config typeNet IP configuration type
    Max speedMaximum speed (in Mbps)
    Proxy addressProxy address
    Proxy typeProxy method type
    RssiReceived signal strength indication
    Subnet maskSubnet mask
    + + +

    The following table lists the security information details you can access with the Security Information API (in mobile and wearable applications).

    + + + + + + + + + + + + + + + + + + + + + + + + +
    + Table: Security information details +
    InformationDescription
    Encryption typeWi-Fi encryption type, used in the infrastructure and ad-hoc mode
    Security typeWi-Fi security type
    Passphrase requiredWhether the passphrase is required
    WPS supportedWhether the WPS (Wi-Fi Protected Setup) is supported
    + +

    You can also obtain the EAP information listed in the following table.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + Table: EAP information details +
    InformationDescription
    Authentication typeType of EAP phase2 authentication of Wi-Fi
    CA certificateEAP CA certificate (valid only if the EAP type is TLS)
    Client CertificateEAP client certificate (valid only if the EAP type is TLS)
    PassphraseEAP passphrase (valid if the EAP type is PEAP or TTLS)
    Private key fileEAP private key file (valid only if the EAP type is TLS)
    EAP typeEAP type of Wi-Fi
    + +

    Wi-Fi Monitor

    + +

    The Wi-Fi Monitor API (in mobile and wearable applications) provides functions for monitoring the Wi-Fi connection state.

    + +

    The Wi-Fi Monitor allows you to get the state of the Wi-Fi connection. The state can be:

    + +
    • WIFI_CONNECTION_STATE_FAILURE +

      Connection failed.

    • +
    • WIFI_CONNECTION_STATE_DISCONNECTED +

      Disconnected.

    • +
    • WIFI_CONNECTION_STATE_ASSOCIATION +

      Association.

    • +
    • WIFI_CONNECTION_STATE_CONFIGURATION +

      Configuration.

    • +
    • WIFI_CONNECTION_STATE_CONNECTED +

      Connected.

    + +

    The Wi-Fi Monitor also allows monitoring the changes in Wi-Fi. With the Wi-Fi Monitor, you can register callback functions, which notify you when Wi-Fi properties change. The property changes resulting in notifications are listed in the following table.

    + + + + + + + + + + + + + + + + + + + + + +
    + Table: Property changes +
    Change inDescription
    Connection stateThe callback is called when the connection state is changed.
    Device stateThe callback is called when the device state changes.
    RSSI levelThe callback is called when the RSSI of the connected Wi-Fi changes.
    + + + +
    + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/native/porting/porting_n.htm b/org.tizen.guides/html/native/porting/porting_n.htm index 28435ea..8f96592 100644 --- a/org.tizen.guides/html/native/porting/porting_n.htm +++ b/org.tizen.guides/html/native/porting/porting_n.htm @@ -203,10 +203,10 @@ if (uri != NULL)

    When the memory levels in the system are extremely low, the system terminates the application and removes it from the memory. However, it is possible to save the application state or context right before this happens. In the 2.2.1 version, it was done using the Tizen::App::IAppCheckpointEventListener interface. In the new native API, every time when the low level memory situation occurs on the device and the system wants to terminate some application, the app_event_cb() callback in that application is called. When you create your application, remember to place the code that must be executed in case of a low memory level in this callback and set the callback using the ui_app_add_event_handler() function.

    Scene Transitions

    -

    In the old 2.2.1 model, the UI scene transitions were handled by specific listeners, such as the Tizen::Ui::Controls::IFormBackEventListener and its OnFormBackRequested() event handler to listen to the Back key events for a backward scene transition. In the 2.3 model, all such actions are handled using the EFL and EFL Extension. The EFL has its own view manager for applications, called naviframe. A naviframe is a stack which holds views or pages as its items. When another view is launched, it is pushed on the top of the stack. Only the topmost view is displayed. The old views are stored on the stack. The EFL Extension provides functions to send key events to the naviframe top item or to pop it. Every time the user presses the Back key, the current view is removed from the stack and the view that was right under it becomes the topmost view and is displayed. The transition animation between views is handled by the EFL and depends on the theme applied to the UI component.

    +

    In the old 2.2.1 model, the UI scene transitions were handled by specific listeners, such as the Tizen::Ui::Controls::IFormBackEventListener and its OnFormBackRequested() event handler to listen to the Back key events for a backward scene transition. In the 2.3 model, all such actions are handled using the EFL and Hardware Input Handling. The EFL has its own view manager for applications, called naviframe. A naviframe is a stack which holds views or pages as its items. When another view is launched, it is pushed on the top of the stack. Only the topmost view is displayed. The old views are stored on the stack. The EFL Extension provides functions to send key events to the naviframe top item or to pop it. Every time the user presses the Back key, the current view is removed from the stack and the view that was right under it becomes the topmost view and is displayed. The transition animation between views is handled by the EFL and depends on the theme applied to the UI component.

    Hardware Keys

    -

    With the arrival of the EFL, handling the hardware key events has changed. Until now, the 2.2.1 model provided the Tizen::Ui::Controls::IFormMenuEventListener interface. This interface delivered the OnFormMenuRequested() event handler to listen to the hardware Menu key events. Now, all this functionality is obtained using the EFL. In the EFL Extension documentation, find functions which enable you to manipulate the key modifiers. Use them to add handling for the hardware key events.

    +

    With the arrival of the EFL, handling the hardware key events has changed. Until now, the 2.2.1 model provided the Tizen::Ui::Controls::IFormMenuEventListener interface. This interface delivered the OnFormMenuRequested() event handler to listen to the hardware Menu key events. Now, all this functionality is obtained using the EFL. In the Managing Menu and Back Key Events documentation, find functions which enable you to manipulate the key modifiers. Use them to add handling for the hardware key events.

    Exceptions

    Normally in the 2.3 API version, the exceptions model functions return an integer which indicates an error value. Usually, the value is 0 if there are no errors and the name format for this value is MODULE_NAME_ERROR_NONE. As in 2.2.1, the current API provides functions to get and set the last error value in the thread. In the 2.3 version, this functionality and the error enumerations are in the Base module. The following example shows how the current native API returns errors.

    diff --git a/org.tizen.guides/html/native/security/key_manager_n.htm b/org.tizen.guides/html/native/security/key_manager_n.htm index b303d1a..020f0a2 100644 --- a/org.tizen.guides/html/native/security/key_manager_n.htm +++ b/org.tizen.guides/html/native/security/key_manager_n.htm @@ -1,124 +1,124 @@ - - - - - - - - - - - - - Key Manager - - - - - -
    -

    Key Manager

    - -

    The key manager provides functions to securely store keys, certificates, and sensitive data related to users and their password-protected APPs. Additionally, it provides secure cryptographic operations for non-exportable keys without revealing the key values to clients.

    - -

    Figure: Key manager process

    -

    Key manager process

    - -

    A key manager stores keys, certificates, and sensitive user data in a central secure repository. The central secure repository is protected by a password.

    - -

    The main features of the Key Manager API include:

    - -
      -
    • Data store policy -

      A client can specify simple access rules when storing data in the key manager:

      -
        -
      • Extractable or non-extractable -
          -
        • Only for data tagged as extractable, the key manager returns the raw value of the data.
        • -
        • If data is tagged as non-extractable, the key manager does not return its raw value. In that case, the key manager provides secure cryptographic operations for non-exportable keys without revealing the key values to the clients.
      • -
      • Per key password -
          -
        • All data in the key manager is protected by a user password.
        • -
        • A client can encrypt its data using their own password additionally.
        • -
        • If a client provides a password when storing data, the data is encrypted with the password. This password must be provided when getting the data from the key manager.
      • -
      -
    • -
    • User login - -

      The user login control is implemented as follows:

      - -
        -
      • A user's database file is encrypted by the user's DKEK (domain key encryption key). A DKEK of a user is randomly generated and stored as encrypted with a user password when a user logs in for the first time.
      • -
      • When a user logs in, the key manager decrypts the user DKEK with a user password. During the login session, any client can access the data which is protected by a user password. When a user logs out, the key manager removes the user DKEK from the memory.
      • -
      • When a user logs in, logs out, or changes their password, the key manager must be notified. Only privileged APPs, such as LockScreen APP or Setting APP, can notify the key manager.
      • -
      • When a user changes their password, the key manager re-encrypts the user DKEK with the new password.
      • -
      -
    • - -
    • Data access control - -

      By default, only the owner of a data can access to the data. If the owner grants the access to other applications, those applications can read or delete the data from the key manager database.

      -

      When an application is deleted, the data and access control information granted by the application are also removed.

      -
    • -
    - - -

    The key manager provides 2 types of APIs (in mobile and wearable applications):

    - - - - -
    - -Go to top - - - - - - + + + + + + + + + + + + + Key Manager + + + + + +
    +

    Key Manager

    + +

    The key manager provides functions to securely store keys, certificates, and sensitive data related to users and their password-protected APPs. Additionally, it provides secure cryptographic operations for non-exportable keys without revealing the key values to clients.

    + +

    Figure: Key manager process

    +

    Key manager process

    + +

    A key manager stores keys, certificates, and sensitive user data in a central secure repository. The central secure repository is protected by a password.

    + +

    The main features of the Key Manager API include:

    + +
      +
    • Data store policy +

      A client can specify simple access rules when storing data in the key manager:

      +
        +
      • Extractable or non-extractable +
          +
        • Only for data tagged as extractable, the key manager returns the raw value of the data.
        • +
        • If data is tagged as non-extractable, the key manager does not return its raw value. In that case, the key manager provides secure cryptographic operations for non-exportable keys without revealing the key values to the clients.
      • +
      • Per key password +
          +
        • All data in the key manager is protected by a user password.
        • +
        • A client can encrypt its data using their own password additionally.
        • +
        • If a client provides a password when storing data, the data is encrypted with the password. This password must be provided when getting the data from the key manager.
      • +
      +
    • +
    • User login + +

      The user login control is implemented as follows:

      + +
        +
      • A user's database file is encrypted by the user's DKEK (domain key encryption key). A DKEK of a user is randomly generated and stored as encrypted with a user password when a user logs in for the first time.
      • +
      • When a user logs in, the key manager decrypts the user DKEK with a user password. During the login session, any client can access the data which is protected by a user password. When a user logs out, the key manager removes the user DKEK from the memory.
      • +
      • When a user logs in, logs out, or changes their password, the key manager must be notified. Only privileged APPs, such as LockScreen APP or Setting APP, can notify the key manager.
      • +
      • When a user changes their password, the key manager re-encrypts the user DKEK with the new password.
      • +
      +
    • + +
    • Data access control + +

      By default, only the owner of a data can access to the data. If the owner grants the access to other applications, those applications can read or delete the data from the key manager database.

      +

      When an application is deleted, the data and access control information granted by the application are also removed.

      +
    • +
    + + +

    The key manager provides 2 types of APIs (in mobile and wearable applications):

    + + + + +
    + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/native/security/privilege_n.htm b/org.tizen.guides/html/native/security/privilege_n.htm index 72f84b4..17e2b55 100644 --- a/org.tizen.guides/html/native/security/privilege_n.htm +++ b/org.tizen.guides/html/native/security/privilege_n.htm @@ -1,65 +1,65 @@ - - - - - - - - - - - - - Privilege Info - - - - - -
    -

    Privilege Info

    - -

    Tizen provides privilege information for user notification.

    - -

    The following information can be retrieved:

    -
      -
    • Privilege name: Privilege description in a simple present participle form.
    • -
    • Privilege description: Detailed information on permissions, including accessible resources and functionality, that the application can get with this privilege. It also contains information related to billing or device performance, such as cost or increase battery usage.
    • -
    - - - -
    - -Go to top - - - - - - + + + + + + + + + + + + + Privilege Info + + + + + +
    +

    Privilege Info

    + +

    Tizen provides privilege information for user notification.

    + +

    The following information can be retrieved:

    +
      +
    • Privilege name: Privilege description in a simple present participle form.
    • +
    • Privilege description: Detailed information on permissions, including accessible resources and functionality, that the application can get with this privilege. It also contains information related to billing or device performance, such as cost or increase battery usage.
    • +
    + + + +
    + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/native/security/security_guide_n.htm b/org.tizen.guides/html/native/security/security_guide_n.htm index fbab149..ea26b3c 100644 --- a/org.tizen.guides/html/native/security/security_guide_n.htm +++ b/org.tizen.guides/html/native/security/security_guide_n.htm @@ -1,65 +1,65 @@ - - - - - - - - - - - - - Security - - - - - -
    - -

    Security

    -

    Security features include basic cryptographic functions and information on privileges for user notification. You can also use various utility functions provided by the OpenSSL open source library.

    - -

    The main security features are:

    -
      -
    • Key Manager

      Enables you to provide a secure repository for keys, certificates, and sensitive data related to users and their password-protected applications.

    • -
    • Privilege Info

      Enables you to get information about permissions granted by a privilege.

    • -
    - - - -
    - -Go to top - - - - - - + + + + + + + + + + + + + Security + + + + + +
    + +

    Security

    +

    Security features include basic cryptographic functions and information on privileges for user notification. You can also use various utility functions provided by the OpenSSL open source library.

    + +

    The main security features are:

    +
      +
    • Key Manager

      Enables you to provide a secure repository for keys, certificates, and sensitive data related to users and their password-protected applications.

    • +
    • Privilege Info

      Enables you to get information about permissions granted by a privilege.

    • +
    + + + +
    + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/native/social/account_manager_n.htm b/org.tizen.guides/html/native/social/account_manager_n.htm index 5c02faf..e2a793c 100644 --- a/org.tizen.guides/html/native/social/account_manager_n.htm +++ b/org.tizen.guides/html/native/social/account_manager_n.htm @@ -1,366 +1,366 @@ - - - - - - - - - - - - - Account Manager - - - - - -
    - - -

    Account Manager

    - -

    An account is a collection of information representing the user of a specific provider.

    - - - - - - - - - - -
    Note
    This feature is supported in mobile applications only.
    - -

    The main features of the Account Manager API include: -

    -
      -
    • Creating and managing accounts
    • -
    • Retrieving account information
    • -
    • Receiving account change notifications
    • -
    - - - - - - - - - -
    Note
    To add, update, or remove an account, you must register your account provider for all your applications belonging to the same package.
    - -

    The account.h header file handles account-related information. The following table lists the account properties that can be modified.

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    - Table: Account properties -
    Account propertyData typeMandatoryDescription
    User nameStringYesIdentity of an account. -

    If the display name and email address are not set for an account, the user name is shown for the account on the Accounts screen in the Setting application.

    -
    Display nameStringNoDisplay name of an account. -

    Display name is shown for the account on the Accounts screen in the Setting application.

    -
    Email addressStringNoEmail address of an account. -

    If the display name is not set for an account, the email address is shown for the account on the Accounts screen in the Setting application.

    -
    Package nameStringNoOne of an account package IDs, like the app ID. -

    If the package name is not set for an account, the app ID is used as a package name.

    -
    Icon pathStringNoIcon path of an account. -

    The icon is shown through the registered icon path as an account icon on the Accounts screen in the Setting application.

    -
    Domain nameStringNoDomain name of an account. -
    Access tokenStringNoAccess token of an account. -
    Auth typeIntegerNoAuthentication type, such as oauth or xauth. -
    CapabilityKey-value string-integer pairsNoCapability of an account. -
    SecretIntegerNoThe secret value is used to decide whether the account is shown on the Accounts screen in the Setting application. -
    Sync supportIntegerNoCurrent synchronization status.
    SourceStringNoSource of an account. -
    User textStringNoString array which you can use freely. -
    User intIntegerNoInteger array which you can use freely. -
    CustomKey-value string pairsNoKey-value pairs which you can use freely. -
    - -

    Account Providers

    -

    Account providers, such as Google and Facebook, represent specific service provider-related information or protocol that provides the user accounts. To add, update, or remove accounts, you must register a specific account provider in your application.

    -

    To register an account provider, define the account provider information in the Account tab of the manifest editor, as described in the following table, and implement the account application control.

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    - Table: Account provider properties -
    Account propertyData typeMandatoryDescription
    Multiple accounts supportbool YesIndicates whether multiple accounts are supported.
    IconStringYesFile path of the account provider icon. -

    The icon size is:

    -
      -
    • 72 x 72 for Xhigh (HD)
    • -
    • 48 x 48 for High (WVGA)
    • -
    -

    Since the icon is used in Settings > Accounts, place the icon in a shared directory.

    Small iconStringYesFile path of the account provider icon. -

    The icon size is:

    -
      -
    • 45 x 45 for Xhigh (HD)
    • -
    • 30 x 30 for High (WVGA)
    • -
    -

    Since the small icon is used in other applications, place the icon in a shared directory.

    Display nameStringYesDisplay name of the account provider.
    CapabilitiesStringNoCapability of the account provider. -

    Capability can be a liaison between an account application and another application. If an account application registers a capability in the manifest file, other applications know that the account application has the capability. And if an account application gives an account a capability, other applications know that the account has the capability.

    -

    Several service-specific capabilities are defined for the Account Manager in Tizen:

    - -
      -
    • Contact capability: -

      ACCOUNT_SUPPORTS_CAPABILITY_CONTACT or "http://tizen.org/account/capability/contact"

      -

      If you register this capability in the manifest file, the user using the contact application can see a list of accounts with the account of your service in the contact application.

      -
    • -
    • Calendar capability: -

      ACCOUNT_SUPPORTS_CAPABILITY_CALENDAR or "http://tizen.org/account/capability/calendar"

      -

      If you register this capability in the manifest file, the user using the calendar application can see a list of accounts with the account of your service in the calendar application.

      -
    • -
    • Email capability: -

      ACCOUNT_SUPPORTS_CAPABILITY_EMAIL or "http://tizen.org/account/capability/email"

      -
    • -
    • Photo capability: -

      ACCOUNT_SUPPORTS_CAPABILITY_PHOTO or "http://tizen.org/account/capability/photo"

      -
    • -
    • Video capability: -

      ACCOUNT_SUPPORTS_CAPABILITY_VIDEO or "http://tizen.org/account/capability/video"

      -
    • -
    • Music capability: -

      ACCOUNT_SUPPORTS_CAPABILITY_MUSIC or "http://tizen.org/account/capability/music"

      -
    • -
    • Document capability: -

      ACCOUNT_SUPPORTS_CAPABILITY_DOCUMENT or "http://tizen.org/account/capability/document"

      -
    • -
    • Message capability: -

      ACCOUNT_SUPPORTS_CAPABILITY_MESSAGE or "http://tizen.org/account/capability/message"

      -
    • -
    • Game capability: -

      ACCOUNT_SUPPORTS_CAPABILITY_GAME or "http://tizen.org/account/capability/game"

      -
    • -
    -
    - -

    If the application has defined the account provider information and implements the appcontrol for the account provider, the account provider is automatically registered when the application is installed.

    - -

    Account Application Control

    -

    The account application control, which allows the user to add and configure accounts, must be implemented in all applications that define an account provider. You are not required to define the application control information in the Application Control tab of the manifest editor.

    - -

    This application control supports the http://tizen.org/appcontrol/operation/account/add and http://tizen.org/appcontrol/operation/account/configure operations.

    - -

    ACCOUNT_OPERATION_SIGNIN Operation

    -

    The http://tizen.org/appcontrol/operation/account/add operation enables the user to add a new account for a specific account provider. With the operation, the login page for the specific account provider can be displayed. In Settings > Accounts, if the account provider is clicked for adding a new account, this operation is launched.

    - -

    You have to define the app_control_cb() callback and register it to ui_app_lifecycle_callback::app_control.

    - -

    The results of the operation are returned in the app_control_get_operation() event handler.

    -

    The following table shows the ACCOUNT_OPERATION_SIGNIN (http://tizen.org/appcontrol/operation/account/add) operation.

    - - - - - - - - - - - - - - -
    - Table: ACCOUNT_OPERATION_SIGNIN operation -
    OperationDescription
    ACCOUNT_OPERATION_SIGNINAccount ID of the added account.
    -

    ACCOUNT_OPERATION_VIEW Operation

    -

    The http://tizen.org/appcontrol/operation/account/configure operation enables the user to set account information, such as synchronization settings. The delete button must be included for removing accounts.

    -

    In Settings > Accounts, if the specific account is clicked for setting the account information, this operation is launched.

    -

    You have to define the app_control_cb() callback and register it to ui_app_lifecycle_callback::app_control.

    -

    The results of the operation are returned in the app_control_get_operation() event handler.

    -

    The following table shows the ACCOUNT_OPERATION_VIEW (http://tizen.org/appcontrol/operation/account/configure) operation.

    - - - - - - - - - - - - - - -
    - Table: ACCOUNT_OPERATION_VIEW operation -
    OperationDescription
    ACCOUNT_OPERATION_VIEWAccount ID for setting account information.
    - - - -
    - -Go to top - - - - - + + + + + + + + + + + + + Account Manager + + + + + +
    + + +

    Account Manager

    + +

    An account is a collection of information representing the user of a specific provider.

    + + + + + + + + + + +
    Note
    This feature is supported in mobile applications only.
    + +

    The main features of the Account Manager API include: +

    +
      +
    • Creating and managing accounts
    • +
    • Retrieving account information
    • +
    • Receiving account change notifications
    • +
    + + + + + + + + + +
    Note
    To add, update, or remove an account, you must register your account provider for all your applications belonging to the same package.
    + +

    The account.h header file handles account-related information. The following table lists the account properties that can be modified.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + Table: Account properties +
    Account propertyData typeMandatoryDescription
    User nameStringYesIdentity of an account. +

    If the display name and email address are not set for an account, the user name is shown for the account on the Accounts screen in the Setting application.

    +
    Display nameStringNoDisplay name of an account. +

    Display name is shown for the account on the Accounts screen in the Setting application.

    +
    Email addressStringNoEmail address of an account. +

    If the display name is not set for an account, the email address is shown for the account on the Accounts screen in the Setting application.

    +
    Package nameStringNoOne of an account package IDs, like the app ID. +

    If the package name is not set for an account, the app ID is used as a package name.

    +
    Icon pathStringNoIcon path of an account. +

    The icon is shown through the registered icon path as an account icon on the Accounts screen in the Setting application.

    +
    Domain nameStringNoDomain name of an account. +
    Access tokenStringNoAccess token of an account. +
    Auth typeIntegerNoAuthentication type, such as oauth or xauth. +
    CapabilityKey-value string-integer pairsNoCapability of an account. +
    SecretIntegerNoThe secret value is used to decide whether the account is shown on the Accounts screen in the Setting application. +
    Sync supportIntegerNoCurrent synchronization status.
    SourceStringNoSource of an account. +
    User textStringNoString array which you can use freely. +
    User intIntegerNoInteger array which you can use freely. +
    CustomKey-value string pairsNoKey-value pairs which you can use freely. +
    + +

    Account Providers

    +

    Account providers, such as Google and Facebook, represent specific service provider-related information or protocol that provides the user accounts. To add, update, or remove accounts, you must register a specific account provider in your application.

    +

    To register an account provider, define the account provider information in the Account tab of the manifest editor, as described in the following table, and implement the account application control.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + Table: Account provider properties +
    Account propertyData typeMandatoryDescription
    Multiple accounts supportbool YesIndicates whether multiple accounts are supported.
    IconStringYesFile path of the account provider icon. +

    The icon size is:

    +
      +
    • 72 x 72 for Xhigh (HD)
    • +
    • 48 x 48 for High (WVGA)
    • +
    +

    Since the icon is used in Settings > Accounts, place the icon in a shared directory.

    Small iconStringYesFile path of the account provider icon. +

    The icon size is:

    +
      +
    • 45 x 45 for Xhigh (HD)
    • +
    • 30 x 30 for High (WVGA)
    • +
    +

    Since the small icon is used in other applications, place the icon in a shared directory.

    Display nameStringYesDisplay name of the account provider.
    CapabilitiesStringNoCapability of the account provider. +

    Capability can be a liaison between an account application and another application. If an account application registers a capability in the manifest file, other applications know that the account application has the capability. And if an account application gives an account a capability, other applications know that the account has the capability.

    +

    Several service-specific capabilities are defined for the Account Manager in Tizen:

    + +
      +
    • Contact capability: +

      ACCOUNT_SUPPORTS_CAPABILITY_CONTACT or "http://tizen.org/account/capability/contact"

      +

      If you register this capability in the manifest file, the user using the contact application can see a list of accounts with the account of your service in the contact application.

      +
    • +
    • Calendar capability: +

      ACCOUNT_SUPPORTS_CAPABILITY_CALENDAR or "http://tizen.org/account/capability/calendar"

      +

      If you register this capability in the manifest file, the user using the calendar application can see a list of accounts with the account of your service in the calendar application.

      +
    • +
    • Email capability: +

      ACCOUNT_SUPPORTS_CAPABILITY_EMAIL or "http://tizen.org/account/capability/email"

      +
    • +
    • Photo capability: +

      ACCOUNT_SUPPORTS_CAPABILITY_PHOTO or "http://tizen.org/account/capability/photo"

      +
    • +
    • Video capability: +

      ACCOUNT_SUPPORTS_CAPABILITY_VIDEO or "http://tizen.org/account/capability/video"

      +
    • +
    • Music capability: +

      ACCOUNT_SUPPORTS_CAPABILITY_MUSIC or "http://tizen.org/account/capability/music"

      +
    • +
    • Document capability: +

      ACCOUNT_SUPPORTS_CAPABILITY_DOCUMENT or "http://tizen.org/account/capability/document"

      +
    • +
    • Message capability: +

      ACCOUNT_SUPPORTS_CAPABILITY_MESSAGE or "http://tizen.org/account/capability/message"

      +
    • +
    • Game capability: +

      ACCOUNT_SUPPORTS_CAPABILITY_GAME or "http://tizen.org/account/capability/game"

      +
    • +
    +
    + +

    If the application has defined the account provider information and implements the appcontrol for the account provider, the account provider is automatically registered when the application is installed.

    + +

    Account Application Control

    +

    The account application control, which allows the user to add and configure accounts, must be implemented in all applications that define an account provider. You are not required to define the application control information in the Application Control tab of the manifest editor.

    + +

    This application control supports the http://tizen.org/appcontrol/operation/account/add and http://tizen.org/appcontrol/operation/account/configure operations.

    + +

    ACCOUNT_OPERATION_SIGNIN Operation

    +

    The http://tizen.org/appcontrol/operation/account/add operation enables the user to add a new account for a specific account provider. With the operation, the login page for the specific account provider can be displayed. In Settings > Accounts, if the account provider is clicked for adding a new account, this operation is launched.

    + +

    You have to define the app_control_cb() callback and register it to ui_app_lifecycle_callback::app_control.

    + +

    The results of the operation are returned in the app_control_get_operation() event handler.

    +

    The following table shows the ACCOUNT_OPERATION_SIGNIN (http://tizen.org/appcontrol/operation/account/add) operation.

    + + + + + + + + + + + + + + +
    + Table: ACCOUNT_OPERATION_SIGNIN operation +
    OperationDescription
    ACCOUNT_OPERATION_SIGNINAccount ID of the added account.
    +

    ACCOUNT_OPERATION_VIEW Operation

    +

    The http://tizen.org/appcontrol/operation/account/configure operation enables the user to set account information, such as synchronization settings. The delete button must be included for removing accounts.

    +

    In Settings > Accounts, if the specific account is clicked for setting the account information, this operation is launched.

    +

    You have to define the app_control_cb() callback and register it to ui_app_lifecycle_callback::app_control.

    +

    The results of the operation are returned in the app_control_get_operation() event handler.

    +

    The following table shows the ACCOUNT_OPERATION_VIEW (http://tizen.org/appcontrol/operation/account/configure) operation.

    + + + + + + + + + + + + + + +
    + Table: ACCOUNT_OPERATION_VIEW operation +
    OperationDescription
    ACCOUNT_OPERATION_VIEWAccount ID for setting account information.
    + + + +
    + +Go to top + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/native/social/calendar_n.htm b/org.tizen.guides/html/native/social/calendar_n.htm index daf8dfc..b4af62e 100644 --- a/org.tizen.guides/html/native/social/calendar_n.htm +++ b/org.tizen.guides/html/native/social/calendar_n.htm @@ -1,742 +1,742 @@ - - - - - - - - - - - - - Calendar - - - - - -
    - - -

    Calendar

    - -

    A calendar is a system of organizing days for social purposes. It is composed of records, such as events and todos. The records consist of subrecords, such as alarms, attendees, or extensions. For example, if an event has a recurrence rule (meaning that it happens multiple times), separate instances are generated for each time the event occurs.

    - - - - - - - - - - -
    Note
    This feature is supported in mobile applications only.
    - -

    Figure: Calendar model

    -

    Calendar model

    - -

    The Calendar Service supports vCalendars.

    - -

    The main features of the Calendar API include:

    -
      -
    • Calendar books -
        -
      • Determine where the events and todos belong.
      • -
      • Create calendar books using the local device (with no account), service providers, such as Google or Yahoo (with an account), or applications, such as ChatON, Joyn, or Facebook.
      • -
      • Search and organize events using filters and queries.
      • -
      • Monitor database changes.
      • -
      -

      Each account can have multiple calendar books. The calendar book name does not need to be unique on the device because it is handled with an ID. Since the local device address book has no account, its related account ID is zero.

      -
    • -
    • Events and tasks -
        -
      • Set properties, such as summary, start time, and description.
      • -
      • Set reminders.
      • -
      -
    • -
    • Time management -
        -
      • Define the calendar UTC time and date.
      • -
      -
    • -
    - -

    The following figure illustrates the different Calendar entities and their relationships.

    - -

    Figure: Calendar entities

    -

    Calendar entities

    - -

    vCalendar supports ver1.0 (vcs) and 2.0 (ics). For more information about vCalendar, see rfc2445.

    - -

    The calendar service module works in a way similar to client-service architecture. In this architecture, the Tizen application is the client side and has to connect to service before using calendar service APIs. Use calendar_connect() and calendar_disconnect() for connecting and disconnecting.

    -
    -calendar_connect();
    -
    -// Jobs for records
    -
    -calendar_disconnect();
    -
    - -

    Calendar Books

    - -

    A calendar book is a placeholder for other records in the Calendar API. Every event and todo has to belong to a calendar book. There are 3 built-in calendar books, as shown in the following table.

    - - - - - - - - - - - - - - - - - - - - - -
    - Table: Calendar books -
    BookDescription
    DEFAULT_EVENT_CALENDAR_BOOK_IDEvent book
    DEFAULT_TODO_CALENDAR_BOOK_IDTodo book
    DEFAULT_BIRTHDAY_CALENDAR_BOOK_IDBirthday book
    - -The following code example sets a calendar book ID. -
    -calendar_record_h event = NULL;
    -
    -calendar_record_create(_calendar_event._uri, &event);
    -
    -// Set default calendar book id
    -calendar_record_set_int(event, _calendar_event.calendar_id, DEFAULT_EVENT_CALENDAR_BOOK_ID);
    -
    -// Set other fields
    -
    -int event_id = 0;
    -calendar_db_insert_record(event &event_id);
    -
    -// Destroy
    -calendar_record_destroy(event, true);
    -
    - - -

    To receive a list of existing calendar books, use the following code:

    -
    calendar_list_h calendar_book_list = NULL;
    -calendar_db_get_all_records(_calendar_calendar_book._uri, 0, 0, &calendar_book_list);
    - -

    In the calendar_db_get_all_records() function, you need as parameters the URI of the view to get records from, the index from which results are received, the maximum number of results, and the record list.

    - -

    Database Change Notifications

    - -

    To detect the calendar database changes, register a callback with the calendar_db_add_changed_cb() function. To unregister the callback and ignore database changes, use the calendar_db_remove_changed_cb() function.

    -

    Clients wait calendar change notifications on the client side. If the calendar is changed by another module, the server publishes an inotify event. The Inotify module broadcasts to the subscribed modules, and an internal inotify handler is called at the client side. A user callback function is called with the user data.

    -
    // Add callback function
    -void __event_changed_ cb(const char *view_uri, void *user_data) {}
    -// Add change notification callback
    -calendar_db_add_changed_cb(_calendar_event._uri, __event_changed_cb, NULL);
    - -

    Events and Instances

    -

    An event record describes various properties, such as description, categories, and priority. It also contains information on when the event takes place. In a recurring event, there are more than one instance of the event. Each instance has its corresponding instance record.

    -

    If an event is inserted with rrule (recurrence rule), alarm, and attendee, its data is saved to each database. Generated instances based on the rrule are also stored in the instance database.

    - -

    Figure: Views and databases

    -

    Views and databases

    - -

    The following table illustrates and example of a recurring event and its instances.

    - - - - - - - - - - - - - -
    - Table: Event and instance example -
    EventInstances
    Recurrence rules: -
    • Start date on 2012-10-09 (Tuesday)
    • -
    • Frequency set to WEEKLY
    • -
    • Interval set to 1
    • -
    • Count set to 3
    2012-10-09 Tuesday -

    2012-10-16 Tuesday

    -

    2012-10-22 Tuesday

    -

    The recurrence model in the Calendar API is compliant with the iCalendar specification. The following event properties have the same functionality as their corresponding values in iCalendar:

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    - Table: Recurrence rules -
    Recurrence rule propertyDescription
    freqYearly, monthly, weekly, or daily
    countUntil count. If the count is 3, 3 instances are generated.
    intervalInterval is a positive integer representing how often the recurrence rule repeats
    bydayMO, TU, WE, TH, FR, SA, or SU
    bymonthdayDays of the month
    byyeardayDays of the year
    byweeknoOrdinals specifying weeks of the year
    bymonthMonths of the year
    bysetposValues which correspond to the nth occurrence within the set of events
    wkstDay on which the workweek starts
    - -

    Exceptions

    -

    If one of the instances of a recurring event is modified (such as its summary or date) or deleted, it is called an exception. For example, if 2nd instance date is modified from 16th to 17th, 17th is the exception.

    - - - - - - - - - - - - - - - - -
    - Table: Exception example -
    EventInstancesExceptions
    Recurrence rules: -
    • Start date on 2012-10-09 (Tuesday)
    • -
    • Frequency set to WEEKLY
    • -
    • Interval set to 1
    • -
    • Count set to 3
    -
    2012-10-09 Tuesday -

    2012-10-16 Tuesday > modified

    -

    2012-10-22 Tuesday

    2012-10-17 Tuesday
    - -

    To get the changes in an exception, use the calendar_db_get_changes_exception_by_version() function. The instances and exceptions are deleted together when the original event is deleted.

    - -

    Filters and Queries

    -

    Queries are used to retrieve data which satisfies a given criteria, like an integer property being greater than a given value, or a string property containing a given substring. The criteria are defined by creating filters and adding conditions to them, joining them with logical operators. Also, instead of a condition, another filter can be added to create more complex filters.

    -

    When a filter is ready, it can be set as a property of a query. Other query properties allow configuring how the returned results are grouped and sorted.

    -

    The operator precedence in filters is determined by the order in which the conditions and filters are added. The following table shows an example of how the operator precedence works.

    - - - - - - - - - - - - - - - - - -
    - Table: Filter conditions -
    ConditionResult
    Condition C1
    -OR
    -Condition C2
    -AND
    -Condition C3
    (C1 OR C2) AND C3
    Filter F1:
    - Condition C1
    - OR
    - Condition C2
    -
    -Filter F2:
    - Condition C3
    - OR
    - Condition C4
    -
    -Filter F3:
    - Condition C5
    - AND
    - F1
    - AND
    - F2
    (C5 AND F1) AND F2
    -Meaning (C5 AND (C1 OR C2)) AND (C3 OR C4)
    - -

    The following code creates a filter, accepting events with high priority or those that include the word "meeting" in their description.

    -
    calendar_filter_h filter = NULL;
    - 
    -// Create a filter returning event type records
    -calendar_filter_create(_calendar_event._uri, &filter);
    - 
    -// Add a 'priority equals high' condition
    -calendar_filter_add_int(filter, _calendar_event.priority, CALENDAR_MATCH_EQUAL, CALENDAR_EVENT_PRIORITY_HIGH);
    - 
    -// Add OR operator
    -calendar_filter_add_operator(filter, CALENDAR_FILTER_OPERATOR_OR);
    - 
    -// Add a 'description contains "meeting"' condition
    -calendar_filter_add_str(filter, _calendar_event.description, CALENDAR_MATCH_CONTAINS, "meeting");
    - -

    Insert the filter into the query and execute the query:

    - -
    calendar_query_h query = NULL;
    -calendar_list_h list = NULL;
    - 
    -// Create a query returning event type records
    -calendar_query_create(_calendar_event._uri, &query);
    - 
    -// Add the filter
    -calendar_query_set_filter(query, filter);
    - 
    -// Execute the query, results are returned in a list
    -calendar_db_get_records_with_query(query, 0, 0, &list);
    - 
    -calendar_filter_destroy(filter);
    -calendar_query_destroy(query);
    - 
    -// Use the list
    - 
    -calendar_list_destroy(list, true);
    - -

    Projections

    -

    Projection is related to searching with filters and queries. A projection allows you to query the data for just those specific properties of a record that you actually need, at lower latency and cost than retrieving the entire set of properties.

    - -

    The following example code creates a filter that gets only the event ID, summary, and start time from those records whose summary has "test" (string filter). It creates a query, adds the filter to it, and receives the results in a list.

    - -
    calendar_query_h query = NULL;
    -calendar_filter_h filter = NULL;
    -
    -// Set query with filter
    -calendar_query_create(_calendar_event_calendar_book_attendee._uri, &query);
    -calendar_filter_create(_calendar_event_calendar_book_attendee._uri, &filter);
    -calendar_filter_add_str(filter, _calendar_event.summary, CALENDAR_MATCH_CONTAINS, "test");
    -calendar_query_set_filter(query, filter);
    -
    -// Set projection
    -unsigned int projection[3];
    -projection[0] = _calendar_event_calendar_book_attendee.event_id;
    -projection[1] = _calendar_event_calendar_book_attendee.summary;
    -projection[2] = _calendar_event_calendar_book_attendee.start_time;
    -
    -// Get list
    -calendar_query_set_projection(query, projection, 3);
    -calendar_db_get_records_with_query(query, 0, 0, &list);
    -
    -// Destroy handle
    -calendar_filter_destroy(filter);
    -calendar_query_destroy(query);
    -calendar_list_destroy(list, true);
    - -

    Records

    - -

    An important concept in the Calendar Service APIs is a record. Although a record represents an actual record in the internal database, you can consider it as a structure describing a single (but complex) entity, like a calendar event or a time zone.

    - -

    A record has many properties, for example, a todo record has the todo description, priority, progress, creation time, last modified and completed time, and many others.

    -

    A record can also contain an identifier field, which holds an ID of another record. Setting this field's value establishes a relation between the records, for example, a calendar event contains the ID of a calendar book to which it belongs.

    - -

    URI

    -

    A record type is identified by a structure called the view. For example, the _calendar_event view describes the properties of the calendar event record. Every view has a special field - _uri - that uniquely identifies the view. In many cases, you must provide the _uri value to indicate what type of record you want to create or operate on.

    -
    // Create an event with _calendar_event view
    -calendar_record_h record = NULL;
    -calendar_record_create(_calendar_event._uri, &record);
    -
    - -

    Record Handle

    -

    To use a record, you must obtain its handle. You can use many methods to obtain the handle, for example, you can create a new record or refer to the child records of a record.

    -
    // Create an event and get a handle
    -calendar_record_h event = NULL;
    -calendar_record_create(_calendar_event._uri, &event);
    -
    -// Get the record handle with ID
    -calendar_record_h event2 = NULL;
    -calendar_db_get_record(_calendar_event._uri, event_id, &event2);
    - -

    Basic Types

    -

    Records contain properties of basic types: integer, lli (long integer, long long int), double, string, bool, and time. The time type holds either a long long int, or 3 integers (year, month, day).

    - -

    The following table lists the setter and getter functions for each type.

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    - Table: Setter and getter functions -
    PropertySetterGetter
    integercalendar_record_set_intcalendar_record_get_int
    long long integercalendar_record_set_llicalendar_record_get_lli
    doublecalendar_record_set_doublecalendar_record_get_double
    stringcalendar_record_set_strcalendar_record_get_str
    calendar_time_scalendar_record_set_caltimecalendar_record_get_caltime
    - -

    Children

    -

    Certain type of records hold "child list" properties. If a record has a property of this type, it can be a parent of other records, called child records. For example, the attendee records can hold an event identifier in their event_id property. The event is the parent record of the child attendee records.

    - -

    The following code example creates an event and inserts it into the default event book.

    - -
    // Create an event
    -calendar_record_h event = NULL;
    -calendar_record_create(_calendar_event._uri, &event);
    - 
    -// Set event summary
    -calendar_record_set_str(event, _calendar_event.summary, "Meeting");
    - 
    -// Put the event into the default calendar book for events
    -calendar_record_set_int(event, _calendar_event.calendar_book_id, book_id);
    - 
    -// Insert calendar book into the database
    -int event_id = 0;
    -calendar_db_insert_record(event, &event_id);
    -
    -// Destroy
    -calendar_record_destroy(event, true);
    - -

    Reminders

    - -

    When an alarm is triggered, the calendar service sends a notification to the package which is registered in the reminder database table by using the calendar_reminder_add_receiver() function.

    - -

    The following figure illustrates how the alarm process works.

    - -

    Figure: Alarm process

    -

    Alarm process

    - -

    After you add a receiver, the registered alarm is triggered at the reserved time if you insert the alarm as a child to an event record:

    -
    // Set alarm
    -calendar_record_h alarm = NULL;
    -calendar_record_create(_calendar_alarm._uri, &alarm);
    -calendar_record_set_int(alarm, _calendar_alarm.tick_unit, CALENDAR_ALARM_TIME_UNIT_SPECIFIC);
    -calendar_record_set_lli(alarm, _calendar_alarm.time, (1404036000 - 60)); // Before 60 sec
    -
    -// Add alarm as child
    -calendar_record_add_child_record(event, _calendar_event.calendar_alarm, alarm);
    - - - - -

    Time Structure

    -

    The calendar time structure, calendar_caltime_s, is defined as follows:

    -
    typedef struct
    -{
    -   calendar_time_type_e type;
    -   union 
    -   {
    -      long long int utime;
    -      struct 
    -      {
    -         int year;
    -         int month;
    -         int mday;
    -      } date;
    -   } time;
    -} calendar_time_s;
    -

    Use this structure when setting the calendar time (_CALENDAR_PROPERTY_CALTIME) properties of the records.

    -

    The time structure can hold 2 types of data: UTC time (long long int) and date, given as year, month, and day of the month (3 integers). These types are identified by the values of the calendar_time_type_e variable, and they determine the usage of the structure.

    - - - - - - - - - - - - - - - - - - - - - - - -
    - Table: Data types -
    IdentifierTypeNamePurpose
    CALENDAR_TIME_UTIMElong long intutimeUTC time, used to describe non-all-day events
    CALENDAR_TIME_LOCALTIMEstructdateDate only (year, month, and day of the month), used to describe all day events.
    - -

    UTC Time Usage

    -

    Structures with UTC time are used for non-all-day events. In such cases, you must convert local time to UTC time. The local time zone identifier must be stored in the record, in the corresponding property.

    -

    For example, when setting the start time of an event, the local time zone must be stored in the start_tzid property.

    -

    When converting local time to UTC time, use the function illustrated in the following example. It converts the given date and time to the corresponding UTC time, considering the given time zone (first argument). The function uses the i18n API.

    - -
    #define ms2sec(ms) (long long int)(ms / 1000.0)
    - 
    -long long int _time_convert_itol(char *tzid, int y, int mon, int d, int h, int min, int s)
    -{
    -   int ret = 0;
    -   i18n_uchar utf16_timezone[64] = {0};
    -   i18n_ustring_copy_ua_n(utf16_timezone, tzid, sizeof(utf16_timezone)/sizeof(i18n_uchar));
    -
    -   i18n_ucalendar_h ucal = NULL;
    -   char *loc_default = NULL;
    -
    -   i18n_ulocale_get_default((const char **)&loc_default);
    -   ret = i18n_ucalendar_create(utf16_timezone, -1, loc_default, I18N_UCALENDAR_GREGORIAN, &ucal);
    -   if (I18N_ERROR_NONE != ret) 
    -   {
    -      dlog_print(DLOG_DEBUG, LOG_TAG, "i18n_ucalendar_create() is failed (%d)\n", ret);
    -
    -      return -1;
    -   }
    -
    -   i18n_ucalendar_set_date_time(ucal, y, mon - 1, d, h, min, s);
    -
    -   i18n_udate date;
    -   ret = i18n_ucalendar_get_milliseconds(ucal, &date);
    -   if (I18N_ERROR_NONE != ret) 
    -   {
    -      dlog_print(DLOG_DEBUG, LOG_TAG, "i18n_ucalendar_create() is failed (%d)\n", ret);
    -      i18n_ucalendar_destroy(ucal);
    -
    -      return -1;
    -   }
    -   i18n_ucalendar_destroy(ucal);
    -
    -   return ms2sec(date);
    -}
    - - -
    // Fill calendar time structures (start and end time)
    -calendar_time_s st = {0};
    -calendar_time_s et = {0};
    - 
    -st.type = CALENDAR_TIME_UTIME;
    -st.time.utime = _time_convert_itol("Asia/Seoul", 2012, 9, 15, 11, 0, 0);
    - 
    -et.type = CALENDAR_TIME_UTIME;
    -et.time.utime = _time_convert_itol("Asia/Seoul", 2012, 9, 15, 12, 0, 0);
    - 
    -// Create an event record
    - 
    -// Set local time zone of start time
    -calendar_record_set_str(event, _calendar_event.start_tzid, "Asia/Seoul");
    - 
    -// Set start time
    -calendar_record_set_caltime(event, _calendar_event.start_time, st);
    - 
    -// Set local time zone of end time
    -calendar_record_set_str(event, _calendar_event.end_tzid, "Asia/Seoul");
    - 
    -// Set end time
    -calendar_record_set_caltime(event, _calendar_event.end_time, et);
    - -

    Date Usage

    -

    Another usage of the time structure is an all day event. In case of such events, the structure type field must be set to CALENDAR_TIME_LOCALTIME. Only the date (no time) is stored. Such structures can be used to set the start and end time of an event.

    -

    Both start and end time of the event must be set, and they do not have to be equal. If they are not, the event lasts more than 1 day. Note that in such cases there are no instances created, as this is still a non-recurring event.

    - -

    Views and Properties

    - -

    Generic access functions can be used (according to data-view declarations) to access calendar views. A data-view is almost the same as a database "VIEW", which limits access and guarantees performance. A "record" represents a single row of the data-views.

    -

    The _calendar_instance_normal and _calendar_instance_allday views are not offered, but combinations with another views are provided.

    - - - - - - - - - - - - - -
    - Table: Calendar views -
    Editable viewRead-only view
    _calendar_book
    -_calendar_event
    -_calendar_todo
    -_calendar_timezone
    -_calendar_attendee
    -_calendar_alarm
    -_calendar_extended_property
    _calendar_updated_info
    -_calendar_event_calendar_book
    -_calendar_todo_calendar_book
    -_calendar_event_calendar_book_attendee
    -_calendar_instance_normal_calendar_book
    -_calendar_instance_allday_calendar_book
    -_calendar_instance_normal_calendar_book_extended
    -_calendar_instance_allday_calendar_book_extended
    - -

    The _calendar_updated_info view is used when identifying record changes depending on the version. The other read-only views are a combination of editable views for UI convenience:

    -
    • _calendar_event + _calendar_book = _calendar_event_calendar_book
    • -
    • _calendar_instance_normal + _calendar_book = _calendar_instance_normal_calendar_book
    • -
    • _calendar_event + _calendar_book + _calendar_attendee = _calendar_event_calendar_book_attendee
    - -

    Properties

    -

    The record types that have *_id as their property hold identifiers of other records. For example, the attendee and alarm views hold the ID of their corresponding events or todos in the event_id or todo_id property (as children of the corresponding event or todo records).

    -

    The record type properties are other records. For example, an event record has attendee and alarm properties, which means that records of those types can be children of the event type records. The following figure illustrates macros in a calendar_view.h header file.

    - -

    Figure: Properties

    -

    Properties

    - -
    // Create an event with _calendar_event view
    -calendar_record_h event = NULL;
    -calendar_record_create(_calendar_event._uri, &event);
    - 
    -// Set event summary to _calendar_event view
    -calendar_record_set_str(event, _calendar_event.summary, "Meeting");
    -
    - -

    Version

    -

    The calendar service uses a version system in the following APIs:

    -
    int calendar_db_get_current_version(int *calendar_db_version);
    -int calendar_db_get_changes_by_version(..., int *current_calendar_db_version);
    -int calendar_db_get_last_change_version(int *last_change_version);
    -int calendar_db_get_changes_exception_by_version(..., int calendar_db_version, ...);
    - -

    Whenever modifications are made in the database, the version number is increased. If sync applications, such as Google or Facebook, sync at version 13 and try to sync again every 1 minute, they want to get the changes from version 14 to the current version.

    -

    To get the current version, the calendar_db_get_current_version() function is used. The calendar_db_get_changes_by_version() function retrieves the modified record list. The calendar_db_get_changes_exception_by_version() function is used to get modified instances in a recurring event.

    - -

    vCalendar

    -

    Use vCalendar to exchange personal calendar and schedule information. In order to avoid confusion with this referenced work, this is to be known as the vCalendar specification. vCalendar ver2.0 is known as iCalendar. The following snippet shows an example of the vCalendar.

    -
    -BEGIN:VCALENDAR
    -VERSION:2.0
    -PRODID:-//hacksw/handcal//NONSGML v1.0//EN
    -BEGIN:VEVENT
    -DTSTART:19970714T170000Z
    -DTEND:19970715T035959Z
    -SUMMARY:Bastille Day Party
    -END:VEVENT
    -END:VCALENDAR
    -
    - -

    The calendar service provides APIs to compose a vCalendar stream. With the stream, it is possible to create files transmit data with JSON data.

    -
    -calendar_list_h list = NULL;
    -// Create or get list to make vcalendar stream
    -
    -char *stream = NULL;
    -calendar_vcalendar_make_from_records(list, &stream);
    -
    -// Jobs for stream
    -
    -// Free
    -free(stream);
    -
    - -

    vCalendar can be parsed with calendar service APIs as well.

    -
    -// Read stream from file
    -
    -calendar_list_h list = NULL;
    -calendar_vcalendar_parse_to_calendar(stream, &list);
    -
    -// Jobs for list
    -calendar_list_destroy(list, true);
    -
    - - - -
    - -Go to top - - - - - + + + + + + + + + + + + + Calendar + + + + + +
    + + +

    Calendar

    + +

    A calendar is a system of organizing days for social purposes. It is composed of records, such as events and todos. The records consist of subrecords, such as alarms, attendees, or extensions. For example, if an event has a recurrence rule (meaning that it happens multiple times), separate instances are generated for each time the event occurs.

    + + + + + + + + + + +
    Note
    This feature is supported in mobile applications only.
    + +

    Figure: Calendar model

    +

    Calendar model

    + +

    The Calendar Service supports vCalendars.

    + +

    The main features of the Calendar API include:

    +
      +
    • Calendar books +
        +
      • Determine where the events and todos belong.
      • +
      • Create calendar books using the local device (with no account), service providers, such as Google or Yahoo (with an account), or applications, such as ChatON, Joyn, or Facebook.
      • +
      • Search and organize events using filters and queries.
      • +
      • Monitor database changes.
      • +
      +

      Each account can have multiple calendar books. The calendar book name does not need to be unique on the device because it is handled with an ID. Since the local device address book has no account, its related account ID is zero.

      +
    • +
    • Events and tasks +
        +
      • Set properties, such as summary, start time, and description.
      • +
      • Set reminders.
      • +
      +
    • +
    • Time management +
        +
      • Define the calendar UTC time and date.
      • +
      +
    • +
    + +

    The following figure illustrates the different Calendar entities and their relationships.

    + +

    Figure: Calendar entities

    +

    Calendar entities

    + +

    vCalendar supports ver1.0 (vcs) and 2.0 (ics). For more information about vCalendar, see rfc2445.

    + +

    The calendar service module works in a way similar to client-service architecture. In this architecture, the Tizen application is the client side and has to connect to service before using calendar service APIs. Use calendar_connect() and calendar_disconnect() for connecting and disconnecting.

    +
    +calendar_connect();
    +
    +// Jobs for records
    +
    +calendar_disconnect();
    +
    + +

    Calendar Books

    + +

    A calendar book is a placeholder for other records in the Calendar API. Every event and todo has to belong to a calendar book. There are 3 built-in calendar books, as shown in the following table.

    + + + + + + + + + + + + + + + + + + + + + +
    + Table: Calendar books +
    BookDescription
    DEFAULT_EVENT_CALENDAR_BOOK_IDEvent book
    DEFAULT_TODO_CALENDAR_BOOK_IDTodo book
    DEFAULT_BIRTHDAY_CALENDAR_BOOK_IDBirthday book
    + +The following code example sets a calendar book ID. +
    +calendar_record_h event = NULL;
    +
    +calendar_record_create(_calendar_event._uri, &event);
    +
    +// Set default calendar book id
    +calendar_record_set_int(event, _calendar_event.calendar_id, DEFAULT_EVENT_CALENDAR_BOOK_ID);
    +
    +// Set other fields
    +
    +int event_id = 0;
    +calendar_db_insert_record(event &event_id);
    +
    +// Destroy
    +calendar_record_destroy(event, true);
    +
    + + +

    To receive a list of existing calendar books, use the following code:

    +
    calendar_list_h calendar_book_list = NULL;
    +calendar_db_get_all_records(_calendar_calendar_book._uri, 0, 0, &calendar_book_list);
    + +

    In the calendar_db_get_all_records() function, you need as parameters the URI of the view to get records from, the index from which results are received, the maximum number of results, and the record list.

    + +

    Database Change Notifications

    + +

    To detect the calendar database changes, register a callback with the calendar_db_add_changed_cb() function. To unregister the callback and ignore database changes, use the calendar_db_remove_changed_cb() function.

    +

    Clients wait calendar change notifications on the client side. If the calendar is changed by another module, the server publishes an inotify event. The Inotify module broadcasts to the subscribed modules, and an internal inotify handler is called at the client side. A user callback function is called with the user data.

    +
    // Add callback function
    +void __event_changed_ cb(const char *view_uri, void *user_data) {}
    +// Add change notification callback
    +calendar_db_add_changed_cb(_calendar_event._uri, __event_changed_cb, NULL);
    + +

    Events and Instances

    +

    An event record describes various properties, such as description, categories, and priority. It also contains information on when the event takes place. In a recurring event, there are more than one instance of the event. Each instance has its corresponding instance record.

    +

    If an event is inserted with rrule (recurrence rule), alarm, and attendee, its data is saved to each database. Generated instances based on the rrule are also stored in the instance database.

    + +

    Figure: Views and databases

    +

    Views and databases

    + +

    The following table illustrates and example of a recurring event and its instances.

    + + + + + + + + + + + + + +
    + Table: Event and instance example +
    EventInstances
    Recurrence rules: +
    • Start date on 2012-10-09 (Tuesday)
    • +
    • Frequency set to WEEKLY
    • +
    • Interval set to 1
    • +
    • Count set to 3
    2012-10-09 Tuesday +

    2012-10-16 Tuesday

    +

    2012-10-22 Tuesday

    +

    The recurrence model in the Calendar API is compliant with the iCalendar specification. The following event properties have the same functionality as their corresponding values in iCalendar:

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + Table: Recurrence rules +
    Recurrence rule propertyDescription
    freqYearly, monthly, weekly, or daily
    countUntil count. If the count is 3, 3 instances are generated.
    intervalInterval is a positive integer representing how often the recurrence rule repeats
    bydayMO, TU, WE, TH, FR, SA, or SU
    bymonthdayDays of the month
    byyeardayDays of the year
    byweeknoOrdinals specifying weeks of the year
    bymonthMonths of the year
    bysetposValues which correspond to the nth occurrence within the set of events
    wkstDay on which the workweek starts
    + +

    Exceptions

    +

    If one of the instances of a recurring event is modified (such as its summary or date) or deleted, it is called an exception. For example, if 2nd instance date is modified from 16th to 17th, 17th is the exception.

    + + + + + + + + + + + + + + + + +
    + Table: Exception example +
    EventInstancesExceptions
    Recurrence rules: +
    • Start date on 2012-10-09 (Tuesday)
    • +
    • Frequency set to WEEKLY
    • +
    • Interval set to 1
    • +
    • Count set to 3
    +
    2012-10-09 Tuesday +

    2012-10-16 Tuesday > modified

    +

    2012-10-22 Tuesday

    2012-10-17 Tuesday
    + +

    To get the changes in an exception, use the calendar_db_get_changes_exception_by_version() function. The instances and exceptions are deleted together when the original event is deleted.

    + +

    Filters and Queries

    +

    Queries are used to retrieve data which satisfies a given criteria, like an integer property being greater than a given value, or a string property containing a given substring. The criteria are defined by creating filters and adding conditions to them, joining them with logical operators. Also, instead of a condition, another filter can be added to create more complex filters.

    +

    When a filter is ready, it can be set as a property of a query. Other query properties allow configuring how the returned results are grouped and sorted.

    +

    The operator precedence in filters is determined by the order in which the conditions and filters are added. The following table shows an example of how the operator precedence works.

    + + + + + + + + + + + + + + + + + +
    + Table: Filter conditions +
    ConditionResult
    Condition C1
    +OR
    +Condition C2
    +AND
    +Condition C3
    (C1 OR C2) AND C3
    Filter F1:
    + Condition C1
    + OR
    + Condition C2
    +
    +Filter F2:
    + Condition C3
    + OR
    + Condition C4
    +
    +Filter F3:
    + Condition C5
    + AND
    + F1
    + AND
    + F2
    (C5 AND F1) AND F2
    +Meaning (C5 AND (C1 OR C2)) AND (C3 OR C4)
    + +

    The following code creates a filter, accepting events with high priority or those that include the word "meeting" in their description.

    +
    calendar_filter_h filter = NULL;
    + 
    +// Create a filter returning event type records
    +calendar_filter_create(_calendar_event._uri, &filter);
    + 
    +// Add a 'priority equals high' condition
    +calendar_filter_add_int(filter, _calendar_event.priority, CALENDAR_MATCH_EQUAL, CALENDAR_EVENT_PRIORITY_HIGH);
    + 
    +// Add OR operator
    +calendar_filter_add_operator(filter, CALENDAR_FILTER_OPERATOR_OR);
    + 
    +// Add a 'description contains "meeting"' condition
    +calendar_filter_add_str(filter, _calendar_event.description, CALENDAR_MATCH_CONTAINS, "meeting");
    + +

    Insert the filter into the query and execute the query:

    + +
    calendar_query_h query = NULL;
    +calendar_list_h list = NULL;
    + 
    +// Create a query returning event type records
    +calendar_query_create(_calendar_event._uri, &query);
    + 
    +// Add the filter
    +calendar_query_set_filter(query, filter);
    + 
    +// Execute the query, results are returned in a list
    +calendar_db_get_records_with_query(query, 0, 0, &list);
    + 
    +calendar_filter_destroy(filter);
    +calendar_query_destroy(query);
    + 
    +// Use the list
    + 
    +calendar_list_destroy(list, true);
    + +

    Projections

    +

    Projection is related to searching with filters and queries. A projection allows you to query the data for just those specific properties of a record that you actually need, at lower latency and cost than retrieving the entire set of properties.

    + +

    The following example code creates a filter that gets only the event ID, summary, and start time from those records whose summary has "test" (string filter). It creates a query, adds the filter to it, and receives the results in a list.

    + +
    calendar_query_h query = NULL;
    +calendar_filter_h filter = NULL;
    +
    +// Set query with filter
    +calendar_query_create(_calendar_event_calendar_book_attendee._uri, &query);
    +calendar_filter_create(_calendar_event_calendar_book_attendee._uri, &filter);
    +calendar_filter_add_str(filter, _calendar_event.summary, CALENDAR_MATCH_CONTAINS, "test");
    +calendar_query_set_filter(query, filter);
    +
    +// Set projection
    +unsigned int projection[3];
    +projection[0] = _calendar_event_calendar_book_attendee.event_id;
    +projection[1] = _calendar_event_calendar_book_attendee.summary;
    +projection[2] = _calendar_event_calendar_book_attendee.start_time;
    +
    +// Get list
    +calendar_query_set_projection(query, projection, 3);
    +calendar_db_get_records_with_query(query, 0, 0, &list);
    +
    +// Destroy handle
    +calendar_filter_destroy(filter);
    +calendar_query_destroy(query);
    +calendar_list_destroy(list, true);
    + +

    Records

    + +

    An important concept in the Calendar Service APIs is a record. Although a record represents an actual record in the internal database, you can consider it as a structure describing a single (but complex) entity, like a calendar event or a time zone.

    + +

    A record has many properties, for example, a todo record has the todo description, priority, progress, creation time, last modified and completed time, and many others.

    +

    A record can also contain an identifier field, which holds an ID of another record. Setting this field's value establishes a relation between the records, for example, a calendar event contains the ID of a calendar book to which it belongs.

    + +

    URI

    +

    A record type is identified by a structure called the view. For example, the _calendar_event view describes the properties of the calendar event record. Every view has a special field - _uri - that uniquely identifies the view. In many cases, you must provide the _uri value to indicate what type of record you want to create or operate on.

    +
    // Create an event with _calendar_event view
    +calendar_record_h record = NULL;
    +calendar_record_create(_calendar_event._uri, &record);
    +
    + +

    Record Handle

    +

    To use a record, you must obtain its handle. You can use many methods to obtain the handle, for example, you can create a new record or refer to the child records of a record.

    +
    // Create an event and get a handle
    +calendar_record_h event = NULL;
    +calendar_record_create(_calendar_event._uri, &event);
    +
    +// Get the record handle with ID
    +calendar_record_h event2 = NULL;
    +calendar_db_get_record(_calendar_event._uri, event_id, &event2);
    + +

    Basic Types

    +

    Records contain properties of basic types: integer, lli (long integer, long long int), double, string, bool, and time. The time type holds either a long long int, or 3 integers (year, month, day).

    + +

    The following table lists the setter and getter functions for each type.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + Table: Setter and getter functions +
    PropertySetterGetter
    integercalendar_record_set_intcalendar_record_get_int
    long long integercalendar_record_set_llicalendar_record_get_lli
    doublecalendar_record_set_doublecalendar_record_get_double
    stringcalendar_record_set_strcalendar_record_get_str
    calendar_time_scalendar_record_set_caltimecalendar_record_get_caltime
    + +

    Children

    +

    Certain type of records hold "child list" properties. If a record has a property of this type, it can be a parent of other records, called child records. For example, the attendee records can hold an event identifier in their event_id property. The event is the parent record of the child attendee records.

    + +

    The following code example creates an event and inserts it into the default event book.

    + +
    // Create an event
    +calendar_record_h event = NULL;
    +calendar_record_create(_calendar_event._uri, &event);
    + 
    +// Set event summary
    +calendar_record_set_str(event, _calendar_event.summary, "Meeting");
    + 
    +// Put the event into the default calendar book for events
    +calendar_record_set_int(event, _calendar_event.calendar_book_id, book_id);
    + 
    +// Insert calendar book into the database
    +int event_id = 0;
    +calendar_db_insert_record(event, &event_id);
    +
    +// Destroy
    +calendar_record_destroy(event, true);
    + +

    Reminders

    + +

    When an alarm is triggered, the calendar service sends a notification to the package which is registered in the reminder database table by using the calendar_reminder_add_receiver() function.

    + +

    The following figure illustrates how the alarm process works.

    + +

    Figure: Alarm process

    +

    Alarm process

    + +

    After you add a receiver, the registered alarm is triggered at the reserved time if you insert the alarm as a child to an event record:

    +
    // Set alarm
    +calendar_record_h alarm = NULL;
    +calendar_record_create(_calendar_alarm._uri, &alarm);
    +calendar_record_set_int(alarm, _calendar_alarm.tick_unit, CALENDAR_ALARM_TIME_UNIT_SPECIFIC);
    +calendar_record_set_lli(alarm, _calendar_alarm.time, (1404036000 - 60)); // Before 60 sec
    +
    +// Add alarm as child
    +calendar_record_add_child_record(event, _calendar_event.calendar_alarm, alarm);
    + + + + +

    Time Structure

    +

    The calendar time structure, calendar_caltime_s, is defined as follows:

    +
    typedef struct
    +{
    +   calendar_time_type_e type;
    +   union 
    +   {
    +      long long int utime;
    +      struct 
    +      {
    +         int year;
    +         int month;
    +         int mday;
    +      } date;
    +   } time;
    +} calendar_time_s;
    +

    Use this structure when setting the calendar time (_CALENDAR_PROPERTY_CALTIME) properties of the records.

    +

    The time structure can hold 2 types of data: UTC time (long long int) and date, given as year, month, and day of the month (3 integers). These types are identified by the values of the calendar_time_type_e variable, and they determine the usage of the structure.

    + + + + + + + + + + + + + + + + + + + + + + + +
    + Table: Data types +
    IdentifierTypeNamePurpose
    CALENDAR_TIME_UTIMElong long intutimeUTC time, used to describe non-all-day events
    CALENDAR_TIME_LOCALTIMEstructdateDate only (year, month, and day of the month), used to describe all day events.
    + +

    UTC Time Usage

    +

    Structures with UTC time are used for non-all-day events. In such cases, you must convert local time to UTC time. The local time zone identifier must be stored in the record, in the corresponding property.

    +

    For example, when setting the start time of an event, the local time zone must be stored in the start_tzid property.

    +

    When converting local time to UTC time, use the function illustrated in the following example. It converts the given date and time to the corresponding UTC time, considering the given time zone (first argument). The function uses the i18n API.

    + +
    #define ms2sec(ms) (long long int)(ms / 1000.0)
    + 
    +long long int _time_convert_itol(char *tzid, int y, int mon, int d, int h, int min, int s)
    +{
    +   int ret = 0;
    +   i18n_uchar utf16_timezone[64] = {0};
    +   i18n_ustring_copy_ua_n(utf16_timezone, tzid, sizeof(utf16_timezone)/sizeof(i18n_uchar));
    +
    +   i18n_ucalendar_h ucal = NULL;
    +   char *loc_default = NULL;
    +
    +   i18n_ulocale_get_default((const char **)&loc_default);
    +   ret = i18n_ucalendar_create(utf16_timezone, -1, loc_default, I18N_UCALENDAR_GREGORIAN, &ucal);
    +   if (I18N_ERROR_NONE != ret) 
    +   {
    +      dlog_print(DLOG_DEBUG, LOG_TAG, "i18n_ucalendar_create() is failed (%d)\n", ret);
    +
    +      return -1;
    +   }
    +
    +   i18n_ucalendar_set_date_time(ucal, y, mon - 1, d, h, min, s);
    +
    +   i18n_udate date;
    +   ret = i18n_ucalendar_get_milliseconds(ucal, &date);
    +   if (I18N_ERROR_NONE != ret) 
    +   {
    +      dlog_print(DLOG_DEBUG, LOG_TAG, "i18n_ucalendar_create() is failed (%d)\n", ret);
    +      i18n_ucalendar_destroy(ucal);
    +
    +      return -1;
    +   }
    +   i18n_ucalendar_destroy(ucal);
    +
    +   return ms2sec(date);
    +}
    + + +
    // Fill calendar time structures (start and end time)
    +calendar_time_s st = {0};
    +calendar_time_s et = {0};
    + 
    +st.type = CALENDAR_TIME_UTIME;
    +st.time.utime = _time_convert_itol("Asia/Seoul", 2012, 9, 15, 11, 0, 0);
    + 
    +et.type = CALENDAR_TIME_UTIME;
    +et.time.utime = _time_convert_itol("Asia/Seoul", 2012, 9, 15, 12, 0, 0);
    + 
    +// Create an event record
    + 
    +// Set local time zone of start time
    +calendar_record_set_str(event, _calendar_event.start_tzid, "Asia/Seoul");
    + 
    +// Set start time
    +calendar_record_set_caltime(event, _calendar_event.start_time, st);
    + 
    +// Set local time zone of end time
    +calendar_record_set_str(event, _calendar_event.end_tzid, "Asia/Seoul");
    + 
    +// Set end time
    +calendar_record_set_caltime(event, _calendar_event.end_time, et);
    + +

    Date Usage

    +

    Another usage of the time structure is an all day event. In case of such events, the structure type field must be set to CALENDAR_TIME_LOCALTIME. Only the date (no time) is stored. Such structures can be used to set the start and end time of an event.

    +

    Both start and end time of the event must be set, and they do not have to be equal. If they are not, the event lasts more than 1 day. Note that in such cases there are no instances created, as this is still a non-recurring event.

    + +

    Views and Properties

    + +

    Generic access functions can be used (according to data-view declarations) to access calendar views. A data-view is almost the same as a database "VIEW", which limits access and guarantees performance. A "record" represents a single row of the data-views.

    +

    The _calendar_instance_normal and _calendar_instance_allday views are not offered, but combinations with another views are provided.

    + + + + + + + + + + + + + +
    + Table: Calendar views +
    Editable viewRead-only view
    _calendar_book
    +_calendar_event
    +_calendar_todo
    +_calendar_timezone
    +_calendar_attendee
    +_calendar_alarm
    +_calendar_extended_property
    _calendar_updated_info
    +_calendar_event_calendar_book
    +_calendar_todo_calendar_book
    +_calendar_event_calendar_book_attendee
    +_calendar_instance_normal_calendar_book
    +_calendar_instance_allday_calendar_book
    +_calendar_instance_normal_calendar_book_extended
    +_calendar_instance_allday_calendar_book_extended
    + +

    The _calendar_updated_info view is used when identifying record changes depending on the version. The other read-only views are a combination of editable views for UI convenience:

    +
    • _calendar_event + _calendar_book = _calendar_event_calendar_book
    • +
    • _calendar_instance_normal + _calendar_book = _calendar_instance_normal_calendar_book
    • +
    • _calendar_event + _calendar_book + _calendar_attendee = _calendar_event_calendar_book_attendee
    + +

    Properties

    +

    The record types that have *_id as their property hold identifiers of other records. For example, the attendee and alarm views hold the ID of their corresponding events or todos in the event_id or todo_id property (as children of the corresponding event or todo records).

    +

    The record type properties are other records. For example, an event record has attendee and alarm properties, which means that records of those types can be children of the event type records. The following figure illustrates macros in a calendar_view.h header file.

    + +

    Figure: Properties

    +

    Properties

    + +
    // Create an event with _calendar_event view
    +calendar_record_h event = NULL;
    +calendar_record_create(_calendar_event._uri, &event);
    + 
    +// Set event summary to _calendar_event view
    +calendar_record_set_str(event, _calendar_event.summary, "Meeting");
    +
    + +

    Version

    +

    The calendar service uses a version system in the following APIs:

    +
    int calendar_db_get_current_version(int *calendar_db_version);
    +int calendar_db_get_changes_by_version(..., int *current_calendar_db_version);
    +int calendar_db_get_last_change_version(int *last_change_version);
    +int calendar_db_get_changes_exception_by_version(..., int calendar_db_version, ...);
    + +

    Whenever modifications are made in the database, the version number is increased. If sync applications, such as Google or Facebook, sync at version 13 and try to sync again every 1 minute, they want to get the changes from version 14 to the current version.

    +

    To get the current version, the calendar_db_get_current_version() function is used. The calendar_db_get_changes_by_version() function retrieves the modified record list. The calendar_db_get_changes_exception_by_version() function is used to get modified instances in a recurring event.

    + +

    vCalendar

    +

    Use vCalendar to exchange personal calendar and schedule information. In order to avoid confusion with this referenced work, this is to be known as the vCalendar specification. vCalendar ver2.0 is known as iCalendar. The following snippet shows an example of the vCalendar.

    +
    +BEGIN:VCALENDAR
    +VERSION:2.0
    +PRODID:-//hacksw/handcal//NONSGML v1.0//EN
    +BEGIN:VEVENT
    +DTSTART:19970714T170000Z
    +DTEND:19970715T035959Z
    +SUMMARY:Bastille Day Party
    +END:VEVENT
    +END:VCALENDAR
    +
    + +

    The calendar service provides APIs to compose a vCalendar stream. With the stream, it is possible to create files transmit data with JSON data.

    +
    +calendar_list_h list = NULL;
    +// Create or get list to make vcalendar stream
    +
    +char *stream = NULL;
    +calendar_vcalendar_make_from_records(list, &stream);
    +
    +// Jobs for stream
    +
    +// Free
    +free(stream);
    +
    + +

    vCalendar can be parsed with calendar service APIs as well.

    +
    +// Read stream from file
    +
    +calendar_list_h list = NULL;
    +calendar_vcalendar_parse_to_calendar(stream, &list);
    +
    +// Jobs for list
    +calendar_list_destroy(list, true);
    +
    + + + +
    + +Go to top + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/native/social/service_adaptor_n.htm b/org.tizen.guides/html/native/social/service_adaptor_n.htm index 1968cf9..7f2236f 100644 --- a/org.tizen.guides/html/native/social/service_adaptor_n.htm +++ b/org.tizen.guides/html/native/social/service_adaptor_n.htm @@ -38,17 +38,17 @@

    Service Adaptor

    -

    You can manage adaptors, which function as agents between the Service Adaptor Client and the related plugins, to take advantage of various services. For example, the Auth and Storage adaptors allow you to access the Auth and Service Plugins to use services, such as Amazon, Box, Dropbox, Gogledrive, Onedrive, and Sugarsync.

    +

    You can manage adaptors, which function as agents between the Service Adaptor Client and the related plugins, to take advantage of various services. For example, the Auth and Storage adaptors allow you to access the Auth and Service Plugins to use services, such as Amazon, Box, Dropbox, Googledrive, Onedrive, and Sugarsync.

    Figure: Service adaptor structure

    Service adaptor structure

    The main feature of the Service Adaptor API is to connect adaptors to and disconnect them from the Service Adaptor Client though D-Bus. The Service adaptor uses 2 path types:

      -
    • Logical path +
    • Logical path

      The path of the root file system. It starts from the root path ("/"), and you can use the path like in Linux (for example, "/folder1/image1.jpg").

    • -
    • Physical path +
    • Physical path

      A specific URI used for the cloud server. Some clouds use a logical path, but others use a specific key or URL (for example, "/" is "ZmNhMWY2MTZlY2M1NDg4OGJmZDY4O" and "/folder1" is "2JI32UNJDWQEQWQWEADSSAD").

    @@ -81,9 +81,9 @@
  • Reset contact information in the Contact server and upload native contact information of the device to the server.
  • Synchronize native contact information of the device with the Contact server according to the [type] field of each contact.
  • Get contact profiles and service registration information.
  • -
  • Set and update device profile in the server.
  • +
  • Set and update the device profile in the server.
  • Upload and delete profile image meta in the File server and set the my profile image to the Profile server.
  • -
  • Set and get my profile privacy level
  • +
  • Set and get the my profile privacy level
  • Set my presence ON/OFF information to the Presence server.
@@ -125,7 +125,8 @@

The following example starts all installed Auth and Storage plugins appending each plugin_uri to the list object:

-bool _plugin_iterator_cb(char *plugin_uri, int service_mask, void *user_data);
+bool 
+_plugin_iterator_cb(char *plugin_uri, int service_mask, void *user_data);
 
 service_adaptor_h service_adaptor = NULL;
 ret = service_adaptor_create(&service_adaptor);
@@ -133,7 +134,8 @@ ret = service_adaptor_create(&service_adaptor);
 Evas_Object *list;
 ret = service_adaptor_foreach_plugin(service_adaptor, _plugin_iterator_cb, (void *)list);
 
-bool _plugin_iterator_cb(char *plugin_uri, int service_mask, void *user_data)
+bool 
+_plugin_iterator_cb(char *plugin_uri, int service_mask, void *user_data)
 {
    Evas_Object *list = (Evas_Object *)user_data;
 
diff --git a/org.tizen.guides/html/native/social/social_guide_n.htm b/org.tizen.guides/html/native/social/social_guide_n.htm
index df58d54..569140d 100644
--- a/org.tizen.guides/html/native/social/social_guide_n.htm
+++ b/org.tizen.guides/html/native/social/social_guide_n.htm
@@ -39,10 +39,10 @@
   

The main social features are:

  • Service Adaptor -

    Allows you to manage adaptors between the Service Adaptor Client and related plugins.

  • +

    Allows you to work with cloud storages and services by managing authentication, contact information and file transfers to and from the cloud.

-

The following guides apply in mobile applications only:

+

The following guides apply in mobile applications only:

  • Account Manager diff --git a/org.tizen.guides/html/native/system/device_n.htm b/org.tizen.guides/html/native/system/device_n.htm index 15beed2..56080fd 100644 --- a/org.tizen.guides/html/native/system/device_n.htm +++ b/org.tizen.guides/html/native/system/device_n.htm @@ -1,71 +1,71 @@ - - - - - - - - - - - - - - Device - - - - - - -
    -

    Device

    - -

    Device features provide functions to control attached devices. The following functionalities are supported:

    -
    • Battery -

      Get the current percentage, the charging state, and the current level state using the Battery API (in mobile and wearable applications).

    • -
    • Display -

      Get the number of displays, the maximum brightness of the display, the current brightness, and the display state. You can also change the current brightness and the display state using the Display API (in mobile and wearable applications).

    • -
    • Haptic -

      Get the number of haptic devices. You can also open or close the haptic handle, and request the vibration effects to play or stop using the Haptic API (in mobile and wearable applications).

    • -
    • LED -

      Get the maximum and current brightness of the camera flash LED. You can also change the current brightness of the camera flash LED, and request the service LED to play or stop effects using the Led API (in mobile and wearable applications).

    • -
    • Power -

      Request the power state to be locked or unlocked, and change the power state using the Power API (in mobile and wearable applications).

    - - - -
    - -Go to top - - - - - - + + + + + + + + + + + + + + Device + + + + + + +
    +

    Device

    + +

    Device features provide functions to control attached devices. The following functionalities are supported:

    +
    • Battery +

      Get the current percentage, the charging state, and the current level state using the Battery API (in mobile and wearable applications).

    • +
    • Display +

      Get the number of displays, the maximum brightness of the display, the current brightness, and the display state. You can also change the current brightness and the display state using the Display API (in mobile and wearable applications).

    • +
    • Haptic +

      Get the number of haptic devices. You can also open or close the haptic handle, and request the vibration effects to play or stop using the Haptic API (in mobile and wearable applications).

    • +
    • LED +

      Get the maximum and current brightness of the camera flash LED. You can also change the current brightness of the camera flash LED, and request the service LED to play or stop effects using the Led API (in mobile and wearable applications).

    • +
    • Power +

      Request the power state to be locked or unlocked, and change the power state using the Power API (in mobile and wearable applications).

    + + + +
    + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/native/system/dlog_n.htm b/org.tizen.guides/html/native/system/dlog_n.htm index 7f9cff9..32a3b33 100644 --- a/org.tizen.guides/html/native/system/dlog_n.htm +++ b/org.tizen.guides/html/native/system/dlog_n.htm @@ -1,323 +1,323 @@ - - - - - - - - - - - - - - dlog - - - - - - -
    -

    dlog

    - -

    The dlog logging service consists of the dlogutil dlog library, and it supports sending log messages to a circular log device. The log device is a circular buffer used to collect log messages from various applications and the system.

    - -

    Figure: Architecture

    - -

    Architecture

    - -

    The dlog service sends a log message to the circular buffer with APIs, including Priority and Tag information. With this information, it is easy to filter and check the messages with dlogutil.

    - -

    Before using dlog, you should know which priorities and tags to use and where to write (format, buffer).

    - -

    Priority

    - - -

    The priority level indicates the urgency of the log message.

    - - - - - - - - - - - - - - - - - - - - - - - - - -
    - Table: Priority levels -
    PriorityDescription
    DLOG_DEBUGLog message which the developer wants to check
    DLOG_INFONormal operational message
    DLOG_WARNNot an error, but a warning that an error will occur if action is not taken -
    DLOG_ERRORAn error
    - -

    For each log level (info, debug, and error), there is a separate macro:

    - -
      -
    • Info -

      Use dlog_print(or dlog_vprint) function with DLOG_INFO priority when you need info messages to be displayed with a specified tag.

      -
      -// Print the "Initialization successful." info message with the tag to the console
      -dlog_print(DLOG_INFO, "MyTag", "Initialization successful.");
    • -
    • Debug -

      Use dlog_print(or dlog_vprint) function with DLOG_DEBUG priority when you need debug messages to be displayed with a specified tag.

      -
      -// Print the debug message "string: Test" to the console
      -dlog_print(DLOG_DEBUG, "MyTag", "string:","%s", "Test");
      -
    • -
    • Error -

      Use dlog_print(or dlog_vprint) function with DLOG_ERROR priority when you need error messages to be displayed with a specified tag.

      -
      -if (something_wrong)
      -{
      -   // Print the error message with the tag to the console
      -   dlog_print(DLOG_ERROR, "MyTag", "An unexpected error occurred");     
      -}
      -
    • -
    • Warning -

      Use dlog_print(or dlog_vprint) function with DLOG_WARN priority when you need warning messages to be displayed with a specified tag.

      -
      -// Print the warning message with the tag to the console
      -dlog_print(DLOG_WARN, "MyTag", "warning!");     
      -
    • -
    - -

    Log macros belong to Info, Debug, Error, and Warn log levels. To filter logs based on their levels, select the applicable log type in the Log view. You can also search logs by keywords, such as Pid, Tid, Tag, and Message. The following figure shows the output of a log macro.

    -

    Figure: Log macro output

    -

    Figure: Log macro output

    - -

    Tag

    -

    A tag is used to identify the source of the log message.

    - -

    There are no naming limitations, but do not forget that the tag is an identification of a module.

    - -

    Each tag must be unique.

    - - -

    Error Type

    - - - - - - - - - - - - - - - - - - - - -
    - Table: dlog error types -
    NumeratorDescription
    DLOG_ERROR_NONESuccessful
    DLOG_ERROR_INVALID_PARAMETERInvalid parameter
    DLOG_ERROR_NOT_PERMITTEDOperation not permitted
    - - - -

    To send a log message:

    - -
    -#include <dlog.h>
    -int main(void)
    -{
    -   int integer = 21;
    -   char string[] = "test dlog";
    -   dlog_print(DLOG_INFO, "USR_TAG", "test dlog");
    -   dlog_print(DLOG_INFO, "USR_TAG", "%s, %d", string, integer);
    -
    -   return 0;
    -}
    - -
    -#include <dlog.h>
    -void my_debug_print(char *format, ...)
    -{
    -   va_list ap;
    -   va_start(ap, format);
    -   dlog_vprint(DLOG_INFO, "USR_TAG", format, ap);
    -   va_end(ap);
    -}
    -
    -int main(void)
    -{
    -   my_debug_print("%s", "test dlog");
    -   my_debug_print("%s, %d", "test dlog", 21);
    -
    -   return 0;
    -}
    -
    - -

    Error Handling with dlog

    -

    Typical error handling example is as follows:

    -
    -location_manager_h location_handle;
    -int result = location_manager_create(LOCATION_METHOD_GPS, location_handle);
    -if (result != LOCATIONS_ERROR_NONE)
    -{
    -   dlog_print(DLOG_INFO, "MyTag", "Creation of the location manager failed.");
    -
    -   return false;
    -}
    -
    - -

    While working with the SDK this information is available in the Log tab. While working with the target device, one can also use dlogutil utility.

    - -

    dlogutil

    -

    You can collect and print out logs with logutil. Logutil supports filtering, and managing the log device.

    - -

    Using Logutil Commands

    -

    You can use a logutil command to view and follow the content of the log buffers. The general usage is:

    - -
    -dlogutil [<option>] ... [<filter-spec>] ...
    -
    - -

    Filtering Log Output

    -

    Every log message has a tag and a priority associated with it.

    - -

    The filter expression follows the tag:priority format, where the tag indicates the tag of interest and the priority indicates the minimum level of priority to report for that tag. You can add any number of tag:priority specifications in a single filter expression.

    - -

    The tag of a log message is a short name indicating the system component from which the message originates.

    -

    The priority is one of the following character values, ordered from the lowest to the highest priority:

    -
    • D - debug
    • -
    • I - info
    • -
    • W - warning
    • -
    • E - Error
    - -

    For example, if you want to see all log messages with the MyApp tag that are above the debug priority:

    - -
    # dlogutil MyApp:D
    - -

    If you want to see all log messages above the info priority:

    - -
    # dlogutil *:I
    - -

    Controlling Log Output Format

    -

    The log messages contain a number of metadata fields in addition to tag and priority. You can modify the output format for messages so that they display a specific metadata field. To do so, use the -v option when starting dlogutil and specify one of the supported output formats:

    - -
      -
    • brief: Displays the priority/tag and PID of the originating process (the default format)
    • -
    • process: Displays the PID only
    • -
    • tag: Displays the priority/tag only
    • -
    • thread: Displays the process:thread and priority/tag only
    • -
    • raw: Displays the raw log message, with no other metadata fields
    • -
    • time: Displays the date, invocation time, priority/tag, and PID of the originating process
    • -
    • long: Displays all metadata fields and separates messages with blank lines
    • -
    - -
    # dlogutil [-v <format>]
    - -

    List of Logutil Command Options

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    - Table: Logutil command options -
    OptionDescription
    -b <buffer>Alternates the log buffer. The main buffer is used by the default buffer.
    -cClears the entire log and exits
    -dDumps the log and exits
    -f <filename>Writes the log to <filename>. The default filename is stdout.
    -gPrints the size of the specified log buffer and exits
    -n <count>Sets the maximum number of rotated logs to <count>. The default value is 4. Requires the -r option.
    -r <Kbytes>Rotates the log file every <Kbytes> of output. The default value is 16. Requires the -f option.
    -sSets the default filter spec to silent
    -v <format>Sets the output format for log messages. The default format is brief.
    - - - -
    - -Go to top - - - - - - + + + + + + + + + + + + + + dlog + + + + + + +
    +

    dlog

    + +

    The dlog logging service consists of the dlogutil dlog library, and it supports sending log messages to a circular log device. The log device is a circular buffer used to collect log messages from various applications and the system.

    + +

    Figure: Architecture

    + +

    Architecture

    + +

    The dlog service sends a log message to the circular buffer with APIs, including Priority and Tag information. With this information, it is easy to filter and check the messages with dlogutil.

    + +

    Before using dlog, you should know which priorities and tags to use and where to write (format, buffer).

    + +

    Priority

    + + +

    The priority level indicates the urgency of the log message.

    + + + + + + + + + + + + + + + + + + + + + + + + + +
    + Table: Priority levels +
    PriorityDescription
    DLOG_DEBUGLog message which the developer wants to check
    DLOG_INFONormal operational message
    DLOG_WARNNot an error, but a warning that an error will occur if action is not taken +
    DLOG_ERRORAn error
    + +

    For each log level (info, debug, and error), there is a separate macro:

    + +
      +
    • Info +

      Use dlog_print(or dlog_vprint) function with DLOG_INFO priority when you need info messages to be displayed with a specified tag.

      +
      +// Print the "Initialization successful." info message with the tag to the console
      +dlog_print(DLOG_INFO, "MyTag", "Initialization successful.");
    • +
    • Debug +

      Use dlog_print(or dlog_vprint) function with DLOG_DEBUG priority when you need debug messages to be displayed with a specified tag.

      +
      +// Print the debug message "string: Test" to the console
      +dlog_print(DLOG_DEBUG, "MyTag", "string:","%s", "Test");
      +
    • +
    • Error +

      Use dlog_print(or dlog_vprint) function with DLOG_ERROR priority when you need error messages to be displayed with a specified tag.

      +
      +if (something_wrong)
      +{
      +   // Print the error message with the tag to the console
      +   dlog_print(DLOG_ERROR, "MyTag", "An unexpected error occurred");     
      +}
      +
    • +
    • Warning +

      Use dlog_print(or dlog_vprint) function with DLOG_WARN priority when you need warning messages to be displayed with a specified tag.

      +
      +// Print the warning message with the tag to the console
      +dlog_print(DLOG_WARN, "MyTag", "warning!");     
      +
    • +
    + +

    Log macros belong to Info, Debug, Error, and Warn log levels. To filter logs based on their levels, select the applicable log type in the Log view. You can also search logs by keywords, such as Pid, Tid, Tag, and Message. The following figure shows the output of a log macro.

    +

    Figure: Log macro output

    +

    Figure: Log macro output

    + +

    Tag

    +

    A tag is used to identify the source of the log message.

    + +

    There are no naming limitations, but do not forget that the tag is an identification of a module.

    + +

    Each tag must be unique.

    + + +

    Error Type

    + + + + + + + + + + + + + + + + + + + + +
    + Table: dlog error types +
    NumeratorDescription
    DLOG_ERROR_NONESuccessful
    DLOG_ERROR_INVALID_PARAMETERInvalid parameter
    DLOG_ERROR_NOT_PERMITTEDOperation not permitted
    + + + +

    To send a log message:

    + +
    +#include <dlog.h>
    +int main(void)
    +{
    +   int integer = 21;
    +   char string[] = "test dlog";
    +   dlog_print(DLOG_INFO, "USR_TAG", "test dlog");
    +   dlog_print(DLOG_INFO, "USR_TAG", "%s, %d", string, integer);
    +
    +   return 0;
    +}
    + +
    +#include <dlog.h>
    +void my_debug_print(char *format, ...)
    +{
    +   va_list ap;
    +   va_start(ap, format);
    +   dlog_vprint(DLOG_INFO, "USR_TAG", format, ap);
    +   va_end(ap);
    +}
    +
    +int main(void)
    +{
    +   my_debug_print("%s", "test dlog");
    +   my_debug_print("%s, %d", "test dlog", 21);
    +
    +   return 0;
    +}
    +
    + +

    Error Handling with dlog

    +

    Typical error handling example is as follows:

    +
    +location_manager_h location_handle;
    +int result = location_manager_create(LOCATION_METHOD_GPS, location_handle);
    +if (result != LOCATIONS_ERROR_NONE)
    +{
    +   dlog_print(DLOG_INFO, "MyTag", "Creation of the location manager failed.");
    +
    +   return false;
    +}
    +
    + +

    While working with the SDK this information is available in the Log tab. While working with the target device, one can also use dlogutil utility.

    + +

    dlogutil

    +

    You can collect and print out logs with logutil. Logutil supports filtering, and managing the log device.

    + +

    Using Logutil Commands

    +

    You can use a logutil command to view and follow the content of the log buffers. The general usage is:

    + +
    +dlogutil [<option>] ... [<filter-spec>] ...
    +
    + +

    Filtering Log Output

    +

    Every log message has a tag and a priority associated with it.

    + +

    The filter expression follows the tag:priority format, where the tag indicates the tag of interest and the priority indicates the minimum level of priority to report for that tag. You can add any number of tag:priority specifications in a single filter expression.

    + +

    The tag of a log message is a short name indicating the system component from which the message originates.

    +

    The priority is one of the following character values, ordered from the lowest to the highest priority:

    +
    • D - debug
    • +
    • I - info
    • +
    • W - warning
    • +
    • E - Error
    + +

    For example, if you want to see all log messages with the MyApp tag that are above the debug priority:

    + +
    # dlogutil MyApp:D
    + +

    If you want to see all log messages above the info priority:

    + +
    # dlogutil *:I
    + +

    Controlling Log Output Format

    +

    The log messages contain a number of metadata fields in addition to tag and priority. You can modify the output format for messages so that they display a specific metadata field. To do so, use the -v option when starting dlogutil and specify one of the supported output formats:

    + +
      +
    • brief: Displays the priority/tag and PID of the originating process (the default format)
    • +
    • process: Displays the PID only
    • +
    • tag: Displays the priority/tag only
    • +
    • thread: Displays the process:thread and priority/tag only
    • +
    • raw: Displays the raw log message, with no other metadata fields
    • +
    • time: Displays the date, invocation time, priority/tag, and PID of the originating process
    • +
    • long: Displays all metadata fields and separates messages with blank lines
    • +
    + +
    # dlogutil [-v <format>]
    + +

    List of Logutil Command Options

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + Table: Logutil command options +
    OptionDescription
    -b <buffer>Alternates the log buffer. The main buffer is used by the default buffer.
    -cClears the entire log and exits
    -dDumps the log and exits
    -f <filename>Writes the log to <filename>. The default filename is stdout.
    -gPrints the size of the specified log buffer and exits
    -n <count>Sets the maximum number of rotated logs to <count>. The default value is 4. Requires the -r option.
    -r <Kbytes>Rotates the log file every <Kbytes> of output. The default value is 16. Requires the -f option.
    -sSets the default filter spec to silent
    -v <format>Sets the output format for log messages. The default format is brief.
    + + + +
    + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/native/system/media_keys_n.htm b/org.tizen.guides/html/native/system/media_keys_n.htm index 23c6eac..3e25776 100644 --- a/org.tizen.guides/html/native/system/media_keys_n.htm +++ b/org.tizen.guides/html/native/system/media_keys_n.htm @@ -1,67 +1,67 @@ - - - - - - - - - - - - - Media key - - - - - -
    -

    Media key

    - -

    Tizen enables you to manage media key events. The media key events are generated by the remote control buttons in a Bluetooth headset or Bluetooth earphone. The media_key_e enumerator (in mobile and wearable applications) defines the available key types.

    - -

    The main features of the Media key API include:

    -
      -
    • Registering a callback -

      You can register a callback for media key events using the media_key_reserve() function. The first parameter of the function defines the media_key_event_cb type callback, which you can implement to perform any actions you need.

      -
    • -
    • Unregistering a callback -

      You can unregister a callback for media key events using the media_key_release() function.

    - - - -
    - -Go to top - - - - - - + + + + + + + + + + + + + Media key + + + + + +
    +

    Media key

    + +

    Tizen enables you to manage media key events. The media key events are generated by the remote control buttons in a Bluetooth headset or Bluetooth earphone. The media_key_e enumerator (in mobile and wearable applications) defines the available key types.

    + +

    The main features of the Media key API include:

    +
      +
    • Registering a callback +

      You can register a callback for media key events using the media_key_reserve() function. The first parameter of the function defines the media_key_event_cb type callback, which you can implement to perform any actions you need.

      +
    • +
    • Unregistering a callback +

      You can unregister a callback for media key events using the media_key_release() function.

    + + + +
    + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/native/system/runtime_info_n.htm b/org.tizen.guides/html/native/system/runtime_info_n.htm index a420bc4..361e892 100644 --- a/org.tizen.guides/html/native/system/runtime_info_n.htm +++ b/org.tizen.guides/html/native/system/runtime_info_n.htm @@ -1,160 +1,160 @@ - - - - - - - - - - - - - - Runtime information - - - - - - -
    -

    Runtime information

    - -

    The capi-system-runtime-info enables your application to get various runtime information.

    -

    To obtain the information, query a runtime info key. The keys are listed in the following table. -

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    - Table: Runtime information keys -
    KeyTypeDescription
    RUNTIME_INFO_KEY_BLUETOOTH_ENABLEDboolIndicates whether Bluetooth is enabled.
    RUNTIME_INFO_KEY_WIFI_HOTSPOT_ENABLEDboolIndicates whether a Wi-Fi hotspot is enabled.
    RUNTIME_INFO_KEY_BLUETOOTH_TETHERING_ENABLEDboolIndicates whether Bluetooth tethering is enabled.
    RUNTIME_INFO_KEY_USB_TETHERING_ENABLEDboolIndicates whether USB tethering is enabled.
    RUNTIME_INFO_KEY_LOCATION_SERVICE_ENABLEDboolIndicates whether the location service is allowed to use location data from GPS satellites.
    RUNTIME_INFO_KEY_LOCATION_NETWORK_POSITION_ENABLEDboolIndicates whether the location service is allowed to use location data from cellular and Wi-Fi.
    RUNTIME_INFO_KEY_PACKET_DATA_ENABLEDboolIndicates whether the packet data through 3G network is enabled.
    RUNTIME_INFO_KEY_DATA_ROAMING_ENABLEboolIndicates whether data roaming is enabled.
    RUNTIME_INFO_KEY_VIBRATION_ENABLEDboolIndicates whether vibration is enabled.
    RUNTIME_INFO_KEY_AUDIO_JACK_CONNECTEDboolIndicates whether an audio jack is connected.
    RUNTIME_INFO_KEY_GPS_STATUSintIndicates the current status of GPS.
    RUNTIME_INFO_KEY_BATTERY_IS_CHARGINGboolIndicates whether the battery is currently charging.
    RUNTIME_INFO_KEY_TV_OUT_CONNECTEDboolIndicates whether TV out is connected.
    RUNTIME_INFO_KEY_AUDIO_JACK_STATUSintIndicates the current status of the audio jack.
    RUNTIME_INFO_KEY_USB_CONNECTEDboolIndicates whether USB is connected.
    RUNTIME_INFO_KEY_CHARGER_CONNECTEDboolIndicates whether a charger is connected.
    RUNTIME_INFO_KEY_AUTO_ROTATION_ENABLEDboolIndicates whether auto-rotation is enabled.
    - - - -
    - -Go to top - - - - - - + + + + + + + + + + + + + + Runtime information + + + + + + +
    +

    Runtime information

    + +

    The capi-system-runtime-info enables your application to get various runtime information.

    +

    To obtain the information, query a runtime info key. The keys are listed in the following table. +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + Table: Runtime information keys +
    KeyTypeDescription
    RUNTIME_INFO_KEY_BLUETOOTH_ENABLEDboolIndicates whether Bluetooth is enabled.
    RUNTIME_INFO_KEY_WIFI_HOTSPOT_ENABLEDboolIndicates whether a Wi-Fi hotspot is enabled.
    RUNTIME_INFO_KEY_BLUETOOTH_TETHERING_ENABLEDboolIndicates whether Bluetooth tethering is enabled.
    RUNTIME_INFO_KEY_USB_TETHERING_ENABLEDboolIndicates whether USB tethering is enabled.
    RUNTIME_INFO_KEY_LOCATION_SERVICE_ENABLEDboolIndicates whether the location service is allowed to use location data from GPS satellites.
    RUNTIME_INFO_KEY_LOCATION_NETWORK_POSITION_ENABLEDboolIndicates whether the location service is allowed to use location data from cellular and Wi-Fi.
    RUNTIME_INFO_KEY_PACKET_DATA_ENABLEDboolIndicates whether the packet data through 3G network is enabled.
    RUNTIME_INFO_KEY_DATA_ROAMING_ENABLEboolIndicates whether data roaming is enabled.
    RUNTIME_INFO_KEY_VIBRATION_ENABLEDboolIndicates whether vibration is enabled.
    RUNTIME_INFO_KEY_AUDIO_JACK_CONNECTEDboolIndicates whether an audio jack is connected.
    RUNTIME_INFO_KEY_GPS_STATUSintIndicates the current status of GPS.
    RUNTIME_INFO_KEY_BATTERY_IS_CHARGINGboolIndicates whether the battery is currently charging.
    RUNTIME_INFO_KEY_TV_OUT_CONNECTEDboolIndicates whether TV out is connected.
    RUNTIME_INFO_KEY_AUDIO_JACK_STATUSintIndicates the current status of the audio jack.
    RUNTIME_INFO_KEY_USB_CONNECTEDboolIndicates whether USB is connected.
    RUNTIME_INFO_KEY_CHARGER_CONNECTEDboolIndicates whether a charger is connected.
    RUNTIME_INFO_KEY_AUTO_ROTATION_ENABLEDboolIndicates whether auto-rotation is enabled.
    + + + +
    + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/native/system/settings_n.htm b/org.tizen.guides/html/native/system/settings_n.htm index d6b4390..6e88570 100644 --- a/org.tizen.guides/html/native/system/settings_n.htm +++ b/org.tizen.guides/html/native/system/settings_n.htm @@ -1,291 +1,291 @@ - - - - - - - - - - - - - - System Settings - - - - - - -
    -

    System Settings

    - -

    Tizen provides functions for getting the system configuration related to user preferences.

    - -

    The main features of the System Settings API include accessing system-wide configurations, such as ringtone, wallpaper, and font.

    - -

    The system_settings_key_e enumerator defines all enumerations that work as arguments for the System Settings API.

    -

    The System Settings API provides 2 function types listed in the following table. Certain functions support both types, whereas others only support the getter function.

    - - - - - - - - - - - - - - - - - - - -
    Table: System Settings API function types
    Function typeMethodsDescription
    GETTERsystem_settings_get_value_bool -

    system_settings_get_value_int

    -

    system_settings_get_value_string

    Get the user-defined values by data type (bool, int, or string).
    NOTIFIERsystem_settings_set_changed_cb

    system_settings_unset_changed_cb

    Register and unregister callback functions when the SETTER related to the key is called.
    - -

    The following table lists the system settings details.

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    - Table: System settings keys -
    KeyTypeSupporting API type Description
    SYSTEM_SETTINGS_KEY_DEFAULT_FONT_TYPEstringGETTERCurrent system default font type.
    SYSTEM_SETTINGS_KEY_DEVICE_NAMEstringGETTER, NOTIFIERDevice name.
    SYSTEM_SETTINGS_KEY_DISPLAY_SCREEN_ROTATION_AUTOboolGETTER, NOTIFIERIndicates whether rotation control is automatic.
    SYSTEM_SETTINGS_KEY_EMAIL_ALERT_RINGTONEstringGETTER, NOTIFIERFile path of the current email alert ringtone.
    SYSTEM_SETTINGS_KEY_FONT_SIZEintGETTER, NOTIFIERCurrent system font size.
    SYSTEM_SETTINGS_KEY_FONT_TYPEstringGETTER, NOTIFIERCurrent system font type.
    SYSTEM_SETTINGS_KEY_INCOMING_CALL_RINGTONEstringGETTER, NOTIFIERFile path of the current ringtone.
    SYSTEM_SETTINGS_KEY_LOCALE_COUNTRYstringGETTER, NOTIFIERCurrent country setting in the <LANGUAGE>_<REGION> syntax. The country setting is in the ISO 639-2 format, and the region setting is in the ISO 3166-1 alpha-2 format.
    SYSTEM_SETTINGS_KEY_LOCALE_LANGUAGEstringGETTER, NOTIFIERCurrent language setting in the <LANGUAGE>_<REGION> syntax. The language setting is in the ISO 639-2 format and the region setting is in the ISO 3166-1 alpha-2 format.
    SYSTEM_SETTINGS_KEY_LOCALE_TIMEFORMAT_24HOURboolGETTER, NOTIFIERIndicates whether the 24-hour clock is used. If the value is false, the 12-hour clock is used.
    SYSTEM_SETTINGS_KEY_LOCALE_TIMEZONEstringGETTER, NOTIFIERCurrent time zone.
    SYSTEM_SETTINGS_KEY_MOTION_ACTIVATIONboolGETTER, NOTIFIERIndicates whether the motion service is activated.
    SYSTEM_SETTINGS_KEY_NETWORK_FLIGHT_MODEboolGETTER, NOTIFIERIndicates whether the device is in the flight mode.
    SYSTEM_SETTINGS_KEY_NETWORK_WIFI_NOTIFICATIONboolGETTER, NOTIFIERIndicates whether Wi-Fi-related notifications are enabled on the device.
    SYSTEM_SETTINGS_KEY_SCREEN_BACKLIGHT_TIMEintGETTER, NOTIFIERBacklight time (in seconds).
    SYSTEM_SETTINGS_KEY_SOUND_LOCKboolGETTER, NOTIFIERIndicates whether the screen lock sound is enabled on the device (for example, whether the LCD on/off sound is enabled).
    SYSTEM_SETTINGS_KEY_SOUND_NOTIFICATIONstringGETTER, NOTIFIERFile path of the current notification tone set by the user.
    SYSTEM_SETTINGS_KEY_SOUND_NOTIFICATION_REPETITION_PERIODintGETTER, NOTIFIERTime period for notification repetitions.
    SYSTEM_SETTINGS_KEY_SOUND_SILENT_MODEboolGETTER, NOTIFIERIndicates whether the device is in the silent mode.
    SYSTEM_SETTINGS_KEY_SOUND_TOUCHboolGETTER, NOTIFIERIndicates whether the screen touch sound is enabled on the device.
    SYSTEM_SETTINGS_KEY_TIME_CHANGEDintNOTIFIEREvent that occurs when the system changes time to notify you about the time change.
    SYSTEM_SETTINGS_KEY_USB_DEBUGGING_ENABLEDboolGETTER, NOTIFIERIndicates whether the USB debugging is enabled.
    SYSTEM_SETTINGS_KEY_WALLPAPER_HOME_SCREENstringGETTER, NOTIFIERFile path of the current home screen wallpaper.
    SYSTEM_SETTINGS_KEY_WALLPAPER_LOCK_SCREENstringGETTER, NOTIFIERFile path of the current lock screen wallpaper.
    - -

    The following example shows a typical use case: An application sees the name of the current wallpaper and you want to print out a message when the wallpaper changes:

    - -
    -void _img_cb (system_settings_key_e key, void *user_data)
    -{
    -   printf("THIS IS CALLED BY USER APPLICATION WHEN THE WALLPAPER CHANGES \n");
    -}
    -
    -// NOTIFIER 1 - Registering a callback function
    -system_settings_set_changed_cb(SYSTEM_SETTINGS_KEY_WALLPAPER_HOME_SCREEN, _img_cb, NULL);
    -char * path;
    -
    -// GETTER
    -system_settings_get_value_string(SYSTEM_SETTINGS_KEY_WALLPAPER_HOME_SCREEN, &path);
    -printf ("path of the current wallpaper is %s \n", path);
    -
    -// NOTIFIER 2 - Deregistering a callback function
    -system_settings_unset_changed_cb(SYSTEM_SETTINGS_KEY_WALLPAPER_HOME_SCREEN);
    -
    - - - -
    - -Go to top - - - - - - + + + + + + + + + + + + + + System Settings + + + + + + +
    +

    System Settings

    + +

    Tizen provides functions for getting the system configuration related to user preferences.

    + +

    The main features of the System Settings API include accessing system-wide configurations, such as ringtone, wallpaper, and font.

    + +

    The system_settings_key_e enumerator defines all enumerations that work as arguments for the System Settings API.

    +

    The System Settings API provides 2 function types listed in the following table. Certain functions support both types, whereas others only support the getter function.

    + + + + + + + + + + + + + + + + + + + +
    Table: System Settings API function types
    Function typeMethodsDescription
    GETTERsystem_settings_get_value_bool +

    system_settings_get_value_int

    +

    system_settings_get_value_string

    Get the user-defined values by data type (bool, int, or string).
    NOTIFIERsystem_settings_set_changed_cb

    system_settings_unset_changed_cb

    Register and unregister callback functions when the SETTER related to the key is called.
    + +

    The following table lists the system settings details.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + Table: System settings keys +
    KeyTypeSupporting API type Description
    SYSTEM_SETTINGS_KEY_DEFAULT_FONT_TYPEstringGETTERCurrent system default font type.
    SYSTEM_SETTINGS_KEY_DEVICE_NAMEstringGETTER, NOTIFIERDevice name.
    SYSTEM_SETTINGS_KEY_DISPLAY_SCREEN_ROTATION_AUTOboolGETTER, NOTIFIERIndicates whether rotation control is automatic.
    SYSTEM_SETTINGS_KEY_EMAIL_ALERT_RINGTONEstringGETTER, NOTIFIERFile path of the current email alert ringtone.
    SYSTEM_SETTINGS_KEY_FONT_SIZEintGETTER, NOTIFIERCurrent system font size.
    SYSTEM_SETTINGS_KEY_FONT_TYPEstringGETTER, NOTIFIERCurrent system font type.
    SYSTEM_SETTINGS_KEY_INCOMING_CALL_RINGTONEstringGETTER, NOTIFIERFile path of the current ringtone.
    SYSTEM_SETTINGS_KEY_LOCALE_COUNTRYstringGETTER, NOTIFIERCurrent country setting in the <LANGUAGE>_<REGION> syntax. The country setting is in the ISO 639-2 format, and the region setting is in the ISO 3166-1 alpha-2 format.
    SYSTEM_SETTINGS_KEY_LOCALE_LANGUAGEstringGETTER, NOTIFIERCurrent language setting in the <LANGUAGE>_<REGION> syntax. The language setting is in the ISO 639-2 format and the region setting is in the ISO 3166-1 alpha-2 format.
    SYSTEM_SETTINGS_KEY_LOCALE_TIMEFORMAT_24HOURboolGETTER, NOTIFIERIndicates whether the 24-hour clock is used. If the value is false, the 12-hour clock is used.
    SYSTEM_SETTINGS_KEY_LOCALE_TIMEZONEstringGETTER, NOTIFIERCurrent time zone.
    SYSTEM_SETTINGS_KEY_MOTION_ACTIVATIONboolGETTER, NOTIFIERIndicates whether the motion service is activated.
    SYSTEM_SETTINGS_KEY_NETWORK_FLIGHT_MODEboolGETTER, NOTIFIERIndicates whether the device is in the flight mode.
    SYSTEM_SETTINGS_KEY_NETWORK_WIFI_NOTIFICATIONboolGETTER, NOTIFIERIndicates whether Wi-Fi-related notifications are enabled on the device.
    SYSTEM_SETTINGS_KEY_SCREEN_BACKLIGHT_TIMEintGETTER, NOTIFIERBacklight time (in seconds).
    SYSTEM_SETTINGS_KEY_SOUND_LOCKboolGETTER, NOTIFIERIndicates whether the screen lock sound is enabled on the device (for example, whether the LCD on/off sound is enabled).
    SYSTEM_SETTINGS_KEY_SOUND_NOTIFICATIONstringGETTER, NOTIFIERFile path of the current notification tone set by the user.
    SYSTEM_SETTINGS_KEY_SOUND_NOTIFICATION_REPETITION_PERIODintGETTER, NOTIFIERTime period for notification repetitions.
    SYSTEM_SETTINGS_KEY_SOUND_SILENT_MODEboolGETTER, NOTIFIERIndicates whether the device is in the silent mode.
    SYSTEM_SETTINGS_KEY_SOUND_TOUCHboolGETTER, NOTIFIERIndicates whether the screen touch sound is enabled on the device.
    SYSTEM_SETTINGS_KEY_TIME_CHANGEDintNOTIFIEREvent that occurs when the system changes time to notify you about the time change.
    SYSTEM_SETTINGS_KEY_USB_DEBUGGING_ENABLEDboolGETTER, NOTIFIERIndicates whether the USB debugging is enabled.
    SYSTEM_SETTINGS_KEY_WALLPAPER_HOME_SCREENstringGETTER, NOTIFIERFile path of the current home screen wallpaper.
    SYSTEM_SETTINGS_KEY_WALLPAPER_LOCK_SCREENstringGETTER, NOTIFIERFile path of the current lock screen wallpaper.
    + +

    The following example shows a typical use case: An application sees the name of the current wallpaper and you want to print out a message when the wallpaper changes:

    + +
    +void _img_cb (system_settings_key_e key, void *user_data)
    +{
    +   printf("THIS IS CALLED BY USER APPLICATION WHEN THE WALLPAPER CHANGES \n");
    +}
    +
    +// NOTIFIER 1 - Registering a callback function
    +system_settings_set_changed_cb(SYSTEM_SETTINGS_KEY_WALLPAPER_HOME_SCREEN, _img_cb, NULL);
    +char * path;
    +
    +// GETTER
    +system_settings_get_value_string(SYSTEM_SETTINGS_KEY_WALLPAPER_HOME_SCREEN, &path);
    +printf ("path of the current wallpaper is %s \n", path);
    +
    +// NOTIFIER 2 - Deregistering a callback function
    +system_settings_unset_changed_cb(SYSTEM_SETTINGS_KEY_WALLPAPER_HOME_SCREEN);
    +
    + + + +
    + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/native/system/storage_n.htm b/org.tizen.guides/html/native/system/storage_n.htm index 2928c76..a17d8ea 100644 --- a/org.tizen.guides/html/native/system/storage_n.htm +++ b/org.tizen.guides/html/native/system/storage_n.htm @@ -1,117 +1,117 @@ - - - - - - - - - - - - - - Storage - - - - - - -
    -

    Storage

    - -

    Tizen enables you to get storage information and manage directories.

    -

    The Storage API provides access to accessible parts of the file system, which are represented as virtual root locations. The virtual roots form a collection of locations that function as a single virtual device file system. The following table lists the supported virtual roots.

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    - Table: Filesystem virtual roots -
    Virtual rootDescription
    imagesLocation for storing images.
    soundsLocation for storing sound files.
    videosLocation for storing videos.
    cameraLocation for storing camera files.
    downloadsLocation for storing downloaded items.
    musicLocation for storing audio files.
    documentsLocation for storing documents.
    othersLocation for storing other files.
    ringtonesLocation for ringtones (read-only location).
    -

    The main features of the Storage API include:

    -
      -
    • Storage management

      You can manage different storages on the device with the Storage APIs.

      You can retrieve additional information about the storages, including which storage is supported in the device using the storage_foreach_device_supported() function. The callback function returns the storage type, mount state, and virtual root path.

      -
    • -
    • Storage space management -

      You can get the available and total space size of the storage with the storage_get_total_space() and storage_get_available_space() functions. They return the storage size, excluding the minimum memory size to launch the low memory pop-up in case of a low memory situation. Consequently, the available size must be less than the original available size, and you must use these functions to get the memory size. For the same reason, you cannot use the statvfs function directly in Tizen. Instead, use storage_get_internal_memory_size() and storage_get_external_memory_size(). The Statvfs structure has a different structure size defined by "__USE_FILE_OFFSET64". However, you can ignore this, since the Storage API uses a proper function automatically.

    - - - - - -
    - -Go to top - - - - - - + + + + + + + + + + + + + + Storage + + + + + + +
    +

    Storage

    + +

    Tizen enables you to get storage information and manage directories.

    +

    The Storage API provides access to accessible parts of the file system, which are represented as virtual root locations. The virtual roots form a collection of locations that function as a single virtual device file system. The following table lists the supported virtual roots.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + Table: Filesystem virtual roots +
    Virtual rootDescription
    imagesLocation for storing images.
    soundsLocation for storing sound files.
    videosLocation for storing videos.
    cameraLocation for storing camera files.
    downloadsLocation for storing downloaded items.
    musicLocation for storing audio files.
    documentsLocation for storing documents.
    othersLocation for storing other files.
    ringtonesLocation for ringtones (read-only location).
    +

    The main features of the Storage API include:

    +
      +
    • Storage management

      You can manage different storages on the device with the Storage APIs.

      You can retrieve additional information about the storages, including which storage is supported in the device using the storage_foreach_device_supported() function. The callback function returns the storage type, mount state, and virtual root path.

      +
    • +
    • Storage space management +

      You can get the available and total space size of the storage with the storage_get_total_space() and storage_get_available_space() functions. They return the storage size, excluding the minimum memory size to launch the low memory pop-up in case of a low memory situation. Consequently, the available size must be less than the original available size, and you must use these functions to get the memory size. For the same reason, you cannot use the statvfs function directly in Tizen. Instead, use storage_get_internal_memory_size() and storage_get_external_memory_size(). The Statvfs structure has a different structure size defined by "__USE_FILE_OFFSET64". However, you can ignore this, since the Storage API uses a proper function automatically.

    + + + + + +
    + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/native/system/sysinfo_n.htm b/org.tizen.guides/html/native/system/sysinfo_n.htm index fbb3527..f476908 100644 --- a/org.tizen.guides/html/native/system/sysinfo_n.htm +++ b/org.tizen.guides/html/native/system/sysinfo_n.htm @@ -805,22 +805,7 @@ the Tizen reference implementation. http://tizen.org/feature/sensor.heart_rate_monitor bool The platform returns true for this key, if the device supports the heart rate monitor. - - - http://tizen.org/feature/sensor.heart_rate_monitor.led_green - bool - The platform returns true for this key, if the device supports the led green of the heart rate monitor. - - - http://tizen.org/feature/sensor.heart_rate_monitor.led_ir - bool - The platform returns true for this key, if the device supports the led ir of the heart rate monitor. - - - http://tizen.org/feature/sensor.heart_rate_monitor.led_red - bool - The platform returns true for this key, if the device supports the led red of the heart rate monitor. - + http://tizen.org/feature/sensor.humidity bool diff --git a/org.tizen.guides/html/native/telephony/phonenumber_util_n.htm b/org.tizen.guides/html/native/telephony/phonenumber_util_n.htm index daaeaf9..663cf79 100644 --- a/org.tizen.guides/html/native/telephony/phonenumber_util_n.htm +++ b/org.tizen.guides/html/native/telephony/phonenumber_util_n.htm @@ -1,68 +1,68 @@ - - - - - - - - - - - - - Phonenumber utils - - - - - -
    -

    Phonenumber utils

    - -

    Tizen enables you to parse and format phone numbers. The Phonenumber utils APIs are implemented with the libphonenumber opensource library.

    - -

    The main features of the Phonenumber utils API include:

    - -
    • Retrieving the location information -

      You can get the location based on the phone number, region, and language using the phone_number_get_location_from_number() function. If the function cannot provide the location with the passed language, it uses English.

    • - -
    • Formatting the phone number -

      You can format the phone number string based on the region using the dash ("-") and space (" ") characters using the phone_number_get_formatted_number() function.

    • -
    - - - -
    - -Go to top - - - - - - + + + + + + + + + + + + + Phonenumber utils + + + + + +
    +

    Phonenumber utils

    + +

    Tizen enables you to parse and format phone numbers. The Phonenumber utils APIs are implemented with the libphonenumber opensource library.

    + +

    The main features of the Phonenumber utils API include:

    + +
    • Retrieving the location information +

      You can get the location based on the phone number, region, and language using the phone_number_get_location_from_number() function. If the function cannot provide the location with the passed language, it uses English.

    • + +
    • Formatting the phone number +

      You can format the phone number string based on the region using the dash ("-") and space (" ") characters using the phone_number_get_formatted_number() function.

    • +
    + + + +
    + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/native/telephony/telephony_guide_n.htm b/org.tizen.guides/html/native/telephony/telephony_guide_n.htm index 52feb2b..46cb284 100644 --- a/org.tizen.guides/html/native/telephony/telephony_guide_n.htm +++ b/org.tizen.guides/html/native/telephony/telephony_guide_n.htm @@ -1,67 +1,67 @@ - - - - - - - - - - - - - Telephony - - - - - -
    -

    Telephony

    -

    Telephony features include managing phone numbers and information related to the Telephony Service.

    - -

    The main telephony features are:

    - - - - - -
    - -Go to top - - - - - - + + + + + + + + + + + + + Telephony + + + + + +
    +

    Telephony

    +

    Telephony features include managing phone numbers and information related to the Telephony Service.

    + +

    The main telephony features are:

    + + + + + +
    + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/native/telephony/telephony_info_n.htm b/org.tizen.guides/html/native/telephony/telephony_info_n.htm index b4303da..a0496c7 100644 --- a/org.tizen.guides/html/native/telephony/telephony_info_n.htm +++ b/org.tizen.guides/html/native/telephony/telephony_info_n.htm @@ -1,330 +1,330 @@ - - - - - - - - - - - - - Telephony Information - - - - - -
    -

    Telephony Information

    -

    Telephony information features include call, SIM, network, and modem information using the Telephony Service.

    - - -

    The main telephony information features are:

    - -
    • Call information -

      Get the voice and video call states. You can use this information in call-related actions.

    • - -
    • SIM information -

      Extract information stored on a SIM card without changing the information.

    • - -
    • Network information -

      Access (without changing) information about the current cellular network and telephony service.

    • - -
    • Modem information -

      Access (without changing) IMEI information.

    - -

    The following figure illustrates the Telephony Service and APIs.

    - -

    Figure: Telephony APIs and Telephony Service

    -

    Telephony APIs and Telephony Service

    - -

    Call Information

    - -

    The Call API (in mobile and wearable applications) provides the following functions:

    - -
      -
    • telephony_call_get_preferred_voice_subscription() -

      Gets the current value for the preferred voice call subscription. It returns one of the telephony_call_preferred_voice_subs_e values.

    • -
    • telephony_call_get_call_list() -

      Gets the list of the current call. It returns the current call count and the call handle.

    • -
    • telephony_call_release_call_list() -

      Releases the list allocated to the call handle. When the call handle is no longer needed, this function must be called to free the handle.

    • -
    • telephony_call_get_handle_id() -

      Gets the call handle ID.

    • -
    • telephony_call_get_number() -

      Gets the call number.

    • -
    • telephony_call_get_type() -

      Gets the call type. It returns one of the telephony_call_type_e values.

    • -
    • telephony_call_get_status() -

      Gets the call status. It returns one of the telephony_call_status_e values.

    • -
    • telephony_call_get_direction() -

      Gets the call direction: MO (Mobile Originated) or MT (Mobile Terminated). It returns one of the telephony_call_direction_e values.

    • -
    • telephony_call_get_conference_status() -

      Determines whether the call is conference call. It returns true for a conference call or false for a single call.

    - -

    To get call state change notifications, the application must register for the notifications with the telephony_set_noti_cb() function, by specifying the notification ID.

    - -

    The following table defines the available notification IDs.

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    - Table: Call information notification IDs -
    Change in stateNotification ID
    Voice status idleTELEPHONY_NOTI_VOICE_CALL_STATUS_IDLE
    Voice status activeTELEPHONY_NOTI_VOICE_CALL_STATUS_ACTIVE
    Voice status heldTELEPHONY_NOTI_VOICE_CALL_STATUS_HELD
    Voice status dialingTELEPHONY_NOTI_VOICE_CALL_STATUS_DIALING
    Voice status alertingTELEPHONY_NOTI_VOICE_CALL_STATUS_ALERTING
    Voice status incomingTELEPHONY_NOTI_VOICE_CALL_STATUS_INCOMING
    Video status idleTELEPHONY_NOTI_VIDEO_CALL_STATUS_IDLE
    Video status activeTELEPHONY_NOTI_VIDEO_CALL_STATUS_ACTIVE
    Video status dialingTELEPHONY_NOTI_VIDEO_CALL_STATUS_DIALING
    Video status alertingTELEPHONY_NOTI_VIDEO_CALL_STATUS_ALERTING
    Video status incomingTELEPHONY_NOTI_VIDEO_CALL_STATUS_INCOMING
    Preferred voice subscriptionTELEPHONY_NOTI_CALL_PREFERRED_VOICE_SUBSCRIPTION
    - - -

    SIM Information

    - -

    The SIM API (in mobile and wearable applications) provides the following functions:

    -
    • telephony_sim_get_icc_id() -

      Gets the Integrated Circuit Card IDentification (ICC-ID). You get the ICC-ID as a string, which needs to be freed by the application.

    • -
    • telephony_sim_get_operator() -

      Gets the SIM operator (MCC + MNC). You get the operator information as a string, which needs to be freed by the application.

    • -
    • telephony_sim_get_msin() -

      Gets the Mobile Subscription Identification Number (MSIN) of the SIM provider. You get the MSIN as a string, which needs to be freed by the application.

    • -
    • telephony_sim_get_spn() -

      Gets the Service Provider Name (SPN) of the SIM card. You get the SPN as a string, which needs to be freed by the application.

    • -
    • telephony_sim_get_cphs_operator_name() -

      Gets the Operator Name String (ONS) of the Common PCN Handset Specification (CPHS) in the SIM card. You get the CPHS as a string, which needs to be freed by the application.

    • -
    • telephony_sim_get_subscriber_number() -

      Gets the subscriber number embedded in the SIM card. This value contains the MSISDN related to the subscriber. You get the subscriber number as a string, which needs to be freed by the application.

    • -
    • telephony_sim_get_state() -

      Gets the state of the SIM. It returns one of the telephony_sim_state_e values.

    • -
    • telephony_sim_is_changed() -

      Checks whether the current SIM card differs from the previous SIM card.

    • -
    • telephony_sim_get_application_list() -

      Gets the application list on the UICC. It returns one of the masking (telephony_sim_application_type_e) values.

    • -
    • telephony_sim_get_subscriber_id() -

      Gets the subscriber ID as a string, which needs to be freed by the application.

    • -
    - -

    To get SIM state change notifications, the application must register for the notifications with the telephony_set_noti_cb() function, by specifying the notification ID.

    - -

    The following table defines the available notification IDs.

    - - - - - - - - - - - - - -
    - Table: SIM information notification IDs -
    Change in stateNotification ID
    SIM stateTELEPHONY_NOTI_SIM_STATUS
    - - - - - - - - - - -
    Note
    Before retrieving information from the SIM card, you must retrieve the state of the SIM card. You can get SIM-related information only if the SIM state is TELEPHONY_SIM_STATE_AVAILABLE.
    - - -

    Network Information

    - -

    The Network API (in mobile and wearable applications) provides the following functions:

    -
    • telephony_network_get_lac() -

      Gets the LAC (Location Area Code) of the current network.

    • -
    • telephony_network_get_cell_id() -

      Gets the cell identification number.

    • -
    • telephony_network_get_rssi() -

      Gets the RSSI (Received Signal Strength Indicator).

    • -
    • telephony_network_get_roaming_status() -

      Gets the roaming state (true = roaming and false = not roaming).

    • -
    • telephony_network_get_mcc() -

      Gets the MCC (Mobile Country Code) of the current registered network. You get the MCC as a string, which needs to be freed by the application.

    • -
    • telephony_network_get_mnc() -

      Gets the MNC (Mobile Network Code) of the current registered network. You get the MNC as a string, which needs to be freed by the application.

    • -
    • telephony_network_get_network_name() -

      Gets the name of the current registered network. You get the network name as a string, which needs to be freed by the application.

    • -
    • telephony_network_get_type() -

      Gets the network service type of the current registered network. It returns one of the telephony_network_type_e values.

    • -
    • telephony_network_get_service_state() -

      Gets the current network state of the telephony service. It returns one of the telephony_network_service_state_e values.

    • -
    • telephony_network_get_ps_type() -

      Gets the packet service type of the currently registered network. It returns one of the telephony_network_ps_type_e values.

    • -
    • telephony_network_get_network_name_option() -

      Gets the network name option of the currently registered network. It returns one of the telephony_network_name_option_e values.

    • -
    • telephony_network_get_default_data_subscription() -

      Gets the current default subscription for the data service (packet-switched). It returns one of the telephony_network_default_data_subs_e values.

    • -
    • telephony_network_get_default_subscription() -

      Gets the current default subscription for the voice service (circuit-switched). It returns one of the telephony_network_default_subs_e values.

    • -
    - -

    To get network-related information change notifications, the application must register for the notifications with the telephony_set_noti_cb() function, by specifying the notification ID.

    - -

    The following table defines the available notification IDs.

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    - Table: Network information notification IDs -
    Change in stateNotification ID
    Network service stateTELEPHONY_NOTI_NETWORK_SERVICE_STATE
    Cell IDTELEPHONY_NOTI_NETWORK_CELLID
    Roaming statusTELEPHONY_NOTI_NETWORK_ROAMING_STATUS
    Signal strengthTELEPHONY_NOTI_NETWORK_SIGNALSTRENGTH_LEVEL
    Network nameTELEPHONY_NOTI_NETWORK_NETWORK_NAME
    Packet-switched typeTELEPHONY_NOTI_NETWORK_PS_TYPE
    Default data subscriptionTELEPHONY_NOTI_NETWORK_DEFAULT_DATA_SUBSCRIPTION
    Default subscriptionTELEPHONY_NOTI_NETWORK_DEFAULT_SUBSCRIPTION
    - - - - - - - - - - -
    Note
    Before retrieving information from the network, you must retrieve the network service state. You can get network-related information only if the network service state is TELEPHONY_NETWORK_SERVICE_STATE_IN_SERVICE.
    - -

    Modem Information

    - -

    The Modem API (in mobile and wearable applications) provides the following functions:

    -
    • telephony_modem_get_imei() -

      Gets the IMEI (International Mobile Station Equipment Identity) of the mobile phone. You get the IMEI as a string, which needs to be freed by the application.

    • -
    • telephony_modem_get_power_status() -

      Gets the power status of the modem. It returns one of the telephony_modem_power_status_e values.

    • -
    - - - -
    - -Go to top - - - - - - + + + + + + + + + + + + + Telephony Information + + + + + +
    +

    Telephony Information

    +

    Telephony information features include call, SIM, network, and modem information using the Telephony Service.

    + + +

    The main telephony information features are:

    + +
    • Call information +

      Get the voice and video call states. You can use this information in call-related actions.

    • + +
    • SIM information +

      Extract information stored on a SIM card without changing the information.

    • + +
    • Network information +

      Access (without changing) information about the current cellular network and telephony service.

    • + +
    • Modem information +

      Access (without changing) IMEI information.

    + +

    The following figure illustrates the Telephony Service and APIs.

    + +

    Figure: Telephony APIs and Telephony Service

    +

    Telephony APIs and Telephony Service

    + +

    Call Information

    + +

    The Call API (in mobile and wearable applications) provides the following functions:

    + +
      +
    • telephony_call_get_preferred_voice_subscription() +

      Gets the current value for the preferred voice call subscription. It returns one of the telephony_call_preferred_voice_subs_e values.

    • +
    • telephony_call_get_call_list() +

      Gets the list of the current call. It returns the current call count and the call handle.

    • +
    • telephony_call_release_call_list() +

      Releases the list allocated to the call handle. When the call handle is no longer needed, this function must be called to free the handle.

    • +
    • telephony_call_get_handle_id() +

      Gets the call handle ID.

    • +
    • telephony_call_get_number() +

      Gets the call number.

    • +
    • telephony_call_get_type() +

      Gets the call type. It returns one of the telephony_call_type_e values.

    • +
    • telephony_call_get_status() +

      Gets the call status. It returns one of the telephony_call_status_e values.

    • +
    • telephony_call_get_direction() +

      Gets the call direction: MO (Mobile Originated) or MT (Mobile Terminated). It returns one of the telephony_call_direction_e values.

    • +
    • telephony_call_get_conference_status() +

      Determines whether the call is conference call. It returns true for a conference call or false for a single call.

    + +

    To get call state change notifications, the application must register for the notifications with the telephony_set_noti_cb() function, by specifying the notification ID.

    + +

    The following table defines the available notification IDs.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + Table: Call information notification IDs +
    Change in stateNotification ID
    Voice status idleTELEPHONY_NOTI_VOICE_CALL_STATUS_IDLE
    Voice status activeTELEPHONY_NOTI_VOICE_CALL_STATUS_ACTIVE
    Voice status heldTELEPHONY_NOTI_VOICE_CALL_STATUS_HELD
    Voice status dialingTELEPHONY_NOTI_VOICE_CALL_STATUS_DIALING
    Voice status alertingTELEPHONY_NOTI_VOICE_CALL_STATUS_ALERTING
    Voice status incomingTELEPHONY_NOTI_VOICE_CALL_STATUS_INCOMING
    Video status idleTELEPHONY_NOTI_VIDEO_CALL_STATUS_IDLE
    Video status activeTELEPHONY_NOTI_VIDEO_CALL_STATUS_ACTIVE
    Video status dialingTELEPHONY_NOTI_VIDEO_CALL_STATUS_DIALING
    Video status alertingTELEPHONY_NOTI_VIDEO_CALL_STATUS_ALERTING
    Video status incomingTELEPHONY_NOTI_VIDEO_CALL_STATUS_INCOMING
    Preferred voice subscriptionTELEPHONY_NOTI_CALL_PREFERRED_VOICE_SUBSCRIPTION
    + + +

    SIM Information

    + +

    The SIM API (in mobile and wearable applications) provides the following functions:

    +
    • telephony_sim_get_icc_id() +

      Gets the Integrated Circuit Card IDentification (ICC-ID). You get the ICC-ID as a string, which needs to be freed by the application.

    • +
    • telephony_sim_get_operator() +

      Gets the SIM operator (MCC + MNC). You get the operator information as a string, which needs to be freed by the application.

    • +
    • telephony_sim_get_msin() +

      Gets the Mobile Subscription Identification Number (MSIN) of the SIM provider. You get the MSIN as a string, which needs to be freed by the application.

    • +
    • telephony_sim_get_spn() +

      Gets the Service Provider Name (SPN) of the SIM card. You get the SPN as a string, which needs to be freed by the application.

    • +
    • telephony_sim_get_cphs_operator_name() +

      Gets the Operator Name String (ONS) of the Common PCN Handset Specification (CPHS) in the SIM card. You get the CPHS as a string, which needs to be freed by the application.

    • +
    • telephony_sim_get_subscriber_number() +

      Gets the subscriber number embedded in the SIM card. This value contains the MSISDN related to the subscriber. You get the subscriber number as a string, which needs to be freed by the application.

    • +
    • telephony_sim_get_state() +

      Gets the state of the SIM. It returns one of the telephony_sim_state_e values.

    • +
    • telephony_sim_is_changed() +

      Checks whether the current SIM card differs from the previous SIM card.

    • +
    • telephony_sim_get_application_list() +

      Gets the application list on the UICC. It returns one of the masking (telephony_sim_application_type_e) values.

    • +
    • telephony_sim_get_subscriber_id() +

      Gets the subscriber ID as a string, which needs to be freed by the application.

    • +
    + +

    To get SIM state change notifications, the application must register for the notifications with the telephony_set_noti_cb() function, by specifying the notification ID.

    + +

    The following table defines the available notification IDs.

    + + + + + + + + + + + + + +
    + Table: SIM information notification IDs +
    Change in stateNotification ID
    SIM stateTELEPHONY_NOTI_SIM_STATUS
    + + + + + + + + + + +
    Note
    Before retrieving information from the SIM card, you must retrieve the state of the SIM card. You can get SIM-related information only if the SIM state is TELEPHONY_SIM_STATE_AVAILABLE.
    + + +

    Network Information

    + +

    The Network API (in mobile and wearable applications) provides the following functions:

    +
    • telephony_network_get_lac() +

      Gets the LAC (Location Area Code) of the current network.

    • +
    • telephony_network_get_cell_id() +

      Gets the cell identification number.

    • +
    • telephony_network_get_rssi() +

      Gets the RSSI (Received Signal Strength Indicator).

    • +
    • telephony_network_get_roaming_status() +

      Gets the roaming state (true = roaming and false = not roaming).

    • +
    • telephony_network_get_mcc() +

      Gets the MCC (Mobile Country Code) of the current registered network. You get the MCC as a string, which needs to be freed by the application.

    • +
    • telephony_network_get_mnc() +

      Gets the MNC (Mobile Network Code) of the current registered network. You get the MNC as a string, which needs to be freed by the application.

    • +
    • telephony_network_get_network_name() +

      Gets the name of the current registered network. You get the network name as a string, which needs to be freed by the application.

    • +
    • telephony_network_get_type() +

      Gets the network service type of the current registered network. It returns one of the telephony_network_type_e values.

    • +
    • telephony_network_get_service_state() +

      Gets the current network state of the telephony service. It returns one of the telephony_network_service_state_e values.

    • +
    • telephony_network_get_ps_type() +

      Gets the packet service type of the currently registered network. It returns one of the telephony_network_ps_type_e values.

    • +
    • telephony_network_get_network_name_option() +

      Gets the network name option of the currently registered network. It returns one of the telephony_network_name_option_e values.

    • +
    • telephony_network_get_default_data_subscription() +

      Gets the current default subscription for the data service (packet-switched). It returns one of the telephony_network_default_data_subs_e values.

    • +
    • telephony_network_get_default_subscription() +

      Gets the current default subscription for the voice service (circuit-switched). It returns one of the telephony_network_default_subs_e values.

    • +
    + +

    To get network-related information change notifications, the application must register for the notifications with the telephony_set_noti_cb() function, by specifying the notification ID.

    + +

    The following table defines the available notification IDs.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + Table: Network information notification IDs +
    Change in stateNotification ID
    Network service stateTELEPHONY_NOTI_NETWORK_SERVICE_STATE
    Cell IDTELEPHONY_NOTI_NETWORK_CELLID
    Roaming statusTELEPHONY_NOTI_NETWORK_ROAMING_STATUS
    Signal strengthTELEPHONY_NOTI_NETWORK_SIGNALSTRENGTH_LEVEL
    Network nameTELEPHONY_NOTI_NETWORK_NETWORK_NAME
    Packet-switched typeTELEPHONY_NOTI_NETWORK_PS_TYPE
    Default data subscriptionTELEPHONY_NOTI_NETWORK_DEFAULT_DATA_SUBSCRIPTION
    Default subscriptionTELEPHONY_NOTI_NETWORK_DEFAULT_SUBSCRIPTION
    + + + + + + + + + + +
    Note
    Before retrieving information from the network, you must retrieve the network service state. You can get network-related information only if the network service state is TELEPHONY_NETWORK_SERVICE_STATE_IN_SERVICE.
    + +

    Modem Information

    + +

    The Modem API (in mobile and wearable applications) provides the following functions:

    +
    • telephony_modem_get_imei() +

      Gets the IMEI (International Mobile Station Equipment Identity) of the mobile phone. You get the IMEI as a string, which needs to be freed by the application.

    • +
    • telephony_modem_get_power_status() +

      Gets the power status of the modem. It returns one of the telephony_modem_power_status_e values.

    • +
    + + + +
    + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/native/ui/animations_effects_n.htm b/org.tizen.guides/html/native/ui/animations_effects_n.htm deleted file mode 100644 index 90be4f3..0000000 --- a/org.tizen.guides/html/native/ui/animations_effects_n.htm +++ /dev/null @@ -1,2009 +0,0 @@ - - - - - - - - - - - - - Animation and Effect Types - - - - - -
    - -

    Animation and Effect Types

    - -

    Ecore Animator

    - -

    Ecore provides a facility for animations called Ecore_Animator. Ecore animators use the Ecore main loop for creating animations, running a specific action on each tick of a timer in the main loop.

    - -

    To create an Ecore animation:

    -
      -
    1. Determine the duration of the animation.
    2. -
    3. Define a callback function that performs the animation with that duration.
    4. -
    - -

    To use Ecore animators in your application, you must include the <Ecore.h> file. This file is included by default if you are already using the <Elementary.h> file in your application. You then declare an Ecore_Animator* variable and use the variable in the ecore_animator_* functions.

    - -

    The following example shows how to create a simple animation with a finite duration:

    - -
    -static Eina_Bool
    -_do_animation(void *data, double pos)
    -{
    -   evas_object_move(data, 100 * pos, 100 * pos);
    -   // Do some more animating...
    -}
    -ecore_animator_timeline_add(2, _do_animation, my_evas_object);
    -
    - -

    In the above example, we create a linear transition to move my_evas_object from position (0,0) to position (100,100) in 2 seconds.

    - -

    Creating an Animation with a Finite Duration

    - -

    Most of the time, you will want to create animations that last for a predefined time.

    - -

    The ecore_animator_timeline_add() function allows you to define an animator that is automatically deleted after the animation is finished:

    - -
    ecore_animator_timeline_add(double runtime, Ecore_Timeline_Cb func, const void *data)
    - -
      -
    • The first argument is the duration of the animation in seconds. The duration is not affected by frame rate.
    • -
    • The second argument is the callback function that performs the animation.
    • -
    • The third argument is the parameter passed to the callback function. This is usually the Evas object to animate.
    • -
    - - - - - - - - - - -
    Note
    The callback function can return ECORE_CALLBACK_RENEW to keep the animator running or ECORE_CALLBACK_CANCEL to stop the animator and have it be deleted automatically at any time. The callback function is also passed a timeline position parameter with a value between 0.0 (start) to 1.0 (end) to indicate where along the timeline the animator is running.
    - -

    The following example performs a linear horizontal translation of 500 pixels in 8 seconds:

    -
    -static Eina_Bool
    -_my_animation(void *data, double pos)
    -{
    -   Evas_Object *obj = data; // Get the target object
    -   int x, y, w, h; // Target object geometry
    -   evas_object_geometry_get(obj, &x, &y, &w, &h); // Get current object position and size attributes
    -   evas_object_move(obj, 500 * pos, y); // Linear translation of the Evas object
    -}
    -ecore_animator_timeline_add(8, _my_animation, my_evas_object);
    -
    - -

    Position Mappings

    - -

    The Ecore_Pos_Map position mappings are used to define the evolution of a given position in accordance with the desired effects. The value ranges from 0.0 to 1.0 on a given timeline. This position variation allows you to apply dynamic changes to any attribute of your Evas object, such as position, width, height, scale, angle, and color.

    - -

    Ecore supports the following position mappings (with the listed v1 and v2 parameters):

    - -
      -
    • ECORE_POS_MAP_LINEAR: linear 0.0 - 1.0 -
        -
      • v1: not used
      • -
      • v2: not used
      • -
      -
    • -
    • ECORE_POS_MAP_ACCELERATE: start slow, then speed up -
        -
      • v1: not used
      • -
      • v2: not used
      • -
      -
    • -
    • ECORE_POS_MAP_DECELERATE: start fast, then slow down -
        -
      • v1: not used
      • -
      • v2: not used
      • -
      -
    • -
    • ECORE_POS_MAP_SINUSOIDAL: start slow, speed up, then slow down at the end -
        -
      • v1: not used
      • -
      • v2: not used
      • -
      -
    • -
    • ECORE_POS_MAP_ACCELERATE_FACTOR: start slow, then speed up -
        -
      • v1: power factor: 0.0 is linear, 1.0 is standard acceleration, 2.0 is a much more pronounced acceleration (squared), 4.0 is cubed, and so on
      • -
      • v2: not used
      • -
      -
    • -
    • ECORE_POS_MAP_DECELERATE_FACTOR: start fast, then slow down -
        -
      • v1: power factor: 0.0 is linear, 1.0 is standard deceleration, 2.0 is a much more pronounced deceleration (squared), 3.0 is cubed, and so on
      • -
      • v2: not used
      • -
      -
    • -
    • ECORE_POS_MAP_SINUSOIDAL_FACTOR: start slow, speed up, then slow down at the end -
        -
      • v1: power factor: 0.0 is linear, 1.0 is a standard sinusoidal, 2.1 is a much more pronounced sinusoidal (squared), 3.0 is cubed, and so on
      • -
      • v2: not used
      • -
      -
    • -
    • ECORE_POS_MAP_DIVISOR_INTERP: start at gradient * v1, interpolated via power of v2 curve -
        -
      • v1: multiplication factor for gradient
      • -
      • v2: curve value
      • -
      -
    • -
    • ECORE_POS_MAP_BOUNCE: start at 0.0, then "drop" like a ball bouncing to the ground at 1.0, and bounce v2 times, with a decay factor of v1 -
        -
      • v1: bounce decay factor
      • -
      • v2: number of bounces
      • -
      -
    • -
    • ECORE_POS_MAP_SPRING: start at 0.0, then "wobble" like a spring until rest position at 1.0, and wobble v2 times, with a decay factor of v1 -
        -
      • v1: wobble decay factor
      • -
      • v2: number of wobbles
      • -
      -
    • -
    - -

    Figure: Position mappings

    -

    Position mappings

    - -

    Using Position Mappings

    -

    When using the animation callback function, the animator passes a timeline position parameter with a value between 0.0 (start) and 1.0 (end) to indicate where along the timeline the animator is running.

    - -

    If you want to create a non-linear animation, map the position value to one of several curves and mappings:

    -
    ecore_animator_pos_map(double pos, Ecore_Pos_Map map, double v1, double v2)
    -
      -
    • The first argument is the current position value, which ranges from 0.0 to 1.0.
    • -
    • The second argument is the position mapping you want to apply.
    • -
    • The third argument is the first parameter (v1) to pass to the position mapping.
    • -
    • The fourth argument is the second parameter (v2) to pass to the position mapping.
    • -
    - - - - - - - - - - -
    Note
    The v1 and v2 arguments are specific to the chosen position mapping. For example, if you are using ECORE_POS_MAP_BOUNCE, v1 represents the bouncing level and v2 the number of bounces.
    - -

    The following example performs a transition that bounces 7 times, diminishing by a factor of 1.8 over 5 seconds:

    - -
    static Eina_Bool
    -_my_animation_callback(void *data, double pos)
    -{
    -   Evas_Object *obj = data; // Get the target object
    -   int x, y, w, h; // Target object geometry
    -   double frame = pos; // Actual position variation
    -   // Get frame relative position depending on desired effect
    -   frame = ecore_animator_pos_map(pos, ECORE_POS_MAP_BOUNCE, 1.8, 7);
    -   evas_object_geometry_get(obj, &x, &y, &w, &h); // Get current object position and size attributes
    -   evas_object_move(obj, x, 600 * frame); // Move the Evas object according to desired effect
    -
    -   return EINA_TRUE;
    -}
    -ecore_animator_timeline_add(5, _my_animation_callback, my_evas_object);
    - -

    Creating an Infinite Animation

    - -

    If you want the animation to run for an unspecified amount of time, use the ecore_animator_add() function. This function works the same way as the ecore_animation_timeline_add() function, except its interval is based on frame rate. Using frame rate as the basis benefits performance, especially if you define multiple animations, since you may want to have a different timer for each callback function.

    - -
    -ecore_animator_add(Ecore_Task_Cb func, const void *data)
    -
    - -
      -
    • The first argument is the callback function that performs the animation.
    • -
    • The second argument is the parameter passed to the callback function. This is usually the Evas object to animate.
    • -
    - - - - - - - - - - -
    Note
    The function returns a pointer to an Ecore_Animator object, which you can use to adjust the animation.
    - -

    The following example creates a rectangle sliding from left to right and back again. When the rectangle hits one edge of the screen, it changes direction.

    - -
    static Eina_Bool
    -_slide_back_and_forth(void *data)
    -{
    -   typedef enum {LEFT, RIGHT} direction_t; // Direction datatype
    -   static int x = 0; // Initial position
    -   static direction_t direction = RIGHT; // Initial direction
    -   if (x >= 250)
    -      direction = LEFT; // Change direction
    -   else if (x <= 0)
    -      direction = RIGHT; // Change direction
    -   if (direction == RIGHT)
    -      evas_object_move(data, ++x, 350); // Slide to right
    -   else if (direction == LEFT)
    -      evas_object_move(data, --x, 350); // Slide to left
    -
    -   return EINA_TRUE;
    -}
    -int
    -main(int argc, char *argv[])
    -{
    -   // Declarations
    -
    -   // Ecore Evas init
    -
    -   // Draw Evas objects
    -
    -   // Animations go here
    -   anim = ecore_animator_add(_slide_back_and_forth, rectangle);
    -   // Ecore main loop
    -
    -   // Free memory
    -}
    - - - - - - - - - - -
    Note
    To use this code, you have to merge it with the Ecore transition example above.
    - -

    Chaining Animations

    - -

    You may sometimes want to delay animating an object. This can be useful if, for example, you want to start an animation only after another one has finished.

    - -

    You can simply set a delay to the second animation equal to the duration of the first animation:

    - -
    -static int runtime = 5;
    -static int delay = runtime;
    -static Eina_Bool
    -_start_fold_animation(void *data)
    -{
    -   ecore_animator_timeline_add(runtime, _fold_animation, data);
    -
    -   return EINA_FALSE;
    -}
    -static Eina_Bool
    -_start_unfold_animation(void *data)
    -{
    -   ecore_animator_timeline_add(runtime, _unfold_animation, data);
    -
    -   return EINA_FALSE;
    -}
    -_start_fold_animation(my_evas_object);
    -ecore_timer_add(delay, _start_unfold_animation, my_evas_object);
    -
    - -

    Pausing and Resuming Animations

    - -

    You can pause and resume Ecore animations. To pause a running animation, use the ecore_animator_freeze() function:

    - -
    ecore_animator_freeze(Ecore_Animator *animator)
    - -

    The parameter is the Ecore_Animator to pause.

    - -

    To resume the paused animation, use the ecore_animator_thaw() function:

    - -
    ecore_animation_thaw(Ecore_Animator *animator)
    - -

    The parameter is the Ecore_Animator to resume.

    - -

    The following example pauses a transition after 5 seconds and resumes it after 5 more seconds:

    - -
    -static Eina_Bool
    -_freeze_animation(void *data)
    -{
    -   ecore_animator_freeze(data);
    -
    -   return EINA_FALSE;
    -}
    -static Eina_Bool
    -_thaw_animation(void *data)
    -{
    -   ecore_animator_thaw(data);
    -
    -   return EINA_FALSE;
    -}
    -ecore_timer_add(5, _freeze_animation, animator);
    -ecore_timer_add(10, _thaw_animation, animator);
    -
    - -

    Freeing Up Memory

    - -

    When you create an animation that does not have a timeout, you will have to manually free up the memory allocated to the Ecore_Animator object. By comparison, if the animation has a timeout, Ecore implements the mechanisms to automatically delete the animator from the list of pointers: When your animation callback returns 0 or ECORE_CALLBACK_CANCEL, the animator manager takes care of freeing up the allocated memory.

    - -

    To manually free up the memory, delete the pointer by using the ecore_animator_del() function:

    - -
    ecore_animator_del(Ecore_Animator *animator)
    - -

    The argument is the Ecore_Animator whose memory allocation to free up.

    - -

    Regardless of the type of animation, it is good practice to always ensure that the allocated memory is freed up before the program exits:

    - -
    if (animator != NULL)
    -   ecore_animator_del(animator);
    - -

    Frametime

    -

    In most cases, you will want to use the default timer ECORE_ANIMATOR_SOURCE_TIMER. This timer ticks every "frametime" seconds and allows you to perform transitions within a predefined timeline. The timer uses the system clock to tick over every Nth second, with the default being 1/30th of a second.

    - -

    To tweak performance, you can change the frametime value:

    - -
    ecore_animator_frametime_set(double frametime)
    - -

    The argument is the new frametime value.

    - - - - - - - - - - -
    Note
    Too small a value can cause performance issues, whereas too high a value can cause your animation to seem jerky.
    - -

    If you want to get the current frametime value, use the ecore_animator_frametime_get() function.

    - -

    Custom Timer

    - -

    You may want to specify a custom timer to match your animation to third-party events. For example, the filling speed of a progress bar will mainly depend on the time it takes for a task to complete and the velocity at which the remaining time estimation evolves. This kind of animation requires you to use a custom timer.

    - -

    To use a custom timer, first set ECORE_ANIMATOR_SOURCE_CUSTOM as the timer source, and then drive the timer based on an input tick source (such as another application via IPC or a vertical blanking interrupt):

    - -
    ecore_animator_custom_source_tick_begin_callback_set(Ecore_Cb func, const void *data)
    - -

    The first argument is the callback function to call on the tick start. The second argument is the data to pass to the callback function.

    - -
    ecore_animator_custom_source_tick_end_callback_set(Ecore_Cb func, const void *data)
    - -

    The first argument is the callback function to call on the tick end. The second argument is the data to pass to the callback function to set the functions that will be called to start and stop the ticking source.

    - -

    Next, trigger a tick over one frame:

    - -
    ecore_animator_custom_tick(void)
    - -

    The following example supposes a progress bar that will be refreshed every time some progress occurs:

    - -
    ecore_animator_source_set(ECORE_ANIMATOR_SOURCE_CUSTOM);
    -void _on_progress_update()
    -{
    -   // Called when some progress occurs
    -   ecore_animator_custom_tick(); // Tick (next frame in progress bar animation)
    -}
    - -

    Finally, to get the current animator source, use the ecore_animator_source_get() function.

    - - - -

    Edje Animation

    - -

    The Edje animations are based on a very simple principle: going from one state to another. If you want to animate something with Edje, you must define two states and move from the first state to the second.

    - -

    Animating a Rectangle

    - -

    This example shows how to animate a rectangle. It is positioned in the top left corner of the window and is moved to the bottom right corner in five seconds. To do that with Edje, define a part called "rectangle" with the type RECT: this part has two descriptions (or states). In the first state, the rectangle is in is the top left corner. In the second state, it is in is the bottom right corner. To create the transition, set this EDC code for Edje to switch the object from its current state to another.

    - -
    -collections 
    -{
    -   group 
    -   { 
    -      name: "main";
    -      parts 
    -      {
    -         part 
    -         { 
    -            name: "rectangle";
    -            type: RECT;
    -            description 
    -            { 
    -               state: "default" 0.0;
    -               align: 0.0 0.0;
    -               rel1 {relative: 0.0 0.0;}
    -               rel2 {relative: 0.3 0.1;}
    -               color: 0 0 255 255;
    -            }
    -            description 
    -            { 
    -               state: "default" 0.5;
    -               align: 0.0 0.0;
    -               rel1 {relative: 0.7 0.9;}
    -               rel2 {relative: 1.0 1.0;}
    -               color: 0 0 255 255;
    -            }
    -         }
    -      }
    -      programs 
    -      {
    -         program 
    -         { 
    -            name: "animation,state1";
    -            source: "";
    -            signal: "load";
    -            action: STATE_SET "default" 0.5;
    -            target: "rectangle";
    -            transition: LINEAR 5;
    -         }
    -      }
    -   }
    -}
    -
    - -

    The "rectangle" part has two descriptions that share the same name, but have a different "version".

    - -
    -part 
    -{ 
    -   name: "rectangle";
    -   type: RECT;
    -   description 
    -   { 
    -      state: "default" 0.0;
    -   }
    -   description 
    -   { 
    -      state: "default" 0.5;
    -   }
    -}
    -
    - -

    The program defines when and how to move from one state to another. A program is called upon reception of a signal from a source. Here the program is called when the signal load is received from any source.

    - -
    -program 
    -{ 
    -   name: "animation,state1";
    -   source: "";
    -   signal: "load";
    -}
    -
    - -

    An action is performed upon the signal reception. In this example, the state is changed.

    - -
    -action: STATE_SET "default" 0.5;
    -
    - -

    The program has a target, here the "rectangle".

    - -
    -target: "rectangle";
    -
    - -

    The program uses a transition to perform the action.

    - -
    -transition: LINEAR 5;
    -
    - -

    This example produces a blue rectangle that moves from the upper left to the lower right corner with a linear transition in five seconds.

    - -

    Actions

    - -

    The Edje programs are not only for animations. There are different actions, for example STATE_SET and ACTION_STOP. You may also send signals with SIGNAL_EMIT.

    - -

    The STATE_SET action changes the state of the "target".

    - -

    In the following example, the state of the part named "image" changes to "default" "0.0".

    - -
    -program 
    -{
    -   name: "animate";
    -   signal: "animate";
    -   action: STATE_SET "default" 0.0;
    -   transition: LINEAR 3.0;
    -   target: "image";
    -}
    -
    - -

    The ACTION_STOP stops the program specified by "target".

    - -
    -program 
    -{
    -   name: "animate_stop";
    -   signal: "animate_stop";
    -   action: ACTION_STOP;
    -   target: "animate_loop";
    -}
    -
    - -

    The previous example stops the program defined as "target" named animate_loop. This program runs on the animate_stop signal.

    - -

    The SIGNAL_EMIT emits a signal that is used to communicate with the application directly from the theme.

    - -

    The following example emits a signal frame_move "start" when it receives the signal mouse,down,* from the video_over part. In other words, it sends the signal frame_move "start" when the mouse is pressed in the video_over part.

    - -
    -program 
    -{ 
    -   name: "video_move_start";
    -   signal: "mouse,down,*";
    -   source: "video_mover";
    -   action: SIGNAL_EMIT "frame_move" "start";
    -}
    -
    - -

    Transitions

    - -

    The transitions available are:

    -
      -
    • LIN or LINEAR: makes a linear transition and takes the duration in seconds as the parameter
    • -
    • SIN or SINUSOIDAL: makes a sinusoidal transition and takes the duration in seconds as the parameter
    • -
    • ACCEL or ACCELERATE: makes an accelerated transition and takes the duration in seconds as the parameter
    • -
    • DECEL or DECELERATE: makes a decelerated transition and takes the duration in seconds as the parameter
    • -
    • ACCEL_FAC or ACCELERATE_FACTOR: makes an accelerated transition and takes the duration and the factor as the parameters
    • -
    • DECEL_FAC or DECELERATE_FACTOR: makes a decelerated transition and takes the duration and the factor as the parameters
    • -
    • SIN_FAC or SINUSOIDAL_FACTOR: makes a sinusoidal transition and takes the duration and the factor as the parameters
    • -
    • DIVIS or DIVISOR_INTERP: takes 3 parameters: -
        -
      • the duration
      • -
      • the initial gradient start (0.0 is horizontal, 1.0 is diagonal (linear), 2.0 is twice the gradient of linear, and so on)
      • -
      • an integer factor that defines how much the value swings outside the gradient to come back to the final resting spot at the end. 0.0 for the third parameter is equivalent to linear interpolation. Note that DIVIS may exceed 1.0.
      • -
      -
    • -
    • BOUNCE: makes a bounce transition and takes 3 parameters: -
        -
      • the duration
      • -
      • how much the bounce decays, with 0.0 giving linear decay per bounce, and higher values giving more decay
      • -
      • the number of bounces (rounded down to the nearest integer value)
      • -
      -
    • -
    • SPRING: makes a spring transition and takes 3 parameters: -
        -
      • the duration
      • -
      • the decay, with the level exceeding 1.0 on the outer swings
      • -
      • the number of spring swings
      • -
      -
    • -
    - -

    There are graphical representations of these effects in the Ecore_Evas section above.

    - -

    Chaining Edje Programs

    - -

    To define a couple of Edje programs and chain them, we can, for example, create a program to make the rectangle return to its initial state with another transition (such as BOUNCE).

    - -

    Use the statement after in the first program. after takes the name of the transition to run when the program is done.

    - -
    -after: "animation,state0";
    -
    - -

    This is how to add the bounce animation. To return the blue rectangle to its initial position with a BOUNCE transition: it bounces with a factor of 1.8, six times. This program is only to be used at the end of the first one, so it does not have any signal statement.

    - -
    -program 
    -{ 
    -   name: "animation,state0";
    -   source: "";
    -   signal: "";
    -   action: STATE_SET "default" 0.0;
    -   target: "rectangle";
    -   transition: BOUNCE 5 1.8 6;
    -}
    -
    - -

    Playing on Signals

    - -

    The programs start when they receive a signal from a source. Edje handles many kind of signals, including mouse events.

    - - - - - - - - - - -
    Note
    To show the signals, use edje_player -p myfile.edj.
    - -

    For example, in another transition the rectangle is left clicked. The corresponding signal name is mouse,clicked,1.

    - -

    For this transition, define a new state. This state changes the color and the position of the rectangle.

    - -
    -// To be placed in the "part" definition
    -description 
    -{ 
    -   state: "color" 0.0;
    -   rel1 {relative: 0.3 0.3;}
    -   rel2 {relative: 0.7 0.4;}
    -   color: 255 0 0 255;
    -}
    -
    - -

    The program is as follows:

    - -
    -program 
    -{ 
    -   name: "animation,color";
    -   source: "rectangle";
    -   signal: "mouse,clicked,1";
    -   action: STATE_SET "color" 0.0;
    -   target: "rectangle";
    -   transition: SIN 2;
    -}
    -
    - -

    This starts when the rectangle is left clicked.

    - -

    If you want to send a signal from your application when you use signals to start transitions, create a program waiting for your own special signal. For example:

    - -
    -program 
    -{ 
    -   name: "animation,menu_side,hide";
    -   source: "MenuButton";
    -   signal: "hide,sidemenu";
    -   action: STATE_SET "default" 1.0;
    -   target: "menu/side";
    -   transition: LINEAR 0.2;
    -}
    -
    - -

    This program changes the state of the target named animation,menu_side,hide to "default" 1.0. It waits for the hide,sidemenu signal emitted by a source called MenuButton.

    - -
    -edje_object_signal_emit(layout, "hide,sidemenu", "MenuButton");
    -
    - -

    This statement sends a signal named hide,sidemenu with a source named MenuButton to the object called layout.

    - -

    The edje_object_signal_emit function emits a signal on an Evas_Object part of the application.

    - -
    -edje_object_signal_emit(Evas_Object *obj,
    -                        const char *emission,
    -                        const char *source)
    -
    - -
      -
    • The first parameter is the Evas_Object, which emits the signal (layout in the example).
    • -
    • The second parameter is the emission string (the name of the signal hide,sidemenu in the example).
    • -
    • The third parameter is the source of the signal (the name of the source, MenuButton in the example).
    • -
    - -

    If you use the Elementary in the application, you can use elm_object_signal_emit. It functions exactly the same way as edje_object_signal_emit and takes the same parameters.

    - - - - - - - - - - -
    Note
    To find a complete example, use elm_object_signal_emit in the Menu Tutorial.
    - -

    Rotate with Edje

    - -

    The Edje library allows you to rotate objects, using the map statement. For example, if you want to rotate the blue rectangle on a right click, you must define a new rotate state. To enable the map on you object you must add a map part to your default state.

    - -
    -map 
    -{
    -   on: 1;
    -   smooth: 1;
    -   perspective_on: 1;
    -   rotation.x: 0;
    -   rotation.y: 0;
    -   rotation.z: 0;
    -}
    -
    - -
      -
    • on: 1; enables the map on the object
    • -
    • perspective_on: 1, enables the perspective when rotating, even without a perspective point object
    • -
    • smooth: 1; enables a smooth map rendering
    • -
    • The rotation statements define the default rotation of the object on x, y, and z axes.
    • -
    - -

    To add a new rotate state with a rotation around any axis, do the following.

    - -
    -description 
    -{ 
    -   state: "rotate" 0.0;
    -   inherit: "default" 0.0;
    -   map.rotation.z: 120;
    -}
    -
    - -

    This rotate state inherits all the default state properties, but changes the value of map.rotation.z from 0° to 120°.

    - -

    To set a program to run the rotate state, do the following.

    - -
    -program 
    -{ 
    -   name: "animation,rotate";
    -   source: "rectangle";
    -   signal: "mouse,clicked,3";
    -   action: STATE_SET "rotate" 0.0;
    -   target: "rectangle";
    -   transition: LIN 5;
    -}
    -
    - -

    This program runs on a right click on the rectangle object.

    - -

    The complete code of this example is as follows.

    - -
    -collections 
    -{
    -   group 
    -   { 
    -      name: "main";
    -      parts 
    -      {
    -         part 
    -         { 
    -            name: "rectangle";
    -            type: RECT;
    -            description 
    -            { 
    -               state: "default" 0.0;
    -               align: 0.0 0.0;
    -               rel1 {relative: 0.0 0.0;}
    -               rel2 {relative: 0.3 0.1;}
    -               map 
    -               {
    -                  on: 1;
    -                  smooth: 1;
    -                  perspective_on: 1;
    -                  rotation 
    -                  {
    -                     z: 0;
    -                     x: 0;
    -                     y: 0;
    -                  }
    -               }
    -               color: 0 0 255 255;
    -            }
    -            description 
    -            { 
    -               state: "default" 0.5;
    -               align: 0.0 0.0;
    -               rel1 {relative: 0.7 0.9;}
    -               rel2 {relative: 1.0 1.0;}
    -               color: 0 0 255 255;
    -            }
    -            description 
    -            { 
    -               state: "color" 0.0;
    -               rel1 {relative: 0.3 0.3;}
    -               rel2 {relative: 0.7 0.4;}
    -               color: 255 0 0 255;
    -            }
    -            description 
    -            { 
    -               state: "rotate" 0.0;
    -               inherit: "default" 0.0;
    -               map.rotation.z: 120;
    -            }
    -         }
    -      }
    -      programs 
    -      {
    -         program 
    -         { 
    -            name: "animation,state1";
    -            source: "";
    -            signal: "load";
    -            action: STATE_SET "default" 0.5;
    -            target: "rectangle";
    -            transition: LINEAR 1;
    -            after: "animation,state0";
    -         }
    -         program 
    -         { 
    -            name: "animation,state0";
    -            source: "";
    -            signal: "";
    -            action: STATE_SET "default" 0.0;
    -            target: "rectangle";
    -            transition: BOUNCE 2 1.8 26;
    -         }
    -         program 
    -         { 
    -            name: "animation,color";
    -            source: "rectangle";
    -            signal: "mouse,clicked,1";
    -            action: STATE_SET "color" 0.0;
    -            target: "rectangle";
    -            transition: SIN 2;
    -         }
    -         program 
    -         { 
    -            name: "animation,rotate";
    -            source: "rectangle";
    -            signal: "mouse,clicked,3";
    -            action: STATE_SET "rotate" 0.0;
    -            target: "rectangle";
    -            transition: LIN 5;
    -         }
    -      }
    -   }
    -}
    -
    -

    Elementary Animations

    - -

    Elementary transitions (Elm_Transit) allow you to apply various transition effects, such as translation and rotation, to Evas objects. Elementary transitions are mostly based on Ecore animators, but provide some transition methods at a higher level of abstraction. Elementary transitions provide a simpler way of animating objects than Ecore animators or Edje animations.

    - -

    To use Elementary transitions, you must create an Elm_Transit object and define the desired transitions using the methods of this object. After the transitions are registered, they will be automatically managed: their callback functions will be called for the set duration, and they will be deleted upon completion.

    - -

    Use Elementary transitions only when Edje animations are not sufficient. Edje animations are better at handling transitions, have more flexibility, and can be manipulated inside themes. The only drawback is that Edje animations have their own definition language. If you want to code with the C language, use Elementary transitions.

    - -

    Getting Started

    -

    The first thing you need to do when creating an transition with Elm_Transit is to build your transit object using the elm_transit_add() function:

    - -
    Elm_Transit *transit = elm_transit_add();
    - -

    You now have an Elm_Transit instance that will allow you to perform transitions on one or more objects. The transit object holds the information about the target objects and the transition effects that will be used. The transit object also contains information about animation duration, number of repetitions, auto-reverse, and so on. The transit object starts playing as soon as the application enters the main loop.

    - -

    Adding Objects to an Animation

    - -

    You can add your Evas objects to your transition using the elm_transit_object_add() function:

    - -
    elm_transit_object_add(Elm_Transit *transit, Evas_Object *obj)
    - -

    The first argument is the Elm_Transit instance that handles the transition. The second argument is the Evas object to animate.

    - - - - - - - - - - -
    Note

    The Evas object can be a low-level component, such as a rectangle, but also a UI component, such as a button, image, or calendar.

    -

    If you want to animate an Evas object handled by a container, such as a box, you need to either unpack the object before the animation or animate the whole container.

    - -

    If you want to know which objects are currently in your transition, use the elm_transit_objects_get() function. You will get a list of all the objects that are subject to the transition.

    - -

    At any time, you can remove objects from the transition:

    - -
    elm_transit_object_remove(Elm_Transit *transit, Evas_Object *obj)
    - -

    The first argument is the Elm_Transit instance that handles the transition. The second argument is the Evas object to remove from the transition.

    - - - - - - - - - - -
    Note
    After you have added at least one Evas object to your transition, if the list of objects gets emptied somehow, be it because the transition has been terminated or all objects have been deleted, the transition will be automatically deleted. Otherwise, you will have to delete the transition by yourself using the elm_transit_del() function. If you delete the transit while the transition is running, the transition will stop.
    - -

    Adding Images to an Animation

    - -

    If you do not want to manage UI components for animating images, Elm_Transit provides a helper function for directly manipulating images:

    - -
    -elm_transit_effect_image_animation_add(Elm_Transit *transit, Eina_List *images)
    -
    - -

    The first argument is the Elm_Transit instance that handles the transition. The second argument is a list of the image paths.

    - - - - - - - - - - -
    Note
    This list and its contents will be deleted after the effect ends by the elm_transit_effect_image_animation_context_free() function.
    - -

    You can now define your image transitions exactly the same way as with any Evas object.

    - -

    The following example shows how to use Elm_Transit with images:

    - -
    char buf[PATH_MAX];
    -Eina_List *images = NULL;
    -Elm_Transit *transit = elm_transit_add();
    -snprintf(buf, sizeof(buf), "%s/images/btn_default.png", PACKAGE_DATA_DIR);
    -images = eina_list_append(images, eina_stringshare_add(buf));
    -snprintf(buf, sizeof(buf), "%s/images/btn_hover.png", PACKAGE_DATA_DIR);
    -images = eina_list_append(images, eina_stringshare_add(buf));
    -elm_transit_effect_image_animation_add(transit, images);
    - -

    Animation Duration

    - -

    With Elm_Transit, setting the transition duration is mandatory. To set the duration, use the elm_transit_duration_set() function:

    - -
    elm_transit_duration_set(Elm_Transit *transit, double duration)
    - -

    The first argument is the Elm_Transit instance that handles the transition. The second argument is the duration in seconds.

    - - - - - - - - - - -
    Note
    The purpose of Elm_Transit is to abstract the low-level details of object interpolation, so you cannot create an infinite transition by specifying the duration. However, you can make your transition last forever using the repeat function.
    - -

    The following example shows how to make a complete revolution of the target Evas object in 2 seconds:

    - -
    -Elm_Transit *transit = elm_transit_add();
    -elm_transit_object_add(transit, my_evas_object);
    -elm_transit_effect_rotation_add(transit, 0.0, 360);
    -elm_transit_duration_set(transit, 2.0);
    -elm_transit_go(transit);
    -
    - -

    To get the duration of the transition, use the elm_transit_duration_get() function.

    - -

    Animation Acceleration Mode ("Tween Mode")

    - -

    Elm_Transit supports a number of built-in interpolation methods. By default, all interpolations are linear. If you want to change the animation's dynamics, use the elm_transit_tween_mode_set() function:

    - -
    elm_transit_tween_mode_set(Elm_Transit *transit, Elm_Transit_Tween_Mode tween_mode)
    - -

    The first argument is the Elm_Transit instance that handles the transition. The second argument is the tween mode of the transition, which can be one of the following:

    -
      -
    • ELM_TRANSIT_TWEEN_MODE_LINEAR: The default mode.
    • -
    • ELM_TRANSIT_TWEEN_MODE_SINUSOIDAL: The transition starts with acceleration and ends with deceleration.
    • -
    • ELM_TRANSIT_TWEEN_MODE_DECELERATE: The transition decelerates over time.
    • -
    • ELM_TRANSIT_TWEEN_MODE_ACCELERATE: The transition accelerates over time.
    • -
    - -

    To get the current tween mode, use the elm_transit_tween_mode_get() function.

    - -

    Animation Repeat

    - -

    To set a transition to repeat, use the elm_transit_repeat_times_set() function:

    - -
    elm_transit_repeat_times_set(Elm_Transit *transit, int repeat)
    - -

    The function takes the following arguments:

    -
      -
    • The transition you want to repeat.
    • -
    • The number of times the transition repeats.
    • -
    - - - - - - - - - - -
    Note
    If the repeat argument is set to 0, the transition will not loop at all. If set to 1, the transition will run twice. If set to a negative value, the transition will repeat forever.
    - -

    To get the repeat value, use the elm_transit_repeat_times_get() function. The default value is 0.

    - -

    The following example shows how to make an Evas object spin for 3 complete revolutions in 6 seconds:

    - -
    Elm_Transit *transit = elm_transit_add();
    -elm_transit_object_add(transit, my_evas_object);
    -elm_transit_effect_rotation_add(transit, 0.0, 360);
    -elm_transit_duration_set(transit, 2.0);
    -elm_transit_repeat_set(transit, 3.0);
    -elm_transit_go(transit);
    - -

    Animation Auto-reverse

    - -

    Elm_Transit provides a helper function for automatically reversing the transition once it finishes:

    - -
    elm_transit_auto_reverse_set(Elm_Transit *transit, Eina_Bool reverse)
    - -

    The first argument is the transition you want to reverse. The second argument is the reverse state. If the reverse state is set to EINA_TRUE, this function will perform the same transition backwards as soon as the first transition is complete.

    - - - - - - - - - - -
    Note
    -

    Reversing the transition doubles the duration of the transition. Moreover, if the transition is set to repeat, the transition will run back and forth until the repeat count is finished.

    -

    You can calculate the duration as follows if both auto-reverse and repeat are set: 2 * duration * repeat.

    -
    - -

    The following example shows how to make an object perform half a turn and then reverse the animation to its original position in 4 seconds:

    - -
    -Elm_Transit *transit = elm_transit_add();
    -elm_transit_object_add(transit, my_evas_object);
    -elm_transit_effect_rotation_add(transit, 0.0, 360);
    -elm_transit_duration_set(transit, 2.0);
    -elm_transit_auto_reverse_set(transit, EINA_TRUE);
    -elm_transit_go(transit);
    -
    - -

    To determine whether the auto-reverse mode is enabled, use the elm_transit_auto_reverse_get() function.

    - -

    Transitions

    - -

    We distinguish two main transition types:

    -
      -
    • Transitions that are applied to the properties of objects, such as position, size, angle, and color.
    • -
    • Transitions from one object to another, where the first object is hidden to let the second one appear.
    • -
    -

    All transitions are based on the same principle: we set the starting and the ending values for the properties we want to animate, we then set the lifespan of the animation, and finally we inquire the preferred interpolation method (such as linear, acceleration, or bounce).

    - -

    You must declare the transitions after the parent window has been created, since the transition effects make use of the geometric properties of the parent window. If the parent window does not yet exist when calculating the interpolation, the interpolation may end up being based on wrong information.

    - -

    Built-in Transitions

    - -

    Elm_Transit provides several built-in transition definitions that are useful for the most common cases, so you that will not have to code them from scratch.

    - -

    All these built-in effects are implemented as follows:

    - -
    Elm_Transit *transit = elm_transit_add();
    -elm_transit_effect_add(transit,
    -                       elm_transit_effect_translation_op,
    -                       elm_transit_effect_translation_context_new(),
    -                       elm_transit_effect_translation_context_free);
    - -
      -
    • transit: The Elm_Transit object that contains the target Evas objects and all the information needed to setup the transition.
    • -
    • elm_transit_effect_translation_op: The callback function that performs the transition (resizing interpolation in this example).
    • -
    • elm_transit_effect_translation_context_new(): The callback function that returns the context used in the transition for calculations. In this example, the context is the coordinates of the before and after objects.
    • -
    • elm_transit_effect_translation_context_free: The callback function that frees up the memory once the transition is complete.
    • -
    - -

    All the definitions above can be rewritten as follows:

    - -
    -Elm_Transit *transit = elm_transit_add();
    -elm_transit_effect_translation_add(transit, from_x, from_y, to_x, to_y);
    -
    - -

    Translation

    -

    To perform a translation on an Evas object, use the following method:

    - -
    -elm_transit_effect_translation_add(Elm_Transit *transit,
    -                                   Evas_Coord from_dx,
    -                                   Evas_Coord from_dy,
    -                                   Evas_Coord to_dx,
    -                                   Evas_Coord to_dy)
    -
    - -
      -
    • The first argument is the transit object that contains (among other things) all the Evas objects subject to the translation.
    • -
    • from_dx: The starting X coordinate (source).
    • -
    • from_dy: The starting Y coordinate (source).
    • -
    • to_dx: The ending X coordinate (destination).
    • -
    • to_dy: The ending Y coordinate (destination).
    • -
    - -

    The following example shows how to slide an Evas object (a rectangle) on a 45-degree diagonal, from bottom-left to top-right, at a constant speed, and in 1 second:

    - -
    -Elm_Transit *transit = elm_transit_add();
    -elm_transit_object_add(transit, rectangle);
    -elm_transit_effect_translation_add(transit, 0, 0, 280, 280);
    -elm_transit_duration_set(transit, 1);
    -elm_transit_go(transit);
    -
    - -

    Color Transition

    - -

    Color transitions allow you to dynamically change the color of Evas objects. The first argument is the transit object, while the other arguments will be used to define the color transition using RGB colors. There is also an alpha channel that controls the opacity of the color (the background of the object, not the object itself).

    - -
    -elm_transit_effect_color_add(Elm_Transit *transit,
    -                             unsigned int from_r,
    -                             unsigned int from_g,
    -                             unsigned int from_b,
    -                             unsigned int from_a,
    -                             unsigned int to_r,
    -                             unsigned int to_g,
    -                             unsigned int to_b,
    -                             unsigned int to_a)
    -
    - -
      -
    • transit: The transit object that contains (among other things) all the Evas objects subject to the translation.
    • -
    • from_r: The start value for "Red".
    • -
    • from_g: The start value for "Green".
    • -
    • from_b: The start value for "Blue".
    • -
    • from_a: The start value for "Alpha".
    • -
    • to_r: The end value for "Red".
    • -
    • to_g: The end value for "Green".
    • -
    • to_b: The end value for "Blue".
    • -
    • to_a: The end value for "Alpha".
    • -
    - -

    The following example shows how to transit a rectangle from red to blue in 3 seconds:

    - -
    -Elm_Transit *transit = elm_transit_add();
    -elm_transit_object_add(transit, rectangle);
    -elm_transit_effect_color_add(transit, // Target object
    -                             255, 0, 0, 255, // From color
    -                             0, 0, 255, 255); // To color
    -elm_transit_duration_set(transit, 3);
    -elm_transit_go(transit);
    -
    - -

    Rotation

    - -
    elm_transit_effect_rotation_add(Elm_Transit *transit, float from_degree, float to_degree)
    - -
      -
    • transit: The transit object that contains (among other things) all the Evas objects subject to the translation.
    • -
    • from_degree: The start degree of rotation.
    • -
    • to_degree: The end degree of rotation.
    • -
    - -

    This function can be used to perform a rotation on any Evas object. It works the same way as the other transit effects and takes two arguments for the starting and ending angles. Note that if you apply a rotation on multiple objects, they will individually mill around and not act as a group. If you want several objects to revolve around a common point, you must encapsulate the objects into a single parent object and apply the rotation to the parent object. The following example shows how to achieve this:

    - -
    -// Parent container
    -Evas_Object *parent = elm_box_add(my_window);
    -evas_object_show(parent);
    -elm_box_horizontal_set(parent, EINA_TRUE);
    -elm_box_homogeneous_set(parent, EINA_TRUE);
    -
    -// Button 1
    -Evas_Object *btn1 = elm_button_add(parent);
    -elm_object_text_set(btn1, "Btn1");
    -elm_box_pack_start(parent, btn1);
    -evas_object_show(btn1);
    -
    -// Button 2
    -Evas_Object *btn2 = elm_button_add(parent);
    -elm_object_text_set(btn2, "Btn2");
    -elm_box_pack_end(parent, btn2);
    -evas_object_show(btn2);
    -
    -// Make the parent container do a 360 degrees spin
    -Elm_Transit *transit = elm_transit_add();
    -elm_transit_object_add(transit, parent);
    -elm_transit_effect_rotation_add(transit, 0.0, 360);
    -elm_transit_duration_set(transit, 2.0);
    -elm_transit_go(transit);
    -
    - -

    Wipe Effect

    - -

    The wipe effect is designed to dynamically hide or show any element on the scene.

    - -
    -elm_transit_effect_wipe_add(Elm_Transit *transit,
    -                            Elm_Transit_Effect_Wipe_Type type,
    -                            Elm_Transit_Effect_Wipe_Dir dir)
    -
    - -

    In addition to the Elm_Transit instance passed as the first argument, the function takes the following arguments:

    - -
      -
    • type: The wipe type Elm_Transit_Effect_Wipe_Type defines whether to show or hide the target elements. The value can be one of the following: -
        -
      • ELM_TRANSIT_EFFECT_WIPE_TYPE_HIDE
      • -
      • ELM_TRANSIT_EFFECT_WIPE_TYPE_SHOW
      • -
      -
    • -
    • dir: The wipe direction Elm_Transit_Effect_Wipe_Dir defines in which direction the target will progressively appear or disappear. The value can be one of the following: -
        -
      • ELM_TRANSIT_EFFECT_WIPE_DIR_LEFT
      • -
      • ELM_TRANSIT_EFFECT_WIPE_DIR_RIGHT
      • -
      • ELM_TRANSIT_EFFECT_WIPE_DIR_UP
      • -
      • ELM_TRANSIT_EFFECT_WIPE_DIR_DOWN
      • -
      -
    • -
    - -

    The following example shows how to make an object disappear progressively from left to right:

    - -
    -Elm_Transit *transit = elm_transit_add();
    -elm_transit_object_add(transit, my_evas_object);
    -elm_transit_effect_wipe_add(transit,
    -                            ELM_TRANSIT_EFFECT_TYPE_HIDE,
    -                            ELM_TRANSIT_EFFECT_WIPE_DIR_RIGHT);
    -elm_transit_duration_set(transit, 2.0);
    -elm_transit_go(transit);
    -
    - -

    Zoom Effect

    -

    Elm_Transit provides a zoom function.

    - -
    -elm_transit_effect_zoom_add(Elm_Transit *transit,
    -                            float from_rate,
    -                            float to_rate)
    -
    - -
      -
    • transit: The transit object that contains (among other things) all the Evas objects subject to the translation.
    • -
    • from_rate: The starting level of the zoom.
    • -
    • to_rate: The ending level of the zoom.
    • -
    - -

    The from_rate argument defines the scale of the target objects at the beginning of the animation. A value of 1 represents the initial scale of the objects.

    - -

    Setting the value of the to_rate argument to 2 will double the size of the target objects (double the width and double the height). When using this effect, the width and height of a target object will remain proportional to one another. If you want to customize the zoom effect, use the elm_transit_effect_resizing_add() function.

    - -

    The following example shows how to implement a zoom-out transition. At the end of the 2-secondstransition, the animated object will be half its original size.

    - -
    -Elm_Transit *transit = elm_transit_add();
    -elm_transit_object_add(transit, my_evas_object);
    -elm_transit_effect_zoom_add(transit, 1, 0.5);
    -elm_transit_duration_set(transit, 2.0);
    -elm_transit_go(transit);
    -
    - -

    Resizing Effect

    - -

    The resizing effect allows you to design an interpolation of the width and height attributes of one or more target elements.

    - -
    -elm_transit_effect_resizing_add(Elm_Transit *transit,
    -                                Evas_Coord from_w,
    -                                Evas_Coord from_h,
    -                                Evas_Coord to_w,
    -                                Evas_Coord to_h)
    -
    - -
      -
    • transit: The transit object that contains (among other things) all the Evas objects subject to the translation.
    • -
    • from_w: The starting width.
    • -
    • from_h: The starting height.
    • -
    • to_w: The ending width.
    • -
    • to_h: The ending height.
    • -
    - -

    The from_w and from_h arguments define the size at the beginning of the animation. The to_w and to_h arguments define the size at the end.

    - - - - - - - - - - -
    Note
    If you are planning to use this method to hide an Evas object by setting one of the length attributes to zero, consider using the elm_transit_effect_wipe_add() function instead.
    - -

    The following example shows how to make a rectangle exchange its width and height properties in a 2-second transition:

    - -
    -Evas_Coord w, h;
    -evas_object_geometry_get(my_evas_object, NULL, NULL, &w, &h);
    -
    -Elm_Transit *transit = elm_transit_add();
    -elm_transit_object_add(transit, my_evas_object);
    -elm_transit_effect_resize_add(transit, // Transition object
    -                              w, h, // Original sizing
    -                              h, w); // Target sizing
    -elm_transit_duration_set(transit, 2.0);
    -elm_transit_go(transit);
    -
    - -

    Flip Effect

    -

    This transition combines the target Evas objects in pairs, so that one object will show up while the other one disappears. This association relates the even objects in the transit list of objects with the odd ones. The even objects are shown at the beginning of the animation, and the odd objects shown when the transition is complete. In other words, the effect applies to each pair of objects in the order in which they are listed in the transit list of objects.

    - -

    The flip effect itself is a pseudo-3D effect where the first object in the pair is the front object and the second one is the back object. When the transition launches, the front object rotates around a preferred axis in order to let the back object take its place.

    - -
    -elm_transit_effect_flip_add(Elm_Transit *transit,
    -                            Elm_Transit_Effect_Flip_Axis axis,
    -                            Eina_Bool cw)
    -
    - -

    The first argument is the transit object. The second argument is the preferred axis of rotation:

    -
      -
    • ELM_TRANSIT_EFFECT_FLIP_AXIS_X
    • -
    • ELM_TRANSIT_EFFECT_FLIP_AXIS_Y
    • -
    - -

    The third argument is the direction of the rotation:

    -
      -
    • EINA_TRUE is clockwise.
    • -
    • EINA_FALSE is counter-clockwise.
    • -
    - -

    The following example shows how to create a coin that flips indefinitely. Note that we use images as Elementary UI components for demonstration purposes. You can use the elm_transit_effect_image_animation_add() function if you do not want to bother creating UI components.

    - -
    -// Coin Heads
    -Evas_Object *coin_heads = elm_image_add(ad->win);
    -if (!elm_image_file_set(coin_heads, IMG_DIR"/coin_heads.png", NULL))
    -   printf("error: could not load image");
    -elm_win_resize_object_add(ad->win, coin_heads);
    -
    -// Coin Tails
    -Evas_Object *coin_tails = elm_image_add(ad->win);
    -if (!elm_image_file_set(coin_tails, IMG_DIR"/coin_tails.png", NULL))
    -   printf("error: could not load image");
    -elm_win_resize_object_add(ad->win, coin_tails);
    -
    -// Transition definition
    -Elm_Transit *transit = elm_transit_add();
    -elm_transit_object_add(transit, coin_heads);
    -elm_transit_object_add(transit, coin_tails);
    -elm_transit_duration_set(transit, 2.0);
    -elm_transit_auto_reverse_set(transit, EINA_TRUE);
    -elm_transit_repeat_times_set(transit, -1);
    -elm_transit_effect_flip_add(transit, ELM_TRANSIT_EFFECT_FLIP_AXIS_X, EINA_TRUE);
    -elm_transit_go(transit);
    -
    - -

    Figure: Coin flip

    -

    Coin flip

    - -

    Resizable Flip Effect

    -

    In the flip example above, we used two objects that have the same size. However, you may sometimes want to flip from one object to another object with different size attributes. The most common example would be using buttons with dimensions that depend on their contents (such as labels). If you decide to use the classic elm_transit_effect_flip_add() function, the size of the object will change at the moment one object becomes completely hidden and the other one begins to show up. If you wish to interpolate the size attributes as well, use the elm_transit_effect_resizable_flip_add() function:

    - -
    -elm_transit_effect_resizable_flip_add(Elm_Transit *transit,
    -                                      Elm_Transit_Effect_Flip_Axis axis,
    -                                      Eina_Bool cw)
    -
    - -

    The first argument is the transit object. The second argument is the preferred axis of rotation:

    -
      -
    • ELM_TRANSIT_EFFECT_FLIP_AXIS_X
    • -
    • ELM_TRANSIT_EFFECT_FLIP_AXIS_Y
    • -
    - -

    The third argument is the direction of the rotation:

    -
      -
    • EINA_TRUE is clockwise.
    • -
    • EINA_FALSE is counter-clockwise.
    • -
    - -

    This function works the exact same way as the standard flip effect function.

    - -

    Fade Effect

    - -

    This effect is used to transition from one Evas object to another one using a fading effect: the first object will slowly disappear to let the second object take its place.

    - -
    elm_transit_effect_fade_add(Elm_Transit *transit)
    - -

    This effect is applied to each pair of objects in the order in which they are listed in the transit list of objects. The first object in the pair will be the before object and the second one will be the after object.

    - -

    Building on the coin flip example, the following example shows how to fade out one face of the coin while fading in the other face:

    - -
    -Elm_Transit *transit = elm_transit_add();
    -elm_transit_object_add(transit, coin_heads);
    -elm_transit_object_add(transit, coin_tails);
    -elm_transit_duration_set(transit, 2.0);
    -elm_transit_effect_fade_add(transit);
    -elm_transit_go(transit);
    -
    - -

    If you simply want to hide an object with a fade transition, consider using a transparent after object.

    - -

    Blend Effect

    - -

    Another transition involving at least two Evas objects is the blend effect. This transition makes the before object blurry before the after object appears.

    - -
    elm_transit_effect_blend_add(Elm_Transit *transit)
    - -

    The argument is the transition target of the blend effect.

    - -

    Building on the coin flip example, the following example shows how to blur out one face of the coin while blurring in the other face:

    - -
    -Elm_Transit *transit = elm_transit_add();
    -elm_transit_object_add(transit, coin_heads);
    -elm_transit_object_add(transit, coin_tails);
    -elm_transit_duration_set(transit, 2.0);
    -elm_transit_effect_blend_add(transit);
    -elm_transit_go(transit);
    -
    - -

    If you simply want to hide an object with a blur transition, consider using a transparent after object.

    - -

    Combining Transitions

    - -

    To use multiple transitions at the same time on the same objects, simply declare the transitions one after the other.

    - -

    Building on the coin flip example, the following example shows how to roll the coin on the ground using a rotation and a translation effect:

    - -
    -Evas_Object *coin_heads = elm_image_add(ad->win);
    -if (!elm_image_file_set(coin_heads, IMG_DIR"/coin_heads.png", NULL))
    -   printf("error: could not load image");
    -evas_object_resize(coin_heads, 100, 100);
    -evas_object_show(coin_heads);
    -
    -Elm_Transit *transit = elm_transit_add();
    -elm_transit_object_add(transit, coin_heads);
    -elm_transit_duration_set(transit, 5.0);
    -elm_transit_effect_translation_add(transit, 0, 0, 3.1415 * 2 * 100, 0);
    -elm_transit_effect_rotation_add(transit, 0, 360);
    -elm_transit_go(transit);
    -
    - -

    Animation Chain

    - -

    Now that we have listed all the effects that can be implemented using Elm_Transit, we will see how to chain transitions into sequences. To create complex, chained animations without worrying about synchronization between the transitions, use the elm_transit_chain_transit_add() function. This function takes as arguments two Elm_Transit objects and will automatically take care of the chaining for you: the second transition will start as soon as the first transition is finished.

    - -

    The following example shows how to move a datetime component on a square trajectory:

    - -
    -Evas_Object *dt = elm_datetime_add(ad->win);
    -evas_object_resize(dt, 350, 50);
    -evas_object_show(dt);
    -
    -// The first transition
    -Elm_Transit *t1 = elm_transit_add();
    -elm_transit_object_add(t1, dt);
    -elm_transit_duration_set(t1, 2);
    -elm_transit_effect_translation_add(t1, 0, 0, 100, 0);
    -
    -// The second transition
    -Elm_Transit *t2 = elm_transit_add();
    -elm_transit_object_add(t2, dt);
    -elm_transit_duration_set(t2, 2);
    -elm_transit_effect_translation_add(t2, 100, 0, 100, 100);
    -
    -// The third transition
    -Elm_Transit *t3 = elm_transit_add();
    -elm_transit_object_add(t3, dt);
    -elm_transit_duration_set(t3, 2);
    -elm_transit_effect_translation_add(t3, 100, 100, 0, 100);
    -
    -// The fourth transition
    -Elm_Transit *t4 = elm_transit_add();
    -elm_transit_object_add(t4, dt);
    -elm_transit_duration_set(t4, 2);
    -elm_transit_effect_translation_add(t4, 0, 100, 0, 0);
    -
    -// Chaining the transitions
    -elm_transit_chain_transit_add(t1, t2);
    -elm_transit_chain_transit_add(t2, t3);
    -elm_transit_chain_transit_add(t3, t4);
    -
    -// Starting the transitions
    -elm_transit_go(t1);
    -
    - -

    Note that we cannot use transition chaining to make a loop animation, since the transit object is automatically destroyed as soon as the transition completes. Therefore, you cannot do something like this:

    - -
    elm_transit_chain_transit_add(t4, t1);
    - -

    To create a looped animation chain, you have to use low-level components provided by the Ecore and Evas transition libraries, or you can use the elm_transit_del_cb_set() function to define a callback function for when a transition gets deleted. This way, you could recreate your objects and reiterate the transition chain as soon as the last transition ends.

    - -
    -elm_transit_del_cb_set(Elm_Transit *transit, Elm_Transit_Del_Cb cb, void *data)
    -
    - -

    The first argument is the transition object. The second argument is the callback function to run on transition delete. The third argument is the data to pass to the callback function.

    - -

    You can severe the chain relationship between two transits by using the elm_transit_chain_transit_del() function:

    - -
    elm_transit_chain_transit_del(Elm_Transit *transit, Elm_Transit *chain_transit)
    - -

    The first argument is the first transition in the chain. The second argument is the second transition in the chain.

    - -

    To get the current chain transit list, use the elm_transit_chain_transits_get() function.

    - -

    Animation Timeline

    - -

    After you have defined all the properties that define your transition, start the transition with the elm_transit_go() function:

    - -
    elm_transit_go(Elm_Transit *transit)
    - -

    You can maintain full control over the execution process even after the transition has started. You can pause the transition by setting the paused argument to EINA_TRUE:

    - -
    elm_transit_paused_set(Elm_Transit *transit, Eina_Bool paused)
    - -

    You can resume the transition by using the same method but setting the paused argument to EINA_FALSE. If you want to know whether the transition is currently paused, use the elm_transit_paused_get() function.

    - -

    You can remain informed about the present transition flow and get the current frame by using the elm_transit_progress_value_get() function. This function will return the timeline position of the animation, ranging between 0.0 (start) and 1.0 (end).

    - -

    Custom Transition

    - -

    Elm_Transit provides a standard function for defining any effect of your choosing that will be applied to some context data:

    - -
    -elm_transit_effect_add(Elm_Transit *transit,
    -                       Elm_Transit_Effect_Transition_Cb transition_cb,
    -                       Elm_Transit_Effect *effect,
    -                       Elm_Transit_Effect_End_Cb end_cb)
    -
    - -

    The first argument is the transition target of the new effect. The second argument is the transition callback function. The third argument is the new effect. The fourth argument is the callback function to call at the end of the effect.

    - -

    As described earlier in this programming guide, this function embraces three callbacks that will allow you to define every aspects of your transition from its creation to its deletion. The following is an example of how to build a custom resizing animation.

    - -

    First, we define a structure capable of holding the context information about resizing an Evas object:

    - -
    -typedef struct
    -{
    -   struct _size
    -   {
    -      Evas_Coord w, h;
    -   }
    -   from, to;
    -}
    -Custom_Effect;
    -
    - -

    We can now implement our custom resizing callback function. This function takes the following arguments:

    - -
      -
    • The context data that holds the custom properties of our transition, which are used as parameters to calculate the interpolation.
    • -
    • The transit object that contains the list of our Evas objects to animate and all the information about duration, auto-reverse, looping, and so on.
    • -
    • The progress (position along the animation timeline) that ranges from 0.0 to 1.0 and allows us to calculate the desired interpolation for each frame.
    • -
    - -
    -static void
    -_custom_op(void *data, Elm_Transit *transit, double progress)
    -{
    -   if (!data) return;
    -   Evas_Coord w, h;
    -   Evas_Object *obj;
    -   const Eina_List *elist;
    -   Custom_Effect *custom_effect = data;
    -   const Eina_List *objs = elm_transit_objects_get(transit);
    -   if (progress < 0.5)
    -   {
    -      h = custom_effect->from.h + (custom_effect->to.h * progress * 2);
    -      w = custom_effect->from.w;
    -   }
    -   else
    -   {
    -      h = custom_effect->from.h + custom_effect->to.h;
    -      w = custom_effect->from.w + (custom_effect->to.w * (progress - 0.5) * 2);
    -   }
    -   EINA_LIST_FOREACH(objs, elist, obj)
    -      evas_object_resize(obj, w, h);
    -}
    -
    - -

    The callback function above resizes our Evas objects in two steps. During the first half of the transition, only the height changes, while the width remains the same. During the second half, it is the other way around until we get to the desired size.

    - -

    You must then define the context used by your animation:

    - -
    -static void*
    -_custom_context_new(Evas_Coord from_w, Evas_Coord from_h, Evas_Coord to_w, Evas_Coord to_h)
    -{
    -   Custom_Effect *custom_effect;
    -
    -   custom_effect = calloc(1, sizeof(Custom_Effect));
    -   if (!custom_effect) return NULL;
    -
    -   custom_effect->from.w = from_w;
    -   custom_effect->from.h = from_h;
    -   custom_effect->to.w = to_w - from_w;
    -   custom_effect->to.h = to_h - from_h;
    -
    -   return custom_effect;
    -}
    -
    - -

    You must define the function that will take care of deleting all the context objects used by your custom transition and free up the allocated memory:

    - -
    -static void
    -_custom_context_free(void *data, Elm_Transit *transit __UNUSED__)
    -{
    -   free(data);
    -}
    -
    - -

    Finally, apply your custom transition to your Elm_Transit object:

    - -
    -Elm_Transit *transit = elm_transit_add();
    -elm_transit_effect_add(transit,
    -                       _custom_op,
    -                       _custom_context_new(),
    -                       _custom_context_free);
    -
    - -

    If you want to delete an effect from your effects list, use the elm_transit_effect_del() function.

    - - - - -

    Evas Map Effects

    - -

    Evas Map animations allow you to apply transformations to all types of objects by way of UV mapping.

    - -

    In UV mapping, you map points in the source object to 3D space positions in the target object. This allows for rotation, perspective, scale, and other transformation effects, depending on the map. In addition, each map point can carry a multiplier color, which, if properly calculated, can be used to apply 3D shading effects on the target object.

    - -

    Evas provides both raw and easy-to-use functions for UV mapping. The raw functions allow you to create UV maps outside Evas and import them into your application, for example by loading them from an external file. The easy-to-use functions allow you to create UV maps directly in Evas by calculating the map points based on high-level parameters, such as rotation angle and ambient light.

    - -

    Map Points

    - -

    A map consists of a set of points. (Currently, only four points are supported.) Each point contains X and Y canvas coordinates that can be used to alter the geometry of the mapped object, and a Z coordinate that indicates the depth of the point. The Z coordinate does not normally affect the map, but several utility functions use it to calculate the right position of the point given the other parameters.

    - -

    First, create an Evas_Map object using the evas_map_new() function. This function creates the specified number of map points (currently only up to four points). Each point is empty and ready to be modified with Evas_Map functions.

    - -
    Evas_Map *m = evas_map_new(4);
    - -

    If you want to get the size (number of points) of an existing map, use the evas_map_count_get() function.

    - -

    To set the coordinates for each point, use the evas_map_point_coord_set() function:

    - -
    evas_map_point_coord_set(Evas_Map *m, int idx, Evas_Coord x, Evas_Coord y, Evas_Coord z)
    - -

    The following example shows a common way to define a map that matches the geometry of a rectangle (a square in this case):

    - -
    -evas_map_point_coord_set(m, 0, 100, 100, 0);
    -evas_map_point_coord_set(m, 1, 300, 100, 0);
    -evas_map_point_coord_set(m, 2, 300, 300, 0);
    -evas_map_point_coord_set(m, 3, 100, 300, 0);
    -
    - -

    Figure: Map

    -

    Map

    - -

    The following examples all produce the same result as the above example, but with simpler code:

    - -
      -
    • -

      To create a rectangle map using the starting X and Y coordinates combined with width and height, use the evas_map_util_points_populate_from_geometry() function:

      -
      evas_map_util_points_populate_from_geometry(Evas_Map *m, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas_Coord h, Evas_Coord z)
      -

      The following example creates the same map as above:

      -
      evas_map_util_points_populate_from_geometry(m, 100, 100, 200, 200, 0);
      -
    • -
    • -

      To create a map based on the geometry of a given object, use the evas_map_util_points_populate_from_object() or evas_map_util_points_populate_from_object_full() function. The former sets the Z coordinate of all points to 0, whereas the latter allows you to define the same custom Z coordinate for all points:

      -
      evas_map_util_points_populate_from_object(Evas_Map *m, const Evas_Object *obj)
      -
      evas_map_util_points_populate_from_object_full(Evas_Map *m, const Evas_Object *obj, Evas_Coord z)
      -

      The following example creates the same map as above:

      -
      -Evas_Object *o;
      -evas_object_move(o, 100, 100);
      -evas_object_resize(o, 200, 200);
      -evas_map_util_points_populate_from_object(m, o);
      -// OR
      -evas_map_util_points_populate_from_object_full(m, o, 0);
      -
    • -
    - -

    You can apply several effects to an object by simply setting each point of the map to the appropriate coordinates. The following example shows how to create a simulated perspective:

    - -

    Figure: Simulated perspective

    -

    Simulated perspective

    - -
    -evas_map_point_coord_set(m, 0, 100, 100, 0);
    -evas_map_point_coord_set(m, 1, 250, 120, 0);
    -evas_map_point_coord_set(m, 2, 250, 280, 0);
    -evas_map_point_coord_set(m, 0, 100, 300, 0);
    -
    - -

    In the above example, the Z coordinate is unused: when setting points by hand, the Z coordinate is irrelevant.

    - -

    If you want to get the actual coordinates of a map, use the evas_map_point_coord_get() function:

    - -
    evas_map_point_coord_get(const Evas_Map *m, int idx, Evas_Coord *x, Evas_Coord *y, Evas_Coord *z)
    - -

    After you have defined the map points, apply them to your map for transformation:

    - -
    -evas_object_map_set(o, m);
    -evas_object_map_enable_set(o, EINA_TRUE);
    -
    - -

    Finally, after you are done with the map, release the memory allocated to it using the evas_map_free() function:

    - -
    evas_map_free(m);
    - -

    The utility functions described in the next section allow you to perform the above tasks with less coding work.

    - -

    Utility Functions

    - -

    Utility functions take an already configured map and allow you to easily modify it to produce specific effects. For example, to rotate an object around its center, you need the rotation angle and the coordinates of each corner of the object to perform the math required to get the new set of coordinates that needs to be set for the map. Evas provides a utility function that does the math for you:

    - -
    evas_map_util_rotate(Evas_Map *m, double degrees, Evas_Coord cx, Evas_Coord cy)
    - -

    This function rotates the map based on the angle and the center coordinates of the rotation provided as arguments. A positive angle rotates the map clockwise, while a negative angle rotates the map counter-clockwise.

    - -

    The following example shows how to rotate an object around its center point by 45 degrees clockwise. In the following figure, the center of rotation is the red dot.

    - -
    -evas_object_geometry_get(o, &x, &y, &w, &h);
    -m = evas_map_new(4);
    -evas_map_util_points_populate_from_object(m, o);
    -evas_map_util_rotate(m, 45, x + (w / 2), y + (h / 2));
    -evas_object_map_set(o, m);
    -evas_object_map_enable_set(o, EINA_TRUE);
    -evas_map_free(m);
    -
    - -

    Figure: Rotating around the center point

    -

    Rotating around the center point

    - -

    You can rotate the object around any other point simply by setting the last two arguments of the evas_map_util_rotate() function to the appropriate values:

    - -
    evas_map_util_rotate(m, 45, x + w - 20, y + h - 20);
    - -

    Figure: Rotating around other points

    -

    Rotating around other points

    - -

    You can also set the center of the window as the center of the rotation using the appropriate coordinates of the Evas canvas:

    - -
    -evas_output_size_get(evas, &w, &h);
    -m = evas_map_new(4);
    -evas_map_util_points_populate_from_object(m, o);
    -evas_map_util_rotate(m, 45, w, h);
    -evas_object_map_set(o, m);
    -evas_object_map_enable_set(o, EINA_TRUE);
    -evas_map_free(m);
    -
    - -

    Zoom

    - -

    The evas_map_util_zoom() function zooms the points of the map from a center point, defined by cx and cy. The zoomx and zoomy arguments specify how much to zoom in on the X and Y axes. A value of 1.0 means no zoom, 2.0 means double the size, 0.5 means half the size, and so on. All the coordinates are global canvas coordinates.

    - -
    -evas_map_util_zoom(Evas_Map *m, double zoomx, double zoomy, Evas_Coord cx, Evas_Coord cy)
    -
    - -

    3D Maps

    - -

    Maps can also be used to achieve a 3D effect. In a 3D effect, the Z coordinate of each point is meaningful: the higher the value, the further back the point is located. Smaller values (usually negative) mean that the point is closer to the user.

    - -

    3D also introduces the concept of the back face of an object. An object is said to be facing the user when all its points are placed in a clockwise formation, as shown in the left map in the following figure. Rotating the map around its Y axis swaps the order of the points into a counter-clockwise formation, making the object face away from the user, as shown in the right map in the following figure. The back face is especially relevant in lighting (see below).

    - -

    Figure: Rotating around the Y axis

    -

    Rotating around the Y axis

    - -

    To determine whether a map is facing the user, use the evas_map_util_clockwise_get() function. This function returns EINA_TRUE if the map is facing the user and EINA_FALSE if the map is facing away from the user. This is normally done after all the other operations are applied to the map.

    - -
    evas_map_util_clockwise_get(Evas_Map *m)
    - -

    3D Rotation and Perspective

    - -

    The evas_map_util_3d_rotate() function transforms a map to apply a 3D rotation to the mapped object. You can apply the rotation around any point in the canvas (including a Z coordinate). You can also apply the rotation around any of the three axes.

    - -
    evas_map_util_3d_rotate(Evas_Map *m, double dx, double dy, double dz, Evas_Coord cx, Evas_Coord cy, Evas_Coord cz)
    - -

    Starting from this simple setup, and setting the maps so that the blue square rotates around the Y axis, we get the following:

    - -

    Figure: 3D rotation

    -

    3D rotation

    - -

    A simple overlay over the image shows the original geometry of each object and the axis around which they are being rotated. The Z axis is not shown, since it is orthogonal to the screen. To show the Z axis, that is, to add 3D perspective to the transformation, use the evas_map_util_3d_perspective() function on the map after its position has been set:

    - -
    evas_map_util_3d_perspective(Evas_Map *m, Evas_Coord px, Evas_Coord py, Evas_Coord z0, Evas_Coord foc)
    - -

    The result makes the vanishing point the center of each object:

    - -

    Figure: Adding perspective

    -

    Adding perspective

    - -

    Color and Lighting

    - -

    Each point in a map can be set to a color, which will be multiplied with the object’s own color and linearly interpolated between adjacent points. To set the color separately for each point, use the evas_map_point_color_set() function:

    - -
    evas_map_point_color_set(Evas_Map *m, int idx, int r, int g, int b, int a)
    - -

    To set the same color for every point, use the evas_map_util_points_color_set() function:

    - -
    evas_map_util_points_color_set(Evas_Map *m, int r, int g, int b, int a)
    - -

    When using a 3D effect, colors can be used to improve its look by simulating a light source. The evas_map_util_3d_lighting() function makes this task easier by taking the coordinates of the light source and its color, along with the color of the ambient light. Evas then sets the color of each point based on its distance to the light source, the angle at which the object is facing the light source, and the ambient light. Here, the orientation of each point is important.

    - -
    evas_map_util_3d_lighting(Evas_Map *m, Evas_Coord lx, Evas_Coord ly, Evas_Coord lz, int lr, int lg, int lb, int ar, int ag, int ab)
    - -

    If the map points are defined counter-clockwise, the object faces away from the user and is therefore obscured, since no light is reflecting back from it.

    - -

    Figure: Obscured object

    -

    Obscured object

    - -

    Mapping

    - -

    Images need special handling when mapped. While Evas can easily handle objects, it is completely oblivious to the contents of images. This means that each point in a map needs to be mapped to a specific pixel in the source image. Failing to do this can result in unexpected behavior.

    - -

    Let's get started with the following three images, each sized at 200 × 200 pixels:

    - -

    Figure: Starting point

    -

    Starting point

    - -

    The following three images illustrate the case where a map is set to an image object without setting the right UV mapping for each map point. The objects themselves are mapped properly to their new geometries, but the images are not displayed correctly within the mapped objects.

    - -

    Figure: Questionable result

    -

    Questionable result

    - -

    To transform an image correctly, Evas needs to know how to handle the image within the map. You can do this using the evas_map_point_image_uv_set() function, which allows you to map a given point in a map to a given pixel in a source image:

    - -
    -evas_map_point_image_uv_set(Evas_Map *m, int idx, double u, double v)
    -
    - -

    To match our example images to the maps above, all we need is the size of each image, which we can get using the evas_object_image_size_get() function.

    - -
    -// Tux 1: Some cropping and stretch up
    -evas_map_point_image_uv_set(m, 0, 0, 20);
    -evas_map_point_image_uv_set(m, 1, 200, 20);
    -evas_map_point_image_uv_set(m, 2, 200, 180);
    -evas_map_point_image_uv_set(m, 3, 0, 180);
    -evas_object_map_set(tux1, m);
    -evas_object_map_enable_set(tux1, EINA_TRUE);
    -
    -// Inverted texture for shadow:
    -evas_map_point_image_uv_set(m, 0, 0, 180);
    -evas_map_point_image_uv_set(m, 1, 200, 180);
    -evas_map_point_image_uv_set(m, 2, 200, 20);
    -evas_map_point_image_uv_set(m, 3, 0, 20);
    -evas_object_map_set(tux1_shadow, m);
    -evas_object_map_enable_set(tux1_shadow, EINA_TRUE);
    -
    -// Tux 2: Make it fit to the map:
    -evas_map_point_image_uv_set(m, 0, 0, 0);
    -evas_map_point_image_uv_set(m, 1, 200, 0);
    -evas_map_point_image_uv_set(m, 2, 200, 200);
    -evas_map_point_image_uv_set(m, 3, 0, 200);
    -evas_object_map_set(tux2, m);
    -evas_object_map_enable_set(tux2, EINA_TRUE);
    -
    -// Tux 3: Zoom and fit relatively to image size
    -evas_object_image_size_get(evas_object_image_source_get(tux3), &w, &h);
    -evas_map_point_image_uv_set(m, 0, 0.1 * w, 0.1 * h);
    -evas_map_point_image_uv_set(m, 1, 0.9 * w, 0.1 * h);
    -evas_map_point_image_uv_set(m, 2, 0.9 * w, 0.9 * h);
    -evas_map_point_image_uv_set(m, 3, 0.1 * w, 0.9 * h);
    -evas_object_map_set(tux3, m);
    -evas_object_map_enable_set(tux3, EINA_TRUE);
    -
    - -

    Figure: Correct result

    -

    Correct result

    - -

    You can also set a map to use only part of an image, or you can even map the points in inverted order. Combined with the evas_object_image_source_set() function, you can achieve more interesting results still.

    - -

    Lighting

    - -

    Evas_Map allows you to define an ambient light and a light source within the scene. Both of these light sources have their own colors.

    - -
    evas_map_util_3d_lighting(Evas_Map *m, Evas_Coord lx, Evas_Coord ly, Evas_Coord lz, int lr, int lg, int lb, int ar, int ag, int ab)
    - -

    The above function is used to apply lighting calculations (from a single light source) to a given map. The red, green, and blue values of each vertex will be modified to reflect the lighting based on the light source coordinates, its color, the ambient color, and the angle at which the map faces the light source. The points of a surface should be defined in a clockwise formation if the surface is facing the user, since faces have a logical side for lighting.

    - -

    To get the reflections (gradient) in the shadow of our previous example, you have to define a source of light close enough to the user and a very bright ambient light, for example:

    - -
    -evas_map_util_3d_lighting(m, // Evas_Map object
    -                          250/2, 150/2, -100, // Spot light coordinates
    -                          255, 255, 255, // Spot light color
    -                          200, 200, 200); // Ambient light color
    -
    - -

    Alpha Channel

    - -

    You can also use an alpha channel on your map by enabling the alpha channel feature:

    - -
    evas_map_alpha_set(Evas_Map *m, Eina_Bool enabled)
    - -

    Next, set the alpha value separately for each map point:

    - -
    evas_map_point_color_set(Evas_Map *m, int idx, int r, int g, int b, int a)
    - -

    Alternatively, you can set the same alpha value to all map points:

    - -
    evas_map_util_points_color_set(Evas_Map *m, int r, int g, int b, int a)
    - -

    The following code sets the shadow transparency for the first image in the above three-image example:

    - -
    -// Set object transparency to 50%:
    -evas_map_util_points_color_set(m, 255, 255, 255, 127);
    -
    -// Tux's head is almost invisible in the shadow:
    -evas_map_point_color_set(m, 3, 255, 255, 255, 15);
    -evas_map_point_color_set(m, 4, 255, 255, 255, 15);
    -
    - -

    Smoothing

    - -

    To enable smoothing when rendering a map, use the evas_map_smooth_set() function:

    - -
    evas_map_smooth_set(Evas_Map *m, Eina_Bool enabled)
    - -

    The first argument is the Evas_Map object to apply smoothing to. The second argument sets whether to enable the smoothing:

    - -
      -
    • EINA_TRUE: Enable smoothing.
    • -
    • EINA_FALSE: Disable smoothing.
    • -
    - -

    If the object is of a type that has its own smoothing settings, the smoothing settings must be disabled for both the object and the map. Map smoothing is enabled by default. To check whether map smoothing is enabled, use the evas_map_smooth_get() function.

    - - - - -
    - -Go to top - - - - - - - \ No newline at end of file diff --git a/org.tizen.guides/html/native/ui/circle_components_wn.htm b/org.tizen.guides/html/native/ui/circle_components_wn.htm deleted file mode 100644 index 6faac79..0000000 --- a/org.tizen.guides/html/native/ui/circle_components_wn.htm +++ /dev/null @@ -1,688 +0,0 @@ - - - - - - - - - - - - - Circle Components - - - - - -
    -

    Circle Components

    - -

    Circle components extend the UI features and provide functionalities optimized for the circular UI.

    - - - - - - - - - - -
    Note
    This feature is supported in wearable applications only.
    - -

    Generally, circle components can be added with the eext_circle_object_[component_name]_add() function, which returns a circle object handle. Circle components are shown in a form of an arch with radius, line width, and color. These properties can be set with the eext_circle_object_item* APIs. The circle object can also take a rotary event. Generally, a clockwise rotary event increases the value of the rotary event activated by the circle object, and a counter clockwise rotary event decreases the value.

    - -

    Circle Datetime

    - - -

    Figure: Circle Datetime

    -

    Circle Datetime

    - -

    The circle datetime extends elm_datetime by visualizing the selected field. If a rotary event is activated by eext_rotary_object_event_activated_set(), a circle datetime increases or decreases value of selected field in elm_datetime by the clockwise or counter clockwise rotary event.

    - -

    Creating a Circle Datetime

    - -

    You can use the eext_circle_object_datetime_add() function to create a circle object. When creating a circle datetime, the elm_datetime handle must be passed as an argument. If a circle surface is passed as an argument, a circle object connected with a circle surface is created, and it is rendered by the circle surface. When NULL is passed as a surface argument, the new circle object is managed and rendered by itself.

    -
    -Evas_Object *datetime;
    -Evas_Object *circle_datetime;
    -
    -datetime = elm_datetime_add(parent);
    -circle_datetime = eext_circle_object_datetime_add(datetime, surface);
    -
    - -

    Activating a Rotary Event

    - -

    You can activate and deactivate the circle datetime by using the eext_rotary_object_event_activated_set() function. If the second parameter is EINA_TRUE, the circle datetime can receive the rotary event. Otherwise, the circle datetime cannot receive the rotary event.

    -
    -eext_rotary_object_event_activated_set(circle_datetime, EINA_TRUE);
    -
    - -

    Using the Circle Object Property

    - -

    A circle datetime has the following styles:

    -
      -
    • default
    • -
    -

    When created, the circle datetime has default style automatically.

    - -

    The circle datetime objects support the following circle object API calls:

    -
      -
    • eext_circle_object_line_width_set()
    • -
    • eext_circle_object_line_width_get()
    • -
    • eext_circle_object_radius_set()
    • -
    • eext_circle_object_radius_get()
    • -
    • eext_circle_object_color_set()
    • -
    • eext_circle_object_color_get()
    • -
    • eext_circle_object_disabled_set()
    • -
    • eext_circle_object_disabled_get()
    • -
    -

    A circle datetime has the following item:

    -
      -
    • default: Default circle item that draws a marker.
    • -
    - -

    You can change the properties of the items by using the eext_circle_object_item* APIs.

    -

    For more information, see the Efl Extension Circle Datetime API.

    - -

    Circle Genlist

    - -

    Figure: Circle Genlist

    -

    Circle Genlist

    - -

    Use the circle genlist to visualize and utilize the scroll effect for elm_genlist. While elm_genlist provides a scrollbar with straight horizontal and vertical movement, the circle genlist provides scrollbar with circular movement. It is also operated with rotary events to move to the next or previous item.

    - -

    Creating a Circle Genlist

    - -

    A genlist and a surface are necessary when creating the circle genlist. The circle genlist is added with the eext_circle_object_genlist_add() function.

    -
    -Evas_Object *genlist, *circle_genlist, *parent;
    -
    -genlist = elm_genlist_add(parent);
    -circle_genlist = eext_circle_object_genlist_add(genlist, surface);
    -
    - -

    Configuring the Circle Genlist

    - -

    You can set the circle genlist scroller policy by using the eext_circle_object_genlist_scroller_policy_set() function.

    -
    -eext_circle_object_genlist_scroller_policy_set(circle_genlist, 
    -                                               ELM_SCROLLER_POLICY_OFF, 
    -                                               ELM_SCROLLER_POLICY_ON);
    -
    -

    This sets the scrollbar visibility policy of a given scroller. ELM_SCROLLER_POLICY_AUTO indicates the scrollbar is made visible if it is needed, and otherwise is kept hidden. ELM_SCROLLER_POLICY_ON turns the scrollbar on all the time, and ELM_SCROLLER_POLICY_OFF turns it off. This applies to the horizontal and vertical scrollbars respectively.

    -

    The following enum values are available for circle genlist.

    -
      -
    • ELM_SCROLLER_POLICY_AUTO
    • -
    • ELM_SCROLLER_POLICY_ON
    • -
    • ELM_SCROLLER_POLICY_OFF
    • -
    - -

    Activating a Rotary Event

    - -

    You can activate and deactivate the circle genlist by using the eext_rotary_object_event_activated_set() function. If the second parameter is EINA_TRUE, the circle genlist can receive the rotary event. Otherwise, the circle genlist cannot receive the rotary event.

    -
    -eext_rotary_object_event_activated_set(circle_genlist, EINA_TRUE);
    -
    - -

    Using the Circle Object Property

    - -

    Circle genlist objects support the following circle object API calls:

    -
      -
    • eext_circle_object_line_width_set()
    • -
    • eext_circle_object_line_width_get()
    • -
    • eext_circle_object_radius_set()
    • -
    • eext_circle_object_radius_get()
    • -
    • eext_circle_object_color_set()
    • -
    • eext_circle_object_color_get()
    • -
    • eext_circle_object_disabled_set()
    • -
    • eext_circle_object_disabled_get()
    • -
    -

    A circle genlist has the following item:

    -
      -
    • default: Default circle item. It draws vertical scroll bar.
    • -
    • vertical,scroll,bg: Vertical scroll background circle item.
    • -
    -

    You can change the properties of the items by using the eext_circle_object_item* APIs.

    -

    For more information, see the Efl Extension Circle Genlist API.

    - - - -

    Circle Object

    - -

    A circle object extends elementary components in a form of circular design. Sometimes, a circle object merely provides additional UI features to elementary component, and sometimes it works as an independent component with UI and functionalities.

    - -

    Creating a Circle Object

    - -

    You can use the eext_circle_object_add() function to create a circle object. When creating a circle object, you can choose whether the circle object is rendered by itself or by the circle surface. If the circle surface is passed as an argument, a circle object connected with circle surface is created, and it is rendered by the circle surface.

    -
    -Evas_Object *circle_obj;
    -
    -circle_obj = eext_circle_object_add(parent, surface);
    -
    - -

    When NULL is passed as a surface argument, the new circle object is managed and rendered by itself. Here, a circle object without a circle surface is created and showed in a size of 360 x 360.

    -
    -Evas_Object *circle_obj;
    -
    -circle_obj = eext_circle_object_add(parent, NULL);
    -evas_object_size_hint_min_set(circle_obj, 360, 360);
    -evas_object_show(circle_obj);
    -
    - -

    Setting the Line Width

    - -

    You can set the line width of the circle object by using the eext_circle_object_line_width_set() function. Here, circle object with a surface is created and its line width set to 20. You can get the current line width of a circle object by using the eext_circle_object_line_width_get() function.

    -
    -Evas_Object *circle_obj;
    -
    -circle_obj = eext_circle_object_add(parent, surface);
    -eext_circle_object_line_width_set(circle_obj, 20);
    -
    - -

    You can set the line width of a certain item in a circle object by using the eext_circle_object_item_line_width_set() function. If the name of the item is passed as default, it works the same way as the eext_circle_object_line_width_set() function. Similar to the above example, a circle object with a surface is created and its line width is set to 20. You can get the current line width of the item by using the eext_circle_object_item_line_width_get() function.

    -
    Evas_Object *circle_obj;
    -
    -circle_obj = eext_circle_object_add(parent, surface);
    -eext_circle_object_item_line_width_set(circle_obj, "default", 20);
    -
    - -

    Setting the Angle

    - -

    You can set the angle of the circle object by using the eext_circle_object_angle_set() function. Here, circle object with surface is created and its angle set to a 45.0 degree angle. You can get the current angle of a circle object by using the eext_circle_object_angle_get() function.

    -
    -Evas_Object *circle_obj;
    -
    -circle_obj = eext_circle_object_add(parent, surface);
    -eext_circle_object_angle_set(circle_obj, 45.0);
    -
    - -

    You can set the angle of a certain item in a circle object by using the eext_circle_object_item_angle_set() function. If name of the item is passed as default, it works the same way as eext_circle_object_angle_set() function. Similar to the above example, a circle object with surface is created and its angle is set to a 45.0 degree angle. You can get the current angle of the item by using the eext_circle_object_item_angle_get() function.

    -
    -Evas_Object *circle_obj;
    -
    -circle_obj = eext_circle_object_add(parent, surface);
    -eext_circle_object_item_angle_set(circle_obj, "default", 45.0);
    -
    - -

    Setting the Angle Offset

    - -

    You can set the angle offset of the circle object by using the eext_circle_object_angle_offset_set() function. Here, a circle object with a 45.0 degree angle is created and its angle offset set to 30.0 degrees. As a result, the circle object has an arch of 45.0 degree angle line starting from 30.0 degrees to 75.0 degrees. You can get the current angle offset of a circle object by using the eext_circle_object_angle_offset_get() function.

    -
    -Evas_Object *circle_obj;
    -
    -circle_obj = eext_circle_object_add(parent, surface);
    -eext_circle_object_angle_set(circle_obj, 45.0);
    -eext_circle_object_angle_offset_set(circle_obj, 30.0);
    -
    - -

    You can set the angle offset of a certain item in a circle object by using the eext_circle_object_item_angle_offset_set() function. If name of the item is passed as default, it works the same way as eext_circle_object_angle_offset_set() function. The following code works the same way as in the above example. You can get the current angle of the item by using the eext_circle_object_item_angle_offset_get() function.

    -
    -Evas_Object *circle_obj;
    -
    -circle_obj = eext_circle_object_add(parent, surface);
    -eext_circle_object_item_angle_set(circle_obj, "default", 45.0); 
    -eext_circle_object_item_angle_offset_set(circle_obj, "default", 30.0);
    -
    - -

    Setting the Minimum and Maximum Angle

    - -

    You can set the minimum and maximum angle of the circle object by using the eext_circle_object_angle_min_max_set() function. Here, a circle object with a surface is created and its minimum angle set to 0.0 degrees and maximum angle to 90.0 degrees. You can get the current minimum and maximum angle of the circle object by using the eext_circle_object_angle_min_max_get() function.

    -
    -Evas_Object *circle_obj;
    -
    -circle_obj = eext_circle_object_add(parent, surface);
    -eext_circle_object_angle_min_max_set(circle_obj, 0.0, 90.0);
    -
    - -

    You can set the minimum and maximum angles of a certain item in a circle object by using the eext_circle_object_item_angle_min_max_set() function. If name of the item is passed as default, it works the same way as the eext_circle_object_angle_min_max_set() function. Similar to the above example, a circle object with a minimum and maximum angles of 0.0 and 90.0 is created. You can get the current minimum and maximum angle of the item by using the eext_circle_object_item_angle_min_max_get() function.

    -
    -Evas_Object *circle_obj;
    -
    -circle_obj = eext_circle_object_add(parent, surface);
    -eext_circle_object_item_angle_min_max_set(circle_obj, "default", 0.0, 90.0);
    -
    - -

    Setting the Minimum and Maximum Value

    - -

    You can set the minimum and maximum values of the circle object by using the eext_circle_object_value_min_max_set() function. Here, a circle object with a surface is created and its minimum value is set to 0.0 degrees and maximum value to 10.0 degrees. You can get the current minimum and maximum value of the circle object by using the eext_circle_object_value_min_max_get() function.

    -
    -Evas_Object *circle_obj;
    -
    -circle_obj = eext_circle_object_add(parent, surface);
    -eext_circle_object_value_min_max_set(circle_obj, 0.0, 10.0);
    -
    - -

    You can set the value of a certain item in a circle object by using the eext_circle_object_item_angle_min_max_set() function. If name of the item is passed as default, it works the same way as the eext_circle_object_value_min_max_set() function. Similar to the above example, a circle object with a minimum and maximum value of 0.0 to 10.0 degrees is created. You can get the current minimum and maximum values of the item by using the eext_circle_object_item_value_min_max_get() function.

    -
     
    -Evas_Object *circle_obj;
    -
    -circle_obj = eext_circle_object_add(parent, surface);
    -eext_circle_object_item_value_min_max_set(circle_obj, "default", 0.0, 10.0);
    -
    - -

    Setting the Value

    - -

    You can set the value of the circle object by using the eext_circle_object_value_set() function. Here, a circle object with a surface is created and its value set to 5.0. You can get the current value of the circle object by using the eext_circle_object_value_get() function.

    -
    -Evas_Object *circle_obj;
    -
    -circle_obj = eext_circle_object_add(parent, surface);
    -eext_circle_object_value_set(circle_obj, 5.0);
    -
    - -

    You can set the value of a certain item in a circle object by using the eext_circle_object_item_value_set() function. If name of the item is passed as default, it works the same as the eext_circle_object_value_set() function. Similar to the above example, a circle object with a surface is created and its value is set to 5.0 degree angle. You can get the current value of the item by using the eext_circle_object_item_value_get() function.

    -
    -Evas_Object *circle_obj;
    -
    -circle_obj = eext_circle_object_add(parent, surface);
    -eext_circle_object_item_value_set(circle_obj, "default", 5.0);
    -
    - - - - - - - - - - -
    Note
    The value cannot be lower than the minimum value or higher than the maximum value.
    - -

    Setting the Color

    - -

    You can set the color of the circle object by using the eext_circle_object_color_set() function. To set the color, red, green, blue, and alpha values in range from 0 to 255 must be passed. Here, a circle object with a surface is created and its color set to blue. You can get the current color of circle object by using the eext_circle_object_color_get() function.

    -
    -Evas_Object *circle_obj;
    -
    -circle_obj = eext_circle_object_add(parent, surface);
    -eext_circle_object_color_set(circle_obj, 255, 0, 0, 255);
    -
    - -

    You can set the color of a certain item in a circle object by using the eext_circle_object_item_color_set() function. If name of the item is passed as default, it works the same way as the eext_circle_object_color_set() function. Similar to the above example, a circle object with a surface is created and its color is set to red. You can get the current color of the item by using the eext_circle_object_item_color_get() function.

    -
    -Evas_Object *circle_obj;
    -
    -circle_obj = eext_circle_object_add(parent, surface);
    -eext_circle_object_item_value_set(circle_obj, "default", 255, 0, 0, 255);
    -
    - -

    Setting the Radius

    - -

    You can set the radius of the circle object by using the eext_circle_object_radius_set() function. Here, a circle object with radius of 50.0 is created. You can get the current radius of the circle object by using the eext_circle_object_radius_get() function.

    -
    -Evas_Object *circle_obj;
    -
    -circle_obj = eext_circle_object_add(parent, surface);
    -eext_circle_object_radius_set(circle_obj, 50.0);
    -
    - -

    You can set the radius of a certain item in a circle object by using the eext_circle_object_item_radius_set() function. If name of the item is passed as default, it works the same way as the eext_circle_object_radius_set() function. Similar to the above example, a circle object with a radius of 50.0 is created. You can get the current radius of the item by using the eext_circle_object_item_radius_get() function.

    -
    -Evas_Object *circle_obj;
    -
    -circle_obj = eext_circle_object_add(parent, surface);
    -eext_circle_object_item_radius_set(circle_obj, "default", 50.0);
    -
    - -

    Disabling a Circle Object

    - -

    You can disable the circle object by using the eext_circle_object_disabled_set() function. Here, a circle object is disabled. You can get the current disabled status of circle object by using the eext_circle_object_disabled_get() function.

    -
    -Evas_Object *circle_obj;
    -
    -circle_obj = eext_circle_object_add(parent, surface);
    -eext_circle_object_disabled_set(circle_obj, EINA_TRUE);
    -
    - -

    You can enable a disabled circle object by using the eext_circle_object_disabled_set() function with EINA_FALSE argument.

    -
    -eext_circle_object_disabled_set(circle_obj, EINA_FALSE);
    -
    - - - - -

    Circle Progressbar

    - -

    Figure: Circle Progressbar

    -

    Circle Progressbar

    - -

    The circle progressbar aims to show the progress status of a given task with circular design. It visualizes the progress status within a range.

    - -

    Creating a Circle Progressbar

    - -

    You can create the circle progressbar by using the eext_circle_object_progressbar_add() function. When creating the circle progressbar, a surface is necessary to render on the surface.

    -
    -Evas_Object *circle_progressbar, *parent;
    -circle_progressbar = eext_circle_object_progressbar_add(parent, surface);
    -
    - -

    Using the Circle Object Property

    -

    Circle progressbar supports the following circle object API calls:

    -
      -
    • eext_circle_object_value_min_max_set()
    • -
    • eext_circle_object_value_min_max_get()
    • -
    • eext_circle_object_value_set()
    • -
    • eext_circle_object_value_get()
    • -
    • eext_circle_object_angle_min_max_set()
    • -
    • eext_circle_object_angle_min_max_get()
    • -
    • eext_circle_object_angle_offset_set()
    • -
    • eext_circle_object_angle_offset_get()
    • -
    • eext_circle_object_angle_set()
    • -
    • eext_circle_object_angle_get()
    • -
    • eext_circle_object_line_width_set()
    • -
    • eext_circle_object_line_width_get()
    • -
    • eext_circle_object_radius_set()
    • -
    • eext_circle_object_radius_get()
    • -
    • eext_circle_object_color_set()
    • -
    • eext_circle_object_color_get()
    • -
    • eext_circle_object_disabled_set()
    • -
    • eext_circle_object_disabled_get()
    • -
    -

    A circle progressbar has the following items:

    -
      -
    • default: Default circle item that draws the progressbar.
    • -
    • bg: Progress bar background circle item.
    • -
    -

    You can change the properties of the items by using the eext_circle_object_item* APIs.

    -

    For more information, see the Efl Extension Circle Progressbar API.

    - -

    Configuring Circle Progressbar

    - -

    Before using the circle progressbar, its minimum and maximum values are set with the eext_circle_object_value_min_max_set() function. The current value is set with eext_circle_object_value_set().

    -

    Here, the minimum value is set to 0.0, the maximum value to 100.0, and the current value to 3.0.

    -
    -eext_circle_object_value_min_max_set(circle_progressbar, 0.0, 100.0);
    -eext_circle_object_value_set(circle_progressbar, 3.0);
    -
    - -

    Circle Scroller

    - -

    Figure: Circle Scroller

    -

    Circle Scroller

    - -

    The circle scroller changes corresponding to the rotary events. It shows the whole scrollable area with a circular scroll bar. It wraps the elm_scroller internally only to draw a circular scroll bar to the edge of the circular screen. This means you can use elm_scroller callbacks and APIs excluding elm_scroller_policy_set() and elm_scroller_policy_get() APIs.

    - -

    Creating a Circle Scroller

    - -

    To create a circle scroller, use the eext_circle_object_scroller_add() function. elm_scroller has to be passed by the first parameter of this function.

    -
    -Evas_Object *scroller;
    -Evas_Object *circle_scroller;
    -
    -scroller = elm_scroller_add(parent);
    -circle_scroller = eext_circle_object_scroller_add(scroller, surface);
    -
    - -

    Activating the Rotary Event

    - -

    You can activate and deactivate the circle scroller by using the eext_rotary_object_event_activated_set() function. If the second parameter is EINA_TRUE, the circle scroller can receive the rotary event. Otherwise, the circle scroller cannot receive the rotary event.

    -
    -eext_rotary_object_event_activated_set(circle_scroller, EINA_TRUE);
    -
    - -

    Using the Circle Object Property

    - -

    A circle scroller has the following styles:

    -
      -
    • default
    • -
    -

    When created, the circle scroller has default style automatically.

    - -

    Circle scroller objects support the following circle object API calls:

    -
      -
    • eext_circle_object_line_width_set()
    • -
    • eext_circle_object_line_width_get()
    • -
    • eext_circle_object_radius_set()
    • -
    • eext_circle_object_radius_get()
    • -
    • eext_circle_object_color_set()
    • -
    • eext_circle_object_color_get()
    • -
    • eext_circle_object_disabled_set()
    • -
    • eext_circle_object_disabled_get()
    • -
    -

    A circle slider has the following items:

    -
      -
    • default: Default circle item that draws the vertical scroll bar.
    • -
    • vertical,scroll,bg: Vertical scroll background circle item.
    • -
    • horizontal,scroll,bar: Horizontal scroll bar circle item.
    • -
    • horizontal,scroll,bg : Horizontal scroll background circle item.
    • -
    -

    You can change the properties of the items by using the eext_circle_object_item* APIs.

    -

    For more information, see the Efl Extension Circle Scroller API.

    - -

    Configuring the Circle Scroller

    - -

    You can use elm_scroller APIs to configure a circle scroller, except elm_scroller_policy_set() and elm_scroller_policy_get() APIs.

    -

    Instead of excluded APIs, eext_circle_object_scroller_policy_set() and eext_circle_object_scroller_policy_get() functions are provided for the circle scroller.

    -

    A policy parameter has the following value.

    -
      -
    • ELM_SCROLLER_POLICY_AUTO: indicates the scrollbar is made visible if it is needed, and otherwise is kept hidden.
    • -
    • ELM_SCROLLER_POLICY_ON: Turns the scrollbar on all the time.
    • -
    • ELM_SCROLLER_POLICY_OFF: Turns the scrollbar off. This applies to the horizontal and vertical scrollbars respectively.
    • -
    -

    The following example shows how to set the scroll bar visibility policy to ELM_SCROLLER_POLICY_AUTO for horizontal scroll bar and ELM_SCROLLER_POLICY_OFF for vertical scroll bar.

    -
    -eext_circle_object_scroller_policy_set(circle_scroller, ELM_SCROLLER_POLICY_AUTO, ELM_SCROLLER_POLICY_OFF);
    -
    - -

    Circle Slider

    - -

    Figure: Circle Slider

    -

    Circle Slider

    - -

    The circle slider changes corresponding to rotary events. The circle slider not only extends the UI feature of the elm_slider, but also replaces the functionalities of the elm_slider in a circular design.

    - -

    Adding an Eext Slider object

    - -

    To create a circle slider, use the eext_circle_object_slider_add() function.

    -
    -Evas_Object *circle_slider = NULL;
    -circle_slider = eext_circle_object_slider_add(parent, surface);
    -
    - -

    Activating the Rotary Event

    - -

    You can activate or deactivate the circle slider by using the eext_rotary_object_event_activated_set() function. If the second parameter is EINA_TRUE, the circle slider can receive the rotary event. Otherwise, the circle slider cannot receive the rotary event.

    -
    -eext_rotary_object_event_activated_set(circle_slider, EINA_TRUE);
    -
    - -

    Using the Circle Slider Property

    - -

    A circle slider has the following styles:

    -
      -
    • default
    • -
    - -

    When created, the circle slider has default style automatically.

    -

    Circle slider objects support the following circle object API calls:

    -
      -
    • eext_circle_object_value_min_max_set()
    • -
    • eext_circle_object_value_min_max_get()
    • -
    • eext_circle_object_value_set()
    • -
    • eext_circle_object_value_get()
    • -
    • eext_circle_object_angle_min_max_set()
    • -
    • eext_circle_object_angle_min_max_get()
    • -
    • eext_circle_object_angle_offset_set()
    • -
    • eext_circle_object_angle_offset_get()
    • -
    • eext_circle_object_angle_set()
    • -
    • eext_circle_object_angle_get()
    • -
    • eext_circle_object_line_width_set()
    • -
    • eext_circle_object_line_width_get()
    • -
    • eext_circle_object_radius_set()
    • -
    • eext_circle_object_radius_get()
    • -
    • eext_circle_object_color_set()
    • -
    • eext_circle_object_color_get()
    • -
    • eext_circle_object_disabled_set()
    • -
    • eext_circle_object_disabled_get()
    • -
    -

    A circle slider has the following items:

    -
      -
    • default: Default circle item, It draws slider bar.
    • -
    • bg: Background circle item.
    • -
    -

    You can change the properties of the items by using eext_circle_object_item* APIs.

    -

    For more information, see the Efl Extension Circle Slider API.

    - -

    Configuring the Circle Slider

    - -

    The circle slider step value is used when the rotary event increases or decreases the circle slider value. It can be set with the eext_circle_object_slider_step_set() function.

    -

    Here, the step value is set to 0.5.

    -
    -eext_circle_object_slider_step_set(circle_slider, 0.5);
    -
    -

    Before using the circle slider, its minimum and maximum values are set with eext_circle_object_value_min_max_set(). The current value is set with eext_circle_object_value_set().

    -

    Here, the minimum value is set to 0.0, the maximum value to 15.0, and the current value to 3.0.

    -
    -eext_circle_object_value_min_max_set(circle_slider, 0.0, 15.0);
    -eext_circle_object_value_set(circle_slider, 3.0);
    -
    -

    You can retrieve the current value of the circle slider with the eext_circle_object_value_get() function.

    -
    -double value = eext_circle_object_value_get(circle_slider);
    -
    - -

    Using Circle Slider Callbacks

    - -

    The circle slider emits the following signal:

    -
      -
    • value,changed: The rotary event changes the circle slider value.
    • -
    -

    For this signal, event_info is NULL.

    -

    This is how to register a callback on the value,changed signal.

    -
    -{
    -   evas_object_smart_callback_add(slider, "value,changed", _value_changed_cb, data);
    -}
    -
    -// Callback function for the "value,changed" signal
    -// This callback is called when a value of the circle slider is changed
    -static void
    -_value_changed_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   dlog_print(DLOG_INFO, LOG_TAG, "Circle slider value changed. \n");
    -}
    -
    - -

    Circle Surface

    - -

    The circle surface manages and renders circle objects. Multiple circle objects can be connected to one circle surface as candidates of an object to be rendered. When one of circle objects is set as visible, the surface renders the circle object and hides the others.

    - -

    Creating a Circle Surface

    - -

    To create a new circle surface:

    -
    -Eext_Circle_Surface *surface;
    -Evas_Object *conformant;
    -
    -conformant = elm_conformant_add(parent);
    -surface = eext_circle_surface_conformant_add(conformant);
    -
    - -

    The eext_circle_surface_conformant_add() function creates a circle surface in the conformant layer. If you want to create a circle surface in the layout layer, use the eext_circle_surface_layout_add() function:

    -
    -Eext_Circle_Surface *surface;
    -Evas_Object *layout;
    -
    -layout = elm_layout_add(parent);
    -surface = eext_circle_surface_layout_add(layout); 
    -
    - -

    If you want to create a circle surface in the naviframe layer, use the eext_circle_surface_naviframe_add() function:

    -
    -Eext_Circle_Surface *surface;
    -Evas_Object *naviframe;
    -
    -naviframe = elm_naviframe_add(parent);
    -surface = eext_circle_surface_naviframe_add(naviframe); 
    -
    - - - - - - - - - - -
    Note
    A circle surface is a non-graphical object. It adds no graphics to or around the objects it holds.
    - -

    Adding Circle Objects to the Circle Surface

    - -

    You can add any circle object to a circle surface. The following example shows how to create an eext_slider component and add it to a circle surface in conformant layer:

    -
    -Eext_Circle_Surface *surface;
    -Evas_Object *slider;
    -
    -surface = eext_circle_surface_conformant_add(conformant);
    -slider = eext_circle_object_slider_add(parent, surface);
    -
    - -

    Deleting Circle Surface

    - -

    Deleting an Evas object automatically deletes the circle surface in the same layer. However, you can explicitly use the eext_circle_surface_del() function to delete a circle surface.

    -
    -eext_circle_surface_del(surface);
    -
    - - - - - - - - - - -
    Note
    The eext_circle_surface_del() function does not delete the connected circle objects.
    - - - -
    - -Go to top - - - - - - - \ No newline at end of file diff --git a/org.tizen.guides/html/native/ui/components_mn.htm b/org.tizen.guides/html/native/ui/components_mn.htm deleted file mode 100644 index 33c438e..0000000 --- a/org.tizen.guides/html/native/ui/components_mn.htm +++ /dev/null @@ -1,3343 +0,0 @@ - - - - - - - - - - - - - - Components - - - - - - -
    -

    Components

    - - - - - - - - - - -
    Note
    This feature is supported in mobile applications only.
    - -

    Background

    - -

    Figure: Red color background

    -

    Red color background

    - -

    Figure: Background hierarchy

    -

    Background hierarchy

    - -

    The background component can be used to set a solid background decoration to a window or to a container object. It works like an image, but has some background specific properties, for example it can be set to a tiled, centered, scaled, or stretched mode. There are no specific signals relative to background object.

    - -

    Adding a Background Component

    - -

    A background is created with the elm_bg_add() function.

    - -
    -Evas_Object *bg, *parent;
    -
    -// Create a background
    -bg = elm_bg_add(parent);
    -
    - -

    Changing the Color of the Background

    - -

    You can set the color of the background with the elm_bg_color_set() function. The following example sets the background color to red.

    - -
    -Evas_Object *bg;
    -
    -// Use red color for background
    -elm_bg_color_set(bg, 0xFF, 0x00, 0x00);
    -
    - -

    Changing the Image of the Background

    - -

    It is also possible to set an image or an Edje group as a background using the elm_bg_file_set() function. The display mode of the image in the background can be chosen with elm_bg_option_set(), where the following modes are available:

    - -
      -
    • ELM_BG_OPTION_CENTER: center the background image.
    • -
    • ELM_BG_OPTION_SCALE: scale the background image, retaining aspect ratio.
    • -
    • ELM_BG_OPTION_STRETCH: stretch the background image to fill the UI component's area.
    • -
    • ELM_BG_OPTION_TILE: tile the background image at its original size.
    • -
    - -
    -Evas_Object *bg;
    -
    -// Set a file on the disk as a background image
    -elm_bg_file_set(bg, "/path/to/the/image", NULL);
    -// Set an Edje group as a background image
    -elm_bg_file_set(bg, "/path/to/the/edje", "edje_group");
    -elm_bg_option_set(bg, ELM_BG_OPTION_STRETCH)
    -
    - -

    Using Overlay

    - -

    An overlay can be set using the overlay part name.

    - -
    -elm_object_part_content_set(bg, "overlay", over);
    -
    - -

    Here, the overlay is an Edje object that is displayed on top of the current background object.

    - - -

    Button

    - -

    Figure: Button component

    -

    Button component

    - -

    Figure: Button hierarchy

    -

    Button hierarchy

    - -

    The Elementary button component is a simple push button. It is composed of a label icon and an icon object and has an autorepeat feature.

    - -

    Adding a Button Component

    - -

    Create a button.

    -
    -Evas_Object *button, *parent;
    -
    -// Create a button
    -button = elm_button_add(parent);
    - -

    Adding an Icon Inside a Button

    - -

    The icon can be updated with elm_object_part_content_set() function with the icon part name.

    - -
    -Evas_Object *ic;
    -ic = elm_icon_add(button);
    -elm_image_file_set(ic, "icon.png", NULL);
    -elm_object_part_content_set(button, "icon", ic);
    -
    - -

    Adding Text Inside a Button

    - -

    The label can be modified using the elm_object_text_set() function.

    - -
    -elm_object_text_set(button, "Click me!");
    -
    - -

    Using Button Styles

    - -

    Various styles can be used on the button. Tizen supports the following styles:

    - -
      -
    • icon_reorder
    • -
    • icon_expand_add
    • -
    • icon_expand_delete
    • -
    • default
    • -
    • circle
    • -
    • bottom
    • -
    • contacts
    • -
    • option
    • -
    - -

    You can see these themes in action on the following screenshot (in the above order).

    - -

    Figure: Button component

    -

    Button component

    - -

    To change the style of the button, call the elm_object_style_set() function on the button object.

    - -
    -elm_object_style_set(button,"icon_expand_add");
    -
    - -

    Using the Button Callbacks

    - -

    The button emits the following signals:

    - -
      -
    • clicked: The user clicked the button (press/release).
    • -
    • repeated: The user pressed the button without releasing it.
    • -
    • pressed: The user pressed the button.
    • -
    • unpressed: The user released the button after pressing it.
    • -
    - -

    For all these signals the event_info parameter returned in the callback is NULL.

    - -

    This is an example to register and define a callback function called by the clicked signal.

    - -
    -{
    -   evas_object_smart_callback_add(button, "clicked", clicked_cb, data);
    -}
    -// Callback function for the "clicked" signal
    -// This callback is called when the button is clicked by the user
    -void clicked_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   dlog_print(DLOG_INFO, LOG_TAG, "Button clicked\n");
    -}
    -
    - -

    Using the Autorepeat Feature

    - -

    The autorepeat feature is enabled by default. It consists of calling the repeated signal when the user keeps the button pressed. This feature can be disabled with the elm_button_autorepeat_set() function. The autorepeat is configured with the following functions:

    -
      -
    • elm_button_autorepeat_initial_timeout_set(): to set the initial timeout before the autorepeat event is generated
    • -
    • elm_button_autorepeat_gap_timeout_set(): to set the interval between two autorepeat events
    • -
    - -

    Disable the autorepeat feature.

    -
    -elm_button_autorepeat_set(button, EINA_FALSE);
    -
    - -

    Enable the autorepeat feature.

    -
    -elm_button_autorepeat_set(button, EINA_TRUE);
    -
    - -

    Set the initial timeout to five seconds.

    -
    -elm_button_autorepeat_initial_timeout_set(button, 5.0);
    -
    - -

    Set the gap between two signals to 0.5 seconds.

    -
    -elm_button_autorepeat_gap_timeout_set(button, 0.5);
    -
    - - -

    Check

    - -

    Figure: Check component

    -

    Check component

    - -

    Figure: Check hierarchy

    -

    Check hierarchy

    - -

    The check component is similar to the radio component, except that it does not work as a group. It toggles the value of a boolean between true and false.

    - -

    This UI component inherits from the layout component. All layout functions can be used on the check component.

    - -

    Adding a Check Component

    - -

    The following example shows how to create a check component.

    - -
    -Evas_Object *check, *parent;
    -check = elm_check_add(parent);
    -
    - -

    Modifying the Check Styles

    - -

    The check component style can be set with the elm_object_style_set() function. The following styles are available:

    -
      -
    • default
    • -
    • favorite
    • -
    • on and off
    • -
    - -

    The following example sets the favorite style on our check object.

    -
    -elm_object_style_set(check, "favorite");
    -
    - -

    To get the current style, use the elm_object_style_get() function.

    -
    -char *style = elm_object_style_get(check);
    -
    - -

    Using the Check Component

    - -

    After having created a check object, it is possible to set its boolean value to EINA_TRUE.

    -
    -elm_check_state_set(check, EINA_TRUE);
    -
    - -

    You can also retrieve the current value of the check object.

    -
    -Eina_Bool value = elm_check_state_get(check);
    -
    - -

    As with a radio object, an icon and a label can be set.

    -
    -// Create a Home icon 
    -Evas_Object *icon;
    -
    -icon = elm_icon_add(parent);
    -elm_icon_standard_set(icon, "home");
    -
    -// Set it to the check object 
    -elm_object_part_content_set(check, "icon", icon);
    -
    -// Set the check label 
    -elm_object_text_set(check, "Check label");
    -
    - -

    You can also modify the on and off labels.

    - -
    -elm_object_part_text_set(check, "on", "True");
    -elm_object_part_text_set(check, "off", "False");
    -
    - -

    The get functions of the elementary object API can be used to retrieve the content set to the check object.

    - -
    -// Get the current set text of the check label 
    -char *text = elm_object_text_get(check);
    -
    -// Get the content set in the icon part 
    -Evas_Object *icon = elm_object_part_content_get(check, "icon");
    -
    - -

    Using the Check Callbacks

    - -

    When the value is changed by the user, the changed signal is emitted. The event_info parameter is NULL.

    - -

    The following example shows how to register a callback on this signal.

    -
    -{
    -   evas_object_smart_callback_add(check, "changed", changed_cb, data);
    -}
    -
    -// Callback function for the "changed" signal
    -// This callback is called when the check value changes
    -void changed_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   dlog_print(DLOG_INFO, LOG_TAG, "The value has changed\n");
    -}
    -
    - -

    Colorselector

    - -

    Figure: Colorselector component

    -

    Colorselector component

    - -

    Figure: Colorselector hierarchy

    -

    Colorselector hierarchy

    - - -

    The colorselector component provides a color selection solution to the user. There are different modes available, each of them showing a different configuration of the colorselector component.

    - -

    Currently only the Palette mode is available in Tizen.

    -
      -
    • ELM_COLORSELECTOR_PALETTE
    • -
    - -

    The Palette mode displays several color items that enable the user to choose a color in the items displayed. It is possible to add new items, or to update the color of the current item. The list of color items is called a palette, and it is associated with a unique identifier. This enables the developers to create new series of colors (a new palette) and save it under another identifier. By default, the color palette is using the default identifier.

    - -

    This UI component inherits from the layout component, so all function concerning the layout component can also be used on the colorselector component.

    - -

    Adding a Colorselector Component

    - -

    The following example shows how to create a colorselector object.

    - -
    -Evas_Object *colorsel, *parent;
    -
    -colorsel = elm_colorselector_add(parent);
    -
    - -

    Setting the Colorselector Modes

    - -

    The following example shows how to set the mode of the colorselector to the palette mode.

    - -
    -elm_colorselector_mode_set(colorsel, ELM_COLORSELECTOR_PALETTE);
    -
    - -

    The following example shows how to create a new palette called mypalette. This new palette is saved by elementary config and you can to load it again later. You then add three colors in mypalette: red, green, and blue.

    - -
    -elm_colorselector_palette_name_set(colorsel, "mypalette");
    -elm_colorselector_palette_color_add(colorsel, 255, 0, 0, 255);
    -elm_colorselector_palette_color_add(colorsel, 0, 255, 0, 255);
    -elm_colorselector_palette_color_add(colorsel, 0, 0, 255, 255);
    -
    - -

    The default palette already contains 14 colors.

    - -
    -elm_colorselector_palette_name_set(colorsel, "default");
    -
    - -

    When the user clicks on the color elements, the element changes the color that is set to the colorselector component. You can use the following function to retrieve the current selected color.

    -
    -int r, g, b, a;
    -
    -elm_colorselector_color_get(colorsel, &r, &g, &b, &a);
    -
    - -

    Using the Colorselector Callbacks

    - -

    You can register callbacks on the following signals:

    - -
      -
    • changed - The color value changes on the selector. event_info is NULL.
    • -
    • color,item,selected - The user clicks on a color item. The event_info parameter of the callback is the selected color item.
    • -
    • color,item,longpressed - The user long presses on a color item. The event_info parameter of the callback contains the selected color item.
    • -
    - -

    The following example shows how to register a callback on the changed signal.

    -
    -{
    -      evas_object_smart_callback_add(colorselector, "changed", changed_cb, data);
    -}
    -
    -// Callback function for the "changed" signal
    -// This callback is called when the colorselector value changes
    -void changed_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -      dlog_print(DLOG_INFO, LOG_TAG, "The color has changed\n");
    -}
    -
    - - -

    Ctxpopup

    - -

    Figure: Context popup component

    -

    Context popup component

    - -

    Figure: Context popup hierarchy

    -

    Context popup hierarchy

    - - -

    Ctxpopup is a contextual popup that can show a list of items.

    - -

    Adding a Ctxpopup Component

    - -

    A ctxpopup can be created with the elm_ctxpopup_add() function, and when shown, it automatically chooses an area inside its parent object's view (set using elm_ctxpopup_hover_parent_set()) to optimally fit into it.

    - -
    -Evas_Object *ctxpopup, *parent;
    -
    -// Create a ctxpopup 
    -ctxpopup = elm_ctxpopup_add(parent);
    -
    - -

    Modifying the Ctxpopup Style

    - -

    The following styles are available:

    - -
      -
    • dropdown/list
    • -
    • dropdown/label
    • -
    • more/default
    • -
    - -

    Figure: Context popup more/default style

    -

    Context popup more/default style

    - -

    Figure: Context popup dropdown/list

    -

    Context popup dropdown/list

    - -

    Figure: Context popup dropdown/label

    -

    Context popup dropdown/label

    - -

    The following example shows how to set the more/default style.

    - -
    -elm_object_style_set(ctxpopup, "more/default");
    -
    - -

    Configuring the Ctxpopup

    - -

    The context popup orientation can be set with elm_ctxpopup_horizontal_set(). Here it is set to horizontal.

    -
    -elm_ctxpopup_horizontal_set(ctxpopup, EINA_TRUE);
    -
    - -

    Auto hide is enabled by default. You can also disable auto hiding if you want the ctxpopup never to be hidden.

    -
    -elm_ctxpopup_auto_hide_disabled_set(ctxpopup, EINA_TRUE);
    -
    - -

    Managing the Ctxpopup Items

    - -

    The ctxpopup can contain a small number of items. Each of them can have a label and an icon. The following example shows how to append an item with the Test label and no icon.

    -
    -Elm_Object_Item *it;
    -
    -it = elm_ctxpopup_item_append(ctxpopup, "test", NULL, _ctxpopup_item_cb,
    -                  NULL);
    -
    - -

    The _ctxpopup_item_cb() callback is called when the item is clicked. The following example shows how to write the definition of this callback.

    -
    -static void
    -_ctxpopup_item_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   dlog_print(DLOG_INFO, LOG_TAG, "ctxpopup item selected\n");
    -}
    -
    - -

    After that the item label is set to New label.

    - -
    elm_object_item_part_text_set(it, "default", "New label");
    -
    - -

    And its icon is modified to the standard home icon.

    - -
    -Evas_Object *home_icon = elm_icon_add(ctxpopup);
    -elm_icon_standard_set(home_icon, "home");
    -
    -elm_object_item_part_content_set(it, "icon", home_icon);
    -
    - -

    Using the Ctxpopup Callbacks

    - -

    The context popup emits the dismissed signal when it is dismissed. You can register a callback to this signal. The event_info parameter is NULL.

    - -
    -{
    -   evas_object_smart_callback_add(ctxpopup, "dismissed", dismissed_cb, data);
    -}
    -
    -// Callback function for the "dismissed" signal
    -// This callback is called when the ctxpopup is dismissed
    -void dismissed_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   dlog_print(DLOG_INFO, LOG_TAG, "Ctxpopup dismissed\n");
    -}
    -
    - -

    Datetime

    - -

    Figure: Datetime selection

    -

    Datetime selection

    - -

    Figure: Datetime hierarchy

    -

    Datetime hierarchy

    - -

    The datetime component displays and adds date and time values.

    - -

    Adding a Datetime Component

    - -

    The UI component is created with elm_datetime_add(). It is possible to select the visible fields with elm_datetime_field_visible_set(). The following fields can be controlled:

    -
      -
    • ELM_DATETIME_YEAR: the year field
    • -
    • ELM_DATETIME_MONTH: the month field
    • -
    • ELM_DATETIME_DATE: the date field
    • -
    • ELM_DATETIME_HOUR: the hour field
    • -
    • ELM_DATETIME_MINUTE: the minute field
    • -
    • ELM_DATETIME_AMPM: the AM/PM field
    • -
    - -

    The following example shows how to create a datetime component and set the HOUR and MINUTE fields visible.

    - -
    -Evas_Object *datetime, *parent;
    -
    -datetime = elm_datetime_add(parent);
    -
    -elm_datetime_field_visible_set(datetime, ELM_DATETIME_HOUR, EINA_TRUE);
    -elm_datetime_field_visible_set(datetime, ELM_DATETIME_MINUTE, EINA_TRUE);
    -
    -elm_datetime_field_visible_set(datetime, ELM_DATETIME_YEAR, EINA_FALSE);
    -elm_datetime_field_visible_set(datetime, ELM_DATETIME_MONTH, EINA_FALSE);
    -elm_datetime_field_visible_set(datetime, ELM_DATETIME_DATE, EINA_FALSE);
    -elm_datetime_field_visible_set(datetime, ELM_DATETIME_AMPM, EINA_FALSE);
    -
    - -

    Using the Datetime Styles

    - -

    The following styles are available:

    -
      -
    • date_layout
    • -
    • time_layout
    • -
    • time_layout_24h
    • -
    - -

    The following example creates the date_layout style:

    - -
    -elm_object_style_set(datetime, "date_layout");
    -
    - -

    Setting the Datetime Format

    - -

    The format of the date and time can be configured with elm_datetime_format_set() using a combination of allowed Libc date format specifiers. In the following example the format is set to HH : MM.

    - -
    -elm_datetime_format_set(datetime, "%H : %M");
    -
    - -

    Please refer to the API documentation for a complete list of all the options available.

    - -

    Using the Datetime Callbacks

    - -

    A callback can be registered on the changed signal to detect when the Datetime field values are changed. The event_info parameter is NULL.

    - -
    -{
    -   evas_object_smart_callback_add(datetime, "changed", changed_cb, data);
    -}
    -
    -// Callback function for the "changed" signal
    -// This callback is called when the datetime fields change
    -void changed_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   dlog_print(DLOG_INFO, LOG_TAG, "Datetime field changed. \n");
    -}
    - -

    The language,changed signal is emitted when the system locale changes.

    - - -

    UX Issue in Tizen 2.3

    - -
      -
    • date_layout (default): Year, Month, Day
    • -
    • time_layout: Hour, Minute, AM/PM button
    • -
    • time_layout_24hr: Hour, Minute
    • -
    - -

    Basically, the elm_datetime component needs a full-length format that includes the Year, Month, Day, Hour, Minute, and AM/PM. Each style then shows specific fields according their style, limited by the UX concept. If you call the elm_datetime_field_visible_set() function for a field that is not supported in the style, it does not work.

    - - -

    Entry

    - -

    Figure: Entry component

    -

    Entry component

    - -

    Figure: Entry component

    -

    Entry component

    - -

    Figure: Entry hierarchy

    -

    Entry hierarchy

    - -

    The entry component is a box where the user can enter text. It supports the following features:

    -
      -
    • text wrapping
    • -
    • multiline
    • -
    • scrolling
    • -
    • formatted markup text
    • -
    • password mode
    • -
    • filtering text
    • -
    • read/write from a file
    • -
    • theme style overrides
    • -
    - -

    Adding an Entry Component

    - -

    The entry component is created with the elm_entry_add() function, and the text inside the entry can be set with elm_entry_entry_set().

    - -
    -Evas_Object *entry, *parent;
    -
    -entry = elm_entry_add(parent);
    -elm_entry_entry_set(entry, "A short text.");
    -
    - -

    Using the Text Editor

    - -

    You can append text to the end of existing content.

    - -
    -elm_entry_entry_append(entry, "END");
    -
    - -

    You can also insert text at the current cursor position.

    - -
    -elm_entry_entry_insert(entry, "CURSOR");
    -Eina_Bool Empty = elm_entry_is_empty(entry);
    -
    - -

    Call elm_entry_is_empty() to see whether the entry is empty. Here, the boolean variable Empty returns EINA_FALSE.

    - -

    By default, the user can enter text in the entry component when it is in focus. It is possible to prevent the user from editing text if needed.

    - -
    -elm_entry_editable_set(entry, EINA_FALSE);
    -
    - - - - - - - - - - -
    Note
    It is still possible to use the previous functions to modify the text of a non-editable entry.
    - -

    Setting the Password Mode

    - -

    When dealing with password content, the password mode activates to hide what the user is typing. In this mode, the display of any text is replaced by asterisks (*), and the entry is single line (there is no line wrap).

    - -
    -elm_entry_password_set(entry, EINA_TRUE);
    -
    - -

    Entry Line Modes And Wrapping

    - -

    The entry component has two line modes:

    -
      -
    • single line mode
    • -
    • multiline mode
    • -
    - -

    First, set the entry in single line mode.

    - -
    -elm_entry_single_line_set(entry, EINA_TRUE);
    -
    - -

    In this mode, the text does not wrap when reaching the edge, but the entry grows horizontally instead. Pressing the Enter key in this mode generates an activate event instead of adding a new line.

    - -

    When the entry is set to multiline mode (single line off), the text wraps at the end of the entry and pressing Enter creates a new line.

    - -
    -elm_entry_single_line_set(entry, EINA_FALSE);
    -elm_entry_line_wrap_set(entry, ELM_WRAP_WORD);
    -
    - -

    In multiline entries, elm_entry_line_wrap_set() provides a way to cut the text implicitly into a new line when it reaches the far edge of the UI component. The following wrap modes are available:

    -
      -
    • ELM_WRAP_NONE: No wrap
    • -
    • ELM_WRAP_CHAR: Wrap between characters
    • -
    • ELM_WRAP_WORD: Wrap in allowed wrapping points (as defined in the unicode standard)
    • -
    • ELM_WRAP_MIXED: Word wrap, and if that fails, char wrap
    • -
    - -

    Selecting Text

    - -

    Text selections can be made with different functions:

    -
      -
    • To select all the content of the entry component: -
      -elm_entry_select_all(entry);
      -
      -
    • - -
    • To deselect the current selection: -
      -elm_entry_select_none(entry);
      -
      -
    • - -
    • To select part of the text, use elm_entry_select_region_set(). The following code selects the first twenty characters of the entry content. -
      -elm_entry_select_region_set(entry, 0, 20);
      -
      -
    • - -
    • To retrieve the currently selected text in an entry: -
      -const char *selection;
      -
      -selection = elm_entry_selection_get(entry);
      -
      -
    • -
    - -

    If the entry text is empty, elm_entry_selection_get() returns NULL.

    - -

    You can copy or cut the selection to the clipboard.

    -
    -elm_entry_selection_cut(entry);
    -
    - -

    The selection can be pasted in the same or a different entry.

    -
    -elm_entry_selection_paste(entry);
    -
    - -

    Controlling the Cursor

    - -

    The cursor represents the current position in the entry, where the next action, for example, text insertion or deletion, is done. Usually, the cursor is represented as a blinking character, but its appearance depends on the theme configuration. The cursor position can be modified by using several functions.

    -
      -
    • To move the cursor to the beginning of the entry: -
      -elm_entry_cursor_begin_set(entry);
      -
      -
    • - -
    • To move the cursor to the end of the entry: -
      -elm_entry_cursor_end_set(entry);
      -
      -
    • - -
    • To move the cursor one line down or up: -
      -elm_entry_cursor_down(entry);
      -elm_entry_cursor_up(entry);
      -
      -
    • -
    • To move the cursor one character to the left or right: -
      -elm_entry_cursor_prev(entry);
      -elm_entry_cursor_next(entry);
      -
      -
    • - -
    • To set the cursor at a specific position (15th character, for example): -
      -elm_entry_cursor_pos_set(entry, 15);
      -
      -
    • -
    - -

    It is possible to start a selection at the current cursor position, move five characters to the right and end the selection.

    - -
    -elm_entry_cursor_selection_begin(entry);
    -
    -for (i = 0; i < 5; i++)
    -{
    -   elm_entry_cursor_next(entry);
    -}
    -
    -elm_entry_cursor_selection_end(entry);
    -
    - -

    Formatting Text

    - -

    Text within an entry can be formatted by using markups tags that are defined in the theme. The following markups are available:

    -
      -
    • <br>: Inserts a line break.
    • -
    • <ps>: Inserts a paragraph separator. This is preferred over line breaks.
    • -
    • <tab>: Inserts a tab.
    • -
    • <em>...</em>: Emphasis. Sets the oblique style for the enclosed text.
    • -
    • <b>...</b>: Sets the bold style for the enclosed text.
    • -
    • <link>...</link>: Underlines the enclosed text.
    • -
    • <hilight>...</hilight>: Highlights the enclosed text.
    • -
    - -

    Using Special Markups

    - -

    Special markups can be added within the text of the entry:

    -
      -
    • <a href = ..>...</a>: Anchors
    • -
    • <item size = .. vsize = .. href = ..>...</item>: Items
    • -
    - -

    The anchors generate an anchor,clicked signal when the user clicks on them. The href attribute is used to identify the anchor. It also reacts to the anchor,in (mouse in), anchor,out (mouse out), anchor,down (mouse down), and anchor,up (mouse up) events.

    - -

    The item markup provides a way to insert any Evas_Object in the text. The Evas_Object name has to be specified in the href attribute.

    - -

    Overriding Style

    - -

    To tweak the style of the text within the entry component, it is possible to override parts of the theme style to the textblock object by using elm_entry_text_style_user_push(). This function pushes a new style on top of the user style stack that overrides the current style. Remove the style in the top of user style stack with elm_entry_text_style_user_pop().

    - -

    Filtering Text

    - -

    Text within an entry can be filtered in size. The following example sets the maximum number of characters allowed in the entry to 8.

    - -
    -static Elm_Entry_Filter_Limit_Size limit_size = 
    -{
    -   .max_char_count = 8,
    -   .max_byte_count = 0
    -};
    -
    -// Append a new callback to the list, this function is called each time
    -// a text is inserted in the entry. Pass the limit_size struct previously
    -// created to set the maximum number of characters allowed to 8
    - 
    -elm_entry_markup_filter_append(entry, elm_entry_filter_limit_size, limit_size);
    -
    - -

    The content can be filtered by passing an Elm_Entry_Filter_Accept_Set structure. This structure contains the accepted characters and rejected characters. The following example shows how to reject the '+', '-', '*', and '/' characters.

    -
    -static Elm_Entry_Filter_Accept_Set accept_set = 
    -{
    -   .accepted = NULL,
    -   .rejected = "+*-/"
    -};
    -
    -elm_entry_markup_filter_append(entry, elm_entry_filter_accept_set, accept_set);
    -
    - -

    Loading and Saving Files

    - -

    The entry content can be saved to a file (/tmp/test.txt, for example).

    - -
    -// Set the file in which the entry text is saved. This function
    -// implicitly loads the existing file content 
    -elm_entry_file_set(entry, "/tmp/test.txt", ELM_TEXT_FORMAT_MARKUP_UTF8);
    -
    - -

    Autosave is activated by default and changes are written back to the file after a short delay. This feature can be deactivated and you can manually save the content when needed.

    - -
    -// Disable autosaving 
    -elm_entry_autosave_set(entry, EINA_FALSE);
    -
    -// Trigger saving when needed 
    -elm_entry_file_save(entry);
    -
    - -

    Using Entry Theme Content

    - -

    Two content parts of the default theme are available: icon and end. The following example shows how to set an icon in the end content part.

    -
    -Evas_Object *icon;
    -
    -ic = elm_icon_add(entry);
    -elm_image_file_set(ic, "icon.png", NULL);
    -elm_object_part_content_set(entry, "end", icon);
    -
    - -

    Using Entry Theme Texts

    - -

    The default theme allows the use of the following text parts:

    -
      -
    • default - text of the entry
    • -
    • guide - placeholder of the entry
    • -
    - -

    The following example shows how to set the placeholder text of the entry to Hello World.

    - -
    -elm_object_part_text_set(entry, "Hello World");
    -
    - -

    Using Entry Callbacks

    - -

    The entry component emits the following signals:

    -
      -
    • aborted: The escape key is pressed on a single line entry.
    • -
    • activated: The enter key is pressed on a single line entry.
    • -
    • anchor,clicked: An anchor is clicked. event_info points to an object of the type Elm_Entry_Anchor_Info.
    • -
    • anchor,down: Mouse button is pressed on an anchor. event_info points to an object of the type Elm_Entry_Anchor_Info.
    • -
    • anchor,hover,opened: The anchor is clicked. event_info points to an object of the type Elm_Entry_Anchor_Info.
    • -
    • anchor,in: Mouse cursor is moved into an anchor. event_info points to an object of the type Elm_Entry_Anchor_Info.
    • -
    • anchor,out: Mouse cursor is moved out of an anchor. event_info points to an object of the type Elm_Entry_Anchor_Info.
    • -
    • anchor,up: Mouse button is unpressed on an anchor. event_info points to an object of the type Elm_Entry_Anchor_Info.
    • -
    • changed: The text within the entry is changed.
    • -
    • changed,user: The text within the entry is changed because of user interaction. event_info points to an object of the type Edje_Entry_Change_Info.
    • -
    • clicked: The entry is clicked (mouse press and release).
    • -
    • clicked,double: The entry is double clicked.
    • -
    • clicked,triple: The entry is triple clicked.
    • -
    • cursor,changed: The cursor position is changed.
    • -
    • cursor,changed,manual: The cursor position is changed manually.
    • -
    • focused: The entry receives focus. event_info points to an object of the type Elm_Focus_Info.
    • -
    • unfocused: The entry loses focus.
    • -
    • language,changed: Program language is changed.
    • -
    • longpressed: A mouse button is pressed and held for a couple of seconds.
    • -
    • maxlength,reached: A maximum length is reached.
    • -
    • preedit,changed: The preedit string is changed.
    • -
    • press: A mouse button is pressed on the entry.
    • -
    • redo,request: The request is redone.
    • -
    • selection,changed: The current selection is changed.
    • -
    • selection,cleared: The current selection is cleared.
    • -
    • selection,copy: A copy of the selected text into the clipboard is requested.
    • -
    • selection,cut: A cut of the selected text into the clipboard is requested.
    • -
    • selection,paste: A paste of the clipboard contents is requested.
    • -
    • selection,start: A selection is begun and no previous selection exists.
    • -
    • text,set,done: The whole text is set to the entry.
    • -
    • theme,changed: The theme is changed.
    • -
    • undo,request: The request is undone.
    • -
    - -

    For signals, where event_info has not been explicitly described, it is set to NULL.

    - -

    The following example shows how to register a callback to the focused signal.

    - -
    -{
    -   evas_object_smart_callback_add(entry, "focused", focused_cb, data);
    -}
    -
    -// Callback function for the "focused" signal
    -// This callback is called when the entry receive the focus
    -void focused_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   dlog_print(DLOG_INFO, LOG_TAG, "Entry focused\n");
    -} 
    -
    - - -

    Flip

    - -

    Figure: Flip hierarchy

    -

    Flip hierarchy

    - -

    The flip component can hold two Evas_Objects and allows the user flip between them using several pre-defined animations.

    - -

    Adding a Flip Component

    - -

    The following example shows how to create a flip component.

    - -
    -Evas_Object *flip, *parent, *content1, *content2;
    -flip = elm_flip_add(parent);
    -
    - -

    You can add content to the flip component. content1 is set to the front content and content2 is set to the back mode.

    - -
    -elm_object_part_content_set(flip, "front", content1);
    -elm_object_part_content_set(flip, "back", content2);
    -
    - -

    Configuring Flip Animation

    - -

    Now you can run an flip animation.

    -
    -elm_flip_go(flip, ELM_FLIP_CUBE_UP);
    -
    - -

    This animation flips up the front content object as if it was on a side of a cube, letting the down facing side of the cube appear with the back content object. Several animations are available:

    -
      -
    • ELM_FLIP_ROTATE_X_CENTER_AXIS: Rotate the content around a horizontal axis.
    • -
    • ELM_FLIP_ROTATE_Y_CENTER_AXIS: Rotate the content around a vertical axis.
    • -
    • ELM_FLIP_ROTATE_XZ_CENTER_AXIS: Rotate the content around a diagonal axis.
    • -
    • ELM_FLIP_ROTATE_YZ_CENTER_AXIS: Rotate the content around a diagonal axis.
    • -
    • ELM_FLIP_CUBE_LEFT: Rotate the content left as if it was on a side of a cube.
    • -
    • ELM_FLIP_CUBE_RIGHT: Rotate the content right as if it was on a side of a cube.
    • -
    • ELM_FLIP_CUBE_UP: Rotate the content up as if it was on a side of a cube.
    • -
    • ELM_FLIP_CUBE_DOWN: Rotate the content down as if it was on a side of a cube.
    • -
    • ELM_FLIP_PAGE_LEFT: Move the content to the left as if the flip was a book.
    • -
    • ELM_FLIP_PAGE_RIGHT: Move the content to the right as if the flip was a book.
    • -
    • ELM_FLIP_PAGE_UP: Move the content up as if the flip was a book.
    • -
    • ELM_FLIP_PAGE_DOWN: Move the content down as if the flip was a book.
    • -
    - -

    Interacting With the User

    - -

    By default, the user cannot interact with the flip. You can set the interaction to be possible, but you have to choose which animation appears on the interaction (rotation has been selected in the following example).

    - -
    -elm_flip_interaction_set(flip, ELM_FLIP_INTERACTION_ROTATE);
    -
    - -

    The available modes of interaction are

    -
      -
    • ELM_FLIP_INTERACTION_NONE: No interaction is allowed
    • -
    • ELM_FLIP_INTERACTION_ROTATE: Interaction causes a rotating animation
    • -
    • ELM_FLIP_INTERACTION_CUBE: Interaction causes a cube animation
    • -
    • ELM_FLIP_INTERACTION_PAGE: Interaction causes a page animation
    • -
    - -

    You must also choose which interaction directions are enabled. Only right and left are enabled in the following example.

    - -
    -elm_flip_interaction_direction_enabled_set(flip, ELM_FLIP_DIRECTION_LEFT, EINA_TRUE);
    -elm_flip_interaction_direction_enabled_set(flip, ELM_FLIP_DIRECTION_RIGHT, EINA_TRUE);
    -
    - -

    You can also set the amount of the flip that is sensitive to user interaction. In the following example, it is set to the entire flip (1) to make the flip easy to interact with.

    - -
    -elm_flip_interaction_direction_hitsize_set(flip, ELM_FLIP_DIRECTION_LEFT, 1);
    -elm_flip_interaction_direction_hitsize_set(flip, ELM_FLIP_DIRECTION_RIGHT, 1);
    -
    - -

    Using the Flip Callbacks

    - -

    Two signals are emitted by the flip: one when an animation starts and one when it ends. For these signals, event_info parameter is NULL.

    - -
    -"animate,begin" - A flip animation is started
    -"animate,done" - A flip animation is finished
    -
    - -

    You can register a callback on the "animation,begin" signal.

    - -
    -{
    -   evas_object_smart_callback_add(entry, "animate,begin", anim_start_cb, data);
    -}
    -
    -// Callback function for the "animate,begin" signal
    -// This callback is called when the flip animation starts
    -void anim_start_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   dlog_print(DLOG_INFO, LOG_TAG, "Animation starts\n");
    -}
    - -

    Gengrid

    - -

    Figure: Gengrid component

    -

    Gengrid component

    - -

    Figure: Gengrid hierarchy

    -

    Gengrid hierarchy

    - -

    Gengrid component is based on the same idea as the genlist. It aims at displaying objects on a grid layout and rendering only the visible ones. As for the genlist, callbacks are called at item creation or deletion.

    - -

    This UI component inherits from the layout component and implements the scroller interface. Because of this, the scroller and layout functions can be used with this UI component.

    - -

    A gengrid can display its items using a horizontal or vertical layout. In the first layout, the items are displayed in columns from top to bottom, starting a new column when the space for the current column is filled. In the second one, items are set in rows from left to right.

    - -

    Adding a Gengrid Component

    - -

    You can add a gengrid component with the following code.

    -
    -Evas_Object *gengrid, *parent;
    -gengrid = elm_gengrid_add(parent);
    -
    - -

    Gengrid Items

    - -

    A gengrid item is composed of 0 or more texts, 0 or more contents and 0 or more boolean states. The number of the text and content depends on the theme used for gengrid items. In the default Tizen gengrid item theme, items can have two content parts that can be set with the elm.swallow.icon and elm.swallow.end part names.

    - -

    Creating and Deleting Items

    - -

    As with genlists, the items are allocated and deleted on the go, while the user is scrolling the gengrid. The following example shows how to declare a Elm_Gengrid_Item_Class structure to inform the gengrid how to manage items.

    -
    -static Elm_Gengrid_Item_Class *gic = elm_gengrid_item_class_new();
    -gic->item_style = "default";
    -gic->func.text_get = _grid_label_get;
    -gic->func.content_get = _grid_content_get;
    -gic->func.state_get = _grid_state_get;
    -gic->func.del = _grid_del;
    -
    - -

    The parameters of this structure are not be detailed here, because they are very similar to that of the genlist. Please refer to the genlist component page for more detailed information.

    - -

    Managing Items

    - -

    As with genlists, items can be added with the elm_gengrid_item_append(), elm_gengrid_item_prepend(), elm_gengrid_item_insert_before(), and elm_gengrid_item_insert_after() functions. With the gengrid, there is no need to pass the type parameters. They can be cleared with the elm_gengrid_clear() function.

    - -

    You can set the multiselection mode on.

    -
    -elm_gengrid_multi_select_set(gengrid, EINA_TRUE);
    -
    - -

    When the multiselection mode is on, the selected items are retrieved with the elm_gengrid_selected_items_get() function. The function returns a list of all the selected items.

    - -

    When the content of an item changes, you can call elm_gengrid_item_update() to ask the gengrid to update this item's content.

    - -

    It is also possible to select or disable some items manually with the elm_gengrid_item_selected_set() and elm_object_item_disabled_set() functions.

    - -

    Using Gengrid Callbacks

    - -

    The gengrid component emits the following signals:

    -
      -
    • activated: The user has double-clicked or pressed (enter | return | spacebar) on an item. The event_info parameter is the gengrid item that is activated.
    • -
    • clicked,double: The user has double-clicked an item. The event_info parameter is the gengrid item that is double-clicked.
    • -
    • longpressed: The item is pressed for a certain amount of time. By default it is one second.
    • -
    • selected: The user has selected an item. The event_info parameter is the gengrid item that is selected.
    • -
    • unselected: The user has unselected an item. The event_info parameter is the gengrid item that is unselected.
    • -
    • realized: The item in the gengrid has its implementing Evas object instantiated, de facto. event_info is the gengrid item that is created. The object can be deleted at any time, so it is strongly advisable not to use the object pointer returned from elm_gengrid_item_object_get(), because it can point to freed objects.
    • -
    • unrealized: The implementing Evas object for this item is deleted. event_info is the gengrid item that is deleted.
    • -
    • changed: An item is added, removed, resized or moved and the gengrid is resized or has horizontal property changes.
    • -
    • scroll,anim,start: Scrolling animation starts.
    • -
    • scroll,anim,stop: Scrolling animation stops.
    • -
    • drag,start,up: The item in the gengrid is dragged (not scrolled) up.
    • -
    • drag,start,down: The item in the gengrid has dragged (not scrolled) down.
    • -
    • drag,start,left: The item in the gengrid is dragged (not scrolled) left.
    • -
    • drag,start,right: The item in the gengrid is dragged (not scrolled) right.
    • -
    • drag,stop: The item in the gengrid stops being dragged.
    • -
    • drag: The item in the gengrid is dragged.
    • -
    • scroll: The content is scrolled (moved).
    • -
    • scroll,drag,start: Dragging the content starts.
    • -
    • scroll,drag,stop: Dragging the content stops.
    • -
    • edge,top: The gengrid is scrolled to the top edge.
    • -
    • edge,bottom: The gengrid is scrolled to the bottom edge.
    • -
    • edge,left: The gengrid is scrolled to the left edge.
    • -
    • edge,right: The gengrid is scrolled to the right edge.
    • -
    - -

    Genlist

    - -

    Figure: Genlist component

    -

    Genlist component

    - -

    Figure: Genlist hierarchy

    -

    Genlist hierarchy

    - -

    Genlist is a UI component that displays a scrollable list of items. It allows a lot of entries while being fast and has a low memory footprint, as only the visible items are allocated in the memory.

    - -

    For more information, see the Genlist Tutorial.

    - -

    Genlist Item Style

    - -

    An item can have 0 or more texts, 0 or more contents, and 0 or more boolean states. This is defined in the Edje item theme style. Genlist looks for data items named respectively labels, contents, and states in the Edje file. The default item style provides one text part (elm.text), two content parts (elm.swallow.icon and elm.swallow.end) and no state parts.

    - -

    The following item styles are available:

    -
      -
    • default
    • -
    • full
    • -
    • one_icon
    • -
    • end_icon
    • -
    • group_index
    • -
    • double_label
    • -
    - -

    Here are some examples of the item styles.

    - -

    Figure: Default item style

    -

    Default item style

    - -

    Figure: end_icon item style

    -

    end_icon item style

    - -

    Figure: double_label item style

    -

    double_label item style

    - -

    For more information on creating a new genlist item style, see Customizing UI Components.

    - -

    Adding a Genlist Component

    - -

    A genlist component is added with the elm_genlist_add() function.

    -
    -Evas_Object *genlist, *parent;
    -genlist = elm_genlist_add(parent);
    -
    - -

    Creating And Deleting Items

    - -

    To save up memory, genlist allocates and deletes items on the go, while the user is scrolling the list. To enable that, the user creates and fills a Elm_Genlist_Item_Class structure that informs the genlist component which callbacks to call when an item is created or deleted.

    - -
    -Elm_Genlist_Item_Class *itc = elm_genlist_item_class_new();
    -
    -itc->item_style = "default";
    -itc->decorate_item_style = NULL;
    -itc->decorate_all_item_style = NULL;
    -itc->func.text_get = _item_label_get;
    -itc->func.content_get = _item_content_get;
    -itc->func.state_get = _item_state_get;
    -itc->func.del = _item_del;
    -
    - -

    The item_style, decorate_item_style, and decorate_all_item_style attributes define the names of the item style, the decorate mode item style and the decorate all item style.

    - -

    The func structure contains pointers to functions that are called when an item is going to be created or deleted. All of them receive a data parameter that points to the same data passed to the elm_genlist_item_append() and related item creation functions, and an obj parameter that points to the genlist object itself.

    -
      -
    • text_get -

      This function receives a PART parameter that is the name string of one of the existing text parts in the Edje group implementing the item's theme. It has to return a string (duplicated with the strdup() function) corresponding to the PART parameter. The caller is in charge of freeing the string when done.

    • - -
    • content_get -

      The PART parameter is the name string of one of the existing swallow parts in the Edje group. When no content is desired, it must return NULL, or otherwise, a valid object handle. The object is deleted by the genlist on its deletion or when the item is unrealized.

    • - -
    • state_get -

      The PART parameter is the name string of one of the state parts in the Edje group implementing the item's theme. It returns EINA_FALSE for false/off or EINA_TRUE for true/on. The default is false. Genlists emit a signal to the PART parameter's theming Edje object with elm,state,xxx,active as emission and elm as source argument, when the state is true. xxx is the name of the (state) part.

    • - -
    • del -

      This function is called when the genlist item is deleted. It deletes any data that is allocated at the item creation.

    • -
    - -

    Managing Items

    - -

    To add an item, several functions can be used. elm_genlist_item_append() adds an item to the end of the list, or if there is a parent list, to the end of all the child items of the parent list. elm_genlist_item_prepend() is otherwise the same but adds to the beginning of the list or children lists. elm_genlist_item_insert_before() inserts an item before the indicated item and elm_genlist_item_insert_after() inserts an item after the indicated item.

    - -

    The previous functions take a type parameter that can be one of the following.

    -
      -
    • ELM_GENLIST_ITEM_NONE
    • -
    • ELM_GENLIST_ITEM_TREE
    • -
    • ELM_GENLIST_ITEM_GROUP
    • -
    - -

    If ELM_GENLIST_ITEM_TREE is set, this item is displayed as being able to expand and have child items. If ELM_GENLIST_ITEM_GROUP is set, this item is a group index item that is displayed at the top until the next group appears.

    - -

    Figure: Genlist tree

    -

    Genlist tree

    - -

    The application clears the list with elm_genlist_clear(), which deletes all the items in the list. elm_object_item_del() deletes a specific item. elm_genlist_item_subitems_clear() clears all items that are children of the indicated parent item.

    - -

    To help inspect the list items, move to the item at the top of the list with elm_genlist_first_item_get(), which returns the item pointer. elm_genlist_last_item_get() moves to the item at the end of the list. elm_genlist_item_next_get() and elm_genlist_item_prev_get() move to the next and previous items relative to the indicated item. Using these calls you can go through the entire item list or tree.

    - - - - - - - - - - -
    Note
    As a tree, the items are flattened on the list, so elm_genlist_item_parent_get() gives you the name of the parent item (even to skip them if needed).
    - -

    elm_genlist_item_show() scrolls the scroller to show the desired item as visible.

    -

    elm_object_item_data_get() returns the data pointer set by the item creation functions.

    - -

    If an item changes (state, boolean, text or content change), use elm_genlist_item_update() for the genlist to update the item. Genlist re-realizes the item and calls the functions in the _Elm_Genlist_Item_Class for it.

    - -

    Selection

    - -

    Items are manually selected or deselected with elm_genlist_item_selected_set() or disabled with elm_object_item_disabled_set(). In case there is a tree or a group item, the elm_genlist_item_expanded_set() function is used to expand or contract the item.

    - - - - - - - - - - -
    Note
    Calling this function does not show or hide any child of an item (if it is a parent). You must manually delete and create them on the callbacks of the expanded or contracted signals.
    - -

    By default, the genlist is in single-selection mode: only one item can be selected at a time. You can use elm_genlist_multi_select_set() to select multiple items. In the single-selection mode, the elm_genlist_selected_item_get() function can be called to retrieve the selected item. If several items are selected, the elm_genlist_selected_items_get() returns a list of the current selected items.

    - -

    In the following figure, there is a genlist in multi-selection mode with two items selected (#4 and #5) and one item disabled (#2).

    - -

    Figure: Genlist component

    -

    Genlist component

    - -

    Using Genlist Callbacks

    - -

    The genlist component emits the following signals:

    -
      -
    • activated: The user has double-clicked or pressed (enter | return | spacebar) on an item. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
    • -
    • clicked,double: The user has double-clicked an item. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
    • -
    • selected: The user selects an item. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
    • -
    • unselected: The user unselects an item. event_info in the callback function points at an object of type Elm_Object_Item that contains the activated item.
    • -
    • expanded: The item is to be expanded with elm_genlist_item_expanded_set(). This callback fills in the child items. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
    • -
    • contracted: The item is to be contracted with elm_genlist_item_expanded_set(). This callback deletes the child items. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
    • -
    • expand,request: The user wants to expand a tree branch item. The callback decides if the item can expand (if it has any children) and calls elm_genlist_item_expanded_set() to set the state. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
    • -
    • contract,request: The user wants to contract a tree branch item. The callback decides if the item can contract (if it has any children) and calls elm_genlist_item_expanded_set() to set the state. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
    • -
    • realized: The item is created as a real evas object. event_info in the callback function points at an object of the type Elm_Object_Item, that contains the activated item.
    • -
    • unrealized: An item is going to be unrealized. Content objects provided are deleted and the item object is deleted or put into a floating cache. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
    • -
    • drag,start,up: The item in the list is dragged (not scrolled) up. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
    • -
    • drag,start,down: The item in the list is dragged (not scrolled) down. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
    • -
    • drag,start,left: The item in the list is dragged (not scrolled) left. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
    • -
    • drag,start,right: The item in the list is dragged (not scrolled) right. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
    • -
    • drag,stop: The item in the list has stopped being dragged. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
    • -
    • drag: The item in the list is being dragged. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
    • -
    • longpressed: The item is pressed for a certain amount of time. The default specified time is one second. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
    • -
    • scroll,anim,start: The scrolling animation is started. event_info is NULL.
    • -
    • scroll,anim,stop: The scrolling animation is stopped. event_info is NULL.
    • -
    • scroll,drag,start: Dragging the content is started. event_info is NULL.
    • -
    • scroll,drag,stop: Dragging the content is stopped. event_info is NULL.
    • -
    • edge,top: The genlist is scrolled to the top edge. event_info is NULL.
    • -
    • edge,bottom: The genlist is scrolled to the bottom edge. event_info is NULL.
    • -
    • edge,left: The genlist is scrolled to the left edge. event_info is NULL.
    • -
    • edge,right: The genlist is scrolled to the right edge. event_info is NULL.
    • -
    • multi,swipe,left: The genlist is multi-touch swiped left. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
    • -
    • multi,swipe,right: The genlist is multi-touch swiped right. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
    • -
    • multi,swipe,up: The genlist is multi-touch swiped up. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
    • -
    • multi,swipe,down: The genlist is multi-touch swiped down. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
    • -
    • multi,pinch,out: The genlist is multi-touch pinched out. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
    • -
    • multi,pinch,in: The genlist is multi-touch pinched in. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
    • -
    • swipe: The genlist is swiped. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
    • -
    • moved: A genlist item is moved in the reorder mode. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
    • -
    • moved,after: A genlist item is moved after another item in the reorder mode. To access the relative previous item, use elm_genlist_item_prev_get(). This signal is called along with the moved signal. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
    • -
    • moved,before: A genlist item is moved before another item in the reorder mode. To access the relative previous item, use elm_genlist_item_next_get(). This signal is called along with the moved signal. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
    • -
    • language,changed The program's language is changed. event_info is NULL.
    • -
    • tree,effect,finished: A genlist tree effect is finished. event_info is NULL.
    • -
    - - -

    GLView

    - -

    Figure: GLView gears example

    -

    GLView gears example

    - -

    Figure: GLView hierarchy

    -

    GLView hierarchy

    - - -

    The GLView component renders OpenGL in an elementary object, which hides Evas GL complexity. For more information, see OpenGL ES.

    - -

    Adding a GLView Component

    - -

    Create a GLView component with the elm_glview_add() function.

    -
    -Evas_Object *glview, *parent;
    -
    -glview = elm_glview_add(parent);
    -
    - -

    In this example, the size of the GLView is set to 200x200 pixels.

    -
    -elm_glview_size_set(glview, 200, 200);
    -
    - -

    Using the GLView API

    - -

    You can configure the GLView rendering mode by activating the following rendering modes:

    - -
      -
    • ELM_GLVIEW_ALPHA: Alpha channel rendering mode
    • -
    • ELM_GLVIEW_DEPTH: Depth buffer rendering mode
    • -
    • ELM_GLVIEW_STENCIL: Stencil buffer rendering mode
    • -
    • ELM_GLVIEW_DIRECT: Direct rendering mode
    • -
    • ELM_GLVIEW_CLIENT_SIDE_ROTATION: The client handles the GL view rotation if direct rendering is enabled
    • -
    - -

    In the following example, the alpha channel and depth buffer rendering mode are enabled.

    -
    -elm_glview_mode_set(glview, ELM_GLVIEW_ALPHA | ELM_GLVIEW_DEPTH);
    -
    - -

    The following example shows how to decide what to do with the GL surface when the GLView component is resized.

    -
    -elm_glview_resize_policy_set(glview, ELM_GLVIEW_RESIZE_POLICY_RECREATE);
    -
    - -

    The GL surface is destroyed and recreated to the new size (default function). The resize policy can also be set to ELM_GLVIEW_RESIZE_POLICY_SCALE. In that case, only the image object is scaled, not the underlying GL surface.

    - -

    The following example shows how to set the GLView rendering policy.

    -
    -elm_glview_render_policy_set(glview, ELM_GLVIEW_RENDER_POLICY_ALWAYS);
    -
    - -

    The GLView object is always redrawn during the rendering loop. It can also be set to ELM_GLVIEW_RENDER_POLICY_ON_DEMAND (default function), where the GLView component is redrawn only when it is visible.

    - -

    Register the callbacks:

    - -
    elm_glview_init_func_set(glview, _init_gl_cb);
    -elm_glview_del_func_set(glview, _del_gl_cb);
    -elm_glview_resize_func_set(glview, _resize_gl_cb);
    -elm_glview_render_func_set(glview, _draw_gl_cb);
    -
    - -
      -
    • elm_glview_init_func_set() registers an init callback that is called at the GLView object creation.
    • -
    • elm_glview_del_func_set() registers a del function that is called when the GLView object is deleted.
    • -
    • elm_glview_resize_func_set() registers the resize function that is called during the rendering loop when the GLView object is resized.
    • -
    • elm_glview_render_func_set() registers the render function that is called when the GLView object must be redrawn.
    • -
    - -

    Using GLView Callbacks

    - -

    The GLView component emits the following signals:

    - -
      -
    • focused: The Glview component is focused. The event_info parameter points at an object of the type Elm_Focus_Info.
    • -
    • unfocused: The GLView object is unfocused.
    • -
    - -

    To register a callback:

    -
    -{
    -      evas_object_smart_callback_add(glview, "focused", focused_cb, data);
    -}
    -
    -// Callback function for the "focused" signal
    -// This callback is called when the GLView is focused
    -void focused_cb(void *data, Evas_Object *obj, void  *event_info)
    -{
    -      Elm_Focus_Info *fi = event_info;
    -
    -      dlog_print(DLOG_INFO, LOG_TAG, "GLView is focused\n");
    -}
    -
    - -

    Icon

    - -

    Figure: Icon component

    -

    Icon component

    - -

    Figure: Icon hierarchy

    -

    Icon hierarchy

    - -

    The icon component inherits from the image component. It is used to display images in an icon context.

    - -

    Adding an Icon Component

    - -

    You can create an icon and set it as a freedesktop.org Home standard icon.

    - -
    -Evas_Object *icon, *parent;
    -icon = elm_icon_add(parent);
    -elm_icon_standard_set(icon, "Home");
    -
    - -

    Changing Image File

    - -

    You can change the image by using an image in the filesystem (for example, /tmp/Home.png).

    -
    -elm_image_file_set(icon, "/tmp/Home.png", NULL);
    -
    - -

    You can also use a group in an Edje file (for example, /tmp/Home.edj).

    -
    -elm_image_file_set(icon, "/tmp/Home.edj", "elm/icon/Home/default");
    -
    - -

    A thumbnail can be generated and cached for future use. For this, you need the Ethumb library support.

    - -
    -elm_icon_thumb_set(icon, "/tmp/Home.png", NULL);
    -
    - -

    This function sets the file in the icon and enables the use of a cached thumbnail if it already exists. Otherwise, it creates a new thumbnail and caches it for future use.

    - -

    Using Icon Callbacks

    - -

    The icon component emits the following signals:

    -
      -
    • thumb,done: elm_icon_thumb_set() is completed with success.
    • -
    • thumb,error: elm_icon_thumb_set() fails.
    • -
    - -

    In both cases, event_info is NULL.

    - - -

    Image

    - -

    Figure: Image component

    -

    Image component

    - -

    Figure: Image hierarchy

    -

    Image hierarchy

    - -

    The image component can load and display an image from a disk file or a memory region.

    - -

    Adding an Image Component

    - -

    This object is created with elm_image_add().

    - -
    -Evas_Object *image, *parent;
    -image = elm_image_add(parent);
    -
    - -

    Configuring the Image Component

    - -

    Various properties of the image can be tuned. First, you can disable the elementary scaling so that the image does not scale but resizes on both directions.

    -
    -elm_image_no_scale_set(image, EINA_TRUE);
    -elm_image_resizable_set(image, EINA_TRUE, EINA_TRUE);
    -
    - -

    When scaling images, the smooth scaling algorithm can be used. It provides a better quality image but is slower than the default algorithm.

    -
    -elm_image_smooth_set(image, EINA_TRUE);
    -
    - -

    Preloading is used to load images without blocking the user interface. This preserves the reactivity of the user experience. The image is loaded in a thread. It can be disabled if desired.

    -
    -elm_image_preload_disabled_set(image, EINA_TRUE);
    -
    - -

    The image can be rotated or flipped. Here the image is rotated 180 degrees.

    -
    -elm_image_orient_set(image, ELM_IMAGE_ROTATE_180);
    -
    - -

    The following orientations are available:

    -
      -
    • ELM_IMAGE_ORIENT_0: No orientation change
    • -
    • ELM_IMAGE_ROTATE_90: Rotate the image 90 degrees clockwise
    • -
    • ELM_IMAGE_ROTATE_180: Rotate the image 180 degrees clockwise
    • -
    • ELM_IMAGE_ROTATE_270: Rotate the image 90 degrees counter-clockwise
    • -
    • ELM_IMAGE_FLIP_HORIZONTAL: Flip the image horizontally
    • -
    • ELM_IMAGE_FLIP_VERTICAL: Flip the image vertically
    • -
    • ELM_IMAGE_FLIP_TRANSPOSE: Flip the image along the bottom-left to top-right line
    • -
    • ELM_IMAGE_FLIP_TRANSVERSE: Flip the image along the top-left to bottom-right line
    • -
    - -

    If you want to keep the original aspect ration when resizing the image, you must define how the image fits into the object's area.

    -
    -// Tell the image to keep original aspect ratio 
    -elm_image_aspect_fixed_set(image, EINA_TRUE);
    -// Then let the image fill the entire object 
    -elm_image_fill_outside_set(image, EINA_TRUE);
    -
    - -

    In this configuration, part of the image can go outside the object. If elm_image_fill_outside_set is set to EINA_FALSE, the image stays inside the limits of the parent object.

    - -

    Using Image Callbacks

    - -

    The image component emits the following signals:

    -
      -
    • drop: The user drops an image typed object onto the object in question - the event info argument is the path to that image file
    • -
    • clicked: The user clicks the image. event_info is NULL.
    • -
    - -

    To register a callback when a user clicks on the image:

    -
    -{
    -   evas_object_smart_callback_add(image, "clicked", clicked_cb, data);
    -}
    -
    -// Callback function for the "clicked" signal
    -// This callback is called when the image is clicked
    -void clicked_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   dlog_print(DLOG_INFO, LOG_TAG, "Image clicked\n");
    -}
    -
    - -

    Index

    - -

    Figure: Index component

    -

    Index component

    - -

    Figure: Index hierarchy

    -

    Index hierarchy

    - -

    An index component gives you an index for fast access to whichever group of other UI items you have. The index component is by default hidden, but it appears when the user clicks over its reserved area in the canvas. In the default theme, it is a one finger wide area on the right side of the index component's container. Generally, an index is used together with lists, generic lists, or generic grids.

    - -

    Adding an Index Component

    - -

    Call the elm_index_add() function to create a new index component.

    -
    -Evas_Object *index, *parent;
    -index = elm_index_add(parent);
    -
    - -

    Adding Items

    - -

    The following example shows how to add the listitem object at the letter A, calling the smart callback it_select_cb() when this item is selected.

    -
    -Elm_Object_Item *list_item1, *list_item2;
    -elm_index_item_append(index, "A", it_select_cb, list_item1);
    -
    - -

    The following example shows how to define the smart callback.

    -
    -// Callback function called when the list_item1 object
    -// is selected
    -void it_select_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   dlog_print(DLOG_INFO, LOG_TAG, "Item1 selected\n");
    -}
    -
    - -

    In the previous case, the indexes are appended to the existing ones. It is also possible to prepend index items with elm_index_item_prepend().

    - -

    Sorting Index Items

    - -

    You can insert index items using a sorting function. Indexes can be sorted, for example, by alphabetic order.

    - -

    You must write a compare function that returns a positive int, 0 or a negative int when the data2 item parameter is respectively greater than, equal to or lower than the data1 parameter.

    - -
    -static int
    -_index_icmp(const void *data1,
    -      const void *data2)
    -{
    -   int result;
    -
    -   // Code that does the item comparison is written here
    -
    -   return result;
    -}
    -
    - -

    This example shows how to add a new item at the B index using the compare function to sort the indexes.

    - -
    -elm_index_item_sorted_insert(index, "B", NULL, list_item2, _index_icmp, NULL);
    -
    - -

    Using Index Callbacks

    - -

    The index component emits the following signals:

    -
      -
    • changed: The selected index item changes. event_info is the selected item's data pointer.
    • -
    • delay,changed: The selected index item changes, but after a small idling period. event_info is the selected item's data pointer.
    • -
    • selected: The user releases a mouse button and selects an item. event_info is the selected item's data pointer.
    • -
    • level,up: The user moves a finger from the first level to the second level.
    • -
    • level,down: The user moves a finger from the second level to the first level.
    • -
    - -

    When the user selects an item in the index, the selected signal is emitted. The developer can then implement the associated callback to do the appropriate action (to show a given area or child object depending on the index item selected, for example). Here is an example of such a callback.

    -
    -static void
    -_index_selected_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   Elm_Object_Item *lit = event_info;
    -
    -   // Code that does the desired action
    -}
    -
    - -

    After that, the callback to the selected signal is registered.

    -
    -evas_object_smart_callback_add(index, "selected", _index_selected_cb, NULL);
    -
    - - -

    Label

    - -

    Figure: Label component

    -

    Label component

    - -

    Figure: Label hierarchy

    -

    Label hierarchy

    - -

    The label component displays text with simple html-like markup.

    - -

    Adding a Label Component

    - -

    To add a label and set the text in it, use the following functions.

    - -
    -Evas_Object *label = elm_label_add(win);
    -
    -elm_object_text_set(label, "Some long text for our label, that is not so long");
    -
    - -

    Using the Label Styles

    - -

    Label displays the text with several predefined styles.

    -
      -
    • default: No animation
    • -
    • marker: The text is centered and bolded.
    • -
    • slide_long: The text appears from the right of the screen and slides until it disappears in the left of the screen(reappearing on the right again).
    • -
    • slide_short: The text appears in the left of the label and slides to the right to show the overflow. When all of the text has been shown the position is reset.
    • -
    • slide_bounce: The text appears in the left of the label and slides to the right to show the overflow. When all of the text has been shown, the animation reverses, moving the text to the left.
    • -
    - -

    Here the style is set to slide_long.

    - -
    -elm_object_style_set(label, "slide_long");
    -
    - -

    Configuring the Label

    - -

    The duration of the animation and the slide mode can be set with the following functions.

    -
    -elm_label_slide_duration_set(label, 3);
    -elm_label_slide_mode_set(label, ELM_LABEL_SLIDE_MODE_ALWAYS);
    -
    - -

    Use the following function to modify the style.

    -
    -elm_object_style_set(label, "slide_bounce");
    -
    - -

    Using the Label Callbacks

    - -

    This UI component emits the following signals:

    -
      -
    • language,changed: The program's language changes.
    • -
    • slide,end: The slide reaches the end.
    • -
    • anchor,clicked: The anchor is clicked. event_info points to an object of the type Elm_Label_Anchor_Info.
    • -
    • anchor,mouse,down event_info points to an object of the type Elm_Label_Anchor_Info.
    • -
    • anchor,mouse,up event_info points to an object of the type Elm_Label_Anchor_Info.
    • -
    - -

    The following example registers a callback on the slide,end signal.

    - -
    -{
    -   evas_object_smart_callback_add(label, "slide,end", slide_end_cb, data);
    -}
    -
    -// Callback function for the "slide,end" signal
    -// This callback is called when the label slide reaches the end
    -void slide_end_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   dlog_print(DLOG_INFO, LOG_TAG, "Slide has reach the end.\n");
    -}
    -
    - -

    List

    - -

    Figure: List component

    -

    List component

    - -

    Figure: List hierarchy

    -

    List hierarchy

    - - -

    This UI component is a very simple type of a list component. It is not to be used to manage a lot of items. For that, genlists are a better option.

    - -

    The list items can contain a text and two contents (start and end). These are set with the elm_object_item_*() functions.

    - -

    Adding a List Component

    - -
    -Evas_Object *list, *parent;
    -
    -// Create a list 
    -list = elm_list_add(parent);
    -
    - -

    Using the List

    - -

    This UI component implements the scrollable interface, so the scroller component functions can be used on it. For example, if you want to change the bounce property of the scroller or the scrolling policy:

    - -
    -Evas_Object *list;
    -
    -// Change the scroller policy to fix the scroll only vertically
    -elm_scroller_policy_set(list, ELM_SCROLLER_POLICY_ON, ELM_SCROLLER_POLICY_OFF);
    -// Enable bounce effect when the list reaches the upper and lower limits 
    -elm_scroller_bounce_set(list, EINA_TRUE, EINA_TRUE);
    -
    - -

    The elm_list_multi_select_set() function can be called to enable multi-selection of items. Each time an item is clicked, the state changes to selected.

    - -
    -Evas_Object *list;
    -
    -// Activate multi selection 
    -elm_list_multi_select_set(list, EINA_TRUE);
    -
    - -

    Adding Item to the List

    - -

    Items are added with elm_list_item_append() or elm_list_item_prepend(). Here an example of adding ten items with text and one icon on the front: The last two arguments are the callback function when the created item is clicked and the data passed to the callback function.

    - -
    -Evas_Object *list;
    -int i;
    -
    -// This function is called when the list item is selected 
    -static void _selected_item_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   Elm_Object_Item *list_it = elm_list_selected_item_get(obj);
    -   Eina_Bool selected = elm_list_item_selected_get(list_it);
    -   dlog_print(DLOG_INFO, LOG_TAG, "item is %s\n", selected? "selected": "unselected");
    -}
    -
    -for (i = 0; i < 10; i++)
    -{
    -   Evas_Object *ic;
    -   char tmp[8];
    -   snprintf(tmp, sizeof(tmp), "Item %02d", i);
    -   // Create an icon 
    -   ic = elm_icon_add(win);
    -   // Set the file to the icon file 
    -   elm_image_file_set(ic, "path/to/file", NULL);
    -   // Add item to the list 
    -   elm_list_item_append(list, tmp, ic, NULL, _selected_item_cb, NULL);
    -}
    -
    -
    - -

    Changing the Text or Icon of an Item

    - -

    If you want to change the state of an item, you can do it by using all the functions relative to Elm_Object_Item. Each item of the list contains two instances of an evas_object. Give those as the third and the fourth arguments when you append or prepend the item in the list. The evas_object instances are changed with elm_object_item_part_content_set. The first object is referenced as the start object in the theme, whereas the second one is referenced as the end object. Give these names when you use the elm_object_item_part_content_set. The label of the item is changed by using elm_object_item_text_set.

    - -
    -Evas_Object *list;
    -Eina_List *l;
    -Elm_Object_Item *it;
    -
    -// Retrieve the current selected item 
    -it = elm_list_selected_item_get(list);
    -if (!it)
    -   return;
    -
    -ic = elm_icon_add(win);
    -// Set the file to the icon file 
    -elm_image_file_set(ic, "path/to/file", NULL);
    -// Change the first icon 
    -elm_object_item_part_content_set(it, "start", ic);
    -// Change the second icon 
    -elm_object_item_part_content_set(it, "end", ic);
    -// Change the label 
    -elm_object_item_text_set(it, "I've been selected !");
    -
    - -

    Retrieving Selected Items

    - -

    The list of the currently selected items is retrieved with elm_list_selected_items_get(). If the multiselect mode is false, you can retrieve the only selected item with elm_list_selected_item_get(). For example, this is how to unselect all previously selected items.

    - -
    -Evas_Object *list; Eina_List *l;
    -Eina_List *selected_items;
    -// List of Elm_Object_Item 
    -Elm_Object_Item *it;
    -
    -selected_items = elm_list_selected_items_get(list);
    -EINA_LIST_FOREACH(selected_items, l, it)
    -   elm_list_item_selected_set(it, EINA_FALSE);
    -
    - -

    List Item Operations

    - -

    To find out if an item is selected, call elm_list_item_selected_get. This function returns EINA_TRUE if the item is selected, otherwise EINA_FALSE.

    - -

    Elementary list provides two functions for sliding a list to a specific item. elm_list_item_show shows the item passed as an argument, whereas elm_list_item_bring_in shows the item, but only after animating the slide.

    - -

    You can go to the item immediately preceding a specific item with the function elm_list_item_prev, or to the one immediately following a specific item with the function elm_list_item_next.

    - -

    The following example shows selecting the item immediately following the currently selected one, unselecting it, selecting the next one and bringing it to the screen.

    - -
    -Evas_Object *list;
    -Elm_Object_Item *current, *next;
    -current = elm_list_selected_item_get(list);
    -elm_list_item_selected_set(current, EINA_FALSE);
    -next = elm_list_item_next(current);
    -elm_list_item_selected_set(next, EINA_TRUE);
    -elm_list_item_bring_in(next);
    -
    - -

    Using List Callbacks

    - -

    The list emits the following signals:

    -
      -
    • activated: The user double-clicks or presses (enter | return | spacebar) on an item. The event_info parameter of the callback function contains a pointer to the item activated.
    • -
    • clicked,double: The user double-clicks an item. The event_info parameter of the callback function contains a pointer to the item activated.
    • -
    • selected: The user selects an item. The event_info parameter of the callback function contains a pointer to the item activated.
    • -
    • unselected: The user unselects an item. The event_info parameter of the callback function contains a pointer to the item activated.
    • -
    • longpressed: The user long-presses an item. The event_info parameter of the callback function contains a pointer to the item activated.
    • -
    • edge,top: The list is scrolled to the top edge.
    • -
    • edge,bottom: The list is scrolled to the bottom edge.
    • -
    • edge,left: The list is scrolled to the left edge.
    • -
    • edge,right: The list is scrolled to the right edge.
    • -
    • highlighted: The user highlights an item on the list. The event_info parameter of the callback function contains a pointer to the item activated.
    • -
    • unhighlighted: The user unhighlights an item in the list. The event_info parameter of the callback function contains a pointer to the item activated.
    • -
    - -

    You can register to the clicked,double signal with the following code. Note that the currently double-clicked item can be retrieved using the event_info pointer. This code registers to the double,clicked signal and unselects the item that has been double-clicked.

    - -
    -{
    -   Evas_Object *list;
    -
    -   evas_object_smart_callback_add(list, "clicked,double", double_clicked_cb, data);
    -}
    -
    -// Callback function for the "clicked" signal
    -// This callback is called when the button is clicked by the user
    -void double_clicked_cb(void *data, Evas_Object *obj, void  *event_info)
    -{
    -   elm_Object_Item *it = event_info;
    -   elm_list_selected_item_set(it,  EINA_FALSE);
    -}
    -
    - -

    Map

    - -

    Figure: Map hierarchy

    -

    Map hierarchy

    - -

    The map component displays a geographic map. The default map data are provided by the OpenStreetMap project (http://www.openstreetmap.org/). Custom providers can also be added.

    - -

    This UI component supports:

    -
      -
    • Zooming
    • -
    • Scrolling
    • -
    • Markers with content to be displayed when the user clicks over them
    • -
    • Group of markers
    • -
    • Routes
    • -
    - -

    The map component implements the scroller interface so that all the functions that work with the scroller component also work with maps.

    - -

    Adding a Map Component

    - -

    Once created with the elm_map_add() function, zoom level x12 can be set.

    - -
    -Evas_Object *map, *parent;
    -
    -map = elm_map_add(parent);
    -elm_map_zoom_mode_set(map, ELM_MAP_ZOOM_MODE_MANUAL);
    -elm_map_zoom_set(map, 12);
    -
    - -

    Here the zoom mode is set to manual, but it can also be set to the ELM_MAP_ZOOM_MODE_AUTO_FIT mode and the ELM_MAP_ZOOM_MODE_AUTO_FILL mode. In that case however, the elm_map_zoom_set() function cannot be used.

    - -

    Playing with the Map

    - -

    If you have coordinates of a specific area (2 2 N, 48 8 E), it can be shown on the map.

    -
    -elm_map_region_show(map, 2.2, 48.8);
    -
    - -

    This shows the desired coordinates. The location can also be shown with a bring-in animation.

    -
    -elm_map_region_bring_in(map, 2.2, 48.8);
    -
    - -

    The map is rotated 90 degrees around the current position.

    -
    -elm_map_rotate_set(map, 90, 2.2, 48.8);
    -
    - -

    Drawing Overlays

    - -

    Overlays are markers that can be placed anywhere on the map. They can represent any object you want to put on the map.

    - -

    Creating an Overlay Class

    - -

    Overlay classes can be created if several objects are of the same type. For example, you can create a forest overlay class to represent the forests visible on the map. To do this, set the minimum zoom level at which this class is visible. The forest class overlay is visible when the zoom level is superior to eight.

    - -

    Set an icon ("Home" icon) to the forest class. This icon is displayed in place of the forest class on the map.

    -
    -Evas_Object *icon;
    -Elm_Map_Overlay *forest_class = elm_map_overlay_class_add(map);
    -
    -// Set min zoom level at which class is displayed
    -elm_map_overlay_displayed_zoom_min_set(forest_class, 8);
    -
    -// Create a Home icon object and set it to the forest class 
    -icon = elm_icon_add(map);
    -elm_icon_standard_set(icon, "home");
    -elm_map_overlay_icon_set(forest_class, icon);
    -
    - -

    Adding Overlays to a Class

    - -

    After creating a forest class, it is possible to add overlay objects to it. Here an overlay for the Meudon forest is created. The data is linked to the overlay with the elm_map_overlay_data_set() function. Set the name of the forest in the data. The icon can be set to the overlay with the elm_map_overlay_icon_set() function.

    - - - - - - - - - - -
    Note
    Do not use the same icon object for two different overlays. Create a new icon object each time you need one.
    - -
    -Elm_Map_Overlay *ovl;
    -const char* data_meudon = "Meudon forest";
    -const char* data_fausses = "Fausse forest";
    -
    -// Add an overlay
    -ovl = elm_map_overlay_add(map, 2.20718, 48.79759);
    -icon = elm_icon_add(map);
    -elm_icon_standard_set(icon, "stop");
    -elm_map_overlay_icon_set(ovl, icon);
    -elm_map_overlay_data_set(ovl, &data_meudon);
    -
    -// Add the new ovl object to the forest class 
    -elm_map_overlay_class_append(forest_class, ovl);
    -
    -// Add another overlay next to the first one 
    -ovl = elm_map_overlay_add(map, 2.1699, 48.8189);
    -icon = elm_icon_add(map);
    -elm_icon_standard_set(icon, "stop");
    -elm_map_overlay_icon_set(ovl, icon);
    -elm_map_overlay_data_set(ovl, &data_fausses);
    -elm_map_overlay_class_append(forest_class, ovl);
    -
    - -

    If you add another overlay to the forest class, the two overlays can be grouped under the forest class icon on certain zoom level conditions. You can define on which zoom level items are grouped.

    -
    -elm_map_overlay_class_zoom_max_set(forest_class, 8);
    -
    - -

    In this case, overlay members of the forest class are grouped when the map is displayed at less than zoom level eight.

    - -

    Creating Bubbles Following Overlays

    - -

    The following example shows how to set a content in a bubble following an overlay.

    - -
    -// Add an overlay bubble object 
    -Elm_Map_Overlay *bubble = elm_map_overlay_bubble_add(map);
    -
    -// Set it to follow a specific overlay (the last created one here) 
    -elm_map_overlay_bubble_follow(bubble, ovl);
    -
    - -

    Once following an overlay, the bubble appears, moves or hides following the parent overlay's behavior.

    - -

    Content is added to the bubble with the elm_map_overlay_bubble_content_append() function.

    - -

    Adding Other Overlays

    - -

    You can draw a circle on the map with coordinates and a radius size.

    -
    -Elm_Map_Overlay *circle = elm_map_overlay_circle_add(map, 2.2, 48.8, 0.02);
    -
    - -

    You can also add a scale at the 200x0 coordinate (in pixels).

    -
    -Elm_Map_Overlay *scale = elm_map_overlay_scale_add(map, 200, 0);
    -
    - -

    You can also draw a line, a polygon, or a route. For a full description of these functions, see the Map API.

    - -

    Calculating Routes

    - -

    A route between a starting point and an ending point is calculated with the elm_map_route_add() call. The type of transport and the routing calculation method can be provided so as to have the desired result.

    - -

    The following example shows how to get a route calculation between the first and the second overlay. It is configured to use the bicycle, and to find the fastest route possible.

    - -
    -Elm_Map_Route *route = elm_map_route_add(map,
    -         ELM_MAP_ROUTE_TYPE_BICYCLE,
    -         ELM_MAP_ROUTE_METHOD_FASTEST,
    -         2.20718, 48.79759,
    -         2.1699, 48.8189,
    -         NULL, NULL);
    -
    -// Add a callback to when the route has been calculated and loaded 
    -evas_object_smart_callback_add(map, "route,loaded", _route_loaded_cb, route);
    -
    - -

    Once the route is calculated, create a route overlay object and change its color. In this example, the route,loaded callback is used.

    -
    -static void
    -_route_loaded_cb(void *data, Evas_Object *obj, void *ev)
    -{
    -   Elm_Map_Route *route = data;
    -
    -   Elm_Map_Overlay *route_ovl = elm_map_overlay_route_add(obj, route);
    -   elm_map_overlay_color_set(route_ovl, 0, 255, 0, 255);
    -}
    -
    - -

    Using Map Callbacks

    - -

    The map component emits the following callbacks:

    -
      -
    • clicked: The user has clicked the map without dragging around.
    • -
    • clicked,double: The user has double-clicked the map.
    • -
    • press: The user has pressed down on the map.
    • -
    • longpressed: The user has pressed down on the map for a long time without dragging around.
    • -
    • scroll: The content is scrolled (moved).
    • -
    • scroll,drag,start: Dragging the contents around starts.
    • -
    • scroll,drag,stop: Dragging the contents around stops.
    • -
    • scroll,anim,start: Scrolling animation starts.
    • -
    • scroll,anim,stop: Scrolling animation stops.
    • -
    • zoom,start: Zoom animation starts.
    • -
    • zoom,stop: Zoom animation stops.
    • -
    • zoom,change: The zoom is changed when using an auto zoom mode.
    • -
    • tile,load: A map tile image load begins.
    • -
    • tile,loaded: A map tile image load ends.
    • -
    • tile,loaded,fail: A map tile image load fails.
    • -
    • route,load: Route request begins.
    • -
    • route,loaded: Route request ends.
    • -
    • route,loaded,fail: Route request fails.
    • -
    • name,load: Name request begins.
    • -
    • name,loaded: Name request ends.
    • -
    • name,loaded,fail: Name request fails.
    • -
    • overlay,clicked: An overlay is clicked.
    • -
    • loaded: The map is loaded.
    • -
    - - -

    Notify

    - -

    Figure: Notify hierarchy

    -

    Notify hierarchy

    - -

    The notify component displays a container in a particular region of the parent object. It can receive some content, and can be automatically hidden after a certain amount of time.

    - -

    Adding a Notify Component

    - -

    The following example shows how to create a notify object.

    - -
    -Evas_Object *notify, *parent;
    -notify = elm_notify_add(parent);
    -
    - -

    Configuring the Notify Component

    - -

    Create a label and add it to the notify object.

    - -
    -Evas_Object *content;
    -
    -// Create the label and set some text to it 
    -content = elm_label_add(parent);
    -
    -elm_object_text_set(content, "A label text");
    -evas_object_show(content);
    -
    -// Add the label object to the notify component
    -elm_object_content_set(notify, content);
    -
    - -

    In the following example the notify object is shown on the bottom left corner of the parent object.

    - -
    -elm_notify_align_set(notify, 1.0, 1.0);
    -evas_object_show(notify);
    -
    - -

    Set a timeout interval, after which the notify component is hidden. In the following example the timeout interval is five seconds.

    - -
    -elm_notify_timeout_set(notify, 5.0);
    -
    - -

    Using Notify Callbacks

    - -

    The notify component emits the following signals:

    -
      -
    • timeout: The timeout count ends and the notify component is hidden
    • -
    • block,clicked: The user clicks outside of the notify component
    • -
    - -

    For both these signals event_info is NULL.

    - -

    The following example shows how to register a callback on the timeout signal.

    - -
    -{
    -   evas_object_smart_callback_add(notify, "timeout", timeout_cb, data);
    -}
    -
    -// Callback function for the "timeout" signal
    -// The timeout expires and the notify object is hidden
    - 
    -void timeout_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   dlog_print(DLOG_INFO, LOG_TAG, "Notify is hidden\n");
    -}
    -
    - - -

    Panel

    - - -

    Figure: Panel hierarchy

    -

    Panel hierarchy

    -

    The panel component is an animated object that can contain subobjects. It can be expanded or contracted by clicking on the button on its edge.

    - -

    Panel inherits from layout component, so the layout API can be used on this UI component.

    - -

    Adding a Panel Component

    - -

    The following example shows how to add a panel and set its orientation to the left.

    - -
    -Evas_Object *panel, *parent;
    -
    -panel = elm_panel_add(parent);
    -elm_panel_orient_set(panel, ELM_PANEL_ORIENT_LEFT);
    -
    - -

    Using the Panel

    - -

    The panel can be manually hidden.

    -
    -elm_panel_hidden_set(pan, EINA_TRUE);
    -
    - -

    The panel can be toggled if you do not know the hidden state of the UI component.

    -
    -elm_panel_toggle(pan);
    -
    - -

    The panel can be set scrollable.

    -
    -elm_panel_scrollable_set(pan, EINA_TRUE);
    -
    - -

    Creating a Drawer

    - -

    Tizen SDK has implemented a layout theme to add a drawer in the application. This example shows how to add a new Elementary layout object and set the theme of this layout to the drawer.

    - -
    -Evas_Object *layout;
    -
    -// Create a new layout object 
    -layout = elm_layout_add(parent);
    -
    -// Set the "drawer" group theme and "panel" style to it 
    -elm_layout_theme_set(layout,"layout", "drawer", "panel");
    -
    -// Show the new layout
    -evas_object_show(layout);
    -
    - -

    Once the panel object is created, it can be swallowed in the new layout.

    - -
    -elm_object_part_content_set(layout, "elm.swallow.left", pan);
    -
    - -

    You can set content to the elm.swallow.bg and elm.swallow.content parts of the layout.

    -
    -// Panel Background (Dimmed Area) 
    -Evas_Object *bg = create_bg(layout);
    -elm_object_part_content_set(layout, "elm.swallow.bg", bg);
    -
    -// Add content to the drawer 
    -Evas_Object *content;
    -elm_object_part_content_set(layout, "elm.swallow.content", content);
    -
    - -

    Using Panel Callbacks

    - -

    You can register a callback on the scroll signal, when the user scrolls the panel. The event_info parameter is of the type Elm_Panel_Scroll_Info.

    - -
    -{
    -   evas_object_smart_callback_add(pan, "scroll", scroll_cb, data);
    -}
    -// Callback function for the "scroll" signal
    -// This callback is called when the user scrolls the panel
    -void scroll_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   Elm_Panel_Scroll_Info *scrollinfo = event_info;
    -   dlog_print(DLOG_INFO, LOG_TAG, "The panel was scrolled.\n");
    -}
    -
    - - -

    Photo

    - -

    Figure: Photo hierarchy

    -

    Photo hierarchy

    - -

    The photo component is used to display a photo, such as a contact image. If no photo is set on it, it displays a person icon to show that it is a photo placeholder.

    - -

    Adding a Photo Component

    - -

    The following example shows how to create a photo object.

    - -
    -Evas_Object *photo, *parephotoslider = elm_photo_add(parent);
    -photo = elm_photo_add(parent);
    -
    - -

    Using a Photo Component

    - -

    A file can be set to the photo component. Here, PHOTO_FILENAME is a string corresponding to the photo file name on the system.

    -
    -elm_photo_file_set(photo, PHOTO_FILENAME);
    - -

    The photo can be set as editable, and it can be copied, cut, or dragged in another region of the screen.

    -
    -elm_photo_editable_set(photo, EINA_TRUE);
    - -

    The photo can also be completely visible on the screen.

    - -
    -elm_photo_fill_inside_set(photo, EINA_TRUE);
    - -

    Using Photo Callbacks

    - -

    The following callbacks are registered on the photo component.

    -
      -
    • clicked: The user has clicked the photo.
    • -
    • drag,start: The user starts dragging the inner image out of the photo's frame.
    • -
    • drag,end: The user drops the dragged image.
    • -
    - -

    event_info is always NULL.

    - - -

    Photocam

    - -

    Figure: Photocam hierarchy

    -

    Photocam hierarchy

    - -

    The photocam component displays high resolution photos taken from digital cameras. It provides a way to zoom in the photo, load it fast, and fit it nicely on the screen. It is optimized for .jpeg images format and has a low memory footprint.

    - -

    This UI component implements the scroller interface, so all the functions concerning the scroller can be used with the photocam component.

    - -

    Adding a Photocam Component

    - -

    The following example shows how to create a photocam component and set an image file on it.

    - -
    -Evas_Object *photocam;
    -photocam = elm_photocam_add(win);
    -elm_photocam_file_set(photocam, "/tmp/photo.jpeg");
    -
    - -

    Using Photocam Zoom

    - -

    You can choose between two automatic zoom modes and a manual zoom mode. In the following example the zoom mode is set to manual and a double zoom is requested.

    -
    -elm_photocam_zoom_mode_set(photocam, ELM_PHOTOCAM_ZOOM_MODE_MANUAL);
    -elm_photocam_zoom_set(photocam, 2.0);
    -
    - -

    The zoom mode can be set to ELM_PHOTOCAM_ZOOM_MODE_AUTO_FIT. In this case, the photo fits exactly inside the scroll frame with no pixels outside this region. The zoom mode can also be set to ELM_PHOTOCAM_ZOOM_MODE_AUTO_FILL to fill all the pixels of the photocam component.

    - -

    Multi-touch zooming is activated by enabling gestures.

    -
    -elm_photocam_gesture_enabled_set(photocam, EINA_TRUE);
    -
    - -

    You can zoom in a specific region. The following example shows how to zoom in the region starting at the coordinates (200x200), with a width of 400px and a height of 300px.

    - -
    -elm_photocam_image_region_bring_in(photocam, 200, 200, 400, 300);
    -
    - -

    Using Photocam Callbacks

    - -

    The photocam component emits the following signals:

    -
      -
    • clicked: The user has clicked the photo without dragging around.
    • -
    • press: The user has pressed down on the photo.
    • -
    • longpressed: The user has pressed down on the photo for a long time without dragging around.
    • -
    • clicked,double: The user has double-clicked the photo.
    • -
    • load: The photo load begins.
    • -
    • loaded: The image file load is complete for the first view (a low resolution blurry version).
    • -
    • load,detail: A photo detailed data load begins.
    • -
    • loaded,detail: The image file load is complete for the detailed image data (full resolution is needed).
    • -
    • zoom,start: Zoom animation starts.
    • -
    • zoom,stop: Zoom animation stops.
    • -
    • zoom,change: The zoom is changed when using an auto zoom mode.
    • -
    • scroll: The content is scrolled.
    • -
    • scroll,anim,start: Scrolling animation starts.
    • -
    • scroll,anim,stop: Scrolling animation stops.
    • -
    • scroll,drag,start: Dragging the content around starts.
    • -
    • scroll,drag,stop: Dragging the content around stops.
    • -
    - -

    For all these signals, event_info is NULL.

    - -

    The following example shows how to register a callback on the loaded signal.

    - -
    -void message_port_cb(int local_port_id, const char *remote_app_id, bundle *message)
    -{
    -   evas_object_smart_callback_add(photocam, "loaded", loaded_cb, data);
    -}
    -
    -// Callback function for the "loaded" signal
    -// The photocam has loaded the photo file in a low resolution
    - 
    -void loaded_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   dlog_print(DLOG_INFO, LOG_TAG, "The photo has been loaded\n");
    -}
    -
    - -

    Plug

    - -

    Figure: Plug hierarchy

    -

    Plug hierarchy

    - -

    The plug component shows an Evas_Object created by an other process. It can be used anywhere the same way as any other elementary UI component.

    - -

    Adding a Plug Component

    - -

    The following example shows how to create a plug.

    - -
    -Evas_Object *plug, *parent;
    -plug = elm_plug_add(parent);
    -
    - -

    Using the Plug

    - -

    The socket image provides the service where to connect the plug object with the elm_plug_connect() function. In this process, use the service name and number set by the socket you want to connect to.

    - -

    As an example, connect to a service named plug_test on the number 0.

    - -
    -elm_plug_connect(plug, "plug_test", 0, EINA_FALSE);
    -
    - -

    The Evas_Object corresponding to the distant image is retrieved with the elm_plug_image_object_get() function.

    - -
    -Evas_Object *plug_img = elm_plug_image_object_get(plug);
    -
    - - - - - - - - - - -
    Note
    The socket to connect to must be started with the elm_win_socket_listen() function in the other process on the remote window object (it is called remote_win here).
    - -
    -// Create a remote window in the other process 
    -Elm_Win *remote_win = elm_win_add(NULL, "Window Socket",
    -                                  ELM_WIN_SOCKET_IMAGE);
    -// Create a socket named "plug_test" and listen to it
    -elm_win_socket_listen(remote_win, "plug_test", 0, EINA_FALSE);
    -
    - - - -

    Figure: Popup component

    -

    Popup component

    - -

    Figure: Popup hierarchy

    -

    Popup hierarchy

    - - -

    The popup component shows a popup area that can contain:

    -
      -
    • a title area (optional)
    • -
    • a content area
    • -
    • an action area (optional)
    • -
    - -

    The optional title area can contain an icon and text, the action area can contain up to three buttons.

    - -

    Adding a Popup Component

    - -

    The following example shows how to create a popup component.

    -
    -Evas_Object *popup, *parent;
    -
    -// Create a popup 
    -popup = elm_popup_add(parent);
    -
    - -

    Using Popup Styles

    - -

    The following item styles are available for the popup:

    - -
      -
    • popup
    • -
    • toast
    • -
    - -

    The following example sets the style of the popup to toast.

    - -
    elm_object_style_set(popup, "toast");
    - -

    Setting the Popup Areas

    - -

    Configure the title area. Set the icon object using the part name title,icon. Set the title text to Test popup using the partname title,text.

    - -
    -Evas_Object *icon;
    -
    -// Add an icon to the title area 
    -elm_object_part_content_set(popup, "title,icon", icon);
    -
    -// Set the title text 
    -elm_object_part_text_set(popup, "title,text", "Test popup");
    -
    - -

    Set the content of the popup. The content can be simple text.

    - -
    -elm_object_part_text_set(popup, "default", "Test popup");
    -
    - -

    The content can also be an Evas object.

    - -
    -Evas_Object *content;
    -
    -elm_object_content_set(popup, content);
    -
    - -

    Set the buttons of the action area by creating an OK button, a Cancel button, and a Help button.

    - -
    -Evas_Object *button1, *button2, *button3;
    -
    -// Create the 3 buttons 
    -
    -button1 = elm_button_add(popup);
    -elm_object_text_set(button1, "OK");
    -
    -button2 = elm_button_add(popup);
    -elm_object_text_set(button2, "Cancel");
    -
    -button3 = elm_button_add(popup);
    -elm_object_text_set(button3, "Help");
    -
    -// Set the buttons to the action area 
    -elm_object_part_content_set(popup, "button1", button1);
    -elm_object_part_content_set(popup, "button2", button2);
    -elm_object_part_content_set(popup, "button3", button3);
    -
    - -

    Using Popup Callbacks

    -

    The popup emits the following signals:

    -
      -
    • timeout: The popup is closed as a result of timeout.
    • -
    • block,clicked: The user clicks on the Blocked Event area.
    • -
    - -

    elm_popup_timeout_set() is used to hide the popup after a certain time. In this example, the timeout is set to five seconds.

    - -
    -elm_popup_timeout_set(popup, 5.0);
    -
    - -

    When the timeout expires, the timeout signal is sent to the user.

    - -
    -{
    -   evas_object_smart_callback_add(popup, "timeout", _timeout_cb, data);
    -}
    -
    -static void
    -_timeout_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   dlog_print(DLOG_INFO, LOG_TAG, "Timeout \n");
    -}
    -
    - -

    The visible region of the popup is surrounded by a translucent region called Blocked Event area. By clicking on this area, the signal block,clicked is sent to the application.

    - - -

    Progressbar

    - -

    Figure: Progressbar component

    -

    Progressbar component

    - -

    Figure: Progressbar hierarchy

    -

    Progressbar hierarchy

    - - -

    Adding a Progressbar Component

    - -

    This UI component is used to display the progress status of a given job. It inherits from the layout component, so all function concerning the layout component is used on the progressbar component.

    -

    The following example shows how to create a progressbar component.

    - -
    -Evas_Object *pb = elm_progressbar_add(win);
    -
    - -

    Using the Progressbar Styles

    - -

    The progressbar has several styles:

    -
      -
    • default
    • -
    • pending_list
    • -
    • process_large
    • -
    • process_medium
    • -
    • process_small
    • -
    - -

    Set the style of the progressbar to pending_list.

    - -
    elm_object_style_set(pb, "pending_list");
    - -

    Using the Progressbar

    - -

    By default, the progressbar does not show a label or an icon, and the unit label is set to %.0f %%.

    - -

    The following example shows how to set a label. In this example it is named Test label.

    - -
    -elm_object_text_set(pb, "Test label");
    -
    - -

    An icon is set with elm_object_part_content_set() using the partname icon.

    -
    -elm_object_part_content_set(pb, "icon", icon_object);
    -
    - -

    The unit label format string can be modified using a printf style format. Set it to be a float number with two decimals.

    -
    -elm_progressbar_unit_format_set(pb, "%1.2f%%");
    -
    - -

    Configuring the Progressbar

    - -

    The progressbar pulse mode is activated to make the progressbar loop infinitely between the start and end position.

    -
    -elm_progressbar_pulse_set(pb, EINA_TRUE);
    -elm_progressbar_pulse(pb, EINA_TRUE);
    -
    - -

    The progressbar can be inverted. In that mode, the values are inverted so that the high values are on the left and the low values on the right.

    -
    -elm_progressbar_inverted_set(pb, EINA_TRUE);
    -
    - -

    The progressbar emits the changed signal when the progress value changes. The value is changed with the elm_progressbar_value_set() function. Here the pb progress value is set to 20%.

    -
    -elm_progressbar_value_set(pb, 0.2);
    -
    - -

    The current value can be read.

    -
    -double value = elm_progressbar_value_get(pb);
    -
    - -

    You can set the orientation of the progressbar to vertical instead of the default horizontal orientation.

    -
    -elm_progressbar_horizontal_set(pb, EINA_FALSE);
    -
    - -

    Using the Progressbar Callbacks

    - -

    The changed signal is the only signal specifically emitted by the progressbar component.

    - -

    The following example shows how to register a callback on this signal.

    - -
    -{
    -   evas_object_smart_callback_add(pb, "changed", changed_cb, data);
    -}
    -
    -// Callback function for the "changed" signal
    -// This callback is called when the progressbar value changes
    -void changed_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   dlog_print(DLOG_INFO, LOG_TAG, "The value has changed\n");
    -}
    -
    - - -

    Radio

    - -

    Figure: Radio component

    -

    Radio component

    - -

    Figure: Radio hierarchy

    -

    Radio hierarchy

    - -

    This UI component displays one or more options, but the user can only select one of them. It is composed of an indicator (selected or unselected), an optional icon and an optional label. Even though it is usually grouped with two or more other radio objects, it can also be used alone.

    -

    The radio component inherits from the layout component. All the layout functions can be used with radio objects.

    - -

    Adding a Radio Component

    - -

    Create a radio component and set a label to it.

    -
    -Evas_Object *radio, *parent;
    -
    -// Create a radio
    -radio = elm_radio_add(parent);
    -
    -// Set a label to it
    -elm_object_text_set(radio, "Radio component");
    -
    - -

    Set an icon to the radio object.

    -
    -// Create a Home icon 
    -Evas_Object *icon;
    -
    -icon = elm_icon_add(parent);
    -elm_icon_standard_set(icon, "home");
    -
    -// Set it to the radio component 
    -elm_object_part_content_set(radio, "icon", icon);
    -
    - -

    Changing the Radio Value

    - -

    The user can select one of a set of values with the radio component. Each radio object from a group of radio objects represents an integer value. Here the value 1 is set to the new radio object.

    -
    -elm_radio_state_value_set(radio, 1);
    -
    - -

    Managing the Radio Groups

    - -

    The following example shows how to create a group of radio objects with at least two radio components.

    - -
    -// Create another radio object 
    -Evas_Object *radio2 = elm_radio_add(parent);
    -elm_radio_state_value_set(radio2, 2);
    -
    -// Create a group composed of radio and radio2
    -Evas_Object *group = radio;
    -elm_radio_group_add(radio2, group);
    -
    - -

    Now that a group composed of two radio objects has been created, you can choose which one is selected. In this example radio2 is selected.

    - -
    -elm_radio_value_set(group, 2);
    -
    - -

    You can use elm_radio_value_get() to see the currently selected radio of the group.

    - -

    Using the Radio Callbacks

    - -

    When the state of a radio is modified in a group of radio objects, the changed signal is emitted.

    -

    The following example shows how to register a callback on this signal.

    - -
    -{
    -   evas_object_smart_callback_add(radio, "changed", changed_cb, data);
    -}
    -
    -// Callback function for the "changed" signal
    -// This callback is called when the radio value changes
    -void changed_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   dlog_print(DLOG_INFO, LOG_TAG, "The value has changed\n");
    -}
    -
    - - -

    Segmentcontrol

    - -

    Figure: Segmentcontrol with text

    -

    Segmentcontrol with text

    - -

    Figure: Segmentcontrol with icons

    -

    Segmentcontrol with icons

    - -

    Figure: Segmentcontrol hierarchy

    -

    Segmentcontrol hierarchy

    - -

    This UI component consists of several segment items. A segment item is similar to a discrete two state button. Any time, only one segment item can be selected. A segment item is composed of a label (text) and an icon.

    -

    This UI component inherits from the layout component, so all the layout components API can be used on segmentcontrol objects.

    - -

    Adding a Segmentcontrol Component

    - -

    The following example shows how to add a segmentcontrol component.

    - -
    -Evas_Object *segcontrol, *parent;
    -
    -segcontrol = elm_segment_control_add(parent);
    -
    - -

    Adding Items

    - -

    You can add items to the UI component. In the following example four items containing only text labels (no icons) are added.

    -
    -Elm_Object_Item *it;
    -
    -elm_segment_control_item_add(segcontrol, NULL, "item1");
    -elm_segment_control_item_add(segcontrol, NULL, "item2");
    -elm_segment_control_item_add(segcontrol, NULL, "item3");
    -it = elm_segment_control_item_add(segcontrol, NULL, "item4");
    -
    - -

    You can also:

    -
      -
    • Insert an item at a specific position starting at 0. -
      -elm_segment_control_item_insert_at(segcontrol, NULL, "item7", 2);
      -
    • - -
    • Delete an item. -
      -elm_segment_control_item_del_at(segcontrol, 2);
      -
    • - -
    • Set the selected state of an item manually. -
      -elm_segment_control_item_selected_set(it, EINA_TRUE);
      -
    • -
    • Disable the whole segment control. -
      elm_object_disabled_set(segcontrol, EINA_TRUE);
    • -
    - -

    Using the Segmentcontrol Callbacks

    - -

    This is how to register a callback on the changedsignal. It is called when the user clicks on a segment item which is not previously selected. The event_info parameter is the segment item pointer.

    -
    -{
    -   evas_object_smart_callback_add(segcontrol, "changed", changed_cb, data);
    -}
    -
    -// Callback function for the "changed" signal
    -// This callback is called when the segcontrol selected item changes
    -void changed_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   Elm_Segment_Item *it = event_info;
    -
    -   dlog_print(DLOG_INFO, LOG_TAG, "The selected segment item has changed\n");
    -}
    -
    - - -

    Slider

    - -

    Figure: Slider component

    -

    Slider component

    - -

    Figure: Slider hierarchy

    -

    Slider hierarchy

    - -

    The slider component is a draggable bar that is used to select a value within a certain range.

    - -

    Adding a Slider Component

    - -

    The following example shows how to create a slider object.

    -
    -Evas_Object *slider, *parent;
    -
    -slider = elm_slider_add(parent);
    -
    - -

    Using the Slider Styles

    - -

    A slider has the following styles:

    -
      -
    • default
    • -
    • center_point
    • -
    - -

    The following example sets the style to center_point.

    -
    -elm_object_style_set(slider, "center_point");
    -
    - -

    With this style, the slider 0 point is in the middle of the UI component.

    - -

    Configuring the Slider

    - -

    The orientation is set with the elm_slider_horizontal_set() function, and it is inverted the same way as the progressbar component. In the following example it is set to vertical and inverted.

    -
    -elm_slider_horizontal_set(slider, EINA_FALSE);
    -elm_slider_inverted_set(slider, EINA_TRUE);
    -
    - -

    The slider can contain icons (icon and end partnames), a label, a unit label, and an indicator label.

    -
    -Evas_Object *icon1, *icon2;
    -
    -// Set the icons 
    -elm_object_part_content_set(slider, "icon", icon1);
    -elm_object_part_content_set(slider, "end", icon2);
    -
    -// Set the label 
    -elm_object_part_text_set(slider, "default", "slider label");
    -
    -// Set the unit format 
    -elm_slider_unit_format_set(slider, "%1.2f meters");
    -
    - -

    Before using the slider, its minimum and maximum values are set with elm_slider_min_max_set(). The current value is set with (elm_slider_value_set()). The following example sets the minimum value to 0, the maximum value to 100, and the current value to 50.

    -
    -elm_slider_min_max_set(slider, 0.0, 100.0);
    -elm_slider_value_set(slider, 50.0);
    -
    - -

    The span of the slider represents its length horizontally or vertically. It is set with elm_slider_span_size_set() and is scaled by the object or applications scaling factor.

    -

    You can retrieve the current value of the slider anytime.

    -
    -double value = elm_slider_value_get(slider);
    -
    - -

    By default, the slider indicator becomes bigger when the user drags it. This can be disabled if you want the slider indicator to keep its default size. The following example sets the state of the indicator enlargement and then inverts the behavior.

    -
    -// Get the current state of the indicator 
    -Eina_Bool enlarge = elm_slider_indicator_show_get(slider);
    -
    -// Invert the behavior 
    -elm_slider_indicator_show_set(slider, !enlarge);
    -
    - -

    Using the Slider Callbacks

    - -

    This UI component emits the following signals:

    -
      -
    • changed: The user changes the slider value.
    • -
    • slider,drag,start: Dragging the slider indicator around starts.
    • -
    • slider,drag,stop: Dragging the slider indicator around stops.
    • -
    • delay,changed: A short time after the user changes the value. This is called only when the user stops dragging for a very short period or when releases the finger or mouse, so that it avoids possibly expensive reactions to the value change.
    • -
    - -

    For all these signals, event_info is NULL.

    -

    The following example shows how to register a callback on the changed signal.

    -
    -{
    -   evas_object_smart_callback_add(slider, "changed", changed_cb, data);
    -}
    -
    -// Callback function for the "changed" signal
    -// This callback is called when the slider value changes
    -void changed_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   dlog_print(DLOG_INFO, LOG_TAG, "The slider has changed\n");
    -}
    -
    - -

    Spinner

    - - -

    Figure: Spinner component

    -

    Spinner component

    - -

    Figure: Spinner hierarchy

    -

    Spinner hierarchy

    - -

    The spinner component increases or decreases a numeric value with the arrow buttons.

    - -

    This UI component inherits from the layout component, so all functions concerning the layout component are used on the spinner component.

    - -

    Adding a Spinner Component

    -

    The following example shows how to create a spinner object.

    - -
    -Evas_Object *spin, *parent;
    -
    -spin = elm_spinner_add(parent);
    -
    - -

    Configuring the Spinner

    - -

    The label format is set to a different value:

    -
    -elm_spinner_label_format_set(spin, "%1.2f meters");
    -
    - -

    You can determine the result of clicking the arrow buttons. In this example, a click on an arrow increases or decreases with 2.0 units:

    -
    -elm_spinner_step_set(spin, 2.0);
    -
    -

    The wrapping mode is activated. In this mode, the spinner wraps when it reaches its minimum or maximum value.

    -
    -elm_spinner_wrap_set(spin, EINA_TRUE);
    -
    - -

    You can set the minimum and maximum values of the spinner.

    -
    -elm_spinner_min_max_set(spin, -25.0, 100.0);
    -
    - -

    The spinner object can be set vertical, and the change interval when the user presses the arrows long can be modified so that it changes faster.

    -
    -elm_object_style_set(spin, "vertical");
    -elm_spinner_interval_set(spin, 0.1);
    -
    - -

    If the user has to select between text values instead of numerical values, it is possible to add our own text labels. Here spin2 object shows three numbers written in text characters.

    -
    Evas_Object *spin2 = elm_spinner_add(parent);
    -elm_spinner_min_max_set(spin2, 1, 3);
    -elm_spinner_special_value_add(spin2, 1, "One");
    -elm_spinner_special_value_add(spin2, 2, "Two");
    -elm_spinner_special_value_add(spin2, 3, "Three");
    -
    - -

    Using the Spinner Callbacks

    - -

    This UI component emits the following signals:

    -
      -
    • changed: The spinner value changes.
    • -
    • delay,changed: A short time after the user changes the value. This is called only when the user stops dragging for a very short period or releases the finger or mouse, so that it avoids possibly expensive reactions to the value change.
    • -
    - -

    The following example shows how to register a callback on the delay,changed signal.

    - -
    -{
    -   evas_object_smart_callback_add(spin, "delay,changed", delay_changed_cb, data);
    -}
    -
    -// Callback function for the "delay,changed" signal
    -// This callback is called a short time after the spinner value changes
    -void delay_changed_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   dlog_print(DLOG_INFO, LOG_TAG, "The spinner value has changed\n");
    -}
    -
    - -

    Toolbar

    - -

    Figure: Toolbar component

    -

    toolbar component

    - -

    Figure: Toolbar hierarchy

    -

    Toolbar hierarchy

    - - -

    This UI component is a scrollable list of items and shows a menu when an item is selected. Only one item can be selected at a time.

    - -

    Adding and Configuring a Toolbar Component

    - -

    Use the following function to create a toolbar.

    -
    -Evas_Object *toolbar, *parent;
    -
    -toolbar = elm_toolbar_add(parent);
    -
    - -

    Using the Toolbar Styles

    -

    The toolbar has the following styles:

    -
      -
    • default
    • -
    • tabbar
    • -
    • tabbar_with_title
    • -
    • navigationbar
    • -
    -

    The following example sets the style to navigationbar.

    -
    -elm_object_style_set(toolbar, "navigationbar");
    -
    - -

    Configuring the Toolbar

    -

    The toolbar displays its items in one of the following options.

    -
      -
    • ELM_TOOLBAR_SHRINK_NONE: The toolbar sets a minimum size to its items so that all of them fit without scrolling.
    • -
    • ELM_TOOLBAR_SHRINK_HIDE: The toolbar does not scroll or show the items that do not fit in.
    • -
    • ELM_TOOLBAR_SHRINK_SCROLL: The toolbar scrolls to show the items that do not fit in.
    • -
    • ELM_TOOLBAR_SHRINK_MENU: The toolbar creates a button to popup hidden items.
    • -
    - -

    Here the toolbar is set to ELM_TOOLBAR_SHRINK_NONE.

    -
    -elm_toolbar_shrink_mode_set(toolbar, ELM_TOOLBAR_SHRINK_NONE);
    -
    -

    By default, the toolbar displays items homogeneously. Items with long labels occupy a lot of space. To avoid that, you can disable the homogeneous mode.

    -
    -elm_toolbar_homogeneous_set(toolbar, EINA_FALSE);
    -
    - -

    Adding Items to the Toolbar

    -

    The following example shows how to add two items and choose the associated icon, label, and function to call when the item is clicked.

    -
    -{
    -   Elm_Object_Item *home_it, *help_it;
    -
    -   home_it = elm_toolbar_item_append(toolbar, "home", "Home",
    -                                    _home_item_pressed_cb, NULL);
    -   help_it = elm_toolbar_item_append(toolbar, "help", "Help",
    -                                    _help_item_pressed_cb, NULL);
    -}
    -
    -static void
    -_home_item_pressed_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   dlog_print(DLOG_INFO, LOG_TAG, "Home item clicked \n");
    -}
    -
    -static void
    -_help_item_pressed_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   dlog_print(DLOG_INFO, LOG_TAG, "Help item clicked \n");
    -}
    -
    - -

    An item can be disabled. This is how to disable the help item. The disabled item does not receive input and, if the theme supports it, is themed differently (usually greyed out) from its normal state.

    -
    -elm_object_item_disabled_set(help_it, EINA_TRUE);
    -
    - -

    Adding Items with States

    -

    Items have two or more states. Each state has its own icon, label, and function to call when an item is clicked. The following example shows how to create two states to the help item with the same icon but two different labels.

    -
    -elm_toolbar_item_state_add(help_it, "help", "Help state 1",
    -                           _help_item_pressed_cb, NULL);
    -elm_toolbar_item_state_add(help_it, "help", "Help state 2",
    -                           _help_item_pressed_cb, NULL);
    -
    -

    It is possible to cycle through the states of the help item by using the following code.

    -
    -elm_toolbar_item_state_set(help_it, elm_toolbar_item_state_next(help_it));
    -
    - -

    Using the Toolbar Callbacks

    -

    This UI component emits the following signals:

    -
      -
    • clicked: The user clicks on a toolbar item, which is selected. event_info is an object of the type Elm_Toolbar_Item.
    • -
    • clicked,double: The user double-clicks on a toolbar item. event_info is an object of the type Elm_Toolbar_Item.
    • -
    • longpressed: The toolbar is pressed for a certain amount of time. event_info is an object of the type Elm_Toolbar_Item.
    • -
    • language,changed: The program language changes.
    • -
    • item,focused: The item is highlighted. event_info is an object of the type Elm_Toolbar_Item.
    • -
    • item,unfocused: The highlight is removed from the item. event_info is an object of the type Elm_Toolbar_Item.
    • -
    • scroll: The toolbar scrolls. event_info is NULL.
    • -
    • scroll,anim,start: The toolbar scrolling animation starts. event_info is NULL.
    • -
    • scroll,anim,stop: The toolbar scrolling animation stops. event_info is NULL.
    • -
    • scroll,drag,start: The user starts dragging the toolbar. event_info is NULL.
    • -
    • scroll,drag,stop: The user stops dragging the toolbar. event_info is NULL.
    • -
    -

    The following example shows how to register a callback on the clicked signal.

    -
    -{
    -   evas_object_smart_callback_add(toolbar, "clicked", clicked_cb, data);
    -}
    -
    -// Callback function for the "clicked" signal
    -// This callback is called when a toolbar item is clicked
    -void clicked_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   Elm_Toolbar_Item * item = event_info;
    -
    -   dlog_print(DLOG_INFO, LOG_TAG, "Item clicked\n");
    -}
    -
    - -

    Tooltip

    - -

    The tooltip component is a smart object that shows a content in a frame when mouse hovers a parent object. The UI component provides tips or information about the parent object.

    - -

    Adding a Tooltip

    -

    The tooltip component cannot be created with the elm_tooltip_add() function. This component is already contained in a parent component when it is created. You can only activate or disable it.

    - -

    Activating the Tooltip

    -

    To activate the tooltip on a parent object, you can set a tooltip text to the parent object.

    -
    -Evas_Object *parent;
    -
    -elm_object_tooltip_text_set(parent, "The tooltip text";
    -
    -

    You can also set a content to the parent object.

    -
    -{
    -   elm_object_tooltip_content_cb_set(parent, tooltip_content_cb, NULL, tooltip_content_del_cb);
    -}
    -
    -Evas_Object*
    -tooltip_content_cb(void*data, Evas_Object *obj, Evas_Object *tooltip)
    -{
    -   // Create the tooltip content 
    -}
    -
    -void tooltip_content_del_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   // Destroy the tooltip content 
    -}
    -
    - -

    When passing content to the tooltip, the tooltip_content_cb function is called each time the tooltip is showed. The role of this function is to create the content to set in the tooltip. It returns a pointer to an Evas_Object.

    -

    When the tooltip disappears, the tooltip_content_del_cb function is called. This function is in charge of deleting the previously allocated Evas_Object.

    -

    Once set, the tooltip can be manually hidden or shown.

    - -
    -elm_object_tooltip_hide(parent);
    -elm_object_tooltip_show(parent);
    -
    - -

    The tooltip can be removed from the parent object when it is not needed.

    -
    -elm_object_tooltip_unset(parent);
    -
    - - - - - - - - - - -
    Note
    When content is set into the tooltip object, unsetting it calls the callback provided as del_cb to notify that the tooltip cannot be used any longer.
    - -

    A tooltip object is not a UI component, so it does not emit signals. There are no registered callbacks for it.

    - - -

    Win

    - -

    Figure: Win hierarchy

    -

    Win hierarchy

    - - -

    The window component is the root UI component that is often used in an application. It allows the developer create content in it, and it is handled by the window manager.

    -

    The window component is created with the elm_win_add() or elm_win_util_standard_add() function. The content can be added in the window with elm_win_resize_object_add() so that a window resize also resizes the content inside.

    - -

    Adding a Window Component

    - -

    Create a new window and change the title.

    -
    -Evas_Object *window;
    -
    -// Create a window 
    -window = elm_win_add(NULL, "main", ELM_WIN_BASIC);
    -
    -// Change the window title 
    -elm_win_title_set(window, "Example Window");
    -
    - -

    The first element of elm_win_add() is the parent window. For example, for a dialog you want to have the main window as the parent. Here, it is NULL, meaning there is no parent. main is the name of the window used by the window manager for identifying the window uniquely amongst all the windows within this application (and all instances of the application). The type is a basic window (the final parameter).

    - -

    Create a new window with a title and a background. This API is a shortcut of the previous one. It also creates a standard background to the window with elm_bg_add(). The window created is of the type ELM_WIN_BASIC.

    - -
    -Evas_Object *window;
    -
    -// Create a standard window 
    -window = elm_win_util_standard_add("main", "Example Window");
    -
    - -

    Closing a Window

    -

    When the user closes the window outside of the program control, a delete,request signal is emitted to indicate that this event occurred. The developer can take any action, for example, destroy the window object.

    -

    When the autodel parameter is set, the window is automatically destroyed after the signal is emitted. If autodel is EINA_FALSE, the window is not destroyed and the program does so when required. The default is EINA_FALSE, where the window is not destroyed automatically.

    -

    The autodel is set using the following call:

    -
    -elm_win_autodel_set(window, EINA_TRUE);
    -
    - -

    To close the window, use the evas_object_del() function. The window is destroyed and the signal delete,request is sent.

    - -

    Using the Window Callbacks

    -

    The window component emits the following signals:

    -
      -
    • focus,in: The window received focus.
    • -
    • focus,out: The window lost focus.
    • -
    • moved: The window that holds the canvas is moved.
    • -
    • withdrawn: The window is managed normally but is removed from the view.
    • -
    • iconified: The window is minimized (for example, into an icon or a taskbar).
    • -
    • normal: The window is in the normal state (not withdrawn or iconified).
    • -
    • stick: The window shows on all desktops.
    • -
    • unstick: The window shows only on one desktop.
    • -
    • fullscreen: The window is fullscreen.
    • -
    • unfullscreen: The window stops being fullscreen.
    • -
    • maximized: The window is maximized.
    • -
    • unmaximized: The window is diminished.
    • -
    • wm,rotation,changed: The rotation of the window is changed by the Windows Manager.
    • -
    • ioerr: A low-level I/O error occurred in the display system.
    • -
    -

    With all these signals, event_info is NULL.

    -

    The following example registers a callback function called on the fullscreen signal.

    -
    -{
    -   evas_object_smart_callback_add(window, "fullscreen", fullscreen_cb, data);
    -}
    -
    -// Callback function for the "fullscreen" signal
    -// This callback is called when the window becomes fullscreen
    -void fullscreen_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   dlog_print(DLOG_INFO, LOG_TAG, "Window fullscreen\n");
    -}
    -
    - - - - - -
    - -Go to top - - - - - - - - diff --git a/org.tizen.guides/html/native/ui/components_wn.htm b/org.tizen.guides/html/native/ui/components_wn.htm deleted file mode 100644 index b7c8c91..0000000 --- a/org.tizen.guides/html/native/ui/components_wn.htm +++ /dev/null @@ -1,2473 +0,0 @@ - - - - - - - - - - - - - - Components - - - - - - -
    -

    Components

    - - - - - - - - - - -
    Note
    This feature is supported in wearable applications only.
    - -

    Background

    - -

    Figure: Red color background

    -

    Red color background

    - -

    Figure: Background hierarchy

    -

    Background hierarchy

    - -

    The background component can be used to set a solid background decoration to a window or to a container object. It works like an image, but has some background specific properties, for example it can be set to a tiled, centered, scaled, or stretched mode. There are no specific signals relative to background object.

    - -

    Adding a Background Component

    - -

    A background is created with the elm_bg_add() function.

    - -
    -Evas_Object *bg, *parent;
    -
    -// Create a background
    -bg = elm_bg_add(parent);
    -
    - -

    Changing the Color of the Background

    - -

    You can set the color of the background with the elm_bg_color_set() function. The following example sets the background color to red.

    - -
    -Evas_Object *bg;
    -
    -// Use red color for background
    -elm_bg_color_set(bg, 0xFF, 0x00, 0x00);
    -
    - -

    Changing the Image of the Background

    - -

    It is also possible to set an image or an Edje group as a background using the elm_bg_file_set() function. The display mode of the image in the background can be chosen with elm_bg_option_set(), where the following modes are available:

    - -
      -
    • ELM_BG_OPTION_CENTER: center the background image.
    • -
    • ELM_BG_OPTION_SCALE: scale the background image, retaining aspect ratio.
    • -
    • ELM_BG_OPTION_STRETCH: stretch the background image to fill the UI component's area.
    • -
    • ELM_BG_OPTION_TILE: tile the background image at its original size.
    • -
    - -
    -Evas_Object *bg;
    -
    -// Set a file on the disk as a background image
    -elm_bg_file_set(bg, "/path/to/the/image", NULL);
    -// Set an Edje group as a background image
    -elm_bg_file_set(bg, "/path/to/the/edje", "edje_group");
    -elm_bg_option_set(bg, ELM_BG_OPTION_STRETCH)
    -
    - -

    Using Overlay

    - -

    An overlay can be set using the overlay part name.

    - -
    -elm_object_part_content_set(bg, "overlay", over);
    -
    - -

    Here, the overlay is an Edje object that is displayed on top of the current background object.

    - - -

    Button

    - -

    Figure: Button component

    -

    Button component

    - -

    Figure: Button hierarchy

    -

    Button hierarchy

    - -

    The Elementary button component is a simple push button. It is composed of a label icon and an icon object and has an autorepeat feature.

    - -

    Adding a Button Component

    - -

    Create a button.

    -
    -Evas_Object *button, *parent;
    -
    -// Create a button
    -button = elm_button_add(parent);
    - -

    Adding an Icon Inside a Button

    - -

    The icon can be updated with elm_object_part_content_set() function with the icon part name.

    - -
    -Evas_Object *ic;
    -ic = elm_icon_add(button);
    -elm_image_file_set(ic, "icon.png", NULL);
    -elm_object_part_content_set(button, "icon", ic);
    - -

    Adding Text Inside a Button

    - -

    The label can be modified using the elm_object_text_set() function.

    - -
    -elm_object_text_set(button, "Click me!");
    -
    - -

    Using Button Styles

    - -

    Various styles can be used on the button. Tizen supports the following styles for wearable core controls:

    -
      -
    • default
    • -
    • green
    • -
    • orange
    • -
    • red
    • -
    • nextdepth
    • -
    -

    Tizen supports the following styles for Gear O:

    -
      -
    • default
    • -
    • bottom
    • -
    - -

    To change the style of the button, call the elm_object_style_set() function on the button object.

    - -
    -// Example for wearable core control
    -elm_object_style_set(button, "nextdepth");
    -
    -// Example for Gear O
    -elm_object_style_set(button, "bottom");
    -
    - -

    Using the Button Callbacks

    - -

    The button emits the following signals:

    - -
      -
    • clicked: The user clicked the button (press/release).
    • -
    • repeated: The user pressed the button without releasing it.
    • -
    • pressed: The user pressed the button.
    • -
    • unpressed: The user released the button after pressing it.
    • -
    - -

    For all these signals the event_info parameter returned in the callback is NULL.

    - -

    This is an example to register and define a callback function called by the clicked signal.

    -
    -{
    -   evas_object_smart_callback_add(button, "clicked", clicked_cb, data);
    -}
    -// Callback function for the "clicked" signal
    -// This callback is called when the button is clicked by the user
    -void clicked_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   dlog_print(DLOG_INFO, LOG_TAG, "Button clicked\n");
    -}
    -
    - -

    Using the Autorepeat Feature

    - -

    The autorepeat feature is enabled by default. It consists of calling the repeated signal when the user keeps the button pressed. This feature can be disabled with the elm_button_autorepeat_set() function. The autorepeat is configured with the following functions:

    -
      -
    • elm_button_autorepeat_initial_timeout_set(): to set the initial timeout before the autorepeat event is generated
    • -
    • elm_button_autorepeat_gap_timeout_set(): to set the interval between two autorepeat events
    • -
    - -

    Disable the autorepeat feature.

    -
    -elm_button_autorepeat_set(button, EINA_FALSE);
    -
    - -

    Enable the autorepeat feature.

    -
    -elm_button_autorepeat_set(button, EINA_TRUE);
    -
    - -

    Set the initial timeout to five seconds.

    -
    -elm_button_autorepeat_initial_timeout_set(button, 5.0);
    -
    - -

    Set the gap between two signals to 0.5 seconds.

    -
    -elm_button_autorepeat_gap_timeout_set(button, 0.5);
    -
    - - -

    Check

    - -

    Figure: Check component

    -

    Check component

    - -

    Figure: Check hierarchy

    -

    Check hierarchy

    - -

    The check component is similar to the radio component, except that it does not work as a group. It toggles the value of a boolean between true and false.

    - -

    This UI component inherits from the layout component. All layout functions can be used on the check component.

    - -

    Adding a Check Component

    - -

    The following example shows how to create a check component.

    -
    -Evas_Object *check, *parent;
    -check = elm_check_add(parent);
    -
    - -

    Modifying the Check Styles

    - -

    The check component style can be set with the elm_object_style_set() function.

    -

    The following styles are available for wearable core controls:

    -
      -
    • default
    • -
    • on and off
    • -
    -

    The following styles are available for Gear O:

    -
      -
    • default
    • -
    • small
    • -
    • on and off
    • -
    - -

    The following example sets the on and off style on our check object.

    -
    -elm_object_style_set(check, "on and off");
    -
    - -

    To get the current style, use the elm_object_style_get() function.

    -
    -char *style = elm_object_style_get(check);
    -
    - -

    Using the Check Component

    - -

    After having created a check object, it is possible to set its boolean value to EINA_TRUE.

    -
    -elm_check_state_set(check, EINA_TRUE);
    -
    - -

    You can also retrieve the current value of the check object.

    -
    -Eina_Bool value = elm_check_state_get(check);
    -
    - -

    As with a radio object, an icon can be set for the wearable core control.

    -
    -// Create a Home icon 
    -Evas_Object *icon;
    -
    -icon = elm_icon_add(parent);
    -elm_icon_standard_set(icon, "home");
    -
    -// Set it to the check object 
    -elm_object_part_content_set(check, "icon", icon);
    -
    - -

    The get functions of the elementary object API can be used to retrieve the content set to the check object.

    -
    -// Get the content set in the icon part 
    -Evas_Object *icon = elm_object_part_content_get(check, "icon");
    -
    - -

    Using the Check Callbacks

    - -

    When the value is changed by the user, the changed signal is emitted. The event_info parameter is NULL.

    - -

    The following example shows how to register a callback on this signal.

    - -
    -{
    -   evas_object_smart_callback_add(check, "changed", changed_cb, data);
    -}
    -
    -// Callback function for the "changed" signal
    -// This callback is called when the check value changes
    -void changed_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   dlog_print(DLOG_INFO, LOG_TAG, "The value has changed\n");
    -}
    -
    - -

    Ctxpopup

    - -

    Figure: Context popup component

    -

    Context popup component

    - -

    Figure: Context popup hierarchy

    -

    Context popup hierarchy

    - - -

    Ctxpopup is a contextual popup that can show a list of items.

    - -

    Adding a Ctxpopup Component

    - -

    A ctxpopup can be created with the elm_ctxpopup_add() function, and when shown, it automatically chooses an area inside its parent object's view (set using elm_ctxpopup_hover_parent_set()) to optimally fit into it.

    - -
    -Evas_Object *ctxpopup, *parent;
    -
    -// Create a ctxpopup 
    -ctxpopup = elm_ctxpopup_add(parent);
    -
    - -

    Modifying the Ctxpopup Style

    - -

    The following styles are available for wearable core controls:

    -
      -
    • default
    • -
    -

    The following styles are available for Gear O:

    -
      -
    • select_mode
    • -
    • select_mode/top, select_mode/bottom (These two styles can be used as a pair.)
    • -
    - - -

    The following example shows how to set the default style.

    -
    -elm_object_style_set(ctxpopup, "default");
    -
    - -

    Configuring the Ctxpopup

    - -

    The context popup orientation can be set with elm_ctxpopup_horizontal_set(). Here it is set to horizontal.

    -
    -elm_ctxpopup_horizontal_set(ctxpopup, EINA_TRUE);
    -
    - -

    Auto hide is enabled by default. You can also disable auto hiding if you want the ctxpopup never to be hidden.

    -
    -elm_ctxpopup_auto_hide_disabled_set(ctxpopup, EINA_TRUE);
    -
    - -

    Managing the Ctxpopup Items

    - -

    The ctxpopup can contain a small number of items. Each of them can have a label and an icon. The following example shows how to append an item with the Test label and no icon.

    -
    -Elm_Object_Item *it;
    -
    -it = elm_ctxpopup_item_append(ctxpopup, "test", NULL, _ctxpopup_item_cb, 
    -                  NULL);
    -
    - -

    The _ctxpopup_item_cb() callback is called when the item is clicked. The following example shows how to write the definition of this callback.

    -
    -static void
    -_ctxpopup_item_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   dlog_print(DLOG_INFO, LOG_TAG, "ctxpopup item selected\n");
    -}
    -
    - -

    After that the item label is set to New label.

    -
    elm_object_item_part_text_set(it, "default", "New label");
    -
    - -

    And its icon is modified to the standard home icon.

    -
    -Evas_Object *home_icon = elm_icon_add(ctxpopup);
    -elm_icon_standard_set(home_icon, "home");
    -
    -elm_object_item_part_content_set(it, "icon", home_icon);
    -
    - -

    Using the Ctxpopup Callbacks

    - -

    The context popup emits the dismissed signal when it is dismissed. You can register a callback to this signal. The event_info parameter is NULL.

    - -
    -{
    -   evas_object_smart_callback_add(ctxpopup, "dismissed", dismissed_cb, data);
    -}
    -
    -// Callback function for the "dismissed" signal
    -// This callback is called when the ctxpopup is dismissed
    -void dismissed_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   dlog_print(DLOG_INFO, LOG_TAG, "Ctxpopup dismissed\n");
    -}
    -
    - -

    Datetime

    - -

    Figure: Datetime selection

    -

    Datetime selection

    - -

    Figure: Datetime hierarchy

    -

    Datetime hierarchy

    - -

    The datetime component displays and adds date and time values.

    - -

    Adding a Datetime Component

    - -

    The UI component is created with elm_datetime_add().

    -

    The following fields can be controlled:

    -
      -
    • ELM_DATETIME_YEAR: the year field
    • -
    • ELM_DATETIME_MONTH: the month field
    • -
    • ELM_DATETIME_DATE: the date field
    • -
    • ELM_DATETIME_HOUR: the hour field
    • -
    • ELM_DATETIME_MINUTE: the minute field
    • -
    • ELM_DATETIME_AMPM: the AM/PM field
    • -
    - -

    Using the Datetime Styles

    - -

    The following styles are available:

    -
      -
    • datepicker_layout
    • -
    • timepicker_layout
    • -
    - -

    The following example creates the datepicker_layout style:

    -
    -elm_object_style_set(datetime, "datepicker_layout");
    -
    - -

    Setting the Datetime Format

    - -

    The format of the date and time can be configured with elm_datetime_format_set() using a combination of allowed Libc date format specifiers. In the following example the format is set to HH : MM.

    -
    -elm_object_style_set(datetime, "timepicker_layout");
    -elm_datetime_format_set(datetime, "%d/%b/%Y%I:%M");
    -
    -

    Please refer to the API documentation for a complete list of all the options available.

    - -

    Using the Datetime Callbacks

    - -

    A callback can be registered on the changed signal to detect when the Datetime field values are changed. The event_info parameter is NULL.

    -
    -{
    -   evas_object_smart_callback_add(datetime, "changed", changed_cb, data);
    -}
    -
    -// Callback function for the "changed" signal
    -// This callback is called when the datetime fields change
    -void changed_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   dlog_print(DLOG_INFO, LOG_TAG, "Datetime field changed. \n");
    -}
    - -

    The language,changed signal is emitted when the system locale changes.

    - - - -

    Entry

    - -

    Figure: Entry component

    -

    Entry component

    - -

    Figure: Entry component

    -

    Entry component

    - -

    Figure: Entry hierarchy

    -

    Entry hierarchy

    - -

    The entry component is a box where the user can enter text. It supports the following features:

    -
      -
    • text wrapping
    • -
    • multiline
    • -
    • scrolling
    • -
    • formatted markup text
    • -
    • password mode
    • -
    • filtering text
    • -
    • read/write from a file
    • -
    • theme style overrides
    • -
    - -

    Adding an Entry Component

    - -

    The entry component is created with the elm_entry_add() function, and the text inside the entry can be set with elm_entry_entry_set().

    -
    -Evas_Object *entry, *parent;
    -
    -entry = elm_entry_add(parent);
    -elm_entry_entry_set(entry, "A short text.");
    -
    - -

    Using the Text Editor

    - -

    You can append text to the end of existing content.

    -
    -elm_entry_entry_append(entry, "END");
    -
    - -

    You can also insert text at the current cursor position.

    -
    -elm_entry_entry_insert(entry, "CURSOR");
    -Eina_Bool Empty = elm_entry_is_empty(entry);
    -
    - -

    Call elm_entry_is_empty() to see whether the entry is empty. Here, the boolean variable Empty returns EINA_FALSE.

    -

    The user can enter text in the entry component when it is in focus. It is possible to prevent the user from editing text if needed.

    -
    -elm_entry_editable_set(entry, EINA_FALSE);
    -
    - - - - - - - - - - -
    Note
    It is still possible to use the previous functions to modify the text of a non-editable entry.
    - -

    Setting the Password Mode

    - -

    When dealing with password content, the password mode activates to hide what the user is typing. In this mode, the display of any text is replaced by asterisks (*), and the entry is single line (there is no line wrap).

    - -
    -elm_entry_password_set(entry, EINA_TRUE);
    -
    - -

    Entry Line Modes And Wrapping

    - -

    The entry component has two line modes:

    -
      -
    • single line mode
    • -
    • multiline mode
    • -
    - -

    First, set the entry in single line mode.

    - -
    -elm_entry_single_line_set(entry, EINA_TRUE);
    -
    - -

    In this mode, the text does not wrap when reaching the edge, but the entry grows horizontally instead. Pressing the Enter key in this mode generates an activate event instead of adding a new line.

    - -

    When the entry is set to multiline mode (single line off), the text wraps at the end of the entry and pressing Enter creates a new line.

    - -
    -elm_entry_single_line_set(entry, EINA_FALSE);
    -elm_entry_line_wrap_set(entry, ELM_WRAP_WORD);
    -
    - -

    In multiline entries, elm_entry_line_wrap_set() provides a way to cut the text implicitly into a new line when it reaches the far edge of the UI component. The following wrap modes are available:

    -
      -
    • ELM_WRAP_NONE: No wrap
    • -
    • ELM_WRAP_CHAR: Wrap between characters
    • -
    • ELM_WRAP_WORD: Wrap in allowed wrapping points (as defined in the unicode standard)
    • -
    • ELM_WRAP_MIXED: Word wrap, and if that fails, char wrap
    • -
    - -

    Selecting Text

    - -

    Text selections can be made with different functions:

    -
      -
    • To select all the content of the entry component: -
      -elm_entry_select_all(entry);
      -
      -
    • - -
    • To deselect the current selection: -
      -elm_entry_select_none(entry);
      -
      -
    • - -
    • To select part of the text, use elm_entry_select_region_set(). The following code selects the first twenty characters of the entry content. -
      -elm_entry_select_region_set(entry, 0, 20);
      -
      -
    • - -
    • To retrieve the currently selected text in an entry: -
      -const char *selection;
      -
      -selection = elm_entry_selection_get(entry);
      -
      -
    • -
    - -

    If the entry text is empty, elm_entry_selection_get() returns NULL.

    - -

    You can copy or cut the selection to the clipboard.

    -
    -elm_entry_selection_cut(entry);
    -
    - -

    The selection can be pasted in the same or a different entry.

    -
    -elm_entry_selection_paste(entry);
    -
    - -

    Controlling the Cursor

    - -

    The cursor represents the current position in the entry, where the next action, for example, text insertion or deletion, is done. Usually, the cursor is represented as a blinking character, but its appearance depends on the theme configuration. The cursor position can be modified by using several functions.

    -
      -
    • To move the cursor to the beginning of the entry: -
      -elm_entry_cursor_begin_set(entry);
      -
      -
    • - -
    • To move the cursor to the end of the entry: -
      -elm_entry_cursor_end_set(entry);
      -
      -
    • - -
    • To move the cursor one line down or up: -
      -elm_entry_cursor_down(entry);
      -elm_entry_cursor_up(entry);
      -
      -
    • -
    • To move the cursor one character to the left or right: -
      -elm_entry_cursor_prev(entry);
      -elm_entry_cursor_next(entry);
      -
      -
    • - -
    • To set the cursor at a specific position (15th character, for example): -
      -elm_entry_cursor_pos_set(entry, 15);
      -
      -
    • -
    - -

    It is possible to start a selection at the current cursor position, move five characters to the right and end the selection.

    -
    -elm_entry_cursor_selection_begin(entry);
    -
    -for (i = 0; i < 5; i++)
    -{
    -   elm_entry_cursor_next(entry);
    -}
    -
    -elm_entry_cursor_selection_end(entry);
    -
    - -

    Formatting Text

    - -

    Text within an entry can be formatted by using markups tags that are defined in the theme. The following markups are available in the default theme:

    -
      -
    • <br>: Inserts a line break.
    • -
    • <ps>: Inserts a paragraph separator. This is preferred over line breaks.
    • -
    • <tab>: Inserts a tab.
    • -
    • <em>...</em>: Emphasis. Sets the oblique style for the enclosed text.
    • -
    • <b>...</b>: Sets the bold style for the enclosed text.
    • -
    • <link>...</link>: Underlines the enclosed text.
    • -
    • <hilight>...</hilight>: Highlights the enclosed text.
    • -
    - -

    Using Special Markups

    - -

    Special markups can be added within the text of the entry:

    -
      -
    • <a href = ..>...</a>: Anchors
    • -
    • <item size = .. vsize = .. href = ..>...</item>: Items
    • -
    - -

    The anchors generate an anchor,clicked signal when the user clicks on them. The href attribute is used to identify the anchor. It also reacts to the anchor,in (mouse in), anchor,out (mouse out), anchor,down (mouse down), and anchor,up (mouse up) events.

    - -

    The item markup provides a way to insert any Evas_Object in the text. The Evas_Object name has to be specified in the href attribute.

    - -

    Overriding Style

    - -

    To tweak the style of the text within the entry component, it is possible to override parts of the theme style to the textblock object by using elm_entry_text_style_user_push(). This function pushes a new style on top of the user style stack that overrides the current style. Remove the style in the top of user style stack with elm_entry_text_style_user_pop().

    - -

    Filtering Text

    - -

    Text within an entry can be filtered in size. The following example sets the maximum number of characters allowed in the entry to 8.

    -
    -static Elm_Entry_Filter_Limit_Size limit_size = 
    -{
    -   .max_char_count = 8,
    -   .max_byte_count = 0
    -};
    -
    -// Append a new callback to the list, this function is called each time
    -// a text is inserted in the entry. Pass the limit_size struct previously
    -// created to set the maximum number of characters allowed to 8
    - 
    -elm_entry_markup_filter_append(entry, elm_entry_filter_limit_size, limit_size);
    -
    - -

    The content can be filtered by passing an Elm_Entry_Filter_Accept_Set structure. This structure contains the accepted characters and rejected characters. The following example shows how to reject the '+', '-', '*', and '/' characters.

    - -
    -static Elm_Entry_Filter_Accept_Set accept_set = 
    -{
    -   .accepted = NULL,
    -   .rejected = "+*-/"
    -};
    -
    -elm_entry_markup_filter_append(entry, elm_entry_filter_accept_set, accept_set);
    -
    - -

    Loading and Saving Files

    - -

    The entry content can be saved to a file (/tmp/test.txt, for example).

    - -
    -// Set the file in which the entry text is saved. This function
    -// implicitly loads the existing file content 
    -elm_entry_file_set(entry, "/tmp/test.txt", ELM_TEXT_FORMAT_MARKUP_UTF8);
    -
    - -

    Autosave is activated by default and changes are written back to the file after a short delay. This feature can be deactivated and you can manually save the content when needed.

    -
    -// Disable autosaving 
    -elm_entry_autosave_set(entry, EINA_FALSE);
    -
    -// Trigger saving when needed 
    -elm_entry_file_save(entry);
    -
    - -

    Using Entry Theme Content

    - -

    Two content parts of the default theme are available: icon and end. The following example shows how to set an icon in the end content part.

    - -
    -Evas_Object *icon;
    -
    -ic = elm_icon_add(entry);
    -elm_image_file_set(ic, "icon.png", NULL);
    -elm_object_part_content_set(entry, "end", icon);
    -
    - -

    Using Entry Theme Texts

    - -

    The default theme allows the use of the following text parts:

    -
      -
    • elm.text - text of the entry
    • -
    • elm.guide - placeholder of the entry
    • -
    - -

    The following example shows how to set the placeholder text of the entry to Hello World.

    -
    -elm_object_part_text_set(entry, "elm.guide", "Hello World");
    -
    - -

    Using Entry Callbacks

    - -

    The entry component emits the following signals:

    -
      -
    • aborted: The escape key is pressed on a single line entry.
    • -
    • activated: The enter key is pressed on a single line entry.
    • -
    • anchor,clicked: An anchor is clicked. event_info points to an object of the type Elm_Entry_Anchor_Info.
    • -
    • anchor,down: Mouse button is pressed on an anchor. event_info points to an object of the type Elm_Entry_Anchor_Info.
    • -
    • anchor,hover,opened: The anchor is clicked. event_info points to an object of the type Elm_Entry_Anchor_Info.
    • -
    • anchor,in: Mouse cursor is moved into an anchor. event_info points to an object of the type Elm_Entry_Anchor_Info.
    • -
    • anchor,out: Mouse cursor is moved out of an anchor. event_info points to an object of the type Elm_Entry_Anchor_Info.
    • -
    • anchor,up: Mouse button is unpressed on an anchor. event_info points to an object of the type Elm_Entry_Anchor_Info.
    • -
    • changed: The text within the entry is changed.
    • -
    • changed,user: The text within the entry is changed because of user interaction. event_info points to an object of the type Edje_Entry_Change_Info.
    • -
    • clicked: The entry is clicked (mouse press and release).
    • -
    • clicked,double: The entry is double clicked.
    • -
    • clicked,triple: The entry is triple clicked.
    • -
    • cursor,changed: The cursor position is changed.
    • -
    • cursor,changed,manual: The cursor position is changed manually.
    • -
    • focused: The entry receives focus. event_info points to an object of the type Elm_Focus_Info.
    • -
    • unfocused: The entry loses focus.
    • -
    • language,changed: Program language is changed.
    • -
    • longpressed: A mouse button is pressed and held for a couple of seconds.
    • -
    • maxlength,reached: A maximum length is reached.
    • -
    • preedit,changed: The preedit string is changed.
    • -
    • press: A mouse button is pressed on the entry.
    • -
    • redo,request: The request is redone.
    • -
    • selection,changed: The current selection is changed.
    • -
    • selection,cleared: The current selection is cleared.
    • -
    • selection,copy: A copy of the selected text into the clipboard is requested.
    • -
    • selection,cut: A cut of the selected text into the clipboard is requested.
    • -
    • selection,paste: A paste of the clipboard contents is requested.
    • -
    • selection,start: A selection is begun and no previous selection exists.
    • -
    • text,set,done: The whole text is set to the entry.
    • -
    • theme,changed: The theme is changed.
    • -
    • undo,request: The request is undone.
    • -
    - -

    For signals, where event_info has not been explicitly described, it is set to NULL.

    - -

    The following example shows how to register a callback to the focused signal.

    -
    -{
    -   evas_object_smart_callback_add(entry, "focused", focused_cb, data);
    -}
    -
    -// Callback function for the "focused" signal
    -// This callback is called when the entry receive the focus
    -void focused_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   dlog_print(DLOG_INFO, LOG_TAG, "Entry focused\n");
    -} 
    -
    - - -

    Genlist

    - -

    Figure: Genlist component

    -

    Genlist component

    - -

    Figure: Genlist hierarchy

    -

    Genlist hierarchy

    - -

    Genlist is a UI component that displays a scrollable list of items. It allows a lot of entries while being fast and has a low memory footprint, as only the visible items are allocated in the memory.

    - -

    For more information, see the Genlist Tutorial.

    - -

    Genlist Item Style

    - -

    An item can have 0 or more texts, 0 or more contents, and 0 or more boolean states. This is defined in the Edje item theme style. Genlist looks for data items named respectively labels, contents, and states in the Edje file. The default item style provides one text part (elm.text), two content parts (elm.swallow.icon and elm.swallow.end) and no state parts.

    - -

    The following item styles are available:

    -
      -
    • default
    • -
    • groupindex
    • -
    • 1text
    • -
    • 1text.1icon
    • -
    • 2text
    • -
    • 2text.1
    • -
    • 1text.1icon.divider
    • -
    • 1text.1icon.1
    • -
    • 2text.1icon.1
    • -
    • multiline/1text
    • -
    • multiline/2text
    • -
    - -

    Here are some examples of the item styles.

    - -

    Figure: 1text item style

    -

    1 text item style

    - -

    Figure: 1text.1icon.1 item style

    -

    1text.1icon.1 item style

    - -

    Figure: 2text.1icon.1 item style

    -

    2text.1icon.1 item style

    - -

    For more information on creating a new genlist item style, see Customizing UI Components.

    - -

    Adding a Genlist Component

    - -

    A genlist component is added with the elm_genlist_add() function.

    -
    -Evas_Object *genlist, *parent;
    -genlist = elm_genlist_add(parent);
    -
    - -

    Creating And Deleting Items

    - -

    To save up memory, genlist allocates and deletes items on the go, while the user is scrolling the list. To enable that, the user creates and fills a Elm_Genlist_Item_Class structure that informs the genlist component which callbacks to call when an item is created or deleted.

    -
    -Elm_Genlist_Item_Class *itc = elm_genlist_item_class_new();
    -
    -itc->item_style = "default";
    -itc->decorate_item_style = NULL;
    -itc->decorate_all_item_style = NULL;
    -itc->func.text_get = _item_label_get;
    -itc->func.content_get = _item_content_get;
    -itc->func.state_get = _item_state_get;
    -itc->func.del = _item_del;
    -
    - -

    The item_style, decorate_item_style, and decorate_all_item_style attributes define the names of the item style, the decorate mode item style and the decorate all item style.

    - -

    The func structure contains pointers to functions that are called when an item is going to be created or deleted. All of them receive a data parameter that points to the same data passed to the elm_genlist_item_append() and related item creation functions, and an obj parameter that points to the genlist object itself.

    -
      -
    • text_get -

      This function receives a PART parameter that is the name string of one of the existing text parts in the Edje group implementing the item's theme. It has to return a string (duplicated with the strdup() function) corresponding to the PART parameter. The caller is in charge of freeing the string when done.

    • - -
    • content_get -

      The PART parameter is the name string of one of the existing swallow parts in the Edje group. When no content is desired, it must return NULL, or otherwise, a valid object handle. The object is deleted by the genlist on its deletion or when the item is unrealized.

    • - -
    • state_get -

      The PART parameter is the name string of one of the state parts in the Edje group implementing the item's theme. It returns EINA_FALSE for false/off or EINA_TRUE for true/on. The default is false. Genlists emit a signal to the PART parameter's theming Edje object with elm,state,xxx,active as emission and elm as source argument, when the state is true. xxx is the name of the (state) part.

    • - -
    • del -

      This function is called when the genlist item is deleted. It deletes any data that is allocated at the item creation.

    • -
    - -

    Managing Items

    - -

    To add an item, several functions can be used. elm_genlist_item_append() adds an item to the end of the list, or if there is a parent list, to the end of all the child items of the parent list. elm_genlist_item_prepend() is otherwise the same but adds to the beginning of the list or children lists. elm_genlist_item_insert_before() inserts an item before the indicated item and elm_genlist_item_insert_after() inserts an item after the indicated item.

    - -

    The previous functions take a type parameter that can be one of the following.

    -
      -
    • ELM_GENLIST_ITEM_NONE
    • -
    • ELM_GENLIST_ITEM_TREE
    • -
    • ELM_GENLIST_ITEM_GROUP
    • -
    - -

    If ELM_GENLIST_ITEM_TREE is set, this item is displayed as being able to expand and have child items. If ELM_GENLIST_ITEM_GROUP is set, this item is a group index item that is displayed at the top until the next group appears.

    - -

    Figure: Genlist tree

    -

    Genlist tree

    - -

    The application clears the list with elm_genlist_clear(), which deletes all the items in the list. elm_object_item_del() deletes a specific item. elm_genlist_item_subitems_clear() clears all items that are children of the indicated parent item.

    - -

    To help inspect the list items, move to the item at the top of the list with elm_genlist_first_item_get(), which returns the item pointer. elm_genlist_last_item_get() moves to the item at the end of the list. elm_genlist_item_next_get() and elm_genlist_item_prev_get() move to the next and previous items relative to the indicated item. Using these calls you can go through the entire item list or tree.

    - - - - - - - - - - -
    Note
    As a tree, the items are flattened on the list, so elm_genlist_item_parent_get() gives you the name of the parent item (even to skip them if needed).
    - -

    elm_genlist_item_show() scrolls the scroller to show the desired item as visible.

    -

    elm_object_item_data_get() returns the data pointer set by the item creation functions.

    - -

    If an item changes (state, boolean, text or content change), use elm_genlist_item_update() for the genlist to update the item. Genlist re-realizes the item and calls the functions in the _Elm_Genlist_Item_Class for it.

    - -

    Selection

    - -

    Items are manually selected or deselected with elm_genlist_item_selected_set() or disabled with elm_object_item_disabled_set(). In case there is a tree or a group item, the elm_genlist_item_expanded_set() function is used to expand or contract the item.

    - - - - - - - - - - -
    Note
    Calling this function does not show or hide any child of an item (if it is a parent). You must manually delete and create them on the callbacks of the expanded or contracted signals.
    - -

    By default, the genlist is in single-selection mode: only one item can be selected at a time. You can use elm_genlist_multi_select_set() to select multiple items. In the single-selection mode, the elm_genlist_selected_item_get() function can be called to retrieve the selected item. If several items are selected, the elm_genlist_selected_items_get() returns a list of the current selected items.

    - -

    In the following figure, there is a genlist in multi-selection mode with two items selected (#4 and #5) and one item disabled (#2).

    - -

    Figure: Genlist component

    -

    Genlist component

    - -

    Using Genlist Callbacks

    - -

    The genlist component emits the following signals:

    -
      -
    • activated: The user has double-clicked or pressed (enter | return | spacebar) on an item. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
    • -
    • clicked,double: The user has double-clicked an item. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
    • -
    • selected: The user selects an item. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
    • -
    • unselected: The user unselects an item. event_info in the callback function points at an object of type Elm_Object_Item that contains the activated item.
    • -
    • expanded: The item is to be expanded with elm_genlist_item_expanded_set(). This callback fills in the child items. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
    • -
    • contracted: The item is to be contracted with elm_genlist_item_expanded_set(). This callback deletes the child items. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
    • -
    • expand,request: The user wants to expand a tree branch item. The callback decides if the item can expand (if it has any children) and calls elm_genlist_item_expanded_set() to set the state. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
    • -
    • contract,request: The user wants to contract a tree branch item. The callback decides if the item can contract (if it has any children) and calls elm_genlist_item_expanded_set() to set the state. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
    • -
    • realized: The item is created as a real evas object. event_info in the callback function points at an object of the type Elm_Object_Item, that contains the activated item.
    • -
    • unrealized: An item is going to be unrealized. Content objects provided are deleted and the item object is deleted or put into a floating cache. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
    • -
    • drag,start,up: The item in the list is dragged (not scrolled) up. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
    • -
    • drag,start,down: The item in the list is dragged (not scrolled) down. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
    • -
    • drag,start,left: The item in the list is dragged (not scrolled) left. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
    • -
    • drag,start,right: The item in the list is dragged (not scrolled) right. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
    • -
    • drag,stop: The item in the list has stopped being dragged. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
    • -
    • drag: The item in the list is being dragged. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
    • -
    • longpressed: The item is pressed for a certain amount of time. The default specified time is one second. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
    • -
    • scroll,anim,start: The scrolling animation is started. event_info is NULL.
    • -
    • scroll,anim,stop: The scrolling animation is stopped. event_info is NULL.
    • -
    • scroll,drag,start: Dragging the content is started. event_info is NULL.
    • -
    • scroll,drag,stop: Dragging the content is stopped. event_info is NULL.
    • -
    • edge,top: The genlist is scrolled to the top edge. event_info is NULL.
    • -
    • edge,bottom: The genlist is scrolled to the bottom edge. event_info is NULL.
    • -
    • edge,left: The genlist is scrolled to the left edge. event_info is NULL.
    • -
    • edge,right: The genlist is scrolled to the right edge. event_info is NULL.
    • -
    • multi,swipe,left: The genlist is multi-touch swiped left. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
    • -
    • multi,swipe,right: The genlist is multi-touch swiped right. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
    • -
    • multi,swipe,up: The genlist is multi-touch swiped up. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
    • -
    • multi,swipe,down: The genlist is multi-touch swiped down. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
    • -
    • multi,pinch,out: The genlist is multi-touch pinched out. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
    • -
    • multi,pinch,in: The genlist is multi-touch pinched in. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
    • -
    • swipe: The genlist is swiped. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
    • -
    • moved: A genlist item is moved in the reorder mode. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
    • -
    • moved,after: A genlist item is moved after another item in the reorder mode. To access the relative previous item, use elm_genlist_item_prev_get(). This signal is called along with the moved signal. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
    • -
    • moved,before: A genlist item is moved before another item in the reorder mode. To access the relative previous item, use elm_genlist_item_next_get(). This signal is called along with the moved signal. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
    • -
    • language,changed The program's language is changed. event_info is NULL.
    • -
    • tree,effect,finished: A genlist tree effect is finished. event_info is NULL.
    • -
    - - -

    GLView

    - -

    Figure: GLView example

    -

    GLView example

    - -

    Figure: GLView hierarchy

    -

    GLView hierarchy

    - - -

    The GLView component renders OpenGL in an elementary object, which hides Evas GL complexity. For more information, see OpenGL ES.

    - -

    Adding a GLView Component

    - -

    Create a GLView component with the elm_glview_add() function.

    -
    -Evas_Object *glview, *parent;
    -
    -glview = elm_glview_add(parent);
    -
    - -

    In this example, the size of the GLView is set to 200x200 pixels.

    -
    -elm_glview_size_set(glview, 200, 200);
    -
    - -

    Using the GLView API

    - -

    You can configure the GLView rendering mode by activating the following rendering modes:

    -
      -
    • ELM_GLVIEW_ALPHA: Alpha channel rendering mode
    • -
    • ELM_GLVIEW_DEPTH: Depth buffer rendering mode
    • -
    • ELM_GLVIEW_STENCIL: Stencil buffer rendering mode
    • -
    • ELM_GLVIEW_DIRECT: Direct rendering mode
    • -
    • ELM_GLVIEW_CLIENT_SIDE_ROTATION: The client handles the GL view rotation if direct rendering is enabled
    • -
    - -

    In the following example, the alpha channel and depth buffer rendering mode are enabled.

    -
    -elm_glview_mode_set(glview, ELM_GLVIEW_ALPHA | ELM_GLVIEW_DEPTH);
    -
    - -

    The following example shows how to decide what to do with the GL surface when the GLView component is resized.

    -
    -elm_glview_resize_policy_set(glview, ELM_GLVIEW_RESIZE_POLICY_RECREATE);
    -
    - -

    The GL surface is destroyed and recreated to the new size (default function). The resize policy can also be set to ELM_GLVIEW_RESIZE_POLICY_SCALE. In that case, only the image object is scaled, not the underlying GL surface.

    - -

    The following example shows how to set the GLView rendering policy.

    -
    -elm_glview_render_policy_set(glview, ELM_GLVIEW_RENDER_POLICY_ALWAYS);
    -
    - -

    The GLView object is always redrawn during the rendering loop. It can also be set to ELM_GLVIEW_RENDER_POLICY_ON_DEMAND (default function), where the GLView component is redrawn only when it is visible.

    - -

    Register the callbacks:

    -
    elm_glview_init_func_set(glview, _init_gl_cb);
    -elm_glview_del_func_set(glview, _del_gl_cb);
    -elm_glview_resize_func_set(glview, _resize_gl_cb);
    -elm_glview_render_func_set(glview, _draw_gl_cb);
    -
    - -
      -
    • elm_glview_init_func_set() registers an init callback that is called at the GLView object creation.
    • -
    • elm_glview_del_func_set() registers a del function that is called when the GLView object is deleted.
    • -
    • elm_glview_resize_func_set() registers the resize function that is called during the rendering loop when the GLView object is resized.
    • -
    • elm_glview_render_func_set() registers the render function that is called when the GLView object must be redrawn.
    • -
    - -

    Using GLView Callbacks

    - -

    The GLView component emits the following signals:

    -
      -
    • focused: The GlView component is focused. The event_info parameter points at an object of the type Elm_Focus_Info.
    • -
    • unfocused: The GLView object is unfocused.
    • -
    - -

    To register a callback:

    -
    -{
    -      evas_object_smart_callback_add(glview, "focused", focused_cb, data);
    -}
    -
    -// Callback function for the "focused" signal
    -// This callback is called when the GLView is focused
    -void focused_cb(void *data, Evas_Object *obj, void  *event_info)
    -{
    -      Elm_Focus_Info *fi = event_info;
    -
    -      dlog_print(DLOG_INFO, LOG_TAG, "GLView is focused\n");
    -}
    -
    - -

    Icon

    - -

    Figure: Icon hierarchy

    -

    Icon hierarchy

    - -

    The icon component inherits from the image component. It is used to display images in an icon context.

    - -

    Adding an Icon Component

    - -

    You can create an icon and set it as a freedesktop.org Home standard icon.

    - -
    -Evas_Object *icon, *parent;
    -icon = elm_icon_add(parent);
    -elm_icon_standard_set(icon, "Home");
    -
    - -

    Changing Image File

    - -

    You can change the image by using an image in the filesystem (for example, /tmp/Home.png).

    -
    -elm_image_file_set(icon, "/tmp/Home.png", NULL);
    -
    - -

    You can also use a group in an Edje file (for example, /tmp/Home.edj).

    -
    -elm_image_file_set(icon, "/tmp/Home.edj", "elm/icon/Home/default");
    -
    - -

    A thumbnail can be generated and cached for future use. For this, you need the Ethumb library support.

    - -
    -elm_icon_thumb_set(icon, "/tmp/Home.png", NULL);
    -
    - -

    This function sets the file in the icon and enables the use of a cached thumbnail if it already exists. Otherwise, it creates a new thumbnail and caches it for future use.

    - -

    Using Icon Callbacks

    - -

    The icon component emits the following signals:

    -
      -
    • thumb,done: elm_icon_thumb_set() is completed with success.
    • -
    • thumb,error: elm_icon_thumb_set() fails.
    • -
    - -

    In both cases, event_info is NULL.

    - - -

    Image

    - -

    Figure: Image component

    -

    Image component

    - -

    Figure: Image hierarchy

    -

    Image hierarchy

    - -

    The image component can load and display an image from a disk file or a memory region.

    - -

    Adding an Image Component

    - -

    This object is created with elm_image_add().

    - -
    -Evas_Object *image, *parent;
    -image = elm_image_add(parent);
    -
    - -

    Configuring the Image Component

    - -

    Various properties of the image can be tuned. First, you can disable the elementary scaling so that the image does not scale but resizes on both directions.

    -
    -elm_image_no_scale_set(image, EINA_TRUE);
    -elm_image_resizable_set(image, EINA_TRUE, EINA_TRUE);
    -
    - -

    When scaling images, the smooth scaling algorithm can be used. It provides a better quality image but is slower than the default algorithm.

    -
    -elm_image_smooth_set(image, EINA_TRUE);
    -
    - -

    Preloading is used to load images without blocking the user interface. This preserves the reactivity of the user experience. The image is loaded in a thread. It can be disabled if desired.

    -
    -elm_image_preload_disabled_set(image, EINA_TRUE);
    -
    - -

    The image can be rotated or flipped. Here the image is rotated 180 degrees.

    -
    -elm_image_orient_set(image, ELM_IMAGE_ROTATE_180);
    -
    - -

    The following orientations are available:

    -
      -
    • ELM_IMAGE_ORIENT_0: No orientation change
    • -
    • ELM_IMAGE_ROTATE_90: Rotate the image 90 degrees clockwise
    • -
    • ELM_IMAGE_ROTATE_180: Rotate the image 180 degrees clockwise
    • -
    • ELM_IMAGE_ROTATE_270: Rotate the image 90 degrees counter-clockwise
    • -
    • ELM_IMAGE_FLIP_HORIZONTAL: Flip the image horizontally
    • -
    • ELM_IMAGE_FLIP_VERTICAL: Flip the image vertically
    • -
    • ELM_IMAGE_FLIP_TRANSPOSE: Flip the image along the bottom-left to top-right line
    • -
    • ELM_IMAGE_FLIP_TRANSVERSE: Flip the image along the top-left to bottom-right line
    • -
    - -

    If you want to keep the original aspect ration when resizing the image, you must define how the image fits into the object's area.

    -
    -// Tell the image to keep original aspect ratio 
    -elm_image_aspect_fixed_set(image, EINA_TRUE);
    -// Then let the image fill the entire object 
    -elm_image_fill_outside_set(image, EINA_TRUE);
    -
    - -

    In this configuration, part of the image can go outside the object. If elm_image_fill_outside_set is set to EINA_FALSE, the image stays inside the limits of the parent object.

    - -

    Using Image Callbacks

    - -

    The image component emits the following signals:

    -
      -
    • drop: The user drops an image typed object onto the object in question - the event info argument is the path to that image file
    • -
    • clicked: The user clicks the image. event_info is NULL.
    • -
    - -

    To register a callback when a user clicks on the image:

    -
    -{
    -   evas_object_smart_callback_add(image, "clicked", clicked_cb, data);
    -}
    -
    -// Callback function for the "clicked" signal
    -// This callback is called when the image is clicked
    -void clicked_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   dlog_print(DLOG_INFO, LOG_TAG, "Image clicked\n");
    -}
    -
    - -

    Index

    - -

    Figure: Index component

    -

    Index component

    - -

    Figure: Index hierarchy

    -

    Index hierarchy

    - -

    An index component gives you an index for fast access to whichever group of other UI items you have. The index component is by default hidden, but it appears when the user clicks over its reserved area in the canvas. In the default theme, it is a one finger wide area on the right side of the index component's container. Generally, an index is used together with lists, generic lists, or generic grids.

    - -

    Adding an Index Component

    - -

    Call the elm_index_add() function to create a new index component.

    -
    -Evas_Object *index, *parent;
    -index = elm_index_add(parent);
    -
    - -

    Adding Items

    - -

    The following example shows how to add the listitem object at the letter A, calling the smart callback it_select_cb() when this item is selected.

    -
    -Elm_Object_Item *list_item1, *list_item2;
    -elm_index_item_append(index, "A", it_select_cb, list_item1);
    -
    - -

    The following example shows how to add item objects, calling the smart callback it_select_cb() when the item is selected.

    -
    -Elm_Object_Item *it[5];
    -for (i = 0; i < 5; ++i)
    -{
    -   it[i] = elm_index_item_append(index, NULL, it_select_cb, (void *) i);
    -}
    - -

    The following example shows how to define the smart callback.

    -
    -// Callback function called when the list_item1 object
    -// is selected
    -void it_select_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   dlog_print(DLOG_INFO, LOG_TAG, "Item1 selected\n");
    -}
    -
    - -

    In the previous case, the indexes are appended to the existing ones. It is also possible to prepend index items with elm_index_item_prepend().

    - - -

    Using Index Callbacks

    - -

    The index component emits the following signals:

    -
      -
    • changed: The selected index item changes. event_info is the selected item's data pointer.
    • -
    • delay,changed: The selected index item changes, but after a small idling period. event_info is the selected item's data pointer.
    • -
    • selected: The user releases a mouse button and selects an item. event_info is the selected item's data pointer.
    • -
    • level,up: The user moves a finger from the first level to the second level.
    • -
    • level,down: The user moves a finger from the second level to the first level.
    • -
    - -

    When the user selects an item in the index, the selected signal is emitted. The developer can then implement the associated callback to do the appropriate action (to show a given area or child object depending on the index item selected, for example). Here is an example of such a callback.

    -
    -static void
    -_index_selected_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   Elm_Object_Item *lit = event_info;
    -
    -   // Code that does the desired action
    -}
    -
    - -

    After that, the callback to the selected signal is registered.

    -
    -evas_object_smart_callback_add(index, "selected", _index_selected_cb, NULL);
    -
    - - -

    Label

    - -

    Figure: Label component

    -

    Label component

    - -

    Figure: Label hierarchy

    -

    Label hierarchy

    - -

    The label component displays text with simple html-like markup.

    - -

    Adding a Label Component

    - -

    To add a label and set the text in it, use the following functions.

    - -
    -Evas_Object *label = elm_label_add(win);
    -
    -elm_object_text_set(label, "Some long text for our label, that is not so long");
    -
    - -

    Using the Label Styles

    - -

    Label displays the text with several predefined styles.

    -
      -
    • default: No animation
    • -
    • marker: The text is centered and bolded.
    • -
    • slide_long: The text appears from the right of the screen and slides until it disappears in the left of the screen(reappearing on the right again).
    • -
    • slide_roll: The text appears from the left of the label and slides to the right to show the overflow, and then appears from the right of the label again.
    • -
    • slide_short: The text appears in the left of the label and slides to the right to show the overflow. When all of the text has been shown the position is reset.
    • -
    • slide_bounce: The text appears in the left of the label and slides to the right to show the overflow. When all of the text has been shown, the animation reverses, moving the text to the left.
    • -
    - -

    Here the style is set to slide_roll.

    - -
    -elm_object_style_set(label, "slide_roll");
    -
    - -

    Configuring the Label

    - -

    The duration of the animation and the slide mode can be set with the following functions.

    -
    -elm_label_slide_duration_set(label, 3);
    -elm_label_slide_mode_set(label, ELM_LABEL_SLIDE_MODE_ALWAYS);
    -
    - -

    Use the following function to modify the style.

    -
    -elm_object_style_set(label, "slide_bounce");
    -
    - -

    Using the Label Callbacks

    - -

    This UI component emits the following signals:

    -
      -
    • language,changed: The program's language changes.
    • -
    • slide,end: The slide reaches the end.
    • -
    • anchor,clicked: The anchor is clicked. event_info points to an object of the type Elm_Label_Anchor_Info.
    • -
    • anchor,mouse,down event_info points to an object of the type Elm_Label_Anchor_Info.
    • -
    • anchor,mouse,up event_info points to an object of the type Elm_Label_Anchor_Info.
    • -
    - -

    The following example registers a callback on the slide,end signal.

    - -
    -{
    -   evas_object_smart_callback_add(label, "slide,end", slide_end_cb, data);
    -}
    -
    -// Callback function for the "slide,end" signal
    -// This callback is called when the label slide reaches the end
    -void slide_end_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   dlog_print(DLOG_INFO, LOG_TAG, "Slide has reach the end.\n");
    -}
    -
    - -

    List

    - -

    Figure: List component

    -

    List component

    - -

    Figure: List hierarchy

    -

    List hierarchy

    - - -

    This UI component is a very simple type of a list component. It is not to be used to manage a lot of items. For that, genlists are a better option.

    - -

    The list items can contain a text and two contents (start and end). These are set with the elm_object_item_*() functions.

    - -

    Adding a List Component

    - -
    -Evas_Object *list, *parent;
    -
    -// Create a list 
    -list = elm_list_add(parent);
    -
    - -

    Using the List

    - -

    This UI component implements the scrollable interface, so the scroller component functions can be used on it. For example, if you want to change the bounce property of the scroller or the scrolling policy:

    - -
    -Evas_Object *list;
    -
    -// Change the scroller policy to fix the scroll only vertically
    -elm_scroller_policy_set(list, ELM_SCROLLER_POLICY_OFF, ELM_SCROLLER_POLICY_AUTO);
    -// Enable bounce effect when the list reaches the upper and lower limits 
    -elm_scroller_bounce_set(list, EINA_FALSE, EINA_TRUE);
    -
    - -

    The elm_list_multi_select_set() function can be called to enable multi-selection of items. Each time an item is clicked, the state changes to selected.

    - -
    -Evas_Object *list;
    -
    -// Activate multi selection 
    -elm_list_multi_select_set(list, EINA_FALSE);
    -
    - -

    Adding Item to the List

    - -

    Items are added with elm_list_item_append() or elm_list_item_prepend(). Here an example of adding ten items with text and one icon on the front: The last two arguments are the callback function when the created item is clicked and the data passed to the callback function.

    - -
    -Evas_Object *list;
    -int i;
    -
    -// This function is called when the list item is selected 
    -static void _selected_item_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   Elm_Object_Item *list_it = elm_list_selected_item_get(obj);
    -   Eina_Bool selected = elm_list_item_selected_get(list_it);
    -   dlog_print(DLOG_INFO, LOG_TAG, "item is %s\n", selected? "selected": "unselected");
    -}
    -
    -for (i = 0; i < 10; i++)
    -{
    -   Evas_Object *ic;
    -   char tmp[8];
    -   snprintf(tmp, sizeof(tmp), "Item %02d", i);
    -   // Create an icon 
    -   ic = elm_icon_add(win);
    -   // Set the file to the icon file 
    -   elm_image_file_set(ic, "path/to/file", NULL);
    -   // Add item to the list 
    -   elm_list_item_append(list, tmp, ic, NULL, _selected_item_cb, NULL);
    -}
    -
    -
    - -

    Changing the Text or Icon of an Item

    - -

    If you want to change the state of an item, you can do it by using all the functions relative to Elm_Object_Item. Each item of the list contains two instances of an evas_object. Give those as the third and the fourth arguments when you append or prepend the item in the list. The evas_object instances are changed with elm_object_item_part_content_set. The first object is referenced as the start object in the theme, whereas the second one is referenced as the end object. Give these names when you use the elm_object_item_part_content_set. The label of the item is changed by using elm_object_item_text_set.

    - -
    -Evas_Object *list;
    -Eina_List *l;
    -Elm_Object_Item *it;
    -
    -// Retrieve the current selected item 
    -it = elm_list_selected_item_get(list);
    -if (!it)
    -   return;
    -
    -ic = elm_icon_add(win);
    -// Set the file to the icon file 
    -elm_image_file_set(ic, "path/to/file", NULL);
    -// Change the first icon 
    -elm_object_item_part_content_set(it, "start", ic);
    -// Change the second icon 
    -elm_object_item_part_content_set(it, "end", ic);
    -// Change the label 
    -elm_object_item_text_set(it, "I've been selected !");
    -
    - -

    Retrieving Selected Items

    - -

    The list of the currently selected items is retrieved with elm_list_selected_items_get(). If the multiselect mode is false, you can retrieve the only selected item with elm_list_selected_item_get(). For example, this is how to unselect all previously selected items.

    - -
    -Evas_Object *list; Eina_List *l;
    -Eina_List *selected_items;
    -// List of Elm_Object_Item 
    -Elm_Object_Item *it;
    -
    -selected_items = elm_list_selected_items_get(list);
    -EINA_LIST_FOREACH(selected_items, l, it)
    -   elm_list_item_selected_set(it, EINA_FALSE);
    -
    - -

    List Item Operations

    - -

    To find out if an item is selected, call elm_list_item_selected_get. This function returns EINA_TRUE if the item is selected, otherwise EINA_FALSE.

    - -

    Elementary list provides two functions for sliding a list to a specific item. elm_list_item_show shows the item passed as an argument, whereas elm_list_item_bring_in shows the item, but only after animating the slide.

    - -

    You can go to the item immediately preceding a specific item with the function elm_list_item_prev, or to the one immediately following a specific item with the function elm_list_item_next.

    - -

    The following example shows selecting the item immediately following the currently selected one, unselecting it, selecting the next one and bringing it to the screen.

    - -
    -Evas_Object *list;
    -Elm_Object_Item *current, *next;
    -current = elm_list_selected_item_get(list);
    -elm_list_item_selected_set(current, EINA_FALSE);
    -next = elm_list_item_next(current);
    -elm_list_item_selected_set(next, EINA_TRUE);
    -elm_list_item_bring_in(next);
    -
    - -

    Using List Callbacks

    - -

    The list emits the following signals:

    -
      -
    • activated: The user double-clicks or presses (enter | return | spacebar) on an item. The event_info parameter of the callback function contains a pointer to the item activated.
    • -
    • clicked,double: The user double-clicks an item. The event_info parameter of the callback function contains a pointer to the item activated.
    • -
    • selected: The user selects an item. The event_info parameter of the callback function contains a pointer to the item activated.
    • -
    • unselected: The user unselects an item. The event_info parameter of the callback function contains a pointer to the item activated.
    • -
    • longpressed: The user long-presses an item. The event_info parameter of the callback function contains a pointer to the item activated.
    • -
    • edge,top: The list is scrolled to the top edge.
    • -
    • edge,bottom: The list is scrolled to the bottom edge.
    • -
    • edge,left: The list is scrolled to the left edge.
    • -
    • edge,right: The list is scrolled to the right edge.
    • -
    • highlighted: The user highlights an item on the list. The event_info parameter of the callback function contains a pointer to the item activated.
    • -
    • unhighlighted: The user unhighlights an item in the list. The event_info parameter of the callback function contains a pointer to the item activated.
    • -
    - -

    You can register to the clicked,double signal with the following code. Note that the currently double-clicked item can be retrieved using the event_info pointer. This code registers to the double,clicked signal and unselects the item that has been double-clicked.

    - -
    -{
    -   Evas_Object *list;
    -
    -   evas_object_smart_callback_add(list, "clicked,double", double_clicked_cb, data);
    -}
    -
    -// Callback function for the "clicked" signal
    -// This callback is called when the button is clicked by the user
    -void double_clicked_cb(void *data, Evas_Object *obj, void  *event_info)
    -{
    -   elm_Object_Item *it = event_info;
    -   elm_list_selected_item_set(it,  EINA_FALSE);
    -}
    -
    - - -

    Map

    - -

    Figure: Map hierarchy

    -

    Map hierarchy

    - -

    The map component displays a geographic map. The default map data are provided by the OpenStreetMap project (http://www.openstreetmap.org/). Custom providers can also be added.

    - -

    This component supports:

    -
      -
    • Zooming
    • -
    • Scrolling
    • -
    • Markers with content to be displayed when the user clicks over them
    • -
    • Group of markers
    • -
    • Routes
    • -
    - -

    The map component implements the scroller interface so that all the functions that work with the scroller component also work with maps.

    - -

    Adding a Map Component

    - -

    Once created with the elm_map_add() function, zoom level x12 can be set.

    - -
    -Evas_Object *map, *parent;
    -
    -map = elm_map_add(parent);
    -elm_map_zoom_mode_set(map, ELM_MAP_ZOOM_MODE_MANUAL);
    -elm_map_zoom_set(map, 12);
    -
    - -

    Here the zoom mode is set to manual, but it can also be set to the ELM_MAP_ZOOM_MODE_AUTO_FIT mode and the ELM_MAP_ZOOM_MODE_AUTO_FILL mode. In that case however, the elm_map_zoom_set() function cannot be used.

    - -

    Playing with the Map

    - -

    If you have coordinates of a specific area (2 2 N, 48 8 E), it can be shown on the map.

    -
    -elm_map_region_show(map, 2.2, 48.8);
    -
    - -

    This shows the desired coordinates. The location can also be shown with a bring-in animation.

    -
    -elm_map_region_bring_in(map, 2.2, 48.8);
    -
    - -

    The map is rotated 90 degrees around the current position.

    -
    -elm_map_rotate_set(map, 90, 2.2, 48.8);
    -
    - -

    Drawing Overlays

    - -

    Overlays are markers that can be placed anywhere on the map. They can represent any object you want to put on the map.

    - -

    Creating an Overlay Class

    - -

    Overlay classes can be created if several objects are of the same type. For example, you can create a forest overlay class to represent the forests visible on the map. To do this, set the minimum zoom level at which this class is visible. The forest class overlay is visible when the zoom level is superior to eight.

    - -

    Set an icon ("Home" icon) to the forest class. This icon is displayed in place of the forest class on the map.

    -
    -Evas_Object *icon;
    -Elm_Map_Overlay *forest_class = elm_map_overlay_class_add(map);
    -
    -// Set min zoom level at which class is displayed
    -elm_map_overlay_displayed_zoom_min_set(forest_class, 8);
    -
    -// Create a Home icon object and set it to the forest class 
    -icon = elm_icon_add(map);
    -elm_icon_standard_set(icon, "home");
    -elm_map_overlay_icon_set(forest_class, icon);
    -
    - -

    Adding Overlays to a Class

    - -

    After creating a forest class, it is possible to add overlay objects to it. Here an overlay for the Meudon forest is created. The data is linked to the overlay with the elm_map_overlay_data_set() function. Set the name of the forest in the data. The icon can be set to the overlay with the elm_map_overlay_icon_set() function.

    - - - - - - - - - - -
    Note
    Do not use the same icon object for two different overlays. Create a new icon object each time you need one.
    - -
    -Elm_Map_Overlay *ovl;
    -const char* data_meudon = "Meudon forest";
    -const char* data_fausses = "Fausse forest";
    -
    -// Add an overlay
    -ovl = elm_map_overlay_add(map, 2.20718, 48.79759);
    -icon = elm_icon_add(map);
    -elm_icon_standard_set(icon, "stop");
    -elm_map_overlay_icon_set(ovl, icon);
    -elm_map_overlay_data_set(ovl, &data_meudon);
    -
    -// Add the new ovl object to the forest class 
    -elm_map_overlay_class_append(forest_class, ovl);
    -
    -// Add another overlay next to the first one 
    -ovl = elm_map_overlay_add(map, 2.1699, 48.8189);
    -icon = elm_icon_add(map);
    -elm_icon_standard_set(icon, "stop");
    -elm_map_overlay_icon_set(ovl, icon);
    -elm_map_overlay_data_set(ovl, &data_fausses);
    -elm_map_overlay_class_append(forest_class, ovl);
    -
    - -

    If you add another overlay to the forest class, the two overlays can be grouped under the forest class icon on certain zoom level conditions. You can define on which zoom level items are grouped.

    -
    -elm_map_overlay_class_zoom_max_set(forest_class, 8);
    -
    - -

    In this case, overlay members of the forest class are grouped when the map is displayed at less than zoom level eight.

    - -

    Creating Bubbles Following Overlays

    - -

    The following example shows how to set a content in a bubble following an overlay.

    - -
    -// Add an overlay bubble object 
    -Elm_Map_Overlay *bubble = elm_map_overlay_bubble_add(map);
    -
    -// Set it to follow a specific overlay (the last created one here) 
    -elm_map_overlay_bubble_follow(bubble, ovl);
    -
    - -

    Once following an overlay, the bubble appears, moves or hides following the parent overlay's behavior.

    - -

    Content is added to the bubble with the elm_map_overlay_bubble_content_append() function.

    - -

    Adding Other Overlays

    - -

    You can draw a circle on the map with coordinates and a radius size.

    -
    -Elm_Map_Overlay *circle = elm_map_overlay_circle_add(map, 2.2, 48.8, 0.02);
    -
    - -

    You can also add a scale at the 200x0 coordinate (in pixels).

    -
    -Elm_Map_Overlay *scale = elm_map_overlay_scale_add(map, 200, 0);
    -
    - -

    You can also draw a line, a polygon, or a route. For a full description of these functions, see the Map API.

    - -

    Calculating Routes

    - -

    A route between a starting point and an ending point is calculated with the elm_map_route_add() call. The type of transport and the routing calculation method can be provided so as to have the desired result.

    - -

    The following example shows how to get a route calculation between the first and the second overlay. It is configured to use the bicycle, and to find the fastest route possible.

    - -
    -Elm_Map_Route *route = elm_map_route_add(map,
    -         ELM_MAP_ROUTE_TYPE_BICYCLE,
    -         ELM_MAP_ROUTE_METHOD_FASTEST,
    -         2.20718, 48.79759,
    -         2.1699, 48.8189,
    -         NULL, NULL);
    -
    -// Add a callback to when the route has been calculated and loaded 
    -evas_object_smart_callback_add(map, "route,loaded", _route_loaded_cb, route);
    -
    - -

    Once the route is calculated, create a route overlay object and change its color. In this example, the route,loaded callback is used.

    -
    -static void
    -_route_loaded_cb(void *data, Evas_Object *obj, void *ev)
    -{
    -   Elm_Map_Route *route = data;
    -
    -   Elm_Map_Overlay *route_ovl = elm_map_overlay_route_add(obj, route);
    -   elm_map_overlay_color_set(route_ovl, 0, 255, 0, 255);
    -}
    -
    - -

    Using Map Callbacks

    - -

    The map component emits the following callbacks:

    -
      -
    • clicked: The user has clicked the map without dragging around.
    • -
    • clicked,double: The user has double-clicked the map.
    • -
    • press: The user has pressed down on the map.
    • -
    • longpressed: The user has pressed down on the map for a long time without dragging around.
    • -
    • scroll: The content is scrolled (moved).
    • -
    • scroll,drag,start: Dragging the contents around starts.
    • -
    • scroll,drag,stop: Dragging the contents around stops.
    • -
    • scroll,anim,start: Scrolling animation starts.
    • -
    • scroll,anim,stop: Scrolling animation stops.
    • -
    • zoom,start: Zoom animation starts.
    • -
    • zoom,stop: Zoom animation stops.
    • -
    • zoom,change: The zoom is changed when using an auto zoom mode.
    • -
    • tile,load: A map tile image load begins.
    • -
    • tile,loaded: A map tile image load ends.
    • -
    • tile,loaded,fail: A map tile image load fails.
    • -
    • route,load: Route request begins.
    • -
    • route,loaded: Route request ends.
    • -
    • route,loaded,fail: Route request fails.
    • -
    • name,load: Name request begins.
    • -
    • name,loaded: Name request ends.
    • -
    • name,loaded,fail: Name request fails.
    • -
    • overlay,clicked: An overlay is clicked.
    • -
    • loaded: The map is loaded.
    • -
    - - -

    Notify

    - -

    Figure: Notify hierarchy

    -

    Notify hierarchy

    - -

    The notify component displays a container in a particular region of the parent object. It can receive some content, and can be automatically hidden after a certain amount of time.

    - -

    Adding a Notify Component

    - -

    The following example shows how to create a notify object.

    -
    -Evas_Object *notify, *parent;
    -notify = elm_notify_add(parent);
    -
    - -

    Configuring the Notify Component

    - -

    Create a label and add it to the notify object.

    -
    -Evas_Object *content;
    -
    -// Create the label and set some text to it 
    -content = elm_label_add(parent);
    -
    -elm_object_text_set(content, "A label text");
    -evas_object_show(content);
    -
    -// Add the label object to the notify component
    -elm_object_content_set(notify, content);
    -
    - -

    In the following example the notify object is shown on the bottom left corner of the parent object.

    -
    -elm_notify_align_set(notify, 1.0, 1.0);
    -evas_object_show(notify);
    -
    - -

    Set a timeout interval, after which the notify component is hidden. In the following example the timeout interval is five seconds.

    -
    -elm_notify_timeout_set(notify, 5.0);
    -
    - -

    Using Notify Callbacks

    - -

    The notify component emits the following signals:

    -
      -
    • timeout: The timeout count ends and the notify component is hidden
    • -
    • block,clicked: The user clicks outside of the notify component
    • -
    - -

    For both these signals event_info is NULL.

    - -

    The following example shows how to register a callback on the timeout signal.

    - -
    -{
    -   evas_object_smart_callback_add(notify, "timeout", timeout_cb, data);
    -}
    -
    -// Callback function for the "timeout" signal
    -// The timeout expires and the notify object is hidden
    - 
    -void timeout_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   dlog_print(DLOG_INFO, LOG_TAG, "Notify is hidden\n");
    -}
    -
    - -

    Plug

    - -

    Figure: Plug hierarchy

    -

    Plug hierarchy

    - -

    The plug component shows an Evas_Object created by an other process. It can be used anywhere the same way as any other elementary UI component.

    - -

    Adding a Plug Component

    - -

    The following example shows how to create a plug.

    -
    -Evas_Object *plug, *parent;
    -plug = elm_plug_add(parent);
    -
    - -

    Using the Plug

    - -

    The socket image provides the service where to connect the plug object with the elm_plug_connect() function. In this process, use the service name and number set by the socket you want to connect to.

    - -

    As an example, connect to a service named plug_test on the number 0.

    - -
    -elm_plug_connect(plug, "plug_test", 0, EINA_FALSE);
    -
    - -

    The Evas_Object corresponding to the distant image is retrieved with the elm_plug_image_object_get() function.

    - -
    -Evas_Object *plug_img = elm_plug_image_object_get(plug);
    -
    - - - - - - - - - - -
    Note
    The socket to connect to must be started with the elm_win_socket_listen() function in the other process on the remote window object (it is called remote_win here).
    - -
    -// Create a remote window in the other process 
    -Elm_Win *remote_win = elm_win_add(NULL, "Window Socket",
    -                                  ELM_WIN_SOCKET_IMAGE);
    -// Create a socket named "plug_test" and listen to it
    -elm_win_socket_listen(remote_win, "plug_test", 0, EINA_FALSE);
    -
    - - - -

    Figure: Popup component

    -

    Popup component

    - -

    Figure: Popup hierarchy

    -

    Popup hierarchy

    - - -

    The popup component shows a popup area that can contain:

    -
      -
    • a title area (optional)
    • -
    • a content area
    • -
    • an action area (optional)
    • -
    - -

    The optional title area can contain an icon and text, the action area can contain up to three buttons.

    - -

    Adding a Popup Component

    - -

    The following example shows how to create a popup component.

    -
    -Evas_Object *popup, *parent;
    -
    -// Create a popup 
    -popup = elm_popup_add(parent);
    -
    - -

    Using Popup Styles

    - -

    The following item styles are available for wearable core controls:

    -
      -
    • popup
    • -
    • toast
    • -
    -

    The following item styles are available for Gear O:

    -
      -
    • circle
    • -
    • toast/circle
    • -
    -

    The following layout styles are available for Gear O:

    -
      -
    • content/circle
    • -
    • content/circle/buttons1
    • -
    • content/circle/buttons2
    • -
    - -

    The following example sets the style of the popup to toast.

    -
    -elm_object_style_set(popup, "toast");
    -
    - - -

    Setting the Popup Areas in Wearable Core Controls

    -

    Configure the title area. Set the title text to Test popup using the partname title,text.

    - -
    -elm_object_part_text_set(popup, "title,text", "Test popup");
    -
    -

    Set the content of the popup. The content can be simple text.

    -
    -elm_object_text_set(popup, "simple text");
    -
    -

    The content can also be an Evas object.

    -
    -Evas_Object *content;
    -
    -elm_object_content_set(popup, content);
    -
    -

    Set the buttons of the action area by creating an OK button and a Cancel button.

    -
    -Evas_Object *button1, *button2;
    -
    -// Create the two buttons 
    -button1 = elm_button_add(popup);
    -elm_object_style_set(button1, "popup");
    -evas_object_size_hint_weight_set(button1, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
    -elm_object_text_set(button1, "Cancel");
    -
    -button2 = elm_button_add(popup)
    -elm_object_style_set(button2, "popup");
    -evas_object_size_hint_weight_set(button2, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
    -elm_object_text_set(button2, "OK");
    -
    -evas_object_show(popup);
    -
    -// Set the buttons to the action area 
    -elm_object_part_content_set(popup, "button1", button1);
    -elm_object_part_content_set(popup, "button2", button2);
    -
    - -

    Setting the Popup Areas in Gear O

    -

    Set the circle style and the layout of the popup.

    -
    -// Setting the style
    -elm_object_style_set(popup, "circle");
    -
    -// Setting the layout
    -layout = elm_layout_add(popup);
    -elm_layout_theme_set(layout, "layout", "popup", "content/circle/buttons2");
    -
    - -

    To configure the title area, set the title text to Test popup using the partname elm.text.title.

    -
    -// Setting the title text 
    -elm_object_part_text_set(layout, "elm.text.title", "Text popup");
    -
    - -

    Set the content of the popup. The content can be simple text.

    -
    elm_object_part_text_set(layout, "elm.text.content", "Test popup");
    -
    - -

    The content of the popup can also be an Evas object.

    -
    -Evas_Object *content;
    -
    -elm_object_content_set(layout, content);
    -
    -

    Set the popup content.

    -
    -elm_object_content_set(popup, layout);
    -
    - -

    Set the buttons of the action area by creating an OK button, a Cancel button, and a Help button.

    - -
    -Evas_Object *button1, *button2, *icon;
    -
    -// Create the 2 buttons 
    -
    -button1 = elm_button_add(popup);
    -elm_object_style_set(button1, "popup/circle/left");
    -icon = elm_image_add(button1);
    -elm_image_file_set(icon, ICON_DIR"/b_option_list_icon_share.png", NULL);
    -evas_object_size_hint_weight_set(icon, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
    -elm_object_part_content_set(button1, "elm.swallow.content", icon);
    -evas_object_show(icon);
    -
    -button2 = elm_button_add(popup);
    -elm_object_style_set(button2, "popup/circle/right");
    -icon = elm_image_add(button2);
    -elm_image_file_set(icon, ICON_DIR"/b_option_list_icon_delete.png", NULL);
    -evas_object_size_hint_weight_set(icon, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
    -elm_object_part_content_set(button2, "elm.swallow.content", icon);
    -evas_object_show(icon);
    -
    -// Set the buttons to the action area 
    -elm_object_part_content_set(popup, "button1", button1);
    -elm_object_part_content_set(popup, "button2", button2);
    -
    -
    - -

    Using Popup Callbacks

    -

    The popup emits the following signals:

    -
      -
    • timeout: The popup is closed as a result of timeout.
    • -
    • block,clicked: The user clicks on the Blocked Event area.
    • -
    - -

    elm_popup_timeout_set() is used to hide the popup after a certain time. In the following example the timeout is set to five seconds.

    -
    elm_popup_timeout_set(popup, 5.0);
    - -

    When the timeout expires, the timeout signal is sent to the user.

    -
    -{
    -   evas_object_smart_callback_add(popup, "timeout", _timeout_cb, data);
    -}
    -
    -static void
    -_timeout_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   dlog_print(DLOG_INFO, LOG_TAG, "Timeout \n");
    -}
    -
    - -

    The visible region of the popup is surrounded by a translucent region called Blocked Event area. By clicking on this area, the signal block,clicked is sent to the application.

    - - -

    Progressbar

    - -

    Figure: Progressbar component

    -

    Progressbar component

    - -

    Figure: Progressbar hierarchy

    -

    Progressbar hierarchy

    - - -

    Adding a Progressbar Component

    - -

    This UI component is used to display the progress status of a given job. It inherits from the layout component, so all function concerning the layout component is used on the progressbar component.

    -

    The following example shows how to create a progressbar component.

    -
    -Evas_Object *pb = elm_progressbar_add(win);
    -
    - -

    Using the Progressbar Styles

    - -

    The progressbar has several styles for wearable core controls:

    -
      -
    • default
    • -
    • pending_list
    • -
    • process
    • -
    • process/groupindex
    • -
    • process/popup/small
    • -
    -

    The progressbar has several styles for Gear O:

    -
      -
    • process
    • -
    • process/small
    • -
    - -

    Set the style of the progressbar to pending_list.

    - -
    -elm_object_style_set(pb, "pending_list");
    -
    - -

    Configuring the Progressbar for Wearable Core Control

    - -

    The progressbar pulse mode is activated to make the progressbar loop infinitely between the start and end position.

    -
    elm_progressbar_pulse_set(pb, EINA_TRUE);
    -elm_progressbar_pulse(pb, EINA_TRUE);
    -
    - -

    The progressbar can be inverted. In that mode, the values are inverted so that the high values are on the left and the low values on the right.

    -
    elm_progressbar_inverted_set(pb, EINA_TRUE);
    - -

    The progressbar emits the changed signal when the progress value changes. The value is changed with the elm_progressbar_value_set() function. Here the pb progress value is set to 20%.

    -
    elm_progressbar_value_set(pb, 0.2);
    - -

    It is possible to read the current value.

    -
    double value = elm_progressbar_value_get(pb);
    - -

    Configuring the Progressbar for Gear O

    -

    The progressbar emits the changed signal when the progress value changes. The value is changed with the elm_progressbar_value_set() function. Here the pb progress value is set to 20%.

    - -
    -elm_progressbar_value_set(pb, 0.2);
    -
    -

    The current value can be read.

    -
    -double value = elm_progressbar_value_get(pb);
    -
    - - -

    Using the Progressbar Callbacks

    - -

    The changed signal is the only signal specifically emitted by the progressbar component.

    -

    The following example shows how to register a callback on this signal.

    - -
    -{
    -   evas_object_smart_callback_add(pb, "changed", changed_cb, data);
    -}
    -
    -// Callback function for the "changed" signal
    -// This callback is called when the progressbar value changes
    -void changed_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   dlog_print(DLOG_INFO, LOG_TAG, "The value has changed\n");
    -}
    -
    - - -

    Radio

    - -

    Figure: Radio component

    -

    Radio component

    - -

    Figure: Radio hierarchy

    -

    Radio hierarchy

    - -

    This UI component displays one or more options, but the user can only select one of them. It is composed of an indicator (selected or unselected). Even though it is usually grouped with two or more other radio objects, it can also be used alone. -

    -

    The radio component inherits from the layout component. All the layout functions can be used with radio objects.

    - -

    Adding a Radio Component

    - -

    Create a radio component.

    -
    -Evas_Object *radio, *parent;
    -
    -// Create a radio
    -radio = elm_radio_add(parent);
    -
    - -

    Changing the Radio Value

    - -

    The user can select one of a set of values with the radio component. Each radio object from a group of radio objects represents an integer value. Here the value 1 is set to the new radio object.

    -
    -elm_radio_state_value_set(radio, 1);
    -
    - -

    Managing the Radio Groups

    - -

    The following example shows how to create a group of radio objects with at least two radio components.

    - -
    -// Create another radio object 
    -Evas_Object *radio2 = elm_radio_add(parent);
    -elm_radio_state_value_set(radio2, 2);
    -
    -// Create a group composed of radio and radio2
    -Evas_Object *group = radio;
    -elm_radio_group_add(radio2, group);
    -
    - -

    Now that a group composed of two radio objects has been created, you can choose which one is selected. In this example radio2 is selected.

    - -
    elm_radio_value_set(group, 2);
    - -

    You can use elm_radio_value_get() to see the currently selected radio of the group.

    - -

    Using the Radio Callbacks

    - -

    This UI component emits the following signals:

    -
    • changed: The state of a radio is modified in a group of radio objects.
    - -

    The following example shows how to register a callback on this signal.

    -
    -{
    -   evas_object_smart_callback_add(radio, "changed", changed_cb, data);
    -}
    -
    -// Callback function for the "changed" signal
    -// This callback is called when the radio value changes
    -void changed_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   dlog_print(DLOG_INFO, LOG_TAG, "The value has changed\n");
    -}
    -
    - -

    Using the Radio Callbacks with Gear O

    - -

    This UI component emits the following signals:

    -
      -
    • changed: The user changes the slider value.
    • -
    • clicked: Radio was clicked.
    • -
    - -

    The following example shows how to register a callback on this signal.

    -
    -{
    -   evas_object_smart_callback_add(radio, "clicked", clicked_cb, data);
    -}
    -
    -// Callback function for the "changed" signal
    -// This callback is called when the radio value changes
    -void changed_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   dlog_print(DLOG_INFO, LOG_TAG, "This radio was clicked\n");
    -}
    -
    - - -

    Slider for the Wearable Core

    - -

    Figure: Slider component

    -

    Slider component

    - -

    Figure: Slider hierarchy

    -

    Slider hierarchy

    - -

    The slider component is a draggable bar that is used to select a value within a certain range.

    - -

    Adding a Slider Component

    - -

    The following example shows how to create a slider object.

    -
    -Evas_Object *slider, *parent;
    -
    -slider = elm_slider_add(parent);
    -
    - -

    Using the Slider Styles

    - -

    A slider has the following styles:

    -
      -
    • default
    • -
    - -

    Configuring the Slider

    - -

    It can contain icons (elm.swallow.icon partname), a label, a unit label and an indicator label.

    -
    -Evas_Object *icon1, *icon2;
    -
    -// Set the icons 
    -elm_object_part_content_set(slider, "elm.swallow.icon", icon1);
    -
    -// Set the unit format 
    -elm_slider_unit_format_set(slider, "%1.2f meters");
    -
    - -

    Before using the slider, its minimum and maximum values are set with elm_slider_min_max_set(). The current value is set with (elm_slider_value_set()). The following example sets the minimum value to 0, the maximum value to 100, and the current value to 50.

    -
    -elm_slider_min_max_set(slider, 0.0, 100.0);
    -elm_slider_value_set(slider, 50.0);
    -
    - -

    The span of the slider represents its length horizontally. It is set with elm_slider_span_size_set() and is scaled by the object or applications scaling factor.

    -

    You can retrieve the current value of the slider anytime.

    -
    -double value = elm_slider_value_get(slider);
    -
    - -

    By default, the slider indicator becomes bigger when the user drags it. This can be disabled if you want the slider indicator to keep its default size. The following example sets the state of the indicator enlargement and then inverts the behavior.

    -
    -// Get the current state of the indicator 
    -Eina_Bool enlarge = elm_slider_indicator_show_get(slider);
    -
    -// Invert the behavior 
    -elm_slider_indicator_show_set(slider, !enlarge);
    -
    - -

    Using the Slider Callbacks

    - -

    This UI component emits the following signals:

    -
      -
    • changed: The user changes the slider value.
    • -
    • slider,drag,start: Dragging the slider indicator around starts.
    • -
    • slider,drag,stop: Dragging the slider indicator around stops.
    • -
    • delay,changed: A short time after the user changes the value. This is called only when the user stops dragging for a very short period or when releases the finger or mouse, so that it avoids possibly expensive reactions to the value change.
    • -
    - -

    For all these signals, event_info is NULL.

    -

    The following example shows how to register a callback on the changed signal.

    -
    -{
    -   evas_object_smart_callback_add(slider, "changed", changed_cb, data);
    -}
    -
    -// Callback function for the "changed" signal
    -// This callback is called when the slider value changes
    -void changed_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   dlog_print(DLOG_INFO, LOG_TAG, "The slider has changed\n");
    -}
    -
    - - - -

    Win

    - -

    Figure: Win hierarchy

    -

    Win hierarchy

    - - -

    The window component is the root UI component that is often used in an application. It allows the developer create content in it, and it is handled by the window manager.

    -

    The window component is created with the elm_win_add() or elm_win_util_standard_add() function. The content can be added in the window with elm_win_resize_object_add() so that a window resize also resizes the content inside.

    - -

    Adding a Window Component

    - -

    Create a new window and change the title.

    -
    -Evas_Object *window;
    -
    -// Create a window 
    -window = elm_win_add(NULL, "main", ELM_WIN_BASIC);
    -
    -// Change the window title 
    -elm_win_title_set(window, "Example Window");
    -
    - -

    The first element of elm_win_add() is the parent window. For example, for a dialog you want to have the main window as the parent. Here, it is NULL, meaning there is no parent. main is the name of the window used by the window manager for identifying the window uniquely amongst all the windows within this application (and all instances of the application). The type is a basic window (the final parameter).

    - -

    Create a new window with a title and a background. This API is a shortcut of the previous one. It also creates a standard background to the window with elm_bg_add(). The window created is of the type ELM_WIN_BASIC.

    - -
    -Evas_Object *window;
    -
    -// Create a standard window 
    -window = elm_win_util_standard_add("main", "Example Window");
    -
    - -

    Closing a Window

    -

    When the user closes the window outside of the program control, a delete,request signal is emitted to indicate that this event occurred. The developer can take any action, for example, destroy the window object.

    -

    When the autodel parameter is set, the window is automatically destroyed after the signal is emitted. If autodel is EINA_FALSE, the window is not destroyed and the program does so when required. The default is EINA_FALSE, where the window is not destroyed automatically.

    -

    The autodel is set using the following call:

    -
    -elm_win_autodel_set(window, EINA_TRUE);
    -
    - -

    To close the window, use the evas_object_del() function. The window is destroyed and the signal delete,request is sent.

    - -

    Using the Window Callbacks

    -

    The window component emits the following signals:

    -
      -
    • delete,request: The window is requested delete.
    • -
    • focus,in: The window received focus.
    • -
    • focus,out: The window lost focus.
    • -
    • moved: The window that holds the canvas is moved.
    • -
    • withdrawn: The window is managed normally but is removed from the view.
    • -
    • iconified: The window is minimized (for example, into an icon or a taskbar).
    • -
    • normal: The window is in the normal state (not withdrawn or iconified).
    • -
    • stick: The window shows on all desktops.
    • -
    • unstick: The window shows only on one desktop.
    • -
    • fullscreen: The window is fullscreen.
    • -
    • unfullscreen: The window stops being fullscreen.
    • -
    • maximized: The window is maximized.
    • -
    • unmaximized: The window is diminished.
    • -
    • wm,rotation,changed: The rotation of the window is changed by the Windows Manager.
    • -
    • ioerr: A low-level I/O error occurred in the display system.
    • -
    • indicator,prop,changed: The property or indicator mode and indicator opacity are changed.
    • -
    • rotation,changed: The rotation of the window is changed.
    • -
    • profile,changed: The profile of the window is changed.
    • -
    • aux,hint,allowed: aux_hint of the window free.
    • -
    • access,changed: The access function of the window is changed.
    • -
    -

    With all these signals, event_info is NULL.

    -

    The following example registers a callback function called on the fullscreen signal.

    -
    -{
    -   evas_object_smart_callback_add(window, "fullscreen", fullscreen_cb, data);
    -}
    -
    -// Callback function for the "fullscreen" signal
    -// This callback is called when the window becomes fullscreen
    -void fullscreen_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   dlog_print(DLOG_INFO, LOG_TAG, "Window fullscreen\n");
    -}
    -
    - - - - - -
    - -Go to top - - - - - - - - diff --git a/org.tizen.guides/html/native/ui/containers_mn.htm b/org.tizen.guides/html/native/ui/containers_mn.htm deleted file mode 100644 index 5c6155b..0000000 --- a/org.tizen.guides/html/native/ui/containers_mn.htm +++ /dev/null @@ -1,610 +0,0 @@ - - - - - - - - - - - - - - Containers - - - - - - -
    -

    Containers

    - - - - - - - - - - -
    Note
    This feature is supported in mobile applications only.
    - -

    Box

    - - -

    Figure: Box container

    -

    Box container

    - - -

    Most of the time, you want to display UI components on the screen in a specific order. In Form Tutorial, for example, the user information is arranged vertically. This basic container is called a box. There is no theme for a box layout. It is just a linear method of arranging UI components horizontally or vertically.

    -

    Creating a Box

    -

    To create a new horizontal box:

    -
    Evas_Object *vbox;
    -
    -vbox = elm_box_add(parent);
    -
    -

    By default, the elm_box_add() function creates a vertical box. If you want to create a horizontal box, use the elm_box_horizontal_set() function:

    -
    Evas_Object *hbox;
    -
    -hbox = elm_box_add(parent);
    -elm_box_horizontal_set(hbox, EINA_TRUE);
    -
    - - - - - - - - - - -
    Note
    A box is a non-graphical object. It adds no graphics to or around the objects it holds.
    - -

    Adding Objects to the Box

    -

    You can add any Evas object to the box. Here, we create 5 button components and add them to a box:

    -
    int i;
    -Evas_Object *bt;
    -Evas_Object *vbox;
    -
    -vbox = elm_box_add(parent);
    -
    -for (i = 0; i < 5; i++)
    -{
    -   char tmp[16];
    -   snprintf(tmp, sizeof(tmp), "Button %d", i);
    -   bt = elm_button_add(vbox);
    -   elm_object_text_set(bt, tmp);
    -   elm_box_pack_end(vbox, bt);
    -   evas_object_show(bt);
    -}
    -evas_object_show(vbox);
    -
    -

    The most important function in the above code is elm_box_pack_end(), which is used to add the button component to the end of the box.

    - -

    Setting the Padding

    -

    You can set the padding between the objects in a box by using the elm_box_padding_set() function. The padding values are the number of pixels horizontally and vertically.

    -
    elm_box_padding_set(vbox, 16, 64);
    -
    - -

    Handling Element Size

    -

    You can add different-size elements to a container. For example, to add an image with a size of 128x128 pixels as the first element in a box, use the elm_box_pack_start() function:

    -
    ic = elm_icon_add(vbox);
    -elm_image_file_set(ic, "./c1.png", NULL);
    -evas_object_size_hint_min_set(ic, 128, 128);
    -evas_object_show(ic);
    -elm_box_pack_start(vbox, ic);
    -
    -

    We ask Evas to set the size hint for the icon object by using the elm_object_size_hint_min_set() function. Evas will try to set the minimum size of this object accordingly.

    -

    If you want to create a homogeneous box, where all objects have the same height or width, depending on the orientation of the box, use the elm_box_homogeneous_set() function:

    -
    elm_box_homogeneous_set(vbox, EINA_TRUE);
    -
    -

    Elementary will set the height of the tallest object as the height of all objects, or the width of the widest element as the width of all objects.

    -

    Setting the Alignment

    -

    You can set the alignment of UI components inside a box using the elm_box_align_set() function. The function takes two doubles values, a horizontal value and a vertical value, representing the percentage between 0 and 1.0 of the alignment in the horizontal and vertical axes. When you add a UI component with the elm_box_pack_end() or elm_box_pack_start() function, Elementary computes the global size of the box. If the global size is bigger than the size of the box's parent, the box will take up all the space occupied by the parent, and the size of the parent may be extended to hold the box. If the global size is smaller than the parent's size, the alignment values will set the position of the box inside the parent.

    - -

    Figure: Alignment

    -

    Alignment

    - -

    Here, we set an alignment of 0.8 vertically:

    -
    elm_box_align_set(vbox, 0.0, 0.8);
    -
    - - - - - - - - - - -
    Note
    The alignment only takes effect in the opposite direction than the one defined with the elm_box_horizontal_set() function.
    - - -

    The elm_box_layout_transition() function provides the ability to animate the motion of the objects in a box when switching from one layout to another.

    -

    Using Size Hints

    -

    Size hints are a set of functions that can be used on any Evas object. You request Evas to take care of various properties, and Evas will honor these requests if it can. This is why they are called "hints". The size hint functions are:

    -
      -
    • evas_object_size_hint_min_set()
    • -
    • evas_object_size_hint_max_set()
    • -
    • evas_object_size_hint_aspect_set()
    • -
    • evas_object_size_hint_align_set()
    • -
    • evas_object_size_hint_weight_set()
    • -
    -

    You can also use the respective get functions to get the current hint values.

    -

    In case of the evas_object_size_hint_min_set() function, you ask Evas to respect the minimum size you define for the object. For example, to set the minimum size of an icon to 64x46 pixels:

    -
    evas_object_size_hint_min_set(ic, 64, 64);
    -
    -

    You can also set a maximum size for the same icon:

    -
    evas_object_size_hint_max_set(ic, 128, 128);
    -
    -

    When you resize the parent of the icon, if there are no constraints to the parent, the minimum size of the parent will be the minimum hint size of the icon. If you increase the parent size, the icon will grow larger until its maximum hint size is reached. After this point, the icon will not grow any larger and there will be empty space around the icon within the parent.

    -

    When the aspect size hint is set, Evas tries to fix the dimensional proportions of the object. Here, the proportion of the icon is respected, and the width will be the same as the height:

    -
    evas_object_size_hint_aspect_set(ic, EVAS_ASPECT_CONTROL_VERTICAL, 1, 1);
    -
    -

    Here, the width will be twice the height:

    -
    evas_object_size_hint_aspect_set(ic, EVAS_ASPECT_CONTROL_VERTICAL, 2, 1);
    -
    -

    If we want to change the alignment of the icon relative to the parent, we can use the evas_object_size_hint_align() function. By default, the icon is centered, so it is aligned with a value of 0.5. You can change the alignment as follows:

    -
    evas_object_size_hint_align_set(ic, EVAS_HINT_FILL, EVAS_HINT_FILL);
    -
    -

    In the above case, the icon is aligned to the bottom left corner of the parent.

    -

    We can also play with the size of the icon inside its container by using the weight size hint. By default, the weight is not set, so the size of the icon will be the minimum size. But if you set this value to 1, the icon will be expand as much as it can inside the container:

    -
    evas_object_size_hint_weight_set(ic, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
    -
    -

    You can also use the alignment and weight hints together. Here, we want the icon to take up all the space in its parent:

    -
    evas_object_size_hint_align_set(ic, EVAS_HINT_FILL, EVAS_HINT_FILL);
    -evas_object_size_hint_weight_set(ic, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
    -
    - - -

    Conformant

    - -

    Figure: Conformant container

    -

    Conformant container

    - -

    A conformant is a container UI component that accounts for the space taken by the indicator, virtual keyboard, and softkey windows. The content area of the conformant is resized and positioned based on the space available. When the virtual keyboard is displayed, the content area is not resized.

    - -

    Creating a Conformant

    -

    To create a conformant, use the elm_conformant_add() function:

    -
    -Evas_Object *conformant;
    -
    -conformant = elm_conformant_add(parent);
    -
    - -

    Adding Content to the Conformant

    -

    To add content to the conformant, use the elm_object_content_set() function:

    -
    elm_object_content_set(conformant, main_view);
    -
    - -

    Signals

    -

    To receive notifications about the state of the virtual keyboard and clipboard, listen to the following Evas signals:

    -
      -
    • "virtualkeypad,state,on": The virtual keyboard has been switched on.
    • -
    • "virtualkeypad,state,off": The virtual keyboard has been switched off.
    • -
    • "virtualkeypad,size,changed": The virtual keyboard size has changed.
    • -
    • "clipboard,state,on": The clipboard has been switched on.
    • -
    • "clipboard,state,off": The clipboard has been switched off.
    • -
    - - -

    Grid

    - -

    In a grid, objects are placed at specific positions along a fixed grid, where the position of each object is given as a percentage of the full width and height of the grid. By default, the size of the grid is 100 x 100 pixels.

    - -

    Creating a Grid

    -

    To create a grid, use the elm_grid_add() function:

    -
    Evas_Object *grid;
    -
    -grid = elm_grid_add(parent);
    -

    Adding Items to the Grid

    -

    To add an item to the grid, use the elm_grid_pack_set() function. Provide the X and Y coordinates, and the width and height in the grid as parameters. The following code adds 12 icons in a circle formation:

    -
    for (i = 0; i < 12; i++)
    -{
    -   ic = elm_icon_add(grid);
    -   elm_image_file_set(ic, "c1.png", NULL);
    -   evas_object_size_hint_min_set(ic, 128, 128);
    -   evas_object_show(ic);
    -   x = 40 * cos(2.0 * M_PI / 12 * i);
    -   y = 40 * sin(2.0 * M_PI / 12 * i);
    -   elm_grid_pack(grid, ic,  40 + x,  40 + y,  20 , 20);
    -}
    -evas_object_show(grid);
    -
    - -

    Changing Position and Size

    -

    To change the position of an item in the grid, use the elm_grid_pack_set() function. The first parameter is the item you want to move, and the following parameters are the same as for the elm_grid_pack() function.

    -

    To change the size of the grid, use the elm_grid_size_set() function. You can set the new width and height for the grid. The position and size of the items in the grid are changed accordingly.

    -

    Clearing the Grid

    -

    To clear the grid, use the elm_grid_clear() function. All items are removed from the grid. If you set the clear parameter, all the items are also deleted, with the evas_object_del() function called on each item.

    - - -

    Layout

    - -

    A layout is a container that takes a standard Edje design file and wraps it very thinly in a UI component. Layouts are the basis of a lot of graphics components used in Elementary.

    - -

    An Edje design file describes how the elements of the UI are positioned and how they behave when interacted with. For more information about Edje, see the Edje guide.

    - -

    Creating a Layout

    - -

    To create a new layout, use the elm_layout_add() function:

    -
    Evas_Object *layout;
    -
    -layout = elm_layout_add(parent);
    -
    -

    In Tizen, the layout component is extended to support different kinds of layouts. Rather than define layouts yourself, you can use the following predefined default layouts:

    -
      -
    • application/default: This layout can be used to display content inside a window.
    • -
    • drawer/panel: This layout can be used to create a 2-panel view.
    • -
    • nocontents/default: This layout can be used when there is no content to display, such as in a contact or email.
    • -
    -

    To use the application/default layout:

    -
    Evas_Object *ly;
    -
    -ly = elm_layout_add(parent);
    -elm_layout_theme_set(ly, "layout", "application", "default");
    -
    - -

    Adding Objects to the Layout

    -

    To add an Evas object to the layout:

    -
    elm_object_part_content_set(ly, "elm.swallow.content" view);
    -
    -

    elm.swallow.content is the swallow part of the application layout, and with this call you integrate the view inside the swallow object of the layout.

    -

    The drawer/panel layout can display 2 different views, the background and the main content:

    -
    Evas_Object *ly;
    -
    -ly = elm_layout_add(parent);
    -elm_layout_theme_set(ly, "layout", "drawer", "panel");
    -
    -

    To swallow an object inside the main content and background views:

    -
    elm_object_part_content_set(ly, "elm.swallow.content", main_view);
    -elm_object_part_content_set(ly, "elm.swallow.background", background);
    -
    -

    The nocontents/default layout is a special layout in that it does not contain any swallows. You can only set the text part. There are two different texts zones: elm.text and elm.help.text. To change the text:

    -
    elm_object_part_text_set(ly, "elm.text", "Hi All :)");
    -elm_object_part_text_set(ly, "elm.help.text", "Hi All :)");
    -
    -

    Using Layout Themes

    -

    The layout component supports the following predefined default themes:

    -
      -
    • toolbar-content: For applications with a toolbar and main content area.
    • -
    • toolbar-content-back: For applications with a toolbar, main content area (with a back button), and title area.
    • -
    • toolbar-content-back-next: For applications with a toolbar, main content area (with back and next buttons), and title area.
    • -
    • content-back: For applications with main content (with a back button) and title areas.
    • -
    • content-back-next: For applications with main content (with back and next buttons) and title areas.
    • -
    • toolbar-vbox: For applications with a toolbar and main content area as a vertical box.
    • -
    • toolbar-table: For applications with a toolbar and main content area as a table.
    • -
    -

    To set a theme to the layout, use the elm_layout_theme_set() function.

    - - -

    Mapbuf

    - -

    Figure: Mapbuf hierarchy

    -

    Mapbuf hierarchy

    - -

    A mapbuf component is a container UI component that uses an Evas map to hold a content object. This component is used to improve the moving and resizing performance of complex UI components.

    - -

    The content object is treated as a single image by the Evas map. If you have a content object containing several child objects, frequently moving the mapbuf component will be faster than frequently moving the content object.

    - -

    The mapbuf component inherits all the functions of the container class.

    - -

    Creating a Mapbuf

    -

    To create a mapbuf component, use the elm_mapbuf_add() function:

    -
    Evas_Object *mapbuf, *parent, *content;
    -
    -// Creating a mapbuf
    -mapbuf = elm_mapbuf_add(parent);
    -
    -

    Adding Content to the Mapbuf

    -

    To add content to the mapbuf component, use the elm_object_content_set() function with the "default" part:

    -
    elm_object_content_set(mapbuf, content);
    - - - - - - - - - - -
    Note
    Calling elm_object_content_set(mapbuf, content) is equivalent to calling elm_object_part_content_set(mapbuf, "default", content).
    - - -

    To activate smooth map rendering and alpha rendering for the mapbuf component:

    -
    elm_mapbuf_smooth_set(mapbuf, EINA_TRUE);
    -elm_mapbuf_alpha_set(mapbuf, EINA_TRUE);
    -
    - -

    Activating the Mapbuf

    -

    Finally, to use the mapbuf component, you must activate it:

    -
    elm_mapbuf_enabled_set (mapbuf, EINA_TRUE);
    - -

    Signals

    -

    The mapbuf component does not emit any signals and therefore does not provide any callbacks that you can register.

    - - - - -

    A naviframe component consists of a stack of views. New views are pushed on top of previous ones, and only the top-most view on the stack is displayed. The previous views are not deleted. A previous view is displayed when the view on top of it is popped. Transitions can be animated on a push or a pop, depending on the theme applied to the UI component.

    - -

    Creating a Naviframe

    -

    To create a naviframe, use the elm_naviframe_add() function:

    -
    Evas_Object *nav;
    -
    -nav = elm_naviframe_add(parent);
    -
    -

    Adding and Deleting Views

    -

    The naviframe is a stack of views. A new view is always pushed to the top of the stack. The top-most view is deleted by popping it.

    -

    To add a new view to the naviframe:

    -
    Elm_Object_Item *nav_it;
    -
    -nav_it = elm_naviframe_item_push(nav, NULL, NULL, NULL, view, NULL);
    -// In Tizen 2.3, the back button is not supported in the naviframe 
    -
    -

    When you push a new view to the stack, you receive an Elm_Object_Item for the view. You can use this item to modify the view.

    -

    To pop and delete the top-most view:

    -
    elm_naviframe_item_pop(nav);
    -
    - -

    Adding Fixed Content

    -

    The naviframe can also display fixed content on top of the current (top-most) view. Use the elm_object_item_part_content_set() function to set this content. Use the following part names to specify the location of the content:

    -
      -
    • "default": The main content area of the current view.
    • -
    • "icon": An icon in the title area of the current view.
    • -
    • "title_left_btn": A button on the left side of the naviframe.
    • -
    • "title_right_btn": A button on the right side of the naviframe.
    • -
    -

    For example, to add a button to the naviframe:

    -
    btn = elm_button_add(nav);
    -elm_object_style_set(btn, "naviframe/title_cancel");
    -elm_object_item_part_content_set(nav_it, "title_left_btn", btn);
    -
    -

    To set the title labels of the naviframe, use the elm_object_item_part_text_set() function and specify one of the following label locations:

    -
      -
    • "default": Sets the title label in the title area of the current view.
    • -
    • "subtitle": Sets the subtitle label in the title area of the current view.
    • -
    -

    Signals

    -

    The naviframe emits the following signals:

    -
      -
    • "transition,finished": The transition has finished changing the view.
    • -
    • "title,transition,finished": The title area transition has finished changing the state of the title.
    • -
    • "title,clicked": The user has clicked the title area.
    • -
    - - - -

    Panes

    - -

    Figure: Panes component

    -

    Panes component

    - -

    A panes component adds a draggable bar between two sections of content. The sections are resized when the bar is dragged.

    - -

    Creating Panes

    -

    To create a panes component, use the elm_panes_add() function:

    -
    Evas_Object *panes;
    -
    -panes = elm_panes_add(parent);
    -
    - -

    Adding Content to the Panes

    -

    To add content to the panes, use the elm_object_part_content_set() function. The following code adds an object to the left pane:

    -
    elm_object_part_content_set(panes, "left", obj);
    -
    - -

    Setting Panes Options

    -

    To set the orientation of the panes, use the elm_panes_horizontal_set() function.

    - -

    To set the size of the panes, use the elm_panes_content_left_size_set() and elm_panes_content_right_size_set() functions.

    - -

    Signals

    -

    The panes component emits the following signals:

    -
      -
    • "press": The panes component has been pressed (but the press has not been released yet).
    • -
    • "unpress": The press has been released.
    • -
    • "clicked": The panes component has been clicked.
    • -
    • "clicked,double": The panes component has been double-clicked.
    • -
    - - -

    Scroller

    - -

    A scroller holds (and clips) a single object and allows you to scroll across it. This means that the user can use a scroll bar or their finger to drag the viewable region across the object, moving through a much larger area than is contained in the viewport. The scroller will always have a default minimum size that is not limited by its contents.

    -

    The scroller component inherits all the functions of the Layout.

    -

    Creating a Scroller

    -

    To create a scroller, use the elm_scroller_add() function:

    -
    -Evas_Object *scroller;
    -
    -scroller = elm_scroller_add(parent);
    -
    -

    Adding Objects to the Scroller

    -

    To add an object to the scroller, use the elm_object_content_set() function:

    -
    Evas_Object *image;
    -
    -image = elm_image_add(parent);
    -elm_image_file_set(image, "image.png", NULL);
    -evas_object_show(image);
    -evas_object_size_hint_min_set(image, 2560, 1600);
    -elm_object_content_set(scroller, image);
    -
    -

    In the above code, we set a minimum size of 2560 x 1600 pixels for the image. The scroller is smaller than the image, so you can scroll across the image.

    -

    If you want to be informed when the user begins scrolling the image, use the following code:

    -
    -evas_object_smart_callback_add(scroller, "scroll,drag,start", _scroll_start_cb, NULL);
    -
    -// Callback function for the "animate,begin" signal
    -// This callback is called when the user begins scrolling the image
    -void _scroll_start_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   printf("Scroll starts\n");
    -}
    - -

    Managing the Properties of the Scroller

    -

    When scrolling content, the scroller may "bounce" when reaching the edge of the content. This is a visual way of indicating that there is no more content to scroll in that direction. Bounce is enabled by default for both axes. To enable or disable the bounce for either or both axes, use the elm_scroller_bounce_set() function. The following code disables the bounce for the horizontal axis and enables it for the vertical axis:

    - -
    elm_scroller_bounce_set(scroller, EINA_FALSE, EINA_TRUE);
    -
    -

    The scroller can limit the scrolling to "pages". In this case, the scrolling occurs in page-sized chunks of content rather than in a purely continuous fashion, with the scroller displaying a single "page" at a time. This feature sets the size of the page relative to the viewport of the scroller. A size of 1.0 equals 1 viewport (horizontally or vertically). A size of 0.0 disables paging for that axis. These settings are mutually exclusive with page size (see the elm_scroller_page_size_set() function). A size of 0.5 equals half a viewport. Usable size values are normally between 0.0 and 1.0, including 1.0. If you only want a single axis to scroll in pages, use 0.0 for the other axis.

    - -

    Signals

    - -

    The scroller emits the following signals, which you can catch in your application:

    - -
      -
    • "edge,left": The left edge of the content has been reached.
    • -
    • "edge,right": The right edge of the content has been reached.
    • -
    • "edge,top": The top edge of the content has been reached.
    • -
    • "edge,bottom": The bottom edge of the content has been reached.
    • -
    • "scroll": The content has been scrolled (moved).
    • -
    • "scroll,anim,start": The scrolling animation has started.
    • -
    • "scroll,anim,stop": The scrolling animation has stopped.
    • -
    • "scroll,drag,start": Dragging the contents has started.
    • -
    • "scroll,drag,stop": Dragging the contents has stopped.
    • -
    • "vbar,drag": The vertical scroll bar has been dragged.
    • -
    • "vbar,press": The vertical scroll bar has been pressed.
    • -
    • "vbar,unpress": The vertical scroll bar has been unpressed.
    • -
    • "hbar,drag": The horizontal scroll bar has been dragged.
    • -
    • "hbar,press": The horizontal scroll bar has been pressed.
    • -
    • "hbar,unpress": The horizontal scroll bar has been unpressed.
    • -
    • "scroll,page,changed": The visible page has changed.
    • -
    - -

    Example

    -

    A good example of the scroller is a picture slideshow: we add images to the scroller and limit the scrolling to pages (one picture at a time). In the following code, we disable the scroll bars for both axes, limit the scrolling to pages by using the elm_scroller_page_scroll_limit_set() function, and lock the scrolling on the Y axis by using the elm_object_scroll_lock_y_set() function:

    -
    elm_scroller_policy_set(scroller, ELM_SCROLLER_POLICY_OFF, ELM_SCROLLER_POLICY_OFF);
    -elm_scroller_page_scroll_limit_set(scroller, 1, 0);
    -elm_object_scroll_lock_y_set(scroller, EINA_TRUE);
    -
    -

    We create a horizontal box, which will contain all the images, and which itself will be contained by the scroller:

    -
    box = elm_box_add(scroller);
    -elm_box_horizontal_set(box, EINA_TRUE);
    -elm_object_content_set(scroller, box);
    -evas_object_show(box);
    -
    -

    We then create all the images and add them to the horizontal box:

    -
    img = elm_image_add(scroller);
    -snprintf(buf, sizeof(buf), IMAGE_DIR"/%d.jpg", i);
    -elm_image_file_set(img, buf, NULL);
    -evas_object_show(img);
    -pages = eina_list_append(pages, img);
    -elm_box_pack_end(box, img);
    -
    -

    We store references to the images in an eina_list for easy retrieval later.

    -

    Finally, we display the first page of the scroller:

    -
    elm_scroller_page_show(scroller, 0, 0);
    -
    -

    The size of the scroller depends on the size of the parent. When the parent changes, for example when the window is resized or rotated, the scroller is also resized. Since we need to be informed when the scroller is resized, we add a callback on the EVAS_CALLBACK_RESIZE event for the scroller:

    -
    evas_object_event_callback_add(scroller, EVAS_CALLBACK_RESIZE, _scroller_resize_cb, NULL);
    -

    The callback retrieves the new size of the scroller by using the evas_object_geometry_get() function on the object pointer. The pointer is relative to the object that has been resized, which in our case is the scroller itself. We can then iterate through the images of the scroller and set the minimum size to fit the scroller size:

    -
    EINA_LIST_FOREACH(images, l, page)
    -{
    -   evas_object_size_hint_min_set(page, w, h);
    -}
    -
    -

    Finally, we set the page size of the scroller to match the scroller size and display the first page:

    -
    elm_scroller_page_size_set(obj, w, h);
    -elm_scroller_page_show(obj, 0, 0);
    - -

    Table

    - -

    A table is like a box but with 2 dimensions. You have the same kind of APIs as with boxes. An item inside the table can span multiple columns and rows, and even overlap with other items (and it can then be raised or lowered accordingly to adjust stacking if there is overlap).

    - -

    Creating a Table

    - -

    To create a table, use the elm_table_add() function:

    -
    Evas_Object *table;
    -table = elm_table_add(parent);
    - -

    Adding Items to the Table

    - -

    Items are added to the table with the elm_table_pack() function. This function takes as parameters the table, the item to add to the table, and the position where to add the item: column, row, and the size of the item in number of rows and columns (colspan and rowspan). If we want to create an icon that takes 3 columns and rows and a button that only takes 1 row and column, the code will look like this:

    -
    ic = elm_icon_add(table);
    -elm_image_file_set(ic, "icon.png", NULL);
    -evas_object_show(ic);
    -elm_table_pack(table, ic, 0, 0, 3, 3);
    -
    -btn = elm_button_add(table);
    -elm_object_text_set(btn, "Click me i'm famous");
    -evas_object_show(btn);
    -elm_table_pack(table, btn, 3, 1, 1, 1);
    -evas_object_show(table);
    -
    - -

    Managing the Items

    - -

    If you want to change the position of the item after adding it, use the elm_table_pack_set() function. This function takes as parameters the item whose position to change, the new column, the new row, and the size of the item in number of rows and columns (colspan and rowspan).

    - -

    To add padding around the item, use the elm_table_padding_set() function. The second parameter is the padding between columns, and the third parameter is the padding between rows:

    -
    elm_table_padding_set(table, 10, 10);
    - -

    To change the alignment and size of an item, use the evas_object_size_hint parameters. They are used in the same way as with boxes. You can set the same size and weight to each item by using the homogeneous parameter:

    -
    elm_table_homogeneous_set(table, EINA_TRUE);
    -
    - -

    Clearing the Table

    - -

    To clear the table, use the elm_table_clear() function. If the clear parameter is EINA_TRUE, the table items are deleted. The evas_object_del() function will be called on each item.

    - - - - - -
    - -Go to top - - - - - - - - diff --git a/org.tizen.guides/html/native/ui/containers_wn.htm b/org.tizen.guides/html/native/ui/containers_wn.htm deleted file mode 100644 index c8d1ccc..0000000 --- a/org.tizen.guides/html/native/ui/containers_wn.htm +++ /dev/null @@ -1,555 +0,0 @@ - - - - - - - - - - - - - - Containers - - - - - - -
    -

    Containers

    - - - - - - - - - - -
    Note
    This feature is supported in wearable applications only.
    - -

    Box

    - - -

    Figure: Box container

    -

    Box container

    - - -

    Most of the time, you want to display UI components on the screen in a specific order. To arrange the user information in a linear manner, you can use a basic container called a box. There is no theme for a box layout. It is just a linear method of arranging UI components horizontally or vertically.

    -

    Creating a Box

    -

    To create a new horizontal box:

    -
    Evas_Object *vbox;
    -
    -vbox = elm_box_add(parent);
    -
    -

    By default, the elm_box_add() function creates a vertical box. If you want to create a horizontal box, use the elm_box_horizontal_set() function:

    -
    Evas_Object *hbox;
    -
    -hbox = elm_box_add(parent);
    -elm_box_horizontal_set(hbox, EINA_TRUE);
    -
    - - - - - - - - - - -
    Note
    A box is a non-graphical object. It adds no graphics to or around the objects it holds.
    - -

    Adding Objects to the Box

    -

    You can add any Evas object to the box. Here, we create 5 button components and add them to a box:

    -
    int i;
    -Evas_Object *bt;
    -Evas_Object *vbox;
    -
    -vbox = elm_box_add(parent);
    -
    -for (i = 0; i < 5; i++)
    -{
    -   char tmp[16];
    -   snprintf(tmp, sizeof(tmp), "Button %d", i);
    -   bt = elm_button_add(vbox);
    -   elm_object_text_set(bt, tmp);
    -   elm_box_pack_end(vbox, bt);
    -   evas_object_show(bt);
    -}
    -evas_object_show(vbox);
    -
    -

    The most important function in the above code is elm_box_pack_end(), which is used to add the button component to the end of the box.

    - -

    Setting the Padding

    -

    You can set the padding between the objects in a box by using the elm_box_padding_set() function. The padding values are the number of pixels horizontally and vertically.

    -
    elm_box_padding_set(vbox, 16, 64);
    -
    - -

    Handling Element Size

    -

    You can add different-size elements to a container. For example, to add an image with a size of 128x128 pixels as the first element in a box, use the elm_box_pack_start() function:

    -
    ic = elm_icon_add(vbox);
    -elm_image_file_set(ic, "./c1.png", NULL);
    -evas_object_size_hint_min_set(ic, 128, 128);
    -evas_object_show(ic);
    -elm_box_pack_start(vbox, ic);
    -
    -

    We ask Evas to set the size hint for the icon object by using the elm_object_size_hint_min_set() function. Evas will try to set the minimum size of this object accordingly.

    -

    If you want to create a homogeneous box, where all objects have the same height or width, depending on the orientation of the box, use the elm_box_homogeneous_set() function:

    -
    elm_box_homogeneous_set(vbox, EINA_TRUE);
    -
    -

    Elementary will set the height of the tallest object as the height of all objects, or the width of the widest element as the width of all objects.

    -

    Setting the Alignment

    -

    You can set the alignment of UI components inside a box using the elm_box_align_set() function. The function takes two doubles values, a horizontal value and a vertical value, representing the percentage between 0 and 1.0 of the alignment in the horizontal and vertical axes. When you add a UI component with the elm_box_pack_end() or elm_box_pack_start() function, Elementary computes the global size of the box. If the global size is bigger than the size of the box's parent, the box will take up all the space occupied by the parent, and the size of the parent may be extended to hold the box. If the global size is smaller than the parent's size, the alignment values will set the position of the box inside the parent.

    - -

    Figure: Alignment

    -

    Alignment

    - -

    Here, we set an alignment of 0.8 vertically:

    -
    elm_box_align_set(vbox, 0.0, 0.8);
    -
    - - - - - - - - - - -
    Note
    The alignment only takes effect in the opposite direction than the one defined with the elm_box_horizontal_set() function.
    - - -

    The elm_box_layout_transition() function provides the ability to animate the motion of the objects in a box when switching from one layout to another.

    -

    Using Size Hints

    -

    Size hints are a set of functions that can be used on any Evas object. You request Evas to take care of various properties, and Evas will honor these requests if it can. This is why they are called "hints". The size hint functions are:

    -
      -
    • evas_object_size_hint_min_set()
    • -
    • evas_object_size_hint_max_set()
    • -
    • evas_object_size_hint_aspect_set()
    • -
    • evas_object_size_hint_align_set()
    • -
    • evas_object_size_hint_weight_set()
    • -
    -

    You can also use the respective get functions to get the current hint values.

    -

    In case of the evas_object_size_hint_min_set() function, you ask Evas to respect the minimum size you define for the object. For example, to set the minimum size of an icon to 64x46 pixels:

    -
    evas_object_size_hint_min_set(ic, 64, 64);
    -
    -

    You can also set a maximum size for the same icon:

    -
    evas_object_size_hint_max_set(ic, 128, 128);
    -
    -

    When you resize the parent of the icon, if there are no constraints to the parent, the minimum size of the parent will be the minimum hint size of the icon. If you increase the parent size, the icon will grow larger until its maximum hint size is reached. After this point, the icon will not grow any larger and there will be empty space around the icon within the parent.

    -

    When the aspect size hint is set, Evas tries to fix the dimensional proportions of the object. Here, the proportion of the icon is respected, and the width will be the same as the height:

    -
    evas_object_size_hint_aspect_set(ic, EVAS_ASPECT_CONTROL_VERTICAL, 1, 1);
    -
    -

    Here, the width will be twice the height:

    -
    evas_object_size_hint_aspect_set(ic, EVAS_ASPECT_CONTROL_VERTICAL, 2, 1);
    -
    -

    If we want to change the alignment of the icon relative to the parent, we can use the evas_object_size_hint_align() function. By default, the icon is centered, so it is aligned with a value of 0.5. You can change the alignment as follows:

    -
    evas_object_size_hint_align_set(ic, EVAS_HINT_FILL, EVAS_HINT_FILL);
    -
    -

    In the above case, the icon is aligned to the bottom left corner of the parent.

    -

    We can also play with the size of the icon inside its container by using the weight size hint. By default, the weight is not set, so the size of the icon will be the minimum size. But if you set this value to 1, the icon will be expand as much as it can inside the container:

    -
    evas_object_size_hint_weight_set(ic, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
    -
    -

    You can also use the alignment and weight hints together. Here, we want the icon to take up all the space in its parent:

    -
    evas_object_size_hint_align_set(ic, EVAS_HINT_FILL, EVAS_HINT_FILL);
    -evas_object_size_hint_weight_set(ic, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
    -
    - - -

    Conformant

    - -

    Figure: Conformant container

    -

    Conformant container

    - -

    A conformant is a container UI component that accounts for the space taken by the indicator, virtual keyboard, and softkey windows. The content area of the conformant is resized and positioned based on the space available. When the virtual keyboard is displayed, the content area is not resized.

    - -

    Creating a Conformant

    -

    To create a conformant, use the elm_conformant_add() function:

    -
    -Evas_Object *conformant;
    -
    -conformant = elm_conformant_add(parent);
    -
    - -

    Adding Content to the Conformant

    -

    To add content to the conformant, use the elm_object_content_set() function:

    -
    elm_object_content_set(conformant, main_view);
    -
    - -

    Signals

    -

    To receive notifications about the state of the virtual keyboard and clipboard, listen to the following Evas signals:

    -
      -
    • "virtualkeypad,state,on": The virtual keyboard has been switched on.
    • -
    • "virtualkeypad,state,off": The virtual keyboard has been switched off.
    • -
    • "virtualkeypad,size,changed": The virtual keyboard size has changed.
    • -
    • "clipboard,state,on": The clipboard has been switched on.
    • -
    • "clipboard,state,off": The clipboard has been switched off.
    • -
    - - -

    Grid

    - -

    In a grid, objects are placed at specific positions along a fixed grid, where the position of each object is given as a percentage of the full width and height of the grid. By default, the size of the grid is 100 x 100 pixels.

    - -

    Creating a Grid

    -

    To create a grid, use the elm_grid_add() function:

    -
    Evas_Object *grid;
    -
    -grid = elm_grid_add(parent);
    -

    Adding Items to the Grid

    -

    To add an item to the grid, use the elm_grid_pack_set() function. Provide the X and Y coordinates, and the width and height in the grid as parameters. The following code adds 12 icons in a circle formation:

    -
    for (i = 0; i < 12; i++)
    -{
    -   ic = elm_icon_add(grid);
    -   elm_image_file_set(ic, "c1.png", NULL);
    -   evas_object_size_hint_min_set(ic, 128, 128);
    -   evas_object_show(ic);
    -   x = 40 * cos(2.0 * M_PI / 12 * i);
    -   y = 40 * sin(2.0 * M_PI / 12 * i);
    -   elm_grid_pack(grid, ic,  40 + x,  40 + y,  20 , 20);
    -}
    -evas_object_show(grid);
    -
    - -

    Changing Position and Size

    -

    To change the position of an item in the grid, use the elm_grid_pack_set() function. The first parameter is the item you want to move, and the following parameters are the same as for the elm_grid_pack() function.

    -

    To change the size of the grid, use the elm_grid_size_set() function. You can set the new width and height for the grid. The position and size of the items in the grid are changed accordingly.

    -

    Clearing the Grid

    -

    To clear the grid, use the elm_grid_clear() function. All items are removed from the grid. If you set the clear parameter, all the items are also deleted, with the evas_object_del() function called on each item.

    - - -

    Layout

    - -

    A layout is a container that takes a standard Edje design file and wraps it very thinly in a UI component. Layouts are the basis of a lot of graphics components used in Elementary.

    - -

    An Edje design file describes how the elements of the UI are positioned and how they behave when interacted with. For more information about Edje, see the Edje guide.

    - -

    Creating a Layout

    - -

    To create a new layout, use the elm_layout_add() function:

    -
    Evas_Object *layout;
    -
    -layout = elm_layout_add(parent);
    -
    -

    In Tizen, the layout component is extended to support different kinds of layouts. Rather than define layouts yourself, you can use the following predefined default layouts:

    -
      -
    • application/default: This layout can be used to display content inside a window.
    • -
    • nocontents/default: This layout can be used when there is no content to display, such as in a contact or email.
    • -
    • body_thumbnail: This layout can be used when you display an image and text inside a window and the position is already defined internally.
    • -
    - -

    To set a theme to the layout, use the elm_layout_theme_set() function.

    - -

    To use the application/default layout:

    -
    Evas_Object *ly;
    -
    -ly = elm_layout_add(parent);
    -elm_layout_theme_set(ly, "layout", "application", "default");
    -
    - -

    Adding Objects to the Layout

    -

    To add an Evas object to the layout:

    -
    elm_object_part_content_set(ly, "elm.swallow.content" view);
    -
    -

    elm.swallow.content is the swallow part of the application layout, and with this call you integrate the view inside the swallow object of the layout.

    - -

    To swallow an object inside the main content and background views:

    -
    elm_object_part_content_set(ly, "elm.swallow.content", main_view);
    -elm_object_part_content_set(ly, "elm.swallow.background", background);
    -
    -

    The nocontents/default layout is a special layout in that it does not contain any swallows. You can only set the text part with the elm.text text zone. To change the text:

    -
    elm_object_part_text_set(ly, "elm.text", "Hi All :)");
    -
    - -

    Mapbuf

    - -

    Figure: Mapbuf hierarchy

    -

    Mapbuf hierarchy

    - -

    A mapbuf component is a container UI component that uses an Evas map to hold a content object. This component is used to improve the moving and resizing performance of complex UI components.

    - -

    The content object is treated as a single image by the Evas map. If you have a content object containing several child objects, frequently moving the mapbuf component will be faster than frequently moving the content object.

    - -

    The mapbuf component inherits all the functions of the container class.

    - -

    Creating a Mapbuf

    -

    To create a mapbuf component, use the elm_mapbuf_add() function:

    -
    Evas_Object *mapbuf, *parent, *content;
    -
    -// Creating a mapbuf
    -mapbuf = elm_mapbuf_add(parent);
    -
    -

    Adding Content to the Mapbuf

    -

    To add content to the mapbuf component, use the elm_object_content_set() function with the "default" part:

    -
    elm_object_content_set(mapbuf, content);
    - - - - - - - - - - -
    Note
    Calling elm_object_content_set(mapbuf, content) is equivalent to calling elm_object_part_content_set(mapbuf, "default", content).
    - - -

    To activate smooth map rendering and alpha rendering for the mapbuf component:

    -
    elm_mapbuf_smooth_set(mapbuf, EINA_TRUE);
    -elm_mapbuf_alpha_set(mapbuf, EINA_TRUE);
    -
    - -

    Activating the Mapbuf

    -

    Finally, to use the mapbuf component, you must activate it:

    -
    elm_mapbuf_enabled_set (mapbuf, EINA_TRUE);
    - -

    Signals

    -

    The mapbuf component does not emit any signals and therefore does not provide any callbacks that you can register.

    - - - - -

    A naviframe component consists of a stack of views. New views are pushed on top of previous ones, and only the top-most view on the stack is displayed. The previous views are not deleted. A previous view is displayed when the view on top of it is popped. Transitions can be animated on a push or a pop, depending on the theme applied to the UI component.

    - -

    Creating a Naviframe

    -

    To create a naviframe, use the elm_naviframe_add() function:

    -
    Evas_Object *nav;
    -
    -nav = elm_naviframe_add(parent);
    -
    -

    Adding and Deleting Views

    -

    The naviframe is a stack of views. A new view is always pushed to the top of the stack. The top-most view is deleted by popping it.

    -

    To add a new view to the naviframe:

    -
    Elm_Object_Item *nav_it;
    -
    -nav_it = elm_naviframe_item_push(nav, NULL, NULL, NULL, view, NULL);
    -// In Tizen 2.3, the back button is not supported in the naviframe 
    -
    -

    When you push a new view to the stack, you receive an Elm_Object_Item for the view. You can use this item to modify the view.

    -

    To pop and delete the top-most view:

    -
    elm_naviframe_item_pop(nav);
    -
    - -

    Adding Fixed Content

    -

    The naviframe can also display fixed content on top of the current (top-most) view. Use the elm_object_item_part_content_set() function to set this content. Use the following part names to specify the location of the content:

    -
      -
    • "default": The main content area of the current view.
    • -
    • "title_icon": An icon in the title area of the current view.
    • -
    -

    For example, to add a button to the naviframe:

    -
    btn = elm_button_add(nav);
    -elm_object_style_set(btn, "naviframe/title_icon");
    -elm_object_part_content_set(btn, "icon", ic);
    -
    -

    To set the title labels of the naviframe, use the elm_object_item_part_text_set() function and specify one of the following label locations:

    -
      -
    • "default": Sets the title label in the title area of the current view.
    • -
    -

    Signals

    -

    The naviframe emits the following signals:

    -
      -
    • "transition,finished": The transition has finished changing the view.
    • -
    • "title,transition,finished": The title area transition has finished changing the state of the title.
    • -
    • "title,clicked": The user has clicked the title area.
    • -
    - - -

    Scroller

    - -

    A scroller holds (and clips) a single object and allows you to scroll across it. This means that the user can use a scroll bar or their finger to drag the viewable region across the object, moving through a much larger area than is contained in the viewport. The scroller will always have a default minimum size that is not limited by its contents.

    -

    The scroller component inherits all the functions of the Layout.

    -

    Creating a Scroller

    -

    To create a scroller, use the elm_scroller_add() function:

    -
    -Evas_Object *scroller;
    -
    -scroller = elm_scroller_add(parent);
    -
    -

    Adding Objects to the Scroller

    -

    To add an object to the scroller, use the elm_object_content_set() function:

    -
    Evas_Object *image;
    -
    -image = elm_image_add(parent);
    -elm_image_file_set(image, "image.png", NULL);
    -evas_object_show(image);
    -evas_object_size_hint_min_set(image, 2560, 1600);
    -elm_object_content_set(scroller, image);
    -
    -

    In the above code, we set a minimum size of 2560 x 1600 pixels for the image. The scroller is smaller than the image, so you can scroll across the image.

    -

    If you want to be informed when the user begins scrolling the image, use the following code:

    -
    -evas_object_smart_callback_add(scroller, "scroll,drag,start", _scroll_start_cb, NULL);
    -
    -// Callback function for the "animate,begin" signal
    -// This callback is called when the user begins scrolling the image
    -void _scroll_start_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   printf("Scroll starts\n");
    -}
    - -

    Managing the Properties of the Scroller

    -

    When scrolling content, the scroller may "bounce" when reaching the edge of the content. This is a visual way of indicating that there is no more content to scroll in that direction. Bounce is enabled by default for both axes. To enable or disable the bounce for either or both axes, use the elm_scroller_bounce_set() function. The following code disables the bounce for the horizontal axis and enables it for the vertical axis:

    - -
    elm_scroller_bounce_set(scroller, EINA_FALSE, EINA_TRUE);
    -
    -

    The scroller can limit the scrolling to "pages". In this case, the scrolling occurs in page-sized chunks of content rather than in a purely continuous fashion, with the scroller displaying a single "page" at a time. This feature sets the size of the page relative to the viewport of the scroller. A size of 1.0 equals 1 viewport (horizontally or vertically). A size of 0.0 disables paging for that axis. These settings are mutually exclusive with page size (see the elm_scroller_page_size_set() function). A size of 0.5 equals half a viewport. Usable size values are normally between 0.0 and 1.0, including 1.0. If you only want a single axis to scroll in pages, use 0.0 for the other axis.

    - -

    Signals

    - -

    The scroller emits the following signals, which you can catch in your application:

    - -
      -
    • "edge,left": The left edge of the content has been reached.
    • -
    • "edge,right": The right edge of the content has been reached.
    • -
    • "edge,top": The top edge of the content has been reached.
    • -
    • "edge,bottom": The bottom edge of the content has been reached.
    • -
    • "scroll": The content has been scrolled (moved).
    • -
    • "scroll,anim,start": The scrolling animation has started.
    • -
    • "scroll,anim,stop": The scrolling animation has stopped.
    • -
    • "scroll,drag,start": Dragging the contents has started.
    • -
    • "scroll,drag,stop": Dragging the contents has stopped.
    • -
    • "vbar,drag": The vertical scroll bar has been dragged.
    • -
    • "vbar,press": The vertical scroll bar has been pressed.
    • -
    • "vbar,unpress": The vertical scroll bar has been unpressed.
    • -
    • "hbar,drag": The horizontal scroll bar has been dragged.
    • -
    • "hbar,press": The horizontal scroll bar has been pressed.
    • -
    • "hbar,unpress": The horizontal scroll bar has been unpressed.
    • -
    • "scroll,page,changed": The visible page has changed.
    • -
    - -

    Example

    -

    A good example of the scroller is a picture slideshow: we add images to the scroller and limit the scrolling to pages (one picture at a time). In the following code, we disable the scroll bars for both axes, limit the scrolling to pages by using the elm_scroller_page_scroll_limit_set() function, and lock the scrolling on the Y axis by using the elm_object_scroll_lock_y_set() function:

    -
    elm_scroller_policy_set(scroller, ELM_SCROLLER_POLICY_OFF, ELM_SCROLLER_POLICY_OFF);
    -elm_scroller_page_scroll_limit_set(scroller, 1, 0);
    -elm_object_scroll_lock_y_set(scroller, EINA_TRUE);
    -
    -

    We create a horizontal box, which will contain all the images, and which itself will be contained by the scroller:

    -
    box = elm_box_add(scroller);
    -elm_box_horizontal_set(box, EINA_TRUE);
    -elm_object_content_set(scroller, box);
    -evas_object_show(box);
    -
    -

    We then create all the images and add them to the horizontal box:

    -
    img = elm_image_add(scroller);
    -snprintf(buf, sizeof(buf), IMAGE_DIR"/%d.jpg", i);
    -elm_image_file_set(img, buf, NULL);
    -evas_object_show(img);
    -pages = eina_list_append(pages, img);
    -elm_box_pack_end(box, img);
    -
    -

    We store references to the images in an eina_list for easy retrieval later.

    -

    Finally, we display the first page of the scroller:

    -
    elm_scroller_page_show(scroller, 0, 0);
    -
    -

    The size of the scroller depends on the size of the parent. When the parent changes, for example when the window is resized or rotated, the scroller is also resized. Since we need to be informed when the scroller is resized, we add a callback on the EVAS_CALLBACK_RESIZE event for the scroller:

    -
    evas_object_event_callback_add(scroller, EVAS_CALLBACK_RESIZE, _scroller_resize_cb, NULL);
    -

    The callback retrieves the new size of the scroller by using the evas_object_geometry_get() function on the object pointer. The pointer is relative to the object that has been resized, which in our case is the scroller itself. We can then iterate through the images of the scroller and set the minimum size to fit the scroller size:

    -
    EINA_LIST_FOREACH(images, l, page)
    -{
    -   evas_object_size_hint_min_set(page, w, h);
    -}
    -
    -

    Finally, we set the page size of the scroller to match the scroller size and display the first page:

    -
    elm_scroller_page_size_set(obj, w, h);
    -elm_scroller_page_show(obj, 0, 0);
    - -

    Table

    - -

    A table is like a box but with 2 dimensions. You have the same kind of APIs as with boxes. An item inside the table can span multiple columns and rows, and even overlap with other items (and it can then be raised or lowered accordingly to adjust stacking if there is overlap).

    - -

    Creating a Table

    - -

    To create a table, use the elm_table_add() function:

    -
    Evas_Object *table;
    -table = elm_table_add(parent);
    - -

    Adding Items to the Table

    - -

    Items are added to the table with the elm_table_pack() function. This function takes as parameters the table, the item to add to the table, and the position where to add the item: column, row, and the size of the item in number of rows and columns (colspan and rowspan). If we want to create an icon that takes 3 columns and rows and a button that only takes 1 row and column, the code will look like this:

    -
    ic = elm_icon_add(table);
    -elm_image_file_set(ic, "icon.png", NULL);
    -evas_object_show(ic);
    -elm_table_pack(table, ic, 0, 0, 3, 3);
    -
    -btn = elm_button_add(table);
    -elm_object_text_set(btn, "Click me i'm famous");
    -evas_object_show(btn);
    -elm_table_pack(table, btn, 3, 1, 1, 1);
    -evas_object_show(table);
    -
    - -

    Managing the Items

    - -

    If you want to change the position of the item after adding it, use the elm_table_pack_set() function. This function takes as parameters the item whose position to change, the new column, the new row, and the size of the item in number of rows and columns (colspan and rowspan).

    - -

    To add padding around the item, use the elm_table_padding_set() function. The second parameter is the padding between columns, and the third parameter is the padding between rows:

    -
    elm_table_padding_set(table, 10, 10);
    - -

    To change the alignment and size of an item, use the evas_object_size_hint parameters. They are used in the same way as with boxes. You can set the same size and weight to each item by using the homogeneous parameter:

    -
    elm_table_homogeneous_set(table, EINA_TRUE);
    -
    - -

    Clearing the Table

    - -

    To clear the table, use the elm_table_clear() function. If the clear parameter is EINA_TRUE, the table items are deleted. The evas_object_del() function will be called on each item.

    - - - - - -
    - -Go to top - - - - - - - - diff --git a/org.tizen.guides/html/native/ui/data_types_n.htm b/org.tizen.guides/html/native/ui/data_types_n.htm deleted file mode 100644 index a06baab..0000000 --- a/org.tizen.guides/html/native/ui/data_types_n.htm +++ /dev/null @@ -1,1753 +0,0 @@ - - - - - - - - - - - - - Data Types - - - -
    -
    -

    Mobile native

    -
    - -
    -

    Content

    - -

    Related Info

    - -
    -
    - -
    - -

    Data Types

    - -

    The Eina library is a central part of the EFL. It implements an API for data types, and allows you to create and manipulate several data types:

    - -
      -
    • Inline Array: standard array of inlined members
    • -
    • Array: standard array of void* data
    • -
    • Hash Table: standard hash of void* data
    • -
    • Inline List: list with nodes inlined into the user type
    • -
    • Compact List
    • -
    • List: standard list of void* data
    • -
    • Iterator Functions
    • -
    • Sparse Matrix: sparse matrix of void* data
    • -
    • Red-Black tree: red-black tree with nodes inlined into the user type
    • -
    • String Buffer: mutable string to prepend, insert, or append strings to a buffer
    • -
    • Stringshare: shares read-only string references
    • -
    • Tiler split: merges and navigates into 2D tiled regions
    • -
    • Trash: container of unused but allocated data
    • -
    • Generic Value Storage: container for generic value storage and access
    • -
    • Data Model API: container for data with a user-defined hierarchy or structure
    • -
    - - -

    Iterator Functions

    -

    Eina provides a set of iterator functions to manipulate data types, such as arrays.

    -

    These functions allow access to container elements in a generic way, without knowing which container is used (similar to iterators in the C++ STL). Iterators only allow sequential access (that is, from one element to the next one). For random access, Eina provides accessor functions.

    -

    Getting an iterator to access elements of a given container is done through the functions of that particular container. There is no function to create a generic iterator as iterators absolutely depend on the container. Note that all iterators, regardless of the container type, are always deleted with the same eina_iterator_free() function.

    -

    To get the data and iterate, use the eina_iterator_next() function. To call a function on every single element of a container, use the eina_iterator_foreach() function.

    -

    In addition to iterator functions, each data type also owns a set of macros that provide the iterators, such as FOREACH or REVERSE_FOREACH.

    - -

    Strings

    - -

    Stringshare

    - -

    The Eina_Stringshare data type functions allow you to store a single copy of a string and use it in multiple places throughout your program. This way you can save a lot of strings with less memory. It improves string creation and destruction speed, reduces memory use, and decreases memory fragmentation.

    -

    With this data type you can reduce the number of duplicated strings kept in memory. It is common for the same strings to be dynamically allocated repeatedly between applications and libraries, especially in circumstances where you can have multiple copies of a structure that allocates the string. Rather than duplicating and freeing these strings, request a read-only pointer to an existing string and only incur the overhead of a hash lookup. This can sound like micro-optimizing, but profiling has shown that this can have a significant impact as the number of copies grows.

    - -

    To manage stringshares:

    -
      -
    1. To create a stringshare, declare a string variable and call the eina_stringshare_add() function: -
      -const char *mystr;
      -const char *prologue = "Enlightenment is not just a window manager for Linux/X11 and others"
      -
      -mystr = eina_stringshare_add(prologue);
      -
    2. - -
    3. To retrieve or modify the string data: -
        -
      • Retrieve a string for use in a program from a format string using the eina_stringshare_printf() function. If you have a "format" string to pass to a function like printf, you can store it as a stringshare as well. -

        The following example produces "1 desktop manager to rule them all".

        -
        -const char *myfmtstr = "%d desktop manager to rule them all";
        -const char *str;
        -
        -str = eina_stringshare_printf(myfmtstr, 1);
        -
        -print(str)
        -
        -
      • - -
      • Replace the value of a stringshare with the eina_stringshare_replace() function. Pass the pointer address and the new value to the function. -
        -eina_stringshare_replace(&str,"One desktop manager to rule them all");
        -
        -
      • - -
      • Retrieve the length of the stringshare value with the eina_stringshare_strlen() function. -
        -printf("length: %d\n", eina_stringshare_strlen(str));
        -
        -
      • -
      -
    4. -
    5. When the string is no longer needed, delete it using the eina_stringshare_del() function: -
      -eina_stringshare_del(mystr);
      -
      -
    6. -
    - - - -

    String Buffer

    -

    The string buffer data type is designed to be a mutable string, allowing you to append, prepend or insert a string to a buffer. It allows easy handling of buffers in your applications.

    -

    To manage string buffers:

    -
      -
    1. Initialize the Eina_Strbuf instance and create the buffer: -
      -Eina_Strbuf *buf;
      -mybuffer = eina_strbuf_new();
      -
      -
    2. -
    3. Manage the buffer content: -
        -
      • To append characters to the buffer: -
          -
        • -

          For basic strings, use the eina_strbuf_append() function:

          -
          -eina_strbuf_append(mybuffer, "This is my string.");
          -
          -
        • -
        • To append 1 character to your buffer, use the eina_strbuf_append_char() function. You can also append a sized string to the buffer using the eina_strbuf_append_length() function. -
          -eina_strbuf_append_length(mybuffer, "Buffe", 5);
          -eina_strbuf_append_char(mybuffer, 'r');
          -
          -
        • -
        • To handle "printf" format strings, use the eina_strbuf_append_printf() function to add formatted strings to the buffer: -
          -eina_strbuf_append_printf(buf, "%s%c", "buffe", 'r');
          -
          -
        • -
        -
      • - -
      • To remove characters from one position to another, use the eina_strbuf_remove() function. The first parameter is the buffer, the second is the start position of the characters you want to delete, and the last the end position. -

        This example removes the first 19 characters of the buffer:

        -
        -eina_strbuf_remove(buf, 0, 18);
        -
        -
      • - -
      • To replace characters: - -
        • -eina_strbuf_replace() replaces a specific occurrence of a given string in the buffer with another string.
        • -
        • -eina_strbuf_replace_all() replaces all occurrences of a given string in the buffer with another string. -
        • -
        -
        -eina_strbuf_append(mybuffer, "buffer buffer buffer");
        -
        -// Replacing one occurrence of "buffer" by "B-U-F-F-E-R"
        -eina_strbuf_replace(mybuffer, "buffer", "B-U-F-F-E-R", 1);
        -
        -// Replacing all the occurrences of "buffer" by "B-U-F-F-E-R"
        -eina_strbuf_replace_all(mybuffer, "buffer", "B-U-F-F-E-R");
        -
        -// Replacing all the occurrences of "B-U-F-F-E-R" by "Buffer"
        -eina_strbuf_replace_all(mybuffer, "B-U-F-F-E-R", "Buffer");
        -
        -
      • -
      • To insert a string at the specified position, use the eina_strbuf_insert() function. Use the eina_strbuf_insert_printf() function with formatted strings. -
        -eina_strbuf_insert(mybuffer, "More buffer", 10);
        -
        -// Using eina_strbuf_length_get to get the buffer length
        -eina_strbuf_insert_printf(buf, " %s: %d", 6, "length", eina_strbuf_length_get(buf));
        -
        -
      • - -
      • To get the complete length of the string and the buffer, use the eina_strbuf_string_get() and eina_strbuf_length_get() functions: -
        -printf("%s : %d\n", eina_strbuf_string_get(mybuffer), eina_strbuf_length_get(buf));
        -
        -
      • -
      -
    4. - -
    5. When no longer needed, free the buffer with the eina_strbuf_free() function. You can also free the content of Eina_Strbuf without freeing the buffer itself using the eina_strbuf_string_free() function. -
      -eina_strbuf_free(mybuffer);
      -
      -
    6. -
    - -

    Arrays

    -

    An array is a data type which describes an ordered collection of values. The values are accessed by their index.

    -
    -INDEX | VALUE
    ---------------
    -0     | value0
    -1     | value1
    -2     | value2
    -3     | value3
    -4     | value4
    -5     | value5
    -6     | value6
    -7     | value7
    -
    -

    Eina provides 2 array types: the classic array and an inline array.

    - -

    Creating and Destroying a Classic Array

    - -

    The eina_array_new() function creates a new array. You can store strings or objects in the created array. The function returns a new array, or if memory allocation fails, NULL.

    -

    The first parameter of the eina_array_new() function defines the size of the array allocation step. For example, if you set it to 4, the function returns an array of 4 elements and the next time you grow the array it grows by 4 elements. Unless you have pushed 4 elements inside, it does not grow. But once you add the 5th element, it grows again and becomes an array of 8 elements. The allocation step feature is very useful for optimizing performance, and it also reduces memory fragmentation by having a size that fits the array usage. If you set the step to 0, the function sets a default safe value.

    - -

    To create an array to store strings:

    -
      -
    1. Create the array: -
      -// Strings to store in the array 
      -const char* strings[] = 
      -{
      -   "helo", "hera", "starbuck", "kat", "boomer",
      -   "hotdog", "longshot", "jammer", "crashdown", "hardball",
      -   "duck", "racetrack", "apolo", "husker", "freaker",
      -   "skulls", "bulldog", "flat top", "hammerhead", "gonzo"
      -};
      -// Declaring the array (type Eina_Array)
      -Eina_Array *array;
      -unsigned int i;
      -
      -// Creating the array
      -array = eina_array_new(20);
      -
      -// Inserting elements in the array
      -for (i = 0; i < 20; i++)
      -   eina_array_push(array, strdup(strings[i]));
      -
      -
    2. -
    3. To change the allocation step, use the eina_array_step_set() function: -
      • The first parameter is the array you want to change.
      • -
      • The second parameter is the size of that specific array (retrieved with the sizeof() function).
      • -
      • The last parameter is the new step size.
      -

      In this example, the array step changes from 20 to 30.

      -
      -eina_array_step_set(array, sizeof(*array), 30);
      -
      -
    4. -
    5. When no longer used, use the eina_array_free() function to free the array. It first calls the eina_array_flush() function and frees the memory of the pointer. It does not free the memory allocated for the elements of the array. To free them, use a while statement with the eina_array_pop function. -
      -// Freeing the array elements
      -while (eina_array_count(array))
      -   free(eina_array_pop(array));
      -
      -// Freeing the array itself
      -eina_array_free(array);
      -
      -
    6. -
    - -

    Modifying Classic Array Content

    - -

    To modify classic array content:

    -
      -
    • To set the data of an element, use the eina_array_data_set() function. The first parameter is the array, the second is the index of the element you want to set, and the last one is the data. You must first get the related pointer if you need to free it, as this function replaces the previously held data. Be careful, as there is no array or index check. If the value is NULL or invalid, the application can crash. -
      -free(eina_array_data_get(array, 0));
      -eina_array_data_set(array, 0, strdup(strings[3]);
      -
      -
    • -
    • To add elements to the end of the array, use the eina_array_push() function. The function returns EINA_TRUE on success, and EINA_FALSE on failure. The first parameter is the array to store the element, the second one is the data you want to store. If you store strings, remember to allocate the memory first. The example uses the strdup function to duplicate the string contained in strings[]. This function allocates the memory of the returned string, so you do not have to do it yourself. -
      -for (i = 0; i < 20; i++)
      -   eina_array_push(array, strdup(strings[i]));
      -
      -
    • - -
    • To remove the last element of an array, use the eina_array_pop() function. It takes the array as a parameter, and if the operation is successful, returns a pointer to the data of the removed element. -
      -while (eina_array_count(array))
      -   free(eina_array_pop(array));
      -
      -
    • - -
    • To rebuild the array by specifying the data to be kept, use the eina_array_remove() function: -
      • The first parameter is the array to be changed.
      • -
      • The second parameter is the function which selects the data to keep in the rebuilt array.
      • -
      • The last parameter is the data to pass to the selector function defined as the second parameter.
      -

      The selector function has to return an Eina_Bool, EINA_TRUE if the element stays, and EINA_FALSE if it has to be removed.

      -

      The following example shows how to remove all the elements of the array that are longer than 5.

      -
      -// Selector function 
      -Eina_Bool keep(void *data, void *gdata)
      -{
      -   if (strlen((const char*)data) <= 5)
      -      return EINA_TRUE;
      -
      -   return EINA_FALSE;
      -}
      -
      -int remove_array()
      -{
      -   Eina_Array *array;
      -   Eina_Array_Iterator iterator;
      -   const char *item;
      -   unsigned int i;
      -
      -   // Creating and populating an array
      -
      -   // Removing the undesired elements 
      -   eina_array_remove(array, keep, NULL);
      -
      -   // Flushing and freeing the array
      -
      -   return 0;
      -}
      -
      -
    • -
    • To completely wipe an array out, use the eina_array_flush() function. This function sets the count and total members of an array to 0, and frees and sets its data members to NULL. For performance reasons, there is no array check. If the value is NULL or invalid, the program can crash. The only parameter of this function is a pointer to the Eina_Array array you want to flush. -
      -eina_array_flush(array);
      -
      -
    • -
    • To empty an array quickly, use the eina_array_clean() function. This function sets the counting of members in the array to 0. It does not free any space so you have to use it carefully. For performance reasons, there is no array check. If the value is NULL or invalid, the program can crash. -
      -eina_array_clean(array);
      -
      -
    • -
    - -

    Accessing Classic Array Data

    - -

    To access classic array data:

    -
      -
    • To access the data in the array, use the eina_array_data_get() function with the array and the index of the element you want to get. The function returns a pointer to the data. -
      -// Getting the data of the first element 
      -char *mydata;
      -mydata = eina_array_data_get(array, 0);
      -
      -
    • - - -
    • To get the number of elements in an array, use the eina_array_count() function. The first parameter is a pointer to the array variable returned by the eina_array_new() function. -

      The function returns the number of elements.

      -
      -unsigned int nb_elm;
      -nb_elm = eina_array_count(array);
      -
      -
    • - -
    • To iterate through an array, you can use various methods: -
        -
      • Use the Eina_Array iterator called ITER_NEXT. -

        You can use the iterator by calling the macro EINA_ARRAY_ITER_NEXT(). It takes the array to iterate as the first parameter, a counter for the current index during the iteration, and a variable of the same type as the item data and an Eina_Iterator. To use it, declare an Eina_Iterator, an int counter, and, for example, a char * item if your array contains any strings.

        -
        -Eina_Array_Iterator iterator;
        -const char *item;
        -unsigned int i;
        -
        -EINA_ARRAY_ITER_NEXT(array, i, item, iterator)
        -   printf("item #%d: %s\n", i, item);
        -
        -
      • -
      • Use the eina_array_foreach() function to iterate over the array. -

        The first parameter is the array to iterate, the second is a callback function which determines whether the iteration can continue,and the last is the data passed to the callback function.

        -

        To iterate over the array and to print the data of each array element:

        -
        -// Callback function 
        -static Eina_Bool
        -elm_print(const void *container, void *data, void *fdata)
        -{
        -   printf("%s\n", (char *)data);
        -
        -   return EINA_TRUE;
        -}
        -
        -int iterating_array()
        -{
        -   Eina_Array *array;
        -   unsigned int i;
        -
        -   // Creating and populating an array
        -
        -   // Iterating over the array and calling elm_print on each element
        -   eina_array_foreach(array, elm_print, NULL);
        -
        -   // Freeing the element data and array
        -
        -   return 0;
        -}
        -
        -
      • - -
      • Use the eina_array_iterator_new() function to create an iterator for the array.

        The function returns a newly allocated iterator associated with the array. If the array is NULL or the count of the array members is less than or equal to 0, the function returns NULL. If the memory cannot be allocated, NULL is returned and EINA_ERROR_OUT_OF_MEMORY is thrown. Otherwise, a valid iterator is returned.

        -

        Pass to this function the array for which you want to create a new iterator. The iterator is used to run a sequential walk through the array, just like the eina_array_foreach() function.

        -

        To create an iterator and use it to print the data of each array element:

        -
        -static Eina_Bool
        -print_one(const void *container, void *data, void *fdata)
        -{
        -   printf("%s\n", (char*)data);
        -
        -   return EINA_TRUE;
        -}
        -
        -int new_iterator()
        -{
        -   Eina_Array *arra;
        -   Eina_Iterator *it;
        -   unsigned short int i;
        -   void *uninteresting;
        -   Eina_Bool rt;
        -
        -   // Creating and populating an array
        -
        -   it = eina_array_iterator_new(array);
        -
        -   it = eina_iterator_next(it, &uninteresting);
        -   eina_iterator_foreach(it, print_one, NULL);
        -   eina_iterator_free(it);
        -
        -   return 0;
        -}
        -
        -
      • -
      • Use the eina_array_accessor_new() function to get random access to the array elements. -

        The function returns a newly allocated accessor associated with the array. If the array is NULL or the counting of array members is less than or equal to 0, this function returns NULL. If the memory cannot be allocated, NULL is returned and EINA_ERROR_OUT_OF_MEMORY is thrown. Otherwise, a valid accessor is returned.

        -

        To use the accessor to retrieve and print the data of every other array element:

        -
        -int random_access()
        -{
        -   // Declaration of the array 
        -   Eina_Array *array;
        -   // Declaration of the accessor
        -   Eina_Accessor *acc;
        -
        -   // Generic counter
        -   unsigned short int i;
        -
        -   // Variable to put the data retrieved from an array element
        -   void *data;
        -
        -   // Creating and populating an array
        -
        -   // Creating the array accessor
        -   acc = eina_array_accessor_new(array);
        -
        -   // Random access to the data of the array elements
        -   for(i = 1; i < 10; i += 2)
        -   {
        -      // Putting the data in the variable 'data'
        -      eina_accessor_data_get(acc, i, &data);
        -      printf("%s\n", (const char *)data);
        -   }
        -
        -   // Freeing the accessor
        -   eina_accessor_free(acc);
        -
        -   // Freeing the array
        -
        -   return 0;
        -}
        -
        -
      • -
      -
    • -
    - - -

    Creating and Destroying an Inline Array

    - -

    An inline array is a container that stores the data itself, not the pointers to the data. This means there is no memory fragmentation, and for small data types, such as char, short, and int, it is more memory-efficient. This is because the data is stored in the cache and is faster to access. The bigger the data gets, however, the less likely it is and the less interesting it becomes.

    -

    To create an inline array, use the eina_inarray_new() function:

    -
    • The first parameter is the size of the value. In this example, only the characters are stored, and because of that, only sizeof(char) is passed to the function.
    • -
    • The second parameter defines the size of the array allocation step. For example, if you set it to 4, the function returns an inline array of 4 elements, and the next time you grow the inline array, it grows by 4 elements and becomes an array of 8 elements. If you set the step to 0, the function sets a default safe value. -

      The step can be changed later on using the eina_inarray_step_set() function.

    - -

    The eina_inarray_new() function returns a pointer to the new Eina_Inarray variable.

    -
    -int inline_array() 
    -{
    -   // Declare an inline array variable of the type Eina_Inarray
    -   Eina_Inarray *iarr;
    -
    -   // Create an inline array of "char"
    -   iarr = eina_inarray_new(sizeof(char), 0);
    -
    -   // When no longer needed, free the array memory
    -   eina_inarray_free(iarr);
    -
    -   return 0;
    -}
    -
    - -

    Modifying Inline Array Content

    - -

    To modify inline array content:

    -
      -
    • -

      To add data as the last element of the inline array, use the eina_inarray_push() function. The first parameter is a pointer to the array variable returned by the eina_inarray_new() function. The second parameter is the data you want to push to the inline array.

      -

      If everything runs fine, the function returns the index of the new element. If something goes wrong, it returns -1.

      -
      -ch = 'a';
      -eina_inarray_push(iarr, &ch);
      -
      -
    • -
    • -

      To insert data to a given position of the inline array, use the eina_inarray_insert_at() function:

      -
      • The first parameter is a pointer to the array variable returned by the eina_inarray_new() function.
      • -
      • The second parameter is the index of the element you want to add to the inline array.
      • -
      • The last parameter is a pointer to the content to be added.
      -

      The content of the pointer is copied to the given position in the inline array. All the members from the position to the end of the array are shifted towards the end. If the position is equal to the end of the array, the member is appended. If the position is bigger than the array length, the function fails.

      -
      -ch = 'a';
      -eina_inarray_push(iarr, &ch);
      -ch = 'b';
      -eina_inarray_push(iarr, &ch);
      -ch = 'd';
      -eina_inarray_push(iarr, &ch);
      -
      -// Adding data on position 3
      -ch = 'c';
      -eina_inarray_insert_at(iarr, 2, &ch)
      -
      -
    • -
    • -

      To insert data with your own position criteria, use the eina_inarray_insert() or eina_inarray_insert_sorted() function. The only difference between these functions is that the eina_inarray_insert_sorted() function assumes that the array is already sorted and consequently optimizes the insertion position by doing a binary search.

      -

      In both functions:

      -
      • The first parameter is a pointer to the array variable returned by the eina_inarray_new() function.
      • -
      • The second parameter is the data you want to push to the inline array.
      • -
      • The last parameter is the callback comparison function. -

        The Eina_Compare_Cb callback function compares data1 and data2. data1 is the value contained in the inline array and data2 is the data you pass to the eina_inarray_insert() or eina_inarray_insert_sorted() function as the second parameter. If data1 is less than data2, -1 must be returned, if it is greater, 1 must be returned, and if they are equal, 0 must be returned.

      -

      The following example shows how to insert a value before a greater value:

      -
      -// Defining the comparison function with the position criteria
      -Eina_Compare_Cb cmp(const void *a, const void *b)
      -{
      -   return *(int*)a > *(int*)b;
      -}
      -
      -int inline_insert()
      -{
      -   Eina_Inarray *iarr;
      -   char ch, *ch3;
      -   int a, *b;
      -
      -   // Creating an inline array
      -
      -   // Adding data to the inline array
      -   a = 97;
      -   eina_inarray_push(iarr, &a);
      -   a = 98;
      -   eina_inarray_push(iarr, &a);
      -   a = 100;
      -   eina_inarray_push(iarr, &a);
      -
      -   // Inserting data with the criteria
      -   a = 99;
      -   eina_inarray_insert_sorted(iarr, &a, cmp);
      -
      -   eina_inarray_free(iarr);
      -}
      -
      -
    • -
    • -

      To remove the last element of the inline array, use the eina_inarray_pop() function. The only parameter is a pointer to the array variable returned by the eina_inarray_new() function. This function returns the data removed from the inline array.

      -
      -eina_inarray_pop(iarr);
      -
      -
    • -
    • -

      To remove specific data from an inline array, use the eina_inarray_remove() function. The first parameter is a pointer to the array variable returned by the eina_inarray_new() function. The second parameter is the data you want to remove from the inline array.

      - -

      The eina_inarray_remove() function finds the data and removes the matching members from the array. The data can be an existing member of an inline array for optimized usage. In other cases, the content is matched using the memcmp() function.

      - - -

      The eina_inarray_remove() function returns the index of the removed member, or -1 if failed.

      -
      -iarr = eina_inarray_new(sizeof(char), 0);
      -
      -ch = 'a';
      -eina_inarray_push(iarr, &ch);
      -
      -// Removing data from the array
      -eina_inarray_remove(iarr, &ch);
      -
      -
    • - -
    • -

      To remove data from a defined position in an inline array, use the eina_inarray_remove_at() function. The first parameter is a pointer to the array variable returned by the eina_inarray_new() function. The second parameter is the index of the element you want to remove from the inline array.

      -

      The function returns EINA_TRUE on success and EINA_FALSE if something goes wrong. The member is removed from the inline array and any members after it are moved towards the array's head.

      -
      -// Removing data from position 2
      -eina_inarray_remove_at(iarr, 2);
      -
      -
    • -
    • To remove all the elements of the array, use the eina_inarray_flush() function. The first parameter is a pointer to the array variable returned by the eina_inarray_new() function. The function removes every member from the array.

      -
      -eina_inarray_flush(iarr);
      -
      -
    • - -
    • -

      To replace values in the inline array, use the eina_inarray_replace_at() function, which copies the data over the given position:

      -
      • The first parameter is a pointer to the array variable returned by the eina_inarray_new() function.
      • -
      • The second parameter is the index of the element you want to remove from the inline array.
      • -
      • The last parameter is the data you want to copy in place of the current data.
      -

      The function returns EINA_TRUE on success, and EINA_FALSE on failure. The given pointer content is copied to the given position in the array. The pointer is not referenced, instead its contents are copied to the member's array using the previously defined member_size. If the position does not exist, the function fails.

      -
      -// Replacing the member at position 3 
      -ch = 'd';
      -eina_inarray_replace_at(iarr, 3, &ch);
      -
      -
    • - -
    • -

      To sort an inline array, use the eina_inarray_sort() function, which applies a quick sorting algorithm to the inline array:

      -
      • The first parameter is a pointer to the array returned by the eina_inarray_new() function.
      • -
      • The last parameter is the Eina_Compare_Cb callback comparison function, which compares data1 and data2. -

        data1 and data2 are values contained in the inline array. If the data matches, the function must return 0, if data1 is less than data2, -1 must be returned and if it is greater, 1 must be returned.

      -
      -static int
      -short_cmp(const void *pa, const void *pb)
      -{
      -   const short *a = pa, *b = pb;
      -
      -   return *a - *b;
      -}
      -
      -int sorting_inline_array()
      -{
      -   Eina_Inarray *array;
      -   int i;
      -
      -   // Creating and populating the inline array
      -
      -   eina_inarray_sort(array, short_cmp);
      -   eina_inarray_free(array);
      -}
      -
      - -

      Be careful, the data given to the compare function is the pointer to the member memory itself. Do not change it.

      -
    • -
    - -

    Accessing Inline Array Data

    - -

    To access inline array data:

    -
      -
    • -

      To search a member in an inline array, use the eina_inarray_search() function that runs a linear walk looking for the given data:

      - -
      • The first parameter is a pointer to the array variable returned by the eina_inarray_new() function.
      • -
      • The second parameter is the data used by the callback function to run the comparison.
      • -
      • The last parameter is the Eina_Compare_Cb callback comparison function, which compares data1 and data2. -

        data1 is the value contained in the inline array and data2 is the data you pass to the eina_inarray_search() function as the second parameter. If the data matches, the function must return 0, if data1 is less than data2, -1 must be returned and if it is greater, 1 must be returned.

      -

      The function returns the member index, or -1 if not found.

      -
      -Eina_Compare_Cb
      -compare(const void *pa, const void *pb)
      -{
      -   const short *a = pa, *b = pb;
      -   if (*a == *b)
      -   {
      -      return EINA_TRUE;
      -   }
      -
      -   return EINA_FALSE;
      -}
      -
      -int search_inline_array()
      -{
      -   Eina_Inarray *array;
      -   int i;
      -   int elm_index;
      -   int to_search = 3;
      -
      -   // Creating and populating the inline array
      -
      -   elm_index = eina_inarray_search(array, &to_search, compare);
      -   eina_inarray_free(array);
      -}
      -
      - -

      Be careful, the data given to the compare function is the pointer to the member memory itself. Do not change it.

      -

      The eina_inarray_search_sorted() function does exactly the same as eina_inarray_search(), but uses a binary search for the given data.

      -
    • - -
    • -

      To get the number of elements in an inline array, use the eina_inarray_count(). The first parameter is a pointer to the array returned by the eina_inarray_new() function. The function returns an unsigned int, the number of elements.

      -
      -printf("Inline array of integers with %d elements:\n", eina_inarray_count(iarr));
      -
      -
    • - -
    • To iterate through an inline array, you can use various methods: -
        -
      • You can use the iterator macros for the inline arrays: FOREACH and REVERSE_FOREACH.

      • -
      • -

        To run a linear walk over an array of elements, use the EINA_INARRAY_FOREACH() macro. The first parameter is a pointer to the array variable returned by eina_inarray_new(), and the second parameter is the variable into which the current value is put during the walk. The EINA_INARRAY_REVERSE_FOREACH() macro does the same thing but starts from the last element.

        - -

        The following example illustrates the printing of each element and its pointer:

        -
        -iarr = eina_inarray_new(sizeof(char), 0);
        -int a, *b;
        -
        -a = 97;
        -eina_inarray_push(iarr, &a);
        -a = 98;
        -eina_inarray_push(iarr, &a);
        -a = 99;
        -eina_inarray_push(iarr, &a);
        -
        -EINA_INARRAY_FOREACH(iarr, b)
        -  printf("int: %d(pointer: %p)\n", *b, b);
        -
        -
      • -
      • To process the array data, use the eina_inarray_foreach() function, which invokes the given function on each element of the array with the given data: -
        • The first parameter is a pointer to the array variable returned by eina_inarray_new().
        • -
        • The second parameter is the function to run on each element. -

          The function must return EINA_TRUE as long as you want to continue iterating. By returning EINA_FALSE, you stop the iteration and make the eina_inarray_foreach() function return EINA_FALSE.

          -

          The data given to the function is the pointer to the member itself.

        • -
        • The last parameter is the data passed to the function called on each element.
        -

        The eina_inarray_foreach() function returns EINA_TRUE if it successfully iterates through all items of the array. Call the function for every given data in the array. This is a safe way to iterate over an array.

        -
        -static Eina_Bool
        -array_foreach(const void *array __UNUSED__, void *p, void *user_data __UNUSED__)
        -{
        -   short *member = p;
        -   int *i = user_data;
        -   (*p)++;
        -   (*i)++;
        -
        -   return EINA_TRUE;
        -}
        -
        -int inline_array_foreach()
        -{
        -   Eina_Inarray *iarr;
        -   iarr = eina_inarray_new(sizeof(char), 1);
        -   int i;
        -
        -   for (i = 0; i < numbers_count; i++)
        -   {
        -      short val = i;
        -      eina_inarray_push(iarr, &val);
        -   }
        -
        -   i = 0;
        -   eina_inarray_foreach(iarr, array_foreach, &i);
        -
        -   eina_inarray_free(iarr);
        -
        -   return 0;
        -}
        -
        -
      • - -
      • To remove some elements based on your own criteria, use the eina_inarray_foreach_remove() function, which walks through the array and, if the value matches in the callback function, removes the element: -
        • The first parameter is a pointer to the array returned by eina_inarray_new() function.
        • -
        • The second parameter is the callback function to run on each element. -

          The callback function returns EINA_TRUE if the value matches, or EINA_FALSE if it does not match.

        • -
        • The last parameter is the data passed to the callback function.
        -

        The function returns the number of removed entries or -1 if something goes wrong.

        -
        -static Eina_Bool
        -array_foreach(const void *array __UNUSED__, void *p, void *user_data __UNUSED__)
        -{
        -   short *member = p;
        -   int *i = user_data;
        -   if (*i == *p) 
        -   { 
        -      return EINA_TRUE;
        -   }
        -
        -   return EINA_FALSE;
        -}
        -
        -int inline_array_foreach_remove()
        -{
        -   Eina_Inarray *iarr;
        -   iarr = eina_inarray_new(sizeof(char), 1);
        -   int i;
        -
        -   for (i = 0; i < numbers_count; i++)
        -   {
        -      short val = i;
        -      eina_inarray_push(iarr, &val);
        -   }
        -
        -   i = 6;
        -   eina_inarray_foreach_remove(iarr, array_foreach, &i);
        -
        -   eina_inarray_free(iarr);
        -
        -   return 0;
        -}
        -
        - -
      • -
      -
    • -
    - - -

    Hash Tables

    -

    The Eina_Hash provides a way to store values in association with a key. For example, if you want to store some tuples into a table, you can do it using the Eina_Hash.

    -

    The Eina_Hash is implemented using an array of "buckets" where each bucket is a pointer to a structure that is the head of a red-black tree. This implementation makes it very robust against week keys as in the worst case scenario, you can still depend on an efficient binary tree implementation.

    - -

    Creating a Hash Table

    - -

    To create the hash table, use the eina_hash_new() function:

    -
      -
    • The first parameter is the function called when getting the size of the key.
    • -
    • The second parameter is the function called when comparing the keys.
    • -
    • The third parameter is the function called when getting the values.
    • -
    • The fourth parameter is the function called on each value when the hash table is freed, or when an item is deleted from it. NULL can be passed as the callback.
    • -
    • The last parameter is the size of the buckets.
    • -
    -

    When you create an Eina_Hash instance, you have to create 4 potentially long callback functions. To make the functions shorter, Eina_Hash offers some predefined functions to create the following kinds of hash tables:

    -
      -
    • eina_hash_string_djb2_new() creates a new hash table using the djb2 algorithm for strings.
    • -
    • eina_hash_string_superfast_new() creates a new hash table for use with strings (better with long strings).
    • -
    • eina_hash_string_small_new() creates a new hash table for use with strings with a small bucket size.
    • -
    • eina_hash_int32_new() and eina_hash_int64_new() create a new hash table for use with 32-bit and 64-bit integers.
    • -
    • eina_hash_pointer_new() creates a new hash table for use with pointers.
    • -
    • eina_hash_stringshared_new() creates a new hash table for use with shared strings.
    • -
    -

    All these predefined functions require only one parameter, which is the function to free the data you store in the hash table.

    -

    The following example shows how to manage a small phone book using the eina_hash_string_superfast_new() function to create the hash table.

    -
      -
    1. Create the phone book structure and some static data:

      -
      -struct _Phone_Entry 
      -{
      -   const char *name; // Full name
      -   const char *number; // Phone number
      -};
      -
      -typedef struct _Phone_Entry Phone_Entry;
      -
      -static Phone_Entry _start_entries[] = 
      -{
      -   { "Wolfgang Amadeus Mozart", "+01 23 456-78910" },
      -   { "Ludwig van Beethoven", "+12 34 567-89101" },
      -   { "Richard Georg Strauss", "+23 45 678-91012" },
      -   { "Heitor Villa-Lobos", "+34 56 789-10123" },
      -   { NULL, NULL }
      -};
      -
      -
    2. - -
    3. Create the callback to free the data:

      -
      -static void
      -_phone_entry_free_cb(void *data)
      -{
      -   free(data);
      -}
      -
      -

      The free callback can be changed later using the eina_hash_free_cb_set() function. You need to pass the hash and the new callback function.

      -
    4. - -
    5. Create and destroy the hash table.

      -

      The eina_hash_free_buckets() function frees all hash table buckets. It empties the hash but does not destroy it, and you can still use it for another purpose. When eina_hash_free() is called, the space allocated for the hash is freed.

      -
      -int free_data()
      -{
      -   Eina_Hash *phone_book = NULL;
      -   phone_book = eina_hash_string_superfast_new(_phone_entry_free_cb);
      -
      -   // Empty the phone book without destroying it
      -   eina_hash_free_buckets(phone_book);
      -   eina_hash_free(phone_book);
      -}
      -
      -
    6. -
    - - - - -

    Modifying Hash Table Content

    - -

    To modify hash table content:

    -
      -
    • -

      To add some data to a hash, use the eina_hash_add() function. This function takes the hash, the key to access the data, and the data as its parameters.

      -

      The following example shows how to add the initial data declared earlier to the hash:

      -
      -for (i = 0; _start_entries[i].name != NULL; i++)
      -{
      -   eina_hash_add(phone_book, _start_entries[i].name, strdup(_start_entries[i].number));
      -}
      -
      - -

      The Eina_Hash offers various ways to add elements to a hash, such as the eina_hash_direct_add() function, which adds the entry without duplicating the string key. The key is stored in the struct, so this function can be used with eina_stringshare to avoid key data duplication.

      -
      -for (i = 0; _start_entries[i].name != NULL; i++)
      -{
      -   // Allocating memory for the phone entry
      -   Phone_Entry *e = malloc(sizeof(Phone_Entry));
      -
      -   // Creating an eina_stringshare for the name and the phone number
      -   e->name = eina_stringshare_add(_start_entries[i].name);
      -   e->number = eina_stringshare_add(_start_entries[i].number);
      -
      -   // Adding the entry to the hash 
      -   eina_hash_direct_add(phone_book, e->name, e);
      -}
      -
      -
    • -
    • -

      To modify an entry, use eina_hash_modify() function passing the hash, the key of the data to change, and the new data. The function returns the old data on success.

      -

      The eina_hash_set() function does the same work as eina_hash_modify(), but if the entry does not exist, the function creates a new one.

      -
      -char *old_phone = NULL;
      -char *phone = NULL;
      -// Replace the phone number of Richard Strauss
      -old_phone = eina_hash_modify(phone_book, "Richard Georg Strauss", strdup("+23 45 111-11111"));
      -phone = eina_hash_set(phone_book, "Philippe de Magalhães", strdup("+33 6 111-11111"));
      -eina_hash_set(phone_book, "Richard Georg Strauss", strdup("+23 45 111-117711"));
      -
      -
    • -
    • -

      To change the key associated with the data without freeing and creating a new entry, use the eina_hash_move() function. You only have to pass the hash, the old key, and the new key. If the operation succeeds, the function returns EINA_TRUE, if not, it returns EINA_FALSE.

      -
      -Eina_Bool res;
      -res = eina_hash_move(phone_book, "Philippe de Magalhães", "Filipe de Magalhães");
      -
      -
    • -
    • -

      To delete entries from a hash table:

      -
      • Use the eina_hash_del() function to remove the entry identified by a key or data from the given hash table: -
        -Eina_Bool r;
        -const char *entry_name = "Heitor Villa-Lobos";
        -r = eina_hash_del(phone_book, entry_name, NULL);
        -
      • -
      • Use the eina_hash_del_by_key() function to remove an entry based on the key: -
        -r = eina_hash_del_by_key(phone_book, "Richard Georg Strauss");
        -
        -
      • -
      • -

        Use the eina_hash_del_by_data() function to remove an entry based on the data:

        -
        -r = eina_hash_del_by_data(phone_book, "+12 34 567-89101");
        -
        -
      • -
    - -

    Accessing Hash Table Data

    -

    To find hash table elements and get data based on the key name:

    -
      -
    • -

      To retrieve an entry based on its key, use the eina_hash_find() function by passing the hash and the key you are looking for:

      -
      -char *phone = NULL;
      -const char *entry_name = "Heitor Villa-Lobos";
      -
      -// Look for a specific entry and get its phone number
      -phone = eina_hash_find(phone_book, entry_name);
      -
      -
    • -
    • -

      To get the number of entries in a hash, use the eina_hash_population() function. Pass the hash as the only argument.

      -
      -unsigned int nb_elm;
      -nb_elm = eina_hash_population(phone_book);
      -
      -
    • - -
    • To iterate through a hash table, you can use various methods: -
        - -
      • to iterate over the hash table, use the eina_hash_foreach() function: - -
        • The first parameter is the hash.
        • -
        • The second parameter is the callback function called on each iteration. -

          The callback function has to return an Eina_Bool, EINA_TRUE if the iteration has to continue and EINA_FALSE if the iteration has to stop.

        • -
        • The last parameter one is the data passed to the callback function.
        - -

        The following example prints the key and the data of the hash entry (the name and the phone number):

        - -
        -static Eina_Bool
        -pb_foreach_cb(const Eina_Hash *phone_book, const void *key, void *data, void *fdata)
        -{
        -   const char *name = key;
        -   const char *number = data;
        -   printf("%s: %s\n", name, number);
        -
        -   // Return EINA_FALSE to stop this callback from being called
        -   return EINA_TRUE;
        -}
        -
        -printf("List of phones:\n");
        -
        -// Running the callback on the hash called phone_book 
        -eina_hash_foreach(phone_book, pb_foreach_cb, NULL);
        -printf("\n");
        -
        -
      • -
      • To iterate over the keys, use the eina_hash_iterator_key_new() function: -
        -// Declaration of the Eina_Iterator
        -Eina_Iterator *it;
        -
        -// Variable to handle the current iteration "data"
        -void *data;
        -
        -// Iterate over the keys (names)
        -printf("List of names in the phone book:\n");
        -
        -it = eina_hash_iterator_key_new(phone_book);
        -
        -// Use the generic eina_iterator_next()
        -while (eina_iterator_next(it, &data))
        -{
        -   const char *name = data;
        -   printf("%s\n", name);
        -}
        -
        -// Free the iterator
        -eina_iterator_free(it);
        -
        -
      • - -
      • To iterate over the hash data, use the eina_hash_iterator_data_new() function the same way as eina_hash_iterator_key_new(): -
        -// Declaration of the Eina_Iterator
        -Eina_Iterator *it;
        -
        -// Variable to handle the current iteration "data"
        -void *data;
        -
        -// Iterate over hash data 
        -printf("List of numbers in the phone book:\n");
        -
        -it = eina_hash_iterator_data_new(phone_book);
        -while (eina_iterator_next(it, &data))
        -{
        -   const char *number = data;
        -   printf("%s\n", number);
        -}
        -
        -// Free the iterator
        -eina_iterator_free(it);
        -
        -
      • -
      • To iterate over a tuple composed of keys and data, use the eina_hash_iterator_tuple_new() function: -
        -// Declaration of the Eina_Iterator
        -Eina_Iterator *tit;
        -
        -// Variable to handle the current iteration "data"
        -void *tuple;
        -
        -printf("List of phones:\n");
        -tit = eina_hash_iterator_tuple_new(phone_book);
        -while (eina_iterator_next(tit, &tuple))
        -{
        -   Eina_Hash_Tuple *t = tuple;
        -   const char *name = t->key;
        -   const char *number = t->data;
        -   printf("%s: %s\n", name, number);
        -}
        -
        -// Always free the iterator after its use
        -eina_iterator_free(tit); 
        -
        -
      • -
      -
    • -
    - - -

    Lists

    - -

    The Eina_List is a double-linked list that can store data of any type as void pointers. It provides a set of functions to create and manipulate the list to avoid the access to the struct's fields, similar to a self-made double-link list.

    -

    In addition to the previous and next node and its data, the Eina_List nodes keep a reference to an accounting structure. The accounting structure is used to improve the performance of some functions. The structure is private and must not be modified.

    - -

    In an Eina_List, everything is a "list": the list itself is a list where each node is a list as well.

    - -

    Eina provides 2 list types: the classic list (Eina_List) and an inline list (Eina_Inlist).

    - -

    Creating and Destroying a List

    -

    To use an Eina_List:

    - -
    1. Declare the list with NULL as the default value: -
      -int list()
      -{
      -   // Declaration of the Eina_List with NULL as default value;
      -   Eina_List *list = NULL;
      -
    2. - -
    3. Call the eina_list_append() function with the list and the data you want to append as parameters. -

      The list must be a pointer to the first element of the list (or NULL). The function returns a pointer to the list.

      -
      -   // Creating the first element of the list 
      -   list = eina_list_append(list, "watch");
      -
      -   // Adding more elements
      -   list = eina_list_append(list, "phone");
      -   list = eina_list_append(list, "ivi");
      -   list = eina_list_append(list, "notebook");
      -
    4. - -
    5. When you no longer need the list, free it: -
      -   // Free the Eina_List
      -   eina_list_free(list);
      -
      -   return 0;
      -}
      -
    6. -
    - - -

    Modifying List Content

    - -

    To modify list content:

    -
      -
    • -

      To add data to a list:

      - -
        -
      • To add data at the end of the list, use the eina_list_append() function. To add data at the top of the list, use eina_list_prepend(). The functions work in the same way, only adding the data to different places. -
        -list = eina_list_prepend(list, "set-top box");
        -
        -
      • - -
      • To insert data into the list after a specified data, use the eina_list_append_relative() function. As the last parameter, define the element after which the data is added. -

        For example to append data after the "phone" element:

        -
        -list = eina_list_append_relative(list, "single-board computer", "phone");
        -
        -
      • - -
      • To add a new entry before a specified data, use the eina_list_prepend_relative() function. It is similar to the eina_list_append_relative() function. -
        -list = eina_list_prepend_relative(list, "ultrabook", "ivi");
        -
        -
      • - -
      • To append a list node to a linked list after a specified member, use the eina_list_append_relative_list() function. To prepend a list node to a linked list before a specified member, use the Eina_List * eina_list_prepend_relative_list() function. -
      • -
      -
    • - -
    • To set data in a list member, use the eina_list_data_set() function. Pass the "list" (node) as the first argument and the data to set as the second. - -

      The following example also shows the usage of the eina_list_last() function, which returns the last element of an Eina_List.

      - -
      -// Setting new data for the last element
      -eina_list_data_set(eina_list_last(list), eina_stringshare_add("Boris"));
      -
      -
    • - -
    • To remove a node from the list, use the eina_list_remove() function. This function removes the first instance of the specified data from the given list. -
      -list = eina_list_remove(list, "ultrabook");
      -
      -

      You can also remove a "list" (node) from a list using the eina_list_remove_list() function. Pass the list you want to delete an element from and a 'list' (node) you want to delete.

      -
      -Eina_List *app_list = NULL;
      -Eina_List *to_remove = NULL;
      -
      -// Adding some elements to the list (using stringshares)
      -app_list = eina_list_append(app_list, eina_stringshare_add("enna"));
      -app_list = eina_list_append(app_list, eina_stringshare_add("ebird"));
      -app_list = eina_list_append(app_list, eina_stringshare_add("calaos"));
      -app_list = eina_list_append(app_list, eina_stringshare_add("rage"));
      -app_list = eina_list_append(app_list, eina_stringshare_add("terminology"));
      -app_list = eina_list_append(app_list, eina_stringshare_add("enlightenment"));
      -app_list = eina_list_append(app_list, eina_stringshare_add("eyelight"));
      -app_list = eina_list_append(app_list, eina_stringshare_add("ephoto"));
      -
      -// Finding the "list" to remove 
      -to_remove = eina_list_data_find_list(list, eina_string_share_add("enlightenment"));
      -
      -list = eina_list_remove_list(list, to_remove);
      -
      -
    • - -
    • To move elements in a list, you can use various function, such as eina_list_promote_list() that promotes an element to the top of the list or eina_list_demote_list() that puts the specified element at the end of the list. Remember that everything is a list so the second parameter represents the "list" (node) you want to move. Use the functions just like the eina_list_remove_list() function. -
      -list = eina_list_promote_list(list, eina_list_data_find_list(list, "ivi"));
      -
      -
    • -
    • To reverse all the elements of a list, use the eina_list_reverse() function. To obtain a reversed copy of the list while keeping the initial list unchanged, use the eina_list_reverse_clone() function. -
      -Eina_List *rev_copy;
      -
      -app_list = eina_list_reverse(app_list);
      -rev_copy = eina_list_reverse_clone(app_list);
      -
      -
    • -
    • To sort a list, use the eina_list_sort() function. This function takes a list which needs to be sorted, the maximum number of elements to be sorted, and a callback function that compares data. To sort all list elements, set the maximum number of elements to 0. -
      -int sort_cb(const void *d1, const void *d2)
      -{
      -   const char *txt = d1;
      -   const char *txt2 = d2;
      -   if(!txt) return(1);
      -   if(!txt2) return(-1);
      -
      -   return(strcmp(txt, txt2));
      -}
      -
      -extern Eina_List *list;
      -list = eina_list_sort(list, 0, sort_cb);
      -
      -
    • -
    • To merge 2 list into 1, use the eina_list_merge() function. The eina_list_sorted_merge() function merges 2 sorted lists according to the ordering function that you pass as the last argument. -
      -int sort_cb(void *d1, void *d2)
      -{
      -   const char *txt = NULL;
      -   const char *txt2 = NULL;
      -   if(!d1) return(1);
      -   if(!d2) return(-1);
      -
      -   return(strcmp((const char*)d1, (const char*)d2));
      -}
      -
      -Eina_List *sorted1;
      -Eina_List *sorted2;
      -Eina_List *newlist;
      -
      -// Insert some values and sort your lists
      -
      -// Simply merge 2 lists without any process
      -newlist = eina_list_merge(sorted1, sorted2);
      -
      -newlist = eina_list_sorted_merge(sorted1, sorted2, sort_cb);
      -
      -
    • -
    • To split a list, use the eina_list_split_list() function: -
      • The first parameter is the list to split.
      • -
      • The second parameter is the "list" (element) after which the list is split.
      • -
      • The last parameter is the head of the second list.
      -
      -// Original list (left list)
      -Eina_List *list = NULL;
      -
      -// New list (right list)
      -Eina_List *other_list = NULL;
      -
      -// Eina_List (element)
      -Eina_List *l;
      -
      -list = eina_list_append(list, "super tux");
      -list = eina_list_append(list, "frozen bubble");
      -list = eina_list_append(list, "lincity-ng");
      -
      -// Sorting the list (just for fun)
      -list = eina_list_sort(list, 0, cmp_func);
      -
      -// Looking for the 'split' element
      -l = eina_list_search_sorted_list(list, cmp_func, "frozen bubble");
      -
      -// Splitting the list
      -list = eina_list_split_list(list, l, &other_list);
      -
      -
    • -
    • To copy a list, use the eina_list_clone() function. The function copies all the elements in the list in the exact same order. -
      -Eina_List *app_list_copy;
      -
      -app_list_copy = eina_list_clone(app_list);
      -
      -
    • - -
    - - -

    Accessing List Data

    -

    To access list data:

    -
      -
    • To find some data on your list, use the eina_list_data_find() function. Pass the list containing your data as the first parameter and the data you are looking for as the last one. The function returns the found member data pointer if found, NULL otherwise. -

      The eina_list_data_find() function searches the list from the beginning to the end for the first member for which the data pointer is data. If it is found, the data is returned, otherwise NULL is returned. The function only compares pointers, which is why using Eina_Stringshare is very useful with lists, because it always returns the same pointer for the same string.

      -
      -Eina_List *app_list = NULL;
      -const char *res_str;
      -
      -// Adding some elements to the list (using stringshares)
      -app_list = eina_list_append(app_list, eina_stringshare_add("enna"));
      -app_list = eina_list_append(app_list, eina_stringshare_add("ebird"));
      -app_list = eina_list_append(app_list, eina_stringshare_add("calaos"));
      -app_list = eina_list_append(app_list, eina_stringshare_add("rage"));
      -app_list = eina_list_append(app_list, eina_stringshare_add("terminology"));
      -app_list = eina_list_append(app_list, eina_stringshare_add("enlightenment"));
      -app_list = eina_list_append(app_list, eina_stringshare_add("eyelight"));
      -app_list = eina_list_append(app_list, eina_stringshare_add("ephoto"));
      -
      -// Finding the data
      -res_str = eina_list_data_find(list, eina_string_share_add("enlightenment"));
      -if (res_str == eina_stringshare_add("enlightenment"))
      -   printf("Data is present");
      -else
      -   printf("Data not present");
      -
      - -

      The above example returns "Data is present".

      -

      The eina_list_data_find_list() function does the same thing as eina_list_data_find(), but returns an Eina_List. For an example, see the eina_list_remove_list() function.

      -

      You can access the data or a "list" (node) of an Eina_List using the eina_list_nth() and eina_list_nth_list() functions. The first one returns a pointer to the data of the "n" element and the second a pointer to the "list". To access the data of the 3rd element of an Eina_List:

      -
      -const char *res;
      -Eina_List *res_lst;
      -
      -res = eina_list_nth(app_list, 2);
      -res_lst = eina_list_nth_list(app_list, 2);
      -
      - -

      The res variable contains the pointer to the string "calaos". The res_lst variable is the list containing "calaos".

      -
    • - -
    • To search for data in a list, select your function based on whether the list is sorted or unsorted. -
        -
      • To search in an unsorted list, use the eina_list_search_unsorted() function: -
        • The first parameter is the list.
        • -
        • The second parameter is a callback function for comparison.
        • -
        • The last parameter is the data you are looking for.
        - -

        The eina_list_search_unsorted_list() function does the same but returns an "Eina_List".

        - - -

        The following example shows 2 searches using both the eina_list_search_unsorted() and eina_list_search_unsorted_list() functions:

        -
        -int search_list()
        -{
        -   // Declaring the list
        -   Eina_List *list = NULL; 
        -   Eina_List *l;
        -   // Little trick to use strcmp as Eina_Compare_Cb 
        -   Eina_Compare_Cb cmp_func = (Eina_Compare_Cb)strcmp;
        -
        -   void *data;
        -   int cmp_result;
        -
        -   list = eina_list_append(list, "debian");
        -   list = eina_list_append(list, "archlinux");
        -   list = eina_list_append(list, "centos");
        -
        -   data = eina_list_search_unsorted(list, cmp_func, "archlinux");
        -   l = eina_list_search_unsorted_list(list, cmp_func, "archlinux");
        -   if (l->data != data)
        -   {
        -      eina_list_free(list);
        -
        -      return 1;
        -   }
        -
        -   eina_list_free(list);
        -
        -   return 0;
        -}
        -
        - -
      • -
      • To search in sorted lists, use the eina_list_search_sorted_list() and eina_list_search_sorted() functions. They work similarly as the eina_list_search_unsorted() function. -
      • -
      -
    • - - -
    • To get data from a list element, use the eina_list_data_get() function. The function returns the data contained in the given list. - -

      The following example uses the eina_list_next() function to move through the list in a statement.

      -
      -int list_data_set()
      -{
      -   // Declaring the list
      -   Eina_List *list = NULL;
      -   // Eina_List in which to place the elements or lists
      -   Eina_List *l;
      -
      -   void *list_data;
      -
      -   list = eina_list_append(list, eina_stringshare_add("Bertrand"));
      -   list = eina_list_append(list, eina_stringshare_add("Cedric"));
      -   list = eina_list_append(list, eina_stringshare_add("Nicolas"));
      -   list = eina_list_append(list, eina_stringshare_add("Vincent"));
      -   list = eina_list_append(list, eina_stringshare_add("Raoul"));
      -   list = eina_list_append(list, eina_stringshare_add("Fabien"));
      -   list = eina_list_append(list, eina_stringshare_add("Philippe"));
      -   list = eina_list_append(list, eina_stringshare_add("billiob"));
      -
      -   for(l = list; l; l = eina_list_next(l))
      -      // Printing the data returned by eina_list_data_get
      -      printf("%s\n", (char*)eina_list_data_get(l));
      -
      -   EINA_LIST_FREE(list, list_data)
      -      eina_stringshare_del(list_data);
      -
      -   return 0;
      -}
      -
      -
    • - -
    • To move in a list, use the eina_list_last(), eina_list_next(), or eina_list_prev() functions to move to the last, next, or previous element in the list. -

      The following example scrolls backwards starting from the end of the list:

      -
      -for(l = eina_list_last(list); l; l = eina_list_prev(l))
      -   printf("%s\n", (char*)eina_list_data_get(l));
      -
      - -
    • - -
    • To count the list elements, use the eina_list_count() function. The function returns the number of items in a list. -
      -printf("List size: %d\n", eina_list_count(list));
      -
      -
    • -
    • To iterate through an array, you can use various iterators: -
        -
      • To iterate over a list from the beginning to the end, use the EINA_LIST_FOREACH macro: -
        • The first parameter is the list to iterate.
        • -
        • The second parameter is an Eina_List * to hold the current "List" (node).
        • -
        • The last parameter receives the current data during the run.
        - -

        The following example prints the data of each "List" (node) of the list:

        -
        -Eina_List *list = NULL;
        -Eina_List *l;
        -void *list_data;
        -
        -list = eina_list_append(list, "ls");
        -list = eina_list_append(list, "top");
        -list = eina_list_append(list, "rmdir");
        -list = eina_list_append(list, "uname");
        -
        -EINA_LIST_FOREACH(list, l, list_data)
        -   printf("%s\n", (char*)list_data);
        -
        -eina_list_free(list);
        -
        -
      • -
      • To iterate from the last element to the first, use the EINA_LIST_REVERSE_FOREACH macro. It works similarly as EINA_LIST_FOREACH(). -
      • -
      • To iterate over a list from the beginning to the end, you can also use the EINA_LIST_FOREACH_SAFE macro. It is called safe, because it stores the next "List" (node), so you can safely remove the current "List" (node) and continue the iteration. -
        -Eina_List *list;
        -Eina_List *l;
        -Eina_List *l_next;
        -char *data;
        -
        -list = eina_list_append(list, "tizen");
        -list = eina_list_append(list, "tizen");
        -list = eina_list_append(list, "tizen");
        -list = eina_list_append(list, "tizen");
        -
        -// Using EINA_LIST_FOREACH_SAFE to free the elements that match "tizen"
        -
        -EINA_LIST_FOREACH_SAFE(list, l, l_next, data)
        -   if (strcmp(data, "tizen") == 0) 
        -   {
        -      free(data);
        -      list = eina_list_remove_list(list, l);
        -   }
        -
        -
      • - - -
      • To remove each list element while having access to the node's data, use the EINA_LIST_FREE macro. Pass the list and a pointer to hold the current data. -
        -Eina_List *list;
        -char *data;
        -
        -// List is filled
        -
        -EINA_LIST_FREE(list, data)
        -   free(data);
        -
        -
      • -
      -
    • -
    - -

    Using an Inline List

    -

    The Eina_Inlist is a special data type drawn to store nodes pointers in the same memory as data. This way the memory is less fragmented, but operations, such as sort and count, are slower. The Eina_Inlist has its own purpose, but if you do not understand what the purpose is, use the regular Eina_List instead.

    - -

    The Eina_Inlist nodes can be part of a regular Eina_List, simply added with the eina_list_append() or eina_list_prepend() functions.

    - -

    To use the inline list:

    -
      -
    1. Define the structure of the data before creating the inline list: -
      -struct my_struct 
      -{
      -   EINA_INLIST;
      -   int a, b;
      -};
      -
      - -

      The structure is composed of 2 integers, the real data, and the EINA_INLIST type which is composed of 3 pointers defining the inline list structure:

      - -
        -
      • Eina_Inlist * next: next node
      • -
      • Eina_Inlist * prev: previous node
      • -
      • Eina_Inlist * last: last node
      • -
    2. - -
    3. -

      To create the inlist nodes, allocate the memory and use the eina_inlist_append() function:

      -
      • The first parameter is the existing list head or NULL to create a new list. -

        The following example passes NULL to create a new list.

      • -
      • The second parameter is the new list node, and it must not be NULL. -

        You must use the EINA_INLIST_GET() macro to get the inlist object of the datastruct.

      -
      -struct my_struct *d, *cur;
      -Eina_Inlist *list, *itr, *tmp;
      -
      -d = malloc(sizeof(*d));
      -d->a = 1;
      -d->b = 10;
      -
      -list = eina_inlist_append(NULL, EINA_INLIST_GET(d));
      -
      - -

      Repeat this operation for every new node:

      -
      -d = malloc(sizeof(*d));
      -d->a = 2;
      -d->b = 20;
      -list = eina_inlist_append(list, EINA_INLIST_GET(d));
      -
      -
    4. - -
    5. To add data to the inline list: -
      • Put data at the end of the inline list with the eina_inlist_prepend() function: -
        -d = malloc(sizeof(*d));
        -d->a = 3;
        -d->b = 30;
        -list = eina_inlist_prepend(list, EINA_INLIST_GET(d));
        -
        -
      • - -
      • Add a node before or after a given node with the eina_inlist_prepend_relative() and eina_inlist_append_relative() functions. -

        In both functions, the first parameter is the target list, the second is the element you want to add, and the last is the reference element to place data after (in this case). Similarly as in a regular Eina_List, everything is a list, so the last parameter is an Eina_Inlist typed variable.

        -
        d = malloc(sizeof(*d));
        -d->a = 4;
        -d->b = 40;
        -list = eina_inlist_append_relative(list, EINA_INLIST_GET(d), list);
        -
        -
    6. - -
    7. To sort and iterate an inline list, to find and move list elements, and to perform other inline list operations, see the Inline List API.
    8. - -
    9. When the inline list is no longer needed, destroy it by looping over the list to free each EINA_INLIST structure and the data using allocated memory. Use the eina_inlist_remove() function on each node. - -

      In the following example, the EINA_INLIST_CONTAINER_GET() macro returns the container object of an inlist (the EINA_INLIST of my_struc), and the list element is removed and the allocated memory of the container "object" is freed.

      - -
      while (list)
      -{
      -   struct my_struct *aux = EINA_INLIST_CONTAINER_GET(list, struct my_struct);
      -
      -   // Remove the current list element 
      -   list = eina_inlist_remove(list, list);
      -   free(aux);
      -}
      -
      -
    10. - - -
    - -

    Generic Value

    - -

    The Eina_Value object provides generic data storage and access, allowing you to store what you want in one single type of Eina_Value. It is meant for simple data types, providing uniform access and release functions, useful to exchange data preserving their types. The Eina_Value comes with predefined types for numbers, array, list, hash, blob, and structs, and it can convert between data types, including string.

    - -

    The Eina_Value can handle the following types:

    -
      -
    • EINA_VALUE_TYPE_UCHAR: unsigned char
    • -
    • EINA_VALUE_TYPE_USHORT: unsigned short
    • -
    • EINA_VALUE_TYPE_UINT: unsigned int
    • -
    • EINA_VALUE_TYPE_ULONG: unsigned long
    • -
    • EINA_VALUE_TYPE_TIMESTAMP: unsigned long used for timestamps
    • -
    • EINA_VALUE_TYPE_UINT64: unsigned integer of 64 bits
    • -
    • EINA_VALUE_TYPE_CHAR: char
    • -
    • EINA_VALUE_TYPE_SHORT: short
    • -
    • EINA_VALUE_TYPE_INT: int
    • -
    • EINA_VALUE_TYPE_LONG: long
    • -
    • EINA_VALUE_TYPE_INT64: integer of 64 bits
    • -
    • EINA_VALUE_TYPE_FLOAT: float
    • -
    • EINA_VALUE_TYPE_DOUBLE: double
    • -
    • EINA_VALUE_TYPE_STRINGSHARE: stringshared string
    • -
    • EINA_VALUE_TYPE_STRING: string
    • -
    • EINA_VALUE_TYPE_ARRAY: array
    • -
    • EINA_VALUE_TYPE_LIST: list
    • -
    • EINA_VALUE_TYPE_HASH: hash
    • -
    • EINA_VALUE_TYPE_TIMEVAL: 'struct timeval'
    • -
    • EINA_VALUE_TYPE_BLOB: blob of bytes
    • -
    • EINA_VALUE_TYPE_STRUCT: struct
    • -
    - - -

    To set up a generic value:

    -
      -
    1. Declare the necessary variables: -
      -// The Eina_Value itself
      -Eina_Value v;
      -// An integer 
      -int i;
      -// And a char *
      -char *newstr;
      -
      -
    2. - -
    3. To set up an Eina_Value for an integer, use the eina_value_setup() function. The first argument is the Eina_Value and the second is the type. -
      -eina_value_setup(&v, EINA_VALUE_TYPE_INT);
      -
      -
    4. -
    -

    To manage the generic value:

    -
      -
    • To set an integer, use the eina_value_set() function: -
      -eina_value_set(&v, 123);
      -
      -
    • - -
    • To get the value, use the eina_value_get() function. Pass the Eina_Value as the first argument, and a pointer to a variable to store the value (the target variable must have the same type as the Eina_Value). -
      -eina_value_get(&v, &i);
      -printf("v=%d\n", i);
      -
      -

      The above example prints "v=123".

      -
    • - -
    • To convert an Eina_Value to a string, use the eina_value_to_string() function. The code snippet above printed an int value. It is also possible to print the value as a string. -
      -newstr = eina_value_to_string(&v);
      -printf("v as string: %s\n", newstr);
      -
      -free(newstr);
      -
      -
    • - -
    • To free the memory allocated by eina_value_to_string(), use the eina_value_flush() function: -
      -eina_value_flush(&v);
      -
      -
    • - -
    • To store a string, get its value, and print it: -
      -const char *s;
      -
      -eina_value_setup(&v, EINA_VALUE_TYPE_STRING);
      -eina_value_set(&v, "My string");
      -eina_value_get(&v, &s);
      -
      -printf("v=%s (pointer: %p)\n", s, s);
      -
      -
    • - -
    • To set up a string, use the eina_value_to_string() function with an Eina_Value: -
      -char *newstr; 
      -
      -newstr = eina_value_to_string(&v);
      -printf("v as string: %s (pointer: %p)\n", newstr, newstr);
      -
      -// Free the memory allocated by eina_value_to_string
      -free(newstr);
      -
      -eina_value_flush(&v); 
      -
      -
    • - -
    • To convert from one Eina_Value to another, use the eina_value_convert() function. -

      The function puts the converted value into another Eina_Value. It accepts pointers, so you have to pass an Eina_Value pointer.

      -
      -Eina_Value v;
      -Eina_Value otherv;
      -
      -// Set up 2 Eina_Values: 1 int and 1 string
      -eina_value_setup(&otherv, EINA_VALUE_TYPE_STRING);
      -eina_value_setup(&v, EINA_VALUE_TYPE_INT);
      -
      -// Convert from int to string
      -eina_value_set(&v, 123);
      -eina_value_convert(&v, &otherv);
      -eina_value_get(&otherv, &s);
      -printf("otherv=%s\n", s);
      -
      -// Another way to do the same 
      -eina_value_set(&otherv, "33");
      -eina_value_convert(&otherv, &v);
      -eina_value_get(&v, &i);
      -printf("v=%d\n", i);
      -
      -// Clean your values
      -eina_value_flush(&otherv);
      -eina_value_flush(&v);
      -
      -
    • - -
    • To store an Eina_List, use the Eina_Value that corresponds to the EINA_VALUE_TYPE_LIST type. -
    • -
    • To create an Eina_Value_List, use the eina_value_list_setup() function. The function initializes a generic value storage of the list type. The first parameter is the "object" value, and the second one is the type (how to manage the stored list members). -
    • -
    - - - -
    - -Go to top - - - - - - - \ No newline at end of file diff --git a/org.tizen.guides/html/native/ui/ecore_n.htm b/org.tizen.guides/html/native/ui/ecore_n.htm deleted file mode 100644 index cfdbba0..0000000 --- a/org.tizen.guides/html/native/ui/ecore_n.htm +++ /dev/null @@ -1,65 +0,0 @@ - - - - - - - - - - - - - Ecore - - - - - -
    - -

    Ecore

    -

    The Ecore library provides convenience functions, which allow you to manage the application main loop and threading.

    - -

    The main features of Ecore are:

    -
      -
    • Main Loop

      Enables you to manage the main loop and get data.

    • -
    • Thread Usage

      Enables you to use threads with the Ecore main loop.

    • -
    - - - -
    - -Go to top - - - - - - - \ No newline at end of file diff --git a/org.tizen.guides/html/native/ui/edc_part_block_n.htm b/org.tizen.guides/html/native/ui/edc_part_block_n.htm deleted file mode 100644 index 0d4faf4..0000000 --- a/org.tizen.guides/html/native/ui/edc_part_block_n.htm +++ /dev/null @@ -1,2071 +0,0 @@ - - - - - - - - - - - - - Edje Parts and Blocks - - - - - -
    - -

    Edje Parts and Blocks

    - - - -

    Edje Blocks

    - -

    A typical Edje file starts with the following definitions:

    - -
    -images {}
    -fonts {}
    -color_classes {}
    -styles {}
    -collections 
    -{
    -   sounds 
    -   {
    -      tone: "tone-1" 2300;
    -      tone: "tone-2" 2300;
    -      sample 
    -      {
    -         name: "sound1" RAW;
    -         source: "sound_file1.wav";
    -      }
    -   }
    -   group {}
    -   group {}
    -}
    -
    - -

    To get more details above each sub-block, click on the links inside the collections block above.

    - - - - - - - - - - -
    Note
    This guide is based on original work from Andres Blanc (dresb) andresblanc@gmail.com, it has been heavily expanded and edited since then.
    - -

    Images Block

    - -
    -images 
    -{
    -   image: "filename1.ext" COMP;
    -   image: "filename2.ext" LOSSY 99;
    -   set {}
    -   set {}
    -}
    -
    - -

    The images block is used to list each image file which are used in the theme. If any compression method is used, it is also defined here. Besides the document's root, additional images blocks can be included inside other blocks, usually collections, group, and part. This makes file list maintenance easier when the theme is split among multiple files.

    - -
      -
    • image [image file] [compression method] (compression level) -

      This is included in each image file. The full path to the directory holding the images can be defined later with edje_cc's "-id" option. Available compression methods are:

      -
        -
      • RAW: Uncompressed
      • -
      • COMP: Lossless compression
      • -
      • LOSSY [0-100]: JPEG lossy compression with quality from 0 to 100
      • -
      • USER: Not embedded to the file, refer to the external file instead
      • -
      -
    • -
    - -

    Images.set Block

    - -
    -set 
    -{
    -   name: "image_name_used";
    -   image {}
    -   image {}
    -}
    -
    - -

    The set block is used to define an image with different content depending on their size. Besides the document's root, additional set blocks can be included inside other blocks, normally collections, group, and part. This makes file list maintenance easier when the theme is split among multiple files.

    - -
      -
    • name [image name] -

      Defines the name that refer to this image description.

      -
    • -
    - -

    Images.set.image Block

    - -
    -image 
    -{
    -   image: "filename4.ext" COMP;
    -   size: 51 51 200 200;
    -   border: 0 0 0 0;
    -   border_scale_by: 0.0;
    -}
    -
    - -

    The image block inside a set block defines the characteristic of an image. Every block describes one image and the size rule to use it.

    - -

    For full documentation, see Image.

    - -
      -
    • image [image file] [compression method] (compression level) -

      This is included in each image file. The full path to the directory holding the images can be defined later with edje_cc's -id option. Available compression methods are:

      -
        -
      • RAW: Uncompressed
      • -
      • COMP: Lossless compression
      • -
      • LOSSY [0-100]: JPEG lossy compression with quality from 0 to 100
      • -
      • USER: Not embedded to the file, refer to the external file instead
      • -
      -
    • -
    • size [minw] [minh] [maxw] [maxh] -

      Defines the minimum and maximum size that selects the specified image.

      -
    • -
    • border [left] [right] [top] [bottom] -

      If set, the area (in pixels) of each side of the image is displayed as a fixed size border, from the side to inwards, preventing the corners from being changed on a resize.

      -
    • -
    • border_scale_by [value] -

      If border scaling is enabled then normally the OUTPUT border sizes (e.g. if 3 pixels on the left edge are set as a border, then normally at scale 1.0, those 3 columns are always the exact 3 columns of output, or at scale 2.0 they will be 6 columns, or 0.33 they will merge into a single column). This property multiplies the input scale factor by this multiplier, allowing the creation of supersampled borders to make much higher resolution outputs possible by always using the highest resolution artwork and then runtime scaling it down. Valid values are: 0.0 or bigger (0.0 or 1.0 to turn it off).

      -
    • -
    - -

    Fonts Block

    - -
    -fonts 
    -{
    -   font: "filename1.ext" "fontname";
    -   font: "filename2.ext" "otherfontname";
    -}
    -
    - -

    The fonts block is used to list each font file with an alias used later in the theme. As with the images block, additional fonts blocks can be included inside other blocks.

    - -
      -
    • font [font filename] [font alias] -

      Defines each font file and alias, the full path to the directory containing the font files can be defined with edje_cc's -fd option. -

    • -
    - -

    Data Block

    - -
    -data 
    -{
    -   item: "key" "value";
    -   file: "otherkey" "filename.ext";
    -}
    -
    - -

    This block behaves in the same way as the data block inside the parts, only the use-cases are different: this is useful for data that is for the whole theme, for instance license information, version, authors, and so on.

    - -

    Color_classes Block

    - -
    -color_classes 
    -{
    -   color_class 
    -   {
    -      name: "colorclassname";
    -      color: [0-255] [0-255] [0-255] [0-255];
    -      color2: [0-255] [0-255] [0-255] [0-255];
    -      color3: [0-255] [0-255] [0-255] [0-255];
    -   }
    -}
    -
    - -

    The color_classes block contains a list of one or more color_class blocks. Each color_class allows the designer to name an arbitrary group of colors to be used in the theme, the application can use that name to alter the color values at runtime.

    - -
      -
    • name [color class name] -

      Sets the name for the color class, used as reference by both the theme and the application.

      -
    • - -
    • color [red] [green] [blue] [alpha] -

      The main color.

      -
    • - -
    • color2 [red] [green] [blue] [alpha] -

      Used as outline in text and textblock parts.

      -
    • - -
    • color3 [red] [green] [blue] [alpha] -

      Used as shadow in text and textblock parts.

      -
    • -
    - -

    Styles Block

    - -
    -styles 
    -{
    -   style 
    -   {
    -      name: "stylename";
    -      base: "..default style properties..";
    -      tag: "tagname" "..style properties..";
    -   }
    -}
    -
    - -

    The styles block contains a list of one or more style blocks. A style block is used to create style <tags> for advanced TEXTBLOCK formatting.

    - -
      -
    • name [style name] -

      The name of the style to be used as reference later in the theme.

      -
    • - -
    • base [style properties string] -

      The default style properties that is applied to the complete text. The available tags that can be used in the style property are the following:

      -
        -
      • font
      • -
      • font_size - - - - - - - - - -
        Note
        The font size is a point size, and the size of the rendered text is affected by the ppi information. The system basic ppi is 96, and you can change it on the Emulator menu.
        - -
      • -
      • color
      • -
      • color_class
      • -
      • text_class
      • -
      • ellipsis
      • -
      • wrap
      • -
      • style
      • -
      • valign
      • -
      • align
      • - -
      - -
    • - -
    • tag [tag name] [style properties string] -

      Style to be applied only to text between style <tags>..</tags>. When creating paired tags, like <bold></bold>, a '+' sign must be added at the start of the style properties of the first part (<bold>). If the second part (</bold>) is also defined, a '-' sign must be added to its style properties. This applies only to paired tags; single tags, like <tab>, must not have a starting '+'.

      -
        -
      • br
      • -
      • tab
      • -
      • b
      • -
      • match
      • -
      - -
    • -
    - -

    The following code is the sample of a text style for the text style:

    - -
    -style 
    -{ 
    -   name: "list_text_main";
    -   base: "font=Tizen:style=Regular font_size=30 color=#ffffff ellipsis=1.0";
    -   tag: "br" "\n";\
    -   tag: "ps" "ps";\
    -   tag: "tab" "\t";\
    -   tag: "b" "+ font_weight=Bold";
    -}
    -
    - - - -

    Collections Block

    - -
    -collections 
    -{
    -   base_scale: 1.8;
    -   sounds 
    -   {
    -      tone: "tone-1" 2300;
    -      tone: "tone-2" 440;
    -      sample 
    -      {
    -         name: "sound_file1" RAW;
    -         source: "sound_file1.wav";
    -      }
    -   }
    -   group 
    -   {
    -      name: "groupname";
    -      alias: "anothername;"
    -      min: width height;
    -      max: width height;
    -      parts {}
    -      scripts {}
    -      limits {}
    -      data {}
    -      programs {}
    -   }
    -}
    -
    - -

    The collections block is used to list the groups that compose the theme. Additional collections blocks do not prevent overriding group names.

    - -

    The sounds block contains a list of one or more sound sample and tone items.

    - -

    Base Scale

    - -
      -
    • base_scale: [scale factor] -

      Information about the scale factor in the edc file.

      -
    • -
    - -

    Object scaling must be defined in the config.xml file of this application to show the application in a proper size in other devices. However, the scaling must be based on the scale 1.0 or, if the application is based on another scale, this scale must be defined in the config.xml file. This predefined scale is called the "base scale".

    - -

    The size of a scalable object is multiplied with the device scale value. If the scalable object with the size 10 is created in a device with the scale 1.0, the size of the object is 20 in a device with the scale 2.0, and 40 in a device with the scale 4.0.

    - -

    For more information about supporting multiple screens in one edc, see the Multiple Screen Support guide.

    - - -

    Sounds Block

    - -

    -
      -
    • tone [tone name] [frequency] -

      A sound of the given frequency.

      -
    • -
    - - -

    Sounds.sample Block

    - -

    The sample block defines the sound sample.

    - -

    -
      -
    • name [sample name] [compression type] (quality) -

      Used to include each sound file. The full path to the directory holding the sounds can be defined later with edje_cc's -sd option. Valid types are:

      -
        -
      • RAW: Uncompressed
      • -
      • COMP: Lossless compression
      • -
      • LOSSY [-0.1 - 1.0]: Lossy compression with quality from 0.0 to 1.0
      • -
      • AS_IS: No compression or encoding, write the file information as it is
      • -
      -
    • -
    - -

    -
      -
    • source [file name] -

      The sound source file name (source can be mono/stereo WAV file. Only files with 44.1 KHz sample rate are supported for now).

      -
    • -
    - - -

    Group Block

    - -
    -group 
    -{
    -   name: "nameusedbytheapplication";
    -   alias: "anothername";
    -   min: width height;
    -   max: width height;
    -   parts 
    -   {
    -      <definitions of parts>
    -   }
    -   script 
    -   {
    -      <embryo script>
    -   }
    -   limits 
    -   {
    -      vertical: "limit_name" height_barrier;
    -      horizontal: "limit_name" width_barrier;
    -   }
    -   data 
    -   {
    -      items: "key" "value";
    -      file: "key" "file";
    -   }
    -   programs {}
    -}
    -
    - -

    Group

    - -

    A group block contains the list of parts and programs that compose a given Edje Object.

    - -
      -
    • name [group name] -

      The name that is used by the application to load the resulting Edje object and to identify the group to swallow in a GROUP part. If a group with the same name exists already it will be completely overridden by the new group.

      -
    • - -
    • inherit_only [1 or 0] -

      This flags the group as being used only for inheriting, which will inhibit edje_cc resolving of programs and parts that may not exist in this group, but are located in the group which is inheriting this group.

      -
    • - -
    • inherit [parent group name] -

      Parent group name for inheritance. Group inherit is used to inherit any predefined group and change some property which belongs to part, description, items or program. The child group has the same properties as its parent group. If you specify the type again in an inherited part, it causes an error.

      - - - - - - - - - -
      Note
      When inheriting any parts, descriptions without state names are not allowed.
      -
    • - -
    • script_recursion [1/0] -

      This flag (1 or 0) determines whether to error on unsafe calls when recursively running Embryo programs. For example, running an Embryo script which calls EDC that has a script{} block is unsafe, and the outer-most (first) Embryo stack is corrupted. It is strongly unadvisable to use this flag.

    • - -
    • alias [additional group name] -

      Additional name to be used as an identifier. Defining multiple aliases is supported.

      -
    • - -
    • min [width] [height] -

      The minimum size for the container defined by the composition of the parts. It is not enforced.

      -
    • - -
    • max [width] [height] -

      The maximum size for the container defined by the totality of the parts. It is not enforced.

      -
    • - -
    • broadcast_signal [on/off] -

      Signal gets automatically broadcasted to all sub group parts. Default is "true".

      -
    • - -
    • orientation [AUTO/LTR/RTL] -

      This defines GROUP orientation. It is useful if you want match interface orientation with language.

      -
        -
      • AUTO: Follow system defaults
      • -
      • LTR: Used in Left To Right Languages (Latin)
      • -
      • RTL: Used in Right To Left Languages (Hebrew, Arabic interface)
      • -
      -
    • - -
    • mouse_events [1 or 0] -

      Changes the default value of mouse_events for every part in this group. Default is "1", to maintain compatibility.

      -
    • - -
    • program_source [source name] -

      Change the default value of source for every program in the current group which is declared after this value is set. Defaults to an unset value to maintain compatibility. The name of source can be set on every program, but if the name can be defined in the group level, it reduces the effort to indicate it in every program.

      -
    • -
    - -

    Group.parts

    - -
    -parts 
    -{
    -   part {}
    -   part {}
    -   part {}
    -}
    -
    - -

    The parts group contain one or more part. Each part describes a visual element and has a type: text, image, table, etc.

    - -

    For complete documentation, see the Part Block guide.

    - -

    Group.script

    - -
    -group 
    -{
    -   script 
    -   {
    -      <embryo script>
    -   }
    -   program 
    -   {
    -      script 
    -      {
    -         <embryo script>
    -      }
    -   }
    -}
    -
    - -

    This block is used to inject embryo scripts to a given Edje theme and it functions in two modalities. When it is included inside a program block, the script is executed every time the program is run, on the other hand, when included directly into a group, part, or description block, it is executed once at the load time, in the load order.

    - -

    For more information, see the Program guide.

    - -

    Group.limits

    - -
    -limits 
    -{
    -   vertical: "limit_name" height_barrier;
    -   horizontal: "limit_name" width_barrier;
    -}
    -
    - -

    This block is used to trigger signals when the Edje object is resized.

    -

    -
      -
    • vertical [name] [height barrier] -

      This sends a signal limit,name,over when the object is resized and passes the limit by growing over it. When the object's size is reduced below the limit, signal limit,name,below is sent. This limit is applied on the y axis and is given in pixels.

      -
    • -
    - -

    -
      -
    • horizontal [name] [width barrier] -

      This sends a signal limit,name,over when the object is resized and passes the limit by growing over it. When the object's size is reduced below the limit, signal limit,name,below is sent. This limit is applied on the x axis and is given in pixels.

      -
    • -
    - -

    Group.data

    - -
    -data 
    -{
    -   item: "key" "value";
    -   file: "key2" "somefile";
    -}
    -
    - -

    The data block is used to pass arbitrary parameters from the theme to the application. Unlike the images and fonts blocks, additional data blocks can only be included inside the group block.

    - -
      -
    • items: "key" "value"; -

      Defines a new parameter, the value is the string specified next to it.

      -
    • -
    • file: "key" "file"; -

      Defines a new parameter, the value is the contents of the specified file formatted as a single string of text. This property only works with plain text files.

      -
    • -
    - - - - - - - - - - -
    Note
    For genlist item styles, keys must be texts and icons, respectively for text parts and swallow parts; values must the names of the parts, separated with spaces.
    - -

    Group.programs

    - -
    -programs 
    -{
    -   program {}
    -   program {}
    -   program {}
    -}
    -
    - -

    The programs group contain one or more program.

    - -

    For more information about the program structure, see the Program guide.

    - - -

    Part Block

    - -
    -part 
    -{
    -   // inherit all the fields of another part
    -   inherit: "partname";
    -   // name the part
    -   name: "partname";
    -   // set the part type
    -   type: IMAGE;
    -   // enable mouse events on the part
    -   mouse_events: 0/1;
    -   // repeat mouse events to parts below the current one
    -   repeat_events: 0/1;
    -   ignore_flags: NONE;
    -   // whether the part sizes scale with the edje scaling factor
    -   scale: 0/1;
    -   // whether fully-transparent pixels are taken into account for collision detection
    -   precise_is_inside: 0/1;
    -   // only render the area of the part that coincides with the given part
    -   clip_to: "anotherpart";
    -   // for group/textblock parts: swallow the given group (for textblock: goes below text)
    -   source: "groupname";
    -   // same as source but goes on top of text
    -   source2: "groupname";
    -   // for textblock parts: swallow the given group below the mouse cursor when it hovers over the part
    -   source3: "groupname";
    -   // same as source3 but goes on top of the cursor
    -   source4: "groupname";
    -   // for textblock parts: swallow the given group below text anchors (<a>...</a>)
    -   source5: "groupname";
    -   // same as source5 but goes on to top of the anchor
    -   source6: "groupname";
    -   // add a shadow effect to the part
    -   effect: SOFT_SHADOW (BOTTOM_RIGHT);
    -   // for textblock parts: makes the text editable, possibly with a specific behavior
    -   entry_mode: PASSWORD;
    -   // for textblock parts: change how the tex selection is triggered
    -   select_mode: EXPLICIT;
    -   // for editable textblock parts: where to draw the (blinking) cursor
    -   cursor_mode: UNDER;
    -   // for editable textblock parts: allow multiple lines
    -   multiline: 0/1;
    -   // for textblock parts: accessibility features will be used
    -   access: 0/1;
    -   // no-one uses that
    -   pointer_mode: AUTOGRAB;
    -   use_alternate_font_metrics: 0/1;
    -   // remove the given program; useful when it was inherited
    -   program_remove: "programname";
    -   // remove the given part; useful when it was inherited
    -   part_remove: "partname";
    -   // insert the current part below the given part, as if it were declared before
    -   insert_before: "partname";
    -   // insert the current part above the given part, as if it were declared after
    -   insert_after: "partname";
    -   // define a new part inside this one
    -   part 
    -   {
    -      <part definition>
    -   }
    -   draggable 
    -   {
    -      // confine the current part to the given part
    -      confine: "another part";
    -      // only start drag when it would have moved enough to be outside of the given part
    -      threshold: "another part";
    -      // forward drag events to the given part instead of handling them
    -      events: "another draggable part";
    -      // enable horizontal drag of the part with steps each step_size or with steps_count steps
    -      x: 0/1 <step_size> <steps_count>;
    -      // same as x but vertical
    -      y: 1 0 100;
    -   }
    -   // for box or table parts
    -   box/table 
    -   {
    -      // list of items
    -      items 
    -      {
    -         item 
    -         {
    -            // define item type, can only be GROUP
    -            type: GROUP;
    -            // name the item
    -            name: "name";
    -            // set the source for this item, i.e. its contents
    -            source: "groupname";
    -            // minimum horizontal and vertical item sizes (-1 for expand)
    -            min: -1 -1;
    -            // maximum horizontal and vertical item sizes (-1 for ignore)
    -            max: 100 100;
    -            // set the item padding in pixels
    -            padding: 2 2 2 2;
    -            spread: 1 1;
    -            // set the item alignment
    -            align: 0.5 0.5;
    -            // set a weight hint in the box for the given object
    -            weight: 1 1;
    -            // set the aspect ratio hint
    -            aspect: 1 1;
    -            aspect_mode: BOTH;
    -            // number of columns and rows the item will take
    -            span: 1 1;
    -         }
    -      }
    -   }
    -   description 
    -   {
    -      // inherit another description
    -      inherit: "default" 1.0;
    -      // name the current description
    -      state: "default" 1.0;
    -      // use another part as content of the current "PROXY" part (This description only works in the PROXY part and the current part mirrors the rendering content of the source part)
    -      source: "partname";
    -      // make the part (in)visible (invisible parts emit no signals)
    -      visible: 0/1;
    -      // emit a signal when the given dimension becomes zero or stops being zero
    -      limit: WIDTH;
    -      // horizontal and vertical alignment of the part inside its parent
    -      align: 0.5 0.5;
    -      // set that the part does not change size
    -      fixed: 0/1 0/1;
    -      // set the minimum size for the part
    -      min: 200 200;
    -      // forcibly multiply the minimum sizes by the given factors
    -      minmul: 1.2 1.2;
    -      // set the maximum size for the part
    -      max: 400 400;
    -      // make vertical and horizontal resizes happen in steps
    -      step: 0 0;
    -      // force aspect ratio to be kept between min and max between resizes
    -      aspect: 0.8 1.2;
    -      // the dimension to which the aspect ratio applies
    -      aspect_preference: BOTH;
    -      // use the given color class which can be used to factor font colors
    -      color_class: "colorclassname";
    -      // set the text color
    -      color: 255 0 0 255;
    -      // set the color of the text's shadow
    -      color2: 0 255 0 255;
    -      // set the color of the text's outline
    -      color3: 0 0 255 255;
    -      // define the positions of the top-left (rel1) and bottom-right (rel2) corners
    -      rel1/rel2 
    -      {
    -         // make relative and offset use the given part for their positioning
    -         to: "partname";
    -         // position the corner relative to the part given through to (0.0 being axis beginning, 1.0 being its end)
    -         relative: 0.1 0.1;
    -         // add an absolute offset (in pixels) along each axis
    -         offset: 10 10;
    -         // same as to but only for the x axis
    -         to_x: "partname";
    -         // same as to but only for the y axis
    -         to_y: "partname";
    -      }
    -      // settings specific to parts of type image
    -      image 
    -      {
    -         // name (not path) of the regular image
    -         normal: "imagename";
    -         // image to use while transitioning to the normal image; use several times to create animations
    -         tween: "imagename2";
    -         // set the number of pixels that make up each border of the image, i.e. are not resized when the image is
    -         border: 4 4 4 4;
    -         // hide, strip from its alpha or show (default) the non-border part of the image
    -         middle: DEFAULT;
    -         border_scale_by: 1.0;
    -         // whether to scale the border or not
    -         border_scale: 0/1;
    -         scale_hint: STATIC;
    -         // set how the image is going to fill its part
    -         fill: 
    -         {
    -            // whether to smooth the image when scaling it
    -            smooth: 0/1;
    -            spread: ??;
    -            // whether to scale or tile to fit when resizing the image is needed
    -            type: SCALE/TILE;
    -            // only display the part of the image that is below and to the right of the given point
    -            origin 
    -            {
    -               // specify top-left point as relative coordinates
    -               relative: 0.1 0.1;
    -               // specify top-left point as a pixel offset
    -               offset: 10 10;
    -            }
    -            // specify bottom-right point as relative coordinates
    -            size 
    -            {
    -               relative: 0.1 0.1;
    -               // specify bottom-right point as a pixel offset
    -               offset: 10 10;
    -            }
    -         }
    -      }
    -      // settings specific to parts of type text and textblock
    -      text 
    -      {
    -         // set the part's text
    -         text: "some text";
    -         // set the text's font
    -         font: "Tizen Sans";
    -         // set the text's size
    -         size: 14;
    -         // set the text's class which can be used to factor font and font-size settings
    -         text_class: "classname";
    -         // use the styles defined in stylename
    -         style: "stylename";
    -         // for textblocks in password mode, replace characters to hide with this string
    -         repch: "*";
    -         // set the min and max font sizes allowed when resizing (default is 0 0, i.e. unrestricted)
    -         size_range: 6 18;
    -         // increase font size as much as possible while still remaining in the container for both axis
    -         fit: 0/1 0/1;
    -         // make the min size of the container equal to the min size of the current text (0 0 by default)
    -         min: 0/1 0/1;
    -         // make the max size of the container equal to the max size of the current text (0 0 by default)
    -         max: 0/1 0/1;
    -         // set the vertical and horizontal alignments of the text
    -         align: 0.5 0.5;
    -         // re-use the text of another part
    -         text_source: "partname";
    -         // when text is too long to fit, relative position at which to cut the text and put an ellipsis ("...")
    -         ellipsis: 0.9;
    -      }
    -      // settings specific to parts of type box
    -      box 
    -      {
    -         // set how children while be arranged in the box
    -         layout: horizontal_homogeneous;
    -         // set the vertical and horizontal alignments of box
    -         align: 0.5 0.5;
    -         // set the padding between items of the box
    -         padding: 1 1;
    -         // make the box' min size be the min size of its elements (i.e. make it shrinkable as much as its items)
    -         min: 0 1;
    -      }
    -      table 
    -      {
    -         // make items homogeneous
    -         homogeneous: NONE;
    -         // set the vertical and horizontal alignments of box
    -         align: 0.5 0.5;
    -         // set the padding between items of the box
    -         padding: 1 1;
    -         // make the table's min size be the min size of its elements (i.e. make it shrinkable as much as its items)
    -         min: 0 1;
    -      }
    -      map 
    -      {
    -         perspective: "partname";
    -         light: "partname";
    -         on: 0/1;
    -         smooth: 0/1;
    -         alpha: 0/1;
    -         backface_cull: 0/1;
    -         perspective_on: 0/1;
    -         color: 0/1;
    -         rotation 
    -         {
    -            center: "partname";
    -            x: 45;
    -            y: 120;
    -            z: 90;
    -         }
    -         perspective 
    -         {
    -            zplane: 0/1;
    -            focal: 20;
    -         }
    -         // simpler syntax to create transitions to the current part
    -         link 
    -         {
    -            base: "edje,signal" "edje";
    -         }
    -      }
    -   }
    -}
    -
    - -

    Part

    - -
    -part 
    -{
    -   name: "partname";
    -   type: IMAGE;
    -   mouse_events:  1;
    -   repeat_events: 0;
    -   ignore_flags: NONE;
    -   clip_to: "anotherpart";
    -   source:  "groupname";
    -   pointer_mode: AUTOGRAB;
    -   use_alternate_font_metrics: 0;
    -
    -   dragable {}
    -   items {}
    -   description {}
    -}
    -
    - -

    Parts are used to represent the most basic design elements of the theme, for example, a part can represent a line in a border or a label on a button.

    - -
      -
    • inherit [part name] -

      Copies all attributes except part name from referenced part into current part. All existing attributes, except part name, are overwritten.

      - - - - - - - - - -
      Note
      When inheriting any parts, descriptions without state names are not allowed.
      -
    • - -
    • program_remove [program name] (program name) (program name) ... -

      Removes the listed programs from an inherited group. Removing non-existing programs is not allowed.

      - - - - - - - - - -
      Note
      This breaks program sequences if a program in the middle of the sequence is removed.
      -
    • - -
    • part_remove [part name] (part name) (part name) ... -

      Removes the listed parts from an inherited group. Removing non-existing parts is not allowed.

      -
    • - -
    • name [part name] -

      The part's name is used as reference in the theme's relative positioning system, by programs and in some cases by the application. It must be unique within the group.

      -
    • - -
    • type [TYPE] -

      Sets the type. This is set to IMAGE by default. Valid types are:

      -
        -
      • RECT: Rectangle object in the screen
      • -
      • TEXT: Simple text
      • -
      • IMAGE: Image area
      • -
      • SWALLOW: Area where you can add the object
      • -
      • TEXTBLOCK: Complex text with multiple lines, mark-up elements, and such.
      • -
      • GROUP: Part which can include other groups in the same group.
      • -
      • BOX: Container object as a container. It has a row or column.
      • -
      • TABLE: Container object as a container. It has a row and column.
      • -
      • PROXY: Clone of another part in the same group. It shares the memory of the source part.
      • - -
      • SPACER: Rectangle object, but invisible. Recommended to padding because it does not allocate any memory.
      • - -
      -
    • - -
    • part [part declaration] -

      Nested parts adds hierarchy to Edje. Nested part inherits its location relatively to the parent part. To declare a nested part create a new part within current part declaration. Define parent part name before adding nested parts.

      -
      -part 
      -{
      -   name: "parent_rect";
      -   type: RECT;
      -   description {}
      -   part 
      -   {
      -      name: "nested_rect";
      -      type: RECT;
      -      description {}
      -   }
      -}
      -
      -
    • - -
    • insert_before [another part's name] -

      The part's name which this part is inserted before. One part cannot have both insert_before and insert_after. One part cannot refer more than one by insert_before.

      -
    • - -
    • insert_after [another part's name] -

      The part's name which this part is inserted after. One part cannot have both insert_before and insert_after. One part cannot refer more than one by insert_after.

      -
    • - -
    • mouse_events [1 or 0] -

      Specifies whether the part emits signals, although it is named mouse_events. Disabling it (0) prevents the part from emitting signal. It is set to 1 by default, or to the value set to mouse_events at the group level, if any.

      -
    • - -
    • repeat_events [1 or 0] -

      Specifies whether a part echoes a mouse event to other parts below the pointer (1), or not (0). It is set to 0 by default.

      -
    • - -
    • ignore_flags [FLAG] ... -

      Specifies whether events with the given flags are ignored, i.e., do not emit signals to the parts. Multiple flags must be separated by spaces, the effect is ignoring all events with one of the flags specified. Possible flags are:

      -
        -
      • NONE: Event is handled properly (default value)
      • -
      • ON_HOLD: Event is not handled or passed in this part
      • - -
      -
    • - -
    • scale [1 or 0] -

      Specifies whether the part scales its size with an Edje scaling factor. By default scale is off (0) and the default scale factor is 1.0 which means no scaling. This is used to scale properties such as font size, min/max size of the part, and it can also be used to scale based on DPI of the target device. The reason to be selective is that some parts are scaled well, others are not, so choose what works best.

      -
    • - -
    • pointer_mode [MODE] -

      Sets the mouse pointer behavior for a given part. The default value is AUTOGRAB. Available modes are:

      -
        -
      • AUTOGRAB, when the part is clicked and the button remains pressed, the part is the source of all future mouse signals emitted, even outside the object, until the button is released.
      • -
      • NOGRAB, the effect is limited to the part's container.
      • -
      -
    • - -
    • precise_is_inside [1 or 0] -

      Enables precise point collision detection for the part, which is more resource-intensive. It is disabled by default.

      -
    • - -
    • use_alternate_font_metrics [1 or 0] -

      Only affects text and textblock parts, when enabled Edje uses different size measurement functions. It is disabled by default.

      -
    • - -
    • clip_to [another part's name] -

      Only renders the area of part that coincides with another part's container. Overflowing content is not displayed. Note that the part being clipped to can only be a rectangle part.

      -
    • - -
    • source [another group's name] -

      Only available to GROUP or TEXTBLOCK parts. Swallows the specified group into the part's container if it is a GROUP. If TEXTBLOCK it is used for the group to be loaded and used for selection display UNDER the selected text. source2 is used for on top of the selected text, if source2 is specified.

      -
    • - -
    • source2 [another group's name] -

      Only available to TEXTBLOCK parts. It is used for the group to be loaded and used for selection display OVER the selected text. source is used for under of the selected text, if source is specified.

      -
    • - -
    • source3 [another group's name] -

      Only available to TEXTBLOCK parts. It is used for the group to be loaded and used for cursor display UNDER the cursor position. source4 is used for over the cursor text, if source4 is specified.

      -
    • - -
    • source4 [another group's name] -

      Only available to TEXTBLOCK parts. It is used for the group to be loaded and used for cursor display OVER the cursor position. source3 is used for under the cursor text, if source4 is specified.

      -
    • - -
    • source5 [another group's name] -

      Only available to TEXTBLOCK parts. It is used for the group to be loaded and used for anchors display UNDER the anchor position. source6 is used for over the anchors text, if source6 is specified.

      -
    • - -
    • source6 [another group's name] -

      Only available to TEXTBLOCK parts. It is used for the group to be loaded and used for anchor display OVER the anchor position. source5 is used for under the anchor text, if source6 is specified.

      -
    • - -
    • effect [effect] (shadow direction) -

      Apply the selected outline, shadow, or glow effect to "textblock" (take care that this effect only works for the textblock). The available effects are:

      -
        -
      • PLAIN
      • -
      • OUTLINE
      • -
      • SOFT_OUTLINE
      • -
      • SHADOW
      • -
      • SOFT_SHADOW
      • -
      • OUTLINE_SHADOW
      • -
      • OUTLINE_SOFT_SHADOW
      • -
      • FAR_SHADOW
      • -
      • FAR_SOFT_SHADOW
      • -
      • GLOW
      • -
      - -

      The available shadow directions definitions are (default is BOTTOM_RIGHT):

      -
        -
      • BOTTOM_RIGHT
      • -
      • BOTTOM
      • -
      • BOTTOM_LEFT
      • -
      • LEFT
      • -
      • TOP_LEFT
      • -
      • TOP
      • -
      • TOP_RIGHT
      • -
      • RIGHT
      • -
      -
    • - -
    • entry_mode [mode] -

      Sets the edit mode for a textblock part. The available modes are:

      -
        -
      • NONE: -

        The textblock is non-editable.

      • -
      • PLAIN: -

        The textblock is non-editable, but selectable.

      • -
      • EDITABLE: -

        The textblock is editable.

      • -
      • PASSWORD: -

        The textblock is editable if the Edje object has the keyboard focus and the part has the Edje focus (or selectable always regardless of focus). In the event of password mode, not selectable and all text chars replaced with *'s but editable and pastable.

      • -
      -
    • - -
    • select_mode [mode] -

      Sets the selection mode for a textblock part. The available modes are:

      -
        -
      • DEFAULT, selection mode is what you would expect on any desktop. Press mouse, drag and release to end.
      • -
      • EXPLICIT, this mode requires the application controlling the Edje object has to explicitly begin and end selection modes, and the selection itself is draggable at both ends.
      • -
      -
    • - -
    • cursor_mode [mode] -

      Sets the cursor mode for a textblock part. The available modes are:

      -
        -
      • UNDER, the cursor draws below the character pointed at. That is the default.
      • -
      • BEFORE, the cursor is drawn as a vertical line before the current character, just like many other GUI toolkits handle it.
      • -
      -
    • - -
    • multiline [1 or 0] -

      It causes a textblock that is editable to allow multiple lines for editing.

      -
    • - -
    • access [1 or 0] -

      Specifies whether the part uses accessibility feature (1), or not (0). It is set to 0 by default.

      -
    • -
    - -

    Draggable

    - -
    -dragable 
    -{
    -   confine: "another part";
    -   threshold: "another part";
    -   events:  "another draggable part";
    -   x: 0 0 0;
    -   y: 0 0 0;
    -}
    -
    - -

    When this block is used the part can be dragged around the interface, do not confuse with external drag and drop. By default Edje (and most applications) attempts to use the minimal size possible for a draggable part. If the min property is not set in the description the part is (most likely) set to 0px width and 0px height, thus invisible.

    - -
      - -
    • x [enable/disable] [step] [count] -

      Used to set up dragging events for the X axis. The first parameter is used to enable (1 or -1) and disable (0) dragging along the axis. When enabled, 1 sets the starting point at 0.0 and -1 at 1.0. The second parameter takes any integer and limits movement to values divisible by it, causing the part to jump from position to position. If step is set to 0 it is calculated as width of confine part divided by count.

      -
    • - -
    • y [enable/disable] [step] [count] -

      Used to set up dragging events for the Y axis. The first parameter is used to enable (1 or -1) and disable (0) dragging along the axis. When enabled, 1 sets the starting point at 0.0 and -1 at 1.0. The second parameter takes any integer and limits movement to values divisible by it, causing the part to jump from position to position. If step is set to 0 it is calculated as height of confine part divided by count.

      -
    • - -
    • confine [another part's name] -

      Limits the movement of the dragged part to another part's container. Set a min size for the part, or the dragged object will not show up.

      -
    • - -
    • threshold [another part's name] -

      When set, the movement of the dragged part can only start when it get moved enough to be outside of the threshold part.

      -
    • - -
    • events [another draggable part's name] -

      Causes the part to forward the drag events to another part, thus ignoring them for itself.

      -
    • - -
    - -

    Box/table

    - -

    Items

    - -
    -box/table 
    -{
    -   items 
    -   {
    -      item 
    -      {
    -         type: GROUP;
    -         source: "some source";
    -         min: -1 -1;
    -         max: 100 100;
    -         padding: 1 1 2 2;
    -      }
    -      item 
    -      {
    -         type: GROUP;
    -         source: "some other source";
    -         name: "some name";
    -         align: 1.0 0.5;
    -      }
    -   }
    -}
    -
    - -

    On a BOX part, this block is used to set other groups as elements of the box. These can be mixed with external objects set by the application through the edje_object_part_box*() functions.

    - -
    Item
    - -
      - -
    • type [item type] -

      Sets the type of the object this item holds. The supported type is:

      -
        -
      • GROUP (default)
      • -
      -
    • - -
    • name [name for the object] -

      Sets the name of the object via evas_object_name_set().

      -
    • - -
    • source [another group's name] -

      Sets the group this object is made of.

      -
    • - -
    • min [width] [height] -

      Sets the minimum size hints for this object.

      - - - - - - - - - -
      Note
      Must be -1 to get expand behavior.
      -
    • - -
    • spread [width] [height] -

      Replicates the item in a rectangle of size width x height box starting from the defined position of this item. The default value is 1 1;.

      -
    • - -
    • prefer [width] [height] -

      Sets the preferred size hints for this object.

      -
    • - -
    • max [width] [height] -

      Sets the maximum size hints for this object.

      -
    • - -
    • padding [left] [right] [top] [bottom] -

      Sets the padding hints for this object.

      -
    • - -
    • align [x] [y] -

      Sets the alignment hints for this object.

      -
    • - -
    • weight [x] [y] -

      Sets the weight hints for this object.

      -
    • - -
    • aspect [w] [h] -

      Sets the aspect width and height hints for this object.

      -
    • - -
    • aspect_mode [mode] -

      Sets the aspect control hints for this object. The available hints are:

      -
        -
      • NONE
      • -
      • NEITHER
      • -
      • HORIZONTAL
      • -
      • VERTICAL
      • -
      • BOTH
      • -
      -
    • - -
    • options [extra options] -

      Sets extra options for the object.

      -
    • - -
    • position [col] [row] -

      Sets the position this item has in the table. This is required for parts of type TABLE.

      -
    • - -
    • span [col] [row] -

      Sets how many columns and rows this item uses. The default value is 1 1.

      -
    • - -
    - -

    Description

    - -
    -description 
    -{
    -   inherit: "another_description" INDEX;
    -   state: "description_name" INDEX;
    -   visible: 1;
    -   min: 0 0;
    -   max: -1 -1;
    -   align: 0.5 0.5;
    -   fixed: 0 0;
    -   step: 0 0;
    -   aspect: 1 1;
    -
    -   rel1 
    -   {
    -      ...
    -   }
    -
    -   rel2 
    -   {
    -      ...
    -   }
    -}
    -
    - -

    Every part can have one or more description blocks. Each description is used to define style and layout properties of a part in a given "state".

    - -
      - -
    • inherit [another description's name] [another description's index] -

      Thee description inherits all the properties from the named description. The properties defined in this part override the inherited properties, reducing the amount of necessary code for simple state changes. Note: inheritance in Edje is single level only.

      -
    • - -
    • source [another part's name] -

      Causes the part to use another part's content as the content of this part. This works only with PROXY part.

      -
    • - -
    • state [name for the description] [index] -

      Sets a name used to identify a description inside a given part. Multiple descriptions are used to declare different states of the same part, like "clicked" or "invisible". All state declarations are also coupled with an index number between 0.0 and 1.0. All parts must have at least one description named "default 0.0".

      -
    • - -
    • visible [0 or 1] -

      Takes a Boolean value specifying whether part is visible (1) or not (0). Non-visible parts do not emit signals. The default value is 1.

      -
    • - -
    • limit [mode] -

      Emits a signal when the part size changes from zero or to a zero (limit,width,over, limit,width,zero). By default no signal are emitted. Valid values are:

      -
        -
      • NONE
      • -
      • WIDTH
      • -
      • HEIGHT
      • -
      • BOTH
      • -
      -
    • - -
    • align [X axis] [Y axis] -

      When the displayed object's size is smaller or bigger than its container, this property moves it relatively along both axis inside its container. "0.0" means left/top edges of the object touching container's respective ones, and "1.0" stands for right/bottom edges of the object (on horizontal/vertical axis, respectively). The default value is "0.5 0.5". For a more detailed explanation, see the Align Size Hint.

      -
    • - -
    • fixed [width, 0 or 1] [height, 0 or 1] -

      Sets the minimum size calculation. See edje_object_size_min_calc() and edje_object_size_min_restricted_calc(). This tells the min size calculation routine that this part does not change size in width or height (1 for it does not, 0 for it does), so the routine does not try to expand or contract the part.

      -
    • - -
    • min [width] [height] or SOURCE -

      Sets the minimum size of the state. When min is defined to SOURCE, it looks at the original image size and enforces its minimal size to match at least the original one. The part must be an IMAGE or a GROUP part.

      -
    • - -
    • minmul [width multiplier] [height multiplier] -

      A multiplier forcibly applied to whatever minimum size is only during minimum size calculation.

      -
    • - -
    • max [width] [height] or SOURCE -

      The maximum size of the state. A size of -1.0 means that it is ignored in one direction. When max is set to SOURCE, Edje enforces the part to be not more than the original image size. The part must be an IMAGE part.

      -
    • - -
    • step [width] [height] -

      Restricts resizing of each dimension to values divisible by its value. This causes the part to jump from value to value while resizing. The default value is "0 0" which disables stepping.

      -
    • - -
    • aspect [min] [max] -

      Normally width and height can be resized to any values independently. The aspect property forces the width to height ratio to be kept between the minimum and maximum set. For example, "1.0 1.0" increases the width a pixel for every pixel added to height. The default value is "0.0 0.0" which disables aspect. For a more detailed explanation, see the Min Size Hint .

      -
    • - -
    • aspect_preference [DIMENSION] -

      Set the dimensions to which the "aspect" property applies. Available options are:

      -
        -
      • BOTH
      • -
      • VERTICAL
      • -
      • HORIZONTAL
      • -
      • SOURCE
      • -
      • NONE
      • -
      -

      For a more detailed explanation, see Min Size Hint.

      -
    • - -
    • color_class [color class name] -

      The part uses the color values of the named color_class, these values can be overridden by the "color", "color2" and "color3" properties.

      -
    • - -
    • color [red] [green] [blue] [alpha] -

      Sets the main color to the specified values (between 0 and 255).

      - - - - - - - - - -
      Note
      The textblock part is not affected by the color description. Set the color in the text style.
      - -
    • - -
    • color2 [red] [green] [blue] [alpha] -

      Sets the text shadow color to the specified values (0 to 255).

      -
    • - -
    • color3 [red] [green] [blue] [alpha] -

      Sets the text outline color to the specified values (0 to 255).

      -
    • - -
    - -

    Rel1/rel2

    -
    -description 
    -{
    -   rel1 
    -   {
    -      relative: 0.0 0.0;
    -      offset:     0   0;
    -   }
    -   rel2 
    -   {
    -      relative: 1.0 1.0;
    -      offset:    -1  -1;
    -   }
    -}
    -
    - -

    The rel1 and rel2 blocks are used to define the position of each corner of the part's container. With rel1 being the left-up corner and rel2 being the right-down corner.

    - -
      - -
    • relative [X axis] [Y axis] -

      Moves the corner to a relative position inside the container of the relative "to" part. Values from 0.0 (0%, beginning) to 1.0 (100%, end) of each axis.

      -
    • - -
    • offset [X axis] [Y axis] -

      Affects the corner position a fixed number of pixels along each axis.

      -
    • - -
    • to [another part's name] -

      Positions the corner relatively to another part's container. Setting to "" resets this value for inherited parts.

      -
    • - -
    • to_x [another part's name] -

      Positions the corner relatively to the X axis of another part's container. This affects the first parameter of "relative". Setting to "" resets this value for inherited parts.

      -
    • - -
    • to_y [another part's name] -

      Positions the corner relatively to the Y axis of another part's container. This affects the second parameter of "relative". Setting to "" resets this value for inherited parts.

      -
    • - -
    - -

    Image

    - -
    -description 
    -{
    -   image 
    -   {
    -      normal: "filename.ext";
    -      tween:  "filename2.ext";
    -      tween:  "filenameN.ext";
    -      border:  left right top bottom;
    -      middle:  0/1/NONE/DEFAULT/SOLID;
    -      fill {}
    -   }
    -}
    -
    - -
      - -
    • normal [image's filename] -

      Name of image to be used as previously declared in the images block. In an animation, this is the first and last image displayed. It is required in any image part

      -
    • - -
    • tween [image's filename] -

      Name of an image to be used in an animation loop, an image block can have none, one or multiple tween declarations. Images are displayed in the order they are listed, during the transition to the state they are declared in; the "normal" image is the final state.

      -
    • - -
    • border [left] [right] [top] [bottom] -

      Sets the area (in pixels) of each side of the image is displayed as a fixed size border, from the side -> inwards, preventing the corners from being changed on a resize.

      -
    • - -
    • middle [mode] -

      If border is set, this value tells Edje if the rest of the image (not covered by the defined border) displayed or not or be assumed to be solid (without alpha). The default value is 1/DEFAULT. The available values are:

      -
        -
      • 0 or NONE
      • -
      • 1 or DEFAULT
      • -
      • SOLID (strip alpha from the image over the middle zone)
      • -
      -
    • - -
    • border_scale_by [value] -

      If border scaling is enabled then normally the OUTPUT border sizes (e.g. if 3 pixels on the left edge are set as a border, then normally at scale 1.0, those 3 columns are always exactly 3 columns of output, or at scale 2.0 they are 6 columns, or 0.33 they merge into a single column). This property multiplies the input scale factor by this multiplier, allowing the creation of supersampled borders to make higher resolution outputs possible by always using the highest resolution artwork and then runtime scaling it down. Value can be: 0.0 or bigger (0.0 or 1.0 to turn it off)

      -
    • - -
    • border_scale [0/1] -

      Tells Edje if the border is scaled by the object/global Edje scale factors.

      -
    • - -
    • scale_hint [mode] -

      Sets the evas image scale hint letting the engine more effectively save cached copies of the scaled image if it makes sense. Valid values are:

      -
        -
      • 0 or NONE
      • -
      • DYNAMIC
      • -
      • STATIC
      • -
      -
    • - -
    - -
    Image.fill
    - -
    -image 
    -{
    -   fill 
    -   {
    -      type: SCALE;
    -      smooth: 0-1;
    -      origin {}
    -      size {}
    -   }
    -}
    -
    - -

    The fill method is an optional block that defines the way an IMAGE part is going to be displayed inside its container. It can be used for tiling (repeating the image) or displaying only part of an image. See evas_object_image_fill_set() documentation for more details.

    - -
      - -
    • smooth [0 or 1] -

      The smooth property takes a boolean value to decide if the image will be smoothed on scaling (1) or not (0). The default value is 1.

      -
    • - -
    • spread -
    • - -
    • type [fill type] -

      Sets the image fill type. The part parameter "min" must be set, it is size of tiled image. If parameter "max" set tiled area has the size accordingly "max" values. SCALE is default type. Valid values are:

      -
        -
      • SCALE, image is scaled accordingly the value of the parameters "relative" and "offset" from "origin" and "size" blocks.
      • -
      • TILE, image is tiled accordingly parameters value "relative" and "offset" from "origin" and "size" blocks.
      • -
      -
    • - -
    - -
    Image.fill.origin
    - -
    -image 
    -{
    -   fill 
    -   {
    -      origin 
    -      {
    -         relative: 0.0 0.0;
    -         offset: 0 0;
    -      }
    -   }
    -}
    -
    - -

    The origin block is used to place the starting point, inside the displayed element, that is used to render the tile. By default, the origin is set at the element's left-up corner.

    - -
      - -
    • relative [X axis] [Y axis] -

      Sets the starting point relatively to displayed element's content.

      -
    • -
    • offset [X axis] [Y axis] -

      Affects the starting point a fixed number of pixels along each axis.

      -
    • - -
    - -
    Image.fill.size
    - -
    -image 
    -{
    -   fill 
    -   {
    -      size 
    -      {
    -         relative: 1.0 1.0;
    -         offset: -1 -1;
    -      }
    -   }
    -}
    -
    - -

    The size block defines the tile size of the content that are displayed.

    - -
      - -
    • relative [width] [height] -

      Takes a pair of decimal values that represent the percentage of the original size of the element. For example, "0.5 0.5" represents half the size, while "2.0 2.0" represents the double. The default value is "1.0 1.0".

      -
    • -
    • offset [X axis] [Y axis] -

      Affects the size of the tile a fixed number of pixels along each axis.

      -
    • - -
    - -

    Text

    - -
    -text 
    -{
    -   text: "some string of text to display";
    -   font: "font_name";
    -   size: SIZE;
    -   text_class: "class_name";
    -   fit: horizontal vertical;
    -   min: horizontal vertical;
    -   max: horizontal vertical;
    -   align: X-axis Y-axis;
    -   source: "part_name";
    -   text_source: "text_part_name";
    -   style: "stylename";
    -}
    -
    - - -
      - -
    • text [a string of text, or nothing] -

      Sets the default content of a text part, normally the application is the one changing its value.

      -
    • - -
    • text_class [text class name] -

      Similar to color_class, this is the name used by the application to alter the font family and size at runtime.

      -
    • - -
    • font [font alias] -

      This sets the font family to one of the aliases set up in the "fonts" block. Can be overridden by the application.

      -
    • - -
    • style [the style name] -

      Causes the part to use the default style and tags defined in the "style" block with the specified name.

      -
    • - -
    • repch [the replacement character string] -

      If this is a textblock and is in PASSWORD mode this string is used to replace every character to hide the details of the entry. Normally * is used, but you can use anything you like.

      -
    • - -
    • size [font size in points (pt)] -

      Sets the default font size for the text part. Can be overridden by the application.

      -
    • - -
    • size_range [font min size in points (pt)] [font max size in points (pt)] -

      Sets the allowed font size for the text part. Setting min and max to 0 means that sizing is not restricted. This is also the default value.

      -
    • - -
    • fit [horizontal] [vertical] -

      When any of the parameters is set to 1 Edje resizes the text for it to fit in its container. Both are disabled by default.

      -
    • - -
    • min [horizontal] [vertical] -

      When any of the parameters is enabled (1) it forces the minimum size of the container to be equal to the minimum size of the text. The default value is "0 0".

      -
    • - -
    • max [horizontal] [vertical] -

      When any of the parameters is enabled (1) it forces the maximum size of the container to be equal to the maximum size of the text. The default value is "0 0".

      -
    • - -
    • align [horizontal] [vertical] -

      Changes the position of the point of balance inside the container. The default value is 0.5 0.5.

      -
    • - -
    • source [another TEXT part's name] -

      Causes the part to use the text properties (like font and size) of another part and update them as they change.

      -
    • - -
    • text_source [another TEXT part's name] -

      Causes the part to display the text content of another part and update them as they change.

      -
    • - -
    • ellipsis [point of balance] -

      Balances the text in a relative point from 0.0 to 1.0, this point is the last section of the string to be cut out in case of a resize that is smaller than the text itself. The default value is 0.0.

      -
    • - -
    - - -

    Box

    - -
    -box 
    -{
    -   layout: "vertical";
    -   padding: 0 2;
    -   align: 0.5 0.5;
    -   min: 0 0;
    -}
    -
    - -

    A box block can contain other objects and display them in different layouts, any of the predefined set, or a custom one, set by the application.

    - -
      - -
    • layout [primary layout] (fallback layout) -

      Sets the layout for the box:

      -
        -
      • horizontal (default)
      • -
      • vertical
      • -
      • horizontal_homogeneous
      • -
      • vertical_homogeneous
      • -
      • horizontal_max (homogeneous to the max sized child)
      • -
      • vertical_max
      • -
      • horizontal_flow
      • -
      • vertical_flow
      • -
      • stack
      • -
      • some_other_custom_layout_set_by_the_application -

        Set a custom layout as a fallback. For more information, see edje_box_layout_register(). If an unregistered layout is used, it defaults to horizontal.

      • - -
      -
    • - -
    • align [horizontal] [vertical] -

      Changes the position of the point of balance inside the container. The default value is 0.5 0.5.

      -
    • - -
    • padding [horizontal] [vertical] -

      Sets the space between cells in pixels. The default value is 0 0.

      -
    • - -
    • min [horizontal] [vertical] -

      When any of the parameters is enabled (1) it forces the minimum size of the box to be equal to the minimum size of the items. The default value is 0 0.

      -
    • - -
    - -

    Table

    - -
    -table 
    -{
    -   homogeneous: TABLE;
    -   padding: 0 2;
    -   align: 0.5 0.5;
    -   min: 0 0;
    -}
    -
    - -

    A table block can contain other objects packed in multiple columns and rows, and each item can span across more than one column and/or row.

    - -
      - -
    • homogeneous [homogeneous mode] -

      Sets the homogeneous mode for the table:

      -
        -
      • NONE: default
      • -
      • TABLE: available space is evenly divided between children (which overflows onto other children if too little space is available)
      • -
      • ITEM: size of each item is the largest minimal size of all the items
      • -
      -
    • - -
    • align [horizontal] [vertical] -

      Changes the position of the point of balance inside the container. The default value is 0.5 0.5.

      -
    • - -
    • padding [horizontal] [vertical] -

      Sets the space between cells in pixels. The default value is 0 0.

      -
    • - -
    • min [horizontal] [vertical] -

      When any of the parameters is enabled (1), it forces the minimum size of the table to be equal to the minimum size of the items. The default value is 0 0.

      -
    • - -
    - -

    Map

    - -
    -map 
    -{
    -   perspective: "name";
    -   light: "name";
    -   on: 1;
    -   smooth: 1;
    -   perspective_on: 1;
    -   backface_cull: 1;
    -   alpha: 1;
    -
    -   rotation 
    -   {
    -      ...
    -   }
    -}
    -
    - -
      - -
    • perspective [another part's name] -

      This sets the part that is used as the perspective point for giving a part a 3D look. The perspective point must have a perspective section that provides zplane and focal properties. The center of this part is used as the focal point, thus size, color and visibility are not relevant, just center point, zplane and focal are used. This also implicitly enables perspective transforms.

      -
    • - -
    • light [another part's name] -

      This sets the part that is used as the light for calculating the brightness (based on how directly the part's surface is facing the light source point). Like the perspective point part, the center point is used and zplane is used for the z position (0 being the zero-plane where all 2D objects normally live) and positive values being further away into the distance. The light part color is used as the light color (alpha not used for light color). The color2 color is used for the ambient lighting when calculating brightness (alpha also not used).

      -
    • - -
    • on [1 or 0] -

      This enables mapping for the part. Default is 0.

      -
    • - -
    • smooth [1 or 0] -

      This enables smooth map rendering. This may be linear interpolation, anisotropic filtering or anything the engine decides is smooth. This is a best-effort hint and may not produce precisely the same results in all engines and situations. The default value is 1.

      -
    • - -
    • alpha [1 or 0] -

      This enables alpha channel when map rendering. The default value is 1.

      -
    • - -
    • backface_cull [1 or 0] -

      This enables backface culling (when the rotated part that normally faces the camera is facing away after being rotated etc.). This means that the object are hidden when backface is culled.

      -
    • - -
    • perspective_on [1 or 0] -

      This enables perspective when rotating even without a perspective point object. This uses perspective set for the object itself or for the canvas as a whole as the global perspective with edje_perspective_set() and edje_perspective_global_set().

      -
    • - -
    • color [point] [red] [green] [blue] [alpha] -

      This sets the color of a vertex in the map. Colors are linearly interpolated between vertex points through the map. The default color of a vertex in a map is white solid (255, 255, 255, 255) which means it has no affect on modifying the part pixels. Currently only four points are supported: 0 - Left-Top point of a part. 1 - Right-Top point of a part. 2 - Left-Bottom point of a part. 3 - Right-Bottom point of a part.

      -
    • - -
    - -
    Map.rotation
    - -
    -rotation 
    -{
    -   center: "name";
    -   x: 45.0;
    -   y: 45.0;
    -   z: 45.0;
    -}
    -
    - -

    Rotates the part, optionally with the center on another part.

    - -
      - -
    • center [another part's name] -

      This sets the part that is used as the center of rotation when rotating the part with this description. The part's center point is used as the rotation center when applying rotation around the x, y and z axes. If no center is given, the parts original center itself is used for the rotation center.

      -
    • - -
    • x [X degrees] -

      This sets the rotation around the x axis of the part considering the center set. The value is given in degrees.

      -
    • - -
    • y [Y degrees] -

      This sets the rotation around the y axis of the part considering the center set. The value is given in degrees.

      -
    • - -
    • z [Z degrees] -

      This sets the rotation around the z axis of the part considering the center set. The value is given in degrees.

      -
    • - -
    - -
    Perspective
    - -
    -perspective 
    -{
    -   zplane: 0;
    -   focal: 1000;
    -}
    -
    - -

    Adds focal and plane perspective to the part. Active if perspective_on is true. Must be provided if the part is being used by other part as it is perspective target.

    - -
      - -
    • zplane [unscaled Z value] -

      This sets the z value that is not scaled. Normally this is 0 as that is the z distance.

      -
    • - -
    • focal [distance] -

      This sets the distance from the focal z plane (zplane) and the camera - i.e. equating to focal length of the camera

      -
    • - -
    - - - -
    -link 
    -{
    -   base: "edje,signal" "edje";
    -   transition: LINEAR 0.2;
    -   in: 0.5 0.1;
    -   after: "some_program";
    -}
    -
    - -

    The link block can be used to create transitions to the enclosing part description state. The result of the above block is identical to creating a program with

    - - -
    -action: STATE_SET "default"";
    -signal: "edje,signal";
    -source: "edje";
    -
    - -
      - -
    • base [signal] [source] -

      Defines the signal and source which triggers the transition to this state. The source parameter is optional here and is filled with the current group's default value if it is not provided.

      -
    • -
    - -

    Program

    - -
    -program
    -{
    -   // name of the program
    -   name: "programname";
    -   // signals which trigger the program
    -   signal: "signalname";
    -   // filter incoming signals depending on the sender name
    -   source: "partname";
    -   // filter incoming signals depending on the part's state
    -   filter: "partname" "statename";
    -   // delay the program by X seconds plus a random time between 0 and Y
    -   in: 0.3 0.0;
    -   // action to perform
    -   action: STATE_SET "statename" state_value;
    -   // if action is STATE_SET, define a transition from the current to the target state
    -   transition: LINEAR 0.5;
    -   // if action is SIGNAL_EMIT, the name of the part which will receive the signal
    -   target: "partname";
    -   // run another program after the current one is done
    -   after: "programname";
    -   after: "anotherprogram";
    -}
    -
    - -

    Program

    - -

    Programs define how your interface reacts to events. Programs can change the state of parts or trigger other events.

    - -
      - -
    • name [program name] -

      Symbolic name of program as a unique identifier.

      -
    • - -
    • signal [signal name] -

      Specifies signals that cause the program to run. The signal received must match the specified source to run. There may be several signals, but only one signal keyword per program can be used. Also, there are some predefined signals for touch event handling. The predefined signals are:

      -
        -
      • "hold,on": Holding on the mouse event matching the source that starts the program.
      • -
      • "hold,off": Holding off the mouse event matching the source that starts the program.
      • -
      • "focus,part,in": Focusing in the matching source that starts the program.
      • -
      • "focus,part,out": Focusing out of the matching source that starts the program.
      • -
      • "mouse,in": Moving the mouse into the matching source that starts the program.
      • -
      • "mouse,out": Moving the mouse out of the matching source that starts the program.
      • -
      • "mouse,move": Moving the mouse in the matching source that starts the program.
      • -
      • "mouse,down,*": Pressing the mouse button in the matching source that starts the program.
      • -
      • "mouse,up,*": Releasing the mouse button in the matching source that starts the program.
      • -
      • "mouse,clicked,*": Clicking any mouse button in the matching source that starts the program.
      • -
      • "mouse,wheel,0,*": Moving the mouse wheel in the matching source that starts the program. A positive number moves up and a negative number moves down.
      • -
      • "drag,start": Starting a drag of the mouse in the matching source that starts the program. This signal works only in the draggable part.
      • -
      • "drag,stop": Stopping a drag of the mouse in the matching source that starts the program. This signal works only in the draggable part.
      • -
      • "drag": Dragging the mouse in the matching source that starts the program. This signal works only in the draggable part.
      • -
      -
    • - -
    • source [source name] -

      Source of accepted signal. There may be several signals, but only one source keyword per program can be used. For example, source: "button-*"; (signals from any part or program named "button-*" are accepted).

      -
    • - -
    • filter [part] [state] -

      Filter signals to be only accepted if the part is in state named [state]. Only one filter per program can be used. If [state] is not given, the source of the event is used instead.

      -
    • - -
    • in [from] [range] -

      Wait [from] seconds before executing the program and add a random number of seconds (from 0 to [range]) to the total waiting time.

      -
    • - -
    • action [type] (param1) (param2) (param3) (param4) -

      Action to be performed by the program. Valid actions (only one can be specified) are:

      -
        -
      • STATE_SET: Set "target part" state as "target state"
      • -
      • ACTION_STOP: Stop the ongoing transition.
      • -
      • SIGNAL_EMIT: Emit a signal to the application level. The application can register a callback for handling actions based on the EDC state.
      • -
      • DRAG_VAL_SET: Set a value for the dragable part (x, y values).
      • -
      • DRAG_VAL_STEP: Set a step for the dragable part (x, y values).
      • -
      • DRAG_VAL_PAGE: Set a page for the dragable part (x, y values).
      • -
      • FOCUS_SET: Set the focus to the target group.
      • -
      • PLAY_SAMPLE "sample name" speed (channel): Play a music sample clip. - -

        PLAY_SAMPLE's (optional) channel can be one of:

        -
          -
        • EFFECT/FX
        • -
        • BACKGROUND/BG
        • -
        • MUSIC/MUS
        • -
        • FOREGROUND/FG
        • -
        • INTERFACE/UI
        • -
        • INPUT
        • -
        • ALERT
        • -
        -
      • - -
      • PLAY_TONE "tone name" duration_in_seconds (Range 0.1 to 10.0): Play a predefined tone of a specific duration.
      • -
      • PLAY_VIBRATION "sample name" repeat (repeat count)
      • -
    • - - -
    • transition [type] [length] (interp val 1) (interp val 2) (option) -

      Defines how transitions occur using STATE_SET action. [type] is the style of the transition and [length] is a double specifying the number of seconds in which to preform the transition. Valid types are:

      -
        -
      • LIN or LINEAR
      • -
      • SIN or SINUSOIDAL
      • -
      • ACCEL or ACCELERATE
      • -
      • DECEL or DECELERATE
      • -
      • ACCEL_FAC or ACCELERATE_FACTOR
      • -
      • DECEL_FAC or DECELERATE_FACTOR
      • -
      • SIN_FAC or SINUSOIDAL_FACTOR
      • -
      • DIVIS or DIVISOR_INTERP
      • -
      • BOUNCE
      • -
      • SPRING
      • -
      - -

      ACCEL_FAC, DECEL_FAC and SIN_FAC need the extra optional "interp val 1" to determine the "factor" of curviness. 1.0 is the same as their non-factor counterparts and 0.0 is equal to linear. Numbers higher than 1.0 make the curve angles steeper with a more pronounced curve point.

      - -

      DIVIS, BOUNCE and SPRING also require "interp val 2" in addition to "interp val 1".

      - -

      DIVIS uses [val 1] as the initial gradient start (0.0 is horizontal, 1.0 is diagonal (linear), 2.0 is twice the gradient of linear, etc.). [val 2] is interpreted as an integer factor defining how much the value swings outside the gradient before going back to the final resting spot at the end. 0.0 for [val 2] is equivalent to linear interpolation. Note that DIVIS can exceed 1.0.

      - -

      BOUNCE uses [val 2] as the number of bounces (so it is rounded down to the nearest integer value), with [val 1] determining how much the bounce decays; 0.0 gives linear decay per bounce and higher values give much more decay.

      - -

      SPRING is similar to bounce; [val 2] specifies the number of spring swings and [val 1] specifies the decay, but it can exceed 1.0 on the outer swings.

      - -

      Valid options are:

      -
        -
      • CURRENT causes the object to move from its current position. Can be used as the last parameter of any transition type.
      • -
      -
    • - -
    • target [target] -

      Program or part on which the specified action acts.

      -
    • - -
    • after [after] -

      Specifies a program that is run after the current program completes. The source and signal parameters of a program run as an after are ignored. Multiple after statements can be specified per program.

      -
    • - -
    - - - - -
    - -Go to top - - - - - - - \ No newline at end of file diff --git a/org.tizen.guides/html/native/ui/edje_n.htm b/org.tizen.guides/html/native/ui/edje_n.htm deleted file mode 100644 index 47cdaf7..0000000 --- a/org.tizen.guides/html/native/ui/edje_n.htm +++ /dev/null @@ -1,774 +0,0 @@ - - - - - - - - - - - - - Edje - - - - - -
    - -

    Edje

    - - - -

    This programming guide shows you how to write an EDC file that can be used to theme a Tizen application. It describes concepts about parts positioning and resizing. It also explains part animations that can be done through programs.

    - -

    Basic Concepts

    - -

    What is an EDC File?

    - -

    An EDC file stands for Edje data collection. It is a text file that contains special code format describing the position, size, and other parameters of graphical elements that compose the visual aspect of your application. In addition to graphical elements, it can also handle sounds.

    - -

    The syntax for the Edje data collection files follows a simple structure of "blocks { .. }" that can contain "properties: ..", more blocks, or both.

    - -

    An EDC file has the ".edc" extension.

    - -

    Compiling EDC File

    -

    EDC file needs to be compiled into a ".edj" file using Edje library tools. After compiling the ".edj" file can be used by a native Tizen application.

    - -

    Here is an example about compiling helloworld.edc to ".edj" file using edje_cc tool:

    - -
    -$ edje_cc helloworld.edc
    -
    - -

    This command creates a helloworld.edj file.

    - -

    An EDC file can use external files such as sounds, images, or fonts. The path to these resources are passed to the edje_cc tool so that they are included in the final ".edj" file.

    - -
    -$ edje_cc -sd $SOUNDS_DIR -fd $FONTS_DIR -id $IMAGES_DIR
    -
    - -

    SOUNDS_DIR, FONTS_DIR, and IMAGES_DIR are the paths for sounds, fonts, and images resources respectively.

    - -

    Tizen SDK calls edje_cc during the project building if it finds an EDC source file in the ./res/edje/ directory.

    - -
    -Building file: ../res/edje/helloworld.edc
    -Invoking: EDC Resource Compiler
    -edje_cc -sd ../edje/sounds -fd ../edje/fonts -id ../edje/images ../res/edje/helloworld.edc ../res/edje/helloworld.edj
    -
    - - -

    The Tizen SDK compilation log extract shows you that if your EDC file uses pictures, they must be copied to the ./edje/images directory. Fonts and sounds go to the ./edje/fonts and ./edje/sounds directory respectively. The SDK builds the helloworld.edj file in the ./res/edje/ folder.

    - -

    Writing Simple EDC File

    -

    The code example below shows you the structure of an EDC file. It is a collection of groups that contain parts and programs.

    - -
    -collections 
    -{
    -   group 
    -   {
    -      name: "my_group";
    -      parts {}
    -      programs {}
    -   }
    -}
    -
    - -

    Groups are identified with a name, parts correspond to the graphical elements. Each one of them can have several states that describe a specific position, size, and visual aspect. Programs contain the program code, such as interaction with the main application through signals. Also animations are defined here (changing a part state using an animated transition).

    - -

    The description field is where the state of a part is written.

    - -
    -part
    -{
    -   description 
    -   { 
    -      state: "default" 0.0;
    -   }
    -   description 
    -   { 
    -      state: "state1" 0.0;
    -   }
    -   description 
    -   { 
    -      state: "state2" 0.0;
    -   }
    -}
    -
    - -

    As an example, here is a simple EDC file that contains only one part and one program. The part is a rectangle with blue state and red state, the program changes the state from blue to red when user clicks on the rectangle.

    - -
    -collections 
    -{
    -   group 
    -   {
    -      name: "example";
    -      parts 
    -      {
    -         // create the part
    -         part 
    -         { 
    -            name: "rectangle";
    -            // set the type to RECT (rectangle)
    -            type: RECT;
    -            // default state (blue color)
    -            description 
    -            { 
    -               state: "default" 0.0;
    -               align: 0.0 0.0;
    -               // blue color
    -               color: 0 0 255 255;
    -            }
    -            // second state (red color)
    -            description 
    -            { 
    -               state: "red" 0.0;
    -               align: 0.0 0.0;
    -               // red color
    -               color: 255 0 0 255;
    -            }
    -         }
    -      }
    -      programs 
    -      {
    -         // create a program
    -         program 
    -         { 
    -            name: "change_color";
    -            // program is triggered on mouse click
    -            signal: "mouse,clicked,*";
    -            source: "*";
    -            // set the red state of the "rectangle" part
    -            action: STATE_SET "red" 0.0;
    -            target: "rectangle";
    -         }
    -      }
    -   }
    -}
    -
    - -

    A program is triggered when receiving a signal from a specific source (here all the sources are taken into account). When launched, it does the action (changing the state of a part) on the target (the rectangle).

    - -

    Animating Theme Using Programs

    - -

    The previous example showed how to change the state of a part. It is also possible to use the transition parameter to create an animation between the 2 states. You can specify a transition type (ACCELERATE, DECELERATE, SINUSOIDAL, LINEAR, ...) and length (in seconds) of the transition.

    - -

    The following code example animates the previous state change using a linear transition of 2 seconds.

    - -
    -programs 
    -{
    -   program 
    -   { 
    -      name: "change_color";
    -      signal: "mouse,clicked,*";
    -      source: "*";
    -      action: STATE_SET "red" 0.0;
    -      target: "rectangle";
    -      transition: LINEAR 2.0;
    -   }
    -}
    -
    - -

    Edje calculates all frames needed for the animation. The result is a smooth animation between the two states and it takes 2 seconds.

    - -

    Positioning Basic Parts

    - -

    Size of a part (in pixels) is set using the min and max parameters. The following code example sets the minimum and maximum size of the rectangle part to 200x200 px.

    - -
    -part 
    -{ 
    -   name: "rectangle";
    -   type: RECT;
    -   description 
    -   { 
    -      state: "blue" 0.0;
    -      align: 0.0 0.0;
    -      // set the size to 200x200
    -      min: 200 200;
    -      max: 200 200;
    -      // blue color
    -      color: 0 0 255 255;
    -   }
    -}
    -
    - -

    Position of the parts is defined in the rel1 and rel2 blocks. rel1 and rel2 blocks are used to define respectively the upper-left corner and the lower-right corner of the part. Position can be defined relatively to other parts (with the relative parameter) as an offset (offset parameter). When using relative positioning, the to, to_x and to_y parameters are used to define to which part the relative positioning is done. If nothing else is specified, the positioning is relative to the parent's part.

    - -

    To demonstrate the relative positioning, here is a code example that creates another part and positions it under the first part (the upper-left corner of the new part will start at the lower-left corner of the previous one).

    - -
    -part 
    -{ 
    -   name: "rectangle2";
    -   type: RECT;
    -   description 
    -   { 
    -      state: "green" 0.0;
    -      align: 0.0 0.0;
    -      // set the size to 200x200
    -      min: 200 200;
    -      max: 200 200;
    -      // green color
    -      color: 0 255 0 255;
    -      // set the position
    -      // rel1 is relative to "rectangle"
    -      rel1 
    -      {
    -         relative: 0.0 1.0;
    -         to: "rectangle";
    -      }
    -      // rel2 is relative to the parent
    -      rel2 
    -      {
    -         relative: 1.0 1.0;
    -      }
    -   }
    -}
    -
    - - - - - - - - - - -
    Note
    The align parameter defines how the parts align themselves in the main window if their size is smaller than the main window. If nothing is specified, the parts are aligned in the center of the window.
    - -

    Adding Offset to Relative Positioning

    - -

    The rel1 and rel2 structures also support offset which is a complement to the relative positioning: the corners are first placed according to their relative parameters and then adjusted using the offsets.

    - -

    The picture below shows the pixel positions for a 4x4 rectangle. The indices start in the top-left corner at (0, 0) increase to the right and to the bottom. Since the indices have started at 0, the 4th pixel has an index of 3.

    - -

    Therefore, in order to create a 2x2 blue rectangle centered inside that green square, the top-left corner has to be (1, 1) and the bottom-right one has to be (2, 2).

    - -

    Figure: Offset indices

    -

    Offset indices

    - -

    Edje needs the following things defined:

    -
      -
    • the part coordinates depending on the size and position of the green rectangle
    • -
    • the relative component of positions is the same: the top-left corner of the green rectangle
    • -
    • the top-left pixel is (1, 1) and the bottom-right one is (2, 2)
    • -
    - -

    The following code example defines these things:

    - -
    -name: "blue rectangle";
    -
    -rel1.to: "green rectangle";
    -rel1.relative: 0 0;
    -rel1.offset: 1 1;
    -
    -rel2.to: "green rectangle";
    -rel2.relative: 0 0;
    -rel2.offset: 2 2;
    -
    - -

    For most tasks, relative positioning is simpler than using offsets. Offsets are usually left for fine-tuning and creating borders.

    - -

    The example below is similar to the previous one but uses relative positioning instead of offsets to achieve an equivalent at 4x4 but could scale to larger sizes.

    - -

    The blue square starts at 25% of the green square (both vertically and horizontally) and ends at 75% of it (again, both vertically and horizontally).

    - -

    Just like in the previous example, the blue rectangle is named and Edje is told what the object of reference is:

    - -
    -name: "blue rectangle";
    -rel1.to: "green rectangle";
    -rel2.to: "green rectangle";
    -
    - -

    The image below shows how to refer pixels using relative positioning when the offsets are (0, 0).

    - -

    Figure: Relative positioning

    -

    Relative positioning

    - -

    Note the addressing of pixels: (0, 0) is addressed through relative: 0 0; offset 0 0; and each additional 0.25 in the relative field gives a 1-pixel move. With this, the pixel addressed through relative: 0.75 0.75; offset: 0 0; is at (3, 3) and not (2, 2)!.

    - -

    This comes from a design choice in Evas and Edje which favor simplicity. In the examples shown in this guide, there are 4 pixels and therefore when the [0; 1) range is divided in 4, the result is [0; 0.25), [0.25; 0.50), [0.50; 0.75), [0.75; 0.100). With Edje, the value used to refer to each segment is the left bound and therefore, 0.75 refers to [0.75; 0.100), i.e. the bottom-right pixel of the green rectangle and not the 3/4th one.

    - -

    The way to refer to the pixel right before is to set the rel2 bound to relative: 0.75 0.75;, as would be expressed naturally, and offset: -1 -1;. This can also be understood as extending the rectangle up to 75% of its parent with the upper bound excluded (as shown in the [0.50; 0.75)).

    - -

    Since -1 -1 is the most common offset wanted for rel2, it is the default value; i.e. the default behavior is practical.

    - -

    Calculating Edje Object Total Size

    - -

    When the EDC file is composed of a lot of parts, Edje calculates the size of the global Edje object, by taking all the parts and their parameters into account. Some parameters have an role in this calculation and affect the global size:

    - -
      -
    • min and max: these define the minimum and the maximum size of a part.
    • -
    • rel1 and rel2: these specify the relative position of a part.
    • -
    • align: this relates to the alignment of the part in the parent's object.
    • -
    • fixed: this defines if the part has a fixed size.
    • -
    - - - - - - - - - - -
    Note
    fixed parameter can only be used on TEXTBLOCK type parts. Setting this parameter to fixed: 1 1 will not take into account the part for the calculation of the global size.
    - -

    Using Edje Size Hints

    - -

    Any Evas_Object can have hints, so that the object knows how to properly position and resize. Edje uses these hints when swallowing an Evas_Object to position and resize it in the SWALLOW part of the EDC file.

    - -

    Size hints are not a size enforcement, they just tell the parent object the desired size for this object. Then, the parent tries to get as close as possible to the hint.

    - -

    Hints are set in an Evas_Object using the evas_object_size_hint_*() functions.

    - -

    Min Size Hint

    - -

    This sets the hints for the object's minimum size, given in pixels.

    - -

    Here the horizontal and vertical min size hints of an Evas_Object are set to 0 pixels.

    - -
    -Evas_Object *object;
    -evas_object_size_hint_min_set(object, 0, 0);
    -
    - -

    Max Size Hint

    - -

    This sets the hints for the object's maximum size, given in pixels.

    - -

    Here the horizontal and vertical max size hints of an Evas_Object are set to 200 pixels.

    -
    evas_object_size_hint_max_set(object, 200, 200);
    - -

    Request Size Hint

    - -

    This sets the hints for the object's optimum size.

    - -

    The following code example defines that the optimum size of a part is 200x200 pixels.

    - -
    -evas_object_size_hint_request_set(object, 200, 200);
    -
    - -

    Aspect Size Hint

    - -

    This sets the hints for the object's aspect ratio. Available aspect size hints are:

    - -
      -
    • EVAS_ASPECT_CONTROL_NONE
    • -
    • EVAS_ASPECT_CONTROL_HORIZONTAL
    • -
    • EVAS_ASPECT_CONTROL_VERTICAL
    • -
    • EVAS_ASPECT_CONTROL_BOTH
    • -
    - -

    The other parameters are aspect width and height ratio. These integers are used to calculate the proportions of the object. If aspect ratio terms are null, the object's container ignores the aspect and scale of the object and occupies the whole available area.

    - -

    Figure: Aspect control

    -

    Aspect control

    - -

    Aspect control

    - -

    Aspect control

    - -

    The following code example sets the aspect size hint to EVAS_ASPECT_CONTROL_BOTH with a width of 100 and a height of 200. So aspect ratio should be 1/2.

    - -
    -evas_object_size_hint_aspect_set(object, EVAS_ASPECT_CONTROL_BOTH, 100, 200);
    -
    - -

    Align Size Hint

    -

    This sets the hints for the object's alignment. This hint is used when the object size is smaller than its parent's. The special EVAS_HINT_FILL parameter uses maximum size hints with higher priority, if they are set. Also, any padding hints set on objects are added up to the alignment space on the final scene composition.

    - -

    Figure: Alignment

    -

    Alignment

    - -

    In the code below, the special EVAS_HINT_FILL parameter is used.

    - -
    -evas_object_size_hint_align_set(object, EVAS_HINT_FILL, EVAS_HINT_FILL);
    -
    - -

    Weight Size Hint

    - -

    This sets the hints for the object's weight. The weight tells to a container object how the given child is resized. Using EVAS_HINT_EXPAND parameter asks to expand the child object's dimensions to fit the container's own.

    - -

    When several child objects have different weights in a container object, the container distributes the space it has to layout them by those factors. Most weighted children get larger in this process than the least ones.

    - -

    Here the container is asked to expand the object in both directions.

    - -
    -evas_object_size_hint_weight_set(object, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
    -
    - -

    Padding Size Hint

    - -

    This sets the hints for the object's padding space. Padding is extra space an object takes on each of its delimiting rectangle sides. The padding space is rendered transparent. Four hints can be defined, for the left, right, top, and bottom padding.

    - -

    Figure: Padding

    -

    Padding

    - -

    Here the padding hints are set to 5 pixels on each side of the object.

    - -
    -evas_object_size_hint_padding_set(object, 5, 5, 5, 5);
    -
    - -

    Scaling Objects

    - -

    Part Scaling

    - -

    When scaling an Edje object, only the parts that are declared scalable in the EDC file follow the scale request. This is done using the "scale" parameter.

    - -

    As an example, the previous "rectangle2" part is set as scalable, so that it is scaled when the Edje object is scaled.

    - -
    -part 
    -{ 
    -   name: "rectangle2";
    -   type: RECT;
    -   scale: 1;
    -   description 
    -   { 
    -      state: "green" 0.0;
    -   }
    -}
    -
    - -

    Using Image Set

    - -

    When using images in the Edje EDC file, image file names must be listed in a images block, so that Edje can use them in the theme. In this block, the compression level and compression method of the image can also be defined.

    - -

    Here is an example of an images block that lists two image files.

    - -
    -images 
    -{
    -   image: "image1.jpg" COMP;
    -   image: "image2.png" LOSSY 99;
    -}
    -
    - -

    As the devicescan have different screen sizes and resolutions, it is possible to define that the used image set depends on the resolution.

    - -

    In the example below the image named "image3" selects different files depending on image size.

    - -
    -images 
    -{
    -   set 
    -   {
    -      name: "image3";
    -      image 
    -      {
    -         image: "image3_1.png" LOSSY 90;
    -         size: 0 0 50 50;
    -      }
    -      image 
    -      {
    -         image: "image3_2.png" LOSSY 90;
    -         size: 51 51 200 200;
    -      }
    -      image 
    -      {
    -         image: "image3_3.png" LOSSY 90;
    -         size: 201 201 500 500;
    -      }
    -   }
    -}
    -
    - -

    This is done with the "size" attribute that specifies the minimal width and height and maximal width and height. If the width and height of the object are below 50px, image3_1.png picture file is used. If they are bigger than 201px, image3_3.png file is used.

    - -

    Resizing Borders

    - -

    Sometimes it is needed to keep the borders of an image intact when resizing or scaling it. The border attribute is here to do that.

    - -
    -border [left] [right] [top] [bottom]
    -
    - -

    If set, the area (in pixels) of each side of the image is displayed as a fixed size border, from the side -> inwards. This prevents the corners from being changed on a resize.

    - -

    Here is a code example how to set a border of 10px on each side of the image. This 10px border will not be resized when scaling the image.

    - -
    -part 
    -{ 
    -   name: "image_border";
    -   type: IMAGE;
    -   scale: 1;
    -   description 
    -   {
    -      image 
    -      {
    -         normal: "image1.jpg";
    -         border: 10 10 10 10;
    -      }
    -   }
    -}
    -
    - -

    Edje Swallow

    - -

    The parent of all layout components is Edje. Edje as explained in the Edje Blocks is a library which convert edc files into Evas object. EDC is a description language. It means that the objects of interface are described by using text description. One of its main features is the possibility to create "Swallows" objects. When this kind of object is added in an Evas, it contains any other Evas_Object. To create a swallow part, create first the EDC file:

    - -
    -collections
    -{
    -   group 
    -   { 
    -      name: "container";
    -      parts 
    -      {
    -         part 
    -         {
    -            name: "part.swallow"
    -            type: SWALLOW;
    -            description 
    -            {
    -               state: "default" 0.0;
    -               rel1.offset: 31 31;
    -               rel2.offset: -32 -32;
    -            }
    -         }
    -      }
    -   }
    -}
    -
    - -

    This EDC describes a group named "container", with one part inside of type SWALLOW and with the name part.swallow. This part is centered inside the parent (it is the default behavior) but there are 32 pixels free all around this part. Use edje_cc to compile the EDC file into a binary EDJ file:

    - -
    -edje_cc -o container.edj container.edc
    -
    - -

    Create an Edje object and load this file:

    - -
    -edje = edje_object_add(evas_object_evas_get(parent));
    -edje_object_file_set(edje, "container.edj", "container");
    -
    - - - - - - - - - - -
    Note
    edje_object_add as opposed as all elementary object, does not take an Evas_Object as a parent. Give it the Evas on which the object is added. As the parent is already added on an Evas by elementary, retrieve a reference on it by using the evas_object_evas_get() function.
    - -

    edje_object_file_set is used to set the Edje file from which the object is loaded. The object itself is the name of the group as defined in the EDC file, in this case it is "container".

    - -

    Use the API edje_object_swallow to swallow any kind of Evas_Object inside.

    - -
    -ic = elm_icon_add(parent);
    -elm_image_file_set(ic, "c1.png", NULL);
    -edje_object_part_swallow(edje, "part.swallow", ic);
    -
    - - - - - - - - - - -
    Note
    The elm_image_file_set() function parameters are linked to Edje. The second argument in this example is a PNG file; however, it can also be an Edje file. In that case, the third argument must be the Edje group to load, exactly as previously shown with the edje_object_file_set() function.
    - -

    Create complex layout for your application with Edje. It is may not be the most easy way, but it is the most powerful. This Edje layout is used all around elementary and is the basis of the layout component.

    - -

    ELM Layout

    - -

    Layout is a container component. For the basic use of the elm_layout with a default style, see the Layout Guide (in mobile and wearable applications). Elm layout takes a standard Edje design file and wraps it in a UI component. Layouts are the basis of graphical UI components which are used in Elementary.

    - -

    Adding Layout

    - -

    Create a new elementary layout using elm_layout_add:

    - -
    -Evas_Object *layout;
    -layout = elm_layout_add(parent);
    -
    - -

    As for Edje swallows, load an Edje file. Create first an Edje file, that contains a black rectangle and an icon in the center.

    - -
    -images
    -{
    -   image: "c1.png" COMP;
    -}
    -
    -collections
    -{
    -   group 
    -   { 
    -      name: "my_layout";
    -      parts 
    -      {
    -         part 
    -         {
    -            name: "background";
    -            type: RECT; description 
    -            { 
    -               state: "default" 0.0; color: 0 0 0 255; 
    -            } 
    -         } 
    -         part 
    -         { 
    -            name: "background"; 
    -            type: IMAGE; 
    -            description 
    -            { 
    -               state: "default" 0.0; 
    -               rel1.offset: 31 31; 
    -               rel2.offset: -32 -32; 
    -               default.image: "c1.png"; 
    -            } 
    -         }
    -      } 
    -   } 
    -}
    -
    -

    Compile it with edje_cc -o edje_example.edj edje_example.edc.

    -

    This file can be loaded with elm_layout_file_set:

    - -
    -elm_layout_file_set(layout, "edje_example.edj", "my_layout");
    -
    - -

    The layout component may contain as many parts/children as described in its theme file (EDC). Some of these children can have special types:

    - -
      -
    • SWALLOW (content holder)
    • -
    • BOX
    • -
    • TABLE
    • -
    - -

    Only one object can be added to a SWALLOW. The elm_layout_content_set()/get/unset functions are used to manage objects in a SWALLOW part. After being set to this part, the object's size, position, visibility, clipping and other description properties are controlled by the description of the given part (inside the Edje theme file).

    - -

    The BOX layout can be used through the elm_layout_box_*() set of functions. It is very similar to the elm_box component but the BOX layout's behavior is completely controlled by the Edje theme. The TABLE layout is like the BOX layout, the difference is that it is used through the elm_layout_table_*() set of functions.

    - -

    Signals

    -

    Elm can send Edje signals to the EDC part by using the elm_layout_signal_emit. You can also use elm_layout_signal_callback_add to receive signals.

    - -

    Use the following code to listen to any signals sent by the layout:

    - -
    -elm_layout_signal_callback_add(layout, "*", "*", _signal_cb, NULL);
    -
    -static void _signal_cb(void *data, Evas_Object *obj, const char *emission, const char *source)
    -{
    -   printf("Info received from layout : %s %s\n", emission, source);
    -}
    -
    - -

    For more details on this, see the section on edje signals and layouts.

    - -

    EDC Reference

    - -

    The documentation includes an extensive language reference. You can also access the page on the part block directly.

    - -

    Quick How-tos

    - -

    Adding Element on Screen

    -

    Add a new part inside the parts block.

    - -

    Using Image

    -

    List the image in the images block, make sure the part has type "IMAGE" and set the normal property inside description.image of part.

    - -

    Using Same Color Definitions Across Multiple Elements

    -

    Define a color class and set the description.color_class property.

    - -

    Positioning or Resizing a Part (Relative and Absolute Positioning)

    -

    Fill in the rel1 and rel2 structures inside the description block.

    - -

    Hiding Part

    -

    Set the visible property to 0.

    - -

    Animating Part

    -

    Create several description blocks inside your part and give each of them a different value for state. Set one description for the initial state and one for the end state.

    - -

    Create a program with an action that is STATE_SET "end_state" 0.0; and with a target that is the name of the part. You can also set a non-default transition.

    - -

    When defining the second description, inherit from the first part in order to re-use the values which are already defined.

    - -

    The after property of the program block is used to trigger another program after the animation is done. It can be used to trigger another animation or to emit a signal to the C part of the program.

    - -

    Making Genlist Item Theme

    -

    Create a group with one part element for each part that can be filed from the C code and set the items properties inside the group element:

    - -
    -items: "texts" "text_part_1 text_part_2";
    -items: "icons" "image_part_1 image_part_2";
    -
    -

    On the C side, the text_get and content_get callback are called respectively with text_part_1 and text_part_2, and image_part_1 and image_part_2.

    - - - - -
    - -Go to top - - - - - - - \ No newline at end of file diff --git a/org.tizen.guides/html/native/ui/efl_extension_n.htm b/org.tizen.guides/html/native/ui/efl_extension_n.htm deleted file mode 100644 index a24fe93..0000000 --- a/org.tizen.guides/html/native/ui/efl_extension_n.htm +++ /dev/null @@ -1,150 +0,0 @@ - - - - - - - - - - - - - Efl Extension - - - - - -
    -

    Efl Extension

    - - -

    The Efl Extension is an extension package for EFL that provides functions to work with the hardware keys and rotary events.

    - -

    Working with Hardware Keys

    - - - - - - - - - - -
    Note
    Hardware key events are only supported in mobile devices.
    - -

    Normally, the key events are only delivered to the object in focus. However, with the EFL Extension functions, you can let visible objects without focus get events from the Menu and Back keys.

    - -

    Figure: Menu and Back keys

    -

    Menu and Back keys

    - -

    The EFL Extension maintains its own object stack for determining which object to deliver events to. Only visible objects are added to this stack. The stack is based on the Evas layer. It means that if 2 objects are registered for the same EFL Extension event, the object on the higher Evas layer gets the event.

    - -

    The following figure shows an example of objects and their layers. Objects 1, 2, and 3 are registered with EFL Extension callbacks for the same event, such as a Back key event. When the event occurs, object 3, which is on the highest layer (layer 3), gets the event callback.

    - -

    Figure: Objects with layers

    -

    Objects with layers

    - -

    If objects stay on the same layer, the object which is registered to the callback first gets the event.

    - -

    To register a callback for the Menu or Back key, use the eext_object_event_callback_add() function with the application callback type:

    -
      -
    • EEXT_CALLBACK_BACK: Hardware Back key event
    • -
    • EEXT_CALLBACK_MORE: Hardware Menu key event
    • -
    - -

    To delete a registered event in the EFL Extension, use the eext_object_event_callback_del() function.

    - -

    The EFL Extension also provides other convenient functions to work with the Menu and Back keys for popup, ctxpopup, naviframe, and entry components (in mobile and wearable applications).

    - -

    Working with Rotary Events

    - - - - - - - - - - -
    Note
    Rotary events are only supported in devices with a circular screen.
    - -

    You can use various functions to work with the rotary events. The functions manage the rotary events, which are fired from the rotary device and delivered to a suitable target. To receive rotary events, you must define an event callback or a handler function, and register it using the EFL Extension functions. There are 2 ways to receive the rotary events: the rotary event handler and the rotary object event callback.

    - -

    Rotary Event Handler

    - -

    The rotary event handler is suitable when you want to handle rotary events without taking care about an Evas Object or when the application is not implemented using an Evas Object. The handler works like the Ecore event in EFL:

    - -
    • The application registers a rotary event handler with the eext_rotary_event_handler_add() function.

      - -

      The rotary event handlers are treated "first come first served". It means that the first registered handler is called first when rotary events happens. If the handler returns EINA_TRUE, the next handler is called. Otherwise, EFL Extension stops delivering the rotary events.

      -
    • -
    • To remove a rotary event handler, use the eext_rotary_event_handler_del() function.

    - - - -

    Rotary Object Event Callback

    - -

    The rotary object event callback is suitable when you want EFL Extension to handle the event delivery between objects. It means that EFL Extension manages a callback and an object list and decides which object's callback must be called when rotary events happen:

    - -
    • The application registers a callback using the eext_rotary_object_event_callback_add() function.

      - -

      EFL Extension treats callbacks based on the callback priority. If the application registers callbacks for a same object, the callback with the lowest priority number is called first. If this callback returns EINA_TRUE, the higher priority number is called. The above function registers the rotary event callback with a default priority number (value is 0). To register the rotary event callback with another priority number, use the eext_rotary_object_event_callback_priority_add() function.

    • -
    • To remove a registered callback from an object, use the eext_rotary_object_event_callback_del() function:

    - -

    The rotary events are only delivered to 1 object named the activated object. If there is no activated object, the rotary event is not delivered to any object. If the activated object has registered callbacks and the callbacks return EINA_TRUE, the rotary events are delivered to the upper parents of the activated object until there is 1 callback that consumes the rotary event or it reaches the top parent object.

    -

    To set the object as the activated object, use the eext_rotary_object_event_activated_set() function.

    - -

    Providing the activated parameter with the EINA_TRUE value sets the object as the activated object. Providing the EINA_FALSE value deactivates the object. Since there is only 1 object which is the activated object, if an object is set as the activated object, the previously activated object is deactivated and becomes a normal object. An activated signal named rotary,activated is sent when an object is set as the activated object, and the rotary,deactivated signal is sent when an object is deactivated.

    - -

    You can register callbacks for activated or deactivated signals with the evas_object_smart_callback_add() function.

    - -

    For more information, see the Evas smart callback function (in mobile and wearable applications).

    - - - - -
    - -Go to top - - - - - - - \ No newline at end of file diff --git a/org.tizen.guides/html/native/ui/efl_n.htm b/org.tizen.guides/html/native/ui/efl_n.htm deleted file mode 100644 index 900677e..0000000 --- a/org.tizen.guides/html/native/ui/efl_n.htm +++ /dev/null @@ -1,160 +0,0 @@ - - - - - - - - - - - - - EFL - - - -
    -
    -

    Mobile native Wearable native

    -
    - - -
    - -
    - -

    EFL

    - -

    Tizen provides the functionality to create and manage your application user interface. The heart of the Tizen application UI is the native UI framework, which consists of the Enlightenment Foundation Libraries (EFL).

    - - -

    Figure: EFL

    -

    EFL

    - -

    UI design with EFL consists of the following main parts:

    - -
      -
    • EFL -

      EFL basics contain a set of layered libraries, and EFL functions as the window manager for your application:

      - -
      • EFL Extension -

        The EFL Extension is an extension package for EFL. It provides functions to work with the Menu and Back hardware keys on devices.

      • - -
    • -
    • Edje -

      The Edje library is part of EFL, and provides APIs for theming a Tizen application, by writing EDC file. EDC programming supports part positioning, resizing, and animations.

    • - -
    • Elementary -

      The Elementary library is part of EFL, and provides the basic toolkit for window and layout management, along with the UI and container components for the user interface (in mobile and wearable applications). You can manage the UI components and their focus on the screen, as well as create customizations.

    • - -
    - -

    Some general UI design features include:

    -
      -
    • Animations and effects -

      Tizen supports various methods to create animations and effects in your application.

    • - -
    • Event handling and main loop -

      The user interface relies on callbacks designed to react to EFL events generated by the system or the user. You can handle various events, from low-level Ecore system events to Evas smart object events that happen on object collections.

      -

      The Ecore library provides a main loop abstraction that gets you data when it is available and sends you events. You can manage the main loop and use threads with the Ecore main loop.

    • - -
    • Font settings -

      Tizen supports various methods to change the font of your application to another system default font or your own font.

    • - -
    • Scalability -

      Elementary provides a way to scale UI components (in mobile and wearable applications) in order to be comfortably used with a finger and to make the text more readable.

    - - -

    Making EFL Applications

    - - -

    The Enlightenment Foundation Libraries (EFL) provide all the libraries you need to create powerful applications. This section presents an overview of the libraries and when to use them in developing applications.

    - -

    Enlightenment is a window manager, which in the X Window System means that it handles the borders, iconification, expansion, and movement of windows on the screen. Enlightenment can also provide multiple virtual desktops. The initial version was developed in the 1990s by Rasterman (Carsten Haitzler). Enlightenment has since become much more than a simple window manager. To create this window manager, the Enlightenment team needed powerful libraries to base their work on, which is where the EFL come in. The EFL are the libraries on which the window manager was initially based on, but which have since then become more powerful, more memory efficient, and especially more useful for the embedded world and for touchscreen interfaces.

    - -

    The EFL are a set of layered libraries, as shown in the following diagram:

    - -

    Figure: EFL layers

    -

    EFL layers

    - -

    When you create a basic EFL application, you use the following main libraries as a basis:

    - -
      -
    • Elementary is the top-most library with which you create your EFL application. It provides all the functions you need to create a window, create simple and complex layouts, manage the life cycle of a view, and add UI components. The full list of UI components that can be used in Tizen can be found in Using UI Components (in mobile and wearable applications).
    • -
    • Edje is the library used by Elementary to provide a powerful theme. You can also use Edje to create your own objects and use them in your application. You may also want to extend the default theme. You will find more information about Edje and the EDC format in Edje and Customizing UI Components.
    • -
    • Ecore is the library which manages the main loop of your application. The main loop is one of the most important concepts you need to know about to develop an application. The main loop is where events are handled, and where you interact with the user through the callback mechanism. The main loop mechanisms are explained in the Main Loop guide.
    • -
    • Evas is the canvas engine. Evas is responsible for managing the drawing of your content. All graphical objects that you create are Evas objects. Evas handles the entire state of the window by filling the canvas with objects and manipulating their states. In contrast to other canvas libraries, such as Cairo, OpenGL, and XRender, Evas is not a drawing library but a scene graph library that retains the state of all objects. The Evas concept is explained in Rendering Concept and Method in Evas. Evas objects are created and then manipulated until they are no longer needed, at which point they are deleted. This allows the developer to work in the same terms that a designer thinks in: it is a direct mapping, as opposed to having to convert the concepts into drawing commands in the right order, calculate minimum drawing calls needed to get the job done, and so on.
    • -
    • Eina is the basis of all the EFL libraries. Eina is a toolbox that implements an API for data types in an efficient way. It contains all the functions needed to create lists and hashes, manage shared strings, open shared libraries, and manage errors and memory pools. Eina concepts are explained in Eina.
    • -
    - -

    The EFL include more than just the above libraries, but the above are the most important libraries to get started with. The other libraries, such as Eet, Embryo, and Emotion, will be explored later in the programming guides and the API Reference.

    - -

    When designing EFL applications, you can use the EFL Extension package to work with device hardware keys and the EFL UTIL package to provide additional notifications.

    - -

    Concept of Elementary

    - -

    Before writing an application, you should already have an answer to the following question: What is an application? An application is a process launched by the user. Every application has at least one window for presenting its content. Users can interact with the content through events. Different sources of events can modify the life cycle of the application. The application may receive data from a network connection, and it may also receive touch and key events. From the computer's point of view, an application is a collection of code that reacts to events and displays content on the screen. Elementary bridges this divide between the user and the code.

    - -

    Elementary provides a variety of pre-built UI components, such as layout objects and components, that allow you to build rich graphical user interfaces for your applications. Every Elementary application has at least one window for presenting its content. The window provides the area in which to display the content and where the Evas canvas is placed.

    - -

    There are three main groups of objects provided by Elementary:

    - -
      -
    • UI components: These are the components with which you build your application UI.
    • -
    • Containers: These are the containers that hold the components.
    • -
    • Infrastructure: These are the modules that deal with Elementary as a whole.
    • -
    - -

    The Hello World example shows you how to develop your first application with Elementary and the EFL.

    - -

    Basic Structure of an EFL Application in Tizen

    - -

    Most of the time, your application has to manage multiple views. The easiest way to handle them with the EFL is to create a naviframe object. This object is a container. At first, it is used to contain the pages your application is composed of. Every Tizen application can use this top-layer object to facilitate navigation. More details can be found in the Naviframe Tutorial.

    - -

    Another interesting object that has to be present in every application is the conformant object. Conformant is a container component that accounts for the space taken up by the indicator, virtual keyboard, and softkey windows. The conformant content will be resized and positioned based on the space available. When the virtual keyboard is displayed, the content does not change.

    - -

    Figure: Basic EFL application structure

    -

    Basic EFL application structure

    - -

    Basic Use of Appcore

    - -

    In Tizen, the life cycle of an application is handled by appcore. Appcore is a dedicated library developed for Tizen that provides a set of functions for handling the application life cycle. For example, appcore is responsible for sending the correct signals when the application is created, when the battery is low, when the application is sent to the background, and when the screen is rotated.

    - -

    You can see appcore in action in Handling the Application Fundamentals.

    - - - - - - -
    - -Go to top - - - - - - - \ No newline at end of file diff --git a/org.tizen.guides/html/native/ui/efl_util_n.htm b/org.tizen.guides/html/native/ui/efl_util_n.htm deleted file mode 100644 index 6192593..0000000 --- a/org.tizen.guides/html/native/ui/efl_util_n.htm +++ /dev/null @@ -1,184 +0,0 @@ - - - - - - - - - - - - - EFL UTIL - - - - - -
    - -

    EFL UTIL

    - -

    The EFL UTIL utility package that supports the following EFL functionalities:

    - - - -

    Notification Window

    - -

    The EFL UTIL API allows you to set and get the notification level of the notification window (which is of the EFL window type):

    - -
    • efl_util_set_notification_window_level()
    • -
    • efl_util_get_notification_window_level()
    - -

    To understand notification levels, you must first learn about the Tizen window layer hierarchy. Window layers are logical containers used to control the window stack order. Each window belongs to 1 layer and can change the stack order in the layer. Windows in same layer are always placed on or under a window in another layer. In addition to the default "normal layer", there exists a "notification layer", which is always placed above the normal layer.

    - - -

    Figure: Window layers

    -

    Window layers

    - - -

    Each window is set to a specific layer according to its type or properties. Most application windows belong to the normal layer. However, in case of an important alarm or other information crucial to the user, you can set the window to belong to the notification layer. This ensures that the user notices the information immediately, because the window belonging to the notification layer is always shown above the windows in the normal layer.

    - -

    Using the Notification Windows

    - -

    A window that belongs to the notification layer is called a "notification window". To make a notification window:

    - -
    1. Set the window type to NOTIFICATION, by calling the elm_win_add() function with the third parameter set to ELM_WIN_NOTIFICATION.
    2. -
    3. Set the notification level by calling the efl_util_set_notification_window_level() function. -

      The notification level defines the priority of the window, and the notification layer contains 3 levels (EFL_UTIL_NOTIFICATION_LEVEL_1, EFL_UTIL_NOTIFICATION_LEVEL_2, and EFL_UTIL_NOTIFICATION_LEVEL_3).

      -

      The default notification window level is EFL_UTIL_NOTIFICATION_LEVEL_1. Most of notification windows can be set to this level. The EFL_UTIL_NOTIFICATION_LEVEL_2 is a higher level than EFL_UTIL_NOTIFICATION_LEVEL_1, which means that the window set to EFL_UTIL_NOTIFICATION_LEVEL_2 is always on the EFL_UTIL_NOTIFICATION_LEVEL_1 level window. The EFL_UTIL_NOTIFICATION_LEVEL_3 is the highest level in notification windows. Very few applications can use this level.

      - -

      If there are notification windows that have the same level, the most recently created notification window is placed on top of the other window.

      - -
    - -

    Figure: Notification levels

    -

    Notification levels

    - - -

    The following code snippets shown how to make a notification window with a higher level.

    - -
    -#include <Elementary.h>
    -#include <efl_util.h>
    -#include <dlog.h>
    -
    -static Evas_Object *create_win(const char *name)
    -{
    -   Evas_Object *eo;
    -   efl_util_error_e error;
    -   // Create the NOTIFICATION window object
    -   eo = elm_win_add(NULL, name, ELM_WIN_NOTIFICATION);
    -
    -   if (!eo) return NULL;
    -
    -   // Set the NOTIFICATION level
    -   error = efl_util_set_notification_window_level(eo, EFL_UTIL_NOTIFICATION_LEVEL_1);
    -
    -   elm_win_title_set(eo, name);
    -   elm_win_autodel_set(eo, EINA_TRUE); 
    -   evas_object_smart_callback_add(eo, "delete,request", _quit_cb, NULL); 
    -	
    -   return eo;
    -}
    - -

    Use the efl_util_get_notification_window_level() function to get the currently set notification level of a window. If the window is not of the notification type, the function returns the -EFL_UTIL_ERROR_NOT_SUPPORTED_WINDOW_TYPE error.

    -
    -#include <Elementary.h>
    -#include <efl_util.h>
    -#include <dlog.h>
    -
    -void get_notification_level (Evas_Object *eo)
    -{
    -   efl_util_error_e error;
    -   efl_util_notification_level_e  notification_level;
    -
    -   if (!eo) return;
    -
    -   // Get the window notification level
    -   error = efl_util_get_notification_window_level (eo, &notification_level);
    -
    -   // Check the return value
    -   if (error== EFL_UTIL_ERROR_NONE)
    -   {
    -      switch (notification_level)
    -      {
    -         case EFL_UTIL_NOTIFICATION_LEVEL_1:
    -            // Do something for level 1
    -            break;
    -
    -         case EFL_UTIL_NOTIFICATION_LEVEL_2:
    -            // Do something for level 2
    -            break;
    -      }
    -   }
    -   else
    -   {
    -      // Error handling
    -   }
    -}
    - -

    Screenshot

    - -

    The EFL UTIL SCREENSHOT API (in mobile and wearable applications) allows you to get the screen image to the user.

    - -

    First you must make the efl_util_screenshot_h structure and initialize the structure members with the efl_util_screenshot_initialize() function. To take the actual screenshot, create screen capture data and return it to the tbm_surface handler with the efl_util_screenshot_take_tbm_surface() function.

    -

    When no longer needed, remember to free the efl_util_screenshot_h structure with the efl_util_screenshot_deinitialize() function.

    - - -

    Input Generator

    - -

    The EFL UTIL INPUT API (in mobile and wearable applications) allows you to generate input events (such as key and touch events).

    - -

    First you must make the efl_util_inputgen_h structure and initialize the structure members with the efl_util_input_initialize_generator() function. To generate actual key or touch events, use the efl_util_input_generate_key() or efl_util_input_generate_touch() function.

    -

    When no longer needed, remember to free the efl_util_inputgen_h structure with the efl_util_input_deinitialize_generator() function.

    - - - -
    - -Go to top - - - - - - - \ No newline at end of file diff --git a/org.tizen.guides/html/native/ui/eina_n.htm b/org.tizen.guides/html/native/ui/eina_n.htm deleted file mode 100644 index 4260be9..0000000 --- a/org.tizen.guides/html/native/ui/eina_n.htm +++ /dev/null @@ -1,66 +0,0 @@ - - - - - - - - - - - - - Eina - - - - - -
    - -

    Eina

    -

    Eina provides data types and useful tools.

    - -

    The Eina library implements an API for data types in an efficient way. It also provides some useful tools, such as opening shared libraries, error management, type conversion, time accounting, and memory pool.

    -

    The main features of Eina are:

    -
      -
    • Data Types

      The Eina library is a central part of the EFL. It implements an API for data types, and allows you to create and manipulate several data types.

    • -
    • Eina Tools

      Eina provides a number of tools, such as string manipulation, that make your life easier when coding applications.

    • -
    - - - -
    - -Go to top - - - - - - - \ No newline at end of file diff --git a/org.tizen.guides/html/native/ui/eina_tools_n.htm b/org.tizen.guides/html/native/ui/eina_tools_n.htm deleted file mode 100644 index 4a773eb..0000000 --- a/org.tizen.guides/html/native/ui/eina_tools_n.htm +++ /dev/null @@ -1,234 +0,0 @@ - - - - - - - - - - - - - Eina Tools - - - - - -
    - -

    Eina Tools

    -

    Eina provides a number of tools, such as string manipulation, that make your life easier when coding applications:

    - -
      -
    • Convert fast: conversion from, for example, strings to integers and double
    • -
    • Counter: measures the number of calls and their time
    • -
    • Error: error identifiers
    • -
    • File: file list and path split
    • -
    • Lazy allocator: lazy allocator
    • -
    • Log: full-featured logging system
    • -
    • Magic: provides runtime type checking
    • -
    • Memory Pool: abstraction for various memory allocators
    • -
    • Module lists: loads and shares modules using the Eina_Module standard
    • -
    • Rectangle: rectangle structure and standard manipulation methods
    • -
    • Safety Checks: extra checks that report unexpected conditions and can be disabled during compilation
    • -
    • String: set of functions that manage C strings
    • -
    - -

    String

    - -

    When creating applications, you always need to manipulate strings. Eina provides a very useful API for manipulating C strings:

    - -
    • - -

      The most common string manipulation is the "split". If you have a string, such as "Rasterman:Bluebugs:Tasn:Illogict:billiob:Puppet_Master", and you want to print it in an easily readable format, you can use the eina_str_split() function to split the string using a delimiter. The first parameter is the string to split, the second determines where to split the string, and the final parameter is the maximum number of strings to split the string into. If you set a number less than 1, it splits the string as many times as possible.

      -

      The function returns a newly-allocated NULL-terminated array of strings, or NULL, if it fails to allocate the array. Always remember to free the memory allocated by the eina_str_split() function.

      - -
      -char *nicks = "Rasterman:Bluebugs:Tasn:Illogict:billiob:Puppet_Master";
      -char **result_arr;
      -int i;
      -
      -// Splitting the string with ':' delimiter
      -result_arr = eina_str_split(names, ":", 0);
      -// Printing the result
      -for (i = 0; result_arr[i]; i++)
      -   printf("Nick : %s\n", result_arr[i]);
      -// Remember to free memory
      -free(arr[0]);
      -free(arr);
      -
    • - - -
    • To change the string to lowercase or uppercase, use the eina_str_tolower() and eina_str_toupper() functions. They change the case for all characters of the given string. These functions modify the original strings.

      - -
      -char *str;
      -// Initialize the string
      -str = malloc(sizeof(char) * 4);
      -strcpy(str, "bsd");
      -// Change the string to uppercase
      -eina_str_toupper((char **)&str);
      -printf("%s\n", str);
      -// Change the string to lowercase
      -eina_str_tolower(&str);
      -printf("%s\n", str);
      -// Free the allocated memory
      -free(str);
      -
    • -
    • If you need to "join" 2 strings of known length, use the eina_str_join() function. The fist parameter is the buffer to store the result, the second is the size of the buffer, the third is the separator between the 2 strings, and the 2 final parameters are the stings to be joined.

      - -
      -char *part1 = "Tizen powered by";
      -char *part2 = "Enlightenment Foundation Libraries";
      -char *res;
      -size_t size;
      -// Calculate the string size + 1 for the delimiter
      -size = strlen(part1) + strlen(part2) + 1
      -// Allocate memory for the result
      -res = malloc(sizeof(char) * size);
      -// Join the strings
      -eina_str_join(res, size, ' ', part1, part2);
      -printf("%s\n", res);
      -// Free the allocated memory
      -free(res):
      -
    • -
    • To check whether a string starts or ends with another string, use the eina_str_has_prefix() or eina_str_has_suffix() function. You can also check whether a string has a particular extension with the eina_str_has_extension() function.

      - -

      These functions return EINA_TRUE if the given string contains the specified prefix, suffix, or extension, and EINA_FALSE if it does not.

      - -
      -char *names = "Carsten;Cedric;Tom;Chidambar;Boris;Philippe"
      -if (eina_str_has_prefix(names, "Carsten"))
      -   printf("String starts with 'Carsten'")
      -if (eina_str_has_suffix(names, "Philippe"))
      -   printf("String ends with 'Philippe'")
      -if (eina_str_has_extension(names, "philippe"))
      -   printf("String has extension 'philippe'")
      -else
      -   printf("String does not have extension "philippe)
      -
    - -

    Memory Pool

    - -

    The Eina_Mempool tool provides memory pool functionality. With a memory pool, you can preallocate fixed-size memory spaces for easy memory management.

    - -

    The following mempools are available:

    -
      -
    • buddy
    • -
    • chained_pool
    • -
    • ememoa_fixed and ememoa_unknown
    • -
    • fixed_bitmap
    • -
    • pass_through
    • -
    • one_big
    • -
    - -

    Safety Checks

    - -

    Eina safety checks are a set of macros that can be used to check for parameters or values that must never occur. The concept is similar to the assert() function, but safety checks log the parameter or value and return instead of aborting your program.

    - -

    The following safety checks are available:

    -
      -
    • EINA_SAFETY_ON_NULL_RETURN(exp)
    • -
    • EINA_SAFETY_ON_NULL_RETURN_VAL(exp, val)
    • -
    • EINA_SAFETY_ON_NULL_GOTO(exp, label)
    • -
    • EINA_SAFETY_ON_TRUE_RETURN(exp)
    • -
    • EINA_SAFETY_ON_TRUE_RETURN_VAL(exp, val)
    • -
    • EINA_SAFETY_ON_TRUE_GOTO(exp, label)
    • -
    • EINA_SAFETY_ON_FALSE_RETURN(exp)
    • -
    • EINA_SAFETY_ON_FALSE_RETURN_VAL(exp, val)
    • -
    • EINA_SAFETY_ON_FALSE_GOTO(exp, label)
    • -
    • EINA_ARG_NONNULL(...)
    • -
    - -

    To return if a variable is NULL, use the EINA_SAFETY_ON_NULL_RETURN() function. This macro calls return if the given parameter is NULL.

    - -
    -Eina_Bool myfunction(char *param) 
    -{
    -   // If my param is NULL, EINA_SAFETY_ON_NULL_RETURN calls "return"
    -   EINA_SAFETY_ON_NULL_RETURN(param);
    -
    -   printf("My pram is : %s\n", param);
    -
    -   return EINA_TRUE;
    -} 
    -
    - -

    To return a specific value, use the EINA_SAFETY_ON_NULL_RETURN_VAL() function instead of the EINA_SAFETY_ON_NULL_RETURN() function. This macro returns the given value.

    - -
    -Eina_Bool void myfunction(char *param)
    -{
    -   // If the parameter is NULL, return EINA_FALSE;
    -   EINA_SAFETY_ON_NULL_RETURN_VAL(param, EINA_FALSE);
    -   printf("My pram is : %s\n", param);
    -
    -   return EINA_TRUE;
    -}
    -
    - -

    To call another function if a parameter is NULL, use the EINA_SAFETY_ON_NULL_GOTO() function. This macro works similarly to the EINA_SAFETY_ON_NULL_RETURN() function except that it calls goto with the given function instead of return.

    - -
    -static void isnullcb()
    -{
    -   printf("The parameter is NULL\n");
    -}
    -Eina_Bool void myfunction(char *param)
    -{
    -   // If the parameter is NULL we return EINA_FALSE;
    -   EINA_SAFETY_ON_NULL_GOTO(param, isnullcb);
    -   printf("My pram is : %s\n", param);
    -
    -   return EINA_TRUE;
    -}
    -
    - -

    Eina also provides macros that check whether a given value is TRUE or FALSE. For example, to call return if a given value is TRUE, use the EINA_SAFETY_ON_TRUE_RETURN() function. To call "goto" in a given function if a given value is TRUE, use the EINA_SAFETY_ON_NULL_GOTO() function.

    - - - - - -
    - -Go to top - - - - - - - \ No newline at end of file diff --git a/org.tizen.guides/html/native/ui/elementary_mn.htm b/org.tizen.guides/html/native/ui/elementary_mn.htm deleted file mode 100644 index ea168b8..0000000 --- a/org.tizen.guides/html/native/ui/elementary_mn.htm +++ /dev/null @@ -1,448 +0,0 @@ - - - - - - - - - - - - - Elementary - - - - - -
    - -

    Elementary

    - - - - - - - - - - -
    Note
    This feature is supported in mobile applications only.
    - - -

    Elementary UI components are built in a hierarchical fashion. The idea is to factorize as much code as possible between UI components that behave in a similar manner to facilitate the creation of new UI components. The Elementary UI components inherit a lot of their code from the container UI components and the layout component (a container component that takes a standard Edje design file and wraps it very thinly). You can use the container and layout functions on the Elementary UI components, as well as the Elementary object functions, such as elm_object_part_content_set(), elm_object_part_content_get(), and elm_object_part_content_unset().

    - -

    Getting Started with the Elementary Library

    - -

    To use the Elementary library:

    - -
    1. Initialize the Elementary library with the elm_init() function.
    2. -
    3. Start the Elementary main loop with the elm_run() function. -

      The function does not return, instead, it constantly loops and runs the event and the processing tasks.

    4. -
    5. Add Elementary UI components in the main loop. -

      Generally, an Elementary UI component can be added with the elm_<UI component name>_add() function, which returns an Evas object (Evas_Object*). The Evas object is passed to the functions that are used to configure the UI component.

    6. -
    7. Stop the main loop and return to the main() function with the elm_exit() function.
    8. -
    9. When your application terminates, shut down the Elementary library with the elm_shutdown() function. -

      The function frees the Elementary objects that were allocated in the main loop, so you do not need to separately deallocate them.

    - - -

    The following code snippet shows the main() function of a minimal Elementary application:

    - -
    -#include <Elementary.h>
    -int main(int argc, char **argv)
    -{
    -   elm_init(argc, argv);
    -   elm_run();
    -   elm_shutdown();
    -
    -   return 0;
    -}
    - - - - - - - - - - -
    Note
    An Elementary application must use the ELM_MAIN() macro, which calls the elm_init() function. The HelloWorld example shows a basic Elementary application that uses this macro.
    - -

    Elementary Objects

    - -

    All objects created using Elementary are of the Evas_Object* type. This means that both Evas and Elementary functions can be used on an Elementary object. However, use Elementary functions on Elementary objects only when you do not know which API to use.

    - -

    Since an Elementary object can take up a lot of memory, the Elm_Object_Item type has been created for situations where you need to use a lot of items, such as in a genlist or gengrid component, and to save memory. Using the Elm_Object_Item type, an Elementary UI component can, in theory, contain a lot of items while maintaining a small memory footprint. In practice, the Elm_Object_Item instance is bigger than expected, but can still help in saving memory.

    - -

    Elementary Callbacks

    - -

    Several callbacks can be registered to handle Elementary object events:

    - -
      -
    • Evas event callback -

      Use the evas_object_event_callback_add() function to add a callback for input events (key up, key down, mouse wheel) on an Evas object. In case of an Elementary object, the callback is registered on the underlying Evas object without considering the Elementary object infrastructure (no event propagation).

      -
    • - -
    • Evas smart callback -

      Use the evas_object_smart_callback_add() function to add a callback for a smart event emitted by an Elementary object. Smart callbacks can only be registered on smart objects, and the "smart event" to register must be implemented by the corresponding smart object. Otherwise, the callback does nothing. The callback does not apply to input events (keyboard or mouse).

      -
    • - -
    • Edje signal callback -

      Use the edje_object_signal_callback_add() function to add a callback for a signal coming from an Edje object (a theme object).

      -
    • - -
    • Elementary signal callback -

      Use the elm_object_signal_callback_add() function to add a callback for a signal coming from an Elementary UI component's theme. The callback does not apply to input events (keyboard or mouse).

      -
    • - -
    • Elementary event callback -

      Use the elm_object_event_callback_add() function to add a callback for an input event (keyboard or mouse) coming from an Elementary object. In contrast to the Evas event callback, the Elementary event callback takes the hierarchy of the object into account: the event can be propagated to the parents of the object, and the parents can process the event.

      -
    • -
    - -

    For more information about events related to Elementary objects, see Handling Events. For more information about Evas objects and smart objects, see Rendering Concept and Method in Evas.

    - -

    Managing Elementary Profiles

    - -

    An Elementary profile is a set of preconfigured options that affects the entire look and feel of an application. The options linked to a specific profile form an Elementary configuration, which can be used to store the desired set of options for use in multiple sessions. Once loaded, the Elementary profile configures all the options and sets the look and feel of your Elementary application.

    - -

    To manage Elementary profiles:

    -
      -
    • List the existing profiles: -
      -Eina_List *list = elm_config_profile_list_get();
      -
      -
    • -
    • Set a particular profile: -
      -elm_config_profile_set("myprofile");
      -
      -
    • -
    • Get the current profile: -
      -char *profile = elm_config_profile_get();
      -
      -
    • -
    • To save the current option values as an Elementary configuration for later use, use the elm_config_save() function: -
      -elm_config_save();
      -
      -
    • -
    • To reload the Elementary configuration saved for the current profile: -
      -elm_config_reload();
      -
      -
    • -
    - -

    Configuring Elementary Options

    - -

    You can set the following options in the Elementary configuration. In addition, you can customize themes and manage focus.

    -
      - -
    • To scale UI components: -

      You can configure UI component scaling in terms of both interactive and readable areas.

      -
        -
      • Set the global scaling factor (for example, setting it to 2.0 doubles the size of all scalable UI components): -
        -elm_config_scale_set(2.0);
        -
        -
      • - -
      • Set the finger size: -
        -elm_config_finger_size_set(1.5);
        -
        -
      • -
      -
    • - -
    • To manage caches: -
        -
      • Enable the globally configured cache flush, and set the flush interval (in this example, to 60 seconds): -
        -elm_config_cache_flush_enabled_set(EINA_TRUE);
        -elm_config_cache_flush_interval_set(60);
        -
        -
      • - -
      • Configure the font and image cache sizes (to 500 and 5 000 000 bytes, respectively): -
        -elm_config_cache_font_cache_size_set(500);
        -elm_config_cache_image_cache_size_set(5000000);
        -
        -
      • - -
      • Set the Edje collection and Edje file cache sizes: -
        -elm_config_cache_edje_file_cache_size_set(500);
        -elm_config_cache_edje_collection_cache_size_set(500);
        -
        -
      • -
      -
    • - - -
    • To configure the gesture layer: -

      You can set the duration of the long tap and double tap events on the gesture layer objects. The following example sets the duration to 500 ms.

      - -
      -elm_config_glayer_long_tap_start_timeout_set(0.5);
      -elm_config_glayer_double_tap_timeout_set(0.5);
      -
      -
    • -
    • To manage scrolling: -
        -
      • Make the scroller bounce when it reaches its viewport's edge during scrolling by using the elm_config_scroll_bounce_enabled_set() function: -
        -elm_config_scroll_bounce_enabled_set(EINA_TRUE);
        -
        -
      • - -
      • Control the inertia of the bounce animation by using the elm_config_scroll_bounce_friction_set() function: -
        -elm_config_scroll_bounce_friction_set(0.5);
        -
        -

        You can also set the friction for a page scroll, include animations, and zoom animations.

        -
      • - -
      • Set the scroller to be draggable by using the elm_config_scroll_thumbscroll_enabled_set() function. You can configure several drag options, such as friction, sensitivity, acceleration, and momentum. - -

        The following example sets the scroller to be draggable, defines that the number of pixels one must travel while dragging the scroller view to actually trigger scrolling is 20 pixels.

        -
        -elm_config_scroll_thumbscroll_enabled_set(EINA_TRUE);
        -elm_config_scroll_thumbscroll_threshold_set(20);
        -
        -
      • -
      -
    • - -
    • To configure long press events: -

      Get the current timeout before a long press event is retrieved, and modify it. The following example increases the timeout by 1 second.

      -
      -double lp_timeout = elm_config_longpress_timeout_get();
      -elm_config_longpress_timeout_set(lp_timeout + 1.0);
      -
      -
    • - -
    • To configure tooltips: -

      Set the duration after which a tooltip is shown. The following example sets the delay to 2 seconds.

      - -
      -elm_config_tooltip_delay_set(2.0);
      -
      -
    • - -
    • To configure the password show last feature: -

      The password show last feature enables the user to view the last input entered for a few seconds before it is masked.

      - -
        -
      • Enable the password show last feature: -
        -elm_config_password_show_last_set(EINA_TRUE);
        -
        -
      • -
      • Set the visibility timeout (how many seconds the input is visible): -
        -elm_config_password_show_last_timeout_set(5.0);
        -
        -
      • -
      -
    • -
    • To set the Elementary engine: -

      You can define the rendering engine that Elementary uses to draw the windows. The following rendering engines are supported:

      - -
        -
      • "software_x11"
      • -
      • "fb"
      • -
      • "directfb"
      • -
      • "software_16_x11"
      • -
      • "software_8_x11"
      • -
      • "xrender_x11"
      • -
      • "opengl_x11"
      • -
      • "software_gdi"
      • -
      • "software_16_wince_gdi"
      • -
      • "sdl"
      • -
      • "software_16_sdl"
      • -
      • "opengl_sdl"
      • -
      • "buffer"
      • -
      • "ews"
      • -
      • "opengl_cocoa"
      • -
      • "psl1ght"
      • -
      - -
      -elm_config_engine_set("opengl_x11");
      -
      -
    • - -
    • To activate the access mode: -

      Set the access mode as active, so that information about an Elementary object is read when the object receives an EVAS_CALLBACK_MOUSE_IN event:

      - -
      -elm_config_access_set(EINA_TRUE);
      -
      -
    • - -
    • To configure the selection mode: -

      Set the selection mode so that the selection is cleared when the entry component is unfocused:

      -
      -elm_config_selection_unfocused_clear_set(EINA_TRUE);
      -
      -
    • - -
    • To enable mirroring: -

      Elementary allows UI mirroring both on a single object and on the entire UI. If mirroring is enabled, an Elementary UI component displays as if there was a vertical mirror in the middle of it. Only the controls and the disposition of the UI component are mirrored. Text is not mirrored.

      - -
      -elm_config_mirrored_set(EINA_TRUE);
      -
      -
    • - -
    • To set the frame rate: -

      Define the frames per second (FPS) value for the ecore_animator_frametime and edje_frametime calculations. This example sets the FPS 60.

      - -
      -elm_config_fps_set(60.0);
      -
      -
    • -
    - -

    Customizing Themes

    - -

    Elementary uses Edje to theme its UI components. Edje provides a default theme for each UI component in an application. You can change the theme using the ELM_THEME environment variable. You can also modify the theme globally with the elementary_config utility.

    - -

    For custom styles, use extensions. Extensions allow you to write styles for specific UI components. Add a new extension to the list of Elementary themes with the elm_theme_extension_add() function, and apply the new style to the UI component with the elm_object_style_set() function. Once set, the extension replaces the default theme of the UI component.

    - - - - - - - - - - -
    Note
    When developing an extension, to respect the signals emitted and the elements that need to be in place, you must know how the UI component is themed. If something is missing from the extension, it can break the UI component's behavior.
    - -

    To modify Elementary themes, you can also use overlays. An overlay can replace the look of all UI components by overriding the default styles. As with extensions, you must write the correct overlay theme for a UI component. When looking for a theme to apply, Elementary first checks the list of overlays, then the set theme, and finally the list of extensions. To add or remove an overlay, use the elm_theme_overlay_add() and elm_theme_overlay_del() functions.

    - - - - - - - - - - -
    Note
    With overlays, you can replace the default view and affect every UI component. This is very similar to setting the theme for the whole application, and probably clashes with end user options. Using overlays also runs the risk of non-matching styles across the application. Unless you have a very good reason to use them, avoid overlays.
    - -

    Managing Focus

    - -

    When an Elementary object has the focus, input events are directly passed to that object in the application window. The focused object can also change its decoration to show the user where the focus is. In an Elementary application, only one object can have the focus at a time.

    - -

    To set the focus to a new Elementary object and take the focus away from the previous focused object, use the elm_object_focus_set() function. You can make an object unfocusable with the elm_object_focus_allow_set() function.

    - - - - - - - - - - -
    Note
    Only visible objects can have the focus.
    - -

    Elementary supports focus chains that allow you to cycle through all the focusable objects in a window. By default, the focus chain is defined by the order in which the UI components are added to the code. It is also possible to define custom focus chains, when needed.

    - -

    For more information on focus, see Managing UI Component Focus.

    - -

    To manage the focus:

    - -
      -
    • To define a custom focus chain, create an Eina_List, and add the Elementary objects to it in the desired focus order. Use the elm_object_focus_custom_chain_set() function to set the final list as the custom focus chain of the parent object (in the following example, container_object is the parent object). - -
      Eina_List *obj_list = NULL;
      -
      -list = eina_list_append(list, obj1); 
      -list = eina_list_append(list, obj4);
      -list = eina_list_append(list, obj2); 
      -list = eina_list_append(list, obj3);
      -
      -elm_object_focus_custom_chain_set(container_object, list);
      -
    • - -
    • To remove the custom focus chain and use the default focus chain instead, use the elm_object_focus_custom_chain_unset() function. -
    • - -
    • To programmatically cycle through the focus chain, use the elm_object_focus_next() function. -
    • - -
    • To show a highlight on the focused object: - -
      -elm_config_focus_highlight_enabled_set(EINA_TRUE);
      -
      -
    • - -
    • To activate an animation when the focus shifts from one object to another: - -
      -elm_config_focus_highlight_animate_set(EINA_TRUE);
      -
      -
    • -
    - - - - - -
    - -Go to top - - - - - - - \ No newline at end of file diff --git a/org.tizen.guides/html/native/ui/elementary_wn.htm b/org.tizen.guides/html/native/ui/elementary_wn.htm deleted file mode 100644 index 1673f5b..0000000 --- a/org.tizen.guides/html/native/ui/elementary_wn.htm +++ /dev/null @@ -1,447 +0,0 @@ - - - - - - - - - - - - - Elementary - - - - - -
    - -

    Elementary

    - - - - - - - - - - -
    Note
    This feature is supported in wearable applications only.
    - - -

    Elementary UI components are built in a hierarchical fashion. The idea is to factorize as much code as possible between UI components that behave in a similar manner to facilitate the creation of new UI components. The Elementary UI components inherit a lot of their code from the container UI components and the layout component (a container component that takes a standard Edje design file and wraps it very thinly). You can use the container and layout functions on the Elementary UI components, as well as the Elementary object functions, such as elm_object_part_content_set(), elm_object_part_content_get(), and elm_object_part_content_unset().

    - -

    Getting Started with the Elementary Library

    - -

    To use the Elementary library:

    - -
    1. Initialize the Elementary library with the elm_init() function.
    2. -
    3. Start the Elementary main loop with the elm_run() function. -

      The function does not return, instead, it constantly loops and runs the event and the processing tasks.

    4. -
    5. Add Elementary UI components in the main loop. -

      Generally, an Elementary UI component can be added with the elm_<UI component name>_add() function, which returns an Evas object (Evas_Object*). The Evas object is passed to the functions that are used to configure the UI component.

    6. -
    7. Stop the main loop and return to the main() function with the elm_exit() function.
    8. -
    9. When your application terminates, shut down the Elementary library with the elm_shutdown() function. -

      The function frees the Elementary objects that were allocated in the main loop, so you do not need to separately deallocate them.

    - - -

    The following code snippet shows the main() function of a minimal Elementary application:

    - -
    -#include <Elementary.h>
    -int main(int argc, char **argv)
    -{
    -   elm_init(argc, argv);
    -   elm_run();
    -   elm_shutdown();
    -
    -   return 0;
    -}
    - - - - - - - - - - -
    Note
    An Elementary application must use the ELM_MAIN() macro, which calls the elm_init() function. The HelloWorld example shows a basic Elementary application that uses this macro.
    - -

    Elementary Objects

    - -

    All objects created using Elementary are of the Evas_Object* type. This means that both Evas and Elementary functions can be used on an Elementary object. However, use Elementary functions on Elementary objects only when you do not know which API to use.

    - -

    Since an Elementary object can take up a lot of memory, the Elm_Object_Item type has been created for situations where you need to use a lot of items, such as in a genlist or gengrid component, and to save memory. Using the Elm_Object_Item type, an Elementary UI component can, in theory, contain a lot of items while maintaining a small memory footprint. In practice, the Elm_Object_Item instance is bigger than expected, but can still help in saving memory.

    - -

    Elementary Callbacks

    - -

    Several callbacks can be registered to handle Elementary object events:

    - -
      -
    • Evas event callback -

      Use the evas_object_event_callback_add() function to add a callback for input events (key up, key down, mouse wheel) on an Evas object. In case of an Elementary object, the callback is registered on the underlying Evas object without considering the Elementary object infrastructure (no event propagation).

      -
    • - -
    • Evas smart callback -

      Use the evas_object_smart_callback_add() function to add a callback for a smart event emitted by an Elementary object. Smart callbacks can only be registered on smart objects, and the "smart event" to register must be implemented by the corresponding smart object. Otherwise, the callback does nothing. The callback does not apply to input events (keyboard or mouse).

      -
    • - -
    • Edje signal callback -

      Use the edje_object_signal_callback_add() function to add a callback for a signal coming from an Edje object (a theme object).

      -
    • - -
    • Elementary signal callback -

      Use the elm_object_signal_callback_add() function to add a callback for a signal coming from an Elementary UI component's theme. The callback does not apply to input events (keyboard or mouse).

      -
    • - -
    • Elementary event callback -

      Use the elm_object_event_callback_add() function to add a callback for an input event (keyboard or mouse) coming from an Elementary object. In contrast to the Evas event callback, the Elementary event callback takes the hierarchy of the object into account: the event can be propagated to the parents of the object, and the parents can process the event.

      -
    • -
    - -

    For more information about events related to Elementary objects, see Handling Events. For more information about Evas objects and smart objects, see Rendering Concept and Method in Evas.

    - -

    Managing Elementary Profiles

    - -

    An Elementary profile is a set of preconfigured options that affects the entire look and feel of an application. The options linked to a specific profile form an Elementary configuration, which can be used to store the desired set of options for use in multiple sessions. Once loaded, the Elementary profile configures all the options and sets the look and feel of your Elementary application.

    - -

    To manage Elementary profiles:

    -
      -
    • List the existing profiles: -
      -Eina_List *list = elm_config_profile_list_get();
      -
      -
    • -
    • Set a particular profile: -
      -elm_config_profile_set("myprofile");
      -
      -
    • -
    • Get the current profile: -
      -char *profile = elm_config_profile_get();
      -
      -
    • -
    • To save the current option values as an Elementary configuration for later use, use the elm_config_save() function: -
      -elm_config_save();
      -
      -
    • -
    • To reload the Elementary configuration saved for the current profile: -
      -elm_config_reload();
      -
      -
    • -
    - -

    Configuring Elementary Options

    - -

    You can set the following options in the Elementary configuration. In addition, you can customize themes and manage focus.

    -
      - -
    • To scale UI components: -

      You can configure UI component scaling in terms of both interactive and readable areas.

      -
        -
      • Set the global scaling factor (for example, setting it to 2.0 doubles the size of all scalable UI components): -
        -elm_config_scale_set(2.0);
        -
        -
      • - -
      • Set the finger size: -
        -elm_config_finger_size_set(1.5);
        -
        -
      • -
      -
    • - -
    • To manage caches: -
        -
      • Enable the globally configured cache flush, and set the flush interval (in this example, to 60 seconds): -
        -elm_config_cache_flush_enabled_set(EINA_TRUE);
        -elm_config_cache_flush_interval_set(60);
        -
        -
      • - -
      • Configure the font and image cache sizes (to 500 and 5 000 000 bytes, respectively): -
        -elm_config_cache_font_cache_size_set(500);
        -elm_config_cache_image_cache_size_set(5000000);
        -
        -
      • - -
      • Set the Edje collection and Edje file cache sizes: -
        -elm_config_cache_edje_file_cache_size_set(500);
        -elm_config_cache_edje_collection_cache_size_set(500);
        -
        -
      • -
      -
    • - - -
    • To configure the gesture layer: -

      You can set the duration of the long tap and double tap events on the gesture layer objects. The following example sets the duration to 500 ms.

      - -
      -elm_config_glayer_long_tap_start_timeout_set(0.5);
      -elm_config_glayer_double_tap_timeout_set(0.5);
      -
      -
    • -
    • To manage scrolling: -
        -
      • Make the scroller bounce when it reaches its viewport's edge during scrolling by using the elm_config_scroll_bounce_enabled_set() function: -
        -elm_config_scroll_bounce_enabled_set(EINA_TRUE);
        -
        -
      • - -
      • Control the inertia of the bounce animation by using the elm_config_scroll_bounce_friction_set() function: -
        -elm_config_scroll_bounce_friction_set(0.5);
        -
        -

        You can also set the friction for a page scroll, include animations, and zoom animations.

        -
      • - -
      • Set the scroller to be draggable by using the elm_config_scroll_thumbscroll_enabled_set() function. You can configure several drag options, such as friction, sensitivity, acceleration, and momentum. - -

        The following example sets the scroller to be draggable, defines that the number of pixels one must travel while dragging the scroller view to actually trigger scrolling is 20 pixels.

        -
        -elm_config_scroll_thumbscroll_enabled_set(EINA_TRUE);
        -elm_config_scroll_thumbscroll_threshold_set(20);
        -
        -
      • -
      -
    • - -
    • To configure long press events: -

      Get the current timeout before a long press event is retrieved, and modify it. The following example increases the timeout by 1 second.

      -
      -double lp_timeout = elm_config_longpress_timeout_get();
      -elm_config_longpress_timeout_set(lp_timeout + 1.0);
      -
      -
    • - -
    • To configure tooltips: -

      Set the duration after which a tooltip is shown. The following example sets the delay to 2 seconds.

      - -
      -elm_config_tooltip_delay_set(2.0);
      -
      -
    • - -
    • To configure the password show last feature: -

      The password show last feature enables the user to view the last input entered for a few seconds before it is masked.

      - -
        -
      • Enable the password show last feature: -
        -elm_config_password_show_last_set(EINA_TRUE);
        -
        -
      • -
      • Set the visibility timeout (how many seconds the input is visible): -
        -elm_config_password_show_last_timeout_set(5.0);
        -
        -
      • -
      -
    • -
    • To set the Elementary engine: -

      You can define the rendering engine that Elementary uses to draw the windows. The following rendering engines are supported:

      - -
        -
      • "software_x11"
      • -
      • "fb"
      • -
      • "directfb"
      • -
      • "software_16_x11"
      • -
      • "software_8_x11"
      • -
      • "xrender_x11"
      • -
      • "opengl_x11"
      • -
      • "software_gdi"
      • -
      • "software_16_wince_gdi"
      • -
      • "sdl"
      • -
      • "software_16_sdl"
      • -
      • "opengl_sdl"
      • -
      • "buffer"
      • -
      • "ews"
      • -
      • "opengl_cocoa"
      • -
      • "psl1ght"
      • -
      - -
      -elm_config_engine_set("opengl_x11");
      -
      -
    • - -
    • To activate the access mode: -

      Set the access mode as active, so that information about an Elementary object is read when the object receives an EVAS_CALLBACK_MOUSE_IN event:

      - -
      -elm_config_access_set(EINA_TRUE);
      -
      -
    • - -
    • To configure the selection mode: -

      Set the selection mode so that the selection is cleared when the entry component is unfocused:

      -
      -elm_config_selection_unfocused_clear_set(EINA_TRUE);
      -
      -
    • - -
    • To enable mirroring: -

      Elementary allows UI mirroring both on a single object and on the entire UI. If mirroring is enabled, an Elementary UI component displays as if there was a vertical mirror in the middle of it. Only the controls and the disposition of the UI component are mirrored. Text is not mirrored.

      - -
      -elm_config_mirrored_set(EINA_TRUE);
      -
      -
    • - -
    • To set the frame rate: -

      Define the frames per second (FPS) value for the ecore_animator_frametime and edje_frametime calculations. This example sets the FPS 60.

      - -
      -elm_config_fps_set(60.0);
      -
      -
    • -
    - -

    Customizing Themes

    - -

    Elementary uses Edje to theme its UI components. Edje provides a default theme for each UI component in an application. You can change the theme using the ELM_THEME environment variable. You can also modify the theme globally with the elementary_config utility.

    - -

    For custom styles, use extensions. Extensions allow you to write styles for specific UI components. Add a new extension to the list of Elementary themes with the elm_theme_extension_add() function, and apply the new style to the UI component with the elm_object_style_set() function. Once set, the extension replaces the default theme of the UI component.

    - - - - - - - - - - -
    Note
    When developing an extension, to respect the signals emitted and the elements that need to be in place, you must know how the UI component is themed. If something is missing from the extension, it can break the UI component's behavior.
    - -

    To modify Elementary themes, you can also use overlays. An overlay can replace the look of all UI components by overriding the default styles. As with extensions, you must write the correct overlay theme for a UI component. When looking for a theme to apply, Elementary first checks the list of overlays, then the set theme, and finally the list of extensions. To add or remove an overlay, use the elm_theme_overlay_add() and elm_theme_overlay_del() functions.

    - - - - - - - - - - -
    Note
    With overlays, you can replace the default view and affect every UI component. This is very similar to setting the theme for the whole application, and probably clashes with end user options. Using overlays also runs the risk of non-matching styles across the application. Unless you have a very good reason to use them, avoid overlays.
    - -

    Managing Focus

    - -

    When an Elementary object has the focus, input events are directly passed to that object in the application window. The focused object can also change its decoration to show the user where the focus is. In an Elementary application, only one object can have the focus at a time.

    - -

    To set the focus to a new Elementary object and take the focus away from the previous focused object, use the elm_object_focus_set() function. You can make an object unfocusable with the elm_object_focus_allow_set() function.

    - - - - - - - - - - -
    Note
    Only visible objects can have the focus.
    - -

    Elementary supports focus chains that allow you to cycle through all the focusable objects in a window. By default, the focus chain is defined by the order in which the UI components are added to the code. It is also possible to define custom focus chains, when needed.

    - -

    For more information on focus, see Managing UI Component Focus.

    - -

    To manage the focus:

    - -
      -
    • To define a custom focus chain, create an Eina_List, and add the Elementary objects to it in the desired focus order. Use the elm_object_focus_custom_chain_set() function to set the final list as the custom focus chain of the parent object (in the following example, container_object is the parent object). - -
      Eina_List *obj_list = NULL;
      -
      -list = eina_list_append(list, obj1); 
      -list = eina_list_append(list, obj4);
      -list = eina_list_append(list, obj2); 
      -list = eina_list_append(list, obj3);
      -
      -elm_object_focus_custom_chain_set(container_object, list);
      -
    • - -
    • To remove the custom focus chain and use the default focus chain instead, use the elm_object_focus_custom_chain_unset() function. -
    • - -
    • To programmatically cycle through the focus chain, use the elm_object_focus_next() function. -
    • - -
    • To show a highlight on the focused object: - -
      -elm_config_focus_highlight_enabled_set(EINA_TRUE);
      -
      -
    • - -
    • To activate an animation when the focus shifts from one object to another: - -
      -elm_config_focus_highlight_animate_set(EINA_TRUE);
      -
      -
    • -
    - - - - -
    - -Go to top - - - - - - - \ No newline at end of file diff --git a/org.tizen.guides/html/native/ui/evas_n.htm b/org.tizen.guides/html/native/ui/evas_n.htm deleted file mode 100644 index 53506d1..0000000 --- a/org.tizen.guides/html/native/ui/evas_n.htm +++ /dev/null @@ -1,979 +0,0 @@ - - - - - - - - - - - - - Evas - - - - - -
    - -

    Evas

    - -

    Evas is a clean display canvas API for several target display systems that can draw anti-aliased text, smooth super and sub-sampled scaled images, alpha-blend objects and much more.

    -

    It abstracts any need to know much about what the characteristics of your display system are, what graphics calls are used to draw them, and how. It deals on an object level where all you do is create and manipulate objects in a canvas and set their properties.

    -

    Evas optimizes the rendering pipeline to minimize effort in redrawing changes made to the canvas and so takes this work out of the programmers hand, saving a lot of time and energy.

    -

    It is designed to work on embedded systems all the way to large and powerful multi-cpu workstations. It can be compiled to only have the features you need for your target platform if you so wish. It has several display back-ends, allowing it display on several display systems, making it portable for cross-device and cross-platform development.

    - -

    Evas is not a UI component set or a UI component toolkit, but it is their base. See Elementary for a toolkit based on Evas, Edje, Ecore and other Enlightenment technologies.

    -

    It is not dependent or aware of main loops, input or output systems. Input must be polled from various sources and fed to Evas. It does not create windows or report windows updates to your system, but draws the pixels and reports to the user the areas that are changed. These operations are ready to be used in Ecore, particularly in Ecore_Evas wrapper/helper set of functions.

    - -

    Rendering Concept and Method in Evas

    -

    Evas is a canvas display library. It is markedly different from most display and windowing systems as the canvas is structural and is also a state engine, whereas most display and windowing systems are immediate mode display targets. Evas handles the logic between a structural display via its state engine, and controls the target windowing system in order to produce rendered results of the current canvas' state on the display.

    -

    Immediate mode display systems retain very little or no state. A program executes a series of commands, as in the following pseudo code.

    -
    -draw line from position (0, 0) to position (100, 200);
    -
    -draw rectangle from position (10, 30) to position (50, 500);
    -
    -bitmap_handle = create_bitmap();
    -scale bitmap_handle to size 100 x 100;
    -draw image bitmap_handle at position (10, 30);
    -
    -

    The series of commands is executed by the windowing system and the results are typically displayed on the screen. Once the commands are executed, the display system does not know how to reproduce this image again, and has to be instructed by the application on how to redraw sections of the screen if needed. Each successive command is executed as instructed by the application and either emulated by software or sent to the graphics hardware on the device to be performed.

    -

    The advantage of such a system is that it is simple and gives a program tight control over how something looks and is drawn. Given the increasing complexity of displays and demands by users to have better looking interfaces, more work needs to be done at this level by the internals of UI component sets, custom display components and other programs. This means that more logic and display rendering code needs to be written again each time the application needs to figure out how to minimize redraws so that display is fast and interactive, and keep track of redraw logic.

    -

    For example, if in the scene below, the windowing system requires the application to redraw the area from 0, 0 to 50, 50 (also referred to as the "expose event"). Then the programmer calculates manually the updates and repaints it again.

    -
    -Redraw from position (0, 0) to position (50, 50):
    -
    -// What was in area (0, 0, 50, 50)?
    -
    -// 1. intersection part of line (0, 0) to (100, 200)?
    -   draw line from position (0, 0) to position (25, 50);
    -
    -// 2. intersection part of rectangle (10, 30) to (50, 500)?
    -   draw rectangle from position (10, 30) to position (50, 50)
    -
    -// 3. intersection part of image at (10, 30), size 100 x 100?
    -   bitmap_subimage = subregion from position (0, 0) to position (40, 20)
    -   draw image bitmap_subimage at position (10, 30);
    -
    - -

    If all elements in the above scene are opaque, the system is doing useless paints: part of the line is behind the rectangle, and part of the rectangle is behind the image. These useless paints tend to be very costly.

    -

    Evas is a structural system in which the programmer creates and manages display objects and their properties, and as a result of this higher level state management, the canvas is able to redraw the set of objects when needed to represent the current state of the canvas.

    -

    For example, see the following pseudo code.

    -
    -line_handle = create_line();
    -set line_handle from position (0, 0) to position (100, 200);
    -show line_handle;
    -
    -rectangle_handle = create_rectangle();
    -move rectangle_handle to position (10, 30);
    -resize rectangle_handle to size 40 x 470;
    -show rectangle_handle;
    -
    -bitmap_handle = create_bitmap();
    -scale bitmap_handle to size 100 x 100;
    -move bitmap_handle to position (10, 30);
    -show bitmap_handle;
    -
    -render scene;
    -
    - -

    This looks longer, but when the display needs to be refreshed or updated, the programmer only moves, resizes, shows, hides etc. the objects that need to change. The programmer thinks at the object logic level, and the canvas software does the rest of the work, figuring out what changed in the canvas since it was last drawn, how to most efficiently redraw the canvas and its contents to reflect the current state, and doing the actual drawing of the canvas.

    -

    This allows the programmer think in a more natural way when dealing with a display, and saves time and effort of working out how to load and display images, to render given the current display system etc. Since Evas is portable across different display systems, this gives the programmer the ability to port and display the code on different display systems with little work.

    -

    Evas is a display system somewhere between a UI component set and an immediate mode display system. It retains basic display logic, but does little high-level logic such as scrollbars, sliders, push buttons etc.

    - -

    For more information on the UI rendering modes (immediate and retained), see UI Rendering Mode.

    - -

    Evas Object

    -

    An Evas object is the most basic visual entity used in Evas. Everything, be it a single line or a complex list of UI components, is an Evas object.

    - -

    Primitive Renderable Objects

    -

    Primitive objects are the base upon which to build a complex interface: rectangles, lines, polygons, images, textblocks, and texts.

    -

    Rectangle

    -

    There is only one function to deal with rectangle objects. However, the rectangle is manipulated using the generic evas object functions.

    -

    The evas rectangle serves a number of key functions when working on Evas programs.

    -
      -
    • background
    • -
    • debugging
    • -
    • clipper
    • -
    - -
    Background
    -

    A common requirement of Evas programs is to have a solid color background, which can be accomplished with the following code.

    -
    Evas_Object *bg = evas_object_rectangle_add(evas_canvas);
    -
    -// Here we set the rectangles red, green, blue and opacity levels
    -evas_object_color_set(bg, 255, 255, 255, 255); // opaque white background
    -evas_object_resize(bg, WIDTH, HEIGHT); // covers full canvas
    -evas_object_show(bg);
    -
    - -
    Debugging
    -

    When debugging visual issues with evas programs, the rectangle is a useful tool. The rectangle's simplicity means that it is easier to pinpoint issues with it than with more complex objects. A common technique to use when writing an evas program and not getting the desired visual result is to replace an object for a solid color rectangle and seeing how it interacts with the other elements. This often allows us to notice clipping, parenting or positioning issues. Once the issues are identified and corrected, the rectangle can be replaced for the original object, and in all likelihood any remaining issues are specific to that object's type.

    - -
    Clipping
    -

    Clipping serves two main functions:

    -
      -
    • limiting visibility
    • -
    • applying a layer of color to an object
    • -
    - - -

    Text

    -

    An Evas text object shows a basic single-line single-style text.

    -
    Evas_Object *text = evas_object_text_add(evas_canvas);
    -evas_object_text_text_set(text, "some text");
    -evas_object_color_set(text, 127, 0, 0, 127);
    -evas_object_show(text);
    -
    - -

    To set the text, use evas_object_text_text_set(text, some_text). You can set the current text with evas_object_text_text_get(text).

    -

    To set the font, use evas_object_text_font_set(text, font, size):

    -
      -
    • text: The text object
    • -
    • font: The font name you want to use
    • -
    • size: The font size you want to use. To query the current font, use evas_object_text_font_set(text, font, size).
    • -
    -

    To set the text style, use evas_object_text_style_set(text, style). The following styles are supported:

    -
      -
    • EVAS_TEXT_STYLE_PLAIN: Plain, standard text
    • -
    • EVAS_TEXT_STYLE_SHADOW: Text with shadow underneath
    • -
    • EVAS_TEXT_STYLE_OUTLINE: Text with an outline
    • -
    • EVAS_TEXT_STYLE_SOFT_OUTLINE: Text with a soft outline
    • -
    • EVAS_TEXT_STYLE_GLOW: Text with a glow effect
    • -
    • EVAS_TEXT_STYLE_OUTLINE_SHADOW: Text with both outline and shadow effects
    • -
    • EVAS_TEXT_STYLE_FAR_SHADOW: Text with (far) shadow underneath
    • -
    • EVAS_TEXT_STYLE_OUTLINE_SOFT_SHADOW: Text with outline and soft shadow effects combined
    • -
    • EVAS_TEXT_STYLE_SOFT_SHADOW: Text with (soft) shadow underneath
    • -
    • EVAS_TEXT_STYLE_FAR_SOFT_SHADOW: Text with (far soft) shadow underneath
    • -
    • EVAS_TEXT_STYLE_SHADOW_DIRECTION_BOTTOM_RIGHT: Shadow growing to bottom right
    • -
    • EVAS_TEXT_STYLE_SHADOW_DIRECTION_BOTTOM: Shadow growing to the bottom
    • -
    • EVAS_TEXT_STYLE_SHADOW_DIRECTION_BOTTOM_LEFT: Shadow growing to bottom left
    • -
    • EVAS_TEXT_STYLE_SHADOW_DIRECTION_LEFT: Shadow growing to the left
    • -
    • EVAS_TEXT_STYLE_SHADOW_DIRECTION_TOP_LEFT: Shadow growing to top left
    • -
    • EVAS_TEXT_STYLE_SHADOW_DIRECTION_TOP: Shadow growing to the top
    • -
    • EVAS_TEXT_STYLE_SHADOW_DIRECTION_TOP_RIGHT: Shadow growing to top right
    • -
    • EVAS_TEXT_STYLE_SHADOW_DIRECTION_RIGHT: Shadow growing to the right. To query the current style, use evas_object_text_style_get(text).
    • -
    -

    If the text does not fit, make an ellipsis on it by using evas_object_text_ellipsis_set(text, ellipsis). The (float) value specifies, which part of the text is shown.

    -
      -
    • 0.0: The beginning is shown and the end trimmed.
    • -
    • 1.0: The beginning is trimmed and the end shown.
    • -
    • Any value in between means that both ends of the text have ellipsis and the set part is shown.
    • -
    • -1.0: Ellipsis is disabled. To query the current ellipsis value, use evas_object_text_ellipsis_get(text).
    • -
    -

    When the text style is set to glow, set the glow color using evas_object_text_glow_color_set(text, r, g, b, a), where r, g, b, and a are respectively the red, green, blue, and alpha values. The effect is placed at a short distance from the text but not touching it. For glows set right at the text, use evas_object_text_glow2_color_set(text, r, g, b, a). To query the current color, use evas_object_text_glow_color_get(text, r, g, b, a), respectively evas_object_text_glow2_color_get(text, r, g, b, a).

    -

    If your text style is set to display a shadow, use evas_object_text_shadow_color_set(text, r, g, b, a), where r, g, b, and a are respectively the red, green, blue, and alpha values. To query the current color, use evas_object_text_shadow_color_get(text, r, g, b, a)

    -

    If your text style is set to display an outline, use evas_object_text_outline_color_set(text, r, g, b, a), where r, g, b, and a are respectively the red, green, blue, and alpha values. To query the current color, use evas_object_text_outline_color_get(text, r, g, b, a)

    - - -

    Primitive Smart Objects

    -

    A smart object is a special Evas object that provides custom functions to handle automatically clipping, hiding, moving, resizing color setting and more on child elements, for the smart object's user. They could be, for example, a group of objects that move together, or implementations of whole complex UI components, providing some intelligence and extension to simple Evas objects.

    - -

    Primitive Container Objects

    -

    A container is a Smart object that holds children Evas objects in a specific fashion.

    -

    Table

    -

    A table is a smart object that packs children using a tabular layout.

    -
    table = evas_object_table_add(evas);
    -evas_object_table_homogeneous_set(table, EVAS_OBJECT_TABLE_HOMOGENEOUS_NONE);
    -evas_object_table_padding_set(table, 0, 0);
    -evas_object_resize(table, WIDTH, HEIGHT);
    -evas_object_show(table);
    -
    -rect = evas_object_rectangle_add(evas);
    -evas_object_color_set(rect, 255, 0, 0, 255);
    -evas_object_size_hint_min_set(rect, 100, 50);
    -evas_object_show(rect);
    -evas_object_table_pack(table, rect, 1, 1, 2, 1);
    -
    -rect = evas_object_rectangle_add(d.evas);
    -evas_object_color_set(rect, 0, 255, 0, 255);
    -evas_object_size_hint_min_set(rect, 50, 100);
    -evas_object_show(rect);
    -evas_object_table_pack(table, rect, 1, 2, 1, 2);
    -
    -rect = evas_object_rectangle_add(d.evas);
    -evas_object_color_set(rect, 0, 0, 255, 255);
    -evas_object_size_hint_min_set(rect, 50, 50);
    -evas_object_show(rect);
    -evas_object_table_pack(table, rect, 2, 2, 1, 1);
    -
    -rect = evas_object_rectangle_add(d.evas);
    -evas_object_color_set(rect, 255, 255, 0, 255);
    -evas_object_size_hint_min_set(rect, 50, 50);
    -evas_object_show(rect);
    -evas_object_table_pack(table, rect, 2, 3, 1, 1);
    -
    - -

    In this example, we add a non-homogeneous table to the canvas with its padding set to 0.

    -

    We then add four different colored rectangles with different properties.

    -
      -
    • the first one, at the first column and first line, spans two columns and one line
    • -
    • the second one, at the first column and second line, spans one columns and two lines
    • -
    • the third one, at the second column and second line, fits in one cell
    • -
    • the fourth one, at the second column and third line, also fits in one cell
    • -
    -

    To create a table, use evas_object_table_add(evas).

    -

    To set the table layout (the cells), use evas_object_table_homogeneous_set(table, homogeneous). The following values can be homogeneous:

    -
      -
    • EVAS_OBJECT_TABLE_HOMOGENEOUS_NONE: This default value has columns and rows calculated based on hints of individual cells. This is flexible, but much heavier on computations.
    • -
    • EVAS_OBJECT_TABLE_HOMOGENEOUS_TABLE: The table size is divided equally among children, filling the whole table area. If the children have a minimum size that is larger than this (including padding), then the table overflows and is aligned respecting the alignment hint, possibly overlapping sibling cells.
    • -
    • EVAS_OBJECT_TABLE_HOMOGENEOUS_ITEM: The greatest minimum cell size is used: if no element is set to expand, the contents of the table are the minimum size and the bounding box of all the children is aligned relatively to the table object using evas_object_table_align_get(). If the table area is too small to hold this minimum bounding box, then the objects keep their size and the bounding box overflows the box area, still respecting the alignment. To set the current mode, use evas_object_table_homogeneous_get(table).
    • -
    -

    The table's content alignment is set using evas_object_table_align_set(table, horizontal, vertical), where horizontal and vertical are floating values. To see them, use evas_object_table_align_get(table, horizontal, vertical).

    -

    To set the padding, use evas_object_table_padding_set(table, horizontal, vertical). To see the current value, use evas_object_table_padding_get(table, horizontal, vertical).

    -

    _To see the current column and row count, use evas_object_table_col_row_size_get(table, columns, rows).

    - -

    Grid

    -

    A grid is a smart object that packs its children as with a regular grid layout.

    -

    Grids are added to the canvas with evas_object_grid_add(evas).

    -

    To change a grid's virtual resolution, use evas_object_grid_size_set(grid, width, height), to see it, use evas_object_grid_size_get(grid, width, height).

    -

    To add an object, use evas_object_grid_pack(grid, child, x, y, w, h), where

    -
      -
    • x is the virtual X coordinate of the child
    • -
    • y is the virtual y coordinate of the child
    • -
    • w is the virtual width of the child
    • -
    • h is the virtual height of the child
    • -
    -

    Box

    -

    A box is a simple container that sets its children objects linearly.

    -

    To add a box to your canvas, use evas_object_box_add(evas).

    -

    To add a child to the box, use

    -
      -
    • evas_object_box_append(box, child): The child is appended.
    • -
    • evas_object_box_insert_after(box, child, reference): The child is added after reference.
    • -
    • evas_object_box_insert_before(box, child, reference): The child is added before reference.
    • -
    • evas_object_box_insert_at(box, child, pos): The child is added at the specified position.
    • -
    -

    To set the alignment, use evas_object_box_align_set(box, horizontal, vertical).

    -
      -
    • horizontal: 0.0 means aligned to the left, 1.0 means to the right;
    • -
    • vertical: 0.0 means aligned to the top, 1.0 means to the bottom.
    • -
    -

    Evas has predefined box layouts available:

    -
      -
    • evas_object_box_layout_horizontal();
    • -
    • evas_object_box_layout_vertical();
    • -
    • evas_object_box_layout_homogeneous_horizontal();
    • -
    • evas_object_box_layout_homogeneous_vertical();
    • -
    • evas_object_box_layout_homogeneous_max_size_horizontal();
    • -
    • evas_object_box_layout_homogeneous_max_size_vertical();
    • -
    • evas_object_box_layout_flow_horizontal();
    • -
    • evas_object_box_layout_flow_vertical();
    • -
    • evas_object_box_layout_stack().
    • -
    - -

    Image Objects

    - - -

    Using Evas, you can create and manipulate image objects. Evas supports image loaders of various formats as plug-in modules.

    -

    The image formats that Evas supports include bmp, edj, gif, ico, jpeg, pmaps, png, psd, svg, tga, tiff, wbmp, webp, and xpm.

    - -

    Figure: Evas image loader

    -

    Evas image loader

    - -

    Evas Object Image Functions

    - -

    Evas has over 70 image object functions. The following functions are discussed in this document:

    -
    -Evas_Object *evas_object_image_add(Evas *e);
    -void evas_object_image_file_set(Evas_Object *obj, const char *file, const char *key);
    -void evas_object_image_fill_set(Evas_Object *obj, int x, int y, int w, int h);
    -void evas_object_image_filled_set(Evas *e, Eina_Bool setting);
    -Evas_Object *evas_object_image_filled_add(Evas *e);
    -void evas_object_image_smooth_scale_set(Evas_Object *obj, Eina_Bool smoothscale);
    -void evas_object_image_load_size_set(Evas_Object *obj, int w, int h);
    -void evas_object_image_data_set(Evas_Object *obj, void *data);
    -void *evas_object_image_data_get(const Evas_Object *obj, Eina_Bool for_writing);
    -void evas_object_image_size_set(Evas_Object *obj, int w, int h);
    -void evas_object_image_data_update_add(Evas_Object *obj, int x, int y, int w, int h);
    -Eina_Bool evas_object_image_save(const Evas_Object *obj, const char *file, const char *key, const char *flags);
    -
    - -

    Creating an Image Object and Setting the Image Data Source

    -

    A common use case of an image object is to set a file as the image data source. The process has 3 steps and each one involves the following API calls:

    -
      -
    • The evas_object_image_add() function creates an image object and returns the pointer. -
      Evas_Object *evas_object_image_add(Evas *e);
      -
    • -
    • The evas_object_image_file_set() function sets a source file on the image object. The object fetches the image pixel data from the source file. -
      void evas_object_image_file_set(Evas_Object *obj, const char *file, const char *key);
      -
    • -
    • The evas_object_image_fill_set() sets how to fill the image object's area with the given pixel data. -
      void evas_object_image_fill_set(Evas_Object *obj, int x, int y, int w, int h);
      -
    • -
    - -

    In the following code example, the main() function creates an image object and displays it on a window. The image object size is 300x300 and the source image resolution is 100x127. The image is scaled into 300 by 300 to fill the image object area using the evas_object_image_fill_set() function.

    -
    -#include <Elementary.h>
    -
    -int main(int argc, char **argv)
    -{
    -   elm_init(argc, argv);
    -
    -   // Create a window object
    -   Evas_Object *win = elm_win_add(NULL, "main", ELM_WIN_BASIC);
    -   evas_object_resize(win, 400, 400);
    -   evas_object_show(win);
    -
    -   // Return Evas handle from window
    -   Evas *e = evas_object_evas_get(win);
    -
    -   // Create an image object
    -   Evas_Object *img = evas_object_image_add(e);
    -
    -   // Set a source file to fetch pixel data
    -   evas_object_image_file_set(img, "./logo.png", NULL);
    -
    -   // Set the size and position of the image on the image object area
    -   evas_object_image_fill_set(img, 0, 0, 300, 300);
    -
    -   evas_object_move(img, 50, 50);
    -   evas_object_resize(img, 300, 300);
    -   evas_object_show(img);
    -
    -   elm_run();
    -
    -   elm_shutdown();
    -
    -   return 0;
    -}
    -
    -

    Figure: Image object display

    -

    Image object display

    - -

    Image Scaling

    -

    Users can decide how to fill the image object area with the given image pixel data by setting the position, width, and height of the image using the evas_object_image_fill_set() function. Without setting this information, the image is not displayed. If the size of the image is bigger than the image object area, only a sub-region of the original image is displayed. If the image is smaller than the area, images are tiled repeatedly to fill the object area.

    - -

    Figure: Image scaling

    -

    Image scaling

    - - - - - - - - - - - - - - -

    evas_object_image_fill_set(obj, 50, 0, 300, 300)evas_object_image_fill_set(obj, 0, 0, 200, 200)evas_object_image_fill_set(obj, 0, 0, 100, 127)
    - -

    the evas_object_image_filled_set() function scales the image to fit the object area. Resizing the image object automatically triggers an internal call to the evas_object_image_fill_set() function.

    -
    -void evas_object_image_filled_set(Evas *e, Eina_Bool setting);
    - -

    The evas_object_image_filled_add() function creates a new image object that automatically scales its bound image to the object area. This is a helper function around the evas_object_image_add() and evas_object_image_filled_set() functions.

    - -
    Evas_Object *evas_object_image_filled_add(Evas *e);
    - -

    Scaled images' quality can differ according to scaling algorithms. Smooth scaling improves the image quality in the process of size reducing or enlarging. Evas runs its own smooth scaling algorithm by default and provides an API so users can disable the function.

    - -
    -void evas_object_image_smooth_scale_set(Evas_Object *obj, Eina_Bool smoothscale);
    - -

    The algorithm is implemented using the SIMD (Single Instruction Multiple Data) vectorization in case of software rendering. It is optimized on Intel and ARM CPU through MMX and NEON command respectively.

    - -

    There is a trade-off between image smoothness and rendering performance. The load gets bigger as the image gets bigger. Users can avoid such scaling overload by using the same size of the image object and the source image.

    - -

    In the following code, 2 image objects are created to show the effects of smooth scaling. The one with smooth scaling applied appears softer on the screen.

    - -
    -#include <Elementary.h>
    -
    -int main(int argc, char **argv)
    -{
    -   elm_init(argc, argv);
    -
    -   // Create a window object
    -   Evas_Object *win = elm_win_add(NULL, "main", ELM_WIN_BASIC);
    -   evas_object_resize(win, 400, 200);
    -   evas_object_show(win);
    -
    -   // Return Evas handle from window
    -   Evas *e = evas_object_evas_get(win);
    -
    -   // Create an image object
    -   Evas_Object *img = evas_object_image_filled_add(e);
    -   evas_object_image_file_set(img, "./logo.png", NULL);
    -   evas_object_move(img, 0, 0);
    -   evas_object_resize(img, 200, 200);
    -   evas_object_show(img);
    -
    -   // Create another image object
    -   Evas_Object *img2 = evas_object_image_filled_add(e);
    -   evas_object_image_file_set(img2, "./logo.png", NULL);
    -
    -   // Disable smooth scaling
    -   evas_object_image_smooth_scale_set(img2, EINA_FALSE);
    -   evas_object_move(img2, 200, 0);
    -   evas_object_resize(img2, 200, 200);
    -   evas_object_show(img2);
    -
    -   elm_run();
    -
    -   elm_shutdown();
    -
    -   return 0;
    -}
    -
    - - - - - - - - - - - - -
    Figure: Smooth scaling effects

    Smooth scaling effects

    Smooth scaling effects

    Smooth scaling enabledSmooth scaling disabled
    - - -

    Evas caches scaled image data and reuses them. Users can save the memory by loading the image in the scaled size to the memory at the beginning. This option is available only for jpeg format at the moment.

    -
    -void evas_object_image_load_size_set(Evas_Object *obj, int w, int h);
    - -

    An example code is as follows.

    -
    -#include <Elementary.h>
    - 
    -int main(int argc, char **argv)
    -{
    -   elm_init(argc, argv);
    - 
    -   // Create a window object
    -   Evas_Object *win = elm_win_add(NULL, "main", ELM_WIN_BASIC);
    -   evas_object_resize(win, 400, 200);
    -   evas_object_show(win);
    - 
    -   // Return Evas handle from window
    -   Evas *e = evas_object_evas_get(win);
    - 
    -   // Create an image object
    -   Evas_Object *img = evas_object_image_filled_add(e); 
    - 
    -   // Load the image scaled into the object size 
    -   // before evas_object_image_file_set() is called
    -   evas_object_image_load_size_set(img, 300, 300);
    - 
    -   evas_object_image_file_set(img, "./logo.png", NULL); 
    -   
    -   evas_object_move(img, 50, 50);
    -   evas_object_resize(img, 300, 300);
    -   evas_object_show(img); 
    - 
    -   elm_run();
    - 
    -   elm_shutdown();
    -
    -   return 0;
    -}
    -
    - -

    Setting Raw Data to Image Object

    -

    Users can set raw data to the image object manually using the evas_object_image_data_set() function instead of setting an image file as the data source. The image data should be in raw data form. In case of an 200x200 sized image with alpha channel enabled (32 bits per pixel), the size of the image data is 14000 (=200*200*4) bytes.

    - -
    void evas_object_image_data_set(Evas_Object *obj, void *data);
    - -

    Image objects fetch metadata such as width or height from the header of the image files. Since the raw data does not have the metadata, users must set the size of the image using the evas_object_image_size_set() function.

    - -
    void evas_object_image_size_set(Evas_Object *obj, int w, int h);
    - -

    The evas_object_image_data_get() function returns the data pointer of an image object and requires a parameter to determine whether the data is modified or not. If users pass EINA_TRUE for for_writing, Evas updates the image pixels in the next rendering cycle.

    - -
    void *evas_object_image_data_get(const Evas_Object *obj, Eina_Bool for_writing);
    - -

    The evas_object_image_data_update_add() helps to mark the updated area for rendering efficiency.

    - -
    void evas_object_image_data_update_add(Evas_Object *obj, int x, int y, int w, int h);
    - -

    The following example code and figure show how to specify the area to update.

    -
    -evas_object_image_data_update_add(image, 100, 100, 50, 50);
    -evas_object_image_data_update_add(image, 180, 100, 50, 50);
    -evas_object_image_data_update_add(image, 85, 200, 160, 80);
    -
    - -

    Figure: Partial image update

    -

    Partial image update

    - -

    The following code creates an image object and sets a source file on it. Then it implements the blur effect to the pixel data and saves them using the evas_object_image_save() function.

    - -
    Eina_Bool evas_object_image_save(const Evas_Object *obj, const char *file, const char *key, const char *flags);
    - -
    -#include <Elementary.h>
    -
    -void image_blur(Evas_Object *img)
    -{
    -   unsigned char *img_src = evas_object_image_data_get(img, EINA_TRUE);
    -
    -   int w, h;
    -   evas_object_image_size_get(img, &w, &h);
    -   int blur_size = 4;
    -   int x, y, xx, yy;
    -   
    -   for (y = 0; y < h; y++)
    -   {
    -      for (x = 0; x < w; x++)
    -      {
    -         int avg_color[3] = {0, 0, 0};
    -         int blur_pixel_cnt = 0;
    -
    -         for (xx = x; (xx < x + blur_size) && (xx < w); xx++)
    -         {
    -            for (yy = y; (yy < y + blur_size) && (yy < h); yy++)
    -            {
    -               int idx = (yy * w * 4) + (xx * 4);
    -               avg_color[0] += img_src[idx + 0];
    -               avg_color[1] += img_src[idx + 1];
    -               avg_color[2] += img_src[idx + 2];
    -               ++blur_pixel_cnt;
    -            }
    -         }
    -         avg_color[0] /= blur_pixel_cnt;
    -         avg_color[1] /= blur_pixel_cnt;
    -         avg_color[2] /= blur_pixel_cnt;
    -
    -         for (xx = x; (xx < x + blur_size) && (xx < w); xx++)
    -         {
    -            for (yy = y; (yy < y + blur_size) && (yy < h); yy++)
    -            {
    -               int idx = (yy * w * 4) + (xx * 4);
    -               img_src[idx + 0] = avg_color[0];
    -               img_src[idx + 1] = avg_color[1];
    -               img_src[idx + 2] = avg_color[2];
    -            }
    -         }
    -      }
    -   }
    -   evas_object_image_data_update_add(img, 0, 0, w, h);
    -}
    -
    -int main(int argc, char **argv)
    -{
    -   elm_init(argc, argv);
    -
    -   Evas_Object *win = elm_win_add(NULL, "main", ELM_WIN_BASIC);
    -   evas_object_resize(win, 200, 200);
    -   evas_object_show(win);
    -
    -   Evas *e = evas_object_evas_get(win);
    -
    -   Evas_Object *img = evas_object_image_filled_add(e);
    -   evas_object_image_file_set(img, "./logo.png", NULL);
    -   evas_object_resize(img, 200, 200);
    -   evas_object_show(img);
    -
    -   image_blur(img);
    -
    -   evas_object_image_save(img, "logo2.png", NULL, "quality=100 compress=8");
    -
    -   elm_run();
    -
    -   elm_shutdown();
    -
    -   return 0;
    -}
    -
    - - - - - - - - - - - - -
    Figure: Blur effect

    Blur effect

    Blur effect

    BeforeAfter
    - - -

    Textblock Objects

    - -

    Unlike basic text objects, a textblock handles complex text, managing multiple styles and multiline text based on HTML-like tags. However, these extra features are heavier on memory and processing cost.

    -

    The textblock objects is an object that shows big chunks of text. Textblock supports many features, including text formatting, automatic and manual text alignment, embedding items (icons, for example). Textblock has three important parts: the text paragraphs, the format nodes and the cursors.

    -

    To set markup to format text, use for example <font_size=50>Big!</font_size>. Set more than one style directive in one tag with <font_size=50 color=#F00>Big and Red!</font_size>. Please note that we used </font_size> although the format also included color. This is because the first format determines the matching closing tag's name. You can use anonymous tags, such as <font_size=30>Big</>, which pop any type of format, but it is advisable to use the named alternatives instead.

    -

    Textblock supports the following formats:

    -
      -
    • font: Font description in fontconfig such as format, for example "Sans:style=Italic:lang=hi". or "Serif:style=Bold".
    • -
    • font_weight: Overrides the weight defined in "font". For example, "font_weight=Bold" is the same as "font=:style=Bold". The supported weights are "normal", "thin", "ultralight", "light", "book", "medium", "semibold", "bold", "ultrabold", "black", and "extrablack".
    • -
    • font_style: Overrides the style defined in "font". For example, "font_style=Italic" is the same as "font=:style=Italic". The supported styles are "normal", "oblique", and "italic".
    • -
    • font_width: Overrides the width defined in "font". For example, "font_width=Condensed" is the same as "font=:style=Condensed". The supported widths are "normal", "ultracondensed", "extracondensed", "condensed", "semicondensed", "semiexpanded", "expanded", "extraexpanded", and "ultraexpanded".
    • -
    • lang: Overrides the language defined in "font". For example, "lang=he" is the same as "font=:lang=he".
    • -
    • font_fallbacks: A comma delimited list of fonts to try if finding the main font fails.
    • -
    • font_size: The font size in points.
    • -
    • font_source: The source of the font, for example an eet file.
    • -
    • color: The text color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", or "#RGBA".
    • -
    • underline_color: The color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", or "#RGBA".
    • -
    • underline2_color: The color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", or "#RGBA".
    • -
    • outline_color: The color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", or "#RGBA".
    • -
    • shadow_color: The color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", or "#RGBA".
    • -
    • glow_color: The color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", or "#RGBA".
    • -
    • glow2_color: The color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", or "#RGBA".
    • -
    • strikethrough_color: The color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", or "#RGBA".
    • -
    • align: The text alignment in one of the following formats: "auto" (according to text direction), "left", "right", "center" or "middle", which take a value between 0.0 and 1.0 or a value between 0% to 100%.
    • -
    • valign: The vertical text alignment in one of the following formats: "top", "bottom", "middle", "center", "baseline" or "base", which take a value between 0.0 and 1.0 or a value between 0% to 100%.
    • -
    • wrap: The text wrap in one of the following formats: "word", "char", "mixed", or "none".
    • -
    • left_margin: Either "reset" or a pixel value indicating the margin.
    • -
    • right_margin: Either "reset" or a pixel value indicating the margin.
    • -
    • underline: The style of underlining in one of the following formats: "on", "off", "single", or "double".
    • -
    • strikethrough: The style of text that is either "on" or "off".
    • -
    • backing_color: The background color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", or "#RGBA".
    • -
    • backing: The background color enabled or disabled: "on" or "off".
    • -
    • style: The style of the text in one of the following formats: "off", "none", "plain", "shadow", "outline", "soft_outline", "outline_shadow", "outline_soft_shadow", "glow", "far_shadow", "soft_shadow" or "far_soft_shadow". The direction is selected by adding "bottom_right", "bottom", "bottom_left", "left", "top_left", "top", "top_right" or "right". For example, "style=shadow,bottom_right".
    • -
    • tabstops: The pixel value for tab width.
    • -
    • linesize: To force a line size in pixels.
    • -
    • linerelsize: Either a floating point value or a percentage indicating the wanted size of the line relative to the calculated size.
    • -
    • linegap: To force a line gap in pixels.
    • -
    • linerelgap: Either a floating point value or a percentage indicating the wanted size of the line relative to the calculated size.
    • -
    • item: Creates an empty space that is filled by an upper layer. Use "size", "abssize", or "relsize" to define the item"s size, and an optional vsize = full/ascent to define the item's position in the line.
    • -
    • linefill: Either a float value or percentage indicating how much to fill the line.
    • -
    • ellipsis: A value between 0.0 and 1.0 to indicate the type of ellipsis, or -1.0 to indicate that an ellipsis is not wanted.
    • -
    • password: Either "on" or "off", this is used to specifically turn replacing chars with the password mode (that is, replacement char) on and off.
    • -
    - - -

    Clipping Objects

    - -

    Limiting Visibility

    -

    An Evas object can be clipped – in other words, its visible area is restricted with the clipper object.

    - -

    It is often necessary to show only parts of an object, and while it may be possible to create an object that corresponds only to the part that must be shown (which is not always possible), it is usually easier to use a clipper. A clipper is a rectangle that defines what is visible and what is not. The way to do this is to create a solid white rectangle (by default, so you need not use evas_object_color_set()) and give it a position and size of what is wanted visible. The following code exemplifies showing the center half of my_evas_object:

    -
    Evas_Object *clipper = evas_object_rectangle_add(evas_canvas);
    -evas_object_move(clipper, my_evas_object_x / 4, my_evas_object_y / 4);
    -evas_object_resize(clipper, my_evas_object_width / 2, my_evas_object_height / 2);
    -evas_object_clip_set(my_evas_object, clipper);
    -evas_object_show(clipper);
    -
    - -

    Layer of Color

    -

    A solid white clipper does not produce a change in the color of the clipped object, only hides what is outside the clipper's area. Changing the color of an object is accomplished by using a colored clipper. Clippers with color function by multiplying the colors of the clipped object. The following code shows how to remove all the red from an object.

    -
    Evas_Object *clipper = evas_object_rectangle_add(evas);
    -evas_object_move(clipper, my_evas_object_x, my_evas_object_y);
    -evas_object_resize(clipper, my_evas_object_width, my_evas_object_height);
    -evas_object_color_set(clipper, 0, 255, 255, 255);
    -evas_object_clip_set(obj, clipper);
    -evas_object_show(clipper);
    -
    - - -

    Mapping Objects

    - -

    Evas allows different transformations to be applied to all kinds of objects. These are applied by means of UV mapping. With UV mapping, one map points in the source object to a 3D space positioning at target. This allows rotation, perspective, scale, and many other effects depending on the map that is used.

    - -

    Creating a Map

    -

    A map consists of a set of points, but currently only four are supported. Each of these points contains a set of canvas coordinates x and y that are used to alter the geometry of the mapped object, and a z coordinate that indicates the depth of that point. This last coordinate does not normally affect the map, but is used by several of the utility functions to calculate the right position of the point given other parameters.

    -

    The coordinates for each point are set with evas_map_point_coord_set(map, index, x, y, z). In the example below, there is a rectangle whose coordinates are (100, 100) and (300, 300).

    -
    Evas_Object *object = evas_object_rectangle_add(evas);
    -evas_object_move(object, 100, 100);
    -evas_object_resize(object, 200, 200);
    -Evas_Map map = evas_map_new(4);
    -evas_map_point_coord_set(map, 0, 100, 100, 0);
    -evas_map_point_coord_set(map, 1, 300, 100, 0);
    -evas_map_point_coord_set(map, 2, 300, 300, 0);
    -evas_map_point_coord_set(map, 3, 100, 300, 0);
    -
    -

    There are functions to ease the process.

    -

    Use evas_map_util_points_populate_from_geometry(map, x, y, w, h, z), where the map coordinates are set to the given rectangle, and z is the coordinate in the Z axis, which is the same for all points.

    -
    Evas_Object *object = evas_object_rectangle_add(evas);
    -evas_object_move(object, 100, 100);
    -evas_object_resize(object, 200, 200);
    -Evas_Map map = evas_map_new(4);
    -evas_map_util_points_populate_from_geometry(map, 100, 100, 200, 200, 0);
    -
    - -

    You can also use evas_map_util_points_populate_from_object(map, object).

    -
    Evas_Object *object = evas_object_rectangle_add(evas);
    -evas_object_move(object, 100, 100);
    -evas_object_resize(object, 200, 200);
    -Evas_Map map = evas_map_new(4);
    -evas_map_util_points_populate_from_object(map, object);
    -
    - -

    You can also use evas_map_util_points_populate_from_object_full(map, object, z), where z is the coordinate in the Z axis, which is the same for all points.

    -
    Evas_Object *object = evas_object_rectangle_add(evas);
    -evas_object_move(object, 100, 100);
    -evas_object_resize(object, 200, 200);
    -Evas_Map map = evas_map_new(4);
    -evas_map_util_points_populate_from_object_full(map, object, 0);
    -
    - -

    Manual Point Setting

    -

    Several effects are applied to an object by setting each point of the map to the right coordinates. For example, a simulated perspective is achieved as follows.

    -
    evas_map_point_coord_set(map, 0, 300, 100, 0);
    -evas_map_point_coord_set(map, 1, 450, 120, 0);
    -evas_map_point_coord_set(map, 2, 450, 260, 0);
    -evas_map_point_coord_set(map, 3, 300, 300, 0);
    -
    - -

    The Z coordinate is not used when setting points by hand; thus its value is not important.

    - -

    Applying a Map

    -

    Regardless of the specific way you create a map, to apply it to a specific object, use

    -
    evas_object_map_set(object, map);
    -evas_object_map_enable_set(object, EINA_TRUE);
    -
    - -

    Basic Utility Functions

    -

    Evas provides utility functions for common transformations:

    -
      -
    • evas_map_util_rotate(map, angle, cx, cy): This performs a rotation of the angle degrees around the center point with the coordinates (cx, cy).
    • -
    • evas_map_util_zoom(map, zoomx, zoomy, cx, cy): This performs a zoomx and zoomy zoom in the X and Y directions respectively, with the center point with the coordinates (cx, cy).
    • -
    - -

    For example, the following code rotates an object around its center.

    -
    int x, y, w, h;
    -evas_object_geometry_get(object, &x, &y, &w, &h);
    -Evas_Map *map = evas_map_new(4);
    -evas_map_util_points_populate_from_object(map, object);
    -evas_map_util_rotate(map, 45, x + (w / 2), y + (h / 2));
    -evas_object_map_set(object, map);
    -evas_object_map_enable_set(object, EINA_TRUE);
    -evas_map_free(m);
    -
    - -

    The following code rotates an object around the center of the window.

    -
    int w, h;
    -evas_output_size_get(evas, &w, &h);
    -Evas_Map *map = evas_map_new(4);
    -evas_map_util_points_populate_from_object(map, object);
    -evas_map_util_rotate(map, 45, w / 2, h / 2);
    -evas_object_map_set(object, map);
    -evas_object_map_enable_set(object, EINA_TRUE);
    -evas_map_free(m);
    -
    - -

    3D Utility Functions

    -

    Evas provides utility functions for 3D transformations.

    -

    To make a 3D rotation, use evas_map_util_3d_rotate(map, anglex, angley, anglez, cx, cy, cz). With this code, you can set the Z coordinate of the rotation center, and the angles to rotate through around all axes.

    -

    Rotating in the 3D space does not look natural. A more natural look becomes by adding perspective to the transformation, which is done with evas_map_util_3d_perspective(map, px, py, z0, focal) on the map after its position has been set.

    - -
      -
    • px and py specify the "infinite distance" point in the 3D conversion, where all lines converge to.
    • -
    • z0 specifies the Z value at which there is a 1:1 mapping between spatial coordinates and screen coordinates: any points on this Z value do not have their X and Y coordinates modified in the transform, while those further away (Z value higher) shrink into the distance, and those less than this value expand.
    • -
    • focal determines the "focal length" of the camera: this is the distance in reality between the camera lens plane (the rendering results are undefined at or closer than this) and the z0 value; this function allows for some "depth" control.
    • -
    -

    Color and Lighting

    -

    Each point in a map can be set to a color, which is multiplied with the object's own color and linearly interpolated in between adjacent points. To do this, use evas_map_point_color_set(map, index, r, g, b, a) for each point of the map, or evas_map_util_points_color_set(map, r, g, b, a) to set every point into the same color.

    -

    To add lighting for the objects, which is useful with 3D transforms, use evas_map_util_3d_lighting(map, lightx, lighty, lightz, lightr, lightg, lightb, ambientr, ambientg, ambientb):

    -
      -
    • lightx, lighty and lightz are the local light source coordinates;
    • -
    • lightr, lightg and lightb are the local light source colors;
    • -
    • ambientr, ambientg and ambientb are the ambient light colors. Evas sets the color of each point based on the distance to the light source, the angle with which the object is facing the light and the ambient light. The orientation of each point is important. If the map is defined counter-clockwise, the object faces away from the user and becomes obscured, since no light does not reflect from it.
    • -
    - -

    Evas Engines Concept

    -

    Evas delegates most of the actual rendering work to its engines. Engines are the backends that Evas uses to render (primitive) objects on a canvas. The canvas can be the screen, or a buffer in the memory.

    -

    Evas can work with and provides multiple engines, such as (this list is non-exhaustive):

    -
      -
    • buffer: all the rendering takes place in a buffer
    • -
    • fb: the rendering takes place in the system's framebuffer
    • -
    • software_x11: this is the most used, using X11
    • -
    • gl_x11: this also renders to an X11 window, except that it uses OpenGL
    • -
    -

    These implement the rendering of all the basic objects by themselves, because they often can be accelerated by the hardware or backend software libraries to provide fast rendering.

    -

    If a particular engine does not have the provision for a certain primitive object, it reverts back to using a default software version.

    - -

    UI Rendering Mode

    - -

    Evas removes the need to know about the characteristics of your display system or what graphics calls are used to draw them and how. It deals on an object level where all you do is create and manipulate objects in a canvas, set their properties, and the rest is done for you. This rendering method is called the retained mode, whereas the immediate mode is an alternative rendering method.

    - -

    Immediate Mode

    - -

    The immediate mode is the most commonly used in graphics toolkit libraries, such as GTK+, GDI, and GDI+. The application is responsible for repainting the portion of the client area that is invalidated.

    - -

    Figure: Immediate mode

    -

    Immediate mode

    - -

    The application commands any drawing issues as it needs, and the display system draws some GUIs. After the drawing is done, it appears in the destination. This mode allows you to have a exact control over the render cycles. However, if the draw commands are misused, unnecessary drawing can be performed or drawing never happen at all.

    -

    The following example explains the common usage of the immediate mode:

    - -
    -void update()
    -{
    -   Image *img = load_image(NEW_IMG);
    -
    -   // Switch button image to new one
    -   update_button_image(img);
    -
    -   // Issue the invalidate area (button area) to be redrawn on the screen
    -   invalidate_area(button_x, button_y, button_w, button_h);
    -
    -   // Move rectangle from (200, 200) to (300, 300)
    -   int rect_prev_x = rect_x;
    -   int rect_prev_y = rect_y;
    -   rectangle_x = 300;
    -   rectangle_y = 300;
    -   set_rect_position(rect_x, rect_y);
    -   
    -   // Issue the invalidate area (changed area) to be redrawn on the screen
    -   int diff_x = rect_x – rect_prev_x;
    -   int diff_y = rect_y – rect_prev_y;
    -   invalidate_area(rect_prev_x, rect_prev_y, (rect_w + diff_x), (rect_h + diff_y));
    -
    -
    -   // After setting the invalidate area, request rendering to update the screen
    -   render();
    -
    -   // Now you can see how the button image and rectangle position are changed
    -}
    -
    - -

    Retained Mode

    - -

    A graphics system adopting the retained mode is basically responsible for responding to all repaint requests for rendering the application objects. Clients do not directly cause actual rendering, but objects are redrawn when parts of them are updated.

    - -

    Figure: Retained mode

    -

    Retained mode

    - -

    Since Evas works with the retained mode, there is no need to command any drawings. The following example shows how to write a GUI code with Evas for your application:

    - -
    -void create_image()
    -{
    -   // Initialize an image object to be displayed on the screen
    -   Evas_Object *img = evas_object_image_add(e);
    -
    -   // Set image resource
    -   evas_object_image_file_set(img, IMG, NULL);
    -
    -   // Set image position 
    -   evas_object_move(img, 100, 100);
    -
    -   // Set image size
    -   evas_object_resize(img, 200, 200);
    -
    -   // Set image visibility (show or hide)
    -   evas_object_show(img);
    -}
    -
    -void create_rectangle()
    -{
    -   // Initialize an rectangle object to be displayed on the screen
    -   Evas_Object *rect = evas_object_rectangle_add(e);
    -
    -   // Set rectangle color
    -   evas_object_color_set(rect, 255, 0, 0, 255);
    -
    -   // Set rectangle position
    -   evas_object_move(rect, 200, 200);
    -
    -   // Set rectangle size
    -   evas_object_resize(rect, 200, 200);
    -
    -   // Set rectangle visibility (show or hide)
    -   evas_object_show(rect);
    -}
    -
    - -

    A few main loops later you can replace the image with another one and move the rectangle. You only need to set a new image file to the image object and move the rectangle object. Evas computes the invalidate area and redraws the image and rectangle behind the application when it's on rendering time.

    - -
    -void update()
    -{
    -   // Set new image resource
    -   elm_image_file_set(img, NEW_IMG, NULL);
    -
    -   // Set new rectangle position
    -   evas_object_move(rect, 300, 300);
    -}
    -
    - -

    Evas Rendering

    - -

    Tizen Native applications work on the ecore main loop, and the loop goes on a few steps for every frame. Evas redraws some changes in the objects when the main loop goes to the idle enterer step. If there are no changes, Evas rendering is skipped. Otherwise, Evas calculates any changed portions of all display objects and redraws them.

    - -

    Figure: Evas rendering in the main loop

    -

    Evas rendering in the main loop

    - -

    To minimize the rendering, Evas tracks the states of all display objects, such as position, size, visibility, and color. Even if some of these states are changed but the object is hidden by other obscured objects, it is not redrawn. In other words, Evas draws only the necessary changes in the screen.

    - -

    The following figures illustrate how Evas redraws the changed area:

    - -
    • In the first example, there is a blue-color background object (a sky-blue color rectangle) and a partially hidden cloud image object. Above them, there are a red and green rectangle, and the "Hello out there" text is printed on the green rectangle.

      - -

      Figure: Evas redrawing example 1

      -

      Evas redrawing example 1

    • - -
    • In the second example, some of the objects have moved (the cloud image is moved to right and the green rectangle is moved downwards).

      - -

      Figure: Evas redrawing example 2

      -

      Evas redrawing example 2

    • - -
    • As a result, the third example illustrates some regions that require updates.

      - -

      Figure: Evas redrawing example 3

      -

      Evas redrawing example 3

    • - -
    • Evas decides which portions are invalid and to be redrawn. The fourth example shows the cleaned portion of the screen, which is the redrawn area.

      -

      Evas redraws the content only in the redrawn portions.

      -

      Figure: Evas redrawing example 4

      -

      Evas redrawing example 4

    • - -
    • Finally, the fifth example shows how the screen is updated and the result is visible.

      - -

      Figure: Evas redrawing example 5

      -

      Evas redrawing example 5

      - -

      If Evas worked in an immediate mode style, the application would need to calculate the changed areas themselves, adding extra work. With Evas, you can let Evas figure out the updates and you can yourself concentrate on the application and UI core and logic.

    - - - -
    - -Go to top - - - - - - - \ No newline at end of file diff --git a/org.tizen.guides/html/native/ui/event_types_n.htm b/org.tizen.guides/html/native/ui/event_types_n.htm deleted file mode 100644 index e1f14b4..0000000 --- a/org.tizen.guides/html/native/ui/event_types_n.htm +++ /dev/null @@ -1,630 +0,0 @@ - - - - - - - - - - - - - Event Types - - - - - -
    - -

    Event Types

    - - - -

    Ecore Events

    - -

    Table of Contents

    - - - -

    Ecore events are used for low-level handling of events such as key presses, network connections, and communication with sub-processes.

    -

    The low-level handling of key presses is particularly useful for shortcuts: instead of adding a signal handler to a specific graphical element, you can add one globally. This guarantees that no matter which UI component is currently receiving events, the shortcut is caught.

    -

    Note that ecore events are also used to implement new graphical back-ends, but they are low-level and not useful for most applications.

    -

    Ecore Events Useful for Shortcuts

    - -

    There are eight ecore events for shortcuts:

    -
    int ECORE_EVENT_KEY_DOWN;
    -int ECORE_EVENT_KEY_UP;
    -int ECORE_EVENT_MOUSE_BUTTON_DOWN;
    -int ECORE_EVENT_MOUSE_BUTTON_UP;
    -int ECORE_EVENT_MOUSE_MOVE;
    -int ECORE_EVENT_MOUSE_WHEEL;
    -int ECORE_EVENT_MOUSE_IN;
    -int ECORE_EVENT_MOUSE_OUT;
    -
    -

    The callbacks receive additional data through a void * object, whose type depends on the event that has been received.

    -
      -
    • for ECORE_EVENT_KEY_DOWN and ECORE_EVENT_KEY_UP: -
      -typedef struct _Ecore_Event_Key Ecore_Event_Key;
      -
      -struct _Ecore_Event_Key 
      -{
      -   const char *keyname;
      -   const char *key;
      -   const char *string;
      -   const char *compose;
      -   Ecore_Window window;
      -   Ecore_Window root_window;
      -   Ecore_Window event_window;
      -
      -   unsigned int timestamp;
      -   unsigned int modifiers;
      -
      -   int same_screen;
      -};
      -
      - -
    • - -
    • for ECORE_EVENT_MOUSE_BUTTON_DOWN and ECORE_EVENT_MOUSE_BUTTON_UP: -
      typedef struct _Ecore_Event_Mouse_Button Ecore_Event_Mouse_Button;
      -struct _Ecore_Event_Mouse_Button 
      -{
      -   Ecore_Window window;
      -   Ecore_Window root_window;
      -   Ecore_Window event_window;
      -
      -   unsigned int timestamp;
      -   unsigned int modifiers;
      -   unsigned int buttons;
      -   unsigned int double_click;
      -   unsigned int triple_click;
      -   int same_screen;
      -
      -   int x;
      -   int y;
      -   struct 
      -   {
      -      int x;
      -      int y;
      -   } root;
      -
      -   struct 
      -   {
      -      // 0 if normal mouse, 1+ for other mouse-devices (eg multi-touch - other fingers)
      -      int device; 
      -      // Radius of press point - radius_x and y if its an ellipse (radius is the average of the 2)
      -      double radius, radius_x, radius_y; 
      -      // Pressure - 1.0 == normal, > 1.0 == more, 0.0 == none
      -      double pressure; 
      -      // Angle relative to perpendicular (0.0 == perpendicular), in degrees
      -      double angle; 
      -      // Same as x, y root.x, root.y, but with sub-pixel precision, if available
      -      double x, y; 
      -      struct 
      -      {
      -         double x;
      -         double y;
      -      } root;
      -   } multi;
      -};
      -
      - -
    • -
    • for ECORE_EVENT_MOUSE_MOVE and ECORE_EVENT_MOUSE_WHEEL: -
      -typedef struct _Ecore_Event_Mouse_Wheel Ecore_Event_Mouse_Wheel;
      -struct _Ecore_Event_Mouse_Wheel 
      -{
      -   Ecore_Window window;
      -   Ecore_Window root_window;
      -   Ecore_Window event_window;
      -
      -   unsigned int timestamp;
      -   unsigned int modifiers;
      -
      -   int same_screen;
      -   int direction;
      -   int z;
      -
      -   int x;
      -   int y;
      -   struct 
      -   {
      -      int x;
      -      int y;
      -   } root;
      -};
      -
      -
    • -
    • for ECORE_EVENT_MOUSE_IN and int ECORE_EVENT_MOUSE_OUT: -
      -typedef struct _Ecore_Event_Mouse_Move Ecore_Event_Mouse_Move;
      -struct _Ecore_Event_Mouse_Move 
      -{
      -   Ecore_Window window;
      -   Ecore_Window root_window;
      -   Ecore_Window event_window;
      -
      -   unsigned int timestamp;
      -   unsigned int modifiers;
      -
      -   int same_screen;
      -
      -   int x;
      -   int y;
      -   struct 
      -   {
      -      int x;
      -      int y;
      -   } root;
      -
      -   struct 
      -   {
      -      int device; // 0 if normal mouse, 1+ for other mouse-devices (eg multi-touch - other fingers)
      -      double radius, radius_x, radius_y; // radius of press point - radius_x and y if it is an ellipse (radius is the average of the two)
      -      double pressure; // pressure - 1.0 == normal, > 1.0 == more, 0.0 == none
      -      double angle; // angle relative to perpendicular (0.0 == perpendicular), in degrees
      -      double x, y; // same as x, y root.x, root.y, but with sub-pixel precision, if available
      -      struct 
      -      {
      -         double x, y;
      -      } root;
      -   } multi;
      -};
      -
      - -
    • -
    -

    Add an Event Handler: ecore_event_handler_add()

    -

    The ecore_event_handler_add() function enables registering a callback for the given event. Its prototype is:

    -
    -Ecore_Event_Handler* 
    -ecore_event_handler_add(int type,
    -                        Ecore_Event_Handler_Cb func,
    -                        const void* data)
    -
    - -
      -
    • type is an identifier for the event; for example, if you wish to receive notifications when keys are pressed, give ECORE_EVENT_KEY_DOWN.
    • -
    • func is the callback that is called when the event takes place.
    • -
    • data is a pointer to additional data that is given as the argument to the callback; it is optional and NULL is an acceptable value.
    • -
    • return value is a pointer to the event handler, which can be used later to uninstall the handler.
    • -
    - -

    The type of the callback function is defined as follows.

    -
    -Eina_Bool (* Ecore_Event_Handler_Cb) (void *data, int type, void *event)
    -

    The callback function declaration is similar to:

    -
    Eina_Bool some_ecore_event_cb(void *data, int type, void *event);
    -
      -
    • data is the same as the data which was given as a parameter to ecore_event_handler_add().
    • -
    • type is the same as the type which was given as a parameter to ecore_event_handler_add().
    • -
    • event is an object whose actual type depends on the value of the type parameter and is one of Ecore_Event_Key, Ecore_Event_Mouse_Button, Ecore_Event_Mouse_Wheel, Ecore_Event_Mouse_Move.
    • -
    • The return value is either ECORE_CALLBACK_PASS_ON, to allow other callbacks for that event be called, or ECORE_CALLBACK_DONE to not call them.
    • -
    -

    The code below is a short example of how to set a global variable to EINA_TRUE when the Control key is pressed.

    -
    -Eina_Bool ctrl_pressed = EINA_FALSE;
    -
    -static Eina_Bool
    -_key_down_cb(void *data __UNUSED__, int type __UNUSED__, void *ev)
    -{
    -   // The callback is used with the ECORE_EVENT_KEY_DOWN signal: the
    -   // parameter "void *ev" is therefore of the actual type Ecore_Event_Key
    -   // The following renders its fields accessible
    -   Ecore_Event_Key *event = ev;
    -
    -   // Test whether the key that is pressed is Ctrl.
    -   if (!strcmp("Control_L", event->key))
    -   {
    -      // If it is, store that piece of information
    -      ctrl_pressed = EINA_TRUE;
    -   }
    -
    -   // Let the event continue to other callbacks which have not been called yet
    -   return ECORE_CALLBACK_PASS_ON;
    -}
    -
    -ecore_event_handler_add(ECORE_EVENT_KEY_DOWN, _key_down_cb, NULL);
    -
    - -

    Remove an Event Handler: ecore_event_handler_del()

    -

    To remove an event handler, use the ecore_event_handler_del() function. The prototype is:

    -
    -void* ecore_event_handler_del(Ecore_Event_Handler *event_handler)
    -
    - -
      -
    • event_handler is the value returned by ecore_event_handler_add().
    • -
    • The return value is the data pointer that was used in the corresponding call to ecore_event_handler_add().
    • -
    -

    Send Events to the Main Loop Yourself: ecore_event_add()

    -

    You can send events to the main-loop, which helps to handle actions of various origins through the same codepath. Note that this is a thread-safe operation.

    -

    To send an event, use the ecore_event_add() function. The prototype is

    -
    Ecore_Event* 
    -ecore_event_add(int type,
    -                void* ev,
    -                Ecore_End_Cb func_free,
    -                void* func_free_data)
    -
    - -
      -
    • type is the event type. For example, ECORE_EVENT_KEY_DOWN.
    • -
    • ev is the event data. It is given as a parameter to the callback.
    • -
    • func_free is a function to free ev after the callback is called. It is optional: NULL is an acceptable value.
    • -
    • func_free_data is a pointer to additional data that is given as an argument to the func_free callback. It is optional: NULL is an acceptable value.
    • -
    - -

    The type of the func_free function is defined as follows.

    -
    void (* Ecore_End_Cb)(void *user_data, void *func_free_data)
    -

    The callback function declaration is thus similar to

    -
    void some_func_free(void *user_data, void *func_free_data);
    - -

    Create Your Own Type of Events: ecore_event_type_new()

    - -

    You can create your own events. It also helps to use a single codepath.

    -

    The function for creating your own events is ecore_event_type_new(). The prototype is:

    -
    int ecore_event_type_new(void);
    -

    It generates a new unique identifier, which you can use as type in the functions described above.

    - -

    Edje Events

    - -

    Table of Contents

    - - -

    Edje themes have program sections. These are small sections triggered upon the reception of a signal that can execute actions, such as changing the state of an edje part and running another program.

    -

    For more information on themes and programs, see the Edje guide.

    - -

    Basic Usage for a Single Part

    -

    An example program is shown below:

    -
    program 
    -{
    -   name: "change_color";
    -   signal: "mouse,clicked,*";
    -   source: "*";
    -   action: SIGNAL_EMIT "got.a.click" "color_changer";
    -}
    -
    -

    This is a program named "change_color", which triggers on mouse clicks on the current part and emits a signal "got.a.click". The source is set to "color_changer".

    - -

    To catch this signal from the C side, you need to use either edje_object_signal_callback_add() or elm_object_signal_callback_add(). The only difference between the two is that the previous one operates on an edje object and the latter one on an elementary object. Unless you do not use Elementary at all, use the Elementary variant.

    -

    The prototypes of these two functions are shown below.

    -
    void
    -edje_object_signal_callback_add(Edje_Object *obj, const char *emission, const char *source,
    -                                Edje_Signal_Cb func, void *data)
    -
    -
    void
    -elm_object_signal_callback_add(Evas_Object *obj, const char *emission, const char *source,
    -                               Edje_Signal_Cb func, void *data)
    -
    -
      -
    • obj the object which emits the signal that you react on.
    • -
    • emission is the signal name ("*" acts as a wildcard).
    • -
    • source is the signal source (the second parameter to SIGNAL_EMIT above). ("*" acts as a wildcard.)
    • -
    • func is the callback when emission and source match.
    • -
    • data is a pointer to additional data to pass that is given as the argument to the callback. It is optional and NULL is an acceptable value.
    • -
    - -

    The type of the callback function is defined as follows.

    -
    void (*Edje_Signal_Cb) (void *data, Evas_Object *obj, const char *emission, const char *source);
    - -

    The callback function definition is similar to

    -
    void func(void *data, Evas_Object *obj, const char *emission, const char *source);
    -
      -
    • data is the same as the data which was given as parameter to either edje_object_signal_callback_add() or elm_object_signal_callback_add().
    • -
    • obj is the object which emits the signal.
    • -
    • emission is the signal name.
    • -
    • source is the signal source.
    • -
    - -

    Usual Usage for Parts Aggregated in Groups: with Layouts

    -

    Most of the time, edje and elementary are used together. In particular, you can define a group in Edje and use it as a layout in Elementary. This enables doing the theming and object placement in Edje while benefiting from the higher-level functions of Elementary. This is achieved through layouts, which contain several parts and are explained in the Layout guide (in mobile and wearable applications).

    -

    Since there are several parts in a layout, it is not possible to use elm_object_signal_callback_add() and edje_object_signal_callback_add(), as they require a single emitter object. The solution is to use the dedicated function elm_layout_signal_callback_add(). Its prototype is shown below.

    -
    void
    -elm_layout_signal_callback_add(Evas_Object *obj, const char *emission, const char *source,
    -                               Edje_Signal_Cb func, void *data)
    -
    - -

    elm_layout_signal_callback_add() works very similarly to the functions described in the previous section. The only difference is the type of the object in the first parameter. For elm_layout_signal_callback_add() it is a pointer to an Evas_Object, which is obtained through elm_layout_add() as described in the Layout guide (in mobile and wearable applications).

    - - - - - - -

    Evas Events

    - -

    Table of Contents

    - - -

    Evas events happen on a canvas as a whole. This kind of events are too low-level for writing applications and are most often used when writing the graphical toolkit itself.

    - -

    Adding Callbacks to Canvases: evas_event_callback_add/del

    -

    The callbacks are added with evas_event_callback_add(). Its prototype is

    -
    void
    -evas_event_callback_add(Evas* e, Evas_Callback_Type type, Evas_Event_Cb func, const void* data)
    -
    - -
      -
    • e is the evas canvas on which the events happen. If needed, it can be obtained from an Evas_Object through the evas_object_evas_get() function.
    • -
    • type is the type of event that triggers the callback (the list is in the next section).
    • -
    • func is the function that is called.
    • -
    • data is a pointer to additional data that is given as an argument to the callback. It is optional and NULL is an acceptable value.
    • -
    - -

    The type of the callback function is defined as follows.

    -
    void (* Evas_Event_Cb) (void *data, Evas *e, void *event_info)
    - -

    The callback function definition is similar to

    -
    void some_evas_object_event_cb(void *data, Evas *e, void *event_info);
    - -
      -
    • data is the same as the data which was given as the parameter to evas_event_callback_add().
    • -
    • e is the canvas on which the event occurred.
    • -
    • event_info is data which depends on the object type and the event at play. The documentation must be read for each such event.
    • -
    - -

    Types of Evas Events

    -

    The values are defined from the Evas_Callback_Type enum. Some of them are not used for evas_event_callback_add() but are used in the previous section.

    - -
      -
    • EVAS_CALLBACK_RENDER_FLUSH_PRE: The rendering on the canvas is about to be updated.
    • -
    • EVAS_CALLBACK_RENDER_FLUSH_POST: The rendering on the canvas is updated.
    • -
    • EVAS_CALLBACK_CANVAS_FOCUS_IN: The canvas receives focus.
    • -
    • EVAS_CALLBACK_CANVAS_FOCUS_OUT: The canvas loses focus.
    • -
    • EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_IN: Any object on the canvas receives focus. It is advisable to use evas_object_event_callback_add() and EVAS_CALLBACK_FOCUS_IN instead.
    • -
    • EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_OUT: Any object on the canvas loses focus. It is advisable to use evas_object_event_callback_add() and EVAS_CALLBACK_FOCUS_OUT instead.
    • -
    • EVAS_CALLBACK_RENDER_PRE: Rendering on the canvas starts.
    • -
    • EVAS_CALLBACK_RENDER_POST: Rendering on the canvas finishes.
    • -
    - -

    Evas Object Events

    - - - -

    Table of Contents

    - - -

    Each of the evas objects on a given evas canvas can be manipulated independently. They send events, to which callbacks can be attached through evas_object_event_callback_add() and removed with evas_object_event_callback_del(). These events all relate to single objects, not the whole canvas.

    - -

    Adding and Removing Callbacks: evas_object_event_callback_add/del

    -

    Callbacks are added with evas_event_callback_add(). Its prototype is

    -
    void
    -evas_object_event_callback_add(Evas_Object* obj, Evas_Callback_Type type, Evas_Object_Event_Cb func, const void* data)
    -
    - -
      -
    • obj is the object to attach the callback to.
    • -
    • type is the type of event that triggers the callback (the list is in the next section).
    • -
    • func is the function that is called.
    • -
    • data is a pointer to additional data that is given as the argument to the callback. It is optional and NULL is an acceptable value.
    • -
    - -

    The type of the callback function is defined as follows.

    -
    -void (* Evas_Object_Event_Cb) (void *data, Evas *e, Evas_Object *obj, void *event_info)
    -
    - -

    The callback function definition is similar to

    -
    -void some_evas_object_event_cb(void *data, Evas *e, Evas_Object *obj, void *event_info);
    -
    -
      -
    • data is the same as the data which was given as the parameter to evas_object_smart_callback_add().
    • -
    • e is the canvas on which the event occurred.
    • -
    • obj is the object to which the event happened.
    • -
    • event_info is data which depends on the object type and event at play. The documentation must be read for each event.
    • -
    -

    Types of Evas Object Events

    -

    The values are defined from the Evas_Callback_Type enum. Some of them are not used for evas_object_event_callback_add(), but are used in the next section.

    -
      -
    • EVAS_CALLBACK_MOUSE_IN: the pointer got over an object (with no other object between the two). This takes place no matter how the pointer becomes directly above the object. event_info in the callback is a pointer to an Evas_Event_Mouse_In struct.
    • -
    • EVAS_CALLBACK_MOUSE_OUT: triggered similarly to EVAS_CALLBACK_MOUSE_IN, but when the pointer goes outside an object's area. event_info in the callback is a pointer to an Evas_Event_Mouse_Out struct.
    • -
    • EVAS_CALLBACK_MOUSE_DOWN: a mouse button is pressed while the object is receiving events (either because the pointer is on top of the object or because the object had focus). event_info in the callback is a pointer to an Evas_Event_Mouse_Down struct.
    • -
    • EVAS_CALLBACK_MOUSE_UP: triggered similarly to EVAS_CALLBACK_MOUSE_DOWN. event_info in the callback is a pointer to an Evas_Event_Mouse_Up struct.
    • -
    • EVAS_CALLBACK_MOUSE_MOVE: triggered similarly to EVAS_CALLBACK_MOUSE_DOWN. event_info in the callback is a pointer to an Evas_Event_Mouse_Move struct.
    • -
    • EVAS_CALLBACK_MOUSE_WHEEL: triggered similarly to EVAS_CALLBACK_MOUSE_DOWN. event_info in the callback is a pointer to an Evas_Event_Mouse_Wheel struct.
    • -
    • EVAS_CALLBACK_MULTI_DOWN: triggered similarly to EVAS_CALLBACK_MOUSE_DOWN. event_info in the callback is a pointer to an Evas_Event_Multi_Down struct.
    • -
    • EVAS_CALLBACK_MULTI_UP: triggered similarly to EVAS_CALLBACK_MOUSE_DOWN. event_info in the callback is a pointer to an Evas_Event_Multi_Up struct.
    • -
    • EVAS_CALLBACK_MULTI_MOVE: triggered similarly to EVAS_CALLBACK_MOUSE_DOWN. event_info in the callback is a pointer to an Evas_Event_Multi_Move struct.
    • -
    • EVAS_CALLBACK_KEY_DOWN: triggered similarly to EVAS_CALLBACK_MOUSE_DOWN. event_info in the callback is a pointer to an Evas_Event_Key_Down struct.
    • -
    • EVAS_CALLBACK_KEY_UP: triggered similarly to EVAS_CALLBACK_MOUSE_DOWN. event_info in the callback is a pointer to an Evas_Event_Key_Up struct.
    • -
    • EVAS_CALLBACK_FOCUS_IN: the object gained focus. event_info in the callback is a pointer to an Evas_Event_Mouse_In struct.
    • -
    • EVAS_CALLBACK_FOCUS_OUT: the object lost focus. event_info in the callback is a pointer to an Evas_Event_Mouse_In struct.
    • -
    • EVAS_CALLBACK_SHOW: the object is shown by a call to evas_object_show(). event_info in the callback is NULL.
    • -
    • EVAS_CALLBACK_HIDE: the object is hidden by a call to evas_object_hide(). event_info in the callback is NULL.
    • -
    • EVAS_CALLBACK_MOVE: the object's origin was moved (origin is the top-left corner at the creation time of the object). event_info in the callback is NULL.
    • -
    • EVAS_CALLBACK_RESIZE: the object is resized. event_info in the callback is NULL.
    • -
    • EVAS_CALLBACK_RESTACK: the object is re-stacked by evas_object_stack_below(), evas_object_stack_above() or other events. event_info in the callback is NULL.
    • -
    • EVAS_CALLBACK_DEL: the object is deleted.
    • -
    • EVAS_CALLBACK_FREE: for internal use only. Do not use (the object resources are about to be freed). event_info in the callback is NULL.
    • -
    • EVAS_CALLBACK_HOLD: for internal use only. event_info in the callback is a pointer to an Evas_Event_Hold struct.
    • -
    • EVAS_CALLBACK_CHANGED_SIZE_HINTS: the size hints of the object changed.
    • -
    • EVAS_CALLBACK_IMAGE_PRELOADED: an image which was preloaded through evas_object_image_preload() is loaded. event_info in the callback is NULL.
    • -
    • EVAS_CALLBACK_IMAGE_UNLOADED: the image data is unloaded. event_info in the callback is NULL.
    • -
    - -

    Evas Smart Object Events

    - -

    Table of Contents

    - - -

    Evas smart objects events are the most widely-used type of events in graphical applications, since they are used for signals such as "clicked", "clicked,double" (double-click), "pressed", etc. They are identified by strings and each smart object is able to define its own events (although the names follow conventions).

    - -

    Adding a Callback on an Event: evas_object_smart_callback_add()

    - -

    Use the evas_object_smart_callback_add() function to add a callback for an event to an object. Its prototype is

    -
    -void
    -evas_object_smart_callback_add(Evas_Object* obj, const char* event, Evas_Smart_Cb func, const void* data)
    -
    - -
      -
    • obj is the object to add the callback to.
    • -
    • event is the name of the event.
    • -
    • func is the function that is called.
    • -
    • data is a pointer to additional data that is given as the argument to the callback. It is optional and NULL is an acceptable value.
    • -
    -

    The type of the callback function is defined as follows.

    -
    -void (* Evas_Smart_Cb) (void *data, Evas_Object *obj, void *event_info)
    -

    The callback function definition is similar to

    -
    void some_evas_smart_cb(void *data, Evas_Object *obj, void *event_info);
    -
      -
    • data is the same as the data which is given as the parameter to evas_object_smart_callback_add().
    • -
    • obj is the object for which the event happened.
    • -
    • event_info is data, which depends on the object type and event at play. The actual type is given in the documentation for the callback that is triggered.
    • -
    -

    The following defines the _button_clicked() function and sets it as the callback for the clicked event of an Evas_Object (a button here).

    -
    -static void
    -_button_clicked(void *data, Evas_Object *obj, void *event_info)
    -{
    -   // Insert function body here
    -}
    -
    -static void
    -some_function(void) 
    -{
    -   // Code to build the window object
    -   Evas_Object *button = elm_button_add(window);
    -   evas_object_smart_callback_add(button, "clicked", _button_clicked, NULL);
    -}
    -
    - -

    If some of the arguments are not used by the callback function, the compiler may raise the "unused parameter" warning. To avoid it, you can annotate the argument with the __UNUSED__ macro, which is a compiler-independent way to let the compiler know that the parameter is willingly unused rather than by a mistake.

    -
    void cb(void *data __UNUSED__, Evas_Object *obj, void *event_info __UNUSED__);
    - -

    For a given object and event, callbacks are called in the order they have been added. The evas_object_smart_callback_add() function does not execute any special processing if it is called several times with the same callback function and/or data. Callbacks are called as many times as they have been added and in the order they have been added.

    - -

    Removing a Callback on an Event: evas_object_smart_callback_del()

    -

    The evas_object_smart_callback_del() function enables deleting a callback for a signal on an object. Its prototype is

    - -
    void*
    -evas_object_smart_callback_del(Evas_Object* obj, const char* event, Evas_Smart_Cb func)
    -
    - -

    It removes the first match for the given event and callback and returns the data pointer that was used in the corresponding call to evas_object_smart_callback_add().

    - -

    Examples

    -

    Basic Usage: Button with a Callback on the "clicked" Signal

    -
    static void
    -_button_clicked(void *data __UNUSED__, Evas_Object *obj __UNUSED__, void *event_info __UNUSED__)
    -{
    -   fprintf(stdout, "Button clicked.\n");
    -   fflush(stdout);
    -   elm_exit();
    -}
    -
    -static void
    -_add_button(Evas_Object *window) 
    -{
    -   Evas_Object *button;
    -
    -   button = elm_button_add(window);
    -   elm_object_text_set(button, "Click Me To Exit!");
    -   evas_object_smart_callback_add(button, "clicked", _button_clicked, NULL);
    -
    -   evas_object_show(button);
    -}
    -
    - -

    Usage with evas_object_smart_callback_del(): Clicking on the Button Removes the Callback

    -
    static void
    -_button_clicked(void *data __UNUSED__, Evas_Object *obj, void *event_info __UNUSED__)
    -{
    -   fprintf(stdout, "Button clicked.\n");
    -   fflush(stdout);
    -   evas_object_smart_callback_del(obj, "clicked", _button_clicked);
    -}
    -
    -static void
    -_add_button(Evas_Object *window) 
    -{
    -   Evas_Object *button;
    -
    -   button = elm_button_add(window);
    -   elm_object_text_set(button, "Click Me!");
    -   evas_object_smart_callback_add(button, "clicked", _button_clicked, NULL);
    -
    -   evas_object_show(button);
    -}
    -
    - - - - -
    - -Go to top - - - - - - - \ No newline at end of file diff --git a/org.tizen.guides/html/native/ui/events_effects_n.htm b/org.tizen.guides/html/native/ui/events_effects_n.htm deleted file mode 100644 index 20da9b4..0000000 --- a/org.tizen.guides/html/native/ui/events_effects_n.htm +++ /dev/null @@ -1,124 +0,0 @@ - - - - - - - - - - - - - Event and Effect - - - - - -
    - -

    Event and Effect

    -

    Tizen allows you to manage different kinds of events and create various types of effects and animations in your application.

    -

    The main features of events and effects are:

    - - -

    Handling Events

    - -

    The EFLs rely on events and callbacks. In case of an event, (for example, a key press, mouse click or a battery running low), the mainloop calls the callback functions that are associated to that specific event. After the callbacks have finished, the mainloop takes over and waits for new events, upon which to trigger new callbacks.

    -

    It is important to do light work in the callbacks and to return to the mainloop relatively quickly. If there is heavy work to do, it is best to use an asynchronous mechanism like Ecore_con for network I/O or threads for CPU-intensive tasks. Failure to return quickly to the mainloop blocks the application's UI and it appears frozen.

    - -

    EFL Event Types

    -

    There are several event types in the EFLs, and their use depends on the level of the event. The event types from lower- to higher-level are:

    -
      -
    • Evas smart events are the most often used and take place on collections of evas objects (which are most typically handled). They are called "smart" because they have internal logic and can define their own events while other event types are fixed.
    • -
    • Ecore events are the lowest-level events and come directly from the system. Except for application-wide shortcuts, it is not advisable to use them.
    • -
    • Evas object events concern the objects that are on the canvas.
    • -
    • Evas events are events on the graphical canvas as a whole. They are fairly low-level and mostly useful when drawing directly on the canvas.
    • -
    - -

    Figure: Event types in the EFLs: Inner boxes are more specific than outer ones

    -

    Event types in the EFLs: Inner boxes are more specific than outer ones

    - - - - - - - - - - - - -
    Note
    There are also Edje signals, which come from program sections in themes; they can be used from high-level Elementary APIs or a low-level Edje API.
    - -

    Basic Event Flow

    -

    A realistic scenario involving various types of events is an application showing a button, which triggers the download of a file to be processed. There are progress bars for the operations.

    -

    Create the window, create a box, set it vertical and add a button and two progress bars. At first, only the button is fully visible.

    -

    When the user clicks on the button, an evas smart object event named "clicked" is emitted. The callback then starts the download in Ecore_con, displays the first progress bar and adds a callback to monitor the download progress. When the download progress changes, the callback updates the progress bar.

    -

    After the download is finished, the second progress bar is displayed and the file processing is offloaded to another thread through Ecore_thread. The processing function regularly updates the progress bar (wrapped in ecore_main_loop_thread_safe_call_async() because GUI operations are not thread-safe).

    -

    Events enable operations taking more than a few milliseconds' time to be executed outside of the mainloop, therefore not blocking UI redraws.

    -

    Below is an illustration for the event flow that follows a click on the screen.

    - -

    Figure: Event flow for a user click

    -

    Event flow for a user click

    - - -

    Creating Animations and Effects

    - -

    This programming guide introduces the animation functionalities provided by the EFL: Ecore animators, Elementary transitions, Edje animations, and Evas Map animations.

    - -

    The first option for creating animations with EFL is to use Ecore animators. To create an Ecore animation, you must first determine the duration of the animation, and then define a callback function that performs the animation with that duration.

    - -

    You can also create animations using Elementary transitions. Elementary transitions allow you to apply various transition effects, such as translation and rotation, to Evas objects. Elementary transitions are mostly based on Ecore animators, but provide some transition methods at a higher level of abstraction. Elementary transitions provide a simpler way of animating objects than Ecore animators or Edje animations.

    - -

    A third option for animating objects is to use Edje animations, which are based on a simple principle: transitioning from one state to another. To animate an object with Edje, you have to first define the start and end states of the animation, and then transition the object from the start state to the end state.

    - -

    Finally, Evas Map animations allow you to apply transformations to all types of objects by way of UV mapping. In UV mapping, you map points in the source object to 3D space positions in the target object. This allows for rotation, perspective, scale, and other transformation effects, depending on the map. In addition, each map point can carry a multiplier color, which, if properly calculated, can be used to apply 3D shading effects on the target object.

    - - - -
    - -Go to top - - - - - - - \ No newline at end of file diff --git a/org.tizen.guides/html/native/ui/font_setting_n.htm b/org.tizen.guides/html/native/ui/font_setting_n.htm deleted file mode 100644 index ce1efcb..0000000 --- a/org.tizen.guides/html/native/ui/font_setting_n.htm +++ /dev/null @@ -1,231 +0,0 @@ - - - - - - - - - - - - - Font Setting - - - - - -
    - -

    Font Setting

    - - -

    Tizen provides various methods for setting fonts of the application text. Basically, all UI components have a default font, which can be changed according to the system settings.

    - -

    The font handling methods include:

    - -
      -
    • Setting the font for a UI component using the Elementary Fonts API (in mobile and wearable applications)
    • -
    • Setting the font using EDC
    • -
    • Changing the font and text size using the Edje Class: Text API (in mobile and wearable applications) - -

      In the application, you can set a system-wide font and font size to text(textblock) parts with text classes (except tizen). When the system applies a new system-wide font and font size to the application, the font size of text(textblock) parts with the tizen text class are not affected.

      -

      The following words in the text_class definition are reserved for the system:

      - -
        -
      • button
      • -
      • label
      • -
      • entry
      • -
      • title_bar
      • -
      • list_item
      • -
      • grid_item
      • -
      • toolbar_item
      • -
      • menu_item
      • -
      • tizen
      • -
      - - -

      Set a specific ratio to a given font size for each object through the text class. If you give a negative value as font size, it is used as the percentage of the originally given font size. The following example code show set the font size as 150% of the given font size.

      -
      -elm_config_font_overlay_set("my_class", "TizenSans:style=Bold", -150);
      -elm_config_font_overlay_apply();
      -
      -
    • -
    - -

    Applying System Font Settings

    - -

    Tizen provides a special "Tizen" font name. The "Tizen" font name does not match with any specific font; it is just an alias for a system-defined font (system font). When you create a text(textblock) part with the "Tizen" font name in the application's EDC, the system font is loaded into the user application when those objects are created. Additionally, you can apply the system font to a text or textblock part by using the text class, as described above.

    - -

    The following EDC example shows how to apply the system font to a TEXT or TEXTBLOCK part by using the "Tizen" font name and the tizen text class. As font name is "Tizen" and the font size is set to 36, the system font is loaded in size 36. If the system setting changes, this part loads the new system font. However, its font size is not changed, because the text class is tizen.

    - -
    -description 
    -{
    -   text 
    -   {
    -      font: "Tizen:style=Regular";
    -      font_size: 36;
    -      text_class: "tizen";
    -   }
    -}
    - -

    If the part has a predefined text classes other than tizen, its font size is resized as well.

    - -
    -description 
    -{
    -   text 
    -   {
    -      font: "Tizen:style=Regular";
    -      font_size: 36;
    -      text_class: "label";
    -   }
    -}
    - - -

    Supported Font Styles

    -

    The font styles supported by the EFL are listed in the following table.

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Table: Supported font styles
    Font featureStyle attribute
    font_stylenormal
    oblique
    italic
    font_widthnormal
    ultracondensed
    extracondensed
    condensed
    semicondensed
    semiexpanded
    expanded
    extraexpanded
    ultraexpanded
    font_weightnormal
    thin
    ultralight
    light
    book
    medium
    semibold
    bold
    ultrabold
    black
    extrablack
    - -

    The style attributes are not case-sensitive (however, the font feature names are).

    -

    If you set the weight or width attribute to style=, it is processed to the right attribute.

    -
    -font=TizenSans:style=Bold // Textblock
    -"TizenSans:style=Bold"; // Text font
    -<font=TizenSans:style=Bold> // Markup tag
    -
    - -

    You can also use each attribute separately:

    - -
    -font=TizenSans font_style=Regular font_weight=Bold // Textblock
    -<font=TizenSans font_style=Regular font_weight=Bold> // Markup tag
    -
    - - - - -
    - -Go to top - - - - - - - \ No newline at end of file diff --git a/org.tizen.guides/html/native/ui/main_loop_n.htm b/org.tizen.guides/html/native/ui/main_loop_n.htm deleted file mode 100644 index f3980a9..0000000 --- a/org.tizen.guides/html/native/ui/main_loop_n.htm +++ /dev/null @@ -1,379 +0,0 @@ - - - - - - - - - - - - - Main Loop - - - - - -
    - -

    Main Loop

    - -

    The EFL is event-driven. This means that the application polls for data, and listens for events to interact with it.

    - -

    The Ecore library provides the main loop abstraction. It gets data when data is available and sends the events so that costly polling threads are not needed. Ecore manages polling, timers, events, and file descriptors. When there is no ongoing event, the main loop automatically enters an idle mode, minimizing the power consumption. The loop wakes up when needed.

    - -

    Timers

    - -

    Ecore provides timers, which schedule events that are executed later at a specific time. The event can occur once or several times at specific intervals.

    - -

    A timer callback prototype looks like the my_timed_cb() callback function. This function receives data from the application, and returns a Boolean value to specify whether it is called again or completed. The following macros are also provided:

    - -
      -
    • ECORE_CALLBACK_RENEW: the function is called again after the timeout.
    • -
    • ECORE_CALLBACK_CANCEL: the function is not called again, Ecore destroys automatically everything associated with the timer.
    • -
    - -

    To create and destroy a timer:

    - -
      -
    • To create a timer, use the ecore_timer_add() function. The interval, specified in seconds, indicates when the given function is called, and receives the specified data as a parameter. It returns an Ecore_Timer object. -

      In the following example, the my_timed_cb() function is run after 2 seconds and it receives my_data. It is renewed while its count variable value is under 5, and stops after that.

      -
      -Eina_Bool my_timed_cb(void *data)
      -{
      -   static int count = 0;
      -   count++;
      -
      -   if (count < 5) 
      -      return ECORE_CALLBACK_RENEW;
      -
      -   return ECORE_CALLBACK_CANCEL;
      -}
      -ecore_timer_add(2.0, my_timed_cb, my_data);
      -
      -
    • - -
    • To delete the timer, use the ecore_timer_del() function. The timer to delete must still be running, that is, it has not returned a false value. If the timer is not running, the function cannot be called.
    • -
    - -

    To manage a timer:

    -
      -
    • To change the timer's interval, use the ecore_timer_interval_set() function. The interval is specified in seconds. If set during a timer call, this affects the next interval. Use the ecore_timer_interval_get() function to get the timer's current interval.
    • - -
    • To get the timer's pending time, use the ecore_timer_pending_get() function.
    • - -
    • To delay the timer's next occurrence, use the ecore_timer_delay() function. The function adds the specified time to the current interval. It does not change the future occurrences' interval. You can also reset the current interval to its full value by using the ecore_timer_reset() function.
    • - -
    • To pause the currently running timer, use the ecore_timer_freeze() function. The remaining time is saved and used again when the timer is resumed with the ecore_timer_thaw() function.
    • - -
    • To query the current value of the defined timer infrastructure precision, use the ecore_timer_precision_get() function. A higher delay means that more timers can be run together. It diminishes the need to use system wake-ups and thus lowers the power consumption. -

      To set the precision, use the ecore_timer_precision_set() function. This sets the precision for all timers. For example, there are 2 timers, one that expires in 2.0 seconds and another that expires in 2.1 seconds. If the precision is set to 0.1 seconds, Ecore requests the next expiration to happen in 2.1 seconds and runs both callbacks at once, instead of one at 2.0 seconds and the other one 0.1 seconds later. However, if there is no timer expiring in 2.1 seconds, the timeout is at the minimum interval, 2 seconds.

    • -
    - -

    Animators

    - -

    Animators are a specific type of timer, specially designed for on-screen animation purposes:

    - -
      -
    • The time interval is usually known when they are created.
    • -
    • They are called at each screen refresh and their interval can vary. The interval can depend on the system load, the target power consumption, and other factors. The exact interval is not relevant.
    • -
    - -

    To implement animators, Ecore provides the Ecore animator subsystem.

    - -

    Forever-running Animator

    - -

    To create an animation that runs for an indefinite time:

    - -
    -Eina_Bool my_anim_cb(void *data)
    -{
    -   static int count = 0;
    -   count++;
    -   if (count < 5) 
    -      return ECORE_CALLBACK_RENEW;
    -
    -   return ECORE_CALLBACK_CANCEL;
    -}
    -ecore_animator_add(my_anim_cb, my_data);
    -
    - -

    This example looks the same as the one using an Ecore timer. The ecore_animator_add() function takes the callback function and data to pass to it, and returns an Ecore_Animator object. The function is called at a system-defined interval until it returns ECORE_CALLBACK_CANCEL instead of ECORE_CALLBACK_RENEW.

    - -

    Specific-duration Animator

    - -

    An animator callback for an animator running a specific time has a different prototype than the forever running animator.

    - -

    This callback function receives both data and a position which represents the current time among the full timeline, 0 meaning the beginning of the animation, and 1 meaning the end of the animation, returning ECORE_CALLBACK_CANCEL to abort, or ECORE_CALLBACK_RENEW to continue.

    - -

    To create and destroy the animator:

    -
      -
    • To create the animator, use the ecore_animator_timeline_add() function. The first parameter specifies the animator duration, the second parameter is the callback function, and the third parameter is the data to pass to the callback. The data parameter is optional. -
      -Eina_Bool my_anim_cb(void *data, double position)
      -{
      -   if (position < .5) 
      -      return ECORE_CALLBACK_RENEW;
      -
      -   return ECORE_CALLBACK_CANCEL;
      -}
      -ecore_animator_timeline_add(5., my_anim_cb, my_data);
      -
      - -

      In this example, the animator is specified to run for five seconds. The function returns ECORE_CALLBACK_CANCEL as soon as the position among the timeline passes half of the duration, 2.5 seconds.

      - -

      Ecore can generate a virtual position from the original one using ecore_animator_pos_map(position, map, v1, v2). Several maps are available:

      - -
        -
      • ECORE_POS_MAP_LINEAR: linear from 0.0 to 1.0.
      • -
      • ECORE_POS_MAP_ACCELERATE: start slow, then speed up.
      • -
      • ECORE_POS_MAP_DECELERATE: start fast, then slow down.
      • -
      • ECORE_POS_MAP_SINUSOIDAL: start slow, speed up, then slow down at the end.
      • -
      • ECORE_POS_MAP_ACCELERATE_FACTOR: start slow, then speed up, v1 being a power factor: 0.0 is linear, 1.0 is standard acceleration, 2.0 is a much more pronounced acceleration (squared), and 3.0 is cubed.
      • -
      • ECORE_POS_MAP_DECELERATE_FACTOR: start fast, then slow down, v1 being a power factor: 0.0 is linear, 1.0 is standard deceleration, 2.0 is a much more pronounced deceleration (squared), and 3.0 is cubed.
      • -
      • ECORE_POS_MAP_SINUSOIDAL_FACTOR: start slow, speed up, then slow down at the end, v1 being a power factor: 0.0 is linear, 1.0 is a standard sinusoidal, 2.0 is a much more pronounced sinusoidal (squared), and 3.0 is cubed.
      • -
      • ECORE_POS_MAP_DIVISOR_INTERP: start at gradient * v1, interpolated with the power of v2 curve.
      • -
      • ECORE_POS_MAP_BOUNCE: start at 0.0, then drop like a ball bouncing to the ground at 1.0, and bounce v2 times, with a decay factor of v1.
      • -
      • ECORE_POS_MAP_SPRING: start at 0.0, then wobble like a spring to the rest position 1.0, and wobble v2 times, with a decay factor of v1.
      • -
      - -

      Figure: Position maps

      -

      Position maps

      -
    • - -
    • To destroy the animator, use the ecore_animator_del() function. The animator to destroy must be running, that is, it has not returned a false value. If the animator is not running, the function cannot be called.
    • -
    - -

    To manage the animator:

    -
      -
    • To pause the currently running animator, use the ecore_animator_freeze() function. Note that time continues ticking even if the animator is frozen, and that resuming the animation using the ecore_animator_thaw() function does not actually resume, if the full runtime has been passed in the meanwhile.
    • - -
    • To query Ecore for the interval between 2 animator calls, use the ecore_animator_frametime_get() function.
    • - -
    • To change the interval, use the ecore_animator_frametime_set(interval) function. Note that too small a value causes performance and power consumption issues, and too high a value makes the animation jerky.
    • -
    - -

    File Descriptors

    - -

    Ecore provides an infrastructure to monitor file descriptors, so that files do not have to be blocked or polled to read or write on them. Instead, monitor sockets, pipes, or other streams are used to get a file descriptor.

    - -

    To manage the file descriptors:

    -
      -
    • To set a callback, use the _my_cb_func() function. Its first parameter is the data passed to it (optional), and the second one is the Ecore file descriptor handler. Its return value is, as in most Ecore callbacks, ECORE_CALLBACK_RENEW or ECORE_CALLBACK_CANCEL. It tells Ecore whether it wants to be called again or whether its treatment is finished.
    • - -
    • To listen to events, use the ecore_main_fd_handler_add() function.
    • - -
    • To wait for incoming data (that is, to read data) on the my_fd file descriptor, passing my_data: - -
      -Eina_Bool my_fd_cb(void *data, Ecore_Fd_Handler *handler)
      -{
      -   int fd;
      -   fd = ecore_main_fd_handler_fd_get(handler);
      -   count = read(fd, buf, sizeof(buf)); // This is guaranteed not to block
      -
      -   return ECORE_CALLBACK_RENEW;
      -}
      -ecore_main_fd_handler_add(my_fd, ECORE_FD_READ, my_fd_cb, my_data, NULL, NULL);
      -
      -
    • - -
    • To delete a file descriptor handler, use the ecore_main_fd_handler_del() function. This does not close the file descriptor. Always delete the handlers before closing the actual file descriptors.
    • - -
    • To get the handler's file descriptor, use the ecore_main_fd_handler_fd_get() function.
    • - -
    • To select whether a flag is active on a handler, use the ecore_main_fd_handler_active_get() function. For example, the handler is set to monitor both ECORE_FD_READ and ECORE_FD_ERROR. The following example finds out whether the function was called because of an error: - -
      -Eina_Bool my_fd_cb(void *data, Ecore_Fd_Handler *handler)
      -{
      -   int fd;
      -   fd = ecore_main_fd_handler_fd_get(handler);
      -   if (ecore_main_fd_handler_active_get(handler, ECORE_FD_ERROR) == EINA_TRUE) 
      -   {
      -      // We have an error!
      -
      -      return ECORE_CALLBACK_CANCEL;
      -   }
      -   count = read(fd, buf, sizeof(buf)); // This is guaranteed not to block
      -
      -   return ECORE_CALLBACK_RENEW;
      -}
      -ecore_main_fd_handler_add(my_fd, ECORE_FD_READ | ECORE_FD_ERROR, my_fd_cb, my_data, NULL, NULL);
      -
      -
    • - -
    • To change the flags the handler is monitoring, use the ecore_main_fd_handler_active_set() function.
    • -
    - -

    Threads

    - -

    EFL is not entirely thread-safe. This means that if a task is running in another thread and, for example, an Evas object shows the status progress of this task, the object cannot be updated from within the thread. Updating can only be done from the main thread that runs the main loop.

    - -

    Ecore provides a facility to perform tasks on separate worker threads. It is not a simple wrapper around standard threads provided by the operating system. With Ecore threads, it is easier to dispatch a worker function to perform some heavy tasks and get the result once it completes. It does not block the application UI. It is also easy to cancel and reschedule threads. Several threads can be launched simultaneously, since Ecore schedules them according to the number of processors the system has and the maximum amount of concurrent threads set for the application.

    - -

    Ecore has 2 kinds of threads:

    -
      -
    • Short jobs do not give any kind of information on their status to the parent. They are best used for short computing-intensive snippets of code.
    • -
    • Feedback jobs give information on their status to the parent. They are best used for longer snippets requiring a feedback loop, such as an ongoing file download.
    • -
    - -

    Ecore creates a pool of worker threads. The exact count is computed from the number of CPUs or cores, or it can be specified by the application itself.

    - -

    When a worker thread is idle, it picks a job to execute from the waiting list until there is none left. In the following example, there are 2 threads defined by my_short_job() and my_feedback_job(). Both threads take 2 parameters: some data passed to them, and the actual thread running. Call a callback when the jobs end, whether they are cancelled (my_job_cancel()) or end normally (my_job_end()).

    - -
    -struct feedback_msg
    -{
    -   int pos;
    -};
    -
    -void my_short_job(void *data, Ecore_Thread *thread)
    -{
    -   usleep(200000);
    -}
    -
    -void my_feedback_job(void *data, Ecore_Thread *thread)
    -{
    -   int i;
    -   for (i = 0; i < 100; i++) 
    -   {
    -      usleep(50000); // You can have some real computation done
    -      struct feedback_msg *message = malloc(sizeof(struct feedback_msg));
    -      if (message) 
    -      {
    -         message->pos = i;
    -         ecore_thread_feedback(thread, message);
    -      }
    -      if (ecore_thread_check(thread))
    -         return;
    -   }
    -}
    -
    -void my_feedback_job_notify(void *data, Ecore_Thread *thread, void *msg)
    -{
    -   struct feedback_msg *message = msg;
    -   free(message);
    -}
    -
    -void my_job_end(void *data, Ecore_Thread *thread)
    -{
    -   dlog_print(DLOG_INFO, LOG_TAG, "Thread has normally ended.\n");
    -}
    -
    -void my_job_cancel(void *data, Ecore_Thread *thread)
    -{
    -   dlog_print(DLOG_INFO, LOG_TAG, "Thread has been cancelled.\n");
    -}
    -
    -ecore_thread_run(my_short_job, my_job_end, my_job_cancel, my_data);
    -ecore_thread_feedback_run(my_feedback_job, my_feedback_job_notify, my_job_end, 
    -                          my_job_cancel, my_data, EINA_FALSE);
    -
    - -

    To manage threads:

    - -
      -
    • To cancel a thread, use the ecore_thread_cancel() function. However, note that this is done cooperatively: the thread continues to run until it exists. Call the ecore_thread_check() function regularly to check whether the thread has been marked for cancellation and exit if true.
    • - -
    • To run threads that are not accounted for in the worker thread pool, use the ecore_thread_feedback_run() function with the last parameter set to EINA_TRUE. - -

      The feedback message a thread sends as notification can be any kind of data. In the above example, it is a simple integer, but it can be as complex as needed.

      -
    • - -
    • To execute a thread later, use the ecore_thread_reschedule() function. This function is added to the end of the pending tasks.
    • - -
    • To get the maximum number of concurrent threads, use the ecore_thread_max_get() function. If needed, set it by using the ecore_thread_max_set() function, or reset the default value using the ecore_thread_max_reset() function.
    • - -
    • To query the number of active threads, use the ecore_thread_active_get() function. To query the number of available worker threads, use the ecore_thread_available_get() function, which is basically the same as the ecore_thread_max_get() - ecore_thread_active_get().
    • -
    - -

    Idlers

    - -

    When the rendering is done and all work is finished, the main loop enters its idle state until the next loop. You can get the functions of your application called back before the main loop enters or exits the idle state, or when it is in the idle state. They are respectively called Ecore_Idle_Enterer, Ecore_Idle_Exiter, and Ecore_Idler.

    - -

    Figure: Idle loop

    -

    Idle loop

    - -

    The idle enterers, exiters, and idlers all have the same prototype, my_idler(), which receives data and returns ECORE_CALLBACK_RENEW or ECORE_CALLBACK_CANCEL to tell Ecore whether it wants to be called again or is finished.

    - -

    To manage the idlers:

    -
      -
    • To add an idler, use the ecore_idler_add() function.
    • -
    • To delete an idler, use the ecore_idler_del() function.
    • - -
    • To add and delete idle exiters, use the ecore_idle_exiter_add() and ecore_idle_exiter_del() functions.
    • - -
    • To add and delete idle enterers, use the ecore_idle_enterer_add() and ecore_idle_enterer_del() functions. The ecore_idle_enterer_before_add() function is also available, if you want your function to be added at the top of the list so that it is called before the others.
    • -
    - -
    -Eina_Bool my_idle_enterer_cb(void *data)
    -{
    -   return ECORE_CALLBACK_RENEW;
    -}
    -
    -Eina_Bool my_idle_exiter_cb(void *data)
    -{
    -   return ECORE_CALLBACK_CANCEL;
    -}
    -
    -Eina_Bool my_idler(void *data)
    -{
    -   return ECORE_CALLBACK_RENEW;
    -}
    -
    -ecore_idle_enterer_add(my_idle_enterer_cb, my_data);
    -ecore_idle_exiter_add(my_idle_exiter_cb, my_data);
    -ecore_idler_add(my_idler_cb, my_data);
    -
    - - - -
    - -Go to top - - - - - - - \ No newline at end of file diff --git a/org.tizen.guides/html/native/ui/multiple_screens_n.htm b/org.tizen.guides/html/native/ui/multiple_screens_n.htm deleted file mode 100644 index 844439a..0000000 --- a/org.tizen.guides/html/native/ui/multiple_screens_n.htm +++ /dev/null @@ -1,264 +0,0 @@ - - - - - - - - - - - - - Multiple Screen Support - - - - - -
    - -

    Multiple Screen Support

    - -

    Tizen is available in various devices which support different screen sizes and resolutions. When developing Tizen applications, you must take this into account if you want your application to function well in various device models.

    -

    Before implementing multiple screen support, make sure you are familiar with the key concepts of multiple screen support.

    - -

    Key Concepts

    -

    Before building a native application for multiple resolutions using Tizen native UI framework, make sure you are familiar with the following concepts:

    - - -

    Multi-scale in Tizen Native UI Framework

    -

    Tizen native UI framework supports multiple scaling. If the application is implemented considering scalability, it is enough to change the elm_scale value in different device environments without modifying the application code.

    - -

    Scale 1.0 in Tizen native UI framework means that the application is displayed in a set size and is not scaled. Scale 1.0 is used in a display environment, such as a desktop. In the desktop environment, the monitor has a resolution between 1280 x 800 and 1920 x 1080, with a size between 20 and 27 inch, and the dpi between 80 and 100.

    - -

    If an application is scaled up or down after implementing it in a desktop environment, it can be used in another device without modifying the code. Each device has a proper scale value for adjusting the application size. Edje, which handles layout and themes in Tizen native UI framework, gets the size of an object by multiplying the size specified by an application using the scale value.

    - -

    The following figure illustrates a 50 px wide object in a 1280 px wide monitor. If the same object is displayed with not scaling in mobile environment, it looks very small. To show the object in mobile environment in the similar size as in the monitor, define the scale is 2.0, so that the object size is 100 px instead of 50 px.

    - -

    Figure: Scaling from desktop to mobile

    -

    Scaling from desktop to mobile

    - -

    Base Scale

    -

    The object scaling must be defined in the config.xml file of this application to show the application in a proper size in other devices. However, the scaling must be based on scale 1.0 or, if the application is based on another scale, this scale must be defined in the config.xml file. This predefined scale is called the "base scale".

    - -

    The size of a scalable object is multiplied with the device scale value, as illustrated in the following figure. If the scalable object (on the left) with the size 10 is created in a device with scale 1.0, the size of the object is 20 in a device with scale 2.0, and 40 in a device with scale 4.0.

    - -

    Figure: Base scale

    -

    Base scale

    - -

    The middle object has a base scale 2.0. The following example shows its scaling in a device with scale 4.0:

    - - - - - - - -
    Scale = Device scale (information in the target) / Base scale (information in the application) -

    For example: 2.0 = 4.0 / 2.0

    -
    - -

    You must declare the following values as base scale:

    -
      -
    • WVGA: 1.8
    • -
    • HD: 2.4
    • -
    - - - -

    Applying the Base Scale

    -

    To create an application that supports multiple screen sizes, you must learn how to set the base scale in:

    - - -

    Calculating the Base Scale

    - -

    To get the base scale value of your own display, you must know the DPI of the display. Based on the display DPI, you can calculate the base scale, since it is basically proportional to the display DPI with the following formula:

    - -
    -base_scale = (DPI / 90) * profile_factor
    - -

    The profile factor is the value for fitting the object size as a profile. The distance between the user eye and the display differs for each profile. This means that the object size must be different if the device display is changed.

    - -

    The following table lists the profile factors for various profiles.

    - - - - - - - - - - - - - - - - - - - - -
    Table: Profile factors
    ProfileProfile factor
    Wearable0.4
    Mobile0.7
    Desktop1.0
    - -

    For example, if your display has 233 dpi and the platform uses the mobile profile, the base scale is calculated like this:

    -
    -1.8 = (233 / 90) * 0.7
    - -

    The base scale of the device is 1.8. If the application is made in the environment using 233 dpi and mobile profile, its base scale must be set to 1.8. For a desktop, the DPI is 90, and its base scale is 1.0.

    - - -

    Setting the Base Scale in EDC

    -

    The application must specify the scale its base scale. The edje objects are scaled properly if the base scale is set in the collection of the edc file, as in the following example:

    - - - - - - - - -
    Note
    The base scale for WVGA is 1.8, and for HD application, 2.4.
    -
    collections 
    -{
    -   base_scale: 1.8; // This value is for WVGA application
    -   parts 
    -   {
    -      part 
    -      {
    -         name: "box"; 
    -         type: RECT;
    -         min: 100 100;
    -         scale: 1;
    -      }
    -   }
    -}
    -
    -

    Setting the Base Scale in C

    -

    The size of the object must be specified in EDC. However, sometimes it is better for an application to the object size in a C file. If the size is defined with no scaling in the C file, the application is displayed in the same size even if the scale changes. To avoid this, use the ELM_SCALE_SIZE macro, as in the following example:

    - -
    #define ELM_SCALE_SIZE(x) x / elm_app_base_scale_get() * elm_config_scale_get()
    - -

    in the definition, the size (x) is changed to a size based on 1.0 (x/elm_app_base_scale_get()) and it is multiplied with the scale of the current target (elm_config_scale_get()).

    - -

    Set the base scale using the elm_app_base_scale_set() function:

    - -
    int app_create(void *data)
    -{
    -   elm_app_base_scale_set(1.8); // This value is for WVGA application
    -}
    -
    -

    After setting the base scale, use the ELM_SCALE_SIZE macro to set the size of an object in the application:

    - -
    evas_object_size_hint_min_set(object, ELM_SCALE_SIZE(100), ELM_SCALE_SIZE(100));
    -evas_object_resize(object, ELM_SCALE_SIZE(50), ELM_SCALE_SIZE(50));
    -
    - -

    You can use ELM_SCALE_SIZE macro in any API related with setting objects sizes in Tizen native applications.

    - -

    Scaling without the Base Scale

    - -

    In Tizen, each device has a scale value in proportion to the display. If scaling is enabled, the objects are drawn on the display by multiplying with the user-defined object size and the device scale. If the base scale is set, the objects are drawn by dividing the user-defined object size with the base scale and multiplying it by the device scale.

    - -

    If you use the scale feature without setting the base scale, the result is the same as if you set the base scale to 1.0. Then you do not need to care about the base scale variables, because the pixels roll like a virtual pixel. For example, if you set 1 pixel in 129 dpi without setting the base scale value, the 1 pixel before scaling is equivalent to 1 real physical pixel after scaling. In case of 233 dpi, it is the same with 1.8 pixels after scaling.

    - -

    Always consider the pixel before scaling when defining the application UI, in order to ensure a proper UI display on the screen with a diversity of densities.

    - -
    int app_create(void *data)
    -[ Conversion Formula ]
    -Real physical pixel = (a pixel before scaling) x (dpi / 90) x 0.7
    -
    -

    Where 90 is the default DPI on a desktop and 0.7 is the mobile profile factor.

    - -

    The following table shows some examples.

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Table: Pixel conversions
    BaseLow-density device (such as WVGA)High-density device (such as HD)
    DPI129233306
    A pixel before scaling100100100
    Real physical pixel100180240
    Actual base scale1.01.82.4
    - - - - -
    - -Go to top - - - - - - - \ No newline at end of file diff --git a/org.tizen.guides/html/native/ui/preferences_n.htm b/org.tizen.guides/html/native/ui/preferences_n.htm deleted file mode 100644 index c665ef9..0000000 --- a/org.tizen.guides/html/native/ui/preferences_n.htm +++ /dev/null @@ -1,686 +0,0 @@ - - - - - - - - - - - - - UI Component Preferences - - - - - -
    - -

    UI Component Preferences

    - - - - - - - - - - -
    Note
    This feature is supported in mobile applications only.
    - -

    Customizing UI Components

    - - -

    Elementary UI components use the Edje library EDC themes to manage their look.

    - -

    Elementary Theme

    - -

    An Elementary theme is an Edje EDC file that contains groups composed of parts and programs. For more information about Edje, refer to the Edje guide.

    - -

    Use Theme Styles

    - -

    Elementary UI components provide a way to modify only some parts of the styles using the default theme. A style is a part of the EDC theme (a group) that concerns only one UI component. For example, you can create a new style for a button component to change its appearance without modifying the default theme.

    - - - - - - - - - - -
    Note
    When creating a new style, knowledge of how each UI component is themed is required, because setting another style always replaces the entire group used by the UI component. Important signals and parts must be there for the object to behave properly.
    - -

    When several styles are loaded in the current theme, you can set a different style to a specific UI component using the elm_object_style_set() function. It is also possible to see the current style with the elm_object_style_get() function.

    - -

    The default theme specifies several styles for the button component. The code below shows how to set the "anchor" style of a newly created button component.

    - -
    -Evas_Object *parent, *button;
    -
    -// Create a button object 
    -button = elm_button_add(parent);
    -
    -// Set its style to "anchor""
    -elm_object_style_set(button, "anchor");
    -
    - -

    Load Theme Styles

    - -

    Once written and compiled with Edje tools, the Elementary provides two methods to load the style in the application theme:

    -
      -
    • overlays
    • -
    • extensions
    • -
    - -

    When looking for a theme, the Elementary checks the list of overlays, if any are defined. Then it takes the default theme, and if it cannot find a theme for the UI component, it looks at the extensions list.

    - -
    Overlay
    - -

    An overlay can replace the look of all UI components by overriding the default style. If we create a new style called "default" for the button component and add it as an overlay, the Elementary uses the overlay for all button components overriding the default theme.

    - -

    Here is how to add an overlay to your application's theme.

    - -
    -elm_theme_overlay_add(NULL, "./theme_button.edj");
    -
    - - - - - - - - - - -
    Note
    Here we assume that the "theme_button.edj" file only contains a new theme for the button component.
    - - - - - - - - - - -
    Note
    Doing this is not recommended. Adding a file as an overlay makes the Elementary use the new theme for all the button components defined in the application. You must make sure that the "theme_button.edj" file reimplements everything that was previously defined in the default theme concerning the button component.
    - -

    This is how to remove the previously added overlay to return to the default theme.

    - -
    -elm_theme_overlay_del(NULL, "./theme_button.edj");
    -
    - -
    Extension
    - -

    With extensions, we can write styles that we can apply to some UI components (not all of them) by using the elm_object_style_set() function.

    - -

    The application adds a theme to the list of extensions with the following call.

    - -
    -elm_theme_extension_add(NULL, "./theme_button_style_custom.edj");
    -
    - - - - - - - - - - -
    Note
    Here we assume that the "theme_button_style_custom.edj" file contains a new button style called "custom".
    - -

    This is how to use the new "custom" style on a button component.

    - -
    -Evas_Object *parent, *button;
    -
    -// Create a button object 
    -button = elm_button_add(parent);
    -
    -// Set its style to "custom" 
    -elm_object_style_set(button, "custom");
    -
    - - - - - - - - - - -
    Note
    When using elm_theme_extension_add or elm_theme_overlay_add to add a new theme extension or overlay to a Theme object (here called the default theme), the Elementary calls the elm_theme_flush function to flush Elementary theme caches. Thus, the theme of all UI components that use the default theme is reloaded.
    - -

    Create a New Theme

    - -

    This is how to create a new theme object.

    - -
    -Elm_Theme *new_theme = elm_theme_new();
    -
    - -

    This function creates an empty specific theme that only uses the default theme. It has its own private set of extensions and overlays (which are empty by default). Specific themes do not fall back to the themes of parent objects. They are not intended for this use.

    - -

    This is how to apply this theme to a UI component and its children (a button, for example).

    - -
    -// Create a button component 
    -Evas_Object *button = elm_button_add();
    -
    -// Set the new theme to the button component 
    -elm_object_theme_set(button, new_theme);
    -
    - -

    Customizing a UI Component Style

    - -

    UI component themes are written in Edje EDC source files (.edc). These files are compiled with Edje tools to make an .edj file that is used by the application. For more information on using the EDC language, see the Edje guide.

    - -

    A new Edje style can be added for a UI component. The best way is to copy the existing "default" style, rename it, and update it to your needs.

    - -

    Create a Customized Style for the Check Component

    - -

    As an example, we show how to create a new style for the check component. The aim is to update the background and the main pictures of this UI component with custom pictures.

    - -

    The EDC source file concerning the check component (check.edc file) is composed of several groups.

    - -
    -group 
    -{
    -   name: "elm/check/base/default";
    -}
    -
    -group 
    -{
    -   name: "elm/check/base/toggle";
    -}
    -
    - -

    Those two groups define two different styles for the check component (the "default" style and the "toggle" style).

    - -

    We copy the group corresponding to the "default" style in a new file to create a new style called "custom". This new style is saved in the "check_custom.edc" file.

    - -
    -group 
    -{
    -   name: "elm/check/base/custom";
    -   // Here is the copy of the content of "default" style 
    -}
    -
    - -

    In the new group ("elm/check/base/custom"), we have to find the parts we want to modify. Here, the appropriate parts are "bg" and "check" parts.

    - -
    -part 
    -{
    -   name: "bg";
    -   mouse_events: 0;
    -   scale: 1;
    -   description 
    -   {
    -      state: "default" 0.0;
    -      rel1.offset: 1 1;
    -      rel2.relative: 0.0 1.0;
    -      rel2.offset: 1 -2;
    -      align: 0.0 0.5;
    -      min: 16 16;
    -      max: 16 16;
    -      aspect: 1.0 1.0;
    -      aspect_preference: VERTICAL;
    -      image 
    -      {
    -         normal: "check_base.png";
    -         border: 5 5 5 5;
    -         middle: 0;
    -      }
    -      fill.smooth: 0;
    -   }
    -}
    -part 
    -{
    -   name: "check";
    -   mouse_events: 0;
    -   scale: 1;
    -   description 
    -   { 
    -      state: "default" 0.0;
    -      rel1 
    -      {
    -         to: "bg";
    -         offset: 1 1;
    -      }
    -      rel2 
    -      {
    -         to: "bg";
    -         offset: -2 -2;
    -      }
    -      visible: 0;
    -      color: 255 255 255 255;
    -      image.normal: "check.png";
    -   }
    -   description 
    -   {
    -      state: "visible" 0.0;
    -      inherit: "default" 0.0;
    -      visible: 1;
    -   }
    -   description 
    -   {
    -      state: "disabled" 0.0;
    -      inherit: "default" 0.0;
    -      visible: 0;
    -      color: 128 128 128 128;
    -   }
    -   description 
    -   {
    -      state: "disabled_visible" 0.0;
    -      inherit: "default" 0.0;
    -      color: 128 128 128 128;
    -      visible: 1;
    -   }
    -}
    -
    - -

    We do not detail all the options that can be modified here, but assume that the user is familiar with Edje and knows Edje basics.

    - -

    Our custom pictures filenames are:

    -
      -
    • check_base_custom.png for the bg part
    • -
    • check_custom.png for the check part
    - -

    We must update the image.normal attribute in both parts with our custom pictures filenames to modify the pictures of this style.

    - -
    -part 
    -{
    -   name: "bg";   
    -   description 
    -   {
    -      state: "default" 0.0;
    -
    -      image 
    -      {
    -         normal: "check_base_custom.png";
    -         border: 5 5 5 5;
    -         middle: 0;
    -      }
    -                
    -   }
    -}
    -part 
    -{
    -   name: "check";
    -        
    -   description 
    -   {
    -      state: "default" 0.0;
    -            
    -      image.normal: "check_custom.png";
    -   }
    -        
    -}
    -
    - - - - - - - - - - -
    Note
    Here, we assume that the custom images are the same size as the "default" images.
    - -

    Add the Theme File to Your Project

    - -

    Once written, the check_custom.edc file is put in the /res/edje/. directory of the application project in the SDK.

    - -

    When building the application, the SDK calls the Edje tools automatically to build the final check_custom.edj file. This file can be loaded from our application.

    - -

    Use the New Style

    - -

    This is how to add the new theme file as an extension in the application.

    - -
    -char edj_path[PATH_MAX] = {0, };
    -
    -// Get the full path of the edj file 
    -app_get_resource("/edje/check_custom.edj", edj_path, (int)PATH_MAX);
    -
    -// Load check custom style as an extension 
    -elm_theme_extension_add(NULL, edj_path);
    -
    - -

    Use the "custom" style on a new check component.

    - -
    -Evas_Object *parent, *check;
    -
    -// Create a check object 
    -check = elm_check_add(parent);
    -
    -// Set its style to "custom" 
    -elm_object_style_set(check, "custom");
    -
    - -

    Special Theme Parts

    - -

    Some parts of the EDC file can be interacted with the Elementary. The content of parts of the type TEXT are modified using the elm_object_part_set_text() function. The content of SWALLOW parts is updated using the elm_object_part_content_set() function.

    - -
    Swallow Parts
    - -

    In the previous example (the check component "default" style), there is a part called "elm.swallow.content" that is of the type SWALLOW.

    - -
    -part 
    -{
    -   name: "elm.swallow.content";
    -   type: SWALLOW;
    -   scale: 1;
    -   description 
    -   {
    -      state: "default" 0.0;
    -      fixed: 1 0;
    -      visible: 0;
    -      align: 0.0 0.5;
    -      rel1.to_x: "bg";
    -      rel1.relative: 1.0 0.0;
    -      rel1.offset: 1 1;
    -      rel2.to_x: "bg";
    -      rel2.offset: 1 -2;
    -      rel2.relative: 1.0 1.0;
    -   }
    -   description
    -   {
    -      state: "visible" 0.0;
    -      inherit: "default" 0.0;
    -      fixed: 1 0;
    -      visible: 1;
    -      aspect: 1.0 1.0;
    -      min: 16 16;
    -   }
    -   description 
    -   {
    -      state: "disabled" 0.0;
    -      inherit: "default" 0.0;
    -      color: 255 255 255 128;
    -   }
    -   description 
    -   {
    -      state: "disabled_visible" 0.0;
    -      inherit: "default" 0.0;
    -      color: 255 255 255 128;
    -      fixed: 1 0;
    -      visible: 1;
    -      aspect: 1.0 1.0;
    -   }
    -}
    -
    - -

    We can push content (Evas_Object) to this part from the application anytime. The size and position of the content pushed is controlled by the EDC theme.

    - -
    -Evas_Object *parent, *check1, *content;
    -
    -// Create a check object 
    -check1 = elm_check_add(parent);
    -
    -// Set the content of the check object 
    -elm_object_part_content_set(check1, "elm.swallow.content", content);
    -
    - - - - - - - - - - -
    Note
    We can add new SWALLOW parts when customizing a UI component's style, if we want to be able to control more content from the application. Note that removing existing SWALLOW parts changes the UI component's behavior.
    - -
    Text Parts
    - -

    The same is done with parts of the type TEXT. The check "default" style contains a part named "elm.text".

    - -
    -part 
    -{
    -   name: "elm.text";
    -   type: TEXT;
    -   mouse_events: 0;
    -   scale: 1;
    -   description
    -   {
    -      state: "default" 0.0;
    -      visible: 0;
    -      rel1.to_x: "elm.swallow.content";
    -      rel1.relative: 1.0 0.0;
    -      rel1.offset: 1 1;
    -      rel2.relative: 1.0 1.0;
    -      rel2.offset: -2 -2;
    -      color: 0 0 0 255;
    -      text 
    -      {
    -         font: "Sans,Edje-Vera";
    -         size: 10;
    -         min: 0 1;
    -         align: -1.0 0.5;
    -      }
    -   }
    -   description
    -   {
    -      state: "visible" 0.0;
    -      inherit: "default" 0.0;
    -      visible: 1;
    -      text.min: 1 1;
    -   }
    -   description 
    -   {
    -      state: "disabled" 0.0;
    -      inherit: "default" 0.0;
    -      color: 0 0 0 128;
    -      color3: 0 0 0 0;
    -   }
    -   description
    -   {
    -      state: "disabled_visible" 0.0;
    -      inherit: "default" 0.0;
    -      color: 0 0 0 128;
    -      color3: 0 0 0 0;
    -      visible: 1;
    -      text.min: 1 1;
    -   }
    -}
    -
    - -

    This is how to modify the content of the "elm.text" part from the application. The position of the text, its size, color, look and feel are managed by the EDC theme.

    - -
    -Evas_Object *parent, *check2;
    -
    -// Create a check object 
    -check2 = elm_check_add(parent);
    -
    -// Set the text of the check object 
    -elm_object_part_text_set(check2, "elm.text", "Test text");
    -
    - -

    Managing UI Component Focus

    - -

    Focus Presentation

    - -

    Concept of Focus

    -

    Focus is a graphical user interface concept. A component, for example, a UI component, has a focus when it is selected to receive input from the user. The input can be an event, such as mouse button click or key press.

    - -

    Giving Focus

    - -

    Focusing can be immediate (selected by the touchscreen or mouse) or relative (selected by a key press).

    - -

    There are mainly two ways to set focus on a graphical elements:

    - -
      -
    • Direct selection: this is done by clicking on the element.
    • -
    • Relative selection: this is done by moving the selection from a UI component to another, such as going to the previous or next one; this is done with a keyboard.
    • -
    - -

    Direct selection does not really need any kind of special treatment as the user explicitly selects the UI component to interact with.

    - -

    Relative selection' default order is the one the UI components have been added to the canvas. That may not be appropriate, if they are added programmatically in different order than they appear on-screen.

    - -

    Moving Focus

    - -

    Concept of Focus Chain

    -

    The order the focus goes from a UI component to another is called the focus chain. As said before, the default focus chain is set to the order the UI components have been added to the canvas.

    - -

    Focusable Objects

    -

    An object can be focused if the following conditions apply:

    - -
      -
    • object is visible
    • -
    • object is enabled
    • -
    • object accepts focus
    • -
    • object's subtree (if any) is focusable
    • -
    • all of object's parents have their subtrees focusable
    • -
    - -

    If any of these conditions do not apply, the object is unfocusable.

    - -

    Handling Key Input

    - -

    Handling of the keys is done automatically by Elementary. According to which key the user pressed, Elementary switches the focus in the selected direction. For example, using the Tab key the focus goes to the next object in the natural order, whereas using the direction keys the focus goes to the next object in the requested direction.

    - -

    Hiding, Deleting or Disabling a Focused Object

    - -

    When a UI component is hidden, deleted, or disabled, it becomes unfocusable.

    - -

    When a focused object is unfocusable, the focus is moved to another object.

    - -

    Selecting Next Object

    - -

    When the user wants to switch the focus to the next object (i.e. cycle focus), Elementary searches the first object which is focusable.

    - -

    If there is a disabled or read-only object in the focus chain, the focus goes to the following object in the requested direction.

    - -

    Customizing Focus

    - -

    There are several reasons why to customize the focus chain of an application, for example:

    - -
      -
    • If you have created a form with labels and text entries next to them, the focus moves to the entry field when the user clicks on the associated label.
    • -
    • If you have created an interface with several columns (table), set the focus chain as you wish, for example, going horizontally instead of going vertically, regardless whatever the order the UI components are added.
    • -
    - -

    Customizing Object's Focus Exit Chain

    - -

    Set the object to focus after other object in a specific direction using elm_object_focus_next_object_set(object, next, direction). Use the following directions:

    - -
      -
    • ELM_FOCUS_NEXT: next UI component in natural order
    • -
    • ELM_FOCUS_PREVIOUS: previous UI component in natural order
    • -
    • ELM_FOCUS_UP: UI component to focus when going up
    • -
    • ELM_FOCUS_DOWN: UI component to focus when going down
    • -
    • ELM_FOCUS_RIGHT: UI component to focus when going right
    • -
    • ELM_FOCUS_LEFT: UI component to focus when going left
    • -
    - -

    Set the object next to another in a specific direction using elm_object_focus_next_object_get(object, direction).

    - -

    Customizing Whole Application's Focus Chain

    - -

    To customize the application's custom chain:

    - -
    -Evas_Object *main, obj1, obj2, obj3, obj4, obj5;
    -
    -Eina_List *focus_chain = NULL;
    -focus_chain = eina_list_append(focus_chain, obj3);
    -focus_chain = eina_list_append(focus_chain, obj2);
    -// The chain is obj3, then obj2. We set it.
    -elm_object_focus_custom_chain_set(main, focus_chain);
    -// Here we prepend obj5 at the beginning of the chain.
    -elm_object_focus_chain_prepend(main, NULL, obj5);
    -// We append obj1 after obj3.
    -elm_object_focus_chain_append(main, obj3, obj1);
    -// We prepend obj4 before obj1.
    -elm_object_focus_chain_prepend(main, obj1, obj4);
    -
    - -

    The focus chain is obj5, obj3, obj4, obj1, obj2.

    - -

    This actually applies to any container: it is possible to set the focus chain of, for example, a box.

    - -

    Customizing Collision of Both

    - -

    If an object is part of a focus chain and has the next focused object defined, the next object takes precedence over the focus chain.

    - -

    Following on the previous example, if obj4 has obj5 defined as its next object, the actual focus chain is obj5, obj3, obj4, and loop back to obj5.

    - -

    Focus on UI Component

    - -

    If your Evas object has several sub-objects, set its focus chain using the same functions as for the application. Elementary first follows the main focus chain, and then the focus chain of each UI component if applicable.

    - -

    Use elm_object_focus_get(object) to set whether a specific object has the focus. Set the focus to an object using elm_object_focus_set(object, set), where set is a Boolean value. If it is set to EINA_TRUE, the focus is set to that given object. If it is set to EINA_False, the focus is unset and passed back to the previous element in the focus chain. Set the focus only after the object is shown, that is, after evas_object_show(object) has been called. Call the function back when the object receives or loses focus by registering on smart event "focused" or "unfocused"

    - -

    Use elm_object_tree_focus_allow_set(object, focusable) to tell Elementary whether an object and its children are focusable, where focusable is a Boolean value. Get the current value using elm_object_tree_focus_allow_get(object).

    - -

    The similar functions for a specific object are elm_object_focus_allow_set(object, focusable) and elm_object_focus_allow_get(object).

    - - - -
    - -Go to top - - - - - - - \ No newline at end of file diff --git a/org.tizen.guides/html/native/ui/scalability_n.htm b/org.tizen.guides/html/native/ui/scalability_n.htm deleted file mode 100644 index dc46ecd..0000000 --- a/org.tizen.guides/html/native/ui/scalability_n.htm +++ /dev/null @@ -1,765 +0,0 @@ - - - - - - - - - - - - - Scalability Support - - - - - -
    - -

    Scalability Support

    -

    To ensure that your application works well in diverse devices, you must consider scalability when designing the application layout:

    - - -

    Key Concepts

    - -

    When designing the application layout to be scalable, you must pay attention to the following key concepts:

    - -
    • Understand the character of the relative position and the fixed position - -

      In the relative position, the size is determined in proportion to the size of the referred object. For example, if an orange rectangle occupies 30% of the green rectangle, and the green rectangle is expanded, the orange rectangle is expanded accordingly. However, if the scaling value is changed and the green rectangle is not scaled, the orange rectangle remains unchanged too.

      - -

      Figure: Relative position

      -

      Relative position

      - -

      In the fixed position, the size is determined by a value set for the object. For example, the orange rectangle set to the size of 10. If the green rectangle is expanded, the orange rectangle does not change. However, if the scaling value is, for example, doubled, the size of the orange rectangle grows to 20.

      - -

      Figure: Fixed position

      -

      Fixed position

    • - -
    • Use the relative position -

      If you set the object size as a percentage, the ratio remains fixed regardless of the changes in the screen size or resolution. If you want the object size changed in proportion of the window size, use the relative position.

      - -

      Figure: Scaling relative position

      -

      Scaling relative position

    • - -
    • Multiply the scaling value, if you use the fixed size -

      If you use the EDC file to set up the layout, you can set the scale in the part element:

      -
      -parts 
      -{
      -   part 
      -   { 
      -      name: "box"; 
      -      type: RECT;
      -      scale: 1;
      -   }
      -}
      -
      - -

      If you set the fixed size in C code, you can use the ELM_SCALE_SIZE macro:

      -
      evas_object_size_hint_min_set(object, ELM_SCALE_SIZE(100), ELM_SCALE_SIZE(100));
      - -

      For more information see Applying the Base Scale.

    • - -
    • Do not fill the width or height out with a fixed size only -

      If you fill the entire height out with a fixed size only and it is scaled, the end result can be larger than the screen size.

      - -

      Figure: Height filled with a fixed size

      -

      Height filled with a fixed size

      - -

      If you set a partial width or height with a fixed size and leave the remaining area flexible, the layout does not expand outside the screen.

      - -

      Figure: Height with a flexible area

      -

      Height with a flexible area

    - - - -

    Scalability Using Elementary UI Components

    - -

    The Tizen platform provides a UI component toolkit library, called Elementary, that includes an extensive set of UI components. You can use elementary UI components to compose your application user interface (UI). While creating the UI, you can set specific properties for the UI components to control the scalable behavior of the UI. Before you try to create a scalable UI using elementary UI components, make sure you understand the following core concepts on how scalability works with elementary UI components.

    - - - - - - - - - - -
    Note
    The Elementary library provides 3 groups of APIs: -
    • Infrastructure: to control the behavior of elementary.
    • -
    • Container: UI components that can contain other UI components.
    • -
    • UI components: elementary UI components, such as buttons, lists, and check and radio boxes.
    - -

    Using Containers for Effective Layouts

    - -

    The Elementary library provides several containers to display UI components in an effective layout. The containers have no visual identity of their own.

    - -
    • Box - -

      The box container makes a layout where child UI components are stacked in either horizontal or vertical direction. The box size is the sum of its child UI components' size:

      -
      • A vertical box calculates its height as the sum of its children's height and its width as the width of the widest child.
      • -
      • A horizontal box calculates its width as the sum of its children's width and its height as the height of the tallest child.
      - -

      Figure: Box layout

      -

      Box layout

      - -

      The box-based linear layout is the best solution to ensure a minimum size for the child UI components in any device or any orientation.

    • - -
    • Grid - -

      The grid container makes a layout where child UI components set their position and size relative to the container position and size. You can define the virtual width and height of the grid (by default: 100 x 100). You then packs the child UI components into the grid while setting their position and size based on the virtual size of the grid.

      - -

      Figure: Grid layout

      -

      Grid layout

      - -

      The grid-based relative layout can always fill the full screen in any device or any orientation. However, the size of the child UI components is changed based on the screen size.

    - - -

    Using Weight and Align Properties

    - -

    To make a layout scalable with UI components, the UI components must be packed into a container using only the weight and align properties based on their minimum size. Do not resize the UI components directly using pixels.

    - -

    The weight and align properties are associated with every elementary UI component, and they serve as hints for the container they are in. They tell the container how the UI component wants to occupy the space and pack itself with other UI components in the container.

    - -

    Weight

    - -

    You can set the weight property with the evas_object_size_hint_weight_set(x_weight, y_weight) function:

    - -
    • Containers use the weights of the child UI components by normalizing them across all child UI components along both X and Y directions.
    • -
    • The parameter values can be 0 or positive values (default: 0.0). -

      0.0 means that the container allocates a minimum size of the UI component area.

      -

      1.0 (EVAS_HINT_EXPAND) means that the container allocates all of the remaining area to the UI component.

    • -
    • If the container has several UI components, it allocates the UI component area relative to the weights of other UI components.
    - -

    Figure: Weight hint

    -

    Weight hint

    - -

    Figure: Weight hint across multiple child UI components

    -

    Weight hint across multiple child UI components

    - -

    Align

    - -

    You can set the align property with the evas_object_size_hint_align_set(x_align, y_align) function:

    - -
    • UI components use the alignment for their position or size along both X and Y directions.
    • -
    • The parameter values can be from 0.0 to 1.0 or -1.0 (default: 0.5).
    • -
    • The values define positions as follows: left is (x=0.0), right is (x=1.0), top is (y=0.0), and bottom is (y=1.0). The center is (x=0.5, y=0.5). -

      -1.0 (EVAS_HINT_FILL) means that the UI component fills all of the allocated area.

    - -

    Figure: Alignment hint

    -

    Alignment hint

    - -

    Scalability Using Edje

    - -

    The Tizen platform provides a complex graphical design and layout library called Edje, which provides an abstraction layer between the application code and the interface. You can use Edje in your Tizen applications to create visual elements and control the layout, look, and feel.

    -

    Internally, Edje holds a geometry state machine and a state graph that defines, for example, what is visible, where, at what size, and with what colors. These details are described to Edje using an Edje .edj file. The file can be produced by using Edje_cc to take a text file (a .edc file) and "compile" an output .edj file that contains the state graph information, images, and any other needed data.

    - -

    While creating Edje, you set specific element properties to control the scalable behavior of the UI. Before creating a scalable UI using Edje, you must be familiar with the following scalability properties and part types.

    - -

    Part

    -

    Parts are used to represent the most basic layout elements, such as a line in a border or a text on an image.

    -

    The parts can have the following property:

    -
    • scale: 0-1 -

      Specifies whether the part scales its size with the scaling factor (Tizen has a scaling factor to resize the application layout and object). This property is used to scale properties, such as font size or min/max size of the part.

      -

      The default value is 0 (off) and the default scaling factor is 1.0. To make a part scalable, set the property to 1 (on).

      -
    - -

    Description

    -

    Every part can have one or more description blocks to define the layout properties of the part.

    -

    The descriptions can have the following properties:

    - -
    • min/max: width height -

      Specifies the minimum or maximum size of the part in pixels. It has no effect on the container size.

      -

      When the scale property of the part is set to 1 (on), the size is multiplied by the scaling factor.

    • - -
    • fixed: 0-1 0-1 -

      When the min or max property is set, this property sets a boolean value for each dimension (horizontal and vertical, respectively) that tells the application whether it must be scaled when resized.

      -

      The default value is 0 0. To fix a part size to its min or max, set the value to 1.

    • - -
    • align: X-axis Y-axis -

      When the displayed object size is smaller than its container, this property moves it along both axes using the relative position.

      -

      To move the property, use x = 0.0 to move to left, x = 1.0 to move to right, y = 0.0 to move to the top, and y = 1.0 to move to the bottom. The x = 0.5, y = 0.5 value sets the object at the center of its container.

      -

      The default value is 0.5 0.5.

    • - -
    • rel1/rel2 -

      Specifies the position of the left-top and bottom-right corners of the part's container.

      -
      • relative: X-axis Y-axis -

        Specifies the relative position of the part's container.

        -

        The default value is 0.0 0.0 for rel1.relative and 1.0 1.0 for rel2.relative.

      • -
      • to/to_x/to_y -

        Specified that a corner must be positioned relatively to another part's container.

        -

        By default, the corners of a part are placed to the whole interface.

      - - - - - - - - -
      Table: Edje part property example
      -
      -collections 
      -{
      -   group 
      -   {
      -      name: "property_test";
      -                                                                 
      -      images 
      -      {
      -         image: "panorama.png" COMP;
      -      }  
      -                                                                 
      -      parts 
      -      {
      -         part 
      -         {
      -            name: "rect1";
      -            type: RECT;
      -            description 
      -            {
      -               state: "default" 0.0;
      -               rel1 {relative: 0.3 0.4;}
      -               rel2 {relative: 0.7 0.6;}
      -               color: 0 127 255 255;
      -            }
      -         }
      -         part 
      -         {
      -            name: "rect2";
      -            type: RECT;
      -            // Affected by scaling factor
      -            scale: 1; 
      -            description 
      -            {
      -               state: "default" 0.0;
      -               fixed: 0 1;
      -               // Height: 100 pixels (when the scaling factor is 1.0)
      -               min: 0 100;
      -               rel1 {relative: 0.0 1.0;}
      -               rel2 {relative: 1.0 1.0;}
      -               // Bottom-aligned
      -               align: 0.5 1.0;
      -               color: 255 127 0 255;
      -            }
      -         }
      -         part 
      -         {
      -            name: "image";
      -            // Affected by scaling factor
      -            scale: 1;
      -            description 
      -            {
      -               state: "default" 0.0;
      -               fixed: 1 1;
      -               // Image size: 720 x 180 pixels (when the scaling factor is 1.0)
      -               min: 720 180;
      -               // Y-axis is positioned relative to "rect2" part
      -               rel1 {relative: 0.5 0.0; to_y: "rect2";}
      -               rel2 {relative: 0.5 0.0; to_y: "rect2";}
      -               // Bottom-aligned
      -               align: 0.5 1.0;
      -               image.normal: "panorama.png";
      -            }
      -         }
      -      }
      -   }
      -}
      -

      Part example

      -
    • - -
    • aspect: min max -

      Specifies the width to height ratio to keep when the part is resized. When both values are the same, the ratio is fixed. When they differ, the part is forced to keep the ratio between the min and max properties when resized.

      -

      The default value is 0.0 0.0.

    • - -
    • aspect_preference: dimension -

      Specifies the scope of the aspect property to a given dimension.

      -

      The possible values are BOTH, VERTICAL, HORIZONTAL, and NONE. The default is NONE.

      - - - - - - - - -
      Table: Edje part property aspect example
      -
      -collections 
      -{
      -   group 
      -   {
      -      name: "property_test";
      -
      -      images 
      -      {
      -         image: "island.png" COMP;
      -      }
      -   
      -      parts 
      -      {
      -         part 
      -         {
      -            name: "image";
      -            description 
      -            {
      -               state: "default" 0.0;
      -               rel1 {relative: 0.0 0.0;}
      -               rel2 {relative: 1.0 1.0;}
      -               image.normal: "island.png";
      -               aspect: 8/5 8/5;
      -               // Keep the aspect ratio based on the part width
      -               aspect_preference: HORIZONTAL;
      -            }
      -         }
      -      }
      -   }
      -}
      -

      Part aspect example

      -
    - -

    Text

    -

    The text elements are used to display text on the screen.

    -

    The texts can have the following properties:

    - -
    • size: font-size -

      Specifies the font size for the text. When the scale property of the part is set to 1 (on), the size is multiplied by the scaling factor.

    • - -
    • min: horizontal vertical -

      Specifies a pair of boolean values that define whether the container can be reduced further than the text size. The property is used to prevent the container from chopping the text.

      -

      When min is set horizontally or vertically, the minimum height or width of the part is decided by the text size.

      -

      The default value is 0 0.

    • - -
    • max: horizontal vertical -

      Specifies a pair of boolean values that define whether the container can be expanded further than the text size.

      -

      When max is set horizontally or vertically, the maximum height or width of the part is decided by the text size.

      -

      The default value is 0 0.

      - - - - - - - - -
      Table: Edje text property example
      -
      -collections 
      -{
      -   group 
      -   {
      -      name: "property_test";
      -
      -      parts 
      -      {
      -         part 
      -         {
      -            name: "text";
      -            type: TEXT;
      -            scale: 1;
      -            description 
      -            {
      -               state: "default" 0.0;
      -               rel1 {relative: 0.0 0.0;}
      -               rel2 {relative: 1.0 0.0;}
      -               align: 0.5 0.0;
      -               color: 108 108 108 255;
      -               text 
      -               {
      -                  font: "TIZEN";
      -                  // Affected by scaling factor
      -                  size: 80;
      -                  // Minimum height of the part container is decided by the text size
      -                  min: 0 1;
      -                  text: "Test properties!!";
      -               }
      -            }
      -         }
      -      }
      -   }
      -}
      -

      Text example

      - -
    • -
    • fit: horizontal vertical -

      Specifies a pair of values that define whether the text is scaled to fill its container horizontally and/or vertically.

      -

      The default value is 0 0.

      - - - - - - - - -
      Table: Edje text property fit example
      -
      -collections 
      -{
      -   group 
      -   {
      -      name: "property_test";
      -
      -      parts 
      -      {
      -         part 
      -         {
      -            name: "text";
      -            type: TEXT;
      -            description 
      -            {
      -               state: "default" 0.0;
      -               rel1 {relative: 0.0 0.0;}
      -               rel2 {relative: 1.0 0.1;}
      -               color: 108 108 108 255;
      -               text 
      -               {
      -                  font: "TIZEN";
      -                  // Resize text to fill the container height
      -                  fit: 0 1;
      -                  text: "Test properties!!";
      -               }
      -            }
      -         }
      -      }
      -   }
      -}
      -

      Text fit example

    - - -

    Image

    -

    The image elements are used to display images on the screen.

    -

    The images can have the following properties:

    - -
    • border: left right top bottom -

      Specifies the border size of the image in pixels. This property sets the area of each side of the image to be displayed as a fixed size border, preventing the corners from being changed on a resize.

    • - -
    • border_scale -

      Specifies whether the border scales its size according to the scaling factor.

      -

      The default value is 0 (off). To make the border scalable, the value must be set to 1 (on).

      - - - - - - - - -
      Table: Edje image property example
      -
      -collections 
      -{
      -   group 
      -   {
      -      name: "property_test";
      -
      -      images 
      -      {
      -         image: "00_button_01_normal.png" COMP;
      -      }
      -
      -      parts 
      -      {
      -         part 
      -         {
      -            name: "image";
      -            description 
      -            {
      -               state: "default" 0.0;
      -               rel1 {relative: 0.0 0.6;}
      -               rel2 {relative: 1.0 0.7;}
      -               image.normal: "00_button_01_normal.png";
      -            }
      -         }
      -         part 
      -         {
      -            name: "ninepatch_image";
      -            description 
      -            {
      -               state: "default" 0.0;
      -               rel1 {relative: 0.0 0.8;}
      -               rel2 {relative: 1.0 0.9;}
      -               image 
      -               {
      -                  normal: "00_button_01_normal.png";
      -                  border: 4 4 0 0;
      -                  // Affected by scaling factor
      -                  border_scale: 1;
      -               }
      -            }
      -         }
      -      }
      -   }
      -}
      -

      Image example

      - -
    -

    Image Set

    -

    The image set elements are used to display a specific image on the screen based on the container size.

    -

    The image sets can have the following properties:

    - -
    • name: image-name -

      Specifies the name of the image file.

    • - -
    • size: minw minh maxw maxh -

      Specifies the minimum and maximum size that causes a specified image to be selected and shown.

      -

      The image set is used to control resource quality when the image part is scaled to multiple devices. According to the size of the part's container, an appropriate image is loaded.

      - - - - - - - - -
      Table: Edje image set property example
      -
      -collections 
      -{
      -   group 
      -   {
      -      name: "property_test";
      -
      -      images 
      -      {
      -         set 
      -         {
      -            name: "alternative_animal";
      -            image 
      -            {
      -               image: "pig.png" COMP;
      -               size: 640 800 1200 1500;
      -            }
      -            image 
      -            {
      -               image: "monkey.png" COMP;
      -               size: 400 500 639 799;
      -            }
      -            image 
      -            {
      -               image: "cat.png" COMP;
      -               size: 240 300 399 499;
      -            }
      -            image 
      -            {
      -               image: "mouse.png" COMP;
      -               size: 80 100 239 299;
      -            }
      -            image 
      -            {
      -               image: "snail.png" COMP;
      -               size: 0 0 79 99;
      -            }
      -         }
      -      }
      -
      -      parts 
      -      {
      -         part 
      -         {
      -            name: "image1";
      -            description 
      -            {
      -               state: "default" 0.0;
      -               rel1 {relative: 0.0 0.0;}
      -               rel2 {relative: 1.0 0.45;}
      -               image.normal: "alternative_animal";
      -               aspect: 4/5 4/5;
      -               aspect_preference: BOTH;
      -            }
      -         }
      -         part 
      -         {
      -            name: "image2";
      -            description 
      -            {
      -               state: "default" 0.0;
      -               rel1 {relative: 0.0 0.5;}
      -               rel2 {relative: 1.0 0.75;}
      -               image.normal: "alternative_animal";
      -               aspect: 4/5 4/5;
      -               aspect_preference: BOTH;
      -            }
      -         }
      -         part 
      -         {
      -            name: "image3";
      -            description 
      -            {
      -               state: "default" 0.0;
      -               rel1 {relative: 0.0 0.8;}
      -               rel2 {relative: 1.0 1.0;}
      -               image.normal: "alternative_animal";
      -               aspect: 4/5 4/5;
      -               aspect_preference: BOTH;
      -            }
      -         }
      -      }
      -   }
      -}
      -

      Image set example

      -
    - -

    Part Types

    -

    You can use fixed and flexible parts:

    - -
    • Fixed parts - -
      • Fixed parts have a minimum size (at least width or height).
      • -
      • When the part scale property is set to 1 (on), the scaling factor has an effect on the minimum size.
      • -
      • Fixed parts are used when the parts must keep a fixed size in any device or any orientation.
    • -
    • Flexible parts -
      • Flexible parts resize according to the container size and other fixed parts' size.
      • -
      • Flexible parts are used when the parts can be resized in any device or any orientation.
    - -

    Figure: Fixed and flexible parts

    -

    Fixed and flexible parts

    - - -

    Aspect Ratio

    - -

    In Tizen, the application generally fills out the screen. However, sometimes you want the application to be shown in a specific aspect ratio, regardless of the screen size.

    -

    As images are scaled in different devices, they are resized based on the container size. The images have specific properties that define the area to be shown when resized.

    - -

    For example, the following table illustrates what happens to the parts marked with yellow rectangles in the following figures, when scaling properties are applied.

    - -

    Figure: Original image [1920x1280 (8:5)]

    -

    Original image [1920x1280 (8:5)]

    - - - - - - - - - - - -
    Note
    To set the required aspect ratio, use the evas_object_size_hint_aspect_set() function or the aspect_preference attribute in the EDC.
    - - - -- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Table: Image resizing effects with a specific aspect ratio
    AspectContainer area
    720x384 (15:8)720x640 (9:8)
    HORIZONTAL -

    Resizing based on the container width while keeping the image aspect ratio.

    -

    Extra height goes outside the image area and is clipped.

    Scaling effect

    Scaling effect

    VERTICAL -

    Resizing based on the container height while keeping the image aspect ratio.

    -

    Extra width goes outside the image area and is clipped.

    Scaling effect

    Scaling effect

    BOTH -

    Resizing based on the container area while keeping the image aspect ratio.

    -

    No extra width or height goes outside the image area, so the entire image is always shown.

    Scaling effect

    Scaling effect

    NONE -

    Resizing to fill the available area while keeping the image aspect ratio.

    -

    Extra width or height goes outside the image area and is clipped.

    Scaling effect

    Scaling effect

    - -

    Setting the Image Aspect Ratio

    -

    In case of an image object, you can set its aspect ratio with additional APIs:

    - -
    • elm_image_fill_outside_set() -

      If the function is set to TRUE, the image resizes to fill the entire area while keeping its aspect ratio. It lets the extra width or height go outside of the area (same result as with the aspect NONE in the above table).

    • - -
    • elm_image_aspect_fixed_set() - -

      If the function is set to FALSE, the image resizes to fill the entire area without keeping its original aspect ratio. The image can be distorted to fit the area.

      - - - - - - - - - - - - - - -
      Table: Image resizing without keeping the aspect ratio
      Container area
      720x384 (15:8)720x640 (9:8)

      Scaling effect

      Scaling effect

      -
    - - - - - -
    - -Go to top - - - - - - - \ No newline at end of file diff --git a/org.tizen.guides/html/native/ui/styles_mn.htm b/org.tizen.guides/html/native/ui/styles_mn.htm deleted file mode 100644 index 6841480..0000000 --- a/org.tizen.guides/html/native/ui/styles_mn.htm +++ /dev/null @@ -1,928 +0,0 @@ - - - - - - - - - - - - - UI Component Styles - - - -
    -
    -

    Mobile native

    -
    - - -
    - -
    - -

    UI Component Styles

    - -

    For each winset, there are many styles supported in the native framework. Following the concept of the native framework in EFL, apply styles using the elm_object_style_set function.

    - - - - - - - - - - -
    Note
    This feature is supported in mobile applications only.
    - -

    The following tables list the styles for each winset, including the names of the styles, and the name of the part where to set text or some other Evas_Object in the UI component.

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Table: Button styles
    StyleSampleText partSwallow partNotes
    elm/button/base/default elm.textelm.swallow.content
    elm/button/base/anchorelm.textelm.swallow.content
    elm/button/base/bottomelm.textelm.swallow.contentThis style is used widely at the bottom of the screen.
    elm/button/base/circleelm.textelm.swallow.content
    elm/button/base/dropdownelm.text
    elm/button/base/hoversel_horizontal/defaultelm.textelm.swallow.content
    elm/button/base/hoversel_horizontal_entry/defaultelm.textelm.swallow.content
    elm/button/base/hoversel_vertical/defaultelm.textelm.swallow.content
    elm/button/base/hoversel_vertical_entry/defaultelm.textelm.swallow.content
    elm/button/base/icon_reorder
    elm/button/base/naviframe/drawers
    elm/button/base/naviframe/title_cancel
    elm/button/base/naviframe/title_done
    elm/button/base/option
    - - - --- - - - - - - - - - - - - - - - - - -
    Table: Check styles
    StyleSample
    elm/check/base/default
    elm/check/base/favorite
    elm/check/base/on&off
    - - - - - - - - - - - - - - - -
    Table: Colorselector styles
    StyleSampleNotes
    elm/colorselector/item/color/colorplaneUse the following command: elm_colorselector_mode_set(colorselector, ELM_COLORSELECTOR_PALETTE);
    - - - - - - - - - - - - - - - - - -
    Table: Progressbar styles
    StyleSample
    default
    wheel
    - - - --- - - - - - - - - - -
    Table: Radio styles
    StyleSample
    default
    - - - - - - - - - - - - - - - - - -
    Table: List styles
    StyleSampleText partSwallow part
    defaultelm.textelm.swallow.icon: for the icon on the left. -

    elm.swallow.end: for the icon on the right.

    - - - - - - - - - - - - - - - - - -
    Table: Multi Button Entry styles
    StyleSampleText partNotes
    elm/multibuttonentry/base/defaultelm.text, guideThe guide text part is used when there is no item in the Multi Button Entry. It is removed automatically when an item is appended in the Multi Button Entry.
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Table: Toolbar styles
    StyleSampleText partSwallow partNotes
    elm/toolbar/base/default
    elm/toolbar/base/navigationbar
    elm/toolbar/base/tabbar_with_title
    elm/toolbar/item/defaultelm.textelm.swallow.iconThis style is for the toolbar's item. Check the elm_toolbar_item_append() function to set the text and the icon.
    elm/toolbar/item/navigationbarelm.textThis style is for the toolbar's item. Check the elm_toolbar_item_append() function to set the text and the icon.
    - - - --- - - - - - - - - - -
    Table: Flipselector styles
    StyleSample
    default
    - -

    The style of the genlist's item is not set by external APIs. Check the guide of Genlist to check how to use the item class to set the item's style.

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Table: Genlist styles
    StyleSampleText partSwallow partNotes
    defaultelm.textelm.swallow.icon: for the icon on the left. -

    elm.swallow.end: for the icon on the right.

    default_styleelm.textelm.swallow.icon: for the icon on the left. -

    elm.swallow.end: for the icon on the right.

    double_labelelm.text: for the main text. -

    elm.text.sub: for the sub text.

    elm.swallow.icon: for the icon on the left. -

    elm.swallow.end: for the icon on the right.

    end_iconelm.textelm.swallow.icon
    fullelm.swallow.contentThe swallow part is the full size of the item. There is no padding in the item.
    group_indexelm.textelm.swallow.icon: for the icon on the left. -

    elm.swallow.end: for the icon on the right.

    one_iconelm.textelm.swallow.icon
    messageelm.text: for the text on the top. -

    elm.title.1: for the text in the middle.

    -

    elm.title.2: for the text on the bottom.

    - -

    The style of the gengrid's item is not set by external APIs. For more information on using the item class to set the item's style, see the guide of gengrid.

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Table: Gengrid styles
    StyleSampleText partSwallow partNotes
    defaultelm.swallow.icon
    album-previewelm.textelm.swallow.icon
    blockThis style is used to show an empty area.
    group_indexelm.textelm.swallow.icon
    default_gridelm.swallow.icon
    default_gridtext2elm.textelm.swallow.icon
    default_gridtextelm.textelm.swallow.icon
    default_styleelm.textelm.swallow.icon
    - - - - - - - - - - - - - -
    Table: Segmentation Control styles
    StyleSample
    default
    - - - - - - - - - - - - - - - - - - - - - - - - - -
    Table: Index styles
    StyleSampleNotes
    defaultThis style is for supporting the vertical style.
    defaultThis style is for supporting the horizontal style. To set a horizontal index, use the elm_index_horizontal_set.
    pagecontrolThis style is used for the "page control" layout. For more information, refer to the Core Control sample application.
    - - - - - - - - - - - - - - - - - - - - - - - - - -
    Table: Contextual Popup (Ctxpopup) styles
    StyleSampleNotes
    default
    dropdown/listThe size of the item and the ctxpopup follow the size of the screen.
    dropdown/labelThe size of the item and the ctxpopup follow the maximum length of the item.
    - - - --- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Table: Icon styles
    StyleSample
    apps
    arrow_down
    arrow_left
    arrow_right
    arrow_up
    chat
    clock
    close
    delete
    edit
    file
    home
    media_player/forward
    media_player/info
    media_player/next
    media_player/pause
    media_player/play
    media_player/prev
    media_player/rewind
    media_player/stop
    menu/apps
    menu/arrow_down
    menu/arrow_left
    menu/arrow_right
    menu/arrow_up
    menu/chat
    menu/clock
    menu/close
    menu/delete
    menu/edit
    menu/file
    menu/folder
    menu/home
    menu/refresh
    no_photo
    photo/no_photo
    refresh
    toolbar/apps
    toolbar/arrow_down
    toolbar/arrow_left
    toolbar/arrow_right
    toolbar/arrow_up
    toolbar/chat
    toolbar/clock
    toolbar/close
    toolbar/delete
    toolbar/edit
    toolbar/file
    toolbar/folder
    toolbar/home
    toolbar/more_menu
    toolbar/refresh
    - - - - - - - - - - - - - - - - - - - -
    Table: Entry styles
    StyleSampleText partSwallow partNotes
    defaultelm.guide: for the guide text. -

    elm.text: for the main text.

    The guide text is automatically erased when the main text is entered.
    - - - --- - - - - - - - - - - - - - - - - - -
    Table: Datetime styles
    StyleSample
    date_layout
    time_layout
    time_layout_24hr
    - - - - - - - - - - - - - - - - - -
    Table: Panel (drawer) styles
    StyleSampleSwallow partNotes
    defaultelm.swallow.contentFor more information on the drawer, see the [UI Sample] Core Control guide.
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Table: Slider styles
    StyleSampleSwallow part
    horizontal/defaultelm.swallow.icon
    horizontal/center_pointelm.swallow.icon
    vertical/center_point
    vertical/default
    - - - --- - - - - - - - - - - - - - -
    Table: Popup styles
    StyleSample
    default
    toast
    - - - --- - - - - - - - - - - - - - -
    Table: Spinner styles
    StyleSample
    base/horizontal
    base/vertical
    - - - -
    - -Go to top - - - - - - - \ No newline at end of file diff --git a/org.tizen.guides/html/native/ui/styles_wn.htm b/org.tizen.guides/html/native/ui/styles_wn.htm deleted file mode 100644 index 80b54eb..0000000 --- a/org.tizen.guides/html/native/ui/styles_wn.htm +++ /dev/null @@ -1,659 +0,0 @@ - - - - - - - - - - - - - UI Component Styles - - - -
    -
    -

    Wearable native

    -
    - - -
    - -
    - -

    UI Component Styles

    - - -

    For each winset, there are many styles supported in the native framework. Following the concept of the native framework in EFL, apply styles using the elm_object_style_set function.

    - - - - - - - - - - -
    Note
    This feature is supported in wearable applications only.
    - - -

    The following tables list the styles for each winset, including the names of the styles, and the name of the part where to set text or some other Evas_Object in the UI component.

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Table: Button styles (wearable core)
    StyleSampleText partSwallow partNotes
    default elm.textelm.swallow.content
    greenelm.textelm.swallow.content
    orangeelm.textelm.swallow.content
    redelm.textelm.swallow.content
    nextdepth
    naviframe/title_iconelm.swallow.contentThe icon can be set with the elm_object_part_content_set(btn, "icon", ic) function.
    - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Table: Button styles (Gear O)
    StyleSampleText partSwallow partNotes
    default elm.textelm.swallow.content
    bottomelm.textelm.swallow.content
    - - - --- - - - - - - - - - - - - - -
    Table: Check styles (wearable core)
    StyleSample
    default
    on&off
    - - - --- - - - - - - - - - - - - - - - - - -
    Table: Check styles (Gear O)
    StyleSample
    default
    small
    on&off
    - - - - - - - - - - - - - - - -
    Table: Contextual popup (Ctxpopup) styles (wearable core)
    StyleSampleNotes
    defaultUse the elm_ctxpopup_item_append() function to add both text and an icon to the list.
    - - - - - - - - - - - - - - - - - - - - - - - - - -
    Table: Contextual popup (Ctxpopup) styles (Gear O)
    StyleSampleNotes
    select_mode
    select_mode/topPair this style with select_mode/bottom.
    select_mode/bottomPair this style with select_mode/top.
    - - - --- - - - - - - - - - - - - - -
    Table: Datetime styles (wearable core)
    StyleSample
    datepicker_layout
    timepicker_layout
    - - - --- - - - - - - - - - - - - - -
    Table: Datetime styles (Gear O)
    StyleSample
    datepicker/circle
    timepicker/circle
    - - - - - - - - - - - - - - - - - - - -
    Table: Entry styles
    StyleSampleText partSwallow partNotes
    defaultelm.guide: for the guide text. -

    elm.text: for the main text.

    The guide text is automatically erased when the main text is entered.
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Table: Genlist styles (wearable core)
    StyleSampleText partSwallow partNotes
    defaultelm.textelm.swallow.icon: for the icon on the left. -

    elm.swallow.end: for the icon on the right.

    group_indexelm.text: for the main text. -

    elm.text.1: for the sub text.

    elm.icon
    1textelm.text
    1text.1iconelm.textelm.icon
    2textelm.text: for the main text. -

    elm.text.1: for the sub text.

    2text.1elm.text: for the main text. -

    elm.text.1: for the sub text.

    1text.1icon.dividerelm.textelm.icon: for the icon. -

    elm.divider: for the icon divider.

    1text.1icon.1elm.textelm.icon
    2text.1icon.1elm.text: for the main text. -

    elm.text.1: for the sub text.

    elm.icon
    multiline/1textelm.text: for the multi-line text.
    multiline/2textelm.text: for the main text. -

    elm.text.1: for the multi-line sub text.

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Table: Genlist styles (Gear O)
    StyleSampleText partSwallow partNotes
    defaultelm.textelm.swallow.icon: for the icon on the left. -

    elm.swallow.end: for the icon on the right.

    titleelm.text
    groupindexelm.text
    1textelm.text
    1text.1iconelm.textelm.icon
    2textelm.text: for the main text. -

    elm.text.1: for the sub text.

    1text.1icon.dividerelm.textelm.icon: for the icon. -

    elm.divider: for the icon divider.

    1text.1icon.1elm.textelm.icon
    2text.1icon.1elm.text: for the main text. -

    elm.text.1: for the sub text.

    elm.icon
    editfieldelm.text
    - - - - - - - - - - - - - - - - - -
    Table: Index styles (wearable core)
    StyleSample
    thumbnail
    tab
    - - - - - - - - - - - - - - - - - -
    Table: Index styles (Gear O)
    StyleSample
    thumbnail
    circle
    - - - --- - - - - - - - - - - - - - -
    Table: Popup styles (wearable core)
    StyleSample
    default
    toast
    - - - --- - - - - - - - - - - - - - -
    Table: Popup styles (Gear O)
    StyleSample
    circle
    toast/circle
    - - - - - - - - - - - - - - - - - - - - - - - - - -
    Table: Progressbar styles (wearable core)
    StyleSample
    default
    pending_list
    process
    process/groupindex
    - - - - - - - - - - - - - - - - - -
    Table: Progressbar styles (Gear O)
    StyleSample
    process
    process/small
    - - - --- - - - - - - - - - -
    Table: Radio styles (wearable core)
    StyleSample
    default
    - - - --- - - - - - - - - - -
    Table: Radio styles (Gear O)
    StyleSample
    default
    - - - - - - - - - - - - - - - - -
    Table: Slider styles
    StyleSampleSwallow part
    horizontal/defaultelm.swallow.icon
    - - - - -
    - -Go to top - - - - - - - \ No newline at end of file diff --git a/org.tizen.guides/html/native/ui/threads_n.htm b/org.tizen.guides/html/native/ui/threads_n.htm deleted file mode 100644 index d28ca10..0000000 --- a/org.tizen.guides/html/native/ui/threads_n.htm +++ /dev/null @@ -1,499 +0,0 @@ - - - - - - - - - - - - - Thread Usage - - - - - -
    - -

    Thread Usage

    - -

    Threads are concurrent execution environments that are lighter than full-blown processes because they share some operating system resources. Threads make it possible to do several things at the same time while using less resources and offering simpler synchronization and data exchange compared to processes.

    - -

    If you move a blocking operation to a separate thread, it cannot block the event loop and keeps the user interface reactive. Blocking the event loop and using long-running callbacks means the application cannot update its graphical user interface.

    - -

    While threads can be useful, they are not always the best choice:

    - -
    • The first rule to using threads is to avoid them as much as possible, as there are often better tools and approaches. For example, to do network transfers, use Ecore_Con that integrates with the event loop to use a function based on callbacks. Being able to use such a function means that specific support work has been done in libraries. In some cases, using a function and libraries is impossible, and in those situations threads are required.
    • -
    • Use threads in CPU-intensive tasks and disk IOs. For example, a thread is the appropriate way to apply filters to an image or to a video without blocking the interface.
    • -
    • Use threads to take advantage of multiple available CPU cores, if the workload can be split into several units of work and spread across the cores. A typical example for an image processing application on a quad-core CPU is to process 4 images at once, each on 1 thread. For such tasks, the thread pool helps with the creation and scheduling of the threads, handling all the grunt work.
    - -

    Thread Safety

    - -

    If several strings have to work on the same resources, conflicts can happen as the threads are run in parallel. For example, if thread A modifies several values while thread B is reading them, it is likely that some of the values read by B are outdated. Similar issues can happen if both threads are modifying data concurrently.

    - -

    These kinds of conflicts are called race-conditions: depending on which thread is faster, the output changes and can be incorrect. Avoiding such issues is called thread safety. Thread safety involves critical sections, which are blocks of code that operate on shared resources and must not be accessed concurrently by another thread.

    - -

    The usual solution for ensuring exclusive access to shared resources is mutual exclusion: only 1 thread can operate on the data at any given time. Mutual exclusion is often implemented through locks. Before attempting to operate on a shared resource, the thread waits until it can lock something called a mutex (stands for mutual exclusion), then operates on the resource, and unlocks the mutex. Operating systems guarantee that only 1 thread can lock a mutex at a given time: this ensures that only 1 thread operates on the shared resource at one time.

    - -

    For more information on thread safety, see Low-level Functions.

    - -

    Thread Pools

    - -

    Threads are operating system resources: while much lighter than processes, they still have a cost. Moreover, spawning a thousand threads means that each of them only gets 1/1000th of the total CPU time: each thread is progressed slowly and, in the worst case, the system wastes all of its time switching between threads without doing any actual work.

    - -

    Thread pools solve this problem. In thread pools, upto a maximum number of threads are created on-demand and used to execute tasks. When the tasks are finished, they are kept alive but sleeping. This avoids the cost of creating and destroying them.

    - -

    In EFL, the thread pool is controlled by a thread_max parameter, which defines the maximum number of threads running at the same time. Another control feature is the func_end() callback that runs from the main loop thread after a task has completed and is typically used to extract the data from the finished task and make it available to the main loop.

    - -

    To manage the maximum number of threads:

    - -
      -
    • To retrieve the current value, use the ecore_thread_max_get() function. -
    • - -
    • To set the value, use the ecore_thread_max_set() function. The value has a maximum of 16 times the CPU count. -
    • - -
    • To reset the maximum number of threads, use the ecore_thread_max_reset() function. - -
    • - -
    • To get the number of available threads in the pool, use the ecore_thread_available_get() function. The function returns the current maximum number of threads minus the number of running threads. The number can be a negative value, if the maximum number of threads has been lowered. -
    • -
    - -

    The following figures illustrate the thread pool. The first figure shows the occupancy of a hypothetical thread pool. There are several tasks, of which 4 are running. The thread_max parameter of the pool is 4, and the other tasks are waiting. There is no thread with its func_end() callback currently called.

    - -

    Figure: Thread pool, step 1

    -

    Thread pool, step 1

    - -

    When a task, applying the sepia filter on image1, finishes, the corresponding func_end() function is invoked from the main loop.

    - -

    Figure: Thread pool, step 2

    -

    Thread pool, step 2

    - -

    With the task done, one of the threads from the pool becomes available, and another thread, adding the reverberation effect on audio3, can run in it.

    - -

    Figure: Thread pool, step 3

    -

    Thread pool, step 3

    - -

    As long as there are tasks to be done, the thread pool continues the same way, running tasks in its threads whenever a thread is available.

    - - -

    Thread Management with Ecore

    - -

    Ecore offers a simplified API for managing threads in EFL applications. The Ecore API applies to a typical scenario where the main thread creates another thread, which in turn sends data back to the main thread or calls GUI-related functions. GUI-related functions are not thread-safe.

    - -

    Creating Threads with Ecore

    - -

    The threads created with Ecore are by default integrated with the thread pool and offer simple callback-based ways to interact with the main loop. New threads are created as needed until the maximum capacity of the thread pool is reached.

    - -
    • To return values to the main thread: -

      Use the ecore_thread_feedback_run() function to send intermediate feedback from the thread to the main loop.

    • - -
    • To return only the final value to the main thread: -

      To create and run a thread, use the ecore_thread_run() function. It runs a function inside a thread from the thread pool and takes care of all the low-level work. It returns the corresponding thread handler or NULL on failure.

      - -

      The most common way to return data from one thread to the main thread is to put a pointer to it in the data. When the thread is aborted or finishes, either func_cancel() or func_end() is called from the main loop. The functions are running in the simpler context of a single thread running at once and therefore avoid race-conditions.

      - -

      The data pointer approach can only be used when the data is shared between the one thread and the main thread only. However, this does not prevent you from using the func_end() callback to merge the results into a single data structure. For example, you can add all the values computed by the threads to an Eina_List, as all the operations on the list happen from a single thread and therefore one after the other and not concurrently.

    - - -

    Running Callbacks from the Main Loop

    - -

    If you are performing operations in another thread and want to update a progress bar, the update operation must be done from the main thread. The simplest way is to use the ecore_main_loop_thread_safe_call_async() function, which takes a function and some data as parameters and instructs the main loop to execute the given function with the given data.

    - -

    Depending on the kind of thread the function is called from, the process differs:

    -
      -
    • If the function is called from a thread that is not the main one, the function sends a message to the main loop and returns quickly. The message is processed in order, similarly to others.
    • - -
    • If the function is called from the main thread, the function is called immediately as if it were a direct call.
    • -
    - -

    If you want to wait until the callback is called and returns, use the ecore_main_loop_thread_safe_call_sync() function, which is similar but synchronous. Since it is synchronous, it can also return the value returned by the callback.

    - -

    Low-level Functions

    - -

    Eina offers low-level functions that are portable across the operating system, such as locks, conditions, semaphores, barriers, and spinlocks. The functions follow closely the logic of pthreads.

    - -

    While these functions are useful, they are building blocks and not usually useful in EFL applications considering the higher-level functions that are available in Ecore.

    - -

    For an introduction to threads and pthreads in particular, see:

    - - - -

    If you are already familiar with threads, see the standard pthreads documentation and the Eina reference documentation, or the following function lists. Remember that the Eina functions map very closely to the pthreads functions.

    - - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Locks (mutual exclusions)
    pthreads functionEina equivalent
    pthread_mutex_new()eina_lock_new()
    pthread_mutex_destroy()eina_lock_free()
    pthread_mutex_lock()eina_lock_take()
    pthread_mutex_trylock()eina_lock_take_try()
    pthread_mutex_unlock()eina_lock_release()
    none (prints debug information on the lock)eina_lock_debug()
    - - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Conditions (notifications when condition objects change)
    pthreads functionEina equivalent
    pthread_cond_init()eina_condition_new()
    pthread_cond_destroy eina_condition_free()
    pthread_cond_wait()eina_condition_wait()
    pthread_cond_timedwait()eina_condition_timedwait()
    pthread_cond_broadcast()eina_condition_broadcast()
    pthread_cond_signal()eina_condition_signal()
    - - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - -
    RWLocks (Read-write locks, for multiple-readers/single-writer scenarios)
    pthreads functionEina equivalent
    pthread_rwlock_init() -eina_rwlock_new()
    pthread_rwlock_destroy()eina_rwlock_free()
    pthread_rwlock_rwlock_rdlock() -eina_rwlock_take_read()
    pthread_rwlock_rwlock_wrlock() -eina_rwlock_take_write()
    pthread_rwlock_unlock() -eina_rwlock_release()
    - - - ---- - - - - - - - - - - - - - - - - - - - - - - -
    TLS (Thread-Local Storage)
    pthreads functionEina equivalent
    pthread_key_create()eina_tls_new()
    pthread_key_delete()eina_tls_free()
    pthread_getspecific()eina_tls_get()
    pthread_setspecificeina_tls_set()
    - - - ---- - - - - - - - - - - - - - - - - - - - - - - -
    Semaphores (access restrictions for a set of resources)
    pthreads functionEina equivalent
    sem_init()eina_semaphore_new()
    sem_destroy()eina_semaphore_free()
    sem_wait()eina_semaphore_lock()
    sem_post()eina_semaphore_release()
    - - - ---- - - - - - - - - - - - - - - - - - - -
    Barriers
    pthreads functionEina equivalent
    pthread_barrier_init()eina_barrier_new()
    pthread_barrier_destroy()eina_barrier_free()
    pthread_barrier_wait()eina_barrier_wait()
    - -

    Thread Use Examples

    - -

    The following examples display a window with a label. An auxiliary thread semi-regularly changes the text of the label. If you want to display a regular animation, use the Ecore animators described in the Main Loop guide.

    - -

    To use the ecore_thread_feedback() function:

    - -
      - -
    1. Implement the GUI function that sets the text of a label and can be called from the main thread. - -
      -static void
      -_set_label_text(void *data, Ecore_Thread *thread __UNUSED__, void *msgdata)
      -{
      -   char buf[64];
      -   appdata_s *ad = data;
      -   snprintf(buf, sizeof(buf), "Tick %d", (int)(uintptr_t)msgdata);
      -   elm_object_text_set(ad->label, buf);
      -}
      -
      -
    2. -
    3. Send the feedback from the other thread using the ecore_thread_feedback() function. The following function does nothing besides sending the feedback and sleeping. - -
      -static void
      -_long_function(void *data __UNUSED__, Ecore_Thread *thread)
      -{
      -   int iteration;
      -   // Change the text roughly every 1 second. This is only an example; if you
      -   // want regular animations, use Ecore animators!
      -   for (iteration = 0; ; iteration++) 
      -   {
      -      // Since you are running from another thread, you need to take special
      -      // care and instead send data to the main thread and have it run the
      -      // feedback function given when creating the thread
      -      ecore_thread_feedback(thread, (void*)(uintptr_t)iteration);
      -      // Sleep for roughly one second
      -      sleep(1);
      -   }
      -}
      -
      -
    4. - -
    5. Create an end function that is called when the thread exits. In this example, the end function is called only right before the application exits. However, if the blocking function is more complex, it can trigger the end function. - -
      -static void
      -_end_func(void *data, Ecore_Thread *thread __UNUSED__)
      -{
      -   appdata_s *ad = data;
      -   elm_object_text_set(ad->label, "Ticks over");
      -}
      -
      -
    6. - -
    7. Call the ecore_thread_feedback_run() function to start the thread: - -
      -ecore_thread_feedback_run(_long_function, _set_label_text, _end_func, NULL, ad, EINA_FALSE);
      -
      -
    8. -
    - -

    To use the ecore_main_loop_thread_safe_call_sync() function:

    - -
      -
    1. Implement the GUI function that sets the text of a label and can be called from the main thread. The function receives data as a structure and alternatively displays "Tick d" or "Tock d". - -
      -struct thd 
      -{
      -   appdata_s *ad;
      -   Eina_Bool tick_not_tock;
      -   int iteration;
      -};
      -static void *
      -_set_label_text_tick_tock(void *data)
      -{
      -   char buf[64];
      -   struct thd *thd = data;
      -   snprintf(buf, sizeof(buf), "%s %d", (thd->tick_not_tock ? "Tick" : "Tock"), thd->iteration);
      -   elm_object_text_set(thd->ad->label, buf);
      -
      -   return NULL;
      -}
      -
      -
    2. - -
    3. Use the ecore_main_loop_thread_safe_call_sync() function call the GUI function. Differentiate between the ticks and the tocks: - -
      -static void
      -_long_function_tick_tock(void *data, Ecore_Thread *thread __UNUSED__)
      -{
      -   struct thd *thd = malloc(sizeof(struct thd));
      -   thd->ad = data;
      -   for (thd->iteration = 0; ; (thd->iteration)++) 
      -   {
      -      thd->tick_not_tock = EINA_TRUE;
      -      ecore_main_loop_thread_safe_call_sync(_set_label_text_tick_tock, thd);
      -      sleep(1);
      -      thd->tick_not_tock = EINA_FALSE;
      -      ecore_main_loop_thread_safe_call_sync(_set_label_text_tick_tock, thd);
      -      sleep(1);
      -   }
      -   free(thd);
      -}
      -
      -
    4. - -
    5. Start the thread through the ecore_thread_run() function: - -
      -ecore_thread_run(_long_function_tick_tock, _end_func, NULL, ad);
      -
      -
    6. -
    - - - -
    - -Go to top - - - - - - - \ No newline at end of file diff --git a/org.tizen.guides/html/native/ui/ui_component_mn.htm b/org.tizen.guides/html/native/ui/ui_component_mn.htm deleted file mode 100644 index 1e99b22..0000000 --- a/org.tizen.guides/html/native/ui/ui_component_mn.htm +++ /dev/null @@ -1,566 +0,0 @@ - - - - - - - - - - - - - UI Components - - - - - -
    - -

    UI Components

    -

    The UI component management features allow you to the UI components and their focus on the screen, as well as create customizations. The Elementary library provides several UI components than can be used to compose the user interface of your application.

    - - - - - - - - - - -
    Note
    This feature is supported in mobile applications only.
    - -

    The main features of UI component management are:

    -
      -
    • Scaling UI components

      Enables you to scale UI components in order to be comfortably used with a finger and make text more readable.

    • -
    • Using UI components

      Enables you to build your application without having to reinvent basic objects, such as buttons, lists, or text entries.

    • -
    - -

    Scaling UI Components

    - -

    Elementary, through its configuration API (elm_config), provides a way to scale UI components with two different parameters. Finger size parameter is used when the interactive zones (clickable, editable) of the UI components need to be scaled in order to be comfortably used with a finger. Scale parameter is responsible for scaling readable parts of a UI component (text or icons for example), so that it is more visible in the user interface.

    - -

    Finger Size

    - -

    Finger size parameter scales UI components based on the user's finger size. This is useful when using a touchscreen with a finger rather than with a stylus. The finger size parameter is in pixels and determines the minimum size of a square on the screen that is reliably hittable with a finger. This parameter scales the input and interactive areas.

    - -

    The global finger size is set with the elm_config_finger_size_set() function. This adjusts the size and hit area of UI components so they are easy to hit with a finger. The current value is retrieved with the elm_config_finger_size_get() call. The finger size is always in pixel.

    - -

    To increase the current global finger size by 20px:

    - -
    -Evas_Coord finger_size;
    -
    -// Get the current finger size
    -finger_size = elm_config_finger_size_get();
    -
    -// Add 20px to finger size parameter and set it 
    -// to the global Elementary configuration
    -elm_config_finger_size_set(finger_size + 20);
    -
    - -

    Scale

    - -

    This parameter only scales the readable areas of the UI component (text, icons). Parts that must stay pixel-perfect like the highlights, shading, textures and decorations stay as they are.

    - -

    elm_config_scale_set() function is used to set the global scaling factor, that affects to all the UI components. It is also possible to use elm_object_scale_set() to set the scaling factor on a given Elementary UI component and all its children.

    - - - - - - - - - - -
    Note
    The scaling factor is multiplicative, if a child already has a scale size set, it is multiplied by its parent's scale size.
    - -

    The following example sets the global scaling factor to 2.0. Then, the scaling factor of an existing Elementary object is set to 2.0, meaning that this object appears as if it had a 4.0 scale factor, the rest of the application is displayed with a 2.0 scaling factor:

    - -
    -Evas_Object *button;
    -
    -// The button object is created and configured
    -
    -// Set the global scale factor to 2.0
    -elm_config_scale_set(2.0);
    -
    -// Set the scaling factor of the button component to 2.0, this component
    -// appears 4 times bigger than its initial size
    -elm_object_scale_set(button, 2.0);
    -
    - -

    Example

    - -

    This chapter shows the visual result of finger size and scaling factors modification.

    - -

    Figure: elementary_config application

    -

    elementary_config application

    - -

    The previous picture shows the elementary_config application that enables the user to set global scale factor and finger size parameter. As the user drags the sliders, the UI is updated, directly showing the result of the new parameter value.

    - -

    The next picture shows the behavior when the finger size parameter has been increased to 1.30. The text of the sliders and the text of the items in the toolbar are bigger.

    - -

    Figure: Scale increased (1.30)

    -

    Scale increased (1.30)

    - -

    A finger size increase is showed in the image below (increase from 50px to 90 px). Now, the buttons in the toolbar are bigger, so the user can more reliably hit them with a big finger.

    - -

    Figure: Finger size increased (90px)

    -

    Finger size increased (90px)

    - - - - - - - - - - -
    Note
    It is up to the theme (Edje file) to set the parts that are scalable. This is something that needs to be taken into account when developing a new Edje theme. This can be done in EDC with the scale parameter. Refer to the Edje guide for more information on how to do that.
    - -

    Creating Scalable EDC Objects

    - -

    Scale Parameter

    - -

    This chapter explains how to make a scalable Edje object and give hints how to write an EDC file that is scalable. The example shows a basic button that is composed of a background image part and a swallow part that can receive some content.

    - -
    -group 
    -{ 
    -   name: "button";
    -   images 
    -   {
    -      image: "bg.png" COMP;
    -   }
    -   parts 
    -   {
    -      part 
    -      { 
    -         name: "bg";
    -         type: IMAGE;
    -         description 
    -         { 
    -            state: "default" 0.0;
    -            image.normal: "bg.png";
    -         }
    -      }
    -      part 
    -      { 
    -         name: "elm.swallow.content";
    -         type: SWALLOW;
    -         description 
    -         { 
    -            state: "default" 0.0;
    -            visible: 0;
    -         }
    -         description 
    -         { 
    -            state: "visible" 0.0;
    -            visible:1;
    -         }
    -      }
    -   }
    -}
    -
    - -

    To have a scalable object, set the scale parameter to 1 on the parts you want to be scalable as explained in the scalability chapter of the Edje guide. Here the bg and elm.swallow.content parts must be scalable.

    - -
    -group 
    -{ 
    -   name: "button";
    -   images 
    -   {
    -      image: "bg.png" COMP;
    -   }
    -   parts
    -   {
    -      part 
    -      { 
    -         name: "bg";
    -         type: IMAGE;
    -         scale: 1;
    -         description 
    -         { 
    -            state: "default" 0.0;
    -            image.normal: "bg.png";
    -         }
    -      }
    -      part 
    -      { 
    -         name: "elm.swallow.content";
    -         type: SWALLOW;
    -         scale: 1;
    -         description 
    -         { 
    -            state: "default" 0.0;
    -            visible: 0;
    -         }
    -         description 
    -         { 
    -            state: "visible" 0.0;
    -            visible:1;
    -         }
    -      }
    -   }
    -}
    -
    - -

    Image Set

    - -

    If your application needs to be used at different resolutions it is recommended to have 2 images for the background image bg.png. Here the bg_low.png is added to the application. It is used when the size of the image is under 500 px, and a bg_high.png image is for higher resolutions. Use a set on the bg.png image as explained in the Using Image Set chapter of the Edje guide.

    - -
    -group 
    -{ 
    -   name: "button";
    -   images 
    -   {
    -      set 
    -      {
    -         name: "bg.png";
    -         image
    -         {
    -            image: "bg_low.png" COMP;
    -            size: 0 0 200 100;
    -         }
    -         image
    -         {
    -            image: "bg_high.png" COMP;
    -            size: 201 101 5000 5000;
    -         }
    -      }
    -   }
    -}
    -
    - -

    The image below shows three buttons with only a background part visible (the SWALLOW part is empty).

    - -

    Figure: Image set example

    -

    Image set example

    - -

    The first button's size is 100x50 pixels, the background image (bg_low.png) is the same size. The second button is twice bigger than the first one (200x100 pixels). The image is scaled and it does not render well, the borders are quite blurry.

    - -

    To prevent this, the image set has a bigger image to use when the size is bigger than 200x100 pixels (bg_high.png). The third button size is 201x101 pixels and it uses the new image, which has a better quality than the scaled image.

    - -

    Image Borders

    - -

    When the button is resized, the image part is also resized because it is marked as scalable. To get the image resized but to keep the image border as it is, use the border parameter. It specifies the border size which is not resized even if the image is. This is explained in the Border resizing chapter of the Edje guide.

    - -

    To add a 40 pixel border on the left and right part of the bg image and a 20 pixel border on top and bottom borders:

    - -
    -parts 
    -{
    -   part 
    -   { 
    -      name: "bg";
    -      type: IMAGE;
    -      scale: 1;
    -      description 
    -      { 
    -         state: "default" 0.0;
    -         image.normal: "bg.png";
    -         image.border: 40 40 20 20;
    -      }
    -   }
    -}
    -
    - -

    The image below shows that when resizing the button, the corners keep their initial ratio. Only the middle part of the button is resized.

    - -

    Figure: Border example

    -

    Border example

    - -

    Using UI Components

    - -

    Figure: Elementary

    -

    Elementary

    - -

    The Elementary library is a simple toolkit. It provides several UI components than can be used to compose the user interface of your application. UI components allow you to build your application without having to reinvent basic objects, such as buttons, lists, or text entries. UI components will often generate signals that can be caught in the application when the user interacts with the UI components. This guide teaches you the basics of Elementary, describes selected concepts of the Elementary configuration framework, and describes the most common UI components.

    - -

    Elementary Basics

    - -

    In this chapter, we explain how UI components are built in a hierarchical manner, how to build a minimal Elementary application, and what the differences are between the callbacks that can be registered for UI components.

    - -

    Elementary

    - -

    Elementary Configuration

    - -

    Elementary can be configured using profiles. These chapters detail some configuration items that can be modified to tweak the use of Elementary.

    - -

    Managing Elementary Profiles and Configuring Elementary Options

    - -

    Components

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    - Table: Available UI components -
    Component nameDescription
    BackgroundThe background component can be used to set a solid background decoration to a window or a container object. It works like an image, but has some background specific properties, such as setting it to tiled, centered, scaled, or stretched.
    ButtonThe button component is a simple push button. It is composed of a label icon and an icon object, and has an auto-repeat feature.
    CheckThe check component toggles the value of a Boolean between true and false.
    ColorselectorThe colorselector component provides a color selection solution to the user. It has different modes available, each of them showing a different configuration of the color selection.
    CtxpopupThe ctxpopup component is a contextual popup that can show a list of items.
    DatetimeThe datetime component can display and input date and time values.
    EntryThe entry component is a box to which the user can enter text.
    FlipThe flip component can hold two Evas objects and let the user flip between these objects using a variety of predefined animations.
    GengridThe gengrid component displays objects on a grid layout and renders only the visible objects.
    GenlistThe genlist component displays a scrollable list of items. It can hold a lot of items while still being fast and memory-efficient (only the visible items are allocated memory).
    GLViewThe GLView component can render OpenGL in an Elementary object, hiding EvasGL complexity.
    IconThe icon component inherits from the image component. It is used to display images in an icon context.
    ImageThe image component can load and display an image from a file or from memory.
    IndexThe index component provides an index for fast access to another group of UI items.
    LabelThe label component displays text with simple HTML-like markup.
    ListThe list component is a very simple list for managing a small number of items. If you need to manage a lot of items, use the genlist component instead.
    MapThe map component can display a geographic map. The default map data is provided by the OpenStreetMap project (http://www.openstreetmap.org/).
    NotifyThe notify component displays a container in a specific region of the parent object. It can receive some content, and it can be automatically hidden after a certain amount of time.
    PanelThe panel component is an animated object that can contain child objects. It can be expanded or contracted by clicking on the button on its edge.
    PhotoThe photo component can be used to display a photo, such as a contact image. If no photo is set, the UI component displays a person icon to show that it is a photo placeholder.
    PhotocamThe photocam component is designed to display high-resolution photos taken with a digital camera. It allows you to zoom photos, load photos fast, and fit photos. It is optimized for JPEG images and has a low memory footprint.
    PlugThe plug component allows you to show an Evas object created by another process. It can be used anywhere like any other Elementary UI component.
    PopupThe popup component shows a pop-up area that can contain a title area, a content area, and an action area.
    ProgressbarThe progressbar component can be used to display the progress status of a given job.
    RadioThe radio component can display 1 or more options, but the user can only select one of them. The UI component is composed of an indicator (selected/unselected), an optional icon, and an optional label. Even though it is usually grouped with 2 or more other radio components, it can also be used alone.
    SegmentcontrolThe slider component is a draggable bar that is used to select a value from a range of values.
    SliderThe slider component is a draggable bar that is used to select a value from a range of values.
    SpinnerThe spinner component enables the user to increase or decrease a numeric value by using arrow buttons.
    ToolbarThe toolbar component is a scrollable list of items. It can also show a menu when an item is selected. Only one item can be selected at a time.
    TooltipThe tooltip component is a smart object used to show tips or information about a parent object when the mouse hovers over the parent object.
    TransitThe transit component can apply several transition effects to an Evas object, such as translations and rotations. The use of the transit component is documented in the Creating Animations and Effects guide.
    WinThe win component is the root window component that will be often used in an application. It allows you to create some content in it, and it is handled by the window manager.
    - - - -

    UI Component Focus

    - -

    You can programmatically change the focus of UI components in an EFL application.

    - -

    Managing UI Component Focus

    - -

    UI Component Styles

    - -

    You can apply styles to various UI components to change their appearance.

    - -

    UI Component Styles

    - -

    UI Component Customization

    - -

    You can use themes and styles to customize the look and feel of UI components.

    - -

    Customizing UI Components

    - -

    Containers

    - -

    All applications use containers to create the layout of their UI. The EFL and Elementary support several ways to create this layout. You can use a predefined layout or an animated layout, or you can create your own layout.

    - -

    In this guide, we look at how to use the different containers provided by Elementary.

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    - Table: Available container components -
    Container nameDescription
    BoxOne of the most simple containers in the EFL is a box.
    ConformantA conformant is a container component that accounts for the space taken by the indicator, virtual keyboard, and softkey windows.
    GridIn a grid, objects are placed at specific positions along a fixed grid.
    LayoutA layout is a container component that takes a standard Edje design file and wraps it very thinly in a UI component.
    MapbufA mapbuf is a container component that uses an Evas map to hold a content object. This UI component is used to improve the moving and resizing performance of complex UI components.
    NaviframeA naviframe component consists of a stack of views. New views are pushed on top of previous ones, and only the top-most view is displayed.
    PanesA panes component adds a draggable bar between two sections of content. The sections are resized when the bar is dragged.
    ScrollerA scroller holds (and clips) a single object and allows you to scroll across it.
    TableA table is like a box but with 2 dimensions.
    - - - - -
    - -Go to top - - - - - - - \ No newline at end of file diff --git a/org.tizen.guides/html/native/ui/ui_component_n.htm b/org.tizen.guides/html/native/ui/ui_component_n.htm deleted file mode 100644 index 8619779..0000000 --- a/org.tizen.guides/html/native/ui/ui_component_n.htm +++ /dev/null @@ -1,42 +0,0 @@ - - - - - - - - - - - - - UI Components - - -
    -

    UI Components

    - -

    Click the profile you want:

    -

    Mobile native Wearable native

    - - - -
    - - - - - - - \ No newline at end of file diff --git a/org.tizen.guides/html/native/ui/ui_component_wn.htm b/org.tizen.guides/html/native/ui/ui_component_wn.htm deleted file mode 100644 index 2a66324..0000000 --- a/org.tizen.guides/html/native/ui/ui_component_wn.htm +++ /dev/null @@ -1,561 +0,0 @@ - - - - - - - - - - - - - UI Components - - - - - -
    - -

    UI Components

    -

    The UI component management features allow you manage the UI components and their focus on the screen, as well as create customizations. The Elementary library provides several UI components than can be used to compose the user interface of your application.

    - - - - - - - - - - -
    Note
    This feature is supported in wearable applications only.
    - -

    The main features of UI component management are:

    -
      -
    • Scaling UI components

      Enables you to scale UI components in order to be comfortably used with a finger and make text more readable.

    • -
    • Using UI components

      Enables you to build your application without having to reinvent basic objects, such as buttons, lists, or text entries.

    • -
    - -

    Scaling UI Components

    - -

    Elementary, through its configuration API (elm_config), provides a way to scale UI components with two different parameters. Finger size parameter is used when the interactive zones (clickable, editable) of the UI components need to be scaled in order to be comfortably used with a finger. Scale parameter is responsible for scaling readable parts of a UI component (text or icons for example), so that it is more visible in the user interface.

    - -

    Finger Size

    - -

    Finger size parameter scales UI components based on the user's finger size. This is useful when using a touchscreen with a finger rather than with a stylus. The finger size parameter is in pixels and determines the minimum size of a square on the screen that is reliably hittable with a finger. This parameter scales the input and interactive areas.

    - -

    The global finger size is set with the elm_config_finger_size_set() function. This adjusts the size and hit area of UI components so they are easy to hit with a finger. The current value is retrieved with the elm_config_finger_size_get() call. The finger size is always in pixel.

    - -

    To increase the current global finger size by 20px:

    - -
    -Evas_Coord finger_size;
    -
    -// Get the current finger size
    -finger_size = elm_config_finger_size_get();
    -
    -// Add 20px to finger size parameter and set it 
    -// to the global Elementary configuration
    -elm_config_finger_size_set(finger_size + 20);
    -
    - -

    Scale

    - -

    This parameter only scales the readable areas of the UI component (text, icons). Parts that must stay pixel-perfect like the highlights, shading, textures and decorations stay as they are.

    - -

    elm_config_scale_set() function is used to set the global scaling factor, that affects to all the UI components. It is also possible to use elm_object_scale_set() to set the scaling factor on a given Elementary UI component and all its children.

    - - - - - - - - - - -
    Note
    The scaling factor is multiplicative, if a child already has a scale size set, it is multiplied by its parent's scale size.
    - -

    The following example sets the global scaling factor to 2.0. Then, the scaling factor of an existing Elementary object is set to 2.0, meaning that this object appears as if it had a 4.0 scale factor, the rest of the application is displayed with a 2.0 scaling factor:

    - -
    -Evas_Object *button;
    -
    -// The button object is created and configured
    -
    -// Set the global scale factor to 2.0
    -elm_config_scale_set(2.0);
    -
    -// Set the scaling factor of the button component to 2.0, this component
    -// appears 4 times bigger than its initial size
    -elm_object_scale_set(button, 2.0);
    -
    - -

    Example

    - -

    This chapter shows the visual result of finger size and scaling factors modification.

    - -

    Figure: elementary_config application

    -

    elementary_config application

    - -

    The previous picture shows the elementary_config application that enables the user to set global scale factor and finger size parameter. As the user drags the sliders, the UI is updated, directly showing the result of the new parameter value.

    - -

    The next picture shows the behavior when the finger size parameter has been increased to 1.30. The text of the sliders and the text of the items in the toolbar are bigger.

    - -

    Figure: Scale increased (1.30)

    -

    Scale increased (1.30)

    - -

    A finger size increase is showed in the image below (increase from 50px to 90 px). Now, the buttons in the toolbar are bigger, so the user can more reliably hit them with a big finger.

    - -

    Figure: Finger size increased (90px)

    -

    Finger size increased (90px)

    - - - - - - - - - - -
    Note
    It is up to the theme (Edje file) to set the parts that are scalable. This is something that needs to be taken into account when developing a new Edje theme. This can be done in EDC with the scale parameter. Refer to the Edje guide for more information on how to do that.
    - -

    Creating Scalable EDC Objects

    - -

    Scale Parameter

    - -

    This chapter explains how to make a scalable Edje object and give hints how to write an EDC file that is scalable. The example shows a basic button that is composed of a background image part and a swallow part that can receive some content.

    - -
    -group 
    -{ 
    -   name: "button";
    -   images 
    -   {
    -      image: "bg.png" COMP;
    -   }
    -   parts 
    -   {
    -      part 
    -      { 
    -         name: "bg";
    -         type: IMAGE;
    -         description 
    -         { 
    -            state: "default" 0.0;
    -            image.normal: "bg.png";
    -         }
    -      }
    -      part 
    -      { 
    -         name: "elm.swallow.content";
    -         type: SWALLOW;
    -         description 
    -         { 
    -            state: "default" 0.0;
    -            visible: 0;
    -         }
    -         description 
    -         { 
    -            state: "visible" 0.0;
    -            visible:1;
    -         }
    -      }
    -   }
    -}
    -
    - -

    To have a scalable object, set the scale parameter to 1 on the parts you want to be scalable as explained in the scalability chapter of the Edje guide. Here the bg and elm.swallow.content parts must be scalable.

    - -
    -group 
    -{ 
    -   name: "button";
    -   images 
    -   {
    -      image: "bg.png" COMP;
    -   }
    -   parts
    -   {
    -      part 
    -      { 
    -         name: "bg";
    -         type: IMAGE;
    -         scale: 1;
    -         description 
    -         { 
    -            state: "default" 0.0;
    -            image.normal: "bg.png";
    -         }
    -      }
    -      part 
    -      { 
    -         name: "elm.swallow.content";
    -         type: SWALLOW;
    -         scale: 1;
    -         description 
    -         { 
    -            state: "default" 0.0;
    -            visible: 0;
    -         }
    -         description 
    -         { 
    -            state: "visible" 0.0;
    -            visible:1;
    -         }
    -      }
    -   }
    -}
    -
    - -

    Image Set

    - -

    If your application needs to be used at different resolutions it is recommended to have 2 images for the background image bg.png. Here the bg_low.png is added to the application. It is used when the size of the image is under 500 px, and a bg_high.png image is for higher resolutions. Use a set on the bg.png image as explained in the Using Image Set chapter of the Edje guide.

    - -
    -group 
    -{ 
    -   name: "button";
    -   images 
    -   {
    -      set 
    -      {
    -         name: "bg.png";
    -         image
    -         {
    -            image: "bg_low.png" COMP;
    -            size: 0 0 200 100;
    -         }
    -         image
    -         {
    -            image: "bg_high.png" COMP;
    -            size: 201 101 5000 5000;
    -         }
    -      }
    -   }
    -}
    -
    - -

    The image below shows three buttons with only a background part visible (the SWALLOW part is empty).

    - -

    Figure: Image set example

    -

    Image set example

    - -

    The first button's size is 100x50 pixels, the background image (bg_low.png) is the same size. The second button is twice bigger than the first one (200x100 pixels). The image is scaled and it does not render well, the borders are quite blurry.

    - -

    To prevent this, the image set has a bigger image to use when the size is bigger than 200x100 pixels (bg_high.png). The third button size is 201x101 pixels and it uses the new image, which has a better quality than the scaled image.

    - -

    Image Borders

    - -

    When the button is resized, the image part is also resized because it is marked as scalable. To get the image resized but to keep the image border as it is, use the border parameter. It specifies the border size which is not resized even if the image is. This is explained in the Border resizing chapter of the Edje guide.

    - -

    To add a 40 pixel border on the left and right part of the bg image and a 20 pixel border on top and bottom borders:

    - -
    -parts 
    -{
    -   part 
    -   { 
    -      name: "bg";
    -      type: IMAGE;
    -      scale: 1;
    -      description 
    -      { 
    -         state: "default" 0.0;
    -         image.normal: "bg.png";
    -         image.border: 40 40 20 20;
    -      }
    -   }
    -}
    -
    - -

    The image below shows that when resizing the button, the corners keep their initial ratio. Only the middle part of the button is resized.

    - -

    Figure: Border example

    -

    Border example

    - -

    Using UI Components

    - -

    Figure: Elementary

    -

    Elementary

    - -

    The Elementary library is a simple toolkit. It provides several UI components than can be used to compose the user interface of your application. UI components allow you to build your application without having to reinvent basic objects, such as buttons, lists, or text entries. UI components will often generate signals that can be caught in the application when the user interacts with the UI components. This guide teaches you the basics of Elementary, describes selected concepts of the Elementary configuration framework, and describes the most common UI components.

    - -

    Elementary Basics

    - -

    In this chapter, we explain how UI components are built in a hierarchical manner, how to build a minimal Elementary application, and what the differences are between the callbacks that can be registered for UI components.

    - -

    Elementary

    - -

    Elementary Configuration

    - -

    Elementary can be configured using profiles. These chapters detail some configuration items that can be modified to tweak the use of Elementary.

    - -

    Managing Elementary Profiles and Configuring Elementary Options

    - -

    Components

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    - Table: Available UI components -
    Component nameDescription
    BackgroundThe background component can be used to set a solid background decoration to a window or a container object. It works like an image, but has some background specific properties, such as setting it to tiled, centered, scaled, or stretched.
    ButtonThe button component is a simple push button. It is composed of a label icon and an icon object, and has an auto-repeat feature.
    CheckThe check component toggles the value of a Boolean between true and false.
    CtxpopupThe ctxpopup component is a contextual popup that can show a list of items.
    DatetimeThe datetime component can display and input date and time values.
    EntryThe entry component is a box to which the user can enter text.
    GenlistThe genlist component displays a scrollable list of items. It can hold a lot of items while still being fast and memory-efficient (only the visible items are allocated memory).
    GLViewThe GLView component can render OpenGL in an Elementary object, hiding EvasGL complexity.
    IconThe icon component inherits from the image component. It is used to display images in an icon context.
    ImageThe image component can load and display an image from a file or from memory.
    IndexThe index component provides an index for fast access to another group of UI items.
    LabelThe label component displays text with simple HTML-like markup.
    ListThe list component is a very simple list for managing a small number of items. If you need to manage a lot of items, use the genlist component instead.
    NotifyThe notify component displays a container in a specific region of the parent object. It can receive some content, and it can be automatically hidden after a certain amount of time.
    PlugThe plug component allows you to show an Evas object created by another process. It can be used anywhere like any other Elementary UI component.
    PopupThe popup component shows a pop-up area that can contain a title area, a content area, and an action area.
    ProgressbarThe progressbar component can be used to display the progress status of a given job.
    RadioThe radio component can display 1 or more options, but the user can only select one of them. The UI component is composed of an indicator (selected/unselected), an optional icon, and an optional label. Even though it is usually grouped with 2 or more other radio components, it can also be used alone.
    SliderThe slider component is a draggable bar that is used to select a value from a range of values.
    TransitThe transit component can apply several transition effects to an Evas object, such as translations and rotations. The use of the transit component is documented in the Creating Animations and Effects guide.
    WinThe win component is the root window component that will be often used in an application. It allows you to create some content in it, and it is handled by the window manager.
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    - Table: Available circle UI components -
    Component nameDescription
    Circle DatetimeThe circle datetime extends elm_datetime by visualizing the selected field.
    Circle GenlistThe circle genlist provides a scrollbar with circular movement. It is also operated with rotary events to move to the next or previous item.
    Circle ObjectThe circle object extends elementary components in a form of circular design. Sometimes a circle object merely provides additional UI features to elementary component, and sometimes it works as an independent component with UI and functionalities.
    Circle ProgressbarThe circle progressbar aims to show the progress status of a given task with circular design. It visualizes the progress status within a range.
    Circle ScrollerThe circle scroller changes corresponding to the rotary events. It shows the whole scrollable area with a circular scroll bar.
    Circle SliderThe circle slider changes corresponding to rotary events. The circle slider not only extends the UI feature of the elm_slider, but also replaces the functionalities of the elm_slider in a circular design.
    Circle SurfaceThe circle surface manages and renders circle objects. Multiple circle objects can be connected to one circle surface as candidates of an object to be rendered.
    - - -

    UI Component Focus

    - -

    You can programmatically change the focus of UI components in an EFL application.

    - -

    Managing UI Component Focus

    - -

    UI Component Styles

    - -

    You can apply styles to various UI components to change their appearance.

    - -

    UI Component Styles

    - -

    UI Component Customization

    - -

    You can use themes and styles to customize the look and feel of UI components.

    - -

    Customizing UI Components

    - -

    Containers

    - -

    All applications use containers to create the layout of their UI. The EFL and Elementary support several ways to create this layout. You can use a predefined layout or an animated layout, or you can create your own layout.

    - -

    In this guide, we look at how to use the different containers provided by Elementary.

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    - Table: Available container components -
    Container nameDescription
    BoxOne of the most simple containers in the EFL is a box.
    ConformantA conformant is a container component that accounts for the space taken by the indicator, virtual keyboard, and softkey windows.
    GridIn a grid, objects are placed at specific positions along a fixed grid.
    LayoutA layout is a container component that takes a standard Edje design file and wraps it very thinly in a UI component.
    MapbufA mapbuf is a container component that uses an Evas map to hold a content object. This UI component is used to improve the moving and resizing performance of complex UI components.
    NaviframeA naviframe component consists of a stack of views. New views are pushed on top of previous ones, and only the top-most view is displayed.
    ScrollerA scroller holds (and clips) a single object and allows you to scroll across it.
    TableA table is like a box but with 2 dimensions.
    - - - - -
    - -Go to top - - - - - - - \ No newline at end of file diff --git a/org.tizen.guides/html/native/ui/ui_guide_n.htm b/org.tizen.guides/html/native/ui/ui_guide_n.htm index 63b3622..9fe4c3c 100644 --- a/org.tizen.guides/html/native/ui/ui_guide_n.htm +++ b/org.tizen.guides/html/native/ui/ui_guide_n.htm @@ -32,24 +32,14 @@

    UI Framework

    -

    UI framework features include all aspects of creating a visual outlook for your application to ensure the best possible user experience.

    +

    UI framework features include some aspects of creating a visual outlook for your application to ensure the best possible user experience.

    The main UI features are:

      -
    • EFL

      Enables you to construct graphical user interfaces.

    • -
    • Eina

      Enables you to create and manipulate the most common data types and tools of Eina.

    • -
    • Evas

      Enables you to manipulate objects on a clean display canvas formed for the target display systems.

    • -
    • Edje

      Enables you to theme an application.

    • -
    • Ecore

      Enables you to manage the application main loop.
    • -
    • Event and Effect

      Enables you to handle different kinds of events.

    • -
    • UI Components

      Enables you to manage shortcuts, UI components, and scalability.
    • -
    • Efl Extension

      Enables you to work with the Menu and Back hardware keys on devices.

    • -
    • Font Setting

      Enables you to change the font of your application to another system default font or your own font.

    • -
    • EFL UTIL

      Enables you to manage notification window levels.

    • -
    • Multiple Screen Support

      Enables you to design applications for different kinds of screens.

    • -
    • Scalability Support

      Enables you to design applications so that their UI can be scaled for diverse devices without problems.

    • External Output Manager

      Enables you to handle external output devices.

    - + +

    For more information about implementing the UI for your application using the EFL features, see EFL.

    + diff --git a/org.tizen.guides/html/native/uix/stt_n.htm b/org.tizen.guides/html/native/uix/stt_n.htm index 78c552b..c95e4c4 100644 --- a/org.tizen.guides/html/native/uix/stt_n.htm +++ b/org.tizen.guides/html/native/uix/stt_n.htm @@ -1,109 +1,109 @@ - - - - - - - - - - - - - - STT - - - - - - -
    -

    STT

    - -

    The STT (speech-to-text) features enable recognizing sound data recorded by the user and sending the result as text. When your application creates a handle and prepares the STT service by the API, the STT daemon is invoked and connected for background work. This daemon and your application communicate as the server and the client.

    - -

    Basic STT Processes

    - -

    Using STT, you can:

    -
      -
    • Create a handle and register callback functions. -
        -
      • Create a STT handle, which is used for distinguishing your application from other applications also using the STT.
      • -
      • Get notified on state changes, language changes, recognition results, and errors by registered callback functions.
      • -
      -
    • -
    • Start, stop, and cancel recognition. -
        -
      • Start recording the user voice by microphone and analyze the recorded data as text.
      • -
      • If you stop the recording manually by the API, the STT stops the recording and recognizes the sound data. The recognized text is then sent by the registered callback function.
      • -
      • You also can set sounds which are played before the STT recording starts or after the recording stops.
      • -
      -
    • -
    • Get the recognition result. -
        -
      • The recognition result is sent by the registered callback function.
      • -
      • With a specific STT engine, you can obtain the time stamp information for the recognition result.
      • -
      • Some STT engines send the recognition result partially during the user recording. You can get the result information using the parameter of the recognition result callback function.
      • -
      -
    • -
    - -

    The STT life-cycle is described in the following figure.

    - -

    Figure: STT life-cycle

    -

    STT life-cycle

    - -

    Getting STT Information

    -

    You can get the following information about the STT:

    -
      -
    • Get the current state of the STT. The state is also applied as a precondition for each function.
    • -
    • Get the default language. -
      • You can start recognition with the language that you want as a parameter of the start API. However, if you do not set a specific language, the STT starts recording and uses the default language for recognition.
      • -
      • The default language can be changed by the STT setting an application or by the display language changing. If the display language is changed to a non-supported one, the STT language is changed to UK English.
    • -
    • Get a list of the supported languages to check whether the language you want is supported.
    • -
    • Get a list of the supported engines and the selection of current engines. Additional features, such as silence detection and partial result, are provided by specific engines.
    • -
    - - - -
    - -Go to top - - - - - - - - + + + + + + + + + + + + + + STT + + + + + + +
    +

    STT

    + +

    The STT (speech-to-text) features enable recognizing sound data recorded by the user and sending the result as text. When your application creates a handle and prepares the STT service by the API, the STT daemon is invoked and connected for background work. This daemon and your application communicate as the server and the client.

    + +

    Basic STT Processes

    + +

    Using STT, you can:

    +
      +
    • Create a handle and register callback functions. +
        +
      • Create a STT handle, which is used for distinguishing your application from other applications also using the STT.
      • +
      • Get notified on state changes, language changes, recognition results, and errors by registered callback functions.
      • +
      +
    • +
    • Start, stop, and cancel recognition. +
        +
      • Start recording the user voice by microphone and analyze the recorded data as text.
      • +
      • If you stop the recording manually by the API, the STT stops the recording and recognizes the sound data. The recognized text is then sent by the registered callback function.
      • +
      • You also can set sounds which are played before the STT recording starts or after the recording stops.
      • +
      +
    • +
    • Get the recognition result. +
        +
      • The recognition result is sent by the registered callback function.
      • +
      • With a specific STT engine, you can obtain the time stamp information for the recognition result.
      • +
      • Some STT engines send the recognition result partially during the user recording. You can get the result information using the parameter of the recognition result callback function.
      • +
      +
    • +
    + +

    The STT life-cycle is described in the following figure.

    + +

    Figure: STT life-cycle

    +

    STT life-cycle

    + +

    Getting STT Information

    +

    You can get the following information about the STT:

    +
      +
    • Get the current state of the STT. The state is also applied as a precondition for each function.
    • +
    • Get the default language. +
      • You can start recognition with the language that you want as a parameter of the start API. However, if you do not set a specific language, the STT starts recording and uses the default language for recognition.
      • +
      • The default language can be changed by the STT setting an application or by the display language changing. If the display language is changed to a non-supported one, the STT language is changed to UK English.
    • +
    • Get a list of the supported languages to check whether the language you want is supported.
    • +
    • Get a list of the supported engines and the selection of current engines. Additional features, such as silence detection and partial result, are provided by specific engines.
    • +
    + + + +
    + +Go to top + + + + + + + + diff --git a/org.tizen.guides/html/native/uix/tts_n.htm b/org.tizen.guides/html/native/uix/tts_n.htm index 64ef9f6..91d69c7 100644 --- a/org.tizen.guides/html/native/uix/tts_n.htm +++ b/org.tizen.guides/html/native/uix/tts_n.htm @@ -1,110 +1,110 @@ - - - - - - - - - - - - - - TTS - - - - - - -
    -

    TTS

    - -

    The TTS (text-to-speech) features include synthesizing text into sound data as utterances and playing them. It is also possible to pause and stop playing. When your application creates a handle and prepares the TTS service by the API, the TTS daemon is invoked and connected for background work. This daemon and your application communicate as the server and the client.

    - -

    Basic TTS Processes

    - -

    Using TTS, you can:

    -
      -
    • Create a handle and register callback functions. -
        -
      • Create a TTS handle which is used for distinguishing your application from other applications also using the TTS.
      • -
      • To get notifications about state changes, language changes, starting or finishing utterances, and errors, register callback functions.
      • -
      -
    • -
    • Add text. -
        -
      • Add the text that you want to read out by the TTS module. The requested text is handled as an utterance. You can add several texts, and they are managed using a queue.
      • -
      • There is a limit on the maximum text length for one utterance, and the time spent for synthesizing is dependent on the text length.
      • -
      -
    • -
    • Play, pause, and stop playback. -
        -
      • Synthesize the text in the queue and play the sound data after synthesizing.
      • -
      • You can also pause and stop playing. If you call the function to stop, all requested data (both the sound data and text in the queue) is deleted.
      • -
      -
    • -
    - -

    The TTS life-cycle is described in the following figure.

    - -

    Figure: TTS life-cycle

    -

    TTS life-cycle

    - -

    Getting TTS Information

    -

    You can get the following information about the TTS:

    -
      -
    • Get the current state of the TTS. The state is also applied as a precondition for each function.
    • -
    • Get the default voice. -
        -
      • In the TTS, the voice is defined as a combination of the language and the type, such as male or female.
      • -
      • You can request the synthesis of the text with your own voice option by the parameter of the add text function. However, if you do not set a specific option, the TTS synthesizes the text with the default voice.
      • -
      • The default voice can be changed by the TTS setting an application or by the display language changing. If the display language is changed to a non-supported language, the language of the TTS is changed to UK English.
      • -
      -
    • -
    • Get a list of supported voices to check whether the language and voice type you want are supported.
    • -
    - - - -
    - -Go to top - - - - - - - - + + + + + + + + + + + + + + TTS + + + + + + +
    +

    TTS

    + +

    The TTS (text-to-speech) features include synthesizing text into sound data as utterances and playing them. It is also possible to pause and stop playing. When your application creates a handle and prepares the TTS service by the API, the TTS daemon is invoked and connected for background work. This daemon and your application communicate as the server and the client.

    + +

    Basic TTS Processes

    + +

    Using TTS, you can:

    +
      +
    • Create a handle and register callback functions. +
        +
      • Create a TTS handle which is used for distinguishing your application from other applications also using the TTS.
      • +
      • To get notifications about state changes, language changes, starting or finishing utterances, and errors, register callback functions.
      • +
      +
    • +
    • Add text. +
        +
      • Add the text that you want to read out by the TTS module. The requested text is handled as an utterance. You can add several texts, and they are managed using a queue.
      • +
      • There is a limit on the maximum text length for one utterance, and the time spent for synthesizing is dependent on the text length.
      • +
      +
    • +
    • Play, pause, and stop playback. +
        +
      • Synthesize the text in the queue and play the sound data after synthesizing.
      • +
      • You can also pause and stop playing. If you call the function to stop, all requested data (both the sound data and text in the queue) is deleted.
      • +
      +
    • +
    + +

    The TTS life-cycle is described in the following figure.

    + +

    Figure: TTS life-cycle

    +

    TTS life-cycle

    + +

    Getting TTS Information

    +

    You can get the following information about the TTS:

    +
      +
    • Get the current state of the TTS. The state is also applied as a precondition for each function.
    • +
    • Get the default voice. +
        +
      • In the TTS, the voice is defined as a combination of the language and the type, such as male or female.
      • +
      • You can request the synthesis of the text with your own voice option by the parameter of the add text function. However, if you do not set a specific option, the TTS synthesizes the text with the default voice.
      • +
      • The default voice can be changed by the TTS setting an application or by the display language changing. If the display language is changed to a non-supported language, the language of the TTS is changed to UK English.
      • +
      +
    • +
    • Get a list of supported voices to check whether the language and voice type you want are supported.
    • +
    + + + +
    + +Go to top + + + + + + + + diff --git a/org.tizen.guides/html/native/uix/uix_guide_n.htm b/org.tizen.guides/html/native/uix/uix_guide_n.htm index 1389874..0903492 100644 --- a/org.tizen.guides/html/native/uix/uix_guide_n.htm +++ b/org.tizen.guides/html/native/uix/uix_guide_n.htm @@ -1,71 +1,71 @@ - - - - - - - - - - - - - - UIX - - - - - - -
    -

    UIX

    - -

    UIX features include managing sound data, such as voice commands, speech-to-text (STT), and text-to-speech (TTS).

    - - -

    The main UIX features are:

    -
      -
    • TTS

      Enables you to synthesize text into sound data and play it.

    • -
    • STT

      Enables you to recognize sound data recorded by the user and send the result as text.

    • -
    • Voice Control

      Enables you to let the user control the device through voice commands.

    • -
    • Input Method

      Enables you to create an IME application that provides a new keyboard for the user.

    • -
    - - - -
    - -Go to top - - - - - - - - + + + + + + + + + + + + + + UIX + + + + + + +
    +

    UIX

    + +

    UIX features include managing sound data, such as voice commands, speech-to-text (STT), and text-to-speech (TTS).

    + + +

    The main UIX features are:

    +
      +
    • TTS

      Enables you to synthesize text into sound data and play it.

    • +
    • STT

      Enables you to recognize sound data recorded by the user and send the result as text.

    • +
    • Voice Control

      Enables you to let the user control the device through voice commands.

    • +
    • Input Method

      Enables you to create an IME application that provides a new keyboard for the user.

    • +
    + + + +
    + +Go to top + + + + + + + + diff --git a/org.tizen.guides/html/native/web/web_guide_n.htm b/org.tizen.guides/html/native/web/web_guide_n.htm index d813da7..07d3eee 100644 --- a/org.tizen.guides/html/native/web/web_guide_n.htm +++ b/org.tizen.guides/html/native/web/web_guide_n.htm @@ -1,74 +1,74 @@ - - - - - - - - - - - - - - Web - - - - -
    -
    -

    Mobile native Wearable native

    -
    - - -
    - -
    -

    Web

    -

    Web features include accessing Web content in your application.

    - -

    The main Web features are:

    -
      -
    • WebView -

      Enables you to access the Web pages and Web content.

      -

      The WebView API implements the EFL WebKit (EWK), which covers various features for Web browsing, such as loading and displaying Web pages and navigating through the browsing history. EFL APIs (in mobile and wearable applications), such as evas_*, elm_*, and eina_*, are used to build up a complete application supporting Web browsing.

      -
    • -
    - - - - - - - -
    - -Go to top - - - - - - - - + + + + + + + + + + + + + + Web + + + + +
    +
    +

    Mobile native Wearable native

    +
    + + +
    + +
    +

    Web

    +

    Web features include accessing Web content in your application.

    + +

    The main Web features are:

    +
      +
    • WebView +

      Enables you to access the Web pages and Web content.

      +

      The WebView API implements the EFL WebKit (EWK), which covers various features for Web browsing, such as loading and displaying Web pages and navigating through the browsing history. EFL APIs (in mobile and wearable applications), such as evas_*, elm_*, and eina_*, are used to build up a complete application supporting Web browsing.

      +
    • +
    + + + + + + + +
    + +Go to top + + + + + + + + diff --git a/org.tizen.guides/html/scripts/common.js b/org.tizen.guides/html/scripts/common.js index 60250b6..d46479a 100644 --- a/org.tizen.guides/html/scripts/common.js +++ b/org.tizen.guides/html/scripts/common.js @@ -1,1752 +1,1752 @@ -$(document).ready(function(){ - $('#contents table').each(function(){ - if (!$(this).parent().hasClass('table')) { - $(this).wrap('
    '); - } - }); - - // Lnb Menu Initialize - if($('div#contents').find('.lnb').length){ - if($("ul li.events_news").size() > 0) { - $("ul.lnb").after("

    \"Samsung

    "); - } - initLnb(); - initScript(staticURL + "/js/fixednavbar.js", function(){}); - } - - //family site - if($('div#footer').find('dl#familySlider').length){ - fn_rollToEx('familySlider', 'sliderBanner', 1, true); - } - - // Svn Commit Test - - // Language Selection - if($('div#header').find('.util').length){ - var $lang = $('div#header').find('.util'); - $lang.find('a.lang').toggle(function(){ - $(this).css('background-image', $(this).css('background-image').replace('.gif','_.gif')).next('ul.language').show(); - },function(){ - $(this).css('background-image', $(this).css('background-image').replace('_.gif','.gif')).next('ul.language').hide(); - }); - - $lang.bind('mouseleave',function(){ - $(this).find('ul.language').hide(); - $lang.find('a.lang').css('background-image', $lang.find('a.lang').css('background-image').replace('_.gif','.gif')); - }); - - $lang.find('ul.language').children().last().on("keydown", function(e) { - if(e.which == 9 && e.shiftKey) { - return true; - } - - if(e.which == 9) { - e.preventDefault(); - $lang.find('ul.language').hide(); - $lang.find('a.lang').css('background-image', $lang.find('a.lang').css('background-image').replace('_.gif','.gif')); - setTimeout(function() { - $("#searchTop").focus(); - }, 1); - } - }); - } - - // Open the Sitemap - var $open = $('div#header').find('.bt-open'); - $open.bind('click',function(){ - var $self = $(this); - var $sitemap = $('div#wrapper').find('div#sitemap'); - //var source = $sitemap.is(':visible') ? $self.css('background-image').replace('_.gif','.gif') : $self.css('background-image').replace('.gif','_.gif'); - - if($sitemap.is(':visible')){ - var source = $self.css('background-image').replace('_.gif','.gif'); - //if($('body#main').length) $('#header .util').css('border-bottom','3px solid #e4e4e4'); - - $self.attr('title','open sitemap'); - }else{ - var source = $self.css('background-image').replace('.gif','_.gif'); - //if($('body#main').length) $('#header .util').css('border-bottom','3px solid #114196'); - - $self.attr('title','close sitemap'); - } - - $self.css('background-image',source); - $sitemap.slideToggle('fast'); - - $sitemap.find('ul').filter(':last').children().filter(':last').focusout(function(){ - var source = $self.css('background-image').replace('_.gif','.gif'); - $self.css('background-image',source); - $sitemap.slideToggle('fast'); - }); - - }); - - // Search Auto Complete - var $search = $('div#header').find('fieldset.search'); - var $searchList = $search.find('#topAutocomplete>ul'); - - if($search.length){ - $search.find('> input').each(function(){ - $(this).bind({ - keydown : function(e){ - - if(e.type=='keydown'&& $(this).val().length!=0){ - $search.find('#topAutocomplete').show(); - var hei = $searchList.outerHeight(); - if(hei>400){ - $searchList.css({'height':'400px','overflow-y':'auto'}); - } - } - if(e.keyCode==9){ - $search.unbind('focusout.search'); - } - if(e.keyCode==40){ - $search.find('#topAutocomplete>ul').children(':first').find('a').focus(); - //window.scrollTo(0,0); - } - }, - focusin : function(e){ - if($(this).val()==='Search'){ - $(this).val(''); - } - }, - focusout : function(e){ - if($(this).val().length==0) $(this).val('Search'); - } - }); - }); - - //$('#topAutocomplete>ul').children().find('a').bind('focusin',function(e){ - // if(e.keyCode==40){ - // $(this).parent().next().css('border','1px solid red').find('a').focus(); - // } - //}); - - $search.find('#topAutocomplete').bind('mouseleave',function(e){ - if($search.find('> input').val().length==0){ - $search.find('> input').val('Search'); - } - $search.find('#topAutocomplete').hide(); - }); - - $search.find('#topAutocomplete>ul').children().last().focusout(function(){ - $search.find('> input').val('Search'); - $search.find('#topAutocomplete').hide(); - - //$search.bind('focusout.search', function(){ - // $(this).find('> input').val('Search'); - // $(this).find('#topAutocomplete').hide(); - //}); - }); - } -}); - -// 비차단 동적 스크립트 로딩 -function initScript(url, callback){ - var script = document.createElement("script"); - script.type = "text/javascript"; - - if(script.readyState){ // 인터넷 익스플로러 - script.onreadystatechange = function(){ - if(script.readyState=="loaded" || script.readyState=="complete"){ - script.onreadystatechange = null; - callback(); - } - }; - }else{ // 다른 브라우저 - script.onload = function(){ - callback(); - }; - } - - script.src = url; - document.getElementsByTagName("head")[0].appendChild(script); -} - - -// lnb -function initLnb(){ - var sMenu = $('.lnb'); - var sItem = sMenu.find('>li'); - - sItem.each(function(){ - if($(this).find('a').hasClass('more')){ - if($(this).find('ul').is(":visible")) { - $('').insertAfter($(this).find('a').eq(0)); - } else { - $('').insertAfter($(this).find('a').eq(0)); - } - } - }); - - var setIcoArrText = function(obj) { - if(obj.next().is(":visible")) { - obj.text("close submenu"); - } else { - obj.text("open submenu"); - } - } - - sItem.find('.ico-arr').on("click", function() { - var $that = $(this); - var liBox = $that.parent(); - var ulBox = $that.next(); - - sItem.not(liBox).not(".on").find("a.more").next().next().hide(); - sItem.not(liBox).removeClass("active").find("a").removeClass("bov"); - - if(liBox.hasClass("on")) { - if(ulBox.is(":visible")) { - ulBox.hide(); - $that.addClass("ico-on"); - } else { - ulBox.show(); - $that.removeClass("ico-on"); - } - setIcoArrText($that); - return true; - } - - if(liBox.hasClass("active")) { - liBox.removeClass("active").find("a").eq(0).removeClass("bov"); - ulBox.hide(); - } else { - liBox.addClass("active").find("a").eq(0).addClass("bov"); - ulBox.show(); - } - setIcoArrText($that); - }); - - sItem.hover(function(){ - if($(this).hasClass('on')||$(this).hasClass('active')) return false; - $(this).find("a").eq(0).addClass("bov"); - },function(){ - if($(this).hasClass('on')||$(this).hasClass('active')) return false; - $(this).find("a").eq(0).removeClass("bov"); - - }); -} - -//footer rolling banner -function fn_rollToEx(container,objectId,step,auto){ - - // 롤링할 객체를 변수에 담아둔다. - var el = $('#'+container).find('#'+objectId); - var lastChild; - var speed = 3000; - var timer = 0; - var autoplay = false; - - el.data('prev', $('#'+container).find('.prev')); //이전버튼을 data()메서드를 사용하여 저장한다. - el.data('next', $('#'+container).find('.next')); //다음버튼을 data()메서드를 사용하여 저장한다. - el.data('size', el.children().outerWidth()); //롤링객체의 자식요소의 넓이를 저장한다. - el.data('len', el.children().length); //롤링객체의 전체요소 개수 - el.data('animating',false); - el.data('step', step); //매개변수로 받은 step을 저장한다. - el.data('autoStart', false); //매개변수로 받은 step을 저장한다. - - el.css('width',el.data('size')*el.data('len')); //롤링객체의 전체넓이 지정한다. - - if(arguments.length==4){ - el.data('autoStart', auto); - } - - if(el.data('autoStart')){ - if(timer==0){ - timer = setInterval(moveNextSlide, speed); - autoplay = true; - } - } - - el.bind({ - mouseenter:function(){ - if(!autoplay) return false; - - if(timer!=0 && el.data('autoStart')){ - clearInterval(timer); - timer=0; - } - }, - mouseleave:function(){ - if(!autoplay) return false; - - if(timer==0 && el.data('autoStart')){ - timer = setInterval(moveNextSlide, speed); - } - } - }); - - - //el에 첨부된 prev 데이타를 클릭이벤트에 바인드한다. - el.data('prev').bind({ - click:function(e){ - e.preventDefault(); - movePrevSlide(); - }, - mouseenter:function(){ - - $(this).find('img').addClass('btnOn'); - - if(!autoplay) return false; - - if(timer!=0 && el.data('autoStart')){ - clearInterval(timer); - timer=0; - } - }, - mouseleave:function(){ - - $(this).find('img').removeClass('btnOn'); - - if(!autoplay) return false; - - if(timer==0 && el.data('autoStart')){ - timer = setInterval(moveNextSlide, speed); - } - } - }); - - //el에 첨부된 next 데이타를 클릭이벤트에 바인드한다. - el.data('next').bind({ - click:function(e){ - e.preventDefault(); - moveNextSlide(); - }, - mouseenter:function(){ - - $(this).find('img').addClass('btnOn'); - - if(!autoplay) return false; - - if(timer!=0 && el.data('autoStart')){ - clearInterval(timer); - timer=0; - } - }, - mouseleave:function(){ - - $(this).find('img').removeClass('btnOn'); - - if(!autoplay) return false; - - if(timer==0 && el.data('autoStart')){ - timer = setInterval(moveNextSlide, speed); - } - } - }); - - function movePrevSlide(){ - if(!el.data('animating')){ - //전달된 step개수 만큼 롤링객체의 끝에서 요소를 선택하여 복사한후 변수에 저장한다. - var lastItem = el.children().eq(-(el.data('step')+1)).nextAll().clone(true); - lastItem.prependTo(el); //복사된 요소를 롤링객체의 앞에 붙여놓는다. - el.children().eq(-(el.data('step')+1)).nextAll().remove(); //step개수만큼 선택된 요소를 끝에서 제거한다 - el.css('left','-'+(el.data('size')*el.data('step'))+'px'); //롤링객체의 left위치값을 재설정한다. - - el.data('animating',true); //애니메이션 중복을 막기 위해 첨부된 animating 데이타를 true로 설정한다. - - el.animate({'left': '0px'},'normal',function(){ //롤링객체를 left:0만큼 애니메이션 시킨다. - el.data('animating',false); - }); - } - return false; - } - - function moveNextSlide(){ - if(!el.data('animating')){ - el.data('animating',true); - - el.animate({'left':'-'+(el.data('size')*el.data('step'))+'px'},'normal',function(){ //롤링객체를 첨부된 size와 step을 곱한 만큼 애니메이션 시킨다. - //전달된 step개수 만큼 롤링객체의 앞에서 요소를 선택하여 복사한후 변수에 저장한다. - var firstChild = el.children().filter(':lt('+el.data('step')+')').clone(true); - firstChild.appendTo(el); //복사된 요소를 롤링객체의 끝에 붙여놓는다. - el.children().filter(':lt('+el.data('step')+')').remove(); //step개수만큼 선택된 요소를 앞에서 제거한다 - el.css('left','0px'); ////롤링객체의 left위치값을 재설정한다. - - el.data('animating',false); - }); - } - return false; - } - -} - -function fn_slide(options){ - - var opts = jQuery.extend({},options); - - var $bt = $('#'+opts.container).find('#'+opts.bt).children(); //롤링버튼에 대한 선택자 - var $obj = $('#'+opts.container).find('#'+opts.obj); //objectId를 id로 갖는 롤링객체의 선택자 - var $prev = $('#'+opts.container).find('#'+opts.prev).hide(); //이전버튼에 대한 선택자 - var $next = $('#'+opts.container).find('#'+opts.next); //다음버튼에 대한 선택자 - var size = $obj.children().outerWidth(); //롤링객체의 각 이미지 넓이값 - var len = $obj.children().length; //롤링객체의 이미지 갯수 - var effect = false; //슬라이드효과를 위한 boolean변수 - var auto = false; - var current = 0; //현재 보여지는 이미지의 인덱스값을 저장하기 위한 변수 - var time; - - - $obj.css('width',size*len); //롤링객체의 전체넓이 지정 - effect = opts.effect; - auto = opts.auto; - - if(auto){ - time = setTimeout('slideShow()',3000); - } - - slideShow = function(){ - - if(current < len-1){ - current++; - }else{ - current=0; - } - - controllStatus(); - - moveControl('next'); - - time = setTimeout('slideShow()',3000); - } - - controllStatus = function(){ - //이미지의 인덱스값에 따라 이전,다음 버튼 활성여부 지정 - if(current>0||current=len-1){ - $prev.show(); - $next.hide(); - } - } - - moveControl = function(msg){ - if(opts.bt!=null){ - msg=='next'? $bt.eq(current-1).find('img').attr('src', $bt.eq(current-1).find('img').attr('src').replace('_.png','.png')) - :$bt.eq(current+1).find('img').attr('src', $bt.eq(current-1).find('img').attr('src').replace('_.png','.png')); //이전에 활성화된 롤링버튼을 비활성화 - $bt.eq(current).find('img').attr('src', $bt.eq(current).find('img').attr('src').replace('.png','_.png')); //현재 인덱스값을 가지는 롤링버튼을 활성화 - } - - if(effect!=true){ //action변수가 true가 아닐경우 슬라이드 효과없이 현재의 인덱스값을 갖는 이미지를 보여줌. - $obj.children().hide(); - $obj.children().eq(current).show(); - }else{ //action변수가 true일 경우 현재의 인덱스값을 갖는 이미지로 슬라이드됨 - $obj.animate({'left':'-'+size*current},'slow'); - } - } - - $obj.bind({ - mouseenter:function(){ - if(!auto) return false; - clearTimeout(time); - }, - mouseleave:function(){ - if(!auto) return false; - time = setTimeout('slideShow()',3000); - } - }); - - //롤링 버튼 클릭시 - $bt.bind({ - mouseenter:function(){ - if(!auto) return false; - clearTimeout(time); - }, - mouseleave:function(){ - if(!auto) return false; - time = setTimeout('slideShow()',3000); - }, - click:function(){ - var idx = $bt.index(this); //클릭한 롤링버튼의 인덱스값 저장 - - current = idx; //롤링버튼의 인덱스값을 이미지의 인덱스값으로 지정 - - controllStatus(); - - if(effect!=true){ //action변수가 true가 아닐경우 슬라이드 효과없이 현재의 인덱스값을 갖는 이미지를 보여줌. - $obj.children().hide(); - $obj.children().eq(current).show(); - }else{ //action변수가 true일 경우 현재의 인덱스값을 갖는 이미지로 슬라이드됨 - $obj.animate({'left':'-'+size*current},'slow'); - } - - // 모든 롤링 버튼을 비활성화 - $bt.each(function(){ - var source = $(this).find('img').attr('src').replace('_.png','.png'); - $(this).find('img').attr('src',source); - }); - - // 선택한 롤링버튼을 활성화 - var source = $(this).find('img').attr('src').replace('.png','_.png'); - $(this).find('img').attr('src',source); - - return false; - } - }); - - //이전 버튼 클릭시 - $prev.bind({ - mouseenter:function(){ - var source = $(this).find('img').attr('src').replace('.png','_.png'); - $(this).find('img').attr('src',source); - if(!auto) return false; - clearTimeout(time); - }, - mouseleave:function(){ - var source = $(this).find('img').attr('src').replace('_.png','.png'); - $(this).find('img').attr('src',source); - if(!auto) return false; - time = setTimeout('slideShow()',3000); - }, - click:function(){ - if(current==len-1) $next.show(); //이미지 인덱스값이 마지막이 아닐경우 비활성화된 다음버튼을 활성화 - current--; //이미지 인덱스값 1씩 감소 - - moveControl('prev'); - - if(current==0) $(this).hide(); //이미지 인덱스값이 0일 경우, 즉 현재 첫번째 이미지가 활성화될 경우 이전버튼을 비활성화 - - return false; - } - }); - - //다음 버튼 클릭시 - $next.bind({ - mouseenter:function(){ - var source = $(this).find('img').attr('src').replace('.png','_.png'); - $(this).find('img').attr('src',source); - if(!auto) return false; - clearTimeout(time); - }, - mouseleave:function(){ - var source = $(this).find('img').attr('src').replace('_.png','.png'); - $(this).find('img').attr('src',source); - if(!auto) return false; - time = setTimeout('slideShow()',3000); - }, - click:function(){ - current++; //이미지 인덱스값 1씩 증가 - - moveControl('next'); - - if(current>=len-1) $(this).hide(); //이미지인덱스값이 마지막일 경우, 즉 현재 마지막 이미지가 활성화될 경우 다음버튼을 비활성화 - if(current>0) $prev.show(); //이미지인덱스값이 0이 아닌경우 이전버튼 활성화 - - return false; - } - }); - -} - -// main rolling banner -function slideMotion1(){ - var $banner = $('#rolling .motionview'), - //$nav = $('#rolling ul.nav'), - banner = {prev:null, next:null}, - size = $banner.children().length; - index = 1, - speed = 3000, - timer = null, - auto = true, - width = parseInt(100/size), - rest = parseInt(100%size); - - var $nav = $(' diff --git a/org.tizen.guides/html/web/tizen/communication/comm_guide_w.htm b/org.tizen.guides/html/web/tizen/communication/comm_guide_w.htm index 06e740f..ad6ad5c 100644 --- a/org.tizen.guides/html/web/tizen/communication/comm_guide_w.htm +++ b/org.tizen.guides/html/web/tizen/communication/comm_guide_w.htm @@ -41,7 +41,7 @@
  • Secure Element

    Allows you to access secure elements, such as SIM card and secure SD card, in a device.

-

The following guides apply in mobile applications only:

+

The following guides apply in mobile applications only:

  • Messaging

    Allows you to create applications with messaging functionalities using SMS, MMS, and email.

diff --git a/org.tizen.guides/html/web/tizen/guides_tizen_w.htm b/org.tizen.guides/html/web/tizen/guides_tizen_w.htm index 47529cb..336a51c 100644 --- a/org.tizen.guides/html/web/tizen/guides_tizen_w.htm +++ b/org.tizen.guides/html/web/tizen/guides_tizen_w.htm @@ -67,19 +67,19 @@

Enables you to access and manage and retrieve information from the device and its sensors.

  • User Interface

    Enables you to manage badges and notifications on the screen.

  • -
  • Social in mobile applications only +
  • Social in mobile applications only

    Enables you to manage the user's personal data, such as contacts, calendars, and call and browsing history, on the device.

  • +

    For more information about implementing the UI for your application using the Advanced UI Framework (TAU) features, see TAU.

    +

    In addition to the Tizen Web Device API guides above, you can study the following features:

    • Localization

      Enables you to internationalize your application.

    • -
    • Tizen Advanced UI Framework (TAU) -

      Enables you to create and manage various kinds of UI components.

    • -
    • Service Application in wearable applications only

      Allows you to create wearable Web service applications.

    • +
    • Service Application in wearable applications only

      Allows you to create wearable Web service applications.

    • -
    • IME Application in wearable applications only

      Enables you to implement IME (Input Method Editor) applications to provide IME support for client applications.

    • +
    • IME Application in wearable applications only

      Enables you to implement IME (Input Method Editor) applications to provide IME support for client applications.

    diff --git a/org.tizen.guides/html/web/tizen/multimedia/media_key_w.htm b/org.tizen.guides/html/web/tizen/multimedia/media_key_w.htm index e48817e..40873b7 100644 --- a/org.tizen.guides/html/web/tizen/multimedia/media_key_w.htm +++ b/org.tizen.guides/html/web/tizen/multimedia/media_key_w.htm @@ -1,90 +1,90 @@ - - - - - - - - - - - - - Media Key - - - - - -
    -

    Media Key

    - -

    Tizen enables you to handle media keys in your application.

    - - - - - - - - - - -
    Note
    The Media Key API is optional for both Tizen mobile and wearable profiles, which means that it may not be supported in all mobile and wearable devices. -

    The Media Key API is not supported on any Tizen Emulators.

    - -

    The media keys are used to control multimedia playback. The user can click keys, such as PLAY and FAST FORWARD, and you can detect the key clicks in your application and change the playback accordingly.

    - -

    The main features of the Media Key API include:

    -
      -
    • Registering a listener

      You can register and unregister a listener for the media key state changes.

      - - - - - - - - - -
      Note
      You can register only 1 media key state change listener for your application. If you attempt to register a second listener, the first listener is unset and replaced with the new one.
      -
    • -
    • Handling state changes

      With the registered listener, you can monitor the media keys and react to their state changes, when the user presses or releases a key.

    • -
    - - - -
    - -Go to top - - - - - - + + + + + + + + + + + + + Media Key + + + + + +
    +

    Media Key

    + +

    Tizen enables you to handle media keys in your application.

    + + + + + + + + + + +
    Note
    The Media Key API is optional for both Tizen mobile and wearable profiles, which means that it may not be supported in all mobile and wearable devices. +

    The Media Key API is not supported on any Tizen Emulators.

    + +

    The media keys are used to control multimedia playback. The user can click keys, such as PLAY and FAST FORWARD, and you can detect the key clicks in your application and change the playback accordingly.

    + +

    The main features of the Media Key API include:

    +
      +
    • Registering a listener

      You can register and unregister a listener for the media key state changes.

      + + + + + + + + + +
      Note
      You can register only 1 media key state change listener for your application. If you attempt to register a second listener, the first listener is unset and replaced with the new one.
      +
    • +
    • Handling state changes

      With the registered listener, you can monitor the media keys and react to their state changes, when the user presses or releases a key.

    • +
    + + + +
    + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/web/tizen/multimedia/multimedia_guide_w.htm b/org.tizen.guides/html/web/tizen/multimedia/multimedia_guide_w.htm index b776a1c..f14f6c1 100644 --- a/org.tizen.guides/html/web/tizen/multimedia/multimedia_guide_w.htm +++ b/org.tizen.guides/html/web/tizen/multimedia/multimedia_guide_w.htm @@ -1,64 +1,64 @@ - - - - - - - - - - - - - Multimedia - - - - - -
    -

    Multimedia

    -

    Multimedia features include managing the device sound volume and media keys.

    -

    The main multimedia features are:

    -
      -
    • Media Controller

      Enables you to communicate between the media controller server and client.

    • -
    • Media Key

      Enables you to handle media keys in your application.

    • -
    • Sound

      Enables you to control the volume level of several sound types and get information about the current sound mode and the state of the current sound devices.

    • -
    - - - -
    - -Go to top - - - - - - + + + + + + + + + + + + + Multimedia + + + + + +
    +

    Multimedia

    +

    Multimedia features include managing the device sound volume and media keys.

    +

    The main multimedia features are:

    +
      +
    • Media Controller

      Enables you to communicate between the media controller server and client.

    • +
    • Media Key

      Enables you to handle media keys in your application.

    • +
    • Sound

      Enables you to control the volume level of several sound types and get information about the current sound mode and the state of the current sound devices.

    • +
    + + + +
    + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/web/tizen/multimedia/sound_w.htm b/org.tizen.guides/html/web/tizen/multimedia/sound_w.htm index 65f857d..497bf6d 100644 --- a/org.tizen.guides/html/web/tizen/multimedia/sound_w.htm +++ b/org.tizen.guides/html/web/tizen/multimedia/sound_w.htm @@ -1,80 +1,80 @@ - - - - - - - - - - - - - Sound - - - - - -
    -

    Sound

    - -

    Tizen enables you to control the volume level of several sound types and get information about the current sound mode and the state of the current sound devices. The available sound types include, for example, system, notifications, alarms, and media.

    - - - - - - - - - - -
    Note
    The Sound API is mandatory for both Tizen mobile and wearable profiles, which means that it is supported in all mobile and wearable devices. -

    All mandatory APIs are supported on the Tizen Emulators.

    - -

    The main features of the Sound API include:

    - - - - -
    - -Go to top - - - - - - + + + + + + + + + + + + + Sound + + + + + +
    +

    Sound

    + +

    Tizen enables you to control the volume level of several sound types and get information about the current sound mode and the state of the current sound devices. The available sound types include, for example, system, notifications, alarms, and media.

    + + + + + + + + + + +
    Note
    The Sound API is mandatory for both Tizen mobile and wearable profiles, which means that it is supported in all mobile and wearable devices. +

    All mandatory APIs are supported on the Tizen Emulators.

    + +

    The main features of the Sound API include:

    + + + + +
    + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/web/tizen/social/social_guide_w.htm b/org.tizen.guides/html/web/tizen/social/social_guide_w.htm index 228604e..e1fc8e7 100644 --- a/org.tizen.guides/html/web/tizen/social/social_guide_w.htm +++ b/org.tizen.guides/html/web/tizen/social/social_guide_w.htm @@ -53,9 +53,9 @@
  • Calendar

    Allows you to manage calendars, events, and tasks on a device.

  • Call History

    Allows you to search, manage, and monitor the call history of a device.

  • Contact

    Allows you to manage address books and contacts on a device.

  • -
  • Data Synchronization

    Allows you to synchronize device data, such as contacts and calendar events, with the OMA DS server.

  • +
  • Data Synchronization

    Allows you to synchronize device data, such as contacts and calendar events, with the OMA DS server.

  • - + @@ -77,4 +77,4 @@ var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga - + \ No newline at end of file diff --git a/org.tizen.guides/html/web/tizen/system/fm_radio_w.htm b/org.tizen.guides/html/web/tizen/system/fm_radio_w.htm index 3c07e3a..9de359b 100644 --- a/org.tizen.guides/html/web/tizen/system/fm_radio_w.htm +++ b/org.tizen.guides/html/web/tizen/system/fm_radio_w.htm @@ -1,88 +1,88 @@ - - - - - - - - - - - - - FM Radio - - - -
    -
    -

    Mobile Web

    -
    - - -
    - -
    -

    FM Radio

    - -

    Tizen enables you to access and control the FM radio on the device.

    - - - - - - - - - - -
    Note
    This feature is supported in mobile applications only.
    - -

    The main features of the FM Radio API include:

    - -

    The available operations depend on the current radio state. Radio states and transitions between them are illustrated in the following figure.

    -

    Figure: FM radio states and transitions

    -

    FM radio states and transitions

    -

    To get information about current radio state, read the state attribute of the FMRadioManager interface. The RadioState enum specifies possible values of the attribute:

    -
      -
    • READY: Initial state, the radio is not playing and can be started or switched to scan.
    • -
    • PLAYING: The playback is ongoing.
    • -
    • SCANNING: The frequency scan is in progress, the radio is not playing.
    • -
    - - - -
    - -Go to top - - - - - - + + + + + + + + + + + + + FM Radio + + + +
    +
    +

    Mobile Web

    +
    + + +
    + +
    +

    FM Radio

    + +

    Tizen enables you to access and control the FM radio on the device.

    + + + + + + + + + + +
    Note
    This feature is supported in mobile applications only.
    + +

    The main features of the FM Radio API include:

    + +

    The available operations depend on the current radio state. Radio states and transitions between them are illustrated in the following figure.

    +

    Figure: FM radio states and transitions

    +

    FM radio states and transitions

    +

    To get information about current radio state, read the state attribute of the FMRadioManager interface. The RadioState enum specifies possible values of the attribute:

    +
      +
    • READY: Initial state, the radio is not playing and can be started or switched to scan.
    • +
    • PLAYING: The playback is ongoing.
    • +
    • SCANNING: The frequency scan is in progress, the radio is not playing.
    • +
    + + + +
    + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/web/tizen/system/system_guide_w.htm b/org.tizen.guides/html/web/tizen/system/system_guide_w.htm index 284d7ef..2805215 100644 --- a/org.tizen.guides/html/web/tizen/system/system_guide_w.htm +++ b/org.tizen.guides/html/web/tizen/system/system_guide_w.htm @@ -43,7 +43,7 @@
  • Time

    Enables you to use locale-specific calendar features by retrieving date and time information, and manage time features, such as the time zone.

  • -

    The following guides apply in mobile applications only:

    +

    The following guides apply in mobile applications only:

    • FM Radio

      Enables you to access and control the device FM radio.

    • Web Setting

      Enables you to set Web view properties, such as setting Web view user agents and deleting Web view cookies.

    • diff --git a/org.tizen.guides/html/web/tizen/tizen/tizen_guide_w.htm b/org.tizen.guides/html/web/tizen/tizen/tizen_guide_w.htm index 761a167..11fa506 100644 --- a/org.tizen.guides/html/web/tizen/tizen/tizen_guide_w.htm +++ b/org.tizen.guides/html/web/tizen/tizen/tizen_guide_w.htm @@ -1,1023 +1,1023 @@ - - - - - - - - - - - - - Tizen - - - - - -
      -

      Tizen

      -

      Tizen features include handling events and organizing data.

      - - - - - - - - - - -
      Note
      The Tizen API is mandatory for both Tizen mobile and wearable profiles, which means that it is supported in all mobile and wearable devices. -

      All mandatory APIs are supported on the Tizen Emulators.

      - -

      The main Tizen features are:

      - - -

      Handling Exceptions

      -

      You can enable the Tizen APIs to throw errors synchronously with the WebAPIException interface (in mobile and wearable applications) of the Tizen API (in mobile and wearable applications), or return errors in the error event handlers of asynchronous methods with the WebAPIError interface (in mobile and wearable applications).

      - - - - - - - - - -
      Note
      Do not use the code attribute of the WebAPIException interface to distinguish errors, because the code of the exception object is set to 0 in case of new error types that are not defined in DOMException.
      - -

      Handling Generic Events

      -

      Generic event handling features allow you to handle the results of asynchronous operations. The operations can implemented using the SuccessCallback (in mobile and wearable applications) and ErrorCallback (in mobile and wearable applications) event handlers of the Tizen API.

      - -

      Managing Location Coordinates

      - -

      You can use the SimpleCoordinates interface (in mobile and wearable applications) to incorporate location information into your application. For example, you can simply use it to define coordinates:

      var coordinates = new tizen.SimpleCoordinates(37.5665, 126.9779);

      You can also define a latitude and longitude for a calendar event:

      var event = new tizen.CalendarEvent(
      -{
      -   description:"hospital", 
      -   geolocation: new tizen.SimpleCoordinates(37.4889, 127.0876),
      -   startDate: new tizen.TZDate(2011, 11, 1, 14, 0), 
      -   duration: new tizen.TimeDuration(2, "HOURS")
      -});
      - -

      Sorting and Filtering Data

      -

      The Tizen API provides a set of basic definitions and interfaces that are used in the Tizen Device API. The Tizen API contains filters and sorting modes for query methods, generic success and error event handlers, a generic error interface, and a simple coordinate interface for defining location information.

      -

      The main features of the Tizen API include:

      -
        -
      • Filters

        The Tizen API supports the following filter types, which are subtypes of the abstract filter (in mobile and wearable applications):

        -
          -
        • Attribute filter (in mobile and wearable applications)

          Matches objects containing a defined attribute or attribute value. The match is determined based on match flags defined with the FilterMatchFlag type definition (in mobile and wearable applications).

        • -
        • Attribute range (in mobile and wearable applications)

          Matches objects containing an attribute whose values are within a particular range.

        • -
        • Composite filter (in mobile and wearable applications)

          Combines several filters into a set.

        • -
        -

        You can create attribute filters, attribute range filters, and composite filters to search for specific data and make complex queries. The attributes you can use with the filter types vary depending on the API you are using. For example, Calendar, Call History, Contact, Content, and Messaging query methods each have their own sets of supported filter attributes.

      • -
      • Sorting

        You can sort the results of queried data using the SortMode interface (in mobile and wearable applications). The following sorting modes are supported:

        -
          -
        • "ASC": Ascending sorting order

        • -
        • "DESC": Descending sorting order

        • -
        - - - - - - - - - -
        Note

        If you use a type attribute as a sort mode parameter, the sorting is not performed alphabetically since the attribute values are stored normally after the type conversion in the platform implementation.

        For example, if the ContentType enum (in mobile and wearable applications) is the type attribute and the sorting order is "DESC", the sorting result is ordered according to the listed enum order:

        -
          -
        • Image
        • Video
        • Audio
        • Other
      -

      Calendar Filter Attributes

      -

      The following table lists the filter types you can use with specific calendar item attributes in the methods of the Calendar interface.

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      - Table: Calendar filter attributes -
      AttributeAttribute filter supportedAttribute range filter supported

      id

      Yes

      No

      id.uid

      Yes

      No

      description

      Yes

      No

      summary

      Yes

      No

      isAllDay

      Yes

      No

      isDetached

      Yes

      No

      startDate

      Yes

      Yes

      location

      Yes

      No

      geolocation.latitude

      Yes

      Yes

      geolocation.longitude

      Yes

      Yes

      organizer

      Yes

      No

      visibility

      Yes

      No

      status

      Yes

      No

      priority

      Yes

      No

      categories

      Yes

      No

      dueDate

      Yes

      Yes

      completedDate

      Yes

      Yes

      progress

      Yes

      Yes

      endDate

      Yes

      Yes

      availability

      Yes

      No

      lastModificationDate

      Yes

      Yes

      alarms

      No*

      No

      attendees

      No*

      No

      recurrenceRule

      No*

      No

      -

      * The attribute filter is only supported with the EXISTS flag.

      -

      Call History Filter Attributes

      -

      The following table lists the filter types you can use with specific call history attributes in the methods of the CallHistory interface.

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      - Table: Call History filter attributes -
      AttributeAttribute filter supportedAttribute range filter supported

      uid

      Yes

      Yes

      type

      Yes

      No

      features

      Yes

      No

      remoteParties.remoteParty

      Yes

      Yes

      remoteParties.personId

      Yes

      Yes

      startTime

      Yes

      Yes

      duration

      Yes

      Yes

      direction

      Yes

      No

      -

      Contact Filter Attributes

      -

      The following table lists the filter types you can use with specific contact attributes in the methods of the AddressBook interface.

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      - Table: Contact filter attributes -
      AttributeAttribute filter supportedAttribute range filter supported

      id

      Yes

      Yes

      personId

      Yes

      Yes

      lastUpdated

      Yes

      Yes

      isFavorite

      Yes

      Yes

      birthday

      Yes

      Yes

      photoURI

      Yes

      No

      ringtoneURI

      Yes

      No

      name.prefix

      Yes

      No

      name.suffix

      Yes

      No

      name.firstName

      Yes

      No

      name.middleName

      Yes

      No

      name.lastName

      Yes

      No

      name.nicknames

      Yes

      No

      name.phoneticFirstName

      Yes

      No

      name.phoneticLastName

      Yes

      No

      name.displayName

      Yes

      No

      addresses.country

      Yes

      No

      addresses.region

      Yes

      No

      addresses.city

      Yes

      No

      addresses.streetAddress

      Yes

      No

      addresses.additionalInformation

      Yes

      No

      addresses.postalCode

      Yes

      No

      addresses.isDefault

      Yes

      No

      addresses.types

      No

      No

      phoneNumbers.number

      Yes

      No

      phoneNumbers.isDefault

      Yes

      No

      phoneNumbers.types

      No

      No

      emails.email

      Yes

      No

      emails.isDefault

      Yes

      No

      emails.types

      No

      No

      anniversaries.date

      Yes

      Yes

      anniversaries.label

      Yes

      No

      organizations.name

      Yes

      No

      organizations.department

      Yes

      No

      organizations.title

      Yes

      No

      organizations.role

      Yes

      No

      organizations.logoUri

      Yes

      No

      urls.url

      Yes

      No

      urls.type

      No

      No

      groupIds

      Yes

      Yes

      -

      The following table lists the filter types you can use with specific person attributes in the methods of the ContactManager interface.

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      - Table: Person filter attributes -
      AttributeAttribute filter supportedAttribute range filter supported

      id

      Yes

      No

      displayName

      Yes

      No

      contactCount

      Yes

      Yes

      hasPhoneNumber

      Yes

      No

      hasEmail

      Yes

      No

      isFavorite

      Yes

      No

      photoURI

      Yes

      No

      ringtoneURI

      Yes

      No

      displayContactId

      Yes

      No

      -

      Content Filter Attributes

      -

      The following table lists the filter types you can use with specific content attributes in the methods of the ContentManager interface (in mobile and wearable applications).

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      - Table: Content filter attributes -
      AttributeAttribute filter supportedAttribute range filter supported

      id

      Yes

      No

      type

      Yes

      No

      mimeType

      No

      No

      name

      Yes

      No

      title

      Yes

      No

      contentURI

      Yes

      No

      thumbnailURIs

      Yes

      No

      releaseDate

      Yes

      Yes

      modifedDate

      Yes

      Yes

      size

      No

      No

      description

      Yes

      No

      rating

      Yes

      Yes

      geolocation.latitude

      Yes

      Yes

      geolocation.longitude

      Yes

      Yes

      album

      Yes

      No

      genres

      Yes

      No

      artists

      Yes

      No

      composers

      No

      No

      lyrics

      No

      No

      copyright

      No

      No

      bitrate

      No

      No

      trackNumber

      No

      No

      duration

      No

      No

      orientation

      No

      No

      -

      Messaging Filter Attributes

      -

      The following tables list the filter types you can use with specific message attributes in the methods of the MessageStorage interface.

      -

      The following table lists the filter attributes related to the findMessage() method.

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      - Table: Filter attributes for finding messages -
      AttributeAttribute filter supportedAttribute range filter supported

      id

      Yes

      No

      serviceId

      Yes

      No

      conversationId

      No

      No

      folderId

      Yes

      No

      type

      Yes

      No

      timestamp

      No

      Yes

      from

      Yes

      No

      to

      Yes

      No

      cc

      Yes

      No

      bcc

      Yes

      No

      body.plainBody

      Yes

      No

      isRead

      Yes

      No

      hasAttachment

      Yes

      No

      isHighPriority

      Yes

      No

      subject

      Yes

      No

      isResponseTo

      No

      No

      messageStatus

      No

      No

      attachments

      No

      No

      -

      The following table lists the filter attributes related to the findConversations() method.

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      - Table: Filter attributes for finding conversations -
      AttributeAttribute filter supportedAttribute range filter supported

      id

      Yes

      No

      type

      Yes

      No

      timestamp

      No

      Yes

      messageCount

      Yes

      No

      unreadMessages

      Yes

      No

      preview

      Yes

      No

      subject

      No

      No

      isRead

      No

      No

      from

      Yes

      No

      to

      Yes

      No

      cc

      No

      No

      bcc

      No

      No

      lastMessageId

      No

      No

      -

      The following table lists the filter attributes related to the findFolders() method.

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      - Table: Filter attributes for finding message folders -
      AttributeAttribute filter supportedAttribute range filter supported

      id

      No

      No

      parentId

      No

      No

      serviceId

      Yes

      No

      contentType

      No

      No

      name

      No

      No

      path

      No

      No

      type

      No

      No

      synchronizable

      No

      No

      - - - - - - - - - - -
      Note
      The FULLSTRING value of the FilterMatchFlag enumerator (in mobile and wearable applications) is not supported and returns an error callback.
      - - - - -
      - -Go to top - - - - - - + + + + + + + + + + + + + Tizen + + + + + +
      +

      Tizen

      +

      Tizen features include handling events and organizing data.

      + + + + + + + + + + +
      Note
      The Tizen API is mandatory for both Tizen mobile and wearable profiles, which means that it is supported in all mobile and wearable devices. +

      All mandatory APIs are supported on the Tizen Emulators.

      + +

      The main Tizen features are:

      + + +

      Handling Exceptions

      +

      You can enable the Tizen APIs to throw errors synchronously with the WebAPIException interface (in mobile and wearable applications) of the Tizen API (in mobile and wearable applications), or return errors in the error event handlers of asynchronous methods with the WebAPIError interface (in mobile and wearable applications).

      + + + + + + + + + +
      Note
      Do not use the code attribute of the WebAPIException interface to distinguish errors, because the code of the exception object is set to 0 in case of new error types that are not defined in DOMException.
      + +

      Handling Generic Events

      +

      Generic event handling features allow you to handle the results of asynchronous operations. The operations can implemented using the SuccessCallback (in mobile and wearable applications) and ErrorCallback (in mobile and wearable applications) event handlers of the Tizen API.

      + +

      Managing Location Coordinates

      + +

      You can use the SimpleCoordinates interface (in mobile and wearable applications) to incorporate location information into your application. For example, you can simply use it to define coordinates:

      var coordinates = new tizen.SimpleCoordinates(37.5665, 126.9779);

      You can also define a latitude and longitude for a calendar event:

      var event = new tizen.CalendarEvent(
      +{
      +   description:"hospital", 
      +   geolocation: new tizen.SimpleCoordinates(37.4889, 127.0876),
      +   startDate: new tizen.TZDate(2011, 11, 1, 14, 0), 
      +   duration: new tizen.TimeDuration(2, "HOURS")
      +});
      + +

      Sorting and Filtering Data

      +

      The Tizen API provides a set of basic definitions and interfaces that are used in the Tizen Device API. The Tizen API contains filters and sorting modes for query methods, generic success and error event handlers, a generic error interface, and a simple coordinate interface for defining location information.

      +

      The main features of the Tizen API include:

      +
        +
      • Filters

        The Tizen API supports the following filter types, which are subtypes of the abstract filter (in mobile and wearable applications):

        +
          +
        • Attribute filter (in mobile and wearable applications)

          Matches objects containing a defined attribute or attribute value. The match is determined based on match flags defined with the FilterMatchFlag type definition (in mobile and wearable applications).

        • +
        • Attribute range (in mobile and wearable applications)

          Matches objects containing an attribute whose values are within a particular range.

        • +
        • Composite filter (in mobile and wearable applications)

          Combines several filters into a set.

        • +
        +

        You can create attribute filters, attribute range filters, and composite filters to search for specific data and make complex queries. The attributes you can use with the filter types vary depending on the API you are using. For example, Calendar, Call History, Contact, Content, and Messaging query methods each have their own sets of supported filter attributes.

      • +
      • Sorting

        You can sort the results of queried data using the SortMode interface (in mobile and wearable applications). The following sorting modes are supported:

        +
          +
        • "ASC": Ascending sorting order

        • +
        • "DESC": Descending sorting order

        • +
        + + + + + + + + + +
        Note

        If you use a type attribute as a sort mode parameter, the sorting is not performed alphabetically since the attribute values are stored normally after the type conversion in the platform implementation.

        For example, if the ContentType enum (in mobile and wearable applications) is the type attribute and the sorting order is "DESC", the sorting result is ordered according to the listed enum order:

        +
          +
        • Image
        • Video
        • Audio
        • Other
      +

      Calendar Filter Attributes

      +

      The following table lists the filter types you can use with specific calendar item attributes in the methods of the Calendar interface.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      + Table: Calendar filter attributes +
      AttributeAttribute filter supportedAttribute range filter supported

      id

      Yes

      No

      id.uid

      Yes

      No

      description

      Yes

      No

      summary

      Yes

      No

      isAllDay

      Yes

      No

      isDetached

      Yes

      No

      startDate

      Yes

      Yes

      location

      Yes

      No

      geolocation.latitude

      Yes

      Yes

      geolocation.longitude

      Yes

      Yes

      organizer

      Yes

      No

      visibility

      Yes

      No

      status

      Yes

      No

      priority

      Yes

      No

      categories

      Yes

      No

      dueDate

      Yes

      Yes

      completedDate

      Yes

      Yes

      progress

      Yes

      Yes

      endDate

      Yes

      Yes

      availability

      Yes

      No

      lastModificationDate

      Yes

      Yes

      alarms

      No*

      No

      attendees

      No*

      No

      recurrenceRule

      No*

      No

      +

      * The attribute filter is only supported with the EXISTS flag.

      +

      Call History Filter Attributes

      +

      The following table lists the filter types you can use with specific call history attributes in the methods of the CallHistory interface.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      + Table: Call History filter attributes +
      AttributeAttribute filter supportedAttribute range filter supported

      uid

      Yes

      Yes

      type

      Yes

      No

      features

      Yes

      No

      remoteParties.remoteParty

      Yes

      Yes

      remoteParties.personId

      Yes

      Yes

      startTime

      Yes

      Yes

      duration

      Yes

      Yes

      direction

      Yes

      No

      +

      Contact Filter Attributes

      +

      The following table lists the filter types you can use with specific contact attributes in the methods of the AddressBook interface.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      + Table: Contact filter attributes +
      AttributeAttribute filter supportedAttribute range filter supported

      id

      Yes

      Yes

      personId

      Yes

      Yes

      lastUpdated

      Yes

      Yes

      isFavorite

      Yes

      Yes

      birthday

      Yes

      Yes

      photoURI

      Yes

      No

      ringtoneURI

      Yes

      No

      name.prefix

      Yes

      No

      name.suffix

      Yes

      No

      name.firstName

      Yes

      No

      name.middleName

      Yes

      No

      name.lastName

      Yes

      No

      name.nicknames

      Yes

      No

      name.phoneticFirstName

      Yes

      No

      name.phoneticLastName

      Yes

      No

      name.displayName

      Yes

      No

      addresses.country

      Yes

      No

      addresses.region

      Yes

      No

      addresses.city

      Yes

      No

      addresses.streetAddress

      Yes

      No

      addresses.additionalInformation

      Yes

      No

      addresses.postalCode

      Yes

      No

      addresses.isDefault

      Yes

      No

      addresses.types

      No

      No

      phoneNumbers.number

      Yes

      No

      phoneNumbers.isDefault

      Yes

      No

      phoneNumbers.types

      No

      No

      emails.email

      Yes

      No

      emails.isDefault

      Yes

      No

      emails.types

      No

      No

      anniversaries.date

      Yes

      Yes

      anniversaries.label

      Yes

      No

      organizations.name

      Yes

      No

      organizations.department

      Yes

      No

      organizations.title

      Yes

      No

      organizations.role

      Yes

      No

      organizations.logoUri

      Yes

      No

      urls.url

      Yes

      No

      urls.type

      No

      No

      groupIds

      Yes

      Yes

      +

      The following table lists the filter types you can use with specific person attributes in the methods of the ContactManager interface.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      + Table: Person filter attributes +
      AttributeAttribute filter supportedAttribute range filter supported

      id

      Yes

      No

      displayName

      Yes

      No

      contactCount

      Yes

      Yes

      hasPhoneNumber

      Yes

      No

      hasEmail

      Yes

      No

      isFavorite

      Yes

      No

      photoURI

      Yes

      No

      ringtoneURI

      Yes

      No

      displayContactId

      Yes

      No

      +

      Content Filter Attributes

      +

      The following table lists the filter types you can use with specific content attributes in the methods of the ContentManager interface (in mobile and wearable applications).

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      + Table: Content filter attributes +
      AttributeAttribute filter supportedAttribute range filter supported

      id

      Yes

      No

      type

      Yes

      No

      mimeType

      No

      No

      name

      Yes

      No

      title

      Yes

      No

      contentURI

      Yes

      No

      thumbnailURIs

      Yes

      No

      releaseDate

      Yes

      Yes

      modifedDate

      Yes

      Yes

      size

      No

      No

      description

      Yes

      No

      rating

      Yes

      Yes

      geolocation.latitude

      Yes

      Yes

      geolocation.longitude

      Yes

      Yes

      album

      Yes

      No

      genres

      Yes

      No

      artists

      Yes

      No

      composers

      No

      No

      lyrics

      No

      No

      copyright

      No

      No

      bitrate

      No

      No

      trackNumber

      No

      No

      duration

      No

      No

      orientation

      No

      No

      +

      Messaging Filter Attributes

      +

      The following tables list the filter types you can use with specific message attributes in the methods of the MessageStorage interface.

      +

      The following table lists the filter attributes related to the findMessage() method.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      + Table: Filter attributes for finding messages +
      AttributeAttribute filter supportedAttribute range filter supported

      id

      Yes

      No

      serviceId

      Yes

      No

      conversationId

      No

      No

      folderId

      Yes

      No

      type

      Yes

      No

      timestamp

      No

      Yes

      from

      Yes

      No

      to

      Yes

      No

      cc

      Yes

      No

      bcc

      Yes

      No

      body.plainBody

      Yes

      No

      isRead

      Yes

      No

      hasAttachment

      Yes

      No

      isHighPriority

      Yes

      No

      subject

      Yes

      No

      isResponseTo

      No

      No

      messageStatus

      No

      No

      attachments

      No

      No

      +

      The following table lists the filter attributes related to the findConversations() method.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      + Table: Filter attributes for finding conversations +
      AttributeAttribute filter supportedAttribute range filter supported

      id

      Yes

      No

      type

      Yes

      No

      timestamp

      No

      Yes

      messageCount

      Yes

      No

      unreadMessages

      Yes

      No

      preview

      Yes

      No

      subject

      No

      No

      isRead

      No

      No

      from

      Yes

      No

      to

      Yes

      No

      cc

      No

      No

      bcc

      No

      No

      lastMessageId

      No

      No

      +

      The following table lists the filter attributes related to the findFolders() method.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      + Table: Filter attributes for finding message folders +
      AttributeAttribute filter supportedAttribute range filter supported

      id

      No

      No

      parentId

      No

      No

      serviceId

      Yes

      No

      contentType

      No

      No

      name

      No

      No

      path

      No

      No

      type

      No

      No

      synchronizable

      No

      No

      + + + + + + + + + + +
      Note
      The FULLSTRING value of the FilterMatchFlag enumerator (in mobile and wearable applications) is not supported and returns an error callback.
      + + + + +
      + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/web/w3c/communication/comm_guide_w.htm b/org.tizen.guides/html/web/w3c/communication/comm_guide_w.htm index 0b54af0..97ee093 100644 --- a/org.tizen.guides/html/web/w3c/communication/comm_guide_w.htm +++ b/org.tizen.guides/html/web/w3c/communication/comm_guide_w.htm @@ -39,7 +39,7 @@
    • XMLHttpRequest Level 1 and 2

      Enables you to use cross-origin resource sharing (CORS) to request and send data of various content types, and to monitor the operation progress.

    -

    The following guides apply in mobile applications only:

    +

    The following guides apply in mobile applications only:

    diff --git a/org.tizen.guides/html/web/w3c/device/device_guide_w.htm b/org.tizen.guides/html/web/w3c/device/device_guide_w.htm index 4b32703..7bcf749 100644 --- a/org.tizen.guides/html/web/w3c/device/device_guide_w.htm +++ b/org.tizen.guides/html/web/w3c/device/device_guide_w.htm @@ -40,7 +40,7 @@
  • Vibration

    Enables you to implement different vibration patterns on a Tizen device.

  • -

    The following guides apply in mobile applications only:

    +

    The following guides apply in mobile applications only:

    • HTML5 Browser state

      Enables you to retrieve information about the network connection state of the browser.

    • Screen Orientation

      Enables you to retrieve the current screen orientation state, monitor state changes, and lock the screen to a specific orientation.

    • diff --git a/org.tizen.guides/html/web/w3c/device/screen_orientation_w.htm b/org.tizen.guides/html/web/w3c/device/screen_orientation_w.htm index 2401794..a3e1c1d 100644 --- a/org.tizen.guides/html/web/w3c/device/screen_orientation_w.htm +++ b/org.tizen.guides/html/web/w3c/device/screen_orientation_w.htm @@ -1,114 +1,114 @@ - - - - - - - - - - - - - Screen Orientation - - - - - -
      -

      Screen Orientation

      - - - - - - - - - - -
      Note
      This feature is supported in mobile applications only.
      - -

      You can manage the screen orientation state through the Screen interface.

      - -

      The main features of the Screen Orientation API include:

      - -
      • Accessing the current screen orientation -

        You can use the current screen orientation information, for example, to define the visibility or dimensions of the HTML elements according to the orientation state. You can retrieve the state with the screen.orientation attribute. -

        The following code snippet demonstrates how to access the current screen orientation information.

        -
        -var currentScreenOrientation = screen.orientation;
        -
        - -

        The orientation can be portrait-primary, portrait-secondary, landscape-primary, or landscape-secondary.

      • - -
      • Reacting to screen orientation changes -

        To receive notifications of the screen orientation changes, add an event listener to the Screen object, or assign a function reference to the screen.onorientationchange attribute.

        -

        The following code snippet demonstrates how to receive notifications of screen orientation changes.

        -
        -/* Add listener */
        -screen.addEventListener("orientationchange", handleScreenOrientationFun, false);
        -
        -/* Or assign reference */
        -screen.onorientationchange = handleScreenOrientationFun;
        -
        - -

        In the above example, the handleScreenOrientationFun is the event handler called when the screen orientation changes.

      • - -
      • Locking the screen to a specified orientation -

        Locking means that the rendering of the current browsing context is forced to be shown in the specified orientation. The screen remains in the selected orientation state until the lock is removed.

        -

        Lock the screen with the lockOrientation() method. -

        The following code snippet demonstrates how to lock the screen to a specified orientation.

        -
        screen.lockOrientation("portrait-secondary");
        -
        -

        The method accepts the following parameter values: portrait-primary, portrait-secondary, landscape-primary, landscape-secondary, portrait, and landscape.

        - - - - - - - - - -
        Note
        When using the screen orientation lock: -
        • When the portrait value is used to lock the orientation, the orientation can change between portrait-primary and portrait-secondary. The landscape value behaves similarly.
        • -
        • Depending on the browser, unlocking the screen orientation may have no visual effect.
        -
      - - - -
      - -Go to top - - - - - - + + + + + + + + + + + + + Screen Orientation + + + + + +
      +

      Screen Orientation

      + + + + + + + + + + +
      Note
      This feature is supported in mobile applications only.
      + +

      You can manage the screen orientation state through the Screen interface.

      + +

      The main features of the Screen Orientation API include:

      + +
      • Accessing the current screen orientation +

        You can use the current screen orientation information, for example, to define the visibility or dimensions of the HTML elements according to the orientation state. You can retrieve the state with the screen.orientation attribute. +

        The following code snippet demonstrates how to access the current screen orientation information.

        +
        +var currentScreenOrientation = screen.orientation;
        +
        + +

        The orientation can be portrait-primary, portrait-secondary, landscape-primary, or landscape-secondary.

      • + +
      • Reacting to screen orientation changes +

        To receive notifications of the screen orientation changes, add an event listener to the Screen object, or assign a function reference to the screen.onorientationchange attribute.

        +

        The following code snippet demonstrates how to receive notifications of screen orientation changes.

        +
        +/* Add listener */
        +screen.addEventListener("orientationchange", handleScreenOrientationFun, false);
        +
        +/* Or assign reference */
        +screen.onorientationchange = handleScreenOrientationFun;
        +
        + +

        In the above example, the handleScreenOrientationFun is the event handler called when the screen orientation changes.

      • + +
      • Locking the screen to a specified orientation +

        Locking means that the rendering of the current browsing context is forced to be shown in the specified orientation. The screen remains in the selected orientation state until the lock is removed.

        +

        Lock the screen with the lockOrientation() method. +

        The following code snippet demonstrates how to lock the screen to a specified orientation.

        +
        screen.lockOrientation("portrait-secondary");
        +
        +

        The method accepts the following parameter values: portrait-primary, portrait-secondary, landscape-primary, landscape-secondary, portrait, and landscape.

        + + + + + + + + + +
        Note
        When using the screen orientation lock: +
        • When the portrait value is used to lock the orientation, the orientation can change between portrait-primary and portrait-secondary. The landscape value behaves similarly.
        • +
        • Depending on the browser, unlocking the screen orientation may have no visual effect.
        +
      + + + +
      + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/web/w3c/dom/animation_w.htm b/org.tizen.guides/html/web/w3c/dom/animation_w.htm deleted file mode 100644 index 54eef78..0000000 --- a/org.tizen.guides/html/web/w3c/dom/animation_w.htm +++ /dev/null @@ -1,192 +0,0 @@ - - - - - - - - - - - - - CSS Animations Module Level 3 - - - - - - -
      -

      CSS Animations Module Level 3

      - -

      Animations (like transitions) change the presentational value of the CSS properties over time. The principal difference between animations and transitions is that while transitions are triggered implicitly when property values change, animations are explicitly executed when the animation properties are applied. This means that for animations, you must use animation keyframes to define explicit values for the properties being animated.

      - -

      When using the CSS animation properties, the Tizen browser requires the -webkit- prefix.

      - -

      Keyframes

      -

      The CSS animations work based on @-webkit-keyframes rules defined for specific elements. The rules can define various property changes complementing the simple running of a transition.

      -

      If the animation only has one set of changes over its whole iteration, the rule values can be assigned with a from {} to {} rule, where from is the beginning of the animation at 0% and to is the end at 100%. If there are multiple changes required, you can define their exact time periods using multiple <number>% {} rules that together cover the entire animation iteration from 0% to 100%.

      -

      The following code snippet demonstrates how to use keyframes. For a complete source code, see animation_keyframes.html

      -
      -<style type="text/css">
      -
      -   @-webkit-keyframes boxani 
      -   {
      -      from {left: 0; top: 0;}
      -      to {left: 100px; top: 100px;}
      -   }
      -   @-webkit-keyframes boxani_case01 
      -   {
      -      0% {left: 0; top: 0;}
      -      25% {left: 100px; top: 0;}
      -      50% {left: 100px; top: 100px;}
      -      75% {left: 0; top: 100px;}
      -      100% {left: 0; top: 0;}
      -   }
      -
      -</style>
      -
      - -

      Animation Properties

      - -

      You can define various properties for an animation to control how it is played:

      - -
        -
      • animation-name -

        This property uses the name defined in the @-webkit-keyframes rules to play the animation.

      • - -
      • animation-duration -

        This property defines how long one iteration of the animation takes.

      • - -
      • animation-iteration-count -

        This property defines how many times the animation is repeated. If the value is set as infinite, the repetitions are unlimited.

      • - -
      • animation-timing-function -

        This property defines the pace of the animation.

      • - -
      • animation-direction -

        This property defines the replay direction. The reverse value plays the animation from 100% keyframe to 0% keyframe, while the alternate value plays the animation normally during odd iterations, and from 100% keyframe to 0% keyframe during even iterations.

      • - -
      • animation-play-state -

        This property defines the replay status of the animation. The paused value temporarily stops the animation.

      • -
      • animation-delay -

        This property defines the delay time before the start of the animation.

      • - -
      • animation-fill-mode -

        This property defines the state of the animation before or after the animation is played. The forwards value maintains the last value of the keyframe rule when the animation is over, while the backwards value fills up the first value of the keyframe rule when the animation with the animation-delay property is in a standby state. The both value covers both the start and the end of the animation.

      - -

      The following code snippet demonstrates how to use animation properties. For a complete source code, see:

      - - -
      -<head>
      -   <style type="text/css">
      -      .box 
      -      {
      -         -webkit-animation-name: boxani;
      -         -webkit-animation-duration: 5s;
      -         -webkit-animation-iteration-count: infinite;
      -         -webkit-animation-timing-function: linear;
      -         -webkit-animation-direction: normal;
      -         -webkit-animation-delay: 1s;
      -         -webkit-animation-fill-mode: none;
      -      }
      -
      -      .box.case01: hover 
      -      {
      -         -webkit-animation-play-state: paused;
      -         -webkit-animation-fill-mode: forwards;
      -      }
      -   </style>
      -</head>
      -
      -<body>
      -   <h1>animation-name</h1>
      -   <div class="boxarea">
      -      <div class="box">
      -         <p>animate</p>
      -         <p>animation-name: boxani;</p>
      -      </div>
      -   </div>
      -   <div class="boxarea">
      -      <div class="box case01">
      -         <p>animate</p>
      -         <p>animation-name: boxani_case01;</p>
      -      </div>
      -   </div>
      -</body>
      -
      - - - - - - - - - -
      Note
      The hover pseudo class in Tizen maintains a mouseover state when an element is tapped, and becomes a mouseout state when another element is tapped.
      - -

      The animation property allows you to define all the animation properties in a shorthand mode in the order of animation-name | animation-duration | animation-timing-function | animation-delay | animation-iteration-count | animation-direction | animation-fill-mode. If you omit a property value, a default value is used instead.

      - -
      -<style type="text/css">
      -   .box 
      -   {
      -      width: 150px; height: 100px; background: Coral; position: relative;
      -      -webkit-animation: boxani 3s ease 1s infinite alternate backwards;
      -   }
      -</style>
      -
      - - - -
      - -Go to top - - - - - - - \ No newline at end of file diff --git a/org.tizen.guides/html/web/w3c/dom/background_w.htm b/org.tizen.guides/html/web/w3c/dom/background_w.htm deleted file mode 100644 index 48e6e30..0000000 --- a/org.tizen.guides/html/web/w3c/dom/background_w.htm +++ /dev/null @@ -1,130 +0,0 @@ - - - - - - - - - - - - - CSS Backgrounds and Borders Module Level 3 - - - - - - -
      -

      CSS Backgrounds and Borders Module Level 3

      - -

      You can manage the CSS properties for specifying the border style or background of any HTML element.

      - -

      When creating a background for an element, you can use the following properties:

      -
        -
      • background-color -

        Defines the color of the background.

      • -
      • background-image -

        Defines the image to be used. You can add images as separate layers to an element. To add multiple images, separate them by commas to add each image as a separate layer. The images are added in the order they are defined.

      • -
      • background-position -

        Defines the exact position of the image.

      • -
      • background-repeat -

        Defines whether the image is repeated to fill the entire background (in case the image is too small to do it otherwise).

      • -
      • background-origin -

        Defines the position of the initial background for the item.

      • -
      • background-size -

        Defines the size of the image in the background.

      • -
      • background-clip -

        Defines the area of the cropped background element.

      • -
      - -

      The border properties specify the line thickness, style, and color for the element border. You can define the border using 3 separate properties (border-width, border-style, and border-color), or by listing the values for all 3 properties together in 1 border property. To define rounded corners for the border, you can additionally use the border-radius property.

      - -

      To define shading for an element, you can define the horizontal and vertical offset, blur radius, and the spread distance values within the box-shadow property. To switch the shadow from outside to inside the element, add the inset keyword to the property too.

      - -

      The following image shows a simple background color (top left), a background image (top right), multiple images with a solid black border (bottom left), and an element with shading and a solid black border with rounded corners (bottom right). The background image at top right is automatically repeated to cover the entire background, while the images at bottom left are not repeated due to the background-repeat property value.

      - -

      Figure: Background examples

      -

      Background examples

      -

      The following code snippet demonstrates how to set the background color, images, borders, and shadings.

      - -
      -<!--Background color-->
      -#one 
      -{
      -   width: 180px;
      -   height: 40px;
      -   background-color: lightblue;
      -}
      -
      -<!--Background image--> 
      -#one 
      -{
      -   width: 200px;
      -   height: 100px;
      -   background-color: #00F;
      -   background-image: url(t3.png);
      -}
      -
      -<!--Multiple images--> 
      -#multi 
      -{
      -   width: 155px;
      -   height: 100px;
      -   border: 1px solid #000;
      -   background-color: #87CEFA;
      -   background-image: url(t1.png), url(t2.png), url(t3.png);
      -   background-position: center center, 20% 100%, top left;
      -   background-repeat: no-repeat;
      -}
      -
      -<!--Shading and border with rounded corners-->
      -#shading 
      -{
      -   width: 160px;
      -   height: 40px;
      -   border: 1px solid #000;
      -   border-radius: 20px;
      -   background-color: #88f;
      -   box-shadow: #888 10px 10px;
      -}
      -
      - - - -
      - -Go to top - - - - - - - \ No newline at end of file diff --git a/org.tizen.guides/html/web/w3c/dom/basic_ui_w.htm b/org.tizen.guides/html/web/w3c/dom/basic_ui_w.htm deleted file mode 100644 index f9d27d3..0000000 --- a/org.tizen.guides/html/web/w3c/dom/basic_ui_w.htm +++ /dev/null @@ -1,83 +0,0 @@ - - - - - - - - - - - - - CSS Basic User Interface Module Level 3 (CSS3 UI) - - - - - - -
      -

      CSS Basic User Interface Module Level 3 (CSS3 UI)

      - -

      You can apply styles to HTML documents.

      -

      The CSS3 version has caused changes in the Selector, Color, Web Form, and Fonts CSS modules. In addition, the CSS3 UI API also handles changes related to the following user interface items:

      -
        -
      • User interface selectors -

        The CSS Selector is an essential module for applying a CSS to HTML in order to enable the DOM element selection. The pseudo-element selectors can be used to assign the user interface state. With the selectors, you can change the Web form style according to the user input without using JavaScript.

      • - -
      • Box model properties -

        A box model refers to all DOM elements excluding design elements, such as <br> and <i>. The box model area is set as defined in the following figure.

        -
          -
        • Content: Content area
        • -
        • Padding: Gap between the content and boundary
        • -
        • Border: Boundary
        • -
        • Margin: Overall size of the box model
        • -
        -

        Figure: Box model structure

        -

        Figure: Box model structure

        - -

        You can use the box model properties to assign styles to the selected DOM elements:

        -
          -
        • The box-sizing property assigns the box size range.
        • -
        • The outline properties make the box outstanding.
        • -
        • The text-overflow property handles the text extending outside the box.
        -
      • -
      - - - -
      - -Go to top - - - - - - - \ No newline at end of file diff --git a/org.tizen.guides/html/web/w3c/dom/color_w.htm b/org.tizen.guides/html/web/w3c/dom/color_w.htm deleted file mode 100644 index b5b20c9..0000000 --- a/org.tizen.guides/html/web/w3c/dom/color_w.htm +++ /dev/null @@ -1,149 +0,0 @@ - - - - - - - - - - - - - CSS Color Module Level 3 - - - - - - -
      -

      CSS Color Module Level 3

      - -

      You can manage the CSS properties for specifying the color and opacity of an HTML element, and the CSS color value type.

      - - - - - - - - - - -
      Note

      The CSS2 System Color values have been deprecated in favor of the CSS3 UI 'appearance' property.

      - -

      You can specify the color of an element with the following formats:

      -
        -
      • Keyword values -

        You can use basic keywords, such as red, green, blue, or deepskyblue, as defined in Extended color keywords.

        -

        The currentColor keyword can be used with all properties that accept a color value (borders, box shadows, outlines, or backgrounds). The computed value of the currentColor keyword is the computed value of the color property. If the currentColor keyword is set on the color property itself, it is treated as color: inherit. -

        -

        You can use the transparent keyword with all properties that accept a color value (borders, box shadows, outlines, or backgrounds), to turn the element in question transparent (invisible).

        -
      • -
      • RGB values -
          -
        • In hexadecimal notation -

          The format is '#' followed by either 3 or 6 hexadecimal characters. The 3-digit RGB notation (#rgb) is converted into a 6-digit form (#rrggbb) by replicating digits. For example, #fc0 expands to #ffcc00.

        • -
        • In functional notation -

          The format is 'rgb(' followed by a comma-separated list of 3 numerical values (integer or percentage) followed by ')'. The integer value 255 corresponds to 100%, and to F or FF in a hexadecimal notation: rgb(255, 255, 255) = rgb(100%, 100%, 100%) = #FFF. White space characters are allowed around the numerical values. -

        • -
        -
      • -
      • RGBA values -

        The RGB color model is extended to include "alpha" to allow the color opacity to be specified. The RGBA values are defined using functional notation where the final value is the alpha (range from 0.1 to 1). For example: rgba(255, 0, 0, 0.7).

        -
      • -
      • HSL value -

        You can use numerical hue-saturation-lightness (HSL) colors as an alternative to numerical RGB colors. The HSL colors are encoded as a triple (hue, saturation, lightness). The hue is represented as the angle of the color circle, where by definition red=0°=360° and other colors are spread around the circle. The saturation and lightness are represented as percentages, where 100% is full saturation or black lightness, and 0% is a shade of gray or white lightness. 50% lightness is "normal". For example: hsl(0, 100%, 50%). -

      • -
      • HSLA value -

        The HSL color model is extended to include "alpha" to allow the color opacity to be specified. The HSLA values are defined using the HSL notation where a final alpha value is added (range from 0.1 to 1). For example: hsla(120, 100%, 50%, 0.8).

      • -
      -

      The following code snippet demonstrates how to specify a color for an element. For a complete source code, see:

      - -
      -<!--Keywords-->
      -#one
      -{
      -   color: blue;
      -   background: white;
      -   border: 1px solid springgreen;
      -}
      -#one span 
      -{
      -   background: currentColor;
      -}
      -#one span.hide
      -{
      -   color: transparent;
      -}
      -
      -<!--RGB-->
      -#two
      -{
      -    color: #ff0000;
      -}
      -
      -<!--RGBA-->
      -#three
      -{
      -   color: rgba(100%, 0, 0, 0.5);
      -}
      -
      -<!--HSL-->
      -#four
      -{
      -   color: hsl(0, 100%, 50%);
      -}
      -
      -<!--HSLA-->
      -#five
      -{
      -   color: hsla(0, 100%, 50%, 0.5);
      -}
      -
      - - - -
      - -Go to top - - - - - - - \ No newline at end of file diff --git a/org.tizen.guides/html/web/w3c/dom/dom_guide_w.htm b/org.tizen.guides/html/web/w3c/dom/dom_guide_w.htm deleted file mode 100644 index 7836fa7..0000000 --- a/org.tizen.guides/html/web/w3c/dom/dom_guide_w.htm +++ /dev/null @@ -1,82 +0,0 @@ - - - - - - - - - - - - - DOM, Forms and Styles - - - - - -
      - -

      DOM, Forms and Styles

      -

      DOM, forms and styles features include all aspects of using various CSS styles and HTML5 forms.

      -

      The main DOM, forms and styles features are:

      - - -

      The following guides apply in mobile applications only:

      - - - - - -
      - -Go to top - - - - - - - \ No newline at end of file diff --git a/org.tizen.guides/html/web/w3c/dom/flexible_w.htm b/org.tizen.guides/html/web/w3c/dom/flexible_w.htm deleted file mode 100644 index 0266eb8..0000000 --- a/org.tizen.guides/html/web/w3c/dom/flexible_w.htm +++ /dev/null @@ -1,69 +0,0 @@ - - - - - - - - - - - - - CSS Flexible Box Layout Module - - - - - -
      -

      CSS Flexible Box Layout Module

      - -

      CSS attributes, such as float, display, and position, can be used to adjust and align the screen layout according to various resolutions. However, operating the layout accurately among changing screen sizes is difficult.

      - -

      Tizen supports the CSS Flexible Box Layout Module API that enables you to create an easily manageable flexible layout, which fluidly adjusts the layout according to viewport size changes. When you create and use a flexible box layout, the alignment method or object (flex item) size within a specific area (flex container) can be adjusted.

      -

      The main components of the flexible box layout include:

      -
        -
      • Flex container, which refers to flex or inline-flex DOM elements assigned by the display.

        You can use the flex container to assign a flex area and the flex items included in it. The flex container properties are used to assign the indication area and alignment method.

      • -
      • Flex item, which refers to the child nodes of the flex container. -

        The flex item changes its size fluidly according to the area of the flex container. You can define flex item properties to assign the sizes of the respective items and the alignment method.

      • -
      -

      Figure: Flexible box layout

      -

      Flexible box layout

      - - - -
      - -Go to top - - - - - - - \ No newline at end of file diff --git a/org.tizen.guides/html/web/w3c/dom/font_w.htm b/org.tizen.guides/html/web/w3c/dom/font_w.htm deleted file mode 100644 index 2e38106..0000000 --- a/org.tizen.guides/html/web/w3c/dom/font_w.htm +++ /dev/null @@ -1,66 +0,0 @@ - - - - - - - - - - - - - CSS Fonts Module Level 3 - - - - - - -
      -

      CSS Fonts Module Level 3

      - -

      You can change the text fonts easily.

      - -

      The new text features in CSS Fonts Module Level 3 API include:

      -
        -
      • Font properties -

        You can use CSS font properties, such as font-style, font-weight, font-variant, font-size, and font-family, to modify the appearance of text.

      • -
      - - - -
      - -Go to top - - - - - - - \ No newline at end of file diff --git a/org.tizen.guides/html/web/w3c/dom/html5forms_w.htm b/org.tizen.guides/html/web/w3c/dom/html5forms_w.htm deleted file mode 100644 index 90717b9..0000000 --- a/org.tizen.guides/html/web/w3c/dom/html5forms_w.htm +++ /dev/null @@ -1,302 +0,0 @@ - - - - - - - - - - - - - HTML5 Forms - - - - - -
      - -

      HTML5 Forms

      - -

      The HTML5 forms provide a convenient way to create consistent screens in your application for accepting user input. In the past, the Web form allowed you to accept user input before transmitting it to a server. With HTML5, you can now improve the user experience without having to use JavaScript by adding simple features, for example, email validity checks and date pickers, and using more advanced functionality, such as security checks and input value pattern definitions.

      - -

      New HTML5 Elements

      -

      The following table lists the new elements available for your forms in HTML5. For a complete source code, see elements.html.

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      Table: New HTML5 elements
      ElementDescriptionExample
      datalist

      Defines a set of option elements that represent predefined options for other controls. The element is used together with the input element to predefine its value.

      -

      In Tizen, the value selected in the datalist element can be edited.

      -
      -<input type="text" list="search">
      -<datalist id="search">
      -   <option value="Tomato">Tomato</option>
      -   <option value="banana">banana</option>
      -   <option value="Watermelon">Watermelon</option>
      -</datalist>
      -
      -
      keygen

      Defines a control for generating a public-private key pair and for submitting the public key from that key pair. The element creates an encrypted key with the value of the name attribute, saves it in the user's computer and Web server, and activates the next procedure when the 2 values match.

      -
      -<label>user:<input type="text" name="user_name"></label>
      -<label>keygen:<keygen name="keygen"></label>
      -
      -
      meter

      Represents a scalar measurement within a known range (the distribution of the assigned range), or a fractional value.

      -
      -<meter value="75" min="0" max="100" low="60" high="80" optimum="81">
      -   75/100
      -</meter>
      -
      -
      output

      Represents the result of a calculation. The element generally shows the calculated result of the value that the user has entered, and is used within the form element.

      -
      -<fieldset onsubmit="return false"
      -          oninput="foobar.value = parseInt(foo.value) * parseInt(bar.value)">
      -   <input type="number" id="foo" name="foo"> *
      -   <input type="number" id="bar" name="bar"> =
      -   <output for="foo bar" name="foobar"></output>
      -</fieldset>
      -
      -
      progress

      Represents the progress of a task.

      -
      -<progress value="75" max="100">
      -   75/100
      -</progress>
      -
      - -

      New Input Element Types

      -

      The following table lists the new input element types available for your forms in HTML5. Many of the new elements activate a specific keyboard suitable for the type of value the user is expected to enter (for example, an email or URL). For a complete source code, see types.html.

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      Table: New input element types
      TypeDescriptionExample
      color

      Select an HSL color from the color picker. The value format is HEX (#0099ff).

      -
      -
      -<input type="color"
      -       value="#ff0000">
      -<input type="datetime"
      -       value="2012-12-12T03:30Z">
      -<input type="email"
      -       required>
      -<input type="number"
      -       step="3">
      -<input type="range"
      -       min="1" max="10">
      -<input type="tel">
      -<input type="url">
      -
      -
      date

      Enter a date with no time zone (yyyy-mm-dd).

      -
      datetime

      Enter a date and time with the (UTC) time zone (yyyy-mm-ddTtt:mmZ).

      - -
      datetime-local

      Enter a date and time with no time zone (yyyy-mm-ddTtt:mm).

      -
      email

      Enter an email address with the email keyboard.

      -

      If the required attribute is used, the system checks whether the input format is in line with the ABNF regular expression (1*(atext / ".") "@" ldh-str 1*("." ldh-str)).

      -
      month

      Enter a year and month with no time zone (yyyy-mm).

      -
      number

      Enter numbers with the number keyboard.

      -
      range

      Select a value from the slider.

      -
      search

      No specific functionality is defined for this element in the HTML5 specifications.

      -
      tel

      Enter a phone number with the number keyboard.

      -
      time

      Enter a time with no time zone (tt:mm:ss).

      -
      url

      Enter a URL with the URL keyboard.

      -
      week

      Enter a year and week with no time zone (yyyy-week).

      -
      - -

      New Input Element Attributes

      - -

      The following table lists the new input element attributes available for your forms in HTML5. For a complete source code, see attributes.html.

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      Table: New input element attributes
      AttributeDescriptionExample
      autocomplete

      Prefilling feature, which helps the users by, for example, prefilling the user's address based on earlier user input.

      -

      The text used by the user before (such as an input element) is listed in a datalist form. The attribute can be used in all form elements, and is activated if the value is "on" and deactivated if the value is "off".

      -
      -
      -<input type="range" min="1" max="10">
      -<input type="tel" pattern="[0-9]+" required>
      -<input placeholder="You know what to do, huh?">
      -<input type="number" step="3">
      -
      -
      min and max

      Allowed range of values for the element.

      -
      pattern

      Regular expression against which the control's value is checked.

      -

      The attribute can be used to check the validity of the form data. During service, a guide requiring the input format from the user is necessary.

      -
      placeholder

      Short hint intended to aid the user with the data entry.

      -

      The attribute can be used in the majority of form elements for various purposes, such as hint text or advertisement.

      -
      required

      Boolean attribute which, when specified, defines that the element is mandatory.

      -
      step

      Granularity expected of the value, limiting the allowed values.

      -
      - - - -
      - -Go to top - - - - - - - \ No newline at end of file diff --git a/org.tizen.guides/html/web/w3c/dom/media_query_w.htm b/org.tizen.guides/html/web/w3c/dom/media_query_w.htm deleted file mode 100644 index cdf7ed8..0000000 --- a/org.tizen.guides/html/web/w3c/dom/media_query_w.htm +++ /dev/null @@ -1,245 +0,0 @@ - - - - - - - - - - - - - Media Queries - - - - - -
      -

      Media Queries

      - -

      Media queries allow you to apply the CSS differently according to the media type (type of device) and media features (viewport status). Previously, you were able to use the media type only and create Web services with fixed layouts. However, smart phones, tablets, and other devices with various resolutions require a liquid layout. HTML5 now makes various characteristics and conditional defining possible, and can be used to implement responsive Web design (RWD), which is a liquid layout that mainly reacts according to the device resolution.

      - -

      You can use media queries in 3 ways:

      - -
        -
      • In CSS -

        You can define attribute values depending on given conditions:

        -
        @media only screen and (max-width: 480px) {styles}
        -
        - - - - - - - - - -
        Note
        This approach is popular since it can reduce style overlapping; however, if all the styles are applied to 1 CSS, the maintenance work efficiency decreases.
        -
      • -
      • In an @import rule in CSS -

        You can import from CSS a file that matches the condition:

        -
        @import url(example.css) not screen and (min-width: 480px)
        -
        -
      • -
      • In HTML -

        You can directly import the CSS file that matches the condition:

        -
        <link rel="stylesheet" media="all and (max-width: 480px)" href="example.css">
        - - - - - - - - - -
        Note
        The disadvantage of this approach is that every time the condition is expanded, the HTML file must be edited. However, since this approach only imports the CSS files that match the condition, the file transmission amount can be reduced.
        -
      • -
      - -

      For more information on the CSS priorities when different media queries are used, see Media Query Priorities.

      - -

      Media Query Conditions

      - -

      You can define the following conditions for the media queries:

      - -
        -
      • Combination and relevancy -

        You can combine multiple conditions into 1 Boolean query with the and operator. To define a negative condition (something not being relevant), use the not operator.

        -
        @media not screen and (min-width: 320px), screen and (max-width: 480px) 
        -{
        -   .example: after {content: "width: 320px ~ 480px"}
        -}
        -
        -
      • -
      • Viewport width -

        You can define the query to match to a specific viewport width range using the min-width and max-width attributes.

        -
        @media all and (min-width: 320px) and (max-width: 480px) 
        -{
        -   .example: after {content: "width: 320px ~ 480px"}
        -}
        -
        -
      • -
      • Device and viewport height -

        The height attribute refers to restoring the viewport's height, and the device-height attribute refers to restoring the resolution set in the device.

        -

        The same difference applies to the width and aspect-ratio attributes, which can assign 'device-'.

        -
        @media screen and (min-device-height: 700px) 
        -{
        -   .example: after {content: "min-device-height"}
        -}
        -@media screen and (min-height: 550px) 
        -{
        -   .example: after {content: "min-height"}
        -}
        -
        -

        In the above example, a device with the width-height resolution of 480/720 has the {content: "min-height"} rule applied as a priority in a portrait screen, but the {content "min-device-height"} rule applied in a landscape screen.

        - -
      • -
      • Device aspect ratio -

        You can use the device-aspect-ratio attribute to check the width-length ratio (aspect ratio) of the printing device.

        -
        @media all and (device-aspect-ratio: 9/16) and (orientation: portrait),  
        -       all and (device-aspect-ratio: 2/3) and (orientation: portrait) 
        -{
        -   .example: after {content: "aspect-ratio, portrait"}
        -}
        -
        - - - - - - - - - -
        Note
        The device aspect ratio is a reliable way to distinguish the portrait and landscape modes of a smart phone. However, because the aspect ratio of all the devices has to be specified, a precise rule is hard to define. (Currently wildly used screen ratios are 15:9, 16:10, 16:9, 3:2, and 4:3, but devices with other screen ratios may be added in the future.)
        -
      • -
      - -

      Media Query Priorities

      - -

      When multiple media queries and conditions are defined, CSS is applied with the following priorities:

      -
        -
      • In case of the CSS reiteration declaration, the CSS that has been declared last is applied.
      • -
      • In case of specificity, the CSS with the highest specificity is applied. -

        The specificity is calculated as follows:

        • id attribute = 100
        • -
        • class attribute = 10
        • -
        • element = 1
        -

        Selectors, such as section#content > .title p, carry the specificity of 112.

      • -
      • In case of user override, the user CSS is applied instead of the creator CSS.
      • -
      • CSS is applied first based on the conditions in the @import rule, then based on the conditions in CSS, and finally based on the conditions in HTML.

      • -
      • In media queries, regardless of CSS priority, CSS which has not been imported still exists based on the conditions.

      • -
      - -

      To apply media query, consider an example with the following files:

      -
      -<!--example.html-->
      -<link rel="stylesheet" media="all and (max-width: 768px)" href="c.css">
      -<link rel="stylesheet" media="all and (max-width: 768px)" href="a.css">
      -<link rel="stylesheet" media="all and (min-width: 768px)" href="b.css">
      -<style>
      -   @media all and (max-width: 400px) 
      -   {
      -      .example: after {content: "In HTML head"}
      -   }
      -</style>
      -
      -<!--a.css-->
      -body {background-color: #ccc}
      -
      -@media screen and (max-width: 480px) 
      -{
      -   .example: after {content:"a.css : width: ~ 480px"}
      -}
      -@media screen and (min-width: 480px) and (max-width: 768px) 
      -{
      -   .example: after {content: "a.css : width: 480px ~ 768px"}
      -}
      -
      -<!--b.css-->
      -@import url("c.css");
      -
      -body {background-color: #333; color: #fff}
      -
      -@media screen and (min-width: 768px) and (max-width: 1024px) 
      -{
      -   .example: after {content: "b.css : width: 768px ~ 1024px"}
      -}
      -
      -<!--c.css-->
      -body {background-color: tomato}
      -
      -@media screen and (min-width: 768px) and (max-width: 1024px) 
      -{
      -   .example: after {content: "c.css : width: 768px ~ 1024px"}
      -}
      -@media screen and (min-width: 1024px) and (max-width: 1280px) 
      -{
      -   .example: after {content: "c.css : width: 1024px ~ 1280px"}
      -}
      -
      - -

      The CSS is applied based on the viewport:

      -
        -
      • If the viewport is 320 px: -
          -
        • The a.css file is applied (based on content: "a.css : width: ~ 480px").
        • -
        • The c.css and b.css files are not imported.
        • -
        • CSS is applied instead of the HTML <head> (the a.css file has higher priority than content: "In HTML head").
        • -
      • -
      • If the viewport is 700 px: -
        • The a.css file is applied (based on content: "a.css : width: 480px ~ 768px").

        • -
        • The c.css and b.css files are not imported.
      • -
      • If the viewport is 900 px: -
          -
        • The b.css file is imported.
        • -
        • c.css is applied (based on content: "c.css : width: 768px ~ 1024px").
        • -
        • The a.css file is not imported.
        • -
        • The b.css file is applied (based on content: "b.css : width: 768px ~ 1024px").
        • -
      • -
      - - - -
      - -Go to top - - - - - - - \ No newline at end of file diff --git a/org.tizen.guides/html/web/w3c/dom/multi_w.htm b/org.tizen.guides/html/web/w3c/dom/multi_w.htm deleted file mode 100644 index 00f9575..0000000 --- a/org.tizen.guides/html/web/w3c/dom/multi_w.htm +++ /dev/null @@ -1,218 +0,0 @@ - - - - - - - - - - - - - CSS Multi-column Layout Module - - - - - -
      -

      CSS Multi-column Layout Module

      - - - - - - - - - - -
      Note
      This feature is supported in mobile applications only.
      - -

      You can arrange the screen content into columns. Using the CSS column- properties, the content elements can flow between columns when the column height or number changes. You can use the properties alone to create a basic layout, or add JavaScript code to make the layout dynamic.

      - -

      You can manage the following column-related features:

      - - - - - - - - - - - -
      Note
      Up to Tizen SDK version 2.2, most CSS properties and values used in Tizen required the -webkit- prefix. To ensure future compatibility, these properties can now be used with or without the prefix.
      -

      Setting the Column Number and Width

      - -

      When the layout is set to a constant number of columns using the column-count (or -webkit-column-count) property, the column width is set to fill the available horizontal space.

      -

      In the following code snippet and figure, the column number is set to 4. As a result, on a 480 x 800 display (shown on the top), the column width is 116 px, whereas on a 720 x 1280 display (shown on the bottom), the column with is 143 px.

      -

      The following code snippet demonstrates how to use the column-count property. For a complete source code, see multi_column_column_count/renamed_index.html.

      -
      -article
      -{
      -   column-count: 4;
      -   -webkit-column-count: 4;
      -   margin: 10px;
      -}
      -
      - -

      Figure: 4 columns on different resolution displays

      -

      4 columns on different resolution displays

      - -

      The column-width (or -webkit-column-width) property sets the base column width.

      -

      In the following code snippet and figure, the column width is set to 153 px, but the effective column width is 288 px for a 480 x 800 display (shown on the left) and 154 px for a 720 x 1280 display (shown on the right). The parameter sets the column to at least the defined width, but not wider than the available display space or twice the defined width. The actual column width is calculated using a pseudo-algorithm.

      -

      The code snippet shows how the multi-column layout is implemented when the vertical space is limited. If there is more content than fits the available space, the next column is set outside the available space. Using the overflow: scroll property, the column can be scrolled horizontally.

      -

      The following code snippet demonstrates how to use the column-width property. For a complete source code, see multi_column_column_width/renamed_index.html.

      -
      -article
      -{
      -   width: 90vw;
      -   height: 90vh;
      -   column-width: 153px;
      -   -webkit-column-width: 153px;
      -   margin: 5vw;
      -   background: #c3c8ca;
      -   overflow: scroll;
      -}
      -
      - -

      Figure: Column width 153 px on different resolution displays

      -

      Column width 153 px on different resolution displays

      - -

      Setting the Column Gap

      -

      The column-gap (or -webkit-column-gap) property sets the distance between columns. The property affects the column width, as the column width, gap, and margins all take available space. In the following code snippet and figure, the column gap is set to 17 px.

      -

      The following code snippet demonstrates how to use the column-gap property. For a complete source code, see multi_column_column_gap/renamed_index.html.

      -
      -article 
      -{
      -   height: 303px;
      -   column-width: 153px;
      -   -webkit-column-width: 153px;
      -   column-gap: 17px;
      -   -webkit-column-gap: 17px;
      -   margin: 7px;
      -   padding: 3px;
      -   background: #c3c8ca;
      -}
      -
      - -

      Figure: Column gap

      -

      Column gap

      - -

      Setting the Column Rule

      -

      The column-rule (or -webkit-column-rule) property displays a vertical line in the middle of the column gap.

      -

      The rule has analogical parameters, such as width, line style, and color, but its size is not included in the available space, and it is a drawing similar to the background.

      - -

      Rules are only displayed in the content area. If the padding property is set in the same element, the rule appears shorter than the background. In the following code snippet and figure, the rule width is set to 5 px.

      -

      The following code snippet demonstrates how to use the column-rule property. For a complete source code, see multi_column_column_rule/renamed_index.html.

      -
      article 
      -{
      -   -webkit-column-rule-width: 5px;
      -   -webkit-column-rule-color: rgb(92, 203, 246);
      -   -webkit-column-rule-style: solid;
      -}
      -
      - -

      Figure: Column rule

      -

      Column rule

      - - - - - - - - - - -
      Note
      In Tizen SDK version 2.2, to avoid displaying the rules incorrectly, do not use the column-rule (or -webkit-column-rule) property with horizontal scrolling of the columns.
      - -

      Setting the Column Span

      -

      By default, all elements within the columns are no wider than the column width. The column-span (or -webkit-column-span) property can be used to display content across all columns.

      -

      When using this property with column elements which have the column-count or column-width property set, the following restrictions apply:

      -
        -
      • Column element height is not used and elements in columns take more vertical space than is set in height.
      • -
      • If the column element has the overflow property set to hidden, the column-span property is ignored.
      • -
      • An element using the column-span property does not have to be a direct child of the column element.
      • -
      -

      In the figure below, the blue arrow shows the order of the column elements. In the upper header area, the column-span property is not used, and in the lower header area, the column-span property is set to all, as in the following code snippet.

      -

      The following code snippet demonstrates how to use the column-span property. For a complete source code, see multi_column_column_span/renamed_index.html.

      -
      -article.left header 
      -{
      -   column-span: all;
      -   -webkit-column-span: all;
      -}
      -
      - -

      Figure: Column span

      -

      Column span

      - -

      Setting the Column Break

      -

      By default, column elements are broken to balance column height. The break-before (or -webkit-column-break-before), break-after (or -webkit-column-break-after), and break-inside (or -webkit-column-break-inside) properties can be used to define that an element cannot be broken between columns (set to avoid), or that an element must begin or end within a given column.

      - -

      The following code snippet and figure illustrate the use of the break- property. In the upper header area, the break- property is not used, and in the lower header area, the break-before property is set to always.

      -

      The following code snippet demonstrates how to use the column-break property. For a complete source code, see multi_column_column_break/renamed_index.html.

      -
      -article.lower section
      -{
      -   break-before: always;
      -   -webkit-column-break-before: always;
      -}
      -
      - -

      Figure: Column break

      -

      Column break

      - - - -
      - -Go to top - - - - - - - \ No newline at end of file diff --git a/org.tizen.guides/html/web/w3c/dom/selector_w.htm b/org.tizen.guides/html/web/w3c/dom/selector_w.htm deleted file mode 100644 index 3794371..0000000 --- a/org.tizen.guides/html/web/w3c/dom/selector_w.htm +++ /dev/null @@ -1,72 +0,0 @@ - - - - - - - - - - - - - Selectors API Level 1 and Level 2 - - - - - -
      -

      Selectors API Level 1 and Level 2

      - -

      The selectors allow you to select element nodes in the DOM tree by matching them against a group of selectors, and testing whether the element matches a particular selector. Using selectors makes searching and selecting complex elements faster.

      - -

      You can use the querySelector() and querySelectorAll() methods to retrieve the element nodes. Both methods accept a single parameter, a string selector. The string selector is a selector or a group of selectors that can be surrounded by whitespace. If you use a selector group as the string selector with the querySelector() method, the method returns the first element (if any) that matches any of the selectors in the group.

      - -

      The main features of the Selectors API Level 1 and Level 2 include:

      - -

      You can also create an accordion menu.

      - - - -
      - -Go to top - - - - - - - \ No newline at end of file diff --git a/org.tizen.guides/html/web/w3c/dom/session_history_w.htm b/org.tizen.guides/html/web/w3c/dom/session_history_w.htm deleted file mode 100644 index 1920572..0000000 --- a/org.tizen.guides/html/web/w3c/dom/session_history_w.htm +++ /dev/null @@ -1,73 +0,0 @@ - - - - - - - - - - - - - HTML5 session history of browsing contexts - - - - - -
      - - -

      HTML5 session history of browsing contexts

      - -

      You can manage the session history of browsing contexts.

      -

      The history interface is used to save in the session history the page information that has been read by the user. You can also use the state object to directly store the page information which has already been analyzed in the URL, or general information which is not stored in the URL (such as location, or the scroll state of the page or a certain DOM element).

      - - -

      The main features of the HTML5 session history of browsing contexts API include:

      -
        -
      • Adding entries to the session history -

        You can use the pushState() method of the history interface to add an entry to the session history. With the replaceState() method, you can update the session history details. -

      • -
      • Detecting session history status changes -

        The popstate event is fired when the user navigates to a page stored in the session history. The popstate event -references the information stored with the pushState() or replaceState() methods, and enables you to change the status of the page based on the stored session history (such as moving focus to a certain DOM element).

        -
      • -
      - - - -
      - -Go to top - - - - - - \ No newline at end of file diff --git a/org.tizen.guides/html/web/w3c/dom/text_module_w.htm b/org.tizen.guides/html/web/w3c/dom/text_module_w.htm deleted file mode 100644 index 6b6302e..0000000 --- a/org.tizen.guides/html/web/w3c/dom/text_module_w.htm +++ /dev/null @@ -1,67 +0,0 @@ - - - - - - - - - - - - - CSS Text Module Level 3 - - - - - - -
      -

      CSS Text Module Level 3

      - -

      You can apply various text effects easily.

      - -

      The new text features in CSS Text Module Level 3 include:

      -
        - -
      • Text properties -

        You can use CSS text properties, such as text-transform, text-align, text-indent, letter-spacing, and word-spacing, to manipulate and transform text.

      • -
      - - - -
      - -Go to top - - - - - - - \ No newline at end of file diff --git a/org.tizen.guides/html/web/w3c/dom/transform_w.htm b/org.tizen.guides/html/web/w3c/dom/transform_w.htm deleted file mode 100644 index 8de381d..0000000 --- a/org.tizen.guides/html/web/w3c/dom/transform_w.htm +++ /dev/null @@ -1,265 +0,0 @@ - - - - - - - - - - - - - CSS Transforms - - - - - - -
      -

      CSS Transforms

      - -

      Transforms allow you to modify the coordinate space where each element is positioned. The elements can be translated, rotated, and scaled in 2- or 3-dimensional space. According to the API, the coordinate system is a visual formatting model, and positions and sizes in the coordinate space are expressed in pixels, starting in the origin of point with positive values proceeding to the right and down.

      - -

      To enhance the rendering performance and user experience, you can use hardware acceleration and create fade effects.

      - -

      When using the CSS transform properties, the Tizen browser requires no prefix, the Firefox browser requires the -moz- prefix, the Chrome and Safari browsers require the -webkit- prefix, and the Opera browser requires the -o- prefix.

      - -

      Transform Properties

      - -

      You can define various properties to control the elements within the coordinate space:

      - -
        -
      • transform-origin -

        This property changes the location of the transformed element. It can only be used with elements for whom the transform property has been declared.

      • - -
      • transform-style -

        This property defines the rendering of the inherited element in the 3D space. Animation property has been added in the example for easier comprehension.

      • - -
      • perspective -

        This property changes the perspective of the element being expressed. A 3D transform element must be used together with this property to emphasize the expression of the X axis.

      • - -
      • perspective-origin -

        This property defines the location facing the element.

      • -
      • backface-visibility -

        This property defines whether the backface of the transformed element is expressed.

      • -
      - -
      -<head>
      -   <style type="text/css">
      -      .box 
      -      {
      -         transform: rotate(30deg);
      -         transform-origin: 30% 30%;
      -         perspective: 220;
      -         animation: trans-ani 10s infinite linear;
      -         backface-visibility: visible;
      -
      -         /* Chrome and Safari browsers */
      -         -webkit-transform: rotate(30deg);
      -         -webkit-transform-origin: 30% 30%;
      -         -webkit-perspective: 220;
      -         -webkit-animation: trans-ani 10s infinite linear;
      -         -webkit-backface-visibility: visible;
      -      }
      -      .box.case01 
      -      {
      -         transform-style: preserve-3d;
      -         perspective-origin: 30% 30%;
      -
      -         /* Chrome and Safari browsers */
      -         -webkit-transform-style: preserve-3d;
      -         -webkit-perspective-origin: 30% 30%;
      -      }
      -   </style>
      -</head>
      -<body>
      -   <h1>transform-origin</h1>
      -   <div class="boxarea">
      -      <div class="box">
      -         <p>transform</p>
      -         <p>transform-origin: 30% 30%;</p>
      -      </div>
      -      <div class="box case01">
      -         <p>box</p>
      -      </div>
      -   </div>
      -</body>
      -
      - -

      In addition to transform properties, you can also use various 2D and 3D transform functions.

      - -

      2D and 3D Transform Functions

      - -

      The CSS Transforms API supports various transform functions in 2D and 3D.

      - -

      In 2D transforms, all transform functions are expressed based on a matrix. The X and Y values of the translate(), scale(), and skew() functions can be expressed in individual functions. For example, the X and Y values of the translate() function can be expressed with the translateX(number) and translateY(number) functions.

      - -
      -<head>
      -   <style type="text/css">
      -      .box-translate 
      -      {
      -         transform: translate(30px, 30px);
      -         -webkit-transform: translate(30px, 30px);
      -      }
      -
      -      .box-scale 
      -      {
      -         transform: scale(1.2, 1.2);
      -         -webkit-transform: scale(1.2, 1.2);
      -      }
      -
      -      .box-rotate 
      -      {
      -         transform: rotate(45deg);
      -         -webkit-transform: rotate(45deg);
      -      }
      -
      -      .box-skew 
      -      {
      -         transform: skew(20deg, 20deg);
      -         -webkit-transform: skew(20deg, 20deg);
      -      }
      -
      -      .box-matrix 
      -      {
      -         transform: matrix(0.8, 0.5, 0.9, 0.9, 0, 0);
      -         -webkit-transform: matrix(0.8, 0.5, 0.9, 0.9, 0, 0);
      -      }
      -   </style>
      -</head>
      -<body>
      -   <h1>2d transform</h1>
      -   <h2>translate</h2>
      -   <div class="boxarea">
      -      <div class="box no-transform">
      -         <p>Original</p>
      -      </div>
      -      <div class="box transformed box-translate">
      -         <p>transform</p>
      -         <p>transform: translate(30px, 30px);</p>
      -      </div>
      -   </div>
      -</body>
      -
      - -

      In 3D transforms, the Z axis has been added (for example, translateZ(number) and scale3dZ(number)). When handling 3D transforms, pay attention to the following:

      -
        -
      • If a transform function is used together with the perspective property, the z axis is emphasized.
      • -
      • The X, Y, and Z values of the translate3d(), scale3d(), and rotate3d() functions can be expressed in individual functions.
      • -
      • In the rotate3d(number, number, number, angle) function, the element rotates according to the assigned parameter (angle) with the X, Y, and Z directional vectors as the center. Each vector can be expressed as an individual function: for example, the rotateX(<angle>) and rotate3d(1, 0, 0, <angle>) functions perform the same task.
      • -
      -

      The following code snippet demonstrates how to implement a 3D transform. For a complete source code, see 3d_transform.html.

      -
      -<head>
      -   <style type="text/css">
      -      .first-transform {opacity: .5; background: #3399cc;}
      -      .transformed {opacity: .8;}
      -      /* translate3d */
      -      .box-translate3d: hover .first-transform 
      -      {
      -         transform: translate3d(-5px, -5px, -60px) rotateY(70deg);
      -         -webkit-transform: translate3d(-5px, -5px, -60px) rotateY(70deg);
      -      }
      -      .box-translate3d: hover .transformed 
      -      {
      -         transform: translate3d(15px, 15px, 60px) rotateY(70deg);
      -         -webkit-transform: translate3d(15px, 15px, 60px) rotateY(70deg);
      -      }
      -      /* scale3d */
      -      .box-scale3d: hover .first-transform 
      -      {
      -         transform: scale3d(1, 1, 1) rotateY(70deg);
      -         -webkit-transform: scale3d(1, 1, 1) rotateY(70deg);
      -      }
      -      .box-scale3d: hover .transformed 
      -      {
      -         transform: scale3d(0.6, 0.6, 2) rotateY(70deg);
      -         -webkit-transform: scale3d(0.6, 0.6, 2) rotateY(70deg);
      -      }
      -      /* rotate3d */
      -      .box-rotate3d: hover .first-transform 
      -      {
      -         transform: rotate3d(-1, -1, -1, 110deg);
      -         -webkit-transform: rotate3d(-1, -1, -1, 110deg);
      -      }
      -      .box-rotate3d: hover .transformed 
      -      {
      -         transform: rotate3d(1, 1, 1, 110deg);
      -         -webkit-transform: rotate3d(1, 1, 1, 110deg);
      -      }
      -      /* matrix3d */
      -      .box-matrix3d: hover .first-transform 
      -      {
      -         transform: matrix3d(0.3, 0.2, -0.9, 0, 0.2, 0.8, 0.2, 0, 0.6, 0, 0.4, 0, 0, 0, 0, 1);
      -         -webkit-transform: matrix3d(0.3, 0.2, -0.9, 0, 0.2, 0.8, 0.2, 0, 0.6, 0, 0.4, 0, 0, 0, 0, 1);
      -      }
      -      .box-matrix3d: hover .transformed 
      -      {
      -         transform: matrix3d(0.4, -0.5, 0.8, 0, 0.2, 0.8, 0.2, 0, -0.6, 0, 0.4, 0, 0, 0, 0, 1);
      -         -webkit-transform: matrix3d(0.4, -0.5, 0.8, 0, 0.2, 0.8, 0.2, 0, -0.6, 0, 0.4, 0, 0, 0, 0, 1);
      -      }
      -   </style>
      -</head>
      -<body>
      -   <h1>3D transform</h1>
      -   <h2></h2>
      -   <p><strong>First box value:</strong> transform: translate3d(-5px, -5px, -60px) rotateY(70deg);</p>
      -   <p><strong>Second box value:</strong> transform: translate3d(15px, 15px, 60px) rotateY(70deg);</p>
      -   <div class="boxarea box-translate3d">
      -      <div class="box first-transform">
      -         First box
      -      </div>
      -      <div class="box transformed">
      -         <p>Second Box</p>
      -         Mouse over or tab here to animate
      -      </div>
      -   </div>
      -</body>
      -
      - - - -
      - -Go to top - - - - - - - \ No newline at end of file diff --git a/org.tizen.guides/html/web/w3c/dom/transition_w.htm b/org.tizen.guides/html/web/w3c/dom/transition_w.htm deleted file mode 100644 index a0e9a88..0000000 --- a/org.tizen.guides/html/web/w3c/dom/transition_w.htm +++ /dev/null @@ -1,136 +0,0 @@ - - - - - - - - - - - - - CSS Transitions Module Level 3 - - - - - - -
      -

      CSS Transitions Module Level 3

      - -

      Transitions allow you to enable implicit transitions, which describe how the CSS properties can be made to change smoothly from one value to another over a given duration. To enhance the rendering performance, you can use hardware acceleration.

      - -

      When using the CSS transition properties, the Tizen browser requires the -webkit- prefix.

      - -

      Transition Properties

      - -

      You can define various properties to control the element transitions:

      - -
        -
      • transition-property -

        This property defines the element property that is changed during the transition. In the following code snippet, both the width and height of the element change when the mouse hovers over it, but the transition effect is applied to the width property only.

      • - -
      • transition-duration -

        This property defines the duration of the transition. You must define as many instances of the property as you have elements in the transition-property property.

      • - -
      • transition-timing-function -

        This property defines the pace of the transition. The value of the property is defined as a stepping function or a cubic Bézier curve. The ease stepping function equals cubic-bezier(0.25, 0.1, 0.25, 1), and the linear stepping function equals cubic-bezier(0, 0, 1, 1).

      • - -
      • transition-delay -

        This property defines the delay time before the start of the transition.

      • - -
      - -

      The following code snippet demonstrates how to use transition properties. For a complete source code, see transition_property.html.

      - -
      -<head>
      -   <style type="text/css">
      -      body{font-size: 12px}
      -
      -      .box 
      -      {
      -         -webkit-transition-property: width;
      -         -webkit-transition-duration: 2s;
      -         -webkit-transition-timing-function: ease;
      -         -webkit-transition-delay: 0.5s;
      -      }
      -
      -      .box: hover 
      -      {
      -         width: 300px;
      -         height: 200px;
      -         background: CornflowerBlue;
      -      }
      -   </style>
      -</head>
      -<body>
      -   <h1>CSS transitions tutorial</h1>
      -   <div class="box">
      -      <p>Mouse over or tap here to animate</p>
      -      <p>transition-property: width, height, background</p>
      -   </div>
      -</body>
      -
      - - - - - - - - - -
      Note
      The hover pseudo class in Tizen maintains a mouseover state when an element is tapped, and becomes a mouseout state when another element is tapped.
      - -

      The transition property allows you to define all the transition properties in a shorthand mode in the order of transition-property | transition-duration | transition-timing-function | transition-delay. If you omit a property value, a default value is used instead.

      - -
      -<style type="text/css">
      -   .box 
      -   {
      -      -webkit-transition: width 1s ease 1s;
      -   }
      -</style>
      -
      - -

      The transition property connects movement more naturally than the more generally used the pseudo classes, such as :hover or :active. The smooth effect can be achieved more conveniently and easily with the transition property than with JavaScript or Flash, and the transition property also supports the browser side to provide excellent performance.

      - - - -
      - -Go to top - - - - - - - \ No newline at end of file diff --git a/org.tizen.guides/html/web/w3c/dom/woff_w.htm b/org.tizen.guides/html/web/w3c/dom/woff_w.htm deleted file mode 100644 index 06848fe..0000000 --- a/org.tizen.guides/html/web/w3c/dom/woff_w.htm +++ /dev/null @@ -1,67 +0,0 @@ - - - - - - - - - - - - - WOFF File Format 1.0 - - - - - - -
      -

      WOFF File Format 1.0

      - -

      You can decode and restore font data easily.

      - -

      The new text features in WOFF File Format 1.0 include:

      -
        - -
      • WOFF file format 1.0 -

        WOFF (Web Open Font Format) is a packaging format used to decode and restore font data according to the @font-face rule to display it identically with the input font. The @font-face rule is a CSS rule that allows linking to fonts and finding a suitable font to display if the original font is not available. You can use WOFF within a Web page.

      • -
      - - - -
      - -Go to top - - - - - - - \ No newline at end of file diff --git a/org.tizen.guides/html/web/w3c/guides_w3c_w.htm b/org.tizen.guides/html/web/w3c/guides_w3c_w.htm index 33b4dd2..49f5e21 100644 --- a/org.tizen.guides/html/web/w3c/guides_w3c_w.htm +++ b/org.tizen.guides/html/web/w3c/guides_w3c_w.htm @@ -37,8 +37,6 @@

      Select the feature you are interested in and see what Tizen offers for your application:

        -
      • DOM, Forms and Styles -

        Enables you to use various CSS style and HTML5 form features.

      • Device

        Enables you to manage information about device-specific features, such as vibration and browser state.

      • Graphics @@ -55,14 +53,14 @@

        Enables you to use Web workers used to run scripts in the background.

      • Location

        Enables you to use geolocation features.

      • -
      • UI in mobile applications only -

        Enables you to handle the application UI through the clipboard and drag and drop events.

      • Useful Guides for W3C/HTML5 Features

        Enables you to use common W3C features related to various APIs.

      • Supplementary Features

        Enables you to take advantage of supplementary features, such as full screen views, typed arrays, and the WebGL graphics library.

      - + +

      For more information about implementing the UI for your application using the W3C features, see W3C.

      + diff --git a/org.tizen.guides/html/web/w3c/media/getusermedia_w.htm b/org.tizen.guides/html/web/w3c/media/getusermedia_w.htm index b87b64c..159d639 100644 --- a/org.tizen.guides/html/web/w3c/media/getusermedia_w.htm +++ b/org.tizen.guides/html/web/w3c/media/getusermedia_w.htm @@ -1,80 +1,80 @@ - - - - - - - - - - - - - getUserMedia - - - - - -
      - -

      getUserMedia

      -

      You can access multimedia streams, such as camera, on a local device. The feature can be used, for example, for real-time communication, recording, and surveillance.

      - -

      The main features of the getUserMedia API include:

      -
        -
      • Retrieving multimedia streams -

        You can use the navigator.webkitGetUserMedia() method to request user access to retrieve the multimedia streams of local devices, such as camera. The method returns the media as a JSON object.

      • -
      • Capturing media -

        You can capture media content and transform it to various formats.

        - -
      • -
      - - - - - - - - - - -
      Note
      Tizen supports a WebKit-based GetUserMedia() method, so always use it in the webkitGetUserMedia() format.
      - - - -
      - -Go to top - - - - - - + + + + + + + + + + + + + getUserMedia + + + + + +
      + +

      getUserMedia

      +

      You can access multimedia streams, such as camera, on a local device. The feature can be used, for example, for real-time communication, recording, and surveillance.

      + +

      The main features of the getUserMedia API include:

      +
        +
      • Retrieving multimedia streams +

        You can use the navigator.webkitGetUserMedia() method to request user access to retrieve the multimedia streams of local devices, such as camera. The method returns the media as a JSON object.

      • +
      • Capturing media +

        You can capture media content and transform it to various formats.

        + +
      • +
      + + + + + + + + + + +
      Note
      Tizen supports a WebKit-based GetUserMedia() method, so always use it in the webkitGetUserMedia() format.
      + + + +
      + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/web/w3c/media/media_capture_w.htm b/org.tizen.guides/html/web/w3c/media/media_capture_w.htm index 51b6480..b71229b 100644 --- a/org.tizen.guides/html/web/w3c/media/media_capture_w.htm +++ b/org.tizen.guides/html/web/w3c/media/media_capture_w.htm @@ -1,77 +1,77 @@ - - - - - - - - - - - - - HTML Media Capture - - - - - -
      -

      HTML Media Capture

      - - - - - - - - - - -
      Note
      This feature is supported in mobile applications only.
      - -

      Media capture uses the capture attribute of the HTMLInputElement interface to activate features, such as camera or microphone, to enable direct media capture when the user is uploading a file.

      - -

      The following media formats can be used with the capture attribute:

      -
        -
      • filesystem

        Activates the device file picker.

      • -
      • camera

        Activates the device camera.

      • -
      • camcorder

        Activates the device video camera.

      • -
      • microphone

        Activates the device sound recorder.

      • -
      - - - -
      - -Go to top - - - - - - + + + + + + + + + + + + + HTML Media Capture + + + + + +
      +

      HTML Media Capture

      + + + + + + + + + + +
      Note
      This feature is supported in mobile applications only.
      + +

      Media capture uses the capture attribute of the HTMLInputElement interface to activate features, such as camera or microphone, to enable direct media capture when the user is uploading a file.

      + +

      The following media formats can be used with the capture attribute:

      +
        +
      • filesystem

        Activates the device file picker.

      • +
      • camera

        Activates the device camera.

      • +
      • camcorder

        Activates the device video camera.

      • +
      • microphone

        Activates the device sound recorder.

      • +
      + + + +
      + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/web/w3c/media/media_guide_w.htm b/org.tizen.guides/html/web/w3c/media/media_guide_w.htm index d510463..cbb2777 100644 --- a/org.tizen.guides/html/web/w3c/media/media_guide_w.htm +++ b/org.tizen.guides/html/web/w3c/media/media_guide_w.htm @@ -1,70 +1,70 @@ - - - - - - - - - - - - - Media - - - - - -
      -

      Media

      -

      Media features include playing various media, and accessing media streams and capture capabilities.

      -

      The main media features are:

      -
        -
      • getUserMedia

        Enables you to access a local device to generate a multimedia stream.

      • -
      • HTML5 video and audio element

        Enables you to control multimedia playback, retrieve information about playback duration and media content downloading progress, and check supported media formats using the HTML5 <audio> and <video> elements.

      • -
      - -

      The following guides apply in mobile applications only:

      -
        -
      • HTML Media Capture

        Enables you to easily access the media capture capabilities, such as a camera or microphone, based on their type using the HTML capture attribute.

      • -
      • Web Audio

        Enables you to play audio content using the HTML5 <audio> element.

      • -
      - - - - -
      - -Go to top - - - - - - + + + + + + + + + + + + + Media + + + + + +
      +

      Media

      +

      Media features include playing various media, and accessing media streams and capture capabilities.

      +

      The main media features are:

      +
        +
      • getUserMedia

        Enables you to access a local device to generate a multimedia stream.

      • +
      • HTML5 video and audio element

        Enables you to control multimedia playback, retrieve information about playback duration and media content downloading progress, and check supported media formats using the HTML5 <audio> and <video> elements.

      • +
      + +

      The following guides apply in mobile applications only:

      +
        +
      • HTML Media Capture

        Enables you to easily access the media capture capabilities, such as a camera or microphone, based on their type using the HTML capture attribute.

      • +
      • Web Audio

        Enables you to play audio content using the HTML5 <audio> element.

      • +
      + + + + +
      + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/web/w3c/media/video_audio_w.htm b/org.tizen.guides/html/web/w3c/media/video_audio_w.htm index 64478aa..bb8e430 100644 --- a/org.tizen.guides/html/web/w3c/media/video_audio_w.htm +++ b/org.tizen.guides/html/web/w3c/media/video_audio_w.htm @@ -1,187 +1,187 @@ - - - - - - - - - - - - - HTML5 video and audio element - - - - - -
      -

      HTML5 video and audio element

      - -

      You can use the HTML5 audio and video elements to play multimedia files streaming, without a separate plug-in.

      -

      Using JavaScript, the playback can be controlled with media events. The audio and video elements used as media elements inherit all the properties and methods of the HTMLMediaElement interface.

      - -

      The main features of the audio and video elements with JavaScript include:

      -
        -
      • Creating a player -

        You can create a simple audio and video player.

      • -
      • Controlling the playback -

        You can use the Play() and Pause() methods of the Media object to control playing and pausing media files. With media events, additional features can be used.

        -
      • -
      • Retrieving duration and play time -

        You can retrieve the duration and play time of the media file, if its metadata (such as playing time, duration, and video's width and height) is loaded.

        -
      • -
      • Playing from a random position -

        You can indicate the playback time by playing the media file from a random position. To do this, you must change the currentTime value of the Media object to trigger the timeupdate event.

        -
      • -
      • Retrieving progress state -

        You can retrieve and display the download progress state using the Progress media event, which is triggered when information related to the progress of a media object loading media contents is updated.

      • -
      • Checking supported media formats -

        You can check whether the media data can be played using the canPlayType() method. Basically, the MIME type must be set in the Web server in a format that is supported in Tizen. If a non-supported MIME type is used, you can handle exceptions in advance.

        -

        Tizen supports the following media formats:

        -
          -
        • Video: 3GP, AVI, ASF, OGV, MP4, MKV, WMV
        • -
        • Audio: AAC, AMR, MP3, OGG, WAV, WMA
        • -
        -

        The following table lists the codecs supported in Tizen.

        - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
        Table: Supported codecs
        TypeCodecEncoderDecoder

        Video

        MPEG-1

        No

        Yes

        MPEG-4 part 2

        Yes

        Yes

        MPEG-4 part 2 MS v1

        No

        Yes

        MPEG-4 part 2 MS v2

        Yes

        Yes

        MPEG-4 part 2 MS v3

        Yes

        Yes

        H.264, H.263-1996, H.263+, H263-1998, H263 v2

        Yes

        Yes

        H.264, MPEG-4 AVC, MPEG-4 part10

        No

        Yes

        WMV3

        No

        Yes

        VC1

        No

        Yes

        THEORA

        Yes

        Yes

        Audio

        AAC

        No

        Yes

        MP3

        No

        Yes

        WMA (Available up to WMA8. WMA9 is not available.)

        No

        Yes

        AMR-NB

        Yes

        Yes

        AMR-WB

        No

        Yes

        VORBIS

        Yes

        Yes

        -
      • -
      - - - -
      - -Go to top - - - - - - + + + + + + + + + + + + + HTML5 video and audio element + + + + + +
      +

      HTML5 video and audio element

      + +

      You can use the HTML5 audio and video elements to play multimedia files streaming, without a separate plug-in.

      +

      Using JavaScript, the playback can be controlled with media events. The audio and video elements used as media elements inherit all the properties and methods of the HTMLMediaElement interface.

      + +

      The main features of the audio and video elements with JavaScript include:

      +
        +
      • Creating a player +

        You can create a simple audio and video player.

      • +
      • Controlling the playback +

        You can use the Play() and Pause() methods of the Media object to control playing and pausing media files. With media events, additional features can be used.

        +
      • +
      • Retrieving duration and play time +

        You can retrieve the duration and play time of the media file, if its metadata (such as playing time, duration, and video's width and height) is loaded.

        +
      • +
      • Playing from a random position +

        You can indicate the playback time by playing the media file from a random position. To do this, you must change the currentTime value of the Media object to trigger the timeupdate event.

        +
      • +
      • Retrieving progress state +

        You can retrieve and display the download progress state using the Progress media event, which is triggered when information related to the progress of a media object loading media contents is updated.

      • +
      • Checking supported media formats +

        You can check whether the media data can be played using the canPlayType() method. Basically, the MIME type must be set in the Web server in a format that is supported in Tizen. If a non-supported MIME type is used, you can handle exceptions in advance.

        +

        Tizen supports the following media formats:

        +
          +
        • Video: 3GP, AVI, ASF, OGV, MP4, MKV, WMV
        • +
        • Audio: AAC, AMR, MP3, OGG, WAV, WMA
        • +
        +

        The following table lists the codecs supported in Tizen.

        + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
        Table: Supported codecs
        TypeCodecEncoderDecoder

        Video

        MPEG-1

        No

        Yes

        MPEG-4 part 2

        Yes

        Yes

        MPEG-4 part 2 MS v1

        No

        Yes

        MPEG-4 part 2 MS v2

        Yes

        Yes

        MPEG-4 part 2 MS v3

        Yes

        Yes

        H.264, H.263-1996, H.263+, H263-1998, H263 v2

        Yes

        Yes

        H.264, MPEG-4 AVC, MPEG-4 part10

        No

        Yes

        WMV3

        No

        Yes

        VC1

        No

        Yes

        THEORA

        Yes

        Yes

        Audio

        AAC

        No

        Yes

        MP3

        No

        Yes

        WMA (Available up to WMA8. WMA9 is not available.)

        No

        Yes

        AMR-NB

        Yes

        Yes

        AMR-WB

        No

        Yes

        VORBIS

        Yes

        Yes

        +
      • +
      + + + +
      + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/web/w3c/media/webaudio_w.htm b/org.tizen.guides/html/web/w3c/media/webaudio_w.htm index 0e46092..24f44a7 100644 --- a/org.tizen.guides/html/web/w3c/media/webaudio_w.htm +++ b/org.tizen.guides/html/web/w3c/media/webaudio_w.htm @@ -1,86 +1,86 @@ - - - - - - - - - - - - - Web Audio - - - -
      -
      -

      Mobile Web

      -
      - - -
      - -
      -

      Web Audio

      - - - - - - - - - - -
      Note
      This feature is supported in mobile applications only.
      - -

      Tizen provides a high quality sound by setting space and direction through audio data, and synthesizing them. It is used in the audio engines of the sophisticated games to mix, process, and filter effects.

      - -

      The main features of the Web Audio API include:

      - -
        -
      • Loading source data -

        You must load source data before using the Web Audio API. You can do this using XMLHttprequest.

        - -

        The AudioContext interface is used to manage and play the sound. It creates a high quality sound and connects to the destination of the sound.

        -
      • -
      • Modular routing -

        Modular routing means routing audio data either in a direct manner, such as speaker output, or through a connection to AudioNodes, which handle, for example, volume adjustment and filters.

      • -
      • Playing sound -

        Use the noteOn(time) or start(time) method to play sound with the time parameter for specifying the time interval in seconds after which the audio is played. For example, the 0 time value implies playing the audio immediately and the currentTime + 0.75 time value implies that the audio is played after 0.75 seconds.

      • -
      • Stopping sound -

        Use the noteOff(time) or stop(time) method to stop sound with the time parameter for specifying the time interval in seconds after which the audio playback is stopped. For example, the 0 time value implies stopping the audio playback immediately and the currentTime + 0.75 time value implies that the audio playback is stopped after 0.75 seconds.

        -

        After stopping sound, recreate the AudioBufferSourceNode interface instance to play sound again.

      • -
      - - - -
      - -Go to top - - - - - - + + + + + + + + + + + + + Web Audio + + + +
      +
      +

      Mobile Web

      +
      + + +
      + +
      +

      Web Audio

      + + + + + + + + + + +
      Note
      This feature is supported in mobile applications only.
      + +

      Tizen provides a high quality sound by setting space and direction through audio data, and synthesizing them. It is used in the audio engines of the sophisticated games to mix, process, and filter effects.

      + +

      The main features of the Web Audio API include:

      + +
        +
      • Loading source data +

        You must load source data before using the Web Audio API. You can do this using XMLHttprequest.

        + +

        The AudioContext interface is used to manage and play the sound. It creates a high quality sound and connects to the destination of the sound.

        +
      • +
      • Modular routing +

        Modular routing means routing audio data either in a direct manner, such as speaker output, or through a connection to AudioNodes, which handle, for example, volume adjustment and filters.

      • +
      • Playing sound +

        Use the noteOn(time) or start(time) method to play sound with the time parameter for specifying the time interval in seconds after which the audio is played. For example, the 0 time value implies playing the audio immediately and the currentTime + 0.75 time value implies that the audio is played after 0.75 seconds.

      • +
      • Stopping sound +

        Use the noteOff(time) or stop(time) method to stop sound with the time parameter for specifying the time interval in seconds after which the audio playback is stopped. For example, the 0 time value implies stopping the audio playback immediately and the currentTime + 0.75 time value implies that the audio playback is stopped after 0.75 seconds.

        +

        After stopping sound, recreate the AudioBufferSourceNode interface instance to play sound again.

      • +
      + + + +
      + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/web/w3c/perf_opt/jquery_performance_improvement_w.htm b/org.tizen.guides/html/web/w3c/perf_opt/jquery_performance_improvement_w.htm index 4e580b2..b0b32b0 100644 --- a/org.tizen.guides/html/web/w3c/perf_opt/jquery_performance_improvement_w.htm +++ b/org.tizen.guides/html/web/w3c/perf_opt/jquery_performance_improvement_w.htm @@ -1,264 +1,264 @@ - - - - - - - - - - - - - jQuery Performance Improvement - - - -
      -
      -

      Mobile Web Wearable Web

      -
      - - -
      - -
      -

      jQuery Performance Improvement

      -

      The following techniques of writing JavaScript code can be used to improve application performance when using jQuery:

      - -

      The following example HTML code has been used as a basis when describing the techniques:

      -
      <div id="contents">
      -   <h3>Selector Test</h3>
      -   <ul id="contents_list">
      -      <li>List 1</li>
      -      <li>List 2</li>
      -      <li>List 3</li>
      -   </ul>
      -   <button id="search_dom" class="blue">Search DOM</button> 
      -</div>
      -<div id="contents1">
      -   <h3>Selector Test</h3>
      -   <ul id="contents_list1">
      -      <li>List 1</li>
      -      <li>List 2</li>
      -      <li>List 3</li>
      -   </ul>
      -   <button id="search_dom1" class="blue">Search DOM</button>
      -</div>
      -<div id="contents2">
      -   <h3>Selector Test</h3>
      -   <ul id="contents_list2">
      -      <li>List 1</li>
      -      <li>List 2</li>
      -      <li>List 3</li>
      -   </ul>
      -   <button id="search_dom2" class="blue">Search DOM</button>
      -</div>
      -<div id="contents3">
      -   <h3>Selector Test</h3>
      -   <ul id="contents_list3">
      -      <li>List 1</li>
      -      <li>List 2</li>
      -      <li>List 3</li>
      -   </ul>
      -   <button id="search_dom3" class="blue">Search DOM</button>
      -</div>
      -<div id="contents4">
      -   <h3>Selector Test</h3>
      -   <ul id="contents_list4">
      -      <li>List 1</li>
      -      <li>List 2</li>
      -      <li>List 3</li>
      -   </ul>
      -   <button id="search_dom4" class="blue">Search DOM</button>
      -</div>
      -<div id="contents5">
      -   <h3>Selector Test</h3>
      -   <ul id="contents_list5">
      -      <li>List 1</li>
      -      <li>List 2</li>
      -      <li>List 3</li>
      -   </ul>
      -   <button id="search_dom5" class="blue">Search DOM</button>
      -</div>
      -

      Using Selectors

      -

      When navigating a specific element, use an ID selector prior to other selectors, such as tags and classes. The following example shows how using an ID selector improves performance.

      -
      /* Code#1 */
      -var search_button = $('button');
      -
      /* Code#2 */
      -var search_button = $('#contents button');
      -

      Figure: jQuery performance improvement result (in mobile applications only)

      -

      jQuery performance improvement result (in mobile applications only)

      - - - - - - - - - - - - - - -
      Table: jQuery performance improvement result
      BrowserExecution time for Code#1 Execution time for Code#2
      Tizen0.1180.100
      -

      When using a class selector, apply a tag preceded by the class name. The following example shows how using a tag improves performance.

      -
      /* Code#1 */
      -var search_button = $('.blue');
      -
      /* Code#2 */
      -var search_button = $('button.blue');
      -
      /*Code#3*/
      -var search_button = $('#contents button.blue');
      -

      Figure: jQuery performance improvement result (in mobile applications only)

      -

      jQuery performance improvement result (in mobile applications only)

      - - - - - - - - - - - - - - - - -
      Table: jQuery performance improvement result
      BrowserExecution time for Code#1 Execution time for Code#2 Execution time for Code#3
      Tizen0.1050.1000.100
      -

      Using Caches

      -

      When referring to a DOM object, you can first create a cache for it.

      -

      Without doing this, every time a DOM object is called, DOM is searched to return a new jQuery object, which degrades performance.

      -

      The following example shows how using a cache improves performance.

      -
      /* Code#1 */
      -$("#search_dom").on('click', function() {});
      -$("#search_dom").removeClass('blue');
      -$("#search_dom").addClass('red');
      -
      /* Code#2 */
      -var $search_button = $("#search_dom");
      -$search_button.on('click', function() {});
      -$search_button.removeClass('blue');
      -$search_button.addClass('red');
      -

      Figure: jQuery performance improvement result (in mobile applications only)

      -

      jQuery performance improvement result (in mobile applications only)

      - - - - - - - - - - - - - - -
      Table: jQuery performance improvement result
      BrowserExecution time for Code#1 Execution time for Code#2
      Tizen0.1040.100
      -

      Using Chaining

      -

      Chaining makes the code lighter and reduces repeated operations, such as reflow and repaint.

      -

      When a DOM element is changed, chaining ties similar object references into groups for execution. jQuery objects need not be repeatedly created as existing ones can be reused. The following example shows how chaining improves performance.

      -
      /* Code#1 */
      -$("#contents").addClass('active');
      -$("#contents").css('border', '1px solid');
      -$("#contents").('background-color', 'red');
      -
      /* Code#2 */
      -$("#contents").addClass('active').css('border', '1px solid').('background-color', 'red');
      -

      Figure: jQuery performance improvement result (in mobile applications only)

      -

      jQuery performance improvement result (in mobile applications only)

      - - - - - - - - - - - - - - -
      Table: jQuery performance improvement result
      BrowserExecution time for Code#1 Execution time for Code#2
      Tizen0.1080.101
      -

      Managing DOM Control

      -

      Minimizing direct DOM manipulation improves jQuery performance. Every time an element is created and inserted, time and capacity is needed. Using a cached selector with the append() method reduces the need for capacity.

      -

      The following example shows how applying DOM control improves performance.

      -
      /* Code#1 */
      -var $contents_list = $('#contents_list'),
      -    array_list = [...];
      -
      -for (var i = 0, len = array_list.length; i < len; i++)
      -{
      -   $contents_list.append('<li>' + array_list[i] + '</li>');
      -}
      -
      /* Code#2 */
      -var $contents_list = $('#contents_list'),
      -    array_list = [...],
      -    list = '';
      -
      -for (var i = 0, len = array_list.length; i < len; i++)
      -{
      -   list += '<li>' + array_list[i] + '</li>';
      -}
      -$contents_list.append(list);
      -

      Figure: jQuery performance improvement result (in mobile applications only)

      -

      jQuery performance improvement result (in mobile applications only)

      - - - - - - - - - - - - - - - -
      Table: jQuery performance improvement result
      BrowserExecution time for Code#1 Execution time for Code#2
      Tizen0.1200.101
      - - - -
      - -Go to top - - - - - - + + + + + + + + + + + + + jQuery Performance Improvement + + + +
      +
      +

      Mobile Web Wearable Web

      +
      + + +
      + +
      +

      jQuery Performance Improvement

      +

      The following techniques of writing JavaScript code can be used to improve application performance when using jQuery:

      + +

      The following example HTML code has been used as a basis when describing the techniques:

      +
      <div id="contents">
      +   <h3>Selector Test</h3>
      +   <ul id="contents_list">
      +      <li>List 1</li>
      +      <li>List 2</li>
      +      <li>List 3</li>
      +   </ul>
      +   <button id="search_dom" class="blue">Search DOM</button> 
      +</div>
      +<div id="contents1">
      +   <h3>Selector Test</h3>
      +   <ul id="contents_list1">
      +      <li>List 1</li>
      +      <li>List 2</li>
      +      <li>List 3</li>
      +   </ul>
      +   <button id="search_dom1" class="blue">Search DOM</button>
      +</div>
      +<div id="contents2">
      +   <h3>Selector Test</h3>
      +   <ul id="contents_list2">
      +      <li>List 1</li>
      +      <li>List 2</li>
      +      <li>List 3</li>
      +   </ul>
      +   <button id="search_dom2" class="blue">Search DOM</button>
      +</div>
      +<div id="contents3">
      +   <h3>Selector Test</h3>
      +   <ul id="contents_list3">
      +      <li>List 1</li>
      +      <li>List 2</li>
      +      <li>List 3</li>
      +   </ul>
      +   <button id="search_dom3" class="blue">Search DOM</button>
      +</div>
      +<div id="contents4">
      +   <h3>Selector Test</h3>
      +   <ul id="contents_list4">
      +      <li>List 1</li>
      +      <li>List 2</li>
      +      <li>List 3</li>
      +   </ul>
      +   <button id="search_dom4" class="blue">Search DOM</button>
      +</div>
      +<div id="contents5">
      +   <h3>Selector Test</h3>
      +   <ul id="contents_list5">
      +      <li>List 1</li>
      +      <li>List 2</li>
      +      <li>List 3</li>
      +   </ul>
      +   <button id="search_dom5" class="blue">Search DOM</button>
      +</div>
      +

      Using Selectors

      +

      When navigating a specific element, use an ID selector prior to other selectors, such as tags and classes. The following example shows how using an ID selector improves performance.

      +
      /* Code#1 */
      +var search_button = $('button');
      +
      /* Code#2 */
      +var search_button = $('#contents button');
      +

      Figure: jQuery performance improvement result (in mobile applications only)

      +

      jQuery performance improvement result (in mobile applications only)

      + + + + + + + + + + + + + + +
      Table: jQuery performance improvement result
      BrowserExecution time for Code#1 Execution time for Code#2
      Tizen0.1180.100
      +

      When using a class selector, apply a tag preceded by the class name. The following example shows how using a tag improves performance.

      +
      /* Code#1 */
      +var search_button = $('.blue');
      +
      /* Code#2 */
      +var search_button = $('button.blue');
      +
      /*Code#3*/
      +var search_button = $('#contents button.blue');
      +

      Figure: jQuery performance improvement result (in mobile applications only)

      +

      jQuery performance improvement result (in mobile applications only)

      + + + + + + + + + + + + + + + + +
      Table: jQuery performance improvement result
      BrowserExecution time for Code#1 Execution time for Code#2 Execution time for Code#3
      Tizen0.1050.1000.100
      +

      Using Caches

      +

      When referring to a DOM object, you can first create a cache for it.

      +

      Without doing this, every time a DOM object is called, DOM is searched to return a new jQuery object, which degrades performance.

      +

      The following example shows how using a cache improves performance.

      +
      /* Code#1 */
      +$("#search_dom").on('click', function() {});
      +$("#search_dom").removeClass('blue');
      +$("#search_dom").addClass('red');
      +
      /* Code#2 */
      +var $search_button = $("#search_dom");
      +$search_button.on('click', function() {});
      +$search_button.removeClass('blue');
      +$search_button.addClass('red');
      +

      Figure: jQuery performance improvement result (in mobile applications only)

      +

      jQuery performance improvement result (in mobile applications only)

      + + + + + + + + + + + + + + +
      Table: jQuery performance improvement result
      BrowserExecution time for Code#1 Execution time for Code#2
      Tizen0.1040.100
      +

      Using Chaining

      +

      Chaining makes the code lighter and reduces repeated operations, such as reflow and repaint.

      +

      When a DOM element is changed, chaining ties similar object references into groups for execution. jQuery objects need not be repeatedly created as existing ones can be reused. The following example shows how chaining improves performance.

      +
      /* Code#1 */
      +$("#contents").addClass('active');
      +$("#contents").css('border', '1px solid');
      +$("#contents").('background-color', 'red');
      +
      /* Code#2 */
      +$("#contents").addClass('active').css('border', '1px solid').('background-color', 'red');
      +

      Figure: jQuery performance improvement result (in mobile applications only)

      +

      jQuery performance improvement result (in mobile applications only)

      + + + + + + + + + + + + + + +
      Table: jQuery performance improvement result
      BrowserExecution time for Code#1 Execution time for Code#2
      Tizen0.1080.101
      +

      Managing DOM Control

      +

      Minimizing direct DOM manipulation improves jQuery performance. Every time an element is created and inserted, time and capacity is needed. Using a cached selector with the append() method reduces the need for capacity.

      +

      The following example shows how applying DOM control improves performance.

      +
      /* Code#1 */
      +var $contents_list = $('#contents_list'),
      +    array_list = [...];
      +
      +for (var i = 0, len = array_list.length; i < len; i++)
      +{
      +   $contents_list.append('<li>' + array_list[i] + '</li>');
      +}
      +
      /* Code#2 */
      +var $contents_list = $('#contents_list'),
      +    array_list = [...],
      +    list = '';
      +
      +for (var i = 0, len = array_list.length; i < len; i++)
      +{
      +   list += '<li>' + array_list[i] + '</li>';
      +}
      +$contents_list.append(list);
      +

      Figure: jQuery performance improvement result (in mobile applications only)

      +

      jQuery performance improvement result (in mobile applications only)

      + + + + + + + + + + + + + + + +
      Table: jQuery performance improvement result
      BrowserExecution time for Code#1 Execution time for Code#2
      Tizen0.1200.101
      + + + +
      + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/web/w3c/perf_opt/js_performance_improvement_w.htm b/org.tizen.guides/html/web/w3c/perf_opt/js_performance_improvement_w.htm index 75fa04e..e772d67 100644 --- a/org.tizen.guides/html/web/w3c/perf_opt/js_performance_improvement_w.htm +++ b/org.tizen.guides/html/web/w3c/perf_opt/js_performance_improvement_w.htm @@ -1,265 +1,265 @@ - - - - - - - - - - - - - JavaScript Performance Improvement - - - - - -
      -

      JavaScript Performance Improvement

      -

      The following techniques of writing JavaScript code can be used to improve application performance:

      - -

      Removing the Debugging Statement

      -

      The console.log statement, which is frequently used in JavaScript debugging, can cause poor performance. The following example shows how deleting the statement improves performance.

      -
      /* Code#1 */
      -var array_list = [0,1,2,3,4,5,6,7,8,9],
      -    new_array_list = [];
      -
      -for (var i = 0, len = array_list.length; i < len; i++)
      -{
      -   new_array_list.push(array_list[i]);
      -   console.log(array_list[i]);
      -}
      -
      /* Code#2 */
      -var array_list = [0,1,2,3,4,5,6,7,8,9],
      -    new_array_list = [];
      -
      -for (var i = 0, len = array_list.length; i < len; i++)
      -{
      -   new_array_list.push(array_list[i])
      -}
      -

      Figure: JavaScript performance improvement result (in mobile applications only)

      -

      JavaScript performance improvement result (in mobile applications only)

      - - - - - - - - - - - - - - -
      Table: JavaScript performance improvement result
      BrowserExecution time for Code#1 Execution time for Code#2
      Tizen0.8230.100
      -

      Removing Slow Loop Statements

      -

      The for - in loop is relatively slower than the other loops, such as for , while, and do - while, as it assigns object properties to the variable (idx in the example below), navigating the object every time the loop is iterated. The following example shows how modifying the loop improves performance.

      -
      /* Code#1 */
      -var array_list = [0,1,2,3,4,5,6,7,8,9],
      -    new_array_list = [];
      -for (var idx in array_list)
      -{
      -   new_array_list.push(array_list[idx]);
      -}
      - -
      /* Code#2 */
      -var array_list = [0,1,2,3,4,5,6,7,8,9],
      -    new_array_list = [];
      -for (var i = 0, len = array_list.length; i < len; i++)
      -{
      -   new_array_list.push(array_list[i]);
      -}
      -

      Figure: JavaScript performance improvement result (in mobile applications only)

      -

      JavaScript performance improvement result (in mobile applications only)

      - - - - - - - - - -
      Note
      By caching the array_list.length before using it, as shown in the second example above, better performance is achieved. For more information, see Using cached array length.
      - - - - - - - - - - - - - - -
      Table: JavaScript performance improvement result
      BrowserExecution time for Code#1 Execution time for Code#2
      Tizen0.1500.100
      -

      Using Cached Array Length

      -

      In a loop statement, you can cache the length of an array before using it instead of using it directly in the loop. Minimizing the steps taken to search for the scope chain activation object speeds up the response performance. The following example shows how caching the array list improves performance.

      -
      /* Code#1 */
      -var array_list = [],
      -    new_array_list = [],
      -    i = 0;
      -for (i = 0; i < 100; i++)
      -{
      -   array_list.push(i);
      -}
      -for (i = 0; i < array_list.length; i++)
      -{
      -   new_array_list.push(array_list[i]);
      -}
      -
      /* Code#2 */
      -var array_list = [],
      -    new_array_list = [],
      -    i = 0,
      -    arrayLen = 0;
      -for (i = 0; i < 100; i++)
      -{
      -   array_list.push(i);
      -}
      -for (i = 0, arrayLen = array_list.length; i < arrayLen; i++)
      -{
      -   new_array_list.push(array_list[i]);
      -}
      -

      Figure: JavaScript performance improvement result (in mobile applications only)

      -

      JavaScript performance improvement result (in mobile applications only)

      - - - - - - - - - - - - - - -
      Table: JavaScript performance improvement result
      BrowserExecution time for Code#1 Execution time for Code#2
      Tizen0.1040.100
      -

      Using Literal Expressions

      -

      Using literal expressions instead of newly created ones improves the JavaScript performance. Literal expressions are optimized for modern browser engines. They reduce the amount of interpretation time of the JavaScript interpreter. The following example shows how using literal expressions improves performance.

      -
      /* Code#1 */
      -var str = "";    
      -for (var i = 0; i < 100; i++)
      -{
      -   str = new String("abcd");
      -}
      -
      /* Code#2 */
      -var str = "";    
      -for (var i = 0; i < 100; i++)
      -{
      -   str = "abcd";
      -}
      - -

      Figure: JavaScript performance improvement result (in mobile applications only)

      -

      JavaScript performance improvement result (in mobile applications only)

      - - - - - - - - - - - - - - -
      Table: JavaScript performance improvement result
      BrowserExecution time for Code#1 Execution time for Code#2
      Tizen0.1970.100
      -

      Managing DOM Control

      -

      Rendering performance can be improved by minimizing direct DOM manipulation and creating a new instance of a cached DOM object.

      -

      When referring to variables, JavaScript revolves around a scope chain (variable object set that can be accessed in the current scope). The deeper the scope chain, the more execution time is needed.

      -

      The following example shows how applying DOM control improves performance.

      -
      /* Code#1 */
      -var id = document.getElementById('contents_list').getAttribute('id');
      -var name = document.getElementById('contents_list').getAttribute('name');
      -var style = document.getElementById('contents_list').getAttribute('style');
      -for (var i = 0; i < 100; i++)
      -{
      -   id = document.getElementById('contents_list').getAttribute('id');
      -   name = document.getElementById('contents_list').getAttribute('name');
      -   style = document.getElementById('contents_list').getAttribute('style');
      -}
      -
      /* Code#2 */
      -var contents_list = document.getElementById('contents_list');
      -var id = contents_list.getAttribute('id');
      -var name = contents_list.getAttribute('name');
      -var style = contents_list.getAttribute('style');
      -for (var i = 0; i < 100; i++)
      -{
      -   id = contents_list.getAttribute('id');
      -   name = contents_list.getAttribute('name');
      -   style = contents_list.getAttribute('style');
      -}
      -

      Figure: JavaScript performance improvement result (in mobile applications only)

      -

      JavaScript performance improvement result (in mobile applications only)

      - - - - - - - - - - - - - - -
      Table: JavaScript performance improvement result
      BrowserExecution time for Code#1 Execution time for Code#2
      Tizen0.1190.100
      - - - -
      - -Go to top - - - - - - + + + + + + + + + + + + + JavaScript Performance Improvement + + + + + +
      +

      JavaScript Performance Improvement

      +

      The following techniques of writing JavaScript code can be used to improve application performance:

      + +

      Removing the Debugging Statement

      +

      The console.log statement, which is frequently used in JavaScript debugging, can cause poor performance. The following example shows how deleting the statement improves performance.

      +
      /* Code#1 */
      +var array_list = [0,1,2,3,4,5,6,7,8,9],
      +    new_array_list = [];
      +
      +for (var i = 0, len = array_list.length; i < len; i++)
      +{
      +   new_array_list.push(array_list[i]);
      +   console.log(array_list[i]);
      +}
      +
      /* Code#2 */
      +var array_list = [0,1,2,3,4,5,6,7,8,9],
      +    new_array_list = [];
      +
      +for (var i = 0, len = array_list.length; i < len; i++)
      +{
      +   new_array_list.push(array_list[i])
      +}
      +

      Figure: JavaScript performance improvement result (in mobile applications only)

      +

      JavaScript performance improvement result (in mobile applications only)

      + + + + + + + + + + + + + + +
      Table: JavaScript performance improvement result
      BrowserExecution time for Code#1 Execution time for Code#2
      Tizen0.8230.100
      +

      Removing Slow Loop Statements

      +

      The for - in loop is relatively slower than the other loops, such as for , while, and do - while, as it assigns object properties to the variable (idx in the example below), navigating the object every time the loop is iterated. The following example shows how modifying the loop improves performance.

      +
      /* Code#1 */
      +var array_list = [0,1,2,3,4,5,6,7,8,9],
      +    new_array_list = [];
      +for (var idx in array_list)
      +{
      +   new_array_list.push(array_list[idx]);
      +}
      + +
      /* Code#2 */
      +var array_list = [0,1,2,3,4,5,6,7,8,9],
      +    new_array_list = [];
      +for (var i = 0, len = array_list.length; i < len; i++)
      +{
      +   new_array_list.push(array_list[i]);
      +}
      +

      Figure: JavaScript performance improvement result (in mobile applications only)

      +

      JavaScript performance improvement result (in mobile applications only)

      + + + + + + + + + +
      Note
      By caching the array_list.length before using it, as shown in the second example above, better performance is achieved. For more information, see Using cached array length.
      + + + + + + + + + + + + + + +
      Table: JavaScript performance improvement result
      BrowserExecution time for Code#1 Execution time for Code#2
      Tizen0.1500.100
      +

      Using Cached Array Length

      +

      In a loop statement, you can cache the length of an array before using it instead of using it directly in the loop. Minimizing the steps taken to search for the scope chain activation object speeds up the response performance. The following example shows how caching the array list improves performance.

      +
      /* Code#1 */
      +var array_list = [],
      +    new_array_list = [],
      +    i = 0;
      +for (i = 0; i < 100; i++)
      +{
      +   array_list.push(i);
      +}
      +for (i = 0; i < array_list.length; i++)
      +{
      +   new_array_list.push(array_list[i]);
      +}
      +
      /* Code#2 */
      +var array_list = [],
      +    new_array_list = [],
      +    i = 0,
      +    arrayLen = 0;
      +for (i = 0; i < 100; i++)
      +{
      +   array_list.push(i);
      +}
      +for (i = 0, arrayLen = array_list.length; i < arrayLen; i++)
      +{
      +   new_array_list.push(array_list[i]);
      +}
      +

      Figure: JavaScript performance improvement result (in mobile applications only)

      +

      JavaScript performance improvement result (in mobile applications only)

      + + + + + + + + + + + + + + +
      Table: JavaScript performance improvement result
      BrowserExecution time for Code#1 Execution time for Code#2
      Tizen0.1040.100
      +

      Using Literal Expressions

      +

      Using literal expressions instead of newly created ones improves the JavaScript performance. Literal expressions are optimized for modern browser engines. They reduce the amount of interpretation time of the JavaScript interpreter. The following example shows how using literal expressions improves performance.

      +
      /* Code#1 */
      +var str = "";    
      +for (var i = 0; i < 100; i++)
      +{
      +   str = new String("abcd");
      +}
      +
      /* Code#2 */
      +var str = "";    
      +for (var i = 0; i < 100; i++)
      +{
      +   str = "abcd";
      +}
      + +

      Figure: JavaScript performance improvement result (in mobile applications only)

      +

      JavaScript performance improvement result (in mobile applications only)

      + + + + + + + + + + + + + + +
      Table: JavaScript performance improvement result
      BrowserExecution time for Code#1 Execution time for Code#2
      Tizen0.1970.100
      +

      Managing DOM Control

      +

      Rendering performance can be improved by minimizing direct DOM manipulation and creating a new instance of a cached DOM object.

      +

      When referring to variables, JavaScript revolves around a scope chain (variable object set that can be accessed in the current scope). The deeper the scope chain, the more execution time is needed.

      +

      The following example shows how applying DOM control improves performance.

      +
      /* Code#1 */
      +var id = document.getElementById('contents_list').getAttribute('id');
      +var name = document.getElementById('contents_list').getAttribute('name');
      +var style = document.getElementById('contents_list').getAttribute('style');
      +for (var i = 0; i < 100; i++)
      +{
      +   id = document.getElementById('contents_list').getAttribute('id');
      +   name = document.getElementById('contents_list').getAttribute('name');
      +   style = document.getElementById('contents_list').getAttribute('style');
      +}
      +
      /* Code#2 */
      +var contents_list = document.getElementById('contents_list');
      +var id = contents_list.getAttribute('id');
      +var name = contents_list.getAttribute('name');
      +var style = contents_list.getAttribute('style');
      +for (var i = 0; i < 100; i++)
      +{
      +   id = contents_list.getAttribute('id');
      +   name = contents_list.getAttribute('name');
      +   style = contents_list.getAttribute('style');
      +}
      +

      Figure: JavaScript performance improvement result (in mobile applications only)

      +

      JavaScript performance improvement result (in mobile applications only)

      + + + + + + + + + + + + + + +
      Table: JavaScript performance improvement result
      BrowserExecution time for Code#1 Execution time for Code#2
      Tizen0.1190.100
      + + + +
      + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/web/w3c/perf_opt/minify_js_css_w.htm b/org.tizen.guides/html/web/w3c/perf_opt/minify_js_css_w.htm index bf4ca7c..1b5ee75 100644 --- a/org.tizen.guides/html/web/w3c/perf_opt/minify_js_css_w.htm +++ b/org.tizen.guides/html/web/w3c/perf_opt/minify_js_css_w.htm @@ -1,277 +1,277 @@ - - - - - - - - - - - - - JavaScript and CSS Minification - - - -
      -
      -

      Mobile Web Wearable Web

      -
      - - -
      - -
      -

      JavaScript and CSS Minification

      -

      File minification improves application performance as unnecessary data is being removed. For example, page loading time can be decreased by reducing the number of JavaScript and CSS files.

      -

      Minifying tools, such as Closure Compiler and Grunt, include features that can combine and reduce JavaScript file. The following table shows Closure Compiler and Grunt features in comparison.

      - - - - - - - - - - - - - - - - - - - - - - - - - -
      Table: Comparison of minifying tools
      ItemClosure CompilerGrunt
      Summary -

      JavaScript-optimized compiler created by Google

      -

      Task-based automatic JavaScript build tool

      -
      Features
        -
      • File compilation, minimizing size
      • -
      • Can be integrated with Ant Builder for automatic features
      • -
        -
      • File compilation plug-in
      • -
      • Minimizing JavaScript and CSS
      • -
      • Various plug-ins (JavaScript, CSS compilation, and compression)
      • -
      • Application performance improvement based on the decrease of request count, transferred data, and transfer time
      • -
      Usage
        -
      • Java applications

        Provided as a .jar file, used as a command line.

      • -
      • Web application
      • -
      • RESTful API
      • -
        -
      • Node.js installation
      • -
      • grunt-cli installation
      • -
      • package.json must be inserted to the project root
      • -
      • Task definition in the gruntfile.js file
      • -
      -

      Grunt has advantages in terms of expandability by providing various plug-ins. For more information about Grunt, see:

      - -

      Installing and Using Grunt

      -

      The Grunt tool provides application performance improvement based on the decrease of request count, transferred data, and transfer time.

      - -

      Prerequisites

      -

      The commands used for installing and using Grunt work in the same manner, without any changes, across most of the major operating systems. To run the commands, you may need to use sudo (for Linux and BSD), or run your command shell as Administrator (for Windows®).

      -

      Installing Grunt

      -
        -
      1. Install the Node.js platform. The platform includes the Node.js package manager, npm, which is used to install Grunt CLI (command line interface).
      2. -
      3. Install Grunt CLI: -
        npm install -g grunt-cli /* -g: global type */
      4. -
      -

      Using Grunt

      -
        -
      1. Change to the root directory of the project: -
        cd <Project root>
      2. -
      3. Install Grunt and create the Gruntfile.js file: -
        npm install grunt --save-dev
      4. -
      5. Create the package.json file:

        When executing the following command, interactive prompt that receives information on the project is executed. Through the information entered, the package.json file is created.

        -
        npm init
      6. -
      7. Install Grunt plug-in: -
        /* Install grunt concat */
        -npm install grunt-contrib-concat --save-dev
        -
        -/* Install grunt contrib uglify */
        -npm install grunt-contrib-uglify --save-dev
        -
        -/* Install grunt contrib cssmin */
        -npm install grunt-contrib-cssmin --save-dev
        -
      8. -
      9. Run the Grunt plug-in: -
        grunt
        -

        Using the Gruntfile.js file, tasks, such as concat, uglify, and cssmin, are registered.

      10. -
      -

      Improvement through Grunt

      -

      After running the Grunt plug-in, the below comparison result is shown through Chrome inspector. The expected results vary depending on the application, but since the improvement effects are certain, it is recommended to use Grunt.

      - - - - - - - - - -
      Note
      For the sake of comparing improvement, in the following examples, 2 Web applications have been arbitrarily chosen and named App#1 and App#2.
      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      Table: Result for App #01
      ItemRequest (count)Transferred data (mb)Onload time (s)
      ResultImprovementResultImprovementResultImprovement
      Original254-6.66-3.28-
      Minification applied (accumulated result)#01_grunt_concat68-1866.62-0.042.43-0.85
      #02_grunt_uglify68-1.90-4.721.59-0.85
      #03_grunt_cssmin68-1.87-0.031.610.02
      Total improvement73.23% improvement71.92% improvement51.07% improvement
      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      Table: Result for App #02
      ItemRequest (count)Transferred data (mb)Onload time (s)
      ResultImprovementResultImprovementResultImprovement
      Original235-7.89-5.80-
      Minification applied (accumulated result)#01_grunt_concat106-1297.87-0.025.15-0.65
      #02_grunt_uglify106-5.85 -2.024.95-0.19
      #03_grunt_cssmin106-5.84-0.014.89-0.06
      Total improvement54.89% improvement25.98% improvement15.63% improvement
      - - -
      - -Go to top - - - - - - + + + + + + + + + + + + + JavaScript and CSS Minification + + + +
      +
      +

      Mobile Web Wearable Web

      +
      + + +
      + +
      +

      JavaScript and CSS Minification

      +

      File minification improves application performance as unnecessary data is being removed. For example, page loading time can be decreased by reducing the number of JavaScript and CSS files.

      +

      Minifying tools, such as Closure Compiler and Grunt, include features that can combine and reduce JavaScript file. The following table shows Closure Compiler and Grunt features in comparison.

      + + + + + + + + + + + + + + + + + + + + + + + + + +
      Table: Comparison of minifying tools
      ItemClosure CompilerGrunt
      Summary +

      JavaScript-optimized compiler created by Google

      +

      Task-based automatic JavaScript build tool

      +
      Features
        +
      • File compilation, minimizing size
      • +
      • Can be integrated with Ant Builder for automatic features
      • +
        +
      • File compilation plug-in
      • +
      • Minimizing JavaScript and CSS
      • +
      • Various plug-ins (JavaScript, CSS compilation, and compression)
      • +
      • Application performance improvement based on the decrease of request count, transferred data, and transfer time
      • +
      Usage
        +
      • Java applications

        Provided as a .jar file, used as a command line.

      • +
      • Web application
      • +
      • RESTful API
      • +
        +
      • Node.js installation
      • +
      • grunt-cli installation
      • +
      • package.json must be inserted to the project root
      • +
      • Task definition in the gruntfile.js file
      • +
      +

      Grunt has advantages in terms of expandability by providing various plug-ins. For more information about Grunt, see:

      + +

      Installing and Using Grunt

      +

      The Grunt tool provides application performance improvement based on the decrease of request count, transferred data, and transfer time.

      + +

      Prerequisites

      +

      The commands used for installing and using Grunt work in the same manner, without any changes, across most of the major operating systems. To run the commands, you may need to use sudo (for Linux and BSD), or run your command shell as Administrator (for Windows®).

      +

      Installing Grunt

      +
        +
      1. Install the Node.js platform. The platform includes the Node.js package manager, npm, which is used to install Grunt CLI (command line interface).
      2. +
      3. Install Grunt CLI: +
        npm install -g grunt-cli /* -g: global type */
      4. +
      +

      Using Grunt

      +
        +
      1. Change to the root directory of the project: +
        cd <Project root>
      2. +
      3. Install Grunt and create the Gruntfile.js file: +
        npm install grunt --save-dev
      4. +
      5. Create the package.json file:

        When executing the following command, interactive prompt that receives information on the project is executed. Through the information entered, the package.json file is created.

        +
        npm init
      6. +
      7. Install Grunt plug-in: +
        /* Install grunt concat */
        +npm install grunt-contrib-concat --save-dev
        +
        +/* Install grunt contrib uglify */
        +npm install grunt-contrib-uglify --save-dev
        +
        +/* Install grunt contrib cssmin */
        +npm install grunt-contrib-cssmin --save-dev
        +
      8. +
      9. Run the Grunt plug-in: +
        grunt
        +

        Using the Gruntfile.js file, tasks, such as concat, uglify, and cssmin, are registered.

      10. +
      +

      Improvement through Grunt

      +

      After running the Grunt plug-in, the below comparison result is shown through Chrome inspector. The expected results vary depending on the application, but since the improvement effects are certain, it is recommended to use Grunt.

      + + + + + + + + + +
      Note
      For the sake of comparing improvement, in the following examples, 2 Web applications have been arbitrarily chosen and named App#1 and App#2.
      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Table: Result for App #01
      ItemRequest (count)Transferred data (mb)Onload time (s)
      ResultImprovementResultImprovementResultImprovement
      Original254-6.66-3.28-
      Minification applied (accumulated result)#01_grunt_concat68-1866.62-0.042.43-0.85
      #02_grunt_uglify68-1.90-4.721.59-0.85
      #03_grunt_cssmin68-1.87-0.031.610.02
      Total improvement73.23% improvement71.92% improvement51.07% improvement
      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Table: Result for App #02
      ItemRequest (count)Transferred data (mb)Onload time (s)
      ResultImprovementResultImprovementResultImprovement
      Original235-7.89-5.80-
      Minification applied (accumulated result)#01_grunt_concat106-1297.87-0.025.15-0.65
      #02_grunt_uglify106-5.85 -2.024.95-0.19
      #03_grunt_cssmin106-5.84-0.014.89-0.06
      Total improvement54.89% improvement25.98% improvement15.63% improvement
      + + +
      + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/web/w3c/perf_opt/page_w.htm b/org.tizen.guides/html/web/w3c/perf_opt/page_w.htm index 8945064..9caf8ee 100644 --- a/org.tizen.guides/html/web/w3c/perf_opt/page_w.htm +++ b/org.tizen.guides/html/web/w3c/perf_opt/page_w.htm @@ -1,83 +1,83 @@ - - - - - - - - - - - - - Page Visibility - - - - - -
      -

      Page Visibility

      - -

      Page visibility can detect whether the Web document is being shown on the screen. With it, you can design your application to only operate when its page is visible, both enhancing the user experience and reducing the resource usage on the device.

      - -

      The main features of the Page Visibility API include:

      -
        -
      • Retrieving the page visibility status -

        You can use 2 properties to detect the visibility status of the page:

        -
          -
        • The hidden property returns a boolean value indicating whether the page is visible.

        • -
        • The visibilityState property returns a DOMString type indicating whether the page is visible.

        • -
      • -
      • Tracking changes in page visibility -

        You can use the visibilitychange event to be able to respond to changes in the page visibility status.

        -

        For example, in a video player application, you can change the play status of the application based on the event: pause the playback when the page becomes hidden, and continue playing when the page becomes visible again.

        -
      • -
      - - - - - - - - - -
      Note
      Tizen supports the WebKit-based Page Visibility API. When using the Page Visibility API, you must include the webkit prefix.
      - - - -
      - -Go to top - - - - - - + + + + + + + + + + + + + Page Visibility + + + + + +
      +

      Page Visibility

      + +

      Page visibility can detect whether the Web document is being shown on the screen. With it, you can design your application to only operate when its page is visible, both enhancing the user experience and reducing the resource usage on the device.

      + +

      The main features of the Page Visibility API include:

      +
        +
      • Retrieving the page visibility status +

        You can use 2 properties to detect the visibility status of the page:

        +
          +
        • The hidden property returns a boolean value indicating whether the page is visible.

        • +
        • The visibilityState property returns a DOMString type indicating whether the page is visible.

        • +
      • +
      • Tracking changes in page visibility +

        You can use the visibilitychange event to be able to respond to changes in the page visibility status.

        +

        For example, in a video player application, you can change the play status of the application based on the event: pause the playback when the page becomes hidden, and continue playing when the page becomes visible again.

        +
      • +
      + + + + + + + + + +
      Note
      Tizen supports the WebKit-based Page Visibility API. When using the Page Visibility API, you must include the webkit prefix.
      + + + +
      + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/web/w3c/perf_opt/performance_guide_w.htm b/org.tizen.guides/html/web/w3c/perf_opt/performance_guide_w.htm index e6b336c..05261fb 100644 --- a/org.tizen.guides/html/web/w3c/perf_opt/performance_guide_w.htm +++ b/org.tizen.guides/html/web/w3c/perf_opt/performance_guide_w.htm @@ -1,67 +1,67 @@ - - - - - - - - - - - - - Performance and Optimization - - - - - -
      -

      Performance and Optimization

      - -

      Performance and optimization features include animation rate and page visibility control, and Web worker management.

      - -

      The main performance and optimization features are:

      -
        -
      • Page Visibility

        Enables you to retrieve the visibility status of a Web document and detect changes in it.

      • -
      • Timing control for script-based animations

        Enables you to control animation speed by scheduling frame update requests.

      • -
      • Web Workers

        Enables you to create and manage HTML5 Web Workers to run an independent JavaScript thread on the background without affecting the device performance.

      • -
      - - - -
      - -Go to top - - - - - - + + + + + + + + + + + + + Performance and Optimization + + + + + +
      +

      Performance and Optimization

      + +

      Performance and optimization features include animation rate and page visibility control, and Web worker management.

      + +

      The main performance and optimization features are:

      +
        +
      • Page Visibility

        Enables you to retrieve the visibility status of a Web document and detect changes in it.

      • +
      • Timing control for script-based animations

        Enables you to control animation speed by scheduling frame update requests.

      • +
      • Web Workers

        Enables you to create and manage HTML5 Web Workers to run an independent JavaScript thread on the background without affecting the device performance.

      • +
      + + + +
      + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/web/w3c/perf_opt/timing_control_w.htm b/org.tizen.guides/html/web/w3c/perf_opt/timing_control_w.htm index 427d2be..834776a 100644 --- a/org.tizen.guides/html/web/w3c/perf_opt/timing_control_w.htm +++ b/org.tizen.guides/html/web/w3c/perf_opt/timing_control_w.htm @@ -1,83 +1,83 @@ - - - - - - - - - - - - - Timing control for script-based animations - - - - - -
      -

      Timing control for script-based animations

      - -

      Timing control is used mainly in animations for cyclic script execution synchronized with screen changes.

      -

      Making script-based animations requires updating the properties of the animated objects in each frame. In computerized animations, the frame rate is normally 30 or 60 fps (frames per second), because the human eye perceives a sequence of images as an animation when they change at least 12-15 times per second. The requestAnimationFrame() (or webkitRequestAnimationFrame()) method of the WindowAnimationTiming interface enables scheduling the animation frame update requests. The frame update rate depends on implementation. In Tizen SDK version 2.2, it is about 60 fps.

      - - - - - - - - - - -
      Note
      In mobile applications, when using the Emulator, you must include the webkit prefix in method names, such as window.performance.webkitNow(). However, when using a device, the prefix must not be used. In addition, when using the Emulator, methods assigned to variables must be formatted as follows: -
      -window.performance.windowNow = window.performance.now || window.performance.webkitNow || Date.now;
      -window.performance.windowNow();
      -
      - -

      In wearable applications, when you are using the Emulator and want to support backward compatibility, methods assigned to variables must be formatted as follows:

      -
      -window.performance.windowNow = window.performance.now || window.performance.webkitNow || Date.now;
      -window.performance.windowNow();
      -
      -
      - - - - -
      - -Go to top - - - - - - + + + + + + + + + + + + + Timing control for script-based animations + + + + + +
      +

      Timing control for script-based animations

      + +

      Timing control is used mainly in animations for cyclic script execution synchronized with screen changes.

      +

      Making script-based animations requires updating the properties of the animated objects in each frame. In computerized animations, the frame rate is normally 30 or 60 fps (frames per second), because the human eye perceives a sequence of images as an animation when they change at least 12-15 times per second. The requestAnimationFrame() (or webkitRequestAnimationFrame()) method of the WindowAnimationTiming interface enables scheduling the animation frame update requests. The frame update rate depends on implementation. In Tizen SDK version 2.2, it is about 60 fps.

      + + + + + + + + + + +
      Note
      In mobile applications, when using the Emulator, you must include the webkit prefix in method names, such as window.performance.webkitNow(). However, when using a device, the prefix must not be used. In addition, when using the Emulator, methods assigned to variables must be formatted as follows: +
      +window.performance.windowNow = window.performance.now || window.performance.webkitNow || Date.now;
      +window.performance.windowNow();
      +
      + +

      In wearable applications, when you are using the Emulator and want to support backward compatibility, methods assigned to variables must be formatted as follows:

      +
      +window.performance.windowNow = window.performance.now || window.performance.webkitNow || Date.now;
      +window.performance.windowNow();
      +
      +
      + + + + +
      + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/web/w3c/perf_opt/web_workers_w.htm b/org.tizen.guides/html/web/w3c/perf_opt/web_workers_w.htm index e4398c2..14e2432 100644 --- a/org.tizen.guides/html/web/w3c/perf_opt/web_workers_w.htm +++ b/org.tizen.guides/html/web/w3c/perf_opt/web_workers_w.htm @@ -1,347 +1,347 @@ - - - - - - - - - - - - - Web Workers - - - - - -
      -

      Web Workers

      - -

      Web workers run JavaScript in an independent thread instead of the main UI thread, improving the JavaScript performance without affecting the UI.

      -

      Web workers are not DOM-dependent. They handle pure data, which makes them especially suitable for JavaScript code that takes a long time to execute.

      - - - - - - - - - - -
      Note
      Workers use a same-origin policy and therefore using some of the browser resources, such as DOM, document, window, and parent, is not possible, and they must be activated by creating separate JavaScript files. However, ECMA JavaScript and the methods included in the Web Workers API, such as postMessage(), location, navigator, and importScripts() can be used. The self and location attributes are also supported.
      -

      The main features of the Web Workers API include:

      -
        -
      • Creating workers -

        -The worker creates a new thread, and only runs when it is executed. It does not communicate with the UI thread or other same-level workers, and therefore, you cannot assign a work priority order. However, you can create subworkers using the importScripts() method to divide tasks.

        -
      • - -
      • Messaging between workers -

        A subworker can communicate with the host worker using the postMessage() method of the HTML5 Web Messaging API (in mobile or wearable applications). This process is normally used to give work orders to workers or subworkers, or deliver an operation result.

        -

        -If a worker triggers a message event, the onmessage() event handler can be used to check the sent message.

        -
      • - -
      • Multi-threading -

        Multi-thread web workers provide significant advantages over UI threads with higher response speed and lower memory usage in applications.

        -
      • -
      - -

      JavaScript Performance

      -

      JavaScript was originally used for simple inspections and request handling. Therefore, the execution time was not an issue. However, with more advanced UI usage, the use of JavaScript code has been increased and become more complicated, significantly influencing the application performance.

      - -

      Improving performance through effective JavaScript code consists of the following:

      - -

      Multi-threading

      -

      Generally, Web applications are built and run using a single UI thread. Since only 1 task can be handled at a time, the Web application may not respond due to the execution time of a script block, resulting in lower application performance. To solve these performance-related issues, multi-thread Web workers can be used to provide distributed processing in applications. Use Web workers in applications that require complex calculations or parallel processing for better application performance.

      - -

      Since the task of changing the image color using a canvas involves allocating a color value for each pixel of the image displayed on the screen, the program requires a complicated calculation to execute loops by the number of the pixels. The following examples of applying a color filter effects to an image to change the color show:

      - - -

      Using UI Threads

      -

      The following example uses a UI thread to apply a color filter effect on an image and to display the time taken to apply the filter. Since all the calculations are performed in a single UI thread using the colorFilter() method, the execution time is high (16218 milliseconds).

      - -

      Figure: Color filter application using UI thread (in mobile applications only)

      -

      Color filter application using UI thread (in mobile applications only)

      - -
      function colorFilterStart()
      -{
      -   var picture = document.getElementById('picture');
      -   var canvas = document.querySelector('canvas');
      -   canvas.width = document.width;
      -   canvas.height = picture.clientHeight;
      -   var tempContext = canvas.getContext("2d");
      -   tempContext.drawImage(picture, 0, 0, canvas.width, canvas.height);
      -   var pixels = canvas.width * canvas.height * 4;
      -   var canvasData = tempContext.getImageData(0, 0, canvas.width, canvas.height);
      -   var binaryData = canvasData.data;
      -   var timeStart = new Date();
      -
      -   colorFilter(binaryData, pixels);
      -   tempContext.putImageData(canvasData, 0, 0);
      -   var timeDiffer = new Date() - timeStart;
      -   message.innerHTML = timeDiffer + " ms";
      -};
      -
      -function colorChange(scale, gab, position)
      -{
      -   return Math.max(Math.min(255, (scale * gab + (1 - scale) * position)), 0);
      -};
      -
      -function colorFilter(binaryData, pixels)
      -{
      -   var data = binaryData;
      -   var colorValue = parseFloat((Math.random() * 0.9 + 0.1).toFixed(3));
      -   for (var i = 0; i < pixels; i += .5)
      -   {
      -      binaryData[i] = colorChange(Math.random() * 0.5 + 0.5,
      -                                  (data[i] * colorValue)
      -                                  + (data[i + 1] * 0.769)
      -                                  + (data[i + 2] * 0.189), data[i]);
      -      binaryData[i + 1] = colorChange(Math.random() * 0.5 + 0.5,
      -                                      (data[i] * 0.349)
      -                                      + (data[i + 1] * 0.686)
      -                                      + (data[i + 2] * 0.168), data[i + 1]);
      -      binaryData[i + 2] = colorChange(Math.random() * 0.5 + 0.5,
      -                                      (data[i] * 0.272)
      -                                      + (data[i + 1] * 0.534)
      -                                      + (data[i + 2] * 0.131), data[i + 2]);
      -   }
      -};
      -
      - -

      You can test the application performance using the Web Inspector. In the Timeline panel, the event of performing all the calculations in a single UI thread creates a delay of 16218 milliseconds.

      - -

      Figure: UI thread application event performance

      -

      UI thread application event performance

      - -

      Figure: UI thread application memory performance

      -

      UI thread application memory performance

      - - - - - - - - - - -
      Note
      Since launching the Web Inspector takes up a lot of CPU resources, a lot of additional delays are recorded in the Timeline panel. If the Web Inspector is not used, the delay is approximately 6000 milliseconds.
      - -

      Using Multi-thread Web Workers

      -

      The following example uses 4 Web workers to apply a color filter effect on an image by dividing the image into 4 horizontal areas and working on each area simultaneously. The time taken by the application to apply the filter is also displayed on the screen. Since all the calculations are performed by 4 Web workers simultaneously, the execution time is significantly lower (2254 milliseconds).

      - -

      Figure: Color filter application using multi-thread Web workers (in mobile applications only)

      -

      Color filter application using multi-thread Web workers (in mobile applications only)

      - -
      function colorFilterStart()
      -{
      -   var picture = document.getElementById('picture');
      -   var canvas = document.querySelector('canvas');
      -   canvas.width = document.width;
      -   canvas.height = picture.clientHeight;
      -   var tempContext = canvas.getContext("2d");
      -   var pixels = canvas.width * canvas.height * 4;
      -   tempContext.drawImage(picture, 0, 0, canvas.width, canvas.height);
      -   var workerNember = 4;
      -   var count = 0;
      -   var pixelLength = pixels / workerNember;
      -   var pixelSize = canvas.height / workerNember;
      -   var timeStart = new Date();
      -
      -   /* Loop to use multi-thread Web workers */
      -   for (var i = 0; i < workerNember; i++)
      -   {
      -      var worker = new Worker("js/worker.js");
      -      var canvasData = tempContext.getImageData(0, pixelSize * i, canvas.width, pixelSize);
      -
      -      /* Handle data received from the host worker */
      -      worker.onmessage = function(e)
      -      {
      -         count++;
      -         tempContext.putImageData(e.data.canvasData, 0, pixelSize * e.data.count);
      -         if (count == workerNember)
      -         {
      -            var timeDiffer = new Date() - timeStart;
      -            message.innerHTML = timeDiffer + " ms";
      -         }
      -      };
      -
      -      /* Send data to the host worker */
      -      worker.postMessage(
      -      { 
      -         "data": canvasData, 
      -         "length": pixelLength, 
      -         "count": i 
      -      });
      -   }
      -}
      -
      - -

      The worker.js file contains code to perform calculations for all 4 Web workers simultaneously.

      -
      onmessage = function(e)
      -{
      -   var canvasData = e.data.data;
      -   var binaryData = canvasData.data;
      -   var pixels = e.data.length;
      -   var count = e.data.count;
      -
      -   colorFilter(binaryData, pixels);
      -   postMessage(
      -   {
      -      "canvasData": canvasData,
      -      "count": count
      -   });
      -};
      -
      -function colorChange(scale, gab, position)
      -{
      -   return Math.max(Math.min(255, (scale * gab + (1 - scale) * position)), 0);
      -};
      -
      -function colorFilter(binaryData, pixels)
      -{
      -   var data = binaryData;
      -   var colorValue = parseFloat((Math.random() * 0.9 + 0.1).toFixed(3));
      -   for (var i = 0; i < pixels; i += .5)
      -   {
      -      binaryData[i] = colorChange(Math.random() * 0.5 + 0.5,
      -                                  (data[i] * colorValue)
      -                                  + (data[i + 1] * 0.769)
      -                                  + (data[i + 2] * 0.189), data[i]);
      -      binaryData[i + 1] = colorChange(Math.random() * 0.5 + 0.5,
      -                                      (data[i] * 0.349)
      -                                      + (data[i + 1] * 0.686)
      -                                      + (data[i + 2] * 0.168), data[i + 1]);
      -      binaryData[i + 2] = colorChange(Math.random() * 0.5 + 0.5,
      -                                      (data[i] * 0.272)
      -                                      + (data[i + 1] * 0.534)
      -                                      + (data[i + 2] * 0.131), data[i + 2]);
      -   }
      -};
      -
      - -

      By using 4 Web workers in the application, the application performance improves 7 times compared to using a UI thread in the same application.

      - -

      Figure: Multi-thread application event performance

      -

      Multi-thread application event performance

      - -

      Figure: Multi-thread application memory performance

      -

      Multi-thread application memory performance

      - -

      The following table shows the response speed and memory performance based on the number of Web worker threads used to run the application in a Tizen quad-core processor device.

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      - Table: Speed and memory performance -
      Number of threadsResponse speedMemory
      16760 milliseconds24.11 KB
      23820 milliseconds23.73 KB
      32730 milliseconds23.73 KB
      42340 milliseconds23.73 KB
      52120 milliseconds24.72 KB
      62820 milliseconds24.48 KB
      72340 milliseconds23.73 KB
      82400 milliseconds23.73 KB
      - - - - - - - - - - -
      Note
      The Web worker support depends on the type and version of the operating system. If the system does not support multiple processors, using multiple Web workers does not greatly improve the application performance. However, since Web workers are based on HTML5 Web optimization and can use multiple cores, they provide much better performance in Tizen as in other operating systems.
      - - - -
      - -Go to top - - - - - - + + + + + + + + + + + + + Web Workers + + + + + +
      +

      Web Workers

      + +

      Web workers run JavaScript in an independent thread instead of the main UI thread, improving the JavaScript performance without affecting the UI.

      +

      Web workers are not DOM-dependent. They handle pure data, which makes them especially suitable for JavaScript code that takes a long time to execute.

      + + + + + + + + + + +
      Note
      Workers use a same-origin policy and therefore using some of the browser resources, such as DOM, document, window, and parent, is not possible, and they must be activated by creating separate JavaScript files. However, ECMA JavaScript and the methods included in the Web Workers API, such as postMessage(), location, navigator, and importScripts() can be used. The self and location attributes are also supported.
      +

      The main features of the Web Workers API include:

      +
        +
      • Creating workers +

        +The worker creates a new thread, and only runs when it is executed. It does not communicate with the UI thread or other same-level workers, and therefore, you cannot assign a work priority order. However, you can create subworkers using the importScripts() method to divide tasks.

        +
      • + +
      • Messaging between workers +

        A subworker can communicate with the host worker using the postMessage() method of the HTML5 Web Messaging API (in mobile or wearable applications). This process is normally used to give work orders to workers or subworkers, or deliver an operation result.

        +

        +If a worker triggers a message event, the onmessage() event handler can be used to check the sent message.

        +
      • + +
      • Multi-threading +

        Multi-thread web workers provide significant advantages over UI threads with higher response speed and lower memory usage in applications.

        +
      • +
      + +

      JavaScript Performance

      +

      JavaScript was originally used for simple inspections and request handling. Therefore, the execution time was not an issue. However, with more advanced UI usage, the use of JavaScript code has been increased and become more complicated, significantly influencing the application performance.

      + +

      Improving performance through effective JavaScript code consists of the following:

      + +

      Multi-threading

      +

      Generally, Web applications are built and run using a single UI thread. Since only 1 task can be handled at a time, the Web application may not respond due to the execution time of a script block, resulting in lower application performance. To solve these performance-related issues, multi-thread Web workers can be used to provide distributed processing in applications. Use Web workers in applications that require complex calculations or parallel processing for better application performance.

      + +

      Since the task of changing the image color using a canvas involves allocating a color value for each pixel of the image displayed on the screen, the program requires a complicated calculation to execute loops by the number of the pixels. The following examples of applying a color filter effects to an image to change the color show:

      + + +

      Using UI Threads

      +

      The following example uses a UI thread to apply a color filter effect on an image and to display the time taken to apply the filter. Since all the calculations are performed in a single UI thread using the colorFilter() method, the execution time is high (16218 milliseconds).

      + +

      Figure: Color filter application using UI thread (in mobile applications only)

      +

      Color filter application using UI thread (in mobile applications only)

      + +
      function colorFilterStart()
      +{
      +   var picture = document.getElementById('picture');
      +   var canvas = document.querySelector('canvas');
      +   canvas.width = document.width;
      +   canvas.height = picture.clientHeight;
      +   var tempContext = canvas.getContext("2d");
      +   tempContext.drawImage(picture, 0, 0, canvas.width, canvas.height);
      +   var pixels = canvas.width * canvas.height * 4;
      +   var canvasData = tempContext.getImageData(0, 0, canvas.width, canvas.height);
      +   var binaryData = canvasData.data;
      +   var timeStart = new Date();
      +
      +   colorFilter(binaryData, pixels);
      +   tempContext.putImageData(canvasData, 0, 0);
      +   var timeDiffer = new Date() - timeStart;
      +   message.innerHTML = timeDiffer + " ms";
      +};
      +
      +function colorChange(scale, gab, position)
      +{
      +   return Math.max(Math.min(255, (scale * gab + (1 - scale) * position)), 0);
      +};
      +
      +function colorFilter(binaryData, pixels)
      +{
      +   var data = binaryData;
      +   var colorValue = parseFloat((Math.random() * 0.9 + 0.1).toFixed(3));
      +   for (var i = 0; i < pixels; i += .5)
      +   {
      +      binaryData[i] = colorChange(Math.random() * 0.5 + 0.5,
      +                                  (data[i] * colorValue)
      +                                  + (data[i + 1] * 0.769)
      +                                  + (data[i + 2] * 0.189), data[i]);
      +      binaryData[i + 1] = colorChange(Math.random() * 0.5 + 0.5,
      +                                      (data[i] * 0.349)
      +                                      + (data[i + 1] * 0.686)
      +                                      + (data[i + 2] * 0.168), data[i + 1]);
      +      binaryData[i + 2] = colorChange(Math.random() * 0.5 + 0.5,
      +                                      (data[i] * 0.272)
      +                                      + (data[i + 1] * 0.534)
      +                                      + (data[i + 2] * 0.131), data[i + 2]);
      +   }
      +};
      +
      + +

      You can test the application performance using the Web Inspector. In the Timeline panel, the event of performing all the calculations in a single UI thread creates a delay of 16218 milliseconds.

      + +

      Figure: UI thread application event performance

      +

      UI thread application event performance

      + +

      Figure: UI thread application memory performance

      +

      UI thread application memory performance

      + + + + + + + + + + +
      Note
      Since launching the Web Inspector takes up a lot of CPU resources, a lot of additional delays are recorded in the Timeline panel. If the Web Inspector is not used, the delay is approximately 6000 milliseconds.
      + +

      Using Multi-thread Web Workers

      +

      The following example uses 4 Web workers to apply a color filter effect on an image by dividing the image into 4 horizontal areas and working on each area simultaneously. The time taken by the application to apply the filter is also displayed on the screen. Since all the calculations are performed by 4 Web workers simultaneously, the execution time is significantly lower (2254 milliseconds).

      + +

      Figure: Color filter application using multi-thread Web workers (in mobile applications only)

      +

      Color filter application using multi-thread Web workers (in mobile applications only)

      + +
      function colorFilterStart()
      +{
      +   var picture = document.getElementById('picture');
      +   var canvas = document.querySelector('canvas');
      +   canvas.width = document.width;
      +   canvas.height = picture.clientHeight;
      +   var tempContext = canvas.getContext("2d");
      +   var pixels = canvas.width * canvas.height * 4;
      +   tempContext.drawImage(picture, 0, 0, canvas.width, canvas.height);
      +   var workerNember = 4;
      +   var count = 0;
      +   var pixelLength = pixels / workerNember;
      +   var pixelSize = canvas.height / workerNember;
      +   var timeStart = new Date();
      +
      +   /* Loop to use multi-thread Web workers */
      +   for (var i = 0; i < workerNember; i++)
      +   {
      +      var worker = new Worker("js/worker.js");
      +      var canvasData = tempContext.getImageData(0, pixelSize * i, canvas.width, pixelSize);
      +
      +      /* Handle data received from the host worker */
      +      worker.onmessage = function(e)
      +      {
      +         count++;
      +         tempContext.putImageData(e.data.canvasData, 0, pixelSize * e.data.count);
      +         if (count == workerNember)
      +         {
      +            var timeDiffer = new Date() - timeStart;
      +            message.innerHTML = timeDiffer + " ms";
      +         }
      +      };
      +
      +      /* Send data to the host worker */
      +      worker.postMessage(
      +      { 
      +         "data": canvasData, 
      +         "length": pixelLength, 
      +         "count": i 
      +      });
      +   }
      +}
      +
      + +

      The worker.js file contains code to perform calculations for all 4 Web workers simultaneously.

      +
      onmessage = function(e)
      +{
      +   var canvasData = e.data.data;
      +   var binaryData = canvasData.data;
      +   var pixels = e.data.length;
      +   var count = e.data.count;
      +
      +   colorFilter(binaryData, pixels);
      +   postMessage(
      +   {
      +      "canvasData": canvasData,
      +      "count": count
      +   });
      +};
      +
      +function colorChange(scale, gab, position)
      +{
      +   return Math.max(Math.min(255, (scale * gab + (1 - scale) * position)), 0);
      +};
      +
      +function colorFilter(binaryData, pixels)
      +{
      +   var data = binaryData;
      +   var colorValue = parseFloat((Math.random() * 0.9 + 0.1).toFixed(3));
      +   for (var i = 0; i < pixels; i += .5)
      +   {
      +      binaryData[i] = colorChange(Math.random() * 0.5 + 0.5,
      +                                  (data[i] * colorValue)
      +                                  + (data[i + 1] * 0.769)
      +                                  + (data[i + 2] * 0.189), data[i]);
      +      binaryData[i + 1] = colorChange(Math.random() * 0.5 + 0.5,
      +                                      (data[i] * 0.349)
      +                                      + (data[i + 1] * 0.686)
      +                                      + (data[i + 2] * 0.168), data[i + 1]);
      +      binaryData[i + 2] = colorChange(Math.random() * 0.5 + 0.5,
      +                                      (data[i] * 0.272)
      +                                      + (data[i + 1] * 0.534)
      +                                      + (data[i + 2] * 0.131), data[i + 2]);
      +   }
      +};
      +
      + +

      By using 4 Web workers in the application, the application performance improves 7 times compared to using a UI thread in the same application.

      + +

      Figure: Multi-thread application event performance

      +

      Multi-thread application event performance

      + +

      Figure: Multi-thread application memory performance

      +

      Multi-thread application memory performance

      + +

      The following table shows the response speed and memory performance based on the number of Web worker threads used to run the application in a Tizen quad-core processor device.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      + Table: Speed and memory performance +
      Number of threadsResponse speedMemory
      16760 milliseconds24.11 KB
      23820 milliseconds23.73 KB
      32730 milliseconds23.73 KB
      42340 milliseconds23.73 KB
      52120 milliseconds24.72 KB
      62820 milliseconds24.48 KB
      72340 milliseconds23.73 KB
      82400 milliseconds23.73 KB
      + + + + + + + + + + +
      Note
      The Web worker support depends on the type and version of the operating system. If the system does not support multiple processors, using multiple Web workers does not greatly improve the application performance. However, since Web workers are based on HTML5 Web optimization and can use multiple cores, they provide much better performance in Tizen as in other operating systems.
      + + + +
      + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/web/w3c/security/cors_w.htm b/org.tizen.guides/html/web/w3c/security/cors_w.htm index 0b9f6b1..e8d1f4d 100644 --- a/org.tizen.guides/html/web/w3c/security/cors_w.htm +++ b/org.tizen.guides/html/web/w3c/security/cors_w.htm @@ -1,130 +1,130 @@ - - - - - - - - - - - - - Cross-Origin Resource Sharing - - - - - -
      - -

      Cross-Origin Resource Sharing

      - -

      Tizen supports the mechanism of cross-origin resource sharing (CORS), which can activate a client-side cross-origin request (COR).

      -

      In CORS, new headers related to HTTP communication have been added to allow you to accept or reject CORs:

      -
        -
      • Origin request header -

        Includes the domain information which has incurred the COR, and is used for the purpose of checking the source of the domain side that has received the relevant request. In addition, this header is protected in the browser side and cannot be changed from the application side.

      • -
      • Access-Control-Allow-Origin response header -

        Allows a relevant response only when the information in the Origin request header matches. If the Access-Control-Allow-Origin header is a wildcard (*), it unconditionally allows the response regardless of the Origin request header information.

        - - - - - - - - - -
        Note
        If an extremely allowable CORS policy is used, it can lead to spoofing, data stealing, relay, and other attacks through communication with malicious application programs. To avoid unexpected consequences, pay attention when defining the response header.
        -
      • -
      - -

      CORS supports 2 request types: simple and preflight.

      - -

      Simple Request

      -

      The request is considered to be a simple request, if all the conditions following conditions are met:

      -
        -
      • HTTP methods can only use GET, POST, and HEAD.
      • -
      • No custom header is allowed.
      • -
      • The Content-Type is one of the following: -
          -
        • application/x-www-form-urlencoded
        • -
        • multipart/form-data
        • -
        • text/plain
        • -
        -
      • -
      - -

      When using simple requests, the response is set in the server side with the following response headers:

      - - -

      Figure: Simple request workflow

      -

      Simple request workflow

      - - -

      Preflight Request

      - -

      If a request is not a simple request, it is considered to be a preflight (non-simple) request, which is case-insensitive.

      -

      If the access authority is allowed through the preflight request, the actual request for sending the actual data is made. The preflight request can allow access based on various standards other than Origin, such as HTTP certification, HTTP method (for example, GET, POST, or PUT…), or the existence of a certain header.

      -

      When using preflight requests, the response is set in the server side with the following response headers:

      - - - -

      Figure: Preflight request workflow

      -

      Preflight request workflow

      - - - -
      - -Go to top - - - - - - + + + + + + + + + + + + + Cross-Origin Resource Sharing + + + + + +
      + +

      Cross-Origin Resource Sharing

      + +

      Tizen supports the mechanism of cross-origin resource sharing (CORS), which can activate a client-side cross-origin request (COR).

      +

      In CORS, new headers related to HTTP communication have been added to allow you to accept or reject CORs:

      +
        +
      • Origin request header +

        Includes the domain information which has incurred the COR, and is used for the purpose of checking the source of the domain side that has received the relevant request. In addition, this header is protected in the browser side and cannot be changed from the application side.

      • +
      • Access-Control-Allow-Origin response header +

        Allows a relevant response only when the information in the Origin request header matches. If the Access-Control-Allow-Origin header is a wildcard (*), it unconditionally allows the response regardless of the Origin request header information.

        + + + + + + + + + +
        Note
        If an extremely allowable CORS policy is used, it can lead to spoofing, data stealing, relay, and other attacks through communication with malicious application programs. To avoid unexpected consequences, pay attention when defining the response header.
        +
      • +
      + +

      CORS supports 2 request types: simple and preflight.

      + +

      Simple Request

      +

      The request is considered to be a simple request, if all the conditions following conditions are met:

      +
        +
      • HTTP methods can only use GET, POST, and HEAD.
      • +
      • No custom header is allowed.
      • +
      • The Content-Type is one of the following: +
          +
        • application/x-www-form-urlencoded
        • +
        • multipart/form-data
        • +
        • text/plain
        • +
        +
      • +
      + +

      When using simple requests, the response is set in the server side with the following response headers:

      + + +

      Figure: Simple request workflow

      +

      Simple request workflow

      + + +

      Preflight Request

      + +

      If a request is not a simple request, it is considered to be a preflight (non-simple) request, which is case-insensitive.

      +

      If the access authority is allowed through the preflight request, the actual request for sending the actual data is made. The preflight request can allow access based on various standards other than Origin, such as HTTP certification, HTTP method (for example, GET, POST, or PUT…), or the existence of a certain header.

      +

      When using preflight requests, the response is set in the server side with the following response headers:

      + + + +

      Figure: Preflight request workflow

      +

      Preflight request workflow

      + + + +
      + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/web/w3c/security/iframe_w.htm b/org.tizen.guides/html/web/w3c/security/iframe_w.htm index b23c142..a75e536 100644 --- a/org.tizen.guides/html/web/w3c/security/iframe_w.htm +++ b/org.tizen.guides/html/web/w3c/security/iframe_w.htm @@ -1,102 +1,102 @@ - - - - - - - - - - - - - HTML5 iframe element - - - - - -
      - -

      HTML5 iframe element

      - -

      The HTML5 iframe element can be used to solve security and design issues in embedded Web content.

      - -

      The main features of the iframe element include:

      - - - - - - - - - - - - -
      Note
      The scrolling, align, frameborder, marginheight, marginwidth, and longdesc HTML5 attributes are no longer supported in the latest HTML5 version.
      - - - -
      - -Go to top - - - - - - + + + + + + + + + + + + + HTML5 iframe element + + + + + +
      + +

      HTML5 iframe element

      + +

      The HTML5 iframe element can be used to solve security and design issues in embedded Web content.

      + +

      The main features of the iframe element include:

      + + + + + + + + + + + + +
      Note
      The scrolling, align, frameborder, marginheight, marginwidth, and longdesc HTML5 attributes are no longer supported in the latest HTML5 version.
      + + + +
      + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/web/w3c/security/security_guide_w.htm b/org.tizen.guides/html/web/w3c/security/security_guide_w.htm index db06ec7..344c9de 100644 --- a/org.tizen.guides/html/web/w3c/security/security_guide_w.htm +++ b/org.tizen.guides/html/web/w3c/security/security_guide_w.htm @@ -1,65 +1,65 @@ - - - - - - - - - - - - - Security - - - - - -
      - -

      Security

      -

      Security features include HTML element and client-side cross-origin request control.

      - -

      The main security features are:

      -
        -
      • HTML5 iframe element

        Enables you to allow or block specific HTML elements on a Web page.

      • -
      • Cross-Origin Resource Sharing

        Enables you to make cross-origin requests to resources, allowing a client-side Web application to obtain data retrieved from another origin.

      • -
      - - - -
      - -Go to top - - - - - - + + + + + + + + + + + + + Security + + + + + +
      + +

      Security

      +

      Security features include HTML element and client-side cross-origin request control.

      + +

      The main security features are:

      +
        +
      • HTML5 iframe element

        Enables you to allow or block specific HTML elements on a Web page.

      • +
      • Cross-Origin Resource Sharing

        Enables you to make cross-origin requests to resources, allowing a client-side Web application to obtain data retrieved from another origin.

      • +
      + + + +
      + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/web/w3c/storage/storage_guide_w.htm b/org.tizen.guides/html/web/w3c/storage/storage_guide_w.htm index deec280..12f9a0a 100644 --- a/org.tizen.guides/html/web/w3c/storage/storage_guide_w.htm +++ b/org.tizen.guides/html/web/w3c/storage/storage_guide_w.htm @@ -39,7 +39,7 @@
    • Web Storage

      Enables you to use session storage and local storage.

    -

    The following guides apply in mobile applications only:

    +

    The following guides apply in mobile applications only:

    • HTML5 Application caches

      Enables you to activate project resource caching, and manage the cached resources.

    • Web SQL Database

      Enables you to create databases and access them using SQL statements.

    • diff --git a/org.tizen.guides/html/web/w3c/supplement/camera_w.htm b/org.tizen.guides/html/web/w3c/supplement/camera_w.htm index 8ebea64..b39c258 100644 --- a/org.tizen.guides/html/web/w3c/supplement/camera_w.htm +++ b/org.tizen.guides/html/web/w3c/supplement/camera_w.htm @@ -1,86 +1,86 @@ - - - - - - - - - - - - - Camera API (Tizen Extension) - - - - - -
      - - -

      Camera API (Tizen Extension)

      - - - - - - - - - - -
      Note
      This feature is supported in wearable applications only.
      - -

      You can use the camera features in the Tizen wearable Web applications.

      -

      The main features of the Camera API (Tizen Extension) API include:

      - -
        -
      • Accessing the camera device -

        You can access the camera device retrieving the media stream from the camera.

        -
      • -
      • Managing the camera -

        You can manage the camera features in many ways:

        -
        • You can record videos and capture images.
        • -
        • You can access and set the camera settings, such as the file name for the recorded video or captured image.
      • -
      • Deallocating the camera preview stream -

        You can deallocate the camera preview stream resources when the application is invisible so that the preview stream can be assigned to another Web application.

        -
      • - -
      - - - -
      - -Go to top - - - - - - + + + + + + + + + + + + + Camera API (Tizen Extension) + + + + + +
      + + +

      Camera API (Tizen Extension)

      + + + + + + + + + + +
      Note
      This feature is supported in wearable applications only.
      + +

      You can use the camera features in the Tizen wearable Web applications.

      +

      The main features of the Camera API (Tizen Extension) API include:

      + +
        +
      • Accessing the camera device +

        You can access the camera device retrieving the media stream from the camera.

        +
      • +
      • Managing the camera +

        You can manage the camera features in many ways:

        +
        • You can record videos and capture images.
        • +
        • You can access and set the camera settings, such as the file name for the recorded video or captured image.
      • +
      • Deallocating the camera preview stream +

        You can deallocate the camera preview stream resources when the application is invisible so that the preview stream can be assigned to another Web application.

        +
      • + +
      + + + +
      + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/web/w3c/supplement/fullscreen_w.htm b/org.tizen.guides/html/web/w3c/supplement/fullscreen_w.htm index 5366a73..417a135 100644 --- a/org.tizen.guides/html/web/w3c/supplement/fullscreen_w.htm +++ b/org.tizen.guides/html/web/w3c/supplement/fullscreen_w.htm @@ -1,83 +1,83 @@ - - - - - - - - - - - - - FullScreen API - Mozilla - - - - - -
      -

      FullScreen API - Mozilla

      - - - - - - - - - - -
      Note
      This feature is supported in mobile applications only.
      - -

      You can display an element in the fullscreen mode:

      -
      • With the webkitRequestFullScreen() method, you can convert a specific element to fullscreen.
      • -
      • With the webkitCancelFullScreen() method, you can cancel the fullscreen mode.
      -

      If the element uses the :full-screen CSS pseudo-class to switch to the fullscreen mode, a style can be assigned for the fullscreen mode.

      - - - - - - - - - -
      Note
      Tizen supports the WebKit-based Fullscreen API. When using the Fullscreen API, you must include the webkit prefix.
      - - - - -
      - -Go to top - - - - - - + + + + + + + + + + + + + FullScreen API - Mozilla + + + + + +
      +

      FullScreen API - Mozilla

      + + + + + + + + + + +
      Note
      This feature is supported in mobile applications only.
      + +

      You can display an element in the fullscreen mode:

      +
      • With the webkitRequestFullScreen() method, you can convert a specific element to fullscreen.
      • +
      • With the webkitCancelFullScreen() method, you can cancel the fullscreen mode.
      +

      If the element uses the :full-screen CSS pseudo-class to switch to the fullscreen mode, a style can be assigned for the fullscreen mode.

      + + + + + + + + + +
      Note
      Tizen supports the WebKit-based Fullscreen API. When using the Fullscreen API, you must include the webkit prefix.
      + + + + +
      + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.guides/html/web/w3c/supplement/supplement_guide_w.htm b/org.tizen.guides/html/web/w3c/supplement/supplement_guide_w.htm index 90b16a0..9bc0e44 100644 --- a/org.tizen.guides/html/web/w3c/supplement/supplement_guide_w.htm +++ b/org.tizen.guides/html/web/w3c/supplement/supplement_guide_w.htm @@ -38,12 +38,12 @@
    • WebGL - Khronos

      Enables you to use the WebGL graphics library to create 3D visual elements.

    -

    The following guides apply in mobile applications only:

    +

    The following guides apply in mobile applications only:

    -

    The following guides apply in wearable applications only:

    +

    The following guides apply in wearable applications only:

    diff --git a/org.tizen.guides/html/web/w3c/ui/clipboard_w.htm b/org.tizen.guides/html/web/w3c/ui/clipboard_w.htm deleted file mode 100644 index 63ed07c..0000000 --- a/org.tizen.guides/html/web/w3c/ui/clipboard_w.htm +++ /dev/null @@ -1,81 +0,0 @@ - - - - - - - - - - - - - Clipboard API and events - - - - - -
    -

    Clipboard API and events

    - - - - - - - - - - -
    Note
    This feature is supported in mobile applications only.
    - -

    The clipboard and events feature is used for cutting, copying, and pasting content to easily transfer it between Web applications.

    - -

    The main features of Clipboard API and events include:

    - - - - -
    - -Go to top - - - - - - - \ No newline at end of file diff --git a/org.tizen.guides/html/web/w3c/ui/drag_drop_w.htm b/org.tizen.guides/html/web/w3c/ui/drag_drop_w.htm deleted file mode 100644 index a6028f5..0000000 --- a/org.tizen.guides/html/web/w3c/ui/drag_drop_w.htm +++ /dev/null @@ -1,100 +0,0 @@ - - - - - - - - - - - - - HTML5 Drag and drop - - - - - -
    -

    HTML5 Drag and drop

    - - - - - - - - - - -
    Note
    This feature is supported in mobile applications only.
    - -

    HTML5 drag and drop activates through event-based JavaScript and added attributes. -

    -

    -The main features of the HTML5 Drag and drop API include: -

    -
      -
    • Using drag and drop -

      To make an element draggable, add the draggable="true" attribute to it. Only elements thus defined as draggable can generate drag and drop events.

      -

      A drag and drop requires a source, target, and data. It is used through the following events:

      -
      • dragstart
      • -
      • drag
      • -
      • dragleave
      • -
      • dragenter
      • -
      • dragover
      • -
      • drop
      • -
      • dragend
      -

      The dragstart and drop events send data through the DataTransfer interface.

      -
    • -
    • Transferring data -

      You can transfer data from the drag source to the drop target. The DataTransfer interface instance receives the dragstart event and fills itself with the data to be transferred. It then receives a drop event, and puts the data into the drop target.

    • -
    - - - - - - - - - - -
    Note
    To use drag and drop in a Tizen device, long-press the draggable element. When the context menu appears, select the Drag menu.
    - - - -
    - -Go to top - - - - - - - \ No newline at end of file diff --git a/org.tizen.guides/html/web/w3c/ui/ui_guide_w.htm b/org.tizen.guides/html/web/w3c/ui/ui_guide_w.htm deleted file mode 100644 index bca32b2..0000000 --- a/org.tizen.guides/html/web/w3c/ui/ui_guide_w.htm +++ /dev/null @@ -1,75 +0,0 @@ - - - - - - - - - - - - - UI - - - -
    -
    -

    Mobile Web

    -
    - -
    -

    Related Info

    - -
    -
    - -
    -

    UI

    - - - - - - - - - - -
    Note
    The UI API domain is supported in mobile applications only.
    - -

    UI features allow you to manage the clipboard and drag and drop events in your application.

    -

    The main UI features are:

    - - - - -
    - -Go to top - - - - - - - \ No newline at end of file diff --git a/org.tizen.guides/html/web/w3c/useful/frame_flattening_w.htm b/org.tizen.guides/html/web/w3c/useful/frame_flattening_w.htm deleted file mode 100644 index b4046a1..0000000 --- a/org.tizen.guides/html/web/w3c/useful/frame_flattening_w.htm +++ /dev/null @@ -1,57 +0,0 @@ - - - - - - - - - - - - - - Frame Flattening - - - - - -
    -
    - -
    -
    -

    Mobile Web

    -
    - -

    Frame Flattening

    - -

    In the Tizen WebKit, content placed within the <frame> and <iframe> tags is expanded automatically according to the content size. This enables users to view the whole content at once without scrolling.

    -

    The Tizen WebKit supports this feature since scrolling through small subframes on small screen devices is a tedious task and, occasionally, causes confusion between scrolling subframes and scrolling the Web page itself.

    -

    To implement scrollable content in the Tizen WebKit, use the CSS overflow: scroll or webkit-overflow-scrolling: touch property instead of iframe.

    - - - -
    - -Go to top - - - - - - - - diff --git a/org.tizen.guides/html/web/w3c/useful/html_priority_w.htm b/org.tizen.guides/html/web/w3c/useful/html_priority_w.htm deleted file mode 100644 index 51eac0e..0000000 --- a/org.tizen.guides/html/web/w3c/useful/html_priority_w.htm +++ /dev/null @@ -1,382 +0,0 @@ - - - - - - - - - - - - - HTML Priorities - - - -
    -
    -

    Mobile Web Wearable Web

    -
    - - -
    - -
    - -

    HTML Priorities

    - -

    The HTML markup is not as important as before, because JavaScript APIs can be used to create various functionalities. For example, graphics APIs (in mobile or wearable applications) can be used for making games, media APIs (in mobile or wearable applications) for creating video chats, and communication APIs (in mobile or wearable applications) for various types of messaging. However, HTML remains the basis of Web applications, and it is useful to be familiar with its behavior.

    - -

    The structure of the HTML document can be classified into DOCTYPE and HTML DOM (Document Object Model). When an HTML document is loaded, the browser renders the contents in its screen as follows:

    -
      -
    1. HTML is parsed referring to the rules defined in the <!DOCTYPE> element.
    2. -
    3. HTML DOM tree is established.
    4. -
    5. DOM elements, including references to JavaScript, are arranged based on the information defined in the head element. This is called rendering.
    6. -
    7. The elements are painted on the screen based on CSS rules.
    8. -
    - -

    <!DOCTYPE> Element

    - -

    The <!DOCTYPE> element informs the browser of the HTML version and which rules it must follow. It is not a composition element of the HTML.

    - -

    The browser, based on the version defined in the <!DOCTYPE> element and DTD (Document Type Definition), decides how to handle the HTML before interpreting it. Therefore, the <!DOCTYPE> element must be declared at the beginning of an HTML document.

    - -
    <!--HTML5-->
    -<!DOCTYPE html>
    -
    -<!--Prior to HTML5-->
    -<!DOCTYPE html PUBLIC "{HTML Version Information}" "{DTD (Document Type Definition) file link defined by Rule in HTML DOM}">
    -
    - -

    HTML DOM Tree

    - -

    HTML DOM is a structured model to control Web elements. It is an official W3C standard to express the document regardless of platforms or languages, and the foundation of the HTML5 APIs.

    - -

    The <html> element is the top-level element of the HTML DOM tree that wraps the entire document, and it has the <head> and <body> elements as child nodes:

    - -
    <!DOCTYPE html>
    -<html>
    -   <head>
    -      <!--Content-->
    -   </head>
    -   <body>
    -      <!--Content-->
    -   </body>
    -</html>
    - -

    <head> element

    - -

    The <head> element contains the information that the browser refers to when rendering the body element to interpret information, such as the title of HTML document, CSS, JavaScript, and favicon:

    - -
    <!DOCTYPE html>
    -<html>
    -   <head>
    -      <meta charset="utf-8" />
    -      <title> Tizen (in mobile applications) or Tizen Wearable (in wearable applications) </title>
    -      <link rel="stylesheet" href="css/style.css" />
    -      <script src="/common/js/ui.js"></script>
    -   </head>
    -   <body>
    -      <!--Content-->
    -   </body>
    -</html>
    - -

    The <head> contains the following subelements:

    - -
      -
    • <title>: Defines the title of the document.
    • -
    • <meta>: Defines information, such as encoding, creator, and keywords of the document. - - - - - - - - - - -
      Note
      The viewport element, which sets the screen area, is included in the meta information.
    • -
    • <style>, <link>: Sets the styles of the document.
    • -
    • <script>, <noscript>: Adds functions to the document.
    • -
    - -

    <body> element

    - -

    The <body> element defines the area displaying content on the browser screen:

    - -
    <!DOCTYPE html>
    -<html>
    -   <head>
    -      <!--Content-->
    -   </head>
    -   <body>
    -      <section id="tizen_wrap">
    -         <header>
    -            <h1>Tizen Web App (in mobile applications) or Tizen Wearable Wep App (in wearable applications)</h1>
    -         </header>
    -         <section id="contents">
    -            <!--Content-->
    -         </section>
    -         <footer>
    -            <p>&copy; All rights reserved.</p>
    -         </footer>
    -      </section>
    -   </body>
    -</html>
    - -

    CSS Rule Priorities

    -

    The basic rule of HTML, CSS, and JavaScript is that the code is applied from the top to the bottom of the document. Sometimes the lack of understanding of the CSS rule priorities can cause a result you do not expect.

    -

    The following figure illustrates this problem in mobile applications by applying a font color to a black background.

    - -

    Figure: Expected and actual result of applying a font color (in mobile applications only)

    -

    Expected and actual result of applying a font color (in mobile applications only)

    - -

    Basic CSS Rules

    - -

    When creating a CSS document, the following rules apply:

    - -
      -
    • When more than 1 overlapping styles are applied to the same element, only the last style is visible: - -
      p {color: red}
      -p {color: blue}
      -<!--Blue color is applied-->
      -
    • -
    • The style applied in the parent node at the DOM tree is inherited. For more information, see W3C inheritance documentation. -
    • -
    • The style that has the highest CSS specificity is applied. The specificity of different elements is defined as follows: -
        -
      • ID attribute = 100
      • -
      • Class attribute = 10
      • -
      • Element = 1
      • -
      - -
      <body>
      -   <p id="target" class="target">Hello World</p>
      -</body>
      -
      -<style>
      -   p#target {color: black} /* Specificity: 101 */
      -   p#target {color: red} /* Specificity: 101 */
      -   p.target {color: blue} /* Specificity: 11 */
      -   p {color: tomato} /* Specificity: 1 */
      -</style>
      -<!--Red color is applied-->
      -
    • -
    • When the !important attribute is used, it has the highest priority: -
      <body>
      -   <p id="target" class="target">Hello World</p>
      -</body>
      -
      -<style>
      -   p#target {color: black !important}
      -   p#target {color: red}
      -   p.target {color: blue}
      -   p {color: tomato}
      -</style>
      -<!--Black color is applied-->
      -
    • -
    - -

    Keeping these rules in mind, you can use any of the following ways to achieve the expected result illustrated in the figure above:

    -
    .contents {color: #999 !important;}
    -
    -section.contents {color: #999;}
    -
    -body .contents {color: #999;}
    -
    -#container > .contents {color: #999;}
    -
    - -

    Using CSS with HTML

    - -

    There are various ways to connect CSS with HTML. Creating a separate CSS file and managing it separately is convenient when it comes to applying changes in the future. The file is connected to the HTML file using a <link> tag in the <head> element.

    - -

    In the following example, the applied order of the CSS elements is as follows:

    -
      -
    1. <link> tag in the <head> element
    2. -
    3. <style> tag in the <head> element
    4. -
    5. @import attribute in the CSS area
    6. -
    7. style attribute in a HTML element
    8. -
    - -
    <!DOCTYPE html>
    -<html>
    -   <head>
    -      <!--Link in head-->
    -      <link rel="stylesheet" href="css/style.css"/>
    -
    -      <!--Style tag in head-->
    -      <style>
    -         p {color: tomato}
    -      </style>
    -
    -      <!--@import in CSS area-->
    -      <style>
    -         @import url("css/style.css");
    -      </style>
    -   </head>
    -
    -   <body>
    -      <!--Style attribute in HTML element-->
    -      <p style="color: red">Hello World</p>
    -   </body>
    -</html>
    -
    -

    However, the priority order of the elements is as follows:

    -
      -
    1. style attribute in a HTML element
    2. -
    3. <style> tag in the <head> element
    4. -
    5. @import attribute in the CSS area
    6. -
    7. <link> tag in the <head> element
    8. -
    - -

    The style attribute in the HTML element has the highest priority after the !important attribute.

    - -

    Using the order above, if all other color styles are applied to <p> elements, the style attribute is used to apply the red color that has been directly defined in the HTML. This rule differs from the CSS specificity rules.

    - -

    Generally, when the @import attribute is used, connect to the top of CSS file that has been linked externally, as illustrated in the figure below. If the attribute is applied in the middle of the CSS file, it is difficult to know the point where CSS has been applied, and to find the file connected to the source in the future. Therefore, group the CSS file at the top.

    - - - - - - - - - - -
    Note
    Using the @import attribute gives the same result as connecting an external file, but it does not function correctly in older browsers (IE 5.5 and below).
    -

    Figure: Using the @import attribute

    -

    Using the @import attribute

    - -

    The markup in the corresponding files is as follows:

    -
      -
    • In the HTML code: -
      <head>
      -   <link rel="stylesheet" href="css/style.css"/>
      -</head>
      -
    • -
    • In the style.css file: -
      @import url("priorities1.css");
      -
      -p: after {content: " : linked in head"}
      -
      -

      Figure: Result of linking the @import attribute

      -

      Result of linking the @import attribute

    • -
    • In the priorities1.css file: -
      p: after {content: " : Using @import in CSS area"}
      -
      -

      Figure: Result of using the @import attribute in the CSS area

      -

      Result of using the @import attribute in the CSS area

    • -
    - -

    JavaScript Behavior

    -

    With the advent of HTML5, numerous powerful HTML5 APIs have been introduced. Since the usage of JavaScript has increased, it has become important to use it accurately in accordance with optimized JavaScript performance.

    - -

    JavaScript used in Web applications can be divided into the core, ECMAScript, and DOM, which all manipulate HTML. ECMAScript is executed when a method is called, or it can be executed when an event is fired within a HTML document through a linkage with DOM.

    - -

    Using JavaScript with HTML

    -

    Used with HTML, JavaScript works as follows:

    -
      -
    1. During HTML parsing, the content of the <script> tag is parsed to JavaScript Interpreter.
    2. -
    3. The Interpreter parses the received script code.
    4. -
    5. Requests that need not be handled immediately are suspended.
    6. -
    7. The handled result is passed over to the browser, which continues to parse HTML.
    8. -
    - -

    The following example shows how you can use JavaScript with HTML either by linking to a JavaScript file, or embedding it directly in the HTML code:

    -
    /* Linking from HTML */
    -<script src="js/main.js"></script>
    -
    -/* Direct use in HTML */
    -<script>
    -   var obj = document.querySelector(".animated");
    -    
    -   function animate() 
    -   {
    -      /* Execute */
    -   };
    -    
    -   /* Call the animation function when the event is fired */
    -   webkitRequestAnimationFrame(animate);  
    -</script>
    -
    -
    -

    Both ways described above give the same result in behavior. However, the position of the JavaScript code affects the order in which the methods are called.

    - - - - - - - - - -
    Note
    Previously, adding JavaScript code within head tag was recommended because it is easy to maintain. Currently, adding it to the end of the body and executing it after parsing the HTML document is common.
    - -

    JavaScript Events

    - -

    JavaScript generally calls a method when a specific event is fired. More than 70 types of events, such as onload and onclick are available.

    - -

    The following example shows the use of a simple event:

    - -
    <!--HTML-->
    -<body onload="touchEventHandler()">
    -
    -<script>
    -   /* JavaScript */
    -   /* Directly assigning */  
    -   window.onload = touchEventHandler; /* Assigns the name of the subject method */
    -    
    -   /* Event listener (W3C standard) */
    -   document.addEventListener("touchstart", touchEventHandler, false);
    -</script>
    -

    Prefer using W3C standard event listener methods. The inline JavaScript code applied directly to an HTML tag is difficult to maintain. Assigning a method directly to an event is also difficult when passing parameters, as the method needs to be assigned for every event.

    - -

    JavaScript Priorities

    - -

    The rendering order of JavaScript code is based on the following rules:

    -
      -
    • JavaScript within the <head> element is temporarily saved, but not handled.
    • -
    • JavaScript within the <body> element is immediately handled when it is parsed.
    • -
    • When the temporarily saved JavaScript content is executed, the <head> element content is rendered first, and the <body> element content after it.
    • -
    - - - -
    - -Go to top - - - - - - - \ No newline at end of file diff --git a/org.tizen.guides/html/web/w3c/useful/multiple_screens_w.htm b/org.tizen.guides/html/web/w3c/useful/multiple_screens_w.htm deleted file mode 100644 index 0a262e3..0000000 --- a/org.tizen.guides/html/web/w3c/useful/multiple_screens_w.htm +++ /dev/null @@ -1,380 +0,0 @@ - - - - - - - - - - - - - Multiple Screen Support - - - - - -
    -

    Multiple Screen Support

    - - - - - - - - - - -
    Note
    This feature is supported in mobile applications only.
    - -

    Tizen is available in various devices which support different screen sizes and resolutions. When developing Tizen Web applications, you must take this into account if you want your application to function well in various device models.

    -

    Before implementing multiple screen support, make sure you are familiar with the key concepts of multiple screen support.

    -

    Tizen provides the UI scalability resolution feature, which allows you to create scalable applications.

    -

    To optimize images used in Web applications, images based on a single resource can be used in various resolutions.

    -

    Key Concepts

    -

    Before building a Web application for multiple resolutions, make sure you are familiar with the following W3C Web content scaling standards, which must be taken into account when developing Web applications:

    -
      -
    • Viewport meta tag
    • -
    • CSS media query
    • -
    -

    Viewport Meta Tag

    -

    A viewport defines the application area that displays the Web page content.

    -

    In a Web browser, the viewport size depends on the browser window size. If the viewport is smaller than the Web content size, horizontal and vertical scrollbars are displayed for page navigation. The Web browser viewport does not support the zoom feature. However, in a mobile Web browser, there are no window scrollbars and the viewport supports the zoom feature.

    -

    The viewport meta tag enables you to customize the viewport size and zoom levels in a majority of mobile Web browsers. Using this tag, you can set the width, height, initial scale, and scale range for Web pages.

    -

    To use the viewport meta tag while developing Web applications, you must note the following:

    -
      -
    • The device-height and device-width attributes defined in the viewport meta tag are not the same as the real device width and height in pixels.
    • -
    • Using the viewport meta tag, the Web browsers of different devices display the same content with different layout size and scale factor. The scale factor is calculated using the device pixel ratio (DPR).
    • -
    -

    CSS Media Query

    -

    The CSS media query enables you to set conditions for particular media features and types to apply different CSS files for the application content. For Web content scaling, you can use the CSS media query to, for example:

    -
      -
    • Define the image resource to be used based on the screen dots per inch (DPI) ratio.
    • -
    • Determine the CSS layout to be used based on the screen width.
    • -
    -

    -

    UI Scalability

    -

    With UI scalability, you can support multiple screen resolutions in a single Tizen Web application. Tizen automatically converts and translates the size and position values that are defined in the application's logical resolution to the physical resolution at runtime. The Tizen Advanced UI (TAU) uses the viewport meta tag to fit the Web page into the device screen, and the rem unit to determine the size of the Tizen Web UI components.

    -

    Setting the Viewport

    -

    Tizen devices support a variety of screen resolutions and dots per inch (DPI) values. If the viewport meta tag is not defined, TAU uses the default viewport width and scale factor. This ensures that Web content layout varies between different screen resolutions.

    -

    In the following example, the viewport width is set to device-width, which is determined by the width of the Tizen device. The device-width value is retrieved to set similar virtual DPI values and to display UI components with similar physical sizes across all devices. (TAU uses the example value by default, if no other viewport value is defined.)

    -
    <meta name="viewport"
    -      content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no">
    -

    If the viewport width is set to device-width, the width and scale factor values are calculated by the Web browser. The following table shows different layout sizes and scale factors of the Tizen Web site (http://tizen.org) on different devices with the viewport width set to device-width.

    -
    <meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no">
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    - Table: Layout size and scale factor -
    Device screen resolutionReal screen DPIDevice DPIWeb browser pageViewport widthScale factor
    720 x 1280306320captured screen1360 px2.0
    480 x 800218240captured screen2320 px1.5
    -

    Working with Tizen Web Winsets

    -

    The default sizes of Tizen Web winsets (such as Popup, Button, and Checkbox) are designed based on the reference viewport DPI of 160. Therefore, these winsets are of similar sizes on any Tizen device if the viewport width is set to device-width.

    -

    If you manually set the viewport width of your application to a fixed value, the Tizen Web winsets may not fit appropriately in the application. To avoid the problem, Tizen Web winsets use the rem unit for the winset length, which depends on the base font size of the winset. Each Tizen Web winset theme has its own base font size, and the <html> element font size is also set to the base font size. If the viewport width is set to a fixed value, this base font size is recalculated and set to the <html> element to adjust the Tizen Web winset sizes accurately.

    -

    Creating Applications Supporting Multiple Screens

    -

    To create an application that supports multiple screen sizes, you must consider the following while coding your application:

    -
      -
    • Configuring the viewport
    • -
    • Optimizing resources
    • -
    • Creating screen resolution-independent UI
    • -
    -

    Configuring the Viewport

    -

    To use UI scalability in your application, set the viewport meta tag while creating a Web application project in IDE. To configure the viewport in the Tizen Web applications, add the viewport meta tag in the <head> section of the index.html file:

    -
    <meta name="viewport"
    -      content="width=device-width, initial-scale=1.0,
    -               minimum-scale=1.0, maximum-scale=1.0, user-scalable=no">
    -

    Optimizing Resources

    -

    By default, the Tizen Advanced UI (TAU) consists of the HD Web winsets. The winset scale is lowered for lower screen resolution devices. To optimize resources for different screen resolutions and devices, use the CSS media query for different resolutions available in Tizen. You can use CSS media queries in the HTML or CSS files.

    -

    In the HTML file:

    -
    <link media="only screen and (min-resolution: 320dpi)"
    -      href="high-quality-images.css" type= "text/css" rel="stylesheet">
    -

    In the CSS file:

    -
    @media screen and (max-resolution: 159dpi)
    -{
    -   <!--Set styles-->
    -}
    -
    -@media screen and (min-resolution: 160dpi and max-resolution: 239dpi)
    -{
    -   <!--Set styles-->
    -}
    -
    -@media screen and (min-resolution: 240dpi and max-resolution: 319dpi)
    -{
    -   <!--Set styles-->
    -}
    -
    -@media screen and (min-resolution: 320dpi)
    -{
    -   <!--Set styles-->
    -}
    -
    -

    You can also set different layout and resources for the portrait and landscape views in the CSS file:

    -
    @media screen and (orientation: portrait)
    -{
    -   <!--Set styles-->
    -}
    -
    -@media screen and (orientation: landscape)
    -{
    -   <!--Set styles-->
    -}
    -
    -

    Creating Screen Resolution-independent UI

    -

    The Tizen base font size is 22 px. This base font size value varies based on the device screen resolution. However, to create a screen resolution-independent UI, the Web browser engine renders the base font size as a logical pixel size instead of a physical pixel size.

    -

    Image Resolution Optimization

    - -

    In Web applications, optimization of applications for various platforms (regarding devices, OS, and resolution) is efficient.

    -

    Media Queries and Flexible Box Layout can be used to create flexible layouts, and to build the deployable package easily.

    - -

    Images can be used in Web applications in the following ways:

    - -

    When selecting an option from the list above, consider the type of the image resource you are going to use.

    -

    You can use the following types of image resources:

    - -

    Photos

    -

    An image can be added to an application using the HTML img tag, or CSS background property as shown in the following example:

    -
    <!--HTML-->
    -<img src="images/sample.jpg" alt="sample image" />
    -
    -<!--CSS-->
    -.photo
    -{
    -   background: url(../images/sample.jpg) 0 0 no-repeat;
    -   background-size: 100%;
    -   width: 100%;
    -   height: 200px;
    -}
    -
    -

    In terms of performance, there is no difference between the options.

    - -

    The image color is expressed based on pixels. Therefore, the higher resolution an image has, the better it looks on a large screen. For full HD display, a resolution bigger than the image size displayed on the screen is needed. However, since a high resolution image tends to have a large size, limit the image size as to fit the maximum screen size:

    -
    • 1024 x 768 px: 90 KB
    • 300 x 200 px: 39 KB
    • 300 x 200 px: 15 KB
    -

    Current full HD displays have a resolution that is 1.5 to 2 times bigger than the actual screen size. The image quality is guaranteed if you size images as 2 times bigger than their original size.

    -
    img
    -{
    -   max-width: 100%;
    -}
    -
    - -

    Figure: Enlarging a low-resolution image

    -

    Enlarging a low-resolution image

    -

    Icons

    -

    Icons generally have a fixed size. Size icon images as 2 times bigger than their original size. Using the CSS3 background-size property, you can add an image with the size of, for example, 40 x 40 px, compressed as 20 x 20 px.

    -
    .prev_icon, .next_icon
    -{
    -   padding-left: 30px;
    -   height: 30px;
    -   line-height: 30px;
    -   font-size: 1.2em;
    -   background-repeat: no-repeat;
    -   background-position: 0 50%;
    -   background-size: auto 20px;
    -}
    -
    -.prev_icon.icon1
    -{
    -   background-image: url(../images/page_navi_arrow_left_01.png);
    -}
    -
    - -

    When multiple icons are used on a page, all the image files are called separately. This slows down the loading speed and causes a large number of network roundtrips, as illustrated in the figure below.

    - -

    Figure: Network speed when calling each image separately

    -

    Calling each of image separately

    - -

    You can use the sprite image technique (grouping multiple images as one and showing the only desired images defined with the background-position property) to noticeably reduce the page loading speed without any loss in quality of the image, as the following example shows. -

    -
    .prev_icon, .next_icon
    -{
    -   background-size: 20px auto; <!--Full HD Display-->
    -   background-image: url(../images/page_navi_arrow.png);
    -}
    -
    -.prev_icon.icon1
    -{
    -   background-position: 0 0;
    -}
    -
    -.prev_icon.icon2
    -{
    -   background-position: 0 -50px;
    -}
    -
    -

    Figure: Network speed when using sprite images

    -

    Network speed when using sprite image

    -

    Animated Images

    -

    Animated images can be created in various formats and with many tools, such as GIF, JavaScript, Canvas, and SVG.

    - -

    To create a simple and repetitive animation effect as below as effectively as possible, use GIF images, JavaScript, or the CSS3 animation attribute.

    -

    Figure: JAVA mascot character in GIF (source: http://lea.verou.me)

    -

    JAVA mascot character  in GIF


    - -

    Below, the network capacity usage and timeline using the following animation types are compared using the Web Inspector:

    - - -

    GIF Animation

    - -

    Using GIF animation, the resource usage is as follows:

    -
    • Events: Fires only the painting event
    • -
    • Memory: 3 ~ 4 MB
    • -
    • Network: 10 ~ 25 ms
    • -
    - -

    Figure: Events for a GIF image

    -

    Events


    -

    Figure: Memory usage of a GIF image

    -

    Memory


    -

    Figure: Network capacity usage of a GIF image

    -

    Network


    - -

    GIF animation can be created in various resolutions without quality loss, when you use the option introduced in Photos. This, however, increases memory occupancy.

    - -

    JavaScript Animation

    - -

    JavaScript animation is less affected by enlarging or reducing its screen size. However, it uses a lot of device resources compared to using CSS3 animations:

    -
    • -Events: Event is fired every 100 ms, the interval of setInterval().
    • -Memory: Increases in proportion to time, from the initial size 90 KB.
    • -Network: Used until the animation is stopped.
    -

    Figure: Events for a JavaScript animation

    -

    Events


    -

    Figure: Memory usage of a JavaScript animation

    -

    Memory


    -

    Figure: Network capacity usage of a JavaScript animation

    -

    Network


    -

    The following example shows how JavaScript animation can be implemented:

    -
    <script>
    -   var obj = document.querySelector(".animated img"), flag = 0;
    -   function animate()
    -   {
    -      obj.src = './images/sprite_' + ((flag++) % 10) + '.png';
    -   };
    -   setInterval(animate, 100);
    -</script>
    -
    - -

    You can use the requestAnimationFrame() method of the Timing control for script-based animations API to prevent animation freezes that occur occasionally:

    - -
    <script>
    -   var obj = document.querySelector(".animated img"), flag = 0, i = 0;
    -   function animate()
    -   {
    -      if (!(i % 6)) obj.src = './images/sprite_' + ((flag++) % 10) + '.png';
    -         i++;
    -      -webkit-RequestAnimationFrame(animate);
    -   };
    -   -webkit-RequestAnimationFrame(animate);
    -</script>
    -
    - -

    CSS3 Animation

    - -

    CSS3 animation has a low usage of events, memory, and network capacity. It is efficient for animations that have a fixed size. However, since CSS3 animation is pixel-based, it is difficult to use for animations that need to be enlarged or reduced, in which case JavaScript is a better option:

    -
    • -Events: Fires only rendering and painting events
    • -Memory: 50 ~ 90 KB
    • -Network: 9 ~ 21 ms
    - -

    Figure: Events for a CSS3 animation

    -

    Events


    -

    Figure: Memory usage of a CSS3 animation

    -

    Memory


    -

    Figure: Network capacity usage of a CSS3 animation

    -

    Network


    - -

    The following example shows how CSS3 animation can be implemented:

    -
    <style>
    -   .css_animation
    -   {
    -      width: 50px;
    -      height: 70px;
    -      background-image: url(../images/sprite.png);
    -      -webkit-animation: cssAni .8s steps(10) infinite;
    -   }
    -
    -   @-webkit-keyframes cssAni
    -   {
    -      from {background-position: 0px;}
    -      to {background-position: -500px;}
    -   }
    -</style>
    -
    - - - -
    - -Go to top - - - - - - - \ No newline at end of file diff --git a/org.tizen.guides/html/web/w3c/useful/ui_layout_w.htm b/org.tizen.guides/html/web/w3c/useful/ui_layout_w.htm deleted file mode 100644 index ff63998..0000000 --- a/org.tizen.guides/html/web/w3c/useful/ui_layout_w.htm +++ /dev/null @@ -1,715 +0,0 @@ - - - - - - - - - - - - - Multiple UI Layouts - - - - - -
    -

    Multiple UI Layouts

    - - - - - - - - - - -
    Note
    This feature is supported in wearable applications only.
    - -

    To ensure the largest possible market for your application, you have to design your application layout so that your application can run on multiple Tizen devices.

    - -

    Although the Web was originally designed to structure documents for large-scaled Internet world, with CSS (Cascading Style Sheet), JavaScript, and various device APIs, it is quickly evolving to a complete runtime environment for applications. In addition, its W3C open development model and the flexibility of its CSS-based presentation make it every developer's choice as the next development platform. CSS is the key technology for flexible presentation, and it is used to describe the look and formatting of HTML documents. The role of CSS is to determine how the logical structure of the document is displayed to the user.

    - -

    The Tizen Web engine provides the basic mechanisms for fitting the application content to the target screen. However, to ensure that the application runs well on multiple devices, you must understand those mechanisms in detail. In general, select a relative layout rather than a fixed layout, because a relative layout helps to maintain usability even when the application runs on unexpected devices. To enhance usability even further, use different layouts for each device category.

    - -

    Using some CSS techniques and Tizen Web engine mechanisms, you can design your application UI layout so that it displays properly on multiple devices:

    -
    • You can use a single layout and take advantage of the auto-fitting mechanism of the Tizen Web engine to ensure that a single layout covers multiple devices.
    • -
    • You can use multiple layouts to define a separate optimal layout for each device category.
    - -

    Single Layout for Multiple Devices

    -

    A typical application developer designs an optimized UI for a target device with a fixed layout and high-quality resources. This approach usually results in a nice look for the end user, but can sometimes result in an ugly layout, which makes the application unusable. And this unfortunate result can occur merely due to a change in the device form factor.

    -

    Since the presentation and business logic are strictly separated in a Web application, it handles the device form factor change better than native applications. One single layout, taking advantage of Web technology, can ensure usability even on multiple devices with different form factors.

    - -

    To design applications with a single layout, you must consider the following issues:

    - - - -

    For a complete application layout that considers all the above issues, see Single Layout Example.

    - -

    Viewport and Other Meta Tags

    - -

    The viewport is a screen area that the Web engine displays in the UI and, in the Web world, the viewport meta tag is used to inform the Web engine that this content is written for a specific form factor, such as device width. The viewport meta tag was introduced by Apple to fill the screen resolution gap between initial Smartphone (for example, 320 px) and PC (for example, 980 px). Basically, the viewport meta tag helps the Web engine to determine the scale factor for the content on the current device.

    - -

    To use the tag in an HTML file, set its name and content:

    -
    -<meta name="viewport" content="XXX">
    -
    - -

    As shown in the following code snippet, use the viewport meta tag to tell the Web engine which device width is targeted by the application. The Web engine can estimate the scale factor based on the target content size and the real screen width. For example, usually almost all wearable applications have the following viewport meta tag, which sets the viewport width to the appropriate size based on each device:

    -
    -<meta name="viewport" content="width=device-width, user-scalable=no">
    -
    - -

    If you want to set your content layout to the target width of 320 px on every wearable device, use the following meta tag:

    -
    -<meta name="viewport" content="width=320">
    -
    - -

    The viewport meta tag has other properties, such as height, initial-scale, minimum-scale, maximum-scale, and user-scalable. However, do not use those properties unless you understand their exact meaning. Wrong values can cause the Web engine to incorrectly fit the application content to the current device.

    - -

    Relative Layout

    - -

    The relative layout concept means that the element size of all content is set as a relative unit (such as percentage), and not as absolute values (such as pixels or points). In responsive Web design, this concept is also known as fluid grid (for more information, search for responsive web design in your Web browser). To achieve a layout that works on multiple devices, you only need to know about relative layout, not all the other concepts of responsive Web design.

    -

    To implementing a relative layout, you only have to set the width and height of each element as a percentage, as shown in the following example and figure. In the example, the width and height of the number_pad element is set to 100% and 70%, not 320 px and 224 px.

    - -

    Figure: 320x320 calculator

    -

    number_pad {width: 100%; height: 70%;}

    -

    320x320 calculator

    - -

    An application with this relative layout is auto-fitted when it runs on an unexpected device, such as the device with a 360x480 resolution shown in the following figure. Even though this adjusted layout may not be as good as the original, it is good enough, since it shows a usable application UI.

    - - -

    Figure: 360x480 calculator with a relative layout

    -

    360x480 calculator with a relative layout

    - -

    The following figure shows what happens if you use an absolute 320x320 layout. The presentation is definitely ugly (with an empty white space at the bottom) and usability reduced, although the calculation logic itself still works.

    -

    Figure: 360x480 calculator with an absolute 320x320 layout

    -

    number_pad {width: 320px; height: 224px;}

    - - -

    360x480 calculator with an absolute 320x320 layout

    - - - -

    While the content layout itself becomes the application UI layout on a Web page, a typical wearable application layout consists of a header area, content area, and footer area. With this trend, many wearable Web applications are designed by separating the 3 areas explicitly.

    -

    Figure: Typical wearable Web application layout

    -

    Typical wearable Web application layout

    - -

    Not setting the place of the header and footer areas clearly can easily cause problems for your layout. In case of the header, the side-effect is relatively small. However, a wrongly defined footer area can be quite visible and lead to poor usability. The following figure shows the original layout of a pedometer application that consists of a header, content, and footer, with a Stop button set in the footer area.

    -

    Figure: 320x320 sample Web application

    -

    320x320 sample Web application

    - -

    In this case, if the position of the footer is not defined explicitly or if the position and bottom properties do not have proper values, an ugly layout can be displayed on an unexpected device, such as the 360x480 screen shown in the following figure.

    -

    Figure: Layout on 360x480

    -

    Layout on 360x480

    - -

    To make the layout correct, define the position property as fixed and set the bottom property explicitly as 0 px:

    - -
    -.footer {position: fixed; bottom: 0px;}
    -
    - -

    The following figure shows the same Web application running on the unexpected device after the footer properties are defined properly. With the correct values, the Web application is usable even on a new target, not planned during the development phase. Note that if a relative layout is also applied to the content area, the result is an even better layout and further improved usability.

    -

    Figure: Usable layout on 360x480

    -

    Usable layout on 360x480

    - -

    Flexible Media

    - -

    One of key elements used in the content area is a media element, including image and video. As all other elements, the media elements also must be placed within a relative layout to allow the application flexibly handle resolution changes. When such relative sizing is applied to a media element, it is called flexible media in responsive Web design.

    -

    The main issue when making a media element size relative is to ensure that the usable ratio does not change. The following figure shows a video element that works on both 320x320 and 360x480 resolutions, even though the aspect ratio of the screen is changed and scaled up. Basically, when handling media elements, you want to keep the size or ratio of the element the same as in the initially targeted device, even when displayed using a different resolution and aspect ratio. To achieve this, set the width and height properties of the media element with percentage and the auto keyword.

    - -

    Figure: Flexible media on 320x320 and 360x480

    -

    .video iframe {width: 100%; height: auto;}

    -

    Flexible media on 320x320 and 360x480

    - - -

    The following figure shows an example of wrong usage, where usability decreases as the video element is simply scaled up based on the aspect ratio change. If you set the video element size using a fixed size like this, you get no benefit from the increased resolution, and the layout on the whole screen becomes inharmonious, decreasing usability.

    - - -

    Figure: Fixed size media element

    -

    .video iframe {width: 320px; height: 240px;}

    -

    Fixed size media element

    - -

    Single Layout Example

    - -

    This section illustrates a complete application layout that takes advantage of the issues discussed in previous sections. In particular, it shows how to set the viewport properly to help the Web engine scaling mechanism and how to create a CSS-based layout.

    - - -

    First of all, set the targeted size of the content area as 320 px in the viewport meta tag, and disable the user-scalable property, as shown in the following code snippet.

    - -
    -<html>
    -   <head>
    -      <link href="css/style.css" rel="stylesheet" type="text/css">                                             
    -      <meta name="viewport" content="width=320px, user-scalable=no" />                                                 
    -   </head>                                                                                                           
    -   <body>
    -      <main>
    -         <div class="tile left">
    -            <div id="box1" class="box"></div>
    -         </div>            
    -         <div class="tile right">
    -            <div id="box2" class="box"></div>
    -         </div> 
    -         <div class="tile left">
    -            <div id="box3" class="box"></div>                                                                       
    -         </div>
    -         <div class="tile right">
    -            <div id="box4" class="box"></div>                                                                       
    -         </div> 
    -      </main>
    -   </body> 
    -</html>
    -
    - -

    In the above HTML code, the content area consists of 4 <div> box elements, and their UI layout is described in the style.css file. The following CSS code programs the layout and the specific box element styles that were defined in the HTML file.

    -

    The code snippet shows that the content size is set to be same as the viewport size. Each box is filled with a different color and placed so that it fills a quarter of the content area. Because each box size is defined with the width and height of 100%, the relative size of each box element remains the same even if the viewport size changes.

    - -
    -<!--Default, used for all-->
    -* {box-sizing: border-box;}
    -body, div, h1 {margin: 0px; padding: 0px;}
    -html, body {width: 100%; height: 100%; overflow-x: hidden;}
    -
    -#box1 {background-color: rgb(255, 255, 141);}
    -#box2 {background-color: rgb(165, 241, 238);}
    -#box3 {background-color: rgb(248, 179, 179);}
    -#box4 {background-color: rgb(192, 161, 246);}
    -.tile 
    -{
    -   width: 50%;
    -   height: 50%;
    -   float: left;
    -}
    -.left {padding: 10px 5px 5px 10px;}
    -.right {padding: 10px 10px 5px 5px;}
    -
    -.box 
    -{
    -   width: 100%;
    -   height: 100%;
    -}
    -
    - - -

    The following figure shows a final view when the 320 px is set as a target device in the HTML file. As defined in the CSS file, the content area fills the whole screen, 320x320 pixels, and the 4 box elements equally divide the area.

    - -

    Figure: Original layout on a target device

    -

    Original layout on a target device

    -

    The following figure shows that the relative layout and scaling are correctly applied even when the same application is run on a mobile device with the aspect ratio of 16:9.

    -

    Figure: Scaled layout on a 16:9 mobile device

    -

    Scaled layout on a 16:9 mobile device

    -

    The following code snippet shows an example where the background color is replaced with an image while the layout is exactly same as in the 4 box example. The following figures show how the layout including media elements (such as images) functions exactly like the basic box layout.

    - -
    -<!--Default, used for all-->
    -* {box-sizing: border-box;}
    -body, div, h1 {margin: 0px; padding: 0px;}
    -html, body {width: 100%; height: 100%; overflow-x: hidden;}
    -
    -#box1 {background-color: rgb(255, 255, 141);}
    -#box2 {background-color: rgb(165, 241, 238);}
    -#box3 {background-color: rgb(248, 179, 179);}
    -#box4 {background-color: rgb(192, 161, 246);}
    -.tile 
    -{
    -   width: 50%;
    -   height: 50%;
    -   float: left;
    -}
    -.left {padding: 10px 5px 5px 10px;}
    -.right {padding: 10px 10px 5px 5px;}
    -
    -.box 
    -{
    -   width: 100%;
    -   height: 100%;
    -   padding: 20px;
    -   background: no-repeat center;
    -   background-size: 100% 100%;
    -}
    -
    -#box1 {background-image: url('../a.png');}
    -#box2 {background-image: url('../b.png');}
    -#box3 {background-image: url('../c.png');}
    -#box4 {background-image: url('../d.png');}
    -
    - - - -

    Figure: Image-based layout on a target device

    -

    Image-based layout on a target device

    - -

    Figure: Image-based scaled layout on a 16:9 mobile device

    -

    Image-based scaled layout on a 16:9 mobile device

    - - -

    Multiple Layouts for Multiple Devices

    - -

    In many cases, the desired end result for your application can be achieved using scaling and a relative layout within a single layout. However, this approach does not always provide the best quality for the end user.

    -

    You can support the best possible layout and usability with some additional development efforts. For instance, you can create an application which, on a tablet, shows the main information (clock face) and also delivers more meaningful information (calendar), while on a watch device the same application only displays the main information (clock face). This kind of end result, as shown in the following figure, cannot be achieved by only scaling up the whole layout of the watch device.

    -

    Figure: Application for a watch and tablet

    -

    Application for a watch and tablet

    - -

    W3C CSS3 Media Queries already support the majority of techniques needed to provide category-based layouts. To support the optimal layout using CSS techniques and design applications with multiple layouts, you must consider the following issues:

    - - - - -

    Since the 2.3.1 version, Tizen also supports a special media query feature to provide device shape-based layouts. If you want to create an application for both square-shaped and circular-shaped devices, you can easily migrate your application to support both shapes.

    -

    Figure: Application for a square and circular device

    -

    Application for a square and circular device

    - - -

    Viewport Setting for Multiple Layouts

    -

    The difference between multiple and single layouts is that, in the multiple layouts, the content width of the viewport meta tag is set to "device-width". This sets the layout viewport width to the ideal viewport width and tells the Web engine that the application adapts to the device width. In short, the "device-width" setting is needed to create an adaptive and responsive Web application.

    - -

    To use the meta tag in an HTML file, set its name and content:

    -
    -<meta name="viewport" content="width=device-width, user-scalable=no">
    -
    - -

    Category Classification

    - -

    When creating multiple layouts, you must first configure the layout categories. In other words, a classifying category is needed to fit the layout on the current executable environment. Media queries are supported in CSS3 to give Web application information to the executable environment.

    - -

    W3C Media Queries

    -

    Media queries consist of a media type and expressions of media features.

    - -

    The media types indicate the media on which the current Web application is running. They are defined in HTML4. The following media types are supported:

    -
    • aural
    • -
    • braille
    • -
    • handheld
    • -
    • print
    • -
    • projection
    • -
    • screen
    • -
    • tty
    • -
    • tv
    • -
    - -

    You can declare that sections apply to certain media types inside a CSS style sheet. As in the following example, you can declare screen as a media type and describe its layout inside {...}. That code applies the layout inside {...} when the Web application is run on the screen type executable context.

    - -
    -@media screen {...}
    -
    - -

    Several media queries can be combined in a media query list to configure the executable environment and define the detailed layout configuration, as needed. The following example shows a case in which the Web application runs on the executable environment having a screen media type and a 500 pixel minimum width. Its final view shows the layout inside {...} to the end user.

    - -
    -@media screen and (min-width: 500px) {...}
    -
    - -

    The following table lists the CSS media features, which you can use to specify the layout utilizing the media queries.

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Table: Media features
    FeatureValueMin/MaxDescription
    colorintegeryesNumber of bits per a color component
    color-indexNumber of entries in the color lookup table
    device-aspect-ratiointeger/integerAspect ratio
    device-heightlengthOutput device height
    device-widthOutput device width
    gridintegernoSet to true for a grid-based device
    heightlengthyesRendering surface height
    monochromeintegerNumber of bits per pixel in a monochrome frame buffer
    resolutionresolution (dpi or dpcm)Resolution
    scanprogressive or interlacednoScanning process of the tv media types
    widthlengthyesRendering surface width
    - -

    Tizen Specialized Media Query

    -

    Tizen supports a special media query feature for a circular device shape. The following table lists the supported media features.

    - - - - - - - - - - -
    Note
    This feature is supported since 2.3.1.
    - - - - - - - - - - - - - - - - - - - -
    Table: Tizen specialized media feature
    FeatureValueMin/MaxDescription
    -tizen-geometric-shape"rectangle" | "circle"NoDevice shape
    - -

    You can combine this media query feature with the W3C type in your code. The final view shows the layout inside {...} to the end user:

    -
    -@media all and (-tizen-geometric-shape: circle) {...}
    -
    - - -

    Classification for Display Modes

    - -

    The display mode can be classified as portrait or landscape for a rectangle-shaped device, or circular for a circular device.

    - -

    Portrait and Landscape

    - -

    You can configure the device landscape and portrait mode using the device-aspect-ratio attribute in media queries. This approach is already commonly used in creating mobile Web applications. The following example shows how the max-device-aspect-ratio feature is used.

    -

    If you use the orientation:portrait/landscape feature, the layout can change unexpectedly when the virtual keypad is displayed. To avoid the problem, use the device-aspect-ratio to configure the portrait and landscape mode.

    -
    -@media screen and (max-width: 320px) and (max-device-aspect-ratio: 1/1) 
    -{
    -   <!--For portrait mode-->
    -}
    -@media screen and (max-width: 640px) and (min-device-aspect-ratio: 11/10) 
    -{
    -   <!--For landscape mode-->
    -}
    -
    - -

    Circular Device

    - -

    You can configure the device circular mode using the -tizen-geometric-shape attribute in the Tizen environment. The following example shows how to use the -tizen-geometric-shape feature.

    - - - - - - - - - - -
    Note
    This feature is supported since 2.3.1.
    - - -
    -@media all and (-tizen-geometric-shape: circle) 
    -{
    -   <!--For a circular device-->
    -}
    -
    - -

    Application Migration to a Circular Device

    - -

    This section illustrates an example for how you can migrate a basic application from a rectangular device (such as Gear 2 or Gear S) to a circular device. Use this example as the best practice to improve your layout.

    - -

    The example uses the following HTML and CSS code for the sample application and its layout.

    - -
    -<!--HTML code-->
    -<section id="main">
    -   <header>HEADER</header>
    -   <article id="content">
    -      lt;ul>
    -         <li>List Item 1</li>
    -         <li>List Item 2</li>
    -         <li>List Item 3</li>
    -         <li>List Item 4</li>
    -         <li>List Item 5</li>
    -         <li>List Item 6</li>
    -         <li>List Item 7</li>
    -         <li>List Item 8</li>
    -         <li>List Item 9</li>
    -         <li>List Item 10</li>
    -      </ul>
    -   </article>
    -   <footer>FOOTER</footer>
    -</section>
    -
    -<!--CSS code-->
    -html, body 
    -{
    -   height: 100%;
    -   width: 100%;
    -   padding: 0;
    -   margin: 0;
    -   font-size: 24px;
    -   overflow: hidden;
    -}
    -
    -section 
    -{
    -   width: 100%;
    -   height: 100%;
    -   overflow: auto;
    -   padding: 70px 0;
    -}
    -
    -header, footer 
    -{
    -   width: 100%;
    -   height: 70px;
    -   min-height: 70px;
    -   line-height: 70px;
    -   font-size: 30px;
    -   text-align: center;
    -   position: fixed;
    -}
    -
    -header 
    -{
    -   top: 0;
    -}
    -
    -footer 
    -{
    -   bottom: 0;
    -}
    -
    -article ul li 
    -{
    -   border-top: 1px solid rgba(52, 52, 52, 1);
    -   padding: 15px 20px;
    -   color: rgba(209, 209, 209, 1);
    -   font-size: 40px;
    -}
    -
    -article ul li:first 
    -{
    -   border-top: 0 none;
    -}
    - -

    To migrate the application, use the following steps:

    - -
      -
    1. Use a relative layout. - -

      To achieve a responsive layout for different devices, implement a relative layout. Simply set the width: 100% attribute to the layout elements in the CSS code:

      -
      -section 
      -{
      -   width: 100%;
      -   height: 100%;
      -   ...
      -}
      -
      -header, footer 
      -{
      -   width: 100%;
      -   ...
      -} 
      - - - - - - - - - -
      Note
      The relative layout concept is described in more detail in Relative Layout.
      -
    2. -
    3. Set extra spaces both at the top and bottom. - -

      During the migration, you can see how a certain portion of the rectangle view is covered over by the circular view, especially the header and the footer. To make them fully and consistently visible in the circular view, provide a "padding" space at the top and bottom of the page. In the following example migrating to a circular gear device from a rectangular Gear S, extra 77 px padding is used:

      -
      -@media all and (-tizen-geometric-shape: circle) 
      -{
      -   section {padding: 77px 0;}
      -}
      -
      - -

      Figure: Top and bottom padding

      -

      Top and bottom padding

      -
    4. -
    5. Set the header and footer position. - -

      After setting the top and bottom padding, set the header and footer position for scrolling in the circular view.

      -

      For a rectangular device with a lengthwise screen, especially Gear S, the best option is to make only the content area scrollable.

      - -

      Figure: Scrolling with a rectangular screen

      -

      Scrolling with a rectangular screen

      -

      In a circular screen, it is better to make the whole page scrollable, including the top and bottom space.

      -

      Figure: Scrolling with a circular screen

      -

      Scrolling with a circular screen

      - -

      To implement the header and footer position, use the CSS position attribute:

      -
      -<!--Rectangular device-->
      -header, footer 
      -{
      -   position: fixed;
      -}
      -
      -<!--Circular device-->
      -@media all and (-tizen-geometric-shape: circle) 
      -{
      -   header, footer 
      -   {
      -      position: static;
      -   }
      -}
      -
      - -
    6. -
    7. Move the display to the initial position. - -

      To provide a better user experience, show the entire display at the beginning, including the "top padding" space. A few seconds after the application launch, move the display back to its initial position, where the header is placed on the top without any space between itself and the edge of the screen. When the display moves like this, the users can perceive the existence of the top space.

      - -

      Figure: Moving to the initial position

      -

      Moving to the initial position

      - -

      The scroll move requires several lines of JavaScript code. In the following sample, the few (N) seconds is set to 1500 ms, but you can change the value as needed.

      -
      -(function initScrollPosition() 
      -{
      -   var SCROLL_DELAY_TIME = 1500,
      -       page = document.getElementById("main"),
      -       scrollPosition = window.parseInt(window.getComputedStyle(page)["padding-top"]),
      -       initScrollTimeoutId = null,
      -       mql = window.matchMedia("(-tizen-geometric-shape: circle)");;
      -
      -   /* The effect is applied to a circular device only, so use mediaquery */
      -   if (mql.matches) 
      -   {	
      -      page.addEventListener("scroll", function clearInitScrollCallback() 
      -      {
      -         window.clearTimeout(initScrollTimeoutId);
      -         page.removeEventListener("scroll", clearInitScrollCallback, false);
      -      }, false);
      -
      -      initScrollTimeoutId = window.setTimeout(function() 
      -      {
      -         page.scrollTop = scrollPosition;
      -      }, SCROLL_DELAY_TIME);
      -   }
      -}());
      -
      - -
    8. -
    9. Set extra attributes for a better view. - -

      Extra attributes are not mandatory in the migration process, but they can be helpful for a better application view.

      -

      Sometimes changing the layout of the basic elements is not enough to achieve a user-friendly view, and changes in other elements' layout are needed too. For example, consider setting the text-align: center attribute for the header and list items in the circular view (this attribute is already defined in the above circular screenshots). If the list is aligned to left in a circular view, the list items may not be all visible when placed out of the middle space.

      - -
      -<!--Common style for header and footer text-->
      -header, footer 
      -{
      -   text-align: center;
      -}
      -
      -<!--In a circular screen, list item has a center position-->
      -@media all and (-tizen-geometric-shape: circle) 
      -{
      -   article ul li 
      -   {
      -      text-align: center;
      -      line-height: 60px;
      -   }
      -}
      -
      -
    10. -
    - - - -
    - -Go to top - - - - - - - \ No newline at end of file diff --git a/org.tizen.guides/html/web/w3c/useful/useful_guide_w.htm b/org.tizen.guides/html/web/w3c/useful/useful_guide_w.htm index 8cfa727..cf0b44e 100644 --- a/org.tizen.guides/html/web/w3c/useful/useful_guide_w.htm +++ b/org.tizen.guides/html/web/w3c/useful/useful_guide_w.htm @@ -12,43 +12,28 @@ Useful Guides for W3C/HTML5 Features - +
    -
    -

    Mobile Web Wearable Web

    -
    -
    +
    +

    Mobile Web Wearable Web

    +
    -

    Useful Guides for W3C/HTML5 Features

    +

    Useful Guides for W3C/HTML5 Features

    Useful guides for W3C/HTML5 features include information on W3C features related to various APIs.

    -

    The main useful features are:

    - -
      -
    • HTML Priorities

      Enables you to use CSS and JavaScript code effectively with HTML elements.

    • -
    - -

    The following guides apply in mobile applications only:

    +

    The following guides apply in mobile applications only:

    -

    The following guides apply in wearable applications only:

    +

    The following guides apply in wearable applications only:

    • Performance Improvement

      Allows you to improve the performance of Tizen Web applications.

    • -
    • Multiple UI Layouts

      Allows you to design your application layout so that your application can run on multiple Tizen devices.

    diff --git a/org.tizen.guides/index.xml b/org.tizen.guides/index.xml index 34b8882..ed4afe5 100644 --- a/org.tizen.guides/index.xml +++ b/org.tizen.guides/index.xml @@ -56,42 +56,12 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - @@ -139,17 +109,9 @@ - - - - - - - - @@ -175,7 +137,7 @@ - + @@ -191,7 +153,7 @@ - + @@ -213,7 +175,7 @@ - + @@ -221,11 +183,11 @@ - + - + @@ -262,46 +224,6 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/org.tizen.guides/plugin.xml b/org.tizen.guides/plugin.xml index 90140e5..4c22a91 100644 --- a/org.tizen.guides/plugin.xml +++ b/org.tizen.guides/plugin.xml @@ -1,8 +1,8 @@ - - - - - - - - + + + + + + + + diff --git a/org.tizen.sampledescriptions/.project b/org.tizen.sampledescriptions/.project index bed8d0a..1cb0dce 100644 --- a/org.tizen.sampledescriptions/.project +++ b/org.tizen.sampledescriptions/.project @@ -1,22 +1,22 @@ - - - org.tizen.sampledescriptions_2.4.0 - - - - - - org.eclipse.pde.ManifestBuilder - - - - - org.eclipse.pde.SchemaBuilder - - - - - - org.eclipse.pde.PluginNature - - + + + org.tizen.sampledescriptions_2.4.0 + + + + + + org.eclipse.pde.ManifestBuilder + + + + + org.eclipse.pde.SchemaBuilder + + + + + + org.eclipse.pde.PluginNature + + diff --git a/org.tizen.sampledescriptions/META-INF/MANIFEST.MF b/org.tizen.sampledescriptions/META-INF/MANIFEST.MF index e984c7e..88f81e0 100644 --- a/org.tizen.sampledescriptions/META-INF/MANIFEST.MF +++ b/org.tizen.sampledescriptions/META-INF/MANIFEST.MF @@ -1,7 +1,7 @@ -Manifest-Version: 1.0 -Bundle-ManifestVersion: 1 -Bundle-Name: Tizen Sample Applications -Bundle-SymbolicName: org.tizen.sampledescriptions;singleton=true -Bundle-Version: 2.4.0 -Bundle-Vendor: The Linux Foundation - +Manifest-Version: 1.0 +Bundle-ManifestVersion: 1 +Bundle-Name: Tizen Sample Applications +Bundle-SymbolicName: org.tizen.sampledescriptions;singleton=true +Bundle-Version: 2.4.0 +Bundle-Vendor: The Linux Foundation + diff --git a/org.tizen.sampledescriptions/build.properties b/org.tizen.sampledescriptions/build.properties index b84ff38..264c2a1 100644 --- a/org.tizen.sampledescriptions/build.properties +++ b/org.tizen.sampledescriptions/build.properties @@ -1,8 +1,8 @@ -bin.includes = plugin.xml,\ - META-INF/,\ - html/,\ - build.properties,\ - .project,\ - about.html,\ - index.xml - +bin.includes = plugin.xml,\ + META-INF/,\ + html/,\ + build.properties,\ + .project,\ + about.html,\ + index.xml + diff --git a/org.tizen.sampledescriptions/html/css/snippet.css b/org.tizen.sampledescriptions/html/css/snippet.css index f880409..2be1b1f 100644 --- a/org.tizen.sampledescriptions/html/css/snippet.css +++ b/org.tizen.sampledescriptions/html/css/snippet.css @@ -1,52 +1,52 @@ -/* Pretty printing styles. Used with prettify.js. */ - -/* SPAN elements with the classes below are added by prettyprint. */ -.pln { color: #000 } /* plain text */ - -@media screen { - .str { color: #793AFF } /* string content */ - .kwd { color: #7F0055 } /* a keyword */ - .com { color: green} /* a comment */ - .typ { color: #1C1C1C } /* a type name */ - .lit { color: black } /* a literal value */ - /* punctuation, lisp open bracket, lisp close bracket */ - .pun, .opn, .clo { color: #1C1C1C} - .tag { color: #008 } /* a markup tag name */ - .atn { color: #606 } /* a markup attribute name */ - .atv { color: #080 } /* a markup attribute value */ - .dec, .var { color: #606 } /* a declaration; a variable name */ - .fun { color: red } /* a function name */ -} - -/* Use higher contrast and text-weight for printable form. */ -@media print, projection { - .str { color: #060 } - .kwd { color: #006; font-weight: bold } - .com { color: #600; font-style: italic } - .typ { color: #404; font-weight: bold } - .lit { color: #044 } - .pun, .opn, .clo { color: #440 } - .tag { color: #006; font-weight: bold } - .atn { color: #404 } - .atv { color: #060 } -} - -/* Put a border around prettyprinted code snippets. */ -pre.prettyprint { overflow: auto; padding: 2px; border: 1px solid #888 } - -/* Specify class=linenums on a pre to get line numbering */ -ol.linenums { margin-top: 0; margin-bottom: 0 } /* IE indents via margin-left */ -li.L0, -li.L1, -li.L2, -li.L3, -li.L5, -li.L6, -li.L7, -li.L8 { list-style-type: none } -/* Alternate shading for lines */ -li.L1, -li.L3, -li.L5, -li.L7, -li.L9 { background: #eee } +/* Pretty printing styles. Used with prettify.js. */ + +/* SPAN elements with the classes below are added by prettyprint. */ +.pln { color: #000 } /* plain text */ + +@media screen { + .str { color: #793AFF } /* string content */ + .kwd { color: #7F0055 } /* a keyword */ + .com { color: green} /* a comment */ + .typ { color: #1C1C1C } /* a type name */ + .lit { color: black } /* a literal value */ + /* punctuation, lisp open bracket, lisp close bracket */ + .pun, .opn, .clo { color: #1C1C1C} + .tag { color: #008 } /* a markup tag name */ + .atn { color: #606 } /* a markup attribute name */ + .atv { color: #080 } /* a markup attribute value */ + .dec, .var { color: #606 } /* a declaration; a variable name */ + .fun { color: red } /* a function name */ +} + +/* Use higher contrast and text-weight for printable form. */ +@media print, projection { + .str { color: #060 } + .kwd { color: #006; font-weight: bold } + .com { color: #600; font-style: italic } + .typ { color: #404; font-weight: bold } + .lit { color: #044 } + .pun, .opn, .clo { color: #440 } + .tag { color: #006; font-weight: bold } + .atn { color: #404 } + .atv { color: #060 } +} + +/* Put a border around prettyprinted code snippets. */ +pre.prettyprint { overflow: auto; padding: 2px; border: 1px solid #888 } + +/* Specify class=linenums on a pre to get line numbering */ +ol.linenums { margin-top: 0; margin-bottom: 0 } /* IE indents via margin-left */ +li.L0, +li.L1, +li.L2, +li.L3, +li.L5, +li.L6, +li.L7, +li.L8 { list-style-type: none } +/* Alternate shading for lines */ +li.L1, +li.L3, +li.L5, +li.L7, +li.L9 { background: #eee } diff --git a/org.tizen.sampledescriptions/html/css/styles.css b/org.tizen.sampledescriptions/html/css/styles.css index 4c8f5a8..ad7ebcb 100644 --- a/org.tizen.sampledescriptions/html/css/styles.css +++ b/org.tizen.sampledescriptions/html/css/styles.css @@ -1,756 +1,756 @@ -@charset "utf-8"; - -body { - background: white; - color: #1C1C1C; - margin-right: 20px; - margin-left: 20px; - font-size: 9pt; - font-weight: normal; - font-family: Arial, Helvetica, sans-serif; -} - -h1, h2, h3, h4, h5, h6, p, table, td, caption, th, ol, dl, dd, dt, footer { - font-family: Arial, Verdana, Helvetica, sans-serif - } - -/* Set default font to 9 pt */ -table, div, p, dl, td, caption, th, ul, ol, li, dd, dt, pre, code { - font-size: 9pt; -} - -pre, code { - font-family: "Courier New", Courier, monospace; - border: 1px solid #719cc7; - margin: 6px 1.5px; - padding: 1px 1px 1px 1px; - font-weight: normal; - font-style: normal; -} - -h1 {font-size: 24pt; color: #0E437D;} -h2 {font-size: 18pt; color: #0E437D;} -h3 {font-size: 14pt; color: #1C1C1C;} -h4 {font-size: 12pt; color: #1C1C1C;} -h5 {font-size: 10pt; color: #1C1C1C;} - -h1, h2, h3, h4, h5 { - font-weight: bold; - font-style: normal; - line-height: normal; - margin-top: 16pt; -} - -caption, p.caption { - font-size: 9pt; - color: #1C1C1C; - font-weight: bold; - text-align: left; - margin-top: 20px; - margin-bottom: 0px; -} - -ol { - margin-bottom: 20px; -} - -ul ul , ol ul, ul ol, ol ol{ - margin-top: 10px; -} - -ul li, ol li { - margin-bottom: 10px; -} - -ol.tutorstep li { - border-top: 2px solid #719cc7; - list-style-position: inside; - font-weight: bold; - margin-top: 30px; - margin-left: -20px; - padding-top: 3px; - font-size: 12pt; -} - -ol.tutorstep li p{ - font-size: 9pt; - font-weight: normal; - margin-top: 10px; -} - -ol.tutorstep ol li, ol.tutorstep li ol li, ol.tutorstep li ul li { - font-size: 9pt; - list-style-position: outside; - margin-left: 0px; - font-weight: normal; -} - -ol.tutorstep ol li p, ol.tutorstep ul li p { - font-size: 9pt; - font-weight: normal; - margin-top: 5px; -} - -ol li p, ul li p { - font-size: 9pt; - font-weight: normal; - margin-bottom: 2px; - margin-top: 2px; -} - -ol ol , ol.tutorstep ol{ - font-size: 9pt; - font-weight: normal; - list-style-type: lower-alpha; - color: #1C1C1C; - border-style: none; - margin-top: 10px; -} - -ol.tutorstep ul { - margin-top: 10px; - font-size: 9pt; -} - -ol ol li, ol ul li, ol.tutorstep ol li, ol.tutorstep ul li { - border-style: none; - margin-top: 5px; - font-size: 9pt; -} - -ul { - font-size: 9pt; - font-weight: normal; - color: #1C1C1C; -} - - -/* End of font face declarations */ - -/* Set table borders and heading row background */ -table { - border: 0px; - border-collapse: collapse; - width: 100%; - margin-top: 20px; - margin-bottom: 20px; - background: white; -} - -th { - border-top: 2px solid #719cc7; - border-right: 1px solid #c6d9f1; - border-left: 1px solid #c6d9f1; - background-color: #f3f7fb; - padding: 4px; - color: #719cc7; - font-size: 9pt; - font-weight: bold; -} - -td { - border: 1px solid #c6d9f1; - vertical-align:top; - padding: 3px 20px 5px 20px; - } - -td.middle { - border: 1px solid #c6d9f1; - vertical-align:middle; - padding: 3px 20px 5px 20px; - } - -/* Notes stand out using a light top & bottom borders with yellow background */ -table.note { - border-top: 2px solid #719cc7; - border-left: 0px; - border-right: 0px; - width: 100%; -} - -tr.note { - text-align: left; -} - -th.note { - text-align: left; - background-color: #ddd9c3; - background-image: note.gif; - border-top: 2px solid #719cc7; - border-bottom:1px solid #719cc7; - border-right: none; - -} - -td.note, p.note { - background-color: #eeece1; - color: #1C1C1C; - padding: 5px; - margin-top:12px; - margin-bottom:12px; - border: none; -} - -/* Figure titles are centered and bolded */ -p.figure , ol.tutorstep li p.figure, ol.tutorstep ol li p.figure, ol.tutorstep ul li p.figure { - text-align: center; - font-weight: bold; -} - -/* Red background and white text for things that need fixing before release */ -.fix { - background-color: red; - font-weight: bold; - color: white; - } - -/* Classes for creating collapsible content */ -#banner { - padding: 8px 4px 8px 4px; - /* top right bottom left */ - border: 1px solid #7f7f7f; - width: 100%; - background-image: url("banner.png"); - text-align: left; - font-weight: bold; - font-size: 9pt; - color: #ffffff; -} - -#toc-navigation {width: 20%; position: fixed; right: 17px; top: 0; bottom: 51px; /* overflow: auto; *//* min-width: 200px; *//* background: white; */z-index: 100;padding-top: 10px;/* padding-bottom: 88px; */margin-bottom: 89px;} -#toc {padding: 0px 20px 5px 20px; /* border: 2px solid #567a9c; */ border-radius: 15px;position: absolute;top: 78px;bottom: 9px;overflow: auto;/* margin-bottom: 5px; */padding-bottom: 5px;border-bottom: 3px transparent solid;margin-left: 5px;} -#main {width: 75%; height: 90%;} -#container {width:100%;} -#container #contents {padding:0px 0 20px; overflow: auto;position: fixed;top: 0;bottom: 0;margin-bottom: 64px;right: 200px;left: 20px;} -body.no-toc #container #contents {right: 0;padding-right:30px;} -body.no-toc #toc-navigation {width: auto;} -body.no-toc .top {right: 19px; /* float:none; */ width: 28px;} -body.no-toc #profile {float: right;right: -32px;} -body.no-toc #profile p {padding: 0; margin: 0;} -#container #contents:after {content: "."; display: block; height: 20px; clear: both; visibility: hidden;} - #container #contents>.content {/* width:75%; */min-width: 600px;/* right: 300px; *//* position: fixed; */padding-right: 5px;} - #container #contents>.content>.cont { margin-bottom:80px; padding-bottom:80px; } - -.devicespecs-util {float:right; margin-top:25px;} - .devicespecs-util ul.dutil {margin:0; padding-bottom:0; height: 11px; list-style-type:none;} - .devicespecs-util ul.dutil:after {content: "."; display: block; height: 0px; clear: both; visibility: hidden;} - .devicespecs-util ul.dutil li {float:left; margin-right:8px; padding-right:8px; background:url('../images/bg_util_bar.gif') no-repeat right center; color:#666;} - .devicespecs-util ul.dutil li.none {margin-right:0; padding-right:0; background-image:none;} - .devicespecs-util ul.dutil li a { font-size:11px; color:#666; line-height: 11px;} - .devicespecs-util ul.dutil li a:hover { color:#222; } - .devicespecs-util ul.dutil li a:active { color:#222; } - -ul.devicespecifications {clear:both; width:100%; margin:0; padding: 0;} -ul.devicespecifications > li { width:100%; margin-top:0; padding-left:0; list-style-type:none; border:1px solid #799cd3; padding: 5px 0px 5px 0px;} -ul.devicespecifications li div.devicespec-con {width:90%; margin:10px 0 20px 0; padding:0 14px; font-size: 13px;} -ul.devicespecifications li div.devicespec-tit {/*height:22px;*/ padding-right: 71px; background-color:#ffffff; position: relative;} - ul.devicespecifications li div.devicespec-tit .items-tit { /*float:left;*/ margin:0 0 0 14px; padding:0; color:#567a9c; line-height: 22px; font-size: 14px; font-style:normal; font-weight: bold;} - - ul.devicespecifications li div.devicespec-tit .items-tit-h2 { /*float:left;*/ margin: 0px 0px 0px 14px; padding:0; line-height: 22px; font-size: 18pt; color: #0E437D; font-style:normal; font-weight: bold;} - ul.devicespecifications li div.devicespec-tit .items-tit-h3 { /*float:left;*/ margin:0 0 0 14px; padding:0; line-height: 22px; font-size: 14pt; color: #1C1C1C; font-style:normal; font-weight: bold;} - ul.devicespecifications li div.devicespec-tit .items-tit-h4 { /*float:left;*/ margin:0 0 0 14px; padding:0; line-height: 22px; font-size: 12pt; color: #1C1C1C; font-style:normal; font-weight: bold;} - - ul.devicespecifications li div.devicespec-tit > span {position: absolute; top: 0; right:0;background:#416cbb; display:block; height:22px; margin-right:0; border-left: solid 1px #7a9bd4; } - ul.devicespecifications li div.devicespec-tit > span a.bt-arr {display:block; width: 55px; height:15px; margin-left:0; padding-top:5px; padding-left: 14px; text-align:left; background: url('../images/ico_arr_hidden.gif') 46px 9px no-repeat;} - ul.devicespecifications li div.devicespec-tit > span a.bt-arr em {display:inline-block; height: 14px; line-height:11px; font-size:11px; color:#fff; font-style:normal; margin-right: 8px;} - ul.devicespecifications li div.devicespec-tit > span * {vertical-align:middle;} - - ul.devicespecifications li div.devicespec-con ul.con-list { width:100%; } - ul.devicespecifications li div.devicespec-con ul.con-list li {line-height: 18px; margin:0; padding:0 0 0 7px; background: url("../images/ico_bullet_2_7.gif") 0 8px no-repeat; } - -.ul.ul, .ul.ul li {margin-bottom: 10px; list-style-type: disc; border: none;} -.ul.ul ul, .ul.ul ul li, .ol.ol ul, .ol.ol ul li {list-style-type: circle;} -.ol.ol, .ol.ol li {list-style-type: decimal; border: none;} -.ol.ol ol, .ol.ol ol li, .ul.ul ol, .ul.ul ol li {list-style-type: lower-alpha;} - -.static-cont {width:100%; margin-bottom:40px;} - -.top {text-align: right;} -.toc, ul.toc{ - margin: 10px 0px 0px 0px; - padding-left: 13px; - list-style: disc; - font-size: 9pt; - line-height: 115%; - } - -.toc-title { - font-size: 12pt; - color: #0E437D; - font-weight: bold; - font-style: normal; - line-height: normal; - margin-top: 16pt; -} - -a.top { - display:block; - float: right; - position:fixed; - width: 28px; - height:89px; - bottom:50px; - z-index: 101; - right: 19%; - } - -a img {border: 0;} - -/* Footer includes space and a gray line above */ -#footer { - position: fixed; - /* width: 100%; */ - bottom: 0px; - text-align: center; - border-top: 1px solid #CCCCCC; - background-color: #FFFFFF; - left: 21px; right: 21px; -} - -.footer {font-size: 8pt;} - -caption { - font-size: 9pt; - color: #1C1C1C; - font-weight: bold; - text-align: center; - margin-top: 20px; - margin-bottom: 0px; -} - -div.qindex, div.navpath, div.navtab{ - background-color: #e8eef2; - border: 1px solid #84b0c7; - text-align: center; - margin: 2px; - padding: 2px; -} - -div.qindex, div.navpath { - width: 100%; - line-height: 140%; -} - -div.navtab { - margin-right: 15px; -} - -/* @group Link Styling */ - -a:link { - color: #719cc7; - text-decoration: underline; - font-weight: bold; -} - -a:hover { - color: #0e437d; -} - -a:visited { - text-decoration: underline; - color: #719cc7; - font-weight: bold; -} - -a.qindex { - font-weight: bold; - padding: 2px; -} - -a.qindex:hover { - text-decoration: underline; - color: #0e437d; - padding: 2px; -} - -a.qindex:visited { - text-decoration: underline; - font-weight: bold; - color: #719cc7; - padding: 2px; -} - -a.qindexHL { - text-decoration: underline; - font-weight: bold; - background-color: #6666cc; - color: #ffffff; - padding: 2px 6px; - border: 1px double #9295C2; -} - -a.qindexHL:hover { - text-decoration: none; - background-color: #6666cc; - color: #ffffff; - padding: 2px 6px; -} - -dl.el { - margin-left: -1cm -} - -.fragment { - font-family: monospace, fixed; - font-size: 105%; -} - -pre.fragment { - border: 1px solid #CCCCCC; - background-color: #f5f5f5; - padding: 4px 6px; - margin: 4px 8px 4px 2px; -} - -div.fragment { - border: 1px solid #CCCCCC; - background-color: #f5f5f5; - padding: 6px; -} - -div.ah { - background-color: black; - font-weight: bold; - color: #ffffff; - margin-bottom: 3px; - margin-top: 3px -} - -td.md { - background-color: #f5f5f5; - font-weight: bold; -} - -td.mdname1 { - background-color: #f5f5f5; - font-weight: bold; - color: #602020; -} - -td.mdname { - background-color: #f5f5f5; - font-weight: bold; - color: #602020; - width: 600px; -} - -div.groupHeader { - margin-left: 16px; - margin-top: 12px; - margin-bottom: 6px; - font-weight: bold; -} - -div.groupText { - margin-left: 16px; - font-style: italic; -} - -td.indexkey { - background-color: #eeeeff; - font-weight: bold; - border: 1px solid #CCCCCC; - margin: 2px 0px 2px 0; - padding: 2px 10px; -} - -td.indexvalue { - background-color: #eeeeff; - border: 1px solid #CCCCCC; - padding: 2px 10px; - margin: 2px 0px; -} - -tr.memlist { - background-color: #f0f0f0; -} - -p.formulaDsp { - text-align: center; -} - -img.formulaDsp { -} - -img.formulaInl { - vertical-align: middle; -} - -/* @group Code Colorization */ - -span.keyword { color: #008000 } -span.keywordtype { color: #604020 } -span.keywordflow { color: #e08000 } -span.comment { color: #800000 } -span.preprocessor { color: #806020 } -span.stringliteral { color: #002080 } -span.charliteral { color: #008080 } -span.vhdldigit { color: #ff00ff } -span.vhdlchar { color: #000000 } -span.vhdlkeyword { color: #700070 } -span.vhdllogic { color: #ff0000 } - -.mdTable { - border: 1px solid #868686; - background-color: #F4F4FB; -} - -.mdRow { - padding: 8px 10px; -} - -/* @group Member Descriptions */ - -.mdescLeft, .mdescRight, -.memItemLeft, .memItemRight, -.memTemplItemLeft, .memTemplItemRight, .memTemplParams { - background-color: #F4F4F4A; - border: none; - margin: 4px; - padding: 3px 8px 4px 8px; -} - -.mdescLeft, .mdescRight { - padding: 0px 8px 4px 8px; - color: #555; -} - -.memItemLeft, .memItemRight, .memTemplParams { - border-top: 1px solid #DBDBDB; -} - -.memTemplParams { - color: #606060; -} - -/* @end */ - -/* @group Member Details */ - -/* Styles for detailed member documentation */ - -.memtemplate { - font-size: 80%; - color: #606060; - font-weight: normal; - margin-left: 3px; -} - -.memnav { - background-color: #eeeeff; - border: 1px solid #84b0c7; - text-align: center; - margin: 2px; - margin-right: 15px; - padding: 2px; -} - -.memitem { - padding: 0; -} - -.memname { - white-space: nowrap; - font-weight: bold; -} - -.memproto, .memdoc { - border: 1px solid #9BBCDD; -} - -.memproto { - padding: 0; - background-color: #D5E2EF; - font-weight: bold; - -webkit-border-top-left-radius: 8px; - -webkit-border-top-right-radius: 8px; - -moz-border-radius-topleft: 8px; - -moz-border-radius-topright: 8px; -} - -.memdoc { - padding: 2px 5px; - background-color: #eef3f5; - border-top-width: 0; - -webkit-border-bottom-left-radius: 8px; - -webkit-border-bottom-right-radius: 8px; - -moz-border-radius-bottomleft: 8px; - -moz-border-radius-bottomright: 8px; -} - -.memdoc p, .memdoc dl, .memdoc ul { - margin: 6px 0; -} - -.paramkey { - text-align: right; -} - -.paramtype { - white-space: nowrap; -} - -.paramname { - color: #853E0E; - white-space: nowrap; -} -.paramname em { - font-style: normal; -} - -/* @end */ - -.search { color: #003399; - font-weight: bold; -} - -form.search { - margin-bottom: 0px; - margin-top: 0px; -} - -input.search { font-size: 75%; - color: #000080; - font-weight: normal; - background-color: #eeeeff; -} - -td.tiny { - font-size: 75%; -} - -.highlight { - background-color:#E2E2FF; -} - -/*---------- ide-eclipse Styles ---------*/ -.sh_ide-eclipse{font-family: "Courier New", Courier, monospace; - margin: 0px 0px; - padding: -30px -30px -30px -30px; - font-weight: normal; - font-style: normal;} -.sh_ide-eclipse .sh_sourceCode{background-color:#fff;color:#000;font-weight:normal;font-style:normal;} -.sh_ide-eclipse .sh_sourceCode .sh_keyword{color:#7f0055;font-weight:bold;font-style:normal;} -.sh_ide-eclipse .sh_sourceCode .sh_type{color:#7f0055;font-weight:bold;font-style:normal;} -/*.sh_ide-eclipse .sh_sourceCode .sh_string{color:#00f;font-weight:normal;font-style:normal;}*/ -.sh_ide-eclipse .sh_sourceCode .sh_string{color:#2A00FF;font-weight:normal;font-style:normal;} - -.sh_ide-eclipse .sh_sourceCode .sh_regexp{color:#00f;font-weight:normal;font-style:normal;} -.sh_ide-eclipse .sh_sourceCode .sh_specialchar{color:#00f;font-weight:normal;font-style:normal;} -.sh_ide-eclipse .sh_sourceCode .sh_comment{color:#238E23;font-weight:normal;font-style:normal;} -.sh_ide-eclipse .sh_sourceCode .sh_number{color:#000;font-weight:normal;font-style:normal;} -.sh_ide-eclipse .sh_sourceCode .sh_preproc{color:#3f5fbf;font-weight:normal;font-style:normal;} -.sh_ide-eclipse .sh_sourceCode .sh_function{color:#000;font-weight:normal;font-style:normal;} -.sh_ide-eclipse .sh_sourceCode .sh_url{color:#00f;font-weight:normal;font-style:normal;} -.sh_ide-eclipse .sh_sourceCode .sh_date{color:#7f0055;font-weight:bold;font-style:normal;} -.sh_ide-eclipse .sh_sourceCode .sh_time{color:#7f0055;font-weight:bold;font-style:normal;} -.sh_ide-eclipse .sh_sourceCode .sh_file{color:#7f0055;font-weight:bold;font-style:normal;} -.sh_ide-eclipse .sh_sourceCode .sh_ip{color:#00f;font-weight:normal;font-style:normal;} -.sh_ide-eclipse .sh_sourceCode .sh_name{color:#00f;font-weight:normal;font-style:normal;} -.sh_ide-eclipse .sh_sourceCode .sh_variable{color:#7f0055;font-weight:bold;font-style:normal;} -.sh_ide-eclipse .sh_sourceCode .sh_oldfile{color:#00f;font-weight:normal;font-style:normal;} -.sh_ide-eclipse .sh_sourceCode .sh_newfile{color:#00f;font-weight:normal;font-style:normal;} -.sh_ide-eclipse .sh_sourceCode .sh_difflines{color:#7f0055;font-weight:bold;font-style:normal;} -.sh_ide-eclipse .sh_sourceCode .sh_selector{color:#7f0055;font-weight:bold;font-style:normal;} -.sh_ide-eclipse .sh_sourceCode .sh_property{color:#7f0055;font-weight:bold;font-style:normal;} -.sh_ide-eclipse .sh_sourceCode .sh_value{color:#00f;font-weight:normal;font-style:normal;} -.sh_ide-eclipse .sh_sourceCode .sh_unknown{font-family: "Courier New", Courier, monospace;} - -/*------------- STYLE FOR NAMES FROM XML FILE -------------*/ -.sh_styleFromXML{color:#800000;font-weight:bold;} -/*-------------------------------------------------------*/ - -/*-------- Snippet Base Styles ----------*/ -.snippet-wrap {position:relative;} -*:first-child+html .snippet-wrap {display:inline-block;} -* html .snippet-wrap {display:inline-block;} -.snippet-reveal{text-decoration:underline;} -.snippet-wrap .snippet-menu, .snippet-wrap .snippet-hide {position:absolute; top:-99999px; right:15px; font-size:.9em;z-index:1;background-color:transparent;} -.snippet-wrap .snippet-hide {top:auto; bottom:1px;} -*:first-child+html .snippet-wrap .snippet-hide {bottom:1px;} -* html .snippet-wrap .snippet-hide {bottom:1px;} -.snippet-wrap .snippet-menu pre, .snippet-wrap .snippet-hide pre {background-color:transparent; margin:1; padding:0;} -.snippet-wrap .snippet-menu a, .snippet-wrap .snippet-hide a {padding:1px; text-decoration:underline;} -.snippet-wrap pre.sh_sourceCode{padding:1px;line-height:120%;overflow:auto;position:relative; --moz-border-radius:0px; --webkit-border-radius:0px; -border-radius:0px; -box-shadow: 1px 1px px #000; --moz-box-shadow: 2px 2px 1px #000; --webkit-box-shadow: 1px 1px 1px #000;} -.snippet-wrap pre.snippet-textonly {padding:1em;} -*:first-child+html .snippet-wrap pre.snippet-formatted {padding:0.5em 0.5em;} -* html .snippet-wrap pre.snippet-formatted {padding:0em 0.3em;} -.snippet-reveal pre.sh_sourceCode {padding:0em 0em; text-align:right;} -.snippet-wrap .snippet-num li{padding-left:2px;} -.snippet-wrap .snippet-no-num{list-style:none; padding:0em 0em; margin:0;} -.snippet-wrap .snippet-no-num li {list-style:none; padding-left:0;} -.snippet-wrap .snippet-num {margin:1em 0 1em 1em; padding-left:2px;} -.snippet-wrap .snippet-num li {list-style:decimal-leading-zero outside none;} -.snippet-wrap .snippet-no-num li.box {padding:0 6px; margin-left:-6px;} -.snippet-wrap .snippet-num li.box {border:1px solid; list-style-position:inside; margin-left:0px; padding-left:2px;} -*:first-child+html .snippet-wrap .snippet-num li.box {margin-left:-2px;} -* html .snippet-wrap .snippet-num li.box {margin-left:-2px;} -.snippet-wrap li.box-top {border-width:0px 0px 0 !important;} -.snippet-wrap li.box-bot {border-width:0 0px 0px !important;} -.snippet-wrap li.box-mid {border-width:0 0px !important;} -.snippet-wrap .snippet-num li .box-sp {width:10px; display:inline-block;} -*:first-child+html .snippet-wrap .snippet-num li .box-sp {width:20px;} -* html .snippet-wrap .snippet-num li .box-sp {width:2px;} -.snippet-wrap .snippet-no-num li.box {border:1px solid;} -.snippet-wrap .snippet-no-num li .box-sp {display:none;} - -/* Layout fixing */ -.clfix:after {content: "."; display: block; height: 0px; clear: both; visibility: hidden;} -.clfix {display: inline-block;} -.clfix {display: block;} -* html .clfix {height: 1%;} /* Hides from IE-mac */ -.clfix {zoom:1;} /*for IE 5.5-7*/ - -.fl {float:left !important;} -.fr {float:right !important;} -.cl {clear:both;} -.rel {position:relative;} -.abs {position:absolute;} -.ac {text-align:center !important;} -.ar {text-align:right !important;} -.al {text-align:left !important;} -.at {vertical-align:top !important;} -.am {vertical-align:middle !important;} -.ab {vertical-align:bottom;} -.hand {cursor:pointer;} -.bgnone {background:none !important;} -.brnone {border:none !important;} -.b {font-weight:bold !important;} -.n {font-weight:normal !important;} -.invisible{display:block; overflow:hidden; visibility:hidden; width:0; height:0; margin:0; font-size:0; line-height:0;} -.mt5 {margin-top:5px !important;} -/* //Layout fixing */ - -@media print { .hide, .show { display: none; }} - -div#profile { - position: relative; -} -#profile p { - text-align: right; -} - -div#toc_border { - border: 2px solid rgb(86, 122, 156); border-top-left-radius: 15px; border-top-right-radius: 15px; border-bottom-right-radius: 15px; border-bottom-left-radius: 15px; height: 565px; -} - -#contents li { - padding-top: 3px; - margin-top: 5px; - /* overflow: auto; */ -} - -p { - /* overflow: auto; */ -} - -div.table { - /* overflow: auto; */ +@charset "utf-8"; + +body { + background: white; + color: #1C1C1C; + margin-right: 20px; + margin-left: 20px; + font-size: 9pt; + font-weight: normal; + font-family: Arial, Helvetica, sans-serif; +} + +h1, h2, h3, h4, h5, h6, p, table, td, caption, th, ol, dl, dd, dt, footer { + font-family: Arial, Verdana, Helvetica, sans-serif + } + +/* Set default font to 9 pt */ +table, div, p, dl, td, caption, th, ul, ol, li, dd, dt, pre, code { + font-size: 9pt; +} + +pre, code { + font-family: "Courier New", Courier, monospace; + border: 1px solid #719cc7; + margin: 6px 1.5px; + padding: 1px 1px 1px 1px; + font-weight: normal; + font-style: normal; +} + +h1 {font-size: 24pt; color: #0E437D;} +h2 {font-size: 18pt; color: #0E437D;} +h3 {font-size: 14pt; color: #1C1C1C;} +h4 {font-size: 12pt; color: #1C1C1C;} +h5 {font-size: 10pt; color: #1C1C1C;} + +h1, h2, h3, h4, h5 { + font-weight: bold; + font-style: normal; + line-height: normal; + margin-top: 16pt; +} + +caption, p.caption { + font-size: 9pt; + color: #1C1C1C; + font-weight: bold; + text-align: left; + margin-top: 20px; + margin-bottom: 0px; +} + +ol { + margin-bottom: 20px; +} + +ul ul , ol ul, ul ol, ol ol{ + margin-top: 10px; +} + +ul li, ol li { + margin-bottom: 10px; +} + +ol.tutorstep li { + border-top: 2px solid #719cc7; + list-style-position: inside; + font-weight: bold; + margin-top: 30px; + margin-left: -20px; + padding-top: 3px; + font-size: 12pt; +} + +ol.tutorstep li p{ + font-size: 9pt; + font-weight: normal; + margin-top: 10px; +} + +ol.tutorstep ol li, ol.tutorstep li ol li, ol.tutorstep li ul li { + font-size: 9pt; + list-style-position: outside; + margin-left: 0px; + font-weight: normal; +} + +ol.tutorstep ol li p, ol.tutorstep ul li p { + font-size: 9pt; + font-weight: normal; + margin-top: 5px; +} + +ol li p, ul li p { + font-size: 9pt; + font-weight: normal; + margin-bottom: 2px; + margin-top: 2px; +} + +ol ol , ol.tutorstep ol{ + font-size: 9pt; + font-weight: normal; + list-style-type: lower-alpha; + color: #1C1C1C; + border-style: none; + margin-top: 10px; +} + +ol.tutorstep ul { + margin-top: 10px; + font-size: 9pt; +} + +ol ol li, ol ul li, ol.tutorstep ol li, ol.tutorstep ul li { + border-style: none; + margin-top: 5px; + font-size: 9pt; +} + +ul { + font-size: 9pt; + font-weight: normal; + color: #1C1C1C; +} + + +/* End of font face declarations */ + +/* Set table borders and heading row background */ +table { + border: 0px; + border-collapse: collapse; + width: 100%; + margin-top: 20px; + margin-bottom: 20px; + background: white; +} + +th { + border-top: 2px solid #719cc7; + border-right: 1px solid #c6d9f1; + border-left: 1px solid #c6d9f1; + background-color: #f3f7fb; + padding: 4px; + color: #719cc7; + font-size: 9pt; + font-weight: bold; +} + +td { + border: 1px solid #c6d9f1; + vertical-align:top; + padding: 3px 20px 5px 20px; + } + +td.middle { + border: 1px solid #c6d9f1; + vertical-align:middle; + padding: 3px 20px 5px 20px; + } + +/* Notes stand out using a light top & bottom borders with yellow background */ +table.note { + border-top: 2px solid #719cc7; + border-left: 0px; + border-right: 0px; + width: 100%; +} + +tr.note { + text-align: left; +} + +th.note { + text-align: left; + background-color: #ddd9c3; + background-image: note.gif; + border-top: 2px solid #719cc7; + border-bottom:1px solid #719cc7; + border-right: none; + +} + +td.note, p.note { + background-color: #eeece1; + color: #1C1C1C; + padding: 5px; + margin-top:12px; + margin-bottom:12px; + border: none; +} + +/* Figure titles are centered and bolded */ +p.figure , ol.tutorstep li p.figure, ol.tutorstep ol li p.figure, ol.tutorstep ul li p.figure { + text-align: center; + font-weight: bold; +} + +/* Red background and white text for things that need fixing before release */ +.fix { + background-color: red; + font-weight: bold; + color: white; + } + +/* Classes for creating collapsible content */ +#banner { + padding: 8px 4px 8px 4px; + /* top right bottom left */ + border: 1px solid #7f7f7f; + width: 100%; + background-image: url("banner.png"); + text-align: left; + font-weight: bold; + font-size: 9pt; + color: #ffffff; +} + +#toc-navigation {width: 20%; position: fixed; right: 17px; top: 0; bottom: 51px; /* overflow: auto; *//* min-width: 200px; *//* background: white; */z-index: 100;padding-top: 10px;/* padding-bottom: 88px; */margin-bottom: 89px;} +#toc {padding: 0px 20px 5px 20px; /* border: 2px solid #567a9c; */ border-radius: 15px;position: absolute;top: 78px;bottom: 9px;overflow: auto;/* margin-bottom: 5px; */padding-bottom: 5px;border-bottom: 3px transparent solid;margin-left: 5px;} +#main {width: 75%; height: 90%;} +#container {width:100%;} +#container #contents {padding:0px 0 20px; overflow: auto;position: fixed;top: 0;bottom: 0;margin-bottom: 64px;right: 200px;left: 20px;} +body.no-toc #container #contents {right: 0;padding-right:30px;} +body.no-toc #toc-navigation {width: auto;} +body.no-toc .top {right: 19px; /* float:none; */ width: 28px;} +body.no-toc #profile {float: right;right: -32px;} +body.no-toc #profile p {padding: 0; margin: 0;} +#container #contents:after {content: "."; display: block; height: 20px; clear: both; visibility: hidden;} + #container #contents>.content {/* width:75%; */min-width: 600px;/* right: 300px; *//* position: fixed; */padding-right: 5px;} + #container #contents>.content>.cont { margin-bottom:80px; padding-bottom:80px; } + +.devicespecs-util {float:right; margin-top:25px;} + .devicespecs-util ul.dutil {margin:0; padding-bottom:0; height: 11px; list-style-type:none;} + .devicespecs-util ul.dutil:after {content: "."; display: block; height: 0px; clear: both; visibility: hidden;} + .devicespecs-util ul.dutil li {float:left; margin-right:8px; padding-right:8px; background:url('../images/bg_util_bar.gif') no-repeat right center; color:#666;} + .devicespecs-util ul.dutil li.none {margin-right:0; padding-right:0; background-image:none;} + .devicespecs-util ul.dutil li a { font-size:11px; color:#666; line-height: 11px;} + .devicespecs-util ul.dutil li a:hover { color:#222; } + .devicespecs-util ul.dutil li a:active { color:#222; } + +ul.devicespecifications {clear:both; width:100%; margin:0; padding: 0;} +ul.devicespecifications > li { width:100%; margin-top:0; padding-left:0; list-style-type:none; border:1px solid #799cd3; padding: 5px 0px 5px 0px;} +ul.devicespecifications li div.devicespec-con {width:90%; margin:10px 0 20px 0; padding:0 14px; font-size: 13px;} +ul.devicespecifications li div.devicespec-tit {/*height:22px;*/ padding-right: 71px; background-color:#ffffff; position: relative;} + ul.devicespecifications li div.devicespec-tit .items-tit { /*float:left;*/ margin:0 0 0 14px; padding:0; color:#567a9c; line-height: 22px; font-size: 14px; font-style:normal; font-weight: bold;} + + ul.devicespecifications li div.devicespec-tit .items-tit-h2 { /*float:left;*/ margin: 0px 0px 0px 14px; padding:0; line-height: 22px; font-size: 18pt; color: #0E437D; font-style:normal; font-weight: bold;} + ul.devicespecifications li div.devicespec-tit .items-tit-h3 { /*float:left;*/ margin:0 0 0 14px; padding:0; line-height: 22px; font-size: 14pt; color: #1C1C1C; font-style:normal; font-weight: bold;} + ul.devicespecifications li div.devicespec-tit .items-tit-h4 { /*float:left;*/ margin:0 0 0 14px; padding:0; line-height: 22px; font-size: 12pt; color: #1C1C1C; font-style:normal; font-weight: bold;} + + ul.devicespecifications li div.devicespec-tit > span {position: absolute; top: 0; right:0;background:#416cbb; display:block; height:22px; margin-right:0; border-left: solid 1px #7a9bd4; } + ul.devicespecifications li div.devicespec-tit > span a.bt-arr {display:block; width: 55px; height:15px; margin-left:0; padding-top:5px; padding-left: 14px; text-align:left; background: url('../images/ico_arr_hidden.gif') 46px 9px no-repeat;} + ul.devicespecifications li div.devicespec-tit > span a.bt-arr em {display:inline-block; height: 14px; line-height:11px; font-size:11px; color:#fff; font-style:normal; margin-right: 8px;} + ul.devicespecifications li div.devicespec-tit > span * {vertical-align:middle;} + + ul.devicespecifications li div.devicespec-con ul.con-list { width:100%; } + ul.devicespecifications li div.devicespec-con ul.con-list li {line-height: 18px; margin:0; padding:0 0 0 7px; background: url("../images/ico_bullet_2_7.gif") 0 8px no-repeat; } + +.ul.ul, .ul.ul li {margin-bottom: 10px; list-style-type: disc; border: none;} +.ul.ul ul, .ul.ul ul li, .ol.ol ul, .ol.ol ul li {list-style-type: circle;} +.ol.ol, .ol.ol li {list-style-type: decimal; border: none;} +.ol.ol ol, .ol.ol ol li, .ul.ul ol, .ul.ul ol li {list-style-type: lower-alpha;} + +.static-cont {width:100%; margin-bottom:40px;} + +.top {text-align: right;} +.toc, ul.toc{ + margin: 10px 0px 0px 0px; + padding-left: 13px; + list-style: disc; + font-size: 9pt; + line-height: 115%; + } + +.toc-title { + font-size: 12pt; + color: #0E437D; + font-weight: bold; + font-style: normal; + line-height: normal; + margin-top: 16pt; +} + +a.top { + display:block; + float: right; + position:fixed; + width: 28px; + height:89px; + bottom:50px; + z-index: 101; + right: 19%; + } + +a img {border: 0;} + +/* Footer includes space and a gray line above */ +#footer { + position: fixed; + /* width: 100%; */ + bottom: 0px; + text-align: center; + border-top: 1px solid #CCCCCC; + background-color: #FFFFFF; + left: 21px; right: 21px; +} + +.footer {font-size: 8pt;} + +caption { + font-size: 9pt; + color: #1C1C1C; + font-weight: bold; + text-align: center; + margin-top: 20px; + margin-bottom: 0px; +} + +div.qindex, div.navpath, div.navtab{ + background-color: #e8eef2; + border: 1px solid #84b0c7; + text-align: center; + margin: 2px; + padding: 2px; +} + +div.qindex, div.navpath { + width: 100%; + line-height: 140%; +} + +div.navtab { + margin-right: 15px; +} + +/* @group Link Styling */ + +a:link { + color: #719cc7; + text-decoration: underline; + font-weight: bold; +} + +a:hover { + color: #0e437d; +} + +a:visited { + text-decoration: underline; + color: #719cc7; + font-weight: bold; +} + +a.qindex { + font-weight: bold; + padding: 2px; +} + +a.qindex:hover { + text-decoration: underline; + color: #0e437d; + padding: 2px; +} + +a.qindex:visited { + text-decoration: underline; + font-weight: bold; + color: #719cc7; + padding: 2px; +} + +a.qindexHL { + text-decoration: underline; + font-weight: bold; + background-color: #6666cc; + color: #ffffff; + padding: 2px 6px; + border: 1px double #9295C2; +} + +a.qindexHL:hover { + text-decoration: none; + background-color: #6666cc; + color: #ffffff; + padding: 2px 6px; +} + +dl.el { + margin-left: -1cm +} + +.fragment { + font-family: monospace, fixed; + font-size: 105%; +} + +pre.fragment { + border: 1px solid #CCCCCC; + background-color: #f5f5f5; + padding: 4px 6px; + margin: 4px 8px 4px 2px; +} + +div.fragment { + border: 1px solid #CCCCCC; + background-color: #f5f5f5; + padding: 6px; +} + +div.ah { + background-color: black; + font-weight: bold; + color: #ffffff; + margin-bottom: 3px; + margin-top: 3px +} + +td.md { + background-color: #f5f5f5; + font-weight: bold; +} + +td.mdname1 { + background-color: #f5f5f5; + font-weight: bold; + color: #602020; +} + +td.mdname { + background-color: #f5f5f5; + font-weight: bold; + color: #602020; + width: 600px; +} + +div.groupHeader { + margin-left: 16px; + margin-top: 12px; + margin-bottom: 6px; + font-weight: bold; +} + +div.groupText { + margin-left: 16px; + font-style: italic; +} + +td.indexkey { + background-color: #eeeeff; + font-weight: bold; + border: 1px solid #CCCCCC; + margin: 2px 0px 2px 0; + padding: 2px 10px; +} + +td.indexvalue { + background-color: #eeeeff; + border: 1px solid #CCCCCC; + padding: 2px 10px; + margin: 2px 0px; +} + +tr.memlist { + background-color: #f0f0f0; +} + +p.formulaDsp { + text-align: center; +} + +img.formulaDsp { +} + +img.formulaInl { + vertical-align: middle; +} + +/* @group Code Colorization */ + +span.keyword { color: #008000 } +span.keywordtype { color: #604020 } +span.keywordflow { color: #e08000 } +span.comment { color: #800000 } +span.preprocessor { color: #806020 } +span.stringliteral { color: #002080 } +span.charliteral { color: #008080 } +span.vhdldigit { color: #ff00ff } +span.vhdlchar { color: #000000 } +span.vhdlkeyword { color: #700070 } +span.vhdllogic { color: #ff0000 } + +.mdTable { + border: 1px solid #868686; + background-color: #F4F4FB; +} + +.mdRow { + padding: 8px 10px; +} + +/* @group Member Descriptions */ + +.mdescLeft, .mdescRight, +.memItemLeft, .memItemRight, +.memTemplItemLeft, .memTemplItemRight, .memTemplParams { + background-color: #F4F4F4A; + border: none; + margin: 4px; + padding: 3px 8px 4px 8px; +} + +.mdescLeft, .mdescRight { + padding: 0px 8px 4px 8px; + color: #555; +} + +.memItemLeft, .memItemRight, .memTemplParams { + border-top: 1px solid #DBDBDB; +} + +.memTemplParams { + color: #606060; +} + +/* @end */ + +/* @group Member Details */ + +/* Styles for detailed member documentation */ + +.memtemplate { + font-size: 80%; + color: #606060; + font-weight: normal; + margin-left: 3px; +} + +.memnav { + background-color: #eeeeff; + border: 1px solid #84b0c7; + text-align: center; + margin: 2px; + margin-right: 15px; + padding: 2px; +} + +.memitem { + padding: 0; +} + +.memname { + white-space: nowrap; + font-weight: bold; +} + +.memproto, .memdoc { + border: 1px solid #9BBCDD; +} + +.memproto { + padding: 0; + background-color: #D5E2EF; + font-weight: bold; + -webkit-border-top-left-radius: 8px; + -webkit-border-top-right-radius: 8px; + -moz-border-radius-topleft: 8px; + -moz-border-radius-topright: 8px; +} + +.memdoc { + padding: 2px 5px; + background-color: #eef3f5; + border-top-width: 0; + -webkit-border-bottom-left-radius: 8px; + -webkit-border-bottom-right-radius: 8px; + -moz-border-radius-bottomleft: 8px; + -moz-border-radius-bottomright: 8px; +} + +.memdoc p, .memdoc dl, .memdoc ul { + margin: 6px 0; +} + +.paramkey { + text-align: right; +} + +.paramtype { + white-space: nowrap; +} + +.paramname { + color: #853E0E; + white-space: nowrap; +} +.paramname em { + font-style: normal; +} + +/* @end */ + +.search { color: #003399; + font-weight: bold; +} + +form.search { + margin-bottom: 0px; + margin-top: 0px; +} + +input.search { font-size: 75%; + color: #000080; + font-weight: normal; + background-color: #eeeeff; +} + +td.tiny { + font-size: 75%; +} + +.highlight { + background-color:#E2E2FF; +} + +/*---------- ide-eclipse Styles ---------*/ +.sh_ide-eclipse{font-family: "Courier New", Courier, monospace; + margin: 0px 0px; + padding: -30px -30px -30px -30px; + font-weight: normal; + font-style: normal;} +.sh_ide-eclipse .sh_sourceCode{background-color:#fff;color:#000;font-weight:normal;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_keyword{color:#7f0055;font-weight:bold;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_type{color:#7f0055;font-weight:bold;font-style:normal;} +/*.sh_ide-eclipse .sh_sourceCode .sh_string{color:#00f;font-weight:normal;font-style:normal;}*/ +.sh_ide-eclipse .sh_sourceCode .sh_string{color:#2A00FF;font-weight:normal;font-style:normal;} + +.sh_ide-eclipse .sh_sourceCode .sh_regexp{color:#00f;font-weight:normal;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_specialchar{color:#00f;font-weight:normal;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_comment{color:#238E23;font-weight:normal;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_number{color:#000;font-weight:normal;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_preproc{color:#3f5fbf;font-weight:normal;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_function{color:#000;font-weight:normal;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_url{color:#00f;font-weight:normal;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_date{color:#7f0055;font-weight:bold;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_time{color:#7f0055;font-weight:bold;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_file{color:#7f0055;font-weight:bold;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_ip{color:#00f;font-weight:normal;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_name{color:#00f;font-weight:normal;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_variable{color:#7f0055;font-weight:bold;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_oldfile{color:#00f;font-weight:normal;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_newfile{color:#00f;font-weight:normal;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_difflines{color:#7f0055;font-weight:bold;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_selector{color:#7f0055;font-weight:bold;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_property{color:#7f0055;font-weight:bold;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_value{color:#00f;font-weight:normal;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_unknown{font-family: "Courier New", Courier, monospace;} + +/*------------- STYLE FOR NAMES FROM XML FILE -------------*/ +.sh_styleFromXML{color:#800000;font-weight:bold;} +/*-------------------------------------------------------*/ + +/*-------- Snippet Base Styles ----------*/ +.snippet-wrap {position:relative;} +*:first-child+html .snippet-wrap {display:inline-block;} +* html .snippet-wrap {display:inline-block;} +.snippet-reveal{text-decoration:underline;} +.snippet-wrap .snippet-menu, .snippet-wrap .snippet-hide {position:absolute; top:-99999px; right:15px; font-size:.9em;z-index:1;background-color:transparent;} +.snippet-wrap .snippet-hide {top:auto; bottom:1px;} +*:first-child+html .snippet-wrap .snippet-hide {bottom:1px;} +* html .snippet-wrap .snippet-hide {bottom:1px;} +.snippet-wrap .snippet-menu pre, .snippet-wrap .snippet-hide pre {background-color:transparent; margin:1; padding:0;} +.snippet-wrap .snippet-menu a, .snippet-wrap .snippet-hide a {padding:1px; text-decoration:underline;} +.snippet-wrap pre.sh_sourceCode{padding:1px;line-height:120%;overflow:auto;position:relative; +-moz-border-radius:0px; +-webkit-border-radius:0px; +border-radius:0px; +box-shadow: 1px 1px px #000; +-moz-box-shadow: 2px 2px 1px #000; +-webkit-box-shadow: 1px 1px 1px #000;} +.snippet-wrap pre.snippet-textonly {padding:1em;} +*:first-child+html .snippet-wrap pre.snippet-formatted {padding:0.5em 0.5em;} +* html .snippet-wrap pre.snippet-formatted {padding:0em 0.3em;} +.snippet-reveal pre.sh_sourceCode {padding:0em 0em; text-align:right;} +.snippet-wrap .snippet-num li{padding-left:2px;} +.snippet-wrap .snippet-no-num{list-style:none; padding:0em 0em; margin:0;} +.snippet-wrap .snippet-no-num li {list-style:none; padding-left:0;} +.snippet-wrap .snippet-num {margin:1em 0 1em 1em; padding-left:2px;} +.snippet-wrap .snippet-num li {list-style:decimal-leading-zero outside none;} +.snippet-wrap .snippet-no-num li.box {padding:0 6px; margin-left:-6px;} +.snippet-wrap .snippet-num li.box {border:1px solid; list-style-position:inside; margin-left:0px; padding-left:2px;} +*:first-child+html .snippet-wrap .snippet-num li.box {margin-left:-2px;} +* html .snippet-wrap .snippet-num li.box {margin-left:-2px;} +.snippet-wrap li.box-top {border-width:0px 0px 0 !important;} +.snippet-wrap li.box-bot {border-width:0 0px 0px !important;} +.snippet-wrap li.box-mid {border-width:0 0px !important;} +.snippet-wrap .snippet-num li .box-sp {width:10px; display:inline-block;} +*:first-child+html .snippet-wrap .snippet-num li .box-sp {width:20px;} +* html .snippet-wrap .snippet-num li .box-sp {width:2px;} +.snippet-wrap .snippet-no-num li.box {border:1px solid;} +.snippet-wrap .snippet-no-num li .box-sp {display:none;} + +/* Layout fixing */ +.clfix:after {content: "."; display: block; height: 0px; clear: both; visibility: hidden;} +.clfix {display: inline-block;} +.clfix {display: block;} +* html .clfix {height: 1%;} /* Hides from IE-mac */ +.clfix {zoom:1;} /*for IE 5.5-7*/ + +.fl {float:left !important;} +.fr {float:right !important;} +.cl {clear:both;} +.rel {position:relative;} +.abs {position:absolute;} +.ac {text-align:center !important;} +.ar {text-align:right !important;} +.al {text-align:left !important;} +.at {vertical-align:top !important;} +.am {vertical-align:middle !important;} +.ab {vertical-align:bottom;} +.hand {cursor:pointer;} +.bgnone {background:none !important;} +.brnone {border:none !important;} +.b {font-weight:bold !important;} +.n {font-weight:normal !important;} +.invisible{display:block; overflow:hidden; visibility:hidden; width:0; height:0; margin:0; font-size:0; line-height:0;} +.mt5 {margin-top:5px !important;} +/* //Layout fixing */ + +@media print { .hide, .show { display: none; }} + +div#profile { + position: relative; +} +#profile p { + text-align: right; +} + +div#toc_border { + border: 2px solid rgb(86, 122, 156); border-top-left-radius: 15px; border-top-right-radius: 15px; border-bottom-right-radius: 15px; border-bottom-left-radius: 15px; height: 565px; +} + +#contents li { + padding-top: 3px; + margin-top: 5px; + /* overflow: auto; */ +} + +p { + /* overflow: auto; */ +} + +div.table { + /* overflow: auto; */ } \ No newline at end of file diff --git a/org.tizen.sampledescriptions/html/images/DigitalWatch_sd1.png b/org.tizen.sampledescriptions/html/images/DigitalWatch_sd1.png deleted file mode 100644 index a35c9da..0000000 Binary files a/org.tizen.sampledescriptions/html/images/DigitalWatch_sd1.png and /dev/null differ diff --git a/org.tizen.sampledescriptions/html/images/DigitalWatch_sd2.png b/org.tizen.sampledescriptions/html/images/DigitalWatch_sd2.png deleted file mode 100644 index 0f073cd..0000000 Binary files a/org.tizen.sampledescriptions/html/images/DigitalWatch_sd2.png and /dev/null differ diff --git a/org.tizen.sampledescriptions/html/images/analog_watch_sd_wn.png b/org.tizen.sampledescriptions/html/images/analog_watch_sd_wn.png new file mode 100644 index 0000000..55e53fe Binary files /dev/null and b/org.tizen.sampledescriptions/html/images/analog_watch_sd_wn.png differ diff --git a/org.tizen.sampledescriptions/html/images/analog_watch_tree_sd_wn.png b/org.tizen.sampledescriptions/html/images/analog_watch_tree_sd_wn.png new file mode 100644 index 0000000..58bd40b Binary files /dev/null and b/org.tizen.sampledescriptions/html/images/analog_watch_tree_sd_wn.png differ diff --git a/org.tizen.sampledescriptions/html/images/appcalleecaller_mw.png b/org.tizen.sampledescriptions/html/images/appcalleecaller_mw.png deleted file mode 100644 index 3ebc9a6..0000000 Binary files a/org.tizen.sampledescriptions/html/images/appcalleecaller_mw.png and /dev/null differ diff --git a/org.tizen.sampledescriptions/html/images/bluetoothchat_circle_sd.png b/org.tizen.sampledescriptions/html/images/bluetoothchat_circle_sd.png new file mode 100644 index 0000000..f66c4d3 Binary files /dev/null and b/org.tizen.sampledescriptions/html/images/bluetoothchat_circle_sd.png differ diff --git a/org.tizen.sampledescriptions/html/images/cairo_basic.png b/org.tizen.sampledescriptions/html/images/cairo_basic.png new file mode 100644 index 0000000..d7f49bf Binary files /dev/null and b/org.tizen.sampledescriptions/html/images/cairo_basic.png differ diff --git a/org.tizen.sampledescriptions/html/images/cairo_basic_circular.png b/org.tizen.sampledescriptions/html/images/cairo_basic_circular.png new file mode 100644 index 0000000..6af469a Binary files /dev/null and b/org.tizen.sampledescriptions/html/images/cairo_basic_circular.png differ diff --git a/org.tizen.sampledescriptions/html/images/cairo_evasgl.png b/org.tizen.sampledescriptions/html/images/cairo_evasgl.png new file mode 100644 index 0000000..1061df2 Binary files /dev/null and b/org.tizen.sampledescriptions/html/images/cairo_evasgl.png differ diff --git a/org.tizen.sampledescriptions/html/images/cairo_evasgl_circular.png b/org.tizen.sampledescriptions/html/images/cairo_evasgl_circular.png new file mode 100644 index 0000000..635568f Binary files /dev/null and b/org.tizen.sampledescriptions/html/images/cairo_evasgl_circular.png differ diff --git a/org.tizen.sampledescriptions/html/images/digital_watch_sd_wn.png b/org.tizen.sampledescriptions/html/images/digital_watch_sd_wn.png new file mode 100644 index 0000000..9b6cfed Binary files /dev/null and b/org.tizen.sampledescriptions/html/images/digital_watch_sd_wn.png differ diff --git a/org.tizen.sampledescriptions/html/images/evas_gl_sd_wn.png b/org.tizen.sampledescriptions/html/images/evas_gl_sd_wn.png new file mode 100644 index 0000000..a182c00 Binary files /dev/null and b/org.tizen.sampledescriptions/html/images/evas_gl_sd_wn.png differ diff --git a/org.tizen.sampledescriptions/html/images/fmradio_sd_mw.png b/org.tizen.sampledescriptions/html/images/fmradio_sd_mw.png new file mode 100644 index 0000000..ebb10b9 Binary files /dev/null and b/org.tizen.sampledescriptions/html/images/fmradio_sd_mw.png differ diff --git a/org.tizen.sampledescriptions/html/images/glview11_cube_wn.png b/org.tizen.sampledescriptions/html/images/glview11_cube_wn.png new file mode 100644 index 0000000..8fd51cd Binary files /dev/null and b/org.tizen.sampledescriptions/html/images/glview11_cube_wn.png differ diff --git a/org.tizen.sampledescriptions/html/images/glview_cube_wn.png b/org.tizen.sampledescriptions/html/images/glview_cube_wn.png new file mode 100644 index 0000000..e1f0c09 Binary files /dev/null and b/org.tizen.sampledescriptions/html/images/glview_cube_wn.png differ diff --git a/org.tizen.sampledescriptions/html/images/glview_shader_wn.png b/org.tizen.sampledescriptions/html/images/glview_shader_wn.png new file mode 100644 index 0000000..5e03811 Binary files /dev/null and b/org.tizen.sampledescriptions/html/images/glview_shader_wn.png differ diff --git a/org.tizen.sampledescriptions/html/images/lockscreen_ui_diagram.png b/org.tizen.sampledescriptions/html/images/lockscreen_ui_diagram.png new file mode 100644 index 0000000..07888d9 Binary files /dev/null and b/org.tizen.sampledescriptions/html/images/lockscreen_ui_diagram.png differ diff --git a/org.tizen.sampledescriptions/html/images/screen_locked.png b/org.tizen.sampledescriptions/html/images/screen_locked.png new file mode 100644 index 0000000..e4ef202 Binary files /dev/null and b/org.tizen.sampledescriptions/html/images/screen_locked.png differ diff --git a/org.tizen.sampledescriptions/html/images/screen_unlock_1.png b/org.tizen.sampledescriptions/html/images/screen_unlock_1.png new file mode 100644 index 0000000..1ec26e6 Binary files /dev/null and b/org.tizen.sampledescriptions/html/images/screen_unlock_1.png differ diff --git a/org.tizen.sampledescriptions/html/images/screen_unlock_2.png b/org.tizen.sampledescriptions/html/images/screen_unlock_2.png new file mode 100644 index 0000000..bac01d3 Binary files /dev/null and b/org.tizen.sampledescriptions/html/images/screen_unlock_2.png differ diff --git a/org.tizen.sampledescriptions/html/images/screen_unlocked.png b/org.tizen.sampledescriptions/html/images/screen_unlocked.png new file mode 100644 index 0000000..f8c6799 Binary files /dev/null and b/org.tizen.sampledescriptions/html/images/screen_unlocked.png differ diff --git a/org.tizen.sampledescriptions/html/images/soundmanager_sd_mw.png b/org.tizen.sampledescriptions/html/images/soundmanager_sd_mw.png new file mode 100644 index 0000000..9077ea2 Binary files /dev/null and b/org.tizen.sampledescriptions/html/images/soundmanager_sd_mw.png differ diff --git a/org.tizen.sampledescriptions/html/images/volume_sample_screenshot.png b/org.tizen.sampledescriptions/html/images/volume_sample_screenshot.png new file mode 100644 index 0000000..6a2e85c Binary files /dev/null and b/org.tizen.sampledescriptions/html/images/volume_sample_screenshot.png differ diff --git a/org.tizen.sampledescriptions/html/images/widget_application_sd.png b/org.tizen.sampledescriptions/html/images/widget_application_sd.png new file mode 100644 index 0000000..700389f Binary files /dev/null and b/org.tizen.sampledescriptions/html/images/widget_application_sd.png differ diff --git a/org.tizen.sampledescriptions/html/index.htm b/org.tizen.sampledescriptions/html/index.htm index 5cdd220..75a457d 100644 --- a/org.tizen.sampledescriptions/html/index.htm +++ b/org.tizen.sampledescriptions/html/index.htm @@ -26,7 +26,6 @@
    • Mobile Web
        -
      • AppCaller and AppCallee
      • ArchiveManager
      • BluetoothChat
      • Calculator
      • @@ -40,6 +39,7 @@
      • EventManager
      • ExcercisePlanner
      • FileManager
      • +
      • FMRadio
      • HelloTizen
      • MediaContent
      • MoneyBook
      • @@ -50,6 +50,7 @@
      • Piano
      • SelfCamera
      • SensorBall
      • +
      • SoundManager
      • Systeminfo
      • TizenWinset
      • TouchPaint
      • @@ -87,6 +88,8 @@
      • Mobile Native diff --git a/org.tizen.sampledescriptions/html/mobile_n/cairo_basic_sd_mn.htm b/org.tizen.sampledescriptions/html/mobile_n/cairo_basic_sd_mn.htm new file mode 100644 index 0000000..8b13090 --- /dev/null +++ b/org.tizen.sampledescriptions/html/mobile_n/cairo_basic_sd_mn.htm @@ -0,0 +1,183 @@ + + + + + + + + + + + + + + Cairo Basic Sample Overview + + + + +
        +
        + +
        +
        +

        Mobile native

        +
        + +

        Cairo Basic Sample Overview

        + +

        The Cairo Basic sample application demonstrates how to use a Cairo image backend with the Tizen SDK.

        + + + + + + + + + +
        Note
        The application presented in this overview is not a full Tizen application, since it does not use the Application Framework. The application simply starts and runs.
        + +

        The following figure illustrates the main screen of the Cairo Basic.

        +

        Figure: Cairo Basic screen

        +

        Cairo Basic rectangular screen

        + +

        Implementation

        + +

        First create a basic application. This provides a basic UI application skeleton which already makes available the window object that can contain the Cairo drawing.

        +
          +
        1. Include the <cairo.h> and <math.h> header files, which are needed for this sample application. +
          +#include <cairo.h>
          +#include <math.h>
          +
          + +
        2. +
        3. You can define the appdata structure that contains all the pointers to objects to be manipulated. +
          +typedef struct appdata 
          +{
          +   Evas_Object *win;	
          +   Evas_Object *img;
          +   cairo_surface_t *surface;
          +   cairo_t *cairo;
          +   unsigned char *pixels;
          +} appdata_s;
          +
          +
        4. +
        5. To display the Cairo drawing on the screen, create the Elm_window and the Evas_object image. +

          When creating the Elm_window, you can set the name as your PACKAGE name. It is created when you create this project in the Tizen SDK.

          +
          +// Window
          +ad->win = elm_win_util_standard_add(PACKAGE, PACKAGE);
          +elm_win_autodel_set(ad->win, EINA_TRUE);
          +if (elm_win_wm_rotation_supported_get(ad->win))
          +{
          +   int rots[4] = { 0, 90, 180, 270 };
          +   elm_win_wm_rotation_available_rotations_set(ad->win, (const int *)(&rots), 4);
          +}
          +evas_object_smart_callback_add(ad->win, "delete,request", win_delete_request_cb, NULL);
          +eext_object_event_callback_add(ad->win, EEXT_CALLBACK_BACK, win_back_cb, ad);
          +evas_object_show(ad->win);
          +
          +// Image
          +ad->img = evas_object_image_filled_add(evas_object_evas_get(ad->win));
          +evas_object_show(ad->img);
          +
          + +
        6. +
        + +

        Drawing a Polygon and Rectangle with Cairo

        +

        To create the Cairo drawing, you need the window size to set the Cairo surface. You can get the window size with the evas_object_geometry_get() function after the evas_object_show(ad->win) function is called.

        +

        To draw Cairo with some specific vector positions, you can use the window size as before.

        +
        +evas_object_geometry_get(ad->win, NULL, NULL, &ad->width, &ad->height);
        +ad->surface = cairo_image_surface_create(CAIRO_FORMAT_ARGB32, ad->width, ad->height);
        +ad->cairo = cairo_create(ad->surface);
        +
        +

        In this example, a Cairo image is drawn on a square screen. You can compare the windows width and height and get the smaller length to set the square side.

        +
        +void 
        +cairo_drawing(void *data)
        +{
        +   appdata_s *ad = data;
        +   int d = 0;
        +   if(ad->width < ad->height)
        +      d = ad->width;
        +   else
        +      d = ad->height;
        +
        +

        To set the background as white color, set the color as white and paint the Cairo.

        +
        +   // Clear background as white
        +   cairo_set_source_rgba(ad->cairo, 1, 1, 1, 1);
        +   cairo_paint(ad->cairo);
        +
        + +

        In the following example, you can draw the polygon and rectangle. You must use the cairo_surface_flush() function. This function call implements any pending drawings for the surface.

        +
        +   cairo_translate(ad->cairo, 0.1 * d, 0.1 * d);
        +   cairo_set_line_width(ad->cairo,2);
        +   cairo_set_source_rgba(ad->cairo, 0.0, 0.0, 1.0, 1.0);
        +
        +   cairo_move_to(ad->cairo, 0.2 * d , 0.2 * d);
        +   cairo_line_to(ad->cairo, 0.4 * d, 0.3 * d);
        +   cairo_rel_line_to(ad->cairo, 0.2 * d, -0.1 * d);
        +   cairo_arc(ad->cairo, 0.4 * d, 0.4 * d, 0.2* d * sqrt(2), -0.25 * M_PI, 0.25 * M_PI);
        +   cairo_rel_curve_to(ad->cairo, -0.2* d, -0.1 * d, -0.2* d, 0.1 * d, -0.4 * d, 0);
        +   cairo_close_path(ad->cairo);
        +   cairo_fill(ad->cairo);
        +
        +   cairo_rectangle(ad->cairo, 0, 0, 0.8 * d, 0.8 * d);
        +   cairo_stroke(ad->cairo);
        +   cairo_surface_flush(ad->surface);
        +
        + +

        To update the Evas object image on the screen:

        +
        +   // Display the Cairo drawing on screen
        +   unsigned char * imageData = cairo_image_surface_get_data(cairo_get_target(ad->cairo));
        +   evas_object_image_data_set(ad->img, imageData);
        +   evas_object_image_data_update_add(ad->img, 0, 0, ad->width, ad->height);
        +}
        +
        + +

        Deleting Cairo

        + +

        The delete callback is triggered when the Window is destroyed from the main loop.

        +
        +static void win_delete_request_cb(void *data, Evas_Object *obj, void *event_info)
        +{
        +   appdata_s *ad = data;
        +   cairo_surface_destroy(ad->surface);
        +   cairo_destroy(ad->cairo);
        +   ui_app_exit();
        +}
        +
        + + + + + +
        + +Go to top + + + + + + + \ No newline at end of file diff --git a/org.tizen.sampledescriptions/html/mobile_n/cairo_evasgl_sd_mn.htm b/org.tizen.sampledescriptions/html/mobile_n/cairo_evasgl_sd_mn.htm new file mode 100644 index 0000000..0c140a6 --- /dev/null +++ b/org.tizen.sampledescriptions/html/mobile_n/cairo_evasgl_sd_mn.htm @@ -0,0 +1,282 @@ + + + + + + + + + + + + + + Cairo EvasGL Sample Overview + + + + +
        +
        + +
        +
        +

        Mobile native

        +
        + +

        Cairo EvasGL Sample Overview

        + +

        The Cairo EvasGL sample application demonstrates how to draw vector graphics using the Cairo GL backend with the Evas_GL surface using the Tizen SDK.

        + + + + + + + + + +
        Note
        The application presented in this overview is not a full Tizen application, since it does not use the Application Framework. The application simply starts and runs.
        + +

        The following figure illustrates the main screen of the Cairo EvasGL.

        +

        Figure: Cairo EvasGL screen

        +

        Cairo EvasGL screen

        + +

        Implementation

        + +

        To create a basic application that provides a UI application skeleton which already makes available the window object that can contain a Cairo drawing:

        +
          +
        1. Build the environment. +

          For using the Cairo GL backend on the Evas_GL surface, include the following header files.

          +
          +#include <cairo.h>
          +#include <Evas_GL.h>
          +#include <cairo-evas-gl.h>
          +#include <math.h>
          +
          +

          Define the appdata structure that contains all the pointers to objects to be manipulated:

          +
          +typedef struct appdata 
          +{
          +   Evas_Object *win;	
          +   Evas_Object *img;
          +
          +   cairo_surface_t *surface;
          +   cairo_t *cairo;
          +   cairo_device_t *cairo_device;
          +		
          +   Evas_GL *evas_gl;
          +   Evas_GL_Config *evas_gl_config;
          +   Evas_GL_Surface *evas_gl_surface;
          +   Evas_GL_Context *evas_gl_context;
          +} appdata_s;
          +
          +
        2. +
        3. Create the Elm_window for EvasGL. +

          For using the EvasGL backend, you have to add this before the window creation. This makes it possible for the Cairo drawings on EvasGL to be displayed on the screen.

          +
          +elm_config_accel_preference_set("opengl");
          +ad->win = elm_win_util_standard_add(PACKAGE, PACKAGE);
          +elm_win_autodel_set(ad->win, EINA_TRUE);
          +if (elm_win_wm_rotation_supported_get(ad->win))
          +{
          +   int rots[4] = { 0, 90, 180, 270 };
          +   elm_win_wm_rotation_available_rotations_set(ad->win, (const int *)(&rots), 4);
          +}
          +evas_object_smart_callback_add(ad->win, "delete,request", win_delete_request_cb, NULL);
          +eext_object_event_callback_add(ad->win, EEXT_CALLBACK_BACK, win_back_cb, ad);
          +evas_object_show(ad->win);
          +
          +
        4. +
        5. Create the Evas_object image: +
          +ad->img = evas_object_image_filled_add(evas_object_evas_get(ad->win));
          +evas_object_show(ad->img);
          +
          +
        6. + +
        7. Initialize the variables for EvasGL. +

          Before initializing EvasGL and creating the Evas_GL surface, get the window size.

          +
          +evas_object_geometry_get(ad->win, NULL, NULL, &ad->width, &ad->height);
          +
          +

          Initialize the variables related to the Evas_GL within the appdata structure.

          +

          For creating the EvasGL object, you can use the Evas_object image created before.

          +
          +Evas_Native_Surface ns;
          +ad->evas_gl = evas_gl_new(evas_object_evas_get(ad->img));
          +ad->evas_gl_config = evas_gl_config_new();
          +ad->evas_gl_config->color_format = EVAS_GL_RGBA_8888;
          +ad->evas_gl_surface = evas_gl_surface_create(ad->evas_gl, ad->evas_gl_config, ad->width, ad->height);
          +ad->evas_gl_context = evas_gl_context_create(ad->evas_gl, NULL);
          +evas_gl_native_surface_get(ad->evas_gl, ad->evas_gl_surface, &ns);
          +evas_object_image_native_surface_set(ad->img, &ns);
          +evas_object_image_pixels_get_callback_set(ad->img, cairo_drawing, ad);
          +
          +
        8. +
        9. Link the Evas callback function to draw the Cairo image. +
          +evas_object_image_pixels_get_callback_set(ad->img, cairo_drawing, NULL);
          +
          +
        10. + +
        11. Create Cairo with EvasGL. +

          To create the Cairo surface by using Evas_GL, the Cairo device must be provided. Set the CAIRO_GL_COMPOSITOR as msaa for using full GPU acceleration. In addition, to prevent unnecessary context switches in the Cairo GL backend, use the cairo_gl_device_set_thread_aware() function.

          +
          +setenv("CAIRO_GL_COMPOSITOR", "msaa", 1);
          +ad->cairo_device = (cairo_device_t *)cairo_evas_gl_device_create(ad->evas_gl, ad->evas_gl_context);
          +cairo_gl_device_set_thread_aware(ad->cairo_device, 0);
          +ad->surface = (cairo_surface_t *)cairo_gl_surface_create_for_evas_gl(ad->cairo_device, ad->evas_gl_surface, ad->evas_gl_config, ad->width, ad->height);
          +ad->cairo = cairo_create (ad->surface);
          +
          +
        12. + +
        13. Draw random items (rectangles, circles, and triangles) with the cairo_drawing() function: +
          +void cairo_drawing(void *data)
          +{
          +   appdata_s *ad = data;
          +   int i;
          +   double r, g, b, a;
          +
          +   // Clear background as white
          +   cairo_set_source_rgba(ad->cairo, 1, 1, 1, 1);
          +   cairo_paint(ad->cairo);
          +
          +   cairo_set_operator(ad->cairo, CAIRO_OPERATOR_OVER);
          +   for (i = 0; i < 100; i++)
          +   {
          +      int shape = drand48() *3;
          +      float width = drand48() * 50 + 1;
          +
          +      int line_cap = drand48() * 3;
          +      cairo_line_cap_t line_cap_style = CAIRO_LINE_CAP_BUTT;
          +      if (line_cap == 1)
          +         line_cap_style = CAIRO_LINE_CAP_ROUND;
          +      else if (line_cap == 2)
          +         line_cap_style = CAIRO_LINE_CAP_SQUARE;
          +
          +      int line_join = drand48() * 3;
          +      cairo_line_join_t line_join_style = CAIRO_LINE_JOIN_MITER;
          +      if (line_join == 1)
          +         line_join_style = CAIRO_LINE_JOIN_ROUND;
          +      else if (line_join == 2)
          +         line_join_style = CAIRO_LINE_JOIN_BEVEL;
          +
          +      double dash[] = {0.0, 0.0};
          +      dash[0] = drand48() * 50;
          +      dash[1] = drand48() * 50;
          +
          +      cairo_set_dash(ad->cairo, dash, 2, 0);
          +      cairo_set_line_width(ad->cairo, width);
          +      cairo_set_line_join(ad->cairo, line_join_style);
          +      cairo_set_line_cap(ad->cairo, line_cap_style);
          +
          +      // Random color
          +      r = drand48();
          +      g = drand48();
          +      b = drand48();
          +      a = drand48();
          +      cairo_set_source_rgba(ad->cairo, r, g, b, a);
          +
          +      // Random position
          +      float x = drand48() * ad->width;
          +      float y = drand48() * ad->height;
          +      float side = drand48() * 300;
          +
          +      if (shape == 0)
          +      {
          +         // Draw a square
          +         cairo_rectangle(ad->cairo, x, y, side, side);
          +         cairo_fill(ad->cairo);
          +      }
          +      else if (shape == 1)
          +      {
          +         // Draw a circle
          +         cairo_arc(ad->cairo, x, y, side/2, 0.0, 2.0 * M_PI);
          +         cairo_stroke(ad->cairo);
          +      }
          +      else
          +      {
          +         // Draw a triangle
          +         cairo_move_to(ad->cairo, x, y);
          +         cairo_line_to(ad->cairo, x + side, y);
          +         cairo_line_to(ad->cairo, x, y + side);
          +         cairo_close_path(ad->cairo);
          +         cairo_stroke(ad->cairo);
          +      }
          +   }
          +   cairo_surface_flush(ad->surface);
          +}
          +
          +
        14. +
        15. Add the animator function callback. +

          The following is an example of a default update refresh rate. You can add the animator after creating Cairo and EvasGL.

          +

          Add the animator function callback with the ecore_animator_add() function. The evas_object_image_pixels_dirty_set() function updates the Evas_object image which is connected to EvasGL. After this, the Evas_object image updates with the evas_object_image_pixels_get_callback_set() callback function calls whenever Evas renders.

          +
          +static Eina_Bool _animate_cb(void *data)
          +{
          +   Evas_Object *obj = (Evas_Object *)data;
          +   evas_object_image_pixels_dirty_set(obj, EINA_TRUE);
          +
          +   return EINA_TRUE;
          +}
          +static bool app_create(void *data)
          +{
          +   appdata_s *ad = data;
          +   cairo_evasgl_drawing(ad);
          +
          +   ecore_animator_frametime_set(0.016);
          +   Ecore_Animator *animator = ecore_animator_add(_animate_cb, (void *)ad->img);
          +
          +   return true;
          +}
          +
          + +
        16. + +
        17. Delete Cairo and EvasGL. +

          The delete callback is triggered when the Window is destroyed from the main loop.

          +
          +static void win_delete_request_cb(void *data, Evas_Object *obj, void *event_info)
          +{
          +   appdata_s *ad = data;
          +   cairo_surface_destroy(ad->surface);
          +   cairo_destroy(ad->cairo);
          +   cairo_device_destroy(ad->cairo_device);
          +   evas_gl_surface_destroy(ad->evas_gl, ad->evas_gl_surface);
          +   evas_gl_context_destroy(ad->evas_gl, ad->evas_gl_context);
          +   evas_gl_config_free(ad->evas_gl_config);
          +   evas_gl_free(ad->evas_gl);
          +   ui_app_exit();
          +}
          +
          +
        18. +
        + + + + + + +
        + +Go to top + + + + + + + \ No newline at end of file diff --git a/org.tizen.sampledescriptions/html/mobile_n/glview11_cube_sd_mn.htm b/org.tizen.sampledescriptions/html/mobile_n/glview11_cube_sd_mn.htm index 57df1dd..c469378 100644 --- a/org.tizen.sampledescriptions/html/mobile_n/glview11_cube_sd_mn.htm +++ b/org.tizen.sampledescriptions/html/mobile_n/glview11_cube_sd_mn.htm @@ -1,329 +1,329 @@ - - - - - - - - - - - - - - GLView11Cube Sample Overview - - - - -
        -
        - -
        -
        -

        Mobile native

        -
        - -

        GLView11Cube Sample Overview

        - -

        The GLView11Cube sample demonstrates how you can use ElmGLView to create a 3D cube using OpenGL® ES 1.1.

        - - - - - - - - - - -
        Note
        The application presented in this overview is not a full Tizen application, since it does not use the Application Framework. The application simply starts and runs.
        - -

        This sample extends the functionality of OpenGL® ES 1.1 on the Tizen platform to create spinning 3D cubes. OpenGL® is a standard specification defining a cross-language, cross-platform API for writing applications that produce 2D and 3D computer graphics. OpenGL® ES 1.1 is light-weight but packed with functionalities for hardware acceleration, improved image quality with multi-texture support, and optimizations to increase performance while reducing memory bandwidth usage to save power. ElmGLView can support the surface for 3D rendering.

        - -

        Figure: GLView11Cube

        -

        GLView11Cube

        - - -

        Initializing the Application

        -

        The easiest way to use OpenGL® within an EFL application is to rely on the Elementary GLView component.

        -

        Current GLView can support both GELS2.0 and 1.1. GLView with the GLES 1.1 basic application has a similar basic format as the other GLView application.

        -

        Create a basic application:

        -
        -#include <Evas_GL.h>
        -#include <Elementary.h>
        -#include <efl_extension.h>
        -#include <dlog.h>
        -
        - -

        The GLView application should include the header files as the <Evas_GL.h> and <Elementary.h>. The <efl_extension.h> header file is related to key events and the <dlog.h> header file is for seeing logs.

        -
        -#define S(a) evas_object_show(a)
        -
        -#define SX(a) do 
        -{
        -   evas_object_size_hint_align_set(a, EVAS_HINT_FILL, EVAS_HINT_FILL);
        -   evas_object_size_hint_weight_set(a, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
        -   evas_object_show(a);
        -} while (0)
        -
        -#define SF(a) do 
        -{
        -   evas_object_size_hint_align_set(a, EVAS_HINT_FILL, EVAS_HINT_FILL);
        -   evas_object_size_hint_weight_set(a, 0.00001, 0.00001);
        -   evas_object_show(a);
        -} while (0)
        -
        -static bool
        -app_create(void *data)
        -{
        -   Evas_Object *o, *t;
        -   appdata_s *ad = (appdata_s*)data;
        -
        -   // Force OpenGL engine
        -   elm_config_accel_preference_set("opengl");
        -
        -   // Add a window
        -   ad->win = o = elm_win_add(NULL,"glview", ELM_WIN_BASIC);
        -   evas_object_smart_callback_add(o, "delete,request", _close_cb, ad);
        -   evas_object_event_callback_add(o, EVAS_CALLBACK_RESIZE, _win_resize_cb, ad);
        -   eext_object_event_callback_add(o, EEXT_CALLBACK_BACK, _close_cb, ad);
        -   S(o);
        -
        -   // Add a background
        -   ad->bg = o = elm_bg_add(ad->win);
        -   elm_win_resize_object_add(ad->win, ad->bg);
        -   elm_bg_color_set(o, 68, 68, 68);
        -   S(o);
        -
        -   // Add a resize conformant
        -   ad->conform = o = elm_conformant_add(ad->win);
        -   elm_win_resize_object_add(ad->win, ad->conform);
        -   SX(o);
        -
        -   ad->table = t = elm_table_add(ad->win);
        -   S(t);
        -
        -   o = elm_label_add(ad->win);
        -   elm_object_text_set(o, "Gles 1.1 Cube");
        -   elm_table_pack(t, o, 1, 0, 3, 1);
        -   SF(o);
        -
        -   o = elm_button_add(ad->win);
        -   elm_object_text_set(o, "Quit");
        -   evas_object_smart_callback_add(o, "clicked", _close_cb, ad);
        -   elm_table_pack(t, o, 1, 9, 3, 1);
        -   SF(o);
        -
        -   ad->glview = o = _glview_create(ad);
        -   SX(o);
        -
        -   // Add an animator to call _anim_cb_() every (1/60) seconds
        -   // _anim_cb() indicates that glview has changed, which eventually triggers
        -   // function (draw_gl() here) to redraw glview surface
        -   
        -   ecore_animator_frametime_set(1.0 / 60.0);
        -   ad->anim = ecore_animator_add(_anim_cb, ad);
        -   evas_object_event_callback_add(ad->glview, EVAS_CALLBACK_DEL, _destroy_anim, ad->anim);
        -
        -   return true;
        -}
        -
        - -

        To set the GL rendering engine, the application calls the elm_config_accel_preference_set("opengl") function with the special string:

        -
        -static Evas_Object*
        -_glview_create(appdata_s *ad)
        -{
        -   Evas_Object *obj;
        -
        -   // Create a GLView with an OpenGL®-ES 1.1 context
        -   obj = elm_glview_version_add(ad->win, EVAS_GL_GLES_1_X);
        -   elm_table_pack(ad->table, obj, 1, 1, 3, 1);
        -   evas_object_data_set(obj, APPDATA_KEY, ad);
        -
        -   elm_glview_mode_set(obj,
        -                       ELM_GLVIEW_ALPHA |
        -                       ELM_GLVIEW_DEPTH
        -                       );
        -   elm_glview_resize_policy_set(obj, ELM_GLVIEW_RESIZE_POLICY_RECREATE);
        -   elm_glview_render_policy_set(obj, ELM_GLVIEW_RENDER_POLICY_ON_DEMAND);
        -
        -   elm_glview_init_func_set(obj, init_gles);
        -   elm_glview_del_func_set(obj, destroy_gles);
        -   elm_glview_resize_func_set(obj, resize_gl);
        -   elm_glview_render_func_set(obj, draw_gl);
        -
        -   return obj;
        -}
        -
        - -

        To create ElmGLView with GLES 1.1, use the elm_glview_version_add() function with the specific version (EVAS_GL_GLES_1_X). The current ElmGLView can support both GLES 2.0 and 1.1.

        - -

        Setting up Callbacks

        -

        To set up callbacks:

        -
          -
        1. Set the initialization callback. -

          The initialization callback is called when the GLView is first created, after a valid OpenGL® context and surface have been created. This is called from the main loop, as are the 3 other callbacks.

          -
          -#include <Elementary_GL_Helpers.h>
          - -

          The <Elementary_GL_Helpers.h> header file provides a set of convenience functions and macros. To use these functions and macros, include the header file in the application.

          -
          -void
          -init_gles(Evas_Object *obj)
          -{
          -   int w, h;
          -   appdata_s *ad;
          -
          -   ELEMENTARY_GLVIEW_USE(obj);
          -   ad = evas_object_data_get(obj, APPDATA_KEY);
          -
          -   glGenTextures(2, ad->tex_ids);
          -
          -   // Create and map texture 1
          -   glBindTexture(GL_TEXTURE_2D, ad->tex_ids[0]);
          -   glTexImage2D(GL_TEXTURE_2D, 0, GL_RGBA, 128, 128, 0, GL_RGBA, GL_UNSIGNED_SHORT_4_4_4_4, IMAGE_4444_128_128_1);
          -   glTexParameterx(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_LINEAR);
          -   glTexParameterx(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_LINEAR);
          -   glTexParameterx(GL_TEXTURE_2D, GL_TEXTURE_WRAP_S, GL_CLAMP_TO_EDGE);
          -   glTexParameterx(GL_TEXTURE_2D, GL_TEXTURE_WRAP_T, GL_CLAMP_TO_EDGE);
          -
          -   // Create and map texture 2
          -   glBindTexture(GL_TEXTURE_2D, ad->tex_ids[1]);
          -   glTexImage2D(GL_TEXTURE_2D, 0, GL_RGB, 128, 128, 0, GL_RGB, GL_UNSIGNED_SHORT_5_6_5, IMAGE_565_128_128_1);
          -   glTexParameterx(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_LINEAR);
          -   glTexParameterx(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_LINEAR);
          -   glTexParameterx(GL_TEXTURE_2D, GL_TEXTURE_WRAP_S, GL_CLAMP_TO_EDGE);
          -   glTexParameterx(GL_TEXTURE_2D, GL_TEXTURE_WRAP_T, GL_CLAMP_TO_EDGE);
          -
          -   ad->current_tex_index = 0;
          -
          -   glShadeModel(GL_SMOOTH);
          -
          -   glEnable(GL_CULL_FACE);
          -   glCullFace(GL_BACK);
          -
          -   glEnable(GL_DEPTH_TEST);
          -   glDepthFunc(GL_LESS);
          -
          -   elm_glview_size_get(obj, &w, &h);
          -   set_perspective(obj, 60.0f, w, h, 1.0f, 400.0f);
          -}
          -
          - -

          In the GLES 1.1 sample, 2 textures are created and mapped in this function.

          -
        2. - -
        3. Set the resize callback. -

          The resize callback is called whenever the GLView component is resized. A common action to take here is to reset the viewport and matrix mode.

          -
          -void resize_gl(Evas_Object *obj)
          -{
          -   int w, h;
          -
          -   elm_glview_size_get(obj, &w, &h);
          -   set_perspective(obj, 60.0f, w, h, 1.0f, 400.0f);
          -}
          -
          -
        4. - -
        5. Set the draw callback. -

          The draw callback is called whenever a new frame has to be drawn. The exact moment when this function is called depends on the policy set when calling.

          -
          -   elm_glview_render_policy_set(glview, ELM_GLVIEW_RENDER_POLICY_ON_DEMAND);
          - -

          Another policy is ELM_GLVIEW_POLICY_ALWAYS.

          -

          The application can now draw anything using GL primitives when this callback is triggered. All draw operations are restricted to the surface of the GLView object previously created. The following example covers the whole window:

          -
          -void draw_gl(Evas_Object *obj)
          -{
          -ELEMENTARY_GLVIEW_USE(obj);
          -
          -   glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);
          -   glClearColor(0.0f, 0.0f, 0.0f, 0.0f);
          -
          -   draw_cube1(obj);
          -   draw_cube2(obj);
          -}
          -
          -
        6. - -
        7. Set the delete callback. -

          The delete callback is triggered when the GLView is destroyed from the main loop, and no other callback can be called on the same object afterwards. In GELS 1.1, 2 textures are deleted.

          -
          -void
          -destroy_gles(Evas_Object *obj)
          -{
          -   appdata_s *ad;
          -
          -   ELEMENTARY_GLVIEW_USE(obj);
          -   ad = evas_object_data_get(obj, APPDATA_KEY);
          -
          -   if (ad->tex_ids[0])
          -   {
          -      glDeleteTextures(1, &(ad->tex_ids[0]));
          -      ad->tex_ids[0] = 0;
          -   }
          -
          -   if (ad->tex_ids[1])
          -   {
          -      glDeleteTextures(1, &(ad->tex_ids[1]));
          -      ad->tex_ids[1] = 0;
          -   }
          -}
          -
          -
        8. - -
        9. Add an animator. -

          The application above is technically working but the scene does not get updated unless the object is marked as such. Games usually use an animator to update the scene regularly. The following example shows a default update refresh rate:

          -
          -static Eina_Bool
          -_anim_cb(void *data)
          -{
          -   appdata_s *ad = data;
          -
          -   elm_glview_changed_set(ad->glview);
          -   return ECORE_CALLBACK_RENEW;
          -}
          -
          - -

          Any other event can be used to refresh the view, for example, the user input if the view does not need to be updated.

          -
        10. -
        - - - - - - - - - - -
        Note
        OpenGL® ES 1.1 application can be implemented in Tizen. However, if OpenGL® ES 1.1 and OpenGL® ES 2.0 are used together, they cannot be used in the same file.
        - - - -
        - -Go to top - - - - - - - - + + + + + + + + + + + + + + GLView11Cube Sample Overview + + + + +
        +
        + +
        +
        +

        Mobile native

        +
        + +

        GLView11Cube Sample Overview

        + +

        The GLView11Cube sample demonstrates how you can use ElmGLView to create a 3D cube using OpenGL® ES 1.1.

        + + + + + + + + + + +
        Note
        The application presented in this overview is not a full Tizen application, since it does not use the Application Framework. The application simply starts and runs.
        + +

        This sample extends the functionality of OpenGL® ES 1.1 on the Tizen platform to create spinning 3D cubes. OpenGL® is a standard specification defining a cross-language, cross-platform API for writing applications that produce 2D and 3D computer graphics. OpenGL® ES 1.1 is light-weight but packed with functionalities for hardware acceleration, improved image quality with multi-texture support, and optimizations to increase performance while reducing memory bandwidth usage to save power. ElmGLView can support the surface for 3D rendering.

        + +

        Figure: GLView11Cube

        +

        GLView11Cube

        + + +

        Initializing the Application

        +

        The easiest way to use OpenGL® within an EFL application is to rely on the Elementary GLView component.

        +

        Current GLView can support both GELS2.0 and 1.1. GLView with the GLES 1.1 basic application has a similar basic format as the other GLView application.

        +

        Create a basic application:

        +
        +#include <Evas_GL.h>
        +#include <Elementary.h>
        +#include <efl_extension.h>
        +#include <dlog.h>
        +
        + +

        The GLView application should include the header files as the <Evas_GL.h> and <Elementary.h>. The <efl_extension.h> header file is related to key events and the <dlog.h> header file is for seeing logs.

        +
        +#define S(a) evas_object_show(a)
        +
        +#define SX(a) do 
        +{
        +   evas_object_size_hint_align_set(a, EVAS_HINT_FILL, EVAS_HINT_FILL);
        +   evas_object_size_hint_weight_set(a, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
        +   evas_object_show(a);
        +} while (0)
        +
        +#define SF(a) do 
        +{
        +   evas_object_size_hint_align_set(a, EVAS_HINT_FILL, EVAS_HINT_FILL);
        +   evas_object_size_hint_weight_set(a, 0.00001, 0.00001);
        +   evas_object_show(a);
        +} while (0)
        +
        +static bool
        +app_create(void *data)
        +{
        +   Evas_Object *o, *t;
        +   appdata_s *ad = (appdata_s*)data;
        +
        +   // Force OpenGL engine
        +   elm_config_accel_preference_set("opengl");
        +
        +   // Add a window
        +   ad->win = o = elm_win_add(NULL,"glview", ELM_WIN_BASIC);
        +   evas_object_smart_callback_add(o, "delete,request", _close_cb, ad);
        +   evas_object_event_callback_add(o, EVAS_CALLBACK_RESIZE, _win_resize_cb, ad);
        +   eext_object_event_callback_add(o, EEXT_CALLBACK_BACK, _close_cb, ad);
        +   S(o);
        +
        +   // Add a background
        +   ad->bg = o = elm_bg_add(ad->win);
        +   elm_win_resize_object_add(ad->win, ad->bg);
        +   elm_bg_color_set(o, 68, 68, 68);
        +   S(o);
        +
        +   // Add a resize conformant
        +   ad->conform = o = elm_conformant_add(ad->win);
        +   elm_win_resize_object_add(ad->win, ad->conform);
        +   SX(o);
        +
        +   ad->table = t = elm_table_add(ad->win);
        +   S(t);
        +
        +   o = elm_label_add(ad->win);
        +   elm_object_text_set(o, "Gles 1.1 Cube");
        +   elm_table_pack(t, o, 1, 0, 3, 1);
        +   SF(o);
        +
        +   o = elm_button_add(ad->win);
        +   elm_object_text_set(o, "Quit");
        +   evas_object_smart_callback_add(o, "clicked", _close_cb, ad);
        +   elm_table_pack(t, o, 1, 9, 3, 1);
        +   SF(o);
        +
        +   ad->glview = o = _glview_create(ad);
        +   SX(o);
        +
        +   // Add an animator to call _anim_cb_() every (1/60) seconds
        +   // _anim_cb() indicates that glview has changed, which eventually triggers
        +   // function (draw_gl() here) to redraw glview surface
        +   
        +   ecore_animator_frametime_set(1.0 / 60.0);
        +   ad->anim = ecore_animator_add(_anim_cb, ad);
        +   evas_object_event_callback_add(ad->glview, EVAS_CALLBACK_DEL, _destroy_anim, ad->anim);
        +
        +   return true;
        +}
        +
        + +

        To set the GL rendering engine, the application calls the elm_config_accel_preference_set("opengl") function with the special string:

        +
        +static Evas_Object*
        +_glview_create(appdata_s *ad)
        +{
        +   Evas_Object *obj;
        +
        +   // Create a GLView with an OpenGL®-ES 1.1 context
        +   obj = elm_glview_version_add(ad->win, EVAS_GL_GLES_1_X);
        +   elm_table_pack(ad->table, obj, 1, 1, 3, 1);
        +   evas_object_data_set(obj, APPDATA_KEY, ad);
        +
        +   elm_glview_mode_set(obj,
        +                       ELM_GLVIEW_ALPHA |
        +                       ELM_GLVIEW_DEPTH
        +                       );
        +   elm_glview_resize_policy_set(obj, ELM_GLVIEW_RESIZE_POLICY_RECREATE);
        +   elm_glview_render_policy_set(obj, ELM_GLVIEW_RENDER_POLICY_ON_DEMAND);
        +
        +   elm_glview_init_func_set(obj, init_gles);
        +   elm_glview_del_func_set(obj, destroy_gles);
        +   elm_glview_resize_func_set(obj, resize_gl);
        +   elm_glview_render_func_set(obj, draw_gl);
        +
        +   return obj;
        +}
        +
        + +

        To create ElmGLView with GLES 1.1, use the elm_glview_version_add() function with the specific version (EVAS_GL_GLES_1_X). The current ElmGLView can support both GLES 2.0 and 1.1.

        + +

        Setting up Callbacks

        +

        To set up callbacks:

        +
          +
        1. Set the initialization callback. +

          The initialization callback is called when the GLView is first created, after a valid OpenGL® context and surface have been created. This is called from the main loop, as are the 3 other callbacks.

          +
          +#include <Elementary_GL_Helpers.h>
          + +

          The <Elementary_GL_Helpers.h> header file provides a set of convenience functions and macros. To use these functions and macros, include the header file in the application.

          +
          +void
          +init_gles(Evas_Object *obj)
          +{
          +   int w, h;
          +   appdata_s *ad;
          +
          +   ELEMENTARY_GLVIEW_USE(obj);
          +   ad = evas_object_data_get(obj, APPDATA_KEY);
          +
          +   glGenTextures(2, ad->tex_ids);
          +
          +   // Create and map texture 1
          +   glBindTexture(GL_TEXTURE_2D, ad->tex_ids[0]);
          +   glTexImage2D(GL_TEXTURE_2D, 0, GL_RGBA, 128, 128, 0, GL_RGBA, GL_UNSIGNED_SHORT_4_4_4_4, IMAGE_4444_128_128_1);
          +   glTexParameterx(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_LINEAR);
          +   glTexParameterx(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_LINEAR);
          +   glTexParameterx(GL_TEXTURE_2D, GL_TEXTURE_WRAP_S, GL_CLAMP_TO_EDGE);
          +   glTexParameterx(GL_TEXTURE_2D, GL_TEXTURE_WRAP_T, GL_CLAMP_TO_EDGE);
          +
          +   // Create and map texture 2
          +   glBindTexture(GL_TEXTURE_2D, ad->tex_ids[1]);
          +   glTexImage2D(GL_TEXTURE_2D, 0, GL_RGB, 128, 128, 0, GL_RGB, GL_UNSIGNED_SHORT_5_6_5, IMAGE_565_128_128_1);
          +   glTexParameterx(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_LINEAR);
          +   glTexParameterx(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_LINEAR);
          +   glTexParameterx(GL_TEXTURE_2D, GL_TEXTURE_WRAP_S, GL_CLAMP_TO_EDGE);
          +   glTexParameterx(GL_TEXTURE_2D, GL_TEXTURE_WRAP_T, GL_CLAMP_TO_EDGE);
          +
          +   ad->current_tex_index = 0;
          +
          +   glShadeModel(GL_SMOOTH);
          +
          +   glEnable(GL_CULL_FACE);
          +   glCullFace(GL_BACK);
          +
          +   glEnable(GL_DEPTH_TEST);
          +   glDepthFunc(GL_LESS);
          +
          +   elm_glview_size_get(obj, &w, &h);
          +   set_perspective(obj, 60.0f, w, h, 1.0f, 400.0f);
          +}
          +
          + +

          In the GLES 1.1 sample, 2 textures are created and mapped in this function.

          +
        2. + +
        3. Set the resize callback. +

          The resize callback is called whenever the GLView component is resized. A common action to take here is to reset the viewport and matrix mode.

          +
          +void resize_gl(Evas_Object *obj)
          +{
          +   int w, h;
          +
          +   elm_glview_size_get(obj, &w, &h);
          +   set_perspective(obj, 60.0f, w, h, 1.0f, 400.0f);
          +}
          +
          +
        4. + +
        5. Set the draw callback. +

          The draw callback is called whenever a new frame has to be drawn. The exact moment when this function is called depends on the policy set when calling.

          +
          +   elm_glview_render_policy_set(glview, ELM_GLVIEW_RENDER_POLICY_ON_DEMAND);
          + +

          Another policy is ELM_GLVIEW_POLICY_ALWAYS.

          +

          The application can now draw anything using GL primitives when this callback is triggered. All draw operations are restricted to the surface of the GLView object previously created. The following example covers the whole window:

          +
          +void draw_gl(Evas_Object *obj)
          +{
          +ELEMENTARY_GLVIEW_USE(obj);
          +
          +   glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);
          +   glClearColor(0.0f, 0.0f, 0.0f, 0.0f);
          +
          +   draw_cube1(obj);
          +   draw_cube2(obj);
          +}
          +
          +
        6. + +
        7. Set the delete callback. +

          The delete callback is triggered when the GLView is destroyed from the main loop, and no other callback can be called on the same object afterwards. In GELS 1.1, 2 textures are deleted.

          +
          +void
          +destroy_gles(Evas_Object *obj)
          +{
          +   appdata_s *ad;
          +
          +   ELEMENTARY_GLVIEW_USE(obj);
          +   ad = evas_object_data_get(obj, APPDATA_KEY);
          +
          +   if (ad->tex_ids[0])
          +   {
          +      glDeleteTextures(1, &(ad->tex_ids[0]));
          +      ad->tex_ids[0] = 0;
          +   }
          +
          +   if (ad->tex_ids[1])
          +   {
          +      glDeleteTextures(1, &(ad->tex_ids[1]));
          +      ad->tex_ids[1] = 0;
          +   }
          +}
          +
          +
        8. + +
        9. Add an animator. +

          The application above is technically working but the scene does not get updated unless the object is marked as such. Games usually use an animator to update the scene regularly. The following example shows a default update refresh rate:

          +
          +static Eina_Bool
          +_anim_cb(void *data)
          +{
          +   appdata_s *ad = data;
          +
          +   elm_glview_changed_set(ad->glview);
          +   return ECORE_CALLBACK_RENEW;
          +}
          +
          + +

          Any other event can be used to refresh the view, for example, the user input if the view does not need to be updated.

          +
        10. +
        + + + + + + + + + + +
        Note
        OpenGL® ES 1.1 application can be implemented in Tizen. However, if OpenGL® ES 1.1 and OpenGL® ES 2.0 are used together, they cannot be used in the same file.
        + + + +
        + +Go to top + + + + + + + + diff --git a/org.tizen.sampledescriptions/html/mobile_n/glview_cube_sd_mn.htm b/org.tizen.sampledescriptions/html/mobile_n/glview_cube_sd_mn.htm index 9d0de04..1df061c 100644 --- a/org.tizen.sampledescriptions/html/mobile_n/glview_cube_sd_mn.htm +++ b/org.tizen.sampledescriptions/html/mobile_n/glview_cube_sd_mn.htm @@ -1,284 +1,284 @@ - - - - - - - - - - - - - - GLViewCube Sample Overview - - - - -
        -
        - -
        -
        -

        Mobile native

        -
        - -

        GLViewCube Sample Overview

        - -

        This sample demonstrates how to render with OpenGL® ES 2.0 using an Elementary GLView component. It goes through the creation of a simple UI and how to draw a rotating cube using simple vertex and fragment shaders.

        - - - - - - - - - - -
        Note
        The application presented in this overview is not a full Tizen application, since it does not use the Application Framework. The application simply starts and runs.
        - - -

        Figure: GLViewCube

        -

        GLViewCube

        - -

        Elementary_GL_Helpers

        -

        The <Elementary_GL_Helpers.h> header file provides a set of convenience functions and macros. To use these functions and macros, include this header file in the application.

        -
        -#include <app.h>
        -#include <Elementary.h>
        -#include <Elementary_GL_Helpers.h>
        -#include <efl_extension.h>
        -
        -#include "glviewcube_utils.h"
        -
        -ELEMENTARY_GLVIEW_GLOBAL_DEFINE();
        -...
        -static bool app_create(void *data) 
        -{
        -...
        -   // Create and initialize GLView
        -   gl = elm_glview_add(win);
        -   ELEMENTARY_GLVIEW_GLOBAL_USE(gl);
        -...
        -}
        -
        - -

        Setting up Callbacks

        -
          -
        1. Set the initialization callback. -

          The initialization callback is called when the GLView is first created, after a valid OpenGL® context and surface have been created.

          -

          This callback function initializes shaders using the init_shaders(obj) function.

          - -
          -static void init_gl(Evas_Object *obj) 
          -{
          -   appdata_s *ad = evas_object_data_get(obj, "ad");
          -
          -   if (!ad->initialized) 
          -   {
          -      init_shaders(obj);
          -      glEnable(GL_DEPTH_TEST);
          -      ad->initialized = EINA_TRUE;
          -   }
          -      ...
          -}
          -
          -
        2. - -
        3. Initialize the shaders. -
            -
          1. The shader instances for the fragment and vertex shader are compiled and created by passing the shader type as a parameter to the glCreateShader() function. -

            Load the shader objects, use the GLES2 Shader compiler to read and compile the shader source code for both the fragment and the vertex shader.

            -
            -static void init_shaders(Evas_Object *obj) 
            -{
            -   appdata_s *ad = evas_object_data_get(obj, "ad");
            -   const char *p;
            -   p = vertex_shader;
            -   ad->vtx_shader = glCreateShader(GL_VERTEX_SHADER);
            -   glShaderSource(ad->vtx_shader, 1, &p, NULL);
            -   glCompileShader(ad->vtx_shader);
            -
            -   p = fragment_shader;
            -   ad->fgmt_shader = glCreateShader(GL_FRAGMENT_SHADER);
            -   glShaderSource(ad->fgmt_shader, 1, &p, NULL);
            -   glCompileShader(ad->fgmt_shader);
            -
          2. -
          3. Once the shader objects have been loaded, a shader program is created. The program attaches and links the shader objects to the shader program. -
            -   ad->program = glCreateProgram();
            -   glAttachShader(ad->program, ad->vtx_shader);
            -   glAttachShader(ad->program, ad->fgmt_shader);
            -   glLinkProgram(ad->program);
            -
            -
          4. - -
          5. Get the location for each vertex or pixel attribute in the shader program using the glGetAttribLocation() and glGetUniformLocation() functions. If the shader program attributes a_position, a_color, and u_mvpMatrix are valid, these functions return an integer value that represents the index location of the attributes. For invalid attributes, the return value is -1. -

            The glGetAttribLocation() function retrieves the location of the attributes that have an effect on a vertex or pixel, such as position vector, normal vector, or vertex color. The glGetUniformLocation() retrieves the location of the attributes that have an effect on groups of vertices or pixels, such as model view matrix, projection matrix, or light position.

            -
            -   ad->idx_position = glGetAttribLocation(ad->program, "a_position");
            -   ad->idx_color = glGetAttribLocation(ad->program, "a_color");
            -   ad->idx_mvp = glGetUniformLocation(ad->program, "u_mvpMatrix");
            -	
            -
          6. - -
          7. Install the shader program and enable the GPU to execute the shader operations in the frame buffer. -
            -   glUseProgram(ad->program);
            -}
            -
            -
          8. -
          -
        4. - -
        5. Set the resize callback. -

          The resize callback is called whenever the GLView component is resized. It resets the viewport.

          -
          -static void resize_gl(Evas_Object *obj) 
          -{
          -   int w, h;
          -   elm_glview_size_get(obj, &w, &h);
          -   glViewport(0, 0, w, h);
          -}
          -
          -
        6. - - -
        7. Set the draw callback. -

          The draw callback is called whenever a new frame has to be drawn.

          -

          The application can now draw anything using GL primitives when this callback is triggered.

          -
            -
          1. The glViewport() function specifies the affine transformation of the x and y values from normalized device coordinates to window coordinates as specified by the elm_glview_size_get() function. -
            -static void draw_gl(Evas_Object *obj) 
            -{
            -   ...
            -   elm_glview_size_get(obj, &w, &h);
            -   ...
            -   glViewport(0, 0, w, h);
            -
            -
          2. -
          3. The glVertexAttribPointer() function is used to define an array of generic vertex attribute data. These attributes are parameters associated with each vertex of the cube. In this case, the parameters are position and color. In both instances, the final parameter (vertices and colors) represent the previously defined arrays - vertices and colors. -

            The glEnableVertexAttribArray() function enables the generic vertex attribute data arrays. The enabled attributes can be accessed and used to render the scene.

            -
            -   glVertexAttribPointer(ad->idx_position, 3, GL_FLOAT, GL_FALSE,
            -         3 * sizeof(float), cube_vertices);
            -   glVertexAttribPointer(ad->idx_color, 4, GL_FLOAT, GL_FALSE,
            -         4 * sizeof(float), cube_colors);
            -
            -   glEnableVertexAttribArray(ad->idx_position);
            -   glEnableVertexAttribArray(ad->idx_color);
            -	
            -
          4. - -
          5. The glUniformMatrix4fv() function modifies the values of the 4x4 MVP (Model View/Projection) uniform matrix according to the vertices information of the cube. An MVP matrix is created with data after each vertex of the cube has passed through 2 transformation stages: The first transformation state is the model view transformation, which includes translation, rotation, and scaling of objects. The second state is projection, which includes changes in the perspective or orthography. -
            -   glUniformMatrix4fv(ad->idx_mvp, 1, GL_FALSE, ad->mvp);
            -
          6. - -
          7. Once the vertex arrays have been enabled, the actual process of rendering graphics primitives from the array data occurs using the glDrawElements() function. The final parameter in this function is the indices array. -
            -   glDrawElements(GL_TRIANGLES, cube_indices_count, 				
            -                  GL_UNSIGNED_SHORT, cube_indices);
            -	
            -
          8. -
          -
        8. - -
        9. Add an animator. -

          The application regularly triggers updates of the GLView using the elm_glview_changed_set() function.

          -
          -static Eina_Bool anim(void *data) 
          -{
          -elm_glview_changed_set(data);
          -return EINA_TRUE;
          -}
          -
          -static bool app_create(void *data) 
          -{
          -      ...
          -   ani = ecore_animator_add(anim, gl);
          -      ...
          -}
          -
          -
        10. - -
        11. Set event callbacks. -

          The event callbacks receive touch events and allow you to rotate the cube in a vertical or horizontal direction.

          - -
          -static void mouse_down_cb(void *data, Evas *e , Evas_Object *obj , void *event_info)
          -{
          -   appdata_s *ad = data;
          -   ad->mouse_down = EINA_TRUE;
          -}
          -
          -static void mouse_move_cb(void *data, Evas *e , Evas_Object *obj , void *event_info)
          -{
          -   Evas_Event_Mouse_Move *ev;
          -   ev = (Evas_Event_Mouse_Move *)event_info;
          -   appdata_s *ad = data;
          -   float dx = 0, dy = 0;
          -
          -   if (ad->mouse_down) 
          -   {
          -      dx = ev->cur.canvas.x - ev->prev.canvas.x;
          -      dy = ev->cur.canvas.y - ev->prev.canvas.y;
          -      ad->xangle += dy;
          -      ad->yangle += dx;
          -   }
          -}
          -
          -static void mouse_up_cb(void *data, Evas *e , Evas_Object *obj , void *event_info)
          -{
          -   appdata_s *ad = data;
          -   ad->mouse_down = EINA_FALSE;
          -}
          -
          -
        12. - - -
        13. Set the delete callback. -

          The delete callback is triggered when the GLView is destroyed from the main loop.

          -

          The glDeleteShader() and glDeleteProgram() functions are used to free memory.

          -
          -static void del_gl(Evas_Object *obj) 
          -{
          -   appdata_s *ad = evas_object_data_get(obj, "ad");
          -
          -   glDeleteShader(ad->vtx_shader);
          -   glDeleteShader(ad->fgmt_shader);
          -   glDeleteProgram(ad->program);
          -
          -   evas_object_data_del((Evas_Object*) obj, "ad");
          -}
          -
          -
        14. -
        - - - -
        - -Go to top - - - - - - - - + + + + + + + + + + + + + + GLViewCube Sample Overview + + + + +
        +
        + +
        +
        +

        Mobile native

        +
        + +

        GLViewCube Sample Overview

        + +

        This sample demonstrates how to render with OpenGL® ES 2.0 using an Elementary GLView component. It goes through the creation of a simple UI and how to draw a rotating cube using simple vertex and fragment shaders.

        + + + + + + + + + + +
        Note
        The application presented in this overview is not a full Tizen application, since it does not use the Application Framework. The application simply starts and runs.
        + + +

        Figure: GLViewCube

        +

        GLViewCube

        + +

        Elementary_GL_Helpers

        +

        The <Elementary_GL_Helpers.h> header file provides a set of convenience functions and macros. To use these functions and macros, include this header file in the application.

        +
        +#include <app.h>
        +#include <Elementary.h>
        +#include <Elementary_GL_Helpers.h>
        +#include <efl_extension.h>
        +
        +#include "glviewcube_utils.h"
        +
        +ELEMENTARY_GLVIEW_GLOBAL_DEFINE();
        +...
        +static bool app_create(void *data) 
        +{
        +...
        +   // Create and initialize GLView
        +   gl = elm_glview_add(win);
        +   ELEMENTARY_GLVIEW_GLOBAL_USE(gl);
        +...
        +}
        +
        + +

        Setting up Callbacks

        +
          +
        1. Set the initialization callback. +

          The initialization callback is called when the GLView is first created, after a valid OpenGL® context and surface have been created.

          +

          This callback function initializes shaders using the init_shaders(obj) function.

          + +
          +static void init_gl(Evas_Object *obj) 
          +{
          +   appdata_s *ad = evas_object_data_get(obj, "ad");
          +
          +   if (!ad->initialized) 
          +   {
          +      init_shaders(obj);
          +      glEnable(GL_DEPTH_TEST);
          +      ad->initialized = EINA_TRUE;
          +   }
          +      ...
          +}
          +
          +
        2. + +
        3. Initialize the shaders. +
            +
          1. The shader instances for the fragment and vertex shader are compiled and created by passing the shader type as a parameter to the glCreateShader() function. +

            Load the shader objects, use the GLES2 Shader compiler to read and compile the shader source code for both the fragment and the vertex shader.

            +
            +static void init_shaders(Evas_Object *obj) 
            +{
            +   appdata_s *ad = evas_object_data_get(obj, "ad");
            +   const char *p;
            +   p = vertex_shader;
            +   ad->vtx_shader = glCreateShader(GL_VERTEX_SHADER);
            +   glShaderSource(ad->vtx_shader, 1, &p, NULL);
            +   glCompileShader(ad->vtx_shader);
            +
            +   p = fragment_shader;
            +   ad->fgmt_shader = glCreateShader(GL_FRAGMENT_SHADER);
            +   glShaderSource(ad->fgmt_shader, 1, &p, NULL);
            +   glCompileShader(ad->fgmt_shader);
            +
          2. +
          3. Once the shader objects have been loaded, a shader program is created. The program attaches and links the shader objects to the shader program. +
            +   ad->program = glCreateProgram();
            +   glAttachShader(ad->program, ad->vtx_shader);
            +   glAttachShader(ad->program, ad->fgmt_shader);
            +   glLinkProgram(ad->program);
            +
            +
          4. + +
          5. Get the location for each vertex or pixel attribute in the shader program using the glGetAttribLocation() and glGetUniformLocation() functions. If the shader program attributes a_position, a_color, and u_mvpMatrix are valid, these functions return an integer value that represents the index location of the attributes. For invalid attributes, the return value is -1. +

            The glGetAttribLocation() function retrieves the location of the attributes that have an effect on a vertex or pixel, such as position vector, normal vector, or vertex color. The glGetUniformLocation() retrieves the location of the attributes that have an effect on groups of vertices or pixels, such as model view matrix, projection matrix, or light position.

            +
            +   ad->idx_position = glGetAttribLocation(ad->program, "a_position");
            +   ad->idx_color = glGetAttribLocation(ad->program, "a_color");
            +   ad->idx_mvp = glGetUniformLocation(ad->program, "u_mvpMatrix");
            +	
            +
          6. + +
          7. Install the shader program and enable the GPU to execute the shader operations in the frame buffer. +
            +   glUseProgram(ad->program);
            +}
            +
            +
          8. +
          +
        4. + +
        5. Set the resize callback. +

          The resize callback is called whenever the GLView component is resized. It resets the viewport.

          +
          +static void resize_gl(Evas_Object *obj) 
          +{
          +   int w, h;
          +   elm_glview_size_get(obj, &w, &h);
          +   glViewport(0, 0, w, h);
          +}
          +
          +
        6. + + +
        7. Set the draw callback. +

          The draw callback is called whenever a new frame has to be drawn.

          +

          The application can now draw anything using GL primitives when this callback is triggered.

          +
            +
          1. The glViewport() function specifies the affine transformation of the x and y values from normalized device coordinates to window coordinates as specified by the elm_glview_size_get() function. +
            +static void draw_gl(Evas_Object *obj) 
            +{
            +   ...
            +   elm_glview_size_get(obj, &w, &h);
            +   ...
            +   glViewport(0, 0, w, h);
            +
            +
          2. +
          3. The glVertexAttribPointer() function is used to define an array of generic vertex attribute data. These attributes are parameters associated with each vertex of the cube. In this case, the parameters are position and color. In both instances, the final parameter (vertices and colors) represent the previously defined arrays - vertices and colors. +

            The glEnableVertexAttribArray() function enables the generic vertex attribute data arrays. The enabled attributes can be accessed and used to render the scene.

            +
            +   glVertexAttribPointer(ad->idx_position, 3, GL_FLOAT, GL_FALSE,
            +         3 * sizeof(float), cube_vertices);
            +   glVertexAttribPointer(ad->idx_color, 4, GL_FLOAT, GL_FALSE,
            +         4 * sizeof(float), cube_colors);
            +
            +   glEnableVertexAttribArray(ad->idx_position);
            +   glEnableVertexAttribArray(ad->idx_color);
            +	
            +
          4. + +
          5. The glUniformMatrix4fv() function modifies the values of the 4x4 MVP (Model View/Projection) uniform matrix according to the vertices information of the cube. An MVP matrix is created with data after each vertex of the cube has passed through 2 transformation stages: The first transformation state is the model view transformation, which includes translation, rotation, and scaling of objects. The second state is projection, which includes changes in the perspective or orthography. +
            +   glUniformMatrix4fv(ad->idx_mvp, 1, GL_FALSE, ad->mvp);
            +
          6. + +
          7. Once the vertex arrays have been enabled, the actual process of rendering graphics primitives from the array data occurs using the glDrawElements() function. The final parameter in this function is the indices array. +
            +   glDrawElements(GL_TRIANGLES, cube_indices_count, 				
            +                  GL_UNSIGNED_SHORT, cube_indices);
            +	
            +
          8. +
          +
        8. + +
        9. Add an animator. +

          The application regularly triggers updates of the GLView using the elm_glview_changed_set() function.

          +
          +static Eina_Bool anim(void *data) 
          +{
          +elm_glview_changed_set(data);
          +return EINA_TRUE;
          +}
          +
          +static bool app_create(void *data) 
          +{
          +      ...
          +   ani = ecore_animator_add(anim, gl);
          +      ...
          +}
          +
          +
        10. + +
        11. Set event callbacks. +

          The event callbacks receive touch events and allow you to rotate the cube in a vertical or horizontal direction.

          + +
          +static void mouse_down_cb(void *data, Evas *e , Evas_Object *obj , void *event_info)
          +{
          +   appdata_s *ad = data;
          +   ad->mouse_down = EINA_TRUE;
          +}
          +
          +static void mouse_move_cb(void *data, Evas *e , Evas_Object *obj , void *event_info)
          +{
          +   Evas_Event_Mouse_Move *ev;
          +   ev = (Evas_Event_Mouse_Move *)event_info;
          +   appdata_s *ad = data;
          +   float dx = 0, dy = 0;
          +
          +   if (ad->mouse_down) 
          +   {
          +      dx = ev->cur.canvas.x - ev->prev.canvas.x;
          +      dy = ev->cur.canvas.y - ev->prev.canvas.y;
          +      ad->xangle += dy;
          +      ad->yangle += dx;
          +   }
          +}
          +
          +static void mouse_up_cb(void *data, Evas *e , Evas_Object *obj , void *event_info)
          +{
          +   appdata_s *ad = data;
          +   ad->mouse_down = EINA_FALSE;
          +}
          +
          +
        12. + + +
        13. Set the delete callback. +

          The delete callback is triggered when the GLView is destroyed from the main loop.

          +

          The glDeleteShader() and glDeleteProgram() functions are used to free memory.

          +
          +static void del_gl(Evas_Object *obj) 
          +{
          +   appdata_s *ad = evas_object_data_get(obj, "ad");
          +
          +   glDeleteShader(ad->vtx_shader);
          +   glDeleteShader(ad->fgmt_shader);
          +   glDeleteProgram(ad->program);
          +
          +   evas_object_data_del((Evas_Object*) obj, "ad");
          +}
          +
          +
        14. +
        + + + +
        + +Go to top + + + + + + + + diff --git a/org.tizen.sampledescriptions/html/mobile_n/gps_service_sd_mn.htm b/org.tizen.sampledescriptions/html/mobile_n/gps_service_sd_mn.htm index 94250fc..eab282c 100644 --- a/org.tizen.sampledescriptions/html/mobile_n/gps_service_sd_mn.htm +++ b/org.tizen.sampledescriptions/html/mobile_n/gps_service_sd_mn.htm @@ -44,7 +44,7 @@

        The current implementation requires precise knowledge about the message receiver application (its package name).

        -

        Requirements

        +

        Prerequisites

        To ensure proper application execution, the http://tizen.org/privilege/location privilege must be set and the following features must be enabled:

        • http://tizen.org/feature/location
        • diff --git a/org.tizen.sampledescriptions/html/mobile_n/lockscreen_sd_mn.htm b/org.tizen.sampledescriptions/html/mobile_n/lockscreen_sd_mn.htm new file mode 100644 index 0000000..5e699d3 --- /dev/null +++ b/org.tizen.sampledescriptions/html/mobile_n/lockscreen_sd_mn.htm @@ -0,0 +1,345 @@ + + + + + + + + + + + + + Lockscreen Sample Overview + + + + +
          +
          + +
          +
          +

          Mobile native

          +
          +

          Lockscreen Sample Overview

          + +

          The Lockscreen sample application demonstrates how to implement the screen locking mechanism. The application interface consists of a main window and a simple swipe lock displayed over it. It enables the user to unlock the screen by swiping up or down.

          +

          The following figures show the user interface hierarchy and the unlock sequence where the lock is being swiped upwards.

          + +

          Figure: User interface hierarchy

          +

          + User interface hierarchy +

          + +

          Figure: Unlock sequence

          +

          + Screen is locked + Lock is swiped + Lock is swiped further + Screen is unlocked +

          + +

          To make this application work, the user must select it as a default lockscreen through the Settings menu.

          + +

          Implementation

          +

          The application follows the MVC pattern. Aside from the standard native application module with the main() function, it consists of the following components:

          +
            +
          • controller.c module
          • +
          • settings.c module serving as a model
          • +
          • main_window.c, lock.c, and swipe_lock.c modules serving as views
          • +
          + +

          The application initialization takes place with the controller_application_start() function. This function creates the main window and sets the current lock type based on user preferences. It also sets the current lockscreen background. But most of all, it registers callbacks for the following events:

          +
            +
          • Successful unlock using swipe gesture
          • +
          • Lockscreen background change (using the Settings application)
          • +
          • Display state change
          • +
          + +
          +bool
          +controller_application_start(void)
          +{
          +   if (!main_window_create())
          +   {
          +      // Error handling
          +   }
          +
          +   current_lock_set();
          +   // Add a controller swipe callback to the main window
          +   main_window_callbacks_add(swipe_unlocked_cb);
          +   // Add a lockscreen background image change callback, the image is selected in Settings application
          +   wallpaper_changed_cb(SYSTEM_SETTINGS_KEY_WALLPAPER_LOCK_SCREEN, NULL)
          +   // Add a callback for the background change (also changed using the Settings application)
          +   system_settings_set_changed_cb(SYSTEM_SETTINGS_KEY_WALLPAPER_LOCK_SCREEN, wallpaper_changed_cb, NULL);
          +   // Add a callback to listen to LCD on/off events
          +   device_add_callback(DEVICE_CALLBACK_DISPLAY_STATE, device_cb, NULL);
          +
          +   return true;
          +}
          +
          + +

          Activating the Lock

          + +

          To activate the lockscreen:

          + +
          1. Each time the LCD display is switched on, the currently selected lock type is activated through the device_cb() callback function: + +
            +static void
            +device_cb(device_callback_e type, void *value, void *user_data)
            +{
            +   switch ((display_state_e)value)
            +   {
            +      case DISPLAY_STATE_NORMAL:
            +         current_lock_set();
            +         break;
            +      case DISPLAY_STATE_SCREEN_DIM:
            +         break;
            +      case DISPLAY_STATE_SCREEN_OFF:
            +         break;
            +      default:
            +         current_lock_set();
            +         break;
            +   }
            +}
            +
          2. + +
          3. The settings_get_lock_type() model function is used to obtain the current lock type. +

            With this sample application, you can add other types of lock implementations of your own. To do that, modify the lockscreen_type_t enumeration type.

            +
            +static void
            +current_lock_set(void)
            +{
            +   switch(settings_get_lock_type())
            +   {
            +      case LOCKSCREEN_NONE:
            +         main_window_swipe_lock_deactivate();
            +         break;
            +      case LOCKSCREEN_SWIPE:
            +         main_window_swipe_lock_activate();
            +         break;
            +      default:
            +         break;
            +   }
            +}
            +
          4. +
          5. The user interface is created with the main_window_create() function. It consists of a background and a swipe lock view. +
            +bool
            +main_window_create(void)
            +{
            +   s_main_window_data.win = elm_win_add(NULL, PACKAGE, ELM_WIN_DOCK);
            +
            +   // Error handling
            +
            +   // Common window settings
            +
            +   // Default alpha is 0
            +   elm_win_alpha_set(s_main_window_data.win, EINA_TRUE);
            +
            +   evas_object_smart_callback_add(s_main_window_data.win, "delete,request", delete_cb, NULL);
            +
            +   if (!background_create(s_main_window_data.screen_width, s_main_window_data.screen_height) ||
            +      // Create the swipe lock to cover the entire window
            +      !swipe_create(s_main_window_data.screen_width, s_main_window_data.screen_height))
            +   {
            +      return false;
            +   }
            +
            +   // Show the window after the base GUI is set up
            +   evas_object_show(s_main_window_data.win);
            +
            +   return true;
            +}
            +
          + +

          Unlocking the Device

          + +

          To unlock the device:

          + +
          1. The controller module uses the main_window_callbacks_add() function to register its callbacks for the user interface. Consequently, the module is notified whenever the user successfully unlocks the device with a swipe gesture, and the swipe_unlocked_cb() function is invoked. + +
            +void
            +main_window_callbacks_add(swipe_unlock_cb unlock_cb)
            +{
            +   if (!s_main_window_data.swipe_unlock_cb || unlock_cb)
            +   {
            +      swipe_lock_callbacks_add(s_main_window_data.swipe_lock, swipe_drag_cb, swipe_drag_end_cb);
            +      s_main_window_data.swipe_unlock_cb = unlock_cb;
            +   }
            +}
            +
            +static void
            +swipe_unlocked_cb(void)
            +{
            +   main_window_lock_deactivate();
            +}
            +
          2. + +
          3. After a successful swipe, the swipe lock is deactivated using the main_window_swipe_lock_deactivate() function: +
            +void
            +main_window_swipe_lock_deactivate(void)
            +{
            +   // Hide the swipe lock UI object
            +   evas_object_hide(s_main_window_data.swipe_lock);
            +   // Hide the main application window
            +   evas_object_hide(s_main_window_data.win);
            +}
            +
          + +

          Creating the Lockscreen View

          + +

          The swipe lock view is created as the elm_layout in the lock_create() function (called from the swipe_lock_create() function). One of its parameters is the layout edj file name.

          +

          The lock_create() function +associates the elm_layout with the EDJE.

          +
          +Evas_Object * lock_create(Evas_Object * parent, const char *edje_file_name)
          +{
          +   char layout_file_full_path[PATH_MAX] = {0,};
          +
          +   Evas_Object *lock = elm_layout_add(parent);
          +
          +   // Error handling and layout file path obtaining
          +
          +   if (!elm_layout_file_set(lock, layout_file_full_path, LOCK_MAIN_GROUP))
          +   {
          +      // Error handling
          +   }
          +
          +   return lock;
          +}
          +
          +Evas_Object *
          +swipe_lock_create(Evas_Object * parent)
          +{
          +   return lock_create(parent, SWIPE_LOCK_EDJ_FILE_NAME);
          +}
          +
          + +

          The following example is the related EDJE file:

          + +
          +#include "edje_definitions.h"
          +
          +styles
          +{
          +   style
          +   // main_text_style applies to MAIN_TEXT_PART of TEXTBLOCK type
          +   // Its syntax is very similar to HTML
          +   {
          +      name: "main_text_style";
          +      base: "font="default" font_size=60 align=center color=#ffffffff style=shadow,bottom shadow_color=#000000ff wrap=mixed";
          +   }
          +}
          +
          +collections
          +{
          +   group
          +   {
          +      name: LOCK_MAIN_GROUP;
          +      parts
          +      {
          +         part
          +         {
          +            name: BACKGROUND_PART;
          +            type: RECT;
          +            description
          +            {
          +               // This is the default state description for the BACKGROUND_PART
          +               // The BACKGROUND_COLOR constants are defined in "edje_definitions.h"
          +               state: "default" 0.0;
          +               color: BACKGROUND_COLOR_R BACKGROUND_COLOR_G BACKGROUND_COLOR_B BACKGROUND_COLOR_A;
          +               visible: 1;
          +               // The background spans over the entire layout (which is the size of the main window):
          +               rel1.relative: 0.0 0.0;
          +               rel2.relative: 1.0 1.0;
          +            }
          +            // The BACKGROUND_PART is given a special attribute and it can be dragged all over the screen
          +            // x and y axis attribute properties' meanings are: 
          +            // 1st: enable(1)/disable(0) movement, 2nd: step, 3rd is not used in this application
          +            // See https://docs.enlightenment.org/auto/edje/edcref.html#sec_collections_group_parts_dragable for more information
          +
          +            dragable
          +            {
          +               x: 0 0 0;
          +               y: 1 1 0;
          +            }
          +         }
          +
          +         part
          +         {
          +            name: MAIN_TEXT_PART;
          +            type: TEXTBLOCK;
          +            repeat_events: 1;
          +            description
          +            {
          +               // This is default state description for MAIN_TEXT_PART
          +               // SWIPE_MAIN_TEXT_PART_REL constants are defined in "edje_definitions.h"
          +               // MAIN_TEXT_PART is the text you can see in the "Unlock sequence" figure
          +               // Note that although only the BACKGROUND_PART is draggable, the MAIN_TEXT_PART moves with it too
          +               // This is because the MAIN_TEXT_PART keeps its relative position to the BACKGROUND_PART all the time
          +               state: "default" 0.0;
          +               rel1.relative: SWIPE_MAIN_TEXT_PART_REL1_X SWIPE_MAIN_TEXT_PART_REL1_Y; rel1.to: BACKGROUND_PART;
          +               rel2.relative: SWIPE_MAIN_TEXT_PART_REL2_X SWIPE_MAIN_TEXT_PART_REL2_Y; rel2.to: BACKGROUND_PART;
          +               text
          +               {
          +                  style: "main_text_style";
          +                  text: SWIPE_MAIN_TEXT_PART_TEXT;
          +               }
          +            }
          +         }
          +      }
          +
          +      programs
          +      {
          +         program
          +         {
          +            // The EDJE script contains a program to reset a draggable part to its initial position
          +            // Normally, when the user stops dragging the BACKGROUND_PART, it does not go back to its original position 
          +            // The program is triggered from the swipe_lock_drag_reset() function (see below)
          +            name: "reset_initial_position";
          +            signal: SWIPE_RESET_SIGNAL;
          +            source: SWIPE_RESET_SIGNAL_SOURCE;
          +            action: DRAG_VAL_SET 0.0 0.0;
          +            target: BACKGROUND_PART;
          +         }
          +      }
          +   }
          +}
          +
          + +
          +void
          +swipe_lock_drag_reset(Evas_Object *swipe_lock)
          +{
          +   elm_layout_signal_emit(swipe_lock, SWIPE_RESET_SIGNAL, SWIPE_RESET_SIGNAL_SOURCE);
          +}
          +
          + + + +
          + +Go to top + + + + + + + \ No newline at end of file diff --git a/org.tizen.sampledescriptions/html/mobile_n/preference_sd_mn.htm b/org.tizen.sampledescriptions/html/mobile_n/preference_sd_mn.htm index e89850e..8ea90df 100644 --- a/org.tizen.sampledescriptions/html/mobile_n/preference_sd_mn.htm +++ b/org.tizen.sampledescriptions/html/mobile_n/preference_sd_mn.htm @@ -74,7 +74,7 @@

          The following figure illustrates the application workflow with the PROPERTY_ITEMS_ENUM_KEY constraints.

          Figure: Application workflow

          Application workflow

          -

          Requirements

          +

          Prerequisites

          The following privilege must be set:

          • http://tizen.org/privilege/systemsettings
          • diff --git a/org.tizen.sampledescriptions/html/mobile_n/sd_mn.htm b/org.tizen.sampledescriptions/html/mobile_n/sd_mn.htm index 689c4a0..c56a082 100644 --- a/org.tizen.sampledescriptions/html/mobile_n/sd_mn.htm +++ b/org.tizen.sampledescriptions/html/mobile_n/sd_mn.htm @@ -46,6 +46,14 @@ Bundle Demonstrates how you can manipulate bundle objects. + + Cairo Basic + Demonstrates how you can implement the Cairo image backend. + + + Cairo EvasGL + Demonstrates how you can implement the Cairo GL backend with the Evas_GL surface. + Calculator Demonstrates how you can implement an advanced calculator application. @@ -74,7 +82,6 @@ GLViewShader Demonstrates how you can render more complex geometric shapes with OepnGL® ES and use Elementary GLView helper macros to port existing code. - HybridServiceApp Demonstrates how you can communicate with a Tizen Web application (HybridWebApp) to manage the timer for the Web application. + Lockscreen + Demonstrates how you can implement a screen locking mechanism. + + Media App Demonstrates how you can develop media handling applications with the ability to manage different media sources. @@ -141,6 +151,10 @@ UI Components Demonstrates how you can implement an interactive application GUI with basic Elementary UI components. + + Volume + Demonstrates how you can acquire and set the device sound levels. + [UI Sample] Alignment Demonstrates how you can place objects on the layout. diff --git a/org.tizen.sampledescriptions/html/mobile_n/ui_email_sd_mn.htm b/org.tizen.sampledescriptions/html/mobile_n/ui_email_sd_mn.htm index 15763d0..adb5e8e 100644 --- a/org.tizen.sampledescriptions/html/mobile_n/ui_email_sd_mn.htm +++ b/org.tizen.sampledescriptions/html/mobile_n/ui_email_sd_mn.htm @@ -1,292 +1,292 @@ - - - - - - - - - - - - - - [UI Sample] Email Sample Overview - - - - -
            -
            - -
            -
            -

            Mobile native

            -
            - -

            [UI Sample] Email Sample Overview

            - -

            The [UI Sample] Email sample application demonstrates how to implement a complex view by a recursive composition of standard EFL UI components and containers in a UI component hierarchy.

            -

            The sample uses UI components, such as elm_conformant, elm_naviframe and elm_layout for the view management, containers, such as elm_list, elm_genlist, and elm_panel for the UI component management inside the view, and UI components, such as elm_button and elm_image for the content inside view.

            - -

            Main View

            - -

            The following figure illustrates the main view of the [UI Sample] Email sample application, its wireframe structure, and the UI component tree.

            - -

            Figure: [UI Sample] Email main view

            -

            [UI Sample] Email main view

            -

            [UI Sample] Email main view

            -

            [UI Sample] Email main view

            - -

            The create_base_gui() function creates the window which consists of an indicator (elm_conformant), view manager (elm_naviframe), and the content created by using the create_main_view() function. The drawer and compose button are inserted in the naviframe.

            -
            -static void
            -create_base_gui(appdata_s *ad)
            -{
            -   Evas_Object *btn1, *btn2, *bg;
            -   Elm_Object_Item *nf_it;
            -
            -   // Window
            -   ad->win = elm_win_util_standard_add(PACKAGE, PACKAGE);
            -   elm_win_wm_desktop_layout_support_set(ad->win, EINA_TRUE);
            -   elm_win_conformant_set(ad->win, EINA_TRUE);
            -   elm_win_autodel_set(ad->win, EINA_TRUE);
            -
            -   if (elm_win_wm_rotation_supported_get(ad->win)) 
            -   {
            -      int rots[4] = { 0, 90, 180, 270 };
            -      elm_win_wm_rotation_available_rotations_set(ad->win, (const int *)(&rots), 4);
            -   }
            -   evas_object_smart_callback_add(ad->win, "delete,request", win_delete_request_cb, NULL);
            -
            -   // Conformant
            -   ad->conform =  elm_conformant_add(ad->win);
            -   elm_win_indicator_mode_set(ad->win, ELM_WIN_INDICATOR_SHOW);
            -   elm_win_indicator_opacity_set(ad->win, ELM_WIN_INDICATOR_OPAQUE);
            -   elm_win_resize_object_add(ad->win, ad->conform);
            -   evas_object_show(ad->conform);
            -
            -   // Indicator BG
            -   bg = elm_bg_add(ad>conform);
            -   elm_object_style_set(bg, "indicator/headerbg");
            -   elm_object_part_content_set(ad>conform, "elm.swallow.indicator_bg", bg);
            -   evas_object_show(bg);
            -
            -   // Main view
            -   ad->base_ly = create_main_view(ad);
            -   elm_object_content_set(ad>conform, ad>base_ly);
            -
            -   // Naviframe
            -   ad->nf = elm_naviframe_add(ad->base_ly);
            -   eext_object_event_callback_add(ad>nf, EEXT_CALLBACK_BACK, eext_naviframe_back_cb, ad);
            -   elm_object_part_content_set(ad->base_ly, "elm.swallow.content", ad->nf);
            -   evas_object_show(ad->nf);
            -
            -   // Genlist
            -   ad>genlist = create_genlist(ad>nf);
            -
            -   nf_it = elm_naviframe_item_push(ad->nf, "In Box", NULL, NULL, ad->genlist, NULL);
            -   elm_naviframe_item_pop_cb_set(nf_it, nf_it_pop_cb, ad);
            -   elm_object_item_part_text_set(nf_it, "subtitle", user_email);
            -
            -   // Left panel toggle button
            -   btn1 = create_button(ad->nf, "naviframe/drawers", NULL);
            -   evas_object_smart_callback_add(btn1, "clicked", _left_panel_button_clicked_cb, ad);
            -   elm_object_item_part_content_set(nf_it, "title_left_btn", btn1);
            -
            -   // Right compose button
            -   btn2 = create_button(ad->nf, NULL, "<font_size=20>New</font_size>");
            -   evas_object_smart_callback_add(btn2, "clicked", _composer_button_clicked_cb, ad);
            -   elm_object_item_part_content_set(nf_it, "title_right_btn", btn2);
            -
            -   // Show the window after the base GUI is set up
            -   evas_object_show(ad->win);
            -}
            -
            - -

            The create_main_view() function creates the content of the view. First, the base layout is created. The drawer (panel) list and genlist are also created. The drawer and genlist are inserted in the layout. The drawer contains a list.

            -
            -static Evas_Object *
            -create_main_view(appdata_s *ad)
            -{
            -   Evas_Object *layout;
            -
            -   // Drawer layout
            -   layout = create_base_layout(ad->conform);
            -
            -   // Panel
            -   ad->panel = create_panel(layout);
            -   elm_object_part_content_set(layout, "elm.swallow.left", ad->panel);
            -
            -   // Panel list
            -   ad->panel_list = create_panel_list(ad->panel);
            -   evas_object_size_hint_weight_set(ad->panel_list, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
            -   evas_object_size_hint_align_set(ad->panel_list, EVAS_HINT_FILL, EVAS_HINT_FILL);
            -   evas_object_smart_callback_add(ad->panel_list, "selected", _list_clicked_cb, ad);
            -   elm_object_content_set(ad->panel, ad->panel_list);
            -
            -   return layout;
            -}
            -
            - -The create_genlist() function creates a genlist. The genlist has 2 item classes, group item and item. -
            -static Evas_Object *
            -create_genlist(Evas_Object *parent)
            -{
            -   ...
            -   // Create item class
            -   Elm_Genlist_Item_Class *gitc = elm_genlist_item_class_new();
            -   Elm_Genlist_Item_Class *itc = elm_genlist_item_class_new();
            -
            -   gitc->item_style = "groupindex";
            -   gitc->func.text_get = gl_text_get_cb;
            -   gitc->func.content_get = gl_content_get_cb;
            -   gitc->func.del = gl_del_cb;
            -
            -   itc->item_style = "2line.top.3";
            -   itc->func.text_get = gl_text_get_cb;
            -   itc->func.content_get = gl_content_get_cb;
            -   itc->func.del = gl_del_cb;
            -
            -   genlist = elm_genlist_add(parent);
            -
            -   ...
            -
            -   int group_count = 0;
            -   for (index = 0; index < n_items; index++) 
            -   {
            -      item_data_s *id = calloc(sizeof(item_data_s), 1);
            -      id->index = index;
            -      if (index % 10 == 0) 
            -      {
            -         group_count++;
            -         id->index = group_count;
            -         git = elm_genlist_item_append(genlist, // Genlist object
            -                     gitc, // Item class
            -                     id, // Item class user data
            -                     NULL,
            -                     ELM_GENLIST_ITEM_GROUP, // Item type
            -                     gl_selected_cb, // Select smart callback
            -                     id); // Smart callback user data
            -         id->item = git;
            -      }
            -      else 
            -      {
            -         it = elm_genlist_item_append(genlist, // Genlist object
            -                     itc, // Item class
            -                     id, // Item class user data
            -                     git, // Parent item
            -                     ELM_GENLIST_ITEM_NONE, // Item type
            -                     gl_selected_cb, // Select smart callback
            -                     id); // Smart callback user data
            -         id->item = it;
            -      }
            -   }
            -   elm_genlist_item_class_free(gitc);
            -   elm_genlist_item_class_free(itc);
            -   evas_object_show(genlist);
            -
            -   return genlist;
            -}
            -
            - -

            Compose View

            - -

            The following figure illustrates the main screen of the Compose view, its wireframe structure, and the UI component tree.

            - -

            Figure: Compose view

            -

            Email compose view

            -

            Email compose UI component tree

            - -
            evas_object_smart_callback_add(btn, "clicked", _composer_button_clicked_cb, ad);
            -
            - -

            In this sample, a smart callback for clicking the compose button is added by default.

            - -

            The smart callback is called when the compose button is clicked. In this callback, the compose view is created. It consists of a scroller containing a box. The box contains 4 entries. The vertical weight of the box is 0.0, which means that the box resizes to the minimum size.

            -
            -static void
            -_composer_button_clicked_cb(void *data, Evas_Object * obj, void *event_info)
            -{
            -   appdata_s *ad = data;
            -   cdata_s *cd = calloc(1, sizeof(cdata_s));
            -   cd->ad = ad;
            -   Evas_Object *btn, *scroller, *main_box, *myemail, *to, *subject, *content;
            -   Elm_Object_Item *nf_it;
            -
            -   scroller = create_scroller(ad->nf);
            -
            -   // Append box
            -   main_box = create_box(scroller);
            -   evas_object_size_hint_weight_set(main_box, EVAS_HINT_EXPAND, 0.0);
            -   evas_object_size_hint_align_set(main_box, EVAS_HINT_FILL, EVAS_HINT_FILL);
            -   elm_box_padding_set(main_box, 0, 30);
            -   elm_object_content_set(scroller, main_box);
            -
            -   // Use email
            -   myemail = create_entry(main_box, user_email, NULL);
            -   elm_entry_editable_set(myemail, EINA_FALSE);
            -   elm_entry_single_line_set(myemail, EINA_TRUE);
            -   evas_object_size_hint_weight_set(myemail, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
            -   evas_object_size_hint_align_set(myemail, EVAS_HINT_FILL, EVAS_HINT_FILL);
            -   elm_box_pack_end(main_box, myemail);
            -
            -   // To
            -   to = create_entry(main_box, NULL, "To");
            -   evas_object_size_hint_weight_set(to, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
            -   evas_object_size_hint_align_set(to, EVAS_HINT_FILL, EVAS_HINT_FILL);
            -   elm_box_pack_end(main_box, to);
            -   cd->to = to;
            -
            -   // Subject
            -   subject = create_entry(main_box, NULL, "Subject");
            -   evas_object_size_hint_weight_set(subject, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
            -   evas_object_size_hint_align_set(subject, EVAS_HINT_FILL, EVAS_HINT_FILL);
            -   elm_box_pack_end(main_box, subject);
            -   cd->subject = subject;
            -
            -   // Content
            -   content = create_entry(main_box, NULL, "Compose email");
            -   evas_object_size_hint_weight_set(content, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
            -   evas_object_size_hint_align_set(content, EVAS_HINT_FILL, EVAS_HINT_FILL);
            -   elm_box_pack_end(main_box, content);
            -   cd->content = content;
            -
            -   nf_it = elm_naviframe_item_push(ad->nf, "Compose", NULL, NULL, scroller, NULL);
            -
            -   // Back button
            -   btn = create_button(ad->nf, "naviframe/title_cancel", NULL);
            -   evas_object_smart_callback_add(btn, "clicked", _back_button_clicked_cb, cd);
            -   elm_object_item_part_content_set(nf_it, "title_left_btn", btn);
            -
            -   // Send button
            -   btn = create_button(ad->nf, "naviframe/title_done", NULL);
            -   evas_object_smart_callback_add(btn, "clicked", _send_button_clicked_cb, cd);
            -   elm_object_item_part_content_set(nf_it, "title_right_btn", btn);
            -}
            -
            - - - -
            - -Go to top - - - - - - + + + + + + + + + + + + + + [UI Sample] Email Sample Overview + + + + +
            +
            + +
            +
            +

            Mobile native

            +
            + +

            [UI Sample] Email Sample Overview

            + +

            The [UI Sample] Email sample application demonstrates how to implement a complex view by a recursive composition of standard EFL UI components and containers in a UI component hierarchy.

            +

            The sample uses UI components, such as elm_conformant, elm_naviframe and elm_layout for the view management, containers, such as elm_list, elm_genlist, and elm_panel for the UI component management inside the view, and UI components, such as elm_button and elm_image for the content inside view.

            + +

            Main View

            + +

            The following figure illustrates the main view of the [UI Sample] Email sample application, its wireframe structure, and the UI component tree.

            + +

            Figure: [UI Sample] Email main view

            +

            [UI Sample] Email main view

            +

            [UI Sample] Email main view

            +

            [UI Sample] Email main view

            + +

            The create_base_gui() function creates the window which consists of an indicator (elm_conformant), view manager (elm_naviframe), and the content created by using the create_main_view() function. The drawer and compose button are inserted in the naviframe.

            +
            +static void
            +create_base_gui(appdata_s *ad)
            +{
            +   Evas_Object *btn1, *btn2, *bg;
            +   Elm_Object_Item *nf_it;
            +
            +   // Window
            +   ad->win = elm_win_util_standard_add(PACKAGE, PACKAGE);
            +   elm_win_wm_desktop_layout_support_set(ad->win, EINA_TRUE);
            +   elm_win_conformant_set(ad->win, EINA_TRUE);
            +   elm_win_autodel_set(ad->win, EINA_TRUE);
            +
            +   if (elm_win_wm_rotation_supported_get(ad->win)) 
            +   {
            +      int rots[4] = { 0, 90, 180, 270 };
            +      elm_win_wm_rotation_available_rotations_set(ad->win, (const int *)(&rots), 4);
            +   }
            +   evas_object_smart_callback_add(ad->win, "delete,request", win_delete_request_cb, NULL);
            +
            +   // Conformant
            +   ad->conform =  elm_conformant_add(ad->win);
            +   elm_win_indicator_mode_set(ad->win, ELM_WIN_INDICATOR_SHOW);
            +   elm_win_indicator_opacity_set(ad->win, ELM_WIN_INDICATOR_OPAQUE);
            +   elm_win_resize_object_add(ad->win, ad->conform);
            +   evas_object_show(ad->conform);
            +
            +   // Indicator BG
            +   bg = elm_bg_add(ad>conform);
            +   elm_object_style_set(bg, "indicator/headerbg");
            +   elm_object_part_content_set(ad>conform, "elm.swallow.indicator_bg", bg);
            +   evas_object_show(bg);
            +
            +   // Main view
            +   ad->base_ly = create_main_view(ad);
            +   elm_object_content_set(ad>conform, ad>base_ly);
            +
            +   // Naviframe
            +   ad->nf = elm_naviframe_add(ad->base_ly);
            +   eext_object_event_callback_add(ad>nf, EEXT_CALLBACK_BACK, eext_naviframe_back_cb, ad);
            +   elm_object_part_content_set(ad->base_ly, "elm.swallow.content", ad->nf);
            +   evas_object_show(ad->nf);
            +
            +   // Genlist
            +   ad>genlist = create_genlist(ad>nf);
            +
            +   nf_it = elm_naviframe_item_push(ad->nf, "In Box", NULL, NULL, ad->genlist, NULL);
            +   elm_naviframe_item_pop_cb_set(nf_it, nf_it_pop_cb, ad);
            +   elm_object_item_part_text_set(nf_it, "subtitle", user_email);
            +
            +   // Left panel toggle button
            +   btn1 = create_button(ad->nf, "naviframe/drawers", NULL);
            +   evas_object_smart_callback_add(btn1, "clicked", _left_panel_button_clicked_cb, ad);
            +   elm_object_item_part_content_set(nf_it, "title_left_btn", btn1);
            +
            +   // Right compose button
            +   btn2 = create_button(ad->nf, NULL, "<font_size=20>New</font_size>");
            +   evas_object_smart_callback_add(btn2, "clicked", _composer_button_clicked_cb, ad);
            +   elm_object_item_part_content_set(nf_it, "title_right_btn", btn2);
            +
            +   // Show the window after the base GUI is set up
            +   evas_object_show(ad->win);
            +}
            +
            + +

            The create_main_view() function creates the content of the view. First, the base layout is created. The drawer (panel) list and genlist are also created. The drawer and genlist are inserted in the layout. The drawer contains a list.

            +
            +static Evas_Object *
            +create_main_view(appdata_s *ad)
            +{
            +   Evas_Object *layout;
            +
            +   // Drawer layout
            +   layout = create_base_layout(ad->conform);
            +
            +   // Panel
            +   ad->panel = create_panel(layout);
            +   elm_object_part_content_set(layout, "elm.swallow.left", ad->panel);
            +
            +   // Panel list
            +   ad->panel_list = create_panel_list(ad->panel);
            +   evas_object_size_hint_weight_set(ad->panel_list, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
            +   evas_object_size_hint_align_set(ad->panel_list, EVAS_HINT_FILL, EVAS_HINT_FILL);
            +   evas_object_smart_callback_add(ad->panel_list, "selected", _list_clicked_cb, ad);
            +   elm_object_content_set(ad->panel, ad->panel_list);
            +
            +   return layout;
            +}
            +
            + +The create_genlist() function creates a genlist. The genlist has 2 item classes, group item and item. +
            +static Evas_Object *
            +create_genlist(Evas_Object *parent)
            +{
            +   ...
            +   // Create item class
            +   Elm_Genlist_Item_Class *gitc = elm_genlist_item_class_new();
            +   Elm_Genlist_Item_Class *itc = elm_genlist_item_class_new();
            +
            +   gitc->item_style = "groupindex";
            +   gitc->func.text_get = gl_text_get_cb;
            +   gitc->func.content_get = gl_content_get_cb;
            +   gitc->func.del = gl_del_cb;
            +
            +   itc->item_style = "2line.top.3";
            +   itc->func.text_get = gl_text_get_cb;
            +   itc->func.content_get = gl_content_get_cb;
            +   itc->func.del = gl_del_cb;
            +
            +   genlist = elm_genlist_add(parent);
            +
            +   ...
            +
            +   int group_count = 0;
            +   for (index = 0; index < n_items; index++) 
            +   {
            +      item_data_s *id = calloc(sizeof(item_data_s), 1);
            +      id->index = index;
            +      if (index % 10 == 0) 
            +      {
            +         group_count++;
            +         id->index = group_count;
            +         git = elm_genlist_item_append(genlist, // Genlist object
            +                     gitc, // Item class
            +                     id, // Item class user data
            +                     NULL,
            +                     ELM_GENLIST_ITEM_GROUP, // Item type
            +                     gl_selected_cb, // Select smart callback
            +                     id); // Smart callback user data
            +         id->item = git;
            +      }
            +      else 
            +      {
            +         it = elm_genlist_item_append(genlist, // Genlist object
            +                     itc, // Item class
            +                     id, // Item class user data
            +                     git, // Parent item
            +                     ELM_GENLIST_ITEM_NONE, // Item type
            +                     gl_selected_cb, // Select smart callback
            +                     id); // Smart callback user data
            +         id->item = it;
            +      }
            +   }
            +   elm_genlist_item_class_free(gitc);
            +   elm_genlist_item_class_free(itc);
            +   evas_object_show(genlist);
            +
            +   return genlist;
            +}
            +
            + +

            Compose View

            + +

            The following figure illustrates the main screen of the Compose view, its wireframe structure, and the UI component tree.

            + +

            Figure: Compose view

            +

            Email compose view

            +

            Email compose UI component tree

            + +
            evas_object_smart_callback_add(btn, "clicked", _composer_button_clicked_cb, ad);
            +
            + +

            In this sample, a smart callback for clicking the compose button is added by default.

            + +

            The smart callback is called when the compose button is clicked. In this callback, the compose view is created. It consists of a scroller containing a box. The box contains 4 entries. The vertical weight of the box is 0.0, which means that the box resizes to the minimum size.

            +
            +static void
            +_composer_button_clicked_cb(void *data, Evas_Object * obj, void *event_info)
            +{
            +   appdata_s *ad = data;
            +   cdata_s *cd = calloc(1, sizeof(cdata_s));
            +   cd->ad = ad;
            +   Evas_Object *btn, *scroller, *main_box, *myemail, *to, *subject, *content;
            +   Elm_Object_Item *nf_it;
            +
            +   scroller = create_scroller(ad->nf);
            +
            +   // Append box
            +   main_box = create_box(scroller);
            +   evas_object_size_hint_weight_set(main_box, EVAS_HINT_EXPAND, 0.0);
            +   evas_object_size_hint_align_set(main_box, EVAS_HINT_FILL, EVAS_HINT_FILL);
            +   elm_box_padding_set(main_box, 0, 30);
            +   elm_object_content_set(scroller, main_box);
            +
            +   // Use email
            +   myemail = create_entry(main_box, user_email, NULL);
            +   elm_entry_editable_set(myemail, EINA_FALSE);
            +   elm_entry_single_line_set(myemail, EINA_TRUE);
            +   evas_object_size_hint_weight_set(myemail, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
            +   evas_object_size_hint_align_set(myemail, EVAS_HINT_FILL, EVAS_HINT_FILL);
            +   elm_box_pack_end(main_box, myemail);
            +
            +   // To
            +   to = create_entry(main_box, NULL, "To");
            +   evas_object_size_hint_weight_set(to, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
            +   evas_object_size_hint_align_set(to, EVAS_HINT_FILL, EVAS_HINT_FILL);
            +   elm_box_pack_end(main_box, to);
            +   cd->to = to;
            +
            +   // Subject
            +   subject = create_entry(main_box, NULL, "Subject");
            +   evas_object_size_hint_weight_set(subject, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
            +   evas_object_size_hint_align_set(subject, EVAS_HINT_FILL, EVAS_HINT_FILL);
            +   elm_box_pack_end(main_box, subject);
            +   cd->subject = subject;
            +
            +   // Content
            +   content = create_entry(main_box, NULL, "Compose email");
            +   evas_object_size_hint_weight_set(content, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
            +   evas_object_size_hint_align_set(content, EVAS_HINT_FILL, EVAS_HINT_FILL);
            +   elm_box_pack_end(main_box, content);
            +   cd->content = content;
            +
            +   nf_it = elm_naviframe_item_push(ad->nf, "Compose", NULL, NULL, scroller, NULL);
            +
            +   // Back button
            +   btn = create_button(ad->nf, "naviframe/title_cancel", NULL);
            +   evas_object_smart_callback_add(btn, "clicked", _back_button_clicked_cb, cd);
            +   elm_object_item_part_content_set(nf_it, "title_left_btn", btn);
            +
            +   // Send button
            +   btn = create_button(ad->nf, "naviframe/title_done", NULL);
            +   evas_object_smart_callback_add(btn, "clicked", _send_button_clicked_cb, cd);
            +   elm_object_item_part_content_set(nf_it, "title_right_btn", btn);
            +}
            +
            + + + +
            + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.sampledescriptions/html/mobile_n/volume_sd_mn.htm b/org.tizen.sampledescriptions/html/mobile_n/volume_sd_mn.htm new file mode 100644 index 0000000..9ef2912 --- /dev/null +++ b/org.tizen.sampledescriptions/html/mobile_n/volume_sd_mn.htm @@ -0,0 +1,204 @@ + + + + + + + + + + + + + Volume Sample Overview + + + + +
            +
            + +
            +
            +

            Mobile native

            +
            +

            Volume Sample Overview

            +

            The Volume sample demonstrates how you can use the Sound Manager API to acquire and set the device sound levels. The application window consists of a list of sliders that manage the levels of different volume types.

            + +

            When the application is launched, it acquires the values of the volume types and sets the sliders accordingly. Apart from manually managing the volumes using sliders, the application also reacts to changes made outside it, for example, in the device settings or using hardware buttons.

            +

            The following figure illustrates the main screen of the application.

            + +

            Figure: Volume screen

            +

            + Volume screen +

            + +

            Prerequisites

            +

            The following privilege must be set:

            +
              +
            • http://tizen.org/privilege/volume.set
            • +
            + + +

            Implementation

            + +

            The application uses the volume_controller_type enum to manage different volume types easily:

            +
            +typedef enum 
            +{
            +   CONTROLLER_SYSTEM,
            +   CONTROLLER_NOTIFICATION,
            +   CONTROLLER_ALARM,
            +   CONTROLLER_RINGTONE,
            +   CONTROLLER_MEDIA,
            +   CONTROLLER_CALL,
            +   CONTROLLER_MAX
            +} volume_controller_type;
            +
            +

            The enum is designed to be compliant with the sound_type_e enum used by the Sound Manager API to avoid unnecessary types duplication.

            +
            +typedef enum
            +{
            +   SOUND_TYPE_SYSTEM, // Sound type for system
            +   SOUND_TYPE_NOTIFICATION, // Sound type for notifications
            +   SOUND_TYPE_ALARM, // Sound type for alarm
            +   SOUND_TYPE_RINGTONE, // Sound type for ringtones
            +   SOUND_TYPE_MEDIA, // Sound type for media
            +   SOUND_TYPE_CALL, // Sound type for call
            +   SOUND_TYPE_VOIP, // Sound type for voip
            +   SOUND_TYPE_VOICE, // Sound type for voice
            +} sound_type_e;
            +
            +

            The 2 last sound types of the sound_type_e are not supported in this application.

            + +

            Volume Manager Module

            + +

            Before the volume level sliders are created, the maximum possible value must be known for each volume type. To retrieve this information, use the sound_manager_get_max_volume() function. It takes the sound_type_e enum as an in parameter and int as an out parameter.

            +
            +if (sound_manager_get_max_volume((sound_type_e)type, &max_volume) != SOUND_MANAGER_ERROR_NONE) 
            +{
            +   // Error handling
            +}
            +
            + +

            The volume_manager_get_volume() and +volume_manager_set_volume() functions manage the device sound levels. To get the volume level for each sound type, use the sound_manager_get_volume() function. Similarly, to set the volume level, use the sound_manager_set_volume() function. Both the functions require a sound_type_e value to be passed.

            +
            +int
            +volume_manager_get_volume(volume_controller_type type)
            +{
            +   int volume = -1;
            +
            +   if (sound_manager_get_volume((sound_type_e)type, &volume) != SOUND_MANAGER_ERROR_NONE) 
            +   {
            +      // Error handling
            +   }
            +
            +   return volume;
            +}
            +
            +bool
            +volume_manager_set_volume(volume_controller_type type, int value)
            +{
            +   if (sound_manager_set_volume((sound_type_e)type, value) != SOUND_MANAGER_ERROR_NONE) 
            +   {
            +      // Error handling
            +   }
            +
            +   return true;
            +}
            +
            + +

            To react to volume level changes made outside the application, set a callback function for the volume change event with the sound_manager_set_volume_changed_cb() function.

            + +

            The callback in this sample application invokes the view_set_volume_value() function to update the UI. Both the sound_type_e enum and the new volume value are passed to the callback function as parameters to introduce the changes to the UI correctly.

            +
            +if (sound_manager_set_volume_changed_cb(__volume_changed_cb, NULL) != SOUND_MANAGER_ERROR_NONE) 
            +{
            +    // Error handling
            +}
            +
            +static void
            +__volume_changed_cb(sound_type_e type, unsigned int volume, void *user_data)
            +{
            +   view_set_volume_value((volume_controller_type)type, (double)volume);
            +}
            +
            + +

            When the callback function is no longer needed, unset it using the sound_manager_unset_volume_changed_cb() function.

            +
            +if (sound_manager_unset_volume_changed_cb() != SOUND_MANAGER_ERROR_NONE)
            +   // Error handling
            +
            + +

            View Manager Module

            + +

            A controller is created for each of the volume types. The controller consists of a volume type label, volume value label, and a slider for manually changing the value. Each controller has a custom EDJ layout.

            + +
            +static Evas_Object *
            +__create_controller(volume_controller_type type)
            +{
            +   // Variable declaration
            +
            +   __app_get_resource(EDJ_ITEM_FILE, edj_item_path, (int)PATH_MAX);
            +
            +   item_layout = elm_layout_add(s_viewdata.layout);
            +   // Error handling
            +
            +   elm_layout_file_set(item_layout, edj_item_path, GRP_MAIN);
            +   elm_object_part_text_set(item_layout, PART_ITEM_TYPE_TEXT, volume_item_title[type]);
            +
            +   slider = __create_slider(item_layout);
            +   // Error handling
            +
            +   evas_object_smart_callback_add(slider, "changed", _slider_changed_cb, (void*)type);
            +   elm_object_part_content_set(item_layout, PART_ITEM_SLIDER, slider);
            +
            +   elm_object_part_content_set(s_viewdata.layout, volume_item_part_name[type], item_layout);
            +
            +   return item_layout;
            +}
            +
            + +

            A callback function is set for the slider change event. When the user manually changes the slider value, the _slider_changed_cb() function is invoked, which in turn invokes the volume_manager_set_volume() function to change the proper sound level on the device.

            + +
            +static void
            +_slider_changed_cb(void *data, Evas_Object *obj, void *event_info)
            +{
            +   // Variable declaration
            +
            +   type = (volume_controller_type)data;
            +   value = elm_slider_value_get(obj);
            +
            +   __set_controller_value_label(s_viewdata.volume_controller[type], value);
            +   volume_manager_set_volume(type, value);
            +}
            +
            + + + + + +
            + +Go to top + + + + + + + \ No newline at end of file diff --git a/org.tizen.sampledescriptions/html/mobile_w/appcalleecaller_mw.htm b/org.tizen.sampledescriptions/html/mobile_w/appcalleecaller_mw.htm deleted file mode 100644 index e73b52d..0000000 --- a/org.tizen.sampledescriptions/html/mobile_w/appcalleecaller_mw.htm +++ /dev/null @@ -1,168 +0,0 @@ - - - - - - - - - - - - - - AppCaller and AppCallee Sample Overview - - - - -
            -
            -

            Mobile Web

            -
            - -
            -

            Related Info

            - -
            -
            - -
            -

            AppCaller and AppCallee Sample Overview

            -

            The AppCaller and AppCallee sample applications demonstrate how you can use the application control to call other applications based on the operation type.

            -

            For information on creating the sample application project in the IDE, see Creating Sample Applications.

            -

            The following figure illustrates the main screens of the AppCaller and AppCallee.

            -

            Figure: AppCaller and AppCallee screens

            -

            AppCaller and AppCallee screens

            - - -

            The AppCaller application is used to call the AppCallee application, which returns an emoji to the AppCaller:

            - -
            1. In the AppCaller, make the call by clicking Call App. -

              In the AppCallee, information about the call is displayed on the screen along with a list of emojis.

            2. -
            3. In the AppCallee, click the emoji you want to return to the AppCaller. -

              The AppCaller displays the selected emoji.

            - -

            Prerequisites

            - -
            • Since the AppCaller and AppCallee applications work best along with each other, both applications must be installed before you try to run either of them.

            - - -

            Source Files

            -

            You can create and view the sample application project including the source files in the IDE.

            - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
            File nameDescription
            appcallee/config.xmlThis file contains the application information for the platform to install and launch the application, including the operation type of the application.
            appcallee/css/style.cssThis file contains CSS styling for the application UI.
            appcallee/image/This directory contains the images used to create the user interface.
            appcallee/index.htmlThis is a starting file from which the application starts loading. It contains the layout of the application screen.
            appcallee/js/main.jsThis file contains the code for handling the main application functionalities.
            appcaller/config.xmlThis file contains the application information for the platform to install and launch the application.
            appcaller/css/style.cssThis file contains CSS styling for the application UI.
            appcaller/image/This directory contains the images used to create the user interface.
            appcaller/index.htmlThis is a starting file from which the application starts loading. It contains the layout of the application screen.
            appcaller/js/main.jsThis file contains the code for handling the main application functionalities.
            - - - - - - - - - - -
            Note
            The Emoji set used in this application was designed and offered free by Emoji One. For more information on their license terms, see the Emoji One site.
            - -

            Implementation

            - -

            In the AppCallee application, the <tizen:app-control/> element of the configuration file provides a service description for the application control. The operation name describes an action to be performed by the application.

            -
            -<tizen:app-control>
            -   <tizen:src name="index.html">
            -   <tizen:operation name="http://tizen.org/appcontrol/operation/appcall"/>
            -</tizen:app-control> 
            - -

            In the AppCaller application, the ApplicationControl interface (consisting of an operation, URI, MIME type, and data) describes an action to be performed by the Callee application. When the system gets the application control request, it finds the corresponding application to perform the requested application control and launches the selected application.

            -
            -AppControl = new tizen.ApplicationControl('http://tizen.org/appcontrol/operation/appcall',
            -                                          null, null, null);
            -
            -

            In the AppCallee application, the replyAppCaller() function replies back to the AppCaller with the data on the selected emoji:

            -
            • The application control request passed to the AppCallee can be accessed by the getRequestedAppControl() function. The passed application control contains the reason the application was launched and information about what the application is doing.
            • -
            • The ApplicationControlData interface defines the key-value pair used to pass data between applications, and it is sent to the AppCaller through the replyResult() function of the RequestedApplicationControl interface.
            -
            -function replyAppCaller(text)
            -{
            -   reqAppControl = tizen.application.getCurrentApplication().getRequestedAppControl();
            -
            -   /* Construct result data */
            -   data = new tizen.ApplicationControlData("text", [text]);
            -
            -   /* Reply to caller */
            -   reqAppControl.replyResult([data]);
            -   tizen.application.getCurrentApplication().exit();
            -}
            - - - -
            - -Go to top - - - - - - - diff --git a/org.tizen.sampledescriptions/html/mobile_w/calendar_mw.htm b/org.tizen.sampledescriptions/html/mobile_w/calendar_mw.htm index 39e0c41..aee801d 100644 --- a/org.tizen.sampledescriptions/html/mobile_w/calendar_mw.htm +++ b/org.tizen.sampledescriptions/html/mobile_w/calendar_mw.htm @@ -182,7 +182,7 @@ function getDaysMatrix(date) </div>
    -

    Navigation between Months

    +

    Navigation Between Months

    To switch between months, the user clicks the buttons in the application footer. To handle the month switching, the application registers event listeners to the navigation buttons.

    diff --git a/org.tizen.sampledescriptions/html/mobile_w/fmradio_mw.htm b/org.tizen.sampledescriptions/html/mobile_w/fmradio_mw.htm new file mode 100644 index 0000000..99acda4 --- /dev/null +++ b/org.tizen.sampledescriptions/html/mobile_w/fmradio_mw.htm @@ -0,0 +1,282 @@ + + + + + + + + + + + + + + FMRadio Sample Overview + + + + +
    +
    +

    Mobile Web

    +
    + +
    +

    Related Info

    + +
    +
    + +
    +

    FMRadio Sample Overview

    +

    The FMRadio sample application demonstrates how you can play the FM radio, scan frequencies to find stations, and manage stations and save them in the HTML local storage.

    +

    For information on creating the sample application project in the IDE, see Creating Sample Applications.

    +

    The following figure illustrates the screens of the FMRadio.

    +

    Figure: FMRadio screens

    +

    FMRadio screens

    +

    The application opens with the main screen, which shows the control panel of the radio:

    + +
    • In the circular widget, use the control buttons to change to the next or previous available station, change the current frequency ±0.1MHz, mute the radio, and scan the whole spectrum in order to find all available stations. +

      The middle of the circular widget displays the currently played radio station.

    • +
    • In the footer, use the buttons to navigate between saved stations. The middle button opens the stations screen.
    + +

    The stations screen displays all stations found after clicking Scan in the circular widget on the main screen. On this screen, you can manage the stations: remove or change the name of each station.

    + +

    Prerequisites

    +
    • Device with the FM Radio module
    + + +

    Source Files

    +

    You can create and view the sample application project including the source files in the IDE.

    + +

    The application uses a simple MVC (Model-View-Controller) architectural model.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    File nameDescription
    config.xmlThis file contains the application information for the platform to install and launch the application, including the view mode and the icon to be used in the device menu.
    css/This directory contains the CSS styling for the application UI.
    index.htmlThis is a starting file from which the application starts loading. It contains the layout of the application screens.
    js/This directory contains the application code.
    js/core/This directory contains the application framework.
    js/models/radio.jsThis file contains the methods for handling radio data.
    js/models/stations.jsThis file contains the methods for handling radio station data.
    js/views/main.jsThis file contains the methods related to the main screen UI.
    js/views/popup.jsThis file contains the methods related to popups.
    js/views/stationList.jsThis file contains the methods related to the stations screen UI.
    templates/stationsListItem.tplThis file contains the template of the station list row. The HTML content of the list is generated from this template.
    + +

    Implementation

    +

    The application can work only if the FM Radio module is supported on the device. Additionally, the external antenna has to be connected to the device in order to switch on the radio. The following functions checks whether the radio is supported and the antennal connected: +

    + +
    +/* js/app.js */
    +function isRadioSupported() 
    +{
    +   var isSupported = false;
    +
    +   try 
    +   {
    +      isSupported = tizen.systeminfo.getCapability('http://tizen.org/feature/fmradio');
    +   } 
    +   catch (error) 
    +   {
    +      console.error('No support for radio feature: ', error.message);
    +   } 
    +   finally 
    +   {
    +      return isSupported;
    +   }
    +}
    +
    +function isAntennaConnected() 
    +{
    +   return tizen.fmradio.isAntennaConnected;
    +}
    +
    + +

    When the application starts, the init() methods check the application requirements, set up all event handlers, and initialize the radio:

    + +
    +/* js/app.js */
    +function init() 
    +{
    +   if (checkRequirements()) 
    +   {
    +      main.initialize(); /* Call views/main.js init() */
    +   }
    +}
    +
    +/* js/views/main.js */
    +function init() 
    +{
    +   bindEvents(); /* Bind all events */
    +   refreshStationButtons(); /* Refresh main page UI */ 
    +   radio.initialize(); /* Initialize the radio */
    +}
    +
    + +

    After initializing, the radio is ready to be played. The following functionalities are provided:

    +
      +
    • Starting the radio: + +
      +/* js/models/radio.js */
      +function start(freq) 
      +{
      +   if (radio.state !== radioState.SCAN) 
      +   {
      +      radio.start(freq);
      +   }
      +}
      +
    • +
    • Stopping the radio: + +
      +/* js/models/radio.js */
      +function stop() 
      +{
      +   if (radio.state !== radioState.PLAY) 
      +   {
      +      radio.stop();
      +   }
      +}
      +
    • +
    • Muting the radio: + +
      +/* js/models/radio.js */
      +function setMuted(isMuted) 
      +{
      +   radio.mute = isMuted;
      +}
      +
    • +
    • Scanning the whole frequency spectrum. +

      The radio.scanStart() function takes an object containing 2 callbacks (onfrequencyfound and onfinished as the first parameter and the error callback as the second parameter. The onfrequencyfound callback is called for each found station, while the onfinished callback is called when the scanning is finished.

      + +
      +/* js/models/radio.js */
      +var scanCallback = {
      +   onfrequencyfound: function onFrequencyFound(frequency) 
      +   {
      +      /* Found a frequency */
      +   },
      +    
      +   onfinished: function onFinished(frequencies) 
      +   {
      +      /* Finished finding all frequencies */
      +   }
      +};
      +
      +function scanStart() 
      +{
      +   if (radio.state === radioState.PLAY) 
      +   {
      +      radio.stop();
      +   }
      +   radio.scanStart(scanCallback, errorCallback);
      +}
      +
    • +
    • Stopping the scan. +

      The radio.scanStop() function takes a success callback function and error callback function as parameters.

      + +
      +/* js/models/radio.js */
      +function scanStop() 
      +{
      +   if (radio.state === radioState.SCAN) 
      +   {
      +      radio.scanStop(scanStopSuccess, errorCallback);
      +   }
      +}
      +
    • +
    • Finding the nearest station with a greater or lower frequency than the currently played one: +

      Both the radio.seekUp() and radio.seekDown() functions take a success and error callback as parameters. The success callback is called with the found frequency.

      + +
      +/* js/models/radio.js */
      +
      +/* Nearest station with a greater frequency */
      +function seekUp(successCb) 
      +{
      +   if (radio.state === radioState.PLAY) 
      +   {
      +      radio.seekUp(successCb, errorCallback);
      +   }
      +}
      +
      +/* Nearest station with a lower frequency */
      +function seekDown(successCb) 
      +{
      +   if (radio.state === radioState.PLAY) 
      +   {
      +      radio.seekDown(successCb, errorCallback);
      +   }
      +}
      +
    • +
    + + + +
    + +Go to top + + + + + + + diff --git a/org.tizen.sampledescriptions/html/mobile_w/sd_mw.htm b/org.tizen.sampledescriptions/html/mobile_w/sd_mw.htm index 87a7060..6b235af 100644 --- a/org.tizen.sampledescriptions/html/mobile_w/sd_mw.htm +++ b/org.tizen.sampledescriptions/html/mobile_w/sd_mw.htm @@ -39,13 +39,6 @@ Sample name Description - - AppCaller and AppCallee - Demonstrates how you can use the application control to call other applications based on the operation type using: - - ArchiveManager Demonstrates how you can create, browse, and manage archive file using: @@ -156,7 +149,15 @@

    This sample is also explained in the tutorials: Task: File Manager.

    - + + + FMRadio + Demonstrates how you can listen to the FM radio and manage the stations using: + + + HelloTizen Demonstrates how you can receive hardware key events and display text on the screen using: @@ -208,6 +209,14 @@

    This sample is also explained in the tutorials: Task: Sensor Ball.

    + SoundManager + Demonstrates how you can manage custom sound profiles using: + + + + Systeminfo Demonstrates how you can retrieve system-related information and display it in your application using:
      @@ -219,7 +228,7 @@ TizenWinset Demonstrates how you can use Tizen Advanced UI (TAU) UI components using:

      This sample is also explained in the UI Component Reference.

      diff --git a/org.tizen.sampledescriptions/html/mobile_w/soundmanager_mw.htm b/org.tizen.sampledescriptions/html/mobile_w/soundmanager_mw.htm new file mode 100644 index 0000000..7e344b8 --- /dev/null +++ b/org.tizen.sampledescriptions/html/mobile_w/soundmanager_mw.htm @@ -0,0 +1,325 @@ + + + + + + + + + + + + + + SoundManager Sample Overview + + + + +
      +
      +

      Mobile Web

      +
      + +
      +

      Related Info

      + +
      +
      + +
      +

      SoundManager Sample Overview

      +

      The SoundManager sample application demonstrates how you can manage custom sound profiles. A sound profile is a structure consisting of a unique name and a list of volume values of all available sound types, such as ringtone, notification, and alarm.

      +

      For information on creating the sample application project in the IDE, see Creating Sample Applications.

      +

      The following figure illustrates the screens of the SoundManager.

      +

      Figure: SoundManager screens

      +

      SoundManager screens

      +

      The application opens with the main screen, which lists the created sound profiles. The profile without the Set button is currently active.

      + +

      On the main screen:

      +
      • To active a profile, click Set. +

        The system sound settings are set up with the profiles values.

      • +
      • To add a new profile, click + in the top left corner. +

        The new profile is initialized with the current system sound settings and you can specify its name.

      • +
      • To modify an existing profile, click it in the list. +

        The profile details screen opens:

        +
        • To change the values of various sound types, use the sliders. When an active profile is changed, the changes are applied directly to the system settings.
        • +
        • To restore the profile values to the state when the screen opened, click Reset.
        • +
        • To delete the profile, click Delete.
      + + +

      Source Files

      +

      You can create and view the sample application project including the source files in the IDE.

      + +

      The application uses a simple MVC (Model-View-Controller) architectural model.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      File nameDescription
      config.xmlThis file contains the application information for the platform to install and launch the application, including the view mode and the icon to be used in the device menu.
      css/This directory contains the CSS styling for the application UI.
      index.htmlThis is a starting file from which the application starts loading. It contains the layout of the application screens.
      js/This directory contains the application code.
      js/core/This directory contains the application framework.
      js/models/This directory contains the application model modules.
      js/views/This directory contains the implementation code for the application views.
      templates/This directory contains the templates of the list items.
      + +

      Implementation

      +

      To implement the main module managing custom sound profiles:

      + +
      1. Define variables: +
        • currentProfileId: Object containing the current profile values
        • +
        • profiles: Array of all profiles
        • +
        • SOUND_TYPES: Array containing all available sound types
        • +
        • activeProfileId: ID of the active profile or null if there is no active profile
        + +
        +var currentProfile = {},
        +    profiles = [],
        +    SOUND_TYPES = 
        +    [
        +       'SYSTEM',
        +       'NOTIFICATION',
        +       'ALARM',
        +       'MEDIA',
        +       'VOICE',
        +       'RINGTONE'
        +    ],
        +    activeProfileId = null;
        +
        + +

        The sound profile is represented by an object with the following fields:

        +
        • id: Unique identifier of the profile
        • +
        • title: Title of the profile
        • +
        • XXX: Value of the XXX sound type, where XXX is a SOUND_TYPES value
        • +
        + +
        +{
        +   id: 1313,
        +   title: 'Custom Profile',
        +   SYSTEM: 0.1,
        +   NOTIFICATION: 0.2,
        +   ALARM: 0.3,
        +   MEDIA: 0.5,
        +   VOICE: 0,
        +   RINGTONE: 1
        +}
        +
      2. +
      3. +

        Initialize the application by first loading the current system profile and storing it in the currentProfile object. Next, register a changing volume listener that updates the currentProfile object and clears the activeProfileId variable (volume is changed so the current system profile is different than the active profile; therefore, the active profile stops being active). +

        + +
        +function init() 
        +{
        +   var i = 0,
        +       soundType = null;
        +
        +   for (i = 0; i < SOUND_TYPES.length; i += 1) 
        +   {
        +      soundType = SOUND_TYPES[i];
        +      try 
        +      {
        +         currentProfile[soundType] = tizen.sound.getVolume(soundType);
        +      } 
        +      catch (e) 
        +      {
        +         console.error(e.message);
        +      }
        +   }
        +
        +   try 
        +   {
        +      tizen.sound.setVolumeChangeListener(onVolumeChanged);
        +   } 
        +   catch (e) 
        +   {
        +      console.error(e.message);
        +   }
        +}
        +
        +function onVolumeChanged(soundType, volume) 
        +{
        +   if (currentProfile[soundType] !== volume) 
        +   {
        +      currentProfile[soundType] = volume;
        +      if (activeProfileId !== null) 
        +      {
        +         activeProfileId = null;
        +      }
        +   }
        +}
        +
      4. +
      5. +

        Define the setActive() method that sets a profile active:

        + +
        +function setActive(id) 
        +{
        +   if (activeProfileId !== id) 
        +   {
        +      changeSystemProfile(getProfile(id));
        +      activeProfileId = id;
        +   }
        +}
        +
        +function getProfile(id) 
        +{
        +   var i = 0,
        +       profile = null;
        +
        +   for (i = 0; i < profiles.length; i += 1) 
        +   {
        +      profile = profiles[i];
        +      if (profile.id === id) 
        +      {
        +         return profile;
        +      }
        +   }
        +
        +   return null;
        +}
        +
        + +

        The changeSystemProfile() method changes the system profile values to values from the specified profile:

        +
        +function changeSystemProfile(profile) 
        +{
        +   var i = 0,
        +       soundType = null;
        +
        +   for (i = 0; i < SOUND_TYPES.length; i += 1) 
        +   {
        +      soundType = SOUND_TYPES[i];
        +      changeSystemSoundVolume(soundType, profile[soundType]);
        +   }
        +}
        +
        +function changeSystemSoundVolume(soundType, volume) 
        +{
        +   try 
        +   {
        +      currentProfile[soundType] = volume;
        +      tizen.sound.setVolume(soundType, volume);
        +   } 
        +   catch (e) 
        +   {
        +      console.error('Setting ' + soundType + ' error: ' + e.message);
        +   }
        +}
        +
      6. +
      7. +

        Define the createProfile() method that creates a new profile with values from the system settings. The method obtains the title of the created profile. The following code takes advantage of the fact that sound settings are contained in the currentProfile object.

        + +
        +function createProfile(title) 
        +{
        +   var currentProfileCopy = JSON.parse(JSON.stringify(currentProfile)),
        +       id = profiles.length ? profiles[profiles.length - 1].id + 1 : 0;
        +   currentProfileCopy.title = title;
        +   currentProfileCopy.id = id;
        +   profiles.push(currentProfileCopy);
        +}
        +
      8. +
      9. Define the updateProfile() method to update the specified profile. In this method, you can use the functions defined in the previous steps. +

        The method obtains the ID of the profile that you want to change, the name of the sound type, and the new value.

        + +
        +function updateProfile(profileId, soundType, volume) 
        +{
        +   var profile = getProfile(profileId);
        +
        +   if (profile) 
        +   {
        +      profile[soundType] = volume;
        +      if (profile.id === activeProfileId) 
        +      {
        +         changeSystemSoundVolume(soundType, volume);
        +      }
        +   }
        +}
        +
      10. +
      11. Define the deleteProfile() method that deletes the profile with the specified ID. + +
        +function deleteProfile(id) 
        +{
        +   var index = getProfileIndex(id);
        +   if (index !== -1) 
        +   {
        +      profiles.splice(index, 1);
        +   }
        +}
        +
        +function getProfileIndex(profileId) 
        +{
        +   var i = 0;
        +
        +   for (i = 0; i < profiles.length; i += 1) 
        +   {
        +      if (profiles[i].id === profileId) 
        +      {
        +         return i;
        +      }
        +   }
        +
        +   return -1;
        +}
        +
      + + + +
      + +Go to top + + + + + + + diff --git a/org.tizen.sampledescriptions/html/mobile_w/winset_mw.htm b/org.tizen.sampledescriptions/html/mobile_w/winset_mw.htm index f58a3ba..327f8f3 100644 --- a/org.tizen.sampledescriptions/html/mobile_w/winset_mw.htm +++ b/org.tizen.sampledescriptions/html/mobile_w/winset_mw.htm @@ -24,8 +24,8 @@ diff --git a/org.tizen.sampledescriptions/html/scripts/common.js b/org.tizen.sampledescriptions/html/scripts/common.js index 60250b6..d46479a 100644 --- a/org.tizen.sampledescriptions/html/scripts/common.js +++ b/org.tizen.sampledescriptions/html/scripts/common.js @@ -1,1752 +1,1752 @@ -$(document).ready(function(){ - $('#contents table').each(function(){ - if (!$(this).parent().hasClass('table')) { - $(this).wrap('
      '); - } - }); - - // Lnb Menu Initialize - if($('div#contents').find('.lnb').length){ - if($("ul li.events_news").size() > 0) { - $("ul.lnb").after("

      \"Samsung

      "); - } - initLnb(); - initScript(staticURL + "/js/fixednavbar.js", function(){}); - } - - //family site - if($('div#footer').find('dl#familySlider').length){ - fn_rollToEx('familySlider', 'sliderBanner', 1, true); - } - - // Svn Commit Test - - // Language Selection - if($('div#header').find('.util').length){ - var $lang = $('div#header').find('.util'); - $lang.find('a.lang').toggle(function(){ - $(this).css('background-image', $(this).css('background-image').replace('.gif','_.gif')).next('ul.language').show(); - },function(){ - $(this).css('background-image', $(this).css('background-image').replace('_.gif','.gif')).next('ul.language').hide(); - }); - - $lang.bind('mouseleave',function(){ - $(this).find('ul.language').hide(); - $lang.find('a.lang').css('background-image', $lang.find('a.lang').css('background-image').replace('_.gif','.gif')); - }); - - $lang.find('ul.language').children().last().on("keydown", function(e) { - if(e.which == 9 && e.shiftKey) { - return true; - } - - if(e.which == 9) { - e.preventDefault(); - $lang.find('ul.language').hide(); - $lang.find('a.lang').css('background-image', $lang.find('a.lang').css('background-image').replace('_.gif','.gif')); - setTimeout(function() { - $("#searchTop").focus(); - }, 1); - } - }); - } - - // Open the Sitemap - var $open = $('div#header').find('.bt-open'); - $open.bind('click',function(){ - var $self = $(this); - var $sitemap = $('div#wrapper').find('div#sitemap'); - //var source = $sitemap.is(':visible') ? $self.css('background-image').replace('_.gif','.gif') : $self.css('background-image').replace('.gif','_.gif'); - - if($sitemap.is(':visible')){ - var source = $self.css('background-image').replace('_.gif','.gif'); - //if($('body#main').length) $('#header .util').css('border-bottom','3px solid #e4e4e4'); - - $self.attr('title','open sitemap'); - }else{ - var source = $self.css('background-image').replace('.gif','_.gif'); - //if($('body#main').length) $('#header .util').css('border-bottom','3px solid #114196'); - - $self.attr('title','close sitemap'); - } - - $self.css('background-image',source); - $sitemap.slideToggle('fast'); - - $sitemap.find('ul').filter(':last').children().filter(':last').focusout(function(){ - var source = $self.css('background-image').replace('_.gif','.gif'); - $self.css('background-image',source); - $sitemap.slideToggle('fast'); - }); - - }); - - // Search Auto Complete - var $search = $('div#header').find('fieldset.search'); - var $searchList = $search.find('#topAutocomplete>ul'); - - if($search.length){ - $search.find('> input').each(function(){ - $(this).bind({ - keydown : function(e){ - - if(e.type=='keydown'&& $(this).val().length!=0){ - $search.find('#topAutocomplete').show(); - var hei = $searchList.outerHeight(); - if(hei>400){ - $searchList.css({'height':'400px','overflow-y':'auto'}); - } - } - if(e.keyCode==9){ - $search.unbind('focusout.search'); - } - if(e.keyCode==40){ - $search.find('#topAutocomplete>ul').children(':first').find('a').focus(); - //window.scrollTo(0,0); - } - }, - focusin : function(e){ - if($(this).val()==='Search'){ - $(this).val(''); - } - }, - focusout : function(e){ - if($(this).val().length==0) $(this).val('Search'); - } - }); - }); - - //$('#topAutocomplete>ul').children().find('a').bind('focusin',function(e){ - // if(e.keyCode==40){ - // $(this).parent().next().css('border','1px solid red').find('a').focus(); - // } - //}); - - $search.find('#topAutocomplete').bind('mouseleave',function(e){ - if($search.find('> input').val().length==0){ - $search.find('> input').val('Search'); - } - $search.find('#topAutocomplete').hide(); - }); - - $search.find('#topAutocomplete>ul').children().last().focusout(function(){ - $search.find('> input').val('Search'); - $search.find('#topAutocomplete').hide(); - - //$search.bind('focusout.search', function(){ - // $(this).find('> input').val('Search'); - // $(this).find('#topAutocomplete').hide(); - //}); - }); - } -}); - -// 비차단 동적 스크립트 로딩 -function initScript(url, callback){ - var script = document.createElement("script"); - script.type = "text/javascript"; - - if(script.readyState){ // 인터넷 익스플로러 - script.onreadystatechange = function(){ - if(script.readyState=="loaded" || script.readyState=="complete"){ - script.onreadystatechange = null; - callback(); - } - }; - }else{ // 다른 브라우저 - script.onload = function(){ - callback(); - }; - } - - script.src = url; - document.getElementsByTagName("head")[0].appendChild(script); -} - - -// lnb -function initLnb(){ - var sMenu = $('.lnb'); - var sItem = sMenu.find('>li'); - - sItem.each(function(){ - if($(this).find('a').hasClass('more')){ - if($(this).find('ul').is(":visible")) { - $('').insertAfter($(this).find('a').eq(0)); - } else { - $('').insertAfter($(this).find('a').eq(0)); - } - } - }); - - var setIcoArrText = function(obj) { - if(obj.next().is(":visible")) { - obj.text("close submenu"); - } else { - obj.text("open submenu"); - } - } - - sItem.find('.ico-arr').on("click", function() { - var $that = $(this); - var liBox = $that.parent(); - var ulBox = $that.next(); - - sItem.not(liBox).not(".on").find("a.more").next().next().hide(); - sItem.not(liBox).removeClass("active").find("a").removeClass("bov"); - - if(liBox.hasClass("on")) { - if(ulBox.is(":visible")) { - ulBox.hide(); - $that.addClass("ico-on"); - } else { - ulBox.show(); - $that.removeClass("ico-on"); - } - setIcoArrText($that); - return true; - } - - if(liBox.hasClass("active")) { - liBox.removeClass("active").find("a").eq(0).removeClass("bov"); - ulBox.hide(); - } else { - liBox.addClass("active").find("a").eq(0).addClass("bov"); - ulBox.show(); - } - setIcoArrText($that); - }); - - sItem.hover(function(){ - if($(this).hasClass('on')||$(this).hasClass('active')) return false; - $(this).find("a").eq(0).addClass("bov"); - },function(){ - if($(this).hasClass('on')||$(this).hasClass('active')) return false; - $(this).find("a").eq(0).removeClass("bov"); - - }); -} - -//footer rolling banner -function fn_rollToEx(container,objectId,step,auto){ - - // 롤링할 객체를 변수에 담아둔다. - var el = $('#'+container).find('#'+objectId); - var lastChild; - var speed = 3000; - var timer = 0; - var autoplay = false; - - el.data('prev', $('#'+container).find('.prev')); //이전버튼을 data()메서드를 사용하여 저장한다. - el.data('next', $('#'+container).find('.next')); //다음버튼을 data()메서드를 사용하여 저장한다. - el.data('size', el.children().outerWidth()); //롤링객체의 자식요소의 넓이를 저장한다. - el.data('len', el.children().length); //롤링객체의 전체요소 개수 - el.data('animating',false); - el.data('step', step); //매개변수로 받은 step을 저장한다. - el.data('autoStart', false); //매개변수로 받은 step을 저장한다. - - el.css('width',el.data('size')*el.data('len')); //롤링객체의 전체넓이 지정한다. - - if(arguments.length==4){ - el.data('autoStart', auto); - } - - if(el.data('autoStart')){ - if(timer==0){ - timer = setInterval(moveNextSlide, speed); - autoplay = true; - } - } - - el.bind({ - mouseenter:function(){ - if(!autoplay) return false; - - if(timer!=0 && el.data('autoStart')){ - clearInterval(timer); - timer=0; - } - }, - mouseleave:function(){ - if(!autoplay) return false; - - if(timer==0 && el.data('autoStart')){ - timer = setInterval(moveNextSlide, speed); - } - } - }); - - - //el에 첨부된 prev 데이타를 클릭이벤트에 바인드한다. - el.data('prev').bind({ - click:function(e){ - e.preventDefault(); - movePrevSlide(); - }, - mouseenter:function(){ - - $(this).find('img').addClass('btnOn'); - - if(!autoplay) return false; - - if(timer!=0 && el.data('autoStart')){ - clearInterval(timer); - timer=0; - } - }, - mouseleave:function(){ - - $(this).find('img').removeClass('btnOn'); - - if(!autoplay) return false; - - if(timer==0 && el.data('autoStart')){ - timer = setInterval(moveNextSlide, speed); - } - } - }); - - //el에 첨부된 next 데이타를 클릭이벤트에 바인드한다. - el.data('next').bind({ - click:function(e){ - e.preventDefault(); - moveNextSlide(); - }, - mouseenter:function(){ - - $(this).find('img').addClass('btnOn'); - - if(!autoplay) return false; - - if(timer!=0 && el.data('autoStart')){ - clearInterval(timer); - timer=0; - } - }, - mouseleave:function(){ - - $(this).find('img').removeClass('btnOn'); - - if(!autoplay) return false; - - if(timer==0 && el.data('autoStart')){ - timer = setInterval(moveNextSlide, speed); - } - } - }); - - function movePrevSlide(){ - if(!el.data('animating')){ - //전달된 step개수 만큼 롤링객체의 끝에서 요소를 선택하여 복사한후 변수에 저장한다. - var lastItem = el.children().eq(-(el.data('step')+1)).nextAll().clone(true); - lastItem.prependTo(el); //복사된 요소를 롤링객체의 앞에 붙여놓는다. - el.children().eq(-(el.data('step')+1)).nextAll().remove(); //step개수만큼 선택된 요소를 끝에서 제거한다 - el.css('left','-'+(el.data('size')*el.data('step'))+'px'); //롤링객체의 left위치값을 재설정한다. - - el.data('animating',true); //애니메이션 중복을 막기 위해 첨부된 animating 데이타를 true로 설정한다. - - el.animate({'left': '0px'},'normal',function(){ //롤링객체를 left:0만큼 애니메이션 시킨다. - el.data('animating',false); - }); - } - return false; - } - - function moveNextSlide(){ - if(!el.data('animating')){ - el.data('animating',true); - - el.animate({'left':'-'+(el.data('size')*el.data('step'))+'px'},'normal',function(){ //롤링객체를 첨부된 size와 step을 곱한 만큼 애니메이션 시킨다. - //전달된 step개수 만큼 롤링객체의 앞에서 요소를 선택하여 복사한후 변수에 저장한다. - var firstChild = el.children().filter(':lt('+el.data('step')+')').clone(true); - firstChild.appendTo(el); //복사된 요소를 롤링객체의 끝에 붙여놓는다. - el.children().filter(':lt('+el.data('step')+')').remove(); //step개수만큼 선택된 요소를 앞에서 제거한다 - el.css('left','0px'); ////롤링객체의 left위치값을 재설정한다. - - el.data('animating',false); - }); - } - return false; - } - -} - -function fn_slide(options){ - - var opts = jQuery.extend({},options); - - var $bt = $('#'+opts.container).find('#'+opts.bt).children(); //롤링버튼에 대한 선택자 - var $obj = $('#'+opts.container).find('#'+opts.obj); //objectId를 id로 갖는 롤링객체의 선택자 - var $prev = $('#'+opts.container).find('#'+opts.prev).hide(); //이전버튼에 대한 선택자 - var $next = $('#'+opts.container).find('#'+opts.next); //다음버튼에 대한 선택자 - var size = $obj.children().outerWidth(); //롤링객체의 각 이미지 넓이값 - var len = $obj.children().length; //롤링객체의 이미지 갯수 - var effect = false; //슬라이드효과를 위한 boolean변수 - var auto = false; - var current = 0; //현재 보여지는 이미지의 인덱스값을 저장하기 위한 변수 - var time; - - - $obj.css('width',size*len); //롤링객체의 전체넓이 지정 - effect = opts.effect; - auto = opts.auto; - - if(auto){ - time = setTimeout('slideShow()',3000); - } - - slideShow = function(){ - - if(current < len-1){ - current++; - }else{ - current=0; - } - - controllStatus(); - - moveControl('next'); - - time = setTimeout('slideShow()',3000); - } - - controllStatus = function(){ - //이미지의 인덱스값에 따라 이전,다음 버튼 활성여부 지정 - if(current>0||current=len-1){ - $prev.show(); - $next.hide(); - } - } - - moveControl = function(msg){ - if(opts.bt!=null){ - msg=='next'? $bt.eq(current-1).find('img').attr('src', $bt.eq(current-1).find('img').attr('src').replace('_.png','.png')) - :$bt.eq(current+1).find('img').attr('src', $bt.eq(current-1).find('img').attr('src').replace('_.png','.png')); //이전에 활성화된 롤링버튼을 비활성화 - $bt.eq(current).find('img').attr('src', $bt.eq(current).find('img').attr('src').replace('.png','_.png')); //현재 인덱스값을 가지는 롤링버튼을 활성화 - } - - if(effect!=true){ //action변수가 true가 아닐경우 슬라이드 효과없이 현재의 인덱스값을 갖는 이미지를 보여줌. - $obj.children().hide(); - $obj.children().eq(current).show(); - }else{ //action변수가 true일 경우 현재의 인덱스값을 갖는 이미지로 슬라이드됨 - $obj.animate({'left':'-'+size*current},'slow'); - } - } - - $obj.bind({ - mouseenter:function(){ - if(!auto) return false; - clearTimeout(time); - }, - mouseleave:function(){ - if(!auto) return false; - time = setTimeout('slideShow()',3000); - } - }); - - //롤링 버튼 클릭시 - $bt.bind({ - mouseenter:function(){ - if(!auto) return false; - clearTimeout(time); - }, - mouseleave:function(){ - if(!auto) return false; - time = setTimeout('slideShow()',3000); - }, - click:function(){ - var idx = $bt.index(this); //클릭한 롤링버튼의 인덱스값 저장 - - current = idx; //롤링버튼의 인덱스값을 이미지의 인덱스값으로 지정 - - controllStatus(); - - if(effect!=true){ //action변수가 true가 아닐경우 슬라이드 효과없이 현재의 인덱스값을 갖는 이미지를 보여줌. - $obj.children().hide(); - $obj.children().eq(current).show(); - }else{ //action변수가 true일 경우 현재의 인덱스값을 갖는 이미지로 슬라이드됨 - $obj.animate({'left':'-'+size*current},'slow'); - } - - // 모든 롤링 버튼을 비활성화 - $bt.each(function(){ - var source = $(this).find('img').attr('src').replace('_.png','.png'); - $(this).find('img').attr('src',source); - }); - - // 선택한 롤링버튼을 활성화 - var source = $(this).find('img').attr('src').replace('.png','_.png'); - $(this).find('img').attr('src',source); - - return false; - } - }); - - //이전 버튼 클릭시 - $prev.bind({ - mouseenter:function(){ - var source = $(this).find('img').attr('src').replace('.png','_.png'); - $(this).find('img').attr('src',source); - if(!auto) return false; - clearTimeout(time); - }, - mouseleave:function(){ - var source = $(this).find('img').attr('src').replace('_.png','.png'); - $(this).find('img').attr('src',source); - if(!auto) return false; - time = setTimeout('slideShow()',3000); - }, - click:function(){ - if(current==len-1) $next.show(); //이미지 인덱스값이 마지막이 아닐경우 비활성화된 다음버튼을 활성화 - current--; //이미지 인덱스값 1씩 감소 - - moveControl('prev'); - - if(current==0) $(this).hide(); //이미지 인덱스값이 0일 경우, 즉 현재 첫번째 이미지가 활성화될 경우 이전버튼을 비활성화 - - return false; - } - }); - - //다음 버튼 클릭시 - $next.bind({ - mouseenter:function(){ - var source = $(this).find('img').attr('src').replace('.png','_.png'); - $(this).find('img').attr('src',source); - if(!auto) return false; - clearTimeout(time); - }, - mouseleave:function(){ - var source = $(this).find('img').attr('src').replace('_.png','.png'); - $(this).find('img').attr('src',source); - if(!auto) return false; - time = setTimeout('slideShow()',3000); - }, - click:function(){ - current++; //이미지 인덱스값 1씩 증가 - - moveControl('next'); - - if(current>=len-1) $(this).hide(); //이미지인덱스값이 마지막일 경우, 즉 현재 마지막 이미지가 활성화될 경우 다음버튼을 비활성화 - if(current>0) $prev.show(); //이미지인덱스값이 0이 아닌경우 이전버튼 활성화 - - return false; - } - }); - -} - -// main rolling banner -function slideMotion1(){ - var $banner = $('#rolling .motionview'), - //$nav = $('#rolling ul.nav'), - banner = {prev:null, next:null}, - size = $banner.children().length; - index = 1, - speed = 3000, - timer = null, - auto = true, - width = parseInt(100/size), - rest = parseInt(100%size); - - var $nav = $('
    • W3C/HTML5/Supplementary Features -

      The following tutorials apply in mobile applications only:

      +

      The following tutorials apply in mobile applications only:

      -

      The following tutorials apply in wearable applications only:

      +

      The following tutorials apply in wearable applications only:

      diff --git a/org.tizen.tutorials/html/native/app_framework/package_tutorial_n.htm b/org.tizen.tutorials/html/native/app_framework/package_tutorial_n.htm old mode 100755 new mode 100644 index 7f96c38..fd5d066 --- a/org.tizen.tutorials/html/native/app_framework/package_tutorial_n.htm +++ b/org.tizen.tutorials/html/native/app_framework/package_tutorial_n.htm @@ -29,7 +29,7 @@

    Related Info

    @@ -41,7 +41,7 @@

    Package Manager: Installing and Uninstalling Applications

    -

    This tutorial demonstrates how you can manage installed packages with its information.

    +

    This tutorial demonstrates how you can manage installed packages and their information.

    Warm-up

    Become familiar with the Package Manager API basics by learning about:

    @@ -64,11 +64,14 @@
     #include <package_manager.h>
     
    -
  • The http://tizen.org/privilege/packagemanager.info privilege is required to get package information.

    -

    Add this privilege to the tizen-manifest.xml file.

  • -
  • Prepare callback function package_info_cb which will be invoked for each package information retrieved
  • + +
  • Add the http://tizen.org/privilege/packagemanager.info privilege to the tizen-manifest.xml file to get package information.

    +
  • +
  • Prepare the package_info_cb() callback function, which is invoked for each retrieved package information: +
    -void package_info_cb(package_info_h package_info, void *user_data)
    +void 
    +package_info_cb(package_info_h package_info, void *user_data)
     {
        int ret;
     
    @@ -108,26 +111,12 @@ void package_info_cb(package_info_h package_info, void *user_data)
        free(version);
        free(type);
     }
    -
    -
  • Use the - package_manager_foreach_package_info() function: This function will retrieve all package information and invoke callback for each information retrieved - -
    -package_manager_foreach_package_info(package_manager_package_info_cb callback, void *user_data)
    -
    - -

    The function takes the following parameters:

    -
      -
    • [in] callback: Callback function to be invoked for each package information retrieved
    • -
    • [in] user_data: User data to be passed to the callback function
    • -
    • [out] 0 on success, otherwise a negative error value
    • -
  • - -
  • Call package_manager_foreach_package_info with passing callback and userdata

    +
  • +
  • Use the package_manager_foreach_package_info() function to retrieve all package information and invoke the callback for each retrieved information. +

    The function takes as parameters the callback function, and user data to be passed to the callback function. The function returns 0 on success, otherwise a negative error value.

    -<<<<<<< Updated upstream
     ret = package_manager_foreach_package_info(package_info_cb, NULL);
     if (ret != PACKAGE_MANAGER_ERROR_NONE) 
     {
    @@ -145,21 +134,25 @@ if (ret != PACKAGE_MANAGER_ERROR_NONE)
     
     #include <package_manager.h>
     
  • -
  • The http://tizen.org/privilege/packagemanager.info privilege is required for this Package Manager API.

    -

    Add the privilege to the tizen-manifest.xml file.

  • -
  • Use the - package_manager_get_package_info() function: -
    -int package_manager_get_package_info(const char *package_id, package_info_h *package_info)
    -
    -

    The function takes the following parameters:

    -
      -
    • [in] package_id: ID of the package
    • -
    • [in] package_info: Package information for the given package ID.
    • -
    • [out] 0 on success, otherwise a negative error value
    • -
  • - -
  • After getting package_info_h handle, use package_info_get_ functions to retrieve specific information + +
  • Add the http://tizen.org/privilege/packagemanager.info privilege to the tizen-manifest.xml file to get package information.

    +
  • +
  • Use the package_manager_get_package_info() function. +

    The function takes as parameters the package ID and the package information handle for the specific package ID. The function returns 0 on success, otherwise a negative error value.

    + +

    After getting the package_info_h handle, use any of the following package_info_get_*() functions to retrieve the specific information:

    +
    • package_info_get_label()
    • +
    • package_info_get_icon()
    • +
    • package_info_get_version()
    • +
    • package_info_get_type()
    • +
    • package_info_get_installed_storage()
    • +
    • package_info_get_root_path()
    • +
    • package_info_is_system_package()
    • +
    • package_info_is_removable_package()
    • +
    • package_info_is_preload_package()
    • +
    • package_info_is_accessible()
    • +
    +
     char *version = NULL;
     char *label = NULL;
    @@ -167,40 +160,27 @@ char *type = NULL;
     package_info_h package_info = NULL;
     package_manager_get_package_info("PACKAGE-ID", &package_info);
     
    -package_info_get_version(package_info, &version);
    -package_info_get_label(package_info, &label);
    -package_info_get_type(package_info, &type);
    +package_info_get_version(package_info, &version);
    +package_info_get_label(package_info, &label);
    +package_info_get_type(package_info, &type);
     
    -dlog_print(DLOG_INFO, TAG, "label \t= [%s]\n", label);
    -dlog_print(DLOG_INFO, TAG, "icon \t= [%s]\n", icon);
    -dlog_print(DLOG_INFO, TAG, "version \t= [%s]\n", version);
    +dlog_print(DLOG_INFO, TAG, "label \t= [%s]\n", label);
    +dlog_print(DLOG_INFO, TAG, "icon \t= [%s]\n", icon);
    +dlog_print(DLOG_INFO, TAG, "version \t= [%s]\n", version);
     
     free(label);
     free(icon);
     free(version);
     
     // Use package information
    -package_info_destroy(package_info);
     
    - -
  • -
  • You can get package information with functions listed below: -
    -package_info_get_label(package_info_h package_info, char **label)
    -package_info_get_icon(package_info_h package_info, char **path)
    -package_info_get_version(package_info_h package_info, char **version)
    -package_info_get_type(package_info_h package_info, char **type)
    -package_info_get_installed_storage(package_info_h package_info, package_info_installed_storage_type_e *storage)
    -package_info_get_root_path(package_info_h package_info, char **path)
    -package_info_is_system_package(package_info_h package_info, bool *system)
    -package_info_is_removable_package(package_info_h package_info, bool *removable)
    -package_info_is_preload_package(package_info_h package_info, bool *preload)
    -package_info_is_accessible(package_info_h package_info, bool *accessible)
  • -
  • Package Manager handle shoule be released with package_info_destroy function.
  • +
  • When no longer needed, release the package information handle with the package_info_destroy() function: +
    +package_info_destroy(package_info);
    +
  • -

    Listening to Package Events

    To detect package events, such as installation, uninstallation, and updates:

    @@ -210,54 +190,45 @@ package_info_is_accessible(package_info_h package_info, bool *accessible)
     #include <package_manager.h>
     
    -
  • The http://tizen.org/privilege/packagemanager.info privilege is required for this Package Manager API.

    -

    Add privilege to the tizen-manifest.xml file.

  • + +
  • Add the http://tizen.org/privilege/packagemanager.info privilege to the tizen-manifest.xml file to get package information.

    +
  • -

    Create the package manager (package_manager_h) using the package_manager_create() function:

    +

    Create the package manager (package_manager_h) using the package_manager_create() function.

    +

    The function takes the package manager handle (newly created on success) as a parameter. The function returns 0 on success, otherwise a negative error value.

    -package_manager_create(package_manager_h * manager)
    -
    package_manager_h manager;
    -package_manager_create(&manager);
    +package_manager_create(package_manager_h *manager) + + +
  • + +
  • Set the package event which you want to listen to by invoking the package_manager_set_event_status() function. +

    The function takes as parameters the package manager handle and the status of the package. The function returns 0 on success, otherwise a negative error value.

    -

    The function takes the following parameters:

    -
      -
    • [in] manager: Package manager handle that is newly created on success
    • -
    • [out] 0 on success, otherwise a negative error value
    • +

      The package status can be one of the following event types you want to listen for:

      +
      • PACKAGE_MANAGER_STATUS_TYPE_ALL: All statuses
      • +
      • PACKAGE_MANAGER_STATUS_TYPE_INSTALL: Install package status
      • +
      • PACKAGE_MANAGER_STATUS_TYPE_UNINSTALL: Uninstall package status
      • +
      • PACKAGE_MANAGER_STATUS_TYPE_UPGRADE: Upgrade package status
      • +
      • PACKAGE_MANAGER_STATUS_TYPE_MOVE: Move package status
      • +
      • PACKAGE_MANAGER_STATUS_TYPE_CLEAR_DATA: Clear data status
      • +
      • PACKAGE_MANAGER_STATUS_TYPE_INSTALL_PROGRESS: Install progress status
      • +
      • PACKAGE_MANAGER_STATUS_TYPE_GET_SIZE: Get size status
      - -
    • - -

      Set the package event which you want to listen by invoking package_manager_set_event_status:

      -
      package_manager_set_event_status(package_manager_h manager, int status_type)
      package_manager_set_event_status(manager, PACKAGE_MANAGER_STATUS_TYPE_ALL);
      -

      The function takes the following parameters:

      -
        -
      • [in] manager: Package manager handle
      • -
      • [in] status_type: Status of the package
        - There are several event types want to listen -
        -PACKAGE_MANAGER_STATUS_TYPE_ALL : All status
        -PACKAGE_MANAGER_STATUS_TYPE_INSTALL :  Install package status
        -PACKAGE_MANAGER_STATUS_TYPE_UNINSTALL : Uninstall package status
        -PACKAGE_MANAGER_STATUS_TYPE_UPGRADE : Upgrade package status
        -PACKAGE_MANAGER_STATUS_TYPE_MOVE : Move package status
        -PACKAGE_MANAGER_STATUS_TYPE_CLEAR_DATA : Clear data status
        -PACKAGE_MANAGER_STATUS_TYPE_INSTALL_PROGRESS : Install progress status
        -PACKAGE_MANAGER_STATUS_TYPE_GET_SIZE : Get size status
        -
      • -
      • [out] 0 on success, otherwise a negative error value
      • -
    • -
    • -

      Implement the package manager event callback:

      +
    • Implement the package manager event callback: -
      void event_cb(const char *type, const char *package, package_manager_event_type_e event_type, package_manager_event_state_e event_state, int progress, package_manager_error_e error, void *user_data)
      +
      void 
      +event_cb(const char *type, const char *package, package_manager_event_type_e event_type, 
      +         package_manager_event_state_e event_state, int progress, 
      +         package_manager_error_e error, void *user_data)
       {
          if (event_state == PACKAGE_MANAGER_EVENT_STATE_STARTED)
          {
      @@ -279,27 +250,14 @@ PACKAGE_MANAGER_STATUS_TYPE_GET_SIZE : Get size status
       
       
    • -
    • -

      Register a callback function to be invoked when the event you registered has happened:

      -
      -int package_manager_set_event_cb(package_manager_h manager, package_manager_event_cb callback, void *user_data)
      +
    • Register a callback function to be invoked when the event you registered has happened. +

      The function takes as parameters the package manager handle, the callback function, and the user data to be passed to the callback function. The function returns 0 on success, otherwise a negative error value.

       package_manager_set_event_cb(manager, event_cb, NULL);
       
      - -

      The function takes the following parameters:

      -
        -
      • [in] manager: Package manager handle
      • -
      • [in] callback: Callback function to be registered
      • -
      • [in] user_data: User data to be passed to the callback function
      • -
      • [out] 0 on success, otherwise a negative error value
      • -
    • -
    • -

      Free the package manager:

      - - +
    • Free the package manager:
      package_manager_destroy(package_manager_h manager);
    • diff --git a/org.tizen.tutorials/html/native/app_framework/widget_tutorial_n.htm b/org.tizen.tutorials/html/native/app_framework/widget_tutorial_n.htm index 2209aae..1d2ed1f 100644 --- a/org.tizen.tutorials/html/native/app_framework/widget_tutorial_n.htm +++ b/org.tizen.tutorials/html/native/app_framework/widget_tutorial_n.htm @@ -11,7 +11,7 @@ - Widget: Creating Widget Applications + Widget Application: Creating Widget Applications @@ -31,23 +31,23 @@

    Related Info

    -

    Widget: Creating Widget Applications

    +

    Widget Application: Creating Widget Applications

    This tutorial demonstrates how you can create a widget application.

    Warm-up

    -

    Become familiar with the Watch Application API basics by learning about:

    +

    Become familiar with the Widget Application API basics by learning about:

    • Initializing the Widget Application

      Initialize a widget application for use.

    • @@ -66,7 +66,7 @@

      To initialize the widget application:

        -
      1. To use the functions and data types of the Widget API (in mobile and wearable applications), include the <widget_app.h> header file in your application: +
      2. To use the functions and data types of the Widget Application API (in mobile and wearable applications), include the <widget_app.h> header file in your application:
         #include <widget_app.h>
         
      3. @@ -125,7 +125,7 @@ widget_class_h widget_app_create (void *user_data)    widget_app_add_event_handler(&handlers[APP_EVENT_REGION_FORMAT_CHANGED],                                 APP_EVENT_REGION_FORMAT_CHANGED, widget_app_region_changed, NULL); -   return widget_app_class_create(obj_callback); +   return widget_app_class_create(obj_callback, user_data); }

        When the system-related callback are no longer needed, remove them with the widget_app_remove_event_handler() function.

        @@ -182,7 +182,7 @@ widget_app_terminate(void *user_data)
      4. This callback is triggered when the widget instance is created.

        Initialize resources for this widget instance and draw the UI. If bundle content is not NULL, restore the previous status.

        -int widget_instance_create(widget_context_h context, bundle *content, int w, int h)
        +int widget_instance_create(widget_context_h context, bundle *content, int w, int h, void *user_data)
         {
            widget_instance_data_s *wid = (widget_instance_data_s*) malloc(sizeof(widget_instance_data_s));
            int ret;
        @@ -202,7 +202,7 @@ int widget_instance_create(widget_context_h context, bundle *content, int w, int
         
      5. This callback is triggered when the widget instance is destroyed.

        Release all widget resources. If the reason for the termination is not WIDGET_APP_DESTROY_TYPE_DEFAULT, store the current status with the incoming bundle.

        -int widget_instance_destroy(widget_context_h context, widget_app_destroy_type_e reason, bundle *content)
        +int widget_instance_destroy(widget_context_h context, widget_app_destroy_type_e reason, bundle *content, void *user_data)
         {
            if (reason != WIDGET_APP_DESTROY_TYPE_DEFAULT) 
            {
        @@ -218,7 +218,7 @@ int widget_instance_destroy(widget_context_h context, widget_app_destroy_type_e
         
      6. This callback is triggered when the widget instance is paused.

        Take the necessary actions since the widget instance becomes invisible. The framework can destroy a paused widget instance.

        -int widget_instance_pause(widget_context_h context)
        +int widget_instance_pause(widget_context_h context, void *user_data)
         {
            return WIDGET_ERROR_NONE;
         }
        @@ -227,7 +227,7 @@ int widget_instance_pause(widget_context_h context)
         
      7. This callback is triggered when the widget instance is resumed.

        Take the necessary actions since the widget instance becomes visible.

        -int widget_instance_resume(widget_context_h context)
        +int widget_instance_resume(widget_context_h context, void *user_data)
         {
            return WIDGET_ERROR_NONE;
         }
        @@ -236,7 +236,7 @@ int widget_instance_resume(widget_context_h context)
         
      8. This callback is triggered before the widget instance is resized.

        Take the necessary actions to accommodate the new size.

        -int widget_instance_resize(widget_context_h context, int w, int h)
        +int widget_instance_resize(widget_context_h context, int w, int h, void *user_data)
         {
            return WIDGET_ERROR_NONE;
         } 
        @@ -245,7 +245,7 @@ int widget_instance_resize(widget_context_h context, int w, int h)
         
      9. This callback is triggered when a widget update event is received.

        Take the necessary actions for the widget update. If the force parameter is true, the widget can be updated even in the pause state.

        -int widget_instance_update(widget_context_h context, bundle *content, int force)
        +int widget_instance_update(widget_context_h context, bundle *content, int force, void *user_data)
         {
            return WIDGET_ERROR_NONE;
         }
        @@ -269,7 +269,7 @@ widget_class_h widget_app_create (void *user_data)
         
            // Register system-related callbacks
         
        -   return widget_app_class_create(obj_callback);
        +   return widget_app_class_create(obj_callback, user_data);
         }
         
      10. @@ -290,8 +290,7 @@ typedef struct widget_instance_data widget_instance_data_s; static int -widget_instance_create(widget_context_h context, bundle *content, -int w, int h) +widget_instance_create(widget_context_h context, bundle *content, int w, int h, void *user_data) {    widget_instance_data_s *wid = (widget_instance_data_s*) malloc(sizeof(widget_instance_data_s)); @@ -346,21 +345,21 @@ typedef struct } user_defined_s; -int widget_instance_create(widget_context_h context, bundle *content, int w, int h) +int widget_instance_create(widget_context_h context, bundle *content, int w, int h, void *user_data) {    user_defined_s *uds = (user_defined_s*)malloc(sizeof(user_defined_s));    uds->val1 = 0;    widget_app_context_set_tag(context, uds); } -int widget_instance_destroy(widget_context_h context, widget_destroy_type_e reason, bundle *content) +int widget_instance_destroy(widget_context_h context, widget_destroy_type_e reason, bundle *content, void *user_data) {    user_defined_s *uds = NULL;    widget_app_context_get_tag(context, (void**)&uds);    free(uds); } -int widget_instance_update(widget_context_h context, bundle *content, int force) +int widget_instance_update(widget_context_h context, bundle *content, int force, void *user_data) {    user_defined_s *uds = NULL;    widget_app_context_get_tag(context, (void**)&uds); @@ -371,7 +370,7 @@ int widget_instance_update(widget_context_h context, bundle *content, int force)
      11. Get the widget instance ID:
        -int widget_instance_update(widget_context_h context, bundle *content, int force)
        +int widget_instance_update(widget_context_h context, bundle *content, int force, void *user_data)
         {
            const char *inst_id = NULL;
            inst_id = widget_app_get_id(context);
        diff --git a/org.tizen.tutorials/html/native/content/content_tutorials_n.htm b/org.tizen.tutorials/html/native/content/content_tutorials_n.htm
        index 79556b5..1a42bcb 100644
        --- a/org.tizen.tutorials/html/native/content/content_tutorials_n.htm
        +++ b/org.tizen.tutorials/html/native/content/content_tutorials_n.htm
        @@ -40,7 +40,7 @@
         	

        Demonstrates how you can manage media content.

      12. MIME Type: Mapping MIME Types to and from File Extensions

        Demonstrates how you can map MIME types to file extensions.

    -

    The following tutorials apply in mobile applications only:

    +

    The following tutorials apply in mobile applications only:

    diff --git a/org.tizen.tutorials/html/native/context/activity_tutorial_n.htm b/org.tizen.tutorials/html/native/context/activity_tutorial_n.htm index d3ff254..6ddb43f 100644 --- a/org.tizen.tutorials/html/native/context/activity_tutorial_n.htm +++ b/org.tizen.tutorials/html/native/context/activity_tutorial_n.htm @@ -1,114 +1,114 @@ - - - - - - - - - - - - - Activity Recognition: Detecting Device Activities - - - - - -
    - -

    Activity Recognition: Detecting Device Activities

    - - -

    This tutorial demonstrates how you can manage and monitor various system information and attached devices.

    - -

    Warm-up

    -

    Become familiar with the Activity Recognition API basics by learning about:

    - - -

    Detecting Activities

    - -

    To set and unset callback functions for the activity monitor and retrieve details from the received activity data:

    -
    1. To use the activity recognition-related features of the Activity Recognition API (in mobile and wearable applications), include the <activity_recognition.h> header file in your application:

      -
      -#include <activity_recognition.h>
      -
    2. - -
    3. Create a handle for activity monitoring using the activity_create() function: -
      -activity_h handle;
      -activity_create(&handle);
      -
      -
    4. - -
    5. To subscribe to notifications about specific activity state changes, invoke the activity_start_recognition() function to register a callback function. -

      When specific activity data is received, the example_activity_callback callback is invoked.

      - -

      The following example starts the activity monitor to receive notifications when the ACTIVITY_WALK activity is detected. Any of the activity_type_e enumerators (in mobile and wearable applications) can be used in place of the ACTIVITY_WALK value.

      -
      -activity_start_recognition(handle, ACTIVITY_WALK, example_activity_callback, NULL);
      -
      -
    6. - -
    7. When the example_activity_callback() callback is invoked, the current activity is delivered as a parameter, and you can extract the accuracy of the recognized activity: -
      void example_activity_callback(activity_type_e activity, const activity_data_h data, double timestamp, activity_error_e error, void *user_data)
      -{
      -   int result;
      -
      -   activity_accuracy_e accuracy;
      -   result = activity_get_accuracy(data, &accuracy);
      -
      -   if (result != ACTIVITY_ERROR_NONE) 
      -   {
      -      // Error handling
      -   }
      -}
    8. -
    9. When activity monitoring is no longer used, unset the callback function and destroy the handle: -
      activity_stop_recognition(handle);
      -activity_release(handle);
    - - - - -
    - -Go to top - - - - - - + + + + + + + + + + + + + Activity Recognition: Detecting Device Activities + + + + + +
    + +

    Activity Recognition: Detecting Device Activities

    + + +

    This tutorial demonstrates how you can manage and monitor various system information and attached devices.

    + +

    Warm-up

    +

    Become familiar with the Activity Recognition API basics by learning about:

    + + +

    Detecting Activities

    + +

    To set and unset callback functions for the activity monitor and retrieve details from the received activity data:

    +
    1. To use the activity recognition-related features of the Activity Recognition API (in mobile and wearable applications), include the <activity_recognition.h> header file in your application:

      +
      +#include <activity_recognition.h>
      +
    2. + +
    3. Create a handle for activity monitoring using the activity_create() function: +
      +activity_h handle;
      +activity_create(&handle);
      +
      +
    4. + +
    5. To subscribe to notifications about specific activity state changes, invoke the activity_start_recognition() function to register a callback function. +

      When specific activity data is received, the example_activity_callback callback is invoked.

      + +

      The following example starts the activity monitor to receive notifications when the ACTIVITY_WALK activity is detected. Any of the activity_type_e enumerators (in mobile and wearable applications) can be used in place of the ACTIVITY_WALK value.

      +
      +activity_start_recognition(handle, ACTIVITY_WALK, example_activity_callback, NULL);
      +
      +
    6. + +
    7. When the example_activity_callback() callback is invoked, the current activity is delivered as a parameter, and you can extract the accuracy of the recognized activity: +
      void example_activity_callback(activity_type_e activity, const activity_data_h data, double timestamp, activity_error_e error, void *user_data)
      +{
      +   int result;
      +
      +   activity_accuracy_e accuracy;
      +   result = activity_get_accuracy(data, &accuracy);
      +
      +   if (result != ACTIVITY_ERROR_NONE) 
      +   {
      +      // Error handling
      +   }
      +}
    8. +
    9. When activity monitoring is no longer used, unset the callback function and destroy the handle: +
      activity_stop_recognition(handle);
      +activity_release(handle);
    + + + + +
    + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.tutorials/html/native/context/context_tutorials_n.htm b/org.tizen.tutorials/html/native/context/context_tutorials_n.htm index bc6c5cc..126c4d7 100644 --- a/org.tizen.tutorials/html/native/context/context_tutorials_n.htm +++ b/org.tizen.tutorials/html/native/context/context_tutorials_n.htm @@ -1,77 +1,77 @@ - - - - - - - - - - - - - Context: Detecting and Exploiting Contextual Information - - - - - -
    - -

    Context: Detecting and Exploiting Contextual Information

    - -

    The context tutorials demonstrate how to use the following features in creating Tizen native applications:

    - -

    The following tutorials apply in mobile applications only:

    - - - - - - - -
    - -Go to top - - - - - - + + + + + + + + + + + + + Context: Detecting and Exploiting Contextual Information + + + + + +
    + +

    Context: Detecting and Exploiting Contextual Information

    + +

    The context tutorials demonstrate how to use the following features in creating Tizen native applications:

    + +

    The following tutorials apply in mobile applications only:

    + + + + + + + +
    + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.tutorials/html/native/context/gesture_tutorial_n.htm b/org.tizen.tutorials/html/native/context/gesture_tutorial_n.htm index 28a8d6b..05b91e3 100644 --- a/org.tizen.tutorials/html/native/context/gesture_tutorial_n.htm +++ b/org.tizen.tutorials/html/native/context/gesture_tutorial_n.htm @@ -1,130 +1,130 @@ - - - - - - - - - - - - - Gesture Recognition: Detecting User Gestures - - - - - -
    - -

    Gesture Recognition: Detecting User Gestures

    - - -

    This tutorial demonstrates how you can detect gestures performed with the device.

    - - -

    Warm-up

    -

    Become familiar with the Gesture Recognition API basics by learning about:

    - - -

    Detecting Gestures

    - -

    To set and unset callback functions for user gestures:

    - -
    1. To use the gesture recognition-related features of the Gesture Recognition API (in mobile and wearable applications), include the <gesture_recognition.h> header file in your application:

      -
      -#include <gesture_recognition.h>
      -
    2. - -
    3. Create a handle for gesture detection using the gesture_create() function: - -
      -gesture_h handle;
      -gesture_create(&handle);
    4. - -
    5. To subscribe to notifications about gesture events, invoke the gesture_start_recognition() function to register a callback function and start gesture detection.

      -

      When the registered gesture is detected, the gesture_cb callback is invoked.

      - -
      gesture_start_recognition(handle, GESTURE_PICK_UP, GESTURE_OPTION_DEFAULT, gesture_cb, NULL);
      - -

      The above example starts gesture detection to receive notifications when the GESTURE_PICK_UP gesture is detected. The application can use any of the gesture_type_e enumerators (in mobile and wearable applications) in place of the GESTURE_PICK_UP value. Note that not all gestures are supported by all devices. In such cases, the function returns the GESTURE_ERROR_NOT_SUPPORTED value.

      - -

      If the default gesture option is designated, the system tries to reduce power consumption to detect the gesture. For example, the gesture is not necessarily detected while the display is switched off. Using the GESTURE_OPTION_ALWAYS_ON option prevents such power-saving behaviors. For more information about the gesture options, see the gesture_option_e enumeration (in mobile and wearable applications).

    6. - -
    7. When the gesture_cb() callback function is invoked, you can retrieve the event data using the gesture_get_event() function:

      - -
      void gesture_cb(gesture_type_e gesture, const gesture_data_h data, double timestamp, gesture_error_e error, void *user_data)
      -{			
      -   gesture_event_e event;
      -   if (gesture == GESTURE_PICK_UP) 
      -   {
      -      gesture_get_event(data, &event);
      -
      -      if (event == GESTURE_EVENT_DETECTED) 
      -      {
      -         // Handle the event
      -      }
      -   }
      -}
      - -

      If the application registered multiple gestures to a single callback function, the input parameter gesture can be used to distinguish the gesture received.

      -

      Some gestures can return different types of events. For example, GESTURE_SHAKE can return GESTURE_SHAKE_DETECTED or GESTURE_SHAKE_FINISHED.

      - -

      In case of GESTURE_TILT, the gesture_get_tilt() function can be used to extract the tilting angles.

      - -
      int x, y;
      -if (gesture == GESTURE_TILT) 
      -{
      -   gesture_get_tilt(data, &x, &y);
      -}
    8. - -
    9. When gesture detection is no longer used, unset the callback functions with the gesture_stop_recognition() function and destroy the handle with the gesture_release() function:

      - -
      gesture_stop_recognition(handle);
      -gesture_release(handle);
    - - - - -
    - -Go to top - - - - - - + + + + + + + + + + + + + Gesture Recognition: Detecting User Gestures + + + + + +
    + +

    Gesture Recognition: Detecting User Gestures

    + + +

    This tutorial demonstrates how you can detect gestures performed with the device.

    + + +

    Warm-up

    +

    Become familiar with the Gesture Recognition API basics by learning about:

    + + +

    Detecting Gestures

    + +

    To set and unset callback functions for user gestures:

    + +
    1. To use the gesture recognition-related features of the Gesture Recognition API (in mobile and wearable applications), include the <gesture_recognition.h> header file in your application:

      +
      +#include <gesture_recognition.h>
      +
    2. + +
    3. Create a handle for gesture detection using the gesture_create() function: + +
      +gesture_h handle;
      +gesture_create(&handle);
    4. + +
    5. To subscribe to notifications about gesture events, invoke the gesture_start_recognition() function to register a callback function and start gesture detection.

      +

      When the registered gesture is detected, the gesture_cb callback is invoked.

      + +
      gesture_start_recognition(handle, GESTURE_PICK_UP, GESTURE_OPTION_DEFAULT, gesture_cb, NULL);
      + +

      The above example starts gesture detection to receive notifications when the GESTURE_PICK_UP gesture is detected. The application can use any of the gesture_type_e enumerators (in mobile and wearable applications) in place of the GESTURE_PICK_UP value. Note that not all gestures are supported by all devices. In such cases, the function returns the GESTURE_ERROR_NOT_SUPPORTED value.

      + +

      If the default gesture option is designated, the system tries to reduce power consumption to detect the gesture. For example, the gesture is not necessarily detected while the display is switched off. Using the GESTURE_OPTION_ALWAYS_ON option prevents such power-saving behaviors. For more information about the gesture options, see the gesture_option_e enumeration (in mobile and wearable applications).

    6. + +
    7. When the gesture_cb() callback function is invoked, you can retrieve the event data using the gesture_get_event() function:

      + +
      void gesture_cb(gesture_type_e gesture, const gesture_data_h data, double timestamp, gesture_error_e error, void *user_data)
      +{			
      +   gesture_event_e event;
      +   if (gesture == GESTURE_PICK_UP) 
      +   {
      +      gesture_get_event(data, &event);
      +
      +      if (event == GESTURE_EVENT_DETECTED) 
      +      {
      +         // Handle the event
      +      }
      +   }
      +}
      + +

      If the application registered multiple gestures to a single callback function, the input parameter gesture can be used to distinguish the gesture received.

      +

      Some gestures can return different types of events. For example, GESTURE_SHAKE can return GESTURE_SHAKE_DETECTED or GESTURE_SHAKE_FINISHED.

      + +

      In case of GESTURE_TILT, the gesture_get_tilt() function can be used to extract the tilting angles.

      + +
      int x, y;
      +if (gesture == GESTURE_TILT) 
      +{
      +   gesture_get_tilt(data, &x, &y);
      +}
    8. + +
    9. When gesture detection is no longer used, unset the callback functions with the gesture_stop_recognition() function and destroy the handle with the gesture_release() function:

      + +
      gesture_stop_recognition(handle);
      +gesture_release(handle);
    + + + + +
    + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.tutorials/html/native/location/location_tutorials_n.htm b/org.tizen.tutorials/html/native/location/location_tutorials_n.htm index df9ceaf..9eb76f3 100644 --- a/org.tizen.tutorials/html/native/location/location_tutorials_n.htm +++ b/org.tizen.tutorials/html/native/location/location_tutorials_n.htm @@ -1,72 +1,72 @@ - - - - - - - - - - - - - Location: Retrieve the Device Location and Create Geofences - - - - - -
    -

    Location: Retrieve the Device Location and Create Geofences

    - -

    The location tutorials demonstrate how to use the following features in creating Tizen native applications:

    - -

    The following tutorials apply in mobile applications only:

    - - - - - - -
    - -Go to top - - - - - - + + + + + + + + + + + + + Location: Retrieve the Device Location and Create Geofences + + + + + +
    +

    Location: Retrieve the Device Location and Create Geofences

    + +

    The location tutorials demonstrate how to use the following features in creating Tizen native applications:

    + +

    The following tutorials apply in mobile applications only:

    + + + + + + +
    + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.tutorials/html/native/messaging/email_tutorial_n.htm b/org.tizen.tutorials/html/native/messaging/email_tutorial_n.htm index 6be0acd..80a561f 100644 --- a/org.tizen.tutorials/html/native/messaging/email_tutorial_n.htm +++ b/org.tizen.tutorials/html/native/messaging/email_tutorial_n.htm @@ -176,15 +176,15 @@ if (error_code != EMAILS_ERROR_NONE)
    - diff --git a/org.tizen.tutorials/html/native/messaging/messaging_tutorials_n.htm b/org.tizen.tutorials/html/native/messaging/messaging_tutorials_n.htm index 194305d..af9fcc7 100644 --- a/org.tizen.tutorials/html/native/messaging/messaging_tutorials_n.htm +++ b/org.tizen.tutorials/html/native/messaging/messaging_tutorials_n.htm @@ -41,7 +41,7 @@
  • Messages: Creating and Sending SMS and MMS Messages

    Demonstrates how you can send SMS and MMS messages, and fetch messages from a specified message box.

  • Push: Using the Push Service

    Demonstrates how you can receive notifications through the Internet even when the application is not running.

  • -

    The following tutorials apply in mobile applications only:

    +

    The following tutorials apply in mobile applications only:

    @@ -57,15 +57,15 @@ - diff --git a/org.tizen.tutorials/html/native/messaging/push_tutorial_n.htm b/org.tizen.tutorials/html/native/messaging/push_tutorial_n.htm index c97b0b2..89b2d09 100644 --- a/org.tizen.tutorials/html/native/messaging/push_tutorial_n.htm +++ b/org.tizen.tutorials/html/native/messaging/push_tutorial_n.htm @@ -876,15 +876,15 @@ do - diff --git a/org.tizen.tutorials/html/native/messaging/sms_mms_tutorial_n.htm b/org.tizen.tutorials/html/native/messaging/sms_mms_tutorial_n.htm index 7ea74d4..b8c3350 100644 --- a/org.tizen.tutorials/html/native/messaging/sms_mms_tutorial_n.htm +++ b/org.tizen.tutorials/html/native/messaging/sms_mms_tutorial_n.htm @@ -228,15 +228,15 @@ if (error_code != MESSAGES_ERROR_NONE) - diff --git a/org.tizen.tutorials/html/native/multimedia/image_util_tutorial_n.htm b/org.tizen.tutorials/html/native/multimedia/image_util_tutorial_n.htm old mode 100755 new mode 100644 diff --git a/org.tizen.tutorials/html/native/multimedia/media_controller_tutorial_n.htm b/org.tizen.tutorials/html/native/multimedia/media_controller_tutorial_n.htm index d4e31e7..99580e3 100644 --- a/org.tizen.tutorials/html/native/multimedia/media_controller_tutorial_n.htm +++ b/org.tizen.tutorials/html/native/multimedia/media_controller_tutorial_n.htm @@ -11,7 +11,7 @@ - Media Controller: Communicating between the Server and Client for Media Control + Media Controller: Communicating Between the Server and Client for Media Control @@ -37,7 +37,7 @@
    -

    Media Controller: Communicating between the Server and Client for Media Control

    +

    Media Controller: Communicating Between the Server and Client for Media Control

    This tutorial demonstrates how you can transfer information between the server and the client.

    diff --git a/org.tizen.tutorials/html/native/multimedia/multimedia_tutorials_n.htm b/org.tizen.tutorials/html/native/multimedia/multimedia_tutorials_n.htm index 54c825e..cbbd90a 100644 --- a/org.tizen.tutorials/html/native/multimedia/multimedia_tutorials_n.htm +++ b/org.tizen.tutorials/html/native/multimedia/multimedia_tutorials_n.htm @@ -39,7 +39,7 @@
  • Camera: Controlling a Camera Device

    Demonstrates how you can access the camera preview, focus, and take photos.

  • Image Util: Encoding, Decoding, and Transforming Images

    Demonstrates how you can process images and decode or encode JPEG image files.

  • Media Codec: Encoding and Decoding Media Files

    Demonstrates how you can encode and decode media files.

  • -
  • Media Controller: Communicating between the Server and Client for Media Control

    Demonstrates how you can communicate between the media controller server and the media controller client.

  • +
  • Media Controller: Communicating Between the Server and Client for Media Control

    Demonstrates how you can communicate between the media controller server and the media controller client.

  • Media Tool: Managing Media Handles

    Demonstrates how you can manage media handles.

  • Media Vision: Generating and Detecting Barcodes

    Demonstrates how you can create and read barcodes.

  • Metadata Editor: Editing Metadata from an Input Audio File

    Demonstrates how you can edit the metadata of several popular audio formats.

  • @@ -51,11 +51,11 @@
  • Tone Player: Playing Tones

    Demonstrates how you can play tones.

  • WAV Player: Playing Waveform Audio Files

    Demonstrates how you can play WAV files.

  • Sound Manager: Managing Sound Parameters

    Demonstrates how you can set the sound session type and control volume.

  • -
  • Screen Mirroring Sink: Mirroring Screen and Sound

    Demonstrates how you can mirror the device screen and sound to another device wirelessly.

  • -

    The following tutorials apply in mobile applications only:

    +

    The following tutorials apply in mobile applications only:

    diff --git a/org.tizen.tutorials/html/native/multimedia/screen_mirroring_tutorial_n.htm b/org.tizen.tutorials/html/native/multimedia/screen_mirroring_tutorial_n.htm old mode 100755 new mode 100644 index 4c90d59..343bddb --- a/org.tizen.tutorials/html/native/multimedia/screen_mirroring_tutorial_n.htm +++ b/org.tizen.tutorials/html/native/multimedia/screen_mirroring_tutorial_n.htm @@ -18,7 +18,7 @@ @@ -43,6 +42,17 @@

    This tutorial demonstrates how you can mirror the device screen and sound to another device wirelessly as a sink.

    + + + + + + + + + +
    Note
    This feature is supported in mobile applications only.
    +

    Warm-up

    Become familiar with Screen Mirroring Sink API basics by learning about:

    @@ -68,7 +78,7 @@

    To initialize the screen mirroring sink:

    -
    1. To use the functions and data types of the Screen Mirroring Sink API (in mobile and mobile applications), include the <scmirroring_type.h> and <scmirroring_sink.h> header files in your application:

      +
      1. To use the functions and data types of the Screen Mirroring Sink API, include the <scmirroring_type.h> and <scmirroring_sink.h> header files in your application:

         #include <scmirroring_type.h>
         #include <scmirroring_sink.h>
        diff --git a/org.tizen.tutorials/html/native/network/bluetooth_tutorial_n.htm b/org.tizen.tutorials/html/native/network/bluetooth_tutorial_n.htm
        index 701e024..3c524f4 100644
        --- a/org.tizen.tutorials/html/native/network/bluetooth_tutorial_n.htm
        +++ b/org.tizen.tutorials/html/native/network/bluetooth_tutorial_n.htm
        @@ -1771,15 +1771,15 @@ if (ret != BT_ERROR_NONE)
         
         
    - diff --git a/org.tizen.tutorials/html/native/network/connection_tutorial_n.htm b/org.tizen.tutorials/html/native/network/connection_tutorial_n.htm index 1e87bfc..276a948 100644 --- a/org.tizen.tutorials/html/native/network/connection_tutorial_n.htm +++ b/org.tizen.tutorials/html/native/network/connection_tutorial_n.htm @@ -580,15 +580,15 @@ done:
    - diff --git a/org.tizen.tutorials/html/native/network/network_tutorials_n.htm b/org.tizen.tutorials/html/native/network/network_tutorials_n.htm index 961c4d1..f1dae2b 100644 --- a/org.tizen.tutorials/html/native/network/network_tutorials_n.htm +++ b/org.tizen.tutorials/html/native/network/network_tutorials_n.htm @@ -44,7 +44,7 @@
  • Wi-Fi: Managing Wi-Fi and Monitoring Its State

    Demonstrates how you can manage Wi-Fi connections and monitor the Wi-Fi state.

  • -

    The following tutorials apply in mobile applications only:

    +

    The following tutorials apply in mobile applications only:

    @@ -61,15 +61,15 @@
    - diff --git a/org.tizen.tutorials/html/native/network/nfc_tutorial_n.htm b/org.tizen.tutorials/html/native/network/nfc_tutorial_n.htm index 512908e..7e60eaf 100644 --- a/org.tizen.tutorials/html/native/network/nfc_tutorial_n.htm +++ b/org.tizen.tutorials/html/native/network/nfc_tutorial_n.htm @@ -987,15 +987,15 @@ nfc_ndef_record_get_text(ndef_record, &email); - diff --git a/org.tizen.tutorials/html/native/network/smartcard_tutorial_n.htm b/org.tizen.tutorials/html/native/network/smartcard_tutorial_n.htm index 0345761..1855c3d 100644 --- a/org.tizen.tutorials/html/native/network/smartcard_tutorial_n.htm +++ b/org.tizen.tutorials/html/native/network/smartcard_tutorial_n.htm @@ -511,15 +511,15 @@ else - diff --git a/org.tizen.tutorials/html/native/network/wifi_direct_tutorial_n.htm b/org.tizen.tutorials/html/native/network/wifi_direct_tutorial_n.htm index a11d856..452d532 100644 --- a/org.tizen.tutorials/html/native/network/wifi_direct_tutorial_n.htm +++ b/org.tizen.tutorials/html/native/network/wifi_direct_tutorial_n.htm @@ -480,15 +480,15 @@ wifi_direct_deactivate(NULL); - diff --git a/org.tizen.tutorials/html/native/network/wifi_tutorial_n.htm b/org.tizen.tutorials/html/native/network/wifi_tutorial_n.htm index 696155f..59d3fec 100644 --- a/org.tizen.tutorials/html/native/network/wifi_tutorial_n.htm +++ b/org.tizen.tutorials/html/native/network/wifi_tutorial_n.htm @@ -298,15 +298,15 @@ wifi_deactivate(NULL, NULL); - diff --git a/org.tizen.tutorials/html/native/security/key_tutorial_n.htm b/org.tizen.tutorials/html/native/security/key_tutorial_n.htm index 7699d92..4a93e91 100644 --- a/org.tizen.tutorials/html/native/security/key_tutorial_n.htm +++ b/org.tizen.tutorials/html/native/security/key_tutorial_n.htm @@ -1,1035 +1,1035 @@ - - - - - - - - - - - - - Key Manager: Using Keys and Certificates, and Implementing Access Control - - - - - - -
    -

    Key Manager: Using Keys and Certificates, and Implementing Access Control

    - - -

    This tutorial demonstrates how you can use the key manager to create a secure repository for keys, certificates, and sensitive data.

    - - -

    Warm-up

    -

    Become familiar with the Key Manager API basics by learning about:

    - - -

    Initializing the Key Manager

    - -

    To define the header file and privileges required to use the key manager:

    -
      -
    1. To use the Key Manager privileged API, declare the http://tizen.org/privilege/keymanager privilege in the manifest.xml file of the application package.

    2. -
    3. To use the functions and data types of the Key Manager API (in mobile and wearable applications), include the <ckmc/ckmc-manager.h> header file in your application:

      -
      -#include <ckmc/ckmc-manager.h>
      -
    - -

    Saving, Getting, or Removing a Key

    - -

    To store, remove, and retrieve client keys from the key manager:

    - -
    1. Store a new key. -
      -int ret = CKMC_ERROR_NONE;
      -
      -ckmc_key_s test_key;
      -ckmc_policy_s store_policy;
      -char* alias= "mykey";
      -char* key_password = NULL;
      -
      -char* binary_key = "-----BEGIN PUBLIC KEY-----\n"
      -   "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA2b1bXDa+S8/MGWnMkru4\n"
      -   "T4tUddtZNi0NVjQn9RFH1NMa220GsRhRO56F77FlSVFKfSfVZKIiWg6C+DVCkcLf\n"
      -   "zXJ/Z0pvwOQYBAqVMFjV6efQGN0JzJ1Unu7pPRiZl7RKGEI+cyzzrcDyrLLrQ2W7\n"
      -   "0ZySkNEOv6Frx9JgC5NExuYY4lk2fQQa38JXiZkfyzif2em0px7mXbyf5LjccsKq\n"
      -   "v1e+XLtMsL0ZefRcqsP++NzQAI8fKX7WBT+qK0HJDLiHrKOTWYzx6CwJ66LD/vvf\n"
      -   "j55xtsKDLVDbsotvf8/m6VLMab+vqKk11TP4tq6yo0mwyTADvgl1zowQEO9I1W6o\n"
      -   "zQIDAQAB\n"
      -   "-----END PUBLIC KEY-----";
      -
      -test_key.raw_key =  (unsigned char *) binary_key;
      -test_key.key_size = strlen(binary_key);
      -test_key.key_type = CKMC_KEY_NONE; // The real key type is determined by the key manager
      -test_key.password = NULL; // This means the binary_key is not encrypted with any password
      -
      -store_policy.password = key_password; // NULL means that the test_key is not encrypted with a per key password
      -store_policy.extractable = true; // This means that the key value is extractable
      -
      -ret = ckmc_save_key(alias, test_key, store_policy);
      -if (CKMC_ERROR_NONE != ret)
      -{
      -   // Error handling
      -}
      -
    2. - -
    3. Get a key from the key manager. -
      -int ret = CKMC_ERROR_NONE;
      -
      -ckmc_key_s *test_key;
      -char* alias= "mykey";
      -char* key_password = NULL;
      -
      -ret = ckmc_get_key(alias, key_password, &test_key);
      -if (CKMC_ERROR_NONE != ret)
      -{
      -   // Error handling
      -}
      -
      -dlog_print(DLOG_INFO, LOG_TAG, "key size =%d\n", test_key->key_size);
      -
      -ckmc_key_free(test_key); // Called when the key is no longer needed
      -
    4. - -
    5. Get the key alias list. -
      -int ret = CKMC_ERROR_NONE;
      -
      -ckmc_alias_list_s *alias_list;
      -ckmc_alias_list_s *plist;
      -ckmc_key_s *test_key;
      -char* key_password = NULL;
      -int count_list = 0;
      -
      -ret = ckmc_get_key_alias_list(&alias_list);
      -if (CKMC_ERROR_NONE != ret)
      -{
      -   // Error handling
      -}
      -
      -plist = alias_list;
      -do
      -{
      -   ckmc_get_key(plist->alias, key_password, &test_key);
      -   dlog_print(DLOG_INFO, LOG_TAG, "%d th key : key size =%d\n", ++count_list, test_key->key_size);
      -   ckmc_key_free(test_key);
      -   plist = plist->next;
      -}
      -while(plist != NULL);
      -
      -ckmc_alias_list_all_free(alias_list); // Called when the list is no longer needed.
      -
    6. -
    7. Remove the key. -
      -int ret = CKMC_ERROR_NONE;
      -
      -const char* alias= "mykey";
      -
      -ret = ckmc_remove_key(alias);
      -if (CKMC_ERROR_NONE != ret) 
      -{
      -   // Error handling
      -}
      -
    - -

    Saving, Getting, or Removing a Certificate

    - -

    To store, remove, or retrieve the client certificate from the key manager:

    - -
    1. Store a new certificate. -
      -int ret = CKMC_ERROR_NONE;
      -
      -char* password = NULL;
      -ckmc_cert_s cert;
      -const char *alias = "myCert";
      -ckmc_policy_s test_policy;
      -
      -const char *certPem = "-----BEGIN CERTIFICATE-----\n"
      -"MIIEgDCCA2igAwIBAgIIcjtBYJGQtOAwDQYJKoZIhvcNAQEFBQAwSTELMAkGA1UE\n"
      -"BhMCVVMxEzARBgNVBAoTCkdvb2dsZSBJbmMxJTAjBgNVBAMTHEdvb2dsZSBJbnRl\n"
      -"cm5ldCBBdXRob3JpdHkgRzIwHhcNMTQwNTIyMTEyOTQyWhcNMTQwODIwMDAwMDAw\n"
      -"WjBtMQswCQYDVQQGEwJVUzETMBEGA1UECAwKQ2FsaWZvcm5pYTEWMBQGA1UEBwwN\n"
      -"TW91bnRhaW4gVmlldzETMBEGA1UECgwKR29vZ2xlIEluYzEcMBoGA1UEAwwTYWNj\n"
      -"b3VudHMuZ29vZ2xlLmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEB\n"
      -"ALtlLWVWPN3q3bSEQl1Z97gPdgl5vbgJOZSAr0ZY0tJCuFLBbUKetJWryyE+5KpG\n"
      -"gMMpLS4v8/bvXaZc6mAs+RfAqGM24C3vQg5hPnj4dflnhL0WiOCZBurm1tV4oexk\n"
      -"HLXs3jr/jpnb738AQpj8zZ9a4VEBuHJRZALnWZ/XhqU+dvYomAoRQNuL5OhkT7uu\n"
      -"d0NKJL9JjYLyQglGgE2sVsWv2kj7EO/P9Q6NEKt9BGmhMsFvtfeKUaymynaxpR1g\n"
      -"wEPlqYvB38goh1dIOgVLT0OVyLImeg5Mdwar/8c1U0OYhLOc6PJapOZAfUkE+3+w\n"
      -"xYt8AChLN1b5szOwInrCVpECAwEAAaOCAUYwggFCMB0GA1UdJQQWMBQGCCsGAQUF\n"
      -"BwMBBggrBgEFBQcDAjAeBgNVHREEFzAVghNhY2NvdW50cy5nb29nbGUuY29tMGgG\n"
      -"CCsGAQUFBwEBBFwwWjArBggrBgEFBQcwAoYfaHR0cDovL3BraS5nb29nbGUuY29t\n"
      -"L0dJQUcyLmNydDArBggrBgEFBQcwAYYfaHR0cDovL2NsaWVudHMxLmdvb2dsZS5j\n"
      -"b20vb2NzcDAdBgNVHQ4EFgQU0/UtToEtNIfwDwHuYGuVKcj0xK8wDAYDVR0TAQH/\n"
      -"BAIwADAfBgNVHSMEGDAWgBRK3QYWG7z2aLV29YG2u2IaulqBLzAXBgNVHSAEEDAO\n"
      -"MAwGCisGAQQB1nkCBQEwMAYDVR0fBCkwJzAloCOgIYYfaHR0cDovL3BraS5nb29n\n"
      -"bGUuY29tL0dJQUcyLmNybDANBgkqhkiG9w0BAQUFAAOCAQEAcGNI/X9f0g+7ij0o\n"
      -"ehLpk6vxSMQGrmOZ4+PG/MC9SLClCkt7zJkfU7erZnyVXyxCpwlljq+Wk9YTPUOq\n"
      -"xD/V2ikQVSAANoxGJFO9UoL5jzWusPhKKv8CcM7fuiERz8K+CfBcqfxbgI5rH0g5\n"
      -"dYclmLC81cJ/08i+9Nltvxv69Y3hGfEICT6K+EdSxwnQzOhpMZmvxZsIj+d6CVNa\n"
      -"9ICYgUthsNQVWzrIs5wknpjjZ9liDMwJX0vu8A0rce4X/Lna5hh2bW9igz2iP5WM\n"
      -"9fuwdbTw4y3jfPQgszU4YZxWxhMzccxe058Qx1tLndAknBQEBesQjXytVQpuM1SV\n"
      -"rHva8A==\n"
      -"-----END CERTIFICATE-----\n";
      -
      -test_policy.password = password;
      -test_policy.extractable = true;
      -
      -cert.raw_cert =  (unsigned char *) certPem;
      -cert.cert_size = strlen(certPem);
      -cert.data_format = CKMC_FORM_PEM;
      -
      -ret = ckmc_save_cert(alias, cert, test_policy);
      -if (CKMC_ERROR_NONE != ret)
      -{
      -   // Error handling
      -}
      -
    2. - -
    3. Get a certificate from the key manager. -
      -int ret = CKMC_ERROR_NONE;
      -
      -ckmc_cert_s *test_cert;
      -char* alias= "myCert";
      -char* password = NULL;
      -
      -ret = ckmc_get_cert(alias, password, &test_cert);
      -if (CKMC_ERROR_NONE != ret)
      -{
      -   // Error handling
      -}
      -
      -dlog_print(DLOG_INFO, LOG_TAG, "cert size =%d\n", test_cert->cert_size);
      -
      -ckmc_cert_free(test_cert); // Called when the certificate is no longer needed
      -
    4. -
    5. Get the certificate alias list. -
      -int ret = CKMC_ERROR_NONE;
      -
      -ckmc_alias_list_s *alias_list;
      -ckmc_alias_list_s *plist;
      -ckmc_cert_s *test_cert;
      -char* password = NULL;
      -int count_list = 0;
      -
      -ret = ckmc_get_cert_alias_list(&alias_list);
      -if (CKMC_ERROR_NONE != ret)
      -{
      -   // Error handling
      -}
      -
      -plist = alias_list;
      -do
      -{
      -   ckmc_get_cert(plist->alias, password, &test_cert);
      -   dlog_print(DLOG_INFO, LOG_TAG, "%d th cert : cert size =%d\n", ++count_list, test_cert->cert_size);
      -   ckmc_cert_free(test_cert);
      -   plist = plist->next;
      -}
      -while(plist != NULL);
      -
      -ckmc_alias_list_all_free(alias_list); // Called when the list is no longer needed
      -
    6. - -
    7. Remove the certificate. -
      -int ret = CKMC_ERROR_NONE;
      -
      -const char* alias= "myCert";
      -
      -ret = ckmc_remove_cert(alias);
      -if (CKMC_ERROR_NONE != ret)
      -{
      -   // Error handling
      -}
      -
    - -

    Saving, Getting, or Removing Data

    - -

    To store, remove, or retrieve client data on or from the key manager:

    - -
    1. Store new data. -
      -int ret = CKMC_ERROR_NONE;
      -
      -char* password = NULL;
      -ckmc_raw_buffer_s test_data;
      -const char *alias = "myData";
      -ckmc_policy_s test_policy;
      -
      -const char *char_bin_data = "My Binary Data";
      -
      -test_policy.password = password;
      -test_policy.extractable = true;
      -
      -test_data.data = (unsigned char *) char_bin_data;
      -test_data.size = strlen(char_bin_data);
      -ret = ckmc_save_data(alias, test_data, test_policy);
      -if (CKMC_ERROR_NONE != ret)
      -{
      -   // Error handling
      -}
      -
    2. - -
    3. Get data from the key manager. -
      -int ret = CKMC_ERROR_NONE;
      -
      -char* password = NULL;
      -ckmc_raw_buffer_s *test_data;
      -const char *alias = "myData";
      -
      -ret = ckmc_get_data(alias, password, &test_data);
      -if (CKMC_ERROR_NONE != ret)
      -{
      -   // Error handling
      -}
      -
      -dlog_print(DLOG_INFO, LOG_TAG, "data size =%d\n", test_data-> size);
      -
      -ckmc_buffer_free(test_data); // Called when the buffer is no longer needed
      -
    4. - -
    5. Get the data alias list. -
      -int ret = CKMC_ERROR_NONE;
      -
      -ckmc_alias_list_s *alias_list;
      -ckmc_alias_list_s *plist;
      -ckmc_raw_buffer_s *test_data;
      -char* password = NULL;
      -int count_list = 0;
      -
      -ret = ckmc_get_data_alias_list(&alias_list);
      -if (CKMC_ERROR_NONE != ret)
      -{
      -   // Error handling
      -}
      -
      -plist = alias_list;
      -do
      -{
      -   ckmc_get_data(plist->alias, password, &test_data);
      -   dlog_print(DLOG_INFO, LOG_TAG, "%d th data : data size =%d\n", ++count_list, test_data->size);
      -   ckmc_buffer_free(test_data);
      -   plist = plist->next;
      -}
      -while(plist != NULL);
      -
      -ckmc_alias_list_all_free(alias_list); // Called when the list is no longer needed
      -
    6. -
    7. Remove data. -
      -int ret = CKMC_ERROR_NONE;
      -
      -const char* alias= "myData";
      -
      -ret = ckmc_remove_data(alias);
      -if (CKMC_ERROR_NONE != ret)
      -{
      -   // Error handling
      -}
      -
    - -

    Creating Key Pairs

    - -

    To generate asymmetric key pairs - the RSA, ECDSA, or DSA key pair:

    - -
    • Create the RSA key pair:

      -
      -int ret = CKMC_ERROR_NONE;
      -
      -size_t size = 2048; // Key Manager supports 1024, 2048, 4096
      -const char *private_key_alias = "PRV_RSA1";
      -const char *public_key_alias = "PUB_RSA1";
      -ckmc_policy_s policy_private_key;
      -ckmc_policy_s policy_public_key;
      -
      -// This private key is encrypted with a password additionally
      -policy_private_key.password = (char *)"pri_password";
      -policy_private_key.extractable = false; // This key cannot be extracted from the key manager
      -
      -policy_public_key.password = NULL;
      -policy_public_key.extractable = true;
      -
      -ret = ckmc_create_key_pair_rsa(size, private_key_alias, public_key_alias, policy_private_key, policy_public_key);
      -if (CKMC_ERROR_NONE != ret)
      -{
      -   // Error handling
      -}
      -
    • - -
    • Create the ECDSA key pair:

      -
      -int ret = CKMC_ERROR_NONE;
      -
      -ckmc_ec_type_e ectype = CKMC_EC_PRIME192V1;
      -const char *private_key_alias = "PRV_ECDSA1";
      -const char *public_key_alias = "PUB_ECDSA1";
      -ckmc_policy_s policy_private_key;
      -ckmc_policy_s policy_public_key;
      -
      -// This private key is encrypted with the password additionally
      -policy_private_key.password = (char *)"pri_password";
      -policy_private_key.extractable = false; // This key cannot be extracted from the key manager
      -
      -policy_public_key.password = NULL;
      -policy_public_key.extractable = true;
      -
      -ret = ckmc_create_key_pair_ecdsa(ectype, private_key_alias, public_key_alias, policy_private_key, policy_public_key);
      -if (CKMC_ERROR_NONE != ret)
      -{
      -   // Error handling
      -}
      -
    • - -
    • Create the DSA key pair:

      -
      -int ret = CKMC_ERROR_NONE;
      -
      -size_t size = 1024;
      -const char *private_key_alias = "PRV_DSA1";
      -const char *public_key_alias = "PUB-DSA1";
      -ckmc_policy_s policy_private_key;
      -ckmc_policy_s policy_public_key;
      -
      -// This private key is encrypted with a password additionally
      -policy_private_key.password = (char *)"pri_password";
      -policy_private_key.extractable = false;
      -
      -policy_public_key.password = NULL;
      -policy_public_key.extractable = true;
      -
      -ret = ckmc_create_key_pair_dsa(size, private_key_alias, public_key_alias, policy_private_key, policy_public_key);
      -if (CKMC_ERROR_NONE != ret)
      -
      -{
      -   // Error handling
      -}
      -
    - -

    Creating or Verifying Signatures

    - -

    To create or verify signatures:

    -
    1. Store a private and public key. -
      -int ret = CKMC_ERROR_NONE;
      -
      -const char *pub_alias = "pub1";
      -const char *pri_alias = "prv1";
      -char *key_passwd = (char *) "1234";
      -char *pri_passwd = NULL;
      -char *pub_passwd = NULL;
      -ckmc_hash_algo_e hash_algo = CKMC_HASH_SHA256;
      -ckmc_rsa_padding_algo_e pad_algo = CKMC_PKCS1_PADDING;
      -ckmc_raw_buffer_s *signature;
      -
      -ckmc_key_s pubkey;
      -ckmc_policy_s pubpolicy;
      -ckmc_key_s prikey;
      -ckmc_policy_s pripolicy;
      -
      -const char *prv = "-----BEGIN RSA PRIVATE KEY-----\n"
      -   "Proc-Type: 4,ENCRYPTED\n"
      -   "DEK-Info: DES-EDE3-CBC,6C6507B11671DABC\n"
      -   "\n"
      -   "YiKNviNqc/V/i241CKtAVsNckesE0kcaka3VrY7ApXR+Va93YoEwVQ8gB9cE/eHH\n"
      -   "S0j3ZS1PAVFM/qo4ZnPdMzaSLvTQw0GAL90wWgF3XQ+feMnWyBObEoQdGXE828TB\n"
      -   "SLz4UOIQ55Dx6JSWTfEhwAlPs2cEWD14xvuxPzAEzBIYmWmBBsCN94YgFeRTzjH0\n"
      -   "TImoYVMN60GgOfZWw6rXq9RaV5dY0Y6F1piypCLGD35VaXAutdHIDvwUGECPm7SN\n"
      -   "w05jRro53E1vb4mYlZEY/bs4q7XEOI5+ZKT76Xn0oEJNX1KRL1h2q8fgUkm5j40M\n"
      -   "uQj71aLR9KyIoQARwGLeRy09tLVjH3fj66CCMqaPcxcIRIyWi5yYBB0s53ipm6A9\n"
      -   "CYuyc7MS2C0pOdWKsDvYsHR/36KUiIdPuhF4AbaTqqO0eWeuP7Na7dGK56Fl+ooi\n"
      -   "cUpJr7cIqMl2vL25B0jW7d4TB3zwCEkVVD1fBPeNoZWo30z4bILcBqjjPkQfHZ2e\n"
      -   "xNraG3qI4FHjoPT8JEE8p+PgwaMoINlICyIMKiCdvwz9yEnsHPy7FkmatpS+jFoS\n"
      -   "mg8R9vMwgK/HGEm0dmb/7/a0XsG2jCDm6cOmJdZJFQ8JW7hFs3eOHpNlQYDChG2D\n"
      -   "A1ExslqBtbpicywTZhzFdYU/hxeCr4UqcY27Zmhr4JlBPMyvadWKeOqCamWepjbT\n"
      -   "T/MhWJbmWgZbI5s5sbpu7cOYubQcUIEsTaQXGx/KEzGo1HLn9tzSeQfP/nqjAD/L\n"
      -   "T5t1Mb8o4LuV/fGIT33Q3i2FospJMqp2JINNzG18I6Fjo08PTvJ3row40Rb76+lJ\n"
      -   "wN1IBthgBgsgsOdB6XNc56sV+uq2TACsNNWw+JnFRCkCQgfF/KUrvN+WireWq88B\n"
      -   "9UPG+Hbans5A6K+y1a+bzfdYnKws7x8wNRyPxb7Vb2t9ZTl5PBorPLVGsjgf9N5X\n"
      -   "tCdBlfJsUdXot+EOxrIczV5zx0JIB1Y9hrDG07RYkzPuJKxkW7skqeLo8oWGVpaQ\n"
      -   "LGWvuebky1R75hcSuL3e4QHfjBHPdQ31fScB884tqkbhBAWr2nT9bYEmyT170bno\n"
      -   "8QkyOSb99xZBX55sLDHs9p61sTJr2C9Lz/KaWQs+3hTkpwSjSRyjEMH2n491qiQX\n"
      -   "G+kvLEnvtR8sl9zinorj/RfsxyPntAxudfY3qaYUu2QkLvVdfTVUVbxS/Fg8f7B3\n"
      -   "hEjCtpKgFjPxQuHE3didNOr5xM7mkmLN/QA7yHVgdpE64T5mFgC3JcVRpcR7zBPH\n"
      -   "3OeXHgjrhDfN8UIX/cq6gNgD8w7O0rhHa3mEXI1xP14ykPcJ7wlRuLm9P3fwx5A2\n"
      -   "jQrVKJKw1Nzummmspn4VOpJY3LkH4Sxo4e7Soo1l1cxJpzmERwgMF+vGz1L70+DG\n"
      -   "M0hVrz1PxlOsBBFgcdS4TB91DIs/RcFDqrJ4gOPNKCgBP+rgTXXLFcxUwJfE3lKg\n"
      -   "Kmpwdne6FuQYX3eyRVAmPgOHbJuRQCh/V4fYo51UxCcEKeKy6UgOPEJlXksWGbH5\n"
      -   "VFmlytYW6dFKJvjltSmK6L2r+TlyEQoXwTqe4bkfhB2LniDEq28hKQ==\n"
      -   "-----END RSA PRIVATE KEY-----\n";
      -
      -const char *pub = "-----BEGIN PUBLIC KEY-----\n"
      -   "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA2b1bXDa+S8/MGWnMkru4\n"
      -   "T4tUddtZNi0NVjQn9RFH1NMa220GsRhRO56F77FlSVFKfSfVZKIiWg6C+DVCkcLf\n"
      -   "zXJ/Z0pvwOQYBAqVMFjV6efQGN0JzJ1Unu7pPRiZl7RKGEI+cyzzrcDyrLLrQ2W7\n"
      -   "0ZySkNEOv6Frx9JgC5NExuYY4lk2fQQa38JXiZkfyzif2em0px7mXbyf5LjccsKq\n"
      -   "v1e+XLtMsL0ZefRcqsP++NzQAI8fKX7WBT+qK0HJDLiHrKOTWYzx6CwJ66LD/vvf\n"
      -   "j55xtsKDLVDbsotvf8/m6VLMab+vqKk11TP4tq6yo0mwyTADvgl1zowQEO9I1W6o\n"
      -   "zQIDAQAB\n"
      -   "-----END PUBLIC KEY-----\n";
      -pubkey.raw_key = (unsigned char *)pub;
      -pubkey.key_size = strlen(pub);
      -pubkey.key_type = CKMC_KEY_NONE;
      -pubkey.password = NULL;
      -
      -pubpolicy.password = pub_passwd;
      -pubpolicy.extractable = false;
      -
      -pripolicy.password = pri_passwd;
      -pripolicy.extractable = true;
      -
      -prikey.raw_key = (unsigned char *)prv;
      -prikey.key_size = strlen(prv);
      -prikey.key_type = CKMC_KEY_NONE;
      -prikey.password = key_passwd; // The private key, prv, is encrypted with the key_password
      -
      -ret = ckmc_save_key(pri_alias, prikey, pripolicy);
      -if (CKMC_ERROR_NONE != ret)
      -{
      -   // Error handling
      -}
      -
      -ret = ckmc_save_key(pub_alias, pubkey, pubpolicy);
      -if (CKMC_ERROR_NONE != ret)
      -{
      -   // Error handling
      -}
      -
    2. - -
    3. Create and verify the signature: -
        -
      • Create and verify using a hash algorithm: -
        -int ret = CKMC_ERROR_NONE;
        -
        -const char *message = "message test";
        -ckmc_raw_buffer_s msg_buff;
        -ckmc_raw_buffer_s *signature;
        -ckmc_hash_algo_e hash_algo = CKMC_HASH_SHA256;
        -ckmc_rsa_padding_algo_e pad_algo = CKMC_PKCS1_PADDING;
        -
        -const char *pub_alias = "pub1";
        -const char *pri_alias = "prv1";
        -char *pri_passwd = NULL;
        -char *pub_passwd = NULL;
        -
        -msg_buff.data = (unsigned char *)message;
        -msg_buff.size = strlen(message);
        -
        -ret = ckmc_create_signature (pri_alias, pri_passwd, msg_buff, hash_algo, pad_algo, &signature);
        -if (CKMC_ERROR_NONE != ret)
        -{
        -   // Error handling
        -}
        -
        -ret = ckmc_verify_signature (pub_alias, pub_passwd, msg_buff, *signature, hash_algo, pad_algo);
        -if (CKMC_ERROR_NONE != ret)
        -{
        -   // Error handling
        -}
        -
      • - -
      • Create and verify without a hash algorithm: -
        -int ret = CKMC_ERROR_NONE;
        -
        -const char *message = "message test";
        -ckmc_raw_buffer_s msg_buff;
        -ckmc_raw_buffer_s *signature;
        -ckmc_hash_algo_e hash_algo = CKMC_HASH_NONE; // Do not use a hash algorithm 
        -ckmc_rsa_padding_algo_e pad_algo = CKMC_PKCS1_PADDING;
        -
        -const char *pub_alias = "pub1";
        -const char *pri_alias = "prv1";
        -char *pri_passwd = NULL;
        -char *pub_passwd = NULL;
        -
        -msg_buff.data = (unsigned char *)message;
        -msg_buff.size = strlen(message);
        -
        -ret = ckmc_create_signature (pri_alias, pri_passwd, msg_buff, hash_algo, pad_algo, &signature);
        -if (CKMC_ERROR_NONE != ret)
        -{
        -   // Error handling
        -}
        -
        -ret = ckmc_verify_signature (pub_alias, pub_passwd, msg_buff, *signature, hash_algo, pad_algo);
        -if (CKMC_ERROR_NONE != ret)
        -{
        -   // Error handling
        -}
        -
      • -
      -
    - -

    Verifying or Getting a Certificate Chain

    - -

    To verify and get a certificate chain using raw certificates or a certificate alias for untrusted certificates:

    -
    • Get a certificate chain with raw certificates.

      -

      The key manager verifies a certificate chain and returns it. The trusted root certificate of the chain must exist in the system certificate storage.

      -
      -int ret = CKMC_ERROR_NONE;
      -
      -ckmc_cert_s c_cert; // For a user certificate
      -ckmc_cert_s c_cert1; // For an intermediate untrusted CA certificate
      -ckmc_cert_list_s untrustedcerts; // Linked list of untrusted CA certificate
      -ckmc_cert_list_s *cert_chain_list; // Linked list of a certificate chain
      -
      -int cnt = 0;
      -ckmc_cert_list_s *current;
      -ckmc_cert_list_s *next;
      -
      -const char * ee =
      -"-----BEGIN CERTIFICATE-----\n"
      -"MIIF0TCCBLmgAwIBAgIQaPGTP4aS7Ut/WDNaBzdQrDANBgkqhkiG9w0BAQUFADCB\n"
      -"ujELMAkGA1UEBhMCVVMxFzAVBgNVBAoTDlZlcmlTaWduLCBJbmMuMR8wHQYDVQQL\n"
      -"ExZWZXJpU2lnbiBUcnVzdCBOZXR3b3JrMTswOQYDVQQLEzJUZXJtcyBvZiB1c2Ug\n"
      -"YXQgaHR0cHM6Ly93d3cudmVyaXNpZ24uY29tL3JwYSAoYykwNjE0MDIGA1UEAxMr\n"
      -"VmVyaVNpZ24gQ2xhc3MgMyBFeHRlbmRlZCBWYWxpZGF0aW9uIFNTTCBDQTAeFw0x\n"
      -"NDAyMjAwMDAwMDBaFw0xNTAyMjAyMzU5NTlaMIHmMRMwEQYLKwYBBAGCNzwCAQMT\n"
      -"AlBMMR0wGwYDVQQPExRQcml2YXRlIE9yZ2FuaXphdGlvbjETMBEGA1UEBRMKMDAw\n"
      -"MDAyNTIzNzELMAkGA1UEBhMCUEwxDzANBgNVBBEUBjAwLTk1MDEUMBIGA1UECBML\n"
      -"bWF6b3dpZWNraWUxETAPBgNVBAcUCFdhcnN6YXdhMRYwFAYDVQQJFA1TZW5hdG9y\n"
      -"c2thIDE4MRMwEQYDVQQKFAptQmFuayBTLkEuMQwwCgYDVQQLFANESU4xGTAXBgNV\n"
      -"BAMUEHd3dy5tYmFuay5jb20ucGwwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEK\n"
      -"AoIBAQDph6x8V6xUW/+651+qHF+UmorH9uaz2ZrX2bIWiMKIJFmpDDHlxcapKkqE\n"
      -"BV04is83aiCpqKtc2ZHy2g4Hpj1eSF5BP2+OAlo0YUQZPIeRRdiMjmeAxw/ncBDx\n"
      -"9rQBuCJ4XTD6cqQox5SI0TASOZ+wyAEjbDRXzL73XqRAFZ1LOpb2ONkolS+RutMB\n"
      -"vshvCsWPeNe7eGLuOh6DyC6r1vX9xhw3xnjM2mTSvmtimgzSLacNGKqRrsucUgcb\n"
      -"0+O5C2jZAtAMLyZksL92cxmWbtVzUYzem4chjHu5cRxUlPNzUJWrrczueB7Ip4A8\n"
      -"aQuFMfNXYc0x+WLWjy//urypMKjhAgMBAAGjggGjMIIBnzAbBgNVHREEFDASghB3\n"
      -"d3cubWJhbmsuY29tLnBsMAkGA1UdEwQCMAAwDgYDVR0PAQH/BAQDAgWgMB0GA1Ud\n"
      -"JQQWMBQGCCsGAQUFBwMBBggrBgEFBQcDAjBEBgNVHSAEPTA7MDkGC2CGSAGG+EUB\n"
      -"BxcGMCowKAYIKwYBBQUHAgEWHGh0dHBzOi8vd3d3LnZlcmlzaWduLmNvbS9jcHMw\n"
      -"HQYDVR0OBBYEFN37iGaS7mZnENxZ9FGqNLR+QgoMMB8GA1UdIwQYMBaAFPyKULqe\n"
      -"uSVae1WFT5UAY4/pWGtDMEIGA1UdHwQ7MDkwN6A1oDOGMWh0dHA6Ly9FVlNlY3Vy\n"
      -"ZS1jcmwudmVyaXNpZ24uY29tL0VWU2VjdXJlMjAwNi5jcmwwfAYIKwYBBQUHAQEE\n"
      -"cDBuMC0GCCsGAQUFBzABhiFodHRwOi8vRVZTZWN1cmUtb2NzcC52ZXJpc2lnbi5j\n"
      -"b20wPQYIKwYBBQUHMAKGMWh0dHA6Ly9FVlNlY3VyZS1haWEudmVyaXNpZ24uY29t\n"
      -"L0VWU2VjdXJlMjAwNi5jZXIwDQYJKoZIhvcNAQEFBQADggEBAD0wO+rooUrIM4qp\n"
      -"PHhp+hkXK6WMQ2qzGOmbMcZjw0govg5vkzkefPDryIXXbrF8mRagiJNMSfNaWWeh\n"
      -"Cj41OV24EdUl0OLbFxNzcvub599zRs/apfaRLTfsmlmOgi0/YP305i+3tJ2ll946\n"
      -"P+qV1wXnXqTqEdIl4Ys3+1HmDCdTB1hoDwAAzqRVUXZ5+iiwPAU7R/LTHfMjV1ke\n"
      -"8jtNFfrorlZMCfVH/7eEnHJvVjOJt+YFe4aFMzE+DfuYIK7MH+olC2v79kBwbnEQ\n"
      -"fvHMA9gFwOYLUBBdSfcocp8EKZ+mRlNPGR/3LBrPeaQQ0GZEkxzRK+v/aNTuiYfr\n"
      -"oFXtrg0=\n"
      -"-----END CERTIFICATE-----\n";
      -
      -const char *im =
      -"-----BEGIN CERTIFICATE-----\n"
      -"MIIF5DCCBMygAwIBAgIQW3dZxheE4V7HJ8AylSkoazANBgkqhkiG9w0BAQUFADCB\n"
      -"yjELMAkGA1UEBhMCVVMxFzAVBgNVBAoTDlZlcmlTaWduLCBJbmMuMR8wHQYDVQQL\n"
      -"ExZWZXJpU2lnbiBUcnVzdCBOZXR3b3JrMTowOAYDVQQLEzEoYykgMjAwNiBWZXJp\n"
      -"U2lnbiwgSW5jLiAtIEZvciBhdXRob3JpemVkIHVzZSBvbmx5MUUwQwYDVQQDEzxW\n"
      -"ZXJpU2lnbiBDbGFzcyAzIFB1YmxpYyBQcmltYXJ5IENlcnRpZmljYXRpb24gQXV0\n"
      -"aG9yaXR5IC0gRzUwHhcNMDYxMTA4MDAwMDAwWhcNMTYxMTA3MjM1OTU5WjCBujEL\n"
      -"MAkGA1UEBhMCVVMxFzAVBgNVBAoTDlZlcmlTaWduLCBJbmMuMR8wHQYDVQQLExZW\n"
      -"ZXJpU2lnbiBUcnVzdCBOZXR3b3JrMTswOQYDVQQLEzJUZXJtcyBvZiB1c2UgYXQg\n"
      -"aHR0cHM6Ly93d3cudmVyaXNpZ24uY29tL3JwYSAoYykwNjE0MDIGA1UEAxMrVmVy\n"
      -"aVNpZ24gQ2xhc3MgMyBFeHRlbmRlZCBWYWxpZGF0aW9uIFNTTCBDQTCCASIwDQYJ\n"
      -"KoZIhvcNAQEBBQADggEPADCCAQoCggEBAJjboFXrnP0XeeOabhQdsVuYI4cWbod2\n"
      -"nLU4O7WgerQHYwkZ5iqISKnnnbYwWgiXDOyq5BZpcmIjmvt6VCiYxQwtt9citsj5\n"
      -"OBfH3doxRpqUFI6e7nigtyLUSVSXTeV0W5K87Gws3+fBthsaVWtmCAN/Ra+aM/EQ\n"
      -"wGyZSpIkMQht3QI+YXZ4eLbtfjeubPOJ4bfh3BXMt1afgKCxBX9ONxX/ty8ejwY4\n"
      -"P1C3aSijtWZfNhpSSENmUt+ikk/TGGC+4+peGXEFv54cbGhyJW+ze3PJbb0S/5tB\n"
      -"Ml706H7FC6NMZNFOvCYIZfsZl1h44TO/7Wg+sSdFb8Di7Jdp91zT91ECAwEAAaOC\n"
      -"AdIwggHOMB0GA1UdDgQWBBT8ilC6nrklWntVhU+VAGOP6VhrQzASBgNVHRMBAf8E\n"
      -"CDAGAQH/AgEAMD0GA1UdIAQ2MDQwMgYEVR0gADAqMCgGCCsGAQUFBwIBFhxodHRw\n"
      -"czovL3d3dy52ZXJpc2lnbi5jb20vY3BzMD0GA1UdHwQ2MDQwMqAwoC6GLGh0dHA6\n"
      -"Ly9FVlNlY3VyZS1jcmwudmVyaXNpZ24uY29tL3BjYTMtZzUuY3JsMA4GA1UdDwEB\n"
      -"/wQEAwIBBjARBglghkgBhvhCAQEEBAMCAQYwbQYIKwYBBQUHAQwEYTBfoV2gWzBZ\n"
      -"MFcwVRYJaW1hZ2UvZ2lmMCEwHzAHBgUrDgMCGgQUj+XTGoasjY5rw8+AatRIGCx7\n"
      -"GS4wJRYjaHR0cDovL2xvZ28udmVyaXNpZ24uY29tL3ZzbG9nby5naWYwKQYDVR0R\n"
      -"BCIwIKQeMBwxGjAYBgNVBAMTEUNsYXNzM0NBMjA0OC0xLTQ3MD0GCCsGAQUFBwEB\n"
      -"BDEwLzAtBggrBgEFBQcwAYYhaHR0cDovL0VWU2VjdXJlLW9jc3AudmVyaXNpZ24u\n"
      -"Y29tMB8GA1UdIwQYMBaAFH/TZafC3ey78DAJ80M5+gKvMzEzMA0GCSqGSIb3DQEB\n"
      -"BQUAA4IBAQCWovp/5j3t1CvOtxU/wHIDX4u6FpAl98KD2Md1NGNoElMMU4l7yVYJ\n"
      -"p8M2RE4O0GJis4b66KGbNGeNUyIXPv2s7mcuQ+JdfzOE8qJwwG6Cl8A0/SXGI3/t\n"
      -"5rDFV0OEst4t8dD2SB8UcVeyrDHhlyQjyRNddOVG7wl8nuGZMQoIeRuPcZ8XZsg4\n"
      -"z+6Ml7YGuXNG5NOUweVgtSV1LdlpMezNlsOjdv3odESsErlNv1HoudRETifLriDR\n"
      -"fip8tmNHnna6l9AW5wtsbfdDbzMLKTB3+p359U64drPNGLT5IO892+bKrZvQTtKH\n"
      -"qQ2mRHNQ3XBb7a1+Srwi1agm5MKFIA3Z\n"
      -"-----END CERTIFICATE-----\n";
      -
      -c_cert.raw_cert = (unsigned char *) ee;
      -c_cert.cert_size = strlen(ee);
      -c_cert.data_format = CKMC_FORM_PEM;
      -
      -c_cert1.raw_cert = (unsigned char *) im;
      -c_cert1.cert_size = strlen(im);
      -c_cert1.data_format = CKMC_FORM_PEM;
      -
      -untrustedcerts.cert = &c_cert1;
      -untrustedcerts.next = NULL;
      -
      -ret = ckmc_get_cert_chain(&c_cert, &untrustedcerts, &cert_chain_list);
      -if (CKMC_ERROR_NONE != ret)
      -{
      -   // Error handling
      -}
      -
      -next=cert_chain_list;
      -do
      -{
      -   current = next;
      -   next = current->next;
      -}
      -while(next != NULL);
      -
      -ckmc_cert_list_all_free(cert_chain_list); // Called when the list is no longer needed
      -
    • - -
    • Get a certificate chain with aliases of untrusted CA certificates.

      -

      The key manager verifies a certificate chain and returns it. The trusted root certificate of the chain must exist in the system certificate storage.

      -
      -int ret = CKMC_ERROR_NONE;
      -
      -char* password = NULL;
      -const char *ca_alias = "untrusted_ca_cert1";
      -ckmc_policy_s test_policy;
      -
      -ckmc_cert_s c_cert; // For a user certificate
      -ckmc_cert_s c_cert1; // For an intermediate untrusted CA certificate
      -ckmc_alias_list_s untrustedcerts; // Linked list of untrusted CA certificate's alias
      -ckmc_cert_list_s *cert_chain_list; // Linked list of a certificate chain
      -
      -int cnt = 0;
      -ckmc_cert_list_s *current;
      -ckmc_cert_list_s *next;
      -
      -const char * ee =
      -"-----BEGIN CERTIFICATE-----\n"
      -"MIIF0TCCBLmgAwIBAgIQaPGTP4aS7Ut/WDNaBzdQrDANBgkqhkiG9w0BAQUFADCB\n"
      -"ujELMAkGA1UEBhMCVVMxFzAVBgNVBAoTDlZlcmlTaWduLCBJbmMuMR8wHQYDVQQL\n"
      -"ExZWZXJpU2lnbiBUcnVzdCBOZXR3b3JrMTswOQYDVQQLEzJUZXJtcyBvZiB1c2Ug\n"
      -"YXQgaHR0cHM6Ly93d3cudmVyaXNpZ24uY29tL3JwYSAoYykwNjE0MDIGA1UEAxMr\n"
      -"VmVyaVNpZ24gQ2xhc3MgMyBFeHRlbmRlZCBWYWxpZGF0aW9uIFNTTCBDQTAeFw0x\n"
      -"NDAyMjAwMDAwMDBaFw0xNTAyMjAyMzU5NTlaMIHmMRMwEQYLKwYBBAGCNzwCAQMT\n"
      -"AlBMMR0wGwYDVQQPExRQcml2YXRlIE9yZ2FuaXphdGlvbjETMBEGA1UEBRMKMDAw\n"
      -"MDAyNTIzNzELMAkGA1UEBhMCUEwxDzANBgNVBBEUBjAwLTk1MDEUMBIGA1UECBML\n"
      -"bWF6b3dpZWNraWUxETAPBgNVBAcUCFdhcnN6YXdhMRYwFAYDVQQJFA1TZW5hdG9y\n"
      -"c2thIDE4MRMwEQYDVQQKFAptQmFuayBTLkEuMQwwCgYDVQQLFANESU4xGTAXBgNV\n"
      -"BAMUEHd3dy5tYmFuay5jb20ucGwwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEK\n"
      -"AoIBAQDph6x8V6xUW/+651+qHF+UmorH9uaz2ZrX2bIWiMKIJFmpDDHlxcapKkqE\n"
      -"BV04is83aiCpqKtc2ZHy2g4Hpj1eSF5BP2+OAlo0YUQZPIeRRdiMjmeAxw/ncBDx\n"
      -"9rQBuCJ4XTD6cqQox5SI0TASOZ+wyAEjbDRXzL73XqRAFZ1LOpb2ONkolS+RutMB\n"
      -"vshvCsWPeNe7eGLuOh6DyC6r1vX9xhw3xnjM2mTSvmtimgzSLacNGKqRrsucUgcb\n"
      -"0+O5C2jZAtAMLyZksL92cxmWbtVzUYzem4chjHu5cRxUlPNzUJWrrczueB7Ip4A8\n"
      -"aQuFMfNXYc0x+WLWjy//urypMKjhAgMBAAGjggGjMIIBnzAbBgNVHREEFDASghB3\n"
      -"d3cubWJhbmsuY29tLnBsMAkGA1UdEwQCMAAwDgYDVR0PAQH/BAQDAgWgMB0GA1Ud\n"
      -"JQQWMBQGCCsGAQUFBwMBBggrBgEFBQcDAjBEBgNVHSAEPTA7MDkGC2CGSAGG+EUB\n"
      -"BxcGMCowKAYIKwYBBQUHAgEWHGh0dHBzOi8vd3d3LnZlcmlzaWduLmNvbS9jcHMw\n"
      -"HQYDVR0OBBYEFN37iGaS7mZnENxZ9FGqNLR+QgoMMB8GA1UdIwQYMBaAFPyKULqe\n"
      -"uSVae1WFT5UAY4/pWGtDMEIGA1UdHwQ7MDkwN6A1oDOGMWh0dHA6Ly9FVlNlY3Vy\n"
      -"ZS1jcmwudmVyaXNpZ24uY29tL0VWU2VjdXJlMjAwNi5jcmwwfAYIKwYBBQUHAQEE\n"
      -"cDBuMC0GCCsGAQUFBzABhiFodHRwOi8vRVZTZWN1cmUtb2NzcC52ZXJpc2lnbi5j\n"
      -"b20wPQYIKwYBBQUHMAKGMWh0dHA6Ly9FVlNlY3VyZS1haWEudmVyaXNpZ24uY29t\n"
      -"L0VWU2VjdXJlMjAwNi5jZXIwDQYJKoZIhvcNAQEFBQADggEBAD0wO+rooUrIM4qp\n"
      -"PHhp+hkXK6WMQ2qzGOmbMcZjw0govg5vkzkefPDryIXXbrF8mRagiJNMSfNaWWeh\n"
      -"Cj41OV24EdUl0OLbFxNzcvub599zRs/apfaRLTfsmlmOgi0/YP305i+3tJ2ll946\n"
      -"P+qV1wXnXqTqEdIl4Ys3+1HmDCdTB1hoDwAAzqRVUXZ5+iiwPAU7R/LTHfMjV1ke\n"
      -"8jtNFfrorlZMCfVH/7eEnHJvVjOJt+YFe4aFMzE+DfuYIK7MH+olC2v79kBwbnEQ\n"
      -"fvHMA9gFwOYLUBBdSfcocp8EKZ+mRlNPGR/3LBrPeaQQ0GZEkxzRK+v/aNTuiYfr\n"
      -"oFXtrg0=\n"
      -"-----END CERTIFICATE-----\n";
      -
      -const char *im =
      -"-----BEGIN CERTIFICATE-----\n"
      -"MIIF5DCCBMygAwIBAgIQW3dZxheE4V7HJ8AylSkoazANBgkqhkiG9w0BAQUFADCB\n"
      -"yjELMAkGA1UEBhMCVVMxFzAVBgNVBAoTDlZlcmlTaWduLCBJbmMuMR8wHQYDVQQL\n"
      -"ExZWZXJpU2lnbiBUcnVzdCBOZXR3b3JrMTowOAYDVQQLEzEoYykgMjAwNiBWZXJp\n"
      -"U2lnbiwgSW5jLiAtIEZvciBhdXRob3JpemVkIHVzZSBvbmx5MUUwQwYDVQQDEzxW\n"
      -"ZXJpU2lnbiBDbGFzcyAzIFB1YmxpYyBQcmltYXJ5IENlcnRpZmljYXRpb24gQXV0\n"
      -"aG9yaXR5IC0gRzUwHhcNMDYxMTA4MDAwMDAwWhcNMTYxMTA3MjM1OTU5WjCBujEL\n"
      -"MAkGA1UEBhMCVVMxFzAVBgNVBAoTDlZlcmlTaWduLCBJbmMuMR8wHQYDVQQLExZW\n"
      -"ZXJpU2lnbiBUcnVzdCBOZXR3b3JrMTswOQYDVQQLEzJUZXJtcyBvZiB1c2UgYXQg\n"
      -"aHR0cHM6Ly93d3cudmVyaXNpZ24uY29tL3JwYSAoYykwNjE0MDIGA1UEAxMrVmVy\n"
      -"aVNpZ24gQ2xhc3MgMyBFeHRlbmRlZCBWYWxpZGF0aW9uIFNTTCBDQTCCASIwDQYJ\n"
      -"KoZIhvcNAQEBBQADggEPADCCAQoCggEBAJjboFXrnP0XeeOabhQdsVuYI4cWbod2\n"
      -"nLU4O7WgerQHYwkZ5iqISKnnnbYwWgiXDOyq5BZpcmIjmvt6VCiYxQwtt9citsj5\n"
      -"OBfH3doxRpqUFI6e7nigtyLUSVSXTeV0W5K87Gws3+fBthsaVWtmCAN/Ra+aM/EQ\n"
      -"wGyZSpIkMQht3QI+YXZ4eLbtfjeubPOJ4bfh3BXMt1afgKCxBX9ONxX/ty8ejwY4\n"
      -"P1C3aSijtWZfNhpSSENmUt+ikk/TGGC+4+peGXEFv54cbGhyJW+ze3PJbb0S/5tB\n"
      -"Ml706H7FC6NMZNFOvCYIZfsZl1h44TO/7Wg+sSdFb8Di7Jdp91zT91ECAwEAAaOC\n"
      -"AdIwggHOMB0GA1UdDgQWBBT8ilC6nrklWntVhU+VAGOP6VhrQzASBgNVHRMBAf8E\n"
      -"CDAGAQH/AgEAMD0GA1UdIAQ2MDQwMgYEVR0gADAqMCgGCCsGAQUFBwIBFhxodHRw\n"
      -"czovL3d3dy52ZXJpc2lnbi5jb20vY3BzMD0GA1UdHwQ2MDQwMqAwoC6GLGh0dHA6\n"
      -"Ly9FVlNlY3VyZS1jcmwudmVyaXNpZ24uY29tL3BjYTMtZzUuY3JsMA4GA1UdDwEB\n"
      -"/wQEAwIBBjARBglghkgBhvhCAQEEBAMCAQYwbQYIKwYBBQUHAQwEYTBfoV2gWzBZ\n"
      -"MFcwVRYJaW1hZ2UvZ2lmMCEwHzAHBgUrDgMCGgQUj+XTGoasjY5rw8+AatRIGCx7\n"
      -"GS4wJRYjaHR0cDovL2xvZ28udmVyaXNpZ24uY29tL3ZzbG9nby5naWYwKQYDVR0R\n"
      -"BCIwIKQeMBwxGjAYBgNVBAMTEUNsYXNzM0NBMjA0OC0xLTQ3MD0GCCsGAQUFBwEB\n"
      -"BDEwLzAtBggrBgEFBQcwAYYhaHR0cDovL0VWU2VjdXJlLW9jc3AudmVyaXNpZ24u\n"
      -"Y29tMB8GA1UdIwQYMBaAFH/TZafC3ey78DAJ80M5+gKvMzEzMA0GCSqGSIb3DQEB\n"
      -"BQUAA4IBAQCWovp/5j3t1CvOtxU/wHIDX4u6FpAl98KD2Md1NGNoElMMU4l7yVYJ\n"
      -"p8M2RE4O0GJis4b66KGbNGeNUyIXPv2s7mcuQ+JdfzOE8qJwwG6Cl8A0/SXGI3/t\n"
      -"5rDFV0OEst4t8dD2SB8UcVeyrDHhlyQjyRNddOVG7wl8nuGZMQoIeRuPcZ8XZsg4\n"
      -"z+6Ml7YGuXNG5NOUweVgtSV1LdlpMezNlsOjdv3odESsErlNv1HoudRETifLriDR\n"
      -"fip8tmNHnna6l9AW5wtsbfdDbzMLKTB3+p359U64drPNGLT5IO892+bKrZvQTtKH\n"
      -"qQ2mRHNQ3XBb7a1+Srwi1agm5MKFIA3Z\n"
      -"-----END CERTIFICATE-----\n";
      -
      -c_cert.raw_cert = (unsigned char *) ee;
      -c_cert.cert_size = strlen(ee);
      -c_cert.data_format = CKMC_FORM_PEM;
      -
      -c_cert1.raw_cert = (unsigned char *) im;
      -c_cert1.cert_size = strlen(im);
      -c_cert1.data_format = CKMC_FORM_PEM;
      -
      -test_policy.password = password;
      -test_policy.extractable = true;
      -
      -ret = ckmc_save_cert(ca_alias, c_cert1, test_policy);
      -if (CKMC_ERROR_NONE != ret)
      -{
      -   // Error handling
      -}
      -
      -untrustedcerts.alias = (char *)ca_alias;
      -untrustedcerts.next = NULL;
      -
      -ret = ckmc_get_cert_chain_with_alias(&c_cert, &untrustedcerts, &cert_chain_list);
      -if (CKMC_ERROR_NONE != ret)
      -{
      -   // Error handling
      -}
      -
      -next=cert_chain_list;
      -do
      -{
      -   current = next;
      -   next = current->next;
      -}
      -while(next != NULL);
      -
      -ckmc_cert_list_all_free(cert_chain_list); // Called when the list is no longer needed
      -
    - -

    Loading a Certificate or a PKCS#12 File

    - -

    To load certificates (from a file with the DER or PEM format) or a private key, a certificate, or CA certificates (from a PKCS#12 file):

    - -
    • Load from a certificate file.

      -
      -int ret = CKMC_ERROR_NONE;
      -
      -ckmc_cert_s *pcert;
      -// defined_media_storage_directory can be obtained with the storage_get_directory() function
      -const char *file_name = "<defined_media_storage_directory>/ckmc_test_cert.pem"; 
      -
      -ret = ckmc_load_cert_from_file(file_name, &pcert);
      -if (CKMC_ERROR_NONE != ret)
      -{
      -   // Error handling
      -}
      -
      -dlog_print(DLOG_INFO, LOG_TAG, "cert size =%d\n", pcert->cert_size);
      -
      -ckmc_cert_free(pcert); // Called when the certificate is no longer needed
      -
    • - -
    • Load from a PKCS#12 file.

      -
      -int ret = CKMC_ERROR_NONE;
      -
      -ckmc_key_s *private_key = NULL;
      -ckmc_cert_s *cert = NULL;
      -ckmc_cert_list_s *ca_cert_list = NULL;
      -// defined_media_storage_directory can be obtained with the storage_get_directory() function
      -const char *p12file = "<defined_media_storage_directory>/ckmc_p12_test.p12"; 
      -const char *password = "password";  // PKCS#12 file can be protected by a password
      -
      -ret = ckmc_load_from_pkcs12_file(p12file, password, &private_key, &cert, &ca_cert_list);
      -if (CKMC_ERROR_NONE != ret)
      -{
      -   // Error handling
      -}
      -
      -if (private_key != NULL)
      -{
      -   // Check a private key
      -}
      -
      -if (cert != NULL)
      -{
      -   // Check a certificate
      -
      -}
      -
      -int cnt = 0;
      -ckmc_cert_list_s *tmp_list = ca_cert_list;
      -while(tmp_list!= NULL)
      -{
      -   // Check a certificate list
      -
      -   tmp_list = tmp_list ->next;
      -}
      -
      -ckmc_key_free(private_key); // Called when the key is no longer needed
      -ckmc_cert_free(cert); // Called when the certificate is no longer needed
      -ckmc_cert_list_all_free(ca_cert_list); // Called when the list is no longer needed
      -
    - -

    Implementing Access Control

    - -

    To implement access control rules for each individual client's data, certificates, and keys:

    - -
    1. Store test data:

      -
      -int ret = CKMC_ERROR_NONE;
      -
      -char* password = NULL;
      -ckmc_raw_buffer_s test_data;
      -const char *alias = "targetData";
      -ckmc_policy_s test_policy;
      -
      -const char *char_bin_data = "Access control test Data";
      -
      -test_policy.password = password;
      -test_policy.extractable = true;
      -
      -test_data.data = (unsigned char *) char_bin_data;
      -test_data.size = strlen(char_bin_data);
      -ret = ckmc_save_data(alias, test_data, test_policy);
      -if (CKMC_ERROR_NONE != ret)
      -
      -{
      -   // Error handling
      -}
      -
    2. - -
    3. Set a rule to allow access:

      -
      -int ret = CKMC_ERROR_NONE;
      -
      -const char *target1 = "accessor-allow-1";
      -const char *target2 = "accessor-allow-2";
      -const char *alias = "targetData";
      -
      -ret = ckmc_allow_access(alias, target1, CKMC_AR_READ); // Only allow reading data
      -if (CKMC_ERROR_NONE != ret)
      -{
      -   // Error handling
      -}
      -
      -ret = ckmc_allow_access(alias, target2, CKMC_AR_READ_REMOVE); // Allow reading and deleting data
      -if (CKMC_ERROR_NONE != ret)
      -{
      -   // Error handling
      -}
      -
    4. - -
    5. Set a rule to deny access:

      -
      -int ret = CKMC_ERROR_NONE;
      -
      -const char *target = "denied-accessor";
      -const char *alias = "targetData";
      -
      -ret = ckmc_allow_access(alias, target, CKMC_AR_READ); // Allow the target user to a read (alias)
      -if (CKMC_ERROR_NONE != ret)
      -{
      -   // Error handling
      -}
      -
      -ret = ckmc_deny_access(alias, target); // Deny the target user access to data (alias)
      -if (CKMC_ERROR_NONE != ret)
      -
      -{
      -   // Error handling
      -}
      -
    6. -
    - - - - -
    - -Go to top - - - - - - + + + + + + + + + + + + + Key Manager: Using Keys and Certificates, and Implementing Access Control + + + + + + +
    +

    Key Manager: Using Keys and Certificates, and Implementing Access Control

    + + +

    This tutorial demonstrates how you can use the key manager to create a secure repository for keys, certificates, and sensitive data.

    + + +

    Warm-up

    +

    Become familiar with the Key Manager API basics by learning about:

    + + +

    Initializing the Key Manager

    + +

    To define the header file and privileges required to use the key manager:

    +
      +
    1. To use the Key Manager privileged API, declare the http://tizen.org/privilege/keymanager privilege in the manifest.xml file of the application package.

    2. +
    3. To use the functions and data types of the Key Manager API (in mobile and wearable applications), include the <ckmc/ckmc-manager.h> header file in your application:

      +
      +#include <ckmc/ckmc-manager.h>
      +
    + +

    Saving, Getting, or Removing a Key

    + +

    To store, remove, and retrieve client keys from the key manager:

    + +
    1. Store a new key. +
      +int ret = CKMC_ERROR_NONE;
      +
      +ckmc_key_s test_key;
      +ckmc_policy_s store_policy;
      +char* alias= "mykey";
      +char* key_password = NULL;
      +
      +char* binary_key = "-----BEGIN PUBLIC KEY-----\n"
      +   "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA2b1bXDa+S8/MGWnMkru4\n"
      +   "T4tUddtZNi0NVjQn9RFH1NMa220GsRhRO56F77FlSVFKfSfVZKIiWg6C+DVCkcLf\n"
      +   "zXJ/Z0pvwOQYBAqVMFjV6efQGN0JzJ1Unu7pPRiZl7RKGEI+cyzzrcDyrLLrQ2W7\n"
      +   "0ZySkNEOv6Frx9JgC5NExuYY4lk2fQQa38JXiZkfyzif2em0px7mXbyf5LjccsKq\n"
      +   "v1e+XLtMsL0ZefRcqsP++NzQAI8fKX7WBT+qK0HJDLiHrKOTWYzx6CwJ66LD/vvf\n"
      +   "j55xtsKDLVDbsotvf8/m6VLMab+vqKk11TP4tq6yo0mwyTADvgl1zowQEO9I1W6o\n"
      +   "zQIDAQAB\n"
      +   "-----END PUBLIC KEY-----";
      +
      +test_key.raw_key =  (unsigned char *) binary_key;
      +test_key.key_size = strlen(binary_key);
      +test_key.key_type = CKMC_KEY_NONE; // The real key type is determined by the key manager
      +test_key.password = NULL; // This means the binary_key is not encrypted with any password
      +
      +store_policy.password = key_password; // NULL means that the test_key is not encrypted with a per key password
      +store_policy.extractable = true; // This means that the key value is extractable
      +
      +ret = ckmc_save_key(alias, test_key, store_policy);
      +if (CKMC_ERROR_NONE != ret)
      +{
      +   // Error handling
      +}
      +
    2. + +
    3. Get a key from the key manager. +
      +int ret = CKMC_ERROR_NONE;
      +
      +ckmc_key_s *test_key;
      +char* alias= "mykey";
      +char* key_password = NULL;
      +
      +ret = ckmc_get_key(alias, key_password, &test_key);
      +if (CKMC_ERROR_NONE != ret)
      +{
      +   // Error handling
      +}
      +
      +dlog_print(DLOG_INFO, LOG_TAG, "key size =%d\n", test_key->key_size);
      +
      +ckmc_key_free(test_key); // Called when the key is no longer needed
      +
    4. + +
    5. Get the key alias list. +
      +int ret = CKMC_ERROR_NONE;
      +
      +ckmc_alias_list_s *alias_list;
      +ckmc_alias_list_s *plist;
      +ckmc_key_s *test_key;
      +char* key_password = NULL;
      +int count_list = 0;
      +
      +ret = ckmc_get_key_alias_list(&alias_list);
      +if (CKMC_ERROR_NONE != ret)
      +{
      +   // Error handling
      +}
      +
      +plist = alias_list;
      +do
      +{
      +   ckmc_get_key(plist->alias, key_password, &test_key);
      +   dlog_print(DLOG_INFO, LOG_TAG, "%d th key : key size =%d\n", ++count_list, test_key->key_size);
      +   ckmc_key_free(test_key);
      +   plist = plist->next;
      +}
      +while(plist != NULL);
      +
      +ckmc_alias_list_all_free(alias_list); // Called when the list is no longer needed.
      +
    6. +
    7. Remove the key. +
      +int ret = CKMC_ERROR_NONE;
      +
      +const char* alias= "mykey";
      +
      +ret = ckmc_remove_key(alias);
      +if (CKMC_ERROR_NONE != ret) 
      +{
      +   // Error handling
      +}
      +
    + +

    Saving, Getting, or Removing a Certificate

    + +

    To store, remove, or retrieve the client certificate from the key manager:

    + +
    1. Store a new certificate. +
      +int ret = CKMC_ERROR_NONE;
      +
      +char* password = NULL;
      +ckmc_cert_s cert;
      +const char *alias = "myCert";
      +ckmc_policy_s test_policy;
      +
      +const char *certPem = "-----BEGIN CERTIFICATE-----\n"
      +"MIIEgDCCA2igAwIBAgIIcjtBYJGQtOAwDQYJKoZIhvcNAQEFBQAwSTELMAkGA1UE\n"
      +"BhMCVVMxEzARBgNVBAoTCkdvb2dsZSBJbmMxJTAjBgNVBAMTHEdvb2dsZSBJbnRl\n"
      +"cm5ldCBBdXRob3JpdHkgRzIwHhcNMTQwNTIyMTEyOTQyWhcNMTQwODIwMDAwMDAw\n"
      +"WjBtMQswCQYDVQQGEwJVUzETMBEGA1UECAwKQ2FsaWZvcm5pYTEWMBQGA1UEBwwN\n"
      +"TW91bnRhaW4gVmlldzETMBEGA1UECgwKR29vZ2xlIEluYzEcMBoGA1UEAwwTYWNj\n"
      +"b3VudHMuZ29vZ2xlLmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEB\n"
      +"ALtlLWVWPN3q3bSEQl1Z97gPdgl5vbgJOZSAr0ZY0tJCuFLBbUKetJWryyE+5KpG\n"
      +"gMMpLS4v8/bvXaZc6mAs+RfAqGM24C3vQg5hPnj4dflnhL0WiOCZBurm1tV4oexk\n"
      +"HLXs3jr/jpnb738AQpj8zZ9a4VEBuHJRZALnWZ/XhqU+dvYomAoRQNuL5OhkT7uu\n"
      +"d0NKJL9JjYLyQglGgE2sVsWv2kj7EO/P9Q6NEKt9BGmhMsFvtfeKUaymynaxpR1g\n"
      +"wEPlqYvB38goh1dIOgVLT0OVyLImeg5Mdwar/8c1U0OYhLOc6PJapOZAfUkE+3+w\n"
      +"xYt8AChLN1b5szOwInrCVpECAwEAAaOCAUYwggFCMB0GA1UdJQQWMBQGCCsGAQUF\n"
      +"BwMBBggrBgEFBQcDAjAeBgNVHREEFzAVghNhY2NvdW50cy5nb29nbGUuY29tMGgG\n"
      +"CCsGAQUFBwEBBFwwWjArBggrBgEFBQcwAoYfaHR0cDovL3BraS5nb29nbGUuY29t\n"
      +"L0dJQUcyLmNydDArBggrBgEFBQcwAYYfaHR0cDovL2NsaWVudHMxLmdvb2dsZS5j\n"
      +"b20vb2NzcDAdBgNVHQ4EFgQU0/UtToEtNIfwDwHuYGuVKcj0xK8wDAYDVR0TAQH/\n"
      +"BAIwADAfBgNVHSMEGDAWgBRK3QYWG7z2aLV29YG2u2IaulqBLzAXBgNVHSAEEDAO\n"
      +"MAwGCisGAQQB1nkCBQEwMAYDVR0fBCkwJzAloCOgIYYfaHR0cDovL3BraS5nb29n\n"
      +"bGUuY29tL0dJQUcyLmNybDANBgkqhkiG9w0BAQUFAAOCAQEAcGNI/X9f0g+7ij0o\n"
      +"ehLpk6vxSMQGrmOZ4+PG/MC9SLClCkt7zJkfU7erZnyVXyxCpwlljq+Wk9YTPUOq\n"
      +"xD/V2ikQVSAANoxGJFO9UoL5jzWusPhKKv8CcM7fuiERz8K+CfBcqfxbgI5rH0g5\n"
      +"dYclmLC81cJ/08i+9Nltvxv69Y3hGfEICT6K+EdSxwnQzOhpMZmvxZsIj+d6CVNa\n"
      +"9ICYgUthsNQVWzrIs5wknpjjZ9liDMwJX0vu8A0rce4X/Lna5hh2bW9igz2iP5WM\n"
      +"9fuwdbTw4y3jfPQgszU4YZxWxhMzccxe058Qx1tLndAknBQEBesQjXytVQpuM1SV\n"
      +"rHva8A==\n"
      +"-----END CERTIFICATE-----\n";
      +
      +test_policy.password = password;
      +test_policy.extractable = true;
      +
      +cert.raw_cert =  (unsigned char *) certPem;
      +cert.cert_size = strlen(certPem);
      +cert.data_format = CKMC_FORM_PEM;
      +
      +ret = ckmc_save_cert(alias, cert, test_policy);
      +if (CKMC_ERROR_NONE != ret)
      +{
      +   // Error handling
      +}
      +
    2. + +
    3. Get a certificate from the key manager. +
      +int ret = CKMC_ERROR_NONE;
      +
      +ckmc_cert_s *test_cert;
      +char* alias= "myCert";
      +char* password = NULL;
      +
      +ret = ckmc_get_cert(alias, password, &test_cert);
      +if (CKMC_ERROR_NONE != ret)
      +{
      +   // Error handling
      +}
      +
      +dlog_print(DLOG_INFO, LOG_TAG, "cert size =%d\n", test_cert->cert_size);
      +
      +ckmc_cert_free(test_cert); // Called when the certificate is no longer needed
      +
    4. +
    5. Get the certificate alias list. +
      +int ret = CKMC_ERROR_NONE;
      +
      +ckmc_alias_list_s *alias_list;
      +ckmc_alias_list_s *plist;
      +ckmc_cert_s *test_cert;
      +char* password = NULL;
      +int count_list = 0;
      +
      +ret = ckmc_get_cert_alias_list(&alias_list);
      +if (CKMC_ERROR_NONE != ret)
      +{
      +   // Error handling
      +}
      +
      +plist = alias_list;
      +do
      +{
      +   ckmc_get_cert(plist->alias, password, &test_cert);
      +   dlog_print(DLOG_INFO, LOG_TAG, "%d th cert : cert size =%d\n", ++count_list, test_cert->cert_size);
      +   ckmc_cert_free(test_cert);
      +   plist = plist->next;
      +}
      +while(plist != NULL);
      +
      +ckmc_alias_list_all_free(alias_list); // Called when the list is no longer needed
      +
    6. + +
    7. Remove the certificate. +
      +int ret = CKMC_ERROR_NONE;
      +
      +const char* alias= "myCert";
      +
      +ret = ckmc_remove_cert(alias);
      +if (CKMC_ERROR_NONE != ret)
      +{
      +   // Error handling
      +}
      +
    + +

    Saving, Getting, or Removing Data

    + +

    To store, remove, or retrieve client data on or from the key manager:

    + +
    1. Store new data. +
      +int ret = CKMC_ERROR_NONE;
      +
      +char* password = NULL;
      +ckmc_raw_buffer_s test_data;
      +const char *alias = "myData";
      +ckmc_policy_s test_policy;
      +
      +const char *char_bin_data = "My Binary Data";
      +
      +test_policy.password = password;
      +test_policy.extractable = true;
      +
      +test_data.data = (unsigned char *) char_bin_data;
      +test_data.size = strlen(char_bin_data);
      +ret = ckmc_save_data(alias, test_data, test_policy);
      +if (CKMC_ERROR_NONE != ret)
      +{
      +   // Error handling
      +}
      +
    2. + +
    3. Get data from the key manager. +
      +int ret = CKMC_ERROR_NONE;
      +
      +char* password = NULL;
      +ckmc_raw_buffer_s *test_data;
      +const char *alias = "myData";
      +
      +ret = ckmc_get_data(alias, password, &test_data);
      +if (CKMC_ERROR_NONE != ret)
      +{
      +   // Error handling
      +}
      +
      +dlog_print(DLOG_INFO, LOG_TAG, "data size =%d\n", test_data-> size);
      +
      +ckmc_buffer_free(test_data); // Called when the buffer is no longer needed
      +
    4. + +
    5. Get the data alias list. +
      +int ret = CKMC_ERROR_NONE;
      +
      +ckmc_alias_list_s *alias_list;
      +ckmc_alias_list_s *plist;
      +ckmc_raw_buffer_s *test_data;
      +char* password = NULL;
      +int count_list = 0;
      +
      +ret = ckmc_get_data_alias_list(&alias_list);
      +if (CKMC_ERROR_NONE != ret)
      +{
      +   // Error handling
      +}
      +
      +plist = alias_list;
      +do
      +{
      +   ckmc_get_data(plist->alias, password, &test_data);
      +   dlog_print(DLOG_INFO, LOG_TAG, "%d th data : data size =%d\n", ++count_list, test_data->size);
      +   ckmc_buffer_free(test_data);
      +   plist = plist->next;
      +}
      +while(plist != NULL);
      +
      +ckmc_alias_list_all_free(alias_list); // Called when the list is no longer needed
      +
    6. +
    7. Remove data. +
      +int ret = CKMC_ERROR_NONE;
      +
      +const char* alias= "myData";
      +
      +ret = ckmc_remove_data(alias);
      +if (CKMC_ERROR_NONE != ret)
      +{
      +   // Error handling
      +}
      +
    + +

    Creating Key Pairs

    + +

    To generate asymmetric key pairs - the RSA, ECDSA, or DSA key pair:

    + +
    • Create the RSA key pair:

      +
      +int ret = CKMC_ERROR_NONE;
      +
      +size_t size = 2048; // Key Manager supports 1024, 2048, 4096
      +const char *private_key_alias = "PRV_RSA1";
      +const char *public_key_alias = "PUB_RSA1";
      +ckmc_policy_s policy_private_key;
      +ckmc_policy_s policy_public_key;
      +
      +// This private key is encrypted with a password additionally
      +policy_private_key.password = (char *)"pri_password";
      +policy_private_key.extractable = false; // This key cannot be extracted from the key manager
      +
      +policy_public_key.password = NULL;
      +policy_public_key.extractable = true;
      +
      +ret = ckmc_create_key_pair_rsa(size, private_key_alias, public_key_alias, policy_private_key, policy_public_key);
      +if (CKMC_ERROR_NONE != ret)
      +{
      +   // Error handling
      +}
      +
    • + +
    • Create the ECDSA key pair:

      +
      +int ret = CKMC_ERROR_NONE;
      +
      +ckmc_ec_type_e ectype = CKMC_EC_PRIME192V1;
      +const char *private_key_alias = "PRV_ECDSA1";
      +const char *public_key_alias = "PUB_ECDSA1";
      +ckmc_policy_s policy_private_key;
      +ckmc_policy_s policy_public_key;
      +
      +// This private key is encrypted with the password additionally
      +policy_private_key.password = (char *)"pri_password";
      +policy_private_key.extractable = false; // This key cannot be extracted from the key manager
      +
      +policy_public_key.password = NULL;
      +policy_public_key.extractable = true;
      +
      +ret = ckmc_create_key_pair_ecdsa(ectype, private_key_alias, public_key_alias, policy_private_key, policy_public_key);
      +if (CKMC_ERROR_NONE != ret)
      +{
      +   // Error handling
      +}
      +
    • + +
    • Create the DSA key pair:

      +
      +int ret = CKMC_ERROR_NONE;
      +
      +size_t size = 1024;
      +const char *private_key_alias = "PRV_DSA1";
      +const char *public_key_alias = "PUB-DSA1";
      +ckmc_policy_s policy_private_key;
      +ckmc_policy_s policy_public_key;
      +
      +// This private key is encrypted with a password additionally
      +policy_private_key.password = (char *)"pri_password";
      +policy_private_key.extractable = false;
      +
      +policy_public_key.password = NULL;
      +policy_public_key.extractable = true;
      +
      +ret = ckmc_create_key_pair_dsa(size, private_key_alias, public_key_alias, policy_private_key, policy_public_key);
      +if (CKMC_ERROR_NONE != ret)
      +
      +{
      +   // Error handling
      +}
      +
    + +

    Creating or Verifying Signatures

    + +

    To create or verify signatures:

    +
    1. Store a private and public key. +
      +int ret = CKMC_ERROR_NONE;
      +
      +const char *pub_alias = "pub1";
      +const char *pri_alias = "prv1";
      +char *key_passwd = (char *) "1234";
      +char *pri_passwd = NULL;
      +char *pub_passwd = NULL;
      +ckmc_hash_algo_e hash_algo = CKMC_HASH_SHA256;
      +ckmc_rsa_padding_algo_e pad_algo = CKMC_PKCS1_PADDING;
      +ckmc_raw_buffer_s *signature;
      +
      +ckmc_key_s pubkey;
      +ckmc_policy_s pubpolicy;
      +ckmc_key_s prikey;
      +ckmc_policy_s pripolicy;
      +
      +const char *prv = "-----BEGIN RSA PRIVATE KEY-----\n"
      +   "Proc-Type: 4,ENCRYPTED\n"
      +   "DEK-Info: DES-EDE3-CBC,6C6507B11671DABC\n"
      +   "\n"
      +   "YiKNviNqc/V/i241CKtAVsNckesE0kcaka3VrY7ApXR+Va93YoEwVQ8gB9cE/eHH\n"
      +   "S0j3ZS1PAVFM/qo4ZnPdMzaSLvTQw0GAL90wWgF3XQ+feMnWyBObEoQdGXE828TB\n"
      +   "SLz4UOIQ55Dx6JSWTfEhwAlPs2cEWD14xvuxPzAEzBIYmWmBBsCN94YgFeRTzjH0\n"
      +   "TImoYVMN60GgOfZWw6rXq9RaV5dY0Y6F1piypCLGD35VaXAutdHIDvwUGECPm7SN\n"
      +   "w05jRro53E1vb4mYlZEY/bs4q7XEOI5+ZKT76Xn0oEJNX1KRL1h2q8fgUkm5j40M\n"
      +   "uQj71aLR9KyIoQARwGLeRy09tLVjH3fj66CCMqaPcxcIRIyWi5yYBB0s53ipm6A9\n"
      +   "CYuyc7MS2C0pOdWKsDvYsHR/36KUiIdPuhF4AbaTqqO0eWeuP7Na7dGK56Fl+ooi\n"
      +   "cUpJr7cIqMl2vL25B0jW7d4TB3zwCEkVVD1fBPeNoZWo30z4bILcBqjjPkQfHZ2e\n"
      +   "xNraG3qI4FHjoPT8JEE8p+PgwaMoINlICyIMKiCdvwz9yEnsHPy7FkmatpS+jFoS\n"
      +   "mg8R9vMwgK/HGEm0dmb/7/a0XsG2jCDm6cOmJdZJFQ8JW7hFs3eOHpNlQYDChG2D\n"
      +   "A1ExslqBtbpicywTZhzFdYU/hxeCr4UqcY27Zmhr4JlBPMyvadWKeOqCamWepjbT\n"
      +   "T/MhWJbmWgZbI5s5sbpu7cOYubQcUIEsTaQXGx/KEzGo1HLn9tzSeQfP/nqjAD/L\n"
      +   "T5t1Mb8o4LuV/fGIT33Q3i2FospJMqp2JINNzG18I6Fjo08PTvJ3row40Rb76+lJ\n"
      +   "wN1IBthgBgsgsOdB6XNc56sV+uq2TACsNNWw+JnFRCkCQgfF/KUrvN+WireWq88B\n"
      +   "9UPG+Hbans5A6K+y1a+bzfdYnKws7x8wNRyPxb7Vb2t9ZTl5PBorPLVGsjgf9N5X\n"
      +   "tCdBlfJsUdXot+EOxrIczV5zx0JIB1Y9hrDG07RYkzPuJKxkW7skqeLo8oWGVpaQ\n"
      +   "LGWvuebky1R75hcSuL3e4QHfjBHPdQ31fScB884tqkbhBAWr2nT9bYEmyT170bno\n"
      +   "8QkyOSb99xZBX55sLDHs9p61sTJr2C9Lz/KaWQs+3hTkpwSjSRyjEMH2n491qiQX\n"
      +   "G+kvLEnvtR8sl9zinorj/RfsxyPntAxudfY3qaYUu2QkLvVdfTVUVbxS/Fg8f7B3\n"
      +   "hEjCtpKgFjPxQuHE3didNOr5xM7mkmLN/QA7yHVgdpE64T5mFgC3JcVRpcR7zBPH\n"
      +   "3OeXHgjrhDfN8UIX/cq6gNgD8w7O0rhHa3mEXI1xP14ykPcJ7wlRuLm9P3fwx5A2\n"
      +   "jQrVKJKw1Nzummmspn4VOpJY3LkH4Sxo4e7Soo1l1cxJpzmERwgMF+vGz1L70+DG\n"
      +   "M0hVrz1PxlOsBBFgcdS4TB91DIs/RcFDqrJ4gOPNKCgBP+rgTXXLFcxUwJfE3lKg\n"
      +   "Kmpwdne6FuQYX3eyRVAmPgOHbJuRQCh/V4fYo51UxCcEKeKy6UgOPEJlXksWGbH5\n"
      +   "VFmlytYW6dFKJvjltSmK6L2r+TlyEQoXwTqe4bkfhB2LniDEq28hKQ==\n"
      +   "-----END RSA PRIVATE KEY-----\n";
      +
      +const char *pub = "-----BEGIN PUBLIC KEY-----\n"
      +   "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA2b1bXDa+S8/MGWnMkru4\n"
      +   "T4tUddtZNi0NVjQn9RFH1NMa220GsRhRO56F77FlSVFKfSfVZKIiWg6C+DVCkcLf\n"
      +   "zXJ/Z0pvwOQYBAqVMFjV6efQGN0JzJ1Unu7pPRiZl7RKGEI+cyzzrcDyrLLrQ2W7\n"
      +   "0ZySkNEOv6Frx9JgC5NExuYY4lk2fQQa38JXiZkfyzif2em0px7mXbyf5LjccsKq\n"
      +   "v1e+XLtMsL0ZefRcqsP++NzQAI8fKX7WBT+qK0HJDLiHrKOTWYzx6CwJ66LD/vvf\n"
      +   "j55xtsKDLVDbsotvf8/m6VLMab+vqKk11TP4tq6yo0mwyTADvgl1zowQEO9I1W6o\n"
      +   "zQIDAQAB\n"
      +   "-----END PUBLIC KEY-----\n";
      +pubkey.raw_key = (unsigned char *)pub;
      +pubkey.key_size = strlen(pub);
      +pubkey.key_type = CKMC_KEY_NONE;
      +pubkey.password = NULL;
      +
      +pubpolicy.password = pub_passwd;
      +pubpolicy.extractable = false;
      +
      +pripolicy.password = pri_passwd;
      +pripolicy.extractable = true;
      +
      +prikey.raw_key = (unsigned char *)prv;
      +prikey.key_size = strlen(prv);
      +prikey.key_type = CKMC_KEY_NONE;
      +prikey.password = key_passwd; // The private key, prv, is encrypted with the key_password
      +
      +ret = ckmc_save_key(pri_alias, prikey, pripolicy);
      +if (CKMC_ERROR_NONE != ret)
      +{
      +   // Error handling
      +}
      +
      +ret = ckmc_save_key(pub_alias, pubkey, pubpolicy);
      +if (CKMC_ERROR_NONE != ret)
      +{
      +   // Error handling
      +}
      +
    2. + +
    3. Create and verify the signature: +
        +
      • Create and verify using a hash algorithm: +
        +int ret = CKMC_ERROR_NONE;
        +
        +const char *message = "message test";
        +ckmc_raw_buffer_s msg_buff;
        +ckmc_raw_buffer_s *signature;
        +ckmc_hash_algo_e hash_algo = CKMC_HASH_SHA256;
        +ckmc_rsa_padding_algo_e pad_algo = CKMC_PKCS1_PADDING;
        +
        +const char *pub_alias = "pub1";
        +const char *pri_alias = "prv1";
        +char *pri_passwd = NULL;
        +char *pub_passwd = NULL;
        +
        +msg_buff.data = (unsigned char *)message;
        +msg_buff.size = strlen(message);
        +
        +ret = ckmc_create_signature (pri_alias, pri_passwd, msg_buff, hash_algo, pad_algo, &signature);
        +if (CKMC_ERROR_NONE != ret)
        +{
        +   // Error handling
        +}
        +
        +ret = ckmc_verify_signature (pub_alias, pub_passwd, msg_buff, *signature, hash_algo, pad_algo);
        +if (CKMC_ERROR_NONE != ret)
        +{
        +   // Error handling
        +}
        +
      • + +
      • Create and verify without a hash algorithm: +
        +int ret = CKMC_ERROR_NONE;
        +
        +const char *message = "message test";
        +ckmc_raw_buffer_s msg_buff;
        +ckmc_raw_buffer_s *signature;
        +ckmc_hash_algo_e hash_algo = CKMC_HASH_NONE; // Do not use a hash algorithm 
        +ckmc_rsa_padding_algo_e pad_algo = CKMC_PKCS1_PADDING;
        +
        +const char *pub_alias = "pub1";
        +const char *pri_alias = "prv1";
        +char *pri_passwd = NULL;
        +char *pub_passwd = NULL;
        +
        +msg_buff.data = (unsigned char *)message;
        +msg_buff.size = strlen(message);
        +
        +ret = ckmc_create_signature (pri_alias, pri_passwd, msg_buff, hash_algo, pad_algo, &signature);
        +if (CKMC_ERROR_NONE != ret)
        +{
        +   // Error handling
        +}
        +
        +ret = ckmc_verify_signature (pub_alias, pub_passwd, msg_buff, *signature, hash_algo, pad_algo);
        +if (CKMC_ERROR_NONE != ret)
        +{
        +   // Error handling
        +}
        +
      • +
      +
    + +

    Verifying or Getting a Certificate Chain

    + +

    To verify and get a certificate chain using raw certificates or a certificate alias for untrusted certificates:

    +
    • Get a certificate chain with raw certificates.

      +

      The key manager verifies a certificate chain and returns it. The trusted root certificate of the chain must exist in the system certificate storage.

      +
      +int ret = CKMC_ERROR_NONE;
      +
      +ckmc_cert_s c_cert; // For a user certificate
      +ckmc_cert_s c_cert1; // For an intermediate untrusted CA certificate
      +ckmc_cert_list_s untrustedcerts; // Linked list of untrusted CA certificate
      +ckmc_cert_list_s *cert_chain_list; // Linked list of a certificate chain
      +
      +int cnt = 0;
      +ckmc_cert_list_s *current;
      +ckmc_cert_list_s *next;
      +
      +const char * ee =
      +"-----BEGIN CERTIFICATE-----\n"
      +"MIIF0TCCBLmgAwIBAgIQaPGTP4aS7Ut/WDNaBzdQrDANBgkqhkiG9w0BAQUFADCB\n"
      +"ujELMAkGA1UEBhMCVVMxFzAVBgNVBAoTDlZlcmlTaWduLCBJbmMuMR8wHQYDVQQL\n"
      +"ExZWZXJpU2lnbiBUcnVzdCBOZXR3b3JrMTswOQYDVQQLEzJUZXJtcyBvZiB1c2Ug\n"
      +"YXQgaHR0cHM6Ly93d3cudmVyaXNpZ24uY29tL3JwYSAoYykwNjE0MDIGA1UEAxMr\n"
      +"VmVyaVNpZ24gQ2xhc3MgMyBFeHRlbmRlZCBWYWxpZGF0aW9uIFNTTCBDQTAeFw0x\n"
      +"NDAyMjAwMDAwMDBaFw0xNTAyMjAyMzU5NTlaMIHmMRMwEQYLKwYBBAGCNzwCAQMT\n"
      +"AlBMMR0wGwYDVQQPExRQcml2YXRlIE9yZ2FuaXphdGlvbjETMBEGA1UEBRMKMDAw\n"
      +"MDAyNTIzNzELMAkGA1UEBhMCUEwxDzANBgNVBBEUBjAwLTk1MDEUMBIGA1UECBML\n"
      +"bWF6b3dpZWNraWUxETAPBgNVBAcUCFdhcnN6YXdhMRYwFAYDVQQJFA1TZW5hdG9y\n"
      +"c2thIDE4MRMwEQYDVQQKFAptQmFuayBTLkEuMQwwCgYDVQQLFANESU4xGTAXBgNV\n"
      +"BAMUEHd3dy5tYmFuay5jb20ucGwwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEK\n"
      +"AoIBAQDph6x8V6xUW/+651+qHF+UmorH9uaz2ZrX2bIWiMKIJFmpDDHlxcapKkqE\n"
      +"BV04is83aiCpqKtc2ZHy2g4Hpj1eSF5BP2+OAlo0YUQZPIeRRdiMjmeAxw/ncBDx\n"
      +"9rQBuCJ4XTD6cqQox5SI0TASOZ+wyAEjbDRXzL73XqRAFZ1LOpb2ONkolS+RutMB\n"
      +"vshvCsWPeNe7eGLuOh6DyC6r1vX9xhw3xnjM2mTSvmtimgzSLacNGKqRrsucUgcb\n"
      +"0+O5C2jZAtAMLyZksL92cxmWbtVzUYzem4chjHu5cRxUlPNzUJWrrczueB7Ip4A8\n"
      +"aQuFMfNXYc0x+WLWjy//urypMKjhAgMBAAGjggGjMIIBnzAbBgNVHREEFDASghB3\n"
      +"d3cubWJhbmsuY29tLnBsMAkGA1UdEwQCMAAwDgYDVR0PAQH/BAQDAgWgMB0GA1Ud\n"
      +"JQQWMBQGCCsGAQUFBwMBBggrBgEFBQcDAjBEBgNVHSAEPTA7MDkGC2CGSAGG+EUB\n"
      +"BxcGMCowKAYIKwYBBQUHAgEWHGh0dHBzOi8vd3d3LnZlcmlzaWduLmNvbS9jcHMw\n"
      +"HQYDVR0OBBYEFN37iGaS7mZnENxZ9FGqNLR+QgoMMB8GA1UdIwQYMBaAFPyKULqe\n"
      +"uSVae1WFT5UAY4/pWGtDMEIGA1UdHwQ7MDkwN6A1oDOGMWh0dHA6Ly9FVlNlY3Vy\n"
      +"ZS1jcmwudmVyaXNpZ24uY29tL0VWU2VjdXJlMjAwNi5jcmwwfAYIKwYBBQUHAQEE\n"
      +"cDBuMC0GCCsGAQUFBzABhiFodHRwOi8vRVZTZWN1cmUtb2NzcC52ZXJpc2lnbi5j\n"
      +"b20wPQYIKwYBBQUHMAKGMWh0dHA6Ly9FVlNlY3VyZS1haWEudmVyaXNpZ24uY29t\n"
      +"L0VWU2VjdXJlMjAwNi5jZXIwDQYJKoZIhvcNAQEFBQADggEBAD0wO+rooUrIM4qp\n"
      +"PHhp+hkXK6WMQ2qzGOmbMcZjw0govg5vkzkefPDryIXXbrF8mRagiJNMSfNaWWeh\n"
      +"Cj41OV24EdUl0OLbFxNzcvub599zRs/apfaRLTfsmlmOgi0/YP305i+3tJ2ll946\n"
      +"P+qV1wXnXqTqEdIl4Ys3+1HmDCdTB1hoDwAAzqRVUXZ5+iiwPAU7R/LTHfMjV1ke\n"
      +"8jtNFfrorlZMCfVH/7eEnHJvVjOJt+YFe4aFMzE+DfuYIK7MH+olC2v79kBwbnEQ\n"
      +"fvHMA9gFwOYLUBBdSfcocp8EKZ+mRlNPGR/3LBrPeaQQ0GZEkxzRK+v/aNTuiYfr\n"
      +"oFXtrg0=\n"
      +"-----END CERTIFICATE-----\n";
      +
      +const char *im =
      +"-----BEGIN CERTIFICATE-----\n"
      +"MIIF5DCCBMygAwIBAgIQW3dZxheE4V7HJ8AylSkoazANBgkqhkiG9w0BAQUFADCB\n"
      +"yjELMAkGA1UEBhMCVVMxFzAVBgNVBAoTDlZlcmlTaWduLCBJbmMuMR8wHQYDVQQL\n"
      +"ExZWZXJpU2lnbiBUcnVzdCBOZXR3b3JrMTowOAYDVQQLEzEoYykgMjAwNiBWZXJp\n"
      +"U2lnbiwgSW5jLiAtIEZvciBhdXRob3JpemVkIHVzZSBvbmx5MUUwQwYDVQQDEzxW\n"
      +"ZXJpU2lnbiBDbGFzcyAzIFB1YmxpYyBQcmltYXJ5IENlcnRpZmljYXRpb24gQXV0\n"
      +"aG9yaXR5IC0gRzUwHhcNMDYxMTA4MDAwMDAwWhcNMTYxMTA3MjM1OTU5WjCBujEL\n"
      +"MAkGA1UEBhMCVVMxFzAVBgNVBAoTDlZlcmlTaWduLCBJbmMuMR8wHQYDVQQLExZW\n"
      +"ZXJpU2lnbiBUcnVzdCBOZXR3b3JrMTswOQYDVQQLEzJUZXJtcyBvZiB1c2UgYXQg\n"
      +"aHR0cHM6Ly93d3cudmVyaXNpZ24uY29tL3JwYSAoYykwNjE0MDIGA1UEAxMrVmVy\n"
      +"aVNpZ24gQ2xhc3MgMyBFeHRlbmRlZCBWYWxpZGF0aW9uIFNTTCBDQTCCASIwDQYJ\n"
      +"KoZIhvcNAQEBBQADggEPADCCAQoCggEBAJjboFXrnP0XeeOabhQdsVuYI4cWbod2\n"
      +"nLU4O7WgerQHYwkZ5iqISKnnnbYwWgiXDOyq5BZpcmIjmvt6VCiYxQwtt9citsj5\n"
      +"OBfH3doxRpqUFI6e7nigtyLUSVSXTeV0W5K87Gws3+fBthsaVWtmCAN/Ra+aM/EQ\n"
      +"wGyZSpIkMQht3QI+YXZ4eLbtfjeubPOJ4bfh3BXMt1afgKCxBX9ONxX/ty8ejwY4\n"
      +"P1C3aSijtWZfNhpSSENmUt+ikk/TGGC+4+peGXEFv54cbGhyJW+ze3PJbb0S/5tB\n"
      +"Ml706H7FC6NMZNFOvCYIZfsZl1h44TO/7Wg+sSdFb8Di7Jdp91zT91ECAwEAAaOC\n"
      +"AdIwggHOMB0GA1UdDgQWBBT8ilC6nrklWntVhU+VAGOP6VhrQzASBgNVHRMBAf8E\n"
      +"CDAGAQH/AgEAMD0GA1UdIAQ2MDQwMgYEVR0gADAqMCgGCCsGAQUFBwIBFhxodHRw\n"
      +"czovL3d3dy52ZXJpc2lnbi5jb20vY3BzMD0GA1UdHwQ2MDQwMqAwoC6GLGh0dHA6\n"
      +"Ly9FVlNlY3VyZS1jcmwudmVyaXNpZ24uY29tL3BjYTMtZzUuY3JsMA4GA1UdDwEB\n"
      +"/wQEAwIBBjARBglghkgBhvhCAQEEBAMCAQYwbQYIKwYBBQUHAQwEYTBfoV2gWzBZ\n"
      +"MFcwVRYJaW1hZ2UvZ2lmMCEwHzAHBgUrDgMCGgQUj+XTGoasjY5rw8+AatRIGCx7\n"
      +"GS4wJRYjaHR0cDovL2xvZ28udmVyaXNpZ24uY29tL3ZzbG9nby5naWYwKQYDVR0R\n"
      +"BCIwIKQeMBwxGjAYBgNVBAMTEUNsYXNzM0NBMjA0OC0xLTQ3MD0GCCsGAQUFBwEB\n"
      +"BDEwLzAtBggrBgEFBQcwAYYhaHR0cDovL0VWU2VjdXJlLW9jc3AudmVyaXNpZ24u\n"
      +"Y29tMB8GA1UdIwQYMBaAFH/TZafC3ey78DAJ80M5+gKvMzEzMA0GCSqGSIb3DQEB\n"
      +"BQUAA4IBAQCWovp/5j3t1CvOtxU/wHIDX4u6FpAl98KD2Md1NGNoElMMU4l7yVYJ\n"
      +"p8M2RE4O0GJis4b66KGbNGeNUyIXPv2s7mcuQ+JdfzOE8qJwwG6Cl8A0/SXGI3/t\n"
      +"5rDFV0OEst4t8dD2SB8UcVeyrDHhlyQjyRNddOVG7wl8nuGZMQoIeRuPcZ8XZsg4\n"
      +"z+6Ml7YGuXNG5NOUweVgtSV1LdlpMezNlsOjdv3odESsErlNv1HoudRETifLriDR\n"
      +"fip8tmNHnna6l9AW5wtsbfdDbzMLKTB3+p359U64drPNGLT5IO892+bKrZvQTtKH\n"
      +"qQ2mRHNQ3XBb7a1+Srwi1agm5MKFIA3Z\n"
      +"-----END CERTIFICATE-----\n";
      +
      +c_cert.raw_cert = (unsigned char *) ee;
      +c_cert.cert_size = strlen(ee);
      +c_cert.data_format = CKMC_FORM_PEM;
      +
      +c_cert1.raw_cert = (unsigned char *) im;
      +c_cert1.cert_size = strlen(im);
      +c_cert1.data_format = CKMC_FORM_PEM;
      +
      +untrustedcerts.cert = &c_cert1;
      +untrustedcerts.next = NULL;
      +
      +ret = ckmc_get_cert_chain(&c_cert, &untrustedcerts, &cert_chain_list);
      +if (CKMC_ERROR_NONE != ret)
      +{
      +   // Error handling
      +}
      +
      +next=cert_chain_list;
      +do
      +{
      +   current = next;
      +   next = current->next;
      +}
      +while(next != NULL);
      +
      +ckmc_cert_list_all_free(cert_chain_list); // Called when the list is no longer needed
      +
    • + +
    • Get a certificate chain with aliases of untrusted CA certificates.

      +

      The key manager verifies a certificate chain and returns it. The trusted root certificate of the chain must exist in the system certificate storage.

      +
      +int ret = CKMC_ERROR_NONE;
      +
      +char* password = NULL;
      +const char *ca_alias = "untrusted_ca_cert1";
      +ckmc_policy_s test_policy;
      +
      +ckmc_cert_s c_cert; // For a user certificate
      +ckmc_cert_s c_cert1; // For an intermediate untrusted CA certificate
      +ckmc_alias_list_s untrustedcerts; // Linked list of untrusted CA certificate's alias
      +ckmc_cert_list_s *cert_chain_list; // Linked list of a certificate chain
      +
      +int cnt = 0;
      +ckmc_cert_list_s *current;
      +ckmc_cert_list_s *next;
      +
      +const char * ee =
      +"-----BEGIN CERTIFICATE-----\n"
      +"MIIF0TCCBLmgAwIBAgIQaPGTP4aS7Ut/WDNaBzdQrDANBgkqhkiG9w0BAQUFADCB\n"
      +"ujELMAkGA1UEBhMCVVMxFzAVBgNVBAoTDlZlcmlTaWduLCBJbmMuMR8wHQYDVQQL\n"
      +"ExZWZXJpU2lnbiBUcnVzdCBOZXR3b3JrMTswOQYDVQQLEzJUZXJtcyBvZiB1c2Ug\n"
      +"YXQgaHR0cHM6Ly93d3cudmVyaXNpZ24uY29tL3JwYSAoYykwNjE0MDIGA1UEAxMr\n"
      +"VmVyaVNpZ24gQ2xhc3MgMyBFeHRlbmRlZCBWYWxpZGF0aW9uIFNTTCBDQTAeFw0x\n"
      +"NDAyMjAwMDAwMDBaFw0xNTAyMjAyMzU5NTlaMIHmMRMwEQYLKwYBBAGCNzwCAQMT\n"
      +"AlBMMR0wGwYDVQQPExRQcml2YXRlIE9yZ2FuaXphdGlvbjETMBEGA1UEBRMKMDAw\n"
      +"MDAyNTIzNzELMAkGA1UEBhMCUEwxDzANBgNVBBEUBjAwLTk1MDEUMBIGA1UECBML\n"
      +"bWF6b3dpZWNraWUxETAPBgNVBAcUCFdhcnN6YXdhMRYwFAYDVQQJFA1TZW5hdG9y\n"
      +"c2thIDE4MRMwEQYDVQQKFAptQmFuayBTLkEuMQwwCgYDVQQLFANESU4xGTAXBgNV\n"
      +"BAMUEHd3dy5tYmFuay5jb20ucGwwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEK\n"
      +"AoIBAQDph6x8V6xUW/+651+qHF+UmorH9uaz2ZrX2bIWiMKIJFmpDDHlxcapKkqE\n"
      +"BV04is83aiCpqKtc2ZHy2g4Hpj1eSF5BP2+OAlo0YUQZPIeRRdiMjmeAxw/ncBDx\n"
      +"9rQBuCJ4XTD6cqQox5SI0TASOZ+wyAEjbDRXzL73XqRAFZ1LOpb2ONkolS+RutMB\n"
      +"vshvCsWPeNe7eGLuOh6DyC6r1vX9xhw3xnjM2mTSvmtimgzSLacNGKqRrsucUgcb\n"
      +"0+O5C2jZAtAMLyZksL92cxmWbtVzUYzem4chjHu5cRxUlPNzUJWrrczueB7Ip4A8\n"
      +"aQuFMfNXYc0x+WLWjy//urypMKjhAgMBAAGjggGjMIIBnzAbBgNVHREEFDASghB3\n"
      +"d3cubWJhbmsuY29tLnBsMAkGA1UdEwQCMAAwDgYDVR0PAQH/BAQDAgWgMB0GA1Ud\n"
      +"JQQWMBQGCCsGAQUFBwMBBggrBgEFBQcDAjBEBgNVHSAEPTA7MDkGC2CGSAGG+EUB\n"
      +"BxcGMCowKAYIKwYBBQUHAgEWHGh0dHBzOi8vd3d3LnZlcmlzaWduLmNvbS9jcHMw\n"
      +"HQYDVR0OBBYEFN37iGaS7mZnENxZ9FGqNLR+QgoMMB8GA1UdIwQYMBaAFPyKULqe\n"
      +"uSVae1WFT5UAY4/pWGtDMEIGA1UdHwQ7MDkwN6A1oDOGMWh0dHA6Ly9FVlNlY3Vy\n"
      +"ZS1jcmwudmVyaXNpZ24uY29tL0VWU2VjdXJlMjAwNi5jcmwwfAYIKwYBBQUHAQEE\n"
      +"cDBuMC0GCCsGAQUFBzABhiFodHRwOi8vRVZTZWN1cmUtb2NzcC52ZXJpc2lnbi5j\n"
      +"b20wPQYIKwYBBQUHMAKGMWh0dHA6Ly9FVlNlY3VyZS1haWEudmVyaXNpZ24uY29t\n"
      +"L0VWU2VjdXJlMjAwNi5jZXIwDQYJKoZIhvcNAQEFBQADggEBAD0wO+rooUrIM4qp\n"
      +"PHhp+hkXK6WMQ2qzGOmbMcZjw0govg5vkzkefPDryIXXbrF8mRagiJNMSfNaWWeh\n"
      +"Cj41OV24EdUl0OLbFxNzcvub599zRs/apfaRLTfsmlmOgi0/YP305i+3tJ2ll946\n"
      +"P+qV1wXnXqTqEdIl4Ys3+1HmDCdTB1hoDwAAzqRVUXZ5+iiwPAU7R/LTHfMjV1ke\n"
      +"8jtNFfrorlZMCfVH/7eEnHJvVjOJt+YFe4aFMzE+DfuYIK7MH+olC2v79kBwbnEQ\n"
      +"fvHMA9gFwOYLUBBdSfcocp8EKZ+mRlNPGR/3LBrPeaQQ0GZEkxzRK+v/aNTuiYfr\n"
      +"oFXtrg0=\n"
      +"-----END CERTIFICATE-----\n";
      +
      +const char *im =
      +"-----BEGIN CERTIFICATE-----\n"
      +"MIIF5DCCBMygAwIBAgIQW3dZxheE4V7HJ8AylSkoazANBgkqhkiG9w0BAQUFADCB\n"
      +"yjELMAkGA1UEBhMCVVMxFzAVBgNVBAoTDlZlcmlTaWduLCBJbmMuMR8wHQYDVQQL\n"
      +"ExZWZXJpU2lnbiBUcnVzdCBOZXR3b3JrMTowOAYDVQQLEzEoYykgMjAwNiBWZXJp\n"
      +"U2lnbiwgSW5jLiAtIEZvciBhdXRob3JpemVkIHVzZSBvbmx5MUUwQwYDVQQDEzxW\n"
      +"ZXJpU2lnbiBDbGFzcyAzIFB1YmxpYyBQcmltYXJ5IENlcnRpZmljYXRpb24gQXV0\n"
      +"aG9yaXR5IC0gRzUwHhcNMDYxMTA4MDAwMDAwWhcNMTYxMTA3MjM1OTU5WjCBujEL\n"
      +"MAkGA1UEBhMCVVMxFzAVBgNVBAoTDlZlcmlTaWduLCBJbmMuMR8wHQYDVQQLExZW\n"
      +"ZXJpU2lnbiBUcnVzdCBOZXR3b3JrMTswOQYDVQQLEzJUZXJtcyBvZiB1c2UgYXQg\n"
      +"aHR0cHM6Ly93d3cudmVyaXNpZ24uY29tL3JwYSAoYykwNjE0MDIGA1UEAxMrVmVy\n"
      +"aVNpZ24gQ2xhc3MgMyBFeHRlbmRlZCBWYWxpZGF0aW9uIFNTTCBDQTCCASIwDQYJ\n"
      +"KoZIhvcNAQEBBQADggEPADCCAQoCggEBAJjboFXrnP0XeeOabhQdsVuYI4cWbod2\n"
      +"nLU4O7WgerQHYwkZ5iqISKnnnbYwWgiXDOyq5BZpcmIjmvt6VCiYxQwtt9citsj5\n"
      +"OBfH3doxRpqUFI6e7nigtyLUSVSXTeV0W5K87Gws3+fBthsaVWtmCAN/Ra+aM/EQ\n"
      +"wGyZSpIkMQht3QI+YXZ4eLbtfjeubPOJ4bfh3BXMt1afgKCxBX9ONxX/ty8ejwY4\n"
      +"P1C3aSijtWZfNhpSSENmUt+ikk/TGGC+4+peGXEFv54cbGhyJW+ze3PJbb0S/5tB\n"
      +"Ml706H7FC6NMZNFOvCYIZfsZl1h44TO/7Wg+sSdFb8Di7Jdp91zT91ECAwEAAaOC\n"
      +"AdIwggHOMB0GA1UdDgQWBBT8ilC6nrklWntVhU+VAGOP6VhrQzASBgNVHRMBAf8E\n"
      +"CDAGAQH/AgEAMD0GA1UdIAQ2MDQwMgYEVR0gADAqMCgGCCsGAQUFBwIBFhxodHRw\n"
      +"czovL3d3dy52ZXJpc2lnbi5jb20vY3BzMD0GA1UdHwQ2MDQwMqAwoC6GLGh0dHA6\n"
      +"Ly9FVlNlY3VyZS1jcmwudmVyaXNpZ24uY29tL3BjYTMtZzUuY3JsMA4GA1UdDwEB\n"
      +"/wQEAwIBBjARBglghkgBhvhCAQEEBAMCAQYwbQYIKwYBBQUHAQwEYTBfoV2gWzBZ\n"
      +"MFcwVRYJaW1hZ2UvZ2lmMCEwHzAHBgUrDgMCGgQUj+XTGoasjY5rw8+AatRIGCx7\n"
      +"GS4wJRYjaHR0cDovL2xvZ28udmVyaXNpZ24uY29tL3ZzbG9nby5naWYwKQYDVR0R\n"
      +"BCIwIKQeMBwxGjAYBgNVBAMTEUNsYXNzM0NBMjA0OC0xLTQ3MD0GCCsGAQUFBwEB\n"
      +"BDEwLzAtBggrBgEFBQcwAYYhaHR0cDovL0VWU2VjdXJlLW9jc3AudmVyaXNpZ24u\n"
      +"Y29tMB8GA1UdIwQYMBaAFH/TZafC3ey78DAJ80M5+gKvMzEzMA0GCSqGSIb3DQEB\n"
      +"BQUAA4IBAQCWovp/5j3t1CvOtxU/wHIDX4u6FpAl98KD2Md1NGNoElMMU4l7yVYJ\n"
      +"p8M2RE4O0GJis4b66KGbNGeNUyIXPv2s7mcuQ+JdfzOE8qJwwG6Cl8A0/SXGI3/t\n"
      +"5rDFV0OEst4t8dD2SB8UcVeyrDHhlyQjyRNddOVG7wl8nuGZMQoIeRuPcZ8XZsg4\n"
      +"z+6Ml7YGuXNG5NOUweVgtSV1LdlpMezNlsOjdv3odESsErlNv1HoudRETifLriDR\n"
      +"fip8tmNHnna6l9AW5wtsbfdDbzMLKTB3+p359U64drPNGLT5IO892+bKrZvQTtKH\n"
      +"qQ2mRHNQ3XBb7a1+Srwi1agm5MKFIA3Z\n"
      +"-----END CERTIFICATE-----\n";
      +
      +c_cert.raw_cert = (unsigned char *) ee;
      +c_cert.cert_size = strlen(ee);
      +c_cert.data_format = CKMC_FORM_PEM;
      +
      +c_cert1.raw_cert = (unsigned char *) im;
      +c_cert1.cert_size = strlen(im);
      +c_cert1.data_format = CKMC_FORM_PEM;
      +
      +test_policy.password = password;
      +test_policy.extractable = true;
      +
      +ret = ckmc_save_cert(ca_alias, c_cert1, test_policy);
      +if (CKMC_ERROR_NONE != ret)
      +{
      +   // Error handling
      +}
      +
      +untrustedcerts.alias = (char *)ca_alias;
      +untrustedcerts.next = NULL;
      +
      +ret = ckmc_get_cert_chain_with_alias(&c_cert, &untrustedcerts, &cert_chain_list);
      +if (CKMC_ERROR_NONE != ret)
      +{
      +   // Error handling
      +}
      +
      +next=cert_chain_list;
      +do
      +{
      +   current = next;
      +   next = current->next;
      +}
      +while(next != NULL);
      +
      +ckmc_cert_list_all_free(cert_chain_list); // Called when the list is no longer needed
      +
    + +

    Loading a Certificate or a PKCS#12 File

    + +

    To load certificates (from a file with the DER or PEM format) or a private key, a certificate, or CA certificates (from a PKCS#12 file):

    + +
    • Load from a certificate file.

      +
      +int ret = CKMC_ERROR_NONE;
      +
      +ckmc_cert_s *pcert;
      +// defined_media_storage_directory can be obtained with the storage_get_directory() function
      +const char *file_name = "<defined_media_storage_directory>/ckmc_test_cert.pem"; 
      +
      +ret = ckmc_load_cert_from_file(file_name, &pcert);
      +if (CKMC_ERROR_NONE != ret)
      +{
      +   // Error handling
      +}
      +
      +dlog_print(DLOG_INFO, LOG_TAG, "cert size =%d\n", pcert->cert_size);
      +
      +ckmc_cert_free(pcert); // Called when the certificate is no longer needed
      +
    • + +
    • Load from a PKCS#12 file.

      +
      +int ret = CKMC_ERROR_NONE;
      +
      +ckmc_key_s *private_key = NULL;
      +ckmc_cert_s *cert = NULL;
      +ckmc_cert_list_s *ca_cert_list = NULL;
      +// defined_media_storage_directory can be obtained with the storage_get_directory() function
      +const char *p12file = "<defined_media_storage_directory>/ckmc_p12_test.p12"; 
      +const char *password = "password";  // PKCS#12 file can be protected by a password
      +
      +ret = ckmc_load_from_pkcs12_file(p12file, password, &private_key, &cert, &ca_cert_list);
      +if (CKMC_ERROR_NONE != ret)
      +{
      +   // Error handling
      +}
      +
      +if (private_key != NULL)
      +{
      +   // Check a private key
      +}
      +
      +if (cert != NULL)
      +{
      +   // Check a certificate
      +
      +}
      +
      +int cnt = 0;
      +ckmc_cert_list_s *tmp_list = ca_cert_list;
      +while(tmp_list!= NULL)
      +{
      +   // Check a certificate list
      +
      +   tmp_list = tmp_list ->next;
      +}
      +
      +ckmc_key_free(private_key); // Called when the key is no longer needed
      +ckmc_cert_free(cert); // Called when the certificate is no longer needed
      +ckmc_cert_list_all_free(ca_cert_list); // Called when the list is no longer needed
      +
    + +

    Implementing Access Control

    + +

    To implement access control rules for each individual client's data, certificates, and keys:

    + +
    1. Store test data:

      +
      +int ret = CKMC_ERROR_NONE;
      +
      +char* password = NULL;
      +ckmc_raw_buffer_s test_data;
      +const char *alias = "targetData";
      +ckmc_policy_s test_policy;
      +
      +const char *char_bin_data = "Access control test Data";
      +
      +test_policy.password = password;
      +test_policy.extractable = true;
      +
      +test_data.data = (unsigned char *) char_bin_data;
      +test_data.size = strlen(char_bin_data);
      +ret = ckmc_save_data(alias, test_data, test_policy);
      +if (CKMC_ERROR_NONE != ret)
      +
      +{
      +   // Error handling
      +}
      +
    2. + +
    3. Set a rule to allow access:

      +
      +int ret = CKMC_ERROR_NONE;
      +
      +const char *target1 = "accessor-allow-1";
      +const char *target2 = "accessor-allow-2";
      +const char *alias = "targetData";
      +
      +ret = ckmc_allow_access(alias, target1, CKMC_AR_READ); // Only allow reading data
      +if (CKMC_ERROR_NONE != ret)
      +{
      +   // Error handling
      +}
      +
      +ret = ckmc_allow_access(alias, target2, CKMC_AR_READ_REMOVE); // Allow reading and deleting data
      +if (CKMC_ERROR_NONE != ret)
      +{
      +   // Error handling
      +}
      +
    4. + +
    5. Set a rule to deny access:

      +
      +int ret = CKMC_ERROR_NONE;
      +
      +const char *target = "denied-accessor";
      +const char *alias = "targetData";
      +
      +ret = ckmc_allow_access(alias, target, CKMC_AR_READ); // Allow the target user to a read (alias)
      +if (CKMC_ERROR_NONE != ret)
      +{
      +   // Error handling
      +}
      +
      +ret = ckmc_deny_access(alias, target); // Deny the target user access to data (alias)
      +if (CKMC_ERROR_NONE != ret)
      +
      +{
      +   // Error handling
      +}
      +
    6. +
    + + + + +
    + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.tutorials/html/native/security/privilege_tutorial_n.htm b/org.tizen.tutorials/html/native/security/privilege_tutorial_n.htm index d4f29a1..13ee06d 100644 --- a/org.tizen.tutorials/html/native/security/privilege_tutorial_n.htm +++ b/org.tizen.tutorials/html/native/security/privilege_tutorial_n.htm @@ -1,151 +1,151 @@ - - - - - - - - - - - - - Privilege Info: Managing Privilege Information - - - - - - -
    -

    Privilege Info: Managing Privilege Information

    - - -

    This tutorial demonstrates how you can display privilege information, such as the name and description of a given privilege.

    - -

    Warm-up

    -

    - Become familiar with the Privilege Info API basics by learning about:

    - - -

    Getting Privilege Information

    - -

    To get privilege display information:

    - -
      -
    1. To use the functions and data types of the Privilege Info API (in mobile and wearable applications), include the <privilege_information.h> header file in your application:

      -
      -#include <privilege_information.h>
      -
    2. -
    3. To get various privilege information: -
        - -
      1. Get the privilege display name using the privilege_info_get_display_name() function: - -
        -char* displayName = NULL;
        -int retVal = privilege_info_get_display_name("2.2", "http://tizen.org/privilege/application.launch", &displayName);
        - -

        The function takes the following parameters:

        -
          -
        • API version
        • -
        • Privilege name
        • -
        • Privilege display name
        • -
        - -
      2. - -
      3. Get the privilege display name by package type using the privilege_info_get_display_name_by_pkgtype() function: - -
        -char* displayName = NULL;
        -int retVal = privilege_info_get_display_name_by_pkgtype("PRVINFO_PACKAGE_TYPE_WEB", "2.2", "http://tizen.org/privilege/application.launch", &displayName);
        - -

        The function takes the following parameters:

        -
          -
        • Package type
        • -
        • API version
        • -
        • Privilege name
        • -
        • Privilege display name
        • -
        - -
      4. - -
      5. Get the privilege description using the privilege_info_get_description() function: - -
        -char* description = NULL;
        -int retVal = privilege_info_get_description("2.2", "http://tizen.org/privilege/application.launch", &description);
        - -

        The function takes the following parameters:

        -
          -
        • API version
        • -
        • Privilege name
        • -
        • Description of the privilege
        - -
      6. - - -
      7. Get the privilege description by package type using the privilege_info_get_description_by_pkgtype() function: - -
        -char* description = NULL;
        -int retVal = privilege_info_get_description_by_pkgtype("PRVINFO_PACKAGE_TYPE_WEB", "2.2", "http://tizen.org/privilege/application.launch", &description);
        - -

        The function takes the following parameters:

        -
          -
        • Package type
        • -
        • API version
        • -
        • Privilege name
        • -
        • Description of the privilege
        - -
      8. - -
      -

      All functions above return the defined privilege_info_error_e enum value that indicates the result of executing the function and provides the privilege description by assigning the matching value to the third parameter.

      - -
    - - - - -
    - -Go to top - - - - - - + + + + + + + + + + + + + Privilege Info: Managing Privilege Information + + + + + + +
    +

    Privilege Info: Managing Privilege Information

    + + +

    This tutorial demonstrates how you can display privilege information, such as the name and description of a given privilege.

    + +

    Warm-up

    +

    + Become familiar with the Privilege Info API basics by learning about:

    + + +

    Getting Privilege Information

    + +

    To get privilege display information:

    + +
      +
    1. To use the functions and data types of the Privilege Info API (in mobile and wearable applications), include the <privilege_information.h> header file in your application:

      +
      +#include <privilege_information.h>
      +
    2. +
    3. To get various privilege information: +
        + +
      1. Get the privilege display name using the privilege_info_get_display_name() function: + +
        +char* displayName = NULL;
        +int retVal = privilege_info_get_display_name("2.2", "http://tizen.org/privilege/application.launch", &displayName);
        + +

        The function takes the following parameters:

        +
          +
        • API version
        • +
        • Privilege name
        • +
        • Privilege display name
        • +
        + +
      2. + +
      3. Get the privilege display name by package type using the privilege_info_get_display_name_by_pkgtype() function: + +
        +char* displayName = NULL;
        +int retVal = privilege_info_get_display_name_by_pkgtype("PRVINFO_PACKAGE_TYPE_WEB", "2.2", "http://tizen.org/privilege/application.launch", &displayName);
        + +

        The function takes the following parameters:

        +
          +
        • Package type
        • +
        • API version
        • +
        • Privilege name
        • +
        • Privilege display name
        • +
        + +
      4. + +
      5. Get the privilege description using the privilege_info_get_description() function: + +
        +char* description = NULL;
        +int retVal = privilege_info_get_description("2.2", "http://tizen.org/privilege/application.launch", &description);
        + +

        The function takes the following parameters:

        +
          +
        • API version
        • +
        • Privilege name
        • +
        • Description of the privilege
        + +
      6. + + +
      7. Get the privilege description by package type using the privilege_info_get_description_by_pkgtype() function: + +
        +char* description = NULL;
        +int retVal = privilege_info_get_description_by_pkgtype("PRVINFO_PACKAGE_TYPE_WEB", "2.2", "http://tizen.org/privilege/application.launch", &description);
        + +

        The function takes the following parameters:

        +
          +
        • Package type
        • +
        • API version
        • +
        • Privilege name
        • +
        • Description of the privilege
        + +
      8. + +
      +

      All functions above return the defined privilege_info_error_e enum value that indicates the result of executing the function and provides the privilege description by assigning the matching value to the third parameter.

      + +
    + + + + +
    + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.tutorials/html/native/security/security_tutorials_n.htm b/org.tizen.tutorials/html/native/security/security_tutorials_n.htm index d57853a..ee8f1ea 100644 --- a/org.tizen.tutorials/html/native/security/security_tutorials_n.htm +++ b/org.tizen.tutorials/html/native/security/security_tutorials_n.htm @@ -1,66 +1,66 @@ - - - - - - - - - - - - - Security: Handling Keys and Cryptographic Operations - - - - - - -
    -

    Security: Handling Keys and Cryptographic Operations

    -

    The security tutorials demonstrate how to use the following features in creating Tizen native applications:

    - - - - - - - -
    - -Go to top - - - - - - + + + + + + + + + + + + + Security: Handling Keys and Cryptographic Operations + + + + + + +
    +

    Security: Handling Keys and Cryptographic Operations

    +

    The security tutorials demonstrate how to use the following features in creating Tizen native applications:

    + + + + + + + +
    + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.tutorials/html/native/social/account_tutorial_n.htm b/org.tizen.tutorials/html/native/social/account_tutorial_n.htm index fca2374..665ecd9 100644 --- a/org.tizen.tutorials/html/native/social/account_tutorial_n.htm +++ b/org.tizen.tutorials/html/native/social/account_tutorial_n.htm @@ -1,959 +1,959 @@ - - - - - - - - - - - - - Account Manager: Managing Account Information on the Device - - - - - -
    - -

    Account Manager: Managing Account Information on the Device

    - - -

    This tutorial demonstrates how you can create, delete, and update accounts in the account database, and manage account information, such as user name, display name, domain name, and email address.

    - - - - - - - - - - -
    Note
    This feature is supported in mobile applications only.
    - -

    Warm-up

    -

    Become familiar with the Account Manager API basics by learning about:

    - -

    Follow-up

    -

    Once we have learned the basics of the Account Manager API, we can now move on to more advanced tasks, including:

    - - -

    Initializing the Accounts

    - -

    To initialize the account manager:

    -
      -
    1. To use the functions and data types of the Account Manager API, include the <account.h> header file in your application:

      -
      -#include <account.h>
      -
    2. -
    3. Declare the necessary global variables. To know, whether a function has been executed properly, see that the return is equal to ACCOUNT_ERROR_NONE.

      - -
      -#include <stdio.h>
      -#include <time.h>
      -#include <dlog.h>
      -
      -static account_h account = NULL;
      -static int account_id = 0;
      -int ret = 0;
      -
    4. - -
    5. Set up the required privileges for your application:

      - -
        -
      • To use APIs for reading account data from the account database, add the http://tizen.org/privilege/account.read privilege to the manifest file. -
      • - -
      • To use APIs for writing account data from the account database, add the http://tizen.org/privilege/account.write privilege to the manifest file. -
      • - -
    - -

    Creating and Managing an Account

    - -

    To create an account, set it properties, and add it to the account database:

    - - -
      - -
    1. Create an account using the account_create() function and the previously defined account handle: - -
      -ret = account_create(&account);
      -
      -
    2. -
    3. When the account is created, you can set account properties, such as name, display name, domain name, and email address: - -
      -char* account_name = "Marcus";
      -char* display_name = "Marcus_display";
      -char* domain_name = "Marcus_domain";
      -char* email_address = "marcus@example.com";
      -char* image_path = "image_path";
      -
      -ret = account_set_user_name(account, account_name);
      -
      -ret = account_set_display_name(account, display_name);
      -
      -ret = account_set_domain_name(account, domain_name);
      -
      -ret = account_set_email_address(account, email_address);
      -
      -ret = account_set_icon_path(account, image_path);
      -
      -
    4. - -
    5. When the account is configured, use the account_insert_to_db() function to insert the account to the account database. Use the account ID as the second parameter (account_id): - -
      -ret = account_insert_to_db(account, &account_id);
      -
      -
    6. -
    - -

    Getting Account Information

    - -

    To get account information, such as user name, display name, domain name, and email address:

    - -
      -
    1. Use the account_get_total_count_from_db() function to get the total number of inserted records. -

      To get individual records, use the account_foreach_account_from_db() function, which iterates through all the records and invokes a callback function for each account:

      -
      account_foreach_account_from_db (account_cb callback, void *user_data)
      - -

      The function takes the following parameters:

      -
        -
      • callback: Callback function to be invoked
      • -
      • user_data: User data to be passed to the callback function
      • -
      - -
      -int total_count = -1;
      -ret = account_get_total_count_from_db(&total_count);
      -
      -ret = account_foreach_account_from_db(on_account_read, NULL);
      -
      -
    2. - -
    3. Define the callback function: -
      typedef bool(* account_cb)(account_h account, void *user_data)
      - -

      The callback function takes the following parameters:

      -
        -
      • account: Account handle
      • -
      • user_data: User data passed from the account_foreach_account_from_db() function
      • -
      - -

      This function retrieves information for each account.

      -
    4. -
    5. To get more details, use the account_get_account_id(), account_get_user_name(), account_get_display_name(), and account_get_icon_path() functions: - -
      -static bool on_account_read(account_h account, void *user_data)
      -{
      -   char *name = NULL;
      -   char *display_name = NULL;
      -   char *icon_path = NULL;
      -   // Get the account ID
      -   ret = account_get_account_id(account, &account_id);
      -   if (ret != ACCOUNT_ERROR_NONE)
      -   {
      -      // Error handling
      -      return false;
      -   }
      -   // Get the user name
      -   ret = account_get_user_name(account, &name);
      -   if (ret != ACCOUNT_ERROR_NONE)
      -   {
      -      // Error handling
      -      return false;
      -   }
      -   dlog_print(DLOG_INFO, LOG_TAG, "name: %s", name);
      -   // Get the display name
      -   ret = account_get_display_name(account, &display_name);
      -   if (ret != ACCOUNT_ERROR_NONE)
      -   {
      -      // Error handling
      -      return false;
      -   }
      -   dlog_print(DLOG_INFO, LOG_TAG, "display_name: %s", display_name);
      -   // Get the icon path
      -   ret = account_get_icon_path(account, &icon_path);
      -   if (ret != ACCOUNT_ERROR_NONE)
      -   {
      -      // Error handling
      -      return false;
      -   }
      -   dlog_print(DLOG_INFO, LOG_TAG, "icon_path: %s", icon_path);
      -
      -   free(name);
      -   free(display_name);
      -   free(icon_path);
      -
      -   return true;
      -}
      -
      -
    6. -
    - -

    Retrieving Accounts by Package Name

    - -

    To retrieve accounts by a specific account provider:

    -
      -
    1. Define the account_cb() callback for getting data of accounts as a parameter of the account_query_account_by_package_name() function. -
      -static bool account_callback(account_h account, void* user_data) // account_cb() callback
      -{
      -   // Called once for each account in the database
      -}
      -
    2. -
    3. Retrieve the accounts of a specific account provider using the account_query_account_by_package_name() function, and specifying the package name of the account provider: -
      int ret = -1;
      -char* package_name = "package_name";
      -ret = account_query_account_by_package_name(account_callback, package_name, NULL);
      -
    4. -
    - -

    Retrieving Account Providers by Capability

    - -

    To retrieve account providers by a specific capability:

    -
      -
    1. Define account_type_cb() callback for getting account providers as a parameter of the account_type_query_by_provider_feature() function. The callback takes the account provider handle as the first parameter. -
      -static bool account_type_callback(account_type_h account_type, void* user_data) // account_type_cb() callback
      -{
      -   // Called once for each account type in the database
      -}
      -
      -
    2. - -
    3. Retrieve the account providers of a specific capability by using the account_type_query_by_provider_feature() function: -
      -int ret = -1;
      -char* capability = "http://tizen.org/account/capability/contact";
      -
      -ret = account_type_create(&account_type);
      -
      -account_type_query_by_provider_feature(account_type_callback, capability, NULL);
      -
    4. -
    - -

    Removing an Account

    - -

    To remove an account, use the account_delete_from_db_by_id(), account_delete_from_db_by_user_name(), or account_delete_from_db_by_package_name() function. They all remove a given account record.

    - - - - - - - - - - -
    Note
    To get the ID needed as an argument of the account_delete_from_db_by_id() function, use the account_get_account_id() function.
    - -
    -ret = account_delete_from_db_by_id(account_id);
    -
    - -

    Destroying the Account Handle

    - -

    To destroy the account handle, use the account_destroy() function:

    -
    -ret = account_destroy(account);
    -
    - -

    Adding an Application on the Account Screen

    - -

    To add your application on the Add account screen of the device:

    - -
      -
    1. Add the required information in the manifest file: -
      <account>
      -   <account-provider appid="app-id name" providerid="url style string" multiple-accounts-support="true or false">
      -      <icon section="account">application icon name</icon>
      -      <icon section="account-small">application small icon name</icon>
      -      <label>Application name</label>
      -      <label xml:lang="en-gb">Application name</label>
      -      <label xml:lang="ko-kr">ߖȃخʼnL݇ Lا</label>
      -      <capability>http://tizen.org/account/capability/contact</capability>
      -      <capability>http://tizen.org/account/capability/calendar</capability>
      -   </account-provider>
      -</account>
      - -

      The required information includes:

      -
      • appid="app-id name" -

        Application ID (for example, appid="org.tizen.account").

      • -
      • providerid="url style string" -

        Provider identification string (for example, providerid="http://www.tizen.org").

      • -
      • multiple-accounts-support="true or false" -

        Multiple account support (if your application can manage 2 or more accounts, set to true; otherwise set to false)

      • -
      • <icon section="account">application icon name</icon> -

        Icon displayed on the Add account screen.

        -

        The icon size must be 72x72 px and the icon file must be in the {app-root}\shared\res\ directory.

      • -
      • <icon section="account-small">application small icon name</icon> -

        Small icon displayed on the Other application screen to represent the account provider.

        -

        The small icon file must be in the {app-root}\shared\res\ directory.

      • -
      • <label xml:lang="en-gb">Application name</label> -

        Application name displayed on the Add account screen, according to the selected language.

        -

        An account provider must have at least one label tag.

      • -
      • <capability>http://tizen.org/account/capability/contact</capability> -

        For more information, see the Account Manager guide.

      -
    2. - -
    3. Create the sign-in screen UI. -

      When the user selects your application on the Add account screen, the Account Service launches your application with a specific operation ID (ACCOUNT_OPERATION_SIGNIN) defined in the account-types.h header file, so the sign-in screen must be displayed.

      - -

      Figure: Sign-in screen

      -

      Sign-in screen

      -
    4. -
    - - - - - - - - - - -
    Note
    For more information on operations and events, see the Account Manager guide.
    - -

    Performing Database Queries

    - -

    To perform database queries:

    - - -
      -
    1. Prepare sample content. -

      To perform queries, you need existing content in the database. To access existing account, obtain it from the database. It can be done using a few functions, depending on the user requirements.

      -

      To create new content to the database:

      - -
      1. The create_Account() function creates a new account from a given account_h handle and account details (name, display name, domain, e-mail). 3 capabilities are added to the account to demonstrate some of the query functions. The capabilities as well as user custom types can be predefined.

        - -

        After creating the account, it is added to the database. When no longer needed, the account handle has to be destroyed using the account_destroy(account) function.

        - -
        -int id[3];
        -static account_h account = NULL;
        -
        -Create_Account(&account, "Person", "DiplayPerson", "Person Domain", "someone1@somewho.com");
        -
        -account_set_capability(account, "Custom", ACCOUNT_CAPABILITY_ENABLED);
        -
        -account_set_capability(account, "Next", ACCOUNT_CAPABILITY_ENABLED);
        - 
        -account_set_capability(account, "Another", ACCOUNT_CAPABILITY_DISABLED);
        -
        -account_insert_to_db(account, &id[0]);
        -
        -account_destroy(account);
        -
      2. - -
      3. Add 2 more accounts to the database.

        - -
        -Create_Account(&account, "PersonX", "DisplayX", "Other Domain", "someone2@somewho.com");
        -account_insert_to_db(account, &id[1]);
        -
        -account_destroy(account);
        -
        -Create_Account(&account, "Human", "Humanity", "Everyone", "someone3@somewho.com");
        -
        -account_insert_to_db(account, &id[2]);
        -
        -account_destroy(account);
        -
        -Create_Account(&account, "LastOne", "LastDisplay", "Last Domain", "someone4@somewho.com");
        -account_insert_to_db(account, &id[3]);
        -account_destroy(account);
        -
        -
      4. - -
      5. Create an account. -

        For more information, see Creating and Managing an Account.

        - -
        -static int Create_Account(account_h * account, char * account_name, char * display_name, char *  domain_name, char * email_address)
        -{
        -   account_create(account);
        -
        -   account_set_user_name(*account, account_name);
        -
        -   account_set_display_name(*account, display_name);
        -
        -   account_set_domain_name(*account, domain_name);
        -
        -   account_set_email_address(*account, email_address);
        -}
        -
      -
    2. - -
    3. List accounts. -
      1. -

        To verify the database insertion, all accounts are listed.

        - -
        -struct Account_Records
        -{
        -   int count;
        -   int tab[100];
        -};
        -
        -struct Account_Records rec;
        - 
        -List_Accounts(&rec);
        -
      2. - -
      3. When struct Account_Records* rec is not Null, List_Accounts counts all records in the database. Records are obtained using the account_foreach_account_from_db() function.

        - -
        -static void List_Accounts(struct Account_Records* rec)
        -{
        -   if (rec!=NULL)
        -   {
        -      rec->count=0;
        -   }
        -   account_foreach_account_from_db(on_account_read, rec);
        -}
        -
      4. - -
      5. For each found record, the on_account_read() callback function is called. If void *user_data is not null, the function is counting the existing accounts. String data returned by the get functions has to be released with free. Data prepared with the sprint() function can, for example, be sent for stdout.

        - -
        -static bool on_account_read(account_h account, void *user_data)
        -{
        -   int account_id = 0;
        -   char *name = NULL;
        -   char *display_name = NULL;
        -   struct Account_Records * rec = (struct Account_Records *)user_data;
        -   char buf[100];
        -
        -   account_get_account_id(account, &account_id);
        -
        -   sprintf(buf,"MyCallback ID: %d\n", account_id);
        -
        -   if (user_data!=NULL)
        -   {
        -      rec->tab[rec->count++]=account_id;
        -   }
        -   account_get_user_name(account, &name);
        -   sprintf(buf,"MyCallback Name: %s\n", name);
        -
        -   free(name);
        -
        -   account_get_display_name(account, &display_name);
        -   sprintf(buf,"MyCallback Disp.: %s\n", display_name);
        -
        -   free(display_name);
        -
        -   return 0;
        -}
        -
      -
    4. -
    5. Query the account by ID. -

      The easiest way to get access to an account stored in the database is referring to it by its ID. It can be done with the account_query_account_by_account_id() function. This function requires an existing handle to an account as an input parameter.

      - -
      -for (i=0; i<rec.count; i++)
      -{
      -   account_create(&account);
      -   account_query_account_by_account_id (rec.tab[i], &account);
      -
      -   Show_Account(account);
      -
      -   account_destroy(account);
      -}
      -
      -
    6. - -
    7. Show the account. -

      The following function prepares data to send it to any text output.

      - -
      -static int Show_Account(account_h acc)
      -{
      -   int account_id = 0;
      -   char *name = NULL;
      -   char *display_name = NULL;
      -   char buf[100];
      -
      -   account_get_account_id(acc, &account_id);
      -
      -   sprintf(buf,"Show_Account ID: %d\n", account_id);
      -
      -   account_get_user_name(acc, &name);
      -
      -   sprintf(buf,"Show_Account Name: %s\n", name);
      -
      -   free(name);
      -
      -   account_get_display_name(acc, &display_name);
      -
      -   sprintf(buf,"Show_Account Disp.: %s\n", display_name);
      -
      -   free(display_name);
      -
      -   return 0;
      -}
      -
      -
    8. - -
    9. Query the account by various attributes: -
      • Query by username. -

        Querying data by username requires providing a valid username callback function. In this example, it is the same function as for for_each, but cast without the third parameter.

        - -
        -account_query_account_by_user_name (on_account_read, "Human", NULL);
        -
        -
      • - -
      • Query by package name -

        By default, the accounts created in the application context have a package name set to the application name. Change it using the account_set_package_name() function. To list accounts by package name, the user can provide a name by itself or obtain it with the account_get_package_name() function.

        - -

        The account_query_account_by_package_name() function requires a callback function and a package name. In addition, the user data can be passed to the callback function as a third parameter.

        - -

        The package name has to be released when no longer needed.

        - -
        -char * package_name;
        -account_get_package_name (account, &package_name);
        -account_query_account_by_package_name (on_account_read, package_name, NULL);
        -free(package_name);
        -
        -
      • - -
      • Query by capability -

        The following function allows the user to find all accounts with a specified capability on a specified state. Once again, the callback function is required.

        - -
        -account_query_account_by_capability (on_account_read, "Custom", ACCOUNT_CAPABILITY_ENABLED, NULL);
        -
        -
      • - -
      • Query by capability type -

        This function is similar to the account_query_account_by_capability() function, but returns all accounts with a specified capability, without checking its state.

        - -
        -account_query_account_by_capability_type (on_account_read, "Next", NULL);
        -
        -
      • - -
      • Query capability by account ID -

        The account_query_capability_by_account_id() function is different from the previous functions. It lists all capabilities from an account with a specified ID. In this case it requires a different type of callback, as listed below.

        - -
        -account_query_capability_by_account_id (_capability_cb, id[0], NULL);
        -
        - -

        The callback function prepares data to be sent to an output.

        - -
        -static bool _capability_cb(const char *capability_type, account_capability_state_e capability_state, void *user_data)
        -{
        -   char buf[200];
        -   sprintf(buf,"Found capability: %s on state %d\n", capability_type, capability_state);
        -
        -   return true;
        -}
        -
        -
    10. - -
    11. Clean up. -

      When no longer needed, all handles to accounts have to be destroyed.

      - -
      -account_destroy(account);
      -
      -
    12. -
    - -

    Managing Account Secrecy

    - -

    To manage account secrecy:

    -
      -
    1. Select the secrecy level using the account_secrecy_state_e enumeration. - -
      -static account_h account = NULL;
      -account_secrecy_state_e secret;
      - 
      -char buf[200];
      -int ret;
      -int id;
      -
      -// Account 1
      -Create_Account(&account, "Security 1", "Invalid", "NOBODY", "anony@mous.not");
      -
      -account_set_secret(account, ACCOUNT_SECRECY_INVALID);
      -
      -account_get_secret(account, &secret);
      -
      -account_insert_to_db(account, &id);
      -
      -sprintf(buf,"Account 1 secret: %d\n", secret);
      -
      -account_destroy(account);
      -
      -// Account 2
      -
      -Create_Account(&account, "Security 2", "Invisible", " NOBODY", "anony1@mous.not");
      -
      -account_set_secret(account, ACCOUNT_SECRECY_INVISIBLE);
      -
      -account_get_secret(account, &secret);
      -
      -account_insert_to_db(account, &id);
      -
      -sprintf(buf, " Account 2 secret: %d\n", secret);
      -
      -account_destroy(account);
      -
      -// Account 3
      -
      -Create_Account(&account, "Secret 3", "Visible", " NOBODY", "anony2@mous.not");
      -
      -ret = account_set_secret(account, ACCOUNT_SECRECY_VISIBLE);
      -
      -ret = account_get_secret(account, &secret);
      -
      -ret = account_insert_to_db(account, &id);
      -
      -sprintf(buf," Account 3 secret: %d\n", secret);
      -
      -account_destroy(account);
      -
      -List_Accounts(NULL);
      -
      - -

      Secrecy is linked only with visibility on the account settings screen. The account is still visible and can be accessed using a query or the for_each function. For further information on how to add your application to the account screen, see Adding an Application on the Account Screen.

      - -
      // List_Account() console output
      -MyCallback ID: 12
      -MyCallback Name: Security 1
      -MyCallback Disp.: Invalid
      --------------------
      -MyCallback ID: 13
      -MyCallback Name: Security 2
      -MyCallback Disp.: Invisible
      --------------------
      -MyCallback ID: 14
      -MyCallback Name: Secret 3
      -MyCallback Disp.: Visible
      -
      -
    2. - -
    3. Clean up. -

      Account handles have to be destroyed when no longer needed.

      - -
      -account_destroy(account);
      -
      -
    4. -
    - -

    Updating Accounts

    - -

    To update and track account data.

    - -
      -
    1. Subscribe notifications. -

      To track account changes, create an account_subscribe_h instance and register a notification.

      - -
      -account_subscribe_h account_subscribe;
      -
      -account_subscribe_create(&account_subscribe);
      -
      -account_subscribe_notification(account_subscribe, _account_event_cb, NULL);
      -
      -
    2. - -
    3. Create an account. -

      Accounts are created and then their handles are destroyed. The package name is obtained from the second account.

      - -
      -Create_Account(&account, "Updater", "Updated?", "ToUpdate", "not.up@to.date");
      -account_insert_to_db(account, &id);
      -
      -Show_Account(account);
      -account_destroy(account);
      -
      -Create_Account(&account, "Another", "Updated?", "ToUpdate", "not.up@to.date");
      -account_insert_to_db(account, &id);
      -
      -account_get_package_name (account, &package_name);
      -sprintf(buf, "Package_name: %s\n", package_name);
      -
      -Show_Account(account);
      -account_destroy(account);
      -
      -
    4. - -
    5. Update the account. -
      • To update an account by its ID:

        -
          -
        1. Create a handle to the account.
        2. -
        3. Get the account from the database (also possible by ID).
        4. -
        5. Make the necessary changes.
        6. -
        7. Update the account using the account handle and a valid ID.
        8. -
        9. Destroy the account handle.
        10. -
        - -
        -account_create(&account);
        -account_query_account_by_account_id(id, &account);
        -account_set_display_name(account, "Updated!");
        -account_update_to_db_by_id(account, id);
        -account_destroy(account);
        -
        -
      • - -
      • Update account by user name. -

        To update an account by its user name:

        -
          -
        1. Create a handle to the account.
        2. -
        3. Get the account from the database (also by ID).
        4. -
        5. Make the necessary changes.
        6. -
        7. Update the account using the account handle, a valid user name, and a package name. There can be accounts with the same user names in different packages.
        8. -
        9. Destroy the account handle.
        10. -
        - -
        -account_create(&account);
        -account_query_account_by_account_id(id, &account);
        -account_set_display_name(account, "Updated!");
        -account_update_to_db_by_user_name(account, "Another", package_name);
        -account_destroy(account);
        -
      -
    6. - -
    7. Create the callback. -

      When any action is taking place on any account when a notification is subscribed, a callback function is invoked. The callback function provides in its parameters the event type as a string, the ID of the account associated with the actual change, and, additionally, the user data registered while subscribing the notification.

      - -
      -bool _account_event_cb(const char *event_type, int account_id, void *user_data)
      -{
      -   char buf[200];
      -
      -   sprintf(buf, "ACCOUNT EVENT: %s, %d\n", event_type, account_id);
      -
      -   return true;
      -}
      -
      -
    8. - -
    9. Show accounts. -

      To verify the updates, the account can be shown.

      - -
      -account_create(&account);
      -account_query_account_by_account_id(id, &account);
      -Show_Account(account);
      -account_destroy(account);
      -
      -
    10. - -
    11. Clean up. -

      Unsubscribe the notification when no longer needed.

      - -
      -account_unsubscribe_notification(account_subscribe);
      -
      -
    12. -
    - -

    Retrieving Account Types

    - -

    To retrieve account types:

    - -
      -
    1. Create a type. -

      To operate on the account type, create a handle to it.

      - -
      -account_type_h account_type;
      -
      -account_type_create(&account_type);
      -
      -
    2. - -
    3. Get the type information. -

      If the account type with a specified ID exists, you can get it from the database with the account_query_by_app_id() function.

      - -

      It is possible to set, for example:

      -
        -
      • ID
      • -
      • Labels
      • -
      • Features
      • -
      • Multiple account support (this is only a flag)
      • -
      - -

      To get the account types by the application ID, use the account_type_query_by_app_id() function.

      - -
      -int multiple_account_support = -1;
      -char *your_app_id = "com.tizen.example"; // App ID retrieving account types
      -char *app_id = NULL;
      -char *provider_feature = NULL;
      -char *icon_path = NULL;
      -
      -if (account_type_query_app_id_exist(your_app_id))
      -{
      -   account_type_query_by_app_id(your_app_id, &account_type);
      -
      -   account_type_get_app_id(account_type, &app_id);
      -
      -   account_type_get_multiple_account_support(account_type, &multiple_account_support);
      -
      -   account_type_get_icon_path(account_type, &icon_path);
      -
      -   account_type_get_provider_feature(account_type, &provider_feature);
      -}
      -
      -
    4. - -
    5. List types and labels. -

      To list the account types or all the labels from a specified type, a proper callback function has to be provided.

      - -
      -account_type_foreach_account_type_from_db(_account_type_cb, NULL);
      -
      -account_type_query_label_by_app_id(_account_label_cb, type_id, NULL);
      -
      - -

      While listing the labels, the user has access to the ID of the account type, label and its local value, and the user data passed while casting the query function.

      - -
      -bool _account_label_cb(char *app_id, char *label, char *locale, void *user_data)
      -{
      -   char buf[200];
      -
      -   sprintf(buf,"Get Label ID: %s LABEL: %s LOCALE %s\n", app_id, label, locale);
      -
      -   return true;
      -}
      -
      - -

      The account type callback has access to the account type and user data.

      - -
      -bool _account_type_cb(account_type_h account_type, void *user_data)
      -{
      -   char * id;
      -   int support;
      -   char buf[200];
      -
      -   account_type_get_app_id(account_type, &id);
      -
      -   account_type_get_multiple_account_support(account_type, &support);
      -   sprintf(buf,"Account Type ID: %s Multiple support %d:\n", id, support);
      -
      -   return true;
      -}
      -
      -
    6. - -
    7. Clean up. -

      All allocated handles have to be destroyed.

      - -
      -free(app_id);
      -free(provider_feature);
      -free(icon_path);
      -
      -account_type_destroy(account_type);
      -
      -
    8. -
    - - - - -
    - -Go to top - - - - - - + + + + + + + + + + + + + Account Manager: Managing Account Information on the Device + + + + + +
    + +

    Account Manager: Managing Account Information on the Device

    + + +

    This tutorial demonstrates how you can create, delete, and update accounts in the account database, and manage account information, such as user name, display name, domain name, and email address.

    + + + + + + + + + + +
    Note
    This feature is supported in mobile applications only.
    + +

    Warm-up

    +

    Become familiar with the Account Manager API basics by learning about:

    + +

    Follow-up

    +

    Once we have learned the basics of the Account Manager API, we can now move on to more advanced tasks, including:

    + + +

    Initializing the Accounts

    + +

    To initialize the account manager:

    +
      +
    1. To use the functions and data types of the Account Manager API, include the <account.h> header file in your application:

      +
      +#include <account.h>
      +
    2. +
    3. Declare the necessary global variables. To know, whether a function has been executed properly, see that the return is equal to ACCOUNT_ERROR_NONE.

      + +
      +#include <stdio.h>
      +#include <time.h>
      +#include <dlog.h>
      +
      +static account_h account = NULL;
      +static int account_id = 0;
      +int ret = 0;
      +
    4. + +
    5. Set up the required privileges for your application:

      + +
        +
      • To use APIs for reading account data from the account database, add the http://tizen.org/privilege/account.read privilege to the manifest file. +
      • + +
      • To use APIs for writing account data from the account database, add the http://tizen.org/privilege/account.write privilege to the manifest file. +
      • + +
    + +

    Creating and Managing an Account

    + +

    To create an account, set it properties, and add it to the account database:

    + + +
      + +
    1. Create an account using the account_create() function and the previously defined account handle: + +
      +ret = account_create(&account);
      +
      +
    2. +
    3. When the account is created, you can set account properties, such as name, display name, domain name, and email address: + +
      +char* account_name = "Marcus";
      +char* display_name = "Marcus_display";
      +char* domain_name = "Marcus_domain";
      +char* email_address = "marcus@example.com";
      +char* image_path = "image_path";
      +
      +ret = account_set_user_name(account, account_name);
      +
      +ret = account_set_display_name(account, display_name);
      +
      +ret = account_set_domain_name(account, domain_name);
      +
      +ret = account_set_email_address(account, email_address);
      +
      +ret = account_set_icon_path(account, image_path);
      +
      +
    4. + +
    5. When the account is configured, use the account_insert_to_db() function to insert the account to the account database. Use the account ID as the second parameter (account_id): + +
      +ret = account_insert_to_db(account, &account_id);
      +
      +
    6. +
    + +

    Getting Account Information

    + +

    To get account information, such as user name, display name, domain name, and email address:

    + +
      +
    1. Use the account_get_total_count_from_db() function to get the total number of inserted records. +

      To get individual records, use the account_foreach_account_from_db() function, which iterates through all the records and invokes a callback function for each account:

      +
      account_foreach_account_from_db (account_cb callback, void *user_data)
      + +

      The function takes the following parameters:

      +
        +
      • callback: Callback function to be invoked
      • +
      • user_data: User data to be passed to the callback function
      • +
      + +
      +int total_count = -1;
      +ret = account_get_total_count_from_db(&total_count);
      +
      +ret = account_foreach_account_from_db(on_account_read, NULL);
      +
      +
    2. + +
    3. Define the callback function: +
      typedef bool(* account_cb)(account_h account, void *user_data)
      + +

      The callback function takes the following parameters:

      +
        +
      • account: Account handle
      • +
      • user_data: User data passed from the account_foreach_account_from_db() function
      • +
      + +

      This function retrieves information for each account.

      +
    4. +
    5. To get more details, use the account_get_account_id(), account_get_user_name(), account_get_display_name(), and account_get_icon_path() functions: + +
      +static bool on_account_read(account_h account, void *user_data)
      +{
      +   char *name = NULL;
      +   char *display_name = NULL;
      +   char *icon_path = NULL;
      +   // Get the account ID
      +   ret = account_get_account_id(account, &account_id);
      +   if (ret != ACCOUNT_ERROR_NONE)
      +   {
      +      // Error handling
      +      return false;
      +   }
      +   // Get the user name
      +   ret = account_get_user_name(account, &name);
      +   if (ret != ACCOUNT_ERROR_NONE)
      +   {
      +      // Error handling
      +      return false;
      +   }
      +   dlog_print(DLOG_INFO, LOG_TAG, "name: %s", name);
      +   // Get the display name
      +   ret = account_get_display_name(account, &display_name);
      +   if (ret != ACCOUNT_ERROR_NONE)
      +   {
      +      // Error handling
      +      return false;
      +   }
      +   dlog_print(DLOG_INFO, LOG_TAG, "display_name: %s", display_name);
      +   // Get the icon path
      +   ret = account_get_icon_path(account, &icon_path);
      +   if (ret != ACCOUNT_ERROR_NONE)
      +   {
      +      // Error handling
      +      return false;
      +   }
      +   dlog_print(DLOG_INFO, LOG_TAG, "icon_path: %s", icon_path);
      +
      +   free(name);
      +   free(display_name);
      +   free(icon_path);
      +
      +   return true;
      +}
      +
      +
    6. +
    + +

    Retrieving Accounts by Package Name

    + +

    To retrieve accounts by a specific account provider:

    +
      +
    1. Define the account_cb() callback for getting data of accounts as a parameter of the account_query_account_by_package_name() function. +
      +static bool account_callback(account_h account, void* user_data) // account_cb() callback
      +{
      +   // Called once for each account in the database
      +}
      +
    2. +
    3. Retrieve the accounts of a specific account provider using the account_query_account_by_package_name() function, and specifying the package name of the account provider: +
      int ret = -1;
      +char* package_name = "package_name";
      +ret = account_query_account_by_package_name(account_callback, package_name, NULL);
      +
    4. +
    + +

    Retrieving Account Providers by Capability

    + +

    To retrieve account providers by a specific capability:

    +
      +
    1. Define account_type_cb() callback for getting account providers as a parameter of the account_type_query_by_provider_feature() function. The callback takes the account provider handle as the first parameter. +
      +static bool account_type_callback(account_type_h account_type, void* user_data) // account_type_cb() callback
      +{
      +   // Called once for each account type in the database
      +}
      +
      +
    2. + +
    3. Retrieve the account providers of a specific capability by using the account_type_query_by_provider_feature() function: +
      +int ret = -1;
      +char* capability = "http://tizen.org/account/capability/contact";
      +
      +ret = account_type_create(&account_type);
      +
      +account_type_query_by_provider_feature(account_type_callback, capability, NULL);
      +
    4. +
    + +

    Removing an Account

    + +

    To remove an account, use the account_delete_from_db_by_id(), account_delete_from_db_by_user_name(), or account_delete_from_db_by_package_name() function. They all remove a given account record.

    + + + + + + + + + + +
    Note
    To get the ID needed as an argument of the account_delete_from_db_by_id() function, use the account_get_account_id() function.
    + +
    +ret = account_delete_from_db_by_id(account_id);
    +
    + +

    Destroying the Account Handle

    + +

    To destroy the account handle, use the account_destroy() function:

    +
    +ret = account_destroy(account);
    +
    + +

    Adding an Application on the Account Screen

    + +

    To add your application on the Add account screen of the device:

    + +
      +
    1. Add the required information in the manifest file: +
      <account>
      +   <account-provider appid="app-id name" providerid="url style string" multiple-accounts-support="true or false">
      +      <icon section="account">application icon name</icon>
      +      <icon section="account-small">application small icon name</icon>
      +      <label>Application name</label>
      +      <label xml:lang="en-gb">Application name</label>
      +      <label xml:lang="ko-kr">ߖȃخʼnL݇ Lا</label>
      +      <capability>http://tizen.org/account/capability/contact</capability>
      +      <capability>http://tizen.org/account/capability/calendar</capability>
      +   </account-provider>
      +</account>
      + +

      The required information includes:

      +
      • appid="app-id name" +

        Application ID (for example, appid="org.tizen.account").

      • +
      • providerid="url style string" +

        Provider identification string (for example, providerid="http://www.tizen.org").

      • +
      • multiple-accounts-support="true or false" +

        Multiple account support (if your application can manage 2 or more accounts, set to true; otherwise set to false)

      • +
      • <icon section="account">application icon name</icon> +

        Icon displayed on the Add account screen.

        +

        The icon size must be 72x72 px and the icon file must be in the {app-root}\shared\res\ directory.

      • +
      • <icon section="account-small">application small icon name</icon> +

        Small icon displayed on the Other application screen to represent the account provider.

        +

        The small icon file must be in the {app-root}\shared\res\ directory.

      • +
      • <label xml:lang="en-gb">Application name</label> +

        Application name displayed on the Add account screen, according to the selected language.

        +

        An account provider must have at least one label tag.

      • +
      • <capability>http://tizen.org/account/capability/contact</capability> +

        For more information, see the Account Manager guide.

      +
    2. + +
    3. Create the sign-in screen UI. +

      When the user selects your application on the Add account screen, the Account Service launches your application with a specific operation ID (ACCOUNT_OPERATION_SIGNIN) defined in the account-types.h header file, so the sign-in screen must be displayed.

      + +

      Figure: Sign-in screen

      +

      Sign-in screen

      +
    4. +
    + + + + + + + + + + +
    Note
    For more information on operations and events, see the Account Manager guide.
    + +

    Performing Database Queries

    + +

    To perform database queries:

    + + +
      +
    1. Prepare sample content. +

      To perform queries, you need existing content in the database. To access existing account, obtain it from the database. It can be done using a few functions, depending on the user requirements.

      +

      To create new content to the database:

      + +
      1. The create_Account() function creates a new account from a given account_h handle and account details (name, display name, domain, e-mail). 3 capabilities are added to the account to demonstrate some of the query functions. The capabilities as well as user custom types can be predefined.

        + +

        After creating the account, it is added to the database. When no longer needed, the account handle has to be destroyed using the account_destroy(account) function.

        + +
        +int id[3];
        +static account_h account = NULL;
        +
        +Create_Account(&account, "Person", "DiplayPerson", "Person Domain", "someone1@somewho.com");
        +
        +account_set_capability(account, "Custom", ACCOUNT_CAPABILITY_ENABLED);
        +
        +account_set_capability(account, "Next", ACCOUNT_CAPABILITY_ENABLED);
        + 
        +account_set_capability(account, "Another", ACCOUNT_CAPABILITY_DISABLED);
        +
        +account_insert_to_db(account, &id[0]);
        +
        +account_destroy(account);
        +
      2. + +
      3. Add 2 more accounts to the database.

        + +
        +Create_Account(&account, "PersonX", "DisplayX", "Other Domain", "someone2@somewho.com");
        +account_insert_to_db(account, &id[1]);
        +
        +account_destroy(account);
        +
        +Create_Account(&account, "Human", "Humanity", "Everyone", "someone3@somewho.com");
        +
        +account_insert_to_db(account, &id[2]);
        +
        +account_destroy(account);
        +
        +Create_Account(&account, "LastOne", "LastDisplay", "Last Domain", "someone4@somewho.com");
        +account_insert_to_db(account, &id[3]);
        +account_destroy(account);
        +
        +
      4. + +
      5. Create an account. +

        For more information, see Creating and Managing an Account.

        + +
        +static int Create_Account(account_h * account, char * account_name, char * display_name, char *  domain_name, char * email_address)
        +{
        +   account_create(account);
        +
        +   account_set_user_name(*account, account_name);
        +
        +   account_set_display_name(*account, display_name);
        +
        +   account_set_domain_name(*account, domain_name);
        +
        +   account_set_email_address(*account, email_address);
        +}
        +
      +
    2. + +
    3. List accounts. +
      1. +

        To verify the database insertion, all accounts are listed.

        + +
        +struct Account_Records
        +{
        +   int count;
        +   int tab[100];
        +};
        +
        +struct Account_Records rec;
        + 
        +List_Accounts(&rec);
        +
      2. + +
      3. When struct Account_Records* rec is not Null, List_Accounts counts all records in the database. Records are obtained using the account_foreach_account_from_db() function.

        + +
        +static void List_Accounts(struct Account_Records* rec)
        +{
        +   if (rec!=NULL)
        +   {
        +      rec->count=0;
        +   }
        +   account_foreach_account_from_db(on_account_read, rec);
        +}
        +
      4. + +
      5. For each found record, the on_account_read() callback function is called. If void *user_data is not null, the function is counting the existing accounts. String data returned by the get functions has to be released with free. Data prepared with the sprint() function can, for example, be sent for stdout.

        + +
        +static bool on_account_read(account_h account, void *user_data)
        +{
        +   int account_id = 0;
        +   char *name = NULL;
        +   char *display_name = NULL;
        +   struct Account_Records * rec = (struct Account_Records *)user_data;
        +   char buf[100];
        +
        +   account_get_account_id(account, &account_id);
        +
        +   sprintf(buf,"MyCallback ID: %d\n", account_id);
        +
        +   if (user_data!=NULL)
        +   {
        +      rec->tab[rec->count++]=account_id;
        +   }
        +   account_get_user_name(account, &name);
        +   sprintf(buf,"MyCallback Name: %s\n", name);
        +
        +   free(name);
        +
        +   account_get_display_name(account, &display_name);
        +   sprintf(buf,"MyCallback Disp.: %s\n", display_name);
        +
        +   free(display_name);
        +
        +   return 0;
        +}
        +
      +
    4. +
    5. Query the account by ID. +

      The easiest way to get access to an account stored in the database is referring to it by its ID. It can be done with the account_query_account_by_account_id() function. This function requires an existing handle to an account as an input parameter.

      + +
      +for (i=0; i<rec.count; i++)
      +{
      +   account_create(&account);
      +   account_query_account_by_account_id (rec.tab[i], &account);
      +
      +   Show_Account(account);
      +
      +   account_destroy(account);
      +}
      +
      +
    6. + +
    7. Show the account. +

      The following function prepares data to send it to any text output.

      + +
      +static int Show_Account(account_h acc)
      +{
      +   int account_id = 0;
      +   char *name = NULL;
      +   char *display_name = NULL;
      +   char buf[100];
      +
      +   account_get_account_id(acc, &account_id);
      +
      +   sprintf(buf,"Show_Account ID: %d\n", account_id);
      +
      +   account_get_user_name(acc, &name);
      +
      +   sprintf(buf,"Show_Account Name: %s\n", name);
      +
      +   free(name);
      +
      +   account_get_display_name(acc, &display_name);
      +
      +   sprintf(buf,"Show_Account Disp.: %s\n", display_name);
      +
      +   free(display_name);
      +
      +   return 0;
      +}
      +
      +
    8. + +
    9. Query the account by various attributes: +
      • Query by username. +

        Querying data by username requires providing a valid username callback function. In this example, it is the same function as for for_each, but cast without the third parameter.

        + +
        +account_query_account_by_user_name (on_account_read, "Human", NULL);
        +
        +
      • + +
      • Query by package name +

        By default, the accounts created in the application context have a package name set to the application name. Change it using the account_set_package_name() function. To list accounts by package name, the user can provide a name by itself or obtain it with the account_get_package_name() function.

        + +

        The account_query_account_by_package_name() function requires a callback function and a package name. In addition, the user data can be passed to the callback function as a third parameter.

        + +

        The package name has to be released when no longer needed.

        + +
        +char * package_name;
        +account_get_package_name (account, &package_name);
        +account_query_account_by_package_name (on_account_read, package_name, NULL);
        +free(package_name);
        +
        +
      • + +
      • Query by capability +

        The following function allows the user to find all accounts with a specified capability on a specified state. Once again, the callback function is required.

        + +
        +account_query_account_by_capability (on_account_read, "Custom", ACCOUNT_CAPABILITY_ENABLED, NULL);
        +
        +
      • + +
      • Query by capability type +

        This function is similar to the account_query_account_by_capability() function, but returns all accounts with a specified capability, without checking its state.

        + +
        +account_query_account_by_capability_type (on_account_read, "Next", NULL);
        +
        +
      • + +
      • Query capability by account ID +

        The account_query_capability_by_account_id() function is different from the previous functions. It lists all capabilities from an account with a specified ID. In this case it requires a different type of callback, as listed below.

        + +
        +account_query_capability_by_account_id (_capability_cb, id[0], NULL);
        +
        + +

        The callback function prepares data to be sent to an output.

        + +
        +static bool _capability_cb(const char *capability_type, account_capability_state_e capability_state, void *user_data)
        +{
        +   char buf[200];
        +   sprintf(buf,"Found capability: %s on state %d\n", capability_type, capability_state);
        +
        +   return true;
        +}
        +
        +
    10. + +
    11. Clean up. +

      When no longer needed, all handles to accounts have to be destroyed.

      + +
      +account_destroy(account);
      +
      +
    12. +
    + +

    Managing Account Secrecy

    + +

    To manage account secrecy:

    +
      +
    1. Select the secrecy level using the account_secrecy_state_e enumeration. + +
      +static account_h account = NULL;
      +account_secrecy_state_e secret;
      + 
      +char buf[200];
      +int ret;
      +int id;
      +
      +// Account 1
      +Create_Account(&account, "Security 1", "Invalid", "NOBODY", "anony@mous.not");
      +
      +account_set_secret(account, ACCOUNT_SECRECY_INVALID);
      +
      +account_get_secret(account, &secret);
      +
      +account_insert_to_db(account, &id);
      +
      +sprintf(buf,"Account 1 secret: %d\n", secret);
      +
      +account_destroy(account);
      +
      +// Account 2
      +
      +Create_Account(&account, "Security 2", "Invisible", " NOBODY", "anony1@mous.not");
      +
      +account_set_secret(account, ACCOUNT_SECRECY_INVISIBLE);
      +
      +account_get_secret(account, &secret);
      +
      +account_insert_to_db(account, &id);
      +
      +sprintf(buf, " Account 2 secret: %d\n", secret);
      +
      +account_destroy(account);
      +
      +// Account 3
      +
      +Create_Account(&account, "Secret 3", "Visible", " NOBODY", "anony2@mous.not");
      +
      +ret = account_set_secret(account, ACCOUNT_SECRECY_VISIBLE);
      +
      +ret = account_get_secret(account, &secret);
      +
      +ret = account_insert_to_db(account, &id);
      +
      +sprintf(buf," Account 3 secret: %d\n", secret);
      +
      +account_destroy(account);
      +
      +List_Accounts(NULL);
      +
      + +

      Secrecy is linked only with visibility on the account settings screen. The account is still visible and can be accessed using a query or the for_each function. For further information on how to add your application to the account screen, see Adding an Application on the Account Screen.

      + +
      // List_Account() console output
      +MyCallback ID: 12
      +MyCallback Name: Security 1
      +MyCallback Disp.: Invalid
      +-------------------
      +MyCallback ID: 13
      +MyCallback Name: Security 2
      +MyCallback Disp.: Invisible
      +-------------------
      +MyCallback ID: 14
      +MyCallback Name: Secret 3
      +MyCallback Disp.: Visible
      +
      +
    2. + +
    3. Clean up. +

      Account handles have to be destroyed when no longer needed.

      + +
      +account_destroy(account);
      +
      +
    4. +
    + +

    Updating Accounts

    + +

    To update and track account data.

    + +
      +
    1. Subscribe notifications. +

      To track account changes, create an account_subscribe_h instance and register a notification.

      + +
      +account_subscribe_h account_subscribe;
      +
      +account_subscribe_create(&account_subscribe);
      +
      +account_subscribe_notification(account_subscribe, _account_event_cb, NULL);
      +
      +
    2. + +
    3. Create an account. +

      Accounts are created and then their handles are destroyed. The package name is obtained from the second account.

      + +
      +Create_Account(&account, "Updater", "Updated?", "ToUpdate", "not.up@to.date");
      +account_insert_to_db(account, &id);
      +
      +Show_Account(account);
      +account_destroy(account);
      +
      +Create_Account(&account, "Another", "Updated?", "ToUpdate", "not.up@to.date");
      +account_insert_to_db(account, &id);
      +
      +account_get_package_name (account, &package_name);
      +sprintf(buf, "Package_name: %s\n", package_name);
      +
      +Show_Account(account);
      +account_destroy(account);
      +
      +
    4. + +
    5. Update the account. +
      • To update an account by its ID:

        +
          +
        1. Create a handle to the account.
        2. +
        3. Get the account from the database (also possible by ID).
        4. +
        5. Make the necessary changes.
        6. +
        7. Update the account using the account handle and a valid ID.
        8. +
        9. Destroy the account handle.
        10. +
        + +
        +account_create(&account);
        +account_query_account_by_account_id(id, &account);
        +account_set_display_name(account, "Updated!");
        +account_update_to_db_by_id(account, id);
        +account_destroy(account);
        +
        +
      • + +
      • Update account by user name. +

        To update an account by its user name:

        +
          +
        1. Create a handle to the account.
        2. +
        3. Get the account from the database (also by ID).
        4. +
        5. Make the necessary changes.
        6. +
        7. Update the account using the account handle, a valid user name, and a package name. There can be accounts with the same user names in different packages.
        8. +
        9. Destroy the account handle.
        10. +
        + +
        +account_create(&account);
        +account_query_account_by_account_id(id, &account);
        +account_set_display_name(account, "Updated!");
        +account_update_to_db_by_user_name(account, "Another", package_name);
        +account_destroy(account);
        +
      +
    6. + +
    7. Create the callback. +

      When any action is taking place on any account when a notification is subscribed, a callback function is invoked. The callback function provides in its parameters the event type as a string, the ID of the account associated with the actual change, and, additionally, the user data registered while subscribing the notification.

      + +
      +bool _account_event_cb(const char *event_type, int account_id, void *user_data)
      +{
      +   char buf[200];
      +
      +   sprintf(buf, "ACCOUNT EVENT: %s, %d\n", event_type, account_id);
      +
      +   return true;
      +}
      +
      +
    8. + +
    9. Show accounts. +

      To verify the updates, the account can be shown.

      + +
      +account_create(&account);
      +account_query_account_by_account_id(id, &account);
      +Show_Account(account);
      +account_destroy(account);
      +
      +
    10. + +
    11. Clean up. +

      Unsubscribe the notification when no longer needed.

      + +
      +account_unsubscribe_notification(account_subscribe);
      +
      +
    12. +
    + +

    Retrieving Account Types

    + +

    To retrieve account types:

    + +
      +
    1. Create a type. +

      To operate on the account type, create a handle to it.

      + +
      +account_type_h account_type;
      +
      +account_type_create(&account_type);
      +
      +
    2. + +
    3. Get the type information. +

      If the account type with a specified ID exists, you can get it from the database with the account_query_by_app_id() function.

      + +

      It is possible to set, for example:

      +
        +
      • ID
      • +
      • Labels
      • +
      • Features
      • +
      • Multiple account support (this is only a flag)
      • +
      + +

      To get the account types by the application ID, use the account_type_query_by_app_id() function.

      + +
      +int multiple_account_support = -1;
      +char *your_app_id = "com.tizen.example"; // App ID retrieving account types
      +char *app_id = NULL;
      +char *provider_feature = NULL;
      +char *icon_path = NULL;
      +
      +if (account_type_query_app_id_exist(your_app_id))
      +{
      +   account_type_query_by_app_id(your_app_id, &account_type);
      +
      +   account_type_get_app_id(account_type, &app_id);
      +
      +   account_type_get_multiple_account_support(account_type, &multiple_account_support);
      +
      +   account_type_get_icon_path(account_type, &icon_path);
      +
      +   account_type_get_provider_feature(account_type, &provider_feature);
      +}
      +
      +
    4. + +
    5. List types and labels. +

      To list the account types or all the labels from a specified type, a proper callback function has to be provided.

      + +
      +account_type_foreach_account_type_from_db(_account_type_cb, NULL);
      +
      +account_type_query_label_by_app_id(_account_label_cb, type_id, NULL);
      +
      + +

      While listing the labels, the user has access to the ID of the account type, label and its local value, and the user data passed while casting the query function.

      + +
      +bool _account_label_cb(char *app_id, char *label, char *locale, void *user_data)
      +{
      +   char buf[200];
      +
      +   sprintf(buf,"Get Label ID: %s LABEL: %s LOCALE %s\n", app_id, label, locale);
      +
      +   return true;
      +}
      +
      + +

      The account type callback has access to the account type and user data.

      + +
      +bool _account_type_cb(account_type_h account_type, void *user_data)
      +{
      +   char * id;
      +   int support;
      +   char buf[200];
      +
      +   account_type_get_app_id(account_type, &id);
      +
      +   account_type_get_multiple_account_support(account_type, &support);
      +   sprintf(buf,"Account Type ID: %s Multiple support %d:\n", id, support);
      +
      +   return true;
      +}
      +
      +
    6. + +
    7. Clean up. +

      All allocated handles have to be destroyed.

      + +
      +free(app_id);
      +free(provider_feature);
      +free(icon_path);
      +
      +account_type_destroy(account_type);
      +
      +
    8. +
    + + + + +
    + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.tutorials/html/native/social/calendar_tutorial_n.htm b/org.tizen.tutorials/html/native/social/calendar_tutorial_n.htm index 7d94e52..707fdf4 100644 --- a/org.tizen.tutorials/html/native/social/calendar_tutorial_n.htm +++ b/org.tizen.tutorials/html/native/social/calendar_tutorial_n.htm @@ -1,984 +1,984 @@ - - - - - - - - - - - - - Calendar: Managing Calendar Events and Accessing the Calendar Database - - - - - -
    - -

    Calendar: Managing Calendar Events and Accessing the Calendar Database

    - - -

    This tutorial demonstrates how you can manage events and todo tasks, and convert calendar details to and from the vCalendar format.

    - - - - - - - - - - -
    Note
    This feature is supported in mobile applications only.
    - -

    Warm-up

    -

    Become familiar with the Calendar API basics by learning about:

    - - - -

    Initializing the Calendar

    - -

    To initialize the Calendar Service:

    -
    1. -

      To use the functions and data types of the Calendar API, include the <calendar.h> header file in your application:

      -
      -#include <calendar.h>
      -
    2. - -
    3. -

      Most of API functions return error codes, so you must define at the beginning of your code the int type, which is used to store the error codes. Each time when a function returns error codes, verify the result of the operation.

    4. - -
    5. To connect to the Calendar Service, call the calendar_connect() function. Without this function, you cannot get access to the Calendar database.

      -
      int error_code;
      -error_code = calendar_connect();
      -if (error_code != CALENDAR_ERROR_NONE)
      -   dlog_print(DLOG_ERROR, LOG_TAG, "calendar_connect: %x\n", error_code);
      - - -

      When the Calendar APIs are no longer needed, disconnect from the service using the calendar_disconnect() function:

      -
      error_code = calendar_disconnect();
      -if (error_code != CALENDAR_ERROR_NONE)
      -   dlog_print(DLOG_ERROR, LOG_TAG, "calendar disconnect failed: %x\n", error_code);
    - - -

    Creating an Event

    - -

    To define and create a new event handle (record), since the Calendar Service uses the event handler mechanism:

    -

    Use the calendar_record_create() function with the defined event handle as a parameter to create an event associated to the event handle and an _calendar_event._uri parameter for the event type.

    -

    Verify the status of the error code. If the event is created correctly, the function returns CALENDAR_ERROR_NONE. If an error is reported, you can check the error and take appropriate action or stop other operations on the database.

    -
    calendar_record_h event = NULL;
    -error_code = calendar_record_create(_calendar_event._uri, &event);
    -if (error_code != CALENDAR_ERROR_NONE)
    -   dlog_print(DLOG_ERROR, LOG_TAG, "calendar_record_create: %x\n", error_code);
    - -

    Setting Event Properties

    - -

    To set the event properties:

    - -
    1. Set the event subject. -

      To set the subject, call calendar_record_set_str(). This function takes the event handle (created before), as the first argument, _calendar_event.summary for subject type, and the subject, which is a string value, as the third argument. The calendar_record_set_str() function returns the status code. If the function returns an error, take appropriate action, such as freeing memory, removing handles, and disconnecting from the service, if needed.

      -
      error_code = calendar_record_set_str(event, _calendar_event.summary, "summary");
      -if (error_code != CALENDAR_ERROR_NONE)
      -   dlog_print(DLOG_ERROR, LOG_TAG, "set record summary failed : %x\n", error_code);
    2. -
    3. Set the event description. -

      The calendar_record_set_str() function sets the description of the event when the second argument is _calendar_event.description. This function takes the event handle as the first argument, and the description, which is a string value, as the third argument. The description argument is taken from the UI part of the application. The function returns the status code. If the function returns an error, take appropriate action, such as freeing memory, removing handles, and disconnecting from the service, if needed.

      -
      error_code = calendar_record_set_str(event, _calendar_event.description, "description");
      -if (error_code != CALENDAR_ERROR_NONE)
      -   dlog_print(DLOG_ERROR, LOG_TAG, "set description failed : %x\n", error_code);
    4. -
    5. Set the event time zone ID. -

      The start and end time must be inserted in the event. If the time zone ID is not inserted, the time zone for the start and end time is considered to be UTC. The properties are in the calendar_view.h file.

      -
      error_code = calendar_record_set_str(event, _calendar_event.start_tzid, "Asia/Seoul");
      -if (error_code != CALENDAR_ERROR_NONE)
      -   dlog_print(DLOG_ERROR, LOG_TAG, "set start_tzid failed : %x\n", error_code);
      -
      -error_code = calendar_record_set_str(event, _calendar_event.end_tzid, "Asia/Seoul");
      -if (error_code != CALENDAR_ERROR_NONE)
      -   dlog_print(DLOG_ERROR, LOG_TAG, "set end_tzid failed : %x\n", error_code);
    6. -
    7. Set the event start and end dates. -

      You can set the other properties similarly. To set the start date, call the calendar_record_set_caltime() functions and check the error codes.

      -
      calendar_time_s starttime = {0};
      -starttime.type = CALENDAR_TIME_UTIME;
      -starttime.time.utime = 1404036000; // 2014/06/29 10:00:00 UTC
      -error_code = calendar_record_set_caltime(event, _calendar_event.start_time, starttime);
      -if (error_code != CALENDAR_ERROR_NONE)
      -   dlog_print(DLOG_ERROR, LOG_TAG, "set start_time failed : %x\n", error_code);
      -
      -calendar_time_s endtime = {0};
      -endtime.type = CALENDAR_TIME_UTIME;
      -endtime.time.utime = 1404036000 + 3600; // 2014/06/29 11:00:00 UTC
      -error_code = calendar_record_set_caltime(event, _calendar_event.end_time, endtime);
      -if (error_code != CALENDAR_ERROR_NONE)
      -   dlog_print(DLOG_ERROR, LOG_TAG, "set end_time failed : %x\n", error_code);
      -

      The calendar_time_s has 2 types. For more information about the types, see the Calendar guide.

      -
    8. -
    9. Set the event frequency. -

      To create recurring events, set the frequency property.

      -
      error_code = calendar_record_set_int(event, _calendar_event.freq, CALENDAR_RECURRENCE_MONTHLY);
      -if (error_code != CALENDAR_ERROR_NONE)
      -   dlog_print(DLOG_ERROR, LOG_TAG, "set start_time failed : %x\n", error_code);
      -
      -error_code = calendar_record_set_int(event, _calendar_event.interval, 1);
      -if (error_code != CALENDAR_ERROR_NONE)
      -   dlog_print(DLOG_ERROR, LOG_TAG, "set start_time failed : %x\n", error_code);
      -
      -error_code = calendar_record_set_str(event, _calendar_event.bymonthday, "3,4,5");
      -if (error_code != CALENDAR_ERROR_NONE)
      -   dlog_print(DLOG_ERROR, LOG_TAG, "set start_time failed : %x\n", error_code);
    10. -
    11. Set the range of recurrence for the event. -
      error_code = calendar_record_set_int(event, _calendar_event.range_type, CALENDAR_RANGE_COUNT);
      -if (error_code != CALENDAR_ERROR_NONE)
      -   dlog_print(DLOG_ERROR, LOG_TAG, "set range_type failed : %x\n", error_code);
      -
      -error_code = calendar_record_set_int(event, _calendar_event.count, 8);
      -if (error_code != CALENDAR_ERROR_NONE)
      -   dlog_print(DLOG_ERROR, LOG_TAG, "set count failed : %x\n", error_code);
    12. - -
    13. Add an alarm. -

      To add an alarm, create an alarm handle and insert it as a child.

      -
      calendar_record_h alarm = NULL;
      -calendar_time_s ct;
      -error_code = CALENDAR_ERROR_NONE;
      -error_code += calendar_record_create(_calendar_alarm._uri, &alarm);
      -error_code += calendar_record_set_int(alarm, _calendar_alarm.tick_unit, CALENDAR_ALARM_TIME_UNIT_SPECIFIC);
      -ct.type = CALENDAR_TIME_UTIME;
      -ct.time.utime = 1404036000 - 60; // 60 sec before starttime (1404036000)
      -error_code += calendar_record_set_caltime(alarm, _calendar_alarm.alarm_time, ct);
      -error_code += calendar_record_add_child_record(event, _calendar_event.calendar_alarm, alarm);
      -
      -if (error_code != CALENDAR_ERROR_NONE)
      -   dlog_print(DLOG_ERROR, LOG_TAG, "calendar add alarm failed \n");
      -

      The following alarm tick units are available:

      -
      • CALENDAR_ALARM_TIME_UNIT_MINUTE
      • -
      • CALENDAR_ALARM_TIME_UNIT_HOUR
      • -
      • CALENDAR_ALARM_TIME_UNIT_DAY
      • -
      • CALENDAR_ALARM_TIME_UNIT_WEEK
      • -
      • CALENDAR_ALARM_TIME_UNIT_MONTH (not recommended)
      • -
      • CALENDAR_ALARM_TIME_UNIT_SPECIFIC (must use specific unixtime)
    14. -
    15. Add an attendee. -

      To add an attendee, create an attendee handle and insert it as a child.

      -
      calendar_record_h attendee = NULL;
      -error_code = CALENDAR_ERROR_NONE;
      -error_code += calendar_record_create(_calendar_attendee._uri, &attendee);
      -error_code += calendar_record_set_str(attendee, _calendar_attendee.name, "John");
      -error_code += calendar_record_add_child_record(event, _calendar_event.calendar_attendee, attendee);
      -
      -if (error_code != CALENDAR_ERROR_NONE)
      -   dlog_print(DLOG_ERROR, LOG_TAG, "calendar add alarm failed \n");
    - -

    Inserting an Event to the Database

    - -

    To insert an event record:

    - -
    1. Use the calendar_db_insert_record() function to insert the newly created event into the Calendar database. The first argument is the event handle, the second is the record ID - a unique ID is assigned to the event you are adding and returned as the second argument. If the event is inserted successfully, the function returns CALENDAR_ERROR_NONE. -
      int id = -1;
      -error_code = calendar_db_insert_record(event, &id);
      -if (error_code != CALENDAR_ERROR_NONE)
      -   dlog_print(DLOG_ERROR, LOG_TAG, "db insert record failed: %x\n", error_code);
      -
      -dlog_print(DLOG_ERROR, LOG_TAG, "id: %d\n", id);
    2. -
    3. After inserting, destroy the used structures: -
      calendar_record_destroy(event, true);
    - -

    Getting Events

    - -

    To retrieve a single event or all events one by one. You can also filter the events by one of the properties:

    - -
    1. Get a single event record using its ID. -
      calendar_record_h record;
      -const int event_id = ... // Acquire event ID
      -error_code = calendar_db_get_record(_calendar_event._uri, event_id, &record);
      -if (error_code != CALENDAR_ERROR_NONE)
      -   dlog_print(DLOG_ERROR, LOG_TAG, "db get record failed: %x\n", error_code);
    2. -
    3. Get the event record list. -

      To get all events without filtering, you need a record list:

      -
      calendar_list_h list = NULL;
      -error_code = calendar_db_get_all_records(_calendar_event._uri, 0, 0, &list);
      -if (error_code != CALENDAR_ERROR_NONE)
      -   dlog_print(DLOG_ERROR, LOG_TAG, "db get all records failed: %x\n", error_code);
    4. - -
    5. Filter the list. -
      1. -

        To get events with filtering, you need a record list and a query:

        -
        calendar_list_h list = NULL;
        -calendar_query_h query = NULL;
        -
        -error_code = calendar_query_create(_calendar_event._uri, &query);
        -if (error_code != CALENDAR_ERROR_NONE)
        -   dlog_print(DLOG_ERROR, LOG_TAG, "create query failed: %x\n", error_code);
      2. -
      3. Before retrieving the events, create a filter for the list. You can filter the list based on various parameters. -
        calendar_filter_h filter = NULL;
        -
        -error_code = calendar_filter_create (_calendar_event._uri, &filter);
        -if (error_code != CALENDAR_ERROR_NONE)
        -   dlog_print(DLOG_ERROR, LOG_TAG, "create filter failed: %x\n", error_code);
      4. -
      5. Add a condition, such as summary: -
        error_code = calendar_filter_add_str(filter, _calendar_event.summary, CALENDAR_MATCH_CONTAINS, "summary to find");
        -if (error_code != CALENDAR_ERROR_NONE)
        -   dlog_print(DLOG_ERROR, LOG_TAG, "filter add string failed: %x\n", error_code);
        -
      6. -
      7. To add more conditions, define an operator between the conditions: -
        error_code = calendar_filter_add_operator(filter, CALENDAR_FILTER_OPERATOR_AND);
        -if (error_code != CALENDAR_ERROR_NONE)
        -   dlog_print(DLOG_ERROR, LOG_TAG, "filter add operator failed: %x\n", error_code);
        -
        -error_code = calendar_filter_add_str(filter, _calendar_event.description, CALENDAR_MATCH_CONTAINS, "description to find");
        -if (error_code != CALENDAR_ERROR_NONE)
        -   dlog_print(DLOG_ERROR, LOG_TAG, "filter add string failed: %x\n", error_code);
        -

        In the above example, only events which contain a summary "summary to find" and description "description to find" are retrieved.

        -

        You can create a filter with integer and time conditions. For instance, to filter all day events which start after 1st January 2014, add the following filter:

        -
        calendar_time_s time_to_compare = {0};
        -time_to_compare.type = CALENDAR_TIME_LOCALTIME;
        -time_to_compare.time.date.mday = 1;
        -time_to_compare.time.date.month = 1;
        -time_to_compare.time.date.year = 2014;
        -error_code = calendar_filter_add_caltime(filter, _calendar_event.start_time, CALENDAR_MATCH_GREATER_THAN, time_to_compare);
        -if (error_code != CALENDAR_ERROR_NONE)
        -   dlog_print(DLOG_ERROR, LOG_TAG, "filter add caltime failed: %x\n", error_code);
        -

        The type parameter determines whether the event is a daily (CALENDAR_TIME_LOCALTIME) non-all-day event (CALENDAR_TIME_UTIME). To get the specified time period, use 2 conditions using CALENDAR_MATCH_GREATER_THAN and CALENDAR_MATCH_LESS_THAN with the operator CALENDAR_FILTER_OPERATOR_OR. You can also use CALENDAR_MATCH_EQUAL to set an equality condition.

      8. -
      9. Connect the query with the list: -
        error_code = calendar_query_set_filter(query, filter);
        -if (error_code != CALENDAR_ERROR_NONE)
        -   dlog_print(DLOG_ERROR, LOG_TAG, "query set filter failed: %x\n", error_code);
        -
        -error_code = calendar_db_get_records_with_query(query, 0, 0, &list);
        -if (error_code != CALENDAR_ERROR_NONE)
        -   dlog_print(DLOG_ERROR, LOG_TAG, "db get records with query failed: %x\n", error_code);
        - -

        The third parameter refers to a limit of the results. If 0 is passed, there are no limits. Remember that after all operations, the list must be released.

      10. -
      11. Free the filter and query: -
        calendar_filter_destroy(filter);
        -calendar_query_destroy(query);
    6. - -
    7. Iterate the list and read the records. -
      1. Get records from the list using calendar_list_get_current_record_p(), and calendar_list_next() or calendar_list_prev(). Inside the loop, get details of each record. -

        Note on the returned values' ownership: some functions have the _p postfix. It means that the returned value must not be freed by the application, as it is a pointer to the data in an existing record.

        -
        calendar_record_h record;
        -while (calendar_list_get_current_record_p(list, &record) == CALENDAR_ERROR_NONE)
        -{
        -   char* summary;
        -   calendar_record_get_str_p(record, _calendar_event.summary, &summary);
        -   dlog_print(DLOG_ERROR, LOG_TAG, "summary: %s\n", summary);
        -
        -   error_code = calendar_list_next(list);
        -   if (error_code != CALENDAR_ERROR_NONE)
        -      break;
        -}
      2. -
      3. If you want to get more details of each record, use the calendar_gl_event_data_t structure like below: -
        calendar_gl_event_data_t *gl_event_data = NULL;
        -calendar_record_h record = NULL;
        -while (calendar_list_get_current_record_p(list, &record) == CALENDAR_ERROR_NONE)
        -{
        -   gl_event_data = _create_gl_event_data(record);
        -   // You can get, for example, summary:
        -   // gl_event_data->summary
        -
        -   _free_gl_event_data(gl_event_data);
        -
        -   error_code = calendar_list_next(list);
        -   if (error_code != CALENDAR_ERROR_NONE)
        -      break;
        -}
      4. - -
      5. The memory for the record data is allocated, and the data is copied from the record by the functions listed further on in this document. -
        typedef struct _calendar_gl_event_data
        -{
        -   int id;
        -   char *summary;
        -   char *description;
        -   calendar_time_s start_time;
        -} calendar_gl_event_data_t;
        -
        -static void _free_gl_event_data(calendar_gl_event_data_t *gl_event_data)
        -{
        -   if (NULL == gl_event_data)
        -      return;
        -   free(gl_event_data->summary);
        -   free(gl_event_data->description);
        -   free(gl_event_data);
        -}
        -
        -static calendar_gl_event_data_t *_create_gl_event_data(calendar_record_h record)
        -{
        -   calendar_gl_event_data_t *gl_event_data;
        -   int error_code;
        -
        -   gl_event_data = malloc(sizeof(calendar_gl_event_data_t));
        -   memset(gl_event_data, 0x0, sizeof(calendar_gl_event_data_t));
        -
        -   error_code = calendar_record_get_str(record, _calendar_event.summary, &gl_event_data->summary);
        -   if (error_code != CALENDAR_ERROR_NONE)
        -   {
        -      dlog_print(DLOG_ERROR, LOG_TAG, "record get summary failed: %i\n", error_code);
        -      _free_gl_event_data(gl_event_data);
        -
        -      return NULL;
        -   }
        -
        -   error_code = calendar_record_get_str(record, _calendar_event.description, &gl_event_data->description);
        -   if (error_code != CALENDAR_ERROR_NONE)
        -   {
        -      dlog_print(DLOG_ERROR, LOG_TAG, "record get description failed: %i\n", error_code);
        -      _free_gl_event_data(gl_event_data);
        -
        -      return NULL;
        -   }
        -
        -   error_code = calendar_record_get_int(record, _calendar_event.id, &gl_event_data->id);
        -   if (error_code != CALENDAR_ERROR_NONE)
        -   {
        -      dlog_print(DLOG_ERROR, LOG_TAG, "record get id failed: %i\n", error_code);
        -      _free_gl_event_data(gl_event_data);
        -
        -      return NULL;
        -   }
        -
        -   error_code = calendar_record_get_caltime(record, _calendar_event.start_time, &gl_event_data->start_time);
        -   if (error_code != CALENDAR_ERROR_NONE)
        -   {
        -      dlog_print(DLOG_ERROR, LOG_TAG, "calendar get start time failed: %i\n", error_code);
        -      _free_gl_event_data(gl_event_data);
        -
        -      return NULL;
        -   }
        -
        -   return gl_event_data;
        -}
        -

        To get access to a specified data from the record, firstly it is necessary to get its child responsible for the requested type.

    8. -
    9. Free the list: -
      calendar_list_destroy(list, true);
    - - -

    Updating an Event

    - -

    To update an event record:

    - -
    1. Get the event record handle to update with the ID. -
      calendar_record_h record;
      -const int event_id = ... // Acquire event ID
      -error_code = calendar_db_get_record(_calendar_event._uri, event_id, &record);
      -if (error_code != CALENDAR_ERROR_NONE)
      -   dlog_print(DLOG_ERROR, LOG_TAG, "db get record failed: %x\n", error_code);
    2. -
    3. Set the properties to update. -
      error_code = calendar_record_set_str(record, _calendar_event.summary, "summary updated");
      -if (error_code != CALENDAR_ERROR_NONE)
      -   dlog_print(DLOG_ERROR, LOG_TAG, "record set summary failed: %x\n", error_code);
      -
      -error_code = calendar_record_set_str(record, _calendar_event.description, "description updated");
      -if (error_code != CALENDAR_ERROR_NONE)
      -   dlog_print(DLOG_ERROR, LOG_TAG, "record set description failed: %x\n", error_code);
    4. -
    5. To update the record, call the calendar_db_update_record() function. -
      error_code = calendar_db_update_record(record);
      -if (error_code != CALENDAR_ERROR_NONE)
      -   dlog_print(DLOG_ERROR, LOG_TAG, "db update record failed: %x\n", error_code);
    6. -
    7. When the event handle is no longer needed, use the calendar_record_destroy() function to destroy the event handle and free the allocated memory. -
      calendar_record_destroy(record, true);
    - -

    Deleting an Event

    - -

    To delete an event, call the calendar_db_delete_record() function with _calendar_event._uri as the first parameter and event ID as the second one:

    -
    int event_id = ... // Acquire event ID
    -error_code = calendar_db_delete_record(_calendar_event._uri, event_id);
    -if (error_code != CALENDAR_ERROR_NONE)
    -   dlog_print(DLOG_ERROR, LOG_TAG, "db delete record failed: %x\n", error_code);
    - -

    Setting Exceptions when Inserting Events

    - -

    To set an exception date to an event record when creating the event:

    - -
    1. Create a recurring event. -

      The following example creates an event record with the following properties:

      -
      • Frequency: CALENDAR_RECURRENCE_MONTHLY
      • -
      • Interval: 1
      • -
      • Bymonthday: "3, 4, 5"
      • -
      • Range type: count
      • -
      • Count: 8
      - -
      int error_code = CALENDAR_ERROR_NONE;
      -
      -calendar_record_h event = NULL;
      -error_code += calendar_record_create(_calendar_event._uri, &event);
      -error_code += calendar_record_set_str(event, _calendar_event.summary, "test");
      -error_code += calendar_record_set_str(event, _calendar_event.start_tzid, "Asia/Seoul");
      -error_code += calendar_record_set_str(event, _calendar_event.end_tzid, "Asia/Seoul");
      -
      -calendar_time_s st = {0};
      -st.type = CALENDAR_TIME_UTIME;
      -st.time.utime = 1349226000;
      -error_code += calendar_record_set_caltime(event, _calendar_event.start_time, st);
      -
      -calendar_time_s et = {0};
      -et.type = CALENDAR_TIME_UTIME;
      -et.time.utime = 1354582800;
      -error_code += calendar_record_set_caltime(event, _calendar_event.end_time, et);
      -
      -error_code += calendar_record_set_int(event, _calendar_event.freq, CALENDAR_RECURRENCE_MONTHLY);
      -error_code += calendar_record_set_int(event, _calendar_event.interval, 1);
      -error_code += calendar_record_set_str(event, _calendar_event.bymonthday, "3,4,5");
      -
      -error_code += calendar_record_set_int(event, _calendar_event.range_type, CALENDAR_RANGE_COUNT);
      -error_code += calendar_record_set_int(event, _calendar_event.count, 8);
      -
      -if (error_code != CALENDAR_ERROR_NONE)
      -   dlog_print(DLOG_ERROR, LOG_TAG, "calendar record create failed: \n");
      - -

      The created event has 8 instances.

      - - - - - - - - - - - - - - -
      - Table: Event instances -
      unixtimeDate time
      1349226000 -
      1349312400 -
      1349398800 -
      1351904400 -
      1351990800 -
      1352077200 -
      1354496400 -
      1354582800
      2012-10-03 01:00:00 -
      2012-10-04 01:00:00 -
      2012-10-05 01:00:00 -
      2012-11-03 01:00:00 -
      2012-11-04 01:00:00 -
      2012-11-05 01:00:00 -
      2012-12-03 01:00:00 -
      2012-12-04 01:00:00
    2. -
    3. Set the exdate property to create the exception. -

      In vcalendar 2.0 (RFC 2445), exdate is used to identify a deleted instance. If multiple instances are deleted, datetimes are added with a comma (such as 20121104T010000Z, 20121105T010000Z, 20121203T010000Z).

      -
      error_code = calendar_record_set_str(event, _calendar_event.exdate, "20121104T010000Z");
      -if (error_code != CALENDAR_ERROR_NONE)
      -   dlog_print(DLOG_ERROR, LOG_TAG, "calendar record set string failed: %x\n", error_code);
    4. -
    5. Insert the record. -

      Use the calendar_db_insert_record() function to insert the event into the Calendar database.

      -
      int event_id;
      -error_code = calendar_db_insert_record(event, &event_id);
      -if (error_code != CALENDAR_ERROR_NONE)
      -   dlog_print(DLOG_ERROR, LOG_TAG, "calendar db insert record failed: %x\n", error_code);
      -
      -calendar_record_destroy(event, true);
    - -

    Adding an Exception Date for an Existing Event

    - -

    To add an exception date to an existing event:

    - -
    1. Make sure you have an existing event.
    2. -
    3. Clone the existing event record and set new properties for the exception. -

      Cloning means that the new record has the original event's properties. In vcalendar 2.0 (RFC 2445), the recurrence ID is used to identify the modified instance (exception).

      -
      calendar_record_h clone = NULL;
      -error_code = CALENDAR_ERROR_NONE;
      -
      -error_code += calendar_record_clone(event, &clone);
      -error_code += calendar_record_set_int(clone, _calendar_event.original_event_id, event_id);
      -error_code += calendar_record_set_str(clone, _calendar_event.recurrence_id, "20121005T010000Z");
      -
      -if (error_code != CALENDAR_ERROR_NONE)
      -   dlog_print(DLOG_ERROR, LOG_TAG, "calendar record clone failed: %x\n", error_code);
    4. -
    5. Insert the new record. -

      Use the calendar_db_insert_record() function to insert the new event record into the Calendar database.

      -
      int exdate_event_id = 0;
      -error_code = calendar_db_insert_record(clone, &exdate_event_id);
      -if (error_code != CALENDAR_ERROR_NONE)
      -   dlog_print(DLOG_ERROR, LOG_TAG, "calendar db insert record failed: %x\n", error_code);
      -
      -calendar_record_destroy(clone, true);
      -calendar_record_destroy(event, true);
    - - -

    Monitoring Event Changes

    - -

    To register a callback function that listens for event changes:

    -
    1. Register the callback function. -
      error_code = calendar_db_add_changed_cb(_calendar_event._uri, _event_changed_callback, NULL);
      -if (error_code != CALENDAR_ERROR_NONE)
      -   dlog_print(DLOG_ERROR, LOG_TAG, "db add changed cb failed: %x\n", error_code);
    2. -
    3. Define the callback function. -

      The callback function is called when an event changes. The code below shows how to get the new event details.

      -
      static calendar_gl_event_data_t *_gl_event_data = ...
      -static void _event_changed_callback(const char *view_uri, void *user_data)
      -{
      -   if (0 != strcmp(view_uri, _calendar_event._uri))
      -      return;
      -
      -   if (NULL == _gl_event_data)
      -      return;
      -
      -   int event_id = _gl_event_data->id;
      -   _free_gl_event_data(_gl_event_data);
      -   _gl_event_data = NULL;
      -
      -   calendar_record_h record = NULL;
      -   int error_code;
      -   error_code = calendar_db_get_record(_calendar_event._uri, event_id, &record);
      -   if (error_code != CALENDAR_ERROR_NONE)
      -      return;
      -
      -    _gl_event_data = _create_gl_event_data(record);
      -   // Use _gl_event_data
      -
      -   calendar_record_destroy(record, true);
      -}
    - -

    Creating a Todo

    - -

    To define and create a new todo handle record, since the Calendar Service uses a todo handler mechanism:

    -

    Use the calendar_record_create() function with the defined todo handle as a parameter to create a todo associated with the todo handle and a _calendar_todo._uri parameter for the todo type.

    -

    Verify the status of the error code. If the todo handle is created correctly, the function returns CALENDAR_ERROR_NONE. If an error is reported, check the error and take appropriate action, or stop other operations on the database.

    -
    calendar_record_h todo = NULL;
    -error_code = calendar_record_create(_calendar_todo._uri, &todo);
    -if (error_code != CALENDAR_ERROR_NONE)
    -   dlog_print(DLOG_ERROR, LOG_TAG, "calendar_record_create: %x\n", error_code);
    - -

    Setting Todo Properties

    - -

    To set the todo properties:

    -
    1. Set the todo subject. -

      To set the subject, call calendar_record_set_str(). This function takes the todo handle (created before) as the first argument, _calendar_todo.summary for the subject type, and the subject, which is string value, as the third argument. The calendar_record_set_str() function returns the status code. If the function returns an error, take appropriate action, such as freeing memory, removing handles, and disconnecting from the service, if needed.

      -
      error_code = calendar_record_set_str(todo, _calendar_todo.summary, "summary");
      -if (error_code != CALENDAR_ERROR_NONE)
      -   dlog_print(DLOG_ERROR, LOG_TAG, "set summary failed : %x\n", error_code);
    2. -
    3. Set the todo description. -

      The calendar_record_set_uri() function sets the description of the todo when the second argument is _calendar_todo.description. This function takes the todo handle as the first argument, and the description, which is string value, as the third argument. The description argument is taken from the UI part of the application. The function returns the status code. If the function returns an error, take appropriate action, such as freeing memory, removing handles, and disconnecting from the service, if needed.

      -
      error_code = calendar_record_set_str(todo, _calendar_todo.description, "description");
      -if (error_code != CALENDAR_ERROR_NONE)
      -   dlog_print(DLOG_ERROR, LOG_TAG, "set description failed : %x\n", error_code);
    4. -
    5. Set the todo due date. -

      To set the due date, call the calendar_record_set_caltime function and check the error codes.

      -
      calendar_time_s duetime = {0};
      -duetime.type = CALENDAR_TIME_UTIME;
      -duetime.time.utime = 1404036000; // 2014/06/29 11:00:00 UTC
      -
      -error_code = calendar_record_set_caltime(todo, _calendar_todo.due_time, duetime);
      -if (error_code != CALENDAR_ERROR_NONE)
      -   dlog_print(DLOG_ERROR, LOG_TAG, "set due_time failed : %x\n", error_code);
    6. -
    7. Set the todo status. -

      You can set the other properties similarly. To set the todo status, call the calendar_record_set_int() function and check the error codes.

      -
      error_code = calendar_record_set_int(todo, _calendar_todo.todo_status, CALENDAR_TODO_STATUS_COMPLETED);
      -if (error_code != CALENDAR_ERROR_NONE)
      -   dlog_print(DLOG_ERROR, LOG_TAG, "set todo_status failed : %x\n", error_code);
    - -

    Inserting a Todo to the Database

    - -

    To insert a todo record:

    -
    1. Use the calendar_db_insert_record() function to insert a newly created todo into the Calendar database. The first argument is the todo handle, the second is the record ID. A unique ID is assigned to the record you are adding, and is returned as the third argument of the called function. If the todo is inserted successfully, the function returns CALENDAR_ERROR_NONE. -
      int id;
      -error_code = calendar_db_insert_record(todo, &id);
      -if (error_code != CALENDAR_ERROR_NONE)
      -   dlog_print(DLOG_ERROR, LOG_TAG, "db insert record failed: %x\n", error_code);
    2. -
    3. After inserting, destroy the used structures: -
      calendar_record_destroy(todo, true);
    - -

    Getting Todos

    - -

    To retrieve a single todo or all todos one by one. You can also filter the todos by one of the properties:

    - -
    1. Get a single todo record using its ID. -
      calendar_record_h record;
      -const int todo_id = ... // Acquire todo ID
      -error_code = calendar_db_get_record(_calendar_todo._uri, todo_id, &record);
      -if (error_code != CALENDAR_ERROR_NONE)
      -   dlog_print(DLOG_ERROR, LOG_TAG, "db get record failed: %x\n", error_code);
    2. -
    3. Get the todo record list. -

      To get all todos without filtering, you need a record list:

      -
      calendar_list_h list = NULL;
      -error_code = calendar_db_get_all_records(_calendar_todo._uri, 0, 0, &list);
      -if (error_code != CALENDAR_ERROR_NONE)
      -   dlog_print(DLOG_ERROR, LOG_TAG, "db get all records failed: %x\n", error_code);
    4. -
    5. Filter the list. -
      1. To get todos with filtering, you need a record list and a query: -
        calendar_list_h list = NULL;
        -calendar_query_h query = NULL;
        -
        -error_code = calendar_query_create(_calendar_todo._uri, &query);
        -if (error_code != CALENDAR_ERROR_NONE)
        -   dlog_print(DLOG_ERROR, LOG_TAG, "create query failed: %x\n", error_code);
      2. -
      3. Before retrieving the todos, create a filter for the list. You can filter the list based on various parameters. -
        calendar_filter_h filter = NULL;
        -
        -error_code = calendar_filter_create (_calendar_todo._uri, &filter);
        -if (error_code != CALENDAR_ERROR_NONE)
        -   dlog_print(DLOG_ERROR, LOG_TAG, "create filter failed: %x\n", error_code);
      4. -
      5. Add a condition, such as summary: -
        error_code = calendar_filter_add_str(filter, _calendar_todo.summary, CALENDAR_MATCH_CONTAINS, "summary to find");
        -if (error_code != CALENDAR_ERROR_NONE)
        -   dlog_print(DLOG_ERROR, LOG_TAG, "filter add string failed: %x\n", error_code);
      6. -
      7. To add more conditions, define an operator between the conditions: -
        error_code = calendar_filter_add_operator(filter, CALENDAR_FILTER_OPERATOR_AND);
        -if (error_code != CALENDAR_ERROR_NONE)
        -   dlog_print(DLOG_ERROR, LOG_TAG, "filter add operator failed: %x\n", error_code);
        -
        -error_code = calendar_filter_add_str(filter, _calendar_todo.description, CALENDAR_MATCH_CONTAINS, "description to find");
        -if (error_code != CALENDAR_ERROR_NONE)
        -   dlog_print(DLOG_ERROR, LOG_TAG, "filter add string failed: %x\n", error_code);
        -

        In the above example, only todos which contain a summary "summary to find" and description "description to find" are retrieved.

        -

        You can create a filter with integer and time conditions. For instance, to filter all todos which are completed, add the following filter:

        -
        error_code = calendar_filter_add_int(filter, _calendar_todo.todo_status, CALENDAR_MATCH_EQUAL, CALENDAR_TODO_STATUS_COMPLETED);
        -if (error_code != CALENDAR_ERROR_NONE)
        -   dlog_print(DLOG_ERROR, LOG_TAG, "filter add integer failed: %x\n", error_code);
      8. -
      9. Connect the query with the list: -
        error_code = calendar_query_set_filter(query, filter);
        -if (error_code != CALENDAR_ERROR_NONE)
        -   dlog_print(DLOG_ERROR, LOG_TAG, "query set filter failed: %x\n", error_code);
        -
        -error_code = calendar_db_get_records_with_query(query, 0, 0, &list);
        -if (error_code != CALENDAR_ERROR_NONE)
        -   dlog_print(DLOG_ERROR, LOG_TAG, "db get records with query failed: %x\n", error_code);
        -

        The third parameter refers to a limit of the results. If 0 is passed, there are no limits. Remember that after all operations, the list must be released.

      10. - -
      11. Free the filter and query: -
        calendar_filter_destroy(filter);
        -calendar_query_destroy(query);
      12. -
    6. -
    7. Iterate the list and read the records. -
      1. Get records from the list using calendar_list_get_current_record_p(), and calendar_list_next() or calendar_list_prev(). Inside the loop, get details of each record. -

        Note on the returned values' ownership: some functions have the _p postfix. It means that the returned value must not be freed by the application, as it is a pointer to the data in an existing record.

        -
        calendar_record_h record;
        -while (calendar_list_get_current_record_p(list, &record) == CALENDAR_ERROR_NONE)
        -{
        -   char* summary;
        -   calendar_record_get_str_p(record, _calendar_todo.summary, &summary);
        -   dlog_print(DLOG_ERROR, LOG_TAG, "summary: %s\n", summary);
        -
        -   error_code = calendar_list_next(list);
        -   if (error_code != CALENDAR_ERROR_NONE)
        -      break;
        -}
      2. -
      3. If you want to get more details of each record, use the calendar_gl_todo_data_t structure like below: -
        calendar_gl_todo_data_t *gl_todo_data = NULL;
        -calendar_record_h record = NULL;
        -while (calendar_list_get_current_record_p(list, &record) == CALENDAR_ERROR_NONE)
        -{
        -   gl_todo_data = _create_gl_todo_data(record);
        -   // You can get, for example, summary:
        -   // gl_todo_data->summary
        -
        -   _free_gl_todo_data(gl_todo_data);
        -
        -   error_code = calendar_list_next(list);
        -   if (error_code != CALENDAR_ERROR_NONE)
        -      break;
        -}
      4. - -
      5. The memory for the record data is allocated, and the data is copied from the record by the functions listed further on in this document. -
        typedef struct _calendar_gl_todo_data
        -{
        -   int id;
        -   char *summary;
        -   char *description;
        -   calendar_time_s due_time;
        -} calendar_gl_todo_data_t;
        -
        -static void _free_gl_todo_data(calendar_gl_todo_data_t *gl_todo_data)
        -{
        -   if (NULL == gl_todo_data)
        -      return;
        -   free(gl_todo_data->summary);
        -   free(gl_todo_data->description);
        -   free(gl_todo_data);
        -}
        -
        -static calendar_gl_todo_data_t *_create_gl_todo_data(calendar_record_h record)
        -{
        -   calendar_gl_todo_data_t *gl_todo_data;
        -   int error_code;
        -
        -   gl_todo_data = malloc(sizeof(calendar_gl_todo_data_t));
        -   memset(gl_todo_data, 0x0, sizeof(calendar_gl_todo_data_t));
        -
        -   error_code = calendar_record_get_str(record, _calendar_todo.summary, &gl_todo_data->summary);
        -   if (error_code != CALENDAR_ERROR_NONE)
        -   {
        -      dlog_print(DLOG_ERROR, LOG_TAG, "record get summary failed: %x\n", error_code);
        -      _free_gl_todo_data(gl_todo_data);
        -
        -      return NULL;
        -   }
        -
        -   error_code = calendar_record_get_str(record, _calendar_todo.description, &gl_todo_data->description);
        -   if (error_code != CALENDAR_ERROR_NONE)
        -   {
        -      dlog_print(DLOG_ERROR, LOG_TAG, "record get description failed: %x\n", error_code);
        -      _free_gl_todo_data(gl_todo_data);
        -
        -      return NULL;
        -   }
        -
        -   error_code = calendar_record_get_int(record, _calendar_todo.id, &gl_todo_data->id);
        -   if (error_code != CALENDAR_ERROR_NONE)
        -   {
        -      dlog_print(DLOG_ERROR, LOG_TAG, "record get id failed: %x\n", error_code);
        -      _free_gl_todo_data(gl_todo_data);
        -
        -      return NULL;
        -   }
        -
        -   error_code = calendar_record_get_caltime(record, _calendar_todo.due_time, &gl_todo_data->due_time);
        -   if (error_code != CALENDAR_ERROR_NONE)
        -   {
        -      dlog_print(DLOG_ERROR, LOG_TAG, "calendar get due time failed: %x\n", error_code);
        -      _free_gl_todo_data(gl_todo_data);
        -
        -      return NULL;
        -   }
        -
        -   return gl_todo_data;
        -}
        -

        To get access to a specified data from the record, firstly you must get its child responsible for the requested type. Data returned by any function with the _p suffix must not be passed to _free_gl_todo_data().

    8. -
    9. Free the list: -
      -calendar_list_destroy(list, true);
    - -

    Updating a Todo

    - -

    To update a todo record:

    -
    1. Get the todo record handle to update with the ID. -
      calendar_record_h record;
      -const int todo_id = ... // Acquire todo ID
      -error_code = calendar_db_get_record(_calendar_todo._uri, todo_id, &record);
      -if (error_code != CALENDAR_ERROR_NONE)
      -   dlog_print(DLOG_ERROR, LOG_TAG, "db get record failed: %x\n", error_code);
    2. -
    3. Set the properties to update. -
      error_code = calendar_record_set_str(record, _calendar_todo.summary, "summary updated");
      -if (error_code != CALENDAR_ERROR_NONE)
      -   dlog_print(DLOG_ERROR, LOG_TAG, "record set summary failed: %x\n", error_code);
      -
      -error_code = calendar_record_set_str(record, _calendar_todo.description, "description updated");
      -if (error_code != CALENDAR_ERROR_NONE)
      -   dlog_print(DLOG_ERROR, LOG_TAG, "record set description failed: %x\n", error_code);
    4. -
    5. To update record, call the calendar_db_update_record() function. -
      error_code = calendar_db_update_record(record);
      -if (error_code != CALENDAR_ERROR_NONE)
      -   dlog_print(DLOG_ERROR, LOG_TAG, "db update record failed: %x\n", error_code);
    6. -
    7. When the todo handle is no longer needed, use the calendar_record_destroy() function to destroy the todo handle and free the allocated memory. -
      calendar_record_destroy(record, true);
    - -

    Deleting a Todo

    - -

    To delete a todo, use the calendar_db_delete_record() function with _calendar_todo._uri as the first parameter and the todo ID as the second one.

    -
    int todo_id = ... // Acquire todo ID
    -error_code = calendar_db_delete_record(_calendar_todo._uri, todo_id);
    -if (error_code != CALENDAR_ERROR_NONE)
    -   dlog_print(DLOG_ERROR, LOG_TAG, "db delete record failed: %x\n", error_code);
    - -

    Monitoring Todo Changes

    - -

    To register a callback function that listens for todo changes:

    -
    1. Register the callback function. - -
      error_code = calendar_db_add_changed_cb(_calendar_todo._uri, _todo_changed_callback, NULL);
      -if (error_code != CALENDAR_ERROR_NONE)
      -   dlog_print(DLOG_ERROR, LOG_TAG, "db add changed cb failed: %x\n", error_code);
    2. -
    3. Define the callback function. -

      The callback function is called when a todo changes. The code below shows how to get the new todo details.

      -
      static calendar_gl_todo_data_t *_gl_todo_data = ...
      -static void _todo_changed_callback(const char *view_uri, void *user_data)
      -{
      -   if (0 != strcmp(view_uri, _calendar_todo._uri))
      -      return;
      -
      -   if (NULL == _gl_todo_data)
      -      return;
      -
      -   int todo_id = _gl_todo_data->id;
      -   _free_gl_todo_data(_gl_todo_data);
      -   _gl_todo_data = NULL;
      -
      -   calendar_record_h record = NULL;
      -   calendar_error_e error_code;
      -   error_code = calendar_db_get_record(_calendar_todo._uri, todo_id, &record);
      -   if (error_code != CALENDAR_ERROR_NONE)
      -      return;
      -
      -   _gl_todo_data = _create_gl_todo_data(record);
      -   // Use _gl_todo_data
      -
      -   calendar_record_destroy(record, true);
      -}
    - -

    Making a vCalendar

    - -

    To make a vCalendar stream from an event record:

    -
    1. Get the event record by the event ID. -
      int event_id = ... // Acquire event ID
      -calendar_record_h record = NULL;
      -error_code = calendar_db_get_record(_calendar_event._uri, event_id, &record);
      -if (error_code != CALENDAR_ERROR_NONE)
      -   dlog_print(DLOG_ERROR, LOG_TAG, "db get record failed: %x\n", error_code);
    2. -
    3. Make the vCalendar stream by the event record. -
      char *vcalendar_stream = NULL;
      -calendar_list_h list = NULL;
      -
      -error_code = calendar_list_create(&list);
      -if (error_code != CALENDAR_ERROR_NONE)
      -   dlog_print(DLOG_ERROR, LOG_TAG, "list create failed: %x\n", error_code);
      -
      -error_code = calendar_list_add(list, record);
      -if (error_code != CALENDAR_ERROR_NONE)
      -   dlog_print(DLOG_ERROR, LOG_TAG, "list add failed: %x\n", error_code);
      -
      -error_code = calendar_vcalendar_make_from_records(list, &vcalendar_stream);
      -if (error_code != CALENDAR_ERROR_NONE)
      -   dlog_print(DLOG_ERROR, LOG_TAG, "vcalendar make from records failed: %x\n", error_code);
    4. -
    5. When the list handle is no longer needed, use the calendar_list_destroy() function to destroy the list handle and free the allocated memory. -
      free(vcalendar_stream);
      -calendar_list_destroy(list, true);
    - -

    Parsing a vCalendar

    - -

    To parse a vCalendar from a file and insert to the database:

    -
    char vcalendar_file_path[512] = {0};
    -char *resource_path = app_get_resource_path();
    -snprintf(vcalendar_file_path, sizeof(vcalendar_file_path), "%s/%s", resource_path, "vcalendar.ics");
    -free(resource_path);
    -
    -error_code = calendar_vcalendar_parse_to_calendar_foreach(vcalendar_file_path, // File path of vCalendar
    -                                                          _vcalendar_parse_cb, // Callback function to invoke
    -                                                          NULL); // User data to be passed to the callback function
    - -

    The vCalendar stream contains multiple event or todo objects. The callback function is called after parsing each event or todo. If you return false on the callback function, parsing stops.

    -
    static bool _vcalendar_parse_cb(calendar_record_h record, void *user_data)
    -{
    -   if (NULL == record)
    -      return false;
    -
    -   int id = -1;
    -   error_code = calendar_db_insert_record(record, &id);
    -   if (error_code != CALENDAR_ERROR_NONE)
    -   {
    -      dlog_print(DLOG_ERROR, LOG_TAG, "db insert record failed: %x\n", error_code);
    -
    -      return false;
    -   }
    -   dlog_print(DLOG_ERROR, LOG_TAG, "inserted id: %d\n", id);
    -   // Use record
    -
    -   return true;
    -}
    - - - - -
    - -Go to top - - - - - - + + + + + + + + + + + + + Calendar: Managing Calendar Events and Accessing the Calendar Database + + + + + +
    + +

    Calendar: Managing Calendar Events and Accessing the Calendar Database

    + + +

    This tutorial demonstrates how you can manage events and todo tasks, and convert calendar details to and from the vCalendar format.

    + + + + + + + + + + +
    Note
    This feature is supported in mobile applications only.
    + +

    Warm-up

    +

    Become familiar with the Calendar API basics by learning about:

    + + + +

    Initializing the Calendar

    + +

    To initialize the Calendar Service:

    +
    1. +

      To use the functions and data types of the Calendar API, include the <calendar.h> header file in your application:

      +
      +#include <calendar.h>
      +
    2. + +
    3. +

      Most of API functions return error codes, so you must define at the beginning of your code the int type, which is used to store the error codes. Each time when a function returns error codes, verify the result of the operation.

    4. + +
    5. To connect to the Calendar Service, call the calendar_connect() function. Without this function, you cannot get access to the Calendar database.

      +
      int error_code;
      +error_code = calendar_connect();
      +if (error_code != CALENDAR_ERROR_NONE)
      +   dlog_print(DLOG_ERROR, LOG_TAG, "calendar_connect: %x\n", error_code);
      + + +

      When the Calendar APIs are no longer needed, disconnect from the service using the calendar_disconnect() function:

      +
      error_code = calendar_disconnect();
      +if (error_code != CALENDAR_ERROR_NONE)
      +   dlog_print(DLOG_ERROR, LOG_TAG, "calendar disconnect failed: %x\n", error_code);
    + + +

    Creating an Event

    + +

    To define and create a new event handle (record), since the Calendar Service uses the event handler mechanism:

    +

    Use the calendar_record_create() function with the defined event handle as a parameter to create an event associated to the event handle and an _calendar_event._uri parameter for the event type.

    +

    Verify the status of the error code. If the event is created correctly, the function returns CALENDAR_ERROR_NONE. If an error is reported, you can check the error and take appropriate action or stop other operations on the database.

    +
    calendar_record_h event = NULL;
    +error_code = calendar_record_create(_calendar_event._uri, &event);
    +if (error_code != CALENDAR_ERROR_NONE)
    +   dlog_print(DLOG_ERROR, LOG_TAG, "calendar_record_create: %x\n", error_code);
    + +

    Setting Event Properties

    + +

    To set the event properties:

    + +
    1. Set the event subject. +

      To set the subject, call calendar_record_set_str(). This function takes the event handle (created before), as the first argument, _calendar_event.summary for subject type, and the subject, which is a string value, as the third argument. The calendar_record_set_str() function returns the status code. If the function returns an error, take appropriate action, such as freeing memory, removing handles, and disconnecting from the service, if needed.

      +
      error_code = calendar_record_set_str(event, _calendar_event.summary, "summary");
      +if (error_code != CALENDAR_ERROR_NONE)
      +   dlog_print(DLOG_ERROR, LOG_TAG, "set record summary failed : %x\n", error_code);
    2. +
    3. Set the event description. +

      The calendar_record_set_str() function sets the description of the event when the second argument is _calendar_event.description. This function takes the event handle as the first argument, and the description, which is a string value, as the third argument. The description argument is taken from the UI part of the application. The function returns the status code. If the function returns an error, take appropriate action, such as freeing memory, removing handles, and disconnecting from the service, if needed.

      +
      error_code = calendar_record_set_str(event, _calendar_event.description, "description");
      +if (error_code != CALENDAR_ERROR_NONE)
      +   dlog_print(DLOG_ERROR, LOG_TAG, "set description failed : %x\n", error_code);
    4. +
    5. Set the event time zone ID. +

      The start and end time must be inserted in the event. If the time zone ID is not inserted, the time zone for the start and end time is considered to be UTC. The properties are in the calendar_view.h file.

      +
      error_code = calendar_record_set_str(event, _calendar_event.start_tzid, "Asia/Seoul");
      +if (error_code != CALENDAR_ERROR_NONE)
      +   dlog_print(DLOG_ERROR, LOG_TAG, "set start_tzid failed : %x\n", error_code);
      +
      +error_code = calendar_record_set_str(event, _calendar_event.end_tzid, "Asia/Seoul");
      +if (error_code != CALENDAR_ERROR_NONE)
      +   dlog_print(DLOG_ERROR, LOG_TAG, "set end_tzid failed : %x\n", error_code);
    6. +
    7. Set the event start and end dates. +

      You can set the other properties similarly. To set the start date, call the calendar_record_set_caltime() functions and check the error codes.

      +
      calendar_time_s starttime = {0};
      +starttime.type = CALENDAR_TIME_UTIME;
      +starttime.time.utime = 1404036000; // 2014/06/29 10:00:00 UTC
      +error_code = calendar_record_set_caltime(event, _calendar_event.start_time, starttime);
      +if (error_code != CALENDAR_ERROR_NONE)
      +   dlog_print(DLOG_ERROR, LOG_TAG, "set start_time failed : %x\n", error_code);
      +
      +calendar_time_s endtime = {0};
      +endtime.type = CALENDAR_TIME_UTIME;
      +endtime.time.utime = 1404036000 + 3600; // 2014/06/29 11:00:00 UTC
      +error_code = calendar_record_set_caltime(event, _calendar_event.end_time, endtime);
      +if (error_code != CALENDAR_ERROR_NONE)
      +   dlog_print(DLOG_ERROR, LOG_TAG, "set end_time failed : %x\n", error_code);
      +

      The calendar_time_s has 2 types. For more information about the types, see the Calendar guide.

      +
    8. +
    9. Set the event frequency. +

      To create recurring events, set the frequency property.

      +
      error_code = calendar_record_set_int(event, _calendar_event.freq, CALENDAR_RECURRENCE_MONTHLY);
      +if (error_code != CALENDAR_ERROR_NONE)
      +   dlog_print(DLOG_ERROR, LOG_TAG, "set start_time failed : %x\n", error_code);
      +
      +error_code = calendar_record_set_int(event, _calendar_event.interval, 1);
      +if (error_code != CALENDAR_ERROR_NONE)
      +   dlog_print(DLOG_ERROR, LOG_TAG, "set start_time failed : %x\n", error_code);
      +
      +error_code = calendar_record_set_str(event, _calendar_event.bymonthday, "3,4,5");
      +if (error_code != CALENDAR_ERROR_NONE)
      +   dlog_print(DLOG_ERROR, LOG_TAG, "set start_time failed : %x\n", error_code);
    10. +
    11. Set the range of recurrence for the event. +
      error_code = calendar_record_set_int(event, _calendar_event.range_type, CALENDAR_RANGE_COUNT);
      +if (error_code != CALENDAR_ERROR_NONE)
      +   dlog_print(DLOG_ERROR, LOG_TAG, "set range_type failed : %x\n", error_code);
      +
      +error_code = calendar_record_set_int(event, _calendar_event.count, 8);
      +if (error_code != CALENDAR_ERROR_NONE)
      +   dlog_print(DLOG_ERROR, LOG_TAG, "set count failed : %x\n", error_code);
    12. + +
    13. Add an alarm. +

      To add an alarm, create an alarm handle and insert it as a child.

      +
      calendar_record_h alarm = NULL;
      +calendar_time_s ct;
      +error_code = CALENDAR_ERROR_NONE;
      +error_code += calendar_record_create(_calendar_alarm._uri, &alarm);
      +error_code += calendar_record_set_int(alarm, _calendar_alarm.tick_unit, CALENDAR_ALARM_TIME_UNIT_SPECIFIC);
      +ct.type = CALENDAR_TIME_UTIME;
      +ct.time.utime = 1404036000 - 60; // 60 sec before starttime (1404036000)
      +error_code += calendar_record_set_caltime(alarm, _calendar_alarm.alarm_time, ct);
      +error_code += calendar_record_add_child_record(event, _calendar_event.calendar_alarm, alarm);
      +
      +if (error_code != CALENDAR_ERROR_NONE)
      +   dlog_print(DLOG_ERROR, LOG_TAG, "calendar add alarm failed \n");
      +

      The following alarm tick units are available:

      +
      • CALENDAR_ALARM_TIME_UNIT_MINUTE
      • +
      • CALENDAR_ALARM_TIME_UNIT_HOUR
      • +
      • CALENDAR_ALARM_TIME_UNIT_DAY
      • +
      • CALENDAR_ALARM_TIME_UNIT_WEEK
      • +
      • CALENDAR_ALARM_TIME_UNIT_MONTH (not recommended)
      • +
      • CALENDAR_ALARM_TIME_UNIT_SPECIFIC (must use specific unixtime)
    14. +
    15. Add an attendee. +

      To add an attendee, create an attendee handle and insert it as a child.

      +
      calendar_record_h attendee = NULL;
      +error_code = CALENDAR_ERROR_NONE;
      +error_code += calendar_record_create(_calendar_attendee._uri, &attendee);
      +error_code += calendar_record_set_str(attendee, _calendar_attendee.name, "John");
      +error_code += calendar_record_add_child_record(event, _calendar_event.calendar_attendee, attendee);
      +
      +if (error_code != CALENDAR_ERROR_NONE)
      +   dlog_print(DLOG_ERROR, LOG_TAG, "calendar add alarm failed \n");
    + +

    Inserting an Event to the Database

    + +

    To insert an event record:

    + +
    1. Use the calendar_db_insert_record() function to insert the newly created event into the Calendar database. The first argument is the event handle, the second is the record ID - a unique ID is assigned to the event you are adding and returned as the second argument. If the event is inserted successfully, the function returns CALENDAR_ERROR_NONE. +
      int id = -1;
      +error_code = calendar_db_insert_record(event, &id);
      +if (error_code != CALENDAR_ERROR_NONE)
      +   dlog_print(DLOG_ERROR, LOG_TAG, "db insert record failed: %x\n", error_code);
      +
      +dlog_print(DLOG_ERROR, LOG_TAG, "id: %d\n", id);
    2. +
    3. After inserting, destroy the used structures: +
      calendar_record_destroy(event, true);
    + +

    Getting Events

    + +

    To retrieve a single event or all events one by one. You can also filter the events by one of the properties:

    + +
    1. Get a single event record using its ID. +
      calendar_record_h record;
      +const int event_id = ... // Acquire event ID
      +error_code = calendar_db_get_record(_calendar_event._uri, event_id, &record);
      +if (error_code != CALENDAR_ERROR_NONE)
      +   dlog_print(DLOG_ERROR, LOG_TAG, "db get record failed: %x\n", error_code);
    2. +
    3. Get the event record list. +

      To get all events without filtering, you need a record list:

      +
      calendar_list_h list = NULL;
      +error_code = calendar_db_get_all_records(_calendar_event._uri, 0, 0, &list);
      +if (error_code != CALENDAR_ERROR_NONE)
      +   dlog_print(DLOG_ERROR, LOG_TAG, "db get all records failed: %x\n", error_code);
    4. + +
    5. Filter the list. +
      1. +

        To get events with filtering, you need a record list and a query:

        +
        calendar_list_h list = NULL;
        +calendar_query_h query = NULL;
        +
        +error_code = calendar_query_create(_calendar_event._uri, &query);
        +if (error_code != CALENDAR_ERROR_NONE)
        +   dlog_print(DLOG_ERROR, LOG_TAG, "create query failed: %x\n", error_code);
      2. +
      3. Before retrieving the events, create a filter for the list. You can filter the list based on various parameters. +
        calendar_filter_h filter = NULL;
        +
        +error_code = calendar_filter_create (_calendar_event._uri, &filter);
        +if (error_code != CALENDAR_ERROR_NONE)
        +   dlog_print(DLOG_ERROR, LOG_TAG, "create filter failed: %x\n", error_code);
      4. +
      5. Add a condition, such as summary: +
        error_code = calendar_filter_add_str(filter, _calendar_event.summary, CALENDAR_MATCH_CONTAINS, "summary to find");
        +if (error_code != CALENDAR_ERROR_NONE)
        +   dlog_print(DLOG_ERROR, LOG_TAG, "filter add string failed: %x\n", error_code);
        +
      6. +
      7. To add more conditions, define an operator between the conditions: +
        error_code = calendar_filter_add_operator(filter, CALENDAR_FILTER_OPERATOR_AND);
        +if (error_code != CALENDAR_ERROR_NONE)
        +   dlog_print(DLOG_ERROR, LOG_TAG, "filter add operator failed: %x\n", error_code);
        +
        +error_code = calendar_filter_add_str(filter, _calendar_event.description, CALENDAR_MATCH_CONTAINS, "description to find");
        +if (error_code != CALENDAR_ERROR_NONE)
        +   dlog_print(DLOG_ERROR, LOG_TAG, "filter add string failed: %x\n", error_code);
        +

        In the above example, only events which contain a summary "summary to find" and description "description to find" are retrieved.

        +

        You can create a filter with integer and time conditions. For instance, to filter all day events which start after 1st January 2014, add the following filter:

        +
        calendar_time_s time_to_compare = {0};
        +time_to_compare.type = CALENDAR_TIME_LOCALTIME;
        +time_to_compare.time.date.mday = 1;
        +time_to_compare.time.date.month = 1;
        +time_to_compare.time.date.year = 2014;
        +error_code = calendar_filter_add_caltime(filter, _calendar_event.start_time, CALENDAR_MATCH_GREATER_THAN, time_to_compare);
        +if (error_code != CALENDAR_ERROR_NONE)
        +   dlog_print(DLOG_ERROR, LOG_TAG, "filter add caltime failed: %x\n", error_code);
        +

        The type parameter determines whether the event is a daily (CALENDAR_TIME_LOCALTIME) non-all-day event (CALENDAR_TIME_UTIME). To get the specified time period, use 2 conditions using CALENDAR_MATCH_GREATER_THAN and CALENDAR_MATCH_LESS_THAN with the operator CALENDAR_FILTER_OPERATOR_OR. You can also use CALENDAR_MATCH_EQUAL to set an equality condition.

      8. +
      9. Connect the query with the list: +
        error_code = calendar_query_set_filter(query, filter);
        +if (error_code != CALENDAR_ERROR_NONE)
        +   dlog_print(DLOG_ERROR, LOG_TAG, "query set filter failed: %x\n", error_code);
        +
        +error_code = calendar_db_get_records_with_query(query, 0, 0, &list);
        +if (error_code != CALENDAR_ERROR_NONE)
        +   dlog_print(DLOG_ERROR, LOG_TAG, "db get records with query failed: %x\n", error_code);
        + +

        The third parameter refers to a limit of the results. If 0 is passed, there are no limits. Remember that after all operations, the list must be released.

      10. +
      11. Free the filter and query: +
        calendar_filter_destroy(filter);
        +calendar_query_destroy(query);
    6. + +
    7. Iterate the list and read the records. +
      1. Get records from the list using calendar_list_get_current_record_p(), and calendar_list_next() or calendar_list_prev(). Inside the loop, get details of each record. +

        Note on the returned values' ownership: some functions have the _p postfix. It means that the returned value must not be freed by the application, as it is a pointer to the data in an existing record.

        +
        calendar_record_h record;
        +while (calendar_list_get_current_record_p(list, &record) == CALENDAR_ERROR_NONE)
        +{
        +   char* summary;
        +   calendar_record_get_str_p(record, _calendar_event.summary, &summary);
        +   dlog_print(DLOG_ERROR, LOG_TAG, "summary: %s\n", summary);
        +
        +   error_code = calendar_list_next(list);
        +   if (error_code != CALENDAR_ERROR_NONE)
        +      break;
        +}
      2. +
      3. If you want to get more details of each record, use the calendar_gl_event_data_t structure like below: +
        calendar_gl_event_data_t *gl_event_data = NULL;
        +calendar_record_h record = NULL;
        +while (calendar_list_get_current_record_p(list, &record) == CALENDAR_ERROR_NONE)
        +{
        +   gl_event_data = _create_gl_event_data(record);
        +   // You can get, for example, summary:
        +   // gl_event_data->summary
        +
        +   _free_gl_event_data(gl_event_data);
        +
        +   error_code = calendar_list_next(list);
        +   if (error_code != CALENDAR_ERROR_NONE)
        +      break;
        +}
      4. + +
      5. The memory for the record data is allocated, and the data is copied from the record by the functions listed further on in this document. +
        typedef struct _calendar_gl_event_data
        +{
        +   int id;
        +   char *summary;
        +   char *description;
        +   calendar_time_s start_time;
        +} calendar_gl_event_data_t;
        +
        +static void _free_gl_event_data(calendar_gl_event_data_t *gl_event_data)
        +{
        +   if (NULL == gl_event_data)
        +      return;
        +   free(gl_event_data->summary);
        +   free(gl_event_data->description);
        +   free(gl_event_data);
        +}
        +
        +static calendar_gl_event_data_t *_create_gl_event_data(calendar_record_h record)
        +{
        +   calendar_gl_event_data_t *gl_event_data;
        +   int error_code;
        +
        +   gl_event_data = malloc(sizeof(calendar_gl_event_data_t));
        +   memset(gl_event_data, 0x0, sizeof(calendar_gl_event_data_t));
        +
        +   error_code = calendar_record_get_str(record, _calendar_event.summary, &gl_event_data->summary);
        +   if (error_code != CALENDAR_ERROR_NONE)
        +   {
        +      dlog_print(DLOG_ERROR, LOG_TAG, "record get summary failed: %i\n", error_code);
        +      _free_gl_event_data(gl_event_data);
        +
        +      return NULL;
        +   }
        +
        +   error_code = calendar_record_get_str(record, _calendar_event.description, &gl_event_data->description);
        +   if (error_code != CALENDAR_ERROR_NONE)
        +   {
        +      dlog_print(DLOG_ERROR, LOG_TAG, "record get description failed: %i\n", error_code);
        +      _free_gl_event_data(gl_event_data);
        +
        +      return NULL;
        +   }
        +
        +   error_code = calendar_record_get_int(record, _calendar_event.id, &gl_event_data->id);
        +   if (error_code != CALENDAR_ERROR_NONE)
        +   {
        +      dlog_print(DLOG_ERROR, LOG_TAG, "record get id failed: %i\n", error_code);
        +      _free_gl_event_data(gl_event_data);
        +
        +      return NULL;
        +   }
        +
        +   error_code = calendar_record_get_caltime(record, _calendar_event.start_time, &gl_event_data->start_time);
        +   if (error_code != CALENDAR_ERROR_NONE)
        +   {
        +      dlog_print(DLOG_ERROR, LOG_TAG, "calendar get start time failed: %i\n", error_code);
        +      _free_gl_event_data(gl_event_data);
        +
        +      return NULL;
        +   }
        +
        +   return gl_event_data;
        +}
        +

        To get access to a specified data from the record, firstly it is necessary to get its child responsible for the requested type.

    8. +
    9. Free the list: +
      calendar_list_destroy(list, true);
    + + +

    Updating an Event

    + +

    To update an event record:

    + +
    1. Get the event record handle to update with the ID. +
      calendar_record_h record;
      +const int event_id = ... // Acquire event ID
      +error_code = calendar_db_get_record(_calendar_event._uri, event_id, &record);
      +if (error_code != CALENDAR_ERROR_NONE)
      +   dlog_print(DLOG_ERROR, LOG_TAG, "db get record failed: %x\n", error_code);
    2. +
    3. Set the properties to update. +
      error_code = calendar_record_set_str(record, _calendar_event.summary, "summary updated");
      +if (error_code != CALENDAR_ERROR_NONE)
      +   dlog_print(DLOG_ERROR, LOG_TAG, "record set summary failed: %x\n", error_code);
      +
      +error_code = calendar_record_set_str(record, _calendar_event.description, "description updated");
      +if (error_code != CALENDAR_ERROR_NONE)
      +   dlog_print(DLOG_ERROR, LOG_TAG, "record set description failed: %x\n", error_code);
    4. +
    5. To update the record, call the calendar_db_update_record() function. +
      error_code = calendar_db_update_record(record);
      +if (error_code != CALENDAR_ERROR_NONE)
      +   dlog_print(DLOG_ERROR, LOG_TAG, "db update record failed: %x\n", error_code);
    6. +
    7. When the event handle is no longer needed, use the calendar_record_destroy() function to destroy the event handle and free the allocated memory. +
      calendar_record_destroy(record, true);
    + +

    Deleting an Event

    + +

    To delete an event, call the calendar_db_delete_record() function with _calendar_event._uri as the first parameter and event ID as the second one:

    +
    int event_id = ... // Acquire event ID
    +error_code = calendar_db_delete_record(_calendar_event._uri, event_id);
    +if (error_code != CALENDAR_ERROR_NONE)
    +   dlog_print(DLOG_ERROR, LOG_TAG, "db delete record failed: %x\n", error_code);
    + +

    Setting Exceptions when Inserting Events

    + +

    To set an exception date to an event record when creating the event:

    + +
    1. Create a recurring event. +

      The following example creates an event record with the following properties:

      +
      • Frequency: CALENDAR_RECURRENCE_MONTHLY
      • +
      • Interval: 1
      • +
      • Bymonthday: "3, 4, 5"
      • +
      • Range type: count
      • +
      • Count: 8
      + +
      int error_code = CALENDAR_ERROR_NONE;
      +
      +calendar_record_h event = NULL;
      +error_code += calendar_record_create(_calendar_event._uri, &event);
      +error_code += calendar_record_set_str(event, _calendar_event.summary, "test");
      +error_code += calendar_record_set_str(event, _calendar_event.start_tzid, "Asia/Seoul");
      +error_code += calendar_record_set_str(event, _calendar_event.end_tzid, "Asia/Seoul");
      +
      +calendar_time_s st = {0};
      +st.type = CALENDAR_TIME_UTIME;
      +st.time.utime = 1349226000;
      +error_code += calendar_record_set_caltime(event, _calendar_event.start_time, st);
      +
      +calendar_time_s et = {0};
      +et.type = CALENDAR_TIME_UTIME;
      +et.time.utime = 1354582800;
      +error_code += calendar_record_set_caltime(event, _calendar_event.end_time, et);
      +
      +error_code += calendar_record_set_int(event, _calendar_event.freq, CALENDAR_RECURRENCE_MONTHLY);
      +error_code += calendar_record_set_int(event, _calendar_event.interval, 1);
      +error_code += calendar_record_set_str(event, _calendar_event.bymonthday, "3,4,5");
      +
      +error_code += calendar_record_set_int(event, _calendar_event.range_type, CALENDAR_RANGE_COUNT);
      +error_code += calendar_record_set_int(event, _calendar_event.count, 8);
      +
      +if (error_code != CALENDAR_ERROR_NONE)
      +   dlog_print(DLOG_ERROR, LOG_TAG, "calendar record create failed: \n");
      + +

      The created event has 8 instances.

      + + + + + + + + + + + + + + +
      + Table: Event instances +
      unixtimeDate time
      1349226000 +
      1349312400 +
      1349398800 +
      1351904400 +
      1351990800 +
      1352077200 +
      1354496400 +
      1354582800
      2012-10-03 01:00:00 +
      2012-10-04 01:00:00 +
      2012-10-05 01:00:00 +
      2012-11-03 01:00:00 +
      2012-11-04 01:00:00 +
      2012-11-05 01:00:00 +
      2012-12-03 01:00:00 +
      2012-12-04 01:00:00
    2. +
    3. Set the exdate property to create the exception. +

      In vcalendar 2.0 (RFC 2445), exdate is used to identify a deleted instance. If multiple instances are deleted, datetimes are added with a comma (such as 20121104T010000Z, 20121105T010000Z, 20121203T010000Z).

      +
      error_code = calendar_record_set_str(event, _calendar_event.exdate, "20121104T010000Z");
      +if (error_code != CALENDAR_ERROR_NONE)
      +   dlog_print(DLOG_ERROR, LOG_TAG, "calendar record set string failed: %x\n", error_code);
    4. +
    5. Insert the record. +

      Use the calendar_db_insert_record() function to insert the event into the Calendar database.

      +
      int event_id;
      +error_code = calendar_db_insert_record(event, &event_id);
      +if (error_code != CALENDAR_ERROR_NONE)
      +   dlog_print(DLOG_ERROR, LOG_TAG, "calendar db insert record failed: %x\n", error_code);
      +
      +calendar_record_destroy(event, true);
    + +

    Adding an Exception Date for an Existing Event

    + +

    To add an exception date to an existing event:

    + +
    1. Make sure you have an existing event.
    2. +
    3. Clone the existing event record and set new properties for the exception. +

      Cloning means that the new record has the original event's properties. In vcalendar 2.0 (RFC 2445), the recurrence ID is used to identify the modified instance (exception).

      +
      calendar_record_h clone = NULL;
      +error_code = CALENDAR_ERROR_NONE;
      +
      +error_code += calendar_record_clone(event, &clone);
      +error_code += calendar_record_set_int(clone, _calendar_event.original_event_id, event_id);
      +error_code += calendar_record_set_str(clone, _calendar_event.recurrence_id, "20121005T010000Z");
      +
      +if (error_code != CALENDAR_ERROR_NONE)
      +   dlog_print(DLOG_ERROR, LOG_TAG, "calendar record clone failed: %x\n", error_code);
    4. +
    5. Insert the new record. +

      Use the calendar_db_insert_record() function to insert the new event record into the Calendar database.

      +
      int exdate_event_id = 0;
      +error_code = calendar_db_insert_record(clone, &exdate_event_id);
      +if (error_code != CALENDAR_ERROR_NONE)
      +   dlog_print(DLOG_ERROR, LOG_TAG, "calendar db insert record failed: %x\n", error_code);
      +
      +calendar_record_destroy(clone, true);
      +calendar_record_destroy(event, true);
    + + +

    Monitoring Event Changes

    + +

    To register a callback function that listens for event changes:

    +
    1. Register the callback function. +
      error_code = calendar_db_add_changed_cb(_calendar_event._uri, _event_changed_callback, NULL);
      +if (error_code != CALENDAR_ERROR_NONE)
      +   dlog_print(DLOG_ERROR, LOG_TAG, "db add changed cb failed: %x\n", error_code);
    2. +
    3. Define the callback function. +

      The callback function is called when an event changes. The code below shows how to get the new event details.

      +
      static calendar_gl_event_data_t *_gl_event_data = ...
      +static void _event_changed_callback(const char *view_uri, void *user_data)
      +{
      +   if (0 != strcmp(view_uri, _calendar_event._uri))
      +      return;
      +
      +   if (NULL == _gl_event_data)
      +      return;
      +
      +   int event_id = _gl_event_data->id;
      +   _free_gl_event_data(_gl_event_data);
      +   _gl_event_data = NULL;
      +
      +   calendar_record_h record = NULL;
      +   int error_code;
      +   error_code = calendar_db_get_record(_calendar_event._uri, event_id, &record);
      +   if (error_code != CALENDAR_ERROR_NONE)
      +      return;
      +
      +    _gl_event_data = _create_gl_event_data(record);
      +   // Use _gl_event_data
      +
      +   calendar_record_destroy(record, true);
      +}
    + +

    Creating a Todo

    + +

    To define and create a new todo handle record, since the Calendar Service uses a todo handler mechanism:

    +

    Use the calendar_record_create() function with the defined todo handle as a parameter to create a todo associated with the todo handle and a _calendar_todo._uri parameter for the todo type.

    +

    Verify the status of the error code. If the todo handle is created correctly, the function returns CALENDAR_ERROR_NONE. If an error is reported, check the error and take appropriate action, or stop other operations on the database.

    +
    calendar_record_h todo = NULL;
    +error_code = calendar_record_create(_calendar_todo._uri, &todo);
    +if (error_code != CALENDAR_ERROR_NONE)
    +   dlog_print(DLOG_ERROR, LOG_TAG, "calendar_record_create: %x\n", error_code);
    + +

    Setting Todo Properties

    + +

    To set the todo properties:

    +
    1. Set the todo subject. +

      To set the subject, call calendar_record_set_str(). This function takes the todo handle (created before) as the first argument, _calendar_todo.summary for the subject type, and the subject, which is string value, as the third argument. The calendar_record_set_str() function returns the status code. If the function returns an error, take appropriate action, such as freeing memory, removing handles, and disconnecting from the service, if needed.

      +
      error_code = calendar_record_set_str(todo, _calendar_todo.summary, "summary");
      +if (error_code != CALENDAR_ERROR_NONE)
      +   dlog_print(DLOG_ERROR, LOG_TAG, "set summary failed : %x\n", error_code);
    2. +
    3. Set the todo description. +

      The calendar_record_set_uri() function sets the description of the todo when the second argument is _calendar_todo.description. This function takes the todo handle as the first argument, and the description, which is string value, as the third argument. The description argument is taken from the UI part of the application. The function returns the status code. If the function returns an error, take appropriate action, such as freeing memory, removing handles, and disconnecting from the service, if needed.

      +
      error_code = calendar_record_set_str(todo, _calendar_todo.description, "description");
      +if (error_code != CALENDAR_ERROR_NONE)
      +   dlog_print(DLOG_ERROR, LOG_TAG, "set description failed : %x\n", error_code);
    4. +
    5. Set the todo due date. +

      To set the due date, call the calendar_record_set_caltime function and check the error codes.

      +
      calendar_time_s duetime = {0};
      +duetime.type = CALENDAR_TIME_UTIME;
      +duetime.time.utime = 1404036000; // 2014/06/29 11:00:00 UTC
      +
      +error_code = calendar_record_set_caltime(todo, _calendar_todo.due_time, duetime);
      +if (error_code != CALENDAR_ERROR_NONE)
      +   dlog_print(DLOG_ERROR, LOG_TAG, "set due_time failed : %x\n", error_code);
    6. +
    7. Set the todo status. +

      You can set the other properties similarly. To set the todo status, call the calendar_record_set_int() function and check the error codes.

      +
      error_code = calendar_record_set_int(todo, _calendar_todo.todo_status, CALENDAR_TODO_STATUS_COMPLETED);
      +if (error_code != CALENDAR_ERROR_NONE)
      +   dlog_print(DLOG_ERROR, LOG_TAG, "set todo_status failed : %x\n", error_code);
    + +

    Inserting a Todo to the Database

    + +

    To insert a todo record:

    +
    1. Use the calendar_db_insert_record() function to insert a newly created todo into the Calendar database. The first argument is the todo handle, the second is the record ID. A unique ID is assigned to the record you are adding, and is returned as the third argument of the called function. If the todo is inserted successfully, the function returns CALENDAR_ERROR_NONE. +
      int id;
      +error_code = calendar_db_insert_record(todo, &id);
      +if (error_code != CALENDAR_ERROR_NONE)
      +   dlog_print(DLOG_ERROR, LOG_TAG, "db insert record failed: %x\n", error_code);
    2. +
    3. After inserting, destroy the used structures: +
      calendar_record_destroy(todo, true);
    + +

    Getting Todos

    + +

    To retrieve a single todo or all todos one by one. You can also filter the todos by one of the properties:

    + +
    1. Get a single todo record using its ID. +
      calendar_record_h record;
      +const int todo_id = ... // Acquire todo ID
      +error_code = calendar_db_get_record(_calendar_todo._uri, todo_id, &record);
      +if (error_code != CALENDAR_ERROR_NONE)
      +   dlog_print(DLOG_ERROR, LOG_TAG, "db get record failed: %x\n", error_code);
    2. +
    3. Get the todo record list. +

      To get all todos without filtering, you need a record list:

      +
      calendar_list_h list = NULL;
      +error_code = calendar_db_get_all_records(_calendar_todo._uri, 0, 0, &list);
      +if (error_code != CALENDAR_ERROR_NONE)
      +   dlog_print(DLOG_ERROR, LOG_TAG, "db get all records failed: %x\n", error_code);
    4. +
    5. Filter the list. +
      1. To get todos with filtering, you need a record list and a query: +
        calendar_list_h list = NULL;
        +calendar_query_h query = NULL;
        +
        +error_code = calendar_query_create(_calendar_todo._uri, &query);
        +if (error_code != CALENDAR_ERROR_NONE)
        +   dlog_print(DLOG_ERROR, LOG_TAG, "create query failed: %x\n", error_code);
      2. +
      3. Before retrieving the todos, create a filter for the list. You can filter the list based on various parameters. +
        calendar_filter_h filter = NULL;
        +
        +error_code = calendar_filter_create (_calendar_todo._uri, &filter);
        +if (error_code != CALENDAR_ERROR_NONE)
        +   dlog_print(DLOG_ERROR, LOG_TAG, "create filter failed: %x\n", error_code);
      4. +
      5. Add a condition, such as summary: +
        error_code = calendar_filter_add_str(filter, _calendar_todo.summary, CALENDAR_MATCH_CONTAINS, "summary to find");
        +if (error_code != CALENDAR_ERROR_NONE)
        +   dlog_print(DLOG_ERROR, LOG_TAG, "filter add string failed: %x\n", error_code);
      6. +
      7. To add more conditions, define an operator between the conditions: +
        error_code = calendar_filter_add_operator(filter, CALENDAR_FILTER_OPERATOR_AND);
        +if (error_code != CALENDAR_ERROR_NONE)
        +   dlog_print(DLOG_ERROR, LOG_TAG, "filter add operator failed: %x\n", error_code);
        +
        +error_code = calendar_filter_add_str(filter, _calendar_todo.description, CALENDAR_MATCH_CONTAINS, "description to find");
        +if (error_code != CALENDAR_ERROR_NONE)
        +   dlog_print(DLOG_ERROR, LOG_TAG, "filter add string failed: %x\n", error_code);
        +

        In the above example, only todos which contain a summary "summary to find" and description "description to find" are retrieved.

        +

        You can create a filter with integer and time conditions. For instance, to filter all todos which are completed, add the following filter:

        +
        error_code = calendar_filter_add_int(filter, _calendar_todo.todo_status, CALENDAR_MATCH_EQUAL, CALENDAR_TODO_STATUS_COMPLETED);
        +if (error_code != CALENDAR_ERROR_NONE)
        +   dlog_print(DLOG_ERROR, LOG_TAG, "filter add integer failed: %x\n", error_code);
      8. +
      9. Connect the query with the list: +
        error_code = calendar_query_set_filter(query, filter);
        +if (error_code != CALENDAR_ERROR_NONE)
        +   dlog_print(DLOG_ERROR, LOG_TAG, "query set filter failed: %x\n", error_code);
        +
        +error_code = calendar_db_get_records_with_query(query, 0, 0, &list);
        +if (error_code != CALENDAR_ERROR_NONE)
        +   dlog_print(DLOG_ERROR, LOG_TAG, "db get records with query failed: %x\n", error_code);
        +

        The third parameter refers to a limit of the results. If 0 is passed, there are no limits. Remember that after all operations, the list must be released.

      10. + +
      11. Free the filter and query: +
        calendar_filter_destroy(filter);
        +calendar_query_destroy(query);
      12. +
    6. +
    7. Iterate the list and read the records. +
      1. Get records from the list using calendar_list_get_current_record_p(), and calendar_list_next() or calendar_list_prev(). Inside the loop, get details of each record. +

        Note on the returned values' ownership: some functions have the _p postfix. It means that the returned value must not be freed by the application, as it is a pointer to the data in an existing record.

        +
        calendar_record_h record;
        +while (calendar_list_get_current_record_p(list, &record) == CALENDAR_ERROR_NONE)
        +{
        +   char* summary;
        +   calendar_record_get_str_p(record, _calendar_todo.summary, &summary);
        +   dlog_print(DLOG_ERROR, LOG_TAG, "summary: %s\n", summary);
        +
        +   error_code = calendar_list_next(list);
        +   if (error_code != CALENDAR_ERROR_NONE)
        +      break;
        +}
      2. +
      3. If you want to get more details of each record, use the calendar_gl_todo_data_t structure like below: +
        calendar_gl_todo_data_t *gl_todo_data = NULL;
        +calendar_record_h record = NULL;
        +while (calendar_list_get_current_record_p(list, &record) == CALENDAR_ERROR_NONE)
        +{
        +   gl_todo_data = _create_gl_todo_data(record);
        +   // You can get, for example, summary:
        +   // gl_todo_data->summary
        +
        +   _free_gl_todo_data(gl_todo_data);
        +
        +   error_code = calendar_list_next(list);
        +   if (error_code != CALENDAR_ERROR_NONE)
        +      break;
        +}
      4. + +
      5. The memory for the record data is allocated, and the data is copied from the record by the functions listed further on in this document. +
        typedef struct _calendar_gl_todo_data
        +{
        +   int id;
        +   char *summary;
        +   char *description;
        +   calendar_time_s due_time;
        +} calendar_gl_todo_data_t;
        +
        +static void _free_gl_todo_data(calendar_gl_todo_data_t *gl_todo_data)
        +{
        +   if (NULL == gl_todo_data)
        +      return;
        +   free(gl_todo_data->summary);
        +   free(gl_todo_data->description);
        +   free(gl_todo_data);
        +}
        +
        +static calendar_gl_todo_data_t *_create_gl_todo_data(calendar_record_h record)
        +{
        +   calendar_gl_todo_data_t *gl_todo_data;
        +   int error_code;
        +
        +   gl_todo_data = malloc(sizeof(calendar_gl_todo_data_t));
        +   memset(gl_todo_data, 0x0, sizeof(calendar_gl_todo_data_t));
        +
        +   error_code = calendar_record_get_str(record, _calendar_todo.summary, &gl_todo_data->summary);
        +   if (error_code != CALENDAR_ERROR_NONE)
        +   {
        +      dlog_print(DLOG_ERROR, LOG_TAG, "record get summary failed: %x\n", error_code);
        +      _free_gl_todo_data(gl_todo_data);
        +
        +      return NULL;
        +   }
        +
        +   error_code = calendar_record_get_str(record, _calendar_todo.description, &gl_todo_data->description);
        +   if (error_code != CALENDAR_ERROR_NONE)
        +   {
        +      dlog_print(DLOG_ERROR, LOG_TAG, "record get description failed: %x\n", error_code);
        +      _free_gl_todo_data(gl_todo_data);
        +
        +      return NULL;
        +   }
        +
        +   error_code = calendar_record_get_int(record, _calendar_todo.id, &gl_todo_data->id);
        +   if (error_code != CALENDAR_ERROR_NONE)
        +   {
        +      dlog_print(DLOG_ERROR, LOG_TAG, "record get id failed: %x\n", error_code);
        +      _free_gl_todo_data(gl_todo_data);
        +
        +      return NULL;
        +   }
        +
        +   error_code = calendar_record_get_caltime(record, _calendar_todo.due_time, &gl_todo_data->due_time);
        +   if (error_code != CALENDAR_ERROR_NONE)
        +   {
        +      dlog_print(DLOG_ERROR, LOG_TAG, "calendar get due time failed: %x\n", error_code);
        +      _free_gl_todo_data(gl_todo_data);
        +
        +      return NULL;
        +   }
        +
        +   return gl_todo_data;
        +}
        +

        To get access to a specified data from the record, firstly you must get its child responsible for the requested type. Data returned by any function with the _p suffix must not be passed to _free_gl_todo_data().

    8. +
    9. Free the list: +
      +calendar_list_destroy(list, true);
    + +

    Updating a Todo

    + +

    To update a todo record:

    +
    1. Get the todo record handle to update with the ID. +
      calendar_record_h record;
      +const int todo_id = ... // Acquire todo ID
      +error_code = calendar_db_get_record(_calendar_todo._uri, todo_id, &record);
      +if (error_code != CALENDAR_ERROR_NONE)
      +   dlog_print(DLOG_ERROR, LOG_TAG, "db get record failed: %x\n", error_code);
    2. +
    3. Set the properties to update. +
      error_code = calendar_record_set_str(record, _calendar_todo.summary, "summary updated");
      +if (error_code != CALENDAR_ERROR_NONE)
      +   dlog_print(DLOG_ERROR, LOG_TAG, "record set summary failed: %x\n", error_code);
      +
      +error_code = calendar_record_set_str(record, _calendar_todo.description, "description updated");
      +if (error_code != CALENDAR_ERROR_NONE)
      +   dlog_print(DLOG_ERROR, LOG_TAG, "record set description failed: %x\n", error_code);
    4. +
    5. To update record, call the calendar_db_update_record() function. +
      error_code = calendar_db_update_record(record);
      +if (error_code != CALENDAR_ERROR_NONE)
      +   dlog_print(DLOG_ERROR, LOG_TAG, "db update record failed: %x\n", error_code);
    6. +
    7. When the todo handle is no longer needed, use the calendar_record_destroy() function to destroy the todo handle and free the allocated memory. +
      calendar_record_destroy(record, true);
    + +

    Deleting a Todo

    + +

    To delete a todo, use the calendar_db_delete_record() function with _calendar_todo._uri as the first parameter and the todo ID as the second one.

    +
    int todo_id = ... // Acquire todo ID
    +error_code = calendar_db_delete_record(_calendar_todo._uri, todo_id);
    +if (error_code != CALENDAR_ERROR_NONE)
    +   dlog_print(DLOG_ERROR, LOG_TAG, "db delete record failed: %x\n", error_code);
    + +

    Monitoring Todo Changes

    + +

    To register a callback function that listens for todo changes:

    +
    1. Register the callback function. + +
      error_code = calendar_db_add_changed_cb(_calendar_todo._uri, _todo_changed_callback, NULL);
      +if (error_code != CALENDAR_ERROR_NONE)
      +   dlog_print(DLOG_ERROR, LOG_TAG, "db add changed cb failed: %x\n", error_code);
    2. +
    3. Define the callback function. +

      The callback function is called when a todo changes. The code below shows how to get the new todo details.

      +
      static calendar_gl_todo_data_t *_gl_todo_data = ...
      +static void _todo_changed_callback(const char *view_uri, void *user_data)
      +{
      +   if (0 != strcmp(view_uri, _calendar_todo._uri))
      +      return;
      +
      +   if (NULL == _gl_todo_data)
      +      return;
      +
      +   int todo_id = _gl_todo_data->id;
      +   _free_gl_todo_data(_gl_todo_data);
      +   _gl_todo_data = NULL;
      +
      +   calendar_record_h record = NULL;
      +   calendar_error_e error_code;
      +   error_code = calendar_db_get_record(_calendar_todo._uri, todo_id, &record);
      +   if (error_code != CALENDAR_ERROR_NONE)
      +      return;
      +
      +   _gl_todo_data = _create_gl_todo_data(record);
      +   // Use _gl_todo_data
      +
      +   calendar_record_destroy(record, true);
      +}
    + +

    Making a vCalendar

    + +

    To make a vCalendar stream from an event record:

    +
    1. Get the event record by the event ID. +
      int event_id = ... // Acquire event ID
      +calendar_record_h record = NULL;
      +error_code = calendar_db_get_record(_calendar_event._uri, event_id, &record);
      +if (error_code != CALENDAR_ERROR_NONE)
      +   dlog_print(DLOG_ERROR, LOG_TAG, "db get record failed: %x\n", error_code);
    2. +
    3. Make the vCalendar stream by the event record. +
      char *vcalendar_stream = NULL;
      +calendar_list_h list = NULL;
      +
      +error_code = calendar_list_create(&list);
      +if (error_code != CALENDAR_ERROR_NONE)
      +   dlog_print(DLOG_ERROR, LOG_TAG, "list create failed: %x\n", error_code);
      +
      +error_code = calendar_list_add(list, record);
      +if (error_code != CALENDAR_ERROR_NONE)
      +   dlog_print(DLOG_ERROR, LOG_TAG, "list add failed: %x\n", error_code);
      +
      +error_code = calendar_vcalendar_make_from_records(list, &vcalendar_stream);
      +if (error_code != CALENDAR_ERROR_NONE)
      +   dlog_print(DLOG_ERROR, LOG_TAG, "vcalendar make from records failed: %x\n", error_code);
    4. +
    5. When the list handle is no longer needed, use the calendar_list_destroy() function to destroy the list handle and free the allocated memory. +
      free(vcalendar_stream);
      +calendar_list_destroy(list, true);
    + +

    Parsing a vCalendar

    + +

    To parse a vCalendar from a file and insert to the database:

    +
    char vcalendar_file_path[512] = {0};
    +char *resource_path = app_get_resource_path();
    +snprintf(vcalendar_file_path, sizeof(vcalendar_file_path), "%s/%s", resource_path, "vcalendar.ics");
    +free(resource_path);
    +
    +error_code = calendar_vcalendar_parse_to_calendar_foreach(vcalendar_file_path, // File path of vCalendar
    +                                                          _vcalendar_parse_cb, // Callback function to invoke
    +                                                          NULL); // User data to be passed to the callback function
    + +

    The vCalendar stream contains multiple event or todo objects. The callback function is called after parsing each event or todo. If you return false on the callback function, parsing stops.

    +
    static bool _vcalendar_parse_cb(calendar_record_h record, void *user_data)
    +{
    +   if (NULL == record)
    +      return false;
    +
    +   int id = -1;
    +   error_code = calendar_db_insert_record(record, &id);
    +   if (error_code != CALENDAR_ERROR_NONE)
    +   {
    +      dlog_print(DLOG_ERROR, LOG_TAG, "db insert record failed: %x\n", error_code);
    +
    +      return false;
    +   }
    +   dlog_print(DLOG_ERROR, LOG_TAG, "inserted id: %d\n", id);
    +   // Use record
    +
    +   return true;
    +}
    + + + + +
    + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.tutorials/html/native/social/contact_tutorial_n.htm b/org.tizen.tutorials/html/native/social/contact_tutorial_n.htm index baa260c..4e30fdd 100644 --- a/org.tizen.tutorials/html/native/social/contact_tutorial_n.htm +++ b/org.tizen.tutorials/html/native/social/contact_tutorial_n.htm @@ -1,3232 +1,3232 @@ - - - - - - - - - - - - - Contacts: Managing Contacts and Groups, and Accessing the Contact Database - - - - - -
    - -

    Contacts: Managing Contacts and Groups, and Accessing the Contact Database

    - - -

    This tutorial demonstrates how you can manage contacts and groups, and import them to or export them from the vCard format.

    - - - - - - - - - - -
    Note
    This feature is supported in mobile applications only.
    - -

    Warm-up

    -

    Become familiar with the Contacts API basics by learning about:

    - -

    Follow-up

    -

    Once we have learned the basics of the Contacts API, we can now move on to more advanced tasks, including:

    - - - -

    Initializing Contacts

    - -

    To start with the Contact Service:

    -
    1. -

      To use the functions and data types of the Contacts API, include the <contacts.h> header file in your application:

      -
      -#include <contacts.h>
      -
    2. -
    3. Most of the API functions return error codes, therefore define at the beginning of your code the int type, which is used to store error codes. Each time when a function returns error codes, verify the result of the operation.
    4. -
    5. Call the contacts_connect() function, which connects your application with the Contact Service. Without this function, you cannot get access to the Contacts database.

      -
      int error_code;
      -error_code = contacts_connect();
      -
    6. -
    7. When the Contacts APIs are not needed anymore, you have to disconnect from the service using the contacts_disconnect() function: -
      error_code = contacts_disconnect();
      -
    - -

    Creating a Contact

    - -

    Before you insert a record, you need to create a record handle. To create it and assign a new record:

    -
    contacts_record_h contact;
    -
    -error_code = contacts_record_create(_contacts_contact._uri, &contact);
    -
    - -

    The first argument determines the type of the created record. Use _contacts_contact._uri to create contact type records.

    -

    This record, however, contains no additional information, like a name or phone number. To add them, you must set contact properties by creating additional records and setting them as child records of the contact record. Note that records created this way are objects in the memory, with contacts_record_h type variables as their handles. Changes made to these objects are not reflected in the database until your explicit request, using contacts_db_insert_record() or contacts_db_update_record().

    - -

    Setting Contact Properties

    - -

    To set the contact name, birthday, and phone number:

    -
    1. Add the contact name. -
      1. Create a name record: -
        contacts_record_h name;
        -
        -error_code = contacts_record_create(_contacts_name._uri, &name);
        -
      2. -
      3. To set the first name, set the value of a string type property identified by _contacts_name.first. -
        error_code = contacts_record_set_str(name, _contacts_name.first, "John");
        -
        -

        The contacts_record_set_str() function is used to set string field values. There are other similar functions for other types, such as integer and double. The name variable is the record handle created above. The second argument – _contacts_name.first – is the property identifier, and the third argument is the value to be assigned.

      4. -
      5. Set the last name similarly: -
        error_code = contacts_record_set_str(name, _contacts_name.last, "Smith");
        -
        -
      6. -
      7. Associate the name record with the contact record, by setting the name as the contact's child record. In this example, it is achieved using contacts_record_add_child_record(). -
        error_code = contacts_record_add_child_record(contact, _contacts_contact.name, name);
        -
        -

        The second argument (_contacts_contact.name) is the parent property to which the child record is assigned. See _contacts_contact view description in the Contacts API. In the API, the name property is listed as one of the record type properties, which means that other records can be assigned to this property as child records ("single" means that only 1 _contacts_name type child record is allowed). The required type of the child record is specified in the API.

    2. -
    3. Add an image. -
      1. Create an image record: -
        contacts_record_h image;
        -
        -error_code = contacts_record_create(_contacts_image._uri, &image);
        -
      2. -
      3. To set the image, set the value of a string type property identified by _contacts_image.path: -
        -char *resource_path = app_get_resource_path();
        -char caller_id_path[1024];
        -snprintf(caller_id_path, sizeof(caller_id_path), "%s/caller_id.jpg", resource_path);
        -free(resource_path);
        -error_code = contacts_record_set_str(image, _contacts_image.path, caller_id_path);
        -
      4. -
      5. Set the image record as the contact's child record: -
        error_code = contacts_record_add_child_record(contact, _contacts_contact.image, image);
        -
    4. -
    5. Add an event. -

      You can add a birthday event associated with the contact. An event contains the date and the event type, among other properties.

      -
      1. Create an event record: -
        contacts_record_h event;
        -
        -error_code = contacts_record_create(_contacts_event._uri, &event);
        -
      2. -
      3. Set the event date. The date is an integer, equal to year * 10000 + month * 100 + day. -
        int year = 1990;
        -int month = 5;
        -int day = 21;
        -int int_date = year * 10000 + month * 100 + day;
        -
        -error_code = contacts_record_set_int(event, _contacts_event.date, int_date);
        -
      4. -
      5. Set the event type to birthday. For available types, see contacts_event_type_e enumeration. -
        error_code = contacts_record_set_int(event, _contacts_event.type, CONTACTS_EVENT_TYPE_BIRTH);
        -
      6. -
      7. If the type is CONTACTS_EVENT_TYPE_CUSTOM, you can set a custom label (see _contacts_event view). -
        error_code = contacts_record_set_int(event, _contacts_event.type, CONTACTS_EVENT_TYPE_CUSTOM);
        -
        -error_code = contacts_record_set_str(event, _contacts_event.label, "Event description");
        -
      8. -
      9. Set the event record as the contact's child record: -
        error_code = contacts_record_add_child_record(contact, _contacts_contact.event, event);
        -
    6. -
    7. Add a phone number. -

      The phone number is added to a parent record using an alternative method.

      -
      1. Create a phone number record and set the number property: -
        contacts_record_h number;
        -
        -error_code = contacts_record_create(_contacts_number._uri, &number);
        -
        -error_code = contacts_record_set_str(number, _contacts_number.number, "+8210-1234-5678");
        -
      2. -
      3. Set the number record as the contact's child record: -
        error_code = contacts_record_add_child_record(contact, _contacts_contact.number, number);
        -
    - -

    Inserting a Contact to the Database

    - -

    To insert a contact:

    - -
    1. When the data is set for the contact and name records, you can insert them into the database. When you insert a parent record, all child records added to it using contacts_record_add_child_record() are inserted automatically.

      - -

      Insert a contact record:

      - -
      int id = -1;
      -
      -error_code = contacts_db_insert_record(contact, &id);
      -
    2. -
    3. When the records are in the database, the objects representing them in the memory are no longer needed and must be destroyed. -
      contacts_record_destroy(contact, true);
      -

      If the second parameter is true, child records of the given record (objects representing them in the memory) are also destroyed. This does not depend on the way the child records were added.

    - -

    Getting Contacts

    - -

    To retrieve contact records:

    - -
    1. A person is an aggregation of one or more contacts associated with the same person. The person is created automatically when inserting a contact record. To use the contact information in your application, you must learn to print basic person information.

      - -

      To get a single person record:

      -
      1. -

        Use the contacts_db_get_record() function with the appropriate person_id:

        -
        contacts_record_h person  = NULL;
        -const int person_id = ... // Acquire person ID
        -int error_code;
        -
        -error_code = contacts_db_get_record(_contacts_person._uri, person_id, &person);
        -
      2. -
      3. When you no longer need the person record, destroy the used structures: -
        -contacts_record_destroy(speeddial, true);
        -
    2. - -
    3. To get the total person record list: -
      1. Use the contacts_db_get_all_records() function:

        -
        contacts_list_h list = NULL;
        -
        -error_code = contacts_db_get_all_records(_contacts_person._uri, 0, 0, &list);
        -
      2. -
      3. Iterate the list and read the records.

        - - - - - - - - - - -
        Note
        Some functions have the _p postfix. It means that the returned value must not be freed by the application, as it is a pointer to the data in an existing record.
        - -
        1. To get the records from the list, use the contacts_list_get_current_record_p(), and contacts_list_next() or contacts_list_prev() functions. Get the details of each record in the loop.

          - -
          contacts_record_h record;
          -while (contacts_list_get_current_record_p(list, &record) == CONTACTS_ERROR_NONE)
          -{
          -   char* display_name;
          -   error_code = contacts_record_get_str_p(record, _contacts_person.display_name, &display_name);
          -   dlog_print(DLOG_DEBUG, LOG_TAG, "display_name: %s", display_name);
          -
          -   error_code = contacts_list_next(list);
          -}
        2. -
        3. If you want to get more details of each record, use the contacts_gl_person_data_t structure like below: -
          contacts_gl_person_data_t *gl_person_data = NULL;
          -contacts_record_h record;
          -while (contacts_list_get_current_record_p(list, &record) == CONTACTS_ERROR_NONE)
          -{
          -   gl_person_data = _create_gl_person_data(record);
          -   // You can get, for example, display name:
          -   // gl_person_data->display_name
          -
          -   _free_gl_person_data(gl_person_data);
          -   error_code = contacts_list_next(list);
          -}
        4. -
        5. The memory for the record data is allocated, and the data is copied from the record by the functions listed further on in this document. -
          typedef struct _contacts_gl_person_data
          -{
          -   int id;
          -   char *display_name;
          -   char *default_phone_number;
          -   contacts_list_h associated_contacts;
          -} contacts_gl_person_data_t;
          -
          -static void _free_gl_person_data(contacts_gl_person_data_t *gl_person_data)
          -{
          -   if (NULL == gl_person_data)
          -      return;
          -   free(gl_person_data->display_name);
          -   free(gl_person_data->default_phone_number);
          -   contacts_list_destroy(gl_person_data->associated_contacts, true);
          -   free(gl_person_data);
          -}
          -
          -static contacts_gl_person_data_t* _create_gl_person_data(contacts_record_h record)
          -{
          -   contacts_gl_person_data_t *gl_person_data;
          -
          -   gl_person_data = malloc(sizeof(contacts_gl_person_data_t));
          -   memset(gl_person_data, 0x0, sizeof(contacts_gl_person_data_t));
          -   if (contacts_record_get_int(record, _contacts_person.id, &gl_person_data->id) != CONTACTS_ERROR_NONE)
          -   {
          -      dlog_print(DLOG_ERROR, LOG_TAG, "get person id failed ");
          -      _free_gl_person_data(gl_person_data);
          -
          -      return NULL;
          -   }
          -   if (false == _get_display_name(record, &gl_person_data->display_name))
          -   {
          -      dlog_print(DLOG_ERROR, LOG_TAG, "_get_display_name() failed ");
          -      _free_gl_person_data(gl_person_data);
          -
          -      return NULL;
          -   }
          -   if (false == _get_default_phone_number(record, &gl_person_data->default_phone_number))
          -   {
          -      dlog_print(DLOG_ERROR, LOG_TAG, "_get_default_phone_number() failed ");
          -      _free_gl_person_data(gl_person_data);
          -
          -      return NULL;
          -   }
          -   if (false == _get_associated_contacts(record, &gl_person_data->associated_contacts))
          -   {
          -      dlog_print(DLOG_ERROR, LOG_TAG, "_get_associated_contacts() failed ");
          -      _free_gl_person_data(gl_person_data);
          -
          -      return NULL;
          -   }
          -   _print_phone_numbers(gl_person_data->associated_contacts);
          -   _print_events(gl_person_data->associated_contacts);
          -
          -   return gl_person_data;
          -}
        6. -
        7. Get person details. -
            -
          • Get the display name. -

            Assuming that you have the person record handle (contacts_record_h), you can access the display_name property. You can read the display name property and print it:

            -
            static bool _get_display_name(contacts_record_h record, char **display_name)
            -{
            -   int error_code;
            -
            -   error_code = contacts_record_get_str(record, _contacts_person.display_name, display_name);
            -   dlog_print(DLOG_DEBUG, LOG_TAG, "display name: %s", *display_name);
            -   if (error_code != CONTACTS_ERROR_NONE)
            -      return false;
            -
            -   return true;
            -}
          • -
          • Get associated contacts. -

            You can get the associated contacts of a person by query. In this example, you get the associated contact records.

            -
            static bool _get_associated_contacts(contacts_record_h record, contacts_list_h *associated_contacts)
            -{
            -   int error_code;
            -   int person_id;
            -   contacts_query_h query = NULL;
            -   contacts_filter_h filter = NULL;
            -
            -   error_code = contacts_record_get_int(record, _contacts_person.id, &person_id);
            -
            -   error_code = CONTACTS_ERROR_NONE;
            -   error_code += contacts_query_create(_contacts_contact._uri, &query);
            -   error_code += contacts_filter_create(_contacts_contact._uri, &filter);
            -   error_code += contacts_filter_add_int(filter, _contacts_contact.person_id, CONTACTS_MATCH_EQUAL, person_id);
            -   error_code += contacts_query_set_filter(query, filter);
            -
            -   error_code += contacts_db_get_records_with_query(query, 0, 0, associated_contacts);
            -
            -   contacts_filter_destroy(filter);
            -   contacts_query_destroy(query);
            -
            -   if (error_code != CONTACTS_ERROR_NONE)
            -      return false;
            -
            -   return true;
            -}
          • -
          • Get phone numbers. -

            You can get the numbers of a person by iterating the contacts list. In this example, you get all the number records and print them.

            -
            static void _print_phone_numbers(contacts_list_h associated_contacts)
            -{
            -   int error_code;
            -   contacts_record_h contact;
            -   if (NULL == associated_contacts) 
            -   {
            -      dlog_print(DLOG_ERROR, LOG_TAG, "associated_contacts is NULL");
            -
            -      return;
            -   }
            -   while (contacts_list_get_current_record_p(associated_contacts, &contact) == CONTACTS_ERROR_NONE)
            -   {
            -      int i;
            -      unsigned int count = 0;
            -
            -      error_code = contacts_record_get_child_record_count(contact, _contacts_contact.number, &count);
            -      if (CONTACTS_ERROR_NONE != error_code) 
            -      {
            -         dlog_print(DLOG_ERROR, LOG_TAG, "contacts_record_get_child_record_count(%d)", error_code);
            -
            -         return;
            -      }
            -      for (i = 0; i < count; i++)
            -      {
            -         contacts_record_h number = NULL;
            -         error_code = contacts_record_get_child_record_at_p(contact, _contacts_contact.number, i, &number);
            -         if (error_code != CONTACTS_ERROR_NONE)
            -            continue;
            -
            -         int number_id;
            -         contacts_record_get_int(number, _contacts_number.id, &number_id);
            -         dlog_print(DLOG_DEBUG, LOG_TAG, "number id: %d", number_id);
            -
            -         char *number_str = NULL;
            -         contacts_record_get_str_p(number, _contacts_number.number, &number_str);
            -         dlog_print(DLOG_DEBUG, LOG_TAG, "number: %s", number_str);
            -      }
            -      error_code = contacts_list_next(associated_contacts);
            -   }
            -}
          • -
          • Get the default phone number. -

            If a contact has multiple phone numbers, one of them is defined as the default phone number. A person also has a default phone number. You can get the default phone number of a person by query. The Contact Service provides the _contacts_person_number view for getting the default phone number of a person. In the default phone number record, the is_primary_default property value is true. This example shows how to get the default phone number of a person by query.

            -
            static bool _get_default_phone_number(contacts_record_h record, char **default_phone_number)
            -{
            -   contacts_query_h query = NULL;
            -   contacts_filter_h filter = NULL;
            -   contacts_list_h list = NULL;
            -   contacts_record_h record_person_number = NULL;
            -   int person_id;
            -   int error_code = CONTACTS_ERROR_NONE;
            -
            -   error_code += contacts_record_get_int(record, _contacts_person.id, &person_id);
            -
            -   error_code += contacts_query_create(_contacts_person_number._uri, &query);
            -   error_code += contacts_filter_create(_contacts_person_number._uri, &filter);
            -   error_code += contacts_filter_add_bool(filter, _contacts_person_number.is_primary_default, true);
            -   error_code += contacts_query_set_filter(query, filter);
            -   error_code += contacts_db_get_records_with_query(query, 0, 0, &list);
            -   error_code += contacts_list_get_current_record_p(list, &record_person_number);
            -
            -   error_code += contacts_record_get_str(record_person_number, _contacts_person_number.number, default_phone_number);
            -
            -   contacts_list_destroy(list, true);
            -   contacts_filter_destroy(filter);
            -   contacts_query_destroy(query);
            -
            -   if (error_code != CONTACTS_ERROR_NONE)
            -      return false;
            -
            -   return true;
            -}
          • -
          • Get events. -

            You can get the events by iterating the contacts list.

            -
            static void _print_events(contacts_list_h associated_contacts)
            -{
            -   int error_code;
            -   contacts_record_h contact;
            -   if (NULL == associated_contacts) 
            -   {
            -      dlog_print(DLOG_ERROR, LOG_TAG, "associated_contacts is NULL");
            -
            -      return;
            -   }
            -   while (contacts_list_get_current_record_p(associated_contacts, &contact) == CONTACTS_ERROR_NONE)
            -   {
            -      int i;
            -      unsigned int count = 0;
            -
            -      error_code = contacts_record_get_child_record_count(contact, _contacts_contact.event, &count);
            -      if (CONTACTS_ERROR_NONE != error_code) 
            -      {
            -         dlog_print(DLOG_ERROR, LOG_TAG, "contacts_record_get_child_record_count(%d)", error_code);
            -
            -         return;
            -      }
            -      for (i = 0; i < count; i++)
            -      {
            -         contacts_record_h event = NULL;
            -         error_code = contacts_record_get_child_record_at_p(contact, _contacts_contact.event, i, &event);
            -         if (error_code != CONTACTS_ERROR_NONE)
            -            continue;
            -
            -         int event_id;
            -         contacts_record_get_int(event, _contacts_event.id, &event_id);
            -         dlog_print(DLOG_DEBUG, LOG_TAG, "event id: %d", event_id);
            -
            -         int date;
            -         contacts_record_get_int(event, _contacts_event.date, &date);
            -         dlog_print(DLOG_DEBUG, LOG_TAG, "event: %d", date);
            -      }
            -      error_code = contacts_list_next(associated_contacts);
            -   }
            -}
      4. -
      5. When you no longer need the person record, destroy the used structures: -
        -contacts_list_destroy(list, true);
        -
    4. -
    5. To get the filtered person record list: -
        -
      1. Use the contacts_db_get_records_with_query() function to filter the list with parameters: -
          -
        1. To get a person list with filtering, create a record list and a query: -
          -contacts_list_h list = NULL;
          -contacts_query_h query = NULL;
          -
          -error_code = contacts_query_create(_contacts_person._uri, &query);
          -
          -
        2. -
        3. Create a filter: -
          -contacts_filter_h filter = NULL;
          -
          -error_code = contacts_filter_create(_contacts_person._uri, &filter);
          -
          -
        4. -
        5. Add a condition, such as display_name: -
          -error_code = contacts_filter_add_str(filter, _contacts_person.display_name, CONTACTS_MATCH_CONTAINS, "John");
          -
          -
        6. -
        7. To add multiple conditions, you must define an operator between the conditions: -
          -error_code = contacts_filter_add_operator(filter, CONTACTS_FILTER_OPERATOR_AND);
          -
          -error_code = contacts_filter_add_bool(filter, _contacts_person.is_favorite, true);
          -
          -
        8. -
        9. Connect the query with the list: -
          -error_code = contacts_query_set_filter(query, filter);
          -
          -error_code = contacts_db_get_records_with_query(query, 0, 0, &list);
          -
          - -

          The third parameter refers to a limit of the results. If 0 is passed, there are no limits. Remember that after all operations, the list must be released.

          -
        10. -
        11. Free the filter and query: -
          -contacts_filter_destroy(filter);
          -contacts_query_destroy(query);
          -
          -
        12. -
        -
      2. -
      3. Iterate the list and read the records.
      4. -
      5. When you no longer need the person record, destroy the used structures: -
        -contacts_list_destroy(list, true);
        -
        -
      6. -
      -
    6. -
    7. To get the searched person record list: -
        -
      1. Use the contacts_db_search_records() function. -

        The Contact Service provides an API for the contact search. The contacts_db_search_records() function provides an easy way to find records based on a given keyword. The following example shows how to find the contact records which contain the "John" keyword:

        - -
        -contacts_list_h list = NULL;
        -
        -error_code = contacts_db_search_records(_contacts_person._uri, "John", 0, 0, &list);
        -
        -
      2. -
      3. Iterate the list and read the records.
      4. -
      5. When you no longer need the person record, destroy the used structures: -
        -contacts_list_destroy(list, true);
        -
        -
      6. -
      -
    8. -
    - -

    Updating a Contact

    - -

    To change the name, birthday, and phone number of an existing contact:

    -
    1. Get the contact. -

      To modify a record, you need to have a handle (contacts_record_h type variable) to a memory object representing the record in the database. One of the ways to acquire it is to use the contact ID:

      -
      int contact_id = ... // Acquire contact ID
      -contacts_record_h contact = NULL;
      -
      -error_code = contacts_db_get_record(_contacts_contact._uri, contact_id, &contact);
      -
      -

      Such handles are also provided by search functions, such as contacts_db_get_records_with_query().

    2. -
    3. Change the name. -
      1. To modify the contact name, get the name record with the contacts_record_get_child_record_at_p() function, which provides a list of the child records of a given type.

        -
        contacts_record_h name = NULL;
        -
        -error_code = contacts_record_get_child_record_at_p(contact, _contacts_contact.name, 0, &name);
        -
        - -

        The function parameters are the parent record, the child record type, a child record index, and the resulting child record. Since there can be only one child record of type _contacts_contact.name, the index is set to 0 to get the first (and only) child record.

      2. - -
      3. Change the first name: -
        error_code = contacts_record_set_str(name, _contacts_name.first, "Mark");
        -
        -

        This only changes the data in the memory object, not in the database. To insert the new value, the name record must be inserted. However, if you acquire this record using contacts_record_get_child_record_at_p() (as in this example), you only need to update the parent record.

    4. -
    5. Change the birthday event. -
      1. If only 1 event is set for the contact, you can call contacts_record_get_child_record_at_p() to get the event record. If there are more events, you must iterate over the child records. -
        contacts_record_h event = NULL;
        -error_code = contacts_record_get_child_record_at_p(contact, _contacts_contact.event, 0, &event);
        -
      2. - -
      3. Update the record: -
        int new_date = 1990 * 10000 + 6 * 100 + 21;
        -
        -error_code = contacts_record_set_int(event, _contacts_event.date, new_date);
        -
    6. -
    7. Update the contact record. -

      Update the contact. Any changes in the child records (such as name and birthday) are also inserted.

      -
      error_code = contacts_db_update_record(contact);
      -
    8. -
    9. When the record handle is no more needed, use the contacts_record_destroy() function to destroy the record handle and free the allocated memory: -
      contacts_record_destroy(contact, true);
    - -

    Deleting a Person

    - -

    To delete a person, call the contacts_db_delete_record() function with _contacts_person._uri as the first parameter and the person ID as the second one:

    -
    int person_id = ... // Acquire person ID
    -
    -error_code = contacts_db_delete_record(_contacts_person._uri, person_id);
    -
    - - - -

    To link and unlink contacts (manually and automatically):

    -
    • To link a person to another person manually, call the contacts_person_link_person() function with base person ID as the first parameter and another person ID as the second one. -
      int person_id1 = ... // Acquire base person ID
      -int person_id2 = ... // Acquire another person ID
      -
      -error_code = contacts_person_link_person(person_id1, person_id2);
      -
    • -
    • To link a contact automatically to a person when creating, set the link_mode property to CONTACTS_CONTACT_LINK_MODE_NONE when inserting. -

      The Contact Service determines the link based on the number and email properties. If the links leads to a contact in the same address book, the link does not work.

      -
      contacts_record_h contact = NULL;
      -
      -error_code = CONTACTS_ERROR_NONE;
      -error_code += contacts_record_create(_contacts_contact._uri, &contact);
      -error_code += contacts_record_set_int(contact, _contacts_contact.link_mode, CONTACTS_CONTACT_LINK_MODE_NONE);
      -
      -contacts_record_h name = NULL;
      -error_code += contacts_record_create(_contacts_name._uri, &name);
      -error_code += contacts_record_set_str(name, _contacts_name.first, "John");
      -error_code += contacts_record_add_child_record(contact, _contacts_contact.name, name);
      -
      -contacts_record_h number = NULL;
      -error_code += contacts_record_create(_contacts_number._uri, &number);
      -error_code += contacts_record_set_str(number, _contacts_number.number, "+8210-1234-5678");
      -error_code += contacts_record_add_child_record(contact, _contacts_contact.number, number);
      -
      -// Contact is linked automatically if an existing person has the same number in a different address book
      -error_code += contacts_db_insert_record(contact, NULL);
      -
      -contacts_record_destroy(contact, true);
    • -
    • To unlink a contact from a person, call the contacts_person_unlink_contact() function with the base person ID as the first parameter and the contact ID as the second one. A new person is created when unlinking. You can get the new person ID as the third parameter. -
      int person_id = ... // Acquire base person ID
      -int contact_id = ... // Acquire contact ID
      -int unlinked_person_id;
      -
      -error_code = contacts_person_unlink_contact(person_id, contact_id, &unlinked_person_id);
      -
    - -

    Managing Favorites

    - -

    To manage person favorites:

    -
    • To set a person as favorite when creating a contact, use the is_favorite property of the person record. If the property is set to true when creating a contact, the person is set as favorite: -
      contacts_record_h contact = NULL;
      -
      -error_code = CONTACTS_ERROR_NONE;
      -error_code += contacts_record_create(_contacts_contact._uri, &contact);
      -error_code += contacts_record_set_bool(contact, _contacts_contact.is_favorite, true);
      -// Set other properties
      -
      -// New person is set as favorite
      -error_code += contacts_db_insert_record(contact, NULL);
      -
      -contacts_record_destroy(contact, true);
    • -
    • To set an existing person as favorite, update the person record: -
      int person_id = ... // Acquire person ID
      -contacts_record_h person = NULL;
      -
      -error_code = contacts_db_get_record(_contacts_person._uri, person_id, &person);
      -
      -error_code = contacts_record_set_bool(person, _contacts_person.is_favorite, true);
      -
      -error_code = contacts_db_update_record(person);
      -
      -contacts_record_destroy(person, true);
    • -
    • To unset a favorite: -
      int person_id = ... // Acquire person ID
      -contacts_record_h person = NULL;
      -
      -error_code = contacts_db_get_record(_contacts_person._uri, person_id, &person);
      -
      -error_code = contacts_record_set_bool(person, _contacts_person.is_favorite, false);
      -
      -error_code = contacts_db_update_record(person);
      -
      -contacts_record_destroy(person, true);
    - -

    Monitoring Person Changes

    - -

    To register a callback function to listen for person changes:

    -
    1. Register the callback function. -
      error_code = contacts_db_add_changed_cb(_contacts_person._uri, _person_changed_callback, NULL);
      -
    2. -
    3. Define the callback function. -

      The callback function is called when the person data changes. The code below shows how to update person details in the callback function.

      -
      static contacts_gl_person_data_t *_gl_person_data = ...
      -void _person_changed_callback(const char *view_uri, void *user_data)
      -{
      -   int error_code;
      -
      -   if (0 != strcmp(view_uri, _contacts_person._uri))
      -      return;
      -
      -   if (_gl_person_data == NULL)
      -      return;
      -
      -   int person_id = _gl_person_data->id;
      -   _free_gl_person_data(_gl_person_data);
      -   _gl_person_data = NULL;
      -
      -   contacts_record_h record = NULL;
      -   error_code = contacts_db_get_record(_contacts_person._uri, person_id, &record);
      -   if (error_code != CONTACTS_ERROR_NONE)
      -      return;
      -
      -   _gl_person_data = _create_gl_person_data(record);
      -   // Use _gl_person_data
      -
      -   contacts_record_destroy(record, true);
      -}
    - -

    Creating a Group

    - -

    To create a new group record:

    -
    contacts_record_h group = NULL;
    -
    -error_code = contacts_record_create(_contacts_group._uri, &group);
    -
    - -

    Setting Group Properties

    - -

    To set group properties:

    - -
    1. Set the group name. -

      The contacts_record_set_str() function sets the name of the group when the second argument is _contacts_group.name. This function takes the group record handle as the first argument, and the name, which is a string value, as the third argument. The name argument is taken from the UI part of the application. The function returns the status code. If the function returns an error, take appropriate action, such as freeing memory, removing handles, and disconnecting from the service if needed.

      -
      error_code = contacts_record_set_str(group, _contacts_group.name, "Neighbors");
      -
    2. -
    3. Set an image and ringtone path. -

      You can set the other properties similarly. To set the image and ringtone path, call the contacts_record_set_str() function and check the error codes.

      -
      -char *resource_path = app_get_resource_path();
      -char temp_path[1024];
      -snprintf(temp_path, sizeof(temp_path), "%s/group_image.jpg", resource_path);
      -error_code = contacts_record_set_str(group, _contacts_group.image_path, temp_path);
      -snprintf(temp_path, sizeof(temp_path), "%s/ringtone.mp3", resource_path);
      -free(resource_path);
      -error_code = contacts_record_set_str(group, _contacts_group.ringtone_path, temp_path);
      -
    - -

    Inserting a Group to the Database

    - -

    To insert a group record:

    -
    1. Use the contacts_db_insert_record() function to insert a newly created group into the Contacts database. -

      The first argument is the group record handle, the second is the record ID. A unique ID is assigned to the record your are adding, and is returned as the third argument of the called function. If the group is inserted successfully, the function returns CONTACTS_ERROR_NONE.

      -
      int added_group_id = -1;
      -
      -error_code = contacts_db_insert_record(group, &added_group_id);
      -
    2. -
    3. After inserting, the used structures have to be destroyed: -
      contacts_record_destroy(group, true);
    - -

    Getting Groups

    - -

    To get all of the group records one by one, or to filter them by one of the properties:

    - -
    1. To get a single group record: -
      1. Use the contacts_db_get_record() function with the appropriate group_id:

        -
        contacts_record_h group;
        -int group_id = ... // Acquire group ID
        -error_code = contacts_db_get_record(_contacts_group._uri, group_id, &group);
        -
      2. -
      3. When you no longer need the group record, destroy the used structures: - -
        contacts_record_destroy(group, true);
    2. - -
    3. To get the total group record list: -
      1. -

        Use the contacts_db_get_all_records() function:

        -
        contacts_list_h list = NULL;
        -error_code = contacts_db_get_all_records(_contacts_group._uri, 0, 0, &list);
        -
      2. - -
      3. To iterate the list and read the records: - - - - - - - - - - -
        Note
        Some functions have the _p postfix. It means that the returned value must not be freed by the application, as it is a pointer to the data in an existing record.
        -
          -
        1. -

          To get the records from the list, use the contacts_list_get_current_record_p(), and contacts_list_next() or contacts_list_prev() functions. Get the details of each record in the loop.

          - -
          -contacts_record_h record;
          -while (contacts_list_get_current_record_p(list, &record) == CONTACTS_ERROR_NONE)
          -{
          -   char* name;
          -   error_code = contacts_record_get_str_p(record, _contacts_group.name, &name);
          -   dlog_print(DLOG_DEBUG, LOG_TAG, "group name: %s", name);
          -
          -   error_code = contacts_list_next(list);
          -   if (error_code != CONTACTS_ERROR_NONE)
          -      break;
          -}
          -
        2. -
        3. If you want to get more details of each record, use the contacts_gl_group_data_t structure like below: -
          -contacts_gl_group_data_t *gl_group_data = NULL;
          -contacts_record_h record;
          -while (contacts_list_get_current_record_p(list, &record) == CONTACTS_ERROR_NONE)
          -{
          -   gl_group_data = _create_gl_group_data(record);
          -   // You can get, for example, display name:
          -   // gl_group_data->name
          -
          -   error_code = contacts_list_next(list);
          -   if (error_code != CONTACTS_ERROR_NONE)
          -      break;
          -}
          -
        4. -
        5. The memory for the record data is allocated, and the data is copied from the record by the functions listed in the following snippet: -
          -typedef struct _contacts_gl_group_data
          -{
          -   int id;
          -   char *name;
          -   char *image_path;
          -   char *ringtone_path;
          -} contacts_gl_group_data_t;
          -
          -static void _free_gl_group_data(contacts_gl_group_data_t *gl_group_data)
          -{
          -   if (NULL == gl_group_data)
          -      return;
          -   free(gl_group_data->name);
          -   free(gl_group_data->image_path);
          -   free(gl_group_data->ringtone_path);
          -   free(gl_group_data);
          -}
          -
          -static contacts_gl_group_data_t* _create_gl_group_data(contacts_record_h record)
          -{
          -   contacts_gl_group_data_t *gl_group_data;
          -   int error_code;
          -
          -   gl_group_data = malloc(sizeof(contacts_gl_group_data_t));
          -   memset(gl_group_data, 0x0, sizeof(contacts_gl_group_data_t));
          -
          -   if (CONTACTS_ERROR_NONE != contacts_record_get_int(record, _contacts_group.id, &gl_group_data->id))
          -   {
          -      dlog_print(DLOG_ERROR, LOG_TAG, "contacts record get integer failed ");
          -      _free_gl_group_data(gl_group_data);
          -
          -      return NULL;
          -   }
          -   if (CONTACTS_ERROR_NONE != contacts_record_get_str(record, _contacts_group.name, &gl_group_data->name))
          -   {
          -      dlog_print(DLOG_ERROR, LOG_TAG, "contacts record get string failed ");
          -      _free_gl_group_data(gl_group_data);
          -
          -      return NULL;
          -   }
          -   if (CONTACTS_ERROR_NONE != contacts_record_get_str(record, _contacts_group.image_path, &gl_group_data->image_path))
          -   {
          -      dlog_print(DLOG_ERROR, LOG_TAG, "contacts record get string failed ");
          -      _free_gl_group_data(gl_group_data);
          -
          -      return NULL;
          -   }
          -   if (CONTACTS_ERROR_NONE != contacts_record_get_str(record, _contacts_group.ringtone_path, &gl_group_data->ringtone_path))
          -   {
          -      dlog_print(DLOG_ERROR, LOG_TAG, "contacts record get string failed ");
          -      _free_gl_group_data(gl_group_data);
          -
          -      return NULL;
          -   }
          -
          -   return gl_group_data;
          -}
          -
        6. -
        -
      4. -
      5. When you no longer need the group record, destroy the used structures: -
        -contacts_list_destroy(list, true);
        -
        -
      6. -
      -
    4. -
    5. To get the filtered group record list: -
        -
      1. Use the contacts_db_get_records_with_query() function to filter the list with parameters: -
          -
        1. To get groups with filtering, you need a record list and a query: -
          contacts_list_h list = NULL;
          -contacts_query_h query = NULL;
          -
          -error_code = contacts_query_create(_contacts_group._uri, &query);
          -
        2. -
        3. Before getting the groups, filter the list. There is a possibility to filter based on various parameters. To create a filter, the following code is used: -
          contacts_filter_h filter = NULL;
          -
          -error_code = contacts_filter_create(_contacts_group._uri, &filter);
          -
        4. -
        5. Add a condition, such as group name: -
          error_code = contacts_filter_add_str(filter, _contacts_group.name, CONTACTS_MATCH_CONTAINS, "neighbors");
          -
          -

          That way only groups which contain the name "neighbors" are retrieved. To use multiple conditions, add an operator between them:

          -
          error_code = contacts_filter_add_operator(filter, CONTACTS_FILTER_OPERATOR_OR);
          -
          -error_code = contacts_filter_add_str(filter, _contacts_group.name, CONTACTS_MATCH_CONTAINS, "friend");
          -
        6. -
        7. Connect the query with the list: -
          error_code = contacts_query_set_filter(query, filter);
          -
          -error_code = contacts_db_get_records_with_query(query, 0, 0, &list);
          -
          -

          The third parameter refers to the limit of the results. If 0 is passed, there are no limits. Remember that after all operations, the list must be released.

        8. -
        9. Free the filter and query: -
          -contacts_filter_destroy(filter);
          -contacts_query_destroy(query);
          -
        10. -
      2. -
      3. To iterate the list and read the records: - - - - - - - - - - -
        Note
        Some functions have the _p postfix. It means that the returned value must not be freed by the application, as it is a pointer to the data in an existing record.
        - -
        1. To get the records from the list, use the contacts_list_get_current_record_p(), and contacts_list_next() or contacts_list_prev() functions. Get the details of each record in the loop.

          - -
          contacts_record_h record;
          -while (contacts_list_get_current_record_p(list, &record) == CONTACTS_ERROR_NONE)
          -{
          -   char* name;
          -   error_code = contacts_record_get_str_p(record, _contacts_group.name, &name);
          -   dlog_print(DLOG_DEBUG, LOG_TAG, "group name: %s", name);
          -
          -   error_code = contacts_list_next(list);
          -   if (error_code != CONTACTS_ERROR_NONE)
          -      break;
          -}
        2. -
        3. If you want to get more details of each record, use the contacts_gl_group_data_t structure like below:

          -
          contacts_gl_group_data_t *gl_group_data = NULL;
          -contacts_record_h record;
          -while (contacts_list_get_current_record_p(list, &record) == CONTACTS_ERROR_NONE)
          -{
          -   gl_group_data = _create_gl_group_data(record);
          -   // You can get, for example, display name:
          -   // gl_group_data->name
          -
          -   error_code = contacts_list_next(list);
          -   if (error_code != CONTACTS_ERROR_NONE)
          -      break;
          -}
        4. -
        5. The memory for the record data is allocated, and the data is copied from the record by the functions listed further on in this document.

          -
          typedef struct _contacts_gl_group_data
          -{
          -   int id;
          -   char *name;
          -   char *image_path;
          -   char *ringtone_path;
          -} contacts_gl_group_data_t;
          -
          -static void _free_gl_group_data(contacts_gl_group_data_t *gl_group_data)
          -{
          -   if (NULL == gl_group_data)
          -      return;
          -   free(gl_group_data->name);
          -   free(gl_group_data->image_path);
          -   free(gl_group_data->ringtone_path);
          -   free(gl_group_data);
          -}
          -
          -static contacts_gl_group_data_t* _create_gl_group_data(contacts_record_h record)
          -{
          -   contacts_gl_group_data_t *gl_group_data;
          -   int error_code;
          -
          -   gl_group_data = malloc(sizeof(contacts_gl_group_data_t));
          -   memset(gl_group_data, 0x0, sizeof(contacts_gl_group_data_t));
          -
          -   if (CONTACTS_ERROR_NONE != contacts_record_get_int(record, _contacts_group.id, &gl_group_data->id))
          -   {
          -      dlog_print(DLOG_ERROR, LOG_TAG, "contacts record get integer failed ");
          -      _free_gl_group_data(gl_group_data);
          -
          -      return NULL;
          -   }
          -   if (CONTACTS_ERROR_NONE != contacts_record_get_str(record, _contacts_group.name, &gl_group_data->name))
          -   {
          -      dlog_print(DLOG_ERROR, LOG_TAG, "contacts record get string failed ");
          -      _free_gl_group_data(gl_group_data);
          -
          -      return NULL;
          -   }
          -   if (CONTACTS_ERROR_NONE != contacts_record_get_str(record, _contacts_group.image_path, &gl_group_data->image_path))
          -   {
          -      dlog_print(DLOG_ERROR, LOG_TAG, "contacts record get string failed ");
          -      _free_gl_group_data(gl_group_data);
          -
          -      return NULL;
          -   }
          -   if (CONTACTS_ERROR_NONE != contacts_record_get_str(record, _contacts_group.ringtone_path, &gl_group_data->ringtone_path))
          -   {
          -      dlog_print(DLOG_ERROR, LOG_TAG, "contacts record get string failed ");
          -      _free_gl_group_data(gl_group_data);
          -
          -      return NULL;
          -   }
          -
          -   return gl_group_data;
          -}
      4. -
      5. When you no longer need the group record, destroy the used structures: -
        -contacts_list_destroy(list, true);
        -
    - -

    Updating a Group

    - -

    To change the name and image of an existing person:

    -
    1. Get the group. -

      To modify a record, you need to have a handle (contacts_record_h type variable) to a memory object representing the record in the database. One of the ways to acquire it is to use the group ID:

      -
      int group_id = ... // Acquire group ID
      -contacts_record_h group = NULL;
      -
      -error_code = contacts_db_get_record(_contacts_group._uri, group_id, &group);
      -
      -

      Such handles are also provided by search functions, such as contacts_db_get_records_with_query().

      -
    2. -
    3. Change the name and image. -

      Change the name and image property using the contacts_record_set_str() function.

      -
      error_code = contacts_record_set_str(group, _contacts_group.name, "Family");
      -char *resource_path = app_get_resource_path();
      -char temp_path[1024];
      -snprintf(temp_path, sizeof(temp_path), "%s/group_image_new.jpg", resource_path);
      -free(resource_path);
      -error_code = contacts_record_set_str(group, _contacts_group.image_path, temp_path);
      -
    4. - -
    5. Update the group record. -

      Update the group. The above changes (name and image) are also inserted.

      -
      error_code = contacts_db_update_record(group);
      -
    6. -
    7. Clean up. -

      When the record handle is no longer needed, use the contacts_record_destroy() function to destroy the record handle and free the allocated memory.

      -
      contacts_record_destroy(group, true);
    - -

    Deleting a Group

    - -

    To delete a group, call the contacts_db_delete_record() function with _contacts_group._uri as the first parameter and group ID as the second one;

    -
    int group_id = ... // Acquire group ID
    -
    -error_code = contacts_db_delete_record(_contacts_group._uri, group_id);
    -
    - -

    Managing Group Members

    - -

    To manage group members:

    - -
    • To add a group member, you need to know the contact ID and the group ID. Then you need to call contacts_group_add_contact(). -
      int contact_id = ... // Acquire contact ID
      -int group_id = ... // Acquire group ID
      -
      -error_code = contacts_group_add_contact(group_id, contact_id);
      -
    • -
    • To remove a contact from a group, call contacts_group_remove_contact(). -
      -error_code = contacts_group_remove_contact(group_id, contact_id);
      -
    • - -
    • To get a list of persons assigned to a specific group: -
      1. Get the records of type _contacts_person_group_assigned: -
        -contacts_query_h query = NULL;
        -contacts_filter_h filter = NULL;
        -contacts_list_h list = NULL;
        -
        -contacts_query_create(_contacts_person_group_assigned._uri, &query);
        -contacts_filter_create(_contacts_person_group_assigned._uri, &filter);
        -contacts_filter_add_int(filter, _contacts_person_group_assigned.group_id, CONTACTS_MATCH_EQUAL, group_id);
        -contacts_query_set_filter(query, filter);
        -contacts_db_get_records_with_query(query, 0, 0, &list);
      2. -
      3. Iterate over the list elements. -
        contacts_record_h person = NULL;
        -int error_code;
        -
        -while (contacts_list_get_current_record_p(list, &person) == CONTACTS_ERROR_NONE)
        -{
        -   int person_id;
        -   contacts_record_get_int(person, _contacts_person_group_assigned.person_id, &person_id);
        -   dlog_print(DLOG_DEBUG, LOG_TAG, "Person id: %d", person_id);
        -
        -   char *display_name;
        -   contacts_record_get_str_p(person, _contacts_person_group_assigned.display_name, &display_name);
        -   dlog_print(DLOG_DEBUG, LOG_TAG, "Display name: %s", display_name);
        -
        -   error_code = contacts_list_next(list);
        -   if (error_code != CONTACTS_ERROR_NONE)
        -      break;
        -}
      4. -
      5. Destroy the filter, query, and list handles when no longer needed. -
        contacts_list_destroy(list, true);
        -contacts_filter_destroy(filter);
        -contacts_query_destroy(query);
    - -

    Monitoring Group Changes

    - -

    To register a callback function to listen for group changes:

    -
    1. Register the callback function. -

      The code below shows how to register a callback function to listen for group changes.

      -
      error_code = contacts_db_add_changed_cb(_contacts_group._uri, _group_changed_callback, NULL);
      -
    2. -
    3. Define the callback function. -

      The callback function is called when the group data changes. The code below shows how to update the group details in the callback function.

      -
      static contacts_gl_group_data_t *_gl_group_data = ...
      -static void _group_changed_callback(const char *view_uri, void *user_data)
      -{
      -   int error_code;
      -
      -   if (0 != strcmp(view_uri, _contacts_group._uri))
      -      return;
      -
      -   if (_gl_group_data == NULL)
      -      return;
      -
      -   int group_id = _gl_group_data->id;
      -   _free_gl_group_data(_gl_group_data);
      -   _gl_group_data = NULL;
      -
      -   contacts_record_h record = NULL;
      -   error_code = contacts_db_get_record(_contacts_group._uri, group_id, &record);
      -   if (error_code != CONTACTS_ERROR_NONE)
      -      return;
      -
      -   _gl_group_data = _create_gl_group_data(record);
      -   // Use _gl_group_data
      -
      -   contacts_record_destroy(record, true);
      -}
    - -

    Making a vCard

    - -

    To make a vCard stream from a person record:

    -
    1. Get the person record by the person ID. -
      int person_id = ... // Acquire person ID
      -
      -contacts_record_h record = NULL;
      -error_code = contacts_db_get_record(_contacts_person._uri, person_id, &record);
      -
    2. -
    3. Make the vCard stream by the person record. -
      char *vcard_stream = NULL;
      -error_code = contacts_vcard_make_from_person(record, &vcard_stream);
      -
      - - - - - - - - - - -
      Note
      The Contact Service API allows you to make a vCard stream from a person, contact, and my profile records: -
      int contacts_vcard_make_from_person(contacts_record_h person, char **vcard_stream);
      -int contacts_vcard_make_from_contact(contacts_record_h contact, char **vcard_stream);
      -int contacts_vcard_make_from_my_profile(contacts_record_h my_profile, char **vcard_stream);
      -
    4. - -
    5. Destroy the handle when it is no longer needed. -
      free(vcard_stream);
      -contacts_record_destroy(record, true);
      -
    - -

    Parsing a vCard

    - -

    To parse a vCard from a file and insert to the database:

    -
    -char *resource_path = app_get_resource_path();
    -char temp_path[1024];
    -snprintf(temp_path, sizeof(temp_path), "%s/vcard.vcf", resource_path);
    -free(resource_path);
    -error_code = contacts_vcard_parse_to_contact_foreach(temp_path, // File path of vCard
    -                                                     _vcard_parse_cb, // Callback function to invoke
    -                                                     NULL); // User data to be passed to the callback function
    -
    - -

    The vCard stream contains multiple contact objects. The callback function is called after parsing each contact. If you return false on the callback function, parsing stops.

    -
    static bool _vcard_parse_cb(contacts_record_h contact, void *user_data)
    -{
    -   if (NULL == contact)
    -      return false;
    -
    -   int contact_id = -1;
    -   error_code = contacts_db_insert_record(contact, &contact_id);
    -   // Use the contact record
    -
    -   return true;
    -}
    - - -

    Creating a Speed Dial

    - -

    To create a speed dial record:

    -
    -contacts_record_h speeddial;
    -error_code = contacts_record_create(_contacts_speeddial._uri, &speeddial);
    -
    -

    The first argument determines the type of the created record. Use _contacts_speeddial._uri to create speed dial type records.

    - -

    Setting Speed Dial Properties

    - -

    To set speed dial properties:

    -
      -
    1. Set the speed dial number. -

      The contacts_record_set_int() function sets the speed dial type when the second argument is _contacts_speeddial.speeddial_number. This function takes the speed dial record handle as the first argument, and the speed dial number, which is an integer value, as the third argument. The function returns the status code. If the function returns an error, take appropriate action, such as freeing memory, removing handles, or disconnecting from the service.

      -
      -int speeddial_number = ... // Acquire speed dial number
      -error_code = contacts_record_set_int(speeddial, _contacts_speeddial.speeddial_number, speeddial_number);
      -
      -
    2. - -
    3. Set the number ID: -
      -int number_id = ... // Acquire number id
      -error_code = contacts_record_set_int(speeddial, _contacts_speeddial. number_id, number_id);
      -
      -
    4. -
    - - - - - - - - - - -
    Note
    This tutorial does not describe how to insert a number. For more information, see the Contact Tutorial.
    - -

    Inserting a Speed Dial to the Database

    - -

    To insert a speed dial record:

    -
    1. Use the contacts_db_insert_record() function to insert a newly created speed dial into the Contacts database. The first argument is the speed dial record handle, the second is the speed dial number. If the speed dial is inserted successfully, the function returns CONTACTS_ERROR_NONE. -
      -int added_speeddial_id = -1;
      -
      -error_code = contacts_db_insert_record(speeddial, &added_speeddial_id);	
      -
      -
    2. - -
    3. After inserting the speed dial record, destroy the used structures: -
      -contacts_record_destroy(speeddial, true);
      -
      -
    4. -
    - -

    Getting Speed Dials

    - -

    To get all of the speed dial records one by one, or to filter them by one of the properties:

    -
      -
    1. To get a single speed dial record: -
        -
      1. Use the contacts_db_get_record() function with the appropriate speeddial_id:

        -
        -contacts_record_h speeddial;
        -int speeddial_id = ... // Acquire speed dial ID
        -error_code = contacts_db_get_record(_contacts_speeddial._uri, speeddial_id, &speeddial);
        -
        -
      2. - -
      3. After finish using the speed dial record, destroy the used structures: - -
        contacts_record_destroy(speeddial, true);
    2. - -
    3. To get the total speed dial record list: -
      1. Use the contacts_db_get_all_records() function: -
        -contacts_list_h list = NULL;
        -error_code = contacts_db_get_all_records(_contacts_speeddial._uri, 0, 0, &list);
        -
        -
      2. - -
      3. To iterate the list and read the records, you can get the records from the list using the contacts_list_get_current_record_p(), contacts_list_next(), or contacts_list_prev() function. Get the details of each record in the loop. - - - - - - - - - - -
        Note
        Some functions have the _p postfix. It means that the returned value must not be freed by the application, as it is a pointer to the data in an existing record.
        - - -
        -contacts_record_h record;
        -while (contacts_list_get_current_record_p(list, &record) == CONTACTS_ERROR_NONE)
        -{
        -   int number;
        -   error_code = contacts_record_get_int(record, _contacts_speeddial.speeddial_number, &number);
        -   dlog_print(DLOG_DEBUG, LOG_TAG, "speed dial number: %d", number);
        -
        -   error_code = contacts_list_next(list);
        -   if (error_code != CONTACTS_ERROR_NONE)
        -      break;
        -}
        -
        - -

        To get more details of each record, use the contacts_gl_speeddial_data_t structure:

        - -
        -contacts_gl_speeddial_data_t *gl_speeddial_data = NULL;
        -contacts_record_h record;
        -while (contacts_list_get_current_record_p(list, &record) == CONTACTS_ERROR_NONE)
        -{
        -   gl_speeddial_data = _create_gl_speeddial_data(record);
        -
        -   _free_gl_speeddial_data(gl_speeddial_data);
        -   error_code = contacts_list_next(list);
        -   if (error_code != CONTACTS_ERROR_NONE)
        -      break;
        -}
        -
        - -

        The memory for the record data is allocated, and the data is copied from the record by the functions shown in the following snippet:

        - -
        -typedef struct _contacts_gl_speeddial_data
        -{
        -   int speeddial_number;
        -   char *number;
        -   char *display_name;
        -   char *image_thumbnail_path;
        -} contacts_gl_speeddial_data_t;
        -
        -static void _free_gl_speeddial_data(contacts_gl_speeddial_data_t *gl_speeddial_data)
        -{
        -   if (NULL == gl_speeddial_data)
        -      return;
        -   free(gl_speeddial_data->number);
        -   free(gl_speeddial_data->display_name);
        -   free(gl_speeddial_data->image_thumbnail_path);
        -   free(gl_speeddial_data);
        -}
        -
        -static contacts_gl_speeddial_data_t* _create_gl_speeddial_data(contacts_record_h record)
        -{
        -   contacts_gl_speeddial_data_t *gl_speeddial_data;
        -   int error_code;
        -
        -   gl_speeddial_data = malloc(sizeof(contacts_gl_speeddial_data_t));
        -   memset(gl_speeddial_data, 0x0, sizeof(contacts_gl_speeddial_data_t));
        -
        -   if (CONTACTS_ERROR_NONE != contacts_record_get_int(record, _contacts_speeddial.speeddial_number, &gl_speeddial_data->speeddial_number))
        -   {
        -      dlog_print(DLOG_ERROR, LOG_TAG, "contacts record get integer failed ");
        -      _free_gl_speeddial_data(gl_speeddial_data);
        -
        -      return NULL;
        -   }
        -   if (CONTACTS_ERROR_NONE != contacts_record_get_str(record, _contacts_speeddial.number, &gl_speeddial_data->number))
        -   {
        -      dlog_print(DLOG_ERROR, LOG_TAG, "contacts record get string failed ");
        -      _free_gl_speeddial_data(gl_speeddial_data);
        -
        -      return NULL;
        -   }
        -   if (CONTACTS_ERROR_NONE != contacts_record_get_str(record, _contacts_speeddial.display_name, &gl_speeddial_data->display_name))
        -   {
        -      dlog_print(DLOG_ERROR, LOG_TAG, "contacts record get string failed ");
        -      _free_gl_speeddial_data(gl_speeddial_data);
        -
        -      return NULL;
        -   }
        -   if (CONTACTS_ERROR_NONE != contacts_record_get_str(record, _contacts_speeddial.image_thumbnail_path, &gl_speeddial_data->image_thumbnail_path))
        -   {
        -      dlog_print(DLOG_ERROR, LOG_TAG, "contacts record get string failed ");
        -      _free_gl_speeddial_data(gl_speeddial_data);
        -
        -      return NULL;
        -   }
        -
        -   return gl_speeddial_data;
        -}
        -
        -
      4. -
      5. After you no longer need the speed dial record, destroy the used structures: -
        -contacts_list_destroy(list, true);
        -
      6. -
      -
    4. -
    5. To get the filtered speed dial record list: -
        -
      1. Use the contacts_db_get_records_with_query() function. -
          -
        1. Create a record list and query: - -
          -contacts_list_h list = NULL;
          -contacts_query_h query = NULL;
          -
          -error_code = contacts_query_create(_contacts_speeddial._uri, &query);
          -
          -
        2. -
        3. Filter the list before getting the speed dials. It is possible to filter with various parameters. To create a filter: -
          -contacts_filter_h filter = NULL;
          -
          -error_code = contacts_filter_create(_contacts_speeddial._uri, &filter);
          -
          -
        4. - -
        5. Add a condition, such as the speed dial number. -

          The following example retrieves only those speed dials whose numbers are less than 3.

          -
          -error_code = contacts_filter_add_int(filter, _contacts_speeddial.speeddial_number, CONTACTS_MATCH_LESS_THAN, 3);
          -
          -

          To use multiple conditions, add an operator between them:

          -
          -error_code = contacts_filter_add_operator(filter, CONTACTS_FILTER_OPERATOR_OR);
          -
          -error_code = contacts_filter_add_int(filter, _contacts_speeddial.speeddial_number, CONTACTS_MATCH_GREATER_THAN, 15);
          -
          -
        6. - -
        7. Connect the query with the list: -
          -error_code = contacts_query_set_filter(query, filter);
          -
          -error_code = contacts_db_get_records_with_query(query, 0, 0, &list);
          -
          -

          The third parameter refers to the limit of the results. If 0 is passed, there are no limits. Remember that after all operations, the list must be released.

          -
        8. - -
        9. Free the filter and query: -
          -contacts_filter_destroy(filter);
          -contacts_query_destroy(query);
          -
          -
        10. -
        -
      2. - -
      3. To iterate the list and read the records, you can get the records from the list using the contacts_list_get_current_record_p(), contacts_list_next(), or contacts_list_prev() function. Get the details of each record in the loop. - - - - - - - - - - -
        Note
        Some functions have the _p postfix. It means that the returned value must not be freed by the application, as it is a pointer to the data in an existing record.
        - -
        -contacts_record_h record;
        -while (contacts_list_get_current_record_p(list, &record) == CONTACTS_ERROR_NONE)
        -{
        -   int number;
        -   error_code = contacts_record_get_int(record, _contacts_speeddial.speeddial_number, &number);
        -   dlog_print(DLOG_DEBUG, LOG_TAG, "speed dial number: %d", number);
        -
        -   error_code = contacts_list_next(list);
        -   if (error_code != CONTACTS_ERROR_NONE)
        -      break;
        -}
        -
        - -

        To get more details of each record, use the contacts_gl_speeddial_data_t structure:

        -
        -contacts_gl_speeddial_data_t *gl_speeddial_data = NULL;
        -contacts_record_h record;
        -while (contacts_list_get_current_record_p(list, &record) == CONTACTS_ERROR_NONE)
        -{
        -   gl_speeddial_data = _create_gl_speeddial_data(record);
        -
        -   _free_gl_speeddial_data(gl_speeddial_data);
        -   error_code = contacts_list_next(list);
        -   if (error_code != CONTACTS_ERROR_NONE)
        -      break;
        -}
        -
        -

        The memory for the record data is allocated, and the data is copied from the record by the functions shown in the following snippet.

        -
        -typedef struct _contacts_gl_speeddial_data
        -{
        -   int speeddial_number;
        -   char *number;
        -   char *display_name;
        -   char *image_thumbnail_path;
        -} contacts_gl_speeddial_data_t;
        -
        -static void _free_gl_speeddial_data(contacts_gl_speeddial_data_t *gl_speeddial_data)
        -{
        -   if (NULL == gl_speeddial_data)
        -      return;
        -   free(gl_speeddial_data->number);
        -   free(gl_speeddial_data->display_name);
        -   free(gl_speeddial_data->image_thumbnail_path);
        -   free(gl_speeddial_data);
        -}
        -
        -static contacts_gl_speeddial_data_t* _create_gl_speeddial_data(contacts_record_h record)
        -{
        -   contacts_gl_speeddial_data_t *gl_speeddial_data;
        -   int error_code;
        -
        -   gl_speeddial_data = malloc(sizeof(contacts_gl_speeddial_data_t));
        -   memset(gl_speeddial_data, 0x0, sizeof(contacts_gl_speeddial_data_t));
        -
        -   if (CONTACTS_ERROR_NONE != contacts_record_get_int(record, _contacts_speeddial.speeddial_number, &gl_speeddial_data->speeddial_number))
        -   {
        -      dlog_print(DLOG_ERROR, LOG_TAG, "contacts record get integer failed ");
        -      _free_gl_speeddial_data(gl_speeddial_data);
        -
        -      return NULL;
        -   }
        -   if (CONTACTS_ERROR_NONE != contacts_record_get_str(record, _contacts_speeddial.number, &gl_speeddial_data->number))
        -   {
        -      dlog_print(DLOG_ERROR, LOG_TAG, "contacts record get string failed ");
        -      _free_gl_speeddial_data(gl_speeddial_data);
        -
        -      return NULL;
        -   }
        -   if (CONTACTS_ERROR_NONE != contacts_record_get_str(record, _contacts_speeddial.display_name, &gl_speeddial_data->display_name))
        -   {
        -      dlog_print(DLOG_ERROR, LOG_TAG, "contacts record get string failed ");
        -      _free_gl_speeddial_data(gl_speeddial_data);
        -
        -      return NULL;
        -   }
        -   if (CONTACTS_ERROR_NONE != contacts_record_get_str(record, _contacts_speeddial.image_thumbnail_path, &gl_speeddial_data->image_thumbnail_path))
        -   {
        -      dlog_print(DLOG_ERROR, LOG_TAG, "contacts record get string failed ");
        -      _free_gl_speeddial_data(gl_speeddial_data);
        -
        -      return NULL;
        -   }
        -
        -   return gl_speeddial_data;
        -}
        -
        -
      4. -
      5. When you no longer need the speed dial record, destroy the used structures: -
        -contacts_list_destroy(list, true);
      6. -
    - -

    Updating a Speed Dial

    - -

    To change the number ID of an existing speed dial:

    -
      -
    1. Get the speed dial. -

      To modify a record, you need to have a handle (contacts_record_h type variable) to a memory object representing the record in the database. One of the ways to acquire it is to use the speed dial number:

      -
      -int speeddial_number = ... // Acquire speed dial number
      -contacts_record_h speeddial = NULL;
      -
      -error_code = contacts_db_get_record(_contacts_speeddial._uri, speeddial_number, &speeddial);
      -
      - -

      Such handles are also provided by search functions, such as contacts_db_get_records_with_query().

      -
    2. - -
    3. Change the number ID by setting the number_id property using the contacts_record_set_int() function: -
      -int number_id = ... // Acquire number id
      -error_code = contacts_record_set_int(speeddial, _contacts_speeddial.number_id, number_id);
      -if (error_code != CONTACTS_ERROR_NONE)
      -   dlog_print(DLOG_ERROR, LOG_TAG, "contacts record set integer failed: %x", error_code);
      -
      -
    4. - -
    5. Update the speed dial record. -

      Update the speed dial. The above changes (number_id) are also inserted.

      -
      -error_code = contacts_db_update_record(speeddial);
      -
      -
    6. - -
    7. Clean up. -

      When the record handle is no longer needed, use the contacts_record_destroy() function to destroy the record handle and free the allocated memory.

      -
      -contacts_record_destroy(speeddial, true);
      -
      -
    8. -
    - -

    Deleting a Speed Dial

    - -

    To delete a speed dial, call the contacts_db_delete_record() function with _contacts_speeddial._uri as the first parameter and speed dial number as the second one;

    -
    -int speeddial_number = ... // Acquire speed dial number
    -
    -error_code = contacts_db_delete_record(_contacts_speeddial._uri, speeddial_number);
    -
    - - -

    Creating a Log

    - -

    To create a log record:

    -
    -contacts_record_h log;
    -error_code = contacts_record_create(_contacts_phone_log._uri, &log);
    -if (error_code != CONTACTS_ERROR_NONE)
    -   dlog_print(DLOG_ERROR, LOG_TAG, "contacts record create failed: %x", error_code);
    -
    -

    The first argument determines the type of the created record. Use _contacts_phone_log._uri to create log type records.

    - -

    Setting Log Properties

    - -

    To set log properties:

    -
      -
    1. Set the log type. -

      The contacts_record_set_int() function sets the type of the log when the second argument is _contacts_phone_log.log_type. This function takes the log record handle as the first argument, and the type, which is a integer value, as the third argument. The function returns the status code. If the function returns an error, free memory, remove handles, and disconnect from the service, if needed.

      -
      -error_code = contacts_record_set_int(log, _contacts_phone_log.log_type, CONTACTS_PLOG_TYPE_VOICE_INCOMMING);
      -if (error_code != CONTACTS_ERROR_NONE)
      -   dlog_print(DLOG_ERROR, LOG_TAG, "contacts record set integer failed: %x", error_code);
      -
      - -

      The enumeration flag names for the log types are:

      -
      -CONTACTS_PLOG_TYPE_NONE
      -CONTACTS_PLOG_TYPE_VOICE_INCOMMING
      -CONTACTS_PLOG_TYPE_VOICE_OUTGOING
      -CONTACTS_PLOG_TYPE_VIDEO_INCOMING
      -CONTACTS_PLOG_TYPE_VIDEO_OUTGOING
      -CONTACTS_PLOG_TYPE_VOICE_INCOMMING_UNSEEN
      -CONTACTS_PLOG_TYPE_VOICE_INCOMMING_SEEN
      -CONTACTS_PLOG_TYPE_VIDEO_INCOMING_UNSEEN
      -CONTACTS_PLOG_TYPE_VIDEO_INCOMING_SEEN
      -CONTACTS_PLOG_TYPE_VOICE_REJECT
      -CONTACTS_PLOG_TYPE_VIDEO_REJECT
      -CONTACTS_PLOG_TYPE_VOICE_BLOCKED
      -CONTACTS_PLOG_TYPE_VIDEO_BLOCKED
      -CONTACTS_PLOG_TYPE_MMS_INCOMING
      -CONTACTS_PLOG_TYPE_MMS_OUTGOING
      -CONTACTS_PLOG_TYPE_SMS_INCOMING
      -CONTACTS_PLOG_TYPE_SMS_OUTGOING
      -CONTACTS_PLOG_TYPE_SMS_BLOCKED
      -CONTACTS_PLOG_TYPE_MMS_BLOCKED
      -CONTACTS_PLOG_TYPE_EMAIL_RECEIVED
      -CONTACTS_PLOG_TYPE_EMAIL_SENT
      -
    2. - -
    3. Set time, duration, and address: -
      -error_code = contacts_record_set_int(log, _contacts_phone_log.log_time, (int)time(NULL));
      -if (error_code != CONTACTS_ERROR_NONE)
      -   dlog_print(DLOG_ERROR, LOG_TAG, "contacts record set integer failed: %x", error_code);
      -
      -error_code = contacts_record_set_int(log, _contacts_phone_log.extra_data1, 37);
      -if (error_code != CONTACTS_ERROR_NONE)
      -   dlog_print(DLOG_ERROR, LOG_TAG, "contacts record set integer failed: %x", error_code);
      -
      -error_code = contacts_record_set_str(log, _contacts_phone_log.address, "+8231-1234-5678");
      -if (error_code != CONTACTS_ERROR_NONE)
      -   dlog_print(DLOG_ERROR, LOG_TAG, "contacts record set string failed: %x", error_code);
      -
      - -

      Log time means the number of seconds since 1970-01-01 00:00:00 (UTC). The extra_data1 property means the message_id, email_id, or duration (seconds) of a call. The address property means a number or an email.

      -
    4. -
    - -

    Inserting a Log to the Database

    - -

    To insert a log record:

    -
      -
    1. Use the contacts_db_insert_record() function to insert a newly created log into the Contacts database. The first argument is the log record handle, the second is the record ID. If the log is inserted successfully, the function returns CONTACTS_ERROR_NONE. -
      -int added_log_id = -1;
      -
      -error_code = contacts_db_insert_record(log, &added_log_id);
      -if (error_code != CONTACTS_ERROR_NONE)
      -   dlog_print(DLOG_ERROR, LOG_TAG, "contacts db insert record failed: %x", error_code);
      -
      -
    2. -
    3. After inserting the log, destroy the used structures: -
      contacts_record_destroy(log, true);
      -
    4. -
    - -

    Getting Logs

    - -

    To get all log records one by one, or to filter them by one of the properties:

    -
      -
    1. To get a single log record: -
      1. Use the contacts_db_get_record() function with the appropriate log_id:

        -
        contacts_record_h log;
        -int log_id = ... // Acquire log ID
        -error_code = contacts_db_get_record(_contacts_phone_log._uri, log_id, &log);
        -if (error_code != CONTACTS_ERROR_NONE)
        -   dlog_print(DLOG_ERROR, LOG_TAG, "contacts db get record failed: %x", error_code);
        -
      2. -
      3. After inserting the log, destroy the used structures: -
        contacts_record_destroy(log, true);
      -
    2. -
    3. To get the total log record list: -
      1. Use the contacts_db_get_all_records() function:

        -
        -contacts_list_h list = NULL;
        -error_code = contacts_db_get_all_records(_contacts_phone_log._uri, 0, 0, &list);
        -if (error_code != CONTACTS_ERROR_NONE)
        -   dlog_print(DLOG_ERROR, LOG_TAG, "contacts db get all records failed: %x", error_code);
        -
        -
      2. - -
      3. To iterate the list and read the records, you can get the records from the list using the contacts_list_get_current_record_p(), contacts_list_next(), or contacts_list_prev() function. Get the details of each record in the loop. - - - - - - - - - - -
        Note
        Some functions have the _p postfix. It means that the returned value must not be freed by the application, as it is a pointer to the data in an existing record.
        - - -
        -contacts_record_h record;
        -while (contacts_list_get_current_record_p(list, &record) == CONTACTS_ERROR_NONE)
        -{
        -   int type;
        -   error_code = contacts_record_get_int(record, _contacts_phone_log.log_type, &type);
        -   dlog_print(DLOG_DEBUG, LOG_TAG, "log type: %d", type);
        -
        -   error_code = contacts_list_next(list);
        -   if (error_code != CONTACTS_ERROR_NONE)
        -      break;
        -}
        -
        - -

        To get more details of each record, use the contacts_gl_log_data_t structure:

        - -
        -contacts_gl_log_data_t *gl_log_data = NULL;
        -contacts_record_h record;
        -while (contacts_list_get_current_record_p(list, &record) == CONTACTS_ERROR_NONE)
        -{
        -   gl_log_data = _create_gl_log_data(record);
        -
        -   _free_gl_log_data(gl_log_data);
        -   error_code = contacts_list_next(list);
        -   if (error_code != CONTACTS_ERROR_NONE)
        -      break;
        -}
        -
        - -

        The memory for the record data is allocated, and the data is copied from the record by the functions listed further on in this document.

        - -
        -typedef struct _contacts_gl_log_data
        -{
        -   int id;
        -   char *address;
        -   int log_type;
        -   int log_time;
        -} contacts_gl_log_data_t;
        -
        -static void _free_gl_log_data(contacts_gl_log_data_t *gl_log_data)
        -{
        -   if (NULL == gl_log_data)
        -      return;
        -   free(gl_log_data->address);
        -   free(gl_log_data);
        -}
        -
        -static contacts_gl_log_data_t* _create_gl_log_data(contacts_record_h record)
        -{
        -   contacts_gl_log_data_t *gl_log_data;
        -   int error_code;
        -
        -   gl_log_data = malloc(sizeof(contacts_gl_log_data_t));
        -   memset(gl_log_data, 0x0, sizeof(contacts_gl_log_data_t));
        -
        -   if (CONTACTS_ERROR_NONE != contacts_record_get_int(record, _contacts_phone_log.id, &gl_log_data->id))
        -   {
        -      dlog_print(DLOG_ERROR, LOG_TAG, "contacts record get integer failed ");
        -      _free_gl_log_data(gl_log_data);
        -
        -      return NULL;
        -   }
        -   if (CONTACTS_ERROR_NONE != contacts_record_get_str(record, _contacts_phone_log.address, &gl_log_data->address))
        -   {								
        -      dlog_print(DLOG_ERROR, LOG_TAG, "contacts record get string failed ");
        -      _free_gl_log_data(gl_log_data);
        -
        -      return NULL;
        -   }
        -   if (CONTACTS_ERROR_NONE != contacts_record_get_int(record, _contacts_phone_log.log_type, &gl_log_data->log_type))
        -   {
        -      dlog_print(DLOG_ERROR, LOG_TAG, "contacts record get integer failed ");
        -      _free_gl_log_data(gl_log_data);
        -
        -      return NULL;
        -   }
        -   if (CONTACTS_ERROR_NONE != contacts_record_get_int(record, _contacts_phone_log.log_time, &gl_log_data->log_time))
        -   {
        -      dlog_print(DLOG_ERROR, LOG_TAG, "contacts record get integer failed ");
        -      _free_gl_log_data(gl_log_data);
        -
        -      return NULL;
        -   }
        -
        -   return gl_log_data;
        -}
        -
        -
      4. -
      5. After getting the log record, destroy the used structures: -
        -contacts_list_destroy(list, true);
        -
      6. -
      -
    4. -
    5. To get the filtered log record list: -
        -
      1. Use the contacts_db_get_records_with_query() function. -
          -
        1. Create a record list and query: -
          -contacts_list_h list = NULL;
          -contacts_query_h query = NULL;
          -
          -error_code = contacts_query_create(_contacts_phone_log._uri, &query);
          -if (error_code != CONTACTS_ERROR_NONE)
          -   dlog_print(DLOG_ERROR, LOG_TAG, "contacts query create failed: %x", error_code);
          -
          -
        2. - -
        3. Before getting the logs, filter the list. There is a possibility to filter based on various parameters. To create a filter, use the following code: -
          -contacts_filter_h filter = NULL;
          -
          -error_code = contacts_filter_create(_contacts_phone_log._uri, &filter);
          -if (error_code != CONTACTS_ERROR_NONE)
          -   dlog_print(DLOG_ERROR, LOG_TAG, "contacts filter create failed: %x", error_code);
          -
          -
        4. - -
        5. Add a condition, such as the log type. -

          The following example retrieves only those logs which type is CONTACTS_PLOG_TYPE_VOICE_INCOMMING.

          -
          -error_code = contacts_filter_add_int(filter, _contacts_phone_log.log_type, CONTACTS_MATCH_EQUAL, CONTACTS_PLOG_TYPE_VOICE_INCOMMING);
          -if (error_code != CONTACTS_ERROR_NONE)
          -   dlog_print(DLOG_ERROR, LOG_TAG, "contacts filter add integer failed: %x", error_code);
          -
          - -

          To use multiple conditions, add an operator between them:

          -
          -error_code = contacts_filter_add_operator(filter, CONTACTS_FILTER_OPERATOR_OR);
          -if (error_code != CONTACTS_ERROR_NONE)
          -   dlog_print(DLOG_ERROR, LOG_TAG, "contacts filter add operator failed: %x", error_code);
          -error_code = contacts_filter_add_int(filter, _contacts_phone_log.log_type, CONTACTS_MATCH_EQUAL, CONTACTS_PLOG_TYPE_VOICE_OUTGOING);
          -if (error_code != CONTACTS_ERROR_NONE)
          -   dlog_print(DLOG_ERROR, LOG_TAG, "contacts filter add integer failed: %x", error_code);
          -
          -
        6. - -
        7. Connect the query with the list: -
          -error_code = contacts_query_set_filter(query, filter);
          -if (error_code != CONTACTS_ERROR_NONE)
          -   dlog_print(DLOG_ERROR, LOG_TAG, "contacts query set filter failed: %x", error_code);
          -
          -error_code = contacts_db_get_records_with_query(query, 0, 0, &list);
          -if (error_code != CONTACTS_ERROR_NONE)
          -   dlog_print(DLOG_ERROR, LOG_TAG, "contacts db get records with query failed: %x", error_code);
          -
          -

          The third parameter refers to the limit of the results. If 0 is passed, there are no limits. After all operations, release the list.

          -
        8. - -
        9. Free the filter and query: -
          -contacts_filter_destroy(filter);
          -contacts_query_destroy(query);
          -
          -
        10. -
        -
      2. - -
      3. To iterate the list and read the records, use the contacts_list_get_current_record_p(), contacts_list_next(), or contacts_list_prev() function. Get the details of each record in the loop. - - - - - - - - - - - -
        Note
        Some functions have the _p postfix. It means that the returned value must not be freed by the application, as it is a pointer to the data in an existing record.
        - -
        -contacts_record_h record;
        -while (contacts_list_get_current_record_p(list, &record) == CONTACTS_ERROR_NONE)
        -{
        -   int type;
        -   error_code = contacts_record_get_int(record, _contacts_phone_log.log_type, &type);
        -   dlog_print(DLOG_DEBUG, LOG_TAG, "log type: %d", type);
        -
        -   error_code = contacts_list_next(list);
        -   if (error_code != CONTACTS_ERROR_NONE)
        -      break;
        -}
        -
        - -

        To get more details of each record, use the contacts_gl_log_data_t structure:

        -
        -contacts_gl_log_data_t *gl_log_data = NULL;
        -contacts_record_h record;
        -while (contacts_list_get_current_record_p(list, &record) == CONTACTS_ERROR_NONE)
        -{
        -   gl_log_data = _create_gl_log_data(record);
        -
        -   _free_gl_log_data(gl_log_data);
        -   error_code = contacts_list_next(list);
        -   if (error_code != CONTACTS_ERROR_NONE)
        -      break;
        -}
        -
        -

        The memory for the record data is allocated, and the data is copied from the record by the functions listed further on in this document.

        -
        -typedef struct _contacts_gl_log_data
        -{
        -   int id;
        -   char *address;
        -   int log_type;
        -   int log_time;
        -} contacts_gl_log_data_t;
        -
        -static void _free_gl_log_data(contacts_gl_log_data_t *gl_log_data)
        -{
        -   if (NULL == gl_log_data)
        -      return;
        -   free(gl_log_data->address);
        -   free(gl_log_data);
        -}
        -
        -static contacts_gl_log_data_t* _create_gl_log_data(contacts_record_h record)
        -{
        -   contacts_gl_log_data_t *gl_log_data;
        -   int error_code;
        -
        -   gl_log_data = malloc(sizeof(contacts_gl_log_data_t));
        -   memset(gl_log_data, 0x0, sizeof(contacts_gl_log_data_t));
        -
        -   if (CONTACTS_ERROR_NONE != contacts_record_get_int(record, _contacts_phone_log.id, &gl_log_data->id))
        -   {
        -      dlog_print(DLOG_ERROR, LOG_TAG, "contacts record get integer failed ");
        -      _free_gl_log_data(gl_log_data);
        -
        -      return NULL;
        -   }
        -   if (CONTACTS_ERROR_NONE != contacts_record_get_str(record, _contacts_phone_log.address, &gl_log_data->address))
        -   {								
        -      dlog_print(DLOG_ERROR, LOG_TAG, "contacts record get string failed ");
        -      _free_gl_log_data(gl_log_data);
        -
        -      return NULL;
        -   }
        -   if (CONTACTS_ERROR_NONE != contacts_record_get_int(record, _contacts_phone_log.log_type, &gl_log_data->log_type))
        -   {
        -      dlog_print(DLOG_ERROR, LOG_TAG, "contacts record get integer failed ");
        -      _free_gl_log_data(gl_log_data);
        -
        -      return NULL;
        -   }
        -   if (CONTACTS_ERROR_NONE != contacts_record_get_int(record, _contacts_phone_log.log_time, &gl_log_data->log_time))
        -   {
        -      dlog_print(DLOG_ERROR, LOG_TAG, "contacts record get integer failed ");
        -      _free_gl_log_data(gl_log_data);
        -
        -      return NULL;
        -   }
        -
        -   return gl_log_data;
        -}
        -
        -
      4. -
      5. After getting the log record, destroy the used structures. -
        -contacts_list_destroy(list, true);
      6. -
    - -

    Deleting a Log

    - -

    To delete a log, use the contacts_db_delete_record() function with _contacts_phone_log._uri as the first parameter and log ID as the second one:

    -
    -int log_id = ... // Acquire log ID
    -
    -error_code = contacts_db_delete_record(_contacts_phone_log._uri, log_id);
    -if (error_code != CONTACTS_ERROR_NONE)
    -   dlog_print(DLOG_ERROR, LOG_TAG, "contacts db delete record failed: %x", error_code);
    -
    - -

    Inserting New Records

    - -

    To insert a new record:

    - -
      -
    1. Create a record. - -

      The basic concept in the Contacts API is a record. A record can be a complex set of data, containing other data. For example, an address record can contain the country, region, and street. Also, the contained data can be a reference to another record. For example, a contact record contains the address property, which is a reference to an address record. Effectively, a record can be a node in a tree or a graph of relations between records.

      - -

      Each record type has a special view structure, which contains identifiers of its properties. For example, the _contacts_contact view describes the properties of the contact record. It contains properties, such as the name, company, and nickname of the contact. A special property in such structures is the URI, which is used to identify the record type. Every view describing a record has this property.

      - -

      To create a new contact record, create a root record of the _contacts_contact view type:

      - -
      -contacts_record_h hcontact = NULL;
      -
      -error_code = contacts_record_create(_contacts_contact._uri, &hcontact);
      -
      - -

      Creating a group is similar to creating a record. The only difference is using another view – the group view.

      -
    2. - -
    3. Set properties. -

      Set the properties of the newly created record. Almost every property in the contact view is a record itself, so create more records, as needed. The following example shows how to add an address record to a contact.

      - -
        -
      1. Create a new record. -

        Use the address view because the added record is an address:

        - -
        -contacts_record_h haddress = NULL;
        -contacts_record_create(_contacts_address._uri, &haddress);
        -
        -
      2. - -
      3. Set the address record properties (parameters available in the current view): - -
        -contacts_record_set_str(haddress, _contacts_address.country, "Korea");
        -
        -
      4. - -
      5. Add the address record to your contact: - -
        -contacts_record_add_child_record(hcontact, _contacts_contact.address, haddress
        -
        -

        Do not destroy the record handle which is added to another as a child.

        -
      -
    4. - -
    5. Insert records. -

      After setting properties, insert the root record only to the database. You receive the ID of this record in the database.

      - -
      -int id;
      -error_code = contacts_db_insert_record(hcontact, &id);
      -
      -
    6. - -
    7. Clean up. -

      Destroy the record structure.

      - -
      -error_code = contacts_record_destroy(hcontact, true);
      -
      -
    8. -
    - -

    Getting Record Details

    - -

    To find all records and get their details:

    - -
      -
    1. Get a single record. -

      Get a record handle when you know its ID:

      - -
      -contacts_record_h record;
      -const int ID = 2;
      -
      -contacts_db_get_record(_contacts_contact._uri, ID, &record);
      -
      -
    2. - -
    3. Get record details. -

      To get the details, use the contacts_record_get_* function with the record handle. The following example gets the contact display name:

      - -
      -char * d_name;
      -contacts_record_get_str(record, _contacts_contact.display_name, d_name);
      -free(d_name);
      -
      -
    4. - -
    5. Get child record details. -

      When using 1 view, you sometimes need details from another view. For example, you get records using the contact view and need to get the first or last name. If you want to get the name, get the record from the name view using the contacts_db_get_child_record_at_p() function:

      - -
      -contacts_record_h child_record;
      -contacts_record_get_child_record_at_p(record, _contacts_contact.name, 0, &child_record);
      -// In the child_record, you have the record form name view
      -char *f_name;
      -contacts_record_get_str(record, _contacts_name.first_name, f_name);
      -free(f_name);
      -
      -
    6. - -
    7. Get parent record details. -

      When using the child view, you sometimes need to get details of the parent. For example, you get records using the name view and want to know whether the contact has an email address. To get the parent details, get its ID in almost every view with contact_id. After that, get the parent record:

      - -
      -contacts_record_h parent_record;
      -int parent_id;
      -contacts_record_get_int(record, _contacts_name.contact_id, &parent_id);
      -contacts_db_get_child_record(_contacts_contact._uri, parent_id, &parent_record);
      -// In the parent_record, get bool
      -bool h_email;
      -contacts_record_get_bool(parent_record, _contacts_contact.has_email, &h_email);
      -
      -
    8. - -
    9. Get details through a structure. -
      1. For more record details, use a structure to get them.

        -

        The memory for the record data is allocated and the data is copied from the record by functions listed in the following step.

        - -
        -gldata = _create_gl_data(record);
        -char * number = gldata->number;
        -
        -typedef struct _contact_gl_data
        -{
        -   int id;
        -   char *first;
        -   char *last;
        -   char *number;
        -   char *image_path;
        -} contact_gl_data_t;
        -
        -static contact_gl_data_t *_create_gl_data(contacts_record_h r_contact)
        -{
        -   contact_gl_data_t *data;
        -   data = malloc(sizeof(contact_gl_data_t));
        -   memset(data, 0x0, sizeof(contact_gl_data_t));
        -
        -   if (! _get_contact_id(r_contact, &data->id))
        -   {
        -      free(data);
        -
        -      return NULL;
        -   }
        -
        -   if (!_get_contact_number(r_contact, &data->number))
        -   {
        -      free(data);
        -
        -      return NULL;
        -   }
        -   if (!_get_contact_first(r_contact, &data->first))
        -   {
        -      free(data->number);
        -      free(data);
        -
        -      return NULL;
        -   }
        -   if (!_get_contact_last(r_contact, &data->last))
        -   {
        -      free(data->number);
        -      free(data->first);
        -      free(data);
        -
        -      return NULL;
        -   }
        -   if (!_get_contact_image(r_contact, &data->image_path))
        -   {
        -      free(data->number);
        -      free(data->first);
        -      free(data->last);
        -      free(data);
        -
        -      return NULL;
        -   }
        -
        -   return data;
        -}
        -
        -
      2. - -
      3. Retrieve record data into the structure. -

        Contacts are organized in a parent-child structure. To access specified data from a record, get the child responsible for the requested type using the contacts_record_get_child_record_at_p() function (for the property lists, see View/Property). Do not pass any data returned by a function with the _p suffix to the free() function.

        - -
        • To get the name details, get the _contacts_contact.name (representing the child) from the r_contact parent. Both structures have the contacts_record_h type. After obtaining a child record, get the desired data from it using the contacts_record_get_str() function.

          - -
          -static bool _get_contact_last(contacts_record_h r_contact, char **last)
          -{
          -   contacts_record_h r_name;
          -   int error_code;
          -
          -   error_code = contacts_record_get_child_record_at_p(r_contact,  _contacts_contact.name, 0, &r_name);
          -
          -   error_code = contacts_record_get_str(r_name, _contacts_name.last, last);
          -}
          -
        • - -
        • The record ID is obtained directly from the parent record. An ID is a unique number representing the record key in the database. You can manipulate a record with functions, such as contacts_db_get_record() or contacts_db_delete_records(), if you know their ID.

          - -
          -static bool _get_contact_id(contacts_record_h r_contact, int *id)
          -{
          -   int error_code;
          -
          -   error_code = contacts_record_get_int(r_contact, _contacts_contact.id, id);
          -
          -   return true;
          -}
          -
        • - -
        • To get a contact number, check whether it exists using the contacts_record_get_bool() function. If it exists, use the various Query and Filter functions from the Contacts API to make a query to get a list. At the end, free any data returned by a function not containing the _p suffix.

          -
          • Get a list of all numbers and filter the list to get the default: -
            -static bool _get_contact_number(contacts_record_h r_contact, char **number)
            -{
            -   int id;
            -   int error_code;
            -   contacts_record_h r_number;
            -   contacts_query_h query = NULL;
            -   contacts_filter_h filter = NULL;
            -   contacts_list_h list = NULL;
            -
            -   if (!_get_contact_id(r_contact, &id))
            -      return false;
            -
            -
            -   bool has_number;
            -   error_code = contacts_record_get_bool(r_contact, _contacts_contact.has_phonenumber, &has_number);
            -
            -   error_code = contacts_query_create(_contacts_number._uri, &query);
            -
            -   unsigned int fields[] = { _contacts_number.number };
            -   error_code = contacts_query_set_projection(query, fields, 1);
            -
            -   error_code = contacts_filter_create(_contacts_number._uri, &filter);
            -
            -   error_code = contacts_filter_add_int(filter, _contacts_number.contact_id, CONTACTS_MATCH_EXACTLY, id);
            -
            -   error_code = contacts_filter_add_operator(filter, CONTACTS_FILTER_OPERATOR_AND);
            -
            -   error_code = contacts_filter_add_bool(filter, _contacts_number.is_default, true);
            -
            -   error_code = contacts_query_set_filter(query, filter);
            -
            -   error_code = contacts_db_get_records_with_query(query, 0, 1, &list);
            -
            -   error_code = contacts_list_get_current_record_p(list, &r_number);
            -
            -   error_code = contacts_record_get_str(r_number, _contacts_number.number, number);
            -
            -   contacts_query_destroy(query);
            -   contacts_filter_destroy(filter);
            -   contacts_list_destroy(list, true);
            -}
            -
          • - -
          • Directly access the default number:

            - -
            -static bool _get_contact_number(contacts_record_h r_contact, char **number)
            -{
            -   int error_code;
            -   contacts_record_h r_number;
            -
            -   bool has_number;
            -   error_code = contacts_record_get_bool(r_contact, _contacts_contact.has_phonenumber, &has_number);
            -
            -   if (!has_number)
            -   {
            -      *number = NULL;
            -
            -      return true;
            -   }
            -
            -   error_code = contacts_record_get_child_record_at_p(r_contact, _contacts_contact.number, 0, &r_number);
            -
            -   error_code = contacts_record_get_str(r_number, _contacts_number.number, number);
            -
            -   return true;
            -}
            -
            -

            To get a second number, change the third parameter (contacts_record_get_child_record_at_p) from 0 to 1.

        • - - -
        • An image can be obtained directly from the parent record:

          - -
          -static bool _get_contact_image(contacts_record_h r_contact, char **image_path)
          -{
          -   int error_code;
          -
          -   error_code = contacts_record_get_str(r_contact, _contacts_contact.image_thumbnail_path, image_path);
          -
          -   dlog_print(DLOG_ERROR, LOG_TAG, "Thumb path: \'%s\'", *image_path);
          -
          -   return true;
          -}
          -
        • - -
        • Get the first name as the last name:

          - -
          -static bool _get_contact_first(contacts_record_h r_contact, char **first)
          -{
          -   contacts_record_h r_name;
          -   int error_code;
          -
          -   error_code = contacts_record_get_child_record_at_p(r_contact, _contacts_contact.name, 0, &r_name);
          -
          -   error_code = contacts_record_get_str(r_name, _contacts_name.first, first);
          -}
          -
        -
    10. - -
    11. Clean up. -
      1. Destroy the contacts_list_h list.

        -

        When the access to the database is no longer needed, disconnect from the service using the contact_disconnect() function.

        - -
        -error_code = contacts_list_destroy(list, true);
        -
        -error_code = contacts_disconnect();
        -
      2. - -
      3. Destroy all other used handles as well:

        - -
        -contacts_query_destroy(query); // If query has been used
        -contacts_filter_destroy(filter); // If filter has been used
        -
      -
    12. -
    - -

    Handling Lists

    - -

    To access multiple records using lists and contact property filters, and to sort records:

    - -
      -
    1. Get a record list. -
      • To get all records: -

        The following function retrieves all records and returns the result list. After all operations, the list must be released with the contacts_list_destroy() function.

        - -
        -contacts_list_h list = NULL;
        -
        -contacts_db_get_all_records(_contacts_contact._uri, 0, 0, &list);
        -
        -
      • -
      • To filter and get specific records: -
          -
        1. Create a query for a list. -

          To filter or sort records, you need a record list and query:

          - -
          -contacts_list_h list = NULL;
          -contacts_query_h query = NULL;
          -
          -contacts_query_create(_contacts_name._uri, &query);
          -
          -
        2. - -
        3. Create a filter for the query. -

          Before getting contacts, filter the list. It is possible to filter by various parameters, such as the name view.

          - -
          -contacts_filter_h filter = NULL;
          -
          -contacts_filter_create (_contacts_name._uri, &filter);
          -
          - -

          The first parameter defines in which view to place the filter. To filter by the first and last name, use the _contacts_name filter. The first parameter of the contacts_query_create() function must be the same parameter as in the filter to be appended. For more information on views, see the View/Property tables.

        4. - -
        5. Add a condition, such as the following where only contacts beginning with "Za" are shown:

          - -
          -contacts_filter_add_str(filter, _contacts_name.last_name, CONTACTS_MATCH_CONTAINS, "Za");
          -
          - -

          To receive contacts which starts by a given string, the CONTACTS_MATCH_CONTAINS parameter has to be set. Use the parameter if you need to get records which contain the given string anywhere.

        6. - -
        7. To add more conditions, add operators between them. In this case, define the operator between conditions first:

          - -
          -contacts_filter_add_operator(filter, CONTACTS_FILTER_OPERATOR_AND);
          -
          - -

          After that you can add another condition. If you need to use a logic expression "C1 AND (C2 OR C3)", conditions 2 and 3 must be in another filter to have logical brackets. The following example shows a filter that passes through contacts with a first name starting with "Ada" or "Igo":

          - -
          -contacts_filter_h n_filter = NULL;
          -contacts_filter_create (_contacts_name._uri, &n_filter);
          -contacts_filter_add_str(n_filter, _contacts_name.first_name, CONTACTS_MATCH_STARTSWITH, "Ada");
          -contacts_filter_add_operator(n_filter, CONTACTS_FILTER_OPERATOR_OR);
          -contacts_filter_add_str(n_filter, _contacts_name.first_name, CONTACTS_MATCH_STARTSWITH, "Igo”");
          -
        8. - -
        9. To add an extra filter to a parent filter:

          - -
          -contacts_filter_add_filter(filter, n_filter);
          -
          - -

          The parent filter passes through contacts with a last name beginning with "Za" and a first name starting with "Ada" or "Igo".

        10. -
        11. Connect a filter with query:

          - -
          -contacts_query_set_filter(query, filter);
          -
      -
    2. - -
    3. Sort a record list. -

      To sort records by any of its view details:

      - -
      -contacts_query_set_sort(query, _contacts_name.first, true);
      -
      - -

      The first parameter is the query to be filtered, the second is the property to sort, and the last sets the ascending order.

      -
    4. - -
    5. Set a projection to a list. -

      A projection allows you to query the data for specific properties of a record. It can reduce latency in case of a large database.

      -

      To set the projection, use the contacts_query_set_projection() function. The following example limits the properties from the previous steps to the first and last name:

      - -
      -unsigned my_projection[] = {_contacts_name.contact_id, _contacts_name.first, _contacts_name.last}
      -contacts_query_set_projection(query, my_projection, sizeof(my_projection)/sizeof(int));
      -
      - -

      After filtering, such as getting numbers, there can be several records which differ only in a few detail types. When setting the projection, the results can contain identical records. To avoid these situations, use the distinction function:

      - -
      -contacts_query_set_distinct(query, true);
      -
      -
    6. - -
    7. Get the record list with a query. -

      Get the list with the query:

      - -
      -contacts_db_get_records_with_query(query, 0, 0, &list);
      -
      - -

      The third parameter refers to limiting results. If 0 is passed, there are no limits. Release the list after all the operations.

      -
    8. - -
    9. Iterate on the list and read the records. -

      The contacts_list_get_current_record_p() function retrieves a record from the contacts list. The current default record is the first record.

      - -

      To iterate on a list, use the contacts_list_prev(), contacts_list_next(), contacts_list_first(), and contacts_list_last() functions.

      - - - - - - - - - - -
      Note
      Some functions have the _p postfix. It means that the returned value must not be freed by the application, as it is a pointer to data in an existing record.
      - -

      To read records:

      - -
      • To get only a few details: - -
        -contacts_record_h record;
        -
        -while (contacts_list_get_current_record_p(list, &record) == 0)
        -{
        -   // Get details
        -   char * disp_name;
        -   contacts_record_get_str(record, _contacts_contact.display_name, &disp_name);
        -   free(disp_name);
        -   error_code = contacts_list_next(list);
        -}
        -
      • - -
      • To get more details, use the following example, where the obtained records are passed to the _create_gl_data() function for further processing:

        - -
        -contacts_record_h record;
        -contact_gl_data_t *gldata = NULL;
        -
        -while (contacts_list_get_current_record_p(list, &record) == 0)
        -{
        -   gldata = _create_gl_data(record);
        -
        -   error_code = contacts_list_next(list);
        -}
        -
      • - -
      • The previous examples work if you use the default (_contacts_contact) view. If you use filtering in another view as shown in the filter example, and you want to use this structure (change view to default), use the following code:

        - -
        -contacts_record_h record;
        -contact_gl_data_t *gldata = NULL;
        -
        -while (contacts_list_get_current_record_p(list, &record) == 0)
        -{
        -   int record_id;
        -   contacts_record_h c_record;
        -   contacts_record_get_int(record, _contacts_name._uri, &contact_id);
        -   contacts_db_get_record(_contacts_contact._uri, contact_id, &c_record);
        -   gldata = _create_gl_data(c_record);
        -
        -   error_code = contacts_list_next(list);
        -}
        -
        - -

        This way it is possible to switch to the default view from another view (in a similar manner to the above example _contacts_name).

      -
    10. - -
    11. Insert the list to the database. -

      You can insert a whole list to the database. This can be useful when you have several records to create and you want to insert them all at once.

      - -
        -
      1. If you have a list, use it or create a new one: - -
        -contacts_list_h list;
        -contacts_list_create(&list);
        -
        -
      2. - -
      3. Add records to the list: - -
        -contacts_list_add (list, record);
        -
        -
      4. - -
      5. Insert the list into the database: - -
        -int *ids = NULL;
        -unsigned int count = 0;
        -contacts_db_insert_records(list, &ids, &count);
        -dlog_print(DLOG_DEBUG, LOG_TAG, "%d records inserted", count);
        -free(ids);
        -
        - -

        This inserts the entire list to the database and gets the IDs of the inserted records.

        -
      6. - -
      7. Destroy the list: - -
        -contacts_list_destroy(list, true);
        -
        -
      8. -
      -
    12. -
    - -

    Deleting Records

    - -

    To delete records from the contact database, you need to know their ID:

    - -
    -int id;
    -// Get id
    -int error = contacts_db_delete_record(_contacts_contact._uri, id);
    -
    - -

    If you only have the record handle, get the ID first:

    - -
    -contacts_record_get_int(record, _contacts_contact.id, &id);
    -
    - -

    Linking Persons

    - -

    To link persons (a useful joining method if there are several contacts assigned to one person):

    - -
      -
    1. Link a person to another person. -

      To link persons with the contacts_person_link_person() function, you need the person ID. To get the person ID, use the contacts_record_get_int() function.

      - -
      -int first_person_id;
      -contacts_record h record1;
      -// Get the first record
      -int error_code = contacts_record_get_int(record1, _contacts_contact.person_id, &first_person_id);
      -
      -contacts_record h record2;
      -// Get the second record
      -error_code = contacts_record_get_int(record2, _contacts_contact.person_id, &second_person_id);
      -
      -contacts_person_link_person(first_person_id, second_person_id);
      -
      - -

      This links the 2 contacts available through record handles.

      -
    2. - -
    3. Set the default properties. -

      Set the default values from one of the linked contacts with the contacts_person_set_default_property() function. The first parameter determines the detail to be set using the contacts_person_property_e enum.

      - -

      To set a default number from one of the persons, you have to know its ID. Get the detail ID using the contacts_record_get_child_record_at_p() function, because you need to get the value from the _contact_number view.

      - -
      -contacts_record_h record;
      -int record_number = -1;
      -// Get the record handle
      -contacts_record_h record_number;
      -error_code = contacts_record_get_child_record_at_p(record, _contacts_contact.number, 0, &record_number);
      -
      -error_code = contacts_record_get_int(record_number, _contacts_number.id, &number_id);
      -
      -error_code = contacts_record_destroy(record_number, true);
      -
      -// Use the record_number variable
      -error_code = contacts_person_set_default_property(CONTACTS_PERSON_PROPERTY_NUMBER, person_id, number_id);
      -
      -
    4. - -
    5. Get default properties. -

      Get the default property values of a person with the contacts_person_get_default_property() function:

      - -
      1. Get the ID of the default email details:

        - -
        -int person_email_number;
        -error_code = contacts_person_get_default_property (CONTACTS_PERSON_PROPERTY_EMAIL, person_id, &person_email_number);
        -
      2. - -
      3. Get the default email:

        - -
        -int person_email_detail_number;
        -error_code = contacts_person_get_default_property (CONTACTS_PERSON_PROPERTY_EMAIL, person_id, &person_email_number);
        -
        -contacts_record_h email_record;
        -error_code = contacts_db_get_record(_contacts_email._uri, person_email_detail_number, &email_record);
        -char * default_email;
        -
        -error_code = contacts_record_get_str_p(email_record, _contacts_email.email, &default_email);
        -
        -// Use default_email
        -
        -error_code = contacts_record_destroy(email_record, true);
        -
      -
    6. - -
    7. Unlink persons. -

      To unlink a contact using the contacts_person_unlink_contact() function:

      - -
      1. If you have the record handle, get the contact ID:

        - -
        -int person_id;
        -contacts_record_get_int(record, _contacts_contact.id, &person_id);
        -
      2. - -
      3. Unlink a contact from another and get its ID:

        - -
        -int unlinked_person_id;
        -int contacts_person_unlink_contact(person_id,
        -                                   contact_id,
        -                                   &unlinked_person_id)
        -
      -
    8. -
    - -

    Managing Contact Settings

    - -

    To manage the display settings of contacts:

    - -
      -
    1. Get the display and sorting order. -

      Check the current display order (the order in which the names are displayed) using the contacts_setting_get_name_display_order() function, and the sorting order using the contacts_setting_get_name_sorting_order() function:

      - -
      -contacts_name_display_order_e display_order;
      -contacts_setting_get_name_display_order (&display_order);
      -// Now you have the display order
      -sprintf("Display order: %s", display_order==CONTACTS_NAME_DISPLAY_ORDER_FIRSTLAST?"CONTACTS_NAME_DISPLAY_ORDER_FIRSTLAST":"CONTACTS_NAME_DISPLAY_ORDER_LASTFIRST");
      -
      -contacts_name_sorting_order_e sorting_order;
      -contacts_setting_get_name_sorting_order (&sorting_order);
      -// Now you have the sorting order
      -sprintf("Sorting order: %s", sorting_order==CONTACTS_NAME_SORTING_ORDER_FIRSTLAST?"CONTACTS_NAME_SORTING_ORDER_FIRSTLAST":"CONTACTS_NAME_SORTING_ORDER_LASTFIRST");
      -
      -
    2. - -
    3. Change the display and sorting orders. -

      To change the display and sorting orders, use the contacts_setting_set_name_display_order() and contacts_setting_set_name_sorting_order() functions:

      - -
      -contacts_setting_set_name_display_order (CONTACTS_NAME_DISPLAY_ORDER_FIRSTLAST);
      -
      -contacts_setting_set_name_sorting_order (CONTACTS_NAME_SORTING_ORDER_FIRSTLAST);
      -
      -
    4. - -
    5. Track the order changes with callbacks. -

      To track changes in the display and sorting orders:

      -
      1. Register callbacks with the contacts_setting_add_name_display_order_changed_cb() and contacts_setting_add_name_sorting_order_changed_cb() functions.
      2. -
      3. Define the callbacks themselves: -
        -static void display_changed_cb(contacts_name_display_order_e name_display_order, void *user_data)
        -{
        -   dlog_print(DLOG_DEBUG, LOG_TAG, "changed display order: %s", name_display_order==CONTACTS_NAME_DISPLAY_ORDER_FIRSTLAST?"CONTACTS_NAME_DISPLAY_ORDER_FIRSTLAST":"CONTACTS_NAME_DISPLAY_ORDER_LASTFIRST");
        -}
        -
        -static void sorting_changed_cb(contacts_name_sorting_order_e name_display_order, void *user_data)
        -{
        -   dlog_print(DLOG_DEBUG, LOG_TAG, "changed sorting order: %s", name_display_order==CONTACTS_NAME_SORTING_ORDER_FIRSTLAST?"CONTACTS_NAME_SORTING_ORDER_FIRSTLAST":"CONTACTS_NAME_SORTING_ORDER_LASTFIRST");
        -}
        -
        -

        The above examples cause a message to be printed when the order changes. To track the changes, write a timeout function after setting the callback.

      4. -
      5. Unregister the callbacks when they are no longer needed using the contacts_setting_remove_name_display_order_changed_cb() and contacts_setting_remove_name_sorting_order_changed_cb() functions.
      - -
    6. -
    - -

    Managing Contacts on the SIM Card

    - -

    To check whether the SIM card is initialized and then import contacts from the SIM card:

    -
      -
    1. Check whether the SIM card is initialized. -

      Before using any SIM card methods, ensure that the SIM card initialization is complete:

      - -
      -bool completed = false;
      -contacts_sim_get_initialization_status(&completed);
      -dlog_print(DLOG_DEBUG, LOG_TAG, "SIM %s completed", completed?"":"not ");
      -
    2. - -
    3. Import all contacts from the SIM card. -

      When the contacts from the SIM card are available, import them:

      - -
      -int err = contacts_sim_import_all_contacts();
      -
      -
    4. - -
    - -

    Importing from vCard

    - -

    To import contacts from all vCard files from a specified directory:

    - -
      -
    • Get contact records from a stream. -

      To receive a records list from the vCard stream, use the contacts_vcard_parse_to_contacts() function. Afterwards, the received list is ready to use and you can perform the iteration on the list.

      - -

      The following example uses the stream in the vCard format and gets the records from the received list:

      - -
      -char * vcard_stream;
      -// Get vCard stream
      -contacts_list_h contacts_list;
      -int err = contacts_vcard_parse_to_contacts(vcard_stream, contacts_list);
      -
      -while (contacts_list_get_current_record_p(list_import, &record) == 0) 
      -{
      -   // Get next records from file
      -   err = contacts_list_next(list_import);
      -}
      -err = contacts_list_destroy(list_import, true);
      -
      - -

      You can also use the contacts_vcard_parse_to_contact_foreach() function. With this function, you have to get the file content manually, and it needs a callback:

      - -
      -bool contacts_vcard_cb(contacts_record_h record, void *user_data)
      -{
      -   // Here you have a record
      -   return true;
      -}
      -
      - -

      The callback is called for each record from a vCard file. The iteration continues as long as the callback returns true.

      - -

      To check how many records are contained in a vCard file, use the contacts_vcard_get_entity_count() function.

      - -
    • - -
    • Import the vCard stream. -
      • Get all the files with a .vcf extension from the directory. It can be done through dirent structures available in the <dirent.h> header. The following example gets the path to every file in a directory:

        - -
        -int internal_storage_id;
        -char *vcf_path = NULL;
        -
        -static bool 
        -storage_cb(int storage_id, storage_type_e type, storage_state_e state, const char *path, void *user_data)
        -{
        -   if (type == STORAGE_TYPE_INTERNAL)
        -   {
        -      internal_storage_id = storage_id;
        -
        -      return false;
        -   }
        -
        -   return true;
        -}
        -
        -void 
        -_get_storage_path()
        -{
        -   int error_code = 0;
        -   char *path = NULL;
        -
        -   error_code = storage_foreach_device_supported(storage_cb, NULL);
        -   error_code = storage_get_directory(internal_storage_id, STORAGE_DIRECTORY_DOWNLOADS, &path);
        -   if (error_code != STORAGE_ERROR_NONE)
        -   {
        -      vcf_path = strdup(path);
        -      free(path);
        -   }
        -}
        -
        -void 
        -_import_vcard()
        -{
        -   int path_len = 0;
        -
        -   DIR *dir = opendir(vcf_path);
        -   struct dirent *pDirent = NULL;
        -   if (NULL == dir)
        -   {
        -      free(vcf_path);
        -
        -      return;
        -   }
        -
        -   while ((pDirent = readdir(dir)) != NULL)
        -   {
        -      if (pDirent->d_type != DT_REG)
        -         continue;
        -      char *extension = strrchr(pDirent->d_name, '.');
        -      if (!extension || strcmp(extension, ".vcf"))
        -         continue;
        -      char * filepath = malloc(strlen(vcf_path)+strlen(pDirent->d_name)+4);
        -      sprintf(filepath, "%s/%s", vcf_path, pDirent->d_name);
        -        
        -      // Full path to file available through filepath string
        -
        -      free(filepath);
        -   }
        -}
        -
      • - -
      • If you use the contacts_vcard_parse_to_contacts() function, you need to get the file stream manually. The following example shows how to get a records list from a file:

        - -
        -FILE *fp = fopen(filepath, "r");
        -fseek(fp, 0, 2);
        -int bufsize = ftell(fp);
        -rewind(fp);
        -if (bufsize < 1)
        -   return 1;
        -char * vcard_stream = malloc(sizeof(char) * (bufsize));
        -memset(vcard_stream, '\0', sizeof(vcard_stream));
        -if (fp != NULL) 
        -{
        -   char str[200];
        -   while(fgets(str, 200, fp) != NULL)
        -      sprintf(vcard_stream+strlen(vcard_stream), "%s", str);
        -   fclose(fp); 
        -} 
        -else
        -   // Error handling
        -int err = contacts_vcard_parse_to_contacts(vcard_stream, contacts_list);
        -free(vcard_stream);
        -
      • - -
      • You can also use the contacts_vcard_parse_to_contact_foreach() function. It requires a callback and retrieves the file path instead of a file stream:

        - -
        -bool contacts_vcard_cb(contacts_record_h record, void *user_data)
        -{
        -   // Here you have a record
        -   return true;
        -}
        -
        -err = contacts_vcard_parse_to_contact_foreach (filepath, contacts_vcard_cb, NULL);
        -
      • - -
      • Add a record in a callback function:

        - -
        -int id = -1;
        -err = contacts_db_insert_record(record, &id);
        -
      - -

      The following example represents the full code of the previous step:

      - -
      -char []folder = "/path/";
      -contacts_list_h list_import;
      -contacts_record_h record;
      -err = contacts_vcard_parse_to_contacts(content, &list_import);
      -
      -while (contacts_list_get_current_record_p(list_import, &record) == 0) 
      -{
      -   int id = -1;
      -   err = contacts_db_insert_record(record, &id); // Add to list
      -
      -   contacts_list_next(list_import);
      -}
      -
      -DIR *dir = opendir(folder);
      -struct dirent *pDirent = NULL;
      -if (dir) 
      -{
      -   while ((pDirent = readdir(dir)) != NULL) 
      -   {
      -      if (pDirent->d_type != DT_REG)
      -         continue;
      -
      -      char *exte = strrchr(pDirent->d_name, '.');
      -      if (!exte || strcmp(exte, ".vcf"))
      -         continue;
      -      dlog_print(DLOG_DEBUG, LOG_TAG, "file %s", pDirent->d_name);
      -
      -      char * file_path = malloc(strlen(folder)+strlen(pDirent->d_name)+4);
      -      sprintf(file_path, "%s/%s", folder, pDirent->d_name);
      -      int count;
      -      contacts_vcard_get_entity_count(file_path, &count);
      -      // Number of records in file: count
      -      if (count < 1)
      -         continue;
      -
      -      FILE * fp = fopen(file_path, "r");
      -      if (fseek(fp, 0, 2) != 0)
      -         // Error handling
      -      int bufsize = ftell(fp);
      -      rewind(fp);
      -      dlog_print(DLOG_DEBUG, LOG_TAG, "file size: %i", bufsize); 
      -      if (bufsize < 1)
      -         return 1;
      -      char * vcard_stream = malloc(sizeof(char) * (bufsize));
      -      memset(vcard_stream, '\0', sizeof(vcard_stream));
      -      if (fp != NULL) 
      -      {
      -         char str[150];
      -         while(fgets(str, 150, fp) != NULL)
      -            sprintf(vcard_stream+strlen(vcard_stream), "%s", str);
      -         fclose(fp);
      -      } 
      -      else
      -         return 1;
      -      // Import the contacts
      -      contacts_list_h list_import;
      -      err = contacts_vcard_parse_to_contacts(vcard_stream, &list_import);
      -      if (err != 0)
      -         dlog_print(DLOG_ERROR, LOG_TAG, "contacts_vcard_parse_to_contacts failed: %d", err);
      -      free(vcard_stream);
      -      while (contacts_list_get_current_record_p(list_import, &record) == 0) 
      -      {
      -         int id = -1;
      -         err = contacts_db_insert_record(record, &id); // Add to list
      -         if (err != 0)
      -            dlog_print(DLOG_ERROR, LOG_TAG, "contacts_list_add failed");
      -         err = contacts_list_next(list_import);
      -      }
      -      err = contacts_list_destroy(list_import, true);
      -      if (err != 0)
      -      {
      -         dlog_print(DLOG_ERROR, LOG_TAG, "contacts_list_destroy failed: %d", err);
      -      }
      -      free (file_path);
      -   }
      -   closedir(dir);
      -}
      -
      -
    • -
    - -

    Exporting to vCard

    - -

    To export your contacts to a vCard file:

    - -
      -
    1. Export contacts to a file. -
      • To export a contact from the _contacts_contact view to the vCard format, use the contacts_vcard_make_from_contact() function.

      • - - -
      • To export details from the _contacts_person view, use the contacts_vcard_make_from_person() function. If you need to export details from the _contacts_my_profile view, use the contacts_vcard_make_from_my_profile() function.

      - -

      The following example uses the _contacts_contact view, but the use of the other views is the same:

      - -
      -contacts_record_h contact;
      -// Get record to contacts_record_h
      -char *vcard_stream;
      -int err = contacts_vcard_make_from_contact(contact, &vcard_stream);
      -
      -// Stream in vCard format is now in vcard_stream
      -free(vcard_stream);
      -
    2. - -
    3. Write to a file:

      - -
      -FILE * file = fopen("/path/contacts.vcf", "w");
      -fwrite(vcard_stream, 1, strlen(vcard_stream), file);
      -fclose(file);
      -
    - - -

    The following example shows how to get all records from a database and put them into a single file.

    -

    Get the list of all records using the contacts_db_get_all_records() function and the current records using the contacts_list_get_current_record_p() function. Get the vCard stream and write to the file in a while loop:

    - -
    -char file_path[] = "/path/contacts.vcf";
    -contacts_list_h list = NULL;
    -err = contacts_db_get_all_records(_contacts_contact._uri, 0, 0, &list);
    -
    -contacts_record_h record;
    -FILE * file = fopen(file_path, "w");
    -
    -while (contacts_list_get_current_record_p(list, &record) == 0) 
    -{
    -   err = contacts_vcard_make_from_contact(record, &vcard_stream);
    -   // Save to file
    -   fwrite(vcard_stream, 1, strlen(vcard_stream), file);
    -   free(vcard_stream);
    -   err = contacts_list_next(list);
    -}
    -fclose(file);
    -contacts_list_destroy(list, true);
    -
    - - - - -
    - -Go to top - - - - - - + + + + + + + + + + + + + Contacts: Managing Contacts and Groups, and Accessing the Contact Database + + + + + +
    + +

    Contacts: Managing Contacts and Groups, and Accessing the Contact Database

    + + +

    This tutorial demonstrates how you can manage contacts and groups, and import them to or export them from the vCard format.

    + + + + + + + + + + +
    Note
    This feature is supported in mobile applications only.
    + +

    Warm-up

    +

    Become familiar with the Contacts API basics by learning about:

    + +

    Follow-up

    +

    Once we have learned the basics of the Contacts API, we can now move on to more advanced tasks, including:

    + + + +

    Initializing Contacts

    + +

    To start with the Contact Service:

    +
    1. +

      To use the functions and data types of the Contacts API, include the <contacts.h> header file in your application:

      +
      +#include <contacts.h>
      +
    2. +
    3. Most of the API functions return error codes, therefore define at the beginning of your code the int type, which is used to store error codes. Each time when a function returns error codes, verify the result of the operation.
    4. +
    5. Call the contacts_connect() function, which connects your application with the Contact Service. Without this function, you cannot get access to the Contacts database.

      +
      int error_code;
      +error_code = contacts_connect();
      +
    6. +
    7. When the Contacts APIs are not needed anymore, you have to disconnect from the service using the contacts_disconnect() function: +
      error_code = contacts_disconnect();
      +
    + +

    Creating a Contact

    + +

    Before you insert a record, you need to create a record handle. To create it and assign a new record:

    +
    contacts_record_h contact;
    +
    +error_code = contacts_record_create(_contacts_contact._uri, &contact);
    +
    + +

    The first argument determines the type of the created record. Use _contacts_contact._uri to create contact type records.

    +

    This record, however, contains no additional information, like a name or phone number. To add them, you must set contact properties by creating additional records and setting them as child records of the contact record. Note that records created this way are objects in the memory, with contacts_record_h type variables as their handles. Changes made to these objects are not reflected in the database until your explicit request, using contacts_db_insert_record() or contacts_db_update_record().

    + +

    Setting Contact Properties

    + +

    To set the contact name, birthday, and phone number:

    +
    1. Add the contact name. +
      1. Create a name record: +
        contacts_record_h name;
        +
        +error_code = contacts_record_create(_contacts_name._uri, &name);
        +
      2. +
      3. To set the first name, set the value of a string type property identified by _contacts_name.first. +
        error_code = contacts_record_set_str(name, _contacts_name.first, "John");
        +
        +

        The contacts_record_set_str() function is used to set string field values. There are other similar functions for other types, such as integer and double. The name variable is the record handle created above. The second argument – _contacts_name.first – is the property identifier, and the third argument is the value to be assigned.

      4. +
      5. Set the last name similarly: +
        error_code = contacts_record_set_str(name, _contacts_name.last, "Smith");
        +
        +
      6. +
      7. Associate the name record with the contact record, by setting the name as the contact's child record. In this example, it is achieved using contacts_record_add_child_record(). +
        error_code = contacts_record_add_child_record(contact, _contacts_contact.name, name);
        +
        +

        The second argument (_contacts_contact.name) is the parent property to which the child record is assigned. See _contacts_contact view description in the Contacts API. In the API, the name property is listed as one of the record type properties, which means that other records can be assigned to this property as child records ("single" means that only 1 _contacts_name type child record is allowed). The required type of the child record is specified in the API.

    2. +
    3. Add an image. +
      1. Create an image record: +
        contacts_record_h image;
        +
        +error_code = contacts_record_create(_contacts_image._uri, &image);
        +
      2. +
      3. To set the image, set the value of a string type property identified by _contacts_image.path: +
        +char *resource_path = app_get_resource_path();
        +char caller_id_path[1024];
        +snprintf(caller_id_path, sizeof(caller_id_path), "%s/caller_id.jpg", resource_path);
        +free(resource_path);
        +error_code = contacts_record_set_str(image, _contacts_image.path, caller_id_path);
        +
      4. +
      5. Set the image record as the contact's child record: +
        error_code = contacts_record_add_child_record(contact, _contacts_contact.image, image);
        +
    4. +
    5. Add an event. +

      You can add a birthday event associated with the contact. An event contains the date and the event type, among other properties.

      +
      1. Create an event record: +
        contacts_record_h event;
        +
        +error_code = contacts_record_create(_contacts_event._uri, &event);
        +
      2. +
      3. Set the event date. The date is an integer, equal to year * 10000 + month * 100 + day. +
        int year = 1990;
        +int month = 5;
        +int day = 21;
        +int int_date = year * 10000 + month * 100 + day;
        +
        +error_code = contacts_record_set_int(event, _contacts_event.date, int_date);
        +
      4. +
      5. Set the event type to birthday. For available types, see contacts_event_type_e enumeration. +
        error_code = contacts_record_set_int(event, _contacts_event.type, CONTACTS_EVENT_TYPE_BIRTH);
        +
      6. +
      7. If the type is CONTACTS_EVENT_TYPE_CUSTOM, you can set a custom label (see _contacts_event view). +
        error_code = contacts_record_set_int(event, _contacts_event.type, CONTACTS_EVENT_TYPE_CUSTOM);
        +
        +error_code = contacts_record_set_str(event, _contacts_event.label, "Event description");
        +
      8. +
      9. Set the event record as the contact's child record: +
        error_code = contacts_record_add_child_record(contact, _contacts_contact.event, event);
        +
    6. +
    7. Add a phone number. +

      The phone number is added to a parent record using an alternative method.

      +
      1. Create a phone number record and set the number property: +
        contacts_record_h number;
        +
        +error_code = contacts_record_create(_contacts_number._uri, &number);
        +
        +error_code = contacts_record_set_str(number, _contacts_number.number, "+8210-1234-5678");
        +
      2. +
      3. Set the number record as the contact's child record: +
        error_code = contacts_record_add_child_record(contact, _contacts_contact.number, number);
        +
    + +

    Inserting a Contact to the Database

    + +

    To insert a contact:

    + +
    1. When the data is set for the contact and name records, you can insert them into the database. When you insert a parent record, all child records added to it using contacts_record_add_child_record() are inserted automatically.

      + +

      Insert a contact record:

      + +
      int id = -1;
      +
      +error_code = contacts_db_insert_record(contact, &id);
      +
    2. +
    3. When the records are in the database, the objects representing them in the memory are no longer needed and must be destroyed. +
      contacts_record_destroy(contact, true);
      +

      If the second parameter is true, child records of the given record (objects representing them in the memory) are also destroyed. This does not depend on the way the child records were added.

    + +

    Getting Contacts

    + +

    To retrieve contact records:

    + +
    1. A person is an aggregation of one or more contacts associated with the same person. The person is created automatically when inserting a contact record. To use the contact information in your application, you must learn to print basic person information.

      + +

      To get a single person record:

      +
      1. +

        Use the contacts_db_get_record() function with the appropriate person_id:

        +
        contacts_record_h person  = NULL;
        +const int person_id = ... // Acquire person ID
        +int error_code;
        +
        +error_code = contacts_db_get_record(_contacts_person._uri, person_id, &person);
        +
      2. +
      3. When you no longer need the person record, destroy the used structures: +
        +contacts_record_destroy(speeddial, true);
        +
    2. + +
    3. To get the total person record list: +
      1. Use the contacts_db_get_all_records() function:

        +
        contacts_list_h list = NULL;
        +
        +error_code = contacts_db_get_all_records(_contacts_person._uri, 0, 0, &list);
        +
      2. +
      3. Iterate the list and read the records.

        + + + + + + + + + + +
        Note
        Some functions have the _p postfix. It means that the returned value must not be freed by the application, as it is a pointer to the data in an existing record.
        + +
        1. To get the records from the list, use the contacts_list_get_current_record_p(), and contacts_list_next() or contacts_list_prev() functions. Get the details of each record in the loop.

          + +
          contacts_record_h record;
          +while (contacts_list_get_current_record_p(list, &record) == CONTACTS_ERROR_NONE)
          +{
          +   char* display_name;
          +   error_code = contacts_record_get_str_p(record, _contacts_person.display_name, &display_name);
          +   dlog_print(DLOG_DEBUG, LOG_TAG, "display_name: %s", display_name);
          +
          +   error_code = contacts_list_next(list);
          +}
        2. +
        3. If you want to get more details of each record, use the contacts_gl_person_data_t structure like below: +
          contacts_gl_person_data_t *gl_person_data = NULL;
          +contacts_record_h record;
          +while (contacts_list_get_current_record_p(list, &record) == CONTACTS_ERROR_NONE)
          +{
          +   gl_person_data = _create_gl_person_data(record);
          +   // You can get, for example, display name:
          +   // gl_person_data->display_name
          +
          +   _free_gl_person_data(gl_person_data);
          +   error_code = contacts_list_next(list);
          +}
        4. +
        5. The memory for the record data is allocated, and the data is copied from the record by the functions listed further on in this document. +
          typedef struct _contacts_gl_person_data
          +{
          +   int id;
          +   char *display_name;
          +   char *default_phone_number;
          +   contacts_list_h associated_contacts;
          +} contacts_gl_person_data_t;
          +
          +static void _free_gl_person_data(contacts_gl_person_data_t *gl_person_data)
          +{
          +   if (NULL == gl_person_data)
          +      return;
          +   free(gl_person_data->display_name);
          +   free(gl_person_data->default_phone_number);
          +   contacts_list_destroy(gl_person_data->associated_contacts, true);
          +   free(gl_person_data);
          +}
          +
          +static contacts_gl_person_data_t* _create_gl_person_data(contacts_record_h record)
          +{
          +   contacts_gl_person_data_t *gl_person_data;
          +
          +   gl_person_data = malloc(sizeof(contacts_gl_person_data_t));
          +   memset(gl_person_data, 0x0, sizeof(contacts_gl_person_data_t));
          +   if (contacts_record_get_int(record, _contacts_person.id, &gl_person_data->id) != CONTACTS_ERROR_NONE)
          +   {
          +      dlog_print(DLOG_ERROR, LOG_TAG, "get person id failed ");
          +      _free_gl_person_data(gl_person_data);
          +
          +      return NULL;
          +   }
          +   if (false == _get_display_name(record, &gl_person_data->display_name))
          +   {
          +      dlog_print(DLOG_ERROR, LOG_TAG, "_get_display_name() failed ");
          +      _free_gl_person_data(gl_person_data);
          +
          +      return NULL;
          +   }
          +   if (false == _get_default_phone_number(record, &gl_person_data->default_phone_number))
          +   {
          +      dlog_print(DLOG_ERROR, LOG_TAG, "_get_default_phone_number() failed ");
          +      _free_gl_person_data(gl_person_data);
          +
          +      return NULL;
          +   }
          +   if (false == _get_associated_contacts(record, &gl_person_data->associated_contacts))
          +   {
          +      dlog_print(DLOG_ERROR, LOG_TAG, "_get_associated_contacts() failed ");
          +      _free_gl_person_data(gl_person_data);
          +
          +      return NULL;
          +   }
          +   _print_phone_numbers(gl_person_data->associated_contacts);
          +   _print_events(gl_person_data->associated_contacts);
          +
          +   return gl_person_data;
          +}
        6. +
        7. Get person details. +
            +
          • Get the display name. +

            Assuming that you have the person record handle (contacts_record_h), you can access the display_name property. You can read the display name property and print it:

            +
            static bool _get_display_name(contacts_record_h record, char **display_name)
            +{
            +   int error_code;
            +
            +   error_code = contacts_record_get_str(record, _contacts_person.display_name, display_name);
            +   dlog_print(DLOG_DEBUG, LOG_TAG, "display name: %s", *display_name);
            +   if (error_code != CONTACTS_ERROR_NONE)
            +      return false;
            +
            +   return true;
            +}
          • +
          • Get associated contacts. +

            You can get the associated contacts of a person by query. In this example, you get the associated contact records.

            +
            static bool _get_associated_contacts(contacts_record_h record, contacts_list_h *associated_contacts)
            +{
            +   int error_code;
            +   int person_id;
            +   contacts_query_h query = NULL;
            +   contacts_filter_h filter = NULL;
            +
            +   error_code = contacts_record_get_int(record, _contacts_person.id, &person_id);
            +
            +   error_code = CONTACTS_ERROR_NONE;
            +   error_code += contacts_query_create(_contacts_contact._uri, &query);
            +   error_code += contacts_filter_create(_contacts_contact._uri, &filter);
            +   error_code += contacts_filter_add_int(filter, _contacts_contact.person_id, CONTACTS_MATCH_EQUAL, person_id);
            +   error_code += contacts_query_set_filter(query, filter);
            +
            +   error_code += contacts_db_get_records_with_query(query, 0, 0, associated_contacts);
            +
            +   contacts_filter_destroy(filter);
            +   contacts_query_destroy(query);
            +
            +   if (error_code != CONTACTS_ERROR_NONE)
            +      return false;
            +
            +   return true;
            +}
          • +
          • Get phone numbers. +

            You can get the numbers of a person by iterating the contacts list. In this example, you get all the number records and print them.

            +
            static void _print_phone_numbers(contacts_list_h associated_contacts)
            +{
            +   int error_code;
            +   contacts_record_h contact;
            +   if (NULL == associated_contacts) 
            +   {
            +      dlog_print(DLOG_ERROR, LOG_TAG, "associated_contacts is NULL");
            +
            +      return;
            +   }
            +   while (contacts_list_get_current_record_p(associated_contacts, &contact) == CONTACTS_ERROR_NONE)
            +   {
            +      int i;
            +      unsigned int count = 0;
            +
            +      error_code = contacts_record_get_child_record_count(contact, _contacts_contact.number, &count);
            +      if (CONTACTS_ERROR_NONE != error_code) 
            +      {
            +         dlog_print(DLOG_ERROR, LOG_TAG, "contacts_record_get_child_record_count(%d)", error_code);
            +
            +         return;
            +      }
            +      for (i = 0; i < count; i++)
            +      {
            +         contacts_record_h number = NULL;
            +         error_code = contacts_record_get_child_record_at_p(contact, _contacts_contact.number, i, &number);
            +         if (error_code != CONTACTS_ERROR_NONE)
            +            continue;
            +
            +         int number_id;
            +         contacts_record_get_int(number, _contacts_number.id, &number_id);
            +         dlog_print(DLOG_DEBUG, LOG_TAG, "number id: %d", number_id);
            +
            +         char *number_str = NULL;
            +         contacts_record_get_str_p(number, _contacts_number.number, &number_str);
            +         dlog_print(DLOG_DEBUG, LOG_TAG, "number: %s", number_str);
            +      }
            +      error_code = contacts_list_next(associated_contacts);
            +   }
            +}
          • +
          • Get the default phone number. +

            If a contact has multiple phone numbers, one of them is defined as the default phone number. A person also has a default phone number. You can get the default phone number of a person by query. The Contact Service provides the _contacts_person_number view for getting the default phone number of a person. In the default phone number record, the is_primary_default property value is true. This example shows how to get the default phone number of a person by query.

            +
            static bool _get_default_phone_number(contacts_record_h record, char **default_phone_number)
            +{
            +   contacts_query_h query = NULL;
            +   contacts_filter_h filter = NULL;
            +   contacts_list_h list = NULL;
            +   contacts_record_h record_person_number = NULL;
            +   int person_id;
            +   int error_code = CONTACTS_ERROR_NONE;
            +
            +   error_code += contacts_record_get_int(record, _contacts_person.id, &person_id);
            +
            +   error_code += contacts_query_create(_contacts_person_number._uri, &query);
            +   error_code += contacts_filter_create(_contacts_person_number._uri, &filter);
            +   error_code += contacts_filter_add_bool(filter, _contacts_person_number.is_primary_default, true);
            +   error_code += contacts_query_set_filter(query, filter);
            +   error_code += contacts_db_get_records_with_query(query, 0, 0, &list);
            +   error_code += contacts_list_get_current_record_p(list, &record_person_number);
            +
            +   error_code += contacts_record_get_str(record_person_number, _contacts_person_number.number, default_phone_number);
            +
            +   contacts_list_destroy(list, true);
            +   contacts_filter_destroy(filter);
            +   contacts_query_destroy(query);
            +
            +   if (error_code != CONTACTS_ERROR_NONE)
            +      return false;
            +
            +   return true;
            +}
          • +
          • Get events. +

            You can get the events by iterating the contacts list.

            +
            static void _print_events(contacts_list_h associated_contacts)
            +{
            +   int error_code;
            +   contacts_record_h contact;
            +   if (NULL == associated_contacts) 
            +   {
            +      dlog_print(DLOG_ERROR, LOG_TAG, "associated_contacts is NULL");
            +
            +      return;
            +   }
            +   while (contacts_list_get_current_record_p(associated_contacts, &contact) == CONTACTS_ERROR_NONE)
            +   {
            +      int i;
            +      unsigned int count = 0;
            +
            +      error_code = contacts_record_get_child_record_count(contact, _contacts_contact.event, &count);
            +      if (CONTACTS_ERROR_NONE != error_code) 
            +      {
            +         dlog_print(DLOG_ERROR, LOG_TAG, "contacts_record_get_child_record_count(%d)", error_code);
            +
            +         return;
            +      }
            +      for (i = 0; i < count; i++)
            +      {
            +         contacts_record_h event = NULL;
            +         error_code = contacts_record_get_child_record_at_p(contact, _contacts_contact.event, i, &event);
            +         if (error_code != CONTACTS_ERROR_NONE)
            +            continue;
            +
            +         int event_id;
            +         contacts_record_get_int(event, _contacts_event.id, &event_id);
            +         dlog_print(DLOG_DEBUG, LOG_TAG, "event id: %d", event_id);
            +
            +         int date;
            +         contacts_record_get_int(event, _contacts_event.date, &date);
            +         dlog_print(DLOG_DEBUG, LOG_TAG, "event: %d", date);
            +      }
            +      error_code = contacts_list_next(associated_contacts);
            +   }
            +}
      4. +
      5. When you no longer need the person record, destroy the used structures: +
        +contacts_list_destroy(list, true);
        +
    4. +
    5. To get the filtered person record list: +
        +
      1. Use the contacts_db_get_records_with_query() function to filter the list with parameters: +
          +
        1. To get a person list with filtering, create a record list and a query: +
          +contacts_list_h list = NULL;
          +contacts_query_h query = NULL;
          +
          +error_code = contacts_query_create(_contacts_person._uri, &query);
          +
          +
        2. +
        3. Create a filter: +
          +contacts_filter_h filter = NULL;
          +
          +error_code = contacts_filter_create(_contacts_person._uri, &filter);
          +
          +
        4. +
        5. Add a condition, such as display_name: +
          +error_code = contacts_filter_add_str(filter, _contacts_person.display_name, CONTACTS_MATCH_CONTAINS, "John");
          +
          +
        6. +
        7. To add multiple conditions, you must define an operator between the conditions: +
          +error_code = contacts_filter_add_operator(filter, CONTACTS_FILTER_OPERATOR_AND);
          +
          +error_code = contacts_filter_add_bool(filter, _contacts_person.is_favorite, true);
          +
          +
        8. +
        9. Connect the query with the list: +
          +error_code = contacts_query_set_filter(query, filter);
          +
          +error_code = contacts_db_get_records_with_query(query, 0, 0, &list);
          +
          + +

          The third parameter refers to a limit of the results. If 0 is passed, there are no limits. Remember that after all operations, the list must be released.

          +
        10. +
        11. Free the filter and query: +
          +contacts_filter_destroy(filter);
          +contacts_query_destroy(query);
          +
          +
        12. +
        +
      2. +
      3. Iterate the list and read the records.
      4. +
      5. When you no longer need the person record, destroy the used structures: +
        +contacts_list_destroy(list, true);
        +
        +
      6. +
      +
    6. +
    7. To get the searched person record list: +
        +
      1. Use the contacts_db_search_records() function. +

        The Contact Service provides an API for the contact search. The contacts_db_search_records() function provides an easy way to find records based on a given keyword. The following example shows how to find the contact records which contain the "John" keyword:

        + +
        +contacts_list_h list = NULL;
        +
        +error_code = contacts_db_search_records(_contacts_person._uri, "John", 0, 0, &list);
        +
        +
      2. +
      3. Iterate the list and read the records.
      4. +
      5. When you no longer need the person record, destroy the used structures: +
        +contacts_list_destroy(list, true);
        +
        +
      6. +
      +
    8. +
    + +

    Updating a Contact

    + +

    To change the name, birthday, and phone number of an existing contact:

    +
    1. Get the contact. +

      To modify a record, you need to have a handle (contacts_record_h type variable) to a memory object representing the record in the database. One of the ways to acquire it is to use the contact ID:

      +
      int contact_id = ... // Acquire contact ID
      +contacts_record_h contact = NULL;
      +
      +error_code = contacts_db_get_record(_contacts_contact._uri, contact_id, &contact);
      +
      +

      Such handles are also provided by search functions, such as contacts_db_get_records_with_query().

    2. +
    3. Change the name. +
      1. To modify the contact name, get the name record with the contacts_record_get_child_record_at_p() function, which provides a list of the child records of a given type.

        +
        contacts_record_h name = NULL;
        +
        +error_code = contacts_record_get_child_record_at_p(contact, _contacts_contact.name, 0, &name);
        +
        + +

        The function parameters are the parent record, the child record type, a child record index, and the resulting child record. Since there can be only one child record of type _contacts_contact.name, the index is set to 0 to get the first (and only) child record.

      2. + +
      3. Change the first name: +
        error_code = contacts_record_set_str(name, _contacts_name.first, "Mark");
        +
        +

        This only changes the data in the memory object, not in the database. To insert the new value, the name record must be inserted. However, if you acquire this record using contacts_record_get_child_record_at_p() (as in this example), you only need to update the parent record.

    4. +
    5. Change the birthday event. +
      1. If only 1 event is set for the contact, you can call contacts_record_get_child_record_at_p() to get the event record. If there are more events, you must iterate over the child records. +
        contacts_record_h event = NULL;
        +error_code = contacts_record_get_child_record_at_p(contact, _contacts_contact.event, 0, &event);
        +
      2. + +
      3. Update the record: +
        int new_date = 1990 * 10000 + 6 * 100 + 21;
        +
        +error_code = contacts_record_set_int(event, _contacts_event.date, new_date);
        +
    6. +
    7. Update the contact record. +

      Update the contact. Any changes in the child records (such as name and birthday) are also inserted.

      +
      error_code = contacts_db_update_record(contact);
      +
    8. +
    9. When the record handle is no more needed, use the contacts_record_destroy() function to destroy the record handle and free the allocated memory: +
      contacts_record_destroy(contact, true);
    + +

    Deleting a Person

    + +

    To delete a person, call the contacts_db_delete_record() function with _contacts_person._uri as the first parameter and the person ID as the second one:

    +
    int person_id = ... // Acquire person ID
    +
    +error_code = contacts_db_delete_record(_contacts_person._uri, person_id);
    +
    + + + +

    To link and unlink contacts (manually and automatically):

    +
    • To link a person to another person manually, call the contacts_person_link_person() function with base person ID as the first parameter and another person ID as the second one. +
      int person_id1 = ... // Acquire base person ID
      +int person_id2 = ... // Acquire another person ID
      +
      +error_code = contacts_person_link_person(person_id1, person_id2);
      +
    • +
    • To link a contact automatically to a person when creating, set the link_mode property to CONTACTS_CONTACT_LINK_MODE_NONE when inserting. +

      The Contact Service determines the link based on the number and email properties. If the links leads to a contact in the same address book, the link does not work.

      +
      contacts_record_h contact = NULL;
      +
      +error_code = CONTACTS_ERROR_NONE;
      +error_code += contacts_record_create(_contacts_contact._uri, &contact);
      +error_code += contacts_record_set_int(contact, _contacts_contact.link_mode, CONTACTS_CONTACT_LINK_MODE_NONE);
      +
      +contacts_record_h name = NULL;
      +error_code += contacts_record_create(_contacts_name._uri, &name);
      +error_code += contacts_record_set_str(name, _contacts_name.first, "John");
      +error_code += contacts_record_add_child_record(contact, _contacts_contact.name, name);
      +
      +contacts_record_h number = NULL;
      +error_code += contacts_record_create(_contacts_number._uri, &number);
      +error_code += contacts_record_set_str(number, _contacts_number.number, "+8210-1234-5678");
      +error_code += contacts_record_add_child_record(contact, _contacts_contact.number, number);
      +
      +// Contact is linked automatically if an existing person has the same number in a different address book
      +error_code += contacts_db_insert_record(contact, NULL);
      +
      +contacts_record_destroy(contact, true);
    • +
    • To unlink a contact from a person, call the contacts_person_unlink_contact() function with the base person ID as the first parameter and the contact ID as the second one. A new person is created when unlinking. You can get the new person ID as the third parameter. +
      int person_id = ... // Acquire base person ID
      +int contact_id = ... // Acquire contact ID
      +int unlinked_person_id;
      +
      +error_code = contacts_person_unlink_contact(person_id, contact_id, &unlinked_person_id);
      +
    + +

    Managing Favorites

    + +

    To manage person favorites:

    +
    • To set a person as favorite when creating a contact, use the is_favorite property of the person record. If the property is set to true when creating a contact, the person is set as favorite: +
      contacts_record_h contact = NULL;
      +
      +error_code = CONTACTS_ERROR_NONE;
      +error_code += contacts_record_create(_contacts_contact._uri, &contact);
      +error_code += contacts_record_set_bool(contact, _contacts_contact.is_favorite, true);
      +// Set other properties
      +
      +// New person is set as favorite
      +error_code += contacts_db_insert_record(contact, NULL);
      +
      +contacts_record_destroy(contact, true);
    • +
    • To set an existing person as favorite, update the person record: +
      int person_id = ... // Acquire person ID
      +contacts_record_h person = NULL;
      +
      +error_code = contacts_db_get_record(_contacts_person._uri, person_id, &person);
      +
      +error_code = contacts_record_set_bool(person, _contacts_person.is_favorite, true);
      +
      +error_code = contacts_db_update_record(person);
      +
      +contacts_record_destroy(person, true);
    • +
    • To unset a favorite: +
      int person_id = ... // Acquire person ID
      +contacts_record_h person = NULL;
      +
      +error_code = contacts_db_get_record(_contacts_person._uri, person_id, &person);
      +
      +error_code = contacts_record_set_bool(person, _contacts_person.is_favorite, false);
      +
      +error_code = contacts_db_update_record(person);
      +
      +contacts_record_destroy(person, true);
    + +

    Monitoring Person Changes

    + +

    To register a callback function to listen for person changes:

    +
    1. Register the callback function. +
      error_code = contacts_db_add_changed_cb(_contacts_person._uri, _person_changed_callback, NULL);
      +
    2. +
    3. Define the callback function. +

      The callback function is called when the person data changes. The code below shows how to update person details in the callback function.

      +
      static contacts_gl_person_data_t *_gl_person_data = ...
      +void _person_changed_callback(const char *view_uri, void *user_data)
      +{
      +   int error_code;
      +
      +   if (0 != strcmp(view_uri, _contacts_person._uri))
      +      return;
      +
      +   if (_gl_person_data == NULL)
      +      return;
      +
      +   int person_id = _gl_person_data->id;
      +   _free_gl_person_data(_gl_person_data);
      +   _gl_person_data = NULL;
      +
      +   contacts_record_h record = NULL;
      +   error_code = contacts_db_get_record(_contacts_person._uri, person_id, &record);
      +   if (error_code != CONTACTS_ERROR_NONE)
      +      return;
      +
      +   _gl_person_data = _create_gl_person_data(record);
      +   // Use _gl_person_data
      +
      +   contacts_record_destroy(record, true);
      +}
    + +

    Creating a Group

    + +

    To create a new group record:

    +
    contacts_record_h group = NULL;
    +
    +error_code = contacts_record_create(_contacts_group._uri, &group);
    +
    + +

    Setting Group Properties

    + +

    To set group properties:

    + +
    1. Set the group name. +

      The contacts_record_set_str() function sets the name of the group when the second argument is _contacts_group.name. This function takes the group record handle as the first argument, and the name, which is a string value, as the third argument. The name argument is taken from the UI part of the application. The function returns the status code. If the function returns an error, take appropriate action, such as freeing memory, removing handles, and disconnecting from the service if needed.

      +
      error_code = contacts_record_set_str(group, _contacts_group.name, "Neighbors");
      +
    2. +
    3. Set an image and ringtone path. +

      You can set the other properties similarly. To set the image and ringtone path, call the contacts_record_set_str() function and check the error codes.

      +
      +char *resource_path = app_get_resource_path();
      +char temp_path[1024];
      +snprintf(temp_path, sizeof(temp_path), "%s/group_image.jpg", resource_path);
      +error_code = contacts_record_set_str(group, _contacts_group.image_path, temp_path);
      +snprintf(temp_path, sizeof(temp_path), "%s/ringtone.mp3", resource_path);
      +free(resource_path);
      +error_code = contacts_record_set_str(group, _contacts_group.ringtone_path, temp_path);
      +
    + +

    Inserting a Group to the Database

    + +

    To insert a group record:

    +
    1. Use the contacts_db_insert_record() function to insert a newly created group into the Contacts database. +

      The first argument is the group record handle, the second is the record ID. A unique ID is assigned to the record your are adding, and is returned as the third argument of the called function. If the group is inserted successfully, the function returns CONTACTS_ERROR_NONE.

      +
      int added_group_id = -1;
      +
      +error_code = contacts_db_insert_record(group, &added_group_id);
      +
    2. +
    3. After inserting, the used structures have to be destroyed: +
      contacts_record_destroy(group, true);
    + +

    Getting Groups

    + +

    To get all of the group records one by one, or to filter them by one of the properties:

    + +
    1. To get a single group record: +
      1. Use the contacts_db_get_record() function with the appropriate group_id:

        +
        contacts_record_h group;
        +int group_id = ... // Acquire group ID
        +error_code = contacts_db_get_record(_contacts_group._uri, group_id, &group);
        +
      2. +
      3. When you no longer need the group record, destroy the used structures: + +
        contacts_record_destroy(group, true);
    2. + +
    3. To get the total group record list: +
      1. +

        Use the contacts_db_get_all_records() function:

        +
        contacts_list_h list = NULL;
        +error_code = contacts_db_get_all_records(_contacts_group._uri, 0, 0, &list);
        +
      2. + +
      3. To iterate the list and read the records: + + + + + + + + + + +
        Note
        Some functions have the _p postfix. It means that the returned value must not be freed by the application, as it is a pointer to the data in an existing record.
        +
          +
        1. +

          To get the records from the list, use the contacts_list_get_current_record_p(), and contacts_list_next() or contacts_list_prev() functions. Get the details of each record in the loop.

          + +
          +contacts_record_h record;
          +while (contacts_list_get_current_record_p(list, &record) == CONTACTS_ERROR_NONE)
          +{
          +   char* name;
          +   error_code = contacts_record_get_str_p(record, _contacts_group.name, &name);
          +   dlog_print(DLOG_DEBUG, LOG_TAG, "group name: %s", name);
          +
          +   error_code = contacts_list_next(list);
          +   if (error_code != CONTACTS_ERROR_NONE)
          +      break;
          +}
          +
        2. +
        3. If you want to get more details of each record, use the contacts_gl_group_data_t structure like below: +
          +contacts_gl_group_data_t *gl_group_data = NULL;
          +contacts_record_h record;
          +while (contacts_list_get_current_record_p(list, &record) == CONTACTS_ERROR_NONE)
          +{
          +   gl_group_data = _create_gl_group_data(record);
          +   // You can get, for example, display name:
          +   // gl_group_data->name
          +
          +   error_code = contacts_list_next(list);
          +   if (error_code != CONTACTS_ERROR_NONE)
          +      break;
          +}
          +
        4. +
        5. The memory for the record data is allocated, and the data is copied from the record by the functions listed in the following snippet: +
          +typedef struct _contacts_gl_group_data
          +{
          +   int id;
          +   char *name;
          +   char *image_path;
          +   char *ringtone_path;
          +} contacts_gl_group_data_t;
          +
          +static void _free_gl_group_data(contacts_gl_group_data_t *gl_group_data)
          +{
          +   if (NULL == gl_group_data)
          +      return;
          +   free(gl_group_data->name);
          +   free(gl_group_data->image_path);
          +   free(gl_group_data->ringtone_path);
          +   free(gl_group_data);
          +}
          +
          +static contacts_gl_group_data_t* _create_gl_group_data(contacts_record_h record)
          +{
          +   contacts_gl_group_data_t *gl_group_data;
          +   int error_code;
          +
          +   gl_group_data = malloc(sizeof(contacts_gl_group_data_t));
          +   memset(gl_group_data, 0x0, sizeof(contacts_gl_group_data_t));
          +
          +   if (CONTACTS_ERROR_NONE != contacts_record_get_int(record, _contacts_group.id, &gl_group_data->id))
          +   {
          +      dlog_print(DLOG_ERROR, LOG_TAG, "contacts record get integer failed ");
          +      _free_gl_group_data(gl_group_data);
          +
          +      return NULL;
          +   }
          +   if (CONTACTS_ERROR_NONE != contacts_record_get_str(record, _contacts_group.name, &gl_group_data->name))
          +   {
          +      dlog_print(DLOG_ERROR, LOG_TAG, "contacts record get string failed ");
          +      _free_gl_group_data(gl_group_data);
          +
          +      return NULL;
          +   }
          +   if (CONTACTS_ERROR_NONE != contacts_record_get_str(record, _contacts_group.image_path, &gl_group_data->image_path))
          +   {
          +      dlog_print(DLOG_ERROR, LOG_TAG, "contacts record get string failed ");
          +      _free_gl_group_data(gl_group_data);
          +
          +      return NULL;
          +   }
          +   if (CONTACTS_ERROR_NONE != contacts_record_get_str(record, _contacts_group.ringtone_path, &gl_group_data->ringtone_path))
          +   {
          +      dlog_print(DLOG_ERROR, LOG_TAG, "contacts record get string failed ");
          +      _free_gl_group_data(gl_group_data);
          +
          +      return NULL;
          +   }
          +
          +   return gl_group_data;
          +}
          +
        6. +
        +
      4. +
      5. When you no longer need the group record, destroy the used structures: +
        +contacts_list_destroy(list, true);
        +
        +
      6. +
      +
    4. +
    5. To get the filtered group record list: +
        +
      1. Use the contacts_db_get_records_with_query() function to filter the list with parameters: +
          +
        1. To get groups with filtering, you need a record list and a query: +
          contacts_list_h list = NULL;
          +contacts_query_h query = NULL;
          +
          +error_code = contacts_query_create(_contacts_group._uri, &query);
          +
        2. +
        3. Before getting the groups, filter the list. There is a possibility to filter based on various parameters. To create a filter, the following code is used: +
          contacts_filter_h filter = NULL;
          +
          +error_code = contacts_filter_create(_contacts_group._uri, &filter);
          +
        4. +
        5. Add a condition, such as group name: +
          error_code = contacts_filter_add_str(filter, _contacts_group.name, CONTACTS_MATCH_CONTAINS, "neighbors");
          +
          +

          That way only groups which contain the name "neighbors" are retrieved. To use multiple conditions, add an operator between them:

          +
          error_code = contacts_filter_add_operator(filter, CONTACTS_FILTER_OPERATOR_OR);
          +
          +error_code = contacts_filter_add_str(filter, _contacts_group.name, CONTACTS_MATCH_CONTAINS, "friend");
          +
        6. +
        7. Connect the query with the list: +
          error_code = contacts_query_set_filter(query, filter);
          +
          +error_code = contacts_db_get_records_with_query(query, 0, 0, &list);
          +
          +

          The third parameter refers to the limit of the results. If 0 is passed, there are no limits. Remember that after all operations, the list must be released.

        8. +
        9. Free the filter and query: +
          +contacts_filter_destroy(filter);
          +contacts_query_destroy(query);
          +
        10. +
      2. +
      3. To iterate the list and read the records: + + + + + + + + + + +
        Note
        Some functions have the _p postfix. It means that the returned value must not be freed by the application, as it is a pointer to the data in an existing record.
        + +
        1. To get the records from the list, use the contacts_list_get_current_record_p(), and contacts_list_next() or contacts_list_prev() functions. Get the details of each record in the loop.

          + +
          contacts_record_h record;
          +while (contacts_list_get_current_record_p(list, &record) == CONTACTS_ERROR_NONE)
          +{
          +   char* name;
          +   error_code = contacts_record_get_str_p(record, _contacts_group.name, &name);
          +   dlog_print(DLOG_DEBUG, LOG_TAG, "group name: %s", name);
          +
          +   error_code = contacts_list_next(list);
          +   if (error_code != CONTACTS_ERROR_NONE)
          +      break;
          +}
        2. +
        3. If you want to get more details of each record, use the contacts_gl_group_data_t structure like below:

          +
          contacts_gl_group_data_t *gl_group_data = NULL;
          +contacts_record_h record;
          +while (contacts_list_get_current_record_p(list, &record) == CONTACTS_ERROR_NONE)
          +{
          +   gl_group_data = _create_gl_group_data(record);
          +   // You can get, for example, display name:
          +   // gl_group_data->name
          +
          +   error_code = contacts_list_next(list);
          +   if (error_code != CONTACTS_ERROR_NONE)
          +      break;
          +}
        4. +
        5. The memory for the record data is allocated, and the data is copied from the record by the functions listed further on in this document.

          +
          typedef struct _contacts_gl_group_data
          +{
          +   int id;
          +   char *name;
          +   char *image_path;
          +   char *ringtone_path;
          +} contacts_gl_group_data_t;
          +
          +static void _free_gl_group_data(contacts_gl_group_data_t *gl_group_data)
          +{
          +   if (NULL == gl_group_data)
          +      return;
          +   free(gl_group_data->name);
          +   free(gl_group_data->image_path);
          +   free(gl_group_data->ringtone_path);
          +   free(gl_group_data);
          +}
          +
          +static contacts_gl_group_data_t* _create_gl_group_data(contacts_record_h record)
          +{
          +   contacts_gl_group_data_t *gl_group_data;
          +   int error_code;
          +
          +   gl_group_data = malloc(sizeof(contacts_gl_group_data_t));
          +   memset(gl_group_data, 0x0, sizeof(contacts_gl_group_data_t));
          +
          +   if (CONTACTS_ERROR_NONE != contacts_record_get_int(record, _contacts_group.id, &gl_group_data->id))
          +   {
          +      dlog_print(DLOG_ERROR, LOG_TAG, "contacts record get integer failed ");
          +      _free_gl_group_data(gl_group_data);
          +
          +      return NULL;
          +   }
          +   if (CONTACTS_ERROR_NONE != contacts_record_get_str(record, _contacts_group.name, &gl_group_data->name))
          +   {
          +      dlog_print(DLOG_ERROR, LOG_TAG, "contacts record get string failed ");
          +      _free_gl_group_data(gl_group_data);
          +
          +      return NULL;
          +   }
          +   if (CONTACTS_ERROR_NONE != contacts_record_get_str(record, _contacts_group.image_path, &gl_group_data->image_path))
          +   {
          +      dlog_print(DLOG_ERROR, LOG_TAG, "contacts record get string failed ");
          +      _free_gl_group_data(gl_group_data);
          +
          +      return NULL;
          +   }
          +   if (CONTACTS_ERROR_NONE != contacts_record_get_str(record, _contacts_group.ringtone_path, &gl_group_data->ringtone_path))
          +   {
          +      dlog_print(DLOG_ERROR, LOG_TAG, "contacts record get string failed ");
          +      _free_gl_group_data(gl_group_data);
          +
          +      return NULL;
          +   }
          +
          +   return gl_group_data;
          +}
      4. +
      5. When you no longer need the group record, destroy the used structures: +
        +contacts_list_destroy(list, true);
        +
    + +

    Updating a Group

    + +

    To change the name and image of an existing person:

    +
    1. Get the group. +

      To modify a record, you need to have a handle (contacts_record_h type variable) to a memory object representing the record in the database. One of the ways to acquire it is to use the group ID:

      +
      int group_id = ... // Acquire group ID
      +contacts_record_h group = NULL;
      +
      +error_code = contacts_db_get_record(_contacts_group._uri, group_id, &group);
      +
      +

      Such handles are also provided by search functions, such as contacts_db_get_records_with_query().

      +
    2. +
    3. Change the name and image. +

      Change the name and image property using the contacts_record_set_str() function.

      +
      error_code = contacts_record_set_str(group, _contacts_group.name, "Family");
      +char *resource_path = app_get_resource_path();
      +char temp_path[1024];
      +snprintf(temp_path, sizeof(temp_path), "%s/group_image_new.jpg", resource_path);
      +free(resource_path);
      +error_code = contacts_record_set_str(group, _contacts_group.image_path, temp_path);
      +
    4. + +
    5. Update the group record. +

      Update the group. The above changes (name and image) are also inserted.

      +
      error_code = contacts_db_update_record(group);
      +
    6. +
    7. Clean up. +

      When the record handle is no longer needed, use the contacts_record_destroy() function to destroy the record handle and free the allocated memory.

      +
      contacts_record_destroy(group, true);
    + +

    Deleting a Group

    + +

    To delete a group, call the contacts_db_delete_record() function with _contacts_group._uri as the first parameter and group ID as the second one;

    +
    int group_id = ... // Acquire group ID
    +
    +error_code = contacts_db_delete_record(_contacts_group._uri, group_id);
    +
    + +

    Managing Group Members

    + +

    To manage group members:

    + +
    • To add a group member, you need to know the contact ID and the group ID. Then you need to call contacts_group_add_contact(). +
      int contact_id = ... // Acquire contact ID
      +int group_id = ... // Acquire group ID
      +
      +error_code = contacts_group_add_contact(group_id, contact_id);
      +
    • +
    • To remove a contact from a group, call contacts_group_remove_contact(). +
      +error_code = contacts_group_remove_contact(group_id, contact_id);
      +
    • + +
    • To get a list of persons assigned to a specific group: +
      1. Get the records of type _contacts_person_group_assigned: +
        +contacts_query_h query = NULL;
        +contacts_filter_h filter = NULL;
        +contacts_list_h list = NULL;
        +
        +contacts_query_create(_contacts_person_group_assigned._uri, &query);
        +contacts_filter_create(_contacts_person_group_assigned._uri, &filter);
        +contacts_filter_add_int(filter, _contacts_person_group_assigned.group_id, CONTACTS_MATCH_EQUAL, group_id);
        +contacts_query_set_filter(query, filter);
        +contacts_db_get_records_with_query(query, 0, 0, &list);
      2. +
      3. Iterate over the list elements. +
        contacts_record_h person = NULL;
        +int error_code;
        +
        +while (contacts_list_get_current_record_p(list, &person) == CONTACTS_ERROR_NONE)
        +{
        +   int person_id;
        +   contacts_record_get_int(person, _contacts_person_group_assigned.person_id, &person_id);
        +   dlog_print(DLOG_DEBUG, LOG_TAG, "Person id: %d", person_id);
        +
        +   char *display_name;
        +   contacts_record_get_str_p(person, _contacts_person_group_assigned.display_name, &display_name);
        +   dlog_print(DLOG_DEBUG, LOG_TAG, "Display name: %s", display_name);
        +
        +   error_code = contacts_list_next(list);
        +   if (error_code != CONTACTS_ERROR_NONE)
        +      break;
        +}
      4. +
      5. Destroy the filter, query, and list handles when no longer needed. +
        contacts_list_destroy(list, true);
        +contacts_filter_destroy(filter);
        +contacts_query_destroy(query);
    + +

    Monitoring Group Changes

    + +

    To register a callback function to listen for group changes:

    +
    1. Register the callback function. +

      The code below shows how to register a callback function to listen for group changes.

      +
      error_code = contacts_db_add_changed_cb(_contacts_group._uri, _group_changed_callback, NULL);
      +
    2. +
    3. Define the callback function. +

      The callback function is called when the group data changes. The code below shows how to update the group details in the callback function.

      +
      static contacts_gl_group_data_t *_gl_group_data = ...
      +static void _group_changed_callback(const char *view_uri, void *user_data)
      +{
      +   int error_code;
      +
      +   if (0 != strcmp(view_uri, _contacts_group._uri))
      +      return;
      +
      +   if (_gl_group_data == NULL)
      +      return;
      +
      +   int group_id = _gl_group_data->id;
      +   _free_gl_group_data(_gl_group_data);
      +   _gl_group_data = NULL;
      +
      +   contacts_record_h record = NULL;
      +   error_code = contacts_db_get_record(_contacts_group._uri, group_id, &record);
      +   if (error_code != CONTACTS_ERROR_NONE)
      +      return;
      +
      +   _gl_group_data = _create_gl_group_data(record);
      +   // Use _gl_group_data
      +
      +   contacts_record_destroy(record, true);
      +}
    + +

    Making a vCard

    + +

    To make a vCard stream from a person record:

    +
    1. Get the person record by the person ID. +
      int person_id = ... // Acquire person ID
      +
      +contacts_record_h record = NULL;
      +error_code = contacts_db_get_record(_contacts_person._uri, person_id, &record);
      +
    2. +
    3. Make the vCard stream by the person record. +
      char *vcard_stream = NULL;
      +error_code = contacts_vcard_make_from_person(record, &vcard_stream);
      +
      + + + + + + + + + + +
      Note
      The Contact Service API allows you to make a vCard stream from a person, contact, and my profile records: +
      int contacts_vcard_make_from_person(contacts_record_h person, char **vcard_stream);
      +int contacts_vcard_make_from_contact(contacts_record_h contact, char **vcard_stream);
      +int contacts_vcard_make_from_my_profile(contacts_record_h my_profile, char **vcard_stream);
      +
    4. + +
    5. Destroy the handle when it is no longer needed. +
      free(vcard_stream);
      +contacts_record_destroy(record, true);
      +
    + +

    Parsing a vCard

    + +

    To parse a vCard from a file and insert to the database:

    +
    +char *resource_path = app_get_resource_path();
    +char temp_path[1024];
    +snprintf(temp_path, sizeof(temp_path), "%s/vcard.vcf", resource_path);
    +free(resource_path);
    +error_code = contacts_vcard_parse_to_contact_foreach(temp_path, // File path of vCard
    +                                                     _vcard_parse_cb, // Callback function to invoke
    +                                                     NULL); // User data to be passed to the callback function
    +
    + +

    The vCard stream contains multiple contact objects. The callback function is called after parsing each contact. If you return false on the callback function, parsing stops.

    +
    static bool _vcard_parse_cb(contacts_record_h contact, void *user_data)
    +{
    +   if (NULL == contact)
    +      return false;
    +
    +   int contact_id = -1;
    +   error_code = contacts_db_insert_record(contact, &contact_id);
    +   // Use the contact record
    +
    +   return true;
    +}
    + + +

    Creating a Speed Dial

    + +

    To create a speed dial record:

    +
    +contacts_record_h speeddial;
    +error_code = contacts_record_create(_contacts_speeddial._uri, &speeddial);
    +
    +

    The first argument determines the type of the created record. Use _contacts_speeddial._uri to create speed dial type records.

    + +

    Setting Speed Dial Properties

    + +

    To set speed dial properties:

    +
      +
    1. Set the speed dial number. +

      The contacts_record_set_int() function sets the speed dial type when the second argument is _contacts_speeddial.speeddial_number. This function takes the speed dial record handle as the first argument, and the speed dial number, which is an integer value, as the third argument. The function returns the status code. If the function returns an error, take appropriate action, such as freeing memory, removing handles, or disconnecting from the service.

      +
      +int speeddial_number = ... // Acquire speed dial number
      +error_code = contacts_record_set_int(speeddial, _contacts_speeddial.speeddial_number, speeddial_number);
      +
      +
    2. + +
    3. Set the number ID: +
      +int number_id = ... // Acquire number id
      +error_code = contacts_record_set_int(speeddial, _contacts_speeddial. number_id, number_id);
      +
      +
    4. +
    + + + + + + + + + + +
    Note
    This tutorial does not describe how to insert a number. For more information, see the Contact Tutorial.
    + +

    Inserting a Speed Dial to the Database

    + +

    To insert a speed dial record:

    +
    1. Use the contacts_db_insert_record() function to insert a newly created speed dial into the Contacts database. The first argument is the speed dial record handle, the second is the speed dial number. If the speed dial is inserted successfully, the function returns CONTACTS_ERROR_NONE. +
      +int added_speeddial_id = -1;
      +
      +error_code = contacts_db_insert_record(speeddial, &added_speeddial_id);	
      +
      +
    2. + +
    3. After inserting the speed dial record, destroy the used structures: +
      +contacts_record_destroy(speeddial, true);
      +
      +
    4. +
    + +

    Getting Speed Dials

    + +

    To get all of the speed dial records one by one, or to filter them by one of the properties:

    +
      +
    1. To get a single speed dial record: +
        +
      1. Use the contacts_db_get_record() function with the appropriate speeddial_id:

        +
        +contacts_record_h speeddial;
        +int speeddial_id = ... // Acquire speed dial ID
        +error_code = contacts_db_get_record(_contacts_speeddial._uri, speeddial_id, &speeddial);
        +
        +
      2. + +
      3. After finish using the speed dial record, destroy the used structures: + +
        contacts_record_destroy(speeddial, true);
    2. + +
    3. To get the total speed dial record list: +
      1. Use the contacts_db_get_all_records() function: +
        +contacts_list_h list = NULL;
        +error_code = contacts_db_get_all_records(_contacts_speeddial._uri, 0, 0, &list);
        +
        +
      2. + +
      3. To iterate the list and read the records, you can get the records from the list using the contacts_list_get_current_record_p(), contacts_list_next(), or contacts_list_prev() function. Get the details of each record in the loop. + + + + + + + + + + +
        Note
        Some functions have the _p postfix. It means that the returned value must not be freed by the application, as it is a pointer to the data in an existing record.
        + + +
        +contacts_record_h record;
        +while (contacts_list_get_current_record_p(list, &record) == CONTACTS_ERROR_NONE)
        +{
        +   int number;
        +   error_code = contacts_record_get_int(record, _contacts_speeddial.speeddial_number, &number);
        +   dlog_print(DLOG_DEBUG, LOG_TAG, "speed dial number: %d", number);
        +
        +   error_code = contacts_list_next(list);
        +   if (error_code != CONTACTS_ERROR_NONE)
        +      break;
        +}
        +
        + +

        To get more details of each record, use the contacts_gl_speeddial_data_t structure:

        + +
        +contacts_gl_speeddial_data_t *gl_speeddial_data = NULL;
        +contacts_record_h record;
        +while (contacts_list_get_current_record_p(list, &record) == CONTACTS_ERROR_NONE)
        +{
        +   gl_speeddial_data = _create_gl_speeddial_data(record);
        +
        +   _free_gl_speeddial_data(gl_speeddial_data);
        +   error_code = contacts_list_next(list);
        +   if (error_code != CONTACTS_ERROR_NONE)
        +      break;
        +}
        +
        + +

        The memory for the record data is allocated, and the data is copied from the record by the functions shown in the following snippet:

        + +
        +typedef struct _contacts_gl_speeddial_data
        +{
        +   int speeddial_number;
        +   char *number;
        +   char *display_name;
        +   char *image_thumbnail_path;
        +} contacts_gl_speeddial_data_t;
        +
        +static void _free_gl_speeddial_data(contacts_gl_speeddial_data_t *gl_speeddial_data)
        +{
        +   if (NULL == gl_speeddial_data)
        +      return;
        +   free(gl_speeddial_data->number);
        +   free(gl_speeddial_data->display_name);
        +   free(gl_speeddial_data->image_thumbnail_path);
        +   free(gl_speeddial_data);
        +}
        +
        +static contacts_gl_speeddial_data_t* _create_gl_speeddial_data(contacts_record_h record)
        +{
        +   contacts_gl_speeddial_data_t *gl_speeddial_data;
        +   int error_code;
        +
        +   gl_speeddial_data = malloc(sizeof(contacts_gl_speeddial_data_t));
        +   memset(gl_speeddial_data, 0x0, sizeof(contacts_gl_speeddial_data_t));
        +
        +   if (CONTACTS_ERROR_NONE != contacts_record_get_int(record, _contacts_speeddial.speeddial_number, &gl_speeddial_data->speeddial_number))
        +   {
        +      dlog_print(DLOG_ERROR, LOG_TAG, "contacts record get integer failed ");
        +      _free_gl_speeddial_data(gl_speeddial_data);
        +
        +      return NULL;
        +   }
        +   if (CONTACTS_ERROR_NONE != contacts_record_get_str(record, _contacts_speeddial.number, &gl_speeddial_data->number))
        +   {
        +      dlog_print(DLOG_ERROR, LOG_TAG, "contacts record get string failed ");
        +      _free_gl_speeddial_data(gl_speeddial_data);
        +
        +      return NULL;
        +   }
        +   if (CONTACTS_ERROR_NONE != contacts_record_get_str(record, _contacts_speeddial.display_name, &gl_speeddial_data->display_name))
        +   {
        +      dlog_print(DLOG_ERROR, LOG_TAG, "contacts record get string failed ");
        +      _free_gl_speeddial_data(gl_speeddial_data);
        +
        +      return NULL;
        +   }
        +   if (CONTACTS_ERROR_NONE != contacts_record_get_str(record, _contacts_speeddial.image_thumbnail_path, &gl_speeddial_data->image_thumbnail_path))
        +   {
        +      dlog_print(DLOG_ERROR, LOG_TAG, "contacts record get string failed ");
        +      _free_gl_speeddial_data(gl_speeddial_data);
        +
        +      return NULL;
        +   }
        +
        +   return gl_speeddial_data;
        +}
        +
        +
      4. +
      5. After you no longer need the speed dial record, destroy the used structures: +
        +contacts_list_destroy(list, true);
        +
      6. +
      +
    4. +
    5. To get the filtered speed dial record list: +
        +
      1. Use the contacts_db_get_records_with_query() function. +
          +
        1. Create a record list and query: + +
          +contacts_list_h list = NULL;
          +contacts_query_h query = NULL;
          +
          +error_code = contacts_query_create(_contacts_speeddial._uri, &query);
          +
          +
        2. +
        3. Filter the list before getting the speed dials. It is possible to filter with various parameters. To create a filter: +
          +contacts_filter_h filter = NULL;
          +
          +error_code = contacts_filter_create(_contacts_speeddial._uri, &filter);
          +
          +
        4. + +
        5. Add a condition, such as the speed dial number. +

          The following example retrieves only those speed dials whose numbers are less than 3.

          +
          +error_code = contacts_filter_add_int(filter, _contacts_speeddial.speeddial_number, CONTACTS_MATCH_LESS_THAN, 3);
          +
          +

          To use multiple conditions, add an operator between them:

          +
          +error_code = contacts_filter_add_operator(filter, CONTACTS_FILTER_OPERATOR_OR);
          +
          +error_code = contacts_filter_add_int(filter, _contacts_speeddial.speeddial_number, CONTACTS_MATCH_GREATER_THAN, 15);
          +
          +
        6. + +
        7. Connect the query with the list: +
          +error_code = contacts_query_set_filter(query, filter);
          +
          +error_code = contacts_db_get_records_with_query(query, 0, 0, &list);
          +
          +

          The third parameter refers to the limit of the results. If 0 is passed, there are no limits. Remember that after all operations, the list must be released.

          +
        8. + +
        9. Free the filter and query: +
          +contacts_filter_destroy(filter);
          +contacts_query_destroy(query);
          +
          +
        10. +
        +
      2. + +
      3. To iterate the list and read the records, you can get the records from the list using the contacts_list_get_current_record_p(), contacts_list_next(), or contacts_list_prev() function. Get the details of each record in the loop. + + + + + + + + + + +
        Note
        Some functions have the _p postfix. It means that the returned value must not be freed by the application, as it is a pointer to the data in an existing record.
        + +
        +contacts_record_h record;
        +while (contacts_list_get_current_record_p(list, &record) == CONTACTS_ERROR_NONE)
        +{
        +   int number;
        +   error_code = contacts_record_get_int(record, _contacts_speeddial.speeddial_number, &number);
        +   dlog_print(DLOG_DEBUG, LOG_TAG, "speed dial number: %d", number);
        +
        +   error_code = contacts_list_next(list);
        +   if (error_code != CONTACTS_ERROR_NONE)
        +      break;
        +}
        +
        + +

        To get more details of each record, use the contacts_gl_speeddial_data_t structure:

        +
        +contacts_gl_speeddial_data_t *gl_speeddial_data = NULL;
        +contacts_record_h record;
        +while (contacts_list_get_current_record_p(list, &record) == CONTACTS_ERROR_NONE)
        +{
        +   gl_speeddial_data = _create_gl_speeddial_data(record);
        +
        +   _free_gl_speeddial_data(gl_speeddial_data);
        +   error_code = contacts_list_next(list);
        +   if (error_code != CONTACTS_ERROR_NONE)
        +      break;
        +}
        +
        +

        The memory for the record data is allocated, and the data is copied from the record by the functions shown in the following snippet.

        +
        +typedef struct _contacts_gl_speeddial_data
        +{
        +   int speeddial_number;
        +   char *number;
        +   char *display_name;
        +   char *image_thumbnail_path;
        +} contacts_gl_speeddial_data_t;
        +
        +static void _free_gl_speeddial_data(contacts_gl_speeddial_data_t *gl_speeddial_data)
        +{
        +   if (NULL == gl_speeddial_data)
        +      return;
        +   free(gl_speeddial_data->number);
        +   free(gl_speeddial_data->display_name);
        +   free(gl_speeddial_data->image_thumbnail_path);
        +   free(gl_speeddial_data);
        +}
        +
        +static contacts_gl_speeddial_data_t* _create_gl_speeddial_data(contacts_record_h record)
        +{
        +   contacts_gl_speeddial_data_t *gl_speeddial_data;
        +   int error_code;
        +
        +   gl_speeddial_data = malloc(sizeof(contacts_gl_speeddial_data_t));
        +   memset(gl_speeddial_data, 0x0, sizeof(contacts_gl_speeddial_data_t));
        +
        +   if (CONTACTS_ERROR_NONE != contacts_record_get_int(record, _contacts_speeddial.speeddial_number, &gl_speeddial_data->speeddial_number))
        +   {
        +      dlog_print(DLOG_ERROR, LOG_TAG, "contacts record get integer failed ");
        +      _free_gl_speeddial_data(gl_speeddial_data);
        +
        +      return NULL;
        +   }
        +   if (CONTACTS_ERROR_NONE != contacts_record_get_str(record, _contacts_speeddial.number, &gl_speeddial_data->number))
        +   {
        +      dlog_print(DLOG_ERROR, LOG_TAG, "contacts record get string failed ");
        +      _free_gl_speeddial_data(gl_speeddial_data);
        +
        +      return NULL;
        +   }
        +   if (CONTACTS_ERROR_NONE != contacts_record_get_str(record, _contacts_speeddial.display_name, &gl_speeddial_data->display_name))
        +   {
        +      dlog_print(DLOG_ERROR, LOG_TAG, "contacts record get string failed ");
        +      _free_gl_speeddial_data(gl_speeddial_data);
        +
        +      return NULL;
        +   }
        +   if (CONTACTS_ERROR_NONE != contacts_record_get_str(record, _contacts_speeddial.image_thumbnail_path, &gl_speeddial_data->image_thumbnail_path))
        +   {
        +      dlog_print(DLOG_ERROR, LOG_TAG, "contacts record get string failed ");
        +      _free_gl_speeddial_data(gl_speeddial_data);
        +
        +      return NULL;
        +   }
        +
        +   return gl_speeddial_data;
        +}
        +
        +
      4. +
      5. When you no longer need the speed dial record, destroy the used structures: +
        +contacts_list_destroy(list, true);
      6. +
    + +

    Updating a Speed Dial

    + +

    To change the number ID of an existing speed dial:

    +
      +
    1. Get the speed dial. +

      To modify a record, you need to have a handle (contacts_record_h type variable) to a memory object representing the record in the database. One of the ways to acquire it is to use the speed dial number:

      +
      +int speeddial_number = ... // Acquire speed dial number
      +contacts_record_h speeddial = NULL;
      +
      +error_code = contacts_db_get_record(_contacts_speeddial._uri, speeddial_number, &speeddial);
      +
      + +

      Such handles are also provided by search functions, such as contacts_db_get_records_with_query().

      +
    2. + +
    3. Change the number ID by setting the number_id property using the contacts_record_set_int() function: +
      +int number_id = ... // Acquire number id
      +error_code = contacts_record_set_int(speeddial, _contacts_speeddial.number_id, number_id);
      +if (error_code != CONTACTS_ERROR_NONE)
      +   dlog_print(DLOG_ERROR, LOG_TAG, "contacts record set integer failed: %x", error_code);
      +
      +
    4. + +
    5. Update the speed dial record. +

      Update the speed dial. The above changes (number_id) are also inserted.

      +
      +error_code = contacts_db_update_record(speeddial);
      +
      +
    6. + +
    7. Clean up. +

      When the record handle is no longer needed, use the contacts_record_destroy() function to destroy the record handle and free the allocated memory.

      +
      +contacts_record_destroy(speeddial, true);
      +
      +
    8. +
    + +

    Deleting a Speed Dial

    + +

    To delete a speed dial, call the contacts_db_delete_record() function with _contacts_speeddial._uri as the first parameter and speed dial number as the second one;

    +
    +int speeddial_number = ... // Acquire speed dial number
    +
    +error_code = contacts_db_delete_record(_contacts_speeddial._uri, speeddial_number);
    +
    + + +

    Creating a Log

    + +

    To create a log record:

    +
    +contacts_record_h log;
    +error_code = contacts_record_create(_contacts_phone_log._uri, &log);
    +if (error_code != CONTACTS_ERROR_NONE)
    +   dlog_print(DLOG_ERROR, LOG_TAG, "contacts record create failed: %x", error_code);
    +
    +

    The first argument determines the type of the created record. Use _contacts_phone_log._uri to create log type records.

    + +

    Setting Log Properties

    + +

    To set log properties:

    +
      +
    1. Set the log type. +

      The contacts_record_set_int() function sets the type of the log when the second argument is _contacts_phone_log.log_type. This function takes the log record handle as the first argument, and the type, which is a integer value, as the third argument. The function returns the status code. If the function returns an error, free memory, remove handles, and disconnect from the service, if needed.

      +
      +error_code = contacts_record_set_int(log, _contacts_phone_log.log_type, CONTACTS_PLOG_TYPE_VOICE_INCOMMING);
      +if (error_code != CONTACTS_ERROR_NONE)
      +   dlog_print(DLOG_ERROR, LOG_TAG, "contacts record set integer failed: %x", error_code);
      +
      + +

      The enumeration flag names for the log types are:

      +
      +CONTACTS_PLOG_TYPE_NONE
      +CONTACTS_PLOG_TYPE_VOICE_INCOMMING
      +CONTACTS_PLOG_TYPE_VOICE_OUTGOING
      +CONTACTS_PLOG_TYPE_VIDEO_INCOMING
      +CONTACTS_PLOG_TYPE_VIDEO_OUTGOING
      +CONTACTS_PLOG_TYPE_VOICE_INCOMMING_UNSEEN
      +CONTACTS_PLOG_TYPE_VOICE_INCOMMING_SEEN
      +CONTACTS_PLOG_TYPE_VIDEO_INCOMING_UNSEEN
      +CONTACTS_PLOG_TYPE_VIDEO_INCOMING_SEEN
      +CONTACTS_PLOG_TYPE_VOICE_REJECT
      +CONTACTS_PLOG_TYPE_VIDEO_REJECT
      +CONTACTS_PLOG_TYPE_VOICE_BLOCKED
      +CONTACTS_PLOG_TYPE_VIDEO_BLOCKED
      +CONTACTS_PLOG_TYPE_MMS_INCOMING
      +CONTACTS_PLOG_TYPE_MMS_OUTGOING
      +CONTACTS_PLOG_TYPE_SMS_INCOMING
      +CONTACTS_PLOG_TYPE_SMS_OUTGOING
      +CONTACTS_PLOG_TYPE_SMS_BLOCKED
      +CONTACTS_PLOG_TYPE_MMS_BLOCKED
      +CONTACTS_PLOG_TYPE_EMAIL_RECEIVED
      +CONTACTS_PLOG_TYPE_EMAIL_SENT
      +
    2. + +
    3. Set time, duration, and address: +
      +error_code = contacts_record_set_int(log, _contacts_phone_log.log_time, (int)time(NULL));
      +if (error_code != CONTACTS_ERROR_NONE)
      +   dlog_print(DLOG_ERROR, LOG_TAG, "contacts record set integer failed: %x", error_code);
      +
      +error_code = contacts_record_set_int(log, _contacts_phone_log.extra_data1, 37);
      +if (error_code != CONTACTS_ERROR_NONE)
      +   dlog_print(DLOG_ERROR, LOG_TAG, "contacts record set integer failed: %x", error_code);
      +
      +error_code = contacts_record_set_str(log, _contacts_phone_log.address, "+8231-1234-5678");
      +if (error_code != CONTACTS_ERROR_NONE)
      +   dlog_print(DLOG_ERROR, LOG_TAG, "contacts record set string failed: %x", error_code);
      +
      + +

      Log time means the number of seconds since 1970-01-01 00:00:00 (UTC). The extra_data1 property means the message_id, email_id, or duration (seconds) of a call. The address property means a number or an email.

      +
    4. +
    + +

    Inserting a Log to the Database

    + +

    To insert a log record:

    +
      +
    1. Use the contacts_db_insert_record() function to insert a newly created log into the Contacts database. The first argument is the log record handle, the second is the record ID. If the log is inserted successfully, the function returns CONTACTS_ERROR_NONE. +
      +int added_log_id = -1;
      +
      +error_code = contacts_db_insert_record(log, &added_log_id);
      +if (error_code != CONTACTS_ERROR_NONE)
      +   dlog_print(DLOG_ERROR, LOG_TAG, "contacts db insert record failed: %x", error_code);
      +
      +
    2. +
    3. After inserting the log, destroy the used structures: +
      contacts_record_destroy(log, true);
      +
    4. +
    + +

    Getting Logs

    + +

    To get all log records one by one, or to filter them by one of the properties:

    +
      +
    1. To get a single log record: +
      1. Use the contacts_db_get_record() function with the appropriate log_id:

        +
        contacts_record_h log;
        +int log_id = ... // Acquire log ID
        +error_code = contacts_db_get_record(_contacts_phone_log._uri, log_id, &log);
        +if (error_code != CONTACTS_ERROR_NONE)
        +   dlog_print(DLOG_ERROR, LOG_TAG, "contacts db get record failed: %x", error_code);
        +
      2. +
      3. After inserting the log, destroy the used structures: +
        contacts_record_destroy(log, true);
      +
    2. +
    3. To get the total log record list: +
      1. Use the contacts_db_get_all_records() function:

        +
        +contacts_list_h list = NULL;
        +error_code = contacts_db_get_all_records(_contacts_phone_log._uri, 0, 0, &list);
        +if (error_code != CONTACTS_ERROR_NONE)
        +   dlog_print(DLOG_ERROR, LOG_TAG, "contacts db get all records failed: %x", error_code);
        +
        +
      2. + +
      3. To iterate the list and read the records, you can get the records from the list using the contacts_list_get_current_record_p(), contacts_list_next(), or contacts_list_prev() function. Get the details of each record in the loop. + + + + + + + + + + +
        Note
        Some functions have the _p postfix. It means that the returned value must not be freed by the application, as it is a pointer to the data in an existing record.
        + + +
        +contacts_record_h record;
        +while (contacts_list_get_current_record_p(list, &record) == CONTACTS_ERROR_NONE)
        +{
        +   int type;
        +   error_code = contacts_record_get_int(record, _contacts_phone_log.log_type, &type);
        +   dlog_print(DLOG_DEBUG, LOG_TAG, "log type: %d", type);
        +
        +   error_code = contacts_list_next(list);
        +   if (error_code != CONTACTS_ERROR_NONE)
        +      break;
        +}
        +
        + +

        To get more details of each record, use the contacts_gl_log_data_t structure:

        + +
        +contacts_gl_log_data_t *gl_log_data = NULL;
        +contacts_record_h record;
        +while (contacts_list_get_current_record_p(list, &record) == CONTACTS_ERROR_NONE)
        +{
        +   gl_log_data = _create_gl_log_data(record);
        +
        +   _free_gl_log_data(gl_log_data);
        +   error_code = contacts_list_next(list);
        +   if (error_code != CONTACTS_ERROR_NONE)
        +      break;
        +}
        +
        + +

        The memory for the record data is allocated, and the data is copied from the record by the functions listed further on in this document.

        + +
        +typedef struct _contacts_gl_log_data
        +{
        +   int id;
        +   char *address;
        +   int log_type;
        +   int log_time;
        +} contacts_gl_log_data_t;
        +
        +static void _free_gl_log_data(contacts_gl_log_data_t *gl_log_data)
        +{
        +   if (NULL == gl_log_data)
        +      return;
        +   free(gl_log_data->address);
        +   free(gl_log_data);
        +}
        +
        +static contacts_gl_log_data_t* _create_gl_log_data(contacts_record_h record)
        +{
        +   contacts_gl_log_data_t *gl_log_data;
        +   int error_code;
        +
        +   gl_log_data = malloc(sizeof(contacts_gl_log_data_t));
        +   memset(gl_log_data, 0x0, sizeof(contacts_gl_log_data_t));
        +
        +   if (CONTACTS_ERROR_NONE != contacts_record_get_int(record, _contacts_phone_log.id, &gl_log_data->id))
        +   {
        +      dlog_print(DLOG_ERROR, LOG_TAG, "contacts record get integer failed ");
        +      _free_gl_log_data(gl_log_data);
        +
        +      return NULL;
        +   }
        +   if (CONTACTS_ERROR_NONE != contacts_record_get_str(record, _contacts_phone_log.address, &gl_log_data->address))
        +   {								
        +      dlog_print(DLOG_ERROR, LOG_TAG, "contacts record get string failed ");
        +      _free_gl_log_data(gl_log_data);
        +
        +      return NULL;
        +   }
        +   if (CONTACTS_ERROR_NONE != contacts_record_get_int(record, _contacts_phone_log.log_type, &gl_log_data->log_type))
        +   {
        +      dlog_print(DLOG_ERROR, LOG_TAG, "contacts record get integer failed ");
        +      _free_gl_log_data(gl_log_data);
        +
        +      return NULL;
        +   }
        +   if (CONTACTS_ERROR_NONE != contacts_record_get_int(record, _contacts_phone_log.log_time, &gl_log_data->log_time))
        +   {
        +      dlog_print(DLOG_ERROR, LOG_TAG, "contacts record get integer failed ");
        +      _free_gl_log_data(gl_log_data);
        +
        +      return NULL;
        +   }
        +
        +   return gl_log_data;
        +}
        +
        +
      4. +
      5. After getting the log record, destroy the used structures: +
        +contacts_list_destroy(list, true);
        +
      6. +
      +
    4. +
    5. To get the filtered log record list: +
        +
      1. Use the contacts_db_get_records_with_query() function. +
          +
        1. Create a record list and query: +
          +contacts_list_h list = NULL;
          +contacts_query_h query = NULL;
          +
          +error_code = contacts_query_create(_contacts_phone_log._uri, &query);
          +if (error_code != CONTACTS_ERROR_NONE)
          +   dlog_print(DLOG_ERROR, LOG_TAG, "contacts query create failed: %x", error_code);
          +
          +
        2. + +
        3. Before getting the logs, filter the list. There is a possibility to filter based on various parameters. To create a filter, use the following code: +
          +contacts_filter_h filter = NULL;
          +
          +error_code = contacts_filter_create(_contacts_phone_log._uri, &filter);
          +if (error_code != CONTACTS_ERROR_NONE)
          +   dlog_print(DLOG_ERROR, LOG_TAG, "contacts filter create failed: %x", error_code);
          +
          +
        4. + +
        5. Add a condition, such as the log type. +

          The following example retrieves only those logs which type is CONTACTS_PLOG_TYPE_VOICE_INCOMMING.

          +
          +error_code = contacts_filter_add_int(filter, _contacts_phone_log.log_type, CONTACTS_MATCH_EQUAL, CONTACTS_PLOG_TYPE_VOICE_INCOMMING);
          +if (error_code != CONTACTS_ERROR_NONE)
          +   dlog_print(DLOG_ERROR, LOG_TAG, "contacts filter add integer failed: %x", error_code);
          +
          + +

          To use multiple conditions, add an operator between them:

          +
          +error_code = contacts_filter_add_operator(filter, CONTACTS_FILTER_OPERATOR_OR);
          +if (error_code != CONTACTS_ERROR_NONE)
          +   dlog_print(DLOG_ERROR, LOG_TAG, "contacts filter add operator failed: %x", error_code);
          +error_code = contacts_filter_add_int(filter, _contacts_phone_log.log_type, CONTACTS_MATCH_EQUAL, CONTACTS_PLOG_TYPE_VOICE_OUTGOING);
          +if (error_code != CONTACTS_ERROR_NONE)
          +   dlog_print(DLOG_ERROR, LOG_TAG, "contacts filter add integer failed: %x", error_code);
          +
          +
        6. + +
        7. Connect the query with the list: +
          +error_code = contacts_query_set_filter(query, filter);
          +if (error_code != CONTACTS_ERROR_NONE)
          +   dlog_print(DLOG_ERROR, LOG_TAG, "contacts query set filter failed: %x", error_code);
          +
          +error_code = contacts_db_get_records_with_query(query, 0, 0, &list);
          +if (error_code != CONTACTS_ERROR_NONE)
          +   dlog_print(DLOG_ERROR, LOG_TAG, "contacts db get records with query failed: %x", error_code);
          +
          +

          The third parameter refers to the limit of the results. If 0 is passed, there are no limits. After all operations, release the list.

          +
        8. + +
        9. Free the filter and query: +
          +contacts_filter_destroy(filter);
          +contacts_query_destroy(query);
          +
          +
        10. +
        +
      2. + +
      3. To iterate the list and read the records, use the contacts_list_get_current_record_p(), contacts_list_next(), or contacts_list_prev() function. Get the details of each record in the loop. + + + + + + + + + + + +
        Note
        Some functions have the _p postfix. It means that the returned value must not be freed by the application, as it is a pointer to the data in an existing record.
        + +
        +contacts_record_h record;
        +while (contacts_list_get_current_record_p(list, &record) == CONTACTS_ERROR_NONE)
        +{
        +   int type;
        +   error_code = contacts_record_get_int(record, _contacts_phone_log.log_type, &type);
        +   dlog_print(DLOG_DEBUG, LOG_TAG, "log type: %d", type);
        +
        +   error_code = contacts_list_next(list);
        +   if (error_code != CONTACTS_ERROR_NONE)
        +      break;
        +}
        +
        + +

        To get more details of each record, use the contacts_gl_log_data_t structure:

        +
        +contacts_gl_log_data_t *gl_log_data = NULL;
        +contacts_record_h record;
        +while (contacts_list_get_current_record_p(list, &record) == CONTACTS_ERROR_NONE)
        +{
        +   gl_log_data = _create_gl_log_data(record);
        +
        +   _free_gl_log_data(gl_log_data);
        +   error_code = contacts_list_next(list);
        +   if (error_code != CONTACTS_ERROR_NONE)
        +      break;
        +}
        +
        +

        The memory for the record data is allocated, and the data is copied from the record by the functions listed further on in this document.

        +
        +typedef struct _contacts_gl_log_data
        +{
        +   int id;
        +   char *address;
        +   int log_type;
        +   int log_time;
        +} contacts_gl_log_data_t;
        +
        +static void _free_gl_log_data(contacts_gl_log_data_t *gl_log_data)
        +{
        +   if (NULL == gl_log_data)
        +      return;
        +   free(gl_log_data->address);
        +   free(gl_log_data);
        +}
        +
        +static contacts_gl_log_data_t* _create_gl_log_data(contacts_record_h record)
        +{
        +   contacts_gl_log_data_t *gl_log_data;
        +   int error_code;
        +
        +   gl_log_data = malloc(sizeof(contacts_gl_log_data_t));
        +   memset(gl_log_data, 0x0, sizeof(contacts_gl_log_data_t));
        +
        +   if (CONTACTS_ERROR_NONE != contacts_record_get_int(record, _contacts_phone_log.id, &gl_log_data->id))
        +   {
        +      dlog_print(DLOG_ERROR, LOG_TAG, "contacts record get integer failed ");
        +      _free_gl_log_data(gl_log_data);
        +
        +      return NULL;
        +   }
        +   if (CONTACTS_ERROR_NONE != contacts_record_get_str(record, _contacts_phone_log.address, &gl_log_data->address))
        +   {								
        +      dlog_print(DLOG_ERROR, LOG_TAG, "contacts record get string failed ");
        +      _free_gl_log_data(gl_log_data);
        +
        +      return NULL;
        +   }
        +   if (CONTACTS_ERROR_NONE != contacts_record_get_int(record, _contacts_phone_log.log_type, &gl_log_data->log_type))
        +   {
        +      dlog_print(DLOG_ERROR, LOG_TAG, "contacts record get integer failed ");
        +      _free_gl_log_data(gl_log_data);
        +
        +      return NULL;
        +   }
        +   if (CONTACTS_ERROR_NONE != contacts_record_get_int(record, _contacts_phone_log.log_time, &gl_log_data->log_time))
        +   {
        +      dlog_print(DLOG_ERROR, LOG_TAG, "contacts record get integer failed ");
        +      _free_gl_log_data(gl_log_data);
        +
        +      return NULL;
        +   }
        +
        +   return gl_log_data;
        +}
        +
        +
      4. +
      5. After getting the log record, destroy the used structures. +
        +contacts_list_destroy(list, true);
      6. +
    + +

    Deleting a Log

    + +

    To delete a log, use the contacts_db_delete_record() function with _contacts_phone_log._uri as the first parameter and log ID as the second one:

    +
    +int log_id = ... // Acquire log ID
    +
    +error_code = contacts_db_delete_record(_contacts_phone_log._uri, log_id);
    +if (error_code != CONTACTS_ERROR_NONE)
    +   dlog_print(DLOG_ERROR, LOG_TAG, "contacts db delete record failed: %x", error_code);
    +
    + +

    Inserting New Records

    + +

    To insert a new record:

    + +
      +
    1. Create a record. + +

      The basic concept in the Contacts API is a record. A record can be a complex set of data, containing other data. For example, an address record can contain the country, region, and street. Also, the contained data can be a reference to another record. For example, a contact record contains the address property, which is a reference to an address record. Effectively, a record can be a node in a tree or a graph of relations between records.

      + +

      Each record type has a special view structure, which contains identifiers of its properties. For example, the _contacts_contact view describes the properties of the contact record. It contains properties, such as the name, company, and nickname of the contact. A special property in such structures is the URI, which is used to identify the record type. Every view describing a record has this property.

      + +

      To create a new contact record, create a root record of the _contacts_contact view type:

      + +
      +contacts_record_h hcontact = NULL;
      +
      +error_code = contacts_record_create(_contacts_contact._uri, &hcontact);
      +
      + +

      Creating a group is similar to creating a record. The only difference is using another view – the group view.

      +
    2. + +
    3. Set properties. +

      Set the properties of the newly created record. Almost every property in the contact view is a record itself, so create more records, as needed. The following example shows how to add an address record to a contact.

      + +
        +
      1. Create a new record. +

        Use the address view because the added record is an address:

        + +
        +contacts_record_h haddress = NULL;
        +contacts_record_create(_contacts_address._uri, &haddress);
        +
        +
      2. + +
      3. Set the address record properties (parameters available in the current view): + +
        +contacts_record_set_str(haddress, _contacts_address.country, "Korea");
        +
        +
      4. + +
      5. Add the address record to your contact: + +
        +contacts_record_add_child_record(hcontact, _contacts_contact.address, haddress
        +
        +

        Do not destroy the record handle which is added to another as a child.

        +
      +
    4. + +
    5. Insert records. +

      After setting properties, insert the root record only to the database. You receive the ID of this record in the database.

      + +
      +int id;
      +error_code = contacts_db_insert_record(hcontact, &id);
      +
      +
    6. + +
    7. Clean up. +

      Destroy the record structure.

      + +
      +error_code = contacts_record_destroy(hcontact, true);
      +
      +
    8. +
    + +

    Getting Record Details

    + +

    To find all records and get their details:

    + +
      +
    1. Get a single record. +

      Get a record handle when you know its ID:

      + +
      +contacts_record_h record;
      +const int ID = 2;
      +
      +contacts_db_get_record(_contacts_contact._uri, ID, &record);
      +
      +
    2. + +
    3. Get record details. +

      To get the details, use the contacts_record_get_* function with the record handle. The following example gets the contact display name:

      + +
      +char * d_name;
      +contacts_record_get_str(record, _contacts_contact.display_name, d_name);
      +free(d_name);
      +
      +
    4. + +
    5. Get child record details. +

      When using 1 view, you sometimes need details from another view. For example, you get records using the contact view and need to get the first or last name. If you want to get the name, get the record from the name view using the contacts_db_get_child_record_at_p() function:

      + +
      +contacts_record_h child_record;
      +contacts_record_get_child_record_at_p(record, _contacts_contact.name, 0, &child_record);
      +// In the child_record, you have the record form name view
      +char *f_name;
      +contacts_record_get_str(record, _contacts_name.first_name, f_name);
      +free(f_name);
      +
      +
    6. + +
    7. Get parent record details. +

      When using the child view, you sometimes need to get details of the parent. For example, you get records using the name view and want to know whether the contact has an email address. To get the parent details, get its ID in almost every view with contact_id. After that, get the parent record:

      + +
      +contacts_record_h parent_record;
      +int parent_id;
      +contacts_record_get_int(record, _contacts_name.contact_id, &parent_id);
      +contacts_db_get_child_record(_contacts_contact._uri, parent_id, &parent_record);
      +// In the parent_record, get bool
      +bool h_email;
      +contacts_record_get_bool(parent_record, _contacts_contact.has_email, &h_email);
      +
      +
    8. + +
    9. Get details through a structure. +
      1. For more record details, use a structure to get them.

        +

        The memory for the record data is allocated and the data is copied from the record by functions listed in the following step.

        + +
        +gldata = _create_gl_data(record);
        +char * number = gldata->number;
        +
        +typedef struct _contact_gl_data
        +{
        +   int id;
        +   char *first;
        +   char *last;
        +   char *number;
        +   char *image_path;
        +} contact_gl_data_t;
        +
        +static contact_gl_data_t *_create_gl_data(contacts_record_h r_contact)
        +{
        +   contact_gl_data_t *data;
        +   data = malloc(sizeof(contact_gl_data_t));
        +   memset(data, 0x0, sizeof(contact_gl_data_t));
        +
        +   if (! _get_contact_id(r_contact, &data->id))
        +   {
        +      free(data);
        +
        +      return NULL;
        +   }
        +
        +   if (!_get_contact_number(r_contact, &data->number))
        +   {
        +      free(data);
        +
        +      return NULL;
        +   }
        +   if (!_get_contact_first(r_contact, &data->first))
        +   {
        +      free(data->number);
        +      free(data);
        +
        +      return NULL;
        +   }
        +   if (!_get_contact_last(r_contact, &data->last))
        +   {
        +      free(data->number);
        +      free(data->first);
        +      free(data);
        +
        +      return NULL;
        +   }
        +   if (!_get_contact_image(r_contact, &data->image_path))
        +   {
        +      free(data->number);
        +      free(data->first);
        +      free(data->last);
        +      free(data);
        +
        +      return NULL;
        +   }
        +
        +   return data;
        +}
        +
        +
      2. + +
      3. Retrieve record data into the structure. +

        Contacts are organized in a parent-child structure. To access specified data from a record, get the child responsible for the requested type using the contacts_record_get_child_record_at_p() function (for the property lists, see View/Property). Do not pass any data returned by a function with the _p suffix to the free() function.

        + +
        • To get the name details, get the _contacts_contact.name (representing the child) from the r_contact parent. Both structures have the contacts_record_h type. After obtaining a child record, get the desired data from it using the contacts_record_get_str() function.

          + +
          +static bool _get_contact_last(contacts_record_h r_contact, char **last)
          +{
          +   contacts_record_h r_name;
          +   int error_code;
          +
          +   error_code = contacts_record_get_child_record_at_p(r_contact,  _contacts_contact.name, 0, &r_name);
          +
          +   error_code = contacts_record_get_str(r_name, _contacts_name.last, last);
          +}
          +
        • + +
        • The record ID is obtained directly from the parent record. An ID is a unique number representing the record key in the database. You can manipulate a record with functions, such as contacts_db_get_record() or contacts_db_delete_records(), if you know their ID.

          + +
          +static bool _get_contact_id(contacts_record_h r_contact, int *id)
          +{
          +   int error_code;
          +
          +   error_code = contacts_record_get_int(r_contact, _contacts_contact.id, id);
          +
          +   return true;
          +}
          +
        • + +
        • To get a contact number, check whether it exists using the contacts_record_get_bool() function. If it exists, use the various Query and Filter functions from the Contacts API to make a query to get a list. At the end, free any data returned by a function not containing the _p suffix.

          +
          • Get a list of all numbers and filter the list to get the default: +
            +static bool _get_contact_number(contacts_record_h r_contact, char **number)
            +{
            +   int id;
            +   int error_code;
            +   contacts_record_h r_number;
            +   contacts_query_h query = NULL;
            +   contacts_filter_h filter = NULL;
            +   contacts_list_h list = NULL;
            +
            +   if (!_get_contact_id(r_contact, &id))
            +      return false;
            +
            +
            +   bool has_number;
            +   error_code = contacts_record_get_bool(r_contact, _contacts_contact.has_phonenumber, &has_number);
            +
            +   error_code = contacts_query_create(_contacts_number._uri, &query);
            +
            +   unsigned int fields[] = { _contacts_number.number };
            +   error_code = contacts_query_set_projection(query, fields, 1);
            +
            +   error_code = contacts_filter_create(_contacts_number._uri, &filter);
            +
            +   error_code = contacts_filter_add_int(filter, _contacts_number.contact_id, CONTACTS_MATCH_EXACTLY, id);
            +
            +   error_code = contacts_filter_add_operator(filter, CONTACTS_FILTER_OPERATOR_AND);
            +
            +   error_code = contacts_filter_add_bool(filter, _contacts_number.is_default, true);
            +
            +   error_code = contacts_query_set_filter(query, filter);
            +
            +   error_code = contacts_db_get_records_with_query(query, 0, 1, &list);
            +
            +   error_code = contacts_list_get_current_record_p(list, &r_number);
            +
            +   error_code = contacts_record_get_str(r_number, _contacts_number.number, number);
            +
            +   contacts_query_destroy(query);
            +   contacts_filter_destroy(filter);
            +   contacts_list_destroy(list, true);
            +}
            +
          • + +
          • Directly access the default number:

            + +
            +static bool _get_contact_number(contacts_record_h r_contact, char **number)
            +{
            +   int error_code;
            +   contacts_record_h r_number;
            +
            +   bool has_number;
            +   error_code = contacts_record_get_bool(r_contact, _contacts_contact.has_phonenumber, &has_number);
            +
            +   if (!has_number)
            +   {
            +      *number = NULL;
            +
            +      return true;
            +   }
            +
            +   error_code = contacts_record_get_child_record_at_p(r_contact, _contacts_contact.number, 0, &r_number);
            +
            +   error_code = contacts_record_get_str(r_number, _contacts_number.number, number);
            +
            +   return true;
            +}
            +
            +

            To get a second number, change the third parameter (contacts_record_get_child_record_at_p) from 0 to 1.

        • + + +
        • An image can be obtained directly from the parent record:

          + +
          +static bool _get_contact_image(contacts_record_h r_contact, char **image_path)
          +{
          +   int error_code;
          +
          +   error_code = contacts_record_get_str(r_contact, _contacts_contact.image_thumbnail_path, image_path);
          +
          +   dlog_print(DLOG_ERROR, LOG_TAG, "Thumb path: \'%s\'", *image_path);
          +
          +   return true;
          +}
          +
        • + +
        • Get the first name as the last name:

          + +
          +static bool _get_contact_first(contacts_record_h r_contact, char **first)
          +{
          +   contacts_record_h r_name;
          +   int error_code;
          +
          +   error_code = contacts_record_get_child_record_at_p(r_contact, _contacts_contact.name, 0, &r_name);
          +
          +   error_code = contacts_record_get_str(r_name, _contacts_name.first, first);
          +}
          +
        +
    10. + +
    11. Clean up. +
      1. Destroy the contacts_list_h list.

        +

        When the access to the database is no longer needed, disconnect from the service using the contact_disconnect() function.

        + +
        +error_code = contacts_list_destroy(list, true);
        +
        +error_code = contacts_disconnect();
        +
      2. + +
      3. Destroy all other used handles as well:

        + +
        +contacts_query_destroy(query); // If query has been used
        +contacts_filter_destroy(filter); // If filter has been used
        +
      +
    12. +
    + +

    Handling Lists

    + +

    To access multiple records using lists and contact property filters, and to sort records:

    + +
      +
    1. Get a record list. +
      • To get all records: +

        The following function retrieves all records and returns the result list. After all operations, the list must be released with the contacts_list_destroy() function.

        + +
        +contacts_list_h list = NULL;
        +
        +contacts_db_get_all_records(_contacts_contact._uri, 0, 0, &list);
        +
        +
      • +
      • To filter and get specific records: +
          +
        1. Create a query for a list. +

          To filter or sort records, you need a record list and query:

          + +
          +contacts_list_h list = NULL;
          +contacts_query_h query = NULL;
          +
          +contacts_query_create(_contacts_name._uri, &query);
          +
          +
        2. + +
        3. Create a filter for the query. +

          Before getting contacts, filter the list. It is possible to filter by various parameters, such as the name view.

          + +
          +contacts_filter_h filter = NULL;
          +
          +contacts_filter_create (_contacts_name._uri, &filter);
          +
          + +

          The first parameter defines in which view to place the filter. To filter by the first and last name, use the _contacts_name filter. The first parameter of the contacts_query_create() function must be the same parameter as in the filter to be appended. For more information on views, see the View/Property tables.

        4. + +
        5. Add a condition, such as the following where only contacts beginning with "Za" are shown:

          + +
          +contacts_filter_add_str(filter, _contacts_name.last_name, CONTACTS_MATCH_CONTAINS, "Za");
          +
          + +

          To receive contacts which starts by a given string, the CONTACTS_MATCH_CONTAINS parameter has to be set. Use the parameter if you need to get records which contain the given string anywhere.

        6. + +
        7. To add more conditions, add operators between them. In this case, define the operator between conditions first:

          + +
          +contacts_filter_add_operator(filter, CONTACTS_FILTER_OPERATOR_AND);
          +
          + +

          After that you can add another condition. If you need to use a logic expression "C1 AND (C2 OR C3)", conditions 2 and 3 must be in another filter to have logical brackets. The following example shows a filter that passes through contacts with a first name starting with "Ada" or "Igo":

          + +
          +contacts_filter_h n_filter = NULL;
          +contacts_filter_create (_contacts_name._uri, &n_filter);
          +contacts_filter_add_str(n_filter, _contacts_name.first_name, CONTACTS_MATCH_STARTSWITH, "Ada");
          +contacts_filter_add_operator(n_filter, CONTACTS_FILTER_OPERATOR_OR);
          +contacts_filter_add_str(n_filter, _contacts_name.first_name, CONTACTS_MATCH_STARTSWITH, "Igo”");
          +
        8. + +
        9. To add an extra filter to a parent filter:

          + +
          +contacts_filter_add_filter(filter, n_filter);
          +
          + +

          The parent filter passes through contacts with a last name beginning with "Za" and a first name starting with "Ada" or "Igo".

        10. +
        11. Connect a filter with query:

          + +
          +contacts_query_set_filter(query, filter);
          +
      +
    2. + +
    3. Sort a record list. +

      To sort records by any of its view details:

      + +
      +contacts_query_set_sort(query, _contacts_name.first, true);
      +
      + +

      The first parameter is the query to be filtered, the second is the property to sort, and the last sets the ascending order.

      +
    4. + +
    5. Set a projection to a list. +

      A projection allows you to query the data for specific properties of a record. It can reduce latency in case of a large database.

      +

      To set the projection, use the contacts_query_set_projection() function. The following example limits the properties from the previous steps to the first and last name:

      + +
      +unsigned my_projection[] = {_contacts_name.contact_id, _contacts_name.first, _contacts_name.last}
      +contacts_query_set_projection(query, my_projection, sizeof(my_projection)/sizeof(int));
      +
      + +

      After filtering, such as getting numbers, there can be several records which differ only in a few detail types. When setting the projection, the results can contain identical records. To avoid these situations, use the distinction function:

      + +
      +contacts_query_set_distinct(query, true);
      +
      +
    6. + +
    7. Get the record list with a query. +

      Get the list with the query:

      + +
      +contacts_db_get_records_with_query(query, 0, 0, &list);
      +
      + +

      The third parameter refers to limiting results. If 0 is passed, there are no limits. Release the list after all the operations.

      +
    8. + +
    9. Iterate on the list and read the records. +

      The contacts_list_get_current_record_p() function retrieves a record from the contacts list. The current default record is the first record.

      + +

      To iterate on a list, use the contacts_list_prev(), contacts_list_next(), contacts_list_first(), and contacts_list_last() functions.

      + + + + + + + + + + +
      Note
      Some functions have the _p postfix. It means that the returned value must not be freed by the application, as it is a pointer to data in an existing record.
      + +

      To read records:

      + +
      • To get only a few details: + +
        +contacts_record_h record;
        +
        +while (contacts_list_get_current_record_p(list, &record) == 0)
        +{
        +   // Get details
        +   char * disp_name;
        +   contacts_record_get_str(record, _contacts_contact.display_name, &disp_name);
        +   free(disp_name);
        +   error_code = contacts_list_next(list);
        +}
        +
      • + +
      • To get more details, use the following example, where the obtained records are passed to the _create_gl_data() function for further processing:

        + +
        +contacts_record_h record;
        +contact_gl_data_t *gldata = NULL;
        +
        +while (contacts_list_get_current_record_p(list, &record) == 0)
        +{
        +   gldata = _create_gl_data(record);
        +
        +   error_code = contacts_list_next(list);
        +}
        +
      • + +
      • The previous examples work if you use the default (_contacts_contact) view. If you use filtering in another view as shown in the filter example, and you want to use this structure (change view to default), use the following code:

        + +
        +contacts_record_h record;
        +contact_gl_data_t *gldata = NULL;
        +
        +while (contacts_list_get_current_record_p(list, &record) == 0)
        +{
        +   int record_id;
        +   contacts_record_h c_record;
        +   contacts_record_get_int(record, _contacts_name._uri, &contact_id);
        +   contacts_db_get_record(_contacts_contact._uri, contact_id, &c_record);
        +   gldata = _create_gl_data(c_record);
        +
        +   error_code = contacts_list_next(list);
        +}
        +
        + +

        This way it is possible to switch to the default view from another view (in a similar manner to the above example _contacts_name).

      +
    10. + +
    11. Insert the list to the database. +

      You can insert a whole list to the database. This can be useful when you have several records to create and you want to insert them all at once.

      + +
        +
      1. If you have a list, use it or create a new one: + +
        +contacts_list_h list;
        +contacts_list_create(&list);
        +
        +
      2. + +
      3. Add records to the list: + +
        +contacts_list_add (list, record);
        +
        +
      4. + +
      5. Insert the list into the database: + +
        +int *ids = NULL;
        +unsigned int count = 0;
        +contacts_db_insert_records(list, &ids, &count);
        +dlog_print(DLOG_DEBUG, LOG_TAG, "%d records inserted", count);
        +free(ids);
        +
        + +

        This inserts the entire list to the database and gets the IDs of the inserted records.

        +
      6. + +
      7. Destroy the list: + +
        +contacts_list_destroy(list, true);
        +
        +
      8. +
      +
    12. +
    + +

    Deleting Records

    + +

    To delete records from the contact database, you need to know their ID:

    + +
    +int id;
    +// Get id
    +int error = contacts_db_delete_record(_contacts_contact._uri, id);
    +
    + +

    If you only have the record handle, get the ID first:

    + +
    +contacts_record_get_int(record, _contacts_contact.id, &id);
    +
    + +

    Linking Persons

    + +

    To link persons (a useful joining method if there are several contacts assigned to one person):

    + +
      +
    1. Link a person to another person. +

      To link persons with the contacts_person_link_person() function, you need the person ID. To get the person ID, use the contacts_record_get_int() function.

      + +
      +int first_person_id;
      +contacts_record h record1;
      +// Get the first record
      +int error_code = contacts_record_get_int(record1, _contacts_contact.person_id, &first_person_id);
      +
      +contacts_record h record2;
      +// Get the second record
      +error_code = contacts_record_get_int(record2, _contacts_contact.person_id, &second_person_id);
      +
      +contacts_person_link_person(first_person_id, second_person_id);
      +
      + +

      This links the 2 contacts available through record handles.

      +
    2. + +
    3. Set the default properties. +

      Set the default values from one of the linked contacts with the contacts_person_set_default_property() function. The first parameter determines the detail to be set using the contacts_person_property_e enum.

      + +

      To set a default number from one of the persons, you have to know its ID. Get the detail ID using the contacts_record_get_child_record_at_p() function, because you need to get the value from the _contact_number view.

      + +
      +contacts_record_h record;
      +int record_number = -1;
      +// Get the record handle
      +contacts_record_h record_number;
      +error_code = contacts_record_get_child_record_at_p(record, _contacts_contact.number, 0, &record_number);
      +
      +error_code = contacts_record_get_int(record_number, _contacts_number.id, &number_id);
      +
      +error_code = contacts_record_destroy(record_number, true);
      +
      +// Use the record_number variable
      +error_code = contacts_person_set_default_property(CONTACTS_PERSON_PROPERTY_NUMBER, person_id, number_id);
      +
      +
    4. + +
    5. Get default properties. +

      Get the default property values of a person with the contacts_person_get_default_property() function:

      + +
      1. Get the ID of the default email details:

        + +
        +int person_email_number;
        +error_code = contacts_person_get_default_property (CONTACTS_PERSON_PROPERTY_EMAIL, person_id, &person_email_number);
        +
      2. + +
      3. Get the default email:

        + +
        +int person_email_detail_number;
        +error_code = contacts_person_get_default_property (CONTACTS_PERSON_PROPERTY_EMAIL, person_id, &person_email_number);
        +
        +contacts_record_h email_record;
        +error_code = contacts_db_get_record(_contacts_email._uri, person_email_detail_number, &email_record);
        +char * default_email;
        +
        +error_code = contacts_record_get_str_p(email_record, _contacts_email.email, &default_email);
        +
        +// Use default_email
        +
        +error_code = contacts_record_destroy(email_record, true);
        +
      +
    6. + +
    7. Unlink persons. +

      To unlink a contact using the contacts_person_unlink_contact() function:

      + +
      1. If you have the record handle, get the contact ID:

        + +
        +int person_id;
        +contacts_record_get_int(record, _contacts_contact.id, &person_id);
        +
      2. + +
      3. Unlink a contact from another and get its ID:

        + +
        +int unlinked_person_id;
        +int contacts_person_unlink_contact(person_id,
        +                                   contact_id,
        +                                   &unlinked_person_id)
        +
      +
    8. +
    + +

    Managing Contact Settings

    + +

    To manage the display settings of contacts:

    + +
      +
    1. Get the display and sorting order. +

      Check the current display order (the order in which the names are displayed) using the contacts_setting_get_name_display_order() function, and the sorting order using the contacts_setting_get_name_sorting_order() function:

      + +
      +contacts_name_display_order_e display_order;
      +contacts_setting_get_name_display_order (&display_order);
      +// Now you have the display order
      +sprintf("Display order: %s", display_order==CONTACTS_NAME_DISPLAY_ORDER_FIRSTLAST?"CONTACTS_NAME_DISPLAY_ORDER_FIRSTLAST":"CONTACTS_NAME_DISPLAY_ORDER_LASTFIRST");
      +
      +contacts_name_sorting_order_e sorting_order;
      +contacts_setting_get_name_sorting_order (&sorting_order);
      +// Now you have the sorting order
      +sprintf("Sorting order: %s", sorting_order==CONTACTS_NAME_SORTING_ORDER_FIRSTLAST?"CONTACTS_NAME_SORTING_ORDER_FIRSTLAST":"CONTACTS_NAME_SORTING_ORDER_LASTFIRST");
      +
      +
    2. + +
    3. Change the display and sorting orders. +

      To change the display and sorting orders, use the contacts_setting_set_name_display_order() and contacts_setting_set_name_sorting_order() functions:

      + +
      +contacts_setting_set_name_display_order (CONTACTS_NAME_DISPLAY_ORDER_FIRSTLAST);
      +
      +contacts_setting_set_name_sorting_order (CONTACTS_NAME_SORTING_ORDER_FIRSTLAST);
      +
      +
    4. + +
    5. Track the order changes with callbacks. +

      To track changes in the display and sorting orders:

      +
      1. Register callbacks with the contacts_setting_add_name_display_order_changed_cb() and contacts_setting_add_name_sorting_order_changed_cb() functions.
      2. +
      3. Define the callbacks themselves: +
        +static void display_changed_cb(contacts_name_display_order_e name_display_order, void *user_data)
        +{
        +   dlog_print(DLOG_DEBUG, LOG_TAG, "changed display order: %s", name_display_order==CONTACTS_NAME_DISPLAY_ORDER_FIRSTLAST?"CONTACTS_NAME_DISPLAY_ORDER_FIRSTLAST":"CONTACTS_NAME_DISPLAY_ORDER_LASTFIRST");
        +}
        +
        +static void sorting_changed_cb(contacts_name_sorting_order_e name_display_order, void *user_data)
        +{
        +   dlog_print(DLOG_DEBUG, LOG_TAG, "changed sorting order: %s", name_display_order==CONTACTS_NAME_SORTING_ORDER_FIRSTLAST?"CONTACTS_NAME_SORTING_ORDER_FIRSTLAST":"CONTACTS_NAME_SORTING_ORDER_LASTFIRST");
        +}
        +
        +

        The above examples cause a message to be printed when the order changes. To track the changes, write a timeout function after setting the callback.

      4. +
      5. Unregister the callbacks when they are no longer needed using the contacts_setting_remove_name_display_order_changed_cb() and contacts_setting_remove_name_sorting_order_changed_cb() functions.
      + +
    6. +
    + +

    Managing Contacts on the SIM Card

    + +

    To check whether the SIM card is initialized and then import contacts from the SIM card:

    +
      +
    1. Check whether the SIM card is initialized. +

      Before using any SIM card methods, ensure that the SIM card initialization is complete:

      + +
      +bool completed = false;
      +contacts_sim_get_initialization_status(&completed);
      +dlog_print(DLOG_DEBUG, LOG_TAG, "SIM %s completed", completed?"":"not ");
      +
    2. + +
    3. Import all contacts from the SIM card. +

      When the contacts from the SIM card are available, import them:

      + +
      +int err = contacts_sim_import_all_contacts();
      +
      +
    4. + +
    + +

    Importing from vCard

    + +

    To import contacts from all vCard files from a specified directory:

    + +
      +
    • Get contact records from a stream. +

      To receive a records list from the vCard stream, use the contacts_vcard_parse_to_contacts() function. Afterwards, the received list is ready to use and you can perform the iteration on the list.

      + +

      The following example uses the stream in the vCard format and gets the records from the received list:

      + +
      +char * vcard_stream;
      +// Get vCard stream
      +contacts_list_h contacts_list;
      +int err = contacts_vcard_parse_to_contacts(vcard_stream, contacts_list);
      +
      +while (contacts_list_get_current_record_p(list_import, &record) == 0) 
      +{
      +   // Get next records from file
      +   err = contacts_list_next(list_import);
      +}
      +err = contacts_list_destroy(list_import, true);
      +
      + +

      You can also use the contacts_vcard_parse_to_contact_foreach() function. With this function, you have to get the file content manually, and it needs a callback:

      + +
      +bool contacts_vcard_cb(contacts_record_h record, void *user_data)
      +{
      +   // Here you have a record
      +   return true;
      +}
      +
      + +

      The callback is called for each record from a vCard file. The iteration continues as long as the callback returns true.

      + +

      To check how many records are contained in a vCard file, use the contacts_vcard_get_entity_count() function.

      + +
    • + +
    • Import the vCard stream. +
      • Get all the files with a .vcf extension from the directory. It can be done through dirent structures available in the <dirent.h> header. The following example gets the path to every file in a directory:

        + +
        +int internal_storage_id;
        +char *vcf_path = NULL;
        +
        +static bool 
        +storage_cb(int storage_id, storage_type_e type, storage_state_e state, const char *path, void *user_data)
        +{
        +   if (type == STORAGE_TYPE_INTERNAL)
        +   {
        +      internal_storage_id = storage_id;
        +
        +      return false;
        +   }
        +
        +   return true;
        +}
        +
        +void 
        +_get_storage_path()
        +{
        +   int error_code = 0;
        +   char *path = NULL;
        +
        +   error_code = storage_foreach_device_supported(storage_cb, NULL);
        +   error_code = storage_get_directory(internal_storage_id, STORAGE_DIRECTORY_DOWNLOADS, &path);
        +   if (error_code != STORAGE_ERROR_NONE)
        +   {
        +      vcf_path = strdup(path);
        +      free(path);
        +   }
        +}
        +
        +void 
        +_import_vcard()
        +{
        +   int path_len = 0;
        +
        +   DIR *dir = opendir(vcf_path);
        +   struct dirent *pDirent = NULL;
        +   if (NULL == dir)
        +   {
        +      free(vcf_path);
        +
        +      return;
        +   }
        +
        +   while ((pDirent = readdir(dir)) != NULL)
        +   {
        +      if (pDirent->d_type != DT_REG)
        +         continue;
        +      char *extension = strrchr(pDirent->d_name, '.');
        +      if (!extension || strcmp(extension, ".vcf"))
        +         continue;
        +      char * filepath = malloc(strlen(vcf_path)+strlen(pDirent->d_name)+4);
        +      sprintf(filepath, "%s/%s", vcf_path, pDirent->d_name);
        +        
        +      // Full path to file available through filepath string
        +
        +      free(filepath);
        +   }
        +}
        +
      • + +
      • If you use the contacts_vcard_parse_to_contacts() function, you need to get the file stream manually. The following example shows how to get a records list from a file:

        + +
        +FILE *fp = fopen(filepath, "r");
        +fseek(fp, 0, 2);
        +int bufsize = ftell(fp);
        +rewind(fp);
        +if (bufsize < 1)
        +   return 1;
        +char * vcard_stream = malloc(sizeof(char) * (bufsize));
        +memset(vcard_stream, '\0', sizeof(vcard_stream));
        +if (fp != NULL) 
        +{
        +   char str[200];
        +   while(fgets(str, 200, fp) != NULL)
        +      sprintf(vcard_stream+strlen(vcard_stream), "%s", str);
        +   fclose(fp); 
        +} 
        +else
        +   // Error handling
        +int err = contacts_vcard_parse_to_contacts(vcard_stream, contacts_list);
        +free(vcard_stream);
        +
      • + +
      • You can also use the contacts_vcard_parse_to_contact_foreach() function. It requires a callback and retrieves the file path instead of a file stream:

        + +
        +bool contacts_vcard_cb(contacts_record_h record, void *user_data)
        +{
        +   // Here you have a record
        +   return true;
        +}
        +
        +err = contacts_vcard_parse_to_contact_foreach (filepath, contacts_vcard_cb, NULL);
        +
      • + +
      • Add a record in a callback function:

        + +
        +int id = -1;
        +err = contacts_db_insert_record(record, &id);
        +
      + +

      The following example represents the full code of the previous step:

      + +
      +char []folder = "/path/";
      +contacts_list_h list_import;
      +contacts_record_h record;
      +err = contacts_vcard_parse_to_contacts(content, &list_import);
      +
      +while (contacts_list_get_current_record_p(list_import, &record) == 0) 
      +{
      +   int id = -1;
      +   err = contacts_db_insert_record(record, &id); // Add to list
      +
      +   contacts_list_next(list_import);
      +}
      +
      +DIR *dir = opendir(folder);
      +struct dirent *pDirent = NULL;
      +if (dir) 
      +{
      +   while ((pDirent = readdir(dir)) != NULL) 
      +   {
      +      if (pDirent->d_type != DT_REG)
      +         continue;
      +
      +      char *exte = strrchr(pDirent->d_name, '.');
      +      if (!exte || strcmp(exte, ".vcf"))
      +         continue;
      +      dlog_print(DLOG_DEBUG, LOG_TAG, "file %s", pDirent->d_name);
      +
      +      char * file_path = malloc(strlen(folder)+strlen(pDirent->d_name)+4);
      +      sprintf(file_path, "%s/%s", folder, pDirent->d_name);
      +      int count;
      +      contacts_vcard_get_entity_count(file_path, &count);
      +      // Number of records in file: count
      +      if (count < 1)
      +         continue;
      +
      +      FILE * fp = fopen(file_path, "r");
      +      if (fseek(fp, 0, 2) != 0)
      +         // Error handling
      +      int bufsize = ftell(fp);
      +      rewind(fp);
      +      dlog_print(DLOG_DEBUG, LOG_TAG, "file size: %i", bufsize); 
      +      if (bufsize < 1)
      +         return 1;
      +      char * vcard_stream = malloc(sizeof(char) * (bufsize));
      +      memset(vcard_stream, '\0', sizeof(vcard_stream));
      +      if (fp != NULL) 
      +      {
      +         char str[150];
      +         while(fgets(str, 150, fp) != NULL)
      +            sprintf(vcard_stream+strlen(vcard_stream), "%s", str);
      +         fclose(fp);
      +      } 
      +      else
      +         return 1;
      +      // Import the contacts
      +      contacts_list_h list_import;
      +      err = contacts_vcard_parse_to_contacts(vcard_stream, &list_import);
      +      if (err != 0)
      +         dlog_print(DLOG_ERROR, LOG_TAG, "contacts_vcard_parse_to_contacts failed: %d", err);
      +      free(vcard_stream);
      +      while (contacts_list_get_current_record_p(list_import, &record) == 0) 
      +      {
      +         int id = -1;
      +         err = contacts_db_insert_record(record, &id); // Add to list
      +         if (err != 0)
      +            dlog_print(DLOG_ERROR, LOG_TAG, "contacts_list_add failed");
      +         err = contacts_list_next(list_import);
      +      }
      +      err = contacts_list_destroy(list_import, true);
      +      if (err != 0)
      +      {
      +         dlog_print(DLOG_ERROR, LOG_TAG, "contacts_list_destroy failed: %d", err);
      +      }
      +      free (file_path);
      +   }
      +   closedir(dir);
      +}
      +
      +
    • +
    + +

    Exporting to vCard

    + +

    To export your contacts to a vCard file:

    + +
      +
    1. Export contacts to a file. +
      • To export a contact from the _contacts_contact view to the vCard format, use the contacts_vcard_make_from_contact() function.

      • + + +
      • To export details from the _contacts_person view, use the contacts_vcard_make_from_person() function. If you need to export details from the _contacts_my_profile view, use the contacts_vcard_make_from_my_profile() function.

      + +

      The following example uses the _contacts_contact view, but the use of the other views is the same:

      + +
      +contacts_record_h contact;
      +// Get record to contacts_record_h
      +char *vcard_stream;
      +int err = contacts_vcard_make_from_contact(contact, &vcard_stream);
      +
      +// Stream in vCard format is now in vcard_stream
      +free(vcard_stream);
      +
    2. + +
    3. Write to a file:

      + +
      +FILE * file = fopen("/path/contacts.vcf", "w");
      +fwrite(vcard_stream, 1, strlen(vcard_stream), file);
      +fclose(file);
      +
    + + +

    The following example shows how to get all records from a database and put them into a single file.

    +

    Get the list of all records using the contacts_db_get_all_records() function and the current records using the contacts_list_get_current_record_p() function. Get the vCard stream and write to the file in a while loop:

    + +
    +char file_path[] = "/path/contacts.vcf";
    +contacts_list_h list = NULL;
    +err = contacts_db_get_all_records(_contacts_contact._uri, 0, 0, &list);
    +
    +contacts_record_h record;
    +FILE * file = fopen(file_path, "w");
    +
    +while (contacts_list_get_current_record_p(list, &record) == 0) 
    +{
    +   err = contacts_vcard_make_from_contact(record, &vcard_stream);
    +   // Save to file
    +   fwrite(vcard_stream, 1, strlen(vcard_stream), file);
    +   free(vcard_stream);
    +   err = contacts_list_next(list);
    +}
    +fclose(file);
    +contacts_list_destroy(list, true);
    +
    + + + + +
    + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.tutorials/html/native/social/social_tutorials_n.htm b/org.tizen.tutorials/html/native/social/social_tutorials_n.htm index 0b1f6d4..90f94ee 100644 --- a/org.tizen.tutorials/html/native/social/social_tutorials_n.htm +++ b/org.tizen.tutorials/html/native/social/social_tutorials_n.htm @@ -1,71 +1,71 @@ - - - - - - - - - - - - - Social: Managing Personal Data - - - - - -
    - -

    Social: Managing Personal Data

    - -

    The social tutorials demonstrate how to use the following features in creating Tizen native applications:

    - - -

    The following tutorials apply in mobile applications only:

    - - - - - -
    - -Go to top - - - - - - + + + + + + + + + + + + + Social: Managing Personal Data + + + + + +
    + +

    Social: Managing Personal Data

    + +

    The social tutorials demonstrate how to use the following features in creating Tizen native applications:

    + + +

    The following tutorials apply in mobile applications only:

    + + + + + +
    + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.tutorials/html/native/telephony/telephony_info_tutorial_n.htm b/org.tizen.tutorials/html/native/telephony/telephony_info_tutorial_n.htm index 5725912..19adc11 100644 --- a/org.tizen.tutorials/html/native/telephony/telephony_info_tutorial_n.htm +++ b/org.tizen.tutorials/html/native/telephony/telephony_info_tutorial_n.htm @@ -483,15 +483,15 @@ void tutorial_telephony_modem_get_imei() - diff --git a/org.tizen.tutorials/html/native/telephony/telephony_tutorials_n.htm b/org.tizen.tutorials/html/native/telephony/telephony_tutorials_n.htm index 38e5266..d7f3c5c 100644 --- a/org.tizen.tutorials/html/native/telephony/telephony_tutorials_n.htm +++ b/org.tizen.tutorials/html/native/telephony/telephony_tutorials_n.htm @@ -53,15 +53,15 @@ - diff --git a/org.tizen.tutorials/html/native/ui/animation_event_types_tutorials_n.htm b/org.tizen.tutorials/html/native/ui/animation_event_types_tutorials_n.htm deleted file mode 100644 index 1ead5df..0000000 --- a/org.tizen.tutorials/html/native/ui/animation_event_types_tutorials_n.htm +++ /dev/null @@ -1,73 +0,0 @@ - - - - - - - - - - - - - - Animation and Effect Types: Using Various Effect and Effect Types - - - - - - -
    -

    Animation and Effect Types: Using Various Effect and Effect Types

    - -

    The animation and effect tutorials demonstrate how to create and implement a variety of animation effects in Tizen native applications:

    - - - - - - -
    - -Go to top - - - - - - - diff --git a/org.tizen.tutorials/html/native/ui/basic_tutorial_mn.htm b/org.tizen.tutorials/html/native/ui/basic_tutorial_mn.htm deleted file mode 100644 index b518575..0000000 --- a/org.tizen.tutorials/html/native/ui/basic_tutorial_mn.htm +++ /dev/null @@ -1,297 +0,0 @@ - - - - - - - - - - - - - - Basic: Using Basic Interactions - - - - - - -
    -

    Basic: Using Basic Interactions

    - - -

    This tutorial teaches the basics of UI components interactions. It builds upon the Hello World example.

    - - - - - - - - - - -
    Note
    This feature is supported in mobile applications only.
    - -

    Warm-up

    -

    Become familiar with the Elementary and Evas API basics by learning about:

    - - -

    Using Buttons

    - -

    The basic application code is the same as in the Hello World example.

    - -

    Button Styles

    -

    Basic Text Button

    - -

    To create a text-only button, use the following code.

    -
    Evas_Object* button;
    -
    -button = elm_button_add(box);
    -elm_object_text_set(button, "Click me");
    -evas_object_size_hint_weight_set(button, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
    -evas_object_size_hint_align_set(button, EVAS_HINT_FILL, 0.5);
    -elm_box_pack_end(box, button);
    -evas_object_show(button);
    -
    - -

    Basic Icon Button

    -

    Instead of a button with text, create a button with an icon.

    -
    Evas_Object* button2;
    -Evas_Object* icon2;
    -
    -button2 = elm_button_add(box);
    -icon2 = elm_icon_add(box);
    -elm_image_file_set(icon2, "icon.png", NULL);
    -elm_object_part_content_set(button2, "icon", icon2);
    -evas_object_size_hint_weight_set(button, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
    -evas_object_size_hint_align_set(button, EVAS_HINT_FILL, 0.5);
    -elm_box_pack_end(box, button);
    -evas_object_show(button);
    -
    - -

    Icon and Text Button

    -

    Create buttons with both an icon and a text label.

    -
    Evas_Object* button3;
    -Evas_Object* icon3;
    -button3 = elm_button_add(box);
    -icon3 = elm_icon_add(box);
    -elm_image_file_set(icon, "icon.png", NULL);
    -elm_object_part_content_set(button3, "icon", icon3);
    -elm_object_text_set(button3, "Press me");
    -evas_object_size_hint_weight_set(button, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
    -evas_object_size_hint_align_set(button, EVAS_HINT_FILL, 0.5);
    -elm_box_pack_end(box, button);
    -evas_object_show(button);
    -
    - -

    Disabled Button

    -

    To disable a button so that it is not in use, only shown.

    -
    elm_object_disabled_set(button2, EINA_TRUE);
    -
    - -

    Callbacks

    -

    The Elementary buttons respond to user interactions with several events.

    - -

    Click Event

    -

    The "click" event is the most basic and well-known one. The following code snippet changes the text of a button upon a click event: a press followed by an unpress.

    -
    -static void _button_click_cb(void *data, Evas_Object *button, void *ev) 
    -{
    -   elm_object_text_set(button, "Clicked!");
    -}
    -evas_object_smart_callback_add(button, "clicked", _button_click_cb, NULL);
    -
    - -

    Press/Unpress Events

    -

    The button can respond to the press and unpress events instead of the entire click event.

    -
    static void _button_press_cb(void *data, Evas_Object *button, void *ev) 
    -{
    -   elm_object_text_set(button, "Pressed!");
    -}
    -static void _button_unpress_cb(void *data, Evas_Object *button, void *ev) 
    -{
    -   elm_object_text_set(button, "Unpressed!");
    -}
    -
    -evas_object_smart_callback_add(button3, "pressed", _button_press_cb, NULL);
    -evas_object_smart_callback_add(button3, "unpressed", _button_unpress_cb, NULL);
    -
    - -

    Repeated Events

    -

    The button can receive several events in case it is being held by the user. Timings, such as the initial timeout and the repeat interval, can be set. In this example, the initial timeout is set to 1 second, and the repeat interval to half a second.

    -
    static void _button_repeat_cb(void *data, Evas_Object *button, void *ev) 
    -{
    -   static int count = 0;
    -   char buf[16];
    -
    -   snprintf(buf, sizeof(buf), "Repeat %d", count++);
    -
    -   elm_object_text_set(button, buf);
    -}
    -
    -elm_button_autorepeat_set(button3, EINA_TRUE);
    -elm_button_autorepeat_initial_timeout_set(button3, 1.0);
    -elm_button_autorepeat_gap_timeout_set(button3, 0.5);
    -evas_object_smart_callback_add(button3, "repeated", _button_repeat_cb, NULL);
    -
    - -

    Using Simple Text

    - -

    Basic Text

    -

    To create a label object, use the following code.

    -
    label = elm_label_add(ad->win);
    -elm_object_text_set(label, "My label");
    -evas_object_show(label);
    -
    - -

    Sliding Text

    -

    If your text is too long, set it to slide. The duration of the slide is set to five seconds in the following example. There are several styles available:

    -
      -
    • slide_short: The text stops at an edge, reverts to its initial position and slides again.
    • -
    • slide_long: The text is originally empty. It slides in, all the way to the edge, continues sliding until the label is empty, and loops.
    • -
    • slide_bounce: The text moves backwards after stopping at the edge. In the example, it is set to bounce.
    • -
    - -
    Evas_Object* label;
    -label = elm_label_add(->win);
    -elm_object_text_set(label, "This text is supposed to be really long.");
    -elm_label_slide_set(label, EINA_TRUE);
    -elm_label_slide_duration_set(label, 5.);
    -elm_object_style_set(label, "slide_bounce");
    -evas_object_show(label);
    -
    - -

    If needed, you can use the slide,end event to respond to the moment when the sliding text reaches its end.

    - -

    Marker Text

    -

    A marker is a text that is centered and bold by default. As the default color is white, set the blue color in this example.

    -
    elm_object_style_set(label, "marker");
    -evas_object_color_set(label, 0, 0, 255, 255);
    -
    - -

    Styling the Text

    -

    You can apply basic styles to the text. For a bolded text, do as follows.

    -
    elm_object_text_set(label, "<b>This text is bold.</b>");
    -
    - -

    Using Simple Lists

    - -

    Basic List

    -

    A list is a scrollable container, whose children are selected.

    -
    Evas_Object* list;
    -Evas_Object* icon;
    -list = elm_list_add(ad->win);
    -elm_list_item_append(list, "Text item", NULL, NULL, NULL, NULL);
    -icon = elm_icon_add(ad->win);
    -elm_icon_standard_set(icon, "chat");
    -elm_list_item_append(list, "Second item", icon, NULL, NULL, NULL);
    -Evas_Object* button;
    -button = elm_button_add();
    -elm_object_text_set(button, "Button");
    -elm_list_item_append(list, "Fourth item", NULL, button, NULL, NULL);
    -elm_list_go(list);
    -
    - -

    Any Evas Object can be added as an icon, either at the beginning (third parameter) or the end (fourth parameter).

    - -

    List Orientation

    -

    By default, a list is set vertically. This is how to display it horizontally.

    -
    elm_list_horizontal_set(list, EINA_TRUE);
    -
    - -

    List Mode

    -

    There are several modes for the list item dimensions.

    -
      -
    • ELM_LIST_COMPRESS: The list does not set any size measures to inform the container how to resize it. If the list is not created as a "resize object", its dimensions are zeroed. The list respects the container's geometry and if any of the list items do not fit into the container transverse axis, the list does not scroll in that direction.
    • -
    • ELM_LIST_SCROLL: This is the default value. This list is the same as ELM_LIST_COMPRESS, with the exception that if any of the list items do not fit into the container transverse axis, the list still scrolls in that direction.
    • -
    • ELM_LIST_LIMIT: This list sets a minimum size measure on the list object, so that containers may respect it (and resize themselves to fit the child properly). More specifically, a minimum size measure is set for its transverse axis, so that the largest item in that direction fits well. This feature is bound by the list object's maximum size measures that are set externally.
    • -
    • ELM_LIST_EXPAND: Besides setting a minimum size on the transverse axis, as in ELM_LIST_LIMIT, this list sets a minimum size on the longitudinal axis to reserve space for all its children to be visible at the same time. This feature is bound by the list object's maximum size measures that are set externally.
    • -
    -
    elm_list_mode_set(list, ELM_LIST_COMPRESS);
    -
    - -

    Scroller Policy

    -

    Several effects are shown on a list.

    -

    For example, the scroller is set to bounce at the end on either direction.

    -
    elm_scroller_bounce_set(list, EINA_TRUE, EINA_TRUE);
    -
    - - -

    This is how to control displaying scrollbars. The second argument is for the horizontal axis, the third one for the vertical axis.

    -
    elm_scroller_policy_set(list, ELM_SCROLLER_POLICY_AUTO, ELM_SCROLLER_POLICY_ON);
    -
    - -

    As for the bounce preference, the second argument is for the horizontal axis, the third one for the vertical axis.

    -
      -
    • ELM_SCROLLER_POLICY_OFF hides the scrollbar
    • -
    • ELM_SCROLLER_POLICY_ON shows the scrollbar
    • -
    • ELM_SCROLLER_POLICY_AUTO the scrollbar is shown only when needed and stays hidden at other times
    • -
    - -

    Events

    -

    A list responds to several events:

    -
      -
    • activated: The user clicks or presses an item.
    • -
    • selected: The user selects an item.
    • -
    • unselected: The user unselects an item.
    • -
    • longpressed: The user long-presses an item.
    • -
    • edge,top: The user scrolls the list to the top edge.
    • -
    • edge,bottom: The user scrolls the list to the bottom edge.
    • -
    • edge,left: The user scrolls the list to the left edge.
    • -
    • edge,right: The user scrolls the list to the right edge.
    • -
    • highlighted: An item is pressed and highlighted.
    • -
    • unhighlighted: The press and highlight is removed on an item.
    • -
    - - - - -
    - -Go to top - - - - - - - diff --git a/org.tizen.tutorials/html/native/ui/button_tutorial_wn.htm b/org.tizen.tutorials/html/native/ui/button_tutorial_wn.htm deleted file mode 100644 index f7fcf7c..0000000 --- a/org.tizen.tutorials/html/native/ui/button_tutorial_wn.htm +++ /dev/null @@ -1,240 +0,0 @@ - - - - - - - - - - - - - - Button: Using Buttons - - - - - - -
    -

    Button: Using Buttons

    - - -

    This tutorial teaches the basics of the button component interactions.

    - - - - - - - - - - -
    Note
    This feature is supported in wearable applications only.
    - -

    Warm-up

    -

    Become familiar with the Button API basics by learning about:

    - - -

    Initializing the Button Application

    - -

    This use case creates an application with a window entitled "Button Basic Tutorial". The window consists of a box component, and a button is placed inside the box.

    - -

    To create a typical elementary application:

    -
    -static void
    -create_base_gui(appdata_s *ad) 
    -{
    -   // Window
    -   Evas_Object *btn1, *btn2, *btn3;
    -
    -   ad->win = elm_win_util_standard_add("main", "Button Basic Tutorial");
    -   elm_win_autodel_set(ad->win, EINA_TRUE);
    -
    -   evas_object_smart_callback_add(ad->win, "delete,request", win_delete_request_cb, NULL);
    -   eext_object_event_callback_add(ad->win, EEXT_CALLBACK_BACK, win_back_cb, ad);
    -
    -   ad->box = elm_box_add(ad->win);
    -   evas_object_size_hint_weight_set(ad->box, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
    -   evas_object_show(ad->box);
    -   elm_win_resize_object_add(ad->win, ad->box);
    -
    -   create_button(ad->box);
    -
    -   // Show the window after the base GUI is set up
    -   evas_object_show(ad->win);
    -}
    -
    -static bool
    -app_create(void *data)
    -{
    -   appdata_s *ad = data;
    -   create_base_gui(ad);
    -
    -   return true;
    -}
    -
    -int
    -main(int argc, char **argv)
    -{
    -   struct app_data ad = {0,};
    -   ui_app_lifecycle_callback_s event_callback = {0,};
    -
    -   event_callback.create = app_create;
    -
    -   return ui_app_main(&argc, &argv, &event_callback, &ad);
    -}
    - - -

    Using Button Styles

    - -

    The basic application code is the same as in the Hello World example.

    - -

    To use various button styles:

    - -
    1. To create buttons using various styles:

      - -
      • Create a basic text-only button: - -
        Evas_Object* button;
        -
        -button = elm_button_add(box);
        -elm_object_text_set(button, "Click me");
        -evas_object_size_hint_weight_set(button, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
        -evas_object_size_hint_align_set(button, EVAS_HINT_FILL, 0.5);
        -elm_box_pack_end(box, button);
        -evas_object_show(button);
        -
      • - -
      • Create a basic icon button (no text, just an icon): -
        Evas_Object* button2;
        -Evas_Object* icon2;
        -
        -button2 = elm_button_add(box);
        -icon2 = elm_icon_add(box);
        -elm_image_file_set(icon2, "icon.png", NULL);
        -elm_object_content_set(button2, icon2);
        -evas_object_size_hint_weight_set(button2, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
        -evas_object_size_hint_align_set(button2, EVAS_HINT_FILL, 0.5);
        -elm_box_pack_end(box, button2);
        -evas_object_show(button2);
        -
      • - -
      • Create a button with both an icon and a text label: -
        Evas_Object* button3;
        -Evas_Object* icon3;
        -button3 = elm_button_add(box);
        -icon3 = elm_icon_add(box);
        -elm_image_file_set(icon3, "icon.png", NULL);
        -elm_object_content_set(button3, icon3);
        -elm_object_text_set(button3, "Press me");
        -evas_object_size_hint_weight_set(button3, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
        -evas_object_size_hint_align_set(button3, EVAS_HINT_FILL, 0.5);
        -elm_box_pack_end(box, button3);
        -evas_object_show(button3);
        -
      • -
    2. -
    3. To disable a button so that it is not in use, only shown:

      -
      elm_object_disabled_set(button2, EINA_TRUE);
      -
    - -

    Managing Button Events

    -

    The Elementary buttons respond to user interactions with several events.

    -

    To manage button events:

    - -
      -
    • Handle click events: -

      The "click" event is the most basic and well-known one. The following code snippet changes the text of a button upon a click event: a press followed by an unpress.

      -
      -static void _button_click_cb(void *data, Evas_Object *button, void *ev) 
      -{
      -   elm_object_text_set(button, "Clicked!");
      -}
      -evas_object_smart_callback_add(button, "clicked", _button_click_cb, NULL);
      -
    • - -
    • Handle press and unpress events: -

      The button can respond to the separate press and unpress events instead of the entire click event.

      -
      static void _button_press_cb(void *data, Evas_Object *button, void *ev) 
      -{
      -   elm_object_text_set(button, "Pressed!");
      -}
      -static void _button_unpress_cb(void *data, Evas_Object *button, void *ev) 
      -{
      -   elm_object_text_set(button, "Unpressed!");
      -}
      -
      -evas_object_smart_callback_add(button3, "pressed", _button_press_cb, NULL);
      -evas_object_smart_callback_add(button3, "unpressed", _button_unpress_cb, NULL);
      -
    • - -
    • Handle repeated events: -

      The button can receive several events in case it is being held by the user. Timings, such as the initial timeout and the repeat interval, can be set. In this example, the initial timeout is set to 1 second, and the repeat interval to half a second.

      -
      static void _button_repeat_cb(void *data, Evas_Object *button, void *ev) 
      -{
      -   static int count = 0;
      -   char buf[16];
      -
      -   snprintf(buf, sizeof(buf), "Repeat %d", count++);
      -
      -   elm_object_text_set(button, buf);
      -}
      -
      -elm_button_autorepeat_set(button3, EINA_TRUE);
      -elm_button_autorepeat_initial_timeout_set(button3, 1.0);
      -elm_button_autorepeat_gap_timeout_set(button3, 0.5);
      -evas_object_smart_callback_add(button3, "repeated", _button_repeat_cb, NULL);
      -
    - - - - - -
    - -Go to top - - - - - - - diff --git a/org.tizen.tutorials/html/native/ui/circle_components_tutorial_wn.htm b/org.tizen.tutorials/html/native/ui/circle_components_tutorial_wn.htm deleted file mode 100644 index 8ca2a27..0000000 --- a/org.tizen.tutorials/html/native/ui/circle_components_tutorial_wn.htm +++ /dev/null @@ -1,176 +0,0 @@ - - - - - - - - - - - - - - Circle Components: Creating a Circular View - - - - - - -
    - -

    Circle Components: Creating a Circular View

    - - -

    This tutorial demonstrates how you can create a circular view with circle UI components, or circle components, which are supported by EFL Extension library. Additionally, you learn how to make your application to operate with rotary events. You need to test your application with a circular device or an emulator with circular display which has a rotary device in it.

    - - - - - - - - - -
    Note
    This feature is supported in wearable applications only.
    - -

    Warm-up

    -

    Become familiar with the Efl Extension circle component basics by learning about:

    - - -

    Creating the Circle Surface

    - -

    Figure: An application view with Circle Slider

    -

    Circle Slider

    - -

    To show the circular UI of circle components, circle surface (Eext_Circle_Surface type) object is needed. The surface object can be connected with several circle components to manage the display. The following code shows how to create a surface object in an elementary naviframe component.

    -
    -Evas_Object *naviframe;
    -Eext_Circle_Surface * surface;
    -
    -naviframe = elm_naviframe_add(parent);
    -evas_object_show(naviframe);
    -
    -surface = eext_circle_surface_naviframe_add(naviframe);
    -
    - -

    Creating the Circle Components

    -

    EFL Extension supports several circle components which operate with rotary events. There circle components are responsible for circular UI which fits with circular display.

    -

    To create the circle components:

    -
      -
    • Create the circle slider. -

      The circle slider provides a circular UI and operates with rotary events to change its value. After calling eext_rotary_object_event_activated_set to the circle slider, every rotary event changes its value with step 0.5.

      -
      -Evas_Object* slider;
      -
      -slider = eext_circle_object_slider_add(parent, surface);
      -eext_circle_object_slider_step_set(slider, 0.5);
      -eext_rotary_object_event_activated_set(slider, EINA_TRUE);
      -
      -
    • - -
    • Create the circle progressbar. -

      The circle progressbar provides a circular UI only. Its design can be changed by eext_circle_object APIs.

      -
      -Evas_Object* progressbar;
      -
      -progressbar = eext_circle_object_progressbar_add(parent, surface);
      -eext_circle_object_value_min_max_set(progressbar, 0.0, 100.0);
      -eext_circle_object_value_set(progressbar, 50);
      -evas_object_show(progressbar);
      -
      -
    • - -
    • Create the circle scroller. -

      The circle scroller provides a circular scroll bar UI to an elementary scroller and operates with rotary events to scroll its content. After calling eext_rotary_object_event_activated_set to the circle scroller, every rotary event moves its content following the scroll direction.

      -
      -Evas_Object* scroller;
      -Evas_Object* circle_scroller;
      -
      -scroller = elm_scroller_add(parent);
      -elm_object_content_set(parent, scroller);
      -
      -circle_scroller = eext_circle_object_scroller_add(scroller, surface);
      -eext_circle_object_scroller_policy_set(circle_scroller, ELM_SCROLLER_POLICY_OFF, ELM_SCROLLER_POLICY_AUTO);
      -eext_rotary_object_event_activated_set(circle_scroller, EINA_TRUE);
      -
      -
    • - -
    • Create the circle genlist. -

      The circle genlist provides circular scroll bar UI to an elementary genlist and operates with rotary events to move to the next or the previous item. After calling eext_rotary_object_event_activated_set to the circle genlist, every rotary event shows the next or the previous item.

      -
      -Evas_Object* genlist;
      -Evas_Object* circle_genlist;
      -
      -genlist = elm_genlist_add(parent);
      -elm_object_content_set(parent, genlist);
      -
      -circle_genlist = eext_circle_object_genlist_add(genlist, surface);
      -eext_circle_object_genlist_scroller_policy_set(circle_genlist, ELM_SCROLLER_POLICY_OFF, ELM_SCROLLER_POLICY_AUTO);
      -eext_rotary_object_event_activated_set(circle_genlist, EINA_TRUE);
      -
      -
    • - -
    • Create the circle datetime. -

      The circle datetime provides a circular UI which is proper to each date or time field of the elementary datetime and operates with rotary events to change its value. After calling eext_rotary_object_event_activated_set to circle datetime, every rotary event changes the value of each date or time field.

      -
      -Evas_Object* datetime;
      -Evas_Object* circle_datetime;
      -
      -datetime = elm_datetime_add(parent);
      -elm_datetime_format_set(datetime, "%d/%b/%Y%I:%M%p");
      -elm_object_content_set(parent, datetime);
      -
      -circle_datetime = eext_circle_object_datetime_add(datetime, surface);
      -eext_rotary_object_event_activated_set(circle_datetime, EINA_TRUE);
      -
      -
    • -
    - - - - - -
    - -Go to top - - - - - - - diff --git a/org.tizen.tutorials/html/native/ui/datetime_tutorial_wn.htm b/org.tizen.tutorials/html/native/ui/datetime_tutorial_wn.htm deleted file mode 100644 index 9ff654a..0000000 --- a/org.tizen.tutorials/html/native/ui/datetime_tutorial_wn.htm +++ /dev/null @@ -1,118 +0,0 @@ - - - - - - - - - - - - - - Datetime: Using Datetime - - - - - - -
    -

    Datetime: Using Datetime

    - - -

    This tutorial explains how you can create UI components that allow the user to select a date or time.

    - - - - - - - - - - -
    Note
    This feature is supported in wearable applications only.
    - -

    Warm-up

    -

    Become familiar with the Datetime API basics by learning about:

    - - -

    Creating a Date Picker

    - -

    Use the elm_datetime component to add a date picker style (Year : Month : Day).

    -

    The following example creates the datepicker-styled Datetime and adds it in the conform.

    - -
    -// Add a datepicker style Datetime component
    -datetime = elm_datetime_add(ad->win);
    -evas_object_size_hint_align_set(datetime, EVAS_HINT_FILL, 0.5);
    -evas_object_size_hint_weight_set(datetime, EVAS_HINT_EXPAND, 1.0);
    -elm_object_style_set(datetime, "datepicker_layout");
    -evas_object_show(datetime);
    -
    -elm_object_content_set(ad->conform, datetime);
    -
    - -

    Creating a Time Picker

    -

    Use the elm_datetime component to add a time picker style (Hour(12) : Min : AM/PM, or Hour(24) : Min).

    -

    The following example creates the timepicker-styled Datetime and adds it in the conform.

    - -
    -// Add a timepicker style Datetime component
    -datetime = elm_datetime_add(ad->win);
    -evas_object_size_hint_align_set(datetime, EVAS_HINT_FILL, 0.5);
    -evas_object_size_hint_weight_set(datetime, EVAS_HINT_EXPAND, 1.0);
    -elm_object_style_set(datetime, "timepicker_layout");
    -evas_object_show(datetime);
    -
    -elm_object_content_set(ad->conform, datetime);
    -
    - - - - - -
    - -Go to top - - - - - - - diff --git a/org.tizen.tutorials/html/native/ui/ecore_effects_tutorial_n.htm b/org.tizen.tutorials/html/native/ui/ecore_effects_tutorial_n.htm deleted file mode 100644 index 623195c..0000000 --- a/org.tizen.tutorials/html/native/ui/ecore_effects_tutorial_n.htm +++ /dev/null @@ -1,438 +0,0 @@ - - - - - - - - - - - - - - Ecore Animator: Creating Ecore Animations - - - - - - -
    -

    Ecore Animator: Creating Ecore Animations

    - - -

    This tutorial demonstrates how you can use Ecore animators to simplify the creation of animations. Using Ecore animators, you can manually create your own animations by changing and manipulating Evas object attributes. Ecore animators work like timers, running callback functions over a given duration (an animation timeline).

    - - -

    Warm-up

    -

    Become familiar with the Ecore, Elementary, and Evas API basics by learning about:

    - - -

    Setting Up the Application

    - -

    In this part of the tutorial, we create a simple application that manipulates and animates an Evas object. We use a "Basic UI Application" as the basis for the application.

    -

    First, we set up the UI components we are going to use in the application:

    - -
    typedef struct appdata 
    -{
    -   // Main window
    -   Evas_Object *win;
    -   // Application title
    -   Evas_Object *label;
    -
    -   // Buttons
    -   Evas_Object *bt1;
    -   Evas_Object *bt2;
    -   Evas_Object *bt3;
    -
    -   // Animation target
    -   Evas_Object *target;
    -} appdata_s;
    -
    - -

    We then create the actual UI components in the create_base_gui() function, starting with the main window and application title:

    - -
    // Main window
    -ad->win = elm_win_util_standard_add(PACKAGE, PACKAGE);
    -elm_win_autodel_set(ad->win, EINA_TRUE);
    -
    -if (elm_win_wm_rotation_supported_get(ad->win)) 
    -{
    -   int rots[4] = { 0, 90, 180, 270 };
    -   elm_win_wm_rotation_available_rotations_set(ad->win, (const int *)(&rots), 4);
    -}
    -
    -evas_object_smart_callback_add(ad->win, "delete,request", win_delete_request_cb, NULL);
    -
    -// Application title
    -ad->label = elm_label_add(ad->win);
    -elm_object_text_set(ad->label, "Ecore Animator Tutorial");
    -evas_object_size_hint_weight_set(ad->label, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
    -elm_win_resize_object_add(ad->win, ad->label);
    -evas_object_show(ad->label);
    -
    - -

    Next, we create the animation target, which is an Evas object of type Elm_Image. The image that is used in the source code is stored in the res/images folder of the application. The image that is used in the EDC file is stored in the edje/images folder.

    - -
    // Animation target
    -// Setting the image path
    -char buf[PATH_MAX];
    -snprintf(buf, sizeof(buf), "/opt/usr/apps/%s/res/images/tizen-logo.png", PACKAGE);
    -// Adding the image
    -ad->target = elm_image_add(ad->win);
    -// Setting the image path
    -if (!elm_image_file_set(ad->target, buf, NULL))
    -   printf("error: could not load image \"%s\"\n", buf);
    -evas_object_size_hint_weight_set(ad->target, EVAS_HINT_FILL, EVAS_HINT_FILL);
    -// Moving the image
    -evas_object_move(ad->target, 130, 100);
    -// Resizing the image
    -evas_object_resize(ad->target, 200, 100);
    -// Showing the image
    -evas_object_show(ad->target);
    -
    - -

    All images are available in the /opt/usr/apps/<PACKAGE_NAME>/res/images folder of the application. The package name is defined at the begin of the application code:

    - -
    #if !defined(PACKAGE)
    -#define PACKAGE "org.tizen.ecoreanimator"
    -#endif
    -
    - -

    The image path is set by calling the elm_image_file_set() function. This function takes as arguments the ad->target Evas object and the path of the image file, built with the snprintf() function and stored in a buffer.

    - -
    // Setting the image path
    -char buf[PATH_MAX];
    -snprintf(buf, sizeof(buf), "/opt/usr/apps/%s/res/images/tizen-logo.png", PACKAGE);
    -// Adding the image
    -ad->target = elm_image_add(ad->win);
    -// Setting the image path
    -if (!elm_image_file_set(ad->target, buf, NULL))
    -   printf("error: could not load image \"%s\"\n", buf);
    -evas_object_size_hint_weight_set(ad->target, EVAS_HINT_FILL, EVAS_HINT_FILL);
    -
    - -

    The remaining code moves and resizes the image:

    - -
    //Moving the image
    -evas_object_move(ad->target, 130, 100);
    -//Resizing the image
    -evas_object_resize(ad->target, 200, 100);
    -//Showing the image
    -
    - -

    Creating a Rotation Effect

    - -

    After the animation target is created, we can create the first button and the associated rotation animation:

    - -
    // Button 1
    -ad->bt1 = elm_button_add(ad->win);
    -elm_object_text_set(ad->bt1, "Rotate");
    -evas_object_size_hint_weight_set(ad->bt1, EVAS_HINT_FILL, EVAS_HINT_FILL);
    -evas_object_move(ad->bt1, 25, 0);
    -evas_object_resize(ad->bt1, 90, 70);
    -evas_object_smart_callback_add(ad->bt1, "clicked", _btn_rotate_cb, ad);
    -evas_object_show(ad->bt1);
    -
    - -

    We create the button for triggering the rotation effect. The button is placed and resized, and associated with the _btn_rotate_cb() callback function. This callback function calls the animation on the animation target.

    - -
    static void _btn_rotate_cb(void *data, Evas_Object *btn, void *ev)
    -{
    -   appdata_s *ad = data;
    -
    -   ecore_animator_timeline_add(1, _do_rotate, ad->target);
    -}
    -
    - -

    In this callback function, we create an Ecore animator timeline using the ecore_animator_timeline_add() function. This function adds an animator that runs for a limited time: we run the _do_rotate() animation callback function for 1 second on the ad->target Evas object.

    - -

    Next, we write the animation callback function that actually runs the animation. This callback is an Ecore_Timeline_Cb function, meaning it returns an Eina_Bool value and takes as arguments some data and the current position along the animation timeline (pos).

    - -

    To create the rotation animation, we use an Evas Map. The map handles the necessary map points and allows you to manipulate the target Evas object on the X, Y, and Z axes.

    - -
    static Eina_Bool
    -_do_rotate(void *data, double pos)
    -{
    -   // Get the animation target
    -   Evas_Object *obj = data;
    -   // Declaration of an `Evas_Map`
    -   Evas_Map *m;
    -   // Variables to store the target size and position
    -   int x, y, w, h;
    -
    -   // Getting the size and position of the target
    -   evas_object_geometry_get(obj, &x, &y, &w, &h);
    -   // Creation of an `Evas_Map` of 4 points
    -   m = evas_map_new(4);
    -   // Populate source and destination map points to match exactly object.
    -   evas_map_util_points_populate_from_object(m, obj);
    -   // Create a rotation of 360° with x+(w/2) "x" center and y +(h/2) "y" center.
    -   evas_map_util_rotate(m, 360.0 * pos, x + (w / 2), y + (h / 2));
    -   // Setting the object to "animate" in the `Evas_Map`
    -   evas_object_map_set(obj, m);
    -   // Starting the Animation
    -   evas_object_map_enable_set(obj, EINA_TRUE);
    -   // Free used memory
    -   evas_map_free(m);
    -
    -   return EINA_TRUE;
    -}
    -
    - -

    In the animation callback function, we first declare the Evas Map. To implement the rotation, we need to set an X and Y center, so we create 4 integer variables to store the size and position of the target. This information is provided by the evas_object_geometry_get() function, which returns the X and Y coordinates and the weight and height of the target Evas object. Now we have all the required data to build the animation.

    - -

    We create an Evas Map consisting of four points, and we populate these points with the animation target:

    - -
    // Creation of an Evas_Map of 4 points
    -m = evas_map_new(4);
    -// Populate source and destination map points to match the object.
    -evas_map_util_points_populate_from_object(m, obj);
    -
    - -

    Now we can define the rotation using the evas_map_util_rotate() function:

    - -
    // Create a rotation of 360° with x+(w/2) "x" center and y +(h/2) "y" center.
    -evas_map_util_rotate(m, 360.0 * pos, x + (w / 2), y + (h / 2));
    -
    - -

    The animation callback function will be called at several points along the timeline, which is why we multiply the rotation angle (360°) by the timeline position (pos) to get the actual animation angle. If we do not do this, we will never see the animation take place. We then join the target object to the map and run the animation:

    - -
    // Setting the object to "animate" in the Evas Map
    -evas_object_map_set(obj, m);
    -// Starting the Animation
    -evas_object_map_enable_set(obj, EINA_TRUE);
    -
    - -

    Each call to the animation callback function will rotate the object (360 * timeline position) degrees.

    - -

    Finally, we free up the memory allocated to the Evas Map:

    - -
    // Free used memory
    -evas_map_free(m);
    -
    - -

    Creating a Zoom Effect

    - -

    The next animation is a zoom, for which we also use an Evas Map.

    - -

    First, we create the button in the create_base_gui() function:

    - -
    // Button 2
    -ad->bt2 = elm_button_add(ad->win);
    -elm_object_text_set(ad->bt2, "Zoom");
    -evas_object_size_hint_weight_set(ad->bt2, EVAS_HINT_FILL, EVAS_HINT_FILL);
    -evas_object_move(ad->bt2, 315, 0);
    -evas_object_resize(ad->bt2, 90, 70);
    -evas_object_smart_callback_add(ad->bt2, "clicked", _btn_zoom_cb, ad);
    -evas_object_show(ad->bt2);
    -
    - -

    We then create the button callback function with a new timeline:

    - -
    static void _btn_zoom_cb(void *data, Evas_Object *btn, void *ev)
    -{
    -   appdata_s *ad = data;
    -
    -   ecore_animator_timeline_add(1, _do_zoom, ad->target);
    -}
    -
    - -

    Next, we create the _do_zoom() animation callback function, which is almost identical to the _do_rotate() callback function, except that we use the evas_map_util_zoom() function to create the animation:

    - -
    static Eina_Bool
    -_do_zoom(void *data, double pos)
    -{
    -   Evas_Object *obj = data;
    -   Evas_Map *m;
    -   int x, y, w, h;
    -
    -   evas_object_geometry_get(obj, &x, &y, &w, &h);
    -   m = evas_map_new(4);
    -   evas_map_util_points_populate_from_object(m, obj);
    -   evas_map_util_zoom(m, 2 * pos, 2 * pos, x , y);
    -   evas_object_map_set(obj, m);
    -   evas_object_map_enable_set(obj, EINA_TRUE);
    -   evas_map_free(m);
    -
    -   return EINA_TRUE;
    -}
    -
    - -

    The evas_map_util_zoom() function takes the following arguments:

    - -
      -
    • The map to change
    • -
    • The horizontal zoom factor
    • -
    • The vertical zoom factor
    • -
    • The horizontal position (X coordinate) of the zooming center
    • -
    • The vertical position (Y coordinate) of the zooming center
    • -
    - -

    Here, we use a horizontal and vertical zoom factor of 2, and the X and Y coordinates of the target as the horizontal and vertical center coordinates.

    - -

    The _do_zoom() callback function is called at several points along the animation timeline, which is why we multiply the horizontal and vertical zoom factor values by the timeline position. Each call will zoom more than the previous one, thereby creating the animation effect.

    - -

    Creating a 3D Rotation Effect

    - -

    The last animation is a 3D rotation. For this one, we are going to rotate the Evas object on all three axes (X, Y, Z).

    - -

    First, we create the button and its callback function:

    - -
    // Button 3
    -ad->bt3 = elm_button_add(ad->win);
    -elm_object_text_set(ad->bt3, "3D");
    -evas_object_size_hint_weight_set(ad->bt3, EVAS_HINT_FILL, EVAS_HINT_FILL);
    -evas_object_move(ad->bt3, 170, 0);
    -evas_object_resize(ad->bt3, 90, 70);
    -evas_object_smart_callback_add(ad->bt3, "clicked", _btn_3d_cb, ad);
    -evas_object_show(ad->bt3);
    -
    - -
    static void _btn_3d_cb(void *data, Evas_Object *btn, void *ev)
    -{
    -   appdata_s *ad = data;
    -
    -   ecore_animator_timeline_add(1, _do_3d, ad->target);
    -}
    -
    - -

    Next, we create the _do_3d() animation callback function, which is very similar to the rotate and zoom callback functions. To create the animation, we use the evas_map_util_3d_rotate() function, which allows you to rotate any Evas object on all three axes.

    - -
    static Eina_Bool
    -_do_3d(void *data, double pos)
    -{
    -   Evas_Object *obj = data;
    -   Evas_Map *m;
    -   int x, y, w, h;
    -
    -   evas_object_geometry_get(obj, &x, &y, &w, &h);
    -   m = evas_map_new(4);
    -   evas_map_util_points_populate_from_object(m, obj);
    -   evas_map_util_3d_rotate(m, pos * 360, pos * 360, pos * 360, x + (w / 3), y + 60, 0);
    -   evas_object_map_set(obj, m);
    -   evas_object_map_enable_set(obj, EINA_TRUE);
    -   evas_map_free(m);
    -
    -   return EINA_TRUE;
    -}
    -
    - -

    The evas_map_util_3d_rotate() function takes the following arguments:

    - -
      -
    • The map to change
    • -
    • The angle (0-360°) to rotate around the X axis
    • -
    • The angle (0-360°) to rotate around the Y axis
    • -
    • The angle (0-360°) to rotate around the Z axis
    • -
    • The X coordinate of the rotation center
    • -
    • The Y coordinate of the rotation center
    • -
    • The Z coordinate of the rotation center
    • -
    - -

    Here, we rotate 360 degrees around each axis. The horizontal (X) rotation center is the X position of the target plus its width divided by 2. The vertical (Y) rotation center is the Y position of the target plus 60. The Z rotation center is 0.

    - -

    As with the rotation and zoom animations, we multiply the angles by the timeline position to gently rotate the target on each call to the _do_3d() callback function along the timeline.

    - -

    Creating Drop and Bounce Effects

    - -

    To finish, we add drop and bounce effects to our buttons at application start. To do this, we create one timeline per button after creating the buttons in the create_base_gui() function:

    - -
    ecore_animator_timeline_add(2, _do_drop, ad->bt1);
    -ecore_animator_timeline_add(2.3, _do_drop, ad->bt2);
    -ecore_animator_timeline_add(2.5, _do_drop, ad->bt3);
    -
    - -

    We call the same _do_drop() animation callback function for each timeline. In this callback, instead of using an Evas Map, we simply change the position of the target using the evas_object_move() function:

    - -
    static Eina_Bool
    -_do_drop(void *data, double pos)
    -{
    -   Evas_Object *obj = data;
    -   int x, y, w, h;
    -   double frame = pos;
    -   frame = ecore_animator_pos_map(pos, ECORE_POS_MAP_BOUNCE, 2, 4);
    -
    -   evas_object_geometry_get(obj, &x, &y, &w, &h);
    -   evas_object_move(obj, x, 600 * frame);
    -
    -   return EINA_TRUE;
    -}
    -
    - -

    To get the bounce effect, we use the ecore_animator_pos_map() function, which maps an input position from 0.0 to 1.0 along the timeline to a position on a different curve. The curve can be of different types, such as LINEAR, SINUSOIDAL, and BOUNCE. This function takes the following arguments:

    - -
      -
    • The input position to map
    • -
    • The mapping to use (LINEAR, SINUSOIDAL, and so on)
    • -
    • v1, which is the first parameter used by the mapping
    • -
    • v2, which is the second parameter used by the mapping
    • -
    - -

    The ECORE_POS_MAP_BOUNCE map we use starts at 0.0, then drops like a ball bouncing to the ground at 1.0, bouncing v2 times with a decay factor of v1. Here, we bounce 4 times with a decay factor of 2:

    - -
    frame = ecore_animator_pos_map(pos, ECORE_POS_MAP_BOUNCE, 2, 4);
    -
    - -

    This frame is used in the move function to create the animation. The value increases on each _do_drop() call along the timeline, which produces a nice drop of the buttons from their initial position to 600 pixels on the vertical axis.

    - - - - -
    - -Go to top - - - - - - - diff --git a/org.tizen.tutorials/html/native/ui/edje_effects_tutorial_n.htm b/org.tizen.tutorials/html/native/ui/edje_effects_tutorial_n.htm deleted file mode 100644 index 664a280..0000000 --- a/org.tizen.tutorials/html/native/ui/edje_effects_tutorial_n.htm +++ /dev/null @@ -1,390 +0,0 @@ - - - - - - - - - - - - - - Edje Animation: Using the Edje Library to Create Animations - - - - - - -
    -

    Edje Animation: Using the Edje Library to Create Animations

    - - -

    One of the greatest strengths of EFL and Edje is the ability to create animations. This tutorial demonstrates how Elm_Transit can create pre-defined animations, but you can also use the Edje library to create your own animations.

    - -

    Warm-up

    -

    Become familiar with the Edje, Elementary, and Evas API basics by learning about:

    - - -

    Animating on Application Start-up

    - - -

    The goal of this tutorial is to create an animation target and buttons to start animations, all this in an EDC (Edje Data Collection) file.

    -

    First create an application using Basic EDC UI Application. This model provides a simple application just like the one used in the previous chapter, but with one more element: an .edc file.

    -

    Animations can be run at application startup. By default the Basic EDC UI Application model produces an empty window with a title. In this example a Tizen logo is added to the window and the behavior of the window title is changed.

    -

    The images used by the Edje file are stored in the edje/images directory of the application. Copy the Tizen logo available in shared/res/<yourapplicationname>.png into the Edje image directory edje/images. Then add the image to the Edje images collection.

    -
    images 
    -{
    -   image: "edceffects.png" COMP;
    -   image: "tizen-logo.png" COMP;
    -}
    -
    - -

    Then add an Edje part using the small logo: this part has two states. This is the first important notion for animations. The STATE describes the appearance of a part: size, position, color, etc.

    -

    In this example, the part has two states, default and down-state:

    -
    // An image using the tizen logo
    -part 
    -{ 
    -   name: "logo";
    -   type: IMAGE;
    -   description 
    -   { 
    -      state: "default" 0.0;
    -      max: 63 63;
    -      min: 63 63;
    -      image { normal: "small-logo.png"; }
    -      rel1.relative: 0.1 0.0;
    -      rel2.relative: 0.0 0.0;
    -   }
    -
    -   description 
    -   { 
    -      state: "down-state" 1.0;
    -      inherit: "default" 0.0;
    -      rel1.relative: 0.1 0.92;
    -      rel2.relative: 0.05 1.0;
    -   }
    -}
    -

    The logo part has the IMAGE type. The default state contains in the first description of the part sets:

    -
      -
    • the maximum and minimum size using the min and max statements
    • -
    • the image to use in this part
    • -
    • the default position.
    • -
    -

    The second state, down-state, inherits all of the default's attributes, and only changes the position to put the image at the bottom of the application window.

    -

    These two states are the start and end states of the animation. To actually create the animation, add a program to the Edge programs collection.

    -
    // Icon drop animation
    -program 
    -{ 
    -   name: "animation,state1";
    -   source: "";
    -   signal: "load";
    -   action: STATE_SET "down-state" 1.0;
    -   target: "logo";
    -   transition: BOUNCE 2.5 0.0 5.0;
    -}
    -

    This program is named animation,state1 and is started when the application receives the load signal immediately on startup. It runs the STATE_SET action so it changes the object state from default to down-state. The target of the program is the logo part.

    -

    In order to switch from one state to another, it uses a transition of the BOUNCE type with three parameters, the FIXME, the FIXME, and the duration which here is set to five seconds.

    -

    This produces an falling and bouncing effect.

    -

    Also add an animation for the window title to make it move from the left to the right with a bounce effect while growing the font size.

    -

    Create a new state on the part called "txt_title" inside which both the font size and position are changed.

    -
    part 
    -{ 
    -   name: "txt_title";
    -   type: TEXT;
    -   mouse_events: 0;
    -
    -   // The default State
    -   description 
    -   { 
    -      state: "default" 0.0;
    -      align: 0.0 0.0;
    -      rel1 { relative: 0.0 0.0; }
    -      rel2 { relative: 0.0 0.0; }
    -      text 
    -      { 
    -         font: "Tizen:style=regular";
    -         size: 24;
    -         min: 1 1;
    -      }
    -      color: 0 0 0 255;
    -   }
    -
    -   // The "Bigger" state
    -   description 
    -   { 
    -      state: "Bigger" 0.0;
    -      align: 0.0 0.0;
    -      rel1 { relative: 0.75 0.0; }
    -      rel2 { relative: 0.0 0.0; }
    -      text 
    -      { 
    -         font: "Tizen:style=regular";
    -         size: 28;
    -         min: 1 1;
    -      }
    -      color: 0 0 0 255;
    -   }
    -}
    -
    -

    Create a program to animate this part on startup, just like the small Tizen logo.

    -
    // Make the title bigger
    -program 
    -{ 
    -   name: "animation,bigtitle";
    -   source: "";
    -   signal: "load";
    -   action: STATE_SET "Bigger" 1.0;
    -   target: "txt_title";
    -   transition: LINEAR 5.0;
    -}
    -
    -

    This program goes from the default state to the bigger state in five seconds with a LINEAR effect, automatically running on the application startup.

    - -

    Animating Object on Click

    - -

    All the previous animations are automatic and do not have any relation with the user's actions. Next animate a part by clicking on another one. Make the title restore its default aspect when clicking on the small logo.

    -

    The parts and the states are already defined. The animation goes back to the default state, there is no need to add any parts or states: only add a program which makes the transition when clicking on logo part.

    -
    // Make the title go back to normal
    -program 
    -{
    -   name: "animation,normaltitle";
    -   source: "logo";
    -   signal: "mouse,clicked,*";
    -   action: STATE_SET "default" 1.0;
    -   target: "txt_title";
    -   transition: LINEAR 0.5;
    -}
    -

    This program starts when the application receives the signal mouse,clicked,* (any button of the mouse is clicked) from the part called logo, (source). It performs the STATE_SET action and sets the default state on the target txt_file part with a LINEAR transition.

    -

    When clicking any mouse button on the small logo, the title goes back to its original state.

    -

    Rotating Parts

    -

    Next add two more buttons to the application and create programs to animate a target.

    -

    It is possible to create a button with Edje from scratch, but to save time, the SWALLOW part is used in this example to store Elementary UI components.

    -

    First create the SWALLOW parts, and then the Elementary UI components in the .c file.

    -
    // Container for the rotate button
    -part 
    -{
    -   type: SWALLOW;
    -   name: "btn/rotate";
    -   description 
    -   {
    -      state: "default" 0.0;
    -      rel1.relative: 0.10 0.80;
    -      rel2.relative: 0.30 0.90;
    -   }
    -}
    -

    This part is called btn/rotate, it only has a SWALLOW type and a default state with its position being on the bottom left of the screen.

    -
    // Container for the grow button
    -part 
    -{
    -   type: SWALLOW;
    -   name: "btn/grow";
    -   description 
    -   {
    -      state: "default" 0.0;
    -      rel1.relative: 1.02 0;
    -      rel1.to: "btn/rotate";
    -      rel2.relative: 2.02 1;
    -      rel2.to: "btn/rotate";
    -   }
    -}
    -

    This second SWALLOW part is very similar to the first one. It is placed relatively to btn/rotate, in order to remain next to it.

    -

    Next create the actual UI components. This is done in the .c file and is very similar to what is done for the buttons in the first chapter.

    -

    This code is added to the create_base_ui function.

    -
    // Creation button in the app window
    -ad->button = elm_button_add(ad->win);
    -elm_object_text_set(ad->button, "Rotate");
    -// Add the button to the edje layout container called "btn/rotate"
    -elm_object_part_content_set(ad->layout, "btn/rotate", ad->button);
    -evas_object_show(ad->button);
    -
    -// Creation a up button in the app window
    -ad->btn_up = elm_button_add(ad->win);
    -// Add the button to the edje layout container called "btn/grow"
    -elm_object_text_set(ad->btn_up, "Grow");
    -elm_object_part_content_set(ad->layout, "btn/grow", ad->btn_up);
    -evas_object_show(ad->btn_up);
    -

    In the default Basic EDC UI Application, the Edje layout is loaded by default. Create two Elementary buttons and add them to the SWALLOW containers, without having to setup sizes or positions as this is done in the SWALLOW container.

    -

    Note that the part name is very important because it is used to be merged the Elementary UI component and the SWALLOW part.

    -

    When the buttons placed and set, create the animation target. it is done in the EDC file.

    -

    Add the animation target part.

    -

    The part initialization and the default state:

    -
    // The animation target
    -part 
    -{
    -   name: "atarget";
    -   type: IMAGE;
    -
    -   // Default state
    -   description 
    -   {
    -      state: "default" 0.0;
    -      image { normal: "tizen-logo.png"; }
    -      color: 255 0 0 255; // red
    -      rel1 { relative: 0.3 0.3; }
    -      rel2 { relative: 0.7 0.4; }
    -   }
    -}
    -
    -

    This part is an image displaying a big Tizen logo, placed on the top of the screen more or less centered.

    -

    Create a state to change the color and add the map statement.

    -
    // The rotate state
    -description 
    -{
    -   state: "rotate" 0.0;
    -   inherit: "default" 0.0;
    -
    -   map 
    -   {
    -      // Enable Map on the part
    -      on: 1;
    -      // Enable smooth rendering
    -      smooth: 1;
    -      // Enable perspective
    -      perspective_on: 1;
    -
    -      // Apply rotations on the part
    -      rotation.x: 0;
    -      rotation.y: 0;
    -      rotation.z: 0;
    -   }
    -   color: 0 255 0 255; // green
    -}
    -

    This part changes the color to green and defines the map. This statement makes rotations possible on an Edje part. Rotations are done around the x, y or z axes. In this example, the map is enabled and a 0° rotation is applied around each axis.

    -

    Add a state with a rotation around the z axis of 360°.

    -
    description 
    -{
    -   state: "rotate" 1.0;
    -   inherit: "rotate" 0.0;
    -   map.rotation.z: 360;
    -}
    -

    This state inherits from the default state parameters and add a rotation around the z axis.

    -

    Finally add a state to the other button animation grow. Change the size of the animation target and add an offset.

    -
    // The grow state
    -description {
    -   state: "grow" 0.0;
    -   color: 0 0 255 255; // blue
    -   rel1 
    -   {
    -      relative: 0.2 0.2;
    -      offset: 0.3 0.3;
    -   }
    -   rel2 
    -   {
    -      relative: 0.7 0.4;
    -      offset: 0.3 0.3;
    -   }
    -}
    -

    The last step is to create the programs to make all these states animate.

    -

    To make the rotation animation smoother, create and chain several programs with different durations.

    -

    First create the main one: it goes from the default state to the rotate 0.0 state in 0.2 seconds.

    -

    Note that the states are all named the same way (rotate) but not with the same version. This version allows you to have more than one state with the same name, in fact the actual name of the state is the name plus the version.

    -
    // Change the color of target to green
    -program 
    -{
    -   name: "rotate,target";
    -   source: "btn/rotate";
    -   signal: "mouse,clicked,*";
    -   action: STATE_SET "rotate" 0.0;
    -   target: "atarget";
    -   transition: SIN 0.2;
    -   after: "rotate,target,2";
    -}
    -

    The program starts when the btn/rotate part is clicked with any mouse button. When the animation ends, it calls the next one called rotate,target,2.

    -
    // Rotate 360°
    -program 
    -{
    -   name: "rotate,target,2";
    -   action: STATE_SET "rotate" 1.0;
    -   target: "atarget";
    -   transition: SIN 0.7;
    -   after: "rotate,end";
    -}
    -

    This program sets the part state to rotate 1.0 in 0.7 seconds, and when done calls the next one rotate,end.

    -
    // Go back to the normal
    -program 
    -{
    -   name: "rotate,end";
    -   action: STATE_SET "rotate" 0.0;
    -   target: "atarget";
    -   transition: LINEAR 0.2;
    -}
    -

    rotate,end is the last program of the rotation effect: it sets the state to rotate 0.0 very fast.

    -

    The last program of this example is the grow effect, it switches from one state to another.

    -
    // Grow the target and go back to normal state
    -program 
    -{
    -   name: "grow,target";
    -   source: "btn/grow";
    -   signal: "mouse,clicked,*";
    -   action: STATE_SET "grow" 1.0;
    -   after: "go,default";
    -   target: "atarget";
    -   transition: SINUSOIDAL 1.0;
    -}
    -

    It starts when the btn/grow part is clicked, it goes from the current state to grow 1.0 in one second. It then calls the go,default program. In this program, both size and color change during the transition.

    -

    The go,default program sets the status back default for the animation target.

    -
    // Go back to normal (default) state
    -program 
    -{
    -   name: "go,default";
    -   action: STATE_SET "default" 1.0;
    -   target: "atarget";
    -   transition: SIN 1.0;
    -}
    -
    - - - - -
    - -Go to top - - - - - - - diff --git a/org.tizen.tutorials/html/native/ui/efl_extension_tutorial_n.htm b/org.tizen.tutorials/html/native/ui/efl_extension_tutorial_n.htm deleted file mode 100644 index 806cdd7..0000000 --- a/org.tizen.tutorials/html/native/ui/efl_extension_tutorial_n.htm +++ /dev/null @@ -1,385 +0,0 @@ - - - - - - - - - - - - - - Efl Extension: Creating a Naviframe Window - - - - - - -
    - -

    Efl Extension: Creating a Naviframe Window

    - - -

    This tutorial demonstrates how you can handle hardware key and rotary events.

    - -

    Warm-up

    -

    Become familiar with the Efl Extension, Elementary, and Evas API basics by learning about:

    - - -

    Initializing the EFL Extension

    - -

    To use the functions and data types of the Efl Extension API (in mobile and wearable applications), include the <efl_extension.h> header file in your application:

    -
    -#include <efl_extension.h>
    -
    - -

    Managing Hardware Key Events

    - - - - - - - - - - -
    Note
    Hardware key events are only supported in mobile devices.
    - -

    The application has a window that contains a naviframe and registers the EFL Extension Menu and Back key events for the naviframe.

    -

    When the Menu key is pressed, a popup is created and an EFL Extension Back key event for this popup is registered. If the popup is shown and the Back key is pressed, the popup is removed. Otherwise, if the Back key is pressed and there is no popup, the application is hidden.

    - -

    To manage hardware key events:

    -
      -
    1. Create objects using the window and naviframe: -
      -static void
      -create_base_gui(appdata_s *ad)
      -{
      -   Evas_Object *win = NULL;
      -
      -   // Create the window
      -   win = elm_win_util_standard_add(NULL, "extension sample");
      -   evas_object_smart_callback_add(win, "delete,request", _win_del, NULL);
      -
      -   // Create the naviframe
      -   Evas_Object *nf = NULL;
      -   nf = elm_naviframe_add(win);
      -   evas_object_size_hint_weight_set(win, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      -   elm_win_resize_object_add(win, nf);
      -   evas_object_show(nf);
      -
      -   // Content
      -   Evas_Object *label = NULL;
      -   label = elm_label_add(nf);
      -   elm_object_text_set(label, "Press menu key to show popup,<br/>back key to exit.");
      -   elm_naviframe_item_push(nf, "Efl Extension usage", NULL, NULL, label, NULL);
      -
      -   // Show the window
      -   evas_object_show(win);
      -}
      -
      -
    2. - -
    3. Register EFL Extension callbacks for the naviframe: -
      -static void
      -create_base_gui(appdata_s *ad)
      -{
      -   // Register the EFL extension callbacks for Menu and Back key events
      -   eext_object_event_callback_add(nf, EEXT_CALLBACK_MORE, _create_popup, NULL);
      -   eext_object_event_callback_add(nf, EEXT_CALLBACK_BACK, _nf_back_cb, win);
      -}
      -
      -
    4. - -
    5. Create a popup and register EFL Extension Back key event callbacks for it: -
      -static void
      -_create_popup(void *data, Evas_Object *obj, void *event_info)
      -{
      -   Evas_Object *parent = obj;
      -
      -   Evas_Object *popup = NULL, *content = NULL;
      -   popup = elm_popup_add(parent);
      -   elm_object_part_text_set(popup, "title,text", "Title");
      -   elm_popup_orient_set(popup, ELM_POPUP_ORIENT_CENTER);
      -
      -   // Popup content
      -   content = elm_label_add(parent);
      -   elm_object_text_set(content, "Press back key to remove popup.");
      -   elm_object_content_set(popup, content);
      -
      -   // Register the EFL extension callback for the Back key event
      -   eext_object_event_callback_add(popup, EEXT_CALLBACK_BACK, eext_popup_back_cb, NULL);
      -   evas_object_show(popup);
      -}
      -
      - -

      To remove the popup when a Back key event occurs, use the eext_popup_back_cb callback.

      - -

      The callback function for menu key callback:

      -
      -static void
      -_nf_back_cb(void *data, Evas_Object *obj, void *event_info)
      -{
      -   Evas_Object *win = data;
      -
      -   // Hide the window
      -   elm_win_lower(win);
      -}
      -
      -
    6. -
    - -

    Managing Rotary Events

    - - - - - - - - - - -
    Note
    Rotary events are only supported in devices with a circular screen.
    - -

    To manage rotary events:

    -
      -
    1. Create the rotary event handler: -
        -
      1. Create the window: -
        -static void
        -create_base_gui(appdata_s *ad)
        -{
        -Evas_Object *win = NULL;
        -
        -   // Window
        -   win = elm_win_util_standard_add(NULL, "extension circle sample");
        -   elm_win_autodel_set(win, EINA_TRUE);
        -   evas_object_smart_callback_add(win, "delete,request", win_delete_request_cb, NULL);
        -
        -   // Show the window after base gui is set up
        -   evas_object_show(win);
        -}
        -
        -
      2. - -
      3. Register the rotary event handler: -
        -static void
        -create_base_gui(appdata_s *ad)
        -{
        -   // Register the rotary event handler
        -   eext_rotary_event_handler_add(_rotary_handler_cb, NULL);
        -}
        -
      4. -
      5. Define the callback function: -
        -Eina_Bool _rotary_handler_cb(void *data, Eext_Rotary_Event_Info *ev)
        -{
        -   if (ev->direction == EEXT_ROTARY_DIRECTION_CLOCKWISE)
        -   {
        -      LOGD("Rotary device rotated in clockwise direction");
        -   }
        -   else
        -   {
        -      LOGD("Rotary device rotated in counter clockwise direction");
        -   }
        -
        -   return EINA_FALSE;
        -}
        -
        -
      6. - -
      7. Remove the rotary event handler and release all resources when you do not need it anymore. -
        -static void
        -app_terminate(void *data)
        -{
        -   // Release all resources
        -   eext_rotary_event_handler_del(_rotary_handler_cb);
        -}
        -
        -
      8. -
      -
    2. -
    3. Create a rotary event callback for a normal Evas object. -

      When a rotary event occurs, the slider value is adjusted accordingly.

      -
        -
      1. Create the objects. -

        The window and the slider are created using the Elementary APIs.

        -
        -static void
        -create_base_gui(appdata_s *ad)
        -{
        -   Evas_Object *win = NULL, *slider = NULL;
        -
        -   // Window 
        -   win = elm_win_util_standard_add(NULL, "extension sample");
        -   elm_win_autodel_set(win, EINA_TRUE);
        -   evas_object_smart_callback_add(win, "delete,request", win_delete_request_cb, NULL);
        -
        -   // Slider
        -   slider = elm_slider_add(win);
        -   evas_object_size_hint_weight_set(slider, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
        -   elm_slider_min_max_set(slider, 0, 50);
        -   elm_slider_step_set(slider, 1.0);
        -   evas_object_show(slider);
        -   elm_win_resize_object_add(win, slider);
        -
        -   // Show the window after the base GUI is set up 
        -   evas_object_show(win);
        -}
        -
        -
      2. -
      3. Register the rotary event callback. -

        To receive the rotary event, register the rotary event callback and set the activated object as the slider object.

        -
        -static void
        -create_base_gui(appdata_s *ad)
        -{
        -   // Register rotary event callback 
        -   ext_rotary_object_event_callback_add(slider, _rotary_event_cb, NULL);
        -   eext_rotary_object_event_activated_set(slider, EINA_TRUE);
        -}
        -
        -

        Define the rotary callback function:

        -
        -Eina_Bool _rotary_event_cb(void *data, Evas_Object *obj, Eext_Rotary_Event_Info *ev)
        -{
        -   Evas_Object *slider = obj;
        -   int val = elm_slider_value_get(slider);
        -   if (ev->direction == EEXT_ROTARY_DIRECTION_CLOCKWISE)
        -   {
        -      elm_slider_value_set(slider, val + 1);
        -   }
        -   else
        -   {
        -      elm_slider_value_set(slider, val - 1);
        -   }
        -
        -   return EINA_FALSE;
        -}
        -
        -
      4. -
      -
    4. -
    5. Create a rotary event callback for an EFL Extension object. -

      When a rotary event occurs, the slider value is adjusted accordingly.

      -
        -
      1. Create the objects: -
        -static void
        -create_base_gui(appdata_s *ad)
        -{
        -   Evas_Object *win = NULL, *conform = NULL;
        -   Eext_Circle_Surface *sur = NULL;
        -
        -   // Window 
        -   win = elm_win_util_standard_add(NULL, "extension circle sample");
        -   elm_win_autodel_set(win, EINA_TRUE);
        -   evas_object_smart_callback_add(win, "delete,request", win_delete_request_cb, NULL);
        -
        -   // Conformant
        -   conform = elm_conformant_add(win);
        -   elm_win_indicator_mode_set(win, ELM_WIN_INDICATOR_SHOW);
        -   elm_win_indicator_opacity_set(win, ELM_WIN_INDICATOR_OPAQUE);
        -   evas_object_size_hint_weight_set(conform, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
        -   elm_win_resize_object_add(win, conform);
        -   evas_object_show(conform);
        -
        -   // Surface 
        -   sur = eext_circle_surface_conformant_add(conform);
        -
        -   // Slider
        -   slider = eext_circle_object_slider_add(conform, sur);
        -   eext_circle_object_value_min_max_set(slider, 0.0, 30.0);
        -   eext_circle_object_value_set(slider, 0.0);
        -
        -   // Show the window after the base GUI is set up
        -   evas_object_show(win);
        -}
        -
        -
      2. -
      3. Set the activated object. -

        Since the EFL Extension API is used to create the slider object, the created slider object already registers the rotary event callbacks internally. To receive a rotary event, you only need to set the activated object as the desired object (slider).

        -
        -static void
        -create_base_gui(appdata_s *ad)
        -{
        -   // Activate circle slider's rotary object event
        -   // Its value increases/decreases its value by 1.0 to clockwise or 
        -   // counter-clockwise rotary event
        -   eext_rotary_object_event_activated_set(slider, EINA_TRUE);
        -   eext_circle_object_slider_step_set(slider, 1.0);
        -}
        -
        -
      4. -
      -
    6. -
    - - - - - - -
    - -Go to top - - - - - - - diff --git a/org.tizen.tutorials/html/native/ui/efl_optimization_tutorial_n.htm b/org.tizen.tutorials/html/native/ui/efl_optimization_tutorial_n.htm deleted file mode 100644 index ff00863..0000000 --- a/org.tizen.tutorials/html/native/ui/efl_optimization_tutorial_n.htm +++ /dev/null @@ -1,727 +0,0 @@ - - - - - - - - - - - - - - EFL Optimization: Optimizing Tizen Native Applications - - - - - - -
    -

    EFL Optimization: Optimizing Tizen Native Applications

    - - -

    This tutorial demonstrates how you can optimize your Tizen native application.

    - -

    Warm-up

    -

    Become familiar with the Edje, Elementary, and Evas API basics by learning about:

    - - -

    Optimizing EDC

    - -

    To optimize EDC:

    -
      -
    1. Remove unnecessary parts. -

      When you create EDC, there can be obsolete and unnecessary parts. Since they have an effect on performance, remove them.

      - - - - - - - - - - - - - - - -
      BeforeAfter

      -

      -collections 
      -{
      -   group 
      -   { 
      -      name: "main";
      -      parts 
      -      {
      -         part 
      -         { 
      -            name: "bg";
      -            type: RECT;
      -            description 
      -            { 
      -               state: "default" 0.0;
      -               rel1.relative: 0.0 0.0;
      -               rel2.relative: 1.0 1.0;
      -               color: 255 255 255 255;
      -            }
      -         }
      -         part 
      -         { 
      -            name: "new";
      -            type: RECT;
      -            scale: 1;
      -            mouse_events: 1;
      -            description 
      -            { 
      -               state: "default" 0.0;
      -               color: 255 255 0 255;
      -               rel1.relative: 0.2 0.2;
      -               rel2.relative: 0.8 0.8;
      -            }
      -         }
      -         part 
      -         { 
      -            name: "old";
      -            type: RECT;
      -            scale: 1;
      -            mouse_events: 1;
      -            description 
      -            { 
      -               state: "default" 0.0;
      -               color: 0 0 0 0;
      -               rel1.relative: 0.5 0.5;
      -               rel2.relative: 1.0 1.0;
      -            }
      -         }
      -      }
      -   }
      -}
      -

      -

      -collections 
      -{
      -   group 
      -   { 
      -      name: "main";
      -      parts 
      -      {
      -         part 
      -         { 
      -            name: "bg";
      -            type: RECT;
      -            description 
      -            { 
      -               state: "default" 0.0;
      -               rel1.relative: 0.0 0.0;
      -               rel2.relative: 1.0 1.0;
      -               color: 255 255 255 255;
      -            }
      -         }
      -         part 
      -         { 
      -            name: "new";
      -            type: RECT;
      -            scale: 1;
      -            mouse_events: 1;
      -            description 
      -            { 
      -               state: "default" 0.0;
      -               color: 255 255 0 255;
      -               rel1.relative: 0.2 0.2;
      -               rel2.relative: 0.8 0.8;
      -            }
      -         }  
      -
      -
      -
      -
      -
      -
      -
      -
      -
      -
      -
      -
      -
      -       
      -      }
      -   }
      -}
      -

      - -
    2. - -
    3. Use Text, if possible, instead of Textblock. -

      The following EDCs lead to the same result. However, use TEXT for the simple texts for high performance apart from using tags or multiple lines.

      - - - - - - - - - - - - - - - -
      BeforeAfter

      -

      -collections 
      -{
      -   styles 
      -   {
      -      style 
      -      { 
      -         name: "text_style";
      -         base: "font="Sans" font_size=30 text_class=entry 
      -         color=#0088AA style=shadow,bottom 
      -         shadow_color=#00000080 valign=0.5 ellipsis=1.0 
      -         wrap=none align=center";
      -      }
      -   }
      -   group 
      -   { 
      -      name: "main";
      -      parts 
      -      {
      -         part 
      -         { 
      -            name: "text";
      -            type: TEXTBLOCK;
      -            scale: 1;
      -            description 
      -            { 
      -               state: "default" 0.0;
      -               text 
      -               {
      -                  style: "text_style";
      -                  text: "TEXT";
      -               }
      -            }
      -         }
      -      }
      -   }
      -}
      -

      -

      -collections 
      -{
      -   group 
      -   { 
      -      name: "main";
      -      part 
      -      { 
      -         name: "simple";
      -         type: TEXT;
      -         scale: 1;
      -         effect: SHADOW;
      -         description 
      -         { 
      -            state: "default" 0.0;
      -            align: 0.5 0.5;
      -            color: 0 136 170 255;
      -            visible: 1;
      -            text 
      -            {
      -               size: 30;
      -               font: "Sans";
      -               text: "TEXT";
      -            }
      -         }
      -      }
      -   }
      -}
      -

      - -
    4. - -
    5. Compress images and embed your images into EDC. -

      When you use a fixed image, it is more efficient to call an image within EDC. This save time in accessing the image data and is more suitable for the data size.

      - -
      -collections 
      -{
      -   images 
      -   {
      -      image: "logo.png" COMP;
      -   }
      -   group 
      -   { 
      -      name: "main";
      -      parts 
      -      {
      -         part 
      -         { 
      -            name: "logo";
      -            type: IMAGE;
      -            description 
      -            { 
      -               state: "default" 0.0;
      -               rel1.relative: 0.0 0.0;
      -               rel2.relative: 1.0 1.0;
      -               image.normal: "logo.png";
      -               aspect: 1 1;
      -               aspect_preference: BOTH;
      -            }
      -         }
      -      }
      -   }
      -}
      -
      - -
    6. - -
    7. Use a SPACER part, if possible. -

      When you use a part (such as Padding) which is invisible but has a size, using Spacer is more efficient. -Since Spacer is invisible, it does not have the visible and color options.

      - - - - - - - - - - - - - - - - -
      BeforeAfter

      -

      -collections 
      -{
      -   group 
      -   { 
      -      name: "main";
      -      parts 
      -      {
      -         part 
      -         { 
      -            name: "bg";
      -            type: RECT;
      -            description 
      -            { 
      -               state: "default" 0.0;
      -               color: 255 255 255 255;
      -            }         
      -         }
      -         part 
      -         { 
      -            name: "padding_left_top";
      -            type: RECT;
      -            description 
      -            { 
      -               state: "default" 0.0;
      -               color: 0 0 0 0;
      -               rel1.to: "bg";
      -               rel2.to:"bg";
      -               rel2.relative: 0.0 0.0;
      -               align: 0.0 0.0;               
      -               min: 100 100;        
      -            }
      -         }
      -         part 
      -         { 
      -            name: "padding_right_bottom";
      -            type: RECT;
      -            description 
      -            { 
      -               state: "default" 0.0;
      -               color: 0 0 0 0;
      -               rel1.to: "bg";
      -               rel1.relative: 1.0 1.0;
      -               rel2.to:"bg";
      -               align: 1.0 1.0;               
      -               min: 100 100;
      -            }         
      -         }
      -         part 
      -         { 
      -            name: "content";
      -            type: RECT;
      -            description 
      -            { 
      -               state: "default" 0.0;
      -               color: 255 255 0 255;
      -               rel1.to: "padding_left_top";
      -               rel1.relative: 1.0 1.0;
      -               rel2.to:"padding_right_bottom";
      -               rel2.relative: 0.0 0.0;
      -            }         
      -         }
      -      }
      -   }
      -}
      -

      -

      -collections 
      -{
      -   group 
      -   { 
      -      name: "main";
      -      parts 
      -      {
      -         part 
      -         { 
      -            name: "bg";
      -            type: RECT;
      -            description 
      -            { 
      -               state: "default" 0.0;
      -               color: 255 255 255 255;
      -            }         
      -         }
      -         part 
      -         { 
      -            name: "padding_left_top";
      -            type: SPACER;
      -            description 
      -            { 
      -               state: "default" 0.0;
      -               rel1.to: "bg";
      -               rel2.to:"bg";
      -               rel2.relative: 0.0 0.0;
      -               align: 0.0 0.0;               
      -               min: 100 100;
      -            }         
      -         }
      -         part 
      -         { 
      -            name: "padding_right_bottom";
      -            type: SPACER;
      -            description 
      -            { 
      -               state: "default" 0.0;
      -               rel1.to: "bg";
      -               rel1.relative: 1.0 1.0;
      -               rel2.to:"bg";
      -               align: 1.0 1.0;               
      -               min: 100 100;
      -            }         
      -         }
      -         part 
      -         { 
      -            name: "content";
      -            type: RECT;
      -            description 
      -            { 
      -               state: "default" 0.0;
      -               color: 255 255 0 255;
      -               rel1.to: "padding_left_top";
      -               rel1.relative: 1.0 1.0;
      -               rel2.to:"padding_right_bottom";
      -               rel2.relative: 0.0 0.0;
      -            }         
      -         }
      -      }
      -   }
      -}
      -

      - -
    8. - -
    9. Use the image border feature. -

      When you use an image, you do not need to use a full size or larger size image. As you can see below, it is much more efficient to scale the image using a border option.

      - - - - - - - - - - - - - - - - - - - -
      BeforeAfter

      -

      -collections 
      -{
      -   images 
      -   {
      -      image: "test.png" COMP;
      -   }
      -   group 
      -   { 
      -      name: "main";
      -      parts 
      -      {
      -         part 
      -         { 
      -            name: "test";
      -            type: IMAGE;
      -            description 
      -            { 
      -               state: "default" 0.0;
      -               rel1.relative: 0.2 0.2;
      -               rel2.relative: 0.8 0.8;
      -               image.normal: "test.png";
      -
      -            }
      -         }
      -      }
      -   }
      -}
      -

      -

      -collections 
      -{
      -   images 
      -   {
      -      image: "test.png" COMP;
      -   }
      -   group 
      -   { 
      -      name: "main";
      -      parts 
      -      {
      -         part 
      -         { 
      -            name: "test";
      -            type: IMAGE;
      -            description 
      -            { 
      -               state: "default" 0.0;
      -               rel1.relative: 0.2 0.2;
      -               rel2.relative: 0.8 0.8;
      -               image.normal: "test.png";
      -               image.border: 5 5 5 5;
      -            }
      -         }
      -      }
      -   }
      -}
      -

      Image before

      Image after

      - -
    10. -
    - -

    Optimizing Evas

    - -

    To optimize Evas:

    -
      -
    1. Use a rectangle object instead of using a solid color image. -

      When you need a solid color object, it is better (more efficient) to use a rectangle object than the image.

      - - - - - - - - - - - - - - - - - - -
      Before

      -

      -image = elm_image_add(win);
      -snprintf(buf, sizeof(buf), "%s/images/white_bg.png", elm_app_data_dir_get()); 
      -elm_image_file_set(image, buf, NULL);
      -evas_object_size_hint_weight_set(image, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      -elm_win_resize_object_add(win, image);
      -evas_object_show(image);
      -

      After

      -

      -rect = evas_object_rectangle_add(evas_object_evas_get(win));
      -evas_object_color_set(rect, 255, 255, 255, 255);
      -evas_object_size_hint_weight_set(rect, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      -elm_win_resize_object_add(win, rect);
      -evas_object_show(rect);
      -

      - -
    2. - -
    3. Make an object invisible instead of setting alpha as 0. -

      To make an object invisible, it is more efficient to use evas_object_hide() instead of changing the alpha value to 0.

      - - - - - - - - - - - - - - - -
      BeforeAfter

      -

      -static void
      -_invisible_cb(void *data, Evas_Object *obj, void *ev)
      -{
      -   evas_object_color_set(obj, 0, 0, 0, 0);   
      -}
      -

      -

      -static void
      -_invisible_cb(void *data, Evas_Object *obj, void *ev)
      -{
      -   evas_object_hide(obj);   
      -}
      -

      - -
    4. - -
    5. If you need maximum optimization, use evas_object_image instead of elm_image and elm_icon. - - - - - - - - - - - - - - - - - - -
      Before

      -

      -img = elm_image_add((parent);
      -snprintf(buf, sizeof(buf), "%s/images/white_bg.png", elm_app_data_dir_get()); 
      -elm_image_file_set(img, buf, NULL);
      -evas_object_size_hint_weight_set(img, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      -evas_object_size_hint_align_set(img, EVAS_HINT_FILL, EVAS_HINT_FILL);
      -evas_object_show(img);
      -

      After

      -

      -img = evas_object_image_add(evas_object_evas_get(parent));
      -snprintf(buf, sizeof(buf), "%s/images/white_bg.png", elm_app_data_dir_get()); 
      -evas_object_image_file_set(img, buf, NULL);
      -evas_object_image_filled_set(img, EINA_TRUE);
      -evas_object_size_hint_weight_set(img, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      -evas_object_size_hint_align_set(img, EVAS_HINT_FILL, EVAS_HINT_FILL);
      -evas_object_show(img);
      -

      -
    6. - -
    7. Set the parent correctly to avoid the elementary tree reconstruction. -

      Before creating an object, make sure that the relationship between parent and child is set correctly to avoid having to reconstruct later.

      - - - - - - - - - - - - - - - -
      BeforeAfter

      -

      -win = elm_win_add();
      -
      -scroller = elm_scroller_add(win);
      -
      -box = elm_box_add(win);
      -
      -button = elm_button_add(win);
      -

      -

      -win = elm_win_add();
      -
      -scroller = elm_scroller_add(win);
      -
      -box = elm_box_add(scroller);
      -
      -button = elm_button_add(box);
      -

      - -
    8. -
    - - - - -
    - -Go to top - - - - - - - \ No newline at end of file diff --git a/org.tizen.tutorials/html/native/ui/efl_tutorial_n.htm b/org.tizen.tutorials/html/native/ui/efl_tutorial_n.htm deleted file mode 100644 index a5d82fe..0000000 --- a/org.tizen.tutorials/html/native/ui/efl_tutorial_n.htm +++ /dev/null @@ -1,658 +0,0 @@ - - - - - - - - - - - - - - EFL: Using EFL Features for Designing the UI - - - - - - -
    - -

    EFL: Using EFL Features for Designing the UI

    - - -

    This tutorial demonstrates how you can use EFL to create your application UI. EFL is an open-source toolkit that provides a set of libraries that offer useful features to applications. EFL covers a number of areas from data structures to UI component sets. EFL is one of the Tizen native UI modules and is available in various Tizen profiles. In Tizen, EFL is commonly used for UI applications, although you can also use it for non-UI applications.

    - - - -

    Warm-up

    -

    Become familiar with the Efl Extension and Elementary API basics by learning about:

    - - - -

    Learning EFL Basics

    - -

    EFL stands for Enlightenment Foundation Libraries. Enlightenment is a project consisting of the Enlightenment window manager, EFL libraries, and various utilities and applications. The Enlightenment team needed powerful libraries to handle, among others, rendering, main loops, and events, so EFL was introduced during the development of the Enlightenment window manager to fill these gaps. EFL is now widely used outside of the Enlightenment window manager.

    - -

    Currently, five EFL libraries are publicly available to Tizen native applications. These libraries provide the following features, among others:

    - -
      -
    • Data structures
    • -
    • Optimized rendering
    • -
    • Thread pool
    • -
    • Events and callbacks
    • -
    • Fd handlers
    • -
    • Timers and animators
    • -
    • UI components
    • -
    • Layout scripts
    • -
    - -

    EFL Characteristics

    - -

    EFL is aimed at not only desktop computers but also touch-screen and embedded devices, making EFL applications portable to many different types of devices. Applications do not need to care about the types of devices and profiles they run on. Instead of changing the code, it is typically enough to simply configure the applications for different devices.

    - -

    The key characteristics of EFL include:

    - -
      -
    • Performance -

      The main reason Tizen adopted EFL as its native toolkit is its speed. EFL is highly optimized by using a scene graph and retained-mode rendering. EFL is fast even in software rendering.

    • -
    • Small memory footprint -

      Despite its fast performance, EFL's memory footprint is smaller than that of other toolkits with similar features. A small memory footprint is useful in the embedded world, since embedded devices do not normally have much memory.

    • -
    • Back-end engine support -

      EFL supports several back-end engines, such as X11 (OpenGL, Xlib, Xcb), Wayland (OpenGL, SHM), Direct Framebuffer, DRM, memory buffers, PS3 native, Windows, and Mac OS. Applications do not need to deal with each back-end engine separately.

    • -
    • GUI and logic separation -

      EFL supports GUI layout and logic separation by having the layout description in a plain text file and the logic code in the C or C++ source files.

    • -
    • Themeable -

      An EFL theme can be changed at runtime without restarting the application. UI components are customizable so that each application can create its own customized theme to overlay above the default theme, adding customized versions of UI components to achieve a specific look and feel.

    • -
    • Scalable -

      EFL supports a scale factor that affects the size of objects in the application at runtime. By configuring the scale factor, applications can scale up and down as needed. The scale factor also supports a default setting that allows applications to scale nicely out-of-the-box.

    • -
    • Animations -

      EFL supports different types of animations. Evas supports Evas maps with low-level APIs for performing 2D, 2.5D, and 3D object transformations. Edje supports pre-defined transitions and wrapping of Evas maps. Elementary supports transit APIs for various types of animations, which can be combined.

    • -
    • Hardware acceleration -

      EFL supports OpenGL® and OpenGL-ES acceleration.

    • -
    - - -

    EFL Libraries

    - -

    Figure: EFL libraries

    -

    EFL libraries

    - -

    Tizen supports the following EFL libraries:

    - -
      -
    • Ecore -

      A clean and tiny event loop library with many convenience modules supporting operating system abstraction and integration. Ecore runs a main loop that is a key feature for event-driven applications and the rest of EFL. The Ecore main loop runs infinitely (or until requested to quit) and handles all registered events, such as touch, mouse, key, timers, animators, idlers, and fd handlers. Ecore also provides modules for handling network connections, files, input methods, and so on. EFL assumes that you run an Ecore main loop at all times (except at application startup and shutdown) and use the main loop to handle all callbacks (unless otherwise documented). ELF also assumes that threads use the Ecore infrastructure to return the results of their work back to the main loop for implementation.

    • -
    • Edje -

      A complex graphical design and layout library. Edje supports a separation between layout and logic. Edje was designed as a theme layer for moving the look, feel, and animation of objects into separate data files loaded at runtime, as opposed to being defined in-code. Using a plain text edc file, you can describe your application's layout without writing a line of code.

    • -
    • Eina -

      A library for data types and other useful tools. Eina provides data types such as lists, in-line lists, arrays, in-line arrays, hash tables, compact lists, iterator functions, sparse matrices, red-black trees, string buffers, shared string tokens, rectangle regions, generic value storage, and data models. Eina also supports tools such as benchmarking infrastructure, converters, counters, error handlers, basic file handlers, lazy allocators, loggers, magic number handlers, memory pools, modules, rectangles, safety checks, and string handlers.

    • -
    • Elementary -

      A UI component set library. Elementary is composed of several common UI components, such as buttons, check boxes, entries, lists, pop-ups, and windows. Some infrastructure is shipped with Elementary, such as scale configuration handling, finger-size configuration for touch UIs, theme handling, focus handling, accessibility, UI mirroring, and profile handling.

    • -
    • Evas -

      A highly optimized scene graph and rendering library. Evas is a stateful canvas scene graph in which you can place objects such as rectangles, lines, polygons, text, text blocks, images, and smart objects. Evas uses a scene graph to keep track of the state of all objects. You do not need to worry about objects repainting or keeping their states. You only need to modify them for the new state and let Evas take care of the rest. Evas supports anti-aliased text, smooth super and sub-sampled scaled images, alpha-blended objects, and more.

    • -
    - -

    Using EFL in Tizen Native Applications

    - -

    To start the Ecore main loop and move your application into the running state, call the ui_app_main() function. The Ecore main loop handles all general events, such as touch, mouse, key, and network events.

    - -
    -int
    -main(int argc, char *argv[])
    -{
    -   ret = ui_app_main(argc, argv, &event_callback, &ad);
    -
    -   return ret;
    -}
    -
    - -After your application is running: - -
      -
    1. Create a window, and organize your UI components inside the window.
    2. -
    3. Create the application logic code to be called when callbacks or timed events occurs (for example, animators for animations, timers for timeouts).
    4. -
    - -

    Using the Base Application Layout

    - -

    This section provides how to use base layout with EFL for your application. Also, you can get some idea of sample layouts for applications.

    - -

    Using the Base Layout

    - -

    When developing a Tizen native application, it is recommended that you base your application layout on the base layout. The base layout supports the indicator and view management. The following figure shows the wireframe and UI component hierarchy of the base layout:

    - -

    Figure: Base layout wireframe and UI component hierarchy

    -

    Base layout wireframe and UI component hierarchy

    - -

    The UI components have the following roles:

    - -
      -
    • Window (Elm_win): Every UI component from Elementary is rendered in a Window.
    • -
    • Conformant (Elm_Conformant): The Conformant supports the indicator area and resizing the application due to rotation or the ISF (keypad).
    • -
    • Naviframe (Elm_Naviframe): The Naviframe acts as a view manager and optionally provides the application title. The main layout of the application is added to the Naviframe's view area.
    • -
    - - -

    Sample Applications with the Base Layout

    - -

    Setting

    - -

    The Setting application consists of a list to show as a menu. For organizing the application, create the application layout with a screen-size-list and place the layout into the Naviframe's view area.

    - -

    Figure: Setting UI and layout

    -

    Settings UI and layout

    - -

    For more information, see the Setting sample application.

    - -

    Application Store

    - -

    For organizing the Application Store application, you need to add a scroller to the base layout, since the total height of the layout will be greater than the screen size, and you will therefore need to scroll the screen contents up and down. If the layout is larger than the screen, the scroller makes the view itself scrollable.

    - -

    You can use a list or grid if the same objects are shown repeatedly. In this sample application, however, the various items are shown in a layout.

    - -

    Figure: Application Store UI and layout

    -

    Application Store UI and layout

    - -

    For more information, see the Application Store sample application.

    - -

    Sample Applications with a Custom Layout

    - -

    Calculator - No Naviframe

    - -

    The Calculator is a good example of an exception to the base layout. The application has no view changes and no application title. As these are the two reasons why you should use a Naviframe, you do not need to add a Naviframe to the Calculator.

    - -

    You can organize the application layout with container components. Container components are used for arranging UI components, both basic UI components and other container components.

    - -

    Figure: Calculator UI and layout

    -

    Calculator UI and layout

    - -

    For more information, see the Calculator sample application.

    - -

    Email - Drawer

    - -

    The Email application shows information using a list. The main view is the same as in the Setting application, consisting of a screen-size-list for displaying emails. However, the Email application has an additional feature: the Drawer, which is used for displaying the menu with a hierarchy.

    - -

    To develop the application as a Tizen native application, add a layout on the Conformant, and add a Naviframe to the layout. This layout has a content area for the Drawer and Naviframe, and its style name is "layout/drawer/panel". To use this layout, use the following code:

    - -
    -layout = elm_layout_add(parent);
    -elm_layout_theme_set(layout, "layout", "drawer", "panel");
    -
    - -

    The style includes parts for locating the Drawer and the main view. In the Drawer area, you can add a list to indicate the menu. In the main view, you can add a Naviframe to organize the view of the layout.

    - -

    Figure: Email UI and layout

    -

    Email UI and layout

    - -

    For more information, see the Email sample application.

    - -

    Creating a Simple Clock View

    - -

    This sample creates a basic clock view that shows the time, current city, and date. This sample demonstrates how to use a box, container component, and label to create a basic layout. The application includes the following UI components:

    - -
      -
    • Elm_window: Basic canvas for rendering the screen
    • -
    • Elm_conformant: Support indicator area
    • -
    • Elm_naviframe: View manager component
    • -
    • Elm_box: Container component for layouting other UI components
    • -
    • Elm_label: Basic UI component for showing text with a tag
    • -
    - -

    The following figure illustrates the main view of the simple clock sample application and its wireframe structure.

    - -

    Figure: Simple clock screen

    -

    Simple clock screen

    - -

    The basic clock is implemented in the world_clock.c file. In this application, the data structure for application is following:

    - -
    typedef struct appdata
    -{
    -   // Save the window
    -   Evas_Object *win;
    -} 
    -appdata_s;
    -
    - -

    The information in appdata is used for the entire system. In this sample application, the information is related to handling the HW back key.

    - -

    The single callback function for application handling is app_create, and it only creates the basic GUI:

    - -
    int
    -main(int argc, char *argv[])
    -{
    -   appdata_s *ad = {0,};
    -   app_event_callback_s event_callback = {0,};
    -   int ret = 0;
    -
    -   event_callback.create = app_create;
    -   event_callback.terminate = app_terminate;
    -   event_callback.pause = app_pause;
    -   event_callback.resume = app_resume;
    -   event_callback.app_control = app_control;
    -
    -   ui_app_add_event_handler(&handlers[APP_EVENT_LOW_BATTERY], APP_EVENT_LOW_BATTERY, ui_app_low_battery, &ad);
    -   ui_app_add_event_handler(&handlers[APP_EVENT_LOW_MEMORY], APP_EVENT_LOW_MEMORY, ui_app_low_memory, &ad);
    -   ui_app_add_event_handler(&handlers[APP_EVENT_DEVICE_ORIENTATION_CHANGED], APP_EVENT_DEVICE_ORIENTATION_CHANGED, ui_app_orient_changed, &ad);
    -   ui_app_add_event_handler(&handlers[APP_EVENT_LANGUAGE_CHANGED], APP_EVENT_LANGUAGE_CHANGED, ui_app_lang_changed, &ad);
    -   ui_app_add_event_handler(&handlers[APP_EVENT_REGION_FORMAT_CHANGED], APP_EVENT_REGION_FORMAT_CHANGED, ui_app_region_changed, &ad);
    -   ui_app_remove_event_handler(handlers[APP_EVENT_LOW_MEMORY]);
    -
    -   ret = app_main(argc, argv, &event_callback, &ad);
    -   if (ret != APP_ERROR_NONE) 
    -   {
    -      LOGE("app_main() is failed. err = %d", ret);
    -   }
    -
    -   return ret;
    -}
    -
    -static bool
    -app_create(void *data)
    -{
    -   appdata_s *ad = data;
    -   create_base_gui(ad);
    -
    -   return true;
    -}
    -
    - -

    Use the create_base_gui() function to create a basic layout with a window, conformant and naviframe. This is the basic layout in the Tizen mobile environment.

    - -
    ad->win = elm_win_util_standard_add(PACKAGE, PACKAGE);
    -elm_win_autodel_set(ad->win, EINA_TRUE);
    -
    -// Conformant
    -conform = elm_conformant_add(ad->win);
    -elm_win_conformant_set(ad->win, EINA_TRUE);
    -evas_object_size_hint_weight_set(conform, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
    -elm_win_resize_object_add(ad->win, conform);
    -evas_object_show(conform);
    -
    -// Naviframe
    -nf = elm_naviframe_add(conform);
    -elm_object_content_set(conform, nf);
    -evas_object_show(nf);
    -
    - -

    After creating a basic layout, create the main layout for the application. In this sample, it contains a box with 3 labels. The labels show the time, city and date. To add the labels to the box, use the elm_box_pack_end() function.

    - -

    After adding the labels, you must set their text. You can set or decorate the text in the labels using the elm_object_text_set() function. You can modify the text size (font_size), color (color), and thickness (b).

    - -
    -// Add the box
    -box = elm_box_add(nf);
    -// Create a label
    -label1 = elm_label_add(box);
    -// Set text to the label with a tag
    -elm_object_text_set(label1, "<font_size=110><color=#000000>07:26</color></font_size>");
    -// Add the label to the box
    -elm_box_pack_end(box, label1);
    -// Change label visibility
    -evas_object_show(label1);
    -
    -// Repeat with other labels
    -
    -evas_object_show(box);
    -
    - -

    After creating the box with labels, set the box as a new view. You can also set the title of the application. These operations are handled by the naviframe using the elm_naviframe_item_push() function:

    - -
    elm_naviframe_item_push(nf, _("World Clock"), NULL, NULL, box, "basic");
    - -

    The parameters include the title, the name of the UI component added as a new view, and the naviframe style. The basic style is used for a simple view with normal title.

    - -

    The following figure illustrates the UI component hierarchy of the application.

    - -

    Figure: Simple clock components

    -

    Simple clock components

    - -

    Set the HW key handler. The Tizen mobile environment supports the More and back keys, but only the back key is handled in this sample.

    -
    eext_object_event_callback_add(ad->win, EEXT_CALLBACK_BACK, win_back_cb, ad);
    -
    - -

    After setting the callback function, the win_back_cb callback is invokes when a back key is pressed. The win_back_cb callback will hide the window:

    -
    static void
    -win_back_cb(void *data , int type , void *event)
    -{
    -   appdata_s *ad = data;
    -   elm_win_lower(ad->win);
    -}
    -
    - -

    Creating a Complex Clock View

    - -

    This sample creates a complex clock view. The sample demonstrates how to organize a basic layout using boxes. The application includes the following UI components:

    - - -
      -
    • Elm_window: Basic canvas for rendering the screen
    • -
    • Elm_conformant: Support indicator area
    • -
    • Elm_naviframe: View manager component
    • -
    • Elm_box: Container component for layouting other UI components
    • -
    • Elm_label: Basic UI component for showing text with a tag
    • -
    • Elm_genlist: List component
    • -
    • Elm_button: Simple push button
    • -
    - -

    The following figure illustrates the main view of the complex clock sample application and its wireframe structure.

    - -

    Figure: Complex clock screen

    -

    Complex clock screen

    - -

    Basic GUI

    - -

    The basic clock is implemented in the world_clock.c file. In this application, the data structure for application is following:

    - -
    typedef struct appdata
    -{
    -   // Save the window
    -   Evas_Object *win;
    -} 
    -appdata_s;
    -
    - -

    The information in appdata is used for the entire system. In this sample application, the information is related to handling the HW back key.

    - -

    The single callback function for application handling is app_create, and it only creates the basic GUI:

    - -
    int
    -main(int argc, char *argv[])
    -{
    -   appdata_s *ad = {0,};
    -   app_event_callback_s event_callback = {0,};
    -   int ret = 0;
    -
    -   event_callback.create = app_create;
    -   event_callback.terminate = app_terminate;
    -   event_callback.pause = app_pause;
    -   event_callback.resume = app_resume;
    -   event_callback.app_control = app_control;
    -
    -   ui_app_add_event_handler(&handlers[APP_EVENT_LOW_BATTERY], APP_EVENT_LOW_BATTERY, ui_app_low_battery, &ad);
    -   ui_app_add_event_handler(&handlers[APP_EVENT_LOW_MEMORY], APP_EVENT_LOW_MEMORY, ui_app_low_memory, &ad);
    -   ui_app_add_event_handler(&handlers[APP_EVENT_DEVICE_ORIENTATION_CHANGED], APP_EVENT_DEVICE_ORIENTATION_CHANGED, ui_app_orient_changed, &ad);
    -   ui_app_add_event_handler(&handlers[APP_EVENT_LANGUAGE_CHANGED], APP_EVENT_LANGUAGE_CHANGED, ui_app_lang_changed, &ad);
    -   ui_app_add_event_handler(&handlers[APP_EVENT_REGION_FORMAT_CHANGED], APP_EVENT_REGION_FORMAT_CHANGED, ui_app_region_changed, &ad);
    -   ui_app_remove_event_handler(handlers[APP_EVENT_LOW_MEMORY]);
    -
    -   ret = app_main(argc, argv, &event_callback, &ad);
    -   if (ret != APP_ERROR_NONE) 
    -   {
    -      LOGE("app_main() is failed. err = %d", ret);
    -   }
    -
    -   return ret;
    -}
    -
    -static bool
    -app_create(void *data)
    -{
    -   appdata_s *ad = data;
    -   create_base_gui(ad);
    -
    -   return true;
    -}
    -
    - -

    The base GUI of the application contains the following elements:

    - -
      -
    • Clock
    • -
    • List
    • -
    • Main layout with buttons
    • -
    - -

    Clock

    - -

    The clock element contains 3 labels. The labels are packed as a single box component, which is part of the main layout.

    -
    static Evas_Object *
    -create_clock(Evas_Object *nf)
    -{
    -   Evas_Object *box, *label1, *label2, *label3;
    -
    -   // Box
    -   box = elm_box_add(nf);
    -
    -   label1 = elm_label_add(box);
    -   elm_object_text_set(label1, "<font_size=110><color=#000000>07:26</color></font_size>");
    -   elm_box_pack_end(box, label1);
    -   evas_object_show(label1);
    -
    -   evas_object_show(box);
    -
    -   return box;
    -}
    -
    - -

    List

    - -

    This element contains a list of cities. The UI component used is genlist, which is a complex list able to show information with various styles.

    -
    static Evas_Object *
    -create_list(Evas_Object *nf)
    -{
    -   Evas_Object* list;
    -   Elm_Genlist_Item_Class *itc = NULL;
    -   int i, num_of_item;
    -   Elm_Object_Item *it;
    -   
    -   list = elm_genlist_add(nf);
    -
    - -

    To add items to the list, use the Elm_Genlist_Item_Class class. After adding a new class, set callback function to detect, when the item is rendered.

    -
    itc = elm_genlist_item_class_new();
    -   itc->item_style = "2line.top.4";
    -   itc->func.text_get = gl_text_get_cb;
    -   itc->func.content_get = NULL;
    -   itc->func.del = NULL;
    -
    - -

    In this application, all the list items are similar and use the same callback function (gl_text_get_cb()) for setting text, so only 1 item class is created:

    -
    static char*
    -gl_text_get_cb(void *data, Evas_Object *obj, const char *part)
    -{
    -   item_data_s *id = data;
    -   char buf[1024];
    -
    -   if (id->index == 0) 
    -   {
    -      if (!strcmp(part, "elm.text.main.left.top")) 
    -      {
    -         snprintf(buf, 1023, "%s", "07:26");
    -
    -         return strdup(buf);
    -      }
    -      else if (!strcmp(part, "elm.text.sub.right.top")) 
    -      {
    -         snprintf(buf, 1023, "%s", "Cardiff");
    -
    -         return strdup(buf);
    -      }
    -      else if (!strcmp(part, "elm.text.sub.left.bottom")) 
    -      {
    -         snprintf(buf, 1023, "%s", "Wen, Jan 1");
    -
    -         return strdup(buf);
    -      }
    -      else if (!strcmp(part, "elm.text.sub.right.bottom")) 
    -      {
    -         snprintf(buf, 1023, "%s", "wales");
    -
    -         return strdup(buf);
    -      }
    -   }
    -
    -   return NULL;
    -}
    -
    - -

    Append items using the elm_genlist_item_append() function. In this application, 3 items are added:

    -
    num_of_item = 3;
    -
    -   for (i = 0; i < num_of_item; i++) 
    -   {
    -      item_data_s *id = calloc(sizeof(item_data_s), 1);
    -      id->index = i;
    -      it = elm_genlist_item_append(list,
    -                                   itc,
    -                                   id,
    -                                   NULL,
    -                                   ELM_GENLIST_ITEM_NONE,
    -                                   NULL,
    -                                   id);
    -      id->item = it;
    -   }
    -
    - -

    Main Layout with a Button

    - -

    In the main layout, the other layout elements are merged together and a button added. The following example describes handling the main layout:

    - -
    static void
    -create_base_gui(appdata_s *ad)
    -{
    -   Evas_Object *conform, *nf, *box, *clock, *layout, *rect, *button;
    -   // Window
    -   ad->win = elm_win_util_standard_add(PACKAGE, PACKAGE);
    -   elm_win_autodel_set(ad->win, EINA_TRUE);
    -
    -   // Conformant
    -   conform = elm_conformant_add(ad->win);
    -   elm_win_conformant_set(ad->win, EINA_TRUE);
    -   evas_object_size_hint_weight_set(conform, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
    -   elm_win_resize_object_add(ad->win, conform);
    -   evas_object_show(conform);
    -
    -   // Naviframe
    -   nf = elm_naviframe_add(conform);
    -   elm_object_content_set(conform, nf);
    -   evas_object_show(nf);
    -}
    -
    - -

    The box component is used to organize the main layout. The box is expanded as much as possible to fill the entire view.

    -
       // Box
    -   box = elm_box_add(nf);
    -   evas_object_size_hint_weight_set(box, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
    -   evas_object_size_hint_align_set(box, EVAS_HINT_FILL, EVAS_HINT_FILL);
    -
    - -

    The box contains the following elements:

    - -
      - -
    • The clock element contains 3 labels. The parameter for the evas_object_size_hint_weight_set() function is 0.1 meaning that the height of the clock box occupies 30% of the available area.

      -
         clock = create_clock(nf);
      -   evas_object_size_hint_weight_set(clock, EVAS_HINT_EXPAND, 0.3);
      -   evas_object_size_hint_align_set(clock, EVAS_HINT_FILL, EVAS_HINT_FILL);
      -   elm_box_pack_end(box, clock);
      -
      -
    • - -
    • The list element is packed into the box. As the genlist elements does not have a determined size, its size depends on the layout parameter.

      -
      -   layout = elm_layout_add(box);
      -   elm_layout_theme_set(layout, "layout", "application", "default");
      -   evas_object_size_hint_weight_set(layout, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      -   evas_object_size_hint_align_set(layout, EVAS_HINT_FILL, EVAS_HINT_FILL);
      -   rect = create_list(nf);
      -   elm_layout_content_set(layout, "elm.swallow.content", rect);
      -   evas_object_show(rect);
      -   evas_object_show(layout);
      -   elm_box_pack_end(box, layout);
      -
      -
    • - -
    • The button element has a callback function to detect, when the button is clicked.

      -
      button = elm_button_add(box);
      -   evas_object_smart_callback_add(button, "clicked", btn_clicked_cb, NULL);
      -   evas_object_size_hint_weight_set(button, EVAS_HINT_EXPAND, 0.1);
      -   evas_object_size_hint_align_set(button, EVAS_HINT_FILL, EVAS_HINT_FILL);
      -   elm_object_text_set(button, "Terminate");
      -   evas_object_show(button);
      -   elm_box_pack_end(box, button);
      -
      -
    • -
    - -

    The following figure illustrates the UI component hierarchy of the application.

    - -

    Figure: Complex clock components

    -

    Complex clock components

    - -

    Add the main layout to the naviframe, and set the HW key handler:

    -
    eext_object_event_callback_add(ad->win, EEXT_CALLBACK_BACK, win_back_cb, ad);
    -
    - -

    After setting the callback function, the win_back_cb callback is invokes when a back key is pressed. The win_back_cb callback will hide the window:

    -
    static void
    -win_back_cb(void *data , int type , void *event)
    -{
    -   appdata_s *ad = data;
    -   elm_win_lower(ad->win);
    -}
    -
    - - - -
    - -Go to top - - - - - - - - diff --git a/org.tizen.tutorials/html/native/ui/efl_util_tutorial_n.htm b/org.tizen.tutorials/html/native/ui/efl_util_tutorial_n.htm deleted file mode 100644 index 17b545a..0000000 --- a/org.tizen.tutorials/html/native/ui/efl_util_tutorial_n.htm +++ /dev/null @@ -1,312 +0,0 @@ - - - - - - - - - - - - - - EFL UTIL: Using EFL Utilities - - - - - - -
    -

    EFL UTIL: Using EFL Utilities

    - - -

    This tutorial demonstrates how you can adjust the level of a notification window using the EFL UTIL API.

    - -

    Warm-up

    -

    Become familiar with the EFL UTIL, Elementary, and Evas API basics by learning about:

    - - - - -

    Initializing EFL Utility

    - -

    To use the EFL UTIL API, the following header file has to be included:

    -
    #include <efl_util.h>
    - -

    Creating a Notification Window and Setting a Notification Window Level

    - -

    To create a notification window and set the window level, use the efl_util_set_notification_window_level() function. If the window type is not notification type, the function returns an error.

    -
    #include <Elementary.h>
    -#include <dlog.h>
    -
    -void create_win() 
    -{
    -   Evas_Object *eo;
    -   efl_util_error_e error;
    -   char *name = "Notification window";
    -   
    -   // Create notification window
    -   eo = elm_win_add(NULL, name, ELM_WIN_NOTIFICATION);
    -   if (!eo) return;
    -   
    -   // Set notification level
    -   error = efl_util_set_notification_window_level
    -           (eo, EFL_UTIL_NOTIFICATION_LEVEL_1);
    -   if (error != EFL_UTIL_ERROR_NONE)
    -   {
    -      // Do error handling
    -   }
    -}
    -
    - -

    Getting the Notification Window Level

    - -

    To get the notification window level, use the efl_util_get_notification_window_level() function:

    - -
    void create_win() 
    -{
    -   Evas_Object *eo;
    -   efl_util_error_e error;
    -   efl_util_notification_level_e notification_level;
    -   char *name = "Notification window";
    -   
    -   // Create notification window
    -   eo = elm_win_add(NULL, name, ELM_WIN_NOTIFICATION);
    -   if (!eo) return;
    -   
    -   // Get notification level
    -   error = efl_util_get_notification_window_level
    -           (eo, &notification_level);
    -   if (error == EFL_UTIL_ERROR_NONE) 
    -   {
    -      switch (notification_level) 
    -      {
    -         case EFL_UTIL_NOTIFICATION_LEVEL_1:
    -            // Do something for notification level 1
    -            break;
    -         case EFL_UTIL_NOTIFICATION_LEVEL_2:
    -            // Do something for notification level 2
    -            break;
    -      }
    -   }
    -}
    - -

    Getting a Screenshot

    - -

    To get a screenshot:

    - -
    1. Initialize with the efl_util_screenshot_initialize() function: -
      -#include <tbm_surface.h>
      -#include <X11/Xlib.h>
      -
      -void capture()
      -{
      -   efl_util_screenshot_h screenshot = NULL;
      -   tbm_surface_h tbm_surface = NULL;
      -   tbm_surface_info_s tsuri;
      -
      -   screenshot = efl_util_screenshot_initialize(width, height);
      -
    2. - -
    3. After getting the efl_util_screenshot_h structure, execute the efl_util_screenshot_take_tbm_surface() function to get the tbm_surface handler which has the screenshot data. -
      -   if (screenshot) 
      -   {
      -      tbm_surface = efl_util_screenshot_take_tbm_surface(screenshot);
      -      if (tbm_surface) 
      -      {
      -         // Treat tbm_surface handler (screenshot data)
      -      }
      -
    4. - -
    5. Free the resources with the efl_util_screenshot_deinitialize() function: -
      -      efl_util_screenshot_deinitialize(screenshot);
      -   }
      -}
    - -

    Generating a Key Input Event

    - -

    To generate key input events:

    - -
    1. Execute the efl_util_input_initialize_generator() function: -
      -void key_event_generator()
      -{
      -   int ret = EFL_UTIL_ERROR_NONE;
      -   efl_util_inputgen_h inputgen = NULL;
      -
      -   inputgen = efl_util_input_initialize_generator(EFL_UTIL_INPUT_DEVTYPE_KEYBOARD);
      -   if (!inputgen)
      -   {
      -      // Failed to initiailize input generator system.
      -      return;
      -   }
      -
    2. -
    3. After setting input device type, execute the efl_util_input_generate_key() function to generate key input events: -
      -   ret = efl_util_input_generate_key(inputgen, "XF86Menu", 1);
      -   if (ret != EFL_UTIL_ERROR_NONE) 
      -   {
      -      // Failed to generate a "XF86Menu" key press event
      -      ret = efl_util_input_deinitialize_generator(inputgen);
      -      if (ret != EFL_UTIL_ERROR_NONE)
      -      {
      -         // Failed to deinitialize input generator system.
      -      }
      -      return;
      -   }
      -   ret = efl_util_input_generate_key(inputgen, "XF86Menu", 0);
      -   if (ret != EFL_UTIL_ERROR_NONE) 
      -   {
      -      // Failed to generate a "XF86Menu" key release event
      -      ret = efl_util_input_deinitialize_generator(inputgen);
      -      if (ret != EFL_UTIL_ERROR_NONE)
      -      {
      -         // Failed to deinitialize input generator system.
      -      }
      -      return;
      -   }
      -
    4. -
    5. Free the resources with the efl_util_input_deinitialize_generator() function: -
      -   ret = efl_util_input_deinitialize_generator(inputgen);
      -   if (ret != EFL_UTIL_ERROR_NONE)
      -   {
      -      // Failed to deinitialize input generator system.
      -   }
      -}
    - - -

    Generating a Touch Input Event

    - -

    To generate touch input events:

    - -
    1. Execute the efl_util_input_initialize_generator() function: -
      -void touch_event_generator()
      -{
      -   int ret = EFL_UTIL_ERROR_NONE;
      -   efl_util_inputgen_h inputgen = NULL;
      -
      -   inputgen = efl_util_input_initialize_generator(EFL_UTIL_INPUT_DEVTYPE_TOUCHSCREEN);
      -   if (!inputgen)
      -   {
      -      // Failed to initiailize input generator system.
      -      return;
      -   }
      -
    2. -
    3. After setting input device type, execute the efl_util_input_generate_touch() function to generate touch input events: -
      -   ret = efl_util_input_generate_touch(inputgen, 0, EFL_UTIL_INPUT_TOUCH_BEGIN, 100, 100);
      -   if (ret != EFL_UTIL_ERROR_NONE) 
      -   {
      -      // Failed to generate a first finger touch press event on (100, 100)
      -      ret = efl_util_input_deinitialize_generator(inputgen);
      -      if (ret != EFL_UTIL_ERROR_NONE)
      -      {
      -         // Failed to deinitialize input generator system.
      -      }
      -      return;
      -   }
      -
      -   ret = efl_util_input_generate_touch(inputgen, 0, EFL_UTIL_INPUT_TOUCH_UPDATE, 110, 110);
      -   if (ret != EFL_UTIL_ERROR_NONE) 
      -   {
      -      // Failed to generate a first finger touch move event to (110, 110)
      -      ret = efl_util_input_deinitialize_generator(inputgen);
      -      if (ret != EFL_UTIL_ERROR_NONE)
      -      {
      -         // Failed to deinitialize input generator system.
      -      }
      -      return;
      -   }
      -
      -   ret = efl_util_input_generate_touch(inputgen, 0, EFL_UTIL_INPUT_TOUCH_END, 110, 110);
      -   if (ret != EFL_UTIL_ERROR_NONE) 
      -   {
      -      // Failed to generate a first finger touch release event to (110, 110)
      -      ret = efl_util_input_deinitialize_generator(inputgen);
      -      if (ret != EFL_UTIL_ERROR_NONE)
      -      {
      -         // Failed to deinitialize input generator system.
      -      }
      -      return;
      -   }
      -
    4. -
    5. Free the resources with the efl_util_input_deinitialize_generator() function: -
      -   ret = efl_util_input_deinitialize_generator(inputgen);
      -   if (ret != EFL_UTIL_ERROR_NONE)
      -   {
      -      // Failed to deinitialize input generator system.
      -   }
      -}
    - - - - - -
    - -Go to top - - - - - - - diff --git a/org.tizen.tutorials/html/native/ui/elm_transit_tutorial_n.htm b/org.tizen.tutorials/html/native/ui/elm_transit_tutorial_n.htm deleted file mode 100644 index 17799e9..0000000 --- a/org.tizen.tutorials/html/native/ui/elm_transit_tutorial_n.htm +++ /dev/null @@ -1,654 +0,0 @@ - - - - - - - - - - - - - - Elementary Animations: Applying Transition Effects to an Evas Object - - - - - - -
    -

    Elementary Animations: Applying Transition Effects to an Evas Object

    - - -

    This tutorial demonstrates how you can use Elm Transit to create animated transitions effects, such as rotation, wiping, zooming, resizing, and fading, to an Evas_Object.

    - -

    Warm-up

    -

    Become familiar with the Ecore, Elementary, and Evas API basics by learning about:

    - - -

    Setting Up the Application

    - -

    First create a basic application like explained in the Basic Tutorial.

    - -

    When the application is ready, create Evas objects and animate them. In this example, one single object is animated with different type of animations.

    - -

    Create the structure of our application represented by a struct named appdata

    - -
    typedef struct appdata 
    -{
    -   Evas_Object *win;
    -   Evas_Object *label;
    -   Evas_Object *button;
    -   Evas_Object *buttonbck;
    -   Evas_Object *hbox;
    -   Evas_Object *left_vbox;
    -   Evas_Object *center_vbox;
    -   Evas_Object *right_vbox;
    -   float rt_angle, zto, zfrom;
    -} appdata_s;
    -
    - -

    This structure holds the main UI components of the application:

    - -
      -
    • win: the main window
    • -
    • label: the title label
    • -
    • button: a button object, the target of the animations
    • -
    • buttonbck: a button representing the back of the target button
    • -
    • left_vbox: a vertical box to place the first buttons column
    • -
    • center_vbox: a vertical box to store the second buttons column
    • -
    • right_vbox: a vertical box to store the last buttons column
    • -
    • hbox: a horizontal box to store the vertical boxes
    • -
    • rt_angle, zto, zfrom: these variables are used to store values for animations
    • -
    - -

    Place the UI components on the application's canvas. To make things easier, the UI component creation is split into two functions.

    - -

    The first function creates UI components on the main window, and the second in the boxes.

    - -
    create_base_gui(appdata_s *ad)
    -{
    -   ad->rt_angle = 360.0;
    -   ad->zfrom = 1.0;
    -   ad->zto = 2.0;
    -
    -   // Window
    -   ad->win = elm_win_util_standard_add(PACKAGE, PACKAGE);
    -   elm_win_autodel_set(ad->win, EINA_TRUE);
    -
    -   if (elm_win_wm_rotation_supported_get(ad->win)) 
    -   {
    -      int rots[4] = { 0, 90, 180, 270 };
    -      elm_win_wm_rotation_available_rotations_set(ad->win, (const int *)(&rots), 4);
    -   }
    -
    -   evas_object_smart_callback_add(ad->win, "delete,request", win_delete_request_cb, NULL);
    -
    -   // Label
    -   ad->label = elm_label_add(ad->win);
    -   elm_object_text_set(ad->label, "Effects Tutorial");
    -   evas_object_size_hint_weight_set(ad->label, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
    -   elm_win_resize_object_add(ad->win, ad->label);
    -   evas_object_show(ad->label);
    -
    -   // Show the window after the base GUI is set up
    -   evas_object_show(ad->win);
    -
    -   ecore_event_handler_add(ECORE_EVENT_KEY_DOWN, keydown_cb, ad);
    -
    -   // Creation a button in the app window
    -   ad->button = elm_button_add(ad->win);
    -
    -   // Moving the button to x=50 y=100
    -   evas_object_move(ad->button, 50, 100);
    -
    -   // Resizing the button 100x50
    -   evas_object_resize(ad->button, 200, 50);
    -
    -   // Showing the button
    -   evas_object_show(ad->button);
    -
    -   // Creation a back button in the app window
    -   ad->buttonbck = elm_button_add(ad->win);
    -   elm_object_text_set(ad->buttonbck, "Button back");
    -   evas_object_move(ad->buttonbck, 50, 100);
    -   evas_object_resize(ad->buttonbck, 200, 50);
    -
    -   _create_btn_box(ad);
    -
    -} // End of create_base_gui
    -
    - -

    This function takes appdata_s *ad as its only parameter. This function is called by the creation callback app_create of the Tizen application (event_callback.create = app_create;) in the main function of the application.

    - -

    Set up the needed values like the rotation angle, the original zoom value (zfrom), and the destination zoom value (zto).

    - -
    ad->rt_angle = 360.0;
    -ad->zfrom = 1.0;
    -ad->zto = 2.0;
    -
    - -

    Create the main window with a title and add the delete callback:

    - -
    // Window
    -ad->win = elm_win_util_standard_add(PACKAGE, PACKAGE);
    -elm_win_autodel_set(ad->win, EINA_TRUE);
    -
    -if (elm_win_wm_rotation_supported_get(ad->win)) 
    -{
    -   int rots[4] = { 0, 90, 180, 270 };
    -   elm_win_wm_rotation_available_rotations_set(ad->win, (const int *)(&rots), 4);
    -}
    -
    -evas_object_smart_callback_add(ad->win, "delete,request", win_delete_request_cb, NULL);
    -
    -// Label
    -ad->label = elm_label_add(ad->win);
    -elm_object_text_set(ad->label, "Effects Tutorial");
    -evas_object_size_hint_weight_set(ad->label, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
    -elm_win_resize_object_add(ad->win, ad->label);
    -evas_object_show(ad->label);
    -
    -// Show the window after the base GUI is set up
    -evas_object_show(ad->win);
    -
    -ecore_event_handler_add(ECORE_EVENT_KEY_DOWN, keydown_cb, ad);
    -
    - -

    Next create the animation target button and the back button. Call the button box creation function with the application data as its parameter.

    - -
    _create_btn_box(ad);
    -
    - -

    Add a set of buttons to this box that starts animations on the animation target.

    - -

    Create the structure of the buttons box with three columns (vertical boxes) and one horizontal for the main container.

    - -
    // Creation of the main container box
    -ad->hbox = elm_box_add(ad->win);
    -elm_box_horizontal_set(ad->hbox, EINA_TRUE);
    -elm_box_homogeneous_set(ad->hbox, EINA_TRUE);
    -evas_object_move(ad->hbox, 10, 500);
    -evas_object_show(ad->hbox);
    -
    -// Creation of the first column
    -ad->left_vbox = elm_box_add(ad->hbox);
    -elm_box_horizontal_set(ad->left_vbox, EINA_FALSE);
    -elm_box_homogeneous_set(ad->left_vbox, EINA_TRUE);
    -evas_object_show(ad->left_vbox);
    -elm_box_pack_start(ad->hbox, ad->left_vbox);
    -
    -// Creation of the second column
    -ad->center_vbox = elm_box_add(ad->hbox);
    -elm_box_horizontal_set(ad->center_vbox, EINA_FALSE);
    -elm_box_homogeneous_set(ad->center_vbox, EINA_TRUE);
    -evas_object_show(ad->center_vbox);
    -elm_box_pack_end(ad->hbox, ad->center_vbox);
    -
    -// Creation of the last column
    -ad->right_vbox = elm_box_add(ad->hbox);
    -elm_box_horizontal_set(ad->right_vbox, EINA_FALSE);
    -elm_box_homogeneous_set(ad->right_vbox, EINA_TRUE);
    -evas_object_show(ad->right_vbox);
    -elm_box_pack_end(ad->hbox, ad->right_vbox);
    -
    - -

    Then create the first action button for the resize effect.

    - -
    // Button creation
    -btn_resize = elm_button_add(ad->win);
    -// Setting the button text
    -elm_object_text_set(btn_resize, "Resize");
    -// Setting the hint weight policy
    -evas_object_size_hint_weight_set(btn_resize, EVAS_HINT_FILL, EVAS_HINT_FILL);
    -// Showing the button
    -evas_object_show(btn_resize);
    -// Setting the "clicked" callback
    -evas_object_smart_callback_add(btn_resize, "clicked", _btn_resize_cb, ad);
    -// Adding the button to the first column
    -elm_box_pack_end(ad->left_vbox, btn_resize);
    -
    - -

    evas_object_smart_callback_add defines the callback function that is to be called when the button is clicked. In this example, set a _btn_resize_cb function and pass the application data ad to this callback function.

    - -

    The callback by itself only sets a new text for the animation target button, and calls a function which will actually animate the button.

    - -
    static void _btn_resize_cb(void *data, Evas_Object *btn, void *ev)
    -{
    -   appdata_s *ad = data;
    -
    -   // Starting the rotation effect 360 degrees
    -   // evas_object_resize(ad->button, 100, 50);
    -   elm_object_text_set(ad->button, "Resize");
    -   _resize_effect(ad->button);
    -
    -}
    -
    - -

    This function is an evas_object_smart_callback and thus needs to have its specific prototype: it does not return anything and receives three parameters:

    - -
      -
    • data: data to be passed
    • -
    • btn: the object the callback is being called about
    • -
    • ev: the actual event, seldom used
    • -
    - -

    In this case, use data to pass the application data to the callback. However, the parameter's type is void * and not appdata_s *. Initialize a variable of the correct type with the pointer.

    -
    appdata_s *ad = data;
    -
    - -

    Then use the application data in the callback function. At this point create the animation directly in the callback function, but it is more straightforward to encapsulate the animation process into a dedicated function. _resize_effect implements the animation code:

    - -
    static void _resize_effect(Evas_Object *obj)
    -{
    -   // Elementary Transition declaration and creation
    -   Elm_Transit *trans = elm_transit_add();
    -
    -   // Adding the transition target object
    -   elm_transit_object_add(trans, obj);
    -
    -   // Setting the resize effect
    -   elm_transit_effect_resizing_add(trans, 100, 50, 300, 150);
    -
    -   // Setting the transition duration
    -   elm_transit_duration_set(trans, 3.0);
    -
    -   // Starting the transition
    -   elm_transit_go(trans);
    -}
    -
    - -

    Create an Elm_Transit * object representing the transition.

    - -
    Elm_Transit *trans = elm_transit_add();
    -
    - -

    Then add the target object to the transition

    - -
    elm_transit_object_add(trans, obj);
    -
    - -

    Add a resizing transition to the object with the origin and destination width and height in pixels.

    - -
    elm_transit_effect_resizing_add(trans, 100, 50, 300, 150);
    -
    -

    100 and 50 are respectively the object's width and height when the effect begins, whereas 300 and 150 are respectively the object's width and height when the effect ends: the object grows from 100×50 to 300×150.

    - -

    After that set the transition duration with elm_transit_duration_set.

    -
    elm_transit_duration_set(trans, 3.0);
    -
    - -

    The animation lasts three seconds. The duration parameter is a double.

    - -

    Now start the animation by calling elm_transit_go with the Elm_Transit object.

    - -
    elm_transit_go(trans);
    -
    - -

    When the resize button is clicked, the animation target button grows.

    - -

    All the action buttons are created exactly the same way as the resize button, with a callback and an animation function.

    - -

    Creating a Rotation Effect

    - -

    This effect rotates the animation target button with an angle of 360°. This angle is stored in the application data as ad->rt_angle.

    - -

    Create the button and add it to the center column in the _create_btn_box function.

    - -
    // The rotation button
    -btn_rotate = elm_button_add(ad->win);
    -elm_object_text_set(btn_rotate, "Rotate");
    -evas_object_size_hint_weight_set(btn_rotate, EVAS_HINT_FILL, EVAS_HINT_FILL);
    -evas_object_show(btn_rotate);
    -evas_object_smart_callback_add(btn_rotate, "clicked", _btn_rotate_cb, ad);
    -elm_box_pack_end(ad->center_vbox, btn_rotate);
    -
    - -

    In the rotate button callback, call the effect function with the target button as first parameter and the rotation angle as the second one.

    - -
    static void _btn_rotate_cb(void *data, Evas_Object *btn, void *ev)
    -{
    -   appdata_s *ad = data;
    -
    -   // Setting the button text
    -   elm_object_text_set(ad->button, "Rotate");
    -   _rotation_effect(ad->button, ad->rt_angle);
    -}
    -
    - -

    The animation function rotates the animation target by adding a rotation effect with elm_transit_effect_rotation_add. This function takes three parameters:

    - -
      -
    • Elm_Transit
    • -
    • the rotation position at which the effect begins
    • -
    • the rotation position at which the effect ends
    • -
    - -

    Rotation starts at 0° to finish at 360°. The animation lasts two seconds.

    - -
    static void _rotation_effect(Evas_Object *obj, float angle)
    -{
    -   Elm_Transit *trans = elm_transit_add();
    -   elm_transit_object_add(trans, obj);
    -
    -   // Rotates the object from its original angle to given degrees to the right
    -   elm_transit_effect_rotation_add(trans, 0.0, angle);
    -   elm_transit_duration_set(trans, 2.0);
    -   elm_transit_go(trans);
    -}
    -
    - -

    Creating a Zoom Effect

    - -

    The zoom effect zooms on the animation target to make it twice bigger. Store the source rate and the destination rate in the application data using ad->zfrom and ad->zto.

    -

    Create the button and add it to the center column in the _create_btn_box function.

    - -
    // The zoom button
    -btn_zoom = elm_button_add(ad->win);
    -elm_object_text_set(btn_zoom, "Zoom");
    -evas_object_size_hint_weight_set(btn_zoom, EVAS_HINT_FILL, EVAS_HINT_FILL);
    -evas_object_show(btn_zoom);
    -evas_object_smart_callback_add(btn_zoom, "clicked", _btn_zoom_cb, ad);
    -elm_box_pack_end(ad->right_vbox, btn_zoom);
    -
    - -

    Then add a callback function in order to perform the animation.

    - -
    static void _btn_zoom_cb(void *data, Evas_Object *btn, void *ev)
    -{
    -   appdata_s *ad = data;
    -
    -   // Starting the rotation effect 360 degrees
    -   // evas_object_resize(ad->button, 100, 50);
    -   elm_object_text_set(ad->button, "Zoom");
    -   _zoom_effect(ad->button, ad->zfrom, ad->zto);
    -}
    -
    - -

    To create the zoom effect, use elm_transit_effect_zoom_add with the start rate and the destination rate stored in application data (ad->zfrom and ad->zto)

    - -
    static void _zoom_effect(Evas_Object *obj, float from, float to)
    -{
    -   Elm_Transit *trans = elm_transit_add();
    -   elm_transit_object_add(trans, obj);
    -
    -   elm_transit_effect_zoom_add(trans, from, to);
    -   elm_transit_duration_set(trans, 2.0);
    -   elm_transit_go(trans);
    -}
    -
    - - -

    Creating a Flip Effect

    - -

    This effect is applied to a pair of objects, in the order they are added, to the Elm_Transit transition. In this example, add the animation target button and the button called buttonbck which represents the back of the target button.

    - -

    Create the action button for the flip effect:

    - -
    // The flip button
    -btn_flip = elm_button_add(ad->win);
    -elm_object_text_set(btn_flip, "Flip x");
    -evas_object_size_hint_weight_set(btn_flip, EVAS_HINT_FILL, EVAS_HINT_FILL);
    -evas_object_show(btn_flip);
    -evas_object_smart_callback_add(btn_flip, "clicked", _btn_flip_cb, ad);
    -elm_box_pack_end(ad->left_vbox, btn_flip);
    -
    - -

    The corresponding callback to create and start the animation with the two objects (target button and back button) to animate is like follows.

    - -
    static void _btn_flip_cb(void *data, Evas_Object *btn, void *ev)
    -{
    -   appdata_s *ad = data;
    -
    -   // Setting the button text
    -   elm_object_text_set(ad->button, "Flip");
    -   _flip_effect(ad->button, ad->buttonbck);
    -}
    -
    - -

    Create the function which runs the animation. This flip animation is created using elm_transit_effect_flip_add. The second parameter is the axis of the flip: in this example it is the X axis, so the button flips down to top to show the back button. The last parameter is the flip direction: EINA_TRUE means clockwise.

    - -
    static void _flip_effect(Evas_Object *obj, Evas_Object *obj2)
    -{
    -   Elm_Transit *trans;
    -
    -   trans = elm_transit_add();
    -   elm_transit_object_add(trans, obj);
    -   elm_transit_object_add(trans, obj2);
    -   elm_transit_effect_flip_add(trans, ELM_TRANSIT_EFFECT_FLIP_AXIS_X, EINA_TRUE);
    -
    -   elm_transit_duration_set(trans, 3.0);
    -   elm_transit_go(trans);
    -}
    -
    - -

    Creating a Blend Transition

    - -

    The blend effect also works the same way as the flip, but without the axes or direction information. Use the back button here as well. To create the blend effect button:

    - -
    // The blend button
    -btn_blend = elm_button_add(ad->win);
    -elm_object_text_set(btn_blend, "Blend");
    -evas_object_size_hint_weight_set(btn_blend, EVAS_HINT_FILL, EVAS_HINT_FILL);
    -evas_object_show(btn_blend);
    -evas_object_smart_callback_add(btn_blend, "clicked", _btn_blend_cb, ad);
    -elm_box_pack_end(ad->center_vbox, btn_blend);
    -
    - -

    The blend transition callback is:

    - -
    static void _btn_blend_cb(void *data, Evas_Object *btn, void *ev)
    -{
    -   appdata_s *ad = data;
    -
    -   // Setting the button text
    -   elm_object_text_set(ad->button, "Blend");
    -   _blend_effect(ad->button, ad->buttonbck);
    -}
    -
    - -

    Create and start the blend animation. This animation is created by adding it to and Elm_Transit with elm_transit_effect_blend_add. Add two objects, as for the flip.

    - -
    static void _blend_effect(Evas_Object *obj, Evas_Object *obj2)
    -{
    -   Elm_Transit *trans;
    -
    -   trans = elm_transit_add();
    -   elm_transit_object_add(trans, obj);
    -   elm_transit_object_add(trans, obj2);
    -   elm_transit_effect_blend_add(trans);
    -   elm_transit_duration_set(trans, 3.0);
    -   elm_transit_go(trans);
    -}
    -
    - -

    Creating a Fade Effect

    - -

    The fade effect works exactly the same way as the blend effect. First create the button:

    - -
    // The fade button
    -btn_fade = elm_button_add(ad->win);
    -elm_object_text_set(btn_fade, "Fade");
    -evas_object_size_hint_weight_set(btn_fade, EVAS_HINT_FILL, EVAS_HINT_FILL);
    -evas_object_show(btn_fade);
    -evas_object_smart_callback_add(btn_fade, "clicked", _btn_fade_cb, ad);
    -elm_box_pack_end(ad->right_vbox, btn_fade);
    -
    - -

    Then add the button's callback:

    - -
    static void _btn_fade_cb(void *data, Evas_Object *btn, void *ev)
    -{
    -   appdata_s *ad = data;
    -
    -
    -   // Setting the button text
    -   elm_object_text_set(ad->button, "Fade");
    -   _fade_effect(ad->button, ad->buttonbck);
    -}
    -
    - -

    The animation function calls elm_transit_effect_fade_add instead of elm_transit_effect_blend_add.

    - -
    static void _fade_effect(Evas_Object *obj, Evas_Object *obj2)
    -{
    -   Elm_Transit *trans;
    -
    -   trans = elm_transit_add();
    -   elm_transit_object_add(trans, obj);
    -   elm_transit_object_add(trans, obj2);
    -   elm_transit_effect_fade_add(trans);
    -   elm_transit_duration_set(trans, 3.0);
    -   elm_transit_go(trans);
    -}
    -
    - -

    Creating a Flip on y Axis

    - -

    This is same as the flip transition, but on y axis. To create a flip on y axis:

    - -
    // The flip y button
    -btn_flip_y = elm_button_add(ad->win);
    -elm_object_text_set(btn_flip_y, "Flip y");
    -evas_object_size_hint_weight_set(btn_flip_y, EVAS_HINT_FILL, EVAS_HINT_FILL);
    -evas_object_show(btn_flip_y);
    -evas_object_smart_callback_add(btn_flip_y, "clicked", _btn_flip_y_cb, ad);
    -elm_box_pack_end(ad->left_vbox, btn_flip_y);
    -
    -static void _btn_flip_y_cb(void *data, Evas_Object *btn, void *ev)
    -{
    -   appdata_s *ad = data;
    -
    -
    -   // Setting the button text
    -   elm_object_text_set(ad->button, "Flip 2");
    -   _flip_y_effect(ad->button, ad->buttonbck);
    -}
    -
    -static void _flip_y_effect(Evas_Object *obj, Evas_Object *obj2)
    -{
    -   Elm_Transit *trans;
    -
    -   trans = elm_transit_add();
    -   elm_transit_object_add(trans, obj);
    -   elm_transit_object_add(trans, obj2);
    -   elm_transit_effect_flip_add(trans, ELM_TRANSIT_EFFECT_FLIP_AXIS_Y, EINA_TRUE);
    -   elm_transit_duration_set(trans, 3.0);
    -   elm_transit_go(trans);
    -}
    -
    - -

    Creating a Wipe Effect

    - -

    The wipe transition is applied on an Evas object considering the wipe type and the direction. Use ELM_TRANSIT_EFFECT_WIPE_TYPE_HIDE to hide the button, and ELM_TRANSIT_EFFECT_WIPE_DIR_RIGHT to do it from left to right.

    - -

    The wipe animation button is as follows:

    - -
    // The wipe button
    -btn_wipe = elm_button_add(ad->win);
    -elm_object_text_set(btn_wipe, "Wipe");
    -evas_object_size_hint_weight_set(btn_wipe, EVAS_HINT_FILL, EVAS_HINT_FILL);
    -evas_object_show(btn_wipe);
    -evas_object_smart_callback_add(btn_wipe, "clicked", _btn_wipe_cb, ad);
    -elm_box_pack_end(ad->right_vbox, btn_wipe);
    -
    - -

    The wipe button callback looks like:

    - -
    static void _btn_wipe_cb(void *data, Evas_Object *btn, void *ev)
    -{
    -   appdata_s *ad = data;
    -
    -   // Starting the rotation effect 360 degrees
    -   // evas_object_resize(ad->button, 100, 50);
    -   // Setting the button text
    -   elm_object_text_set(ad->button, "Wipe");
    -   _wipe_effect(ad->button);
    -}
    -
    - -

    The animation function calls elm_transit_effect_wipe_add with ELM_TRANSIT_EFFECT_WIPE_TYPE_HIDE as the second parameter to hide the button and ELM_TRANSIT_EFFECT_WIPE_DIR_RIGHT as last parameter to set the direction (left to right).

    - -
    static void _wipe_effect(Evas_Object *obj)
    -{
    -    Elm_Transit *trans;
    -
    -    trans = elm_transit_add();
    -    elm_transit_object_add(trans, obj);
    -    elm_transit_effect_wipe_add(trans, ELM_TRANSIT_EFFECT_WIPE_TYPE_HIDE, ELM_TRANSIT_EFFECT_WIPE_DIR_RIGHT);
    -    elm_transit_duration_set(trans, 3.0);
    -    elm_transit_go(trans);
    -}
    -
    - - - - -
    - -Go to top - - - - - - - diff --git a/org.tizen.tutorials/html/native/ui/evas_tutorial_n.htm b/org.tizen.tutorials/html/native/ui/evas_tutorial_n.htm deleted file mode 100644 index 7f0ecb0..0000000 --- a/org.tizen.tutorials/html/native/ui/evas_tutorial_n.htm +++ /dev/null @@ -1,139 +0,0 @@ - - - - - - - - - - - - - - Evas: Creating and Managing Image Objects - - - - -
    -
    -

    Mobile native Wearable native

    -
    - -
    - -
    -

    Evas: Creating and Managing Image Objects

    - - -

    This tutorial demonstrates how you can create and manage image objects.

    - - -

    Warm-up

    -

    Become familiar with the Evas API basics by learning about:

    -
      -
    • Managing Images -

      Manage image objects, for example, by scaling and improving their performance.

    • - -
    - -

    Managing Images

    - -

    To manage image objects in Evas:

    - -
      -
    • Limit visibility. -

      Evas always supports the image file type it was compiled with. Check your software packager for the information and use the evas_object_image_extension_can_load_get() function.

      - -

      Create the image object. Set a source file on it, so that the object knows where to fetch the image data.

      -

      Define how to fill the image object area with the given pixel data. You can use a sub-region of the original image, or have it tiled repeatedly on the image object.

      - -
      -img = evas_object_image_add(canvas);
      -evas_object_image_file_set(img, "path/to/img", NULL);
      -evas_object_image_fill_set(img, 0, 0, w, h);
      -
      - - -

      If the entire source image is to be displayed on the image object, stretched to the destination size, use the evas_object_image_filled_set() function helper that you can use instead of the evas_object_image_fill_set() function:

      - -
      -evas_object_image_filled_set(img, EINA_TRUE);
      -
      -
    • - -
    • Scale image objects. -

      Resizing image objects scales the source images to the image object size, if the source images are set to fill the object area using the evas_object_image_filled_set() function.

      -

      Control the aspect ratio of an image for different sizes with functions to load images scaled up or down in memory.

      - -

      Evas has a scale cache, which caches scaled versions of images used often. You can also have Evas rescale the images smoothly, however, that is computationally expensive.

      -
    • - -
    • Give performance hints. -

      In image viewer applications, you can display an image in full size. The navigation to the adjacent images on your album must be fluid and fast. Thus, while displaying a given image, the program can load the next and previous image in the background to be able to immediately repaint the screen with a new image.

      - -

      Evas addresses this issue with image preloading:

      - -
      -prev = evas_object_image_filled_add(canvas);
      -evas_object_image_file_set(prev, "/path/to/prev", NULL);
      -evas_object_image_preload(prev, EINA_TRUE);
      -next = evas_object_image_filled_add(canvas);
      -evas_object_image_file_set(next, "/path/to/next", NULL);
      -evas_object_image_preload(next, EINA_TRUE);
      -
      - -

      If you are loading an image which is too big, set its loading size smaller.

      - -

      Load a scaled down version of the image in the memory if that is the size you are displaying (this can speed up the loading considerably):

      -
      evas_object_image_load_scale_down_set(img, zoom);
      -

      If you know you are showing a sub-set of the image pixels, you can avoid loading the complementary data:

      -
      evas_object_image_load_region_set(img, x, y, w, h);
      -
      -
    • - -
    • Specify borders. -

      With Evas, you can specify image margins to be treated as borders. The margins then maintain their aspects when the image is resized. This makes setting frames around other UI objects easier. The following figure illustrates the border behavior, when the image is resized.

      - -

      Figure: Borders in Evas

      -

      Borders in Evas

      - -
    • -
    - - - - -
    - -Go to top - - - - - - - diff --git a/org.tizen.tutorials/html/native/ui/events_effects_tutorials_n.htm b/org.tizen.tutorials/html/native/ui/events_effects_tutorials_n.htm deleted file mode 100644 index 7afe60c..0000000 --- a/org.tizen.tutorials/html/native/ui/events_effects_tutorials_n.htm +++ /dev/null @@ -1,71 +0,0 @@ - - - - - - - - - - - - - - Event and Effect: Using Animations and Effects - - - - - - -
    -

    Event and Effect: Using Animations and Effects

    - -

    The event and effect tutorials demonstrate how to create and implement a variety of animation effects and use gestures in Tizen native applications:

    - - - - - - -
    - -Go to top - - - - - - - diff --git a/org.tizen.tutorials/html/native/ui/font_settings_tutorial_n.htm b/org.tizen.tutorials/html/native/ui/font_settings_tutorial_n.htm deleted file mode 100644 index d897433..0000000 --- a/org.tizen.tutorials/html/native/ui/font_settings_tutorial_n.htm +++ /dev/null @@ -1,301 +0,0 @@ - - - - - - - - - - - - - - Font Setting: Using Various Fonts in the Application - - - - - - -
    - -

    Font Setting: Using Various Fonts in the Application

    - - -

    This tutorial demonstrates how you can use different methods to set and change the font style in your application. You can change the font to another system-default font or one of your own fonts.

    - -

    Warm-up

    -

    Become familiar with the Edje, Elementary, and Evas API basics by learning about:

    - - -

    Setting the Font for a UI Component

    - -

    You can use the Elementary Fonts API (in mobile and wearable applications) to set the font for an application.

    -

    To set a font for a UI component:

    -
      -
    • Set the font for a common UI component: - - - - - - - - - - -
      Note
      You can set the font for a textblock in the code, but not in EDC (Edje Data Collection). If you add markup tags for the font inside the text, you can change the font of the text. However, you cannot set the font for a text part in this way because the TEXT type does not support markup tags.
      - -
      -char *buf = "<font=Sans:style=Regular font_size=50>Hello</font/>Font";
      -elm_object_part_text_set(layout, "textblock1", buf);
      -
      -
    • -
    • Set the font for an entry component (in mobile and wearable applications) using the elm_entry_text_style_user_push() function. It overrides the default style of the entry component for each attribute. - - - - - - - - - - -
      Note
      The elm_entry_text_style_user_push() function only affects the main text of the UI component. To change the font of the guide text, you have to add markup tags.
      -
      -char *user_style = "DEFAULT='font=Sans:style=Regular font_size=40'";
      -elm_entry_text_style_user_push(entry, user_style);
      -elm_object_part_text_set(entry, "elm.guide",
      -   "<font=Sans:style=Regular font_size=40>Guide Text</font>");
      -
      -
    • -
    - -

    Setting the Font Using EDC

    - -

    To create a layout with text using the EDC, you can set the font for each text part or textblock:

    -
      -
    • Set the font of a text part using the font family name and a specific style of the font family: -
      -part 
      -{ 
      -   name: "text";
      -   type: TEXT;
      -   scale: 1;
      -   description 
      -   { 
      -      state: "default" 0.0;
      -      rel1.relative: 0.0 0.5;
      -      rel2.relative: 0.5 1.0;
      -      color: 0 136 170 255;
      -      color2: 0 136 170 50;
      -      color3: 0 136 170 25;
      -      text 
      -      {
      -         size: 25;
      -         font: "Sans:style=Bold";
      -         text: "Enventor";
      -         align: 0.5 0.5;
      -      }
      -   }
      -}
      -
      -
    • - -
    • Add style information, which can be used for multiple textblock parts: -
      -styles 
      -{
      -   style 
      -   { 
      -      name: "textblock_style1";
      -      base: "font=Sans:style=Regular font_size=30";
      -   }
      -}
      -
      -part 
      -{ 
      -   name: "textblock";
      -   type: TEXTBLOCK;
      -   scale: 1;
      -   description 
      -   { 
      -      state: "default" 0.0;
      -      align: 0.5 0.5;
      -      fixed: 0 0;
      -      min: 0 0;
      -      visible: 1;
      -      text.text: "TEXTBLOCK";
      -      text.style: "textblock_style1";
      -      rel1.relative: 0.16 0.18;
      -      rel2.relative: 0.88 0.38;
      -   }
      -}
      -
      -
    • -
    - -

    Using the Edje Text Class

    - -

    You can use the Edje Class: Text API (in mobile and wearable applications) to change multiple text occurrences as a batch. If you set a new font or font size to a text class, the change is applied to multiple objects.

    - - - - - - - - - - -
    Note
    Note that the text_class cannot be used in a UI component with markup text or the elm_entry_text_style_user_push() function. You must set the text_class in EDC.
    - - -

    To set the text class, you can use reserved words for text class, but you can also make your own text class:

    - -
      -
    • Set a class for a text part: - -
      -part 
      -{ 
      -   name: "text";
      -   type: TEXT;
      -   scale: 1;
      -   description 
      -   { 
      -      state: "default" 0.0;
      -      rel1.relative: 0.0 0.5;
      -      rel2.relative: 0.5 1.0;
      -      color: 0 136 170 255;
      -      color2: 0 136 170 50;
      -      color3: 0 136 170 25;
      -      text 
      -      {
      -         size: 25;
      -         font: "Sans:style=Bold";
      -         text: "Enventor";
      -         align: 0.5 0.5;
      -         text_class: "my_class";
      -      }
      -   }
      -}
      -
      -
    • -
    • Set a class for a textblock: -
      -styles 
      -{
      -   style 
      -   { 
      -      name: "textblock_style1";
      -      base: "font=Sans:style=Regular font_size=30 ... text_class=my_class";
      -   }
      -}
      -
      -part 
      -{ 
      -   name: "textblock";
      -   type: TEXTBLOCK;
      -   scale: 1;
      -   description 
      -   { 
      -      state: "default" 0.0;
      -      align: 0.5 0.5;
      -      fixed: 0 0;
      -      min: 0 0;
      -      visible: 1;
      -      text.text: "TEXTBLOCK";
      -      text.style: "textblock_style1";
      -      rel1.relative: 0.16 0.18;
      -      rel2.relative: 0.88 0.38;
      -   }
      -}
      -
      -
    • -
    • -

      You can handle font and font style per text_class. If you set your own text_class in the EDC, you can change the font and font size:

      - -
      -elm_config_font_overlay_set("my_class", "TizenSans:style=Bold", 30);
      -elm_config_font_overlay_apply();
      -
      -
    • -
    • -

      Set a specific ratio to a given font size for each object through the text class. If you give a negative value as font size, it is used as the percentage of the originally given font size. The following example code show set the font size as 150% of the given font size.

      -
      -elm_config_font_overlay_set("my_class", "TizenSans:style=Bold", -150);
      -elm_config_font_overlay_apply();
      -
      -
    • -
    - -

    Setting Your Own Font

    - -

    You can create your own font and use them in your application. Before using your fonts, set the path for the fonts. Use the evas_font_path_global_append() or prepend function once when the application is launched.

    -
    -char *font_path = "/opt/usr/apps/org.tizen.myapp/res/fonts/";
    -evas_font_path_global_append(font_path);
    -
    - -

    After calling the evas_font_path_global_append() function, you can load your fonts including the family name and style.

    - - - - -
    - -Go to top - - - - - - - diff --git a/org.tizen.tutorials/html/native/ui/form_tutorial_mn.htm b/org.tizen.tutorials/html/native/ui/form_tutorial_mn.htm deleted file mode 100644 index a19c1c4..0000000 --- a/org.tizen.tutorials/html/native/ui/form_tutorial_mn.htm +++ /dev/null @@ -1,336 +0,0 @@ - - - - - - - - - - - - - - Form: Creating the Basic Application and Layout - - - - - - -
    -

    Form: Creating the Basic Application and Layout

    - - -

    This tutorial explains how to create a basic application for displaying a list of contacts, and a form for displaying and editing contact information when an item is selected on the contact list.

    - - - - - - - - - - -
    Note
    This feature is supported in mobile applications only.
    - -

    Warm-up

    -

    Become familiar with the Eina, Elementary, and Evas API basics by learning about:

    - - -

    Creating the Basic Application

    - -

    To create an elementary application with a single window, use the following code.

    -
    static bool
    -app_create(void *data)
    -{
    -   appdata_s *ad = data;
    -   create_gui(ad);
    -   return true;
    -}
    -
    -int
    -main(int argc, char **argv)
    -{
    -   appdata_s ad = { 0 };
    -   ui_app_lifecycle_callback_s event_callback = { 0 };
    -
    -   event_callback.create = app_create;
    -
    -   // Zero out the structure
    -   memset(&ad, 0x0, sizeof(struct appdata));
    -
    -   // Run the mainloop
    -   return ui_app_main(&argc, &argv, &event_callback, &ad);
    -}
    -
    - - - -

    Use a naviframe in this application to switch between different views. The first view that is displayed is the list of contacts. When a user selects an item on this list, information on the contact is displayed in a form. Both the view list and the form are opened in a naviframe, which handles the animations between the views for you. It also manages creating a back button in the top bar and launching the back animation when you select it, deletes the form view, and shows the list of contacts again.

    - -

    Naviframe

    -

    The naviframe is the main layout of the window, so it takes all the space available. To configure this, use the elm_win_resize_object_add function. The first parameter is the main window, the second is the naviframe object. The naviframe is to be resized along with the window. The object (the naviframe) fills its parent (the main window) by calling the evas_object_resize_hint_weight_set function on the naviframe object. The naviframe object expands in both x and y directions. In the end, evas shows the naviframe object on the screen.

    -
     // Create the naviframe
    -nav = elm_naviframe_add(win);
    -evas_object_size_hint_weight_set(nav, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
    -elm_win_resize_object_add(win, nav);
    -evas_object_show(nav);
    -
    - -

    Contact List

    -

    Handle the contact list with the _create_contact_list function. This function takes the parent object as the parameter (in this case the naviframe) and returns the genlist. To create the genlist, use the following code.

    -
    static Evas_Object *
    -_create_contact_list(Evas_Object *parent)
    -{
    -   Evas_Object *list;
    -   int i;
    -
    -   // Create a new genlist
    -   list = elm_genlist_add(parent);
    -   evas_object_show(list);
    -
    -   // Create a new item class for the genlist
    -   itc = elm_genlist_item_class_new();
    -   itc->item_style = "default";
    -   // Set the callback used when the genlist text is created
    -   itc->func.text_get = _genlist_text_get;
    -   // Set the callback be used when the content of the item is created
    -   itc->func.content_get   = _genlist_content_get;
    -   itc->func.state_get = NULL;
    -   itc->func.del = NULL;
    -}
    -
    - -

    itc is a static variable containing the item class. The item class contains all functions that are called back when an item is created. In this case, create the callbacks _genlist_text_get (for labels) and _genlist_content_get (for icons). These functions are called when labels and icons of the genlist item are created.

    -

    The list of contacts is contained in an array of Contacts.

    -
    typedef struct _Contact Contact;
    -
    -struct _Contact
    -{
    -   const char *name;
    -   const char *mobile;
    -   const char *address;
    -   const char *email;
    -   const char *icon;
    -};
    -
    -static Contact contacts[] = 
    -{
    -   {"Alexander Holmes", "+1234567896", "", "alexander_holmes@tizen.org", "c1.png"},
    -   {"Lara Alvaréz",    "+9876543216", "", "lara_alvares@tizen.org", "c2.png"   },
    -   {"Aksel Møller",    "+1679432846", "", "aksel_moller@tizen.org", "c3.png"   },
    -   {"Anir Amghar",      "+1679432846", "", "anir_amghar@tizen.org", "c4.png"    },
    -   {"Noémie Cordier",    "+1679432846", "", "noemie_cordier@tizen.org", "c5.png"   },
    -   {"Henry Thompson",    "+1679432846", "", "henry_thompson@tizen.org", "c6.png"   },
    -   {"Mai Phan",       "+1679432846", "", "mai_phan@tizen.org", "c7.png"      },
    -};
    -
    - -

    Create a genlist item for each item of the array with the following code.

    -
    -// Create a genlist item for each item in the contacts array
    -for (i = 0; i < EINA_C_ARRAY_LENGTH(contacts); i++)
    -{
    -   // Append the item, add a callback when the item is selected, and use the
    -   // current contact item as data pointer for the callbacks
    -   elm_genlist_item_append(list, itc,
    -                     &contacts[i],
    -                  NULL,
    -                     ELM_GENLIST_ITEM_NONE,
    -                     _contact_selected_cb,
    -                     &contacts[i]);
    -}
    -
    - -

    Attach the _contact_selected_cb callback function to the genlist item. When an item is selected in the list, the data pointer passed as the argument calls this function. Here it is a pointer on the contact. Pass the contact in the array to all the Item Class callbacks.

    -

    Push the list at the top of the naviframe with the following code.

    -
    -// Create the list of contacts
    -list = _create_contact_list(win);
    -
    -// Push the list on top of the naviframe
    -elm_naviframe_item_push(nav, NULL, NULL, NULL, list, NULL);
    -
    - -

    The Item class functions are called, the _genlist_text_get first.

    -
    -static char *
    -_genlist_text_get(void *data, Evas_Object *obj EINA_UNUSED, const char *part)
    -{
    -   Contact *contact = data;
    -
    -   // Return a new allocated string for the contact name
    -   return strdup(contact->name);
    -}
    -
    - -

    These functions show the index of the contact in the array and return a freshly allocated string with the name of the contact.

    -

    When the user selects an item in the list, a callback registers on the select signal and calls the corresponding function; in this case, _contact_selected_cb(). The user retrieves the index of the array passed in the data and creates the form on contact information based on this index.

    -

    The _genlist_content_get function is called several times depending on the style of the created item. In this case, with the default style for the genlist item, there are two different swallow parts. A swallow part is a container in the edje file of the genlist item, which may contain an evas object. The following figure shows the layout of different parts in the theme.

    - - -

    Figure: Genlist item

    -

    Genlist item

    - - -

    There are two elm.swallow parts. When the callback function for the creation of icons is called, the part name is passed via the part variable. Compare this variable to elm.swallow.icon for the first object and to elm.swallow.end for the icon at the end.

    - -

    Icon

    -

    Create the icon when the callback is recognized. In this example, we use an elm_icon object.

    -
    -static Evas_Object *
    -_genlist_content_get(void *data, Evas_Object *obj, const char *part)
    -{
    -   Contact *contact = data;
    -
    -   // Test which part is being created
    -   if (!strcmp(part, "elm.swallow.icon"))
    -   {
    -         char filename[PATH_MAX];
    -      // Create a new icon
    -      Evas_Object *ic = elm_icon_add(obj);
    -      // Set the filename of the file which is to be loaded
    -      snprintf(filename, sizeof(filename), "%s%s", ICON_PATH, contact->icon);
    -      elm_image_file_set(ic, filename, NULL);
    -      // Keep the ratio squared
    -      evas_object_size_hint_aspect_set(ic, EVAS_ASPECT_CONTROL_VERTICAL, 1, 1);
    -
    -      // Return the icon
    -      return ic;
    -   }
    -
    -   return NULL;
    -}
    -
    - -

    Note that in case of elm.swallow.end the return is NULL, and no icon is added.

    -

    The user may question the complexity of creating a genlist, and the benefits of callbacks for the creation of items. In a genlist with thousands of elements, graphical items are not created. Only the ones currently displayed on the screen are created with the callbacks in the Genlist Item Class. Otherwise, objects are created by calling the respective callback function when the user scrolls the list.

    - - - - - - - - - - -
    Note
    When the genlist is first created, the Elementary needs to know the height of the list. All elements in the list are not necessarily the same size due to different kind of styles. Thus, the Elementary creates all elements once to know the size, and displays the scroll bars correctly. If all your items have the same height, use the elm_genlist_homogeneous_set to impose the same height to all items. The Elementary does not create the complete list as the global size is a multiple of the height of the first item. It saves you cpu time.
    - -

    Contact Form

    -

    The contact list is created inside the _create_contact_form function. This function takes a parent Evas_Object and a contact item as parameters, and returns an Evas_Object. The parent is the naviframe object, and the contact item contains the information on the contact.

    -

    To display the various information about the contact, we use boxes in this example.

    - -

    Figure: Form contact layout

    -

    Form contact layout

    - - -

    The first box is an vertical box.

    -
    vbox = elm_box_add(parent);
    -elm_box_align_set(vbox, 0, 0);
    -evas_object_show(vbox);
    -
    - -

    elm_box_align_set keeps the box element aligned to the top left corner.

    -

    To add an icon, use the _genlist_content_get function to create the icon in the genlist item. For a bigger icon, set the minimum size of the icon object to 96x96 px.

    -

    The most important function in this case is elm_box_pack_end. It adds the icon object at the end of the vbox. As the icon is the first object added, it is displayed on top of the box.

    -
    -ic = elm_icon_add(vbox);
    -snprintf(filename, sizeof(filename), "%s%s", ICON_PATH, contact->icon);
    -elm_image_file_set(ic, filename, NULL);
    -evas_object_size_hint_min_set(ic, 96, 96);
    -evas_object_show(ic);
    -elm_box_pack_end(vbox, ic);
    -
    - -

    In the following example, add the information on the contact: the name, the mobile phone number, the postal address and the e-mail address. For each information item, create a label and an edit line. The label contains the kind of the information, and the edit box, the information itself. To set the UI components in a horizontal layout, use a horizontal box.

    -
    -hbox = elm_box_add(vbox);
    -elm_box_horizontal_set(hbox, EINA_TRUE);
    -elm_box_padding_set(hbox, 32, 32);
    -evas_object_size_hint_weight_set(hbox, EVAS_HINT_EXPAND, 0);
    -evas_object_size_hint_align_set(hbox, EVAS_HINT_FILL, 0);
    -evas_object_show(hbox);
    -
    - -

    Change the orientation of the box with elm_box_horizontal_set. To get space between the elements of the vbox, set the padding to 32px. To set the item of the box not to expand vertically, use evas_object_size_hint_weight_set.

    -

    Create the label object, which is an elm_label. Set its text, and do not align or expand it.

    -
    -label = elm_label_add(hbox);
    -elm_object_text_set(label, form_items[i]);
    -evas_object_size_hint_weight_set(label, 0, 0);
    -evas_object_size_hint_align_set(label, 0, 0);
    -evas_object_show(label);
    -
    - -

    Create the edit line, which is an elm_entry.

    -
    -edit = elm_entry_add(hbox);
    -evas_object_size_hint_weight_set(edit, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
    -evas_object_size_hint_align_set(edit, EVAS_HINT_FILL, EVAS_HINT_FILL);
    -evas_object_show(edit);
    -
    - -

    Add the label and the edit inside the horizontal box and add the horizontal box to the vertical box.

    -
    -elm_box_pack_end(hbox, label);
    -elm_box_pack_end(hbox, edit);
    -
    -elm_box_pack_end(vbox, hbox);
    -
    - -

    Figure: Form tutorial: form

    -

    Form tutorial: form

    - -

    Figure: Form tutorial: list

    -

    Form tutorial: list

    - - - - -
    - -Go to top - - - - - - - diff --git a/org.tizen.tutorials/html/native/ui/genlist_tutorial_mn.htm b/org.tizen.tutorials/html/native/ui/genlist_tutorial_mn.htm deleted file mode 100644 index 7dcc7b8..0000000 --- a/org.tizen.tutorials/html/native/ui/genlist_tutorial_mn.htm +++ /dev/null @@ -1,496 +0,0 @@ - - - - - - - - - - - - - - Genlist: Managing Large Element Sets - - - - - - -
    -

    Genlist: Managing Large Element Sets

    - - -

    This tutorial deals with genlists, a list component for large sets of elements. It uses callbacks to populate entries. The same UI component handles both flat lists and trees.

    - - - - - - - - - - -
    Note
    This feature is supported in mobile applications only.
    - -

    Warm-up

    -

    Become familiar with the Elementary and Evas API basics by learning about:

    - - -

    Initializing the Application

    - -

    Figure: Example of a genlist

    -

    Example of a genlist

    -

    The code below shows a typical elementary application that creates a window entitled "Genlist Basic Tutorial". It is consisted of a conformant component that contains a naviframe component. The genlist goes inside the naviframe.

    -
    static bool
    -_app_create(void *data)
    -{
    -   appdata_s *app = data;
    -
    -   app->win = elm_win_util_standard_add("main", "Genlist Basic Tutorial");
    -   elm_win_conformant_set(app->win, EINA_TRUE);
    -   evas_object_show(app->win);
    -   evas_object_resize(app->win, 480, 800);
    -   elm_win_autodel_set(app->win, EINA_TRUE);
    -
    -   app->conformant = elm_conformant_add(app->win);
    -   evas_object_size_hint_weight_set(app->conformant, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
    -   elm_win_resize_object_add(app->win, app->conformant);
    -   evas_object_show(app->conformant);
    -
    -   app->naviframe = elm_naviframe_add(app->win);
    -   evas_object_size_hint_weight_set(app->naviframe, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
    -   elm_win_resize_object_add(app->win, app->naviframe);
    -   evas_object_show(app->naviframe);
    -   elm_object_content_set(app->conformant, app->naviframe);
    -
    -   _create_list(app);
    -   elm_naviframe_item_push(app->naviframe, NULL, NULL, NULL, app->list, NULL);
    -
    -   return true;
    -}
    -
    -int
    -main(int argc, char **argv)
    -{
    -   // Declare a few structures and zero-initialize (C99 feature)
    -   struct app_data app = { 0 };
    -   ui_app_lifecycle_callback_s event_callback = { 0 };
    -
    -   event_callback.create = _app_create;
    -
    -   // Run the mainloop
    -   return ui_app_main(&argc, &argv, &event_callback, &ad);
    -}
    -
    -

    The declaration of the struct app_data is shown below:

    -
    struct app_data
    -{
    -   Evas_Object *win;
    -   Evas_Object *naviframe;
    -   Evas_Object *conformant;
    -   Evas_Object *list;
    -   Elm_Genlist_Item_Class *itc;
    -   Elm_Genlist_Item_Class *itc2;
    -};
    -
    - -

    Creating a Genlist

    - -

    Call elm_genlist_add() to create a genlist. Then new entries can be added. In this example, first the basic windows is created, then a genlist is added to it, and then 10000 elements with text and a colored block on each side of it.

    -
    Evas_Object *list = elm_genlist_add(parent);
    -
    - -

    Adding New Entries

    - -

    Use elm_genlist_item_append() to add new elements. Its second parameter is a structure which describes how to populate entries. Typically this structure is built once and re-used across calls to elm_genlist_item_append().

    -

    -Building a Basic Item Class

    -

    The code for the minimal genlist item class is below:

    - -
    Elm_Genlist_Item_Class *itc = elm_genlist_item_class_new();
    -itc->item_style = "default";
    -itc->func.text_get = NULL;
    -itc->func.content_get = NULL;
    -itc->func.state_get = NULL;
    -itc->func.del = NULL;
    -
    - -

    It creates a simple item class, sets the item_style to "default" and every other field to NULL. However, this leaves out the text_get and content_get fields which are used to add text and an icon to the list entry. This is explained in another section.

    -

    Adding the Element

    -

    Once the genlist item class object is created, a new element is added to the list by calling elm_genlist_item_append().

    -
    elm_genlist_item_append(list,
    -   itc,
    -   NULL,                    // Item data
    -   NULL,                    // Parent item for trees, NULL if none
    -   ELM_GENLIST_ITEM_NONE,   // Item type; this is the common one
    -   NULL,                    // Callback on selection of the item
    -   NULL                     // Data for that callback function
    -);
    -
    -

    With most parameters as NULL and itc having most of its members NULL, too, the elements of that list are blank and will not trigger anything when selected. This shows the APIs that are used.

    -

    Text in the List Elements

    -

    Use text_get callback to add text in the elements in the Elm_Genlist_Item_Class structure. These callbacks must have a prototype matching to the following:

    - -
    char * text_get(void *data, Evas_Object *obj, const char *part);
    -
    -

    This callbacks returns a C string that is displayed in the part named after the part parameter. This callback is called for each user-settable text part according to the current theme.

    -

    If you are not familiar with the concept of parts in the EFLs, read the Write a Simple EDC File section.

    - - - - - - - - - - - -
    Note
    The value returned is freed by the EFLs: the value must be freshly-allocated, do not free it yourself and do not re-use it across list elements.
    - -

    For the default theme there is one part named elm.text. A possible implementation of the text_get callback is therefore:

    -
    static char *
    -_genlist_text_get(void *data, Evas_Object *obj, const char *part)
    -{
    -   // Check this is text for the part we're expecting
    -   if (strcmp(part, "elm.text") == 0) 
    -   {
    -      return strdup("Some text");
    -   }
    -   else {
    -      return NULL;
    -   }
    -}
    -
    - - - - - - - - - - -
    Note
    The names and positions of parts depends on the item_style chosen when adding new items to the genlist. Setting a custom theme makes it possible to completely change genlists by adding and moving parts. The Edje guide explains how to do that.
    - -

    The data parameter makes it possible to behave differently according to data that is given to the EFLs during the call to elm_genlist_item_append() in the data parameter. For example, given an integer in that field through casting with (void *)(uintptr_t) i, it is possible to get its value back using (int)(uintptr_t)data:

    -
    static char *
    -_genlist_text_get(void *data, Evas_Object *obj__UNUSED__, const char *part)
    -{
    -   if (strcmp(part, "elm.text") == 0) 
    -   {
    -      char *buf = malloc(16);
    -      snprintf(buf, 16, "Entry %d.", (int)(uintptr_t)data);
    -
    -      return buf;
    -   }
    -   else 
    -   {
    -      return NULL;
    -   }
    -}
    -
    - -

    Evas_Objects in the List Elements

    -

    Icons are added in a similar fashion: there is a callback named content_get which returns a pointer to an Evas_Object and is called for each part which contents can be set.

    -

    The prototype of the callback must match this one:

    -
    Evas_Object * content_get(void *data, Evas_Object *obj, const char *part);
    -
    - -

    The only difference with the text_get callback is that it returns an Evas_Object* rather than a char *.

    -

    This leads to a fairly simple dummy implementation with colored rectangles in the parts that are to be set:

    -
    -static Evas_Object *
    -_genlist_content_get(void *data, Evas_Object *obj, const char *part)
    -{
    -   int i = (int) (uintptr_t) data;
    -
    -   if (strcmp(part, "elm.swallow.icon") == 0) 
    -   {
    -      Evas_Object *bg = elm_bg_add(obj);
    -      elm_bg_color_set(bg, 255 * cos(i / (double) 10), 0, i % 255);
    -
    -      return bg;
    -   }
    -   else if (strcmp(part, "elm.swallow.end") == 0) 
    -   {
    -      Evas_Object *bg = elm_bg_add(obj);
    -      elm_bg_color_set(bg, 0, 255 * sin(i / (double) 10), i % 255);
    -
    -      return bg;
    -   }
    -   else 
    -   {
    -      return NULL;
    -   }
    -}
    -
    -

    For the default theme, this displays a red rectangle on the left of each list item and a green one on their right.

    -

    Events on Genlist Items

    -

    Genlist items triggers a callback when clicked. This callback is chosen when adding the new item (for example, when calling elm_genlist_item_append()):

    -
    elm_genlist_item_append(list,
    -   itc,
    -   NULL,                    // item data
    -   NULL,                    // parent item for trees, NULL if none
    -   ELM_GENLIST_ITEM_NONE,   // item type, other values are used for trees
    -   _genlist_selected_cb,      // callback on selection of the item
    -   NULL                     // data for that callback function
    -);
    -
    - -

    This callback adheres to the following prototype:

    -
    void _contact_selected_cb(void *data, Evas_Object *obj, void *event_info)
    -
    - -

    The implementation below changes the item style of items when they are selected:

    -
    static void
    -_genlist_selected_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   struct app_data *app = data;
    -
    -   Elm_Object_Item *it = (Elm_Object_Item*) event_info;
    -
    -   elm_genlist_item_item_class_update(it, app->itc2);
    -}
    -
    - -

    Choosing Another Item Style to Add or Remove Parts

    - -

    As mentioned above, the number of parts to fill depends on the item style that is chosen when adding a new item. This is simply a matter of setting the right value when filling the Elm_Genlist_Item_Class struct:

    -
    app->itc->item_style = "default";
    -
    -

    The Genlist component lists all available item styles.

    -

    Further customization is achieved by modifying the theme as explained in the Edje guide.

    -

    In case the customization is only visual, it is good practice to keep the same item style names for new themes. This makes it possible to change theme and keep the code the same while also retaining the same overall item placement.

    - -

    Using Item Modes

    - -

    So far the genlist examples have all featured bare lists while the genlist component is able to display trees or even a "group" mode where scrolling keeps the item at the top of the UI component until another group comes and replaces it.

    -

    Group Mode

    -

    The group mode makes it possible to keep an element visible as long as one of its children is visible. This is most useful for "title" items.

    -

    Mark some elements as ELM_GENLIST_ITEM_GROUP and use the returned Elm_Object_Item to establish the parent-children relationship when adding the children items.

    -

    Since there are two kind of items, create two item classes. Give them different styles and callback functions. The callback functions are visible in the example, they have no functionalities:

    -
    -app->itc = elm_genlist_item_class_new();
    -app->itc->item_style = "default_style";
    -app->itc->func.text_get = _genlist_text_get_size;
    -app->itc->func.content_get = _genlist_content_get_bg;
    -app->itc->func.state_get = NULL;
    -app->itc->func.del = NULL; 
    -
    -app->itc2 = elm_genlist_item_class_new();
    -app->itc2->item_style = "icon_top_text_bottom";
    -app->itc2->func.text_get = _genlist_text_get_nosize;
    -app->itc2->func.content_get = _genlist_content_get_icon;
    -app->itc2->func.state_get = NULL;
    -app->itc2->func.del = NULL; 
    -
    - -

    Then add a group header and follow it with 10 children. This is repeated 1000 times.

    -

    The parent has type ELM_GENLIST_ITEM_GROUP while the children have type ELM_GENLIST_ITEM_NONE.

    -

    The other important point is that the value returned by lm_genlist_item_append() is stored in it and then sent to the elm_genlist_item_append() call that adds the children. This creates the parent-children relationship.

    -
    -for (i = 0; i < 1000; i++) 
    -{
    -   it = elm_genlist_item_append(app->list, app->itc2,
    -      (void *)(uintptr_t) (10 * i),
    -      NULL,
    -      ELM_GENLIST_ITEM_GROUP,
    -      NULL,
    -      NULL
    -   );
    -   for (j = 0; j < 10; j++)
    -   {
    -      elm_genlist_item_append(app->list, app->itc,
    -         (void *)(uintptr_t) (10 * i + j),
    -         it,
    -         ELM_GENLIST_ITEM_NONE,
    -         NULL,
    -         NULL
    -      );
    -   }
    -}
    -
    - -

    Tree Mode

    -

    Like group mode, tree mode uses the parenting relationship with other items. Unlike group mode, the child elements are created on-demand when their parent is expanded and deleted when it is contracted. This is done by using smart callbacks: expand,request, expanded, contract,request, and contracted. Like any smart callback, they are registered through evas_object_smart_callback_add on the genlist object:

    -
    evas_object_smart_callback_add(app->list, "expand,request",
    -   _tree_item_expand_request, NULL);
    -evas_object_smart_callback_add(app->list, "expanded",
    -   _tree_item_expanded, NULL);
    -
    -evas_object_smart_callback_add(app->list, "contract,request",
    -   _tree_item_contract_request, NULL);
    -evas_object_smart_callback_add(app->list, "contracted",
    -   _tree_item_contracted, NULL);
    -
    - -

    The callbacks expand,request and contract,request do only one thing: decide whether the element is expanded or contracted. This is done by using elm_genlist_item_expanded_set() function; if it changes the expansion status of the item, the next callback is called (either expanded or contracted, depending on whether it was an expand,request or contract,request event). A minimal implementation of these callbacks is therefore:

    -
    -static void
    -_tree_item_expand_request(void *data, Evas_Object *o, void *event_info)
    -{
    -   Elm_Object_Item *it = (Elm_Object_Item*) event_info;
    -
    -   elm_genlist_item_item_class_update(it, app->itc2);
    -
    -   elm_genlist_item_expanded_set(it, EINA_TRUE);
    -}
    -
    - - - - - - - - - - -
    Note
    The example above has an extra line: the call to elm_genlist_item_item_class_update(). It changes the item style and is explained in the Changing the item class of an item after its creation section.
    - -
    -static void
    -_tree_item_contract_request(void *data, Evas_Object *o, void *event_info)
    -{
    -   Elm_Object_Item *it = (Elm_Object_Item*) event_info;
    -
    -   elm_genlist_item_item_class_update(it, app->itc);
    -
    -   elm_genlist_item_expanded_set(it, EINA_FALSE);
    -}
    -
    - -

    As said above, once the genlist item status is set to expanded, the expanded event is triggered and it is the duty of a callback for that event to populate the list with the item's children. This relies on the parent parameter of functions like elm_genlist_item_append(), like for the group mode.

    -

    The function below is a callback implementation for the expanded event. It adds items that are built similarly to previous items, the only change is the parent parameter which is not NULL. Conveniently, the parent Elm_Object_Item pointer that is passes to the elm_genlist_item_append() function is given in the event_info callback and needs to be cast.

    -
    static void
    -_tree_item_expanded(void *data, Evas_Object *o, void *event_info)
    -{
    -   Elm_Object_Item *it_parent = (Elm_Object_Item*) event_info;
    -   int i_parent = (int)(uintptr_t) data;
    -   int i;
    -
    -   for (i = 0; i < 10; i++) 
    -   {
    -      elm_genlist_item_append(app->list, app->itc,
    -            (void *)(uintptr_t) (i + i_parent),
    -            it_parent,
    -            ELM_GENLIST_ITEM_NONE,
    -            NULL,
    -            NULL
    -      );
    -   }
    -}
    -
    - -

    The following code has the callback function for the contracted event. It imply calls elm_genlist_item_subitems_clear() to clear all children (including their own children if they have any) of the given item. Again, the item that is being contracted is available through the event_info parameter to the callback.

    -
    static void
    -_tree_item_contracted(void *data, Evas_Object *o, void *event_info)
    -{
    -   Elm_Object_Item *it_parent = (Elm_Object_Item*) event_info;
    -
    -   elm_genlist_item_subitems_clear(it_parent);
    -}
    -
    - -

    Mixing Group and Tree Modes

    -

    A common UI design is to mix group and tree modes. It allows for a tree behavior while also keeping the group header item. The EFLs do not do any magic here and the way to get such a behavior is to create an item of type group, an item of type tree which parent is the group item. Then add the callbacks to populate the children of the tree item in the regular way.

    - -

    Using Other APIs

    - -

    Homogeneous Item Size

    -

    Because of the scroller, the actual height and/or width of the genlist must be computed. This means summing the sizes of all the items, the sizes must be computed. This obviously has a cost and slows down adding items to the genlist.

    -

    The elm_genlist_homogeneous_set() function alleviates this issue by assuming all the items are the same size as the first one of the list. It speeds up large insertions. However, it may lead to serious graphical issues if the items are not actually the same size. Use with care.

    - -

    Changing the Item Class of an Item After Its Creation

    -

    Changing the item class of a UI component is an easy way to change its appearance upon selection or other actions of the user. This is done by calling elm_genlist_item_class_update():

    -
    static void
    -_tree_item_expand_request(void *data, Evas_Object *o, void *event_info)
    -{
    -   Elm_Object_Item *it = (Elm_Object_Item*) event_info;
    -
    -   // Change the appearance and possibly content of the item being expanded.
    -   elm_genlist_item_item_class_update(it, app->itc2);
    -
    -   elm_genlist_item_expanded_set(it, EINA_TRUE);
    -}
    -
    - - - - -
    - -Go to top - - - - - - - diff --git a/org.tizen.tutorials/html/native/ui/genlist_tutorial_wn.htm b/org.tizen.tutorials/html/native/ui/genlist_tutorial_wn.htm deleted file mode 100644 index 6418d83..0000000 --- a/org.tizen.tutorials/html/native/ui/genlist_tutorial_wn.htm +++ /dev/null @@ -1,507 +0,0 @@ - - - - - - - - - - - - - - Genlist: Managing Large Element Sets - - - - - - -
    -

    Genlist: Managing Large Element Sets

    - -

    This tutorial deals with genlists, a list component for large sets of elements. It uses callbacks to populate entries. The same UI component handles both flat lists and trees.

    - - - - - - - - - - -
    Note
    This feature is supported in wearable applications only.
    - -

    Warm-up

    -

    Become familiar with the Elementary and Evas API basics by learning about:

    - - -

    Initializing the Application

    - -

    Figure: Example of a genlist

    -

    Example of a genlist

    -

    The code below shows a typical elementary application that creates a window entitled "Genlist Basic Tutorial". It is consisted of a conformant component that contains a naviframe component. The genlist goes inside the naviframe.

    -
    static bool
    -_app_create(void *data)
    -{
    -   appdata_s *app = data;
    -
    -   app->win = elm_win_util_standard_add("main", "Genlist Basic Tutorial");
    -   elm_win_conformant_set(app->win, EINA_TRUE);
    -   evas_object_show(app->win);
    -   evas_object_resize(app->win, 480, 800);
    -   elm_win_autodel_set(app->win, EINA_TRUE);
    -
    -   app->conformant = elm_conformant_add(app->win);
    -   evas_object_size_hint_weight_set(app->conformant, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
    -   elm_win_resize_object_add(app->win, app->conformant);
    -   evas_object_show(app->conformant);
    -
    -   app->naviframe = elm_naviframe_add(app->win);
    -   evas_object_size_hint_weight_set(app->naviframe, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
    -   elm_win_resize_object_add(app->win, app->naviframe);
    -   evas_object_show(app->naviframe);
    -   elm_object_content_set(app->conformant, app->naviframe);
    -
    -   _create_list(app);
    -   elm_naviframe_item_push(app->naviframe, NULL, NULL, NULL, app->list, NULL);
    -
    -   return true;
    -}
    -
    -int
    -main(int argc, char **argv)
    -{
    -   // Declare a few structures and zero-initialize (C99 feature)
    -   struct app_data app = { 0 };
    -   ui_app_lifecycle_callback_s event_callback = { 0 };
    -
    -   event_callback.create = _app_create;
    -
    -   // Run the mainloop
    -   return ui_app_main(&argc, &argv, &event_callback, &ad);
    -}
    -
    -

    The declaration of the struct app_data is shown below:

    -
    struct app_data
    -{
    -   Evas_Object *win;
    -   Evas_Object *naviframe;
    -   Evas_Object *conformant;
    -   Evas_Object *list;
    -   Elm_Genlist_Item_Class *itc;
    -   Elm_Genlist_Item_Class *itc2;
    -};
    -
    - -

    Creating a Genlist

    - -

    Call elm_genlist_add() to create a genlist. Then new entries can be added. In this example, first the basic windows is created, then a genlist is added to it, and then 10000 elements with text and a colored block on each side of it.

    -
    Evas_Object *list = elm_genlist_add(parent);
    -
    - -

    Adding New Entries

    - -

    Use elm_genlist_item_append() to add new elements. Its second parameter is a structure which describes how to populate entries. Typically this structure is built once and re-used across calls to elm_genlist_item_append().

    -

    -Building a Basic Item Class

    -

    The code for the minimal genlist item class is below:

    - -
    Elm_Genlist_Item_Class *itc = elm_genlist_item_class_new();
    -itc->item_style = "default";
    -itc->func.text_get = NULL;
    -itc->func.content_get = NULL;
    -itc->func.state_get = NULL;
    -itc->func.del = NULL;
    -
    - -

    It creates a simple item class, sets the item_style to "default" and every other field to NULL. However, this leaves out the text_get and content_get fields which are used to add text and an icon to the list entry. This is explained in another section.

    -

    Adding the Element

    -

    Once the genlist item class object is created, a new element is added to the list by calling elm_genlist_item_append().

    -
    elm_genlist_item_append(list,
    -   itc,
    -   NULL,                    // Item data
    -   NULL,                    // Parent item for trees, NULL if none
    -   ELM_GENLIST_ITEM_NONE,   // Item type; this is the common one
    -   NULL,                    // Callback on selection of the item
    -   NULL                     // Data for that callback function
    -);
    -
    -

    With most parameters as NULL and itc having most of its members NULL, too, the elements of that list are blank and will not trigger anything when selected. This shows the APIs that are used.

    -

    Text in the List Elements

    -

    Use text_get callback to add text in the elements in the Elm_Genlist_Item_Class structure. These callbacks must have a prototype matching to the following:

    - -
    char * text_get(void *data, Evas_Object *obj, const char *part);
    -
    -

    This callbacks returns a C string that is displayed in the part named after the part parameter. This callback is called for each user-settable text part according to the current theme.

    -

    If you are not familiar with the concept of parts in the EFLs, read the Write a Simple EDC File section.

    - - - - - - - - - - - -
    Note
    The value returned is freed by the EFLs: the value must be freshly-allocated, do not free it yourself and do not re-use it across list elements.
    - -

    For the default theme there is one part named elm.text. A possible implementation of the text_get callback is therefore:

    -
    static char *
    -_genlist_text_get(void *data, Evas_Object *obj, const char *part)
    -{
    -   // Check this is text for the part we're expecting
    -   if (strcmp(part, "elm.text") == 0) 
    -   {
    -      return strdup("Some text");
    -   }
    -   else {
    -      return NULL;
    -   }
    -}
    -
    - - - - - - - - - - -
    Note
    The names and positions of parts depends on the item_style chosen when adding new items to the genlist. Setting a custom theme makes it possible to completely change genlists by adding and moving parts. The Edje guide explains how to do that.
    - -

    The data parameter makes it possible to behave differently according to data that is given to the EFLs during the call to elm_genlist_item_append() in the data parameter. For example, given an integer in that field through casting with (void *)(uintptr_t) i, it is possible to get its value back using (int)(uintptr_t)data:

    -
    static char *
    -_genlist_text_get(void *data, Evas_Object *obj__UNUSED__, const char *part)
    -{
    -   if (strcmp(part, "elm.text") == 0) 
    -   {
    -      char *buf = malloc(16);
    -      snprintf(buf, 16, "Entry %d.", (int)(uintptr_t)data);
    -
    -      return buf;
    -   }
    -   else 
    -   {
    -      return NULL;
    -   }
    -}
    -
    - -

    Evas_Objects in the List Elements

    -

    Icons are added in a similar fashion: there is a callback named content_get which returns a pointer to an Evas_Object and is called for each part which contents can be set.

    -

    The prototype of the callback must match this one:

    -
    Evas_Object * content_get(void *data, Evas_Object *obj, const char *part);
    -
    - -

    The only difference with the text_get callback is that it returns an Evas_Object* rather than a char *.

    -

    This leads to a fairly simple dummy implementation with colored rectangles in the parts that are to be set:

    -
    -static Evas_Object *
    -_genlist_content_get(void *data, Evas_Object *obj, const char *part)
    -{
    -   int i = (int) (uintptr_t) data;
    -
    -   if (strcmp(part, "elm.swallow.icon") == 0) 
    -   {
    -      Evas_Object *bg = elm_bg_add(obj);
    -      elm_bg_color_set(bg, 255 * cos(i / (double) 10), 0, i % 255);
    -
    -      return bg;
    -   }
    -   else if (strcmp(part, "elm.swallow.end") == 0) 
    -   {
    -      Evas_Object *bg = elm_bg_add(obj);
    -      elm_bg_color_set(bg, 0, 255 * sin(i / (double) 10), i % 255);
    -
    -      return bg;
    -   }
    -   else 
    -   {
    -      return NULL;
    -   }
    -}
    -
    -

    For the default theme, this displays a red rectangle on the left of each list item and a green one on their right.

    -

    Events on Genlist Items

    - - - - - - - - - - -
    Note
    The swallow parts have no minimum size. This means that if you do not fix the minimum size, the part cannot be seen.
    - -

    Genlist items triggers a callback when clicked. This callback is chosen when adding the new item (for example, when calling elm_genlist_item_append()):

    -
    elm_genlist_item_append(list,
    -   itc,
    -   NULL,                    // item data
    -   NULL,                    // parent item for trees, NULL if none
    -   ELM_GENLIST_ITEM_NONE,   // item type, other values are used for trees
    -   _genlist_selected_cb,      // callback on selection of the item
    -   NULL                     // data for that callback function
    -);
    -
    - -

    This callback adheres to the following prototype:

    -
    void _contact_selected_cb(void *data, Evas_Object *obj, void *event_info)
    -
    - -

    The implementation below changes the item style of items when they are selected:

    -
    static void
    -_genlist_selected_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   appdata_s *app = data;
    -
    -   Elm_Object_Item *it = (Elm_Object_Item*) event_info;
    -
    -   elm_genlist_item_item_class_update(it, app->itc2);
    -}
    -
    - -

    Choosing Another Item Style to Add or Remove Parts

    - -

    As mentioned above, the number of parts to fill depends on the item style that is chosen when adding a new item. This is simply a matter of setting the right value when filling the Elm_Genlist_Item_Class struct:

    -
    app->itc->item_style = "default";
    -
    -

    The Genlist component lists all available item styles.

    -

    Further customization is achieved by modifying the theme as explained in the Edje guide.

    -

    In case the customization is only visual, it is good practice to keep the same item style names for new themes. This makes it possible to change theme and keep the code the same while also retaining the same overall item placement.

    - -

    Using Item Modes

    - -

    So far the genlist examples have all featured bare lists while the genlist component is able to display trees or even a "group" mode where scrolling keeps the item at the top of the UI component until another group comes and replaces it.

    -

    Group Mode

    -

    The group mode makes it possible to keep an element visible as long as one of its children is visible. This is most useful for "title" items.

    -

    Mark some elements as ELM_GENLIST_ITEM_GROUP and use the returned Elm_Object_Item to establish the parent-children relationship when adding the children items.

    -

    Since there are two kind of items, create two item classes. Give them different styles and callback functions. The callback functions are visible in the example, they have no functionalities:

    -
    -app->itc = elm_genlist_item_class_new();
    -app->itc->item_style = "default";
    -app->itc->func.text_get = _genlist_text_get_size;
    -app->itc->func.content_get = _genlist_content_get_bg;
    -app->itc->func.state_get = NULL;
    -app->itc->func.del = NULL; 
    -
    -app->itc2 = elm_genlist_item_class_new();
    -app->itc2->item_style = "1text.1icon";
    -app->itc2->func.text_get = _genlist_text_get_nosize;
    -app->itc2->func.content_get = _genlist_content_get_icon;
    -app->itc2->func.state_get = NULL;
    -app->itc2->func.del = NULL; 
    -
    - -

    Then add a group header and follow it with 10 children. This is repeated 1000 times.

    -

    The parent has type ELM_GENLIST_ITEM_GROUP while the children have type ELM_GENLIST_ITEM_NONE.

    -

    The other important point is that the value returned by lm_genlist_item_append() is stored in it and then sent to the elm_genlist_item_append() call that adds the children. This creates the parent-children relationship.

    -
    -for (i = 0; i < 1000; i++) 
    -{
    -   it = elm_genlist_item_append(app->list, app->itc2,
    -      (void *)(uintptr_t) (10 * i),
    -      NULL,
    -      ELM_GENLIST_ITEM_GROUP,
    -      NULL,
    -      NULL
    -   );
    -   for (j = 0; j < 10; j++)
    -   {
    -      elm_genlist_item_append(app->list, app->itc,
    -         (void *)(uintptr_t) (10 * i + j),
    -         it,
    -         ELM_GENLIST_ITEM_NONE,
    -         NULL,
    -         NULL
    -      );
    -   }
    -}
    -
    - -

    Tree Mode

    -

    Like group mode, tree mode uses the parenting relationship with other items. Unlike group mode, the child elements are created on-demand when their parent is expanded and deleted when it is contracted. This is done by using smart callbacks: expand,request, expanded, contract,request, and contracted. Like any smart callback, they are registered through evas_object_smart_callback_add on the genlist object:

    -
    evas_object_smart_callback_add(app->list, "expand,request",
    -   _tree_item_expand_request, NULL);
    -evas_object_smart_callback_add(app->list, "expanded",
    -   _tree_item_expanded, NULL);
    -
    -evas_object_smart_callback_add(app->list, "contract,request",
    -   _tree_item_contract_request, NULL);
    -evas_object_smart_callback_add(app->list, "contracted",
    -   _tree_item_contracted, NULL);
    -
    - -

    The callbacks expand,request and contract,request do only one thing: decide whether the element is expanded or contracted. This is done by using elm_genlist_item_expanded_set() function; if it changes the expansion status of the item, the next callback is called (either expanded or contracted, depending on whether it was an expand,request or contract,request event). A minimal implementation of these callbacks is therefore:

    -
    -static void
    -_tree_item_expand_request(void *data, Evas_Object *o, void *event_info)
    -{
    -   Elm_Object_Item *it = (Elm_Object_Item*) event_info;
    -
    -   elm_genlist_item_item_class_update(it, app->itc2);
    -
    -   elm_genlist_item_expanded_set(it, EINA_TRUE);
    -}
    -
    - - - - - - - - - - -
    Note
    The example above has an extra line: the call to elm_genlist_item_item_class_update(). It changes the item style and is explained in the Changing the item class of an item after its creation section.
    - -
    -static void
    -_tree_item_contract_request(void *data, Evas_Object *o, void *event_info)
    -{
    -   Elm_Object_Item *it = (Elm_Object_Item*) event_info;
    -
    -   elm_genlist_item_item_class_update(it, app->itc);
    -
    -   elm_genlist_item_expanded_set(it, EINA_FALSE);
    -}
    -
    - -

    As said above, once the genlist item status is set to expanded, the expanded event is triggered and it is the duty of a callback for that event to populate the list with the item's children. This relies on the parent parameter of functions like elm_genlist_item_append(), like for the group mode.

    -

    The function below is a callback implementation for the expanded event. It adds items that are built similarly to previous items, the only change is the parent parameter which is not NULL. Conveniently, the parent Elm_Object_Item pointer that is passes to the elm_genlist_item_append() function is given in the event_info callback and needs to be cast.

    -
    static void
    -_tree_item_expanded(void *data, Evas_Object *o, void *event_info)
    -{
    -   Elm_Object_Item *it_parent = (Elm_Object_Item*) event_info;
    -   int i_parent = (int)(uintptr_t) data;
    -   int i;
    -
    -   for (i = 0; i < 10; i++) 
    -   {
    -      elm_genlist_item_append(app->list, app->itc,
    -            (void *)(uintptr_t) (i + i_parent),
    -            it_parent,
    -            ELM_GENLIST_ITEM_NONE,
    -            NULL,
    -            NULL
    -      );
    -   }
    -}
    -
    - -

    The following code has the callback function for the contracted event. It imply calls elm_genlist_item_subitems_clear() to clear all children (including their own children if they have any) of the given item. Again, the item that is being contracted is available through the event_info parameter to the callback.

    -
    static void
    -_tree_item_contracted(void *data, Evas_Object *o, void *event_info)
    -{
    -   Elm_Object_Item *it_parent = (Elm_Object_Item*) event_info;
    -
    -   elm_genlist_item_subitems_clear(it_parent);
    -}
    -
    - -

    Mixing Group and Tree Modes

    -

    A common UI design is to mix group and tree modes. It allows for a tree behavior while also keeping the group header item. The EFLs do not do any magic here and the way to get such a behavior is to create an item of type group, an item of type tree which parent is the group item. Then add the callbacks to populate the children of the tree item in the regular way.

    - -

    Using Other APIs

    - -

    Homogeneous Item Size

    -

    Because of the scroller, the actual height and/or width of the genlist must be computed. This means summing the sizes of all the items, the sizes must be computed. This obviously has a cost and slows down adding items to the genlist.

    -

    The elm_genlist_homogeneous_set() function alleviates this issue by assuming all the items are the same size as the first one of the list. It speeds up large insertions. However, it may lead to serious graphical issues if the items are not actually the same size. Use with care.

    - -

    Changing the Item Class of an Item After Its Creation

    -

    Changing the item class of a UI component is an easy way to change its appearance upon selection or other actions of the user. This is done by calling elm_genlist_item_class_update():

    -
    static void
    -_tree_item_expand_request(void *data, Evas_Object *o, void *event_info)
    -{
    -   Elm_Object_Item *it = (Elm_Object_Item*) event_info;
    -
    -   // Change the appearance and possibly content of the item being expanded.
    -   elm_genlist_item_item_class_update(it, app->itc2);
    -
    -   elm_genlist_item_expanded_set(it, EINA_TRUE);
    -}
    -
    - - - - -
    - -Go to top - - - - - - - diff --git a/org.tizen.tutorials/html/native/ui/gesture_detector_tutorial_n.htm b/org.tizen.tutorials/html/native/ui/gesture_detector_tutorial_n.htm deleted file mode 100644 index b9b9b5a..0000000 --- a/org.tizen.tutorials/html/native/ui/gesture_detector_tutorial_n.htm +++ /dev/null @@ -1,278 +0,0 @@ - - - - - - - - - - - - - - Gesture Detector: Implementing Gestures Provided by the EFL Library - - - - - - -
    -

    Gesture Detector: Implementing Gestures Provided by the EFL Library

    - - -

    This tutorial demonstrates how you can implement different types of gestures provided by the EFL library and instructions on how to use them.

    - -

    Warm-up

    -

    Become familiar with the Elementary and Evas API basics by learning about:

    - - - -

    Initializing Touch Gestures

    - -

    The EFL library provides a wide range of touch gestures, such as tap, double tap, triple tap, long tap, momentum, line, zoom and rotate, which can be used by the application to build a dynamic user interface interaction which is simple to use as well as intuitive.

    -

    The create_base_gui function creates the application layout. It starts by creating a window, then adds the elm_conformant component to it to decorate the window with an indicator. It then adds the elm_naviframe component which acts as a view manager for the window and provides the window title functionality. After this it creates a gesture view by using the create_main_view() function and adds it to naviframe.

    -
    -static void
    -create_base_gui(appdata_s *ad)
    -{
    -   Elm_Object_Item *nf_it, *tabbar_it;
    -   // Window
    -   ad->win = elm_win_util_standard_add(PACKAGE, PACKAGE);
    -   elm_win_autodel_set(ad->win, EINA_TRUE);
    -   evas_object_smart_callback_add(ad->win, "delete,request", win_delete_request_cb, NULL);
    -   // Conformant
    -   ad->conform = elm_conformant_add(ad->win);
    -   elm_win_conformant_set(ad->win, EINA_TRUE);
    -   evas_object_size_hint_weight_set(ad->conform, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
    -   elm_win_resize_object_add(ad->win, ad->conform);
    -   evas_object_show(ad->conform);
    -   // Naviframe
    -   ad->nf = elm_naviframe_add(ad->layout);
    -   // Calendar View
    -   create_main_view(ad);
    -   elm_naviframe_item_push(ad->nf, "Calendar", NULL, NULL, ad->calendar, NULL);
    -   elm_object_part_content_set(ad->layout, "elm.swallow.content", ad->nf);
    -   // Show window after the base GUI is set up
    -   evas_object_show(ad->win);
    -}
    -
    - -

    The create_main_view function creates the application layout by arranging the labels and rectangles by using recursive composition of the box layout:

    -
    -static void
    -create_main_view(appdata_s *ad)
    -{
    -   // Box
    -   ad->box = elm_box_add(ad->nf);
    -   evas_object_size_hint_weight_set(ad->box, EVAS_HINT_EXPAND, VAS_HINT_EXPAND);
    -   elm_box_padding_set(ad->box, 0, 5 * elm_config_scale_get());
    -   evas_object_show(ad->box);
    -   // Event Rect
    -   ad->rect = evas_object_rectangle_add(evas_object_evas_get(ad->box));
    -   evas_object_size_hint_weight_set(ad->rect, EVAS_HINT_EXPAND, VAS_HINT_EXPAND);
    -   evas_object_size_hint_align_set(ad->rect, EVAS_HINT_FILL, EVAS_HINT_FILL);
    -   evas_object_color_set(ad->rect, 204, 204, 204, 255);
    -   evas_object_repeat_events_set(ad->rect, EINA_TRUE);
    -
    -   ad->gl = create_gesture_layer(ad);
    -
    -   elm_box_pack_end(ad->box, ad->rect);
    -   evas_object_show(ad->rect);
    -}
    -
    - -

    A gesture layer is added to the rectangle object. This layer is able to receive the gesture event:

    -
    -static Evas_Object *
    -create_gesture_layer(appdata_s *ad)
    -{
    -   Evas_Object *g = elm_gesture_layer_add(ad->win);
    -   elm_gesture_layer_attach(g, ad->rect);
    -}
    -
    - -

    The following figure illustrates the Gesture Detector.

    - -

    Figure: Gesture Detector screen

    -

    Gesture Detector screen

    - -

    Implementing Touch Gestures

    - -

    The elm_gesture_layer_attach() is the function to which a gesture layer for a particular object is attached.

    -

    A gesture can have 4 different states:

    -
      -
    • ELM_GESTURE_STATE_START
    • -
    • ELM_GESTURE_STATE_MOVE
    • -
    • ELM_GESTURE_STATE_ABORT
    • -
    • ELM_GESTURE_STATE_END
    -

    Every gesture starts with the ELM_GESTURE_STATE_START state and finishes with either the ELM_GESTURE_STATE_END or ELM_GESTURE_STATE_ABORT state depending on whether the gesture is completed or aborted on that object.

    -

    If an application only needs to track a finished gesture, it can listen for the finished state only. For a more complete control of the gesture, an application can listen for all state changes for that particular gesture.

    -

    The elm_gesture_layer_cb_set() function is used for registering state change callback for a particular gesture.

    -

    For more information about the gestures, see the gesture documentation.

    - -

    To detect touch gestures:

    -
      -
    • The following example adds callbacks for listening to the tap gesture:

      -
      -elm_gesture_layer_cb_set(g, ELM_GESTURE_N_TAPS,
      -   ELM_GESTURE_STATE_START, n_finger_tap_start, ad);
      -elm_gesture_layer_cb_set(g, ELM_GESTURE_N_TAPS,
      -   ELM_GESTURE_STATE_END, n_finger_tap_end, ad);
      -elm_gesture_layer_cb_set(g, ELM_GESTURE_N_TAPS,
      -   ELM_GESTURE_STATE_ABORT, n_finger_tap_abort, ad);
      -
    • -
    • The following example adds callbacks for listening to the double tap gesture:

      -
      -elm_gesture_layer_cb_set(g, ELM_GESTURE_N_DOUBLE_TAPS,
      -   ELM_GESTURE_STATE_START, dbl_click_start, ad);
      -elm_gesture_layer_cb_set(g, ELM_GESTURE_N_DOUBLE_TAPS,
      -   ELM_GESTURE_STATE_MOVE, dbl_click_move, ad);
      -elm_gesture_layer_cb_set(g, ELM_GESTURE_N_DOUBLE_TAPS,
      -   ELM_GESTURE_STATE_END, dbl_click_end, ad);
      -elm_gesture_layer_cb_set(g, ELM_GESTURE_N_DOUBLE_TAPS,
      -   ELM_GESTURE_STATE_ABORT, dbl_click_abort, ad);
      -
    • - -
    • The following example adds callbacks for listening to the triple tap gesture:

      -
      -elm_gesture_layer_cb_set(g, ELM_GESTURE_N_TRIPLE_TAPS,
      -   ELM_GESTURE_STATE_START, triple_click_start, ad);
      -elm_gesture_layer_cb_set(g, ELM_GESTURE_N_TRIPLE_TAPS,
      -   ELM_GESTURE_STATE_MOVE, triple_click_move, ad);
      -elm_gesture_layer_cb_set(g, ELM_GESTURE_N_TRIPLE_TAPS,
      -   ELM_GESTURE_STATE_END, triple_click_end, ad);
      -elm_gesture_layer_cb_set(g, ELM_GESTURE_N_TRIPLE_TAPS,
      -   ELM_GESTURE_STATE_ABORT, triple_click_abort, ad);
      -
    • -
    • The following example adds callbacks for listening to the long tap gesture:

      -
      -elm_gesture_layer_cb_set(g, ELM_GESTURE_MOMENTUM,
      -   ELM_GESTURE_STATE_START, momentum_start, ad);
      -elm_gesture_layer_cb_set(g, ELM_GESTURE_MOMENTUM,
      -   ELM_GESTURE_STATE_END, momentum_end, ad);
      -elm_gesture_layer_cb_set(g, ELM_GESTURE_MOMENTUM,
      -   ELM_GESTURE_STATE_ABORT, momentum_abort, ad);
      -elm_gesture_layer_cb_set(g, ELM_GESTURE_MOMENTUM,
      -   ELM_GESTURE_STATE_MOVE, momentum_move, ad);
      -
    • - -
    • The following example adds callbacks for listening to the momentum gesture:

      -
      -elm_gesture_layer_cb_set(g, ELM_GESTURE_MOMENTUM,
      -   ELM_GESTURE_STATE_START, momentum_start, ad);
      -elm_gesture_layer_cb_set(g, ELM_GESTURE_MOMENTUM,
      -   ELM_GESTURE_STATE_END, momentum_end, ad);
      -elm_gesture_layer_cb_set(g, ELM_GESTURE_MOMENTUM,
      -   ELM_GESTURE_STATE_ABORT, momentum_abort, ad);
      -elm_gesture_layer_cb_set(g, ELM_GESTURE_MOMENTUM,
      -   ELM_GESTURE_STATE_MOVE, momentum_move, ad);
      -
    • - -
    • The following example adds callbacks for listening to the line gesture:

      -
      -elm_gesture_layer_cb_set(g, ELM_GESTURE_N_LINES,
      -   ELM_GESTURE_STATE_START, line_start, ad);
      -elm_gesture_layer_cb_set(g, ELM_GESTURE_N_LINES,
      -   ELM_GESTURE_STATE_MOVE, line_move, ad);
      -elm_gesture_layer_cb_set(g, ELM_GESTURE_N_LINES,
      -   ELM_GESTURE_STATE_END, line_end, ad);
      -elm_gesture_layer_cb_set(g, ELM_GESTURE_N_LINES,
      -   ELM_GESTURE_STATE_ABORT, line_abort, ad);
      -
    • - -
    • The following examples add callbacks for listening to the flick gesture:

      -
      -elm_gesture_layer_cb_set(g, ELM_GESTURE_N_FLICKS,
      -   ELM_GESTURE_STATE_START, flick_start, ad);
      -elm_gesture_layer_cb_set(g, ELM_GESTURE_N_FLICKS,
      -   ELM_GESTURE_STATE_END, flick_end, ad);
      -elm_gesture_layer_cb_set(g, ELM_GESTURE_N_FLICKS,
      -   ELM_GESTURE_STATE_ABORT, flick_abort, ad);
      -
    • - -
    • The following examples add callbacks for listening to the zoom gesture:

      -
      -elm_gesture_layer_cb_set(g, ELM_GESTURE_ZOOM,
      -   ELM_GESTURE_STATE_START, zoom_start, ad);
      -elm_gesture_layer_cb_set(g, ELM_GESTURE_ZOOM,
      -   ELM_GESTURE_STATE_END, zoom_end, ad);
      -elm_gesture_layer_cb_set(g, ELM_GESTURE_ZOOM,
      -   ELM_GESTURE_STATE_ABORT, zoom_abort, ad);
      -elm_gesture_layer_cb_set(g, ELM_GESTURE_ZOOM,
      -   ELM_GESTURE_STATE_MOVE, zoom_move, ad);
      -
    • - -
    • The following example adds callbacks for listening to the rotate gesture:

      -
      -elm_gesture_layer_cb_set(g, ELM_GESTURE_ROTATE,
      -   ELM_GESTURE_STATE_START, rotate_start, ad);
      -elm_gesture_layer_cb_set(g, ELM_GESTURE_ROTATE,
      -   ELM_GESTURE_STATE_END, rotate_end, ad);
      -elm_gesture_layer_cb_set(g, ELM_GESTURE_ROTATE,
      -   ELM_GESTURE_STATE_ABORT, rotate_abort, ad);
      -elm_gesture_layer_cb_set(g, ELM_GESTURE_ROTATE,
      -   ELM_GESTURE_STATE_MOVE, rotate_move, ad);
      -
    • - -
    • The following example adds a callback for getting the tap gesture finishing notification:

      -
      -static Evas_Event_Flags
      -n_finger_tap_end(void *data, void *event_info)
      -{
      -   appdata_s *ad = data;
      -   Elm_Gesture_Taps_Info *p = (Elm_Gesture_Taps_Info *) event_info;
      -   return EVAS_EVENT_FLAG_ON_HOLD;
      -}
      -
    • -
    - - - - -
    - -Go to top - - - - - - - diff --git a/org.tizen.tutorials/html/native/ui/menu_tutorial_mn.htm b/org.tizen.tutorials/html/native/ui/menu_tutorial_mn.htm deleted file mode 100644 index 9b4587e..0000000 --- a/org.tizen.tutorials/html/native/ui/menu_tutorial_mn.htm +++ /dev/null @@ -1,555 +0,0 @@ - - - - - - - - - - - - - - Menu: Adding Menus to the Application - - - - - - -
    -

    Menu: Adding Menus to the Application

    - - -

    This tutorial shows how to add menus to the application. The example code creates an application with 3 views, these views are showed by an interaction with a menu bar, placed on the top of the application. The application has also a hidden menu that appears only when the menu button is pressed.

    - - - - - - - - - - -
    Note
    This feature is supported in mobile applications only.
    - -

    Warm-up

    -

    Become familiar with the Ecore, Elementary, and Evas API basics by learning about:

    - - -

    Defining the Application "Structure"

    - -

    Define the structure of the application:

    -
    typedef struct appdata
    -{
    -   Evas_Object* win; // The main window
    -   Evas_Object* layout; // The Edje layout
    -   Evas_Object* conform; // The conform
    -   Evas_Object *nf; // The Naviframe to handle the views
    -   appmenu_s *menu; // The main menu
    -   appmenu_s *sidemenu; // The side menu
    -   mainview_s *main_view; // The main view (dayselector)
    -   calview_s *cal_view; // The calendar view
    -   dateview_s *date_view; // The date and time view
    -   settview_s *settings_view; // The settings view
    -   Eina_Bool sdmenu_up; // A Boolean variable to keep the side menu status
    -} appdata_s;
    -
    -

    This structure contains some specific variables for the views and the menus.

    -

    Define the main view by using the structure mainview, it is composed of a box (the main container), a dayselector, an image img, and a label lb_main.

    -
    typedef struct mainview
    -{
    -   Evas_Object *box; // The main container of the view
    -   Evas_Object *colorselector; // A color selector
    -   Evas_Object *img; // An image 
    -   Evas_Object *lb_day; // A label
    -} mainview_s;
    -
    -

    The date view is very similar, it contains a box, a datetime component and a label lb_date.

    -
    typedef struct dateview
    -{
    -   Evas_Object *box; // The main container of the view 
    -   Evas_Object *datetime; // A datetime component 
    -   Evas_Object *lb_date; // A label 
    -} dateview_s;
    -
    -

    The last view is the calendar, it contains a box, a calendar and a label lb_cal.

    -
    typedef struct calview
    -{
    -   Evas_Object *box; // The main container of the view 
    -   Evas_Object *calendar; // A calendar component  
    -   Evas_Object *lb_cal; // A label component
    -} calview_s;
    -
    -

    The last members of the application structure are the 2 menus. The main menu is fixed and visible, and the side menu is hidden on application starts. These menus are represented by the appmenu structure.

    -
    typedef struct appmenu
    -{
    -   Evas_Object *tb; // The toolbar
    -   Elm_Object_Item *submenu; // The submenu item
    -} appmenu_s;
    -
    - -

    Defining the Application Theme

    - -

    After the structure is defined, define the UI. In this tutorial, Basic EDC UI Application is used.

    -

    This application structure is based on this skeleton:

    - -

    Figure: Menu skeleton

    -

    Menu skeleton

    - - -

    The window, the conformant and the layout are set by the Basic EDC UI Application skeleton. Setup the containers for UI components and views.

    -

    Create the main_menu SWALLOW part in the .edc file.

    -
    -part
    -{
    -   name: "menu/main";
    -   type: SWALLOW;            
    -   description 
    -   {
    -      state: "default" 0.0;
    -      rel1.relative: 0.0 1.0;
    -      rel2.relative: 1.0 1.0;
    -   }
    -   description 
    -   {
    -      state: "up" 0.0;
    -      rel1.relative: 0.0 0.01;
    -      rel2.relative: 1.0 0.18;
    -      
    -   }
    -} // End menu/main
    -
    -

    This part has two descriptions, one for the real position named up and another out of the screen as the default position. Create these states to animate the menu on application start. The animation is run by animation,menu_main.

    -
    program
    -{ 
    -   name: "animation,menu_main";
    -   source: "";
    -   signal: "load";
    -   action: STATE_SET "up" 1.0;
    -   target: "menu/main";
    -   transition: LINEAR 0.5;
    -} // END animation,menu_main
    -
    -

    For more information about animations, see the Effects tutorial.

    -

    Create another container for the views. This container is also a "SWALLOW" part.

    -
    part 
    -{
    -   name: "view/main";
    -   type: SWALLOW;            
    -   description 
    -   {
    -      state: "default" 0.0;
    -      rel1.relative: 0.0 1.0;
    -      rel2.relative: 1.0 1.0;
    -   }
    -   description 
    -   {
    -      state: "up" 0.0;
    -      rel1.relative: 0.0 1.1;
    -      rel1.to: "menu/main";
    -      rel2.relative: 1.0 1.0;
    -      color: 0 255 0 255; 
    -   }
    -} // END view/main 
    -
    -

    This part has also two descriptions for animation purpose, like the main_menu part.

    -

    The program:

    -
    program 
    -{ 
    -   name: "animation,view_main";
    -   source: "";
    -   signal: "load";
    -   action: STATE_SET "up" 1.0;
    -   target: "view/main";
    -   transition: LINEAR 0.2;
    -} // END animation,view_main
    -
    -

    The last container is the side menu called menu/side.

    -
    -part 
    -{ 
    -   name: "menu/side";
    -   type: SWALLOW;
    -   description 
    -   { 
    -      state: "default" 0.0;
    -      rel1.relative: -0.3 0.0;
    -      rel2.relative: -0.3 1.0;
    -      color: 255 0 0 255; 
    -   }
    -   description 
    -   {
    -      state: "up" 0.0;
    -      rel1.relative: 0.0 0.01;
    -      rel2.relative: 0.3 1.0;
    -     color: 255 0 0 255;
    -   }
    -} // END menu/side
    -
    -

    By default, this container is hidden. Clicking menu button makes it appear. The second description places the container on the left of the screen. Here is the program to run animation:

    -
    - program 
    -{ 
    -   name: "animation,menu_side";
    -   source: "MenuButton";
    -   signal: "show,sidemenu";
    -   action: STATE_SET "up" 1.0;
    -   target: "menu/side";
    -   transition: LINEAR 0.2;
    -} // END animation,menu_side
    -
    -

    This program runs when it receives an event called show,sidemenu from MenuButton source.

    -

    Create a program that does the opposite and starts when it receives a signal called hide,menu_side from MenuButton source.

    -
    -program 
    -{ 
    -   name: "animation,menu_side,hide";
    -   source: "MenuButton";
    -   signal: "hide,sidemenu";
    -   action: STATE_SET "default" 1.0;
    -   target: "menu/side";
    -   transition: LINEAR 0.2;
    -} //END animation,menu_side,hide
    -
    -program 
    -{ 
    -   name: "animation,menu_side";
    -   source: "MenuButton";
    -   signal: "show,sidemenu";
    -   action: STATE_SET "up" 1.0;
    -   target: "menu/side";
    -   transition: LINEAR 0.2;
    -} //END animation,menu_side
    -
    - -

    Creating the Basic UI

    - -

    The view container view/main is structured like this:

    - - -

    Figure: Main view

    -

    Main view

    - -

    The naviframe contains and manages the boxes. For more information, see the Container programming guide. This UI component handle views. In this example each view is contained in a box and the box is contained in the naviframe.

    -

    Create the naviframe in the create_base_gui function and allocate the memory to handle the views and menus of the application.

    -
    -// Memory allocation
    -ad->main_view = calloc(1, sizeof(mainview_s)); // Allocating memory for the main view 
    -ad->cal_view = calloc(1, sizeof(calview_s));   // Allocating memory for the calendar view 
    -ad->date_view = calloc(1, sizeof(dateview_s)); // allocating memory for the date view 
    -ad->settings_view = calloc(1, sizeof(settview_s)); // allocating memory for the Settings view
    -// END of Memory allocation
    -
    -

    Use app_terminate function to free the memory:

    -
    app_terminate(void *data)
    -{
    -   // Release all resources
    -   appdata_s *ad = data;
    -
    -   free(ad->menu);
    -   free(ad->sidemenu);
    -   free(ad->main_view);
    -   free(ad->cal_view);
    -   free(ad->settings_view);
    -} // END of app_terminate
    -
    -

    Create the naviframe:

    - -

    Create the main menu after most of the containers are created. First create a new _build_main_menu function, it takes an appdata_s as a parameter. This function is called by create_base_gui.

    -
    static void _build_main_menu(appdata_s *ad)
    -{
    -   // Memory allocation for the main menu function
    -   appmenu_s *menu = calloc(1, sizeof(appmenu_s));
    -   // Putting the "main" menu in the application data
    -   ad->menu = menu;
    -
    -   // Creation of the "Menu" toolbar
    -   menu->tb = elm_toolbar_add(ad->win);
    -
    -   // Setting the "Menu" Toolbar properties
    -   elm_toolbar_shrink_mode_set(menu->tb, ELM_TOOLBAR_SHRINK_NONE);
    -   elm_toolbar_transverse_expanded_set(menu->tb, EINA_TRUE);
    -   elm_toolbar_homogeneous_set(menu->tb, EINA_FALSE);
    -
    -   // Adding menu items to the "Menu" toolbar
    -   elm_toolbar_item_append(menu->tb, ICON_DIR"/home.png", "Home", _menu_item_selected_cb, ad);
    -   elm_toolbar_item_append(menu->tb, ICON_DIR"/calendar.png", "Calendar", _menu_item_selected_cb, ad);
    -   elm_toolbar_item_append(menu->tb, ICON_DIR"/clock.png", "Date", _menu_item_selected_cb, ad);
    -   elm_toolbar_item_append(menu->tb, ICON_DIR"/settings.png", "Settings", _menu_item_selected_cb, ad);
    -
    -   // Showing the UI component
    -   evas_object_show(menu->tb);
    -
    -   // Adding the UI component to the "menu/main" SWALLOW container defined in the .edc theme file.
    -   elm_object_part_content_set(ad->layout, "menu/main", menu->tb);
    -
    -   // Set the default view 
    -   elm_toolbar_item_selected_set(elm_toolbar_first_item_get(menu->tb), EINA_TRUE);
    -}
    -
    -

    Create a toolbar with elm_toolbar_add. This toolbar is a child of the main window so set ad->win as parameter.

    -

    Setup the behavior of the toolbar, the display mode is set by using elm_toolbar_shrink_mode_set. The toolbar does not scroll under #ELM_TOOLBAR_SHRINK_NONE mode, but it enforces a minimum size, so that all the items fit inside it. It does not scroll or show the items that do not fit under #ELM_TOOLBAR_SHRINK_HIDE mode. Finally, it scrolls under #ELM_TOOLBAR_SHRINK_SCROLL mode, and it creates a button to aggregate items which did not fit with the #ELM_TOOLBAR_SHRINK_MENU mode.

    - -

    In this example, there is only a limited number of menu elements and thus ELM_TOOLBAR_SHRINK_NONE is used.

    - -

    Expand the transverse length of the item according the transverse length of the toolbar, giving EINA_TRUE as second parameter of elm_toolbar_transverse_expanded_set.

    - -

    Make the menu items have the same size by setting EINA_TRUE to elm_toolbar_homogeneous_set. This activates the homogeneous mode of the toolbar.

    -

    Add menu items to the toolbar using elm_toolbar_item_append. This function takes 4 parameters:

    -
      -
    • the target toolbar
    • -
    • the icon path for the menu item
    • -
    • the item label
    • -
    • the function to call when the item is clicked
    • -
    • the data to associate with the item for related callbacks.
    • -
    -

    For the icons, add some images in the resource directory of the application res/images and define a macro to contain this path in the application .h file. In this example it is inc/menututorial.h.

    - -
    #define ICON_DIR "/opt/usr/apps/"PACKAGE"/res/images"
    -
    -

    Use the PACKAGE macro to setup this ICON_DIR macro. This way you can add items to the toolbar using icon images placed in the resource directory of the application.

    - -

    The item label is very important, it is used in the item callback function.

    - -

    In this example, only one callback is created to manage all the items but there can be several callback functions. Pass the application data to the callback.

    - -

    This callback is an Evas_Smart_Cb, it must have this prototype:

    -
    -_mycallback(void *data, Evas_Object *obj, void *ev)
    -
    - -

    In this example, the aim of the callback is to create the view which the user has requested. It is named _menu_item_selected_cb, and in this function we recover the calling object text to call the correct view creation function.

    -
    -it = ev;
    -
    -// Get the menu item text
    -str = elm_object_item_text_get(it);
    -
    -// Comparing with the possible view names
    -if (!strcmp(str, "Calendar")) 
    -{
    -   // Build the "Calendar View"
    -   _build_calendar_view(ad);
    -   // Set the view from the application data
    -   view = ad->cal_view->box;
    -}
    -else if (!strcmp(str, "Date")) 
    -{
    -   // Build the "Date View"
    -   _build_date_view(ad);
    -   // Set the view from the application data
    -   view = ad->date_view->box;
    -}
    -else if (!strcmp(str, "Home")) 
    -{
    -   // Build the "Home or main View"
    -   _build_main_view(ad);
    -   // Set the view from the application data
    -   view = ad->main_view->box;
    -}
    -else if (!strcmp(str, "Settings")) 
    -{
    -   // Build the "Settings" view
    -   _build_settings_view(ad);
    -   // Set the view from the application data
    -   view = ad->settings_view->box;
    -}
    -else if (!strcmp(str, "Clock")) 
    -{
    -   // Build the "Date View" 
    -   _build_date_view(ad);
    -   // Set the view from the application data
    -   view = ad->date_view->box;
    -}
    -
    -// Show the view in the naviframe 
    -elm_object_content_set(ad->nf, view);
    -
    -

    The menu has views, Calendar, Date, Settings, and Home (main view). The view names are stored in the menu item label, to get the label compare the returned string with the view names. When the name matches, the view is built by calling the correct function. Store the view in the application data and set up a new content to the naviframe before exit.

    -

    This way when the user clicks a menu item, the view changes. The naviframe component destroys its content on each call of elm_object_content_set. That is why the content must be built again on each item click.

    -

    Create the functions which create the views.

    -
    static void _build_main_view(appdata_s *ad)
    -{
    -   mainview_s *view = ad->main_view;
    -   char buf[PATH_MAX];
    -
    -   // Main box
    -   view->box = elm_box_add(ad->nf);
    -   elm_box_horizontal_set(view->box, EINA_FALSE);
    -   elm_box_homogeneous_set(view->box, EINA_TRUE);
    -
    -   view->colorselector = elm_colorselector_add(view->box);
    -   elm_colorselector_mode_set(view->colorselector, ELM_COLORSELECTOR_PALETTE);
    -   elm_box_pack_start(view->box, view->colorselector);
    -   evas_object_show(view->colorselector);
    -
    -   view->img = elm_image_add(view->box);
    -   evas_object_size_hint_weight_set(view->img, EVAS_HINT_FILL, EVAS_HINT_FILL);
    -   evas_object_size_hint_align_set(view->img, 0.5, 0.5);
    -   evas_object_size_hint_min_set(view->img, 256, 256);
    -   ;snprintf(buf, sizeof(buf), "%s/%s", ICON_DIR, "tizen-logo.png");
    -   if (!elm_image_file_set(view->img, buf, NULL))
    -      elm_object_text_set(view->lb_day, "Problem loading image");
    -   elm_box_pack_start(view->box, view->img);
    -   evas_object_show(view->img);
    -
    -   view->lb_day = elm_label_add(view->box);
    -   elm_object_text_set(view->lb_day, "Main view");
    -   evas_object_size_hint_weight_set(view->lb_day, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
    -   elm_box_pack_end(view->box, view->lb_day);
    -   evas_object_show(view->lb_day);
    -}
    -
    -static void
    -_build_calendar_view(appdata_s *ad)
    -{
    -   calview_s *view = ad->cal_view;
    -
    -   // Main box image = elm_image_add(win);
    -
    -   view->box = elm_box_add(ad->nf);
    -   elm_box_horizontal_set(view->box, EINA_FALSE);
    -   elm_box_homogeneous_set(view->box, EINA_TRUE);
    -
    -   view->calendar = elm_image_add(ad->nf);
    -   evas_object_size_hint_weight_set(view->calendar, EVAS_HINT_FILL, EVAS_HINT_FILL);
    -   evas_object_size_hint_align_set(view->calendar, 0.5, 0.5);
    -   evas_object_size_hint_min_set(view->calendar, 256, 256);
    -   elm_image_file_set(view->calendar, ICON_DIR"/calendar.png", NULL);
    -   elm_box_pack_start(view->box, view->calendar);
    -   evas_object_show(view->calendar);
    -
    -   view->lb_cal = elm_label_add(view->box);
    -   elm_object_text_set(view->lb_cal, "The calendar view");
    -   evas_object_size_hint_weight_set(view->lb_cal, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
    -   elm_box_pack_end(view->box, view->lb_cal);
    -   evas_object_show(view->lb_cal);
    -} // End of_build_calendar_view
    -
    -

    Each function creates a view and stores it in the application data.

    - -

    Creating a Hidden Menu

    - -

    Add a new function called _build_side_menu to create the side Menu toolbar and add some items to it. This function takes the application data as parameter and stores the built menu in the sidemenu attribute of the structure.

    -
    static void _build_side_menu(appdata_s *ad)
    -{
    -   appmenu_s *sidemenu = calloc(1, sizeof(appmenu_s));
    -   ad->sidemenu = sidemenu;
    -
    -   sidemenu->tb = elm_toolbar_add(ad->win);
    -
    -   elm_toolbar_shrink_mode_set(sidemenu->tb, ELM_TOOLBAR_SHRINK_EXPAND);
    -   elm_toolbar_transverse_expanded_set(sidemenu->tb, EINA_TRUE);
    -
    -   elm_toolbar_item_append(sidemenu->tb, ICON_DIR"/home.png", "Home", _menu_item_selected_cb, ad);
    -   elm_toolbar_item_append(sidemenu->tb, ICON_DIR"/account.png", "Account", NULL, NULL);
    -   elm_toolbar_item_append(sidemenu->tb, ICON_DIR"/contacts.png", "Friends", NULL, NULL);
    -   elm_toolbar_item_append(sidemenu->tb, ICON_DIR"/clock.png", "Clock", _menu_item_selected_cb, ad);
    -   elm_toolbar_homogeneous_set(sidemenu->tb, EINA_FALSE);
    -   evas_object_show(sidemenu->tb);
    -   elm_object_part_content_set(ad->layout, "menu/side", sidemenu->tb);
    -   elm_toolbar_horizontal_set(sidemenu->tb, EINA_FALSE);
    -   elm_toolbar_item_selected_set(elm_toolbar_first_item_get(sidemenu->tb), EINA_TRUE);
    -}
    -
    -

    The side menu is created but hidden by default, to make it appear the use must click Home button.

    - -

    By default the Basic EDC UI application creates a function keydown_cb to handle the key down events. In the create_base_gui function an ecore_event_handler_add function is called with the ECORE_EVENT_KEY_DOWN macro and with keydown_cb as callback. In this callback, the KEY_END event puts the window on the lower state.

    -
    keydown_cb(void *data , int type , void *event)
    -{
    -   appdata_s *ad = data;
    -   Ecore_Event_Key *ev = event;
    -   if (!strcmp(ev->keyname, KEY_END)) 
    -   {
    -      // Let window go to hide state
    -      elm_win_lower(ad->win);
    -   }
    -
    -   return ECORE_CALLBACK_DONE;
    -}
    -
    -

    The key name of menu button is XF86Send. Add the menu button key press handling to the keydown_cb. The menu is shown on the first press and hidden it on the second press. Use Eina_Bool sdmenu_up on the application data to store the menu status during the application execution. If ad->sdmenu_up is EINA_TRUE the menu is visible.

    - -

    A program animation,menu_side is defined in the .edc theme file. This program is run when the signal show,sidemenu is received with the source MenuButton. Also the program who hides the side menu is defined and is called animation,menu_side,hide which start on signal hide,sidemenu.

    - -

    Test side menu status by sending the signals using elm_object_signal_emit

    -
    -if (!strcmp(ev->keyname, "XF86Send")) 
    -{
    -   if (ad->sdmenu_up == EINA_TRUE) 
    -   {
    -      // If the menu is visible send a "hide,sidemenu" signal
    -      elm_object_signal_emit(ad->layout, "hide,sidemenu", "MenuButton");
    -      // Store the new menu status (hidden)
    -      ad->sdmenu_up = EINA_FALSE;
    -   }
    -}
    -
    -

    Now the menu appears and disappears when the menu button is pressed.

    -

    The first side menu button sends back to the main view:

    -
    -// Hide the side menu if it's visible
    -if (ad->sdmenu_up == EINA_TRUE) 
    -{
    -   elm_object_signal_emit(ad->layout, "hide,sidemenu", "MenuButton");
    -      ad->sdmenu_up = EINA_FALSE;
    -}
    -
    -

    This way the menu disappears when the view is selected by the user.

    - - - - -
    - -Go to top - - - - - - - diff --git a/org.tizen.tutorials/html/native/ui/multipoint_touch_tutorial_n.htm b/org.tizen.tutorials/html/native/ui/multipoint_touch_tutorial_n.htm deleted file mode 100644 index 338954e..0000000 --- a/org.tizen.tutorials/html/native/ui/multipoint_touch_tutorial_n.htm +++ /dev/null @@ -1,278 +0,0 @@ - - - - - - - - - - - - - - Multi-point Touch: Tracking Touch Events - - - - - - -
    -

    Multi-point Touch: Tracking Touch Events

    - - -

    This tutorial demonstrates how you can use the Evas_Object to paint on a canvas and track touch events.

    - -

    Warm-up

    -

    Become familiar with the Eina, Elementary, and Evas API basics by learning about:

    - - -

    Initializing Multi-point Touch

    - -

    This sample is a fully functional application able to track multiple simultaneous clicks. For every click, a black rectangle spot is drawn on the screen. This way it is easy to test the multi-point touch operation with the application.

    - -

    Initialization is implemented in the multitouch.c file.

    -

    The appdata structure includes Evas_Object pointers, a list, and a Boolean flag.

    -
    -typedef struct appdata 
    -{
    -   Evas_Object *win;
    -   Evas_Object *conform;
    -   Evas_Object *nf;
    -   Evas_Object *button;
    -   Evas_Object *box;
    -   Evas_Object *rect;
    -   Evas_Object *label;
    -
    -   // List of mouse spots
    -   Eina_List *spots;
    -
    -   // Flag for checking the mouse down event
    -   Eina_Bool down; 
    -} 
    -appdata_s;
    -
    - -

    The main() function initializes event callbacks and calls the ui_app_main() function to start the EFL application.

    -
    -int
    -main(int argc, char *argv[])
    -{
    -   appdata_s *ad = {0,};
    -   int ret = 0;
    -
    -   ui_app_lifecycle_callback_s event_callback = {0,};
    -   app_event_handler_h handlers[5] = {NULL,};
    -
    -   event_callback.create = app_create;
    -   event_callback.terminate = app_terminate;
    -   event_callback.pause = app_pause;
    -   event_callback.resume = app_resume;
    -   event_callback.app_control = app_control;
    -
    -   ui_app_add_event_handler(&handlers[APP_EVENT_LOW_BATTERY], APP_EVENT_LOW_BATTERY, ui_app_low_battery, &ad);
    -   ui_app_add_event_handler(&handlers[APP_EVENT_LOW_MEMORY], APP_EVENT_LOW_MEMORY, ui_app_low_memory, &ad);
    -   ui_app_add_event_handler(&handlers[APP_EVENT_DEVICE_ORIENTATION_CHANGED], APP_EVENT_DEVICE_ORIENTATION_CHANGED, ui_app_orient_changed, &ad);
    -   ui_app_add_event_handler(&handlers[APP_EVENT_LANGUAGE_CHANGED], APP_EVENT_LANGUAGE_CHANGED, ui_app_lang_changed, &ad);
    -   ui_app_add_event_handler(&handlers[APP_EVENT_REGION_FORMAT_CHANGED], APP_EVENT_REGION_FORMAT_CHANGED, ui_app_region_changed, &ad);
    -   ui_app_remove_event_handler(handlers[APP_EVENT_LOW_MEMORY]);
    -
    -   ret = ui_app_main(argc, argv, &event_callback, &ad);
    -
    -   return ret;
    -}
    -
    - - -

    The following figure illustrates the Multi-point Touch.

    - -

    Figure: Multi-point Touch screens

    -

    Multi-point Touch screens

    - -

    Handling the Canvas

    - -

    The create_base_gui() function creates base GUI elements including Naviframe and the Naviframe button. Naviframe includes each view screen as an item, which in turn includes the title and a button which clears spots when clicked.

    - -
    static void
    -create_base_gui(appdata_s *ad)
    -{
    -   Elm_Object_Item *nf_it;
    -
    -   // Naviframe
    -   ad->nf = elm_naviframe_add(ad->conform);
    -   elm_object_content_set(ad->conform, ad->nf);
    -   evas_object_show(ad->nf);
    -
    -   // Button
    -   ad->button = elm_button_add(ad->nf);
    -   elm_object_text_set(ad->button, "Clear");
    -   evas_object_smart_callback_add(ad->button, "clicked", button_clicked_cb, ad);
    -
    -   // Create main view
    -   ad->box = create_main_view(ad);
    -   nf_it = elm_naviframe_item_push(ad->nf, "Multi-point Touch",
    -                                   NULL, NULL, ad->box, NULL);
    -   elm_object_item_part_content_set(nf_it, "title_right_btn", ad->button);
    -} 
    -
    - -

    The create_main_view() function creates the main view including the label and an event rectangle.

    -

    The label displays information on mouse event status and coordinates (x, y positions). The event rectangle is received completely through mouse (touch) events. To show 2 elements in a Naviframe content area, a container combining those elements is necessary. A box container functions in that role. The label and rectangle pack end the box and the box is embedded into the Naviframe content area.

    - -
    static Evas_Object *
    -create_main_view(appdata_s *ad)
    -{
    -   Evas_Object *box;
    -
    -   // Box
    -   box = elm_box_add(ad->nf);
    -   evas_object_size_hint_weight_set(box, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
    -   evas_object_show(box);
    -
    -   // Label
    -   ad->label = elm_label_add(box);
    -   elm_object_text_set(ad->label, "None");
    -   evas_object_size_hint_weight_set(ad->label, EVAS_HINT_EXPAND, 0);
    -   evas_object_size_hint_align_set(ad->label, EVAS_HINT_FILL, EVAS_HINT_FILL);
    -   evas_object_repeat_events_set(ad->label, EINA_TRUE);
    -   elm_box_pack_end(box, ad->label);
    -   evas_object_show(ad->label);
    -
    -   // Event Rect
    -   ad->rect = evas_object_rectangle_add(evas_object_evas_get(box));
    -   evas_object_size_hint_weight_set(ad->rect, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
    -   evas_object_size_hint_align_set(ad->rect, EVAS_HINT_FILL, EVAS_HINT_FILL);
    -   evas_object_color_set(ad->rect, 204, 204, 204, 255);
    -   evas_object_repeat_events_set(ad->rect, EINA_TRUE);
    -   elm_box_pack_end(box, ad->rect);
    -   evas_object_show(ad->rect);
    -}
    -
    - -

    The create_spot() function creates a rectangle, resizes the rectangle according to received size input, and moves the rectangle according to received coordinates (x, y positions) input.

    - -
    Evas_Object *
    -create_spot(Evas_Object *parent, Evas_Coord x, Evas_Coord y, int size)
    -{
    -   Evas_Object *spot;
    -   spot = evas_object_rectangle_add(evas_object_evas_get(parent));
    -   evas_object_resize(spot, size, size);
    -   // Adjust x, y positions to be center of object
    -   evas_object_move(spot, x - (size/2), y - (size/2));
    -   evas_object_show(spot);
    -
    -   return spot;
    -}
    -
    - -

    The rectangle object is stored in Eina_List (ad->spots) for managing other functions. The button_clicked_cb() function removes all evas_objects into the ad->spots list, meaning all spot rectangles are cleared.

    - -
    static void
    -button_clicked_cb(void *data, Evas *evas, Evas_Object *object, void *event_info)
    -{
    -   appdata_s *ad = data;
    -   Evas_Object *spot;
    -
    -   EINA_LIST_FREE(ad->spots, spot)
    -   {
    -      evas_object_del(spot);
    -      spot = NULL;
    -   }
    -   elm_object_text_set(ad->label, "Clear");
    -}
    -
    - -

    Managing Touch Events

    - -

    On the bottom of the create_main_view() function, event callbacks are added to the event rectangle. An event callback is added using the evas_object_event_callback_add() function.

    - -

    The following touch event types are supported:

    -
      -
    • EVAS_CALLBACK_MOUSE_DOWN: This event is called when the given object receives the mouse down event.
    • -
    • EVAS_CALLBACK_MOUSE_UP: This event is called when the given object receives the mouse up event.
    • -
    • EVAS_CALLBACK_MOUSE_MOVE: This event is called when the given object receives the mouse move event.
    • -
    • EVAS_CALLBACK_MULTI_DOWN: This event is called when the given object has already received the mouse down event and receives the multi-mouse down event.
    • -
    • EVAS_CALLBACK_MULTI_UP: This event is called when the given object receives the multi-mouse up event.
    • -
    • EVAS_CALLBACK_MULTI_MOVE: This event is called when the given object receives the multi-mouse move event.
    • -
    -

    If the given object receives a mouse event, a callback function is called, and event information, such as coordinates (x, y positions) is passed. The mousemove_cb() function sets the mouse status, positions text in the label, and draws a spot rectangle. To distinguish down and up positions, set different colors for the down and up rectangles.

    - -
    -static void
    -mousemove_cb(void *data, Evas *evas, Evas_Object *obj, void *event_info)
    -{
    -   appdata_s *ad = data;
    -   Evas_Object *spot;
    -   char buf[1024];
    -   Evas_Event_Mouse_Move *ev = event_info;
    -   Evas_Coord x = ev->cur.canvas.x;
    -   Evas_Coord y = ev->cur.canvas.y;
    -   int size = (int) 5 * elm_config_scale_get();
    -
    -   if (!ad->down)
    -      return;
    -
    -   snprintf(buf, sizeof(buf), "Mouse Move, %d, %d", x, y);
    -   elm_object_text_set(ad->label, buf);
    -
    -   // Draw spot on event position
    -   spot = create_spot(ad->rect, x, y, size);
    -   evas_object_color_set(spot, 0, 0, 0, 255);
    -   ad->spots= eina_list_append(ad->spots, spot);
    -}
    -
    - - - - -
    - -Go to top - - - - - - - diff --git a/org.tizen.tutorials/html/native/ui/naviframe_tutorial_mn.htm b/org.tizen.tutorials/html/native/ui/naviframe_tutorial_mn.htm deleted file mode 100644 index c343af1..0000000 --- a/org.tizen.tutorials/html/native/ui/naviframe_tutorial_mn.htm +++ /dev/null @@ -1,274 +0,0 @@ - - - - - - - - - - - - - - Naviframe: Creating Navigation Using Naviframes - - - - - - -
    -

    Naviframe: Creating Navigation Using Naviframes

    - - -

    Naviframes are containers useful for implementing interfaces with several screens having a previous/next relationship.

    - - - - - - - - - - -
    Note
    This feature is supported in mobile applications only.
    - -

    Warm-up

    -

    Become familiar with the Eina, Elementary, and Evas API basics by learning about:

    - - -

    Creating Naviframes

    - -

    Naviframes are containers useful for implementing interfaces with several screens having a previous/next relationship.

    - -

    This tutorial shows a UI with three naviframes. Each naviframe is made of 20 screens, each made up of a label with the text "label -<n>", a title with the same text, and previous and next buttons, which are used to navigate between the screens.

    -

    TODO: screenshots of the staged interface

    -

    The naviframe is "one-way": elements are added, and when the user clicks on the "previous" button, they are removed; there is no "next" button by default. To add it, we define a structure that holds the naviframe object along with a stack of the elements that the user has popped by using the "previous" button.

    -

    Note that it is possible to create the elements on-the-fly each time the "next" button is pressed. Both approaches are valid.

    -
    // NOTE: A zipper is a datastructure for an ordered set of elements and a
    -// cursor in this set, meaning there are elements before the cursor (which are
    -// stored inside the naviframe) and after (which are stored in the "popped"
    -// list.
    -struct naviframe_zipper 
    -{
    -   Evas_Object *naviframe;
    -   Eina_List *popped;
    -};
    -
    - -

    To add several naviframes, create a function that factors their creation and initializes the naviframe_zipper structure defined above.

    -
    static struct naviframe_zipper *
    -_naviframe_add(Evas_Object *parent)
    -{
    -   struct naviframe_zipper *z = malloc(sizeof(struct naviframe_zipper));
    -   z->naviframe = elm_naviframe_add(parent);
    -   z->popped = NULL;
    -
    -   evas_object_size_hint_weight_set(z->naviframe, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
    -   evas_object_size_hint_align_set(z->naviframe, EVAS_HINT_FILL, EVAS_HINT_FILL);
    -   evas_object_show(z->naviframe);
    -   // By default, objects are destroyed when they are popped from the naviframe
    -   // To save and re-use them, enable "preserve_on_pop"
    -   elm_naviframe_content_preserve_on_pop_set(z->naviframe, EINA_TRUE);
    -
    -   return z;
    -}
    -
    -

    Create buttons that are at the top of the naviframe and allow the user to go back and forth between the screens. The naviframe component builds a button for "previous" by default, but allows the programmers to provide their own buttons. It has a specific slot for the "next" button.

    -
    // Save the element that is popped from the naviframe
    -static void
    -_naviframe_prev(void *data, Evas_Object *o __UNUSED__, void *event_info __UNUSED__)
    -{
    -   struct naviframe_zipper *z = data;
    -   z->popped = eina_list_prepend(z->popped, elm_naviframe_item_pop(z->naviframe));
    -}
    -
    -// Set the first element after the current one available and push it to the
    -// naviframe
    -static void
    -_naviframe_next(void *data, Evas_Object *o __UNUSED__, void *event_info __UNUSED__)
    -{
    -   struct naviframe_zipper *z = data;
    -   Evas_Object *label, *prev, *next;
    -   const char *text;
    -   Elm_Object_Item *it;
    -
    -   label = eina_list_data_get(z->popped);
    -   z->popped = eina_list_remove_list(z->popped, z->popped);
    -   if (label != NULL) 
    -   {
    -      // The UI component is saved inside the naviframe but nothing more; we need
    -      // to create new buttons and set the title text again (copy the one
    -      // from the label that is saved).
    -      text = elm_object_text_get(label);
    -      // The _button function creates a button which is either "Previous" (-1) or
    -      // "Next" (1)
    -      prev = _button(z, -1);
    -      next = _button(z, 1);
    -      it = elm_naviframe_item_push(z->naviframe, text, prev, next, label, NULL);
    -   }
    -}
    -
    -

    When a naviframe and the pages that go inside it are built, populate it.

    -

    Remember that three naviframes are created, each populated in a different way. The common bits have been factored out as a function and the specific parts are executed through a callback. The generic function is shown below.

    -
    // Generic naviframe-populate function:
    -// Its third (and last) parameter is a callback for customization, i.e. pushes
    -// the new items to a specific position; it returns a "context" value that is
    -// used between its calls and enables behaviors such as "push after the
    -// previously-pushed item" 
    -static struct naviframe_zipper*
    -_naviframe_populate_gen(Evas_Object *parent, const char *id,
    -      void * (*populate_cb) (Evas_Object *nav, const char *title, Evas_Object
    -         *prev, Evas_Object *next, Evas_Object *label, Elm_Object_Item *context)
    -      )
    -{
    -   struct naviframe_zipper *z;
    -   Evas_Object *label, *prev, *next;
    -   Elm_Object_Item *context = NULL;
    -   char buf[256];
    -   int i;
    -
    -   z = _naviframe_add(parent);
    -
    -   for (i = 0; i < 20; i++) 
    -   {
    -      label = elm_label_add(z->naviframe);
    -      snprintf(buf, sizeof(buf), "%s [%d]", id, i);
    -      elm_object_text_set(label, buf);
    -      evas_object_show(label);
    -      evas_object_size_hint_weight_set(label, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
    -      evas_object_size_hint_align_set(label, EVAS_HINT_FILL, EVAS_HINT_FILL);
    -      // The _button function creates a button which is either "Previous" (-1) or
    -      // "Next" (1)
    -      prev = _button(z, -1);
    -      next = _button(z, 1);
    -      // Use the populate_cb callback to provide the customization of the way the
    -      // elements are added inside the naviframe
    -      context = populate_cb(z->naviframe, buf, prev, next, label, context);
    -   }
    -
    -   return z;
    -}
    -
    -

    The prototype of the callbacks is fairly large, but that is because of the syntax for callbacks in C.

    -
    // Push items one after the other
    -static Elm_Object_Item *
    -_populate_cb__push(Evas_Object *nav, const char *title,
    -      Evas_Object *prev, Evas_Object *next, Evas_Object *label,
    -      Elm_Object_Item *context)
    -{
    -   return elm_naviframe_item_push(nav, title, prev, next, label, NULL);
    -}
    -
    -// Push items one after the other but use insert_after for it
    -static Elm_Object_Item *
    -_populate_cb__push_then_insert_after(Evas_Object *nav, const char *title,
    -      Evas_Object *prev, Evas_Object *next, Evas_Object *label,
    -      Elm_Object_Item *context)
    -{
    -   if (context == NULL) 
    -   {
    -      return elm_naviframe_item_push(nav, title, prev, next, label, NULL);
    -   }
    -   else 
    -   {
    -      return elm_naviframe_item_insert_after(nav, context, title, prev, next, label, NULL);
    -   }
    -}
    -
    -// Push one item and repeatedly insert new items before the last inserted
    -// item
    -static Elm_Object_Item *
    -_populate_cb__push_then_insert_before(Evas_Object *nav, const char *title,
    -      Evas_Object *prev, Evas_Object *next, Evas_Object *label,
    -      Elm_Object_Item *context)
    -{
    -   if (context == NULL) 
    -   {
    -      return elm_naviframe_item_push(nav, title, prev, next, label, NULL);
    -   }
    -   else 
    -   {
    -      return elm_naviframe_item_insert_before(nav, context, title, prev, next, label, NULL);
    -   }
    -}
    -
    -

    Create a window with a vertical box, which holds the three naviframes from the Appcore's app_create callback.

    - -
    static bool
    -_app_create(void *data)
    -{
    -   Evas_Object *w, *box;
    -   struct naviframe_zipper *z;
    -
    -   w = elm_win_util_standard_add("Naviframe Test", "Naviframe Test");
    -
    -   box = elm_box_add(w);
    -   elm_box_horizontal_set(box, EINA_FALSE);
    -   elm_box_homogeneous_set(box, EINA_TRUE);
    -   evas_object_size_hint_weight_set(box, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
    -   evas_object_size_hint_align_set(box, EVAS_HINT_FILL, EVAS_HINT_FILL);
    -   evas_object_show(box);
    -   elm_win_resize_object_add(w, box);
    -
    -   z = _naviframe_populate_gen(w, "Before", _populate_cb__push_then_insert_before);
    -   elm_box_pack_end(box, z->naviframe);
    -
    -   z = _naviframe_populate_gen(w, "After", _populate_cb__push_then_insert_after);
    -   elm_box_pack_end(box, z->naviframe);
    -
    -   z = _naviframe_populate_gen(w, "Push", _populate_cb__push);
    -   elm_box_pack_end(box, z->naviframe);
    -
    -   evas_object_show(w);
    -}
    -
    - - - - -
    - -Go to top - - - - - - - diff --git a/org.tizen.tutorials/html/native/ui/panes_tutorial_mn.htm b/org.tizen.tutorials/html/native/ui/panes_tutorial_mn.htm deleted file mode 100644 index 590d75d..0000000 --- a/org.tizen.tutorials/html/native/ui/panes_tutorial_mn.htm +++ /dev/null @@ -1,338 +0,0 @@ - - - - - - - - - - - - - - Panes: Using Panes - - - - - - -
    -

    Panes: Using Panes

    - - -

    This tutorial explains how to use Panes in the application.

    - - - - - - - - - - -
    Note
    This feature is supported in mobile applications only.
    - -

    Warm-up

    -

    Become familiar with the Elementary and Evas API basics by learning about:

    - - -

    Initializing the Application

    - -

    This is how to start an Appcore application.

    -
    #include <Elementary.h>
    -#include <app.h>
    -
    -struct _appdata 
    -{
    -   const char *name;
    -   Evas_Object *win;
    -};
    -
    -static void app_terminate(void *user_data)
    -{
    -   struct _appdata *ad;
    -
    -   if (!user_data)
    -      return;
    -
    -   ad = user_data;
    -
    -   if (ad->win)
    -      evas_object_del(ad->win);
    -}
    -
    -static bool app_create(void *user_data)
    -{
    -   struct _appdata *ad;
    -   Evas_Object *win, *conformant, *naviframe, *panes, *panes_h, *nav_it, *bt;
    -
    -   if (!user_data)
    -      return false;
    -
    -   ad = user_data;
    -
    -   // Create window 
    -   elm_policy_set(ELM_POLICY_QUIT, ELM_POLICY_QUIT_LAST_WINDOW_CLOSED);
    -   win = elm_win_util_standard_add("panes", "Panes tutorial");
    -   elm_win_autodel_set(win, EINA_TRUE);
    -
    -   if (!win)
    -      return false;
    -
    -   ad->win = win;
    -
    -   // Add elm_conformant 
    -   conformant = elm_conformant_add(win);
    -   elm_win_resize_object_add(win, conformant);
    -   evas_object_size_hint_weight_set(conformant, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
    -   evas_object_show(conformant);
    -
    -   // Add naviframe to conformant 
    -   naviframe = elm_naviframe_add(conformant);
    -   elm_object_content_set(conformant, naviframe);
    -   evas_object_show(naviframe);
    -
    -   evas_object_resize(win, 320, 400);
    -   evas_object_show(win);
    -
    -   return true;
    -}
    -
    -int main(int argc, char **argv)
    -{
    -   appdata_s *ad = {0,};
    -   int ret = 0;
    -
    -   ui_app_lifecycle_callback_s event_callback = {0,};
    -   app_event_handler_h handlers[5] = {NULL,};
    -
    -   event_callback.create = app_create;
    -   event_callback.terminate = app_terminate;
    -   event_callback.pause = app_pause;
    -   event_callback.resume = app_resume;
    -   event_callback.app_control = app_control;
    -
    -   ui_app_add_event_handler(&handlers[APP_EVENT_LOW_BATTERY], APP_EVENT_LOW_BATTERY, ui_app_low_battery, &ad);
    -   ui_app_add_event_handler(&handlers[APP_EVENT_LOW_MEMORY], APP_EVENT_LOW_MEMORY, ui_app_low_memory, &ad);
    -   ui_app_add_event_handler(&handlers[APP_EVENT_DEVICE_ORIENTATION_CHANGED], APP_EVENT_DEVICE_ORIENTATION_CHANGED, ui_app_orient_changed, &ad);
    -   ui_app_add_event_handler(&handlers[APP_EVENT_LANGUAGE_CHANGED], APP_EVENT_LANGUAGE_CHANGED, ui_app_lang_changed, &ad);
    -   ui_app_add_event_handler(&handlers[APP_EVENT_REGION_FORMAT_CHANGED], APP_EVENT_REGION_FORMAT_CHANGED, ui_app_region_changed, &ad);
    -   ui_app_remove_event_handler(handlers[APP_EVENT_LOW_MEMORY]);
    -
    -   ret = ui_app_main(argc, argv, &event_callback, &ad);
    -
    -   return ret;
    -}
    -
    -

    The code above creates a window entitled "Panes tutorial", composed of a conformant component that contains a naviframe component. To add a new Panes object, use the _create() function.

    - -

    Creating a Panes Component

    - -

    The elm_panes component adds a draggable bar between two contents. When dragged, this bar resizes the contents' size. To create a new Panes into an Elementary object, use the elm_panes_add() function:

    -
    // Add an elm_panes 
    -panes = elm_panes_add(naviframe);
    -evas_object_size_hint_weight_set(panes, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
    -elm_win_resize_object_add(win, panes);
    -evas_object_show(panes);
    -
    -nav_it = elm_naviframe_item_push (naviframe, "Panes view", NULL, NULL, panes, NULL);
    -
    -

    Here the Panes is created and added in the naviframe.

    - -

    Configuring the Panes

    - -

    By default, the orientation of the Panes is vertical. To modify the orientation, use the elm_panes_horizontal_set() function.

    -
    // Add a horizontal elm_panes 
    -panes_h = elm_panes_add(naviframe);
    -elm_panes_horizontal_set(panes_h, EINA_TRUE);
    -
    -

    The code above creates another Panes object and sets the horizontal orientation. To add content in a panes, use the elm_object_part_content_set() function. Here we add the horizontal Panes (panes_h) to the "left" part of the first created Panes (panes).

    -
    elm_object_part_content_set(panes, "left", panes_h);
    -
    - -

    This is how to set a button object to the "right" side of our vertical Panes component.

    -
    // Create a button object 
    -bt = elm_button_add(naviframe);
    -elm_object_text_set(bt, "Right");
    -evas_object_size_hint_weight_set(bt, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
    -evas_object_size_hint_align_set(bt, EVAS_HINT_FILL, EVAS_HINT_FILL);
    -evas_object_show(bt);
    -
    -// and set it to the "right" part of the vertical Panes 
    -elm_object_part_content_set(panes, "right", bt);
    -
    - -

    The content of the horizontal Panes is set with two button objects (up and down). When populating a vertically displayed Panes, the left content is placed at the top, and the right content is placed at the bottom.

    -
    // Create a "Up" button 
    -bt = elm_button_add(naviframe);
    -elm_object_text_set(bt, "Up");
    -evas_object_size_hint_weight_set(bt, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
    -evas_object_size_hint_align_set(bt, EVAS_HINT_FILL, EVAS_HINT_FILL);
    -evas_object_show(bt);
    -elm_object_part_content_set(panes_h, "left", bt);
    -
    -// Create a "Down" button 
    -bt = elm_button_add(naviframe);
    -elm_object_text_set(bt, "Down");
    -evas_object_size_hint_weight_set(bt, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
    -evas_object_size_hint_align_set(bt, EVAS_HINT_FILL, EVAS_HINT_FILL);
    -evas_object_show(bt);
    -elm_object_part_content_set(panes_h, "right", bt);
    -
    - -

    The elm_panes can be dragged with the mouse but the proportion can also be set with the elm_panes_content_left_size_set() and elm_panes_content_right_size_set() functions. As an example, this is how to set the left size of both panes to 80%.

    -
    // Set the proportion of the panes to 80% 
    -elm_panes_content_left_size_set(panes, 0.8);
    -elm_panes_content_left_size_set(panes_h, 0.8);
    -
    - -

    The Panes proportions can also be fixed so that the user is not able to drag them. To do this, use the elm_panes_fixed_set() function.

    -
    // Fix the Panes proportion 
    -elm_panes_fixed_set(panes_h, EINA_TRUE);
    -
    - -

    Handling Signals

    - -

    The Panes components emit four different signals, depending on the users' interaction with the draggable bar.

    -
      -
    • "press" - The pane is pressed.
    • -
    • "unpressed" - The pane is released after being pressed.
    • -
    • "clicked" - The pane is clicked.
    • -
    • "clicked,double" - The pane is double clicked.
    • -
    -

    We add a callback function for each of them.

    - -

    "clicked" Signal

    - -

    The callback function for the clicked signal prints "Clicked" to standard output.

    -
    // clicked callback 
    -static void
    -_clicked_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   dlog_print(DLOG_INFO, PANES_TAG, "Clicked\n");
    -}
    -
    - -

    This is how to register this callback function to the vertical panes.

    -
    evas_object_smart_callback_add(panes, "clicked", _clicked_cb, panes);
    -
    - -

    "press" Signal

    - -

    The callback function for the "press" signal prints "Pressed" to the standard output.

    -
    // press callback 
    -static void
    -_press_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   dlog_print(DLOG_INFO, PANES_TAG, "Pressed\n");
    -}
    -
    - -

    This is how to register this callback function to the vertical panes.

    -
    evas_object_smart_callback_add(panes, "press", _press_cb, panes);
    -
    - -

    "unpress" Signal

    - -

    For the "unpress" signal, the proportion size of the left content of the Panes component is printed to the standard output. To do this, use the elm_panes_content_left_size_get() function.

    -
    // unpress callback 
    -static void
    -_unpress_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   dlog_print(DLOG_INFO, PANES_TAG, "Unpressed, size : %f\n",
    -      elm_panes_content_left_size_get(obj));
    -}
    -
    -

    This is how to register this callback function to the Panes.

    -
    evas_object_smart_callback_add(panes, "unpress", _unpress_cb, panes);
    -
    - -

    "clicked,double" Signal

    - -

    Hide the left part of the Panes component on the "clicked,double" signal and set the left proportion to 0.0. To restore the left part proportion with a double click on the hidden part of the Panes component, use the elm_panes_content_left_size_get() and elm_panes_content_left_size_set() functions, and a variable to store the value of the current proportion.

    - -
    // double clicked callback 
    -static void
    -_clicked_double_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   static double size = 0.0;
    -   double tmp_size = 0.0;
    -   tmp_size = elm_panes_content_left_size_get(obj);
    -   if (tmp_size > 0)
    -   {
    -      elm_panes_content_left_size_set(obj, 0.0);
    -      dlog_print(DLOG_INFO, PANES_TAG, "Double clicked, hidden.\n");
    -   }
    -   else
    -   {
    -      elm_panes_content_left_size_set(obj, size);
    -      dlog_print(DLOG_INFO, PANES_TAG,
    -            "Double clicked, restoring size.\n");
    -   }
    -   size = tmp_size;
    -}
    -
    - -

    This is how to register this callback function to the Panes.

    -
    evas_object_smart_callback_add(panes, "clicked,double", _clicked_double_cb,
    -            panes);
    -
    - -

    Figure: Panes tutorial in action

    -

    Panes tutorial in action

    - - - - -
    - -Go to top - - - - - - - diff --git a/org.tizen.tutorials/html/native/ui/popup_tutorial_wn.htm b/org.tizen.tutorials/html/native/ui/popup_tutorial_wn.htm deleted file mode 100644 index d3a2ac9..0000000 --- a/org.tizen.tutorials/html/native/ui/popup_tutorial_wn.htm +++ /dev/null @@ -1,254 +0,0 @@ - - - - - - - - - - - - - - Popup: Using Popups - - - - - - -
    -

    Popup: Using Popups

    - - -

    This tutorial teaches the basics of the popup component interactions.

    - - - - - - - - - - -
    Note
    This feature is supported in wearable applications only.
    - -

    Warm-up

    -

    Become familiar with the Popup API basics by learning about:

    - - -

    Initializing the Popup Application

    - -

    This use case creates an application with a window entitled "Popup Basic Tutorial". The window consists of a conformant component, and a popup is placed inside the conformant.

    - -

    To create a typical elementary application:

    - -
    -static void
    -create_base_gui(appdata_s *ad)
    -{
    -   // Window
    -   ad->win = elm_win_util_standard_add("main", "Popup Basic Tutorial");
    -   elm_win_autodel_set(ad->win, EINA_TRUE);
    -
    -   evas_object_smart_callback_add(ad->win, "delete,request", win_delete_request_cb, NULL);
    -   eext_object_event_callback_add(ad->win, EEXT_CALLBACK_BACK, win_back_cb, ad);
    -
    -   // Conformant
    -   ad->conform = elm_conformant_add(ad->win);
    -   elm_win_indicator_mode_set(ad->win, ELM_WIN_INDICATOR_SHOW);
    -   elm_win_indicator_opacity_set(ad->win, ELM_WIN_INDICATOR_OPAQUE);
    -   evas_object_size_hint_weight_set(ad->conform, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
    -   elm_win_resize_object_add(ad->win, ad->conform);
    -   evas_object_show(ad->conform);
    -
    -   create_popup(ad->conform);
    -
    -   // Show the window after the base GUI is set up
    -   evas_object_show(ad->win);
    -}
    -
    -static bool
    -app_create(void *data)
    -{
    -   appdata_s *ad = data;
    -   create_base_gui(ad);
    -
    -   return true;
    -}
    -
    -int
    -main(int argc, char **argv)
    -{
    -   struct app_data ad = {0,};
    -   ui_app_lifecycle_callback_s event_callback = {0,};
    -
    -   event_callback.create = app_create;
    -
    -   return ui_app_main(&argc, &argv, &event_callback, &ad);
    -}
    - -

    Using Popup Styles

    - -

    To create popups using various styles:

    - -
    • Create a basic text-only popup: - -
      -Evas_Object *popup;
      -struct appdata *ad;
      -ad = (struct appdata *) data;
      -
      -popup = elm_popup_add(ad->win_main);
      -evas_object_size_hint_weight_set(popup, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      -elm_popup_align_set(popup, ELM_NOTIFY_ALIGN_FILL, 1.0);
      -eext_object_event_callback_add(popup, EEXT_CALLBACK_BACK, eext_popup_back_cb, NULL);
      -elm_object_text_set(popup, "This has only texts");
      -evas_object_show(popup);
      -
    • - -
    • Create a popup with a title and text. The title,text attribute is the title area text part that defines the title label. -
      -Evas_Object *popup;
      -struct appdata *ad;
      -ad = (struct appdata *) data;
      -
      -popup = elm_popup_add(ad->win_main);
      -evas_object_size_hint_weight_set(popup, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      -elm_popup_align_set(popup, ELM_NOTIFY_ALIGN_FILL, 1.0);
      -elm_object_part_text_set(popup, "title,text", "Title");
      -elm_object_text_set(popup,"This Popup has title area and text");
      -eext_object_event_callback_add(popup, EEXT_CALLBACK_BACK, eext_popup_back_cb, NULL);
      -evas_object_show(popup);
      -
    • - -
    • Create a popup with a title, text, and 2 buttons: -
      -Evas_Object *popup;
      -Evas_Object *btn;
      -struct appdata *ad = (struct appdata *) data;
      -
      -popup = elm_popup_add(ad->win_main);
      -evas_object_size_hint_weight_set(popup, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      -elm_popup_align_set(popup, ELM_NOTIFY_ALIGN_FILL, 1.0);
      -elm_object_part_text_set(popup, "title,text", "Title");
      -eext_object_event_callback_add(popup, EEXT_CALLBACK_BACK, eext_popup_back_cb, NULL);
      -elm_object_text_set(popup, "This is title text 2button popup");
      -
      -btn = elm_button_add(popup);
      -elm_object_style_set(btn, "popup");
      -evas_object_size_hint_weight_set(btn, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      -elm_object_text_set(btn, "Cancel");
      -elm_object_part_content_set(popup, "button1", btn);
      -evas_object_smart_callback_add(btn, "clicked", _response_cb, popup);
      -
      -btn = elm_button_add(popup);
      -elm_object_style_set(btn, "popup");
      -evas_object_size_hint_weight_set(btn, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      -elm_object_text_set(btn, "OK");
      -elm_object_part_content_set(popup, "button2", btn);
      -evas_object_smart_callback_add(btn, "clicked", _response_cb, popup);
      -
      -evas_object_show(popup);
      -
    • - -
    • Create a toast popup: -
      -Evas_Object *popup;
      -struct appdata *ad = (struct appdata *) data;
      -
      -popup = elm_popup_add(ad->win_main);
      -elm_object_style_set(popup, "toast");
      -elm_popup_orient_set(popup, ELM_POPUP_ORIENT_BOTTOM);
      -evas_object_size_hint_weight_set(popup, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      -elm_popup_align_set(popup, ELM_NOTIFY_ALIGN_FILL, 1.0);
      -eext_object_event_callback_add(popup, EEXT_CALLBACK_BACK, eext_popup_back_cb, NULL);
      -elm_object_part_text_set(popup,"elm.text", "Saving Contacts to sim");
      -
      -evas_object_smart_callback_add(popup, "block,clicked", _block_clicked_cb, NULL);
      -elm_popup_timeout_set(popup, 2.0);
      -evas_object_smart_callback_add(popup, "timeout", _timeout_cb, NULL);
      -
      -evas_object_show(popup);
      -
    • -
    - -

    Managing Popup Events

    -

    The Elementary popups respond to user interactions with several events.

    -

    To manage popup events:

    - -
      -
    • Handle timeout events: -

      The "timeout" event is triggered whenever a popup is closed as a result of timeout.

      -
      -static void _timeout_cb(void *data, Evas_Object *obj, void *event_info)
      -{
      -   evas_object_del(obj);
      -}
      -elm_popup_timeout_set(popup, 3.0);
      -evas_object_smart_callback_add(popup, "timeout", _timeout_cb, NULL);
      -
    • - -
    • Handle the block,clicked events: -

      The "block,clicked" event is triggered whenever the user taps on a blocked event area.

      -
      -static void _block_clicked_cb(void *data, Evas_Object *obj, void *event_info)
      -{
      -   evas_object_del(obj);
      -}
      -evas_object_smart_callback_add(popup, "block,clicked", _block_clicked_cb, NULL);
      -
    • - -
    - - - - - -
    - -Go to top - - - - - - - diff --git a/org.tizen.tutorials/html/native/ui/transit_effect_tutorial_n.htm b/org.tizen.tutorials/html/native/ui/transit_effect_tutorial_n.htm deleted file mode 100644 index cdae081..0000000 --- a/org.tizen.tutorials/html/native/ui/transit_effect_tutorial_n.htm +++ /dev/null @@ -1,230 +0,0 @@ - - - - - - - - - - - - - - Transit: Implementing Elementary Transit Effects - - - - - - -
    -

    Transit: Implementing Elementary Transit Effects

    - -

    This tutorial demonstrates how you can implement a variety of EFL animation effects using the APIs available in the EFL library.

    - -

    Warm-up

    -

    Become familiar with the Ecore, Elementary, and Evas API basics by learning about:

    - - - -

    Initializing the Application Layout

    - -

    The application uses UI components, such as elm_conformant and elm_naviframe for view management, layout classes, such as elm_list for the composition of the screen, and UI components, such as elm_button and elm_image for the content inside the view.

    -

    The transit is designed to apply various animated transition effects to the Evas_Object. The following transition effects are supported in the Tizen native applications:

    -
      -
    • Blend
    • -
    • Color
    • -
    • Fade
    • -
    • Flip
    • -
    • Rotation
    • -
    • Transition
    • -
    • Wipe
    • -
    • Zoom
    • -
    - -

    The application layout is created by the create_base_gui() function. First, a window is created and the elm_conformant component is added to it to decorate the window with an indicator. It then adds the elm_naviframe component, which acts as a view manager for the window and provides the window title functionality.

    -
    -static void
    -create_base_gui(appdata_s *ad)
    -{
    -   // Window
    -   ad->win = elm_win_util_standard_add(PACKAGE, PACKAGE);
    -   elm_win_autodel_set(ad->win, EINA_TRUE);
    -
    -   if (elm_win_wm_rotation_supported_get(ad->win)) 
    -   {
    -      int rots[4] = { 0, 90, 180, 270 };
    -      elm_win_wm_rotation_available_rotations_set(ad->win, (const int *)(&rots), 4);
    -   }
    -
    -   evas_object_smart_callback_add(ad->win, "delete,request", win_delete_request_cb, NULL);
    -
    -   // Conformant
    -   ad->conform = elm_conformant_add(ad->win);
    -   evas_object_size_hint_weight_set(ad->conform, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
    -   elm_win_resize_object_add(ad->win, ad->conform);
    -   evas_object_show(ad->conform);
    -
    -   // Naviframe
    -   ad->nf = create_main_view(ad);
    -   elm_object_content_set(ad->conform, ad->nf);
    -
    -   // Show window after the base GUI is set up
    -   evas_object_show(ad->win);
    -
    -   ecore_event_handler_add(ECORE_EVENT_KEY_DOWN, keydown_cb, ad);
    -}
    -
    - -

    The create_main_view() function creates the main content. It consists of a naviframe containing a list. This function returns a list of naviframe object pointers for the content set.

    -
    -static Evas_Object*
    -create_main_view(appdata_s *ad)
    -{
    -   Elm_Object_Item *nf_it;
    -   Evas_Object *navi, *list;
    -
    -   navi = elm_naviframe_add(ad->conform);
    -
    -   list = elm_list_add(navi);
    -   elm_list_mode_set(list, ELM_LIST_COMPRESS);
    -
    -   elm_list_item_append(list, "Blend", NULL, NULL, blend_cb, navi);
    -   elm_list_item_append(list, "Color", NULL, NULL, color_cb, navi
    -   elm_list_item_append(list, "Fade", NULL, NULL, fade_cb, navi);
    -   elm_list_item_append(list, "Flip", NULL, NULL, flip_cb, navi);
    -   elm_list_item_append(list, "Rotation", NULL, NULL, rotation_cb, navi);
    -   elm_list_item_append(list, "ResizableFlip", NULL, NULL, resizable_flip_cb, navi);
    -   elm_list_item_append(list, "Translation", NULL, NULL, translation_cb, navi);
    -   elm_list_item_append(list, "Wipe", NULL, NULL, wipe_cb, navi);
    -   elm_list_item_append(list, "Zoom", NULL, NULL, zoom_cb, navi);
    -   elm_list_item_append(list, "Custom", NULL, NULL, custom_cb, navi);
    -   elm_list_go(list);
    -
    -   nf_it = elm_naviframe_item_push(navi, "Transit", NULL, NULL, list, NULL);
    -
    -   return navi;
    -}
    -
    - -

    This document describes only the rotation and zoom implementations. For more information about other effects, see the transit.c file and the elm_transit document. The following figure illustrates the rotation and zoom effects.

    - -

    Figure: Rotation and zoom

    -

    Rotation and zoom

    - -

    Implementing the Rotation Effect

    - -

    If the list item named by rotation includes the touch event, the callback function for this event is called.

    -

    The data is sent as an Evas_Object. This implements the animation effect.

    -

    To implement the rotation effect:

    -
      -
    1. Use the elm_transit object with the elm_transit_add() function to add the transit effect.
    2. -
    3. Set the transit rotation amount and duration.
    4. -
    5. To start the transit animation, use the elm_transit_go() function.
    6. -
    -
    -static void
    -rotation_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   Evas_Object *layout = (Evas_Object *) data;
    -   Elm_Transit *transit = elm_transit_add();
    -
    -   // 360 degree rotation effect in the clock-wise direction
    -   elm_transit_object_add(transit, layout);
    -   elm_transit_effect_rotation_add(transit, 0, 360);
    -   elm_transit_duration_set(transit, 1);
    -   elm_transit_del_cb_set(transit, transit_del_cb, NULL);
    -   elm_transit_go(transit);
    -}
    -
    - -

    Implementing the Zoom Effect

    - -

    If the list item named by zoom includes the touch event, the callback function for this event is called.

    -

    The data is sent as an Evas_Object. This implements the animation effect.

    -

    There are 2 transit functions: one is for the zoom effect and the other is for returning to the original effect:

    -
      -
    1. After adding the transit object, add an evas_object to get the effect.
    2. -
    3. Set the zoom from the original size (1.0) to 0.4 times the original size, and set the duration.
    4. -
    5. Similarly, set the zoom size (0.4) back to the original size (1.0), and set the duration.
    6. -
    7. Set both of effects to be applied in sequence.
    8. -
    -
    -static void
    -zoom_cb(void *data, Evas_Object *obj, void *event_info)
    -{
    -   Evas_Object *layout = (Evas_Object *) data;
    -   // Zoom out to scale 0.6
    -   Elm_Transit *transit = elm_transit_add();
    -   elm_transit_smooth_set(transit, EINA_FALSE);
    -   elm_transit_object_add(transit, layout);
    -   elm_transit_effect_zoom_add(transit, 1.0, 0.4);
    -   elm_transit_duration_set(transit, 0.5);
    -
    -   // Zoom in to the original size
    -   Elm_Transit *transit2 = elm_transit_add();
    -   elm_transit_smooth_set(transit2, EINA_FALSE);
    -   elm_transit_object_add(transit2, layout);
    -   elm_transit_effect_zoom_add(transit2, 0.4, 1.0);
    -   elm_transit_duration_set(transit2, 0.5);
    -   elm_transit_del_cb_set(transit2, transit_del_cb, NULL);
    -
    -   elm_transit_chain_transit_add(transit, transit2);
    -   elm_transit_go(transit);
    -}
    -
    - - - - -
    - -Go to top - - - - - - - diff --git a/org.tizen.tutorials/html/native/ui/ui_component_tutorials_mn.htm b/org.tizen.tutorials/html/native/ui/ui_component_tutorials_mn.htm deleted file mode 100644 index 94f4f50..0000000 --- a/org.tizen.tutorials/html/native/ui/ui_component_tutorials_mn.htm +++ /dev/null @@ -1,71 +0,0 @@ - - - - - - - - - - - - - - UI Components: Managing UI Elements - - - - -
    -
    -

    Mobile native

    -
    - -
    - -
    -

    UI Components: Managing UI Elements

    - -

    The UI component tutorials demonstrate how to manage user interface-related features in Tizen native applications:

    - - - - - - -
    - -Go to top - - - - - - - diff --git a/org.tizen.tutorials/html/native/ui/ui_component_tutorials_n.htm b/org.tizen.tutorials/html/native/ui/ui_component_tutorials_n.htm deleted file mode 100644 index 3b6e88f..0000000 --- a/org.tizen.tutorials/html/native/ui/ui_component_tutorials_n.htm +++ /dev/null @@ -1,42 +0,0 @@ - - - - - - - - - - - - - UI Components: Managing UI Elements - - -
    -

    UI Components: Managing UI Elements

    - -

    Click the profile you want:

    -

    Mobile native Wearable native

    - - - -
    - - - - - - - \ No newline at end of file diff --git a/org.tizen.tutorials/html/native/ui/ui_component_tutorials_wn.htm b/org.tizen.tutorials/html/native/ui/ui_component_tutorials_wn.htm deleted file mode 100644 index 59ba0f7..0000000 --- a/org.tizen.tutorials/html/native/ui/ui_component_tutorials_wn.htm +++ /dev/null @@ -1,69 +0,0 @@ - - - - - - - - - - - - - - UI Components: Managing UI Elements - - - - -
    -
    -

    Wearable native

    -
    - -
    - -
    -

    UI Components: Managing UI Elements

    - -

    The UI component tutorials demonstrate how to manage user interface-related features in Tizen native applications:

    - - - - - - -
    - -Go to top - - - - - - - diff --git a/org.tizen.tutorials/html/native/ui/ui_layout_tutorial_mn.htm b/org.tizen.tutorials/html/native/ui/ui_layout_tutorial_mn.htm deleted file mode 100644 index 4ed59e0..0000000 --- a/org.tizen.tutorials/html/native/ui/ui_layout_tutorial_mn.htm +++ /dev/null @@ -1,292 +0,0 @@ - - - - - - - - - - - - - - UI Layout: Creating a UI Screen Layout - - - - - - -
    - -

    UI Layout: Creating a UI Screen Layout

    - - -

    This tutorial demonstrates how you can compose a UI screen using the layout classes available in the EFL UI component library. It also highlights the capabilities of the EFL layout classes in free style layouting as well as layouting in a particular sequence (such as linear or grid).

    - - - - - - - - - - -
    Note
    This feature is supported in mobile applications only.
    - -

    Warm-up

    -

    Become familiar with the Ecore, Elementary, and Evas API basics by learning about:

    - - -

    Creating the UI Layout

    - -

    The sample application uses UI components, such as elm_naviframe and elm_toolbar for the view management, layout classes, such as elm_table, elm_box, and elm_grid for the composition of the screen, and UI components, such as elm_label and elm_image for the content inside the view.

    - -

    The create_base_gui() function creates the application layout. It starts by creating a window, then adds the elm_conformant component to it to decorate the window with an indicator. It then adds the elm_naviframe component which acts as a view manager for the window and provides the window title functionality. After this it creates the toolbar using the create_toolbar() function and adds it to naviframe.

    -
    -static void
    -create_base_gui(appdata_s *ad)
    -{
    -   Elm_Object_Item *nf_it, *tabbar_it;
    -   // Window
    -   ad->win = elm_win_util_standard_add(PACKAGE, PACKAGE);
    -   elm_win_wm_desktop_layout_support_set(ad->win, EINA_TRUE);
    -   elm_win_autodel_set(ad->win, EINA_TRUE);
    -
    -   evas_object_smart_callback_add(ad->win, "delete,request", win_delete_request_cb, NULL);
    -
    -   // Conformant
    -   ad->conform = elm_conformant_add(ad->win);
    -   evas_object_size_hint_weight_set(ad->conform, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
    -   elm_win_resize_object_add(ad->win, ad->conform);
    -   evas_object_show(ad->conform);
    -
    -   // Naviframe
    -   ad->nf = elm_naviframe_add(ad->conform);
    -   elm_object_content_set(ad->conform, ad->nf);
    -   evas_object_show(ad->nf);
    -   nf_it = elm_naviframe_item_push(ad->nf, "UiLayout", NULL, NULL, NULL, "tabbar/icon/notitle");
    -
    -   // Tabbar
    -   ad->tabbar = create_toolbar(ad);
    -   elm_object_item_part_content_set(nf_it, "tabbar", ad->tabbar);
    -
    -   // Set the first view
    -   tabbar_it = elm_toolbar_first_item_get(ad->tabbar);
    -   elm_toolbar_item_selected_set(tabbar_it, EINA_TRUE);
    -
    -   // Show the window after the base GUI is set up
    -   evas_object_show(ad->win);
    -
    -   ecore_event_handler_add(ECORE_EVENT_KEY_DOWN, keydown_cb, NULL);
    -}
    -
    - -

    The create_toolbar() function creates the toolbar which is then added to the naviframe.

    -
    -static Evas_Object*
    -create_toolbar(appdata_s *ad)
    -{
    -   Evas_Object *tabbar;
    -
    -   tabbar = elm_toolbar_add(ad->nf);
    -   elm_object_style_set(tabbar, "tabbar");
    -   elm_toolbar_shrink_mode_set(tabbar, ELM_TOOLBAR_SHRINK_EXPAND);
    -   elm_toolbar_transverse_expanded_set(tabbar, EINA_TRUE);
    -
    -   elm_toolbar_item_append(tabbar, NULL, "Box", tabbar_item_cb, ad);
    -   elm_toolbar_item_append(tabbar, NULL, "Grid", tabbar_item_cb, ad);
    -   elm_toolbar_item_append(tabbar, NULL, "Table", tabbar_item_cb, ad);
    -
    -   return tabbar;
    -}
    -
    - -

    The following figure illustrates the UI Layout.

    - -

    Figure: UI Layout screen

    -

    UI Layout screen

    - -

    Adding Content to the Screen

    - -

    The create_box_view() function creates the screen using a recursive composition of the box layout.

    - -
    static Evas_Object*
    -create_box_view(Evas_Object *parent)
    -{
    -   Evas_Object *box, *box1, *box2, *box3;
    -
    -   box = elm_box_add(parent);
    -   elm_box_padding_set(box, 10, 10);
    -   evas_object_size_hint_weight_set(box, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
    -   evas_object_size_hint_align_set(box, EVAS_HINT_FILL, EVAS_HINT_FILL);
    -
    -   box1 = elm_box_add(box);
    -   elm_box_horizontal_set(box1, EINA_TRUE);
    -   elm_box_padding_set(box1, 8, 8);
    -   evas_object_size_hint_weight_set(box1, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
    -   evas_object_size_hint_align_set(box1, EVAS_HINT_FILL, EVAS_HINT_FILL);
    -   evas_object_show(box1);
    -
    -   box2 = elm_box_add(box);
    -   elm_box_padding_set(box2, 6, 6);
    -   evas_object_size_hint_weight_set(box2, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
    -   evas_object_size_hint_align_set(box2, EVAS_HINT_FILL, EVAS_HINT_FILL);
    -   evas_object_show(box2);
    -
    -   box3 = elm_box_add(box);
    -   elm_box_padding_set(box3, 5, 5);
    -   evas_object_size_hint_weight_set(box3, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
    -   evas_object_size_hint_align_set(box3, EVAS_HINT_FILL, EVAS_HINT_FILL);
    -   elm_box_homogeneous_set(box3, EINA_FALSE);
    -   evas_object_show(box3);
    -} 
    -
    - -

    Once the box layout is created, content or another box layout is added to the box. Box implements the size policy during the size calculation.

    - -
    // Add an item to the box
    -Evas_Object *item1 = create_content(box, "Item 1");
    -evas_object_size_hint_min_set(item1, 0, 40);
    -elm_box_pack_end(box, item1);
    -elm_box_pack_end(box, box1);
    -elm_box_pack_end(box, box3);
    -elm_box_pack_end(box, create_content(box, "Item 4"));
    -
    -// Add an item to the box1
    -elm_box_pack_end(box1, create_content(box1, "Item 2.1"));
    -elm_box_pack_end(box1, box2);
    -elm_box_pack_end(box1, create_content(box1, "Item 2.3"));
    -
    -// Add an item to the box2
    -elm_box_pack_end(box2, create_content(box2, "Item 2.2.1"));
    -elm_box_pack_end(box2, create_content(box2, "Item 2.2.2"));
    -
    -// Add an item to the box3
    -elm_box_pack_end(box3, create_content(box3, "Item 3.1"));
    -elm_box_pack_end(box3, create_content(box3, "Item 3.2"));
    -
    - -

    The create_table_view() function creates the screen by composing table layout with content and grid view.

    - -
    static Evas_Object*
    -create_table_view(Evas_Object *parent)
    -{
    -   Evas_Object *table, *item;
    -
    -   table = elm_table_add(parent);
    -   elm_table_padding_set(table, 10, 10);
    -   elm_table_homogeneous_set(table, EINA_TRUE);
    -   evas_object_size_hint_weight_set(table, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
    -   evas_object_size_hint_align_set(table, EVAS_HINT_FILL, EVAS_HINT_FILL);
    -
    -   item = create_content(table, "Item 1");
    -   elm_table_pack(table, item, 0, 0, 2, 1);
    -
    -   item = create_content(table, "Item 2");
    -   elm_table_pack(table, item, 2, 0, 1, 1);
    -
    -   item = create_content(table, "Item 3");
    -   elm_table_pack(table, item, 0, 1, 3, 1);
    -
    -   // Add a grid view item
    -   item = create_grid_view(table);
    -   evas_object_show(item);
    -   elm_table_pack(table, item, 0, 2, 3, 10);
    -
    -   return table;
    -}
    -
    - -

    The table layout can be used for freestyle layouting, and for standard layouts, such as lists and grids. It does not consider the size policy of the child item during size calculation.

    -

    The create_grid_view() function composes a screen using the grid layout and also uses box and table layout as a child item to pack inside a grid. It uses free style layouting, and during size evaluation of the child item, it does not take the size policy of the child item into consideration.

    - -
    static Evas_Object*
    -create_grid_view(Evas_Object *parent)
    -{
    -   Evas_Object *grid, *item;
    -
    -   grid = elm_grid_add(parent);
    -   evas_object_size_hint_weight_set(grid, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
    -   evas_object_size_hint_align_set(grid, EVAS_HINT_FILL, EVAS_HINT_FILL);
    -
    -   // Red background for the grid
    -   item = create_bg(grid, 255, 0, 0);
    -   elm_grid_pack(grid, item, 0, 0, 100, 100);
    -
    -   // Add the item to the grid
    -   item = create_content(grid, "Item1");
    -   elm_grid_pack(grid, item, 1, 1, 98, 98);
    -
    -   item = create_content(grid, "Item2");
    -   elm_grid_pack(grid, item, 2, 5, 20, 20);
    -
    -   item = create_content(grid, "Item3");
    -   elm_grid_pack(grid, item, 23, 5, 76, 94);
    -
    -   item = create_content(grid, "Item4");
    -   elm_grid_pack(grid, item, 2, 27, 20, 70);
    -
    -   // Black background for the box view item
    -   item = create_bg(grid, 40, 40, 40);
    -   elm_grid_pack(grid, item, 25, 10, 73, 87);
    -
    -   // Add the box view item to the grid
    -   item = create_box_view(grid);
    -   evas_object_show(item);
    -   elm_grid_pack(grid, item, 26, 11, 71, 85);
    -
    -   return grid;
    -}
    -
    - - - - - -
    - -Go to top - - - - - - - diff --git a/org.tizen.tutorials/html/native/ui/ui_tutorials_n.htm b/org.tizen.tutorials/html/native/ui/ui_tutorials_n.htm index 0687922..e427f65 100644 --- a/org.tizen.tutorials/html/native/ui/ui_tutorials_n.htm +++ b/org.tizen.tutorials/html/native/ui/ui_tutorials_n.htm @@ -33,20 +33,12 @@

    UI Framework: Creating the Application UI

    -

    The UI framework tutorials demonstrate how to create and manage the UI and its various elements and events in Tizen native applications:

    +

    The UI framework tutorials demonstrate how to create a visual outlook for your application to ensure the best possible user experience:

    + +

    For more information about implementing the UI for your application using the EFL features, see EFL.

    diff --git a/org.tizen.tutorials/html/scripts/common.js b/org.tizen.tutorials/html/scripts/common.js index 60250b6..d46479a 100644 --- a/org.tizen.tutorials/html/scripts/common.js +++ b/org.tizen.tutorials/html/scripts/common.js @@ -1,1752 +1,1752 @@ -$(document).ready(function(){ - $('#contents table').each(function(){ - if (!$(this).parent().hasClass('table')) { - $(this).wrap('
    '); - } - }); - - // Lnb Menu Initialize - if($('div#contents').find('.lnb').length){ - if($("ul li.events_news").size() > 0) { - $("ul.lnb").after("

    \"Samsung

    "); - } - initLnb(); - initScript(staticURL + "/js/fixednavbar.js", function(){}); - } - - //family site - if($('div#footer').find('dl#familySlider').length){ - fn_rollToEx('familySlider', 'sliderBanner', 1, true); - } - - // Svn Commit Test - - // Language Selection - if($('div#header').find('.util').length){ - var $lang = $('div#header').find('.util'); - $lang.find('a.lang').toggle(function(){ - $(this).css('background-image', $(this).css('background-image').replace('.gif','_.gif')).next('ul.language').show(); - },function(){ - $(this).css('background-image', $(this).css('background-image').replace('_.gif','.gif')).next('ul.language').hide(); - }); - - $lang.bind('mouseleave',function(){ - $(this).find('ul.language').hide(); - $lang.find('a.lang').css('background-image', $lang.find('a.lang').css('background-image').replace('_.gif','.gif')); - }); - - $lang.find('ul.language').children().last().on("keydown", function(e) { - if(e.which == 9 && e.shiftKey) { - return true; - } - - if(e.which == 9) { - e.preventDefault(); - $lang.find('ul.language').hide(); - $lang.find('a.lang').css('background-image', $lang.find('a.lang').css('background-image').replace('_.gif','.gif')); - setTimeout(function() { - $("#searchTop").focus(); - }, 1); - } - }); - } - - // Open the Sitemap - var $open = $('div#header').find('.bt-open'); - $open.bind('click',function(){ - var $self = $(this); - var $sitemap = $('div#wrapper').find('div#sitemap'); - //var source = $sitemap.is(':visible') ? $self.css('background-image').replace('_.gif','.gif') : $self.css('background-image').replace('.gif','_.gif'); - - if($sitemap.is(':visible')){ - var source = $self.css('background-image').replace('_.gif','.gif'); - //if($('body#main').length) $('#header .util').css('border-bottom','3px solid #e4e4e4'); - - $self.attr('title','open sitemap'); - }else{ - var source = $self.css('background-image').replace('.gif','_.gif'); - //if($('body#main').length) $('#header .util').css('border-bottom','3px solid #114196'); - - $self.attr('title','close sitemap'); - } - - $self.css('background-image',source); - $sitemap.slideToggle('fast'); - - $sitemap.find('ul').filter(':last').children().filter(':last').focusout(function(){ - var source = $self.css('background-image').replace('_.gif','.gif'); - $self.css('background-image',source); - $sitemap.slideToggle('fast'); - }); - - }); - - // Search Auto Complete - var $search = $('div#header').find('fieldset.search'); - var $searchList = $search.find('#topAutocomplete>ul'); - - if($search.length){ - $search.find('> input').each(function(){ - $(this).bind({ - keydown : function(e){ - - if(e.type=='keydown'&& $(this).val().length!=0){ - $search.find('#topAutocomplete').show(); - var hei = $searchList.outerHeight(); - if(hei>400){ - $searchList.css({'height':'400px','overflow-y':'auto'}); - } - } - if(e.keyCode==9){ - $search.unbind('focusout.search'); - } - if(e.keyCode==40){ - $search.find('#topAutocomplete>ul').children(':first').find('a').focus(); - //window.scrollTo(0,0); - } - }, - focusin : function(e){ - if($(this).val()==='Search'){ - $(this).val(''); - } - }, - focusout : function(e){ - if($(this).val().length==0) $(this).val('Search'); - } - }); - }); - - //$('#topAutocomplete>ul').children().find('a').bind('focusin',function(e){ - // if(e.keyCode==40){ - // $(this).parent().next().css('border','1px solid red').find('a').focus(); - // } - //}); - - $search.find('#topAutocomplete').bind('mouseleave',function(e){ - if($search.find('> input').val().length==0){ - $search.find('> input').val('Search'); - } - $search.find('#topAutocomplete').hide(); - }); - - $search.find('#topAutocomplete>ul').children().last().focusout(function(){ - $search.find('> input').val('Search'); - $search.find('#topAutocomplete').hide(); - - //$search.bind('focusout.search', function(){ - // $(this).find('> input').val('Search'); - // $(this).find('#topAutocomplete').hide(); - //}); - }); - } -}); - -// 비차단 동적 스크립트 로딩 -function initScript(url, callback){ - var script = document.createElement("script"); - script.type = "text/javascript"; - - if(script.readyState){ // 인터넷 익스플로러 - script.onreadystatechange = function(){ - if(script.readyState=="loaded" || script.readyState=="complete"){ - script.onreadystatechange = null; - callback(); - } - }; - }else{ // 다른 브라우저 - script.onload = function(){ - callback(); - }; - } - - script.src = url; - document.getElementsByTagName("head")[0].appendChild(script); -} - - -// lnb -function initLnb(){ - var sMenu = $('.lnb'); - var sItem = sMenu.find('>li'); - - sItem.each(function(){ - if($(this).find('a').hasClass('more')){ - if($(this).find('ul').is(":visible")) { - $('').insertAfter($(this).find('a').eq(0)); - } else { - $('').insertAfter($(this).find('a').eq(0)); - } - } - }); - - var setIcoArrText = function(obj) { - if(obj.next().is(":visible")) { - obj.text("close submenu"); - } else { - obj.text("open submenu"); - } - } - - sItem.find('.ico-arr').on("click", function() { - var $that = $(this); - var liBox = $that.parent(); - var ulBox = $that.next(); - - sItem.not(liBox).not(".on").find("a.more").next().next().hide(); - sItem.not(liBox).removeClass("active").find("a").removeClass("bov"); - - if(liBox.hasClass("on")) { - if(ulBox.is(":visible")) { - ulBox.hide(); - $that.addClass("ico-on"); - } else { - ulBox.show(); - $that.removeClass("ico-on"); - } - setIcoArrText($that); - return true; - } - - if(liBox.hasClass("active")) { - liBox.removeClass("active").find("a").eq(0).removeClass("bov"); - ulBox.hide(); - } else { - liBox.addClass("active").find("a").eq(0).addClass("bov"); - ulBox.show(); - } - setIcoArrText($that); - }); - - sItem.hover(function(){ - if($(this).hasClass('on')||$(this).hasClass('active')) return false; - $(this).find("a").eq(0).addClass("bov"); - },function(){ - if($(this).hasClass('on')||$(this).hasClass('active')) return false; - $(this).find("a").eq(0).removeClass("bov"); - - }); -} - -//footer rolling banner -function fn_rollToEx(container,objectId,step,auto){ - - // 롤링할 객체를 변수에 담아둔다. - var el = $('#'+container).find('#'+objectId); - var lastChild; - var speed = 3000; - var timer = 0; - var autoplay = false; - - el.data('prev', $('#'+container).find('.prev')); //이전버튼을 data()메서드를 사용하여 저장한다. - el.data('next', $('#'+container).find('.next')); //다음버튼을 data()메서드를 사용하여 저장한다. - el.data('size', el.children().outerWidth()); //롤링객체의 자식요소의 넓이를 저장한다. - el.data('len', el.children().length); //롤링객체의 전체요소 개수 - el.data('animating',false); - el.data('step', step); //매개변수로 받은 step을 저장한다. - el.data('autoStart', false); //매개변수로 받은 step을 저장한다. - - el.css('width',el.data('size')*el.data('len')); //롤링객체의 전체넓이 지정한다. - - if(arguments.length==4){ - el.data('autoStart', auto); - } - - if(el.data('autoStart')){ - if(timer==0){ - timer = setInterval(moveNextSlide, speed); - autoplay = true; - } - } - - el.bind({ - mouseenter:function(){ - if(!autoplay) return false; - - if(timer!=0 && el.data('autoStart')){ - clearInterval(timer); - timer=0; - } - }, - mouseleave:function(){ - if(!autoplay) return false; - - if(timer==0 && el.data('autoStart')){ - timer = setInterval(moveNextSlide, speed); - } - } - }); - - - //el에 첨부된 prev 데이타를 클릭이벤트에 바인드한다. - el.data('prev').bind({ - click:function(e){ - e.preventDefault(); - movePrevSlide(); - }, - mouseenter:function(){ - - $(this).find('img').addClass('btnOn'); - - if(!autoplay) return false; - - if(timer!=0 && el.data('autoStart')){ - clearInterval(timer); - timer=0; - } - }, - mouseleave:function(){ - - $(this).find('img').removeClass('btnOn'); - - if(!autoplay) return false; - - if(timer==0 && el.data('autoStart')){ - timer = setInterval(moveNextSlide, speed); - } - } - }); - - //el에 첨부된 next 데이타를 클릭이벤트에 바인드한다. - el.data('next').bind({ - click:function(e){ - e.preventDefault(); - moveNextSlide(); - }, - mouseenter:function(){ - - $(this).find('img').addClass('btnOn'); - - if(!autoplay) return false; - - if(timer!=0 && el.data('autoStart')){ - clearInterval(timer); - timer=0; - } - }, - mouseleave:function(){ - - $(this).find('img').removeClass('btnOn'); - - if(!autoplay) return false; - - if(timer==0 && el.data('autoStart')){ - timer = setInterval(moveNextSlide, speed); - } - } - }); - - function movePrevSlide(){ - if(!el.data('animating')){ - //전달된 step개수 만큼 롤링객체의 끝에서 요소를 선택하여 복사한후 변수에 저장한다. - var lastItem = el.children().eq(-(el.data('step')+1)).nextAll().clone(true); - lastItem.prependTo(el); //복사된 요소를 롤링객체의 앞에 붙여놓는다. - el.children().eq(-(el.data('step')+1)).nextAll().remove(); //step개수만큼 선택된 요소를 끝에서 제거한다 - el.css('left','-'+(el.data('size')*el.data('step'))+'px'); //롤링객체의 left위치값을 재설정한다. - - el.data('animating',true); //애니메이션 중복을 막기 위해 첨부된 animating 데이타를 true로 설정한다. - - el.animate({'left': '0px'},'normal',function(){ //롤링객체를 left:0만큼 애니메이션 시킨다. - el.data('animating',false); - }); - } - return false; - } - - function moveNextSlide(){ - if(!el.data('animating')){ - el.data('animating',true); - - el.animate({'left':'-'+(el.data('size')*el.data('step'))+'px'},'normal',function(){ //롤링객체를 첨부된 size와 step을 곱한 만큼 애니메이션 시킨다. - //전달된 step개수 만큼 롤링객체의 앞에서 요소를 선택하여 복사한후 변수에 저장한다. - var firstChild = el.children().filter(':lt('+el.data('step')+')').clone(true); - firstChild.appendTo(el); //복사된 요소를 롤링객체의 끝에 붙여놓는다. - el.children().filter(':lt('+el.data('step')+')').remove(); //step개수만큼 선택된 요소를 앞에서 제거한다 - el.css('left','0px'); ////롤링객체의 left위치값을 재설정한다. - - el.data('animating',false); - }); - } - return false; - } - -} - -function fn_slide(options){ - - var opts = jQuery.extend({},options); - - var $bt = $('#'+opts.container).find('#'+opts.bt).children(); //롤링버튼에 대한 선택자 - var $obj = $('#'+opts.container).find('#'+opts.obj); //objectId를 id로 갖는 롤링객체의 선택자 - var $prev = $('#'+opts.container).find('#'+opts.prev).hide(); //이전버튼에 대한 선택자 - var $next = $('#'+opts.container).find('#'+opts.next); //다음버튼에 대한 선택자 - var size = $obj.children().outerWidth(); //롤링객체의 각 이미지 넓이값 - var len = $obj.children().length; //롤링객체의 이미지 갯수 - var effect = false; //슬라이드효과를 위한 boolean변수 - var auto = false; - var current = 0; //현재 보여지는 이미지의 인덱스값을 저장하기 위한 변수 - var time; - - - $obj.css('width',size*len); //롤링객체의 전체넓이 지정 - effect = opts.effect; - auto = opts.auto; - - if(auto){ - time = setTimeout('slideShow()',3000); - } - - slideShow = function(){ - - if(current < len-1){ - current++; - }else{ - current=0; - } - - controllStatus(); - - moveControl('next'); - - time = setTimeout('slideShow()',3000); - } - - controllStatus = function(){ - //이미지의 인덱스값에 따라 이전,다음 버튼 활성여부 지정 - if(current>0||current=len-1){ - $prev.show(); - $next.hide(); - } - } - - moveControl = function(msg){ - if(opts.bt!=null){ - msg=='next'? $bt.eq(current-1).find('img').attr('src', $bt.eq(current-1).find('img').attr('src').replace('_.png','.png')) - :$bt.eq(current+1).find('img').attr('src', $bt.eq(current-1).find('img').attr('src').replace('_.png','.png')); //이전에 활성화된 롤링버튼을 비활성화 - $bt.eq(current).find('img').attr('src', $bt.eq(current).find('img').attr('src').replace('.png','_.png')); //현재 인덱스값을 가지는 롤링버튼을 활성화 - } - - if(effect!=true){ //action변수가 true가 아닐경우 슬라이드 효과없이 현재의 인덱스값을 갖는 이미지를 보여줌. - $obj.children().hide(); - $obj.children().eq(current).show(); - }else{ //action변수가 true일 경우 현재의 인덱스값을 갖는 이미지로 슬라이드됨 - $obj.animate({'left':'-'+size*current},'slow'); - } - } - - $obj.bind({ - mouseenter:function(){ - if(!auto) return false; - clearTimeout(time); - }, - mouseleave:function(){ - if(!auto) return false; - time = setTimeout('slideShow()',3000); - } - }); - - //롤링 버튼 클릭시 - $bt.bind({ - mouseenter:function(){ - if(!auto) return false; - clearTimeout(time); - }, - mouseleave:function(){ - if(!auto) return false; - time = setTimeout('slideShow()',3000); - }, - click:function(){ - var idx = $bt.index(this); //클릭한 롤링버튼의 인덱스값 저장 - - current = idx; //롤링버튼의 인덱스값을 이미지의 인덱스값으로 지정 - - controllStatus(); - - if(effect!=true){ //action변수가 true가 아닐경우 슬라이드 효과없이 현재의 인덱스값을 갖는 이미지를 보여줌. - $obj.children().hide(); - $obj.children().eq(current).show(); - }else{ //action변수가 true일 경우 현재의 인덱스값을 갖는 이미지로 슬라이드됨 - $obj.animate({'left':'-'+size*current},'slow'); - } - - // 모든 롤링 버튼을 비활성화 - $bt.each(function(){ - var source = $(this).find('img').attr('src').replace('_.png','.png'); - $(this).find('img').attr('src',source); - }); - - // 선택한 롤링버튼을 활성화 - var source = $(this).find('img').attr('src').replace('.png','_.png'); - $(this).find('img').attr('src',source); - - return false; - } - }); - - //이전 버튼 클릭시 - $prev.bind({ - mouseenter:function(){ - var source = $(this).find('img').attr('src').replace('.png','_.png'); - $(this).find('img').attr('src',source); - if(!auto) return false; - clearTimeout(time); - }, - mouseleave:function(){ - var source = $(this).find('img').attr('src').replace('_.png','.png'); - $(this).find('img').attr('src',source); - if(!auto) return false; - time = setTimeout('slideShow()',3000); - }, - click:function(){ - if(current==len-1) $next.show(); //이미지 인덱스값이 마지막이 아닐경우 비활성화된 다음버튼을 활성화 - current--; //이미지 인덱스값 1씩 감소 - - moveControl('prev'); - - if(current==0) $(this).hide(); //이미지 인덱스값이 0일 경우, 즉 현재 첫번째 이미지가 활성화될 경우 이전버튼을 비활성화 - - return false; - } - }); - - //다음 버튼 클릭시 - $next.bind({ - mouseenter:function(){ - var source = $(this).find('img').attr('src').replace('.png','_.png'); - $(this).find('img').attr('src',source); - if(!auto) return false; - clearTimeout(time); - }, - mouseleave:function(){ - var source = $(this).find('img').attr('src').replace('_.png','.png'); - $(this).find('img').attr('src',source); - if(!auto) return false; - time = setTimeout('slideShow()',3000); - }, - click:function(){ - current++; //이미지 인덱스값 1씩 증가 - - moveControl('next'); - - if(current>=len-1) $(this).hide(); //이미지인덱스값이 마지막일 경우, 즉 현재 마지막 이미지가 활성화될 경우 다음버튼을 비활성화 - if(current>0) $prev.show(); //이미지인덱스값이 0이 아닌경우 이전버튼 활성화 - - return false; - } - }); - -} - -// main rolling banner -function slideMotion1(){ - var $banner = $('#rolling .motionview'), - //$nav = $('#rolling ul.nav'), - banner = {prev:null, next:null}, - size = $banner.children().length; - index = 1, - speed = 3000, - timer = null, - auto = true, - width = parseInt(100/size), - rest = parseInt(100%size); - - var $nav = $('
    - -Go to top - - - - - - - \ No newline at end of file diff --git a/org.tizen.tutorials/html/web/tizen/communication/bluetooth_tutorial_w.htm b/org.tizen.tutorials/html/web/tizen/communication/bluetooth_tutorial_w.htm index 4a5fc50..e7e86f8 100644 --- a/org.tizen.tutorials/html/web/tizen/communication/bluetooth_tutorial_w.htm +++ b/org.tizen.tutorials/html/web/tizen/communication/bluetooth_tutorial_w.htm @@ -28,6 +28,18 @@
  • Creating a Bonding with a Bluetooth Device
  • Connecting to and Exchanging Data with a Bluetooth Device
  • Communicating with a Health Source Device
  • +
  • Bluetooth Low Energy + +
  • Related Info

    Task

    In the Bluetooth Chat task, we will walk through how to use the device as a Bluetooth server or client in a chat application.

    @@ -320,6 +344,378 @@ healthChannel.close();

    When the channel is disconnected, the onclose event handler in the BluetoothHealthChannelChangeCallback interface is called.

    +

    Discovering Bluetooth Low Energy Devices

    + +

    Learning how to search for remote devices is a basic Bluetooth management skill:

    +
      +
    1. Define a scan event handler by implementing the BluetoothLEScanCallback callback (in mobile and wearable applications). +

      The callback is invoked when a remote device has been detected.

      +
      +var callbacks = 
      +{
      +   onsuccess: function(device)
      +   {
      +      console.log("Found device: "  device.name  " ["  device.address  "]");
      +   }
      +};
      +
      + + + + + + + + + +
      Note
      To allow other Bluetooth devices to find your device, you must set the device to be visible through the system settings.
    2. + +
    3. Retrieve a BluetoothLEAdapter object (in mobile and wearable applications) with the getLEAdapter() method of the BluetoothManager interface (in mobile and wearable applications):

      +
      var adapter = tizen.bluetooth.getLEAdapter();
      +
    4. + +
    5. To search for remote devices, use the startScan() method of the BluetoothLEAdapter interface:

      +
      adapter.startScan(callbacks);
      +
    6. +
    7. When you find the right remote device or the user cancels the scanning, disable the scan using the stopScan() method of the BluetoothLEAdapter interface:

      +
      adapter.stopScan();
      +
    8. + +
    + +

    Managing the Advertising Options

    +

    The Bluetooth Low Energy technology allows a device to broadcast some information without a connection between devices. The Bluetooth Low Energy API provides methods to control this advertising (broadcasting).

    +

    Learning how to control what information is advertised by the device is a useful Bluetooth Low Energy skill:

    + +
      +
    1. Retrieve a BluetoothLEAdapter object (in mobile and wearable applications) with the getLEAdapter() method of the BluetoothManager interface (in mobile and wearable applications):

      +
      var adapter = tizen.bluetooth.getLEAdapter();
      +
    2. + +
    3. Set up options and start advertising with the startAdvertise() method of the BluetoothLEAdapter interface:

      +
      +var advertiseData = new tizen.BluetoothLEAdvertiseData(
      +{
      +   includeName: true,
      +   serviceuuids: ["180f"]  /* 180F is 16bit Battery Service UUID */
      +});
      +var connectable = true;
      +
      +adapter.startAdvertise(advertiseData, "ADVERTISE",
      +                       function onstate(state)
      +                       {
      +                          console.log("Advertising configured: " + state);
      +                       },
      +                       function(error)
      +                       {
      +                          console.log("startAdvertise() failed: " + error.message);
      +                       },
      +                       "LOW_LATENCY", connectable);
      +
      + + + + + + + + + +
      Note
      To learn how to make your mobile device visible to other Bluetooth devices, see Managing the Local Bluetooth Adapter.
      +
    4. +
    5. To disable the advertising, use the stopAdvertise() method of the BluetoothLEAdapter interface:

      +
      adapter.stopAdvertise();
      +
    6. +
    + +

    Connecting to a Bluetooth Low Energy Device

    + +

    Learning how to connect to other devices is a basic Bluetooth Low Energy management skill:

    +
      +
    1. Retrieve a BluetoothLEAdapter object (in mobile and wearable applications) with the getLEAdapter() method of the BluetoothManager interface (in mobile and wearable applications):

      +
      var adapter = tizen.bluetooth.getLEAdapter();
      +
    2. +
    3. Define success and error callbacks for the connect operation:

      +
      +function connectFail(error) 
      +{
      +   console.log("Failed to connect to device: " + e.message);
      +}
      +
      +function connectSuccess() 
      +{
      +   console.log("Connected to device");
      +}
      +
      +
    4. + +
    5. Define a callback for the scan operation that connects to a found device and stops the scan.

      +

      Within the callback request, establish a connection with the found device using the connect() method of the BluetoothLEDevice interface (in mobile and wearable applications):

      +
      +var remoteDevice = null;
      +
      +function onDeviceFound(device)
      +{
      +   if (remoteDevice === null) 
      +   {
      +      remoteDevice = device;
      +      console.log("Found device " + device.name + ". Connecting...");
      +
      +      device.connect(connectSuccess, connectFail);
      +   }
      +
      +   adapter.stopScan();
      +}
      +
      +
    6. + +
    7. When the callbacks are completed, initiate the Bluetooth Low Energy scan using the startScan() method of the BluetoothLEAdapter adapter:

      +
      adapter.startScan({onsuccess: onDeviceFound});
    8. + +
    9. When the connection to the remote device is no longer required, disconnect from the device by calling the disconnect() method of the BluetoothLEDevice interface:

      +
      remoteDevice.disconnect();
    10. + +
    + +

    Receiving Notifications on Connection State Changes

    + +

    Learning how to receive notifications whenever the device connection is established or lost is a useful Bluetooth management skill:

    +
      + +
    1. Retrieve a BluetoothLEAdapter object (in mobile and wearable applications) with the getLEAdapter() method of the BluetoothManager interface (in mobile and wearable applications):

      +
      var adapter = tizen.bluetooth.getLEAdapter();
      +
    2. +
    3. Define a connection state change listener by implementing the BluetoothLEConnectChangeCallback callback (in mobile and wearable applications):

      +
      +var connectionListener = 
      +{
      +   onconnected: function(device) 
      +   {
      +      console.log("Connected to the device: " + device.name + " [" + device.address + "]");
      +   },
      +   ondisconnected: function(device) 
      +   {
      +      console.log("Disconnected from the device " + device.name + " [" + device.address + "]");
      +   }
      +};
      +
      +
    4. + +
    5. Define a callback for the scan operation that connects to a found device and stops the scan.

      +

      Within the callback, register a connection state change listener using the addConnectStateChangeListener() method of the BluetoothLEDevice interface (in mobile and wearable applications):

      +
      +var remoteDevice = null;
      +var watchId;
      +
      +function onDeviceFound(device)
      +{
      +   if (remoteDevice === null) 
      +   {
      +      remoteDevice = device;
      +      console.log("Found device " + device.name + ". Connecting...");
      +
      +      watchId = remoteDevice.addConnectStateChangeListener(connectionListener);
      +
      +      remoteDevice.connect();
      +   }
      +
      +   adapter.stopScan();
      +}
      +
      +
    6. + +
    7. When the callbacks are completed, initiate the Bluetooth Low Energy scan:

      +
      adapter.startScan({onsuccess: onDeviceFound});
    8. + +
    9. When the notifications about the connection are no longer required, unregister the listener from the device by calling the removeConnectStateChangeListener() method of the BluetoothLEDevice interface:

      +
      remoteDevice.removeConnectStateChangeListener(watchId);
    10. +
    + +

    Retrieving Bluetooth GATT Services

    + +

    Learning how to retrieve a list of GATT services (Generic Attribute) provided by a remote device is basic Bluetooth Low Energy management skill:

    +
      + +
    1. Connect to a Bluetooth Low Energy device.
    2. +
    3. Define a connection state change listener by implementing the BluetoothLEConnectChangeCallback (in mobile and wearable applications):

      +
      +function showGATTService(service, indent)
      +{
      +   if (indent === undefined) 
      +   {
      +      indent = "";
      +   }
      +
      +   console.log(indent + "Service " + service.uuid + ". Has " + service.characteristics.length 
      +               + " characteristics and " + service.services.length + " sub-services.");
      +
      +   for (var i = 0; i < service.services.length; i++) 
      +   {
      +      showGATTService(service.services[i], indent + "   ");
      +   }
      +}
      +
      +
    4. +
    5. Retrieve a list of GATT service UUIDs from the uuids attribute of the BluetoothLEDevice interface (in mobile and wearable applications):

      +
      var serviceUUIDs = remoteDevice.uuids;
      +
    6. +
    7. Retrieve GATT service information using the getService() method of the BluetoothLEDevice interface for every service UUID:

      +
      +var i = 0, service = null;
      +
      +for (i; i < serviceUUIDs.length; i++) 
      +{
      +
      +   service = remoteDevice.getService(serviceUUIDs[i]);
      +
      +   showGATTService(service);
      +}
      +
    8. + +
    + +

    Accessing the Bluetooth GATT Characteristic Value

    + +

    Learning how to read and write a value of the Bluetooth characteristic is a useful Bluetooth Low Energy management skill:

    +
      + +
    1. Connect to a Bluetooth Low Energy device.
    2. +
    3. Retrieve a list of GATT service UUIDs from the uuids attribute of the BluetoothLEDevice interface (in mobile and wearable applications):

      +
      var serviceUUIDs = remoteDevice.uuids;
      +
    4. +
    5. Select a GATT service and use the getService() method of the BluetoothLEDevice interface to retrieve an object representing the service. In this example, the first service is used:

      +
      var gattService = remoteDevice.getService(serviceUUIDs[0]);
      +
    6. +
    7. Select an interesting characteristic from the characteristics attribute of the BluetoothGATTService interface (in mobile and wearable applications). In this example, the first characteristic is used:

      +
      var property = gattService.characteristics[0];
      +
    8. +
    9. Define a callback implementing the ReadValueSuccessCallback callback (in mobile and wearable applications), which receives the value of the characteristic:

      +
      +function readSuccess(value)
      +{
      +   console.log("Characteristic value: " + value);
      +}
      +
      +function readFail(error)
      +{
      +   console.log("readValue() failed: " + error);
      +}
      +
      +
    10. +
    11. To retrieve the GATT characteristic value, use the readValue() method of the BluetoothGATTCharacteristic interface (in mobile and wearable applications):

      +
      +if (!property.isReadable) 
      +{
      +   console.log("Property seems not to be readable. Attempting to read...");
      +}
      +property.readValue(readSuccess, readFail);
      +
    12. +
    13. To change the characteristic value, define callbacks and use the writeValue() method of the BluetoothGATTCharacteristic interface:

      +
      +function writeSuccess(value)
      +{
      +   console.log("Written");
      +}
      +
      +function writeFail(error)
      +{
      +   console.log("writeValue() failed: " + error);
      +}
      +
      +if (!property.isWritable) 
      +{
      +   console.log("Property seems not to be writable. Attempting to write...");
      +}
      +var newValue = [82];
      +
      +property.writeValue(newValue, writeSuccess, writeFail);
      +
      +
    14. +
    + +

    Receiving Notifications on Characteristic Value Changes

    + +

    Learning how to monitor a changes in a Bluetooth characteristic is a useful Bluetooth Low Energy management skill:

    +
      + +
    1. Connect to a Bluetooth Low Energy device.
    2. +
    3. Retrieve a list of GATT service UUIDs from the uuids attribute of the BluetoothLEDevice interface (in mobile and wearable applications):

      +
      var serviceUUIDs = remoteDevice.uuids;
      +
    4. +
    5. Select a GATT service and use the getService() method of the BluetoothLEDevice interface to retrieve an object representing the service. In this example, the first service is used:

      +
      var gattService = remoteDevice.getService(serviceUUIDs[0]);
      +
    6. +
    7. Select an interesting characteristic from the characteristics attribute of the BluetoothGATTService interface (in mobile and wearable applications). In this example, the first characteristic is used:

      +
      var property = gattService.characteristics[0];
      +
    8. +
    9. Define a callback implementing the ReadValueSuccessCallback callback (in mobile and wearable applications), which receives the value of the characteristic every time the value changes:

      +
      +function onValueChange(value)
      +{
      +   console.log("Characteristic value is now: " + value);
      +}
      +
      +
    10. + +
    11. Register a value change listener using the addValueChangeListener() method of the BluetoothGATTCharacteristic interface (in mobile and wearable applications):

      +
      var watchId = property.addValueChangeListener(onValueChange);
    12. + +
    13. When the notifications about the connection are no longer required, unregister the listener from the device by calling the removeValueChangeListener() method of the BluetoothGATTCharacteristic interface:

      +
      property.removeValueChangeListener(watchId);
    14. +
    + +

    Accessing the Bluetooth GATT Descriptor Value

    + +

    Learning how to read and write a value of the Bluetooth descriptor is a useful Bluetooth Low Energy management skill:

    +
      + +
    1. Connect to a Bluetooth Low Energy device.
    2. +
    3. Retrieve a list of GATT service UUIDs from the uuids attribute of the BluetoothLEDevice interface (in mobile and wearable applications):

      +
      var serviceUUIDs = remoteDevice.uuids;
      +
    4. +
    5. Select a GATT service and use the getService() method of the BluetoothLEDevice interface to retrieve an object representing the service. In this example, the first service is used:

      +
      var gattService = remoteDevice.getService(serviceUUIDs[0]);
      +
    6. +
    7. Select an interesting characteristic from the characteristics attribute of the BluetoothGATTService interface (in mobile and wearable applications). In this example, the first characteristic is used:

      +
      var characteristic = gattService.characteristics[0];
    8. +
    9. Select an interesting descriptor from the descriptors attribute of the BluetoothGATTCharacteristic interface (in mobile and wearable applications). In this example, the first descriptor is used:

      +
      var descriptor = characteristic.descriptors[0];
      +
    10. +
    11. Define a callback implementing the ReadValueSuccessCallback callback (in mobile and wearable applications), which receives the value of the descriptor:

      +
      +function readSuccess(value)
      +{
      +   console.log("Descriptor value: " + value);
      +}
      +
      +function readFail(error)
      +{
      +   console.log("readValue() failed: " + error);
      +}
      +
      +
    12. +
    13. To retrieve the GATT descriptor value, use the readValue() method of the BluetoothGATTDescriptor interface (in mobile and wearable applications):

      +
      +descriptor.readValue(readSuccess, readFail);
      +
    14. +
    15. To change the descriptor value, define callbacks and use the writeValue() method of the BluetoothGATTDescriptor interface:

      +
      +function writeSuccess(value)
      +{
      +   console.log("Written");
      +}
      +
      +function writeFail(error)
      +{
      +   console.log("writeValue() failed: " + error);
      +}
      +
      +var newValue = [3];
      +
      +descriptor.writeValue(newValue, writeSuccess, writeFail);
      +
      +
    16. +
    @@ -332,15 +728,15 @@ healthChannel.close(); - diff --git a/org.tizen.tutorials/html/web/tizen/communication/comm_tutorials_w.htm b/org.tizen.tutorials/html/web/tizen/communication/comm_tutorials_w.htm index 1137a13..a82293d 100644 --- a/org.tizen.tutorials/html/web/tizen/communication/comm_tutorials_w.htm +++ b/org.tizen.tutorials/html/web/tizen/communication/comm_tutorials_w.htm @@ -37,13 +37,12 @@

    The communication tutorials demonstrate how to use the following features in creating Tizen Web applications:

    -

    The following tutorials apply in mobile applications only:

    +

    The following tutorials apply in mobile applications only:

    @@ -60,15 +59,15 @@ - diff --git a/org.tizen.tutorials/html/web/tizen/communication/messaging_tutorial_w.htm b/org.tizen.tutorials/html/web/tizen/communication/messaging_tutorial_w.htm index 2224f9a..74d12bf 100644 --- a/org.tizen.tutorials/html/web/tizen/communication/messaging_tutorial_w.htm +++ b/org.tizen.tutorials/html/web/tizen/communication/messaging_tutorial_w.htm @@ -378,15 +378,15 @@ watchId = msgService.messageStorage.addMessagesChangeListener(messageChangeCallb - diff --git a/org.tizen.tutorials/html/web/tizen/communication/nfc_tutorial_w.htm b/org.tizen.tutorials/html/web/tizen/communication/nfc_tutorial_w.htm index 8754265..5362f58 100644 --- a/org.tizen.tutorials/html/web/tizen/communication/nfc_tutorial_w.htm +++ b/org.tizen.tutorials/html/web/tizen/communication/nfc_tutorial_w.htm @@ -377,15 +377,15 @@ adapter.cardEmulationMode = "OFF"; - diff --git a/org.tizen.tutorials/html/web/tizen/communication/push_tutorial_w.htm b/org.tizen.tutorials/html/web/tizen/communication/push_tutorial_w.htm index 4eb8064..979d00c 100644 --- a/org.tizen.tutorials/html/web/tizen/communication/push_tutorial_w.htm +++ b/org.tizen.tutorials/html/web/tizen/communication/push_tutorial_w.htm @@ -111,15 +111,15 @@ function notificationCallback(noti) - diff --git a/org.tizen.tutorials/html/web/tizen/communication/secure_element_tutorial_w.htm b/org.tizen.tutorials/html/web/tizen/communication/secure_element_tutorial_w.htm index c5f04ca..e8e40b5 100644 --- a/org.tizen.tutorials/html/web/tizen/communication/secure_element_tutorial_w.htm +++ b/org.tizen.tutorials/html/web/tizen/communication/secure_element_tutorial_w.htm @@ -198,15 +198,15 @@ reader.closeSessions(); - diff --git a/org.tizen.tutorials/html/web/tizen/multimedia/media_controller_tutorial_w.htm b/org.tizen.tutorials/html/web/tizen/multimedia/media_controller_tutorial_w.htm index d09b484..791e957 100644 --- a/org.tizen.tutorials/html/web/tizen/multimedia/media_controller_tutorial_w.htm +++ b/org.tizen.tutorials/html/web/tizen/multimedia/media_controller_tutorial_w.htm @@ -11,7 +11,7 @@ - Media Controller: Communicating between the Media Controller Server and Client + Media Controller: Communicating Between the Media Controller Server and Client @@ -38,7 +38,7 @@
    -

    Media Controller: Communicating between the Media Controller Server and Client

    +

    Media Controller: Communicating Between the Media Controller Server and Client

    This tutorial demonstrates how you can to develop server and client applications for controlling various media functions of the device.

    diff --git a/org.tizen.tutorials/html/web/tizen/multimedia/multimedia_tutorials_w.htm b/org.tizen.tutorials/html/web/tizen/multimedia/multimedia_tutorials_w.htm index 46efd76..fdde298 100644 --- a/org.tizen.tutorials/html/web/tizen/multimedia/multimedia_tutorials_w.htm +++ b/org.tizen.tutorials/html/web/tizen/multimedia/multimedia_tutorials_w.htm @@ -35,7 +35,7 @@

    The multimedia tutorials demonstrate how to use the following features in creating Tizen Web applications:

    diff --git a/org.tizen.tutorials/html/web/tizen/social/account_tutorial_w.htm b/org.tizen.tutorials/html/web/tizen/social/account_tutorial_w.htm index 1cc4809..6b6f6c5 100644 --- a/org.tizen.tutorials/html/web/tizen/social/account_tutorial_w.htm +++ b/org.tizen.tutorials/html/web/tizen/social/account_tutorial_w.htm @@ -1,317 +1,317 @@ - - - - - - - - - - - - - Account: Managing Accounts and Account Information - - - - - -
    - -

    Account: Managing Accounts and Account Information

    - -

    This tutorial demonstrates how you can manage accounts and retrieve account information.

    - - - - - - - - - - -
    Note
    This feature is supported in mobile applications only.
    - -

    Warm-up

    -

    Become familiar with the Account API basics by learning about:

    - - -

    Retrieving Accounts

    - - -

    Learning how to retrieve account information enables you to include account support into your applications:

    - -
      -
    • To retrieve information about all available accounts, use the getAccounts() method of the AccountManager interface: - -
      function getAccountsSuccess(accounts)
      -{
      -   for (var i = 0; i < accounts.length; i++)
      -   {
      -      /* Use the retrieved accounts */
      -   }
      -}
      -function getAccountsError(error)
      -{
      -   console.log('Error: ' + error.message);
      -}
      -tizen.account.getAccounts(getAccountsSuccess, getAccountsError);
      -
    • - -
    • If you already know the ID of the account, you can get the Account object using the getAccount() method of the AccountManager interface: - -
      var account = tizen.account.getAccount(my_account_id);
      -
    • -
    - -

    Retrieving Providers

    - -

    To create accounts, you must learn how to get access to account providers:

    - - - - - - - - - - -
    Note
    To perform these operations, your application needs the http://tizen.org/privilege/account.read privilege.
    - -
      -
    • Get a specific account provider with the given application ID using the getProviders() method of the ApplicationManager interface. -

      If the current application is an account provider application (meaning that it contains the <tizen:account> element in its config.xml file), you can use the current application ID. Otherwise, get the ID of the current application using the getCurrentApplication() method of the ApplicationManager interface:

      - -
      var appId = tizen.application.getCurrentApplication().appInfo.id;
      -var provider = tizen.account.getProvider(appId);
      -
    • -
    • To get information about all available account providers, use the getProviders() method of the AccountManager interface: - -
      function getProvidersSuccess(providers)
      -{
      -   /* Providers is an array whose members are providers with contact capability */
      -}
      -function getProvidersError(error)
      -{
      -   console.log('Error: ' + error.message);
      -}
      -
      -tizen.account.getProviders(getProvidersSuccess, getProvidersError, "http://tizen.org/account/capability/contact");
      -
    • -
    - -

    Managing Accounts

    - -

    Creating, adding, updating, and deleting accounts is a basic account management skill:

    - - - - - - - - - - -
    Note
    To perform these operations, your application needs the http://tizen.org/privilege/account.write privilege and must be the account provider.
    - -
      -
    1. To create an account, first get an account provider. If your application is an account provider application (meaning that it contains the <tizen:account> element in its config.xml file), use the getProvider() method: - -
      var appId = tizen.application.getCurrentApplication().appInfo.id;
      -var accountProvider = tizen.account.getProvider(appId);
      -
    2. -
    3. Create an instance of the Account interface: - -
      var account = new tizen.Account(accountProvider, {userName: 'admin', iconUri: 'path/to/icon.jpg'});
      -
    4. -
    5. Add the account to the account database: - -
      tizen.account.add(account);
      -
    6. -
    7. To update the account information, change the attributes of the Account object for the relevant account: - -
      account.userName = 'new username';
      -
    8. -
    9. To save the changed values, use the update() method of the AccountManager interface: - -
      tizen.account.update(account);
      -
    10. - -
    11. To remove the account from the system, use the remove() method of the AccountManager interface, providing the account ID: - -
      tizen.account.remove(account.id);
      -
    12. -
    - -

    Receiving Notifications on Account Changes

    - -

    Learning how to register change listeners enables you to synchronize the view of your application with the changes in the account database:

    - - - - - - - - - - -
    Note
    To perform these operations, your application needs the http://tizen.org/privilege/account.read privilege.
    - -
      -
    1. Define a listener implementing the AccountChangeCallback interface: - -
      var accountChangeListener =
      -{
      -   onadded: function(account)
      -   {
      -      /* Called when an account is added */
      -   },
      -   onremoved: function(accountId)
      -   {
      -      /* Called when an account is removed */
      -   },
      -   onupdated: function(account)
      -   {
      -      /* Called when a registered account is changed */
      -   }
      -};
      -
    2. -
    3. Register the account listener using the addAccountListener() method of the AccountManager interface to start receiving notifications about changes: - -
      var watchId = tizen.account.addAccountListener(accountChangeListener);
      -
    4. -
    5. When notifications are no longer required, unregister the listener using the removeAccountListener() method of the AccountManager interface: - -
      tizen.account.removeAccountListener(watchId);
      -
    6. -
    -

    Managing Extended Account Data

    - -

    Learning how to manage extended data for an account enables you to include account support into your applications:

    - -
      -
    1. Retrieve the account object.
    2. -
    3. Manage the extended data for the retrieved account: -
      • To set extended data: -

        Set the additional information with the setExtendedData() method:

        - -
        var key = 'nickname';
        -var value = 'nickname of anonymous user';
        -account.setExtendedData(key, value);
        - - - - - - - - - - -
        Note
        To perform this operation, your application needs the http://tizen.org/privilege/account.write privilege.
        -

        To overwrite the previous data value, set a new value with the same key:

        - -
        account.setExtendedData(key, 'nickname updated');
        -
      • - -
      • To get extended data: -
        • To retrieve extended data value for a specific key, use the getExtendedData() method: - -
          var key = 'accessToken';
          -var value = account.getExtendedData(key); 
          - - - - - - - - - - -
          Note
          To perform this operation, your application needs the http://tizen.org/privilege/account.read privilege.
          -
        • -
        • To retrieve all extended data for an account, use the asynchronous version of the getExtendedData() method. The success callback contains an array of the extended data key-value pairs. - -
          account.getExtendedData(function(extendedData)
          -                        {
          -                           for (var i = 0; i < extendedData.length; i++)
          -                           {
          -                              var key = extendedData.key;
          -                              var value = extendedData.value;
          -                              console.log(key + " : " + value);
          -                           }
          -                        },
          -                        function(e)
          -                        {
          -                           console.log("Error : " + e.message);
          -                        });
          - -
    4. - -
    - - - - - -
    - -Go to top - - - - - - + + + + + + + + + + + + + Account: Managing Accounts and Account Information + + + + + +
    + +

    Account: Managing Accounts and Account Information

    + +

    This tutorial demonstrates how you can manage accounts and retrieve account information.

    + + + + + + + + + + +
    Note
    This feature is supported in mobile applications only.
    + +

    Warm-up

    +

    Become familiar with the Account API basics by learning about:

    + + +

    Retrieving Accounts

    + + +

    Learning how to retrieve account information enables you to include account support into your applications:

    + +
      +
    • To retrieve information about all available accounts, use the getAccounts() method of the AccountManager interface: + +
      function getAccountsSuccess(accounts)
      +{
      +   for (var i = 0; i < accounts.length; i++)
      +   {
      +      /* Use the retrieved accounts */
      +   }
      +}
      +function getAccountsError(error)
      +{
      +   console.log('Error: ' + error.message);
      +}
      +tizen.account.getAccounts(getAccountsSuccess, getAccountsError);
      +
    • + +
    • If you already know the ID of the account, you can get the Account object using the getAccount() method of the AccountManager interface: + +
      var account = tizen.account.getAccount(my_account_id);
      +
    • +
    + +

    Retrieving Providers

    + +

    To create accounts, you must learn how to get access to account providers:

    + + + + + + + + + + +
    Note
    To perform these operations, your application needs the http://tizen.org/privilege/account.read privilege.
    + +
      +
    • Get a specific account provider with the given application ID using the getProviders() method of the ApplicationManager interface. +

      If the current application is an account provider application (meaning that it contains the <tizen:account> element in its config.xml file), you can use the current application ID. Otherwise, get the ID of the current application using the getCurrentApplication() method of the ApplicationManager interface:

      + +
      var appId = tizen.application.getCurrentApplication().appInfo.id;
      +var provider = tizen.account.getProvider(appId);
      +
    • +
    • To get information about all available account providers, use the getProviders() method of the AccountManager interface: + +
      function getProvidersSuccess(providers)
      +{
      +   /* Providers is an array whose members are providers with contact capability */
      +}
      +function getProvidersError(error)
      +{
      +   console.log('Error: ' + error.message);
      +}
      +
      +tizen.account.getProviders(getProvidersSuccess, getProvidersError, "http://tizen.org/account/capability/contact");
      +
    • +
    + +

    Managing Accounts

    + +

    Creating, adding, updating, and deleting accounts is a basic account management skill:

    + + + + + + + + + + +
    Note
    To perform these operations, your application needs the http://tizen.org/privilege/account.write privilege and must be the account provider.
    + +
      +
    1. To create an account, first get an account provider. If your application is an account provider application (meaning that it contains the <tizen:account> element in its config.xml file), use the getProvider() method: + +
      var appId = tizen.application.getCurrentApplication().appInfo.id;
      +var accountProvider = tizen.account.getProvider(appId);
      +
    2. +
    3. Create an instance of the Account interface: + +
      var account = new tizen.Account(accountProvider, {userName: 'admin', iconUri: 'path/to/icon.jpg'});
      +
    4. +
    5. Add the account to the account database: + +
      tizen.account.add(account);
      +
    6. +
    7. To update the account information, change the attributes of the Account object for the relevant account: + +
      account.userName = 'new username';
      +
    8. +
    9. To save the changed values, use the update() method of the AccountManager interface: + +
      tizen.account.update(account);
      +
    10. + +
    11. To remove the account from the system, use the remove() method of the AccountManager interface, providing the account ID: + +
      tizen.account.remove(account.id);
      +
    12. +
    + +

    Receiving Notifications on Account Changes

    + +

    Learning how to register change listeners enables you to synchronize the view of your application with the changes in the account database:

    + + + + + + + + + + +
    Note
    To perform these operations, your application needs the http://tizen.org/privilege/account.read privilege.
    + +
      +
    1. Define a listener implementing the AccountChangeCallback interface: + +
      var accountChangeListener =
      +{
      +   onadded: function(account)
      +   {
      +      /* Called when an account is added */
      +   },
      +   onremoved: function(accountId)
      +   {
      +      /* Called when an account is removed */
      +   },
      +   onupdated: function(account)
      +   {
      +      /* Called when a registered account is changed */
      +   }
      +};
      +
    2. +
    3. Register the account listener using the addAccountListener() method of the AccountManager interface to start receiving notifications about changes: + +
      var watchId = tizen.account.addAccountListener(accountChangeListener);
      +
    4. +
    5. When notifications are no longer required, unregister the listener using the removeAccountListener() method of the AccountManager interface: + +
      tizen.account.removeAccountListener(watchId);
      +
    6. +
    +

    Managing Extended Account Data

    + +

    Learning how to manage extended data for an account enables you to include account support into your applications:

    + +
      +
    1. Retrieve the account object.
    2. +
    3. Manage the extended data for the retrieved account: +
      • To set extended data: +

        Set the additional information with the setExtendedData() method:

        + +
        var key = 'nickname';
        +var value = 'nickname of anonymous user';
        +account.setExtendedData(key, value);
        + + + + + + + + + + +
        Note
        To perform this operation, your application needs the http://tizen.org/privilege/account.write privilege.
        +

        To overwrite the previous data value, set a new value with the same key:

        + +
        account.setExtendedData(key, 'nickname updated');
        +
      • + +
      • To get extended data: +
        • To retrieve extended data value for a specific key, use the getExtendedData() method: + +
          var key = 'accessToken';
          +var value = account.getExtendedData(key); 
          + + + + + + + + + + +
          Note
          To perform this operation, your application needs the http://tizen.org/privilege/account.read privilege.
          +
        • +
        • To retrieve all extended data for an account, use the asynchronous version of the getExtendedData() method. The success callback contains an array of the extended data key-value pairs. + +
          account.getExtendedData(function(extendedData)
          +                        {
          +                           for (var i = 0; i < extendedData.length; i++)
          +                           {
          +                              var key = extendedData.key;
          +                              var value = extendedData.value;
          +                              console.log(key + " : " + value);
          +                           }
          +                        },
          +                        function(e)
          +                        {
          +                           console.log("Error : " + e.message);
          +                        });
          + +
    4. + +
    + + + + + +
    + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.tutorials/html/web/tizen/social/bookmark_tutorial_w.htm b/org.tizen.tutorials/html/web/tizen/social/bookmark_tutorial_w.htm index e093ffc..483c1e0 100644 --- a/org.tizen.tutorials/html/web/tizen/social/bookmark_tutorial_w.htm +++ b/org.tizen.tutorials/html/web/tizen/social/bookmark_tutorial_w.htm @@ -1,145 +1,145 @@ - - - - - - - - - - - - - Bookmark: Managing Web Browser Bookmarks - - - - - -
    - -

    Bookmark: Managing Web Browser Bookmarks

    - -

    This tutorial demonstrates how you can manage Tizen Web browser bookmarks on the device.

    - - - - - - - - - - -
    Note
    This feature is supported in mobile applications only.
    - -

    Warm-up

    -

    Become familiar with the Bookmark API basics by learning about:

    - - -

    Creating Bookmark Folders and Items

    - -

    To create engaging applications with bookmark-related features, you must learn how to add bookmark folders and items to the root bookmark folder and subfolders:

    -
      -
    • To add a folder and a bookmark to the root bookmark folder: -
        -
      1. Create an instance of the BookmarkFolder interface by specifying the bookmark folder name:

        -var folder1 = new tizen.BookmarkFolder("folder1");
        -
      2. -
      3. Create an instance of the BookmarkItem interface by specifying the bookmark item name and URL:

        -var tizen = new tizen.BookmarkItem("tizen", "https://www.tizen.org");
      4. -
      5. Use the add() method of the BookmarkManager interface to add both a bookmark folder and a bookmark to the root bookmark folder:

        tizen.bookmark.add(folder1);
        -tizen.bookmark.add(tizen);
        -
      6. -
    • -
    • To add a folder and a bookmark to a subfolder: -
        -
      1. Create an instance of the BookmarkFolder and BookmarkItem interface:

        -var folder2 = new tizen.BookmarkFolder("folder2");
        -var developerTizen = new tizen.BookmarkItem("developerTizen", "https://developer.tizen.org");
        -
      2. -
      3. Use the add() method to add a folder and a bookmark to a bookmark subfolder by specifying the parent bookmark folder name:

        -tizen.bookmark.add(folder2, folder1);
        -tizen.bookmark.add(developerTizen, folder1);
        -
        -

        As a result of the code snippet above, the folder1 folder contains the developerTizen bookmark and the folder2 subfolder.

      4. -
    • -
    - - -

    Deleting Bookmarks

    - -

    To create engaging applications with bookmark-related features, you must learn how to delete bookmarks:

    -
      -
    1. To remove a bookmark item, use the remove() method of the BookmarkManager interface and specify the bookmark item:

      -tizen.bookmark.remove(tizen);
      -
    2. -
    3. To remove a bookmark folder, use the remove() method and specify the bookmark folder:

      -tizen.bookmark.remove(folder2);
    4. -
    5. To remove all the bookmark folders and items from the bookmarks list, use the remove() method without specifying a parameter:

      tizen.bookmark.remove();
      -
    6. -
    - - -

    Retrieving the Bookmark List

    - - -

    To create engaging applications with bookmark-related features, you must learn how to retrieve the bookmarks:

    -
      -
    1. To retrieve bookmarks only from the root bookmark folder, use the get() method of the BookmarkManager interface without specifying any parameter:

      -tizen.bookmark.get();
      -
    2. -
    3. To retrieve bookmarks from the root bookmark folder and subfolders, use the get() method and set the recursive parameter as true:

      -tizen.bookmark.get(null, true);
    4. -
    5. To retrieve bookmarks only from a specific bookmark folder excluding its subfolders, use the get() method and specify the bookmark folder name:

      tizen.bookmark.get(folder1);
      -
    6. -
    7. To retrieve bookmarks from a specific bookmark folder and its subfolders, use the get() method, specifying the bookmark folder name and setting the recursive parameter as true:

      tizen.bookmark.get(folder1, true);
      -
    8. -
    - - - - - -
    - -Go to top - - - - - - + + + + + + + + + + + + + Bookmark: Managing Web Browser Bookmarks + + + + + +
    + +

    Bookmark: Managing Web Browser Bookmarks

    + +

    This tutorial demonstrates how you can manage Tizen Web browser bookmarks on the device.

    + + + + + + + + + + +
    Note
    This feature is supported in mobile applications only.
    + +

    Warm-up

    +

    Become familiar with the Bookmark API basics by learning about:

    + + +

    Creating Bookmark Folders and Items

    + +

    To create engaging applications with bookmark-related features, you must learn how to add bookmark folders and items to the root bookmark folder and subfolders:

    +
      +
    • To add a folder and a bookmark to the root bookmark folder: +
        +
      1. Create an instance of the BookmarkFolder interface by specifying the bookmark folder name:

        +var folder1 = new tizen.BookmarkFolder("folder1");
        +
      2. +
      3. Create an instance of the BookmarkItem interface by specifying the bookmark item name and URL:

        +var tizen = new tizen.BookmarkItem("tizen", "https://www.tizen.org");
      4. +
      5. Use the add() method of the BookmarkManager interface to add both a bookmark folder and a bookmark to the root bookmark folder:

        tizen.bookmark.add(folder1);
        +tizen.bookmark.add(tizen);
        +
      6. +
    • +
    • To add a folder and a bookmark to a subfolder: +
        +
      1. Create an instance of the BookmarkFolder and BookmarkItem interface:

        +var folder2 = new tizen.BookmarkFolder("folder2");
        +var developerTizen = new tizen.BookmarkItem("developerTizen", "https://developer.tizen.org");
        +
      2. +
      3. Use the add() method to add a folder and a bookmark to a bookmark subfolder by specifying the parent bookmark folder name:

        +tizen.bookmark.add(folder2, folder1);
        +tizen.bookmark.add(developerTizen, folder1);
        +
        +

        As a result of the code snippet above, the folder1 folder contains the developerTizen bookmark and the folder2 subfolder.

      4. +
    • +
    + + +

    Deleting Bookmarks

    + +

    To create engaging applications with bookmark-related features, you must learn how to delete bookmarks:

    +
      +
    1. To remove a bookmark item, use the remove() method of the BookmarkManager interface and specify the bookmark item:

      +tizen.bookmark.remove(tizen);
      +
    2. +
    3. To remove a bookmark folder, use the remove() method and specify the bookmark folder:

      +tizen.bookmark.remove(folder2);
    4. +
    5. To remove all the bookmark folders and items from the bookmarks list, use the remove() method without specifying a parameter:

      tizen.bookmark.remove();
      +
    6. +
    + + +

    Retrieving the Bookmark List

    + + +

    To create engaging applications with bookmark-related features, you must learn how to retrieve the bookmarks:

    +
      +
    1. To retrieve bookmarks only from the root bookmark folder, use the get() method of the BookmarkManager interface without specifying any parameter:

      +tizen.bookmark.get();
      +
    2. +
    3. To retrieve bookmarks from the root bookmark folder and subfolders, use the get() method and set the recursive parameter as true:

      +tizen.bookmark.get(null, true);
    4. +
    5. To retrieve bookmarks only from a specific bookmark folder excluding its subfolders, use the get() method and specify the bookmark folder name:

      tizen.bookmark.get(folder1);
      +
    6. +
    7. To retrieve bookmarks from a specific bookmark folder and its subfolders, use the get() method, specifying the bookmark folder name and setting the recursive parameter as true:

      tizen.bookmark.get(folder1, true);
      +
    8. +
    + + + + + +
    + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.tutorials/html/web/tizen/social/calendar_tutorial_w.htm b/org.tizen.tutorials/html/web/tizen/social/calendar_tutorial_w.htm index 49a5d74..36ef391 100644 --- a/org.tizen.tutorials/html/web/tizen/social/calendar_tutorial_w.htm +++ b/org.tizen.tutorials/html/web/tizen/social/calendar_tutorial_w.htm @@ -1,616 +1,616 @@ - - - - - - - - - - - - - Calendar: Managing Calendars and Calendar Events - - - - - -
    - -

    Calendar: Managing Calendars and Calendar Events

    - -

    This tutorial demonstrates how you can manage calendars in the device to access, modify, add, and remove calendar items within a specified calendar on the device.

    - - - - - - - - - - -
    Note
    This feature is supported in mobile applications only.
    - -

    Warm-up

    -

    Become familiar with the Calendar API basics by learning about:

    - -

    Task

    -

    In the Event Manager task, we will walk through how to manage calendar events in your application.

    - -

    Creating a Calendar

    - -

    Creating a new calendar is a basic calendar management skill:

    - - - - - - - - - - -
    Note
    The created calendar is associated with a specified account. Therefore, you must retrieve the account before creating a new calendar.
    -
      -
    1. Declare a variable to store the created calendar: -
      var myCalendar = null;
      -
    2. -
    3. Define a success callback for the getAccounts() method. The callback receives a list of Account objects. Use the first account ID to construct a new Calendar object. -

      Add the new calendar to the system using the addCalendar() method of the CalendarManager interface:

      -
      function getAccountsSuccess(accounts)
      -{
      -   var account = accounts[0];
      -   if (account)
      -   {
      -      /* New calendar can be created and added */
      -      myCalendar = new tizen.Calendar(account.id, "remote calendar", "TASK");
      -      tizen.calendar.addCalendar(myCalendar);
      -      console.log("New calendar created with ID=" + myCalendar.id);
      -   }
      -}
    4. -
    5. To retrieve available accounts, use the getAccounts() method. The following method call invokes the getAccountsSuccess event handler defined above: -
      tizen.account.getAccounts(getAccountsSuccess, function(err));
      -
    6. -
    - - -

    Adding Events to a Calendar

    - - -

    To create engaging applications with various calendar features, you must learn to add events to calendars:

    -
      -
    1. Retrieve the default system calendar using the getDefaultCalendar() method of the CalendarManager interface.

      With the parameter, specify the calendar type as an event.

      -var calendar = tizen.calendar.getDefaultCalendar("EVENT");
      -
    2. -
    3. Create a CalendarEvent object and define the event properties:

      var ev = new tizen.CalendarEvent
      -({
      -   description:"HTML5 Introduction",
      -   summary:"HTML5 Webinar",
      -   startDate: new tizen.TZDate(2011, 3, 30, 10, 0),
      -   duration: new tizen.TimeDuration(1, "HOURS"),
      -   location:"Huesca",
      -
    4. -
    5. To make a recurring event, define a recurrence rule.

      In this example, the event repeats once a day for 3 days.

      -   recurrenceRule: new tizen.CalendarRecurrenceRule("DAILY", {occurrenceCount: 3})
      -});
      -
    6. -
    7. To set up an alarm to remind the user about the event, create an alarm with the CalendarAlarm interface, and add the alarm to the event:

      -/* Alarm is triggered with sound 30 minutes before the event start time */
      -var alarm = new tizen.CalendarAlarm(new tizen.TimeDuration(30, "MINS"), "SOUND");
      -
      -ev.alarms = [alarm];
      -
    8. -
    9. Add the CalendarEvent object to the default calendar with the add() method of the Calendar object.

      calendar.add(ev);  /* ev.id attribute is generated */
    10. -
    - -

    Adding Events to a Calendar in the Batch Mode

    - - -

    To create engaging applications with various calendar features, you must learn to add events to calendars in the batch mode:

    -
      -
    1. Retrieve the default system calendar using the getDefaultCalendar() method of the CalendarManager interface:

      -var calendar = tizen.calendar.getDefaultCalendar("EVENT");
      -
    2. -
    3. Define the items to be added as an array:

      -var ev = new tizen.CalendarEvent
      -({
      -   description:"HTML5 Introduction",
      -   summary:"HTML5 Webinar",
      -   startDate: new tizen.TZDate(2011, 3, 30, 10, 0),
      -   duration: new tizen.TimeDuration(1, "HOURS"),
      -   location:"Huesca"
      -});
      -
      - - - - - - - - - -
      Note
      To keep the example as simple as possible, the array above includes only 1 event.
    4. -
    5. Use the addBatch() method of the Calendar object to add the events in the array to the calendar:

      -calendar.addBatch([ev]);
      -
      - - - - - - - - - -
      Note
      The addBatch() method is asynchronous, and its callbacks must be used to react to the success or failure of the operation.
      -
    6. -
    - -

    Managing a Single Calendar Event

    - -

    To create engaging applications with various calendar features, you must learn to manage a single calendar event:

    -
      -
    1. Retrieve the default system calendar using the getDefaultCalendar() method of the CalendarManager interface.

      With the parameter, specify the calendar type as event.

      -var myCalendar = tizen.calendar.getDefaultCalendar("EVENT");
      -
    2. -
    3. Retrieve all events stored in the calendar by using the find() method of the Calendar object:

      -myCalendar.find(eventSearchSuccessCallback);
      - - - - - - - - - -
      Note
      To retrieve a specific set of events, you can specify a filter and sorting order for the search operation through the filter and sortMode parameters (for attributes supported in the filter, see Calendar Filter Attributes).

      In this example, all the events are retrieved because no filter is used.

    4. -
    5. Update or delete the found item inside the eventSearchSuccessCallback() event handler.

      In this example, the description parameter of the first event is changed and the event is updated in the calendar using the update() method. The second event is deleted using the remove() method.

      /* Define the event success callback */
      -function eventSearchSuccessCallback(events)
      -{
      -   /* Update the first existing event */
      -   events[0].description = "New Description";
      -   myCalendar.update(events[0]);
      -
      -   /* Delete the second existing event */
      -   myCalendar.remove(events[1].id);
      -}
    6. -
    - -

    Updating Recurring Calendar Events

    - -

    To create engaging applications with various calendar features, you must learn to update recurring calendar events:

    -
      -
    1. Retrieve the default system calendar using the getDefaultCalendar() method of the CalendarManager interface.

      -

      Retrieve the calendar event using the get() method by specifying the event ID.

      -var calendar = tizen.calendar.getDefaultCalendar("EVENT");
      -var event = calendar.get(evId);
      -
    2. -
    3. Expand the recurring event to get its instances by using the expandRecurrence() method of the CalendarEvent object:
      -event.expandRecurrence(new tizen.TZDate(2012, 2, 1), new tizen.TZDate(2012, 2, 15),
      -                       eventExpandSuccessCB);

      The expanded event instances have their own id.uid and id.rid attributes, where the id.uid attribute is the same for all instances.

    4. -
    5. Update a single instance of the expanded recurring event.

      In case of recurring events, you can use the second parameter of the update() method to determine whether a single instance or all occurrences of the event are updated. If the parameter is set to true, all instances are updated, while if it is set to false, only the indicated instance of the recurring event is updated (based on the id.rid attribute).

      In this example, the second instance of the event is updated.

      -/* Success event handler */
      -function eventExpandSuccessCB(events)
      -{
      -   events[1].summary = 'updated summary';
      -   calendar.update(events[1], false);
      -}
      -
    6. -
    - -

    Managing Multiple Calendar Events in the Batch Mode

    - -

    To create engaging applications with various calendar features, you must learn to manage multiple calendar events in the batch mode:

    -
      -
    1. Retrieve the default system calendar using the getDefaultCalendar() method of the CalendarManager interface.

      With the parameter, specify the calendar type as event.

      -var myCalendar = tizen.calendar.getDefaultCalendar("EVENT");
      -
    2. -
    3. Retrieve all events stored in the calendar by using the find() method of the Calendar object:

      -myCalendar.find(eventSearchSuccessCallback, errorCallback);
      - - - - - - - - - -
      Note
      To retrieve a specific set of events, you can specify a filter and sorting order for the search operation through the filter and sortMode parameters (for attributes supported in the filter, see Calendar Filter Attributes).

      In this example, all the events are retrieved because no filter is used.

    4. - -
    5. To update events: -
        -
      1. Define the items to be updated in the success event handler of the find() method:

        -function eventSearchSuccessCallback(events)
        -{
        -   events[0].description = "New Description 1";
        -   events[1].description = "New Description 2";
        -
      2. -
      3. Use the updateBatch() method to update multiple calendar items asynchronously:

        -   /* Update the first 2 existing events */
        -   myCalendar.updateBatch(events.slice(0, 2));
        -}
        -
      4. -
    6. -
    7. To delete events, use the removeBatch() method in the success event handler of the find() method to delete multiple calendar items asynchronously:

      -function eventSearchSuccessCallback(events)
      -{
      -   /* Delete the first 2 existing events */
      -   myCalendar.removeBatch([events[0].id, events[1].id]);
      -}
      -
    8. -
    - -

    Converting Calendar Event Formats

    - -

    The following examples illustrate how to make calendar event exchange more efficient in your application by converting the calendar events to iCalendar format or the other way around using the CalendarEvent constructor and the convertToString() method of the Calendar object respectively:

    -
      -
    • To convert an iCalendar string to a calendar event: -
        -
      1. Retrieve the default system calendar using the getDefaultCalendar() method of the CalendarManager interface.

        With the parameter, specify the calendar type as event.

        -var calendar = tizen.calendar.getDefaultCalendar("EVENT");
      2. -
      3. Create a new CalendarEvent object from the iCalendar string and add it to the default calendar:
        -try
        -{
        -   var ev = new tizen.CalendarEvent
        -   (
        -      "BEGIN:VCALENDAR\r\n" +
        -      "BEGIN:VEVENT\r\n" +
        -      "DTSTAMP:19970901T1300Z\r\n" +
        -      "DTSTART:19970903T163000Z\r\n" +
        -      "DTEND:19970903T190000Z\r\n" +
        -      "SUMMARY:Tizen, Annual Employee Review\r\n" +
        -      "CATEGORIES:BUSINESS,HUMAN RESOURCES\r\n" +
        -      "END:VEVENT\r\n" +
        -      "END:VCALENDAR", "ICALENDAR_20"
        -   );
        -
        -   calendar.add(ev);
        -   console.log('Event added with UID ' + ev.id.uid);
        -}
      4. -

      To convert multiple strings and import them to a calendar, convert the strings one by one and then use the addBatch() method to add all the events at once in a batch mode.

    • -
    • To convert a calendar event to the iCalendar format: -
        -
      1. Get the default calendar and find all calendar events which include the "Tizen" string in the Summary attribute:
        -var myCalendar;
        -
        -myCalendar = tizen.calendar.getDefaultCalendar("EVENT");
        -
        -/* Define a filter */
        -var filter = new tizen.AttributeFilter("summary", "CONTAINS", "Tizen");
        -
        -/* Search for the events */
        -myCalendar.find(eventSearchSuccessCallback, errorCallback, filter);
        -
      2. -
      3. Convert a calendar event to an iCalendar string in the success event handler of the find() method using the convertToString() method:
        -function eventSearchSuccessCallback(events)
        -{
        -   /* Convert the first event */
        -   var vevent = events[0].convertToString("ICALENDAR_20");
        -}
        -
      4. -
      -

      To export and convert multiple events from a calendar, find the required events using the find() method with an applicable filter, and then convert the found events one by one.

    - - -

    Adding Tasks to a Calendar

    - -

    To create engaging applications with various calendar features, you must learn to add tasks to calendars:

    -
      -
    1. Retrieve the default system calendar using the getDefaultCalendar() method of the CalendarManager interface.

      With the parameter, specify the calendar type as task.

      -var calendar = tizen.calendar.getDefaultCalendar("TASK");
      -
    2. -
    3. Create a CalendarTask object and define the task properties:

      var task = new tizen.CalendarTask
      -({
      -   description:"HTML5 Introduction",
      -   summary:"HTML5 Webinar",
      -   startDate: new tizen.TZDate(2011, 3, 10, 10, 0),
      -   dueDate: new tizen.TZDate(2011, 3, 30, 10, 0),
      -   completedDate: new tizen.TZDate(2011, 3, 20, 10, 0),
      -   location:"Huesca"
      -});
      -
    4. -
    5. To set up an alarm to remind the user about the task, create an alarm with the CalendarAlarm interface, and add the alarm to the task:

      -/* Alarm is triggered with sound 30 minutes before the task start time */
      -var alarm = new tizen.CalendarAlarm(new tizen.TimeDuration(30, "MINS"), "SOUND");
      -
      -task.alarms = [alarm];
      -
    6. -
    7. Add the CalendarTask object to the default calendar with the add() method of the Calendar object:

      calendar.add(task);  /* task.id attribute is generated */
    8. -
    - -

    Adding Tasks to a Calendar in the Batch Mode

    - -

    To create engaging applications with various calendar features, you must learn to add tasks to calendars in the batch mode:

    -
      -
    1. Retrieve the default system calendar using the getDefaultCalendar() method of the CalendarManager interface:

      -var calendar = tizen.calendar.getDefaultCalendar("TASK");
      -
    2. -
    3. Define the items to be added as an array:

      -var task = new tizen.CalendarTask
      -({
      -   description:"HTML5 Introduction",
      -   summary:"HTML5 Webinar",
      -   startDate: new tizen.TZDate(2011, 3, 30, 10, 0),
      -   dueDate: new tizen.TZDate(2011, 5, 30, 10, 0),
      -   completedDate: new tizen.TZDate(2011, 4, 30, 10, 0),
      -   location:"Huesca"
      -});
      -
      - - - - - - - - - -
      Note
      To keep the example as simple as possible, the array above includes only 1 task. -
    4. -
    5. Use the addBatch() method of the Calendar object to add the tasks in the array to the calendar:

      -calendar.addBatch([task]);
      -
      - - - - - - - - - -
      Note
      The addBatch() method is asynchronous, and its callbacks must be used if you want to react to the success or failure of the operation.
      -
    6. -
    - -

    Managing a Single Calendar Task

    - -

    To create engaging applications with various calendar features, you must learn to manage a single calendar task:

    -
      -
    1. Retrieve the default system calendar using the getDefaultCalendar() method of the CalendarManager interface.

      With the parameter, specify the calendar type as task.

      -var myCalendar = tizen.calendar.getDefaultCalendar("TASK");
      -
    2. -
    3. Retrieve all tasks stored in the calendar by using the find() method of the Calendar object:

      -myCalendar.find(taskSearchSuccessCallback);
      - - - - - - - - - -
      Note
      To retrieve a specific set of tasks, you can specify a filter and sorting order for the search operation through the filter and sortMode parameters (for attributes supported in the filter, see Calendar Filter Attributes).

      In this example, all the tasks are retrieved because no filter is used.

    4. -
    5. Update or delete the found item inside the taskSearchSuccessCallback() event handler.

      In this example, the description parameter of the first task is changed and the task is updated in the calendar using the update() method. The second task is deleted using the remove() method.

      /* Define the event success callback */
      -function taskSearchSuccessCallback(tasks)
      -{
      -   /* Update the first existing task */
      -   tasks[0].description = "New Description";
      -   myCalendar.update(tasks[0]);
      -
      -   /* Delete the second existing task */
      -   myCalendar.remove(tasks[1].id);
      -}
    6. -
    - -

    Managing Multiple Calendar Tasks in the Batch Mode

    - -

    To create engaging applications with various calendar features, you must learn to manage multiple calendar tasks in the batch mode:

    -
      -
    1. Retrieve the default system calendar using the getDefaultCalendar() method of the CalendarManager interface.

      With the parameter, specify the calendar type as task.

      -var myCalendar = tizen.calendar.getDefaultCalendar("TASK");
      -
    2. -
    3. Retrieve all tasks stored in the calendar by using the find() method of the Calendar object:

      -myCalendar.find(taskSearchSuccessCallback);
      - - - - - - - - - -
      Note
      To retrieve a specific set of tasks, you can specify a filter and sorting order for the search operation through the filter and sortMode parameters (for attributes supported in the filter, see Calendar Filter Attributes).

      In this example, all the tasks are retrieved because no filter is used.

    4. -
    5. To update tasks: -
        -
      1. Define the items to be updated in the success event handler of the find() method:

        -function taskSearchSuccessCallback(tasks)
        -{
        -   tasks[0].description = "New Description 1";
        -   tasks[1].description = "New Description 2";
        -
      2. -
      3. Use the updateBatch() method to update multiple calendar items asynchronously:

        -   /* Update the first 2 existing tasks */
        -   myCalendar.updateBatch(tasks.slice(0, 2));
        -}
        -
      4. -
    6. -
    7. To delete tasks, use the removeBatch() method in the success event handler of the find() method to delete multiple calendar items asynchronously:

      -function taskSearchSuccessCallback(tasks)
      -{
      -   /* Delete the first 2 existing tasks */
      -   myCalendar.removeBatch([tasks[0].id, tasks[1].id]);
      -}
      -
    8. -
    - -

    Converting Calendar Task Formats

    - -

    The following examples illustrate how to make calendar task exchange more efficient in your application by converting the calendar task to iCalendar format or the other way around using the CalendarTask constructor and the convertToString() method of the Calendar object respectively:

    -
      -
    • To convert an iCalendar string to a calendar task: -
        -
      1. Retrieve the default system calendar using the getDefaultCalendar() method of the CalendarManager interface.

        With the parameter, specify the calendar type as task.

        -var calendar = tizen.calendar.getDefaultCalendar("TASK");
      2. -
      3. Create a new CalendarTask object from the iCalendar string and add it to the default calendar:
        -var task = new tizen.CalendarTask
        -(
        -   "BEGIN:VCALENDAR\r\n" +
        -   "VERSION:2.0\r\n" +
        -   "BEGIN:VTODO\r\n" +
        -   "DTSTAMP:TZID=CET:20110902T110000Z\r\n" +
        -   "DTSTART;TZID=CET:20110906T140000Z\r\n" +
        -   "DUE;TZID=CET:20110906T150000Z\r\n" +
        -   "SUMMARY:Tizen, discuss the schedule\r\n" +
        -   "DESCRIPTION:Find the feasible schedule\r\n" +
        -   "CATEGORIES:HUMAN RESOURCES\r\n" +
        -   "END:VTODO\r\n" +
        -   "END:VCALENDAR", "ICALENDAR_20"
        -);
        -
        -calendar.add(task);
        -console.log('Task added with id ' + task.id);
        -
      4. -

      To convert multiple strings and import them to a calendar, convert the strings one by one and then use the addBatch() method to add all the tasks at once in a batch mode.

    • -
    • To convert a calendar task to the iCalendar format: -
        -
      1. Get the default calendar and find all calendar items which include the "Tizen" string in the Summary attribute:
        -var myCalendar;
        -
        -myCalendar = tizen.calendar.getDefaultCalendar("TASK");
        -
        -/* Define a filter */
        -var filter = new tizen.AttributeFilter("summary", "CONTAINS", "Tizen");
        -
        -/* Search for the tasks */
        -myCalendar.find(taskSearchSuccessCallback, null, filter);
        -
      2. -
      3. Convert a calendar item to an iCalendar string in the success event handler of the find() method using the convertToString() method:
        -function taskSearchSuccessCallback(tasks)
        -{
        -   /* Convert the first task */
        -   var vtodo = tasks[0].convertToString("ICALENDAR_20");
        -}
        -
      4. -

      To export and convert multiple tasks from a calendar, find the required tasks using the find() method with an applicable filter, and then convert the found tasks one by one.

    • -
    - -

    Receiving Notifications on Calendar Changes

    - -

    To create engaging applications with various calendar features, you must learn to receive notifications when calendar items are added, updated, or removed:

    -
      -
    1. Define the needed variables:

      -/* Watcher identifier */
      -var watcherId = 0;
      -
      -/* This example assumes that the calendar is initialized */
      -var calendar;
      -
    2. -
    3. Define the event handlers for different notifications using the CalendarChangeCallback listener interface:

      -var watcher =
      -{
      -   /* When new items are added */
      -   onitemsadded: function(items)
      -   {
      -      console.log(items.length + " items were added");
      -   },
      -
      -   /* When items are updated */
      -   onitemsupdated: function(items)
      -   {
      -      console.log(items.length + " items were updated");
      -   },
      -
      -   /* When items are deleted */
      -   onitemsremoved: function(ids)
      -   {
      -      console.log(ids.length + " items were removed");
      -   }
      -};
      -
    4. -
    5. Register the listener to use the defined event handlers:

      -watcherId = calendar.addChangeListener(watcher);
      -
    6. -
    7. To stop the notifications, use the removeChangeListener() method:

      -function cancelWatch()
      -{
      -   calendar.removeChangeListener(watcherId);
      -}
      -
    8. -
    - - - - - -
    - -Go to top - - - - - - + + + + + + + + + + + + + Calendar: Managing Calendars and Calendar Events + + + + + +
    + +

    Calendar: Managing Calendars and Calendar Events

    + +

    This tutorial demonstrates how you can manage calendars in the device to access, modify, add, and remove calendar items within a specified calendar on the device.

    + + + + + + + + + + +
    Note
    This feature is supported in mobile applications only.
    + +

    Warm-up

    +

    Become familiar with the Calendar API basics by learning about:

    + +

    Task

    +

    In the Event Manager task, we will walk through how to manage calendar events in your application.

    + +

    Creating a Calendar

    + +

    Creating a new calendar is a basic calendar management skill:

    + + + + + + + + + + +
    Note
    The created calendar is associated with a specified account. Therefore, you must retrieve the account before creating a new calendar.
    +
      +
    1. Declare a variable to store the created calendar: +
      var myCalendar = null;
      +
    2. +
    3. Define a success callback for the getAccounts() method. The callback receives a list of Account objects. Use the first account ID to construct a new Calendar object. +

      Add the new calendar to the system using the addCalendar() method of the CalendarManager interface:

      +
      function getAccountsSuccess(accounts)
      +{
      +   var account = accounts[0];
      +   if (account)
      +   {
      +      /* New calendar can be created and added */
      +      myCalendar = new tizen.Calendar(account.id, "remote calendar", "TASK");
      +      tizen.calendar.addCalendar(myCalendar);
      +      console.log("New calendar created with ID=" + myCalendar.id);
      +   }
      +}
    4. +
    5. To retrieve available accounts, use the getAccounts() method. The following method call invokes the getAccountsSuccess event handler defined above: +
      tizen.account.getAccounts(getAccountsSuccess, function(err));
      +
    6. +
    + + +

    Adding Events to a Calendar

    + + +

    To create engaging applications with various calendar features, you must learn to add events to calendars:

    +
      +
    1. Retrieve the default system calendar using the getDefaultCalendar() method of the CalendarManager interface.

      With the parameter, specify the calendar type as an event.

      +var calendar = tizen.calendar.getDefaultCalendar("EVENT");
      +
    2. +
    3. Create a CalendarEvent object and define the event properties:

      var ev = new tizen.CalendarEvent
      +({
      +   description:"HTML5 Introduction",
      +   summary:"HTML5 Webinar",
      +   startDate: new tizen.TZDate(2011, 3, 30, 10, 0),
      +   duration: new tizen.TimeDuration(1, "HOURS"),
      +   location:"Huesca",
      +
    4. +
    5. To make a recurring event, define a recurrence rule.

      In this example, the event repeats once a day for 3 days.

      +   recurrenceRule: new tizen.CalendarRecurrenceRule("DAILY", {occurrenceCount: 3})
      +});
      +
    6. +
    7. To set up an alarm to remind the user about the event, create an alarm with the CalendarAlarm interface, and add the alarm to the event:

      +/* Alarm is triggered with sound 30 minutes before the event start time */
      +var alarm = new tizen.CalendarAlarm(new tizen.TimeDuration(30, "MINS"), "SOUND");
      +
      +ev.alarms = [alarm];
      +
    8. +
    9. Add the CalendarEvent object to the default calendar with the add() method of the Calendar object.

      calendar.add(ev);  /* ev.id attribute is generated */
    10. +
    + +

    Adding Events to a Calendar in the Batch Mode

    + + +

    To create engaging applications with various calendar features, you must learn to add events to calendars in the batch mode:

    +
      +
    1. Retrieve the default system calendar using the getDefaultCalendar() method of the CalendarManager interface:

      +var calendar = tizen.calendar.getDefaultCalendar("EVENT");
      +
    2. +
    3. Define the items to be added as an array:

      +var ev = new tizen.CalendarEvent
      +({
      +   description:"HTML5 Introduction",
      +   summary:"HTML5 Webinar",
      +   startDate: new tizen.TZDate(2011, 3, 30, 10, 0),
      +   duration: new tizen.TimeDuration(1, "HOURS"),
      +   location:"Huesca"
      +});
      +
      + + + + + + + + + +
      Note
      To keep the example as simple as possible, the array above includes only 1 event.
    4. +
    5. Use the addBatch() method of the Calendar object to add the events in the array to the calendar:

      +calendar.addBatch([ev]);
      +
      + + + + + + + + + +
      Note
      The addBatch() method is asynchronous, and its callbacks must be used to react to the success or failure of the operation.
      +
    6. +
    + +

    Managing a Single Calendar Event

    + +

    To create engaging applications with various calendar features, you must learn to manage a single calendar event:

    +
      +
    1. Retrieve the default system calendar using the getDefaultCalendar() method of the CalendarManager interface.

      With the parameter, specify the calendar type as event.

      +var myCalendar = tizen.calendar.getDefaultCalendar("EVENT");
      +
    2. +
    3. Retrieve all events stored in the calendar by using the find() method of the Calendar object:

      +myCalendar.find(eventSearchSuccessCallback);
      + + + + + + + + + +
      Note
      To retrieve a specific set of events, you can specify a filter and sorting order for the search operation through the filter and sortMode parameters (for attributes supported in the filter, see Calendar Filter Attributes).

      In this example, all the events are retrieved because no filter is used.

    4. +
    5. Update or delete the found item inside the eventSearchSuccessCallback() event handler.

      In this example, the description parameter of the first event is changed and the event is updated in the calendar using the update() method. The second event is deleted using the remove() method.

      /* Define the event success callback */
      +function eventSearchSuccessCallback(events)
      +{
      +   /* Update the first existing event */
      +   events[0].description = "New Description";
      +   myCalendar.update(events[0]);
      +
      +   /* Delete the second existing event */
      +   myCalendar.remove(events[1].id);
      +}
    6. +
    + +

    Updating Recurring Calendar Events

    + +

    To create engaging applications with various calendar features, you must learn to update recurring calendar events:

    +
      +
    1. Retrieve the default system calendar using the getDefaultCalendar() method of the CalendarManager interface.

      +

      Retrieve the calendar event using the get() method by specifying the event ID.

      +var calendar = tizen.calendar.getDefaultCalendar("EVENT");
      +var event = calendar.get(evId);
      +
    2. +
    3. Expand the recurring event to get its instances by using the expandRecurrence() method of the CalendarEvent object:
      +event.expandRecurrence(new tizen.TZDate(2012, 2, 1), new tizen.TZDate(2012, 2, 15),
      +                       eventExpandSuccessCB);

      The expanded event instances have their own id.uid and id.rid attributes, where the id.uid attribute is the same for all instances.

    4. +
    5. Update a single instance of the expanded recurring event.

      In case of recurring events, you can use the second parameter of the update() method to determine whether a single instance or all occurrences of the event are updated. If the parameter is set to true, all instances are updated, while if it is set to false, only the indicated instance of the recurring event is updated (based on the id.rid attribute).

      In this example, the second instance of the event is updated.

      +/* Success event handler */
      +function eventExpandSuccessCB(events)
      +{
      +   events[1].summary = 'updated summary';
      +   calendar.update(events[1], false);
      +}
      +
    6. +
    + +

    Managing Multiple Calendar Events in the Batch Mode

    + +

    To create engaging applications with various calendar features, you must learn to manage multiple calendar events in the batch mode:

    +
      +
    1. Retrieve the default system calendar using the getDefaultCalendar() method of the CalendarManager interface.

      With the parameter, specify the calendar type as event.

      +var myCalendar = tizen.calendar.getDefaultCalendar("EVENT");
      +
    2. +
    3. Retrieve all events stored in the calendar by using the find() method of the Calendar object:

      +myCalendar.find(eventSearchSuccessCallback, errorCallback);
      + + + + + + + + + +
      Note
      To retrieve a specific set of events, you can specify a filter and sorting order for the search operation through the filter and sortMode parameters (for attributes supported in the filter, see Calendar Filter Attributes).

      In this example, all the events are retrieved because no filter is used.

    4. + +
    5. To update events: +
        +
      1. Define the items to be updated in the success event handler of the find() method:

        +function eventSearchSuccessCallback(events)
        +{
        +   events[0].description = "New Description 1";
        +   events[1].description = "New Description 2";
        +
      2. +
      3. Use the updateBatch() method to update multiple calendar items asynchronously:

        +   /* Update the first 2 existing events */
        +   myCalendar.updateBatch(events.slice(0, 2));
        +}
        +
      4. +
    6. +
    7. To delete events, use the removeBatch() method in the success event handler of the find() method to delete multiple calendar items asynchronously:

      +function eventSearchSuccessCallback(events)
      +{
      +   /* Delete the first 2 existing events */
      +   myCalendar.removeBatch([events[0].id, events[1].id]);
      +}
      +
    8. +
    + +

    Converting Calendar Event Formats

    + +

    The following examples illustrate how to make calendar event exchange more efficient in your application by converting the calendar events to iCalendar format or the other way around using the CalendarEvent constructor and the convertToString() method of the Calendar object respectively:

    +
      +
    • To convert an iCalendar string to a calendar event: +
        +
      1. Retrieve the default system calendar using the getDefaultCalendar() method of the CalendarManager interface.

        With the parameter, specify the calendar type as event.

        +var calendar = tizen.calendar.getDefaultCalendar("EVENT");
      2. +
      3. Create a new CalendarEvent object from the iCalendar string and add it to the default calendar:
        +try
        +{
        +   var ev = new tizen.CalendarEvent
        +   (
        +      "BEGIN:VCALENDAR\r\n" +
        +      "BEGIN:VEVENT\r\n" +
        +      "DTSTAMP:19970901T1300Z\r\n" +
        +      "DTSTART:19970903T163000Z\r\n" +
        +      "DTEND:19970903T190000Z\r\n" +
        +      "SUMMARY:Tizen, Annual Employee Review\r\n" +
        +      "CATEGORIES:BUSINESS,HUMAN RESOURCES\r\n" +
        +      "END:VEVENT\r\n" +
        +      "END:VCALENDAR", "ICALENDAR_20"
        +   );
        +
        +   calendar.add(ev);
        +   console.log('Event added with UID ' + ev.id.uid);
        +}
      4. +

      To convert multiple strings and import them to a calendar, convert the strings one by one and then use the addBatch() method to add all the events at once in a batch mode.

    • +
    • To convert a calendar event to the iCalendar format: +
        +
      1. Get the default calendar and find all calendar events which include the "Tizen" string in the Summary attribute:
        +var myCalendar;
        +
        +myCalendar = tizen.calendar.getDefaultCalendar("EVENT");
        +
        +/* Define a filter */
        +var filter = new tizen.AttributeFilter("summary", "CONTAINS", "Tizen");
        +
        +/* Search for the events */
        +myCalendar.find(eventSearchSuccessCallback, errorCallback, filter);
        +
      2. +
      3. Convert a calendar event to an iCalendar string in the success event handler of the find() method using the convertToString() method:
        +function eventSearchSuccessCallback(events)
        +{
        +   /* Convert the first event */
        +   var vevent = events[0].convertToString("ICALENDAR_20");
        +}
        +
      4. +
      +

      To export and convert multiple events from a calendar, find the required events using the find() method with an applicable filter, and then convert the found events one by one.

    + + +

    Adding Tasks to a Calendar

    + +

    To create engaging applications with various calendar features, you must learn to add tasks to calendars:

    +
      +
    1. Retrieve the default system calendar using the getDefaultCalendar() method of the CalendarManager interface.

      With the parameter, specify the calendar type as task.

      +var calendar = tizen.calendar.getDefaultCalendar("TASK");
      +
    2. +
    3. Create a CalendarTask object and define the task properties:

      var task = new tizen.CalendarTask
      +({
      +   description:"HTML5 Introduction",
      +   summary:"HTML5 Webinar",
      +   startDate: new tizen.TZDate(2011, 3, 10, 10, 0),
      +   dueDate: new tizen.TZDate(2011, 3, 30, 10, 0),
      +   completedDate: new tizen.TZDate(2011, 3, 20, 10, 0),
      +   location:"Huesca"
      +});
      +
    4. +
    5. To set up an alarm to remind the user about the task, create an alarm with the CalendarAlarm interface, and add the alarm to the task:

      +/* Alarm is triggered with sound 30 minutes before the task start time */
      +var alarm = new tizen.CalendarAlarm(new tizen.TimeDuration(30, "MINS"), "SOUND");
      +
      +task.alarms = [alarm];
      +
    6. +
    7. Add the CalendarTask object to the default calendar with the add() method of the Calendar object:

      calendar.add(task);  /* task.id attribute is generated */
    8. +
    + +

    Adding Tasks to a Calendar in the Batch Mode

    + +

    To create engaging applications with various calendar features, you must learn to add tasks to calendars in the batch mode:

    +
      +
    1. Retrieve the default system calendar using the getDefaultCalendar() method of the CalendarManager interface:

      +var calendar = tizen.calendar.getDefaultCalendar("TASK");
      +
    2. +
    3. Define the items to be added as an array:

      +var task = new tizen.CalendarTask
      +({
      +   description:"HTML5 Introduction",
      +   summary:"HTML5 Webinar",
      +   startDate: new tizen.TZDate(2011, 3, 30, 10, 0),
      +   dueDate: new tizen.TZDate(2011, 5, 30, 10, 0),
      +   completedDate: new tizen.TZDate(2011, 4, 30, 10, 0),
      +   location:"Huesca"
      +});
      +
      + + + + + + + + + +
      Note
      To keep the example as simple as possible, the array above includes only 1 task. +
    4. +
    5. Use the addBatch() method of the Calendar object to add the tasks in the array to the calendar:

      +calendar.addBatch([task]);
      +
      + + + + + + + + + +
      Note
      The addBatch() method is asynchronous, and its callbacks must be used if you want to react to the success or failure of the operation.
      +
    6. +
    + +

    Managing a Single Calendar Task

    + +

    To create engaging applications with various calendar features, you must learn to manage a single calendar task:

    +
      +
    1. Retrieve the default system calendar using the getDefaultCalendar() method of the CalendarManager interface.

      With the parameter, specify the calendar type as task.

      +var myCalendar = tizen.calendar.getDefaultCalendar("TASK");
      +
    2. +
    3. Retrieve all tasks stored in the calendar by using the find() method of the Calendar object:

      +myCalendar.find(taskSearchSuccessCallback);
      + + + + + + + + + +
      Note
      To retrieve a specific set of tasks, you can specify a filter and sorting order for the search operation through the filter and sortMode parameters (for attributes supported in the filter, see Calendar Filter Attributes).

      In this example, all the tasks are retrieved because no filter is used.

    4. +
    5. Update or delete the found item inside the taskSearchSuccessCallback() event handler.

      In this example, the description parameter of the first task is changed and the task is updated in the calendar using the update() method. The second task is deleted using the remove() method.

      /* Define the event success callback */
      +function taskSearchSuccessCallback(tasks)
      +{
      +   /* Update the first existing task */
      +   tasks[0].description = "New Description";
      +   myCalendar.update(tasks[0]);
      +
      +   /* Delete the second existing task */
      +   myCalendar.remove(tasks[1].id);
      +}
    6. +
    + +

    Managing Multiple Calendar Tasks in the Batch Mode

    + +

    To create engaging applications with various calendar features, you must learn to manage multiple calendar tasks in the batch mode:

    +
      +
    1. Retrieve the default system calendar using the getDefaultCalendar() method of the CalendarManager interface.

      With the parameter, specify the calendar type as task.

      +var myCalendar = tizen.calendar.getDefaultCalendar("TASK");
      +
    2. +
    3. Retrieve all tasks stored in the calendar by using the find() method of the Calendar object:

      +myCalendar.find(taskSearchSuccessCallback);
      + + + + + + + + + +
      Note
      To retrieve a specific set of tasks, you can specify a filter and sorting order for the search operation through the filter and sortMode parameters (for attributes supported in the filter, see Calendar Filter Attributes).

      In this example, all the tasks are retrieved because no filter is used.

    4. +
    5. To update tasks: +
        +
      1. Define the items to be updated in the success event handler of the find() method:

        +function taskSearchSuccessCallback(tasks)
        +{
        +   tasks[0].description = "New Description 1";
        +   tasks[1].description = "New Description 2";
        +
      2. +
      3. Use the updateBatch() method to update multiple calendar items asynchronously:

        +   /* Update the first 2 existing tasks */
        +   myCalendar.updateBatch(tasks.slice(0, 2));
        +}
        +
      4. +
    6. +
    7. To delete tasks, use the removeBatch() method in the success event handler of the find() method to delete multiple calendar items asynchronously:

      +function taskSearchSuccessCallback(tasks)
      +{
      +   /* Delete the first 2 existing tasks */
      +   myCalendar.removeBatch([tasks[0].id, tasks[1].id]);
      +}
      +
    8. +
    + +

    Converting Calendar Task Formats

    + +

    The following examples illustrate how to make calendar task exchange more efficient in your application by converting the calendar task to iCalendar format or the other way around using the CalendarTask constructor and the convertToString() method of the Calendar object respectively:

    +
      +
    • To convert an iCalendar string to a calendar task: +
        +
      1. Retrieve the default system calendar using the getDefaultCalendar() method of the CalendarManager interface.

        With the parameter, specify the calendar type as task.

        +var calendar = tizen.calendar.getDefaultCalendar("TASK");
      2. +
      3. Create a new CalendarTask object from the iCalendar string and add it to the default calendar:
        +var task = new tizen.CalendarTask
        +(
        +   "BEGIN:VCALENDAR\r\n" +
        +   "VERSION:2.0\r\n" +
        +   "BEGIN:VTODO\r\n" +
        +   "DTSTAMP:TZID=CET:20110902T110000Z\r\n" +
        +   "DTSTART;TZID=CET:20110906T140000Z\r\n" +
        +   "DUE;TZID=CET:20110906T150000Z\r\n" +
        +   "SUMMARY:Tizen, discuss the schedule\r\n" +
        +   "DESCRIPTION:Find the feasible schedule\r\n" +
        +   "CATEGORIES:HUMAN RESOURCES\r\n" +
        +   "END:VTODO\r\n" +
        +   "END:VCALENDAR", "ICALENDAR_20"
        +);
        +
        +calendar.add(task);
        +console.log('Task added with id ' + task.id);
        +
      4. +

      To convert multiple strings and import them to a calendar, convert the strings one by one and then use the addBatch() method to add all the tasks at once in a batch mode.

    • +
    • To convert a calendar task to the iCalendar format: +
        +
      1. Get the default calendar and find all calendar items which include the "Tizen" string in the Summary attribute:
        +var myCalendar;
        +
        +myCalendar = tizen.calendar.getDefaultCalendar("TASK");
        +
        +/* Define a filter */
        +var filter = new tizen.AttributeFilter("summary", "CONTAINS", "Tizen");
        +
        +/* Search for the tasks */
        +myCalendar.find(taskSearchSuccessCallback, null, filter);
        +
      2. +
      3. Convert a calendar item to an iCalendar string in the success event handler of the find() method using the convertToString() method:
        +function taskSearchSuccessCallback(tasks)
        +{
        +   /* Convert the first task */
        +   var vtodo = tasks[0].convertToString("ICALENDAR_20");
        +}
        +
      4. +

      To export and convert multiple tasks from a calendar, find the required tasks using the find() method with an applicable filter, and then convert the found tasks one by one.

    • +
    + +

    Receiving Notifications on Calendar Changes

    + +

    To create engaging applications with various calendar features, you must learn to receive notifications when calendar items are added, updated, or removed:

    +
      +
    1. Define the needed variables:

      +/* Watcher identifier */
      +var watcherId = 0;
      +
      +/* This example assumes that the calendar is initialized */
      +var calendar;
      +
    2. +
    3. Define the event handlers for different notifications using the CalendarChangeCallback listener interface:

      +var watcher =
      +{
      +   /* When new items are added */
      +   onitemsadded: function(items)
      +   {
      +      console.log(items.length + " items were added");
      +   },
      +
      +   /* When items are updated */
      +   onitemsupdated: function(items)
      +   {
      +      console.log(items.length + " items were updated");
      +   },
      +
      +   /* When items are deleted */
      +   onitemsremoved: function(ids)
      +   {
      +      console.log(ids.length + " items were removed");
      +   }
      +};
      +
    4. +
    5. Register the listener to use the defined event handlers:

      +watcherId = calendar.addChangeListener(watcher);
      +
    6. +
    7. To stop the notifications, use the removeChangeListener() method:

      +function cancelWatch()
      +{
      +   calendar.removeChangeListener(watcherId);
      +}
      +
    8. +
    + + + + + +
    + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.tutorials/html/web/tizen/social/call_history_tutorial_w.htm b/org.tizen.tutorials/html/web/tizen/social/call_history_tutorial_w.htm index 50163e2..aae5dc0 100644 --- a/org.tizen.tutorials/html/web/tizen/social/call_history_tutorial_w.htm +++ b/org.tizen.tutorials/html/web/tizen/social/call_history_tutorial_w.htm @@ -1,201 +1,201 @@ - - - - - - - - - - - - - Call History: Managing the Call History on the Device - - - - - -
    - -

    Call History: Managing the Call History on the Device

    - -

    This tutorial demonstrates how you can manage and monitor the call history.

    - - - - - - - - - - -
    Note
    This feature is supported in mobile applications only.
    - -

    Warm-up

    -

    Become familiar with the Call History API basics by learning about:

    - -

    Task

    -

    In the Call Log task, we will walk through how to manage call logs in your application.

    - - -

    Searching for Call History Items

    - -

    Learning how to retrieve call history items using different parameters allows you to view specific items in a specific order, making call history monitoring easy and convenient.

    -
      -
    1. To retrieve call history items, use the find(successCallback, errorCallback, filter, sortMode, limit, offset) method of the CallHistory interface.

      This method is asynchronous, and the result of the query is an array of CallHistoryEntry objects.

      tizen.callhistory.find(onSuccess, onError, ifilter, sortMode, 20, 10);
    2. -
    3. Use the SuccessCallback parameter of the find() method to define an event handler for the query result set.

      In the following code snippet, the found call history items are appended to the console log.

      function onSuccess(results) 
      -{
      -   console.log(results.length + " call history item(s) found!");
      -   for (var i = 0; i < results.length; i++) 
      -   {
      -      console.log(i + ". " + results[i].toString()); 
      -      /* Process the CallHistoryEntry */
      -   }
      -}
    4. -
    5. Use the filter parameter of the find() method to define a filter for the query result set. A filter with the CallHistoryEntry attributes is used to limit the results of the call history search.

      You can define various filters:

      -
        -
      • The AttributeFilter type is used to search based on a single CallHistoryEntry attribute (for attributes supported in the filter, see CallHistory Filter Attributes).

        For example, the following filters define that only cellular calls or calls where the remote party has the telephone number 123456789 are included in the query results:

        /* First filter example */
        -var filter = new tizen.AttributeFilter("type", "EXACTLY", "TEL");
        -
        -/* Second filter example */
        -var numberFilter = new tizen.AttributeFilter("remoteParties.remoteParty", "EXACTLY", "123456789")
      • -
      • The CompositeFilter type represents a set of filters. The UNION type composite filter matches any object that is matched by any of its filters; the INTERSECTION type composite filter matches all objects that are matched by all of its filters.

        For example, the following code snippet defines a set of filters that include in the query results only the video calls where the remote party has the telephone number 123456789 and the call has started during the year 2009 or 2011:

        /* Create the ranges for the time filter */
        -var y2009Filter = new tizen.AttributeRangeFilter("startTime", 
        -                                                 new Date(2009, 0, 1),
        -                                                 new Date(2010, 0, 1));
        -var y2011Filter = new tizen.AttributeRangeFilter("startTime",
        -                                                 new Date(2011, 0, 1),
        -                                                 new Date(2012, 0, 1));
        -
        -/* Create a time filter */
        -var dataFilter = new tizen.CompositeFilter("UNION",
        -                                           [y2009Filter, y2011Filter]);
        -
        -/* Create a video call filter */
        -var tfilter = new tizen.AttributeFilter("features", "EXACTLY", "VIDEOCALL");
        -
        -/* Combine the filters into a set */
        -var ifilter = new tizen.CompositeFilter("INTERSECTION", [numberFilter, dataFilter, tfilter]);
      • -
    6. -
    7. Use the sortMode parameter to order the query result set. If the parameter is undefined or set to null, the results are sorted by default in a descending order.

      In the following code snippet, the found call history items are sorted according to the start time, in descending order:

      var sortMode = new tizen.SortMode("startTime", "DESC");
    8. -
    9. Use the limit and offset parameters of the find() method to specify the starting point and upper limit of the results that are returned.

      The limit parameter specifies the maximum number of matching results that are returned (the value 0 makes the limit infinite), while the offset parameter skips that many matching results that are to be returned (the value 0 means nothing is skipped).

      For example, if your search results consist of 100 matching results and you have specified an offset of 10 and a limit of 20, you get the objects from 10-29. The matching results from 0-9 are skipped due to the offset, and the 20 results starting from the first result after the offset are returned.

    10. -
    - - -

    Removing Call History Items

    - -

    Learning how to remove call history items allows you to keep the call history list organized and save storage space on the device:

    -
      -
    1. Use the remove() method of the CallHistory interface to remove a specific item from the call history. First, search for the entry to be removed with the find() method, and then handle the removal in the event handler that is called when the find() method is successful.

      /* Remove the found call history item */
      -function onSuccess(results) 
      -{
      -   if (results.length > 0)
      -      tizen.callhistory.remove(results[0]);
      -}
      -
      -var numberFilter = new tizen.AttributeFilter("remoteParties.remoteParty", 
      -                                             "EXACTLY", "123456789"); 
      -/* Search for the item to be removed */
      -tizen.callhistory.find(onSuccess, onError, numberFilter, null, 1);
      -
    2. -
    3. To remove multiple call history items, use the removeBatch() method.

      The removeBatch() method functions similarly as the remove() method, except that it removes a list of call history items instead of a single item:

      /* Define success callback */
      -function onSuccess(results) 
      -{
      -   tizen.callhistory.removeBatch(results);
      -}
      -
      -var numberFilter = new tizen.AttributeFilter("remoteParties.remoteParty", 
      -                                             "EXACTLY", "123456789"); 
      -tizen.callhistory.find(onSuccess, onError, numberFilter);
      -
    4. -
    5. To remove all call history items, use the removeAll() method:

      tizen.callhistory.removeAll();
    6. -
    - - - -

    Monitoring the Call History

    - -

    Learning how to register change listeners allows you to synchronize the view of your application to changes in the call history database.

    -
      - -
    1. Define the onadded event handler of the CallHistoryChangeCallback listener interface, which tracks all new incoming and outgoing calls that are added to the call history.

      var onHistoryChange = 
      -{
      -   onadded: function(newItems)
      -   {
      -      for (var i in newItems)
      -      {
      -         console.log("Item " + i + " is newly added. Its startTime: " + newItems[i].startTime);
      -      }
      -   },
    2. -
    3. Define the onchanged event handler, which tracks all changes in the call history.

      The event handler receives as an argument an array of CallHistoryEntry instances, which represent the changed items in the call history.

      -   onchanged: function(changedItems)
      -   {
      -      for (var i in changedItems)
      -      {
      -         console.log("Item " + i + " is updated. Its direction: " + changedItems[i].direction);
      -      }
      -   },
      -
    4. -
    5. Define the onremoved event handler, which tracks all items that are removed from the call history:

      -
         onremoved: function(removedItems) 
      -   {
      -      for (var i in removedItems)  
      -      {
      -         console.log("Item " + i + " is removed. The removed item's UID: " + removedItems[i]);
      -      }
      -   }
      -};
      -
    6. -
    7. Use the addChangeListener() method of the CallHistory interface to register a listener for observing call history changes:

      var callHistoryListener = tizen.callhistory.addChangeListener(onHistoryChange);
    8. - -
    9. Use the removeChangeListener() method to unregister a previously registered listener. Use the ID returned by the addChangeListener():

      tizen.callhistory.removeChangeListener(callHistoryListener);
    10. -
    - - - - - -
    - -Go to top - - - - - - + + + + + + + + + + + + + Call History: Managing the Call History on the Device + + + + + +
    + +

    Call History: Managing the Call History on the Device

    + +

    This tutorial demonstrates how you can manage and monitor the call history.

    + + + + + + + + + + +
    Note
    This feature is supported in mobile applications only.
    + +

    Warm-up

    +

    Become familiar with the Call History API basics by learning about:

    + +

    Task

    +

    In the Call Log task, we will walk through how to manage call logs in your application.

    + + +

    Searching for Call History Items

    + +

    Learning how to retrieve call history items using different parameters allows you to view specific items in a specific order, making call history monitoring easy and convenient.

    +
      +
    1. To retrieve call history items, use the find(successCallback, errorCallback, filter, sortMode, limit, offset) method of the CallHistory interface.

      This method is asynchronous, and the result of the query is an array of CallHistoryEntry objects.

      tizen.callhistory.find(onSuccess, onError, ifilter, sortMode, 20, 10);
    2. +
    3. Use the SuccessCallback parameter of the find() method to define an event handler for the query result set.

      In the following code snippet, the found call history items are appended to the console log.

      function onSuccess(results) 
      +{
      +   console.log(results.length + " call history item(s) found!");
      +   for (var i = 0; i < results.length; i++) 
      +   {
      +      console.log(i + ". " + results[i].toString()); 
      +      /* Process the CallHistoryEntry */
      +   }
      +}
    4. +
    5. Use the filter parameter of the find() method to define a filter for the query result set. A filter with the CallHistoryEntry attributes is used to limit the results of the call history search.

      You can define various filters:

      +
        +
      • The AttributeFilter type is used to search based on a single CallHistoryEntry attribute (for attributes supported in the filter, see CallHistory Filter Attributes).

        For example, the following filters define that only cellular calls or calls where the remote party has the telephone number 123456789 are included in the query results:

        /* First filter example */
        +var filter = new tizen.AttributeFilter("type", "EXACTLY", "TEL");
        +
        +/* Second filter example */
        +var numberFilter = new tizen.AttributeFilter("remoteParties.remoteParty", "EXACTLY", "123456789")
      • +
      • The CompositeFilter type represents a set of filters. The UNION type composite filter matches any object that is matched by any of its filters; the INTERSECTION type composite filter matches all objects that are matched by all of its filters.

        For example, the following code snippet defines a set of filters that include in the query results only the video calls where the remote party has the telephone number 123456789 and the call has started during the year 2009 or 2011:

        /* Create the ranges for the time filter */
        +var y2009Filter = new tizen.AttributeRangeFilter("startTime", 
        +                                                 new Date(2009, 0, 1),
        +                                                 new Date(2010, 0, 1));
        +var y2011Filter = new tizen.AttributeRangeFilter("startTime",
        +                                                 new Date(2011, 0, 1),
        +                                                 new Date(2012, 0, 1));
        +
        +/* Create a time filter */
        +var dataFilter = new tizen.CompositeFilter("UNION",
        +                                           [y2009Filter, y2011Filter]);
        +
        +/* Create a video call filter */
        +var tfilter = new tizen.AttributeFilter("features", "EXACTLY", "VIDEOCALL");
        +
        +/* Combine the filters into a set */
        +var ifilter = new tizen.CompositeFilter("INTERSECTION", [numberFilter, dataFilter, tfilter]);
      • +
    6. +
    7. Use the sortMode parameter to order the query result set. If the parameter is undefined or set to null, the results are sorted by default in a descending order.

      In the following code snippet, the found call history items are sorted according to the start time, in descending order:

      var sortMode = new tizen.SortMode("startTime", "DESC");
    8. +
    9. Use the limit and offset parameters of the find() method to specify the starting point and upper limit of the results that are returned.

      The limit parameter specifies the maximum number of matching results that are returned (the value 0 makes the limit infinite), while the offset parameter skips that many matching results that are to be returned (the value 0 means nothing is skipped).

      For example, if your search results consist of 100 matching results and you have specified an offset of 10 and a limit of 20, you get the objects from 10-29. The matching results from 0-9 are skipped due to the offset, and the 20 results starting from the first result after the offset are returned.

    10. +
    + + +

    Removing Call History Items

    + +

    Learning how to remove call history items allows you to keep the call history list organized and save storage space on the device:

    +
      +
    1. Use the remove() method of the CallHistory interface to remove a specific item from the call history. First, search for the entry to be removed with the find() method, and then handle the removal in the event handler that is called when the find() method is successful.

      /* Remove the found call history item */
      +function onSuccess(results) 
      +{
      +   if (results.length > 0)
      +      tizen.callhistory.remove(results[0]);
      +}
      +
      +var numberFilter = new tizen.AttributeFilter("remoteParties.remoteParty", 
      +                                             "EXACTLY", "123456789"); 
      +/* Search for the item to be removed */
      +tizen.callhistory.find(onSuccess, onError, numberFilter, null, 1);
      +
    2. +
    3. To remove multiple call history items, use the removeBatch() method.

      The removeBatch() method functions similarly as the remove() method, except that it removes a list of call history items instead of a single item:

      /* Define success callback */
      +function onSuccess(results) 
      +{
      +   tizen.callhistory.removeBatch(results);
      +}
      +
      +var numberFilter = new tizen.AttributeFilter("remoteParties.remoteParty", 
      +                                             "EXACTLY", "123456789"); 
      +tizen.callhistory.find(onSuccess, onError, numberFilter);
      +
    4. +
    5. To remove all call history items, use the removeAll() method:

      tizen.callhistory.removeAll();
    6. +
    + + + +

    Monitoring the Call History

    + +

    Learning how to register change listeners allows you to synchronize the view of your application to changes in the call history database.

    +
      + +
    1. Define the onadded event handler of the CallHistoryChangeCallback listener interface, which tracks all new incoming and outgoing calls that are added to the call history.

      var onHistoryChange = 
      +{
      +   onadded: function(newItems)
      +   {
      +      for (var i in newItems)
      +      {
      +         console.log("Item " + i + " is newly added. Its startTime: " + newItems[i].startTime);
      +      }
      +   },
    2. +
    3. Define the onchanged event handler, which tracks all changes in the call history.

      The event handler receives as an argument an array of CallHistoryEntry instances, which represent the changed items in the call history.

      +   onchanged: function(changedItems)
      +   {
      +      for (var i in changedItems)
      +      {
      +         console.log("Item " + i + " is updated. Its direction: " + changedItems[i].direction);
      +      }
      +   },
      +
    4. +
    5. Define the onremoved event handler, which tracks all items that are removed from the call history:

      +
         onremoved: function(removedItems) 
      +   {
      +      for (var i in removedItems)  
      +      {
      +         console.log("Item " + i + " is removed. The removed item's UID: " + removedItems[i]);
      +      }
      +   }
      +};
      +
    6. +
    7. Use the addChangeListener() method of the CallHistory interface to register a listener for observing call history changes:

      var callHistoryListener = tizen.callhistory.addChangeListener(onHistoryChange);
    8. + +
    9. Use the removeChangeListener() method to unregister a previously registered listener. Use the ID returned by the addChangeListener():

      tizen.callhistory.removeChangeListener(callHistoryListener);
    10. +
    + + + + + +
    + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.tutorials/html/web/tizen/social/contact_tutorial_w.htm b/org.tizen.tutorials/html/web/tizen/social/contact_tutorial_w.htm index 091ecef..c283388 100644 --- a/org.tizen.tutorials/html/web/tizen/social/contact_tutorial_w.htm +++ b/org.tizen.tutorials/html/web/tizen/social/contact_tutorial_w.htm @@ -1,532 +1,532 @@ - - - - - - - - - - - - - Contact: Managing Contacts and Handling Contact Information - - - - - -
    - -

    Contact: Managing Contacts and Handling Contact Information

    - -

    This tutorial demonstrates how you can manage address books in the device to access, modify, add, and remove contacts within a specified address book on the device.

    - - - - - - - - - - -
    Note
    This feature is supported in mobile applications only.
    - -

    Warm-up

    -

    Become familiar with the Contact API basics by learning about:

    - - -

    Creating an Address Book

    - -

    Creating a new address book is a basic contact management skill:

    - - - - - - - - - - -
    Note
    The created address book is associated with a specified account. Therefore, you must retrieve the account before creating a new address book.
    -
      -
    1. Declare a variable to store the created address book: -
      var myAddressBook = null;
      -
    2. -
    3. Define a success callback for the getAccounts() method. The callback receives a list of Account objects. Use the first account ID to construct a new AddressBook object. - -

      Add the new address book to the system using the addAddressBook() method of the ContactManager interface:

      -
      function getAccountsSuccess(accounts)
      -{
      -   var account = accounts[0];
      -   if (account)
      -   {
      -      /* New address book can be created and added */
      -      myAddressBook = new tizen.AddressBook(account.id, "remote address book");
      -      tizen.contact.addAddressBook(myAddressBook);
      -      console.log("New address book created with ID=" + myAddressBook.id);
      -   }
      -}
    4. -
    5. To retrieve available accounts, use the getAccounts() method. The following method call invokes the getAccountsSuccess event handler defined above. -
      tizen.account.getAccounts(getAccountsSuccess, function(err));
      -
    6. -
    -

    Getting Address Books

    - -

    To create engaging applications with various contacts features, you must learn to access the address books in which the contacts are listed:

    -
      -
    1. To get the default address book, use the getDefaultAddressBook() method of the ContactManager interface to retrieve the default address book as an AddressBook object:

      -var myAddressbook;
      -
      -/* Get the default address book */
      -myAddressbook = tizen.contact.getDefaultAddressBook();
      -
    2. -
    3. To get all available address books, use the getAddressBooks() method. This method passes an array of AddressBook objects to the success event handler.

      -var addressBook;
      -
      -function addressBooksCB(addressBooks)
      -{
      -   if (addressBooks.length > 0)
      -   {
      -      addressBook = addressBooks[0];
      -      console.log("The addressbook name is " + addressBook.name);
      -   }
      -}
      -
      -/* Get the list of available address books */
      -tizen.contact.getAddressBooks(addressBooksCB);
      -
      -

      All available address books on the device are retrieved. You can use an AddressBook object ID to select a specific address book with the getAddressBook() method, if you know the ID of the address book in advance.

      -
    4. - -
    - -

    Adding a Contact

    - -

    To create engaging applications with various contacts features, you must learn to add a contact to an address book:

    -
      -
    1. Retrieve the default system address book using the getDefaultAddressBook() method of the ContactManager interface:

      -var addressbook = tizen.contact.getDefaultAddressBook();
      -
    2. -
    3. Create a Contact object and define its properties as a ContactInit object (the parameter of the Contact constructor):

      -var contact = new tizen.Contact
      -({
      -   name: new tizen.ContactName({firstName: "Jeffrey", lastName: "Hyman"}),
      -   emails: [new tizen.ContactEmailAddress("user@example.com")]
      -});
      -
    4. -
    5. Add the Contact object to the default address book with the add() method of the AddressBook interface:

      addressbook.add(contact);
    6. -
    - -

    Managing a Contact

    - -

    To create engaging applications with various contacts features, you must learn to manage a contact in your address book:

    -
      -
    1. To retrieve a single contact, use the get() method of the AddressBook interface with the ContactID as a parameter: -

      The following example uses the object of the ContactRef interface. The ContactRef object contains both AddressBook ID and Contact ID.

      -/* contactRef is retrieved by other APIs */
      -var contactRef;
      -try
      -{
      -   /* Retrieve the contact corresponding to the given reference */
      -   var addressBook = tizen.contact.getAddressBook(contactRef.addressBookId);
      -   var contact = addressBook.get(contactRef.contactId);
      -}
      -
    2. -
    3. To manage a single contact: -
        -
      1. Retrieve the default address book using the getDefaultAddressBook() method of the ContactManager interface.

        -var addressbook = tizen.contact.getDefaultAddressBook();
        -
      2. -
      3. Retrieve contacts stored in the address book by using the find() method of the AddressBook interface:

        -var filter = new tizen.AttributeFilter("name.firstName", "CONTAINS", "Chris");
        -var sortMode = new tizen.SortMode("name.lastName", "ASC");
        -
        -try
        -{
        -   addressbook.find(contactsFoundCB, null, filter, sortMode);
        -}
        - - - - - - - - - -
        Note
        To retrieve a specific contact, you can specify a filter and sorting order for the search operation through the filter and sortMode parameters (for attributes supported in the filter, see Contact Filter Attributes).

        In this example, contacts whose first name contains "Chris" are retrieved and sorted in the ascending order based on their last name. The filter includes the standard English characters in the uppercase and lowercase. The entire list consists of ASCII characters from 32 to 126, and from 160 to 255.

        The contacts that match the filter are passed as an array to the registered success event handler in the selected sorting order.

      4. -
      5. Update or delete the found contact inside the contactsFoundCB event handler.

        In this example, the first name of the first contact is changed and the contact is updated in the address book using the update() method. The second contact is deleted using the remove() method.

        /* Define the event success callback */
        -function contactsFoundCB(contacts)
        -{
        -   contacts[0].name.firstName = "Christopher";
        -   try
        -   {
        -      /* Update the first found contact */
        -      addressbook.update(contacts[0]);
        -
        -      /* Delete the second found contact */
        -      addressbook.remove(contacts[1].id);
        -   }
        -}
      6. -
    4. -
    - -

    Receiving Notifications on Contact Changes

    - -

    To create engaging applications with various contacts features, you must learn to receive notifications when contacts are added, updated, or removed:

    -
      -
    1. Define the needed variables:

      -/* Watcher identifier */
      -var watcherId = 0;
      -
      -/* This example assumes that the address book is initialized */
      -var addressbook;
      -
    2. -
    3. Define the event handlers for different notifications about changes in the selected address book using the AddressBookChangeCallback listener interface:

      -var watcher =
      -{
      -   /* When contacts are added */
      -   oncontactsadded: function(contacts)
      -   {
      -      console.log(contacts.length + " contacts were added");
      -   },
      -
      -   /* When contacts are updated */
      -   oncontactsupdated: function(contacts)
      -   {
      -      console.log(contacts.length + " contacts were updated");
      -   },
      -
      -   /* When contacts are deleted */
      -   oncontactsremoved: function(ids)
      -   {
      -      console.log(ids.length + " contacts were deleted");
      -   }
      -};
      -
    4. -
    5. Register the listener to use the defined event handlers:

      -watcherId = addressbook.addChangeListener(watcher);
      -
    6. -
    7. To stop the notifications, use the removeChangeListener() method of the AddressBook interface:

      -addressbook.removeChangeListener(watcherId);
      -
    8. -
    - -

    Importing Contacts

    - -

    To create engaging applications with various contacts features, you must learn to import contacts with the help of the vCard format:

    - -
      -
    1. Retrieve the default system address book using the getDefaultAddressBook() method of the ContactManager interface:

      -var addressbook = tizen.contact.getDefaultAddressBook();
      -
    2. -
    3. Create a new Contact object from the vCard string and add it to the default address book:

      -var contact = null;
      -
      -try
      -{
      -   contact = new tizen.Contact("BEGIN:VCARD\n"+
      -                               "VERSION:3.0\n"+
      -                               "N:Gump;Forrest\n"+
      -                               "FN:Forrest Gump\n"+
      -                               "ORG:Bubba Gump Shrimp Co.\n"+
      -                               "TITLE:Shrimp Man\n"+
      -                               "TEL;WORK:(111) 555-1212\n"+
      -                               "TEL;HOME:(404) 555-1212\n"+
      -                               "EMAIL;WORK;PREF:forrestgump@example.com\n"+
      -                               "END:VCARD");
      -
      -   addressbook.add(contact);
      -   console.log("Contact was added with ID " + contact.id);
      -}
    4. -

    To convert multiple strings and import them to an address book, convert the strings one by one and then use the addBatch() method of the AddressBook interface to add all the contacts at once in the batch mode.

    - -

    Exporting Contacts

    - -

    To create engaging applications with various contacts features, you must learn to export contacts with the help of the vCard format:

    -
      -
    1. Retrieve the default system address book using the getDefaultAddressBook() method of the ContactManager interface and find all contacts with "Chris" in the first name:

      -var addressbook;
      -
      -var addressbook = tizen.contact.getDefaultAddressBook();
      -
      -/* Define a filter */
      -var filter = new tizen.AttributeFilter("name.firstName", "CONTAINS", "Chris");
      -
      -/* Search for the contacts */
      -addressbook.find(contactsFoundCB, errorCB, filter);
      -
    2. -
    3. Convert a contact to a vCard string in the success event handler of the find() method.

      In the following example, the first found contact is exported by converting it to the vCard version 3.0 format.

      -function contactsFoundCB(contacts)
      -{
      -   /* Convert the first contact */
      -   var vcard = contacts[0].convertToString("VCARD_30");
      -}
    4. -
    - -

    Adding Multiple Contacts in the Batch Mode

    - -

    To create engaging applications with various contacts features, you must learn to add multiple contacts to an address book in the batch mode:

    -
      -
    1. Retrieve the default system address book using the getDefaultAddressBook() method of the ContactManager interface:

      -addressbook = tizen.contact.getDefaultAddressBook();
      -
    2. -
    3. Define the items to be added as an array:

      -var c1 = new tizen.Contact(
      -{
      -   name: new tizen.ContactName({firstName:"Jeffrey", lastName:"Hyman"}),
      -   emails: [new tizen.ContactEmailAddress("user1@example.com")]
      -});
      -
      -var c2 = new tizen.Contact(
      -{
      -   name: new tizen.ContactName({firstName:"Elton", lastName:"John"}),
      -   emails: [new tizen.ContactEmailAddress("user2@example.com")]
      -});
      -
    4. -
    5. Use the addBatch() method of the AddressBook interface to add the contacts in the array to the address book:

      -addressbook.addBatch([c1, c2]);
      -
      - - - - - - - - - -
      Note
      The addBatch(), updateBatch(), and removeBatch() methods are asynchronous. Provide success and error callbacks with them.
      -
    6. -
    - -

    Managing Multiple Contacts in the Batch Mode

    - -

    To create engaging applications with various contacts features, you must learn to manage multiple contacts in your address books in the batch mode:

    -
      -
    1. Retrieve the default address book using the getDefaultAddressBook() method of the ContactManager interface.

      -var addressbook = tizen.contact.getDefaultAddressBook();
      -
    2. -
    3. Retrieve contacts stored in the address book by using the find() method of the AddressBook interface:

      -var filter = new tizen.AttributeFilter("name.firstName", "CONTAINS", "Chris"};
      -var sortMode = new tizen.SortMode("name.lastName", "ASC");
      -
      -try
      -{
      -   addressbook.find(contactsFoundCB, null, filter, sortMode);
      -}
    4. -
    5. To update contacts: -
        -
      1. Define the contact changes to be made in the success event handler of the find() method:

        -function contactsFoundCB(contacts)
        -{
        -   /* Change the first names of all the found contacts */
        -   for (var i=0; i<contacts.length; i++)
        -   {
        -      contacts[i].name.firstName = "Christopher";
        -   }
        -
      2. -
      3. Use the updateBatch() method to update multiple contacts asynchronously:

        -   /* Update all found contacts */
        -   addressbook.updateBatch(contacts);
        -}
        -
      4. -
    6. -
    7. To delete contacts, use the removeBatch() method in the success event handler of the find() method to delete multiple contacts asynchronously:

      -function contactsFoundCB(contacts)
      -{
      -   /* Delete the first 2 found contacts */
      -   addressbook.removeBatch([contacts[0].id, contacts[1].id]);
      -}
      -
    8. -
    - -

    Managing Contact Groups

    - -

    To create engaging applications with various contact features, you must learn to manage contact groups:

    -
      -
    1. Retrieve the default system address book using the getDefaultAddressBook() method of the ContactManager interface:

      -
      -var addressbook = tizen.contact.getDefaultAddressBook();
    2. -
    3. To create a ContactGroup object and add the newly create group to the system, use the constructor and the addGroup() method of the AddressBook interface:

      -
      -var group;
      -try 
      -{
      -   group = new tizen.ContactGroup("Company");
      -   addressbook.addGroup(group)
      -   console.log("Group added with ID " + group.id);
      -}
      -
    4. - -
    5. To manage groups: - -
      • To retrieve all the contact groups from the address book, use the getGroups() method - of the AddressBook interface:

        -
        -var groups;
        -try 
        -{
        -   groups = addressbook.getGroups();
        -}
        -
      • -
      • To change the name of the group, assign the name property a new value and use the updateGroup() - method of the AddressBook interface:

        -
        -try 
        -{
        -   groups[0].name = "Friends";
        -   addressbook.updateGroup(groups[0]);
        -   console.log("First group updated");
        -}
        -
      • -
      • To retrieve a specific group, use the getGroup() method of - the AddressBook interface:

        -
        -try 
        -{
        -   group = addressbook.getGroup(group.id);
        -}
        -
      • -
      • To remove a group from the address book, use the removeGroup() method of - the AddressBook interface:

        -
        -try 
        -{
        -   addressbook.removeGroup(group.id);
        -   console.log("Group was removed");
        -}
        -
    6. -
    - -

    Managing Persons

    - -

    To create engaging applications with various contacts features, you must learn to manage persons in your contact database:

    -
      -
    1. To manage a single person: -
        -
      1. To retrieve persons, use the find() method of the ContactManager interface:

        tizen.contact.find(personsFoundCB);
      2. -
      3. Update or delete the found persons in the personsFoundCB() event handler. In this example, the favorite flag of the first person is changed and the contact is updated using the update() method. The second person is deleted using the remove() method.

        /* Define the event success callback */
        -function personsFoundCB(persons)
        -{
        -   persons[0].isFavorite = true;
        -   try
        -   {
        -      /* Update the first found person */
        -      tizen.contact.update(persons[0]);
        -
        -      /* Delete the second found person */
        -      tizen.contact.remove(persons[1].id);
        -   }
        -}
      4. -
    2. -
    3. To merge multiple persons into a single person item: -
        -
      1. Retrieve the persons as described above.
      2. -
      3. Define the persons to be merged in the personsFoundCB() event handler:

        function personsFoundCB(persons)
        -{
        -   var sourcePerson = persons[0];
        -   var targetPerson = persons[1];
      4. -
      5. Use the link() method to link contacts that are linked to the other person:

           /* Link 2 persons, contacts from sourcePerson are added to targetPerson and sourcePerson is removed */
        -   targetPerson.link(sourcePerson.id);
        -}
      6. -
    4. -
    - - - - -
    - -Go to top - - - - - - + + + + + + + + + + + + + Contact: Managing Contacts and Handling Contact Information + + + + + +
    + +

    Contact: Managing Contacts and Handling Contact Information

    + +

    This tutorial demonstrates how you can manage address books in the device to access, modify, add, and remove contacts within a specified address book on the device.

    + + + + + + + + + + +
    Note
    This feature is supported in mobile applications only.
    + +

    Warm-up

    +

    Become familiar with the Contact API basics by learning about:

    + + +

    Creating an Address Book

    + +

    Creating a new address book is a basic contact management skill:

    + + + + + + + + + + +
    Note
    The created address book is associated with a specified account. Therefore, you must retrieve the account before creating a new address book.
    +
      +
    1. Declare a variable to store the created address book: +
      var myAddressBook = null;
      +
    2. +
    3. Define a success callback for the getAccounts() method. The callback receives a list of Account objects. Use the first account ID to construct a new AddressBook object. + +

      Add the new address book to the system using the addAddressBook() method of the ContactManager interface:

      +
      function getAccountsSuccess(accounts)
      +{
      +   var account = accounts[0];
      +   if (account)
      +   {
      +      /* New address book can be created and added */
      +      myAddressBook = new tizen.AddressBook(account.id, "remote address book");
      +      tizen.contact.addAddressBook(myAddressBook);
      +      console.log("New address book created with ID=" + myAddressBook.id);
      +   }
      +}
    4. +
    5. To retrieve available accounts, use the getAccounts() method. The following method call invokes the getAccountsSuccess event handler defined above. +
      tizen.account.getAccounts(getAccountsSuccess, function(err));
      +
    6. +
    +

    Getting Address Books

    + +

    To create engaging applications with various contacts features, you must learn to access the address books in which the contacts are listed:

    +
      +
    1. To get the default address book, use the getDefaultAddressBook() method of the ContactManager interface to retrieve the default address book as an AddressBook object:

      +var myAddressbook;
      +
      +/* Get the default address book */
      +myAddressbook = tizen.contact.getDefaultAddressBook();
      +
    2. +
    3. To get all available address books, use the getAddressBooks() method. This method passes an array of AddressBook objects to the success event handler.

      +var addressBook;
      +
      +function addressBooksCB(addressBooks)
      +{
      +   if (addressBooks.length > 0)
      +   {
      +      addressBook = addressBooks[0];
      +      console.log("The addressbook name is " + addressBook.name);
      +   }
      +}
      +
      +/* Get the list of available address books */
      +tizen.contact.getAddressBooks(addressBooksCB);
      +
      +

      All available address books on the device are retrieved. You can use an AddressBook object ID to select a specific address book with the getAddressBook() method, if you know the ID of the address book in advance.

      +
    4. + +
    + +

    Adding a Contact

    + +

    To create engaging applications with various contacts features, you must learn to add a contact to an address book:

    +
      +
    1. Retrieve the default system address book using the getDefaultAddressBook() method of the ContactManager interface:

      +var addressbook = tizen.contact.getDefaultAddressBook();
      +
    2. +
    3. Create a Contact object and define its properties as a ContactInit object (the parameter of the Contact constructor):

      +var contact = new tizen.Contact
      +({
      +   name: new tizen.ContactName({firstName: "Jeffrey", lastName: "Hyman"}),
      +   emails: [new tizen.ContactEmailAddress("user@example.com")]
      +});
      +
    4. +
    5. Add the Contact object to the default address book with the add() method of the AddressBook interface:

      addressbook.add(contact);
    6. +
    + +

    Managing a Contact

    + +

    To create engaging applications with various contacts features, you must learn to manage a contact in your address book:

    +
      +
    1. To retrieve a single contact, use the get() method of the AddressBook interface with the ContactID as a parameter: +

      The following example uses the object of the ContactRef interface. The ContactRef object contains both AddressBook ID and Contact ID.

      +/* contactRef is retrieved by other APIs */
      +var contactRef;
      +try
      +{
      +   /* Retrieve the contact corresponding to the given reference */
      +   var addressBook = tizen.contact.getAddressBook(contactRef.addressBookId);
      +   var contact = addressBook.get(contactRef.contactId);
      +}
      +
    2. +
    3. To manage a single contact: +
        +
      1. Retrieve the default address book using the getDefaultAddressBook() method of the ContactManager interface.

        +var addressbook = tizen.contact.getDefaultAddressBook();
        +
      2. +
      3. Retrieve contacts stored in the address book by using the find() method of the AddressBook interface:

        +var filter = new tizen.AttributeFilter("name.firstName", "CONTAINS", "Chris");
        +var sortMode = new tizen.SortMode("name.lastName", "ASC");
        +
        +try
        +{
        +   addressbook.find(contactsFoundCB, null, filter, sortMode);
        +}
        + + + + + + + + + +
        Note
        To retrieve a specific contact, you can specify a filter and sorting order for the search operation through the filter and sortMode parameters (for attributes supported in the filter, see Contact Filter Attributes).

        In this example, contacts whose first name contains "Chris" are retrieved and sorted in the ascending order based on their last name. The filter includes the standard English characters in the uppercase and lowercase. The entire list consists of ASCII characters from 32 to 126, and from 160 to 255.

        The contacts that match the filter are passed as an array to the registered success event handler in the selected sorting order.

      4. +
      5. Update or delete the found contact inside the contactsFoundCB event handler.

        In this example, the first name of the first contact is changed and the contact is updated in the address book using the update() method. The second contact is deleted using the remove() method.

        /* Define the event success callback */
        +function contactsFoundCB(contacts)
        +{
        +   contacts[0].name.firstName = "Christopher";
        +   try
        +   {
        +      /* Update the first found contact */
        +      addressbook.update(contacts[0]);
        +
        +      /* Delete the second found contact */
        +      addressbook.remove(contacts[1].id);
        +   }
        +}
      6. +
    4. +
    + +

    Receiving Notifications on Contact Changes

    + +

    To create engaging applications with various contacts features, you must learn to receive notifications when contacts are added, updated, or removed:

    +
      +
    1. Define the needed variables:

      +/* Watcher identifier */
      +var watcherId = 0;
      +
      +/* This example assumes that the address book is initialized */
      +var addressbook;
      +
    2. +
    3. Define the event handlers for different notifications about changes in the selected address book using the AddressBookChangeCallback listener interface:

      +var watcher =
      +{
      +   /* When contacts are added */
      +   oncontactsadded: function(contacts)
      +   {
      +      console.log(contacts.length + " contacts were added");
      +   },
      +
      +   /* When contacts are updated */
      +   oncontactsupdated: function(contacts)
      +   {
      +      console.log(contacts.length + " contacts were updated");
      +   },
      +
      +   /* When contacts are deleted */
      +   oncontactsremoved: function(ids)
      +   {
      +      console.log(ids.length + " contacts were deleted");
      +   }
      +};
      +
    4. +
    5. Register the listener to use the defined event handlers:

      +watcherId = addressbook.addChangeListener(watcher);
      +
    6. +
    7. To stop the notifications, use the removeChangeListener() method of the AddressBook interface:

      +addressbook.removeChangeListener(watcherId);
      +
    8. +
    + +

    Importing Contacts

    + +

    To create engaging applications with various contacts features, you must learn to import contacts with the help of the vCard format:

    + +
      +
    1. Retrieve the default system address book using the getDefaultAddressBook() method of the ContactManager interface:

      +var addressbook = tizen.contact.getDefaultAddressBook();
      +
    2. +
    3. Create a new Contact object from the vCard string and add it to the default address book:

      +var contact = null;
      +
      +try
      +{
      +   contact = new tizen.Contact("BEGIN:VCARD\n"+
      +                               "VERSION:3.0\n"+
      +                               "N:Gump;Forrest\n"+
      +                               "FN:Forrest Gump\n"+
      +                               "ORG:Bubba Gump Shrimp Co.\n"+
      +                               "TITLE:Shrimp Man\n"+
      +                               "TEL;WORK:(111) 555-1212\n"+
      +                               "TEL;HOME:(404) 555-1212\n"+
      +                               "EMAIL;WORK;PREF:forrestgump@example.com\n"+
      +                               "END:VCARD");
      +
      +   addressbook.add(contact);
      +   console.log("Contact was added with ID " + contact.id);
      +}
    4. +

    To convert multiple strings and import them to an address book, convert the strings one by one and then use the addBatch() method of the AddressBook interface to add all the contacts at once in the batch mode.

    + +

    Exporting Contacts

    + +

    To create engaging applications with various contacts features, you must learn to export contacts with the help of the vCard format:

    +
      +
    1. Retrieve the default system address book using the getDefaultAddressBook() method of the ContactManager interface and find all contacts with "Chris" in the first name:

      +var addressbook;
      +
      +var addressbook = tizen.contact.getDefaultAddressBook();
      +
      +/* Define a filter */
      +var filter = new tizen.AttributeFilter("name.firstName", "CONTAINS", "Chris");
      +
      +/* Search for the contacts */
      +addressbook.find(contactsFoundCB, errorCB, filter);
      +
    2. +
    3. Convert a contact to a vCard string in the success event handler of the find() method.

      In the following example, the first found contact is exported by converting it to the vCard version 3.0 format.

      +function contactsFoundCB(contacts)
      +{
      +   /* Convert the first contact */
      +   var vcard = contacts[0].convertToString("VCARD_30");
      +}
    4. +
    + +

    Adding Multiple Contacts in the Batch Mode

    + +

    To create engaging applications with various contacts features, you must learn to add multiple contacts to an address book in the batch mode:

    +
      +
    1. Retrieve the default system address book using the getDefaultAddressBook() method of the ContactManager interface:

      +addressbook = tizen.contact.getDefaultAddressBook();
      +
    2. +
    3. Define the items to be added as an array:

      +var c1 = new tizen.Contact(
      +{
      +   name: new tizen.ContactName({firstName:"Jeffrey", lastName:"Hyman"}),
      +   emails: [new tizen.ContactEmailAddress("user1@example.com")]
      +});
      +
      +var c2 = new tizen.Contact(
      +{
      +   name: new tizen.ContactName({firstName:"Elton", lastName:"John"}),
      +   emails: [new tizen.ContactEmailAddress("user2@example.com")]
      +});
      +
    4. +
    5. Use the addBatch() method of the AddressBook interface to add the contacts in the array to the address book:

      +addressbook.addBatch([c1, c2]);
      +
      + + + + + + + + + +
      Note
      The addBatch(), updateBatch(), and removeBatch() methods are asynchronous. Provide success and error callbacks with them.
      +
    6. +
    + +

    Managing Multiple Contacts in the Batch Mode

    + +

    To create engaging applications with various contacts features, you must learn to manage multiple contacts in your address books in the batch mode:

    +
      +
    1. Retrieve the default address book using the getDefaultAddressBook() method of the ContactManager interface.

      +var addressbook = tizen.contact.getDefaultAddressBook();
      +
    2. +
    3. Retrieve contacts stored in the address book by using the find() method of the AddressBook interface:

      +var filter = new tizen.AttributeFilter("name.firstName", "CONTAINS", "Chris"};
      +var sortMode = new tizen.SortMode("name.lastName", "ASC");
      +
      +try
      +{
      +   addressbook.find(contactsFoundCB, null, filter, sortMode);
      +}
    4. +
    5. To update contacts: +
        +
      1. Define the contact changes to be made in the success event handler of the find() method:

        +function contactsFoundCB(contacts)
        +{
        +   /* Change the first names of all the found contacts */
        +   for (var i=0; i<contacts.length; i++)
        +   {
        +      contacts[i].name.firstName = "Christopher";
        +   }
        +
      2. +
      3. Use the updateBatch() method to update multiple contacts asynchronously:

        +   /* Update all found contacts */
        +   addressbook.updateBatch(contacts);
        +}
        +
      4. +
    6. +
    7. To delete contacts, use the removeBatch() method in the success event handler of the find() method to delete multiple contacts asynchronously:

      +function contactsFoundCB(contacts)
      +{
      +   /* Delete the first 2 found contacts */
      +   addressbook.removeBatch([contacts[0].id, contacts[1].id]);
      +}
      +
    8. +
    + +

    Managing Contact Groups

    + +

    To create engaging applications with various contact features, you must learn to manage contact groups:

    +
      +
    1. Retrieve the default system address book using the getDefaultAddressBook() method of the ContactManager interface:

      +
      +var addressbook = tizen.contact.getDefaultAddressBook();
    2. +
    3. To create a ContactGroup object and add the newly create group to the system, use the constructor and the addGroup() method of the AddressBook interface:

      +
      +var group;
      +try 
      +{
      +   group = new tizen.ContactGroup("Company");
      +   addressbook.addGroup(group)
      +   console.log("Group added with ID " + group.id);
      +}
      +
    4. + +
    5. To manage groups: + +
      • To retrieve all the contact groups from the address book, use the getGroups() method + of the AddressBook interface:

        +
        +var groups;
        +try 
        +{
        +   groups = addressbook.getGroups();
        +}
        +
      • +
      • To change the name of the group, assign the name property a new value and use the updateGroup() + method of the AddressBook interface:

        +
        +try 
        +{
        +   groups[0].name = "Friends";
        +   addressbook.updateGroup(groups[0]);
        +   console.log("First group updated");
        +}
        +
      • +
      • To retrieve a specific group, use the getGroup() method of + the AddressBook interface:

        +
        +try 
        +{
        +   group = addressbook.getGroup(group.id);
        +}
        +
      • +
      • To remove a group from the address book, use the removeGroup() method of + the AddressBook interface:

        +
        +try 
        +{
        +   addressbook.removeGroup(group.id);
        +   console.log("Group was removed");
        +}
        +
    6. +
    + +

    Managing Persons

    + +

    To create engaging applications with various contacts features, you must learn to manage persons in your contact database:

    +
      +
    1. To manage a single person: +
        +
      1. To retrieve persons, use the find() method of the ContactManager interface:

        tizen.contact.find(personsFoundCB);
      2. +
      3. Update or delete the found persons in the personsFoundCB() event handler. In this example, the favorite flag of the first person is changed and the contact is updated using the update() method. The second person is deleted using the remove() method.

        /* Define the event success callback */
        +function personsFoundCB(persons)
        +{
        +   persons[0].isFavorite = true;
        +   try
        +   {
        +      /* Update the first found person */
        +      tizen.contact.update(persons[0]);
        +
        +      /* Delete the second found person */
        +      tizen.contact.remove(persons[1].id);
        +   }
        +}
      4. +
    2. +
    3. To merge multiple persons into a single person item: +
        +
      1. Retrieve the persons as described above.
      2. +
      3. Define the persons to be merged in the personsFoundCB() event handler:

        function personsFoundCB(persons)
        +{
        +   var sourcePerson = persons[0];
        +   var targetPerson = persons[1];
      4. +
      5. Use the link() method to link contacts that are linked to the other person:

           /* Link 2 persons, contacts from sourcePerson are added to targetPerson and sourcePerson is removed */
        +   targetPerson.link(sourcePerson.id);
        +}
      6. +
    4. +
    + + + + +
    + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.tutorials/html/web/tizen/social/data_sync_tutorial_w.htm b/org.tizen.tutorials/html/web/tizen/social/data_sync_tutorial_w.htm index 0fdf709..dd624a5 100644 --- a/org.tizen.tutorials/html/web/tizen/social/data_sync_tutorial_w.htm +++ b/org.tizen.tutorials/html/web/tizen/social/data_sync_tutorial_w.htm @@ -1,128 +1,128 @@ - - - - - - - - - - - - - Data Synchronization: Creating a Sync Profile and Synchronizing Device Data - - - - - -
    - -

    Data Synchronization: Creating a Sync Profile and Synchronizing Device Data

    - -

    This tutorial demonstrates how you can synchronize device data, such as contacts and calendar events, with the OMA DS server.

    - - - - - - - - - - -
    Note
    This feature is supported in mobile applications only.
    - -

    Warm-up

    -

    Become familiar with the Data Synchronization API basics by learning about:

    - - -

    Creating a Sync Profile

    - -

    To be able to synchronize your device data, such as contacts and calendar events, with the OMA DS server, you must learn how to create a sync profile:

    -
      -
    1. Check whether there are available profile slots on the device:

      -var numMaxProfiles = tizen.datasync.getMaxProfilesNum();
      -var numProfiles = tizen.datasync.getProfilesNum();
      -
    2. -
    3. Create a sync profile. Use the SyncInfo, SyncServiceInfo, and SyncProfileInfo interfaces to provide sync profile and operation information:

      -if ((numMaxProfiles <= 0) || (numProfiles < numMaxProfiles))
      -{
      -   var syncInfo = new tizen.SyncInfo("http://example.com/sync", "myId", "myPassword", "MANUAL", "TWO_WAY");
      -   var contactInfo = new tizen.SyncServiceInfo(true, "CONTACT", "serverContact");
      -   var eventInfo = new tizen.SyncServiceInfo(true, "EVENT", "serverEvent");
      -   var serviceInfo = [contactInfo, eventInfo];
      -   var profile = new tizen.SyncProfileInfo("MyProfile", syncInfo, serviceInfo);
      -
    4. -
    5. To be able to use the created profile, add it to your device using the add() method of the DataSynchronizationManager interface:

      -   tizen.datasync.add(profile);
      -   var profileId = profile.profileId;
      -}
    6. -
    - -

    Starting and Monitoring Data Synchronization

    - -

    Learning how to start and monitor the data synchronization process is a basic data management skill:

    -
      -
    1. Define the event handlers for the notifications using the SyncProgressCallback listener interface:

      -var syncCallback =
      -{
      -   onprogress: function(profileId, serviceType, isFromServer, totalPerType, syncedPerType)
      -   {
      -      console.log('Total: ' + totalPerType + ', synced: ' + syncedPerType + ' for the sync type: ' + serviceType);
      -   },
      -   onfailed: function(profileId, error)
      -   {
      -      console.log('Failed with id: ' + profileId + ', error name: ' + error.name);
      -   }
      -};
      -
    2. -
    3. Start the sync operation using the startSync() method, with the corresponding listener as a parameter:

      -tizen.datasync.startSync(profileId, syncCallback);
      -
    4. -
    - - - - - -
    - -Go to top - - - - - - + + + + + + + + + + + + + Data Synchronization: Creating a Sync Profile and Synchronizing Device Data + + + + + +
    + +

    Data Synchronization: Creating a Sync Profile and Synchronizing Device Data

    + +

    This tutorial demonstrates how you can synchronize device data, such as contacts and calendar events, with the OMA DS server.

    + + + + + + + + + + +
    Note
    This feature is supported in mobile applications only.
    + +

    Warm-up

    +

    Become familiar with the Data Synchronization API basics by learning about:

    + + +

    Creating a Sync Profile

    + +

    To be able to synchronize your device data, such as contacts and calendar events, with the OMA DS server, you must learn how to create a sync profile:

    +
      +
    1. Check whether there are available profile slots on the device:

      +var numMaxProfiles = tizen.datasync.getMaxProfilesNum();
      +var numProfiles = tizen.datasync.getProfilesNum();
      +
    2. +
    3. Create a sync profile. Use the SyncInfo, SyncServiceInfo, and SyncProfileInfo interfaces to provide sync profile and operation information:

      +if ((numMaxProfiles <= 0) || (numProfiles < numMaxProfiles))
      +{
      +   var syncInfo = new tizen.SyncInfo("http://example.com/sync", "myId", "myPassword", "MANUAL", "TWO_WAY");
      +   var contactInfo = new tizen.SyncServiceInfo(true, "CONTACT", "serverContact");
      +   var eventInfo = new tizen.SyncServiceInfo(true, "EVENT", "serverEvent");
      +   var serviceInfo = [contactInfo, eventInfo];
      +   var profile = new tizen.SyncProfileInfo("MyProfile", syncInfo, serviceInfo);
      +
    4. +
    5. To be able to use the created profile, add it to your device using the add() method of the DataSynchronizationManager interface:

      +   tizen.datasync.add(profile);
      +   var profileId = profile.profileId;
      +}
    6. +
    + +

    Starting and Monitoring Data Synchronization

    + +

    Learning how to start and monitor the data synchronization process is a basic data management skill:

    +
      +
    1. Define the event handlers for the notifications using the SyncProgressCallback listener interface:

      +var syncCallback =
      +{
      +   onprogress: function(profileId, serviceType, isFromServer, totalPerType, syncedPerType)
      +   {
      +      console.log('Total: ' + totalPerType + ', synced: ' + syncedPerType + ' for the sync type: ' + serviceType);
      +   },
      +   onfailed: function(profileId, error)
      +   {
      +      console.log('Failed with id: ' + profileId + ', error name: ' + error.name);
      +   }
      +};
      +
    2. +
    3. Start the sync operation using the startSync() method, with the corresponding listener as a parameter:

      +tizen.datasync.startSync(profileId, syncCallback);
      +
    4. +
    + + + + + +
    + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.tutorials/html/web/tizen/social/social_tutorials_w.htm b/org.tizen.tutorials/html/web/tizen/social/social_tutorials_w.htm index 42d77f2..01267bc 100644 --- a/org.tizen.tutorials/html/web/tizen/social/social_tutorials_w.htm +++ b/org.tizen.tutorials/html/web/tizen/social/social_tutorials_w.htm @@ -1,79 +1,79 @@ - - - - - - - - - - - - - Social: Managing Personal Data - - - -
    -
    -

    Mobile Web

    -
    -
    -

    Related Info

    - -
    -
    - -
    - -

    Social: Managing Personal Data

    - - - - - - - - - - -
    Note
    The Social API domain is supported in mobile applications only.
    - -

    The social data tutorials demonstrate how to use the following features in creating Tizen Web applications:

    - - - - - - -
    - -Go to top - - - - - - + + + + + + + + + + + + + Social: Managing Personal Data + + + +
    +
    +

    Mobile Web

    +
    +
    +

    Related Info

    + +
    +
    + +
    + +

    Social: Managing Personal Data

    + + + + + + + + + + +
    Note
    The Social API domain is supported in mobile applications only.
    + +

    The social data tutorials demonstrate how to use the following features in creating Tizen Web applications:

    + + + + + + +
    + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.tutorials/html/web/tizen/system/system_tutorials_w.htm b/org.tizen.tutorials/html/web/tizen/system/system_tutorials_w.htm index 79f3b5c..5f885ac 100644 --- a/org.tizen.tutorials/html/web/tizen/system/system_tutorials_w.htm +++ b/org.tizen.tutorials/html/web/tizen/system/system_tutorials_w.htm @@ -43,7 +43,7 @@
  • Time: Exposing Information about Date, Time, and Time Zones

    Demonstrates how you can manage date and time information.

  • -

    The following tutorials apply in mobile applications only:

    +

    The following tutorials apply in mobile applications only:

    + +

    For more information about implementing the UI for your application using the Advanced UI Framework (TAU) features, see TAU.

    +

    In addition to the Tizen Web Device API tutorials above, you can implement the following features:

    diff --git a/org.tizen.tutorials/html/web/tutorials_w.htm b/org.tizen.tutorials/html/web/tutorials_w.htm index 6d1ac08..6359524 100644 --- a/org.tizen.tutorials/html/web/tutorials_w.htm +++ b/org.tizen.tutorials/html/web/tutorials_w.htm @@ -41,7 +41,7 @@ Note - The API support differs based on the application profile (mobile or wearable). For a complete list of APIs and their supported profiles, see Tizen Web Device API Reference, W3C/HTML5 and Supplementaries API Reference, and Tizen Web UI Framework Reference. + The API support differs based on the application profile (mobile or wearable). For a complete list of APIs and their supported profiles, see Tizen Web Device API Reference and W3C/HTML5 and Supplementaries API Reference. diff --git a/org.tizen.tutorials/html/web/w3c/communication/comm_tutorials_w.htm b/org.tizen.tutorials/html/web/w3c/communication/comm_tutorials_w.htm index 3a91d89..aa7266a 100644 --- a/org.tizen.tutorials/html/web/w3c/communication/comm_tutorials_w.htm +++ b/org.tizen.tutorials/html/web/w3c/communication/comm_tutorials_w.htm @@ -41,7 +41,7 @@
  • XMLHttpRequest Level 1 and 2: Communicating with the Server

    Demonstrates how you can communicate with a Web server using HTTP requests.

  • -

    The following tutorials apply in mobile applications only:

    +

    The following tutorials apply in mobile applications only:

    @@ -57,15 +57,15 @@
    - diff --git a/org.tizen.tutorials/html/web/w3c/communication/server_sent_tutorial_w.htm b/org.tizen.tutorials/html/web/w3c/communication/server_sent_tutorial_w.htm index 1b6d715..d26ec30 100644 --- a/org.tizen.tutorials/html/web/w3c/communication/server_sent_tutorial_w.htm +++ b/org.tizen.tutorials/html/web/w3c/communication/server_sent_tutorial_w.htm @@ -168,15 +168,15 @@
    - diff --git a/org.tizen.tutorials/html/web/w3c/communication/web_messaging_tutorial_w.htm b/org.tizen.tutorials/html/web/w3c/communication/web_messaging_tutorial_w.htm index 3914590..78b599b 100644 --- a/org.tizen.tutorials/html/web/w3c/communication/web_messaging_tutorial_w.htm +++ b/org.tizen.tutorials/html/web/w3c/communication/web_messaging_tutorial_w.htm @@ -171,15 +171,15 @@
    - diff --git a/org.tizen.tutorials/html/web/w3c/communication/websocket_tutorial_w.htm b/org.tizen.tutorials/html/web/w3c/communication/websocket_tutorial_w.htm index 04be639..503f642 100644 --- a/org.tizen.tutorials/html/web/w3c/communication/websocket_tutorial_w.htm +++ b/org.tizen.tutorials/html/web/w3c/communication/websocket_tutorial_w.htm @@ -202,15 +202,15 @@ function closeConnection() - diff --git a/org.tizen.tutorials/html/web/w3c/communication/xmlhttprequest_tutorial_w.htm b/org.tizen.tutorials/html/web/w3c/communication/xmlhttprequest_tutorial_w.htm index 652fe9e..530df2e 100644 --- a/org.tizen.tutorials/html/web/w3c/communication/xmlhttprequest_tutorial_w.htm +++ b/org.tizen.tutorials/html/web/w3c/communication/xmlhttprequest_tutorial_w.htm @@ -312,15 +312,15 @@ - diff --git a/org.tizen.tutorials/html/web/w3c/device/device_tutorials_w.htm b/org.tizen.tutorials/html/web/w3c/device/device_tutorials_w.htm index afee198..211cdaf 100644 --- a/org.tizen.tutorials/html/web/w3c/device/device_tutorials_w.htm +++ b/org.tizen.tutorials/html/web/w3c/device/device_tutorials_w.htm @@ -40,7 +40,7 @@
  • Touch Events version 1: Controlling Touch Events

    Demonstrates how you can use touch events.

  • Vibration: Managing the Vibration Mechanism

    Demonstrates how you can launch and stop vibration on Tizen devices.

  • -

    The following tutorials apply in mobile applications only:

    +

    The following tutorials apply in mobile applications only:

    • HTML5 Browser state: Monitoring Browser Network Connection

      Demonstrates how you can access the browser connection state.

    • Screen Orientation: Managing Screen Orientation State

      Demonstrates how you can detect rotation and acceleration motions on the device.

    • diff --git a/org.tizen.tutorials/html/web/w3c/device/task_compass_w.htm b/org.tizen.tutorials/html/web/w3c/device/task_compass_w.htm index 64218da..81e3254 100644 --- a/org.tizen.tutorials/html/web/w3c/device/task_compass_w.htm +++ b/org.tizen.tutorials/html/web/w3c/device/task_compass_w.htm @@ -154,7 +154,7 @@ else angleMemory = angle; -
    • The needle position is updated by rotating the needle with the rotate() method of the transform function, based on the angle calculated above.

      +
    • The needle position is updated by rotating the needle with the rotate() method of the transform function, based on the angle calculated above.

      $('#direction').text(text);
      diff --git a/org.tizen.tutorials/html/web/w3c/dom/animation_tutorial_w.htm b/org.tizen.tutorials/html/web/w3c/dom/animation_tutorial_w.htm
      deleted file mode 100644
      index a86b60e..0000000
      --- a/org.tizen.tutorials/html/web/w3c/dom/animation_tutorial_w.htm
      +++ /dev/null
      @@ -1,220 +0,0 @@
      -
      -
      -
      -	
      -	
      -	
      -	
      -		
      -	
      -	
      -	
      -	
      -
      -	CSS Animations Module Level 3: Creating Animations  
      -
      -
      -
      -
      -	
      -
      -
      -

      CSS Animations Module Level 3: Creating Animations

      - - -

      This tutorial demonstrates how you can create animations in your application.

      - - -

      Warm-up

      -

      Become familiar with the CSS Animations Module Level 3 API basics by learning about:

      - - -

      Creating a Logo Animation

      - -

      To enhance the user experience of your application, you must learn to create a logo animation, where element properties can be assigned and changed for each element and keyframe. The logo animation is similar to the animation that appears when a Tizen device (or Emulator) is switched on:

      - -
        -
      1. No elements are initially shown on the screen.
      2. -
      3. The Tizen logo gradually appears in the middle of the screen, and as it moves to the right, it becomes smaller.
      4. -
      5. Each letter in the word "TIZEN" consecutively comes in from the left of the screen and moves to the right to its correct location.
      6. -
      -

      Figure: Logo animation (in mobile applications only)

      -

      Logo animation

      -

      To create a logo animation:

      -
        -
      1. Create the HTML layout for the animation. To be able to manage the movement of each animation part separately, you must define individual elements for each part. -
        -<div class="animation-holder">
        -   <span class="tizen-txt t"></span>
        -   <span class="tizen-txt i"></span>
        -   <span class="tizen-txt z"></span>
        -   <span class="tizen-txt e"></span>
        -   <span class="tizen-txt n"></span>
        -   <span class="tizen-txt tm"></span>
        -   <span class="tizen-logo"></span>
        -</div>
        -
        -
      2. -
      3. Define the basic style for the animation: -
        -.example-body {width: 320px; height: 480px; background: #000; margin: 0 auto; 
        -               position: relative; border: 2px solid #fff; overflow: hidden;}
        -.animation-holder {width: 280px; height: 88px; position: absolute; 
        -                   left: 50%; top: 50%; margin: -54px 0 0 -140px;} 
        -
        -.tizen-txt, .tizen-logo {position: absolute; display: block; 
        -                         background-repeat: no-repeat; background-position: 50% 50%}
        -.tizen-txt.t {width: 48px; height: 56px; background-image: url(images/txt_t.png);}
        -.tizen-txt.i {width: 15px; height: 56px; background-image: url(images/txt_i.png);}
        -.tizen-txt.z {width: 46px; height: 56px; background-image: url(images/txt_z.png);}
        -.tizen-txt.e {width: 45px; height: 56px; background-image: url(images/txt_e.png);}
        -.tizen-txt.n {width: 54px; height: 58px; background-image: url(images/txt_n.png);}
        -.tizen-txt.tm {width: 11px; height: 6px; background-image: url(images/txt_tm.png);}
        -.tizen-logo {width: 220px; height: 211px; left: 30px; top: -61px; 
        -             background-image: url(images/logo_tizen.png); background-size: 100% 100%;}
        -
        -
      4. -
      5. Create the animation: -
          -
        1. To ensure that all the animation elements are played within the same time frame, some common properties are defined for the animation. The animation movement time is 7 seconds, and the animation repeats infinitely. -

          When an animation that repeats itself is activated, it can look unnatural when it suddenly returns to its initial position after finishing an iteration. To make the repetition move naturally, set the animation-direction property to alternate. The alternate direction means that during the odd iterations the animation proceeds in the normal direction (from the 0% keyframe to the 100% keyframe), while during the even iterations the keyframes are played in the opposite direction from 100% to 0%.

          -
          -.tizen-txt, .tizen-logo 
          -{
          -   -webkit-animation-duration: 7s;
          -   -webkit-animation-iteration-count: infinite;
          -   -webkit-animation-direction: alternate;
          -}
          -
          -
        2. -
        3. Create the keyframes to implement the flow for the Tizen logo: -
            -
          • During the first 25% of the animation total playing time (7 seconds), the transparency disappears and the Tizen logo appears.
          • -
          • During the 25 - 50% of the playing time, the logo size becomes smaller as the width and height values are reduced, and due to the left and top value, the logo is positioned to the top right corner of the screen.
          • -
          • During the 50 - 100% of the playing time, the values do not change, and the logo remains in its new position.
          • -
          -

          -
          -@-webkit-keyframes tizen-logo 
          -{
          -   0% {width: 220px; height: 211px; left: 30px; top: -61px; opacity: 0;}
          -   25% {width: 220px; height: 211px; left: 30px; top: -61px; opacity: 1;}
          -   50% {left: 247px; top: 0px; width: 33px; height: 32px; opacity: 1;}
          -   100% {left: 247px; top: 0px; width: 33px; height: 32px; opacity: 1;}
          -}
          -
          - - - - - - - - - - -
          Note
          If the 100% keyframe is not defined, the animation is executed based on the original properties, and the logo size increases to its original size at the end.
        4. -
        5. Create the keyframes to implement the flow for each letter in the word "TIZEN": -
            -
          • To hide the letter initially, the property has been assigned outside the screen at the 0% keyframe. To allow the Tizen logo to appear first, the first letter is introduced at the 30% keyframe.
          • -
          • To create a slight collision animation, the letter element moves to -10 px of the final value at the 40% keyframe before reaching its final 0 px value at the 45% keyframe.
          • -
          • The animation-timing-function property can be changed for each keyframe point, and is used to determine the pace of the animation. When the letter is actually shown on the screen and moved to its final location, the ease in and out timing functions are used.
          • -
          - -

          To show the letters one at a time, the timing is pushed back a bit more for each consecutive letter:

          -
          -<!--Letter T-->
          -@-webkit-keyframes tizen-txt-t 
          -{
          -   0% {left: 340px; top: 31px;}
          -   30% {left: 340px; top: 31px; animation-timing-function: ease-in;}
          -   40% {left: -10px; top: 31px; animation-timing-function: ease-out;}
          -   45% {left: 0; top: 31px;}
          -   100% {left: 0; top: 31px;}
          -}
          -
          -<!--Letter I-->
          -@-webkit-keyframes tizen-txt-i 
          -{
          -   0% {left: 340px; top: 31px;}
          -   40% {left: 340px; top: 31px; animation-timing-function: ease-in;}
          -   50% {left: 47px; top: 31px; animation-timing-function: ease-out;}
          -   55% {left: 57px; top: 31px;}
          -   100% {left: 57px; top: 31px;}
          -}
          -
          -<!--Remaining letters-->
          -
        6. - -
        7. After creating all the keyframes, define the animation-name property for each element:

          -
          -.tizen-txt.t 
          -{
          -   -webkit-animation-name: tizen-txt-t;
          -}
          -.tizen-txt.i 
          -{
          -   -webkit-animation-name: tizen-txt-i;
          -}
          -
        8. - -
      -

      Source Code

      -

      For the complete source code related to this use case, see the following files:

      - - - - - - - -
      - -Go to top - - - - - - - diff --git a/org.tizen.tutorials/html/web/w3c/dom/background_tutorial_w.htm b/org.tizen.tutorials/html/web/w3c/dom/background_tutorial_w.htm deleted file mode 100644 index b44ad7d..0000000 --- a/org.tizen.tutorials/html/web/w3c/dom/background_tutorial_w.htm +++ /dev/null @@ -1,132 +0,0 @@ - - - - - - - - - - - - - - CSS Backgrounds and Borders Module Level 3: Specifying Background and Border Styles - - - - - - -
      -

      CSS Backgrounds and Borders Module Level 3: Specifying Background and Border Styles

      - -

      This tutorial demonstrates how you can create a background for your application.

      - - -

      Warm-up

      -

      Become familiar with the CSS Backgrounds and Borders Module Level 3 API basics by learning about:

      - - -

      Creating Backgrounds

      -

      To enhance the user experience of your application, you must learn to create a multilayer background with the parallax effect using the CSS box model. The background consists of 3 images on separate layers, and 2 of the layers can be moved over each other.

      - -

      Figure: Background with the parallax effect

      -

      Background with the parallax effect

      - -
      1. Prepare 3 images (tizen.png, tizen2.png, and dot.png), each with a transparent background. - -

        tizen.png, tizen2.png, and dot.png images

      2. - -
      3. Create a div element with id="parallelexample" and a slider input element with the minimum, maximum, and initial value: -
        -<div id="parallelexample"></div>
        -<input id="position" type="range" min="1" max="200" value="50">
        -
      4. - -
      5. Define the needed styles for the div element in the <head> section using the parallelexample ID. -

        Define a background using the prepared images in the correct order. The images are shown in the order they have been added, with the first image on the topmost layer. Use the same order when defining the background position for each image.

        -
        -#parallelexample
        -{
        -   width: 300px;
        -   height: 300px;
        -   background-image: url(tizen2_32.png), url(tizen3_32.png), url(dot.png);
        -   background-position: 6.25em 8em, 3.125em 4em, center top;
        -   background-repeat: repeat, repeat, repeat;
        -   border: 1px solid black;
        -   margin: 0px auto;
        -}
        -
      6. -
      7. To create the parallax effect, create a method that moves the background layers by changing the horizontal position values of the images in the div element. To determine the position value change, add an onchange event handler for the slider to determine the change based on the slider handle movement. -
        -function moveLayers() 
        -{
        -   /* Get slider value */
        -   var poz = document.getElementById('position');
        -   /* Get the div element */
        -   var example = document.getElementById('ParallaxExamle');
        -   /* Add the event handler */
        -   poz.onchange = function()
        -   {
        -      var layer1 = this.value/8, layer2 = this.value/16;
        -      example.style.backgroundPosition = layer1 +'em 8em, ' 
        -                                         + layer2 + 'em 4em, center top';
        -   }
        -}
        -
      -

      Source Code

      -

      For the complete source code related to this use case, see the following files:

      - - - - - - - -
      - -Go to top - - - - - - - diff --git a/org.tizen.tutorials/html/web/w3c/dom/basic_ui_tutorial_w.htm b/org.tizen.tutorials/html/web/w3c/dom/basic_ui_tutorial_w.htm deleted file mode 100644 index 0513c78..0000000 --- a/org.tizen.tutorials/html/web/w3c/dom/basic_ui_tutorial_w.htm +++ /dev/null @@ -1,189 +0,0 @@ - - - - - - - - - - - - - - CSS Basic User Interface Module Level 3 (CSS3 UI): Applying Styles to HTML Documents - - - - - - -
      -

      CSS Basic User Interface Module Level 3 (CSS3 UI): Applying Styles to HTML Documents

      - - -

      This tutorial demonstrates how you can change the Web form UI and control the box model in HTML documents.

      - -

      Warm-up

      -

      Become familiar with the CSS Basic User Interface Module Level 3 (CSS3 UI) API basics by learning about:

      - - - -

      Using Pseudo-element Selectors

      - -

      To enhance the user experience of your application, you must learn how to use pseudo-element selectors:

      -
        -
      1. Use the pseudo-classes, such as :enabled and :disabled, to add different styles based on the state of the DOM elements:

        -
        input: enabled {border: 1px solid blue}
        -input: disabled {border: 1px solid red}
        - - - - - - - - - -
        Note
        In the versions prior to CSS3, pseudo-elements, such as :hover, :active, and :focus, were used, and required an attribute selector. Since the :enabled and :disabled classes are not influenced by the display and visibility attributes, they improve the accessibility.
      2. -
      3. To control the state of the HTML5 Web Forms (in mobile or wearable applications), use the :in-range and :out-of-range pseudo-classes. -

        They check for any values that have exceeded the inserted range. (The following figure applies to mobile applications only.)

        -
        -<!--HTML--> 
        -<input type="number" step="10" min="10" max="100">
        -
        -
        -<!--CSS-->
        -input[type="number"]: in-range {border: 3px solid blue; width: 90%}
        -input[type="number"]: out-of-range {border: 3px solid red; width: 90%}
        -
        -

        Element ranges (in mobile applications only)

      4. -
      5. To apply different styles to required input items and option items, use the :required and :optional pseudo-classes. (The following figure applies to mobile applications only.) -
        -<!--HTML-->
        -<fieldset>
        -   <legend>required and optional</legend>
        -   <label>email: <input type="email" required></label>
        -   <label>password: <input type="Password" placeholder="required area" required></label>
        -
        -   <label>date: <input type="date" placeholder="You know what to do, huh?"></label>
        -   <textarea placeholder="Comment"></textarea>
        -</fieldset>
        -
        -<!--CSS-->
        -input: required, textarea: required {border: 1px solid red}
        -input: optional, textarea: optional {border: 1px solid #777}
        -
        -

        Required and optional elements (in mobile applications only)

      - -

      Source Code

      -

      For the complete source code related to this use case, see the following files:

      - - -

      Using Box Model Properties

      - -

      To enhance the user experience of your application, you must learn how to use box model properties:

      - - - - - - - - - -
      Note
      The properties dependent on mouse and keyboard functions are not discussed in this tutorial.
      -
        -
      1. To assign the area that is included in the width and height of the box automatically, use the box-sizing property. To assign the width without a margin, use the box-sizing: border-box property. -
        -div.content-box {box-sizing: content-box} <!--width (height) = content-->
        -div.border-box {box-sizing: border-box} <!--width (height) = content + padding + border-->
        -div.border-box: before {height: 40px}
        -
      2. - -
      3. To draw an outline without using up the area, use the outline property: -
        -.Test-Box {outline: 5px dashed red}
        -.outline: before {outline: 2px dashed red}
        -.outline-offset: before {outline-offset: 35px}
        -
      4. - -
      5. To handle text that exceeds the area of the box model, use the text-overflow property. The text-overflow: ellipsis property is used to indicate the text exceeded the padding area as '...'. -
        div 
        -{
        -   width: 250px;
        -   margin: 20px auto;
        -   padding: 20px 30px;
        -   background-color: #eee;
        -   color: #333;
        -   border: 5px solid #333;
        -   font-weight: bold;
        -   overflow: hidden;
        -   white-space: nowrap;
        -}
        -
        -.clip {text-overflow: clip}
        -.ellipsis {text-overflow: ellipsis}
      6. -
      - -

      The following figure illustrates the box model properties; from left to right, it shows the effects of the box sizing, outline, and text overflow properties.

      -

      Figure: Box model properties (in mobile applications only)

      -

      Box model properties (in mobile applications only)

      - -

      Source Code

      -

      For the complete source code related to this use case, see the following files:

      - - - - - - -
      - -Go to top - - - - - - - diff --git a/org.tizen.tutorials/html/web/w3c/dom/color_tutorial_w.htm b/org.tizen.tutorials/html/web/w3c/dom/color_tutorial_w.htm deleted file mode 100644 index c1439a9..0000000 --- a/org.tizen.tutorials/html/web/w3c/dom/color_tutorial_w.htm +++ /dev/null @@ -1,148 +0,0 @@ - - - - - - - - - - - - - - CSS Color Module Level 3: Specifying Color and Opacity - - - - - - -
      -

      CSS Color Module Level 3: Specifying Color and Opacity

      - -

      This tutorial demonstrates how you can manage colors in your application.

      - - -

      Warm-up

      -

      Become familiar with the CSS Color Module Level 3 API basics by learning about:

      - - -

      Creating a Color Generator

      -

      To enhance the user experience of your application, you must learn to create a HSLA color generator to set the color value for an element in the HSLA format.

      - -

      Figure: HSLA color generator

      -

      HSLA color generator

      - - - -
      1. To create the color generator, define 2 <div> elements for displaying the HSLA value as text and in a color box. You also need 4 slider inputs for defining the HSLA color: -
          -
        • The first input has a range of 0 - 360 and represents hue.
        • -
        • The second and third inputs have a range of 0 - 100 and represent saturation and lightness.
        • -
        • The last input has a range of 0 - 10 and represents alpha transparency. -

          The range should be 0.1 - 1, but the minimum value of the min attribute is 0 so the value can be divided by 10.

        - -
        -<div id="color-generator">
        -   <div id="text-box"></div>
        -   <div id="color-box"></div>
        -
        -   <label>Hue</label>
        -   <input id="hue" value="0" type="range" min="0" max="360">
        -
        -   <label>Saturation</label>
        -   <input id="saturation" value="100" type="range" min="0" max="100">
        -
        -   <label>Lightness</label>
        -   <input id="lightness" value="50" type="range" min="0" max="100">
        -
        -   <label>Alpha</label>
        -   <input id="alpha" value="10" type="range" min="0" max="10">
        -</div>
        -
      2. -
      3. Obtain the values from the slider inputs with the getElementById method. Remember to divide the alpha value by 10 to reach the correct range of 0.1 - 1. -
        -var h = document.getElementById('hue').value,
        -    s = document.getElementById('saturation').value,
        -    l = document.getElementById('lightness').value,
        -    a = document.getElementById('alpha').value / 10;
        -
      4. -
      5. Set the HSLA text and the color of the color box by defining the color from the inputs in the HSL and HSLA formats. -

        If the alpha is 1, the HSL format is displayed. Otherwise, the HSLA format is used.

        -
        -/* Define formats */
        -hsl = 'hsl(' + h + ', ' + s + '%, ' + l + '%)';
        -hsla = 'hsla(' + h + ', ' + s + '%, ' + l + '%, ' + a + ')';
        -
        -/* Set the color of the box */
        -cBox = document.querySelector('#color-box'),
        -
        -/* Set the text */
        -tBox = document.querySelector('#text-box');
        -
      6. - -
      7. Add an event handler to the input sliders to change the displayed text and color box color when the slider values change. -
        -var inputs = document.querySelectorAll('#color-generator input[type=range]');
        -			
        -for (i = 0; i < inputs.length; i++)
        -{
        -   inputs[i].onchange = function()
        -   {
        -      /* Show color */
        -   }
        -}
        -
      -

      Source Code

      -

      For the complete source code related to this use case, see the following file:

      - - - - - - - -
      - -Go to top - - - - - - - diff --git a/org.tizen.tutorials/html/web/w3c/dom/dom_tutorials_w.htm b/org.tizen.tutorials/html/web/w3c/dom/dom_tutorials_w.htm deleted file mode 100644 index cb4b26d..0000000 --- a/org.tizen.tutorials/html/web/w3c/dom/dom_tutorials_w.htm +++ /dev/null @@ -1,82 +0,0 @@ - - - - - - - - - - - - - - DOM, Forms and Styles: Managing CSS Styles and HTML Forms - - - - - - -
      -

      DOM, Forms and Styles: Managing CSS Styles and HTML Forms

      - -

      The DOM, forms and styles tutorials demonstrate how to manage CSS style and HTML5 form features in all Tizen Web applications:

      - - -

      The following tutorials apply in mobile applications only:

      - - - - - -
      - -Go to top - - - - - - - diff --git a/org.tizen.tutorials/html/web/w3c/dom/flexible_tutorial_w.htm b/org.tizen.tutorials/html/web/w3c/dom/flexible_tutorial_w.htm deleted file mode 100644 index 4e42c82..0000000 --- a/org.tizen.tutorials/html/web/w3c/dom/flexible_tutorial_w.htm +++ /dev/null @@ -1,362 +0,0 @@ - - - - - - - - - - - - - - CSS Flexible Box Layout Module: Adjusting the Layout - - - - - - -
      -

      CSS Flexible Box Layout Module: Adjusting the Layout

      - -

      This tutorial demonstrates how you can create a flexible box layout.

      - - -

      Warm-up

      -

      Become familiar with the CSS Flexible Box Layout Module API basics by learning about:

      - - -

      Follow-up

      -

      Once we have learned the basics of the CSS Flexible Box Layout Module API, we can now move on to more advanced tasks, including:

      - - - -

      Using the Flex Container

      -

      To enhance the user experience of your application, you must learn how to assign size and alignment to the flex container:

      - -
        -
      1. Assign the area (flex container) where the flexible box layout is applied by using the display: flex property: -
        <style>
        -   .flex_container {display: -webkit-flex}
        -</style>
        -
        -<div class="flex_container">
        -   <div class="flex_item">A</div>
        -   <div class="flex_item">B</div>
        -   <div class="flex_item">C</div>
        -   <div class="flex_item">D</div>
        -<div>
        - -

        The child nodes within the assigned flex container become flex items.

        -
      2. -
      3. Define the necessary properties for the flex container to assign the alignment of the flex items within it:

        -
          -
        • flex-direction property sets the alignment direction of the flex items: -
            -
          • row: Align from left to right.
          • -
          • row-reverse: Align from right to left.
          • -
          • column: Align from top to bottom.
          • -
          • column-reverse: Align from bottom to top.
          • -
        • - -
        • flex-wrap property sets the line changing of the flex items: -
            -
          • nowrap: Reduces the size of the flex items without changing lines.
          • -
          • wrap: The flex items reaching beyond the flex container area are divided into multiple lines using the cross axis direction of the current writing mode.
          • -
          • wrap-reverse: The flex items reaching beyond the flex container area are divided into multiple lines using the opposite cross axis direction than in the wrap value.
          • -
        • - -
        • justify-content property sets the handling of gaps between the flex items on the main axis: -
            -
          • flex-start: Gathers the items at the alignment starting point.
          • -
          • flex-end: Gathers the items at the alignment finishing point.
          • -
          • center: Gathers the items in the center.
          • -
          • space-between: Aligns the start and end item at both ends, and creates equal gaps in between the rest of the items.
          • -
          • space-around: Creates equal gaps between all items.
          • -
          - - - - - - - - - -
          Note
          This property is similar to text-align, but the alignment direction and the starting point are based on the flex-direction and flex-wrap properties.
        • - -
        • align-content property sets the handling of gaps between the flex items on the cross axis. It has the same values as the justify-content property, and 1 additional value: -
            -
          • stretch: Extends the size of the flex items and aligns them without gaps.
          • -
        • -
        • align-items property sets the relative location and size between the flex items on the cross axis: -
            -
          • flex-start: Aligns the items vertically to the top.
          • -
          • flex-end: Aligns the items vertically to the bottom.
          • -
          • center: Aligns the items vertically to the middle.
          • -
          • baseline: Aligns the items vertically to the baseline.
          • -
          • stretch: Extends the height of the flex items and aligns them without gaps.
          • -
          - - - - - - - - - -
          Note
          If the flex-wrap property is set to wrap-reverse, the start and end points of the alignment are reversed.
      -

      The following figure shows examples of flex containers and how their flex items have been aligned.

      -

      Figure: Flex container properties (in mobile applications only)

      -

      Flex container properties (in mobile applications only)

      - -

      Source Code

      -

      For the complete source code related to this use case, see the following files:

      - - -

      Using the Flex Items

      - -

      To enhance the user experience of your application, you must learn how to assign size and alignment to the flex items:

      - -
        -
      1. Assign the area (flex container) where the flexible box layout is applied, and define the flex items for it: -
        <style>
        -   .flex_container {display: -webkit-flex}
        -</style>
        -
        -<div class="flex_container">
        -   <div class="flex_item">A</div>
        -   <div class="flex_item">B</div>
        -   <div class="flex_item">C</div>
        -<div>
        -
      2. - -
      3. Define the necessary properties for the flex items:

        -
          -
        • align-self property is similar as the align-items property of the flex container. - - - - - - - - - -
          Note
          If both the align-self and align-items properties are used simultaneously, the align-items property is ignored.
        • - -
        • flex property is a shorthand expression defining the flex item size handling: -
            -
          • flex-grow: Sets whether the spaces between flex items are filled.
          • -
          • flex-shrink: Sets whether the width of the flex items is reduced according to the size of the flex container.
          • -
          • flex-basis: Sets the default width of the relevant flex items.
          • -
      -

      The following figure shows examples of how flex items can be placed and sized within a flex container.

      -

      Figure: Flex items (in mobile applications only)

      -

      Flex items (in mobile applications only)

      - -

      Source Code

      -

      For the complete source code related to this use case, see the following files:

      - - -

      Creating a Flexible Layout with CSS3

      -

      To enhance the user experience of your application, you must learn how to create flexible box layout:

      -
        -
      1. Define the HTML content for the flexible layout. In this example, create 2 articles areas, 1 for a text list and 1 for an icon list: -
        <div class="container">
        -   <article class="events">
        -      <h2>UPCOMING EVENTS</h2>
        -      <ul>
        -         <li>
        -            <div class="date"><span>APR</span><br> 15</div>
        -            <p class="title">
        -               Linux Foundation Collaboration Summit <span class="local">San Francisco, CA</span>
        -            </p>
        -         </li>
        -         <!--Other text items-->
        -      </ul>
        -   </article>
        -   <article class="schedule">
        -      <h2>SCHEDULE</h2>
        -      <div class="img_list">
        -         <img src="folder.png" alt="folder">
        -         <img src="alert.png" alt="alert">
        -         <!--Other icons-->
        -      </div>
        -   </article>
        -</div>
      2. - -
      3. Define styles to decorate the article areas. (The following figure applies to mobile applications only.) -
        <!--Border for the article areas-->
        -.container article > * {border: 1px solid #ccc;}
        -
        -<!--Font style for the article area titles-->
        -.container .events > h2, .container .schedule > h2 
        -{
        -   padding: 10px 20px;
        -   text-shadow: 1px 1px 2px #fff, -1px -1px 2px #000;
        -}
        -
        -<!--List styles-->
        -.container .events > ul, .container .schedule .img_list  
        -{
        -   height: 100%; 
        -   padding: 10px;
        -}
        -
        -<!--Text style for the text list item title-->
        -.container .events > ul > li .title 
        -{
        -   color: #51809e;
        -   text-shadow: 1px 1px 2px #000;
        -}
        -
        -<!--Text style for the text list item location info-->
        -.container .events > ul > li .title .local 
        -{
        -   text-indent: 10px;
        -   text-shadow: 0 0 0 #fff;
        -}
        -
        -<!--Styles for the text list item date box-->
        -.container .events > ul > li .date 
        -{
        -   text-align: center;
        -}
        -.container .events > ul > li .date 
        -{
        -   background-color: #ddd;
        -   border-radius: 10px;
        -   box-shadow: inset -2px -2px 4px rgba(0, 0, 0, .5);
        -}
        -.container .events > ul > li .date > span 
        -{
        -   background-color: #fff;
        -   border-radius: 5px;
        -}
        -

        Article areas with styles defined (in mobile applications only)

      4. - - -
      5. Define a flexible alignment for the article areas to support screen orientation changes and ensure that the content fills up the entire available screen area regardless of the orientation: -
          -
        1. Define the text list items and the icon list as flex containers using the display: -webkit-flex; property: -
            -
          • For the text list items, align them vertically in the middle, define a 0 margin at the top for the first item, and center-align the text for the date box.
          • -
          • For the icon list, align the icon list so that the first and last icon are placed at the ends and the gaps between the rest of the icons are equal.
          -

          (The following figure applies to mobile applications only.)

          -
          <!--Flexible alignment of text list-->
          -.container .events > ul > li 
          -{
          -   display: -webkit-flex;
          -   -webkit-align-items: center;
          -}
          -.container .events > ul > li: first-child 
          -{
          -   margin-top: 0;
          -}
          -
          -.container .events > ul > li .date 
          -{
          -   -webkit-flex: 0 0 20%;
          -   text-align: center;
          -}
          -
          -<!--Flexible alignment of icon list-->
          -.container .schedule .img_list 
          -{
          -   display: -webkit-flex;
          -   -webkit-justify-content: space-between;
          -}
          -

          Article areas with a flexible box layout defined (in mobile applications only)

        2. - - -
        3. Special consideration can be given for some screen sizes. The following example defines a specific layout for small screens (where the screen width is less than 390 pixels). (The following figure applies to mobile applications only.) -
          -@media screen and (min-width: 390px) 
          -{
          -   .container .schedule .img_list 
          -   {
          -      display: -webkit-flex;
          -      -webkit-flex-wrap: wrap;
          -      -webkit-justify-content: space-between;
          -      -webkit-align-content: space-around;
          -   }
          -
          -   .container {display: -webkit-flex;}
          -   .container > * {-webkit-align-content: center;}
          -   .container article {height: 250px;}
          -}
          -

          Article areas with a flexible box layout for small screens (in mobile applications only)

          -

          For more information on defining screen-size-specific rules, see Media Queries.

          -
      - -

      Source Code

      -

      For the complete source code related to this use case, see the following files:

      - - - - - - -
      - -Go to top - - - - - - - diff --git a/org.tizen.tutorials/html/web/w3c/dom/font_tutorial_w.htm b/org.tizen.tutorials/html/web/w3c/dom/font_tutorial_w.htm deleted file mode 100644 index b846b38..0000000 --- a/org.tizen.tutorials/html/web/w3c/dom/font_tutorial_w.htm +++ /dev/null @@ -1,220 +0,0 @@ - - - - - - - - - - - - - - CSS Fonts Module Level 3: Manipulating Fonts - - - - - - -
      -

      CSS Fonts Module Level 3: Manipulating Fonts

      - -

      This tutorial demonstrates how you can modify fonts.

      - -

      Warm-up

      -

      Become familiar with the CSS Fonts Module Level 3 API basics by learning about:

      - - -

      Manipulating Fonts

      - -

      To enhance the user experience of your application, you must learn to handle fonts using CSS font properties:

      - -
        -
      1. Define the font-style property within a <style> element in the <head> section of the Web page to apply different font styles:

        - -
        -<head>
        -   <style>
        -      p:nth-child(1) em{font-style: normal}
        -      p:nth-child(2) em{font-style: italic}
        -      p:nth-child(3) em{font-style: oblique}
        -   </style>
        -</head>
        -<body>
        -   <p>font-style: <em>normal</em></p>
        -   <p>font-style: <em>italic</em></p>
        -   <p>font-style: <em>oblique</em></p>
        -</body>
        -
        - -
      2. - -
      3. Define the font-weight property, -which controls the weight of the text:

        - -
        -<head>
        -   <style>
        -      p:nth-child(1) {font-weight: normal}
        -      p:nth-child(2) {font-weight: bold}
        -      p:nth-child(3) {font-weight: 300}
        -      p:nth-child(4) {font-weight: 500}
        -      p:nth-child(5) {font-weight: 700}
        -   </style>
        -</head>
        -<body>
        -   <p>font-weight: <em>normal</em></p>
        -   <p>font-weight: <em>bold</em></p>
        -   <p>font-weight: <em>300</em></p>
        -   <p>font-weight: <em>500</em></p>
        -   <p>font-weight: <em>700</em></p>
        -</body>
        -
        - -
      4. - -
      5. Define the font-variant property to -change the font to, for example, use small capital letters: -
        -<head>
        -   <style>
        -      p:nth-child(1) {font-variant: normal}
        -      p:nth-child(2) {font-variant: small-caps}
        -   </style>
        -</head>
        -<body>
        -   <p>font-variant: <em>normal</em></p>
        -   <p>font-variant: <em>small-caps</em></p>
        -</body>
        -
        - -
      6. - -
      7. Define the font-size property, which controls the size of the font: -
        -<head>
        -   <style>
        -      p:nth-child(1) {font-size: 150%}
        -      p:nth-child(2) {font-size: 1.2em}
        -   </style>
        -</head>
        -<body>
        -   <p>font-size: <em>150%</em></p>
        -   <p>font-size: <em>1.2em</em></p>
        -</body>
        -</html>
        -
        -
      8. - -
      9. Define the line-height property, which controls the height of a text line: -
        -<head>
        -   <style>
        -      p:nth-child(1) {line-height: 1}
        -      p:nth-child(2) {line-height: 1.5}
        -      p:nth-child(3) {line-height: 5}
        -   </style>
        -</head>
        -<body>
        -   <p>line-height: <em>1</em></p>
        -   <p>line-height: <em>1.5</em></p>
        -   <p>line-height: <em>5</em></p>
        -</body>
        -
        - -
      10. - -
      11. Define the font-family property, which assigns a specific font or its representative to an element. The list order within the <style> element determines the property priority. -

        If the assigned font is not installed on the target, a different font is obtained based on the user system.

        -
        -<head>
        -   <style>
        -      p:nth-child(1) {font-family: serif}
        -      p:nth-child(2) {font-family: sans-serif}
        -      p:nth-child(3) {font-family: monospace}
        -      p:nth-child(4) {font-family: cursive}
        -      p:nth-child(5) {font-family: fantasy}
        -      p:nth-child(6) {font-family: 'Arial Black', sans-serif}
        -      p:nth-child(7) {font-family: Tahoma, sans-serif}
        -      p:nth-child(8) {font-family: Verdana, sans-serif}
        -      p:nth-child(9) {font-family: Arial, sans-serif}
        -   </style>
        -</head>
        -<body>
        -   <p>font-family: <em>serif</em></p>
        -   <p>font-family: <em>sans-serif</em></p>
        -   <p>font-family: <em>monospace</em></p>
        -   <p>font-family: <em>cursive</em></p>
        -   <p>font-family: <em>fantasy</em></p>
        -   <p>font-family: <em>'Arial Black', sans-serif</em></p>
        -   <p>font-family: <em>Tahoma, sans-serif</em></p>
        -   <p>font-family: <em>Verdana, sans-serif</em></p>
        -   <p>font-family: <em>Arial, sans-serif</em></p>
        -</body>
        -</html>
        -
        -
      12. -
      - - -

      The following figure shows examples of manipulating the text font properties.

      -

      Figure: Font properties (in mobile applications only)

      -

      Font properties (in mobile applications only)

      - - - - - - - - - - -
      Note
      For a complete list of CSS Fonts Module Level 3 font properties (in mobile or wearable applications) and their possible values, see the Property index.
      - - - - - -
      - -Go to top - - - - - - - diff --git a/org.tizen.tutorials/html/web/w3c/dom/html5forms_tutorial_w.htm b/org.tizen.tutorials/html/web/w3c/dom/html5forms_tutorial_w.htm deleted file mode 100644 index a327409..0000000 --- a/org.tizen.tutorials/html/web/w3c/dom/html5forms_tutorial_w.htm +++ /dev/null @@ -1,208 +0,0 @@ - - - - - - - - - - - - - - HTML5 Forms: Managing User Input - - - - - - -
      -

      HTML5 Forms: Managing User Input

      - - -

      This tutorial demonstrates how you can implement Web forms with HTML5.

      - - -

      Warm-up

      -

      Become familiar with the HTML5 Forms API basics by learning about:

      - - -

      Creating a Basic Login Form

      - -

      To create simple user input forms, you must learn to use the HTML5 features in Web forms:

      - -
        -
      1. Create a simple form where the user can enter their login details (email address and password):

        -
        -<form action="" method="">
        -   <label>email: <input type="text"></label>
        -   <label>password: <input type="password"></label>
        -    
        -   <input type="submit" value="Login">
        -</form>
        -
      2. -
      3. To check the validity of the entered email address automatically, add the required attribute to the input element with the email type:

        -
        -<label>email: <input type="email" required></label>
        -
      4. -
      5. Define the password field as mandatory by using the required attribute in that input element too:

        -
        -<label>password: <input type="password" required></label>
        -
      6. -
      7. Because a device has limited space on the screen, remove the field labels and replace them with hint texts using the placeholder attribute:

        -
        -<input type="email" placeholder="e-mail address" required>
        -<input type="password" placeholder="password" required>
        -
      - -

      The final form that checks the email validity and requires the mandatory password input is complete:

      -
      -<form action="" method="">
      -   <fieldset>
      -      <legend>Login</legend>
      -      <input type="email" placeholder="e-mail address" required>
      -      <input type="password" placeholder="password" required>
      -   </fieldset>
      -    
      -   <input type="submit" value="Login">
      -</form>
      -
      - -

      Source Code

      -

      For the complete source code related to this use case, see the following file:

      - - -

      Creating an Advanced Login Form

      - -

      To create advanced user input forms, you must learn to use the HTML5 features in Web forms:

      - -
        -
      1. Create a login form that checks the email validity and requires the mandatory password input:

        -
        -<form action="" method="">
        -   <fieldset>
        -      <legend>Login</legend>
        -      <input type="email" placeholder="e-mail address" required>
        -      <input type="password" placeholder="password" required>
        -   </fieldset>
        -    
        -   <input type="submit" value="Login">
        -</form>
        -
      2. - -
      3. When the form page is loaded on the screen, put the focus automatically to the email field by using the autofocus attribute:

        -
        -<input type="email" placeholder="e-mail address" required autofocus>
        -
      4. - -
      5. -

        To spare the user from filling in information that they have given previously, use the autocomplete attribute, which shows the previously successfully inserted entries in a datalist, from which the user can select and use them.

        -

        You can apply the autocomplete attribute to a specific field by adding it to the appropriate input element. If you add it to the form element, it applies to all child elements within the form.

        - -
        -<form action="" method="" autocomplete="on">
        -
        -
      6. -
      7. In general, apply the autocomplete attribute to the form element, and then separately set it to off for those fields that must not use it.

        -

        In the following example, the password field must not use autocomplete, to prevent unauthorized access by any user.

        -
        -<input type="password" placeholder="password" required autocomplete="off">
        -
        -
      8. -
      9. Protect the password with private and public key pair using the keygen element.

        -

        The element is used to transform the data sent from the connected form to a pair of encrypted keys using the RSA (Rivest Shamir Adleman) method. When the input data is sent from the form, the private key is saved in the local computer, and the public key is delivered to the server. Only if the keys match, the login process proceeds forwards.

        - -
        -<keygen name="keyvalue">
        -
      10. - -
      11. Use the pattern attribute to perform a validity check that ensures that the password field value matches the given regular expression. The required attribute is used to ensure that the field value must be entered and then the validity check can be performed.

        -

        In the following example, the password only accepts numbers and letters of the alphabet. If an invalid value is entered, the login cannot proceed.

        - -
        <input type="password" placeholder="password" required
        -       pattern="[a-zA-Z]+[0-9]+[a-zA-Z0-9]*|[0-9]+[a-zA-Z]+[a-zA-Z0-9]*" 
        -       autocomplete="off">
        -
      12. -
      13. Define the required length of the password within the pattern attribute.

        -

        In the following example, the password must be 6 to 12 characters long.

        - -
        -<input type="password" placeholder="password" required 
        -       pattern="(?=([a-zA-Z]+[0-9]+[a-zA-Z0-9]*|[0-9]+[a-zA-Z]+[a-zA-Z0-9]*)).{6,12}" 
        -       autocomplete="off">
        -
      14. -
      - -

      The final form with autofocus and autocomplete features, strengthened security, and password value requirements is complete:

      - -
      -<form action="" method="" autocomplete="on">
      -   <fieldset>
      -      <legend>Login</legend>
      -      <input type="email" placeholder="e-mail address" required autofocus>
      -      <input type="password" placeholder="password" required 
      -             pattern="(?=([a-zA-Z]+[0-9]+[a-zA-Z0-9]*|[0-9]+[a-zA-Z]+[a-zA-Z0-9]*)).{6,12}" 
      -             autocomplete="off">
      -   </fieldset>
      -
      -   <keygen name="keyvalue">
      -    
      -   <input type="submit" value="Login">
      -</form>
      -
      - - - - - - - -
      - -Go to top - - - - - - - diff --git a/org.tizen.tutorials/html/web/w3c/dom/media_query_tutorial_w.htm b/org.tizen.tutorials/html/web/w3c/dom/media_query_tutorial_w.htm deleted file mode 100644 index 357e457..0000000 --- a/org.tizen.tutorials/html/web/w3c/dom/media_query_tutorial_w.htm +++ /dev/null @@ -1,171 +0,0 @@ - - - - - - - - - - - - - - Media Queries: Labeling Output Devices in Style Sheets - - - - - - -
      -

      Media Queries: Labeling Output Devices in Style Sheets

      - - -

      This tutorial demonstrates how you can define media queries to determine the styles to be used in the Web document.

      - - -

      Warm-up

      -

      Become familiar with the Media Queries API basics by learning about:

      -
        -
      • Creating a Liquid Layout -

        Create a liquid document layout that organically changes according to the device resolution.

      • -
      - -

      Creating a Liquid Layout

      -

      To enhance the user experience of your application, you must learn to define media queries to determine the styles to be used in the Web document. This example creates a simple Web document with a liquid layout that organically changes according to the device resolution to show the optimized layout on both portrait and landscape modes.

      - - -
        -
      1. Define a page with title and content elements: -
        -<header>
        -   <h1>Media queries tutorial</h1>
        -   <h1><img src="logo.png" alt="Tizen"></h1>
        -</header>
        -<div class="container">
        -   <section class="contents">
        -      <h2>Section Title</h2>
        -      <p class="desc">
        -         The quick brown fox jumps over a lazy dog.  The quick brown...
        -      </p>
        -   </section>
        -   <aside>
        -      Aside
        -   </aside>
        -</div>
        -
      2. -
      3. Define basic styles for the page, using a flexible box (in mobile or wearable applications) and multi-column (in mobile applications only) layout with 2 columns. (The following figure applies to mobile applications only.) -
        -.container 
        -{
        -   display: -webkit-flex;
        -}
        -.container aside 
        -{
        -   -webkit-flex: 1 0 20%;
        -}
        -.contents 
        -{
        -   -webkit-columns: 5em 3;
        -   -webkit-column-rule: 1px solid #999;
        -   -webkit-column-gap: 2em;
        -   -webkit-flex: 1 1 auto;
        -}
        -.contents h2 
        -{
        -   -webkit-column-span: all;
        -}
        -
        - -

        Fixed layout example (in mobile applications only)

        -

        The page is easy to view as long as the screen width is about 600 px; however, in a smaller screen below 400 px, the legibility rapidly decreases. You can edit the layout by reducing the number of columns to 1 and moving the Aside area at the bottom of the screen, but those changes then decrease legibility on a wider screen.

        - -
      4. -
      5. -

        To solve the problem, use a media query to define a liquid layout that changes according to the screen resolution:

        - -
        -@media all and (max-width: 480px) and (orientation: portrait) 
        -{
        -   .contents {-webkit-columns: 1;}
        -}
        -@media all and (min-width: 480px) and (max-width: 768px) 
        -{
        -   .contents {-webkit-columns: 2;}
        -   .container {display: -webkit-flex;}
        -}
        -
        -

        With the above media query, the normal resolution has 2 columns (shown on the right in the figure), while in a smaller resolution in a portrait mode only 1 column is used (shown on the left). (The following figure applies to mobile applications only.)

        -

        Liquid layout example (in mobile applications only)

        - -
      6. -
      7. If you need to define specific styles for a certain resolution range, simply add more media queries. However, too many conditions make the maintenance harder, so carefully consider what kind of resolution ranges you need. -

        - -

        The following conditions are generally used and cover all possibilities up to a Web browser in a PC:

        -
        -<!--Portrait mode of a smart phone-->
        -@media screen and (max-width: 480px) and (orientation: portrait) {<!--Specific layout-->}
        -
        -<!--Landscape mode of a smart phone and a small tablet-->
        -@media screen and (min-width: 480px) and (max-width: 768px) {<!--Specific layout-->}
        -
        -<!--Tablet and a small laptop-->
        -@media screen and (min-width: 768px) and (max-width: 1024px) {<!--Specific layout-->}
        -
        -<!--PC browser-->
        -@media screen and (min-width: 1024px) {<!--Specific layout-->}
        -@media print {<!--Specific layout-->}
        -
      8. - -
      -

      Source Code

      -

      For the complete source code related to this use case, see the following files:

      - - - - - - -
      - -Go to top - - - - - - - diff --git a/org.tizen.tutorials/html/web/w3c/dom/multi_tutorial_w.htm b/org.tizen.tutorials/html/web/w3c/dom/multi_tutorial_w.htm deleted file mode 100644 index f5da892..0000000 --- a/org.tizen.tutorials/html/web/w3c/dom/multi_tutorial_w.htm +++ /dev/null @@ -1,489 +0,0 @@ - - - - - - - - - - - - - - CSS Multi-column Layout Module: Creating Multi-column Layouts - - - - - - -
      -

      CSS Multi-column Layout Module: Creating Multi-column Layouts

      - - - - - - - - - - -
      Note
      This feature is supported in mobile applications only.
      - -

      This tutorial demonstrates how you can create a layout with multiple columns in your application.

      - - -

      Warm-up

      -

      Become familiar with the CSS Multi-column Layout API basics by learning about:

      - - -

      Follow-up

      -

      Once we have learned the basics of CSS Multi-column Layout API, we can now move on to more advanced tasks, including:

      - - -

      Creating a Basic Layout

      -

      To enhance the user experience of your application by providing a consistent behavior across a wide range of displays with different resolution and orientation, you must learn to create a basic layout using CSS:

      - -
        -
      1. -

        Create the HTML layout, defining separate sections for the column content and including an image file:

        -
        -<body>
        -   <article id="article">
        -      <section>
        -         <header>
        -            <h1>Section 1</h1>
        -         </header>
        -         <p>Lorem ipsum dolor (...), id.</p>
        -         <img src="images/pinwheel_green.png" alt="">
        -         <p>Maecenas at (...)tortor.</p>
        -      </section>
        -      <section>
        -         <header>
        -            <h1>Section 2</h1>
        -         </header>
        -         <img src="images/Tizen_Pinwheel_Secondary_Confetti.png" alt="">
        -         <p>Nullam bibendum (...) Curabitur.</p>
        -         <img src="images/Tizen_WhiteFold_4.png" alt="">
        -      </section>
        -      <section>
        -         <header>
        -            <h1>Section 3</h1>
        -         </header>
        -         <p>Sed sagittis, (...) Vivamus sed est sit amet.</p>
        -         <img id="figure" src="images/pinwheel_yellow.png" alt="">
        -         <p>Pellentesque habitant (...). Duis lobortis, nibh.</p>
        -      </section>
        -   </article>
        -</body>
        -
      2. - -
      3. Set the CSS column properties: -
          -
        1. -

          The article element acts as a multi-column container. Set the column-width (or -webkit-column-width) property to enable the multi-column layout:

          - -
          -article 
          -{
          -   width: 80vw;
          -   column-width: 119px;
          -   -webkit-column-width: 119px;
          -
          -   margin: 2vh 5vw;
          -   padding: 2vh 5vw;
          -   background: #c3c8ca;
          - -

          The column-width property defines the default column width but the visible width is not always similar. An algorithm calculates the width according to available space. Normally, a column has a different display width from the one set in the property because as the columns are sized to fill all available space.

          -

          For example, on a 480 x 800 display with portrait orientation, the device width is 123 px, whereas on a 720 x 1280 display with a landscape orientation, the width is 120 px. The space available for columns is the width attribute value reduced by padding, in this case 80vw - (2 * 5vw) = 70vw, which means 70/100 width of the device display.

          -
        2. -
        3. -

          Use the column-gap (or -webkit-column-gap) property to set the distance between columns:

          -
          -   column-gap: 10px;
          -   -webkit-column-gap: 10px;
          -
          -
        4. -
        5. - -

          Use the column-rule (or -webkit-column-rule) property to draw a vertical line between columns. Define the width, color, and style of the rule:

          - -
          -   -webkit-column-rule-width: 1px;
          -   -webkit-column-rule-color: #677784;
          -   -webkit-column-rule-style: solid;
          -   column-rule-width: 1px;
          -   column-rule-color: #677784;
          -   column-rule-style: solid;
          -}
          - -

          The rule width does not increase the distance between columns. It is drawn under the column gap and can be even wider than the gap.

          - -
        - -

        The figure below shows the layout with the column-rule width set to 40 px and the column-gap set to 10 px.

        - -

        Figure: Column settings

        -

        Column settings

        -
      4. -
      5. -

        Define the footer element with the display height set to 5/100 and padding set to 2 * 2vh:

        - -
        -footer 
        -{
        -   padding: 2vh;
        -   height: 5vh;
        -   background: rgba(103, 119, 132, 0.2);
        -}
        -
        -
      6. -
      7. -

        Define the section elements setting the border-bottom and vertical padding values. It is not necessary to define horizontal padding, as it has been defined for the article element.

        - -
        -article>section
        -{
        -   border-bottom: 1px solid #d8d9d4;
        -   padding: 4px 0;
        -   text-align: center;
        -}
        -
        -
      8. -
      9. -

        Set image elements to have an automatic margin to center them within the column.

        -

        In case of the image whose id attribute is set to figure, set it to be a floating element with text drawn around it.

        - -
        -img{
        -   display: block;
        -   margin: 4px auto;
        -}
        -
        -#figure
        -{
        -   float: right;	
        -   margin: 4px;
        -}
        -
        -
      - -

      The following figures illustrate the created layout in different display sizes and orientations.

      - -

      Figure: Basic layout on a 480 x 800 display

      -

      Basic layout on a 480 x 800 display

      - -

      Figure: Basic layout on a 720 x 1280 display

      -

      Basic layout on a 720 x 1280 display

      - -

      Source Code

      -

      For the complete source code related to this use case, see the following files:

      - - -

      Creating a Layout with Dynamic Content

      - -

      To enhance the user experience of your application by providing a consistent behavior across a wide range of displays with different resolution and orientation, you must learn to create a layout displaying a varying amount of content using CSS:

      -
        -
      1. -

        Create the HTML layout. The article element displays the columns, and the nav element contains buttons to add and remove content in the columns.

        -
        -<body>
        -   <article id="article">
        -   </article>
        -   <nav>
        -      <a id="addSections" href="#">Add images</a> 
        -      <input type="number" id="howMany" value="3"> 
        -      <a id="removeGroup" href="#">Remove last Group</a>
        -   </nav>
        -   <footer> Multicolumn Layout Tutorial 02</footer>
        -</body>
        -
        -
      2. -
      3. Set the CSS properties: -
          -
        1. -

          Define the CSS display and column properties:

          -
          -body 
          -{
          -   display: flex;
          -   display: -webkit-flex;
          -   flex-direction: column;
          -   -webkit-flex-direction: column;
          -   background: #fefffa;
          -}
          -
          -
        2. -
        3. -

          Set the article, nav and footer elements in one column using the flexible box layout.

          -

          The nav element is also a flexible box layout container to set UI elements in.

          -
          -nav 
          -{
          -   height: 20vh;
          -   padding-left: 20%;
          -   padding-top: 10px;
          -   display: flex;
          -   display: -webkit-flex;
          -   flex-flow: row wrap;
          -   -webkit-flex-flow: row wrap;
          -   flex: none;
          -   -webkit-flex: none;
          -   justify-content: space-around;
          -   -webkit-justify-content: space-around;
          -   align-items: center;
          -   -webkit-align-items: center;
          -   background: url(../images/white_logo.png) no-repeat;
          -   background-position: 2%;
          -   background-size: auto 70%;
          -}
          -
          -
        4. -
        5. -

          Define the styles for the a elements within the nav element to make them appear as buttons:

          -
          -nav a 
          -{
          -   margin: 3px;
          -   border-radius: 5px;
          -   padding: 5px 15px;
          -   background: rgba(103, 119, 132, 0.2);
          -   text-align: center;
          -   font-weight: bold;
          -}
          -
          -

          When the user taps the Add images button, the images and their descriptions are displayed.

          -
        6. -
        7. -

          Define the input element (with the property type set to number) style with an increased height to match the buttons around it:

          -
          -nav input
          -{
          -   width: 50px;
          -   height: 2em;
          -}
          -
          -
        8. -
        9. -

          The article element contains the column properties. Use the -webkit-column-width property to set the column width. The real width is calculated based on available space.

          -
          -article 
          -{
          -   width: 90vw;
          -   column-width: 136px;
          -   -webkit-column-width: 136px;
          -   margin: 1vh 2vh;
          -   padding: 1vh;
          -   background: #c3c8ca;
          -}
          -
          -
        10. -
        11. -

          Set the images within the article element with a block display to separate them from text:

          -
          -article img 
          -{
          -   margin: 0 auto;
          -   display: block;
          -}
          -
          -
        12. -
        13. -

          Define the column-span property as all for the h1 elements:

          -
          -article>h1 
          -{
          -   background: rgba(103, 119, 132, 0.5);
          -   padding: 4px;
          -   text-align: center;
          -   color: #eed484;
          -   column-span: all;
          -   -webkit-column-span: all;
          -}
          -
          -

          As a result, the h1 elements are spread across the columns. When the column-span property is used, you cannot have more columns than can fit in the available horizontal space.

          -
        14. -
        15. -

          Define the break-inside property as avoid to avoid breaking elements between columns:

          -
          -article>section 
          -{
          -   break-inside: avoid;
          -   -webkit-column-break-inside: avoid;
          -   border-bottom: 1px solid #d8d9d4;
          -   padding: 4px 0;
          -   text-align: center;
          -}
          -
          -
        16. -
        17. -

          Set the footer size:

          -
          -footer 
          -{
          -   padding: 2vh;
          -   height: 5vh;
          -   background: rgba(103, 119, 132, 0.2);
          -}
          -
          -
        18. -
        -
      4. -
      5. Add the JavaScript code to make the content dynamic: -
          -
        1. -

          Declare a variable for the images. Elements included in the variable amount to data displayed in a column layout, such as a newsfeed:

          -
          -var images = ["images/pinwheel_green.png",
          -              "images/Tizen_Pinwheel_Secondary_Confetti.png", 
          -              "images/Tizen_WhiteFold_4.png", 
          -              "images/pinwheel_yellow.png"];
          -
          -
        2. -
        3. -

          Declare a variable for the input element for selecting the number of images added to the content:

          -
          -var howManyInput;
          -
          -
        4. -
        5. -

          Use the addGroup() method with the input parameter value to add random images to the column layout and initialize the button events:

          - -
          -window.onload = function() 
          -{
          -   addGroup(4);
          -   howManyInput = document.getElementById('howMany');
          -   var addBtn = document.getElementById('addSections');
          -   addBtn.onclick = function() 
          -   {
          -      addGroup(howManyInput.value);
          -
          -      return false;
          -   };
          -   var removeBtn = document.getElementById('removeGroup');
          -   removeBtn.onclick = function() 
          -   {
          -      removeGroup();
          -
          -      return false;
          -   };
          -};
          -
          -
        6. -
        7. -

          Declare the h1No variable containing the number of h1 elements included in the article elements, and one added to next lines.

          - -

          Declare the newHTML variable to add new content to the column layout. Each added element contains an h1 element as a header, and section elements. Include an img element with a text description in each section element to display a random image. The art variable is initialized, and new HTML code (newHTML) is concatenated with the existing one (innerHTML):

          -
          -function addGroup(howMany) 
          -{
          -   var h1No = document.querySelectorAll('article>h1').length + 1;
          -   var newHTML = "<h1>Group " + h1No + "</h1>";
          -   var i;
          -
          -   for (i = 0; i < howMany; ++i) 
          -   {
          -      newHTML += "<section><img alt='' src='";
          -      newHTML += images[Math.floor(Math.random() * 4)];
          -      newHTML += "'>Lorem ipsum dolor sit amet diam sodales rutrum.</section>";
          -   }
          -   var art = document.getElementById("article");
          -   art.innerHTML += newHTML;
          -}
          -
          -
        8. -
        9. -

          When the user taps the Remove last Group button, the removeGroup() method is called to remove the group of images that was added last. Use the all variable to select all h1 elements in the content using the querySelectorAll() method. If the last value is less than 0, there is no element to remove. Use the removeNextSibling() method to recursively delete the next sibling element, and the removeChild() method to remove the h1 elements from its parent.

          -
          -function removeGroup() 
          -{
          -   var all = document.querySelectorAll('article>h1');
          -   var last = all.length - 1;
          -   if (last < 0) 
          -   {
          -      return;
          -   }
          -   removeNextSibling(all[last].nextSibling);
          -   all[last].parentElement.removeChild(all[last]);
          -}
          -
          -
        10. -
        -
      -

      The following figures illustrate the created layout in different display sizes and orientations.

      - -

      Figure: Dynamic layout on a 480 x 800 display

      -

      Dynamic layout on a 480 x 800 display

      - -

      Figure: Dynamic layout on a 720 x 1280 display

      -

      Dynamic layout on a 720 x 1280 display

      -

      Source Code

      -

      For the complete source code related to this use case, see the following files:

      - - - - - - -
      - -Go to top - - - - - - - diff --git a/org.tizen.tutorials/html/web/w3c/dom/selector_tutorial_w.htm b/org.tizen.tutorials/html/web/w3c/dom/selector_tutorial_w.htm deleted file mode 100644 index e2fb817..0000000 --- a/org.tizen.tutorials/html/web/w3c/dom/selector_tutorial_w.htm +++ /dev/null @@ -1,221 +0,0 @@ - - - - - - - - - - - - - - Selectors API Level 1 and Level 2: Selecting DOM Elements - - - - - - -
      -

      Selectors API Level 1 and Level 2: Selecting DOM Elements

      - -

      This tutorial demonstrates how you can retrieve desired elements from a page and modify them.

      - -

      Warm-up

      -

      Become familiar with the Selectors API Level 1 and Level 2 basics by learning about:

      - -

      Follow-up

      -

      Once we have learned the basics of the Selectors API Level 1 and Level 2, we can now move on to more advanced tasks, including:

      - - - -

      Selecting a Single Node

      -

      To enhance the user experience of your application, you must learn to use selectors to handle page elements, and to select a single node:

      -
        -
      1. To select the first matching element found in the child nodes, use the querySelector() method with CSS selectors. You get the same result as when using the getElementById(), getElementsByTagName(), and getElementsByClassName() methods. -
        var obj1 = document.getElementsByTagName('td')[0]; /* First <td> element in the document */
        -var obj2 = document.getElementById('foo'); /* Element with the ID #foo */
        -var obj3 = document.getElementsByClassName('bar')[0]; /* First element in the bar class */
        -  
        -var obj4 = document.querySelector('td'); /* Same as obj1 */
        -var obj5 = document.querySelector('#foo'); /* Same as obj2 */ 
        -var obj6 = document.querySelector('.bar'); /* Same as obj3 */
        -

        The querySelector() method returns the first matching element node within the subtrees of the context node. If no matching element is found, the method returns null.

      2. -
      3. You can use the CSS selectors to ensure that elements with complex structures can be easily selected. -

        For example, the following example selects the last element among the child nodes of the second <tr> element, which is a child of the <tbody> element in the second <table> element of the document.

        -
        var obj = document.querySelector('table:nth-child(2) tbody > tr:nth-child(2) :last-child');
      4. -
      5. You can use method chaining to select an element: -
        var obj = document.querySelector('table:nth-child(2)');
        -var targetObj = obj.querySelector('tbody > tr:nth-child(2) :last-child')
      6. -
      - -

      Figure: Single node selection (in mobile applications only)

      -

      Single node selection (in mobile applications only)

      -

      Source Code

      -

      For the complete source code related to this use case, see the following file:

      - - -

      Selecting Multiple Nodes

      -

      To enhance the user experience of your application, you must learn to use selectors to handle page elements, and to select multiple nodes in a node list:

      -
        -
      1. Select an element in the node list using the querySelector() method: -
        var obj = document.querySelector('table:nth-child(2)');
        -

        The querySelector() method returns the first matching element node within the subtrees of the context node. If no matching element is found, the method returns null. The query above selects the second <table> element in the document as a single element.

        -
      2. - -
      3. Select multiple elements in the node list using the querySelectorAll() method, and define a variable to represent the length of the targetObj node list: -
        var targetObj = obj.querySelectorAll('thead th, tbody td');
        -var i = targetObj.length;
        -

        The querySelectorAll() method returns an array containing all of the matching element nodes within the subtrees of the context node, in the document order, and saves the elements in a node list. If there are no matching nodes, the method returns an empty array. The query above selects the <th> elements in the table head and the <td> elements in the table body.

        -
      4. -
      5. Apply a defined style to all elements stored in the targetObj node list: -
        while (0 < i) 
        -{
        -   i--;
        -   targetObj[i].style.backgroundColor = 'orange';
        -   targetObj[i].textContent = 'Exam 3' + i;
        -}
      - -

      Figure: Multiple node selection (in mobile applications only)

      -

      Multiple node selection (in mobile applications only)

      -

      Source Code

      -

      For the complete source code related to this use case, see the following file:

      - - -

      Creating an Accordion Menu

      - -

      To enhance the user experience of your application, you must learn to retrieve element nodes from the DOM tree to create a simple accordion menu.

      -

      The accordion menu is created using the CSS3 Basic User Interface Module Level 3 API (in mobile or wearable applications). When a title is touched, the relevant content is shown, and other content is hidden.

      -
        -
      1. Create the HTML layout: -
        <ul class="accordion">
        -   <li>
        -      <p class="title current">Title 1<p>
        -      <div>contents 1</div>
        -   </li>
        -   <li>
        -      <p class="title">Title 2</p>
        -      <div>contents 2</div>
        -   </li>
        -   <!--Other list elements-->
        -</ul>
      2. - -
      3. Use CSS transitions to add sliding effects when content appears: -
        .accordion  > li  > div 
        -{
        -   padding: 0 15px;
        -
        -   <!--Assign time for CSS transformation-->
        -   -webkit-transition: all .5s;
        -   opacity: 0;
        -   height: 0;
        -   box-shadow: inset 1px 1px 4px rgba(0, 0, 0, .5);
        -   line-height: 2;
        -}
        -<!--Assign styles to be applied in case the current class is added to p.title-->
        -.accordion  > li  > p.current 
        -{
        -   background: -webkit-linear-gradient(top, #666, #000);
        -   color: #fff;
        -}
        -.accordion > li > p.current + div 
        -{
        -   opacity: 1;
        -   height: 200px;
        -}
      4. -
      5. Use the querySelector() and querySelectorAll() methods to change the class of the subject in the elements where the event is fired: -
        var testAccordion = function(obj) 
        -{
        -   var targetObj = document.querySelector(obj);
        -   var targetLength = document.querySelectorAll(obj + 'li').length;
        -
        -   /* In case the elements are not selected */
        -   if (targetLength <= 0) 
        -      return false;
        -
        -   targetObj.onclick = function(e) 
        -   {
        -      var that = e.target;
        -
        -      /* In case the e.target class is not title */
        -      if ((that.className !== 'title')) return false;
        -
        -      for (var i = 0; i < targetLength; i++) 
        -      {
        -         /* Change all classes of the 'li p' elements at the bottom of .accordion to title */
        -         targetObj.querySelectorAll('li p')[i].className = 'title';
        -      }
        -      /* Define the e.target class as current */
        -      that.className += 'current';
        -   }
        -}
        -
      6. -
      7. Define the elements that use the accordion menu: -
        testAccordion('.accordion');
      - -

      Figure: Accordion menu (in mobile applications only)

      -

      Accordion menu (in mobile applications only)

      -

      Source Code

      -

      For the complete source code related to this use case, see the following file:

      - - - - - - - -
      - -Go to top - - - - - - - diff --git a/org.tizen.tutorials/html/web/w3c/dom/session_history_tutorial_w.htm b/org.tizen.tutorials/html/web/w3c/dom/session_history_tutorial_w.htm deleted file mode 100644 index e9d7803..0000000 --- a/org.tizen.tutorials/html/web/w3c/dom/session_history_tutorial_w.htm +++ /dev/null @@ -1,205 +0,0 @@ - - - - - - - - - - - - - - HTML5 session history of browsing contexts: Managing Browsing Contexts - - - - - - -
      -

      HTML5 session history of browsing contexts: Managing Browsing Contexts

      -

      This tutorial demonstrates how you can store and use session history details.

      - - -

      Warm-up

      -

      Become familiar with the HTML5 session history of browsing contexts API basics by learning about:

      - - - -

      Managing Session History Entries

      - -

      Learning how to manage the session history enhances the user browsing experience in your application:

      - -
        -
      1. To add an entry to the session history, use the pushState() method of the history interface: -
        -<script>
        -   history.pushState({index: currentIndex}, document.title);
        -</script>
        -
        - - - - - - - - - -
        Note
        The pushState() method accepts the data, title, and url (optional) parameters. The title parameter refers to the key value used to search for entries saved in the session history, and is currently ignored in all browsers.
        -
      2. - -
      3. To update the entry details, use the replaceState() method: -
        -<script>
        -   history.replaceState({index: currentIndex}, document.title, '#page' + currentIndex);
        -</script>
        -
        -

        The replaceState() method uses the same parameters as the pushState() method. The history_sample.html is the url parameter, which refers to the address of the page that is to be changed.

        -
      4. - -
      5. To use the session history information: -
          -
        1. Implement a page with the Prev and Next buttons: -
          -<nav class="paging">
          -   <a href="#">Prev</a>
          -   <a href="#">Next</a>
          -</nav>
          -<p>Current Index: <output> </output></p>
          -
          -<a href="http://tizen.org/">Tizen.org</a>
          -
          -
        2. -
        3. When the user clicks the buttons, the current index value (representing page numbers) is changed and stored in the state object of the history interface: -
          -var currentIndex = 0;
          -var prev = document.querySelector('.paging > a:nth-child(1)');
          -var next = document.querySelector('.paging > a:nth-child(2)');
          -
          -/* Prev button click event */ 
          -prev.onclick = function() 
          -{
          -   currentIndex -= 1;   
          -   setState(currentIndex);
          -    
          -   return false;
          -};
          -    
          -/* Next button click event */ 
          -next.onclick = function() 
          -{
          -   currentIndex += 1;  
          -   setState(currentIndex);
          -    
          -   return false;
          -};
          -
          -
        4. - -
        5. If the state object has data in it, use the replaceState() method to change the previously stored information. Otherwise, add new info with the pushState() method. -
          -function setState(currentIndex) 
          -{
          -   if (history.state) 
          -   {
          -      history.replaceState({index: currentIndex}, document.title, '#page' + currentIndex);
          -   } 
          -   else 
          -   {
          -      history.pushState({index: currentIndex}, document.title);
          -   }
          -   output.textContent = currentIndex;
          -}
          -
          -
        6. -
        -
      6. -
      -

      Source Code

      -

      For the complete source code related to this use case, see the following file:

      - - -

      Detecting Session History Changes

      - -

      Learning how to track session history changes enhances the user browsing experience in your application:

      - -
      1. A page with data stored in the session history fires a popstate event when the page is loaded (for example, because it is refreshed or moved to from the previous page). -

        Register the event listener:

        - -
        -window.addEventListener("popstate", foo, false);
        -
      2. - -
      3. Define the event handler for the event. You can use the data stored in the state object to retrieve the correct location on the page to be loaded. -
        -var output = document.querySelector('output');
        -
        -window.onpopstate = function() 
        -{
        -   currentIndex = history.state.index;
        -   output.textContent = currentIndex;
        -}
        -
        -

        In the snippet above, when a popstate event is fired, it saves the index value stored in the state object to the currentIndex variable, and outputs the <output> element from the correct index location. -

        - -
      -

      Source Code

      -

      For the complete source code related to this use case, see the following file:

      - - - - - - - -
      - -Go to top - - - - - - - \ No newline at end of file diff --git a/org.tizen.tutorials/html/web/w3c/dom/text_module_tutorial_w.htm b/org.tizen.tutorials/html/web/w3c/dom/text_module_tutorial_w.htm deleted file mode 100644 index 4192c0f..0000000 --- a/org.tizen.tutorials/html/web/w3c/dom/text_module_tutorial_w.htm +++ /dev/null @@ -1,253 +0,0 @@ - - - - - - - - - - - - - - CSS Text Module Level 3: Manipulating Text - - - - - - -
      -

      CSS Text Module Level 3: Manipulating Text

      - -

      This tutorial demonstrates how you can manipulate and transform text.

      - -

      Warm-up

      -

      Become familiar with the CSS Text Module Level 3 API basics by learning about:

      - - -

      Manipulating Text

      - -

      To enhance the user experience of your application, you must learn to handle line breaking, justification, alignment, white space handling, and text transformations using CSS text properties:

      - -
        -
      1. Define the text-transform property within a <style> element in the <head> section of the Web page to control the text capitalization: - -
        -<head>
        -   <style>
        -      p:nth-child(1) {text-transform: none;}
        -      p:nth-child(2) {text-transform: capitalize;}
        -      p:nth-child(3) {text-transform: uppercase;}
        -      p:nth-child(4) {text-transform: lowercase;}
        -      p:nth-child(5) {text-transform: full-width;}
        -   </style>
        -</head>
        -<body>
        -   <p>The quick brown fox jumps over a lazy dog.</p>
        -   <p>The quick brown fox jumps over a lazy dog.</p>
        -   <p>The quick brown fox jumps over a lazy dog.</p>
        -   <p>The quick brown fox jumps over a lazy dog.</p>
        -   <p>The quick brown fox jumps over a lazy dog.</p>
        -</body>
        -
        - -
      2. - -
      3. Define the text-align property, which controls the text alignment: - -
        -<head>
        -   <style>
        -      p:nth-child(1) {text-align: start;}
        -      p:nth-child(2) {text-align: end;}
        -      p:nth-child(3) {text-align: left;}
        -      p:nth-child(4) {text-align: right;}
        -      p:nth-child(5) {text-align: center;}
        -      p:nth-child(6) {text-align: justify;}
        -   </style>
        -</head>
        -
        - -
      4. - -
      5. Define the text-indent property, which controls the text indentation: - -
        -<head>
        -   <style>
        -      p:nth-child(1) {text-indent: 0}
        -      p:nth-child(2) {text-indent: 1em}
        -      p:nth-child(3) {text-indent: -1em}
        -      p:nth-child(4) {text-indent: 5%}
        -      p:nth-child(5) {text-indent: -5%}
        -   </style>
        -</head>
        -
        - -
      6. - -
      7. Define the letter-spacing property, which controls the letter spacing: -
        -<head>
        -   <style>
        -      p:nth-child(1) {letter-spacing: .5em}
        -      p:nth-child(2) {letter-spacing: -.1em}
        -   </style>
        -</head>
        -
        - -
      8. - -
      9. Define the word-spacing property, which controls the space between words: -
        -<head>
        -   <style>
        -      p:nth-child(1) {word-spacing: 1em}
        -      p:nth-child(2) {word-spacing: -.1em}
        -   </style>
        -</head>
        -
        - -
      10. - -
      11. Define the word-break property, which determines the line breaking rules for non-CJK (Chinese, Japanese, and Korean) scripts: -
        -<head>
        -   <style>
        -      p:nth-child(1) {word-break: normal}
        -      p:nth-child(2) {word-break: keep-all}
        -      p:nth-child(3) {word-break: break-all}
        -   </style>
        -</head>
        -
        - -
      12. - -
      13. Define the white-space property, which determines the handling of empty space within an element: -
        -<head>
        -   <style>
        -      p:nth-child(1) {white-space: normal}
        -      p:nth-child(2) {white-space: pre}
        -      p:nth-child(3) {white-space: nowrap}
        -      p:nth-child(4) {white-space: pre-wrap}
        -      p:nth-child(5) {white-space: pre-line}
        -   </style>
        -</head>
        -<body>
        -   <p>The quick brown fox jumps
        -   over a lazy dog.</p>
        -   <p>The quick brown fox jumps
        -   over a lazy dog.</p>
        -   <p>The quick brown fox jumps
        -   over a lazy dog.</p>
        -   <p>The quick brown fox jumps
        -   over a lazy dog.</p>
        -   <p>The quick brown fox jumps
        -   over a lazy dog.</p>
        -</body>
        -</html>
        -
        - -
      14. - -
      15. Define the text-shadow property, which adds a shadow effect to text: -
        -<head>
        -   <style>
        -      p:nth-child(1) {text-shadow: 0.1em 0.1em 0.2em rgba(0, 0, 0, .7)}
        -      p:nth-child(2) {text-shadow: -0.2em 0.2em 0.2em #000, 0.2em -0.2em 0.2em #f00}
        -      p:nth-child(3) {color: #fff; text-shadow: 0 0 .7em #000;}
        -      p:nth-child(4) {color: #fff; text-shadow: 0 0 1px #f00;}
        -   </style>
        -</head>
        -
        - -
      16. - -
      17. Define the word-wrap and overflow-wrap properties, which control forced line breaks when the length of a word is longer than the area where it is displayed: -
        -<head>
        -   <style>
        -      p:nth-child(1) {word-wrap: normal}
        -      p:nth-child(2) {word-wrap: break-word}
        -      p:nth-child(3) {overflow-wrap: normal}
        -      p:nth-child(4) {overflow-wrap: break-word}
        -   </style>
        -</head>
        -<body>
        -   <p>The quick brown foxxxxxxxxxxxxxxxxxxxxxxxx jumps over a lazy dog.</p>
        -   <p>The quick brown foxxxxxxxxxxxxxxxxxxxxxxxx jumps over a lazy dog.</p>
        -   <p>The quick brown foxxxxxxxxxxxxxxxxxxxxxxxx jumps over a lazy dog.</p>
        -   <p>The quick brown foxxxxxxxxxxxxxxxxxxxxxxxx jumps over a lazy dog.</p>
        -</body>
        -
        - -
      18. - -
      - - -

      The following figure shows examples of manipulating the text properties.

      -

      Figure: Text properties (in mobile applications only)

      -

      Text properties (in mobile applications only)

      - - - - - - - - - - -
      Note
      For a complete list of CSS Text Module Level 3 text properties (in mobile or wearable applications) and their possible values, see the Property index.
      - - - - - -
      - -Go to top - - - - - - - diff --git a/org.tizen.tutorials/html/web/w3c/dom/transform_tutorial_w.htm b/org.tizen.tutorials/html/web/w3c/dom/transform_tutorial_w.htm deleted file mode 100644 index 204f3d4..0000000 --- a/org.tizen.tutorials/html/web/w3c/dom/transform_tutorial_w.htm +++ /dev/null @@ -1,588 +0,0 @@ - - - - - - - - - - - - - - CSS Transforms: Manipulating Elements - - - - - - -
      -

      CSS Transforms: Manipulating Elements

      - -

      This tutorial demonstrates how you can use transforms with animations.

      - - -

      Warm-up

      -

      Become familiar with the CSS Transforms API basics by learning about:

      - - -

      Follow-up

      -

      Once we have learned the basics of CSS Transforms API, we can now move on to more advanced tasks, including:

      - - -

      Creating an Animation with Transforms

      -

      To enhance the user experience of your application, you must learn to use transforms with animations. This example uses the animation from the Creating a Logo Animation use case as a basis, and adds a more diverse visual effect to it with the transform property. In the modified animation:

      - -
        -
      • As in the original animation, no elements are initially shown on the screen.
      • -
      • The Tizen logo gradually appears in the middle of the screen, and as it moves to the right, it becomes smaller. With the transform property, the logo is made to rotate.
      • -
      • Each letter in the word "TIZEN" consecutively comes in from the left of the screen and moves to the right to its correct location. With the transform property, the letters are translated in the 3D space and rotated around the Y axis.
      • -
      - -

      Figure: Tizen logo to be transformed

      -

      Tizen logo to be transformed

      - - -
        -
      1. Create the HTML layout to control the movement of each individual animation element: -
        -<div class="animation-holder">
        -   <span class="tizen-txt t"></span>
        -   <span class="tizen-txt i"></span>
        -   <span class="tizen-txt z"></span>
        -   <span class="tizen-txt e"></span>
        -   <span class="tizen-txt n"></span>
        -   <span class="tizen-txt tm"></span>
        -   <span class="tizen-logo"></span>
        -</div>
        -
        -
      2. -
      3. Define the basic style of the animation elements. Add the perspective property to increase the Z axis effect of the 3D transform. -
        -.animation-holder 
        -{
        -   -webkit-perspective: 1000px;
        -   height: 88px;
        -   left: 50%;
        -   margin: -54px 0px 0px -140px;
        -   position: absolute;
        -   top: 50%;
        -   width: 280px;
        -}
        -.tizen-txt,
        -.tizen-logo 
        -{
        -   background-position: 50% 50%;
        -   background-repeat: no-repeat;
        -   display: block;
        -   position: absolute;
        -}
        -.tizen-txt.t 
        -{
        -   background-image: url("images/txt_t.png");
        -   height: 56px;
        -   left: 0px;
        -   top: 31px;
        -   width: 48px;
        -}
        -
        -
      4. -
      5. Create the animation: -
          -
        1. -

          Assign keyframes for the logo element to transform it. In order to rotate the logo, use the -webkit-transform: rotate() function, which defines the angle of the rotation. -

          -
          -@-webkit-keyframes tizen-logo 
          -{
          -   0% 
          -   {
          -      -webkit-animation-timing-function: ease-in;
          -      height: 211px;
          -      left: 30px;
          -      opacity: 0;
          -      top: -61px;
          -      -webkit-transform: rotate(0deg);
          -      width: 220px;
          -   }
          -   30% 
          -   {
          -      -webkit-animation-timing-function: ease-out;
          -      height: 211px;
          -      left: 30px;
          -      opacity: 1;
          -      top: -61px;
          -      -webkit-transform: rotate(720deg);
          -      width: 220px;
          -   }
          -   50% 
          -   {
          -      height: 32px;
          -      left: 247px;
          -      opacity: 1;
          -      top: 0;
          -      -webkit-transform: rotate(1440deg);
          -      width: 33px;
          -   }
          -   100% 
          -   {
          -      height: 32px;
          -      left: 247px;
          -      opacity: 1;
          -      top: 0;
          -      -webkit-transform: rotate(1440deg);
          -      width: 33px;
          -   }
          -}
          -
          - - - - - - - - - -
          Note
          For a rotation, the image has to be carefully created to ensure the correct end result. The rotation occurs with the center of the element as the center. If the rotation center must be moved because the image center is not aligned, use the transform-origin property to adjust the rotation location.
        2. -
        3. Create the keyframes for the first letter in the word "TIZEN". In the animation, due to the translate3d() and rotateY() methods, each letter transforms slightly from the right to the left as it comes in. - -

          Animation

          - -
          -@-webkit-keyframes tizen-txt-t 
          -{
          -   0% 
          -   {
          -      opacity: 0;
          -      -webkit-transform: translate3d(20px, 0, -200px) rotateY(90deg);
          -   }
          -   30% 
          -   {
          -      opacity: 0;
          -      -webkit-transform: translate3d(20px, 0, -200px) rotateY(90deg);
          -   }
          -   35% 
          -   {
          -      opacity: 1;
          -      -webkit-transform: translate3d(0, 0, 0) rotateY(0deg);
          -   }
          -   100% {}
          -}
          -
        4. -
        5. To emphasize the fact that the letters are being created on the right, change the location of the transform. If the transform-origin property is declared for the entire animation element, the logo rotation changes. Consequently, you must only declared it for the letters. -
          -.tizen-txt 
          -{
          -   -webkit-transform-origin: 100% 50%;
          -}
          -
        6. - -
        7. Create the keyframes for the other letters similarly:

          -
          -@-webkit-keyframes tizen-txt-i 
          -{
          -   0% 
          -   {
          -      opacity: 0;
          -      -webkit-transform: translate3d(20px, 0, -200px) rotateY(90deg);
          -   }
          -   32% 
          -   {
          -      opacity: 0;
          -      -webkit-transform: translate3d(20px, 0, -200px) rotateY(90deg);
          -   }
          -   37% 
          -   {
          -      opacity: 1;
          -      -webkit-transform: translateX(0) rotateY(0deg);
          -   }
          -    100% {}
          -}
          -
        - -
      6. -
      - -

      The following figure shows the full Tizen logo animation with the transform properties.

      -

      Figure: Full Tizen logo animation

      -

      Full Tizen logo animation

      - -

      Source Code

      -

      For the complete source code related to this use case, see the following files:

      - - -

      Creating Fade Animation Effects

      - - -

      To enhance the user experience of your application, you must learn to use fade animation effects.

      -

      The modal layer pop-up can be used to, for example, show enlarged thumbnail images or notice messages. The modal layer pop-up has the following basic properties:

      -
        -
      • If an event is fired, it gradually becomes visible. This is known as the Fade In effect.
      • -
      • The existing background is covered with a translucent layer to make the user focus on the pop-up.
      • -
      • When the pop-up is closed, it gradually becomes transparent. This is known as the Fade Out effect.
      • -
      - -

      Figure: Fade effect

      -

      Fade effect

      - -

      You can control UI events and change the DOM elements in the following ways:

      -
        -
      • Events can be controlled with JavaScript, and DOM elements can be devised with CSS.
      • -
      • You can use JavaScript frameworks, such as jQuery, Prototype, and Dojo.
      • -
      - -

      To create fade effects:

      - -
        -
      • Create a modal layer pop-up using jQuery: - -
        -(function($) 
        -{
        -   function showModalPopup(url) 
        -   {
        -      $('body').append('<div class="mask"></div>'); /* Mask in body appended */
        -      $('.mask').css({'height': $(window).height()}); /* Mask area set */
        -
        -      /* Target layer position set */
        -      $(url).css(
        -      {
        -         'top': ($(window).height()/2 + $(document).scrollTop() - $(url).height()/2) + 'px', 
        -         'left': ($(window).width()/2 + $(document).scrollLeft() - $(url).width()/2) + 'px'
        -      });
        -
        -      /* Fade effect */
        -      $('.mask').fadeTo('slow', 0.7);
        -      $(url).fadeTo('slow', 1);
        -   };
        -
        -   $('.layerpopupActive a').on('click', function()
        -   {
        -      var targetUrl = $(this).attr('href');
        -
        -      showModalPopup(targetUrl);
        -
        -      return false;
        -   });
        -  
        -   /* End processing - Fade Out effect */
        -    
        -   $('body').on('click', function(e) 
        -   {
        -      if (e.target.className === 'mask') 
        -      {
        -         $('.layerpop').fadeOut();
        -         $('.mask').fadeOut(400, function() 
        -         {
        -            $('.mask').remove();
        -         });
        -      };
        -   });
        -})(jQuery);
        - -

        If the animation effect is created by using JavaScript, the browser executes the following tasks:

        -
          -
        1. A structure layer is created and added to the document. This is a CPU task.
        2. -
        3. The added layer is painted as a default value. This is a GPU task.
        4. -
        5. The layer is painted once again according to the change of value. This is a CPU operation.
        6. -
        - -

        Steps a and c incur CPU tasks, which affect performance the most.

        -

        In case of step a, only 2 layers are created, but as the number of layers created increases, the efficiency of page rendering work drops. In case of step c as well, the more steps it undergoes, the slower the rendering becomes.

        -

        In certain browsers, even if the style of just 1 layer is changed, the entire document is repainted. As the repainting takes only a moment, any animation effects that are supposed to happen cannot be executed in such a short time. This issue occurs frequently in Android™ with severe fragmentation.

        - - - - - - - - - - -
        Note
        If a new layer is created in Android 4.0X version, and if the fade effect is used, it only shows the initial value and the result value of the layer style.
        - -

        To avoid such a situation to the maximum possible extent, CPU tasks must be reduced to the minimum, and it is better to use transition or animation that uses the internal timer of the browser.

        - - - - - - - - - - -
        Note
        In case of using 3D effects, -webkit-transform: translateZ(0); can be used to accelerate the hardware. However, since hardware acceleration support varies between the OS and devices, the actual resulting effects can vary too. Moreover, in the case of version Android™ 2.1, iOS™3.X and below, note that transition and animation may not be realized.
        -
      • -
      • Create a modal layer pop-up using CSS3: -
        -<!--CSS-->
        -.mask 
        -{
        -   opacity: 0;
        -   z-index: -1;
        -   -webkit-transition: all 400ms ease-in-out;
        -}
        -
        -.mask.active 
        -{
        -   opacity: .7;
        -   z-index: 498;
        -}
        -
        -<!--Layer pop-up public styles-->
        -.layerpop 
        -{
        -   opacity: 0;
        -   z-index: -1;
        -   -webkit-transition: all 300ms ease-in-out;
        -}
        -
        -.layerpop.active 
        -{
        -   opacity: 1;
        -   z-index: 499;
        -}
        -/* JavaScript */
        -function showModalPopup(url) 
        -{
        -   url.className += 'active';
        -}
        -
      • -
      -

      Performance Differences

      - -

      There can be a difference in performance depending on how the modal layer pop-up is used.

      -

      The following figures illustrate the difference in event performance, when using JavaScript and CSS3.

      -

      Figure: Event performance using JavaScript

      -

      Events using JavaScript

      - -

      Figure: Event performance using CSS3

      -

      Events using CSS3

      - -

      The following figures illustrate the difference in memory performance, when using JavaScript and CSS3.

      -

      Figure: Memory performance using JavaScript

      -

      Memory when using JavaScript

      - -

      Figure: Memory performance using CSS3

      -

      Memory when using CSS3

      - -

      When the styles are applied using JavaScript, the UI thread is used to create the pop-up. The UI thread increases the usage of CPU memory in proportion to the number of pop-ups used.

      - - - - - - - - - - -
      Note
      Tizen provides remote debugging through the JavaScript Debugger tool.
      - - - - - - - - - - -
      Note

      If CSS is used, the handling of JavaScript events and UI DOM operations becomes unnecessary, so the load of the UI thread decreases, and the usage of CPU memory decreases as well. However, CSS3 transitions cannot be applied to versions below Android™ 2.3 and for versions above iOS™ 4.3, which are still widely used, so attention is needed when distributing it to various devices.

      - -

      Using Hardware Acceleration

      - -

      The rendering performance of a Web application depends on both the Tizen platform and application design.

      -

      In hardware acceleration, GPU is used to perform a function faster than is possible if the application is running on the CPU. It enhances the rendering performance in the dynamic objects used in Web applications.

      - -

      Using CSS Transition and 3D Transform

      -

      To improve the rendering performance, separate moving elements to independent layers as much as possible. You can use CSS transition with the -webkit-transition CSS attribute, or 3D transform with the -webkit-transform attribute. For the best performance, set the -webkit-transform attribute to the 3D type.

      -

      In all the following examples, a blue box moves from top left to bottom right for a second.

      -

      Figure: Blue box

      -

      Blue box

      - -
        -
      • Use CPU painting: -

        JavaScript performs CPU painting for a moving element for each frame at 16 ms interval using the setTimeout() method over the changing top-left coordinate. This approach does not use hardware acceleration, but only running on the CPU.

        -
          -
        1. Construct the blue box and set its position on the screen: -
          <!DOCTYPE html>
          -<html xmlns="http://www.w3.org/1999/xhtml">
          -   <head>
          -      <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
          -      <title>JavaScript transition sample</title>
          -      <style>
          -         #box 
          -         {
          -            position: absolute;
          -            width: 100px;
          -            height: 100px;
          -            background-color: blue;
          -            left: 0px;
          -            top: 50px;
          -         }
          -      </style>
          -
        2. -
        3. -

          Perform CPU painting for a moving element at a rate of 1 frame per 16 ms (62.5 frames per second) using the setTimeout() method:

          -
                <script>
          -         var delta = 0;
          -         function startTransition() 
          -         {
          -            process();
          -         }
          -         function process ()
          -         {
          -            document.getElementById('box').style.left = delta + "px";
          -            document.getElementById('box').style.top = delta + 50 + "px";
          -            delta += 4;
          -            if (delta <= 200)
          -               setTimeout(function() {process();}, 16);
          -         }
          -      </script>
          -   </head>
          -   <body>
          -      <div id='box' onclick='startTransition()'>click me!</div>
          -   </body>
          -</html>
      • -
      • Use CSS transition: -

        Separate a moving element to an independent layer with the -webkit-transition CSS attribute. This approach uses hardware acceleration, and can enhance performance while an element is moving.

        -
        <!DOCTYPE html>
        -<html xmlns="http://www.w3.org/1999/xhtml">
        -   <head>
        -      <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
        -      <title>-webkit-transition sample</title>
        -      <style>
        -         #box 
        -         {
        -            position: absolute;
        -            width: 100px;
        -            height: 100px;
        -            left: 0px;
        -            top: 50px;
        -            background-color: blue;
        -            -webkit-transition-duration: 1s;
        -            -webkit-transition-timing-function: linear;
        -         }
        -      </style>
        -      <script>
        -         function startTransition()
        -         {
        -            document.getElementById('box').style.webkitTransform = "translate(200px, 200px)";
        -         }
        -      </script>
        -   </head>
        -   <body>
        -      <div id='box' onclick='startTransition()'>click me!</div>
        -   </body>
        -</html>
        -
      • -
      • Use 3D transform: -

        Use the -webkit-transform: translate3d 3D transform attribute. The element is separated to an independent layer and uses hardware acceleration irrespective of its movement:

        -
        <!DOCTYPE html>
        -<html xmlns="http://www.w3.org/1999/xhtml">
        -   <head>
        -      <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
        -      <title>-webkit-transition with translate3d sample</title>
        -      <style>
        -         #box 
        -         {
        -            position: absolute;
        -            width: 100px;
        -            height: 100px;
        -            left: 0px;
        -            top: 50px;
        -            background-color: blue;
        -            -webkit-transform: translate3d(0, 0, 0);
        -            -webkit-transition-duration: 1s;
        -            -webkit-transition-timing-function: linear;
        -         }
        -      </style>
        -      <script>
        -         function startTransition() 
        -         {
        -            document.getElementById('box').style.webkitTransform = "translate3d(200px, 200px, 0px)";
        -         }
        -      </script>
        -   </head>
        -   <body>
        -      <div id='box' onclick='startTransition()'>click me!<p></div>
        -   </body>
        -</html>
        -
      • -
      -

      Using Accelerated Overflow Scroll

      -

      If a page has an overflow scroll, use the -webkit-overflow-scrolling attribute. It separates overflow scroll to an independent layer and enhances rendering performance:

      -
      #scroll_area 
      -{
      -   overflow: scroll;
      -   -webkit-overflow-scrolling: touch;
      -}
      - - - - - -
      - -Go to top - - - - - - - diff --git a/org.tizen.tutorials/html/web/w3c/dom/transition_tutorial_w.htm b/org.tizen.tutorials/html/web/w3c/dom/transition_tutorial_w.htm deleted file mode 100644 index 79ae46c..0000000 --- a/org.tizen.tutorials/html/web/w3c/dom/transition_tutorial_w.htm +++ /dev/null @@ -1,320 +0,0 @@ - - - - - - - - - - - - - - CSS Transitions Module Level 3: Changing Element Styles - - - - - - -
      -

      CSS Transitions Module Level 3: Changing Element Styles

      - -

      This tutorial demonstrates how you can use transitions to change element property values naturally.

      - -

      Warm-up

      -

      Become familiar with the CSS Transitions Module Level 3 API basics by learning about:

      -
        -
      • Modifying Element Properties -

        Modify element properties by adding a background color and transition effects, and changing the font color and size.

      • -
      -

      Follow-up

      -

      Once we have learned the basics of CSS Transitions Module Level 3 API, we can now move on to more advanced tasks, including:

      - - -

      Modifying Element Properties

      - -

      To enhance the user experience of your application, you must learn to use transitions to change element property values naturally. This example uses a partial section of the http://tizen.org Web site, where the current "UPCOMING EVENTS" area only has the text-decoration: underline property in a mouseover state (the text gets underlined when the mouse hovers over it). To improve the effects, the example adds various transitions properties in this area.

      - - -

      Figure: Tizen site section to be transitioned

      -

      Tizen site section to be transitioned

      - - -
      1. Add a background color change to the "UPCOMING EVENTS" area during a mouseover state:

        - -
        1. Originally, the area on the site is defined as follows:

          - -
          -<h2 class="block-title">Upcoming Events</h2>
          -
          - - -

          Additionally, a transition property is declared in the block-title class:

          - -
          -.block-title 
          -{
          -   -webkit-transition: all 2s ease;
          -}
          -
          -

          The all value in the transition property means that the transition effect applies to all CSS properties of the element.

          -
        2. - -
        3. Define the mouseover state for the block-title class: - -
          -.block-title: hover {background: #eaeaea;}
          -
          - -

          Due to the CSS characteristics, adding a class through an event allows immediate rendering in the screen.

        - -

        When the mouse is moved over the "UPCOMING EVENTS" area, the background color changes.

        - -

        Background color change

      2. - -
      3. - -

        Apply the transition effect in other elements:

        - -
        1. To avoid unnecessary repetition, tie a list of transition elements together into groups a and span: - -
          -.location, .date, .location .anibg, h3 > a, .day > span 
          -{
          -   -webkit-transition: all 1s ease;
          -}
          -
        2. - -
        3. When the mouse hovers over the date element, change the background of the date and the font size of all the elements tied into the span group. When the mouse hovers over the title element, change the color of all elements tied into the a group.

          -
          -.date: hover {background: #d2ecff !important;}
          -.date: hover .day > span {font-size: 1.9em;}
          -
          -.event-info: hover h3 > a {color: #ec4986;}
          -
        - -

        Before mouseover -

      4. -
      5. - -

        Emphasize the location phrase by adding an empty element. The emphasis is made by filling the background with black from left to right, and changing the font color to an appropriate value for the black background.

        -
          -
        1. Add the empty element:

          - -
          -<div class="location">San Francisco, CA<span class="anibg"></span></div>
          -
        2. -
        3. Create the effect using the width value of the added element:

          -
          -.location {position: relative; z-index: 3; margin-top: 3px;}
          -.location .anibg 
          -{
          -   position: absolute; 
          -   left: -3px; top: 0; 
          -   display: block; 
          -   width: 0; height: 100%; 
          -   background: #000; 
          -   z-index: -1;
          -}
          -
          - -

          The effect is defined by using the position property. The location element position is declared relative, while the anibg child element position is declared as absolute. The width of the child element basic state is set as 0. Since the child element layer covers the location text, the child element has been defined to come out from the back of the text in the z-index value of the child.

        4. -
        5. Define the state to be changed:

          -
          -.location, .date, .location .anibg, h3 > a, .day > span 
          -{
          -   -webkit-transition: all 1s ease;
          -}
          -
          -.event-info: hover .location {color: #fff;}
          -.event-info: hover .location .anibg {width: 100%; color: #fff;}
          -
          - -

          The transition takes place when the property in question is at the front on the screen. The event-info class is used as the subject for the change, and it has been defined so that the transition occurs simultaneously in the .location and .anibg elements when the mouse hovers over any of the elements tied together as group a. -

        6. - -

        Location phrase emphasis

        -
      -

      Source Code

      -

      For the complete source code related to this use case, see the following file:

      - - -

      Using Hardware Acceleration

      - -

      The rendering performance of a Web application depends on both the Tizen platform and application design.

      -

      In hardware acceleration, GPU is used to perform a function faster than is possible if the application is running on the CPU. It enhances the rendering performance in the dynamic objects used in Web applications.

      - -

      Using CSS Transition and 3D Transform

      -

      To improve the rendering performance, separate moving elements to independent layers as much as possible. You can use CSS transition with the -webkit-transition CSS attribute, or 3D transform with the -webkit-transform attribute. For the best performance, set the -webkit-transform attribute to the 3D type.

      -

      In all the following examples, a blue box moves from top left to bottom right for a second.

      -

      Figure: Blue box

      -

      Blue box

      - -
        -
      • Use CPU painting: -

        JavaScript performs CPU painting for a moving element for each frame at 16 ms interval using the setTimeout() method over the changing top-left coordinate. This approach does not use hardware acceleration, but only running on the CPU.

        -
          -
        1. Construct the blue box and set its position on the screen: -
          <!DOCTYPE html>
          -<html xmlns="http://www.w3.org/1999/xhtml">
          -   <head>
          -      <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
          -      <title>JavaScript transition sample</title>
          -      <style>
          -         #box 
          -         {
          -            position: absolute;
          -            width: 100px;
          -            height: 100px;
          -            background-color: blue;
          -            left: 0px;
          -            top: 50px;
          -         }
          -      </style>
          -
        2. -
        3. -

          Perform CPU painting for a moving element at a rate of 1 frame per 16 ms (62.5 frames per second) using the setTimeout() method:

          -
                <script>
          -         var delta = 0;
          -         function startTransition() 
          -         {
          -            process();
          -         }
          -         function process ()
          -         {
          -            document.getElementById('box').style.left = delta + "px";
          -            document.getElementById('box').style.top = delta + 50 + "px";
          -            delta += 4;
          -            if (delta <= 200)
          -               setTimeout(function() {process();}, 16);
          -         }
          -      </script>
          -   </head>
          -   <body>
          -      <div id='box' onclick='startTransition()'>click me!</div>
          -   </body>
          -</html>
      • -
      • Use CSS transition: -

        Separate a moving element to an independent layer with the -webkit-transition CSS attribute. This approach uses hardware acceleration, and can enhance performance while an element is moving.

        -
        <!DOCTYPE html>
        -<html xmlns="http://www.w3.org/1999/xhtml">
        -   <head>
        -      <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
        -      <title>-webkit-transition sample</title>
        -      <style>
        -         #box 
        -         {
        -            position: absolute;
        -            width: 100px;
        -            height: 100px;
        -            left: 0px;
        -            top: 50px;
        -            background-color: blue;
        -            -webkit-transition-duration: 1s;
        -            -webkit-transition-timing-function: linear;
        -         }
        -      </style>
        -      <script>
        -         function startTransition()
        -         {
        -            document.getElementById('box').style.webkitTransform = "translate(200px, 200px)";
        -         }
        -      </script>
        -   </head>
        -   <body>
        -      <div id='box' onclick='startTransition()'>click me!</div>
        -   </body>
        -</html>
        -
      • -
      • Use 3D transform: -

        Use the -webkit-transform: translate3d 3D transform attribute. The element is separated to an independent layer and uses hardware acceleration irrespective of its movement:

        -
        <!DOCTYPE html>
        -<html xmlns="http://www.w3.org/1999/xhtml">
        -   <head>
        -      <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
        -      <title>-webkit-transition with translate3d sample</title>
        -      <style>
        -         #box 
        -         {
        -            position: absolute;
        -            width: 100px;
        -            height: 100px;
        -            left: 0px;
        -            top: 50px;
        -            background-color: blue;
        -            -webkit-transform: translate3d(0, 0, 0);
        -            -webkit-transition-duration: 1s;
        -            -webkit-transition-timing-function: linear;
        -         }
        -      </style>
        -      <script>
        -         function startTransition() 
        -         {
        -            document.getElementById('box').style.webkitTransform = "translate3d(200px, 200px, 0px)";
        -         }
        -      </script>
        -   </head>
        -   <body>
        -      <div id='box' onclick='startTransition()'>click me!<p></div>
        -   </body>
        -</html>
        -
      • -
      -

      Using Accelerated Overflow Scroll

      -

      If a page has an overflow scroll, use the -webkit-overflow-scrolling attribute. It separates overflow scroll to an independent layer and enhances rendering performance:

      -
      #scroll_area 
      -{
      -   overflow: scroll;
      -   -webkit-overflow-scrolling: touch;
      -}
      - - - - -
      - -Go to top - - - - - - - diff --git a/org.tizen.tutorials/html/web/w3c/dom/woff_tutorial_w.htm b/org.tizen.tutorials/html/web/w3c/dom/woff_tutorial_w.htm deleted file mode 100644 index c26e71b..0000000 --- a/org.tizen.tutorials/html/web/w3c/dom/woff_tutorial_w.htm +++ /dev/null @@ -1,139 +0,0 @@ - - - - - - - - - - - - - - WOFF File Format 1.0: Changing Fonts Using WOFF - - - - - - -
      -

      WOFF File Format 1.0: Changing Fonts Using WOFF

      - -

      This tutorial demonstrates how you can modify fonts with WOFF.

      - -

      Warm-up

      -

      Become familiar with the WOFF File Format 1.0 API basics by learning about:

      - - -

      Using the WOFF File Format

      - -

      To enhance the user experience of your application, you must learn to use the WOFF (Web Open Font Format) file format 1.0, which is a W3C standard font packaging format used in Web pages:

      - -
        -
      1. Download and use fonts installed on the Web server by creating @font-face rules. Within the rules, you can define the following properties: -
          -
        • font-family -

          Defines a name for the font. This property is mandatory.

        • -
        • src -

          Defines the URL of the font file on the server. This property is mandatory. If the local attribute is defined, the font resource is not downloaded from the server if it already exists in the local storage.

        • -
        • font-stretch -

          Defines the way the font is stretched. This property is optional.

        • -
        • font-style -

          Defines the font style. This property is optional.

        • -
        • font-weight -

          Defines the font weight. This property is optional.

        • -
        -

        Define the rules with in a <style> element in the <head> section of a Web page:

        -
        -<head>
        -   <style>
        -   @font-face
        -   {
        -      font-family: MuseoSans;
        -      src: local('MuseoSans'),
        -           url('https://www.tizen.org/sites/all/themes/tizen_theme/webfonts/244CBE_1_0.woff') format('woff');
        -   }
        -
        -   @font-face
        -   {
        -      font-family: MuseoSans;
        -      font-weight: bold;
        -      src: local('MuseoSans'),
        -           url('https://www.tizen.org/sites/all/themes/tizen_theme/webfonts/244CBE_0_0.woff') format('woff');
        -   }
        -
        -   @font-face
        -   {
        -      font-family: MuseoSans;
        -      font-weight: 900;
        -      src: local('MuseoSans'),
        -           url('https://www.tizen.org/sites/all/themes/tizen_theme/webfonts/244CBE_2_0.woff') format('woff');
        -   }
        -
        -   p:nth-child(2) {font-family: MuseoSans}
        -   p:nth-child(3) {font-family: MuseoSans; font-weight: bold;}
        -   p:nth-child(4) {font-family: MuseoSans; font-weight: 900;}
        -   </style>
        -</head>
        -
      2. -
      3. In the <body> section, create <p> elements containing text in which the font rules are implemented: -
        <body>
        -   <p>The quick brown fox jumps over a lazy dog.</p>
        -   <p>The quick brown fox jumps over a lazy dog.</p>
        -   <p>The quick brown fox jumps over a lazy dog.</p>
        -   <p>The quick brown fox jumps over a lazy dog.</p>
        -</body>
        -</html>
        -
        -
      4. -
      -

      Figure: Implementing the @font-face rules (in mobile applications only)

      -

      Implementing the @font-face rules (in mobile applications only)

      - - - - - - -
      - -Go to top - - - - - - - diff --git a/org.tizen.tutorials/html/web/w3c/location/geolocation_tutorial_w.htm b/org.tizen.tutorials/html/web/w3c/location/geolocation_tutorial_w.htm index 7a20b7b..410567a 100644 --- a/org.tizen.tutorials/html/web/w3c/location/geolocation_tutorial_w.htm +++ b/org.tizen.tutorials/html/web/w3c/location/geolocation_tutorial_w.htm @@ -1,165 +1,165 @@ - - - - - - - - - - - - - Geolocation API Specification: Managing Location Information - - - - - -
      - -

      Geolocation API Specification: Managing Location Information

      - -

      This tutorial demonstrates how you can retrieve location information.

      - -

      Warm-up

      -

      Become familiar with the Geolocation API Specification basics by learning about:

      - - - -

      Retrieving Location Information

      - -

      To provide users with location-based features, you must learn to create a mobile GPS application to retrieve location information:

      -
        -
      1. Create event handlers for the location requests. -

        The Geolocation interface allows 2 types of location requests: "one-shot" position request and repeated position updates. Both request types use the same event handlers. The success event handler is invoked when an attempt to obtain the current location is successful, while the error event handler is invoked when the attempt fails. The success event handler is mandatory, and contains a position parameter that hold the actual position information.

        - -
        -function successCallback(position) 
        -{
        -   document.getElementById("locationInfo").innerHTML = "Latitude: " +   
        -   position.coords.latitude + "<br>Longitude: " + position.coords.longitude;
        -}
        -
        -function errorCallback(error) 
        -{
        -   var errorInfo = document.getElementById("locationInfo");
        -
        -   switch (error.code) 
        -   {
        -      case error.PERMISSION_DENIED:         
        -         errorInfo.innerHTML = "User denied the request for Geolocation.";
        -         break;
        -      case error.POSITION_UNAVAILABLE:
        -         errorInfo.innerHTML = "Location information is unavailable.";
        -         break;
        -      case error.TIMEOUT:
        -         errorInfo.innerHTML = "The request to get user location timed out.";
        -         break;
        -      case error.UNKNOWN_ERROR:
        -         errorInfo.innerHTML = "An unknown error occurred.";
        -         break;
        -   }
        -}
        -
      2. -
      3. Create a "one-shot" position request with the getCurrentPosition() method. -

        The maximumAge parameter determines that if the user agent does not have cached position information that is fresher than 60000 milliseconds (1 minute), new location information is automatically obtained.

        -
        -function oneShotFunc() 
        -{
        -   if (navigator.geolocation) 
        -   {
        -      navigator.geolocation.getCurrentPosition(successCallback, errorCallback, 
        -                                               {maximumAge: 60000});
        -   } 
        -   else 
        -   {
        -      document.getElementById("locationInfo").innerHTML = "Geolocation is not supported.";
        -   }
        -}
        -

        If you do not want to wait for new position information, but are willing to use cached information regardless of how old it is, you can use the maximumAge and timeout parameters together ({maximumAge: Infinity, timeout: 0}). In this case, if the user agent has no position information cached, it automatically invokes the error event handler.

        - -
      4. -
      5. Create a repeated position update request with the watchPosition() method: -
        -function watchFunc() 
        -{
        -   if (navigator.geolocation) 
        -   {
        -      watchId = navigator.geolocation.watchPosition(successCallback, errorCallback);
        -   } 
        -   else 
        -   {
        -      document.getElementById("locationInfo").innerHTML = "Geolocation is not supported.";
        -   }
        -}
        -
      6. -
      7. The repeated position update request continues until the clearWatch() method is called with the corresponding identifier: -
        -function stopWatchFunc() 
        -{
        -   if (navigator.geolocation) 
        -   {
        -      navigator.geolocation.clearWatch(watchId);
        -   } 
        -   else 
        -   {
        -      document.getElementById("locationInfo").innerHTML = "Geolocation is not supported.";
        -   }
        -}
        -
      8. -
      - -

      The following figure illustrates the GPS application.

      -

      Figure: GPS application (in mobile applications only)

      -

      GPS application (in mobile applications only)

      - -

      Source Code

      -

      For the complete source code related to this use case, see the following file:

      - - - - - -
      - -Go to top - - - - - - + + + + + + + + + + + + + Geolocation API Specification: Managing Location Information + + + + + +
      + +

      Geolocation API Specification: Managing Location Information

      + +

      This tutorial demonstrates how you can retrieve location information.

      + +

      Warm-up

      +

      Become familiar with the Geolocation API Specification basics by learning about:

      + + + +

      Retrieving Location Information

      + +

      To provide users with location-based features, you must learn to create a mobile GPS application to retrieve location information:

      +
        +
      1. Create event handlers for the location requests. +

        The Geolocation interface allows 2 types of location requests: "one-shot" position request and repeated position updates. Both request types use the same event handlers. The success event handler is invoked when an attempt to obtain the current location is successful, while the error event handler is invoked when the attempt fails. The success event handler is mandatory, and contains a position parameter that hold the actual position information.

        + +
        +function successCallback(position) 
        +{
        +   document.getElementById("locationInfo").innerHTML = "Latitude: " +   
        +   position.coords.latitude + "<br>Longitude: " + position.coords.longitude;
        +}
        +
        +function errorCallback(error) 
        +{
        +   var errorInfo = document.getElementById("locationInfo");
        +
        +   switch (error.code) 
        +   {
        +      case error.PERMISSION_DENIED:         
        +         errorInfo.innerHTML = "User denied the request for Geolocation.";
        +         break;
        +      case error.POSITION_UNAVAILABLE:
        +         errorInfo.innerHTML = "Location information is unavailable.";
        +         break;
        +      case error.TIMEOUT:
        +         errorInfo.innerHTML = "The request to get user location timed out.";
        +         break;
        +      case error.UNKNOWN_ERROR:
        +         errorInfo.innerHTML = "An unknown error occurred.";
        +         break;
        +   }
        +}
        +
      2. +
      3. Create a "one-shot" position request with the getCurrentPosition() method. +

        The maximumAge parameter determines that if the user agent does not have cached position information that is fresher than 60000 milliseconds (1 minute), new location information is automatically obtained.

        +
        +function oneShotFunc() 
        +{
        +   if (navigator.geolocation) 
        +   {
        +      navigator.geolocation.getCurrentPosition(successCallback, errorCallback, 
        +                                               {maximumAge: 60000});
        +   } 
        +   else 
        +   {
        +      document.getElementById("locationInfo").innerHTML = "Geolocation is not supported.";
        +   }
        +}
        +

        If you do not want to wait for new position information, but are willing to use cached information regardless of how old it is, you can use the maximumAge and timeout parameters together ({maximumAge: Infinity, timeout: 0}). In this case, if the user agent has no position information cached, it automatically invokes the error event handler.

        + +
      4. +
      5. Create a repeated position update request with the watchPosition() method: +
        +function watchFunc() 
        +{
        +   if (navigator.geolocation) 
        +   {
        +      watchId = navigator.geolocation.watchPosition(successCallback, errorCallback);
        +   } 
        +   else 
        +   {
        +      document.getElementById("locationInfo").innerHTML = "Geolocation is not supported.";
        +   }
        +}
        +
      6. +
      7. The repeated position update request continues until the clearWatch() method is called with the corresponding identifier: +
        +function stopWatchFunc() 
        +{
        +   if (navigator.geolocation) 
        +   {
        +      navigator.geolocation.clearWatch(watchId);
        +   } 
        +   else 
        +   {
        +      document.getElementById("locationInfo").innerHTML = "Geolocation is not supported.";
        +   }
        +}
        +
      8. +
      + +

      The following figure illustrates the GPS application.

      +

      Figure: GPS application (in mobile applications only)

      +

      GPS application (in mobile applications only)

      + +

      Source Code

      +

      For the complete source code related to this use case, see the following file:

      + + + + + +
      + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.tutorials/html/web/w3c/location/location_tutorials_w.htm b/org.tizen.tutorials/html/web/w3c/location/location_tutorials_w.htm index 8b2f6b3..3ffd3fb 100644 --- a/org.tizen.tutorials/html/web/w3c/location/location_tutorials_w.htm +++ b/org.tizen.tutorials/html/web/w3c/location/location_tutorials_w.htm @@ -1,64 +1,64 @@ - - - - - - - - - - - - - Location: Using Location Features - - - - - -
      - -

      Location: Using Location Features

      - -

      The location tutorials demonstrate how to use the following features in creating Tizen Web applications:

      - - - - - - -
      - -Go to top - - - - - - + + + + + + + + + + + + + Location: Using Location Features + + + + + +
      + +

      Location: Using Location Features

      + +

      The location tutorials demonstrate how to use the following features in creating Tizen Web applications:

      + + + + + + +
      + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.tutorials/html/web/w3c/media/media_tutorials_w.htm b/org.tizen.tutorials/html/web/w3c/media/media_tutorials_w.htm index 5a9fa3c..def7baf 100644 --- a/org.tizen.tutorials/html/web/w3c/media/media_tutorials_w.htm +++ b/org.tizen.tutorials/html/web/w3c/media/media_tutorials_w.htm @@ -39,7 +39,7 @@
    • HTML5 video and audio element: Playing and Managing Multimedia Content

      Demonstrates how you can create a player using video and audio elements.

    -

    The following tutorials apply in mobile applications only:

    +

    The following tutorials apply in mobile applications only:

    • HTML Media Capture: Activating Media Capture Capabilities

      Demonstrates how you can activate the media capture feature during file upload.

    • Web Audio: Playing Audio Content

      Demonstrates how you can play audio content using the HTML5 audio element.

    • diff --git a/org.tizen.tutorials/html/web/w3c/perf_opt/page_tutorial_w.htm b/org.tizen.tutorials/html/web/w3c/perf_opt/page_tutorial_w.htm index 9aa4dd5..409c54c 100644 --- a/org.tizen.tutorials/html/web/w3c/perf_opt/page_tutorial_w.htm +++ b/org.tizen.tutorials/html/web/w3c/perf_opt/page_tutorial_w.htm @@ -201,15 +201,15 @@ - diff --git a/org.tizen.tutorials/html/web/w3c/perf_opt/performance_tutorials_w.htm b/org.tizen.tutorials/html/web/w3c/perf_opt/performance_tutorials_w.htm index 62115c9..5562228 100644 --- a/org.tizen.tutorials/html/web/w3c/perf_opt/performance_tutorials_w.htm +++ b/org.tizen.tutorials/html/web/w3c/perf_opt/performance_tutorials_w.htm @@ -52,15 +52,15 @@ - diff --git a/org.tizen.tutorials/html/web/w3c/perf_opt/timing_control_tutorial_w.htm b/org.tizen.tutorials/html/web/w3c/perf_opt/timing_control_tutorial_w.htm index 2f6f8f5..51431e9 100644 --- a/org.tizen.tutorials/html/web/w3c/perf_opt/timing_control_tutorial_w.htm +++ b/org.tizen.tutorials/html/web/w3c/perf_opt/timing_control_tutorial_w.htm @@ -197,15 +197,15 @@ handlerRequest = window.webkitRequestAnimationFrame(nextFrame); - diff --git a/org.tizen.tutorials/html/web/w3c/perf_opt/web_workers_tutorial_w.htm b/org.tizen.tutorials/html/web/w3c/perf_opt/web_workers_tutorial_w.htm index fb0727e..bbccb9b 100644 --- a/org.tizen.tutorials/html/web/w3c/perf_opt/web_workers_tutorial_w.htm +++ b/org.tizen.tutorials/html/web/w3c/perf_opt/web_workers_tutorial_w.htm @@ -24,7 +24,7 @@

      Content

      Related Info

        @@ -46,7 +46,7 @@ @@ -118,7 +118,7 @@ worker.addEventListener('error', errorMessage, false); -

        Sending Messages between Web Workers

        +

        Sending Messages Between Web Workers

        Learning how to send messages between Web workers is a useful resource management skill:

        @@ -209,15 +209,15 @@ self.onmessage = function(e) - diff --git a/org.tizen.tutorials/html/web/w3c/security/cors_tutorial_w.htm b/org.tizen.tutorials/html/web/w3c/security/cors_tutorial_w.htm index f549c88..f1ad7cc 100644 --- a/org.tizen.tutorials/html/web/w3c/security/cors_tutorial_w.htm +++ b/org.tizen.tutorials/html/web/w3c/security/cors_tutorial_w.htm @@ -1,255 +1,255 @@ - - - - - - - - - - - - - Cross-Origin Resource Sharing: Enabling Client-side Cross-origin Requests - - - - - - -
        -

        Cross-Origin Resource Sharing: Enabling Client-side Cross-origin Requests

        - - -

        This tutorial demonstrates how you can allow cross-origin resource sharing (CORS) through simple and preflight requests.

        - - -

        Warm-up

        -

        Become familiar with the Cross-Origin Resource Sharing API basics by learning about:

        - - -

        Using Simple Requests

        - -

        Learning how to handle a simple request based on XML HTTP Request level 2 enhances the security features of your application:

        - -
          -
        1. Create an XML HTTP request on the client side, using JavaScript code that requests Ajax communication: -
          -<script>
          -   var method = "GET";
          -   var url = "http://another-domain.com/CORS/";
          -   var xhr = new XMLHttpRequest();
          -
          -   xhr.open(method, url);
          -   xhr.send();
          -</script>
          -
          -
        2. - -
        3. On the server side, define the domain from which requests are allowed. In this case, the http://origin-domain.com domain has the required authority. -
          -<?php
          -   header("Access-Control-Allow-Origin: http://origin-domain.com");
          -?>
          -
          -

          If all sites are allowed to send requests, use the wildcard (*):

          -
          -<?php
          -   header("Access-Control-Allow-Origin: *");
          -?>
          -
          -
        4. - -
        5. Check the request header. -

          If you check the request header through the network log, you find that an additional Origin header has been added. This header informs the relevant server of the sender side domain. The Origin header is protected in the browser side, and cannot be changed by the user.

          -
          -GET http://origin-domain.com/CORS/simple_reqeust.html HTTP/1.1
          -Host: origin-domain.com
          -Origin: http://origin-domain.com
          -
          -
        6. - -
        7. Check the response header: -
            -
          • If the request is received from a domain with access authority, the server allows a response. -The response header includes the Access-Control-Allow-Origin header set in the server side.

            -
            -HTTP/1/1 200 OK
            -Access-Control-Allow-Origin: http://origin-domain.com
            -
          • -
          • If the request is received from a domain without access authority, the server sends no response, and the following error occurs: -
            -XMLHttpRequest cannot load http://another-domain.com/CORS.
            -Origin http://another-domain.com/CORS is not allowed by Access-Control-Allow-Origin.
            -
          - - - - - - - - - - -
          Note
          You must define the authorized domains on the server side to ensure that CORS is handled properly. For more information on setting the authorization settings on different platforms, see Enable CORS Web site.
          -
        8. -
        -

        Source Code

        -

        For the complete source code related to this use case, see the following file:

        - - -

        Using Preflight Requests

        - -

        Learning how to handle a preflight request based on XML HTTP Request level 2 enhances the security features of your application.

        - -
          -
        1. Create an XML HTTP request on the client side, using JavaScript code that requests Ajax communication. In addition, define the request Content-Type and add a custom header. -
          -<script>
          -   var xhr = new XMLHttpRequest();
          -   xhr.open("PUT", "http://another-domain.com/CORS/");
          -
          -   xhr.setRequestHeader("Content-Type", "application/json");
          -
          -   xhr.setRequestHeader("Header-Custom-TizenCORS", "OK");
          -   xhr.send(data);
          -</script>
          -
          -
        2. - -
        3. On the server side, define the domain from which requests are allowed. In this case, the http://110.0.0.160:8081 domain has the required authority. In addition, define various server settings.

          -
          -<?php
          -   header("Access-Control-Allow-Origin: http://110.0.0.160:8081");
          -
          -   /* Allowed request method */
          -   header("Access-Control-Allow-Methods: PUT");
          -
          -   /* Allowed custom header */
          -   header("Access-Control-Allow-Headers: Content-Type");
          -
          -   /* Age set to 1 day to improve speed caching */
          -   header("Access-Control-Max-Age: 86400");
          -
          -   /* Options request exits before the page is completely loaded */
          -   if (strtolower($_SERVER['REQUEST_METHOD']) == 'options')
          -   {
          -      exit();
          -   }
          -
          -   /* Response data */
          -   $arr = array("user_name" => "tizen", "phone_number" => "12312334234");
          -
          -   /* Response data returned in JSON format */
          -   echo json_encode($arr);
          -?>
          -
          -
        4. - -
        5. Check the request and response headers. -

          If you check the network log, you find that 2 communications between the browser and server occur consecutively: first the preflight request and response, and then the actual request and response.

          -
            -
          • The preflight request checks the access authority before sending the actual data. The Origin and Access-Control-Request-Headers headers have been added to the request, because the request has a user-defined custom header, and the Content-Type set to application/json:

            -
            -OPTION http://origin-domain.com/CORS/non_simple_reqeust.html HTTP/1.1
            -Host: origin-domain.com
            -Origin: http://origin-domain.com
            -Access-Control-Request-Headers: Header-Custom-Tizen, origin, content-type
            -
          • -
          • If the request is sent from the browser side, a preflight response is sent for it from the server side. The browser determines from the response whether the actual data is sent. In the following preflight response example, the Content-Type and Header-Custom-Tizen are included in the Access-Control-Allow-Headers header:

            -
            -HTTP/1/1 200 OK
            -Access-Control-Allow-Headers: Content-Type, Header-Custom-Tizen
            -Access-Control-Allow-Methods:PUT
            -Access-Control-Allow-Origin:http://origin-domain.com
            -Access-Control-Max-Age:86400
            -
          • -
          • Once the access authority is checked, the browser sends the actual data request to the server side. This request includes the actual data:

            -
            -PUT http://origin-domain.com/CORS/non_simple_reqeust.html HTTP/1.1
            -Content-Type: application/json
            -Host: origin-domain.com
            -Origin: http://origin-domain.com
            -Header-Custom-TizenCOURSTest: OK
            -
          • -
          • The response to the actual data request contains the actual handled result:

            -
            -HTTP/1/1 200 OK
            -Access-Control-Allow-Headers: Content-Type, Header-Custom-Tizen
            -Access-Control-Allow-Methods: PUT
            -Access-Control-Allow-Origin: http://origin-domain.com
            -Access-Control-Max-Age:86400
            -
          - -

          If the access authority fails, the browser does not send the actual data request. Instead, the following error occurs in the browser side:

          -
          -XMLHttpRequest cannot load http://another-domain.com/CORS.
          -Request header field Header-Custom-Tizen is not allowed by Access-Control-Allow-Headers.
          -
          - - - - - - - - - - -
          Note
          You must define the authorized domains on the server side to ensure that CORS is handled properly. For more information on setting the authorization settings on different platforms, see Enable CORS Web site.
          -
        6. -
        - - - - - - - -
        - -Go to top - - - - - - + + + + + + + + + + + + + Cross-Origin Resource Sharing: Enabling Client-side Cross-origin Requests + + + + + + +
        +

        Cross-Origin Resource Sharing: Enabling Client-side Cross-origin Requests

        + + +

        This tutorial demonstrates how you can allow cross-origin resource sharing (CORS) through simple and preflight requests.

        + + +

        Warm-up

        +

        Become familiar with the Cross-Origin Resource Sharing API basics by learning about:

        + + +

        Using Simple Requests

        + +

        Learning how to handle a simple request based on XML HTTP Request level 2 enhances the security features of your application:

        + +
          +
        1. Create an XML HTTP request on the client side, using JavaScript code that requests Ajax communication: +
          +<script>
          +   var method = "GET";
          +   var url = "http://another-domain.com/CORS/";
          +   var xhr = new XMLHttpRequest();
          +
          +   xhr.open(method, url);
          +   xhr.send();
          +</script>
          +
          +
        2. + +
        3. On the server side, define the domain from which requests are allowed. In this case, the http://origin-domain.com domain has the required authority. +
          +<?php
          +   header("Access-Control-Allow-Origin: http://origin-domain.com");
          +?>
          +
          +

          If all sites are allowed to send requests, use the wildcard (*):

          +
          +<?php
          +   header("Access-Control-Allow-Origin: *");
          +?>
          +
          +
        4. + +
        5. Check the request header. +

          If you check the request header through the network log, you find that an additional Origin header has been added. This header informs the relevant server of the sender side domain. The Origin header is protected in the browser side, and cannot be changed by the user.

          +
          +GET http://origin-domain.com/CORS/simple_reqeust.html HTTP/1.1
          +Host: origin-domain.com
          +Origin: http://origin-domain.com
          +
          +
        6. + +
        7. Check the response header: +
            +
          • If the request is received from a domain with access authority, the server allows a response. +The response header includes the Access-Control-Allow-Origin header set in the server side.

            +
            +HTTP/1/1 200 OK
            +Access-Control-Allow-Origin: http://origin-domain.com
            +
          • +
          • If the request is received from a domain without access authority, the server sends no response, and the following error occurs: +
            +XMLHttpRequest cannot load http://another-domain.com/CORS.
            +Origin http://another-domain.com/CORS is not allowed by Access-Control-Allow-Origin.
            +
          + + + + + + + + + + +
          Note
          You must define the authorized domains on the server side to ensure that CORS is handled properly. For more information on setting the authorization settings on different platforms, see Enable CORS Web site.
          +
        8. +
        +

        Source Code

        +

        For the complete source code related to this use case, see the following file:

        + + +

        Using Preflight Requests

        + +

        Learning how to handle a preflight request based on XML HTTP Request level 2 enhances the security features of your application.

        + +
          +
        1. Create an XML HTTP request on the client side, using JavaScript code that requests Ajax communication. In addition, define the request Content-Type and add a custom header. +
          +<script>
          +   var xhr = new XMLHttpRequest();
          +   xhr.open("PUT", "http://another-domain.com/CORS/");
          +
          +   xhr.setRequestHeader("Content-Type", "application/json");
          +
          +   xhr.setRequestHeader("Header-Custom-TizenCORS", "OK");
          +   xhr.send(data);
          +</script>
          +
          +
        2. + +
        3. On the server side, define the domain from which requests are allowed. In this case, the http://110.0.0.160:8081 domain has the required authority. In addition, define various server settings.

          +
          +<?php
          +   header("Access-Control-Allow-Origin: http://110.0.0.160:8081");
          +
          +   /* Allowed request method */
          +   header("Access-Control-Allow-Methods: PUT");
          +
          +   /* Allowed custom header */
          +   header("Access-Control-Allow-Headers: Content-Type");
          +
          +   /* Age set to 1 day to improve speed caching */
          +   header("Access-Control-Max-Age: 86400");
          +
          +   /* Options request exits before the page is completely loaded */
          +   if (strtolower($_SERVER['REQUEST_METHOD']) == 'options')
          +   {
          +      exit();
          +   }
          +
          +   /* Response data */
          +   $arr = array("user_name" => "tizen", "phone_number" => "12312334234");
          +
          +   /* Response data returned in JSON format */
          +   echo json_encode($arr);
          +?>
          +
          +
        4. + +
        5. Check the request and response headers. +

          If you check the network log, you find that 2 communications between the browser and server occur consecutively: first the preflight request and response, and then the actual request and response.

          +
            +
          • The preflight request checks the access authority before sending the actual data. The Origin and Access-Control-Request-Headers headers have been added to the request, because the request has a user-defined custom header, and the Content-Type set to application/json:

            +
            +OPTION http://origin-domain.com/CORS/non_simple_reqeust.html HTTP/1.1
            +Host: origin-domain.com
            +Origin: http://origin-domain.com
            +Access-Control-Request-Headers: Header-Custom-Tizen, origin, content-type
            +
          • +
          • If the request is sent from the browser side, a preflight response is sent for it from the server side. The browser determines from the response whether the actual data is sent. In the following preflight response example, the Content-Type and Header-Custom-Tizen are included in the Access-Control-Allow-Headers header:

            +
            +HTTP/1/1 200 OK
            +Access-Control-Allow-Headers: Content-Type, Header-Custom-Tizen
            +Access-Control-Allow-Methods:PUT
            +Access-Control-Allow-Origin:http://origin-domain.com
            +Access-Control-Max-Age:86400
            +
          • +
          • Once the access authority is checked, the browser sends the actual data request to the server side. This request includes the actual data:

            +
            +PUT http://origin-domain.com/CORS/non_simple_reqeust.html HTTP/1.1
            +Content-Type: application/json
            +Host: origin-domain.com
            +Origin: http://origin-domain.com
            +Header-Custom-TizenCOURSTest: OK
            +
          • +
          • The response to the actual data request contains the actual handled result:

            +
            +HTTP/1/1 200 OK
            +Access-Control-Allow-Headers: Content-Type, Header-Custom-Tizen
            +Access-Control-Allow-Methods: PUT
            +Access-Control-Allow-Origin: http://origin-domain.com
            +Access-Control-Max-Age:86400
            +
          + +

          If the access authority fails, the browser does not send the actual data request. Instead, the following error occurs in the browser side:

          +
          +XMLHttpRequest cannot load http://another-domain.com/CORS.
          +Request header field Header-Custom-Tizen is not allowed by Access-Control-Allow-Headers.
          +
          + + + + + + + + + + +
          Note
          You must define the authorized domains on the server side to ensure that CORS is handled properly. For more information on setting the authorization settings on different platforms, see Enable CORS Web site.
          +
        6. +
        + + + + + + + +
        + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.tutorials/html/web/w3c/security/iframe_tutorial_w.htm b/org.tizen.tutorials/html/web/w3c/security/iframe_tutorial_w.htm index a7c2ffc..09c61bc 100644 --- a/org.tizen.tutorials/html/web/w3c/security/iframe_tutorial_w.htm +++ b/org.tizen.tutorials/html/web/w3c/security/iframe_tutorial_w.htm @@ -1,424 +1,424 @@ - - - - - - - - - - - - - HTML5 iframe element: Controlling HTML Elements - - - - - - -
        -

        HTML5 iframe element: Controlling HTML Elements

        - -

        This tutorial demonstrates how you can block areas that threaten security using the iframe element, and render the browsing content to include it seamlessly in the parent document.

        - - -

        Warm-up

        -

        Become familiar with the HTML5 iframe element API basics by learning about:

        - - -

        Accessing Sandboxed Cookies

        - -

        Learning how to control iframe element content when accessing the cookies of the parent document enhances the security features of your application:

        -
          -
        1. Create an <input> element of the checkbox type that enables the sandbox activation. In addition, create an iframe element with the sandbox property. To allow script execution in the iframe element content and cookie access, set the sandbox attribute value as allow-same-origin: -
          <input type="checkbox" id="chkSandbox" name="chkSandbox" 
          -       onclick="setSandbox()" /> Enable Sandbox
          -<div id="description" style="padding: 10px; margin: 10px;"></div>
          -
          -<iframe src="iframe_cookie_stolen.html" 
          -        sandbox="allow-scripts allow-same-origin" 
          -        id="iframe" seamless 
          -        width="100%" height="350px" 
          -        style="border: 1px solid #DCDCDC;"></iframe>
        2. -
        3. Create a test cookie: -
          <script> 
          -   SetCookie('userid', 'example@tizen.org', 7);
          -	
          -   function SetCookie(name, value, expiredays) 
          -   {
          -      var today = new Date();
          -      today.setDate(today.getDate() + expiredays);
          -      document.cookie = name + "=" + escape(value) + 
          -                        "; path=/; expires=" + today.toGMTString() + ";";
          -   }
          -</script>
        4. - -
        5. To block cookie access, remove the allow-same-origin attribute from the sandbox attribute value: -
          <script>
          -   function setSandbox() 
          -   {
          -      var checkbox = document.querySelector('#chkSandbox');
          -      var frame = document.querySelector('#iframe');
          -      var frameInfo = "", flag = "";
          -
          -      if (checkbox.checked) 
          -      {
          -         /* Access to cookies within the same domain is not allowed */                    
          -         flag = "allow-scripts';
          -         frameInfo = "<iframe src sandbox="allow-scripts"></iframe>";
          -      } 
          -      else 
          -      {
          -         /* Access to cookies within the same domain is allowed */                   
          -         flag = "allow-scripts allow-same-origin";
          -         frameInfo = "<iframe src sandbox="allow-scripts allow-same-origin"></iframe>";
          -      }
          -
          -      frame.setAttribute("sandbox", flag);
          -      frame.setAttribute("src", "iframe_cookie_stolen.html");
          -      document.querySelector("#description").textContent = frameInfo;
          -   }
          -</script>
        6. -
        7. Display the result: -
          <div id="message"></div>
        8. -
        9. If the sandboxing functionality is active, a message is displayed. If the sandboxing functionality is inactive, the imported cookie is displayed: -
          <script>
          -   window.onload = function() 
          -   {
          -      var message = document.getElementById("message");
          -      try 
          -      {
          -         message.innerHTML = "<h3>stole parent window's cookie</h3> userid: " + GetCookie("userid");
          -      } 
          -      catch (e) 
          -      {
          -         message.innerHTML = "<h3>HTML5 Sandbox blocked access to cookies.</h3>";
          -      }
          -   }
          -
          -   function GetCookie(Name) 
          -   {
          -      var search = Name + "="
          -
          -      if (document.cookie.length > 0) 
          -      {
          -
          -         offset = document.cookie.indexOf(search)
          -
          -         if (offset != -1) 
          -         {
          -            offset += search.length
          -            end = document.cookie.indexOf(";", offset)
          -
          -            if (end == -1) end = document.cookie.length
          -
          -            return unescape(document.cookie.substring(offset, end))
          -         }
          -      }
          -
          -      return "";
          -   }
          -</script>
        10. -
        -

        Figure: Sandbox cookie access (in mobile applications only)

        -

        Sandbox cookie access (in mobile applications only)

        -

        Source Code

        -

        For the complete source code related to this use case, see the following files:

        - - -

        Redirecting a Sandboxed Page

        - -

        Learning how to control iframe element content when redirecting a page enhances the security features of your application:

        -
          -
        1. Create an <input> element of the checkbox type that disables the sandbox. In addition, create an iframe element with the sandbox property: -
          <input type="checkbox" id="chkSandbox" name="chkSandbox" 
          -       onclick="setSandbox()" /> Disable Sandbox
          -<div id="description" style="padding: 10px; margin: 10px;"></div>
          -
          -<iframe src="iframe_page_redirection.html" 
          -        sandbox="allow-scripts" 
          -        id="iframe" seamless></iframe>
        2. -
        3. If the sandbox attribute is deactivated, set the allow-top-navigation attribute to the sandbox attribute value: -
          <script> 
          -   function setSandbox() 
          -   {
          -      var checkbox = document.querySelector("#chkSandbox");
          -      var frame = document.querySelector("#iframe");
          -      var frameInfo = "", flag = "";
          -
          -      if (checkbox.checked) 
          -      {
          -         flag = "allow-scripts allow-top-navigation";
          -         frameInfo = "<iframe src sandbox="allow-scripts allow-top-navigation"></iframe>";
          -      } 
          -      else 
          -      {
          -         flag = "allow-scripts";
          -         frameInfo = "<iframe src sandbox="allow-scripts"></iframe>";
          -      }
          -
          -      frame.setAttribute("sandbox", flag);
          -      frame.setAttribute("src", "iframe_page_redirection.html");
          -      document.querySelector("#description").textContent = frameInfo;
          -   }
          -</script>
        4. - - -
        5. Include the image displayed on the page: -
          <img id="img" alt="Tizen Lockup on Dark"
          -     src="http://www.tizen.org/sites/default/files/admins/tizen-branding-lockup-on-dark.png" 
          -     onclick="alert('fake advertisement!');" 
          -     width="240" height="103" />
        6. -
        7. If the page redirection is blocked, a message is displayed. If not, the user is redirected to the warning.html page: -
          <script> 
          -   try 
          -   {
          -      location = "warning.html";
          -   } 
          -   catch (e) 
          -   {
          -      alert("HTML5 Sandbox prevented top level navigation.");
          -   }
          -</script>
        8. -
        - -

        Figure: Sandbox page redirection (in mobile applications only)

        -

        Sandbox page redirection (in mobile applications only)

        - -

        Source Code

        -

        For the complete source code related to this use case, see the following files:

        - - -

        Submitting a Sandboxed Form

        -

        Learning how to control iframe element content when submitting a form enhances the security features of your application:

        -
          -
        1. Create an <input> element of the checkbox type that enables the sandbox activation. In addition, create an iframe element with the sandbox property. To allow form submission, set the sandbox attribute value as allow-forms: -
          <input type="checkbox" id="chkSandbox" name="chkSandbox" 
          -       onclick="setSandbox()" /> Enable Sandbox
          -<div id="description" style="padding: 10px; margin: 10px;"></div>
          -
          -<iframe src="iframe_form_submission.html" 
          -        sandbox="allow-scripts allow-same-origin allow-forms" 
          -        width="100%" height="200px"></iframe>
        2. -
        3. If the sandbox attribute is activated, remove the allow-forms attribute from the sandbox attribute value: -
          <script> 
          -   function setSandbox() 
          -   {
          -      var checkbox = document.querySelector('#chkSandbox');
          -      var frame = document.querySelector('#iframe');
          -      var frameInfo = "", flag = "";
          -
          -      if (checkbox.checked) 
          -      {
          -         flag = "allow-scripts allow-same-origin";
          -         frameInfo = "<iframe src sandbox="allow-scripts allow-same-origin"></iframe>";
          -      } else 
          -      {
          -         flag = "allow-scripts allow-same-origin allow-forms";
          -         frameInfo = "<iframe src sandbox='allow-scripts allow-same-origin allow-forms'></iframe>";
          -      }
          -
          -      frame.setAttribute("sandbox", flag);
          -      frame.setAttribute("src", "iframe_form_submission.html");
          -      document.querySelector("#description").textContent = frameInfo;
          -   }
          -</script>
        4. -
        5. Create a form for the login screen with <input> elements to enter an email and password, and submit them: -
          <form method="get" action="iframe_form_submission.html">
          -   <h3>Advertisement, SNS</h3>
          -	     
          -   <fieldset>
          -      <legend>Login</legend>
          -      <input type="text" id="email" name="email" placeholder="e-mail address" required>
          -      <input type="password" id="password" name="password" placeholder="password" required>
          -   </fieldset>
          -   <input type="submit" value="Login">
          -</form>
        6. - -
        7. If the sandbox attribute is deactivated, the imported login information is displayed: -
          <script>
          -   window.onload = function() 
          -   {
          -      var html;
          -
          -      if (location.href.indexOf("?") >= 0) 
          -      {
          -         html = ['<div id="message">',
          -                '<h3>Catches login qualification certifying information</h3>',
          -                (location.href.split("?")[1]).replace("&", "<br />"),
          -                '</div>'].join('');
          -
          -         document.body.innerHTML = html;
          -      }
          -   }
          -</script>
        8. -
        -

        Figure: Sandbox form submission (in mobile applications only)

        -

        Sandbox form submission (in mobile applications only)

        - - -

        Source Code

        -

        For the complete source code related to this use case, see the following files:

        - - -

        Managing Sandboxed Pop-ups

        - -

        Learning how to control the opening of the iframe element content enhances the security features of your application:

        -
          -
        1. Create an <input> element of the checkbox type that enables the sandbox activation. In addition, create an iframe element with the sandbox property. To allow pop-ups, set the sandbox attribute value as allow-popups: -
          <input type="checkbox" id="chkSandbox" name="chkSandbox" 
          -       onclick="setSandbox()" /> Enable Sandbox
          -<div id="description" style="padding:10 px; margin:10 px;"></div>
          -
          -<iframe src="iframe_popup.html" 
          -        sandbox="allow-scripts allow-same-origin allow-popups"
          -        id="iframe" seamless
          -        style="border: 1px solid #DCDCDC;"></iframe>
          -
        2. -
        3. If the sandbox attribute is activated, remove the allow-popups flag from the sandbox attribute value: -
          <script> 
          -   function setSandbox() 
          -   {
          -      var checkbox = document.querySelector('#chkSandbox');
          -      var frame = document.querySelector('#iframe');
          -      var frameInfo = "", flag ="";
          -
          -      if (checkbox.checked) 
          -      {
          -         flag = 'allow-scripts allow-same-origin';
          -         frameInfo = '<iframe src sandbox="allow-scripts allow-same-origin"></iframe>';
          -      } 
          -      else 
          -      {
          -         flag = 'allow-scripts allow-same-origin allow-popups'
          -         frameInfo = '<iframe src sandbox="allow-scripts allow-same-origin allow-popups"></iframe>';
          -      }
          -
          -      frame.setAttribute("sandbox", flag);
          -      frame.setAttribute("src", "iframe_popup.html");
          -      document.querySelector("#description").textContent = frameInfo;
          -   }
          -</script>
        4. -
        5. Create an external link in the iframe element: -
          <p>[<a href="https://www.tizen.org/about" target="_blank">Click Link!</a>]</p>
        6. -
        - -

        Figure: Sandbox pop-up (in mobile applications only)

        -

        Sandbox pop-up (in mobile applications only)

        -

        Source Code

        -

        For the complete source code related to this use case, see the following files:

        - - -

        Including Rendered Content in the Parent Document

        - -

        Learning how to include rendered content seamlessly in the parent document using the iframe element enhances the security features of your application:

        -
          -
        1. Create the needed HTML elements, including the CSS style of the parent document. Create an iframe element with the seamless attribute setting, and another iframe element without the setting: -
          <head> 
          -   <style>
          -      body, html 
          -      {
          -         margin: 0; padding: 0;
          -      }
          -      body 
          -      {
          -         font-size: 12px;
          -      }
          -      h3
          -      {
          -         color: blue;
          -      }
          -   </style> 
          -</head>
          -<body>
          -   <h2>HTML5 iframe</h2>
          -   <iframe seamless src="iframe.html"></iframe>
          -   <iframe src="iframe.html"></iframe>
          -</body>
        2. -
        3. Create the iframe element content. The iframe element with the seamless attribute set displays the content with the inherited CSS style: -
          <body> 
          -   <h3>iframe! h3 Content</h3>
          -   <ul>
          -      <li><a href="http://tizen.org">tizen.org</a></li>
          -      <li><a href="http://tizen.org" target="_self">
          -         tizen.org target="_self"</a>
          -      </li>
          -   </ul>
          -</body>
        4. -
        -

        Figure: Seamless content appending (in mobile applications only)

        -

        Seamless content appending (in mobile applications only)

        -

        Source Code

        -

        For the complete source code related to this use case, see the following files:

        - - - - - - - -
        - -Go to top - - - - - - + + + + + + + + + + + + + HTML5 iframe element: Controlling HTML Elements + + + + + + +
        +

        HTML5 iframe element: Controlling HTML Elements

        + +

        This tutorial demonstrates how you can block areas that threaten security using the iframe element, and render the browsing content to include it seamlessly in the parent document.

        + + +

        Warm-up

        +

        Become familiar with the HTML5 iframe element API basics by learning about:

        + + +

        Accessing Sandboxed Cookies

        + +

        Learning how to control iframe element content when accessing the cookies of the parent document enhances the security features of your application:

        +
          +
        1. Create an <input> element of the checkbox type that enables the sandbox activation. In addition, create an iframe element with the sandbox property. To allow script execution in the iframe element content and cookie access, set the sandbox attribute value as allow-same-origin: +
          <input type="checkbox" id="chkSandbox" name="chkSandbox" 
          +       onclick="setSandbox()" /> Enable Sandbox
          +<div id="description" style="padding: 10px; margin: 10px;"></div>
          +
          +<iframe src="iframe_cookie_stolen.html" 
          +        sandbox="allow-scripts allow-same-origin" 
          +        id="iframe" seamless 
          +        width="100%" height="350px" 
          +        style="border: 1px solid #DCDCDC;"></iframe>
        2. +
        3. Create a test cookie: +
          <script> 
          +   SetCookie('userid', 'example@tizen.org', 7);
          +	
          +   function SetCookie(name, value, expiredays) 
          +   {
          +      var today = new Date();
          +      today.setDate(today.getDate() + expiredays);
          +      document.cookie = name + "=" + escape(value) + 
          +                        "; path=/; expires=" + today.toGMTString() + ";";
          +   }
          +</script>
        4. + +
        5. To block cookie access, remove the allow-same-origin attribute from the sandbox attribute value: +
          <script>
          +   function setSandbox() 
          +   {
          +      var checkbox = document.querySelector('#chkSandbox');
          +      var frame = document.querySelector('#iframe');
          +      var frameInfo = "", flag = "";
          +
          +      if (checkbox.checked) 
          +      {
          +         /* Access to cookies within the same domain is not allowed */                    
          +         flag = "allow-scripts';
          +         frameInfo = "<iframe src sandbox="allow-scripts"></iframe>";
          +      } 
          +      else 
          +      {
          +         /* Access to cookies within the same domain is allowed */                   
          +         flag = "allow-scripts allow-same-origin";
          +         frameInfo = "<iframe src sandbox="allow-scripts allow-same-origin"></iframe>";
          +      }
          +
          +      frame.setAttribute("sandbox", flag);
          +      frame.setAttribute("src", "iframe_cookie_stolen.html");
          +      document.querySelector("#description").textContent = frameInfo;
          +   }
          +</script>
        6. +
        7. Display the result: +
          <div id="message"></div>
        8. +
        9. If the sandboxing functionality is active, a message is displayed. If the sandboxing functionality is inactive, the imported cookie is displayed: +
          <script>
          +   window.onload = function() 
          +   {
          +      var message = document.getElementById("message");
          +      try 
          +      {
          +         message.innerHTML = "<h3>stole parent window's cookie</h3> userid: " + GetCookie("userid");
          +      } 
          +      catch (e) 
          +      {
          +         message.innerHTML = "<h3>HTML5 Sandbox blocked access to cookies.</h3>";
          +      }
          +   }
          +
          +   function GetCookie(Name) 
          +   {
          +      var search = Name + "="
          +
          +      if (document.cookie.length > 0) 
          +      {
          +
          +         offset = document.cookie.indexOf(search)
          +
          +         if (offset != -1) 
          +         {
          +            offset += search.length
          +            end = document.cookie.indexOf(";", offset)
          +
          +            if (end == -1) end = document.cookie.length
          +
          +            return unescape(document.cookie.substring(offset, end))
          +         }
          +      }
          +
          +      return "";
          +   }
          +</script>
        10. +
        +

        Figure: Sandbox cookie access (in mobile applications only)

        +

        Sandbox cookie access (in mobile applications only)

        +

        Source Code

        +

        For the complete source code related to this use case, see the following files:

        + + +

        Redirecting a Sandboxed Page

        + +

        Learning how to control iframe element content when redirecting a page enhances the security features of your application:

        +
          +
        1. Create an <input> element of the checkbox type that disables the sandbox. In addition, create an iframe element with the sandbox property: +
          <input type="checkbox" id="chkSandbox" name="chkSandbox" 
          +       onclick="setSandbox()" /> Disable Sandbox
          +<div id="description" style="padding: 10px; margin: 10px;"></div>
          +
          +<iframe src="iframe_page_redirection.html" 
          +        sandbox="allow-scripts" 
          +        id="iframe" seamless></iframe>
        2. +
        3. If the sandbox attribute is deactivated, set the allow-top-navigation attribute to the sandbox attribute value: +
          <script> 
          +   function setSandbox() 
          +   {
          +      var checkbox = document.querySelector("#chkSandbox");
          +      var frame = document.querySelector("#iframe");
          +      var frameInfo = "", flag = "";
          +
          +      if (checkbox.checked) 
          +      {
          +         flag = "allow-scripts allow-top-navigation";
          +         frameInfo = "<iframe src sandbox="allow-scripts allow-top-navigation"></iframe>";
          +      } 
          +      else 
          +      {
          +         flag = "allow-scripts";
          +         frameInfo = "<iframe src sandbox="allow-scripts"></iframe>";
          +      }
          +
          +      frame.setAttribute("sandbox", flag);
          +      frame.setAttribute("src", "iframe_page_redirection.html");
          +      document.querySelector("#description").textContent = frameInfo;
          +   }
          +</script>
        4. + + +
        5. Include the image displayed on the page: +
          <img id="img" alt="Tizen Lockup on Dark"
          +     src="http://www.tizen.org/sites/default/files/admins/tizen-branding-lockup-on-dark.png" 
          +     onclick="alert('fake advertisement!');" 
          +     width="240" height="103" />
        6. +
        7. If the page redirection is blocked, a message is displayed. If not, the user is redirected to the warning.html page: +
          <script> 
          +   try 
          +   {
          +      location = "warning.html";
          +   } 
          +   catch (e) 
          +   {
          +      alert("HTML5 Sandbox prevented top level navigation.");
          +   }
          +</script>
        8. +
        + +

        Figure: Sandbox page redirection (in mobile applications only)

        +

        Sandbox page redirection (in mobile applications only)

        + +

        Source Code

        +

        For the complete source code related to this use case, see the following files:

        + + +

        Submitting a Sandboxed Form

        +

        Learning how to control iframe element content when submitting a form enhances the security features of your application:

        +
          +
        1. Create an <input> element of the checkbox type that enables the sandbox activation. In addition, create an iframe element with the sandbox property. To allow form submission, set the sandbox attribute value as allow-forms: +
          <input type="checkbox" id="chkSandbox" name="chkSandbox" 
          +       onclick="setSandbox()" /> Enable Sandbox
          +<div id="description" style="padding: 10px; margin: 10px;"></div>
          +
          +<iframe src="iframe_form_submission.html" 
          +        sandbox="allow-scripts allow-same-origin allow-forms" 
          +        width="100%" height="200px"></iframe>
        2. +
        3. If the sandbox attribute is activated, remove the allow-forms attribute from the sandbox attribute value: +
          <script> 
          +   function setSandbox() 
          +   {
          +      var checkbox = document.querySelector('#chkSandbox');
          +      var frame = document.querySelector('#iframe');
          +      var frameInfo = "", flag = "";
          +
          +      if (checkbox.checked) 
          +      {
          +         flag = "allow-scripts allow-same-origin";
          +         frameInfo = "<iframe src sandbox="allow-scripts allow-same-origin"></iframe>";
          +      } else 
          +      {
          +         flag = "allow-scripts allow-same-origin allow-forms";
          +         frameInfo = "<iframe src sandbox='allow-scripts allow-same-origin allow-forms'></iframe>";
          +      }
          +
          +      frame.setAttribute("sandbox", flag);
          +      frame.setAttribute("src", "iframe_form_submission.html");
          +      document.querySelector("#description").textContent = frameInfo;
          +   }
          +</script>
        4. +
        5. Create a form for the login screen with <input> elements to enter an email and password, and submit them: +
          <form method="get" action="iframe_form_submission.html">
          +   <h3>Advertisement, SNS</h3>
          +	     
          +   <fieldset>
          +      <legend>Login</legend>
          +      <input type="text" id="email" name="email" placeholder="e-mail address" required>
          +      <input type="password" id="password" name="password" placeholder="password" required>
          +   </fieldset>
          +   <input type="submit" value="Login">
          +</form>
        6. + +
        7. If the sandbox attribute is deactivated, the imported login information is displayed: +
          <script>
          +   window.onload = function() 
          +   {
          +      var html;
          +
          +      if (location.href.indexOf("?") >= 0) 
          +      {
          +         html = ['<div id="message">',
          +                '<h3>Catches login qualification certifying information</h3>',
          +                (location.href.split("?")[1]).replace("&", "<br />"),
          +                '</div>'].join('');
          +
          +         document.body.innerHTML = html;
          +      }
          +   }
          +</script>
        8. +
        +

        Figure: Sandbox form submission (in mobile applications only)

        +

        Sandbox form submission (in mobile applications only)

        + + +

        Source Code

        +

        For the complete source code related to this use case, see the following files:

        + + +

        Managing Sandboxed Pop-ups

        + +

        Learning how to control the opening of the iframe element content enhances the security features of your application:

        +
          +
        1. Create an <input> element of the checkbox type that enables the sandbox activation. In addition, create an iframe element with the sandbox property. To allow pop-ups, set the sandbox attribute value as allow-popups: +
          <input type="checkbox" id="chkSandbox" name="chkSandbox" 
          +       onclick="setSandbox()" /> Enable Sandbox
          +<div id="description" style="padding:10 px; margin:10 px;"></div>
          +
          +<iframe src="iframe_popup.html" 
          +        sandbox="allow-scripts allow-same-origin allow-popups"
          +        id="iframe" seamless
          +        style="border: 1px solid #DCDCDC;"></iframe>
          +
        2. +
        3. If the sandbox attribute is activated, remove the allow-popups flag from the sandbox attribute value: +
          <script> 
          +   function setSandbox() 
          +   {
          +      var checkbox = document.querySelector('#chkSandbox');
          +      var frame = document.querySelector('#iframe');
          +      var frameInfo = "", flag ="";
          +
          +      if (checkbox.checked) 
          +      {
          +         flag = 'allow-scripts allow-same-origin';
          +         frameInfo = '<iframe src sandbox="allow-scripts allow-same-origin"></iframe>';
          +      } 
          +      else 
          +      {
          +         flag = 'allow-scripts allow-same-origin allow-popups'
          +         frameInfo = '<iframe src sandbox="allow-scripts allow-same-origin allow-popups"></iframe>';
          +      }
          +
          +      frame.setAttribute("sandbox", flag);
          +      frame.setAttribute("src", "iframe_popup.html");
          +      document.querySelector("#description").textContent = frameInfo;
          +   }
          +</script>
        4. +
        5. Create an external link in the iframe element: +
          <p>[<a href="https://www.tizen.org/about" target="_blank">Click Link!</a>]</p>
        6. +
        + +

        Figure: Sandbox pop-up (in mobile applications only)

        +

        Sandbox pop-up (in mobile applications only)

        +

        Source Code

        +

        For the complete source code related to this use case, see the following files:

        + + +

        Including Rendered Content in the Parent Document

        + +

        Learning how to include rendered content seamlessly in the parent document using the iframe element enhances the security features of your application:

        +
          +
        1. Create the needed HTML elements, including the CSS style of the parent document. Create an iframe element with the seamless attribute setting, and another iframe element without the setting: +
          <head> 
          +   <style>
          +      body, html 
          +      {
          +         margin: 0; padding: 0;
          +      }
          +      body 
          +      {
          +         font-size: 12px;
          +      }
          +      h3
          +      {
          +         color: blue;
          +      }
          +   </style> 
          +</head>
          +<body>
          +   <h2>HTML5 iframe</h2>
          +   <iframe seamless src="iframe.html"></iframe>
          +   <iframe src="iframe.html"></iframe>
          +</body>
        2. +
        3. Create the iframe element content. The iframe element with the seamless attribute set displays the content with the inherited CSS style: +
          <body> 
          +   <h3>iframe! h3 Content</h3>
          +   <ul>
          +      <li><a href="http://tizen.org">tizen.org</a></li>
          +      <li><a href="http://tizen.org" target="_self">
          +         tizen.org target="_self"</a>
          +      </li>
          +   </ul>
          +</body>
        4. +
        +

        Figure: Seamless content appending (in mobile applications only)

        +

        Seamless content appending (in mobile applications only)

        +

        Source Code

        +

        For the complete source code related to this use case, see the following files:

        + + + + + + + +
        + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.tutorials/html/web/w3c/security/security_tutorials_w.htm b/org.tizen.tutorials/html/web/w3c/security/security_tutorials_w.htm index 4a0f6fa..86e7811 100644 --- a/org.tizen.tutorials/html/web/w3c/security/security_tutorials_w.htm +++ b/org.tizen.tutorials/html/web/w3c/security/security_tutorials_w.htm @@ -1,66 +1,66 @@ - - - - - - - - - - - - - Security: Enhancing Application and User Security - - - - - - -
        -

        Security: Enhancing Application and User Security

        - -

        The security tutorials demonstrate how to use the following features in creating Tizen Web applications:

        - - - - - - - -
        - -Go to top - - - - - - + + + + + + + + + + + + + Security: Enhancing Application and User Security + + + + + + +
        +

        Security: Enhancing Application and User Security

        + +

        The security tutorials demonstrate how to use the following features in creating Tizen Web applications:

        + + + + + + + +
        + +Go to top + + + + + + \ No newline at end of file diff --git a/org.tizen.tutorials/html/web/w3c/storage/storage_tutorials_w.htm b/org.tizen.tutorials/html/web/w3c/storage/storage_tutorials_w.htm index 339f63f..cb579f1 100644 --- a/org.tizen.tutorials/html/web/w3c/storage/storage_tutorials_w.htm +++ b/org.tizen.tutorials/html/web/w3c/storage/storage_tutorials_w.htm @@ -40,7 +40,7 @@
      • Web Storage: Saving Structured Data on the Client Side

        Demonstrates how you can use the Web storage.

      -

      The following tutorials apply in mobile applications only:

      +

      The following tutorials apply in mobile applications only:

      -

      The following tutorials apply in mobile applications only:

      +

      The following tutorials apply in mobile applications only:

      -

      The following tutorials apply in wearable applications only:

      +

      The following tutorials apply in wearable applications only:

      diff --git a/org.tizen.tutorials/html/web/w3c/tutorials_w3c_w.htm b/org.tizen.tutorials/html/web/w3c/tutorials_w3c_w.htm index 08204d2..d89903d 100644 --- a/org.tizen.tutorials/html/web/w3c/tutorials_w3c_w.htm +++ b/org.tizen.tutorials/html/web/w3c/tutorials_w3c_w.htm @@ -37,8 +37,6 @@

      Select the feature you are interested in and see how you can implement its various functionalities into your application:

      - +

      For more information about implementing the UI for your application using the W3C features, see W3C.

      diff --git a/org.tizen.tutorials/html/web/w3c/ui/clipboard_tutorial_w.htm b/org.tizen.tutorials/html/web/w3c/ui/clipboard_tutorial_w.htm deleted file mode 100644 index 0eb2862..0000000 --- a/org.tizen.tutorials/html/web/w3c/ui/clipboard_tutorial_w.htm +++ /dev/null @@ -1,303 +0,0 @@ - - - - - - - - - - - - - - Clipboard API and events: Transferring Content Between Applications - - - - - - -
      -

      Clipboard API and events: Transferring Content Between Applications

      - -

      This tutorial demonstrates how you can use clipboard operations in Tizen.

      - - - - - - - - - - -
      Note
      This feature is supported in mobile applications only.
      - - -

      Warm-up

      -

      Become familiar with the Clipboard API and events basics by learning about:

      - - -

      Follow-up

      -

      Once we have learned the basics of using clipboard events, we can now move on to more advanced tasks, including:

      - - -

      Copying Content

      - -

      To enhance the user experience of your application with clipboard operations, you must learn to use the copy event:

      -
        -
      1. Add an event listener to detect the copy event: -
        -<script>
        -   document.addEventListener("copy", function(e)
        -   {
        -      copyHandler(e);
        -   }, false);
        -
      2. -
      3. When you start copying, the copy event is fired and the copyHandler() method is called.

        -

        Stop the system clipboard basic operation and set the range you want to copy:

        -
           function copyHandler(e) 
        -   {
        -      e.preventDefault();
        -
        -      var range = window.getSelection();
        - - - - - - - - - -
        Note
        If the current selection is not influenced and there is no selected range, the clipboard imports the setData() method. The copied content cannot be edited apart from adding a DataTransferItemList item.
        -
      4. -
      5. Store the data of the selected range: -
              e.clipboardData.setData("text/plain", range);
        -   };
        -</script>
        -
        -
      6. -
      -

      Source Code

      -

      For the complete source code related to this use case, see the following file:

      - - -

      Cutting Content

      - -

      To enhance the user experience of your application with clipboard operations, you must learn to use the cut event:

      -
        -
      1. Add an event listener to detect the cut event: -
        -<script>
        -   document.addEventListener("cut", function(e) 
        -   {
        -      cutHandler(e);
        -   }, false);
        - -
      2. -
      3. When you start cutting, the cut event is fired and the cutHandler() method is called.

        -

        Stop the system clipboard basic operation and set the range you want to cut:

        -
           function cutHandler(e) 
        -   {
        -      e.preventDefault();
        -
        -      var range = window.getSelection();
        - -
      4. -
      5. Store the data of the selected range: -
              e.clipboardData.setData("text/plain", range);
        -   };   
        -</script>
        -
        - - - - - - - - - -
        Note
        Before the setData() method is imported, the basic motion of the system event must be cancelled using the preventDefault() method. Otherwise, the data to be allocated to the clipboard is overwritten by the system clipboard.
        -
      6. -
      - -

      Source Code

      -

      For the complete source code related to this use case, see the following file:

      - - -

      Pasting Content

      - -

      To enhance the user experience of your application with clipboard operations, you must learn to use the paste event:

      -
        -
      1. Add an event listener to detect the paste event: -
        -<script>
        -   document.addEventListener("paste", function(e)
        -   {
        -      pasteHandler(e);
        -   }, false);
        -
      2. -
      3. When you start pasting, the paste event is fired and the pasteHandler() method is called.

        -

        Stop the system clipboard basic operation:

        -
           function pasteHandler(e) 
        -   {
        -      e.preventDefault();
        -
      4. -
      5. Paste the clipboard data to the target using the getData() method: -
        -      pasteTarget.innerHTML = e.clipboardData.getData("text/plain");
        -   };              
        -</script>
        -
        -
      6. -
      - -

      Source Code

      -

      For the complete source code related to this use case, see the following file:

      - - -

      Copying and Pasting Content into an Editable Element

      - -

      To enhance the user experience of your application with clipboard operations, you must learn to copy content and paste it in an editable HTML element:

      - -
        -
      1. Define the editable element into which copied data is to be pasted:

        -
        -<head>
        -   <style>
        -      .log {border: 1px solid #d9d9d9; margin: 10px; padding: 5px;}
        -      .target {border: 1px solid #36c; margin: 10px; padding: 5px;}
        -   </style>
        -</head>
        -<body>
        -   <h1>Clipboard API</h1>
        -   <div style="width: 300px; height: 100px; border: 1px solid #d9d9d9" contenteditable>
        -      Edit Section
        -   </div>
        -   <div  class="target">
        -      <h4>Target Element</h4>
        -      <p id="target contenteditable">Paste content</p>
        -   </div>
        -   <div id="ev-log" class="log">Event log</div>
        -   <div contenteditable>
        -      This section is informative
        -      This specification defines the common clipboard operations of cutting, 
        -      copying and pasting, in such a way that they are exposed to Web Applications 
        -      and can be adapted to provide advanced functionalities. 
        -      Its goal is to provide for compatibility where possible with existing implementations.
        -   </div>
        -<body>
        -
        -
      2. - -
      3. Add event listeners to detect the copy and paste events:

        -
        -<script>
        -   var pasteTarget = document.getElementById("target");
        -   var evLogBox = document.getElementById("ev-log");    
        -
        -   document.addEventListener("copy", function(e)
        -   {
        -      copyHandler(e);
        -   }, false);
        -
        -   document.addEventListener("paste", function(e)
        -   {
        -      pasteHandler(e);
        -   }, false);
        -
        -
      4. - -
      5. When the copy event occurs, stop the system clipboard basic operation and set the range you want to copy: -
        -   function copyHandler(e) 
        -   {
        -      e.preventDefault();
        -
        -      var range = window.getSelection();
        -
      6. -
      7. Store the data of the selected range: -
              e.clipboardData.setData("text/plain", range);
        -      evLogBox.innerHTML = "Event log : copy";
        -   };
        -
      8. -
      9. When the paste event occurs, stop the system clipboard basic operation and paste the clipboard data to the target using the getData() method: -
           function pasteHandler(e) 
        -   {
        -      e.preventDefault();
        -
        -      pasteTarget.innerHTML = e.clipboardData.getData("text/plain");
        -      evLogBox.innerHTML = "Event log : paste";
        -   };  
        -</script>
        -
        -
      10. -
      - -

      Figure: Copying and pasting

      -

      Copying and pasting

      - -

      Source Code

      -

      For the complete source code related to this use case, see the following file:

      - - - - - -
      - -Go to top - - - - - - - - diff --git a/org.tizen.tutorials/html/web/w3c/ui/drag_drop_tutorial_w.htm b/org.tizen.tutorials/html/web/w3c/ui/drag_drop_tutorial_w.htm deleted file mode 100644 index 061aebe..0000000 --- a/org.tizen.tutorials/html/web/w3c/ui/drag_drop_tutorial_w.htm +++ /dev/null @@ -1,311 +0,0 @@ - - - - - - - - - - - - - - HTML5 Drag and drop: Handling Drag and Drop Events - - - - - - -
      -

      HTML5 Drag and drop: Handling Drag and Drop Events

      - -

      This tutorial demonstrates how you can use drag and drop in Tizen.

      - - - - - - - - - - -
      Note
      This feature is supported in mobile applications only.
      - - -

      Warm-up

      -

      Become familiar with the HTML5 Drag and drop API basics by learning about:

      - - -

      Handling Drag and Drop Events

      - -

      Learning how to handle drag and drop events is a basic user interaction skill:

      - - -
        -
      1. Define the draggable elements by adding the draggable="true" attribute to them:

        -
        -<h1>Drag and drop tutorial</h1>
        -<div class="example_body">
        -   <div id="drag-list">
        -      <div class="drag-row" draggable="true">1</div>
        -      <div class="drag-row" draggable="true">2</div>
        -   </div>
        -   <div>Drag state: <span id="log"></span></div>
        -</div>
        -
        -
      2. - -
      3. Add event listeners for the various drag and drop events: -
        -<script>
        -   var cols = document.querySelectorAll('#drag-list_.drag-row');
        -   var colsLength = cols.length;
        -
        -   for (var i = 0; i < colsLength; i++) 
        -   {
        -      cols[i].addEventListener('dragstart', dragStart, false);
        -      cols[i].addEventListener('drag', dragIng, false);
        -      cols[i].addEventListener('dragenter', dragEnter, false);
        -      cols[i].addEventListener('dragover', dragOver, false);
        -      cols[i].addEventListener('dragleave', dragLeave, false);
        -      cols[i].addEventListener('drop', dragDrop, false);
        -      cols[i].addEventListener('dragend', dragEnd, false);
        -   };
        -</script>
        -
        -
      4. - -
      5. Define event handlers for the events. In this case, each event handler displays a text on the screen. -
        -function dragStart(e) 
        -{
        -   log.innerHTML = "dragStart"
        -};
        -
        -function dragIng(e) 
        -{
        -   log.innerHTML = "drag"
        -};
        -
        -function dragOver(e) 
        -{
        -   e.preventDefault();
        -   log.innerHTML = "dragOver"
        -};
        -
        -function dragEnter(e) 
        -{
        -   log.innerHTML = "dragEnter"
        -};	
        -
        -function dragLeave(e) 
        -{
        -   log.innerHTML = "dragLeave"
        -};
        -
        -function dragDrop(e) 
        -{
        -   e.stopPropagation();
        -   log.innerHTML = "dragDrop"	
        -};
        -	
        -function dragEnd(e) 
        -{
        -   log.innerHTML = "dragEnd"
        -};
        -
        -
      6. -
      - -

      Source Code

      -

      For the complete source code related to this use case, see the following file:

      - - -

      Transferring Data over Drag and Drop

      - -

      Learning how to transfer data in a simple drag and drop puzzle is a basic user interaction skill:

      - -
        -
      1. Define the draggable elements by adding the draggable="true" attribute to them. -

        In this example, the Tizen logo image has been divided and allocated randomly. Each imager part is defined as draggable, so that the user can rearrange the image parts in the correct order.

        -
        -<h1>Drag and drop tutorial</h1>
        -<div class="example_body">
        -   <div>Drag state: <span id="log"></span></div>
        -   <div class="holder">
        -      <div>
        -         <img src="images/logo.png">
        -         <p class="txt">Complete the puzzle to see a picture</p>
        -      </div>
        -      <ul id="puzzle">
        -         <li class="puzzle-piece" draggable="true">
        -            <img src="images/puzz_06.png">
        -         </li>
        -         <li class="puzzle-piece" draggable="true">
        -            <img src="images/puzz_02.png">
        -         </li>
        -         <li class="puzzle-piece" draggable="true">
        -            <img src="images/puzz_04.png">
        -         </li>
        -         <li class="puzzle-piece" draggable="true">
        -            <img src="images/puzz_05.png">
        -         </li>
        -         <li class="puzzle-piece" draggable="true">
        -            <img src="images/puzz_01.png">
        -         </li>
        -         <li class="puzzle-piece" draggable="true">
        -            <img src="images/puzz_03.png">
        -         </li>
        -      </ul>
        -   </div>
        -</div>
        -
        -
      2. - -
      3. Add event listeners for the dragover, dragleave, dragstart, and drop events: -
        -<script>
        -   var cols = document.querySelectorAll('#puzzle_.puzzle-piece');
        -   var colsLength = cols.length;
        -   for (var i = 0; i < colsLength; i++) 
        -   {
        -      cols[i].addEventListener('dragstart', dragStartHandler, false);
        -      cols[i].addEventListener('dragover', dragOverHandler, false);
        -      cols[i].addEventListener('dragleave', dragLeaveHandler, false);
        -      cols[i].addEventListener('drop', dragDropHandler, false);
        -   };
        -</script>
        -
        -
      4. - -
      5. Transfer data (in this case, image parts): -
          -
        1. Declare the dragElem variable, which is an empty object for the data exchange: -
          -var dragElem = null;
          -
          -
        2. - -
        3. Use the DataTransfer interface in the dragStartHandler() and dragDropHandler() event handlers to exchange image parts: -
          -function dragStartHandler(e) 
          -{
          -   /* Set data */
          -   dragElem = this;
          -   e.dataTransfer.effectAllowed = 'move';
          -   e.dataTransfer.setData('text/html', this.innerHTML);
          -   this.classList.add('over');
          -   for (var i = 0; i < colsLength; i++)
          -   {
          -      cols[i].classList.add('start');
          -   };
          -};
          -function dragDropHandler(e) 
          -{
          -   /* Get data */
          -   dragElem.innerHTML = this.innerHTML;
          -   this.innerHTML = e.dataTransfer.getData('text/html');
          -   for (var i = 0; i < colsLength; i++)
          -   {
          -      cols[i].className = "puzzle-piece";
          -   };
          -   /* Check key */
          -   puzzleCheck();
          -};
          -
          -
        4. - -
        5. Check the completion of the puzzle by making a user key using a simple array, and comparing the user key against the puzzle key (correct answer): -
          -var puzzleKey =  ["01", "02", "03", "04", "05", "06"];
          -var puzzleArray = [];
          -
          -function puzzleCheck() 
          -{
          -   /* Initialize the user key */
          -   puzzleArray = [];
          -   /* Insert the keys in the array */
          -   for (var i = 0; i < colsLength; i++) 
          -   {
          -      puzzleArray.push(cols[i].children[0].getAttribute('src').substring(12, 14));
          -   };
          -   originKey = puzzleKey.join();
          -   userKey = puzzleArray.join();
          -
          -   if (originKey === userKey)
          -   {
          -      alert("Success !");
          -   };
          -};
          -
          -
        6. -
        -
      6. -
      -

      Figure: Drag and drop puzzle

      -

      Drag and drop puzzle

      -

      Source Code

      -

      For the complete source code related to this use case, see the following files:

      - - - - - -
      - -Go to top - - - - - - - - diff --git a/org.tizen.tutorials/html/web/w3c/ui/ui_tutorials_w.htm b/org.tizen.tutorials/html/web/w3c/ui/ui_tutorials_w.htm deleted file mode 100644 index d3a320f..0000000 --- a/org.tizen.tutorials/html/web/w3c/ui/ui_tutorials_w.htm +++ /dev/null @@ -1,78 +0,0 @@ - - - - - - - - - - - - - - UI: Handling User Events on the Screen - - - - -
      -
      -

      Mobile Web

      -
      -
      -

      Related Info

      - -
      -
      - -
      -

      UI: Handling User Events on the Screen

      - - - - - - - - - - -
      Note
      The UI API domain is supported in mobile applications only.
      - -

      The UI tutorials demonstrate how to manage screen elements and events related to them in creating Tizen Web applications:

      - - - - - - -
      - -Go to top - - - - - - - - diff --git a/org.tizen.tutorials/html/web/w3c/useful/html_priority_tutorial_w.htm b/org.tizen.tutorials/html/web/w3c/useful/html_priority_tutorial_w.htm deleted file mode 100644 index 2584860..0000000 --- a/org.tizen.tutorials/html/web/w3c/useful/html_priority_tutorial_w.htm +++ /dev/null @@ -1,140 +0,0 @@ - - - - - - - - - - - - - - HTML Priorities: Understanding HTML Behavior - - - - -
      -
      -

      Mobile Web Wearable Web

      -
      -
      -

      Content

      - -

      Related Info

      - -
      -
      - -
      -

      HTML Priorities: Understanding HTML Behavior

      - -

      The HTML behavior tutorial demonstrates how you can use JavaScript methods within HTML code.

      - -

      Warm-up

      -

      Become familiar with HTML priorities by learning about:

      - - -

      Using JavaScript Code within HTML

      - -

      To provide users with JavaScript-based features, you must learn to use JavaScript code within an HTML document:

      - -
        -
      • To use JavaScript code in the <head> element, place the relevant JavaScript content in a <script> tag: -
        -<head>
        -   <script src="js/jquery_1.9.0_min.js"></script>
        -   <script>       
        -      window.onload = function() 
        -      {
        -         testLog('head onload');
        -      };
        -
        -      $(document).ready(function() 
        -      {
        -         testLog('head ready');
        -      });
        -   </script>
        -</head>
        - -

        The JavaScript code within the <head> element is sent to Interpreter. As there are no methods to be handled immediately, its execution is suspended.

        -
      • -
      • To use JavaScript code in the <body> element, place the relevant JavaScript content in a <script> tag: -
        -<body>
        -   <script src="js/jquery_1.9.0_min.js"></script>
        -   <script>
        -      function testLog(txt) 
        -      {
        -         var logText = document.querySelector('.log');
        -         logText.innerHTML += '<li>JavaScript in HTML ' + txt + '</li>';
        -      };
        -    
        -      window.onload = function() 
        -      {
        -         testLog('body onload');
        -      };
        -
        -      $(document).ready(function() 
        -      {
        -         testLog('body ready');
        -      });
        -
        -      testLog('body');
        -
        -      (function() 
        -      {
        -         testLog('body anonymous function');
        -      }();
        -   </script>
        -</body>
        -
        -

        The JavaScript code within the <body> element is sent to Interpreter. The anonymous method is immediately executed, and the HTML DOM structure is set up. The methods in the $(document).ready method and in the onload event are executed in the stored order.

        -
      - - - - - - - - - - - -
      Note
      jQuery has to be called from both the <head> and <body> elements. The logText variable has to be called from the <body> element. The method connected to the onload event in the <head> element is not executed.
      - - - - -
      - -Go to top - - - - - - - diff --git a/org.tizen.tutorials/html/web/w3c/useful/useful_tutorials_w.htm b/org.tizen.tutorials/html/web/w3c/useful/useful_tutorials_w.htm deleted file mode 100644 index 65da720..0000000 --- a/org.tizen.tutorials/html/web/w3c/useful/useful_tutorials_w.htm +++ /dev/null @@ -1,63 +0,0 @@ - - - - - - - - - - - - - - Useful Practices for W3C/HTML5 Features: Managing Information Related to Various APIs - - - - -
      -
      -

      Mobile Web Wearable Web

      -
      -
      -

      Related Info

      - -
      -
      - -
      -

      Useful Practices for W3C/HTML5 Features: Managing Information Related to Various APIs

      - -

      The useful practices for W3C/HTML5 features tutorials demonstrate how to manage W3C information related to multiple APIs:

      - - - - - - -
      - -Go to top - - - - - - - diff --git a/org.tizen.tutorials/index.xml b/org.tizen.tutorials/index.xml index 8e4512e..585f239 100644 --- a/org.tizen.tutorials/index.xml +++ b/org.tizen.tutorials/index.xml @@ -16,7 +16,6 @@ - @@ -80,23 +79,6 @@ - - - - - - - - - - - - - - - - - @@ -151,13 +133,6 @@ - - - - - - - @@ -186,7 +161,7 @@ - + @@ -275,41 +250,6 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/org.tizen.tutorials/plugin.xml b/org.tizen.tutorials/plugin.xml index 90140e5..4c22a91 100644 --- a/org.tizen.tutorials/plugin.xml +++ b/org.tizen.tutorials/plugin.xml @@ -1,8 +1,8 @@ - - - - - - - - + + + + + + + + diff --git a/org.tizen.ui.guides/.project b/org.tizen.ui.guides/.project new file mode 100755 index 0000000..2c22bce --- /dev/null +++ b/org.tizen.ui.guides/.project @@ -0,0 +1,22 @@ + + + org.tizen.ui.guides_2.4.0 + + + + + + org.eclipse.pde.ManifestBuilder + + + + + org.eclipse.pde.SchemaBuilder + + + + + + org.eclipse.pde.PluginNature + + diff --git a/org.tizen.ui.guides/META-INF/MANIFEST.MF b/org.tizen.ui.guides/META-INF/MANIFEST.MF new file mode 100755 index 0000000..3ef5790 --- /dev/null +++ b/org.tizen.ui.guides/META-INF/MANIFEST.MF @@ -0,0 +1,7 @@ +Manifest-Version: 1.0 +Bundle-ManifestVersion: 1 +Bundle-Name: Tizen UI Guides +Bundle-SymbolicName: org.tizen.ui.guides;singleton=true +Bundle-Version: 2.4.0 +Bundle-Vendor: The Linux Foundation + diff --git a/org.tizen.ui.guides/about.html b/org.tizen.ui.guides/about.html new file mode 100755 index 0000000..814330e --- /dev/null +++ b/org.tizen.ui.guides/about.html @@ -0,0 +1,18 @@ + + + + + + + + About This Content + + + +

      About This Content

      +

      Tizen 2.4.0

      + +

      License

      +

      Except as noted, this content - excluding the Code Examples - is licensed under Creative Commons Attribution 3.0 and all of the Code Examples contained herein are licensed under BSD-3-Clause.
      For details, see the Content License.

      + + \ No newline at end of file diff --git a/org.tizen.ui.guides/build.properties b/org.tizen.ui.guides/build.properties new file mode 100755 index 0000000..264c2a1 --- /dev/null +++ b/org.tizen.ui.guides/build.properties @@ -0,0 +1,8 @@ +bin.includes = plugin.xml,\ + META-INF/,\ + html/,\ + build.properties,\ + .project,\ + about.html,\ + index.xml + diff --git a/org.tizen.ui.guides/html/cover_page.htm b/org.tizen.ui.guides/html/cover_page.htm new file mode 100755 index 0000000..1d59870 --- /dev/null +++ b/org.tizen.ui.guides/html/cover_page.htm @@ -0,0 +1,46 @@ + + + + + + + + + + + + + + Tizen UI Guides + + + + +

      Tizen
      +UI Guides

      + +

      Click the application type you want:

      +

      Web Application Native Application

      + + + + + + + + + + + + diff --git a/org.tizen.ui.guides/html/css/snippet.css b/org.tizen.ui.guides/html/css/snippet.css new file mode 100755 index 0000000..2be1b1f --- /dev/null +++ b/org.tizen.ui.guides/html/css/snippet.css @@ -0,0 +1,52 @@ +/* Pretty printing styles. Used with prettify.js. */ + +/* SPAN elements with the classes below are added by prettyprint. */ +.pln { color: #000 } /* plain text */ + +@media screen { + .str { color: #793AFF } /* string content */ + .kwd { color: #7F0055 } /* a keyword */ + .com { color: green} /* a comment */ + .typ { color: #1C1C1C } /* a type name */ + .lit { color: black } /* a literal value */ + /* punctuation, lisp open bracket, lisp close bracket */ + .pun, .opn, .clo { color: #1C1C1C} + .tag { color: #008 } /* a markup tag name */ + .atn { color: #606 } /* a markup attribute name */ + .atv { color: #080 } /* a markup attribute value */ + .dec, .var { color: #606 } /* a declaration; a variable name */ + .fun { color: red } /* a function name */ +} + +/* Use higher contrast and text-weight for printable form. */ +@media print, projection { + .str { color: #060 } + .kwd { color: #006; font-weight: bold } + .com { color: #600; font-style: italic } + .typ { color: #404; font-weight: bold } + .lit { color: #044 } + .pun, .opn, .clo { color: #440 } + .tag { color: #006; font-weight: bold } + .atn { color: #404 } + .atv { color: #060 } +} + +/* Put a border around prettyprinted code snippets. */ +pre.prettyprint { overflow: auto; padding: 2px; border: 1px solid #888 } + +/* Specify class=linenums on a pre to get line numbering */ +ol.linenums { margin-top: 0; margin-bottom: 0 } /* IE indents via margin-left */ +li.L0, +li.L1, +li.L2, +li.L3, +li.L5, +li.L6, +li.L7, +li.L8 { list-style-type: none } +/* Alternate shading for lines */ +li.L1, +li.L3, +li.L5, +li.L7, +li.L9 { background: #eee } diff --git a/org.tizen.ui.guides/html/css/styles.css b/org.tizen.ui.guides/html/css/styles.css new file mode 100755 index 0000000..ad7ebcb --- /dev/null +++ b/org.tizen.ui.guides/html/css/styles.css @@ -0,0 +1,756 @@ +@charset "utf-8"; + +body { + background: white; + color: #1C1C1C; + margin-right: 20px; + margin-left: 20px; + font-size: 9pt; + font-weight: normal; + font-family: Arial, Helvetica, sans-serif; +} + +h1, h2, h3, h4, h5, h6, p, table, td, caption, th, ol, dl, dd, dt, footer { + font-family: Arial, Verdana, Helvetica, sans-serif + } + +/* Set default font to 9 pt */ +table, div, p, dl, td, caption, th, ul, ol, li, dd, dt, pre, code { + font-size: 9pt; +} + +pre, code { + font-family: "Courier New", Courier, monospace; + border: 1px solid #719cc7; + margin: 6px 1.5px; + padding: 1px 1px 1px 1px; + font-weight: normal; + font-style: normal; +} + +h1 {font-size: 24pt; color: #0E437D;} +h2 {font-size: 18pt; color: #0E437D;} +h3 {font-size: 14pt; color: #1C1C1C;} +h4 {font-size: 12pt; color: #1C1C1C;} +h5 {font-size: 10pt; color: #1C1C1C;} + +h1, h2, h3, h4, h5 { + font-weight: bold; + font-style: normal; + line-height: normal; + margin-top: 16pt; +} + +caption, p.caption { + font-size: 9pt; + color: #1C1C1C; + font-weight: bold; + text-align: left; + margin-top: 20px; + margin-bottom: 0px; +} + +ol { + margin-bottom: 20px; +} + +ul ul , ol ul, ul ol, ol ol{ + margin-top: 10px; +} + +ul li, ol li { + margin-bottom: 10px; +} + +ol.tutorstep li { + border-top: 2px solid #719cc7; + list-style-position: inside; + font-weight: bold; + margin-top: 30px; + margin-left: -20px; + padding-top: 3px; + font-size: 12pt; +} + +ol.tutorstep li p{ + font-size: 9pt; + font-weight: normal; + margin-top: 10px; +} + +ol.tutorstep ol li, ol.tutorstep li ol li, ol.tutorstep li ul li { + font-size: 9pt; + list-style-position: outside; + margin-left: 0px; + font-weight: normal; +} + +ol.tutorstep ol li p, ol.tutorstep ul li p { + font-size: 9pt; + font-weight: normal; + margin-top: 5px; +} + +ol li p, ul li p { + font-size: 9pt; + font-weight: normal; + margin-bottom: 2px; + margin-top: 2px; +} + +ol ol , ol.tutorstep ol{ + font-size: 9pt; + font-weight: normal; + list-style-type: lower-alpha; + color: #1C1C1C; + border-style: none; + margin-top: 10px; +} + +ol.tutorstep ul { + margin-top: 10px; + font-size: 9pt; +} + +ol ol li, ol ul li, ol.tutorstep ol li, ol.tutorstep ul li { + border-style: none; + margin-top: 5px; + font-size: 9pt; +} + +ul { + font-size: 9pt; + font-weight: normal; + color: #1C1C1C; +} + + +/* End of font face declarations */ + +/* Set table borders and heading row background */ +table { + border: 0px; + border-collapse: collapse; + width: 100%; + margin-top: 20px; + margin-bottom: 20px; + background: white; +} + +th { + border-top: 2px solid #719cc7; + border-right: 1px solid #c6d9f1; + border-left: 1px solid #c6d9f1; + background-color: #f3f7fb; + padding: 4px; + color: #719cc7; + font-size: 9pt; + font-weight: bold; +} + +td { + border: 1px solid #c6d9f1; + vertical-align:top; + padding: 3px 20px 5px 20px; + } + +td.middle { + border: 1px solid #c6d9f1; + vertical-align:middle; + padding: 3px 20px 5px 20px; + } + +/* Notes stand out using a light top & bottom borders with yellow background */ +table.note { + border-top: 2px solid #719cc7; + border-left: 0px; + border-right: 0px; + width: 100%; +} + +tr.note { + text-align: left; +} + +th.note { + text-align: left; + background-color: #ddd9c3; + background-image: note.gif; + border-top: 2px solid #719cc7; + border-bottom:1px solid #719cc7; + border-right: none; + +} + +td.note, p.note { + background-color: #eeece1; + color: #1C1C1C; + padding: 5px; + margin-top:12px; + margin-bottom:12px; + border: none; +} + +/* Figure titles are centered and bolded */ +p.figure , ol.tutorstep li p.figure, ol.tutorstep ol li p.figure, ol.tutorstep ul li p.figure { + text-align: center; + font-weight: bold; +} + +/* Red background and white text for things that need fixing before release */ +.fix { + background-color: red; + font-weight: bold; + color: white; + } + +/* Classes for creating collapsible content */ +#banner { + padding: 8px 4px 8px 4px; + /* top right bottom left */ + border: 1px solid #7f7f7f; + width: 100%; + background-image: url("banner.png"); + text-align: left; + font-weight: bold; + font-size: 9pt; + color: #ffffff; +} + +#toc-navigation {width: 20%; position: fixed; right: 17px; top: 0; bottom: 51px; /* overflow: auto; *//* min-width: 200px; *//* background: white; */z-index: 100;padding-top: 10px;/* padding-bottom: 88px; */margin-bottom: 89px;} +#toc {padding: 0px 20px 5px 20px; /* border: 2px solid #567a9c; */ border-radius: 15px;position: absolute;top: 78px;bottom: 9px;overflow: auto;/* margin-bottom: 5px; */padding-bottom: 5px;border-bottom: 3px transparent solid;margin-left: 5px;} +#main {width: 75%; height: 90%;} +#container {width:100%;} +#container #contents {padding:0px 0 20px; overflow: auto;position: fixed;top: 0;bottom: 0;margin-bottom: 64px;right: 200px;left: 20px;} +body.no-toc #container #contents {right: 0;padding-right:30px;} +body.no-toc #toc-navigation {width: auto;} +body.no-toc .top {right: 19px; /* float:none; */ width: 28px;} +body.no-toc #profile {float: right;right: -32px;} +body.no-toc #profile p {padding: 0; margin: 0;} +#container #contents:after {content: "."; display: block; height: 20px; clear: both; visibility: hidden;} + #container #contents>.content {/* width:75%; */min-width: 600px;/* right: 300px; *//* position: fixed; */padding-right: 5px;} + #container #contents>.content>.cont { margin-bottom:80px; padding-bottom:80px; } + +.devicespecs-util {float:right; margin-top:25px;} + .devicespecs-util ul.dutil {margin:0; padding-bottom:0; height: 11px; list-style-type:none;} + .devicespecs-util ul.dutil:after {content: "."; display: block; height: 0px; clear: both; visibility: hidden;} + .devicespecs-util ul.dutil li {float:left; margin-right:8px; padding-right:8px; background:url('../images/bg_util_bar.gif') no-repeat right center; color:#666;} + .devicespecs-util ul.dutil li.none {margin-right:0; padding-right:0; background-image:none;} + .devicespecs-util ul.dutil li a { font-size:11px; color:#666; line-height: 11px;} + .devicespecs-util ul.dutil li a:hover { color:#222; } + .devicespecs-util ul.dutil li a:active { color:#222; } + +ul.devicespecifications {clear:both; width:100%; margin:0; padding: 0;} +ul.devicespecifications > li { width:100%; margin-top:0; padding-left:0; list-style-type:none; border:1px solid #799cd3; padding: 5px 0px 5px 0px;} +ul.devicespecifications li div.devicespec-con {width:90%; margin:10px 0 20px 0; padding:0 14px; font-size: 13px;} +ul.devicespecifications li div.devicespec-tit {/*height:22px;*/ padding-right: 71px; background-color:#ffffff; position: relative;} + ul.devicespecifications li div.devicespec-tit .items-tit { /*float:left;*/ margin:0 0 0 14px; padding:0; color:#567a9c; line-height: 22px; font-size: 14px; font-style:normal; font-weight: bold;} + + ul.devicespecifications li div.devicespec-tit .items-tit-h2 { /*float:left;*/ margin: 0px 0px 0px 14px; padding:0; line-height: 22px; font-size: 18pt; color: #0E437D; font-style:normal; font-weight: bold;} + ul.devicespecifications li div.devicespec-tit .items-tit-h3 { /*float:left;*/ margin:0 0 0 14px; padding:0; line-height: 22px; font-size: 14pt; color: #1C1C1C; font-style:normal; font-weight: bold;} + ul.devicespecifications li div.devicespec-tit .items-tit-h4 { /*float:left;*/ margin:0 0 0 14px; padding:0; line-height: 22px; font-size: 12pt; color: #1C1C1C; font-style:normal; font-weight: bold;} + + ul.devicespecifications li div.devicespec-tit > span {position: absolute; top: 0; right:0;background:#416cbb; display:block; height:22px; margin-right:0; border-left: solid 1px #7a9bd4; } + ul.devicespecifications li div.devicespec-tit > span a.bt-arr {display:block; width: 55px; height:15px; margin-left:0; padding-top:5px; padding-left: 14px; text-align:left; background: url('../images/ico_arr_hidden.gif') 46px 9px no-repeat;} + ul.devicespecifications li div.devicespec-tit > span a.bt-arr em {display:inline-block; height: 14px; line-height:11px; font-size:11px; color:#fff; font-style:normal; margin-right: 8px;} + ul.devicespecifications li div.devicespec-tit > span * {vertical-align:middle;} + + ul.devicespecifications li div.devicespec-con ul.con-list { width:100%; } + ul.devicespecifications li div.devicespec-con ul.con-list li {line-height: 18px; margin:0; padding:0 0 0 7px; background: url("../images/ico_bullet_2_7.gif") 0 8px no-repeat; } + +.ul.ul, .ul.ul li {margin-bottom: 10px; list-style-type: disc; border: none;} +.ul.ul ul, .ul.ul ul li, .ol.ol ul, .ol.ol ul li {list-style-type: circle;} +.ol.ol, .ol.ol li {list-style-type: decimal; border: none;} +.ol.ol ol, .ol.ol ol li, .ul.ul ol, .ul.ul ol li {list-style-type: lower-alpha;} + +.static-cont {width:100%; margin-bottom:40px;} + +.top {text-align: right;} +.toc, ul.toc{ + margin: 10px 0px 0px 0px; + padding-left: 13px; + list-style: disc; + font-size: 9pt; + line-height: 115%; + } + +.toc-title { + font-size: 12pt; + color: #0E437D; + font-weight: bold; + font-style: normal; + line-height: normal; + margin-top: 16pt; +} + +a.top { + display:block; + float: right; + position:fixed; + width: 28px; + height:89px; + bottom:50px; + z-index: 101; + right: 19%; + } + +a img {border: 0;} + +/* Footer includes space and a gray line above */ +#footer { + position: fixed; + /* width: 100%; */ + bottom: 0px; + text-align: center; + border-top: 1px solid #CCCCCC; + background-color: #FFFFFF; + left: 21px; right: 21px; +} + +.footer {font-size: 8pt;} + +caption { + font-size: 9pt; + color: #1C1C1C; + font-weight: bold; + text-align: center; + margin-top: 20px; + margin-bottom: 0px; +} + +div.qindex, div.navpath, div.navtab{ + background-color: #e8eef2; + border: 1px solid #84b0c7; + text-align: center; + margin: 2px; + padding: 2px; +} + +div.qindex, div.navpath { + width: 100%; + line-height: 140%; +} + +div.navtab { + margin-right: 15px; +} + +/* @group Link Styling */ + +a:link { + color: #719cc7; + text-decoration: underline; + font-weight: bold; +} + +a:hover { + color: #0e437d; +} + +a:visited { + text-decoration: underline; + color: #719cc7; + font-weight: bold; +} + +a.qindex { + font-weight: bold; + padding: 2px; +} + +a.qindex:hover { + text-decoration: underline; + color: #0e437d; + padding: 2px; +} + +a.qindex:visited { + text-decoration: underline; + font-weight: bold; + color: #719cc7; + padding: 2px; +} + +a.qindexHL { + text-decoration: underline; + font-weight: bold; + background-color: #6666cc; + color: #ffffff; + padding: 2px 6px; + border: 1px double #9295C2; +} + +a.qindexHL:hover { + text-decoration: none; + background-color: #6666cc; + color: #ffffff; + padding: 2px 6px; +} + +dl.el { + margin-left: -1cm +} + +.fragment { + font-family: monospace, fixed; + font-size: 105%; +} + +pre.fragment { + border: 1px solid #CCCCCC; + background-color: #f5f5f5; + padding: 4px 6px; + margin: 4px 8px 4px 2px; +} + +div.fragment { + border: 1px solid #CCCCCC; + background-color: #f5f5f5; + padding: 6px; +} + +div.ah { + background-color: black; + font-weight: bold; + color: #ffffff; + margin-bottom: 3px; + margin-top: 3px +} + +td.md { + background-color: #f5f5f5; + font-weight: bold; +} + +td.mdname1 { + background-color: #f5f5f5; + font-weight: bold; + color: #602020; +} + +td.mdname { + background-color: #f5f5f5; + font-weight: bold; + color: #602020; + width: 600px; +} + +div.groupHeader { + margin-left: 16px; + margin-top: 12px; + margin-bottom: 6px; + font-weight: bold; +} + +div.groupText { + margin-left: 16px; + font-style: italic; +} + +td.indexkey { + background-color: #eeeeff; + font-weight: bold; + border: 1px solid #CCCCCC; + margin: 2px 0px 2px 0; + padding: 2px 10px; +} + +td.indexvalue { + background-color: #eeeeff; + border: 1px solid #CCCCCC; + padding: 2px 10px; + margin: 2px 0px; +} + +tr.memlist { + background-color: #f0f0f0; +} + +p.formulaDsp { + text-align: center; +} + +img.formulaDsp { +} + +img.formulaInl { + vertical-align: middle; +} + +/* @group Code Colorization */ + +span.keyword { color: #008000 } +span.keywordtype { color: #604020 } +span.keywordflow { color: #e08000 } +span.comment { color: #800000 } +span.preprocessor { color: #806020 } +span.stringliteral { color: #002080 } +span.charliteral { color: #008080 } +span.vhdldigit { color: #ff00ff } +span.vhdlchar { color: #000000 } +span.vhdlkeyword { color: #700070 } +span.vhdllogic { color: #ff0000 } + +.mdTable { + border: 1px solid #868686; + background-color: #F4F4FB; +} + +.mdRow { + padding: 8px 10px; +} + +/* @group Member Descriptions */ + +.mdescLeft, .mdescRight, +.memItemLeft, .memItemRight, +.memTemplItemLeft, .memTemplItemRight, .memTemplParams { + background-color: #F4F4F4A; + border: none; + margin: 4px; + padding: 3px 8px 4px 8px; +} + +.mdescLeft, .mdescRight { + padding: 0px 8px 4px 8px; + color: #555; +} + +.memItemLeft, .memItemRight, .memTemplParams { + border-top: 1px solid #DBDBDB; +} + +.memTemplParams { + color: #606060; +} + +/* @end */ + +/* @group Member Details */ + +/* Styles for detailed member documentation */ + +.memtemplate { + font-size: 80%; + color: #606060; + font-weight: normal; + margin-left: 3px; +} + +.memnav { + background-color: #eeeeff; + border: 1px solid #84b0c7; + text-align: center; + margin: 2px; + margin-right: 15px; + padding: 2px; +} + +.memitem { + padding: 0; +} + +.memname { + white-space: nowrap; + font-weight: bold; +} + +.memproto, .memdoc { + border: 1px solid #9BBCDD; +} + +.memproto { + padding: 0; + background-color: #D5E2EF; + font-weight: bold; + -webkit-border-top-left-radius: 8px; + -webkit-border-top-right-radius: 8px; + -moz-border-radius-topleft: 8px; + -moz-border-radius-topright: 8px; +} + +.memdoc { + padding: 2px 5px; + background-color: #eef3f5; + border-top-width: 0; + -webkit-border-bottom-left-radius: 8px; + -webkit-border-bottom-right-radius: 8px; + -moz-border-radius-bottomleft: 8px; + -moz-border-radius-bottomright: 8px; +} + +.memdoc p, .memdoc dl, .memdoc ul { + margin: 6px 0; +} + +.paramkey { + text-align: right; +} + +.paramtype { + white-space: nowrap; +} + +.paramname { + color: #853E0E; + white-space: nowrap; +} +.paramname em { + font-style: normal; +} + +/* @end */ + +.search { color: #003399; + font-weight: bold; +} + +form.search { + margin-bottom: 0px; + margin-top: 0px; +} + +input.search { font-size: 75%; + color: #000080; + font-weight: normal; + background-color: #eeeeff; +} + +td.tiny { + font-size: 75%; +} + +.highlight { + background-color:#E2E2FF; +} + +/*---------- ide-eclipse Styles ---------*/ +.sh_ide-eclipse{font-family: "Courier New", Courier, monospace; + margin: 0px 0px; + padding: -30px -30px -30px -30px; + font-weight: normal; + font-style: normal;} +.sh_ide-eclipse .sh_sourceCode{background-color:#fff;color:#000;font-weight:normal;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_keyword{color:#7f0055;font-weight:bold;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_type{color:#7f0055;font-weight:bold;font-style:normal;} +/*.sh_ide-eclipse .sh_sourceCode .sh_string{color:#00f;font-weight:normal;font-style:normal;}*/ +.sh_ide-eclipse .sh_sourceCode .sh_string{color:#2A00FF;font-weight:normal;font-style:normal;} + +.sh_ide-eclipse .sh_sourceCode .sh_regexp{color:#00f;font-weight:normal;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_specialchar{color:#00f;font-weight:normal;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_comment{color:#238E23;font-weight:normal;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_number{color:#000;font-weight:normal;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_preproc{color:#3f5fbf;font-weight:normal;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_function{color:#000;font-weight:normal;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_url{color:#00f;font-weight:normal;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_date{color:#7f0055;font-weight:bold;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_time{color:#7f0055;font-weight:bold;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_file{color:#7f0055;font-weight:bold;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_ip{color:#00f;font-weight:normal;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_name{color:#00f;font-weight:normal;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_variable{color:#7f0055;font-weight:bold;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_oldfile{color:#00f;font-weight:normal;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_newfile{color:#00f;font-weight:normal;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_difflines{color:#7f0055;font-weight:bold;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_selector{color:#7f0055;font-weight:bold;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_property{color:#7f0055;font-weight:bold;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_value{color:#00f;font-weight:normal;font-style:normal;} +.sh_ide-eclipse .sh_sourceCode .sh_unknown{font-family: "Courier New", Courier, monospace;} + +/*------------- STYLE FOR NAMES FROM XML FILE -------------*/ +.sh_styleFromXML{color:#800000;font-weight:bold;} +/*-------------------------------------------------------*/ + +/*-------- Snippet Base Styles ----------*/ +.snippet-wrap {position:relative;} +*:first-child+html .snippet-wrap {display:inline-block;} +* html .snippet-wrap {display:inline-block;} +.snippet-reveal{text-decoration:underline;} +.snippet-wrap .snippet-menu, .snippet-wrap .snippet-hide {position:absolute; top:-99999px; right:15px; font-size:.9em;z-index:1;background-color:transparent;} +.snippet-wrap .snippet-hide {top:auto; bottom:1px;} +*:first-child+html .snippet-wrap .snippet-hide {bottom:1px;} +* html .snippet-wrap .snippet-hide {bottom:1px;} +.snippet-wrap .snippet-menu pre, .snippet-wrap .snippet-hide pre {background-color:transparent; margin:1; padding:0;} +.snippet-wrap .snippet-menu a, .snippet-wrap .snippet-hide a {padding:1px; text-decoration:underline;} +.snippet-wrap pre.sh_sourceCode{padding:1px;line-height:120%;overflow:auto;position:relative; +-moz-border-radius:0px; +-webkit-border-radius:0px; +border-radius:0px; +box-shadow: 1px 1px px #000; +-moz-box-shadow: 2px 2px 1px #000; +-webkit-box-shadow: 1px 1px 1px #000;} +.snippet-wrap pre.snippet-textonly {padding:1em;} +*:first-child+html .snippet-wrap pre.snippet-formatted {padding:0.5em 0.5em;} +* html .snippet-wrap pre.snippet-formatted {padding:0em 0.3em;} +.snippet-reveal pre.sh_sourceCode {padding:0em 0em; text-align:right;} +.snippet-wrap .snippet-num li{padding-left:2px;} +.snippet-wrap .snippet-no-num{list-style:none; padding:0em 0em; margin:0;} +.snippet-wrap .snippet-no-num li {list-style:none; padding-left:0;} +.snippet-wrap .snippet-num {margin:1em 0 1em 1em; padding-left:2px;} +.snippet-wrap .snippet-num li {list-style:decimal-leading-zero outside none;} +.snippet-wrap .snippet-no-num li.box {padding:0 6px; margin-left:-6px;} +.snippet-wrap .snippet-num li.box {border:1px solid; list-style-position:inside; margin-left:0px; padding-left:2px;} +*:first-child+html .snippet-wrap .snippet-num li.box {margin-left:-2px;} +* html .snippet-wrap .snippet-num li.box {margin-left:-2px;} +.snippet-wrap li.box-top {border-width:0px 0px 0 !important;} +.snippet-wrap li.box-bot {border-width:0 0px 0px !important;} +.snippet-wrap li.box-mid {border-width:0 0px !important;} +.snippet-wrap .snippet-num li .box-sp {width:10px; display:inline-block;} +*:first-child+html .snippet-wrap .snippet-num li .box-sp {width:20px;} +* html .snippet-wrap .snippet-num li .box-sp {width:2px;} +.snippet-wrap .snippet-no-num li.box {border:1px solid;} +.snippet-wrap .snippet-no-num li .box-sp {display:none;} + +/* Layout fixing */ +.clfix:after {content: "."; display: block; height: 0px; clear: both; visibility: hidden;} +.clfix {display: inline-block;} +.clfix {display: block;} +* html .clfix {height: 1%;} /* Hides from IE-mac */ +.clfix {zoom:1;} /*for IE 5.5-7*/ + +.fl {float:left !important;} +.fr {float:right !important;} +.cl {clear:both;} +.rel {position:relative;} +.abs {position:absolute;} +.ac {text-align:center !important;} +.ar {text-align:right !important;} +.al {text-align:left !important;} +.at {vertical-align:top !important;} +.am {vertical-align:middle !important;} +.ab {vertical-align:bottom;} +.hand {cursor:pointer;} +.bgnone {background:none !important;} +.brnone {border:none !important;} +.b {font-weight:bold !important;} +.n {font-weight:normal !important;} +.invisible{display:block; overflow:hidden; visibility:hidden; width:0; height:0; margin:0; font-size:0; line-height:0;} +.mt5 {margin-top:5px !important;} +/* //Layout fixing */ + +@media print { .hide, .show { display: none; }} + +div#profile { + position: relative; +} +#profile p { + text-align: right; +} + +div#toc_border { + border: 2px solid rgb(86, 122, 156); border-top-left-radius: 15px; border-top-right-radius: 15px; border-bottom-right-radius: 15px; border-bottom-left-radius: 15px; height: 565px; +} + +#contents li { + padding-top: 3px; + margin-top: 5px; + /* overflow: auto; */ +} + +p { + /* overflow: auto; */ +} + +div.table { + /* overflow: auto; */ +} \ No newline at end of file diff --git a/org.tizen.guides/html/images/4_columns.png b/org.tizen.ui.guides/html/images/4_columns.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/4_columns.png rename to org.tizen.ui.guides/html/images/4_columns.png diff --git a/org.tizen.tutorials/html/images/9patch.png b/org.tizen.ui.guides/html/images/9patch.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.tutorials/html/images/9patch.png rename to org.tizen.ui.guides/html/images/9patch.png diff --git a/org.tizen.ui.guides/html/images/9patch_buffer.png b/org.tizen.ui.guides/html/images/9patch_buffer.png new file mode 100755 index 0000000..3895bc8 Binary files /dev/null and b/org.tizen.ui.guides/html/images/9patch_buffer.png differ diff --git a/org.tizen.ui.guides/html/images/9patch_resource.png b/org.tizen.ui.guides/html/images/9patch_resource.png new file mode 100755 index 0000000..7a20d38 Binary files /dev/null and b/org.tizen.ui.guides/html/images/9patch_resource.png differ diff --git a/org.tizen.ui.guides/html/images/9patch_zoomed.png b/org.tizen.ui.guides/html/images/9patch_zoomed.png new file mode 100755 index 0000000..2196d66 Binary files /dev/null and b/org.tizen.ui.guides/html/images/9patch_zoomed.png differ diff --git a/org.tizen.ui.guides/html/images/actor_coordinates.png b/org.tizen.ui.guides/html/images/actor_coordinates.png new file mode 100755 index 0000000..039b06d Binary files /dev/null and b/org.tizen.ui.guides/html/images/actor_coordinates.png differ diff --git a/org.tizen.ui.guides/html/images/actor_position.png b/org.tizen.ui.guides/html/images/actor_position.png new file mode 100755 index 0000000..f591fdc Binary files /dev/null and b/org.tizen.ui.guides/html/images/actor_position.png differ diff --git a/org.tizen.ui.guides/html/images/after_resize.png b/org.tizen.ui.guides/html/images/after_resize.png new file mode 100755 index 0000000..e045c5e Binary files /dev/null and b/org.tizen.ui.guides/html/images/after_resize.png differ diff --git a/org.tizen.guides/html/images/align.png b/org.tizen.ui.guides/html/images/align.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/align.png rename to org.tizen.ui.guides/html/images/align.png diff --git a/org.tizen.ui.guides/html/images/align_hints.png b/org.tizen.ui.guides/html/images/align_hints.png new file mode 100755 index 0000000..4ca26c6 Binary files /dev/null and b/org.tizen.ui.guides/html/images/align_hints.png differ diff --git a/org.tizen.ui.guides/html/images/anchor_point.png b/org.tizen.ui.guides/html/images/anchor_point.png new file mode 100755 index 0000000..1db87e5 Binary files /dev/null and b/org.tizen.ui.guides/html/images/anchor_point.png differ diff --git a/org.tizen.tutorials/html/images/animation1.png b/org.tizen.ui.guides/html/images/animation1.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.tutorials/html/images/animation1.png rename to org.tizen.ui.guides/html/images/animation1.png diff --git a/org.tizen.ui.guides/html/images/animation_components.png b/org.tizen.ui.guides/html/images/animation_components.png new file mode 100755 index 0000000..3e00baf Binary files /dev/null and b/org.tizen.ui.guides/html/images/animation_components.png differ diff --git a/org.tizen.guides/html/images/application_page_layout.png b/org.tizen.ui.guides/html/images/application_page_layout.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/application_page_layout.png rename to org.tizen.ui.guides/html/images/application_page_layout.png diff --git a/org.tizen.ui.guides/html/images/application_store_sd.png b/org.tizen.ui.guides/html/images/application_store_sd.png new file mode 100755 index 0000000..0e2e0fa Binary files /dev/null and b/org.tizen.ui.guides/html/images/application_store_sd.png differ diff --git a/org.tizen.ui.guides/html/images/applying_color.png b/org.tizen.ui.guides/html/images/applying_color.png new file mode 100755 index 0000000..c23e828 Binary files /dev/null and b/org.tizen.ui.guides/html/images/applying_color.png differ diff --git a/org.tizen.ui.guides/html/images/applying_invisibility.png b/org.tizen.ui.guides/html/images/applying_invisibility.png new file mode 100755 index 0000000..53a1529 Binary files /dev/null and b/org.tizen.ui.guides/html/images/applying_invisibility.png differ diff --git a/org.tizen.ui.guides/html/images/aspect-control-both.png b/org.tizen.ui.guides/html/images/aspect-control-both.png new file mode 100755 index 0000000..b807599 Binary files /dev/null and b/org.tizen.ui.guides/html/images/aspect-control-both.png differ diff --git a/org.tizen.ui.guides/html/images/aspect-control-horizontal.png b/org.tizen.ui.guides/html/images/aspect-control-horizontal.png new file mode 100755 index 0000000..143d8fb Binary files /dev/null and b/org.tizen.ui.guides/html/images/aspect-control-horizontal.png differ diff --git a/org.tizen.ui.guides/html/images/aspect-control-none.png b/org.tizen.ui.guides/html/images/aspect-control-none.png new file mode 100755 index 0000000..6d35d33 Binary files /dev/null and b/org.tizen.ui.guides/html/images/aspect-control-none.png differ diff --git a/org.tizen.guides/html/images/backWearable.png b/org.tizen.ui.guides/html/images/backWearable.png similarity index 100% rename from org.tizen.guides/html/images/backWearable.png rename to org.tizen.ui.guides/html/images/backWearable.png diff --git a/org.tizen.ui.guides/html/images/background_order.png b/org.tizen.ui.guides/html/images/background_order.png new file mode 100755 index 0000000..05c958c Binary files /dev/null and b/org.tizen.ui.guides/html/images/background_order.png differ diff --git a/org.tizen.ui.guides/html/images/base_layout.png b/org.tizen.ui.guides/html/images/base_layout.png new file mode 100755 index 0000000..7976836 Binary files /dev/null and b/org.tizen.ui.guides/html/images/base_layout.png differ diff --git a/org.tizen.guides/html/images/base_scale.png b/org.tizen.ui.guides/html/images/base_scale.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/base_scale.png rename to org.tizen.ui.guides/html/images/base_scale.png diff --git a/org.tizen.ui.guides/html/images/base_scales.png b/org.tizen.ui.guides/html/images/base_scales.png new file mode 100755 index 0000000..7f7b224 Binary files /dev/null and b/org.tizen.ui.guides/html/images/base_scales.png differ diff --git a/org.tizen.tutorials/html/images/basic_layout_480x800.png b/org.tizen.ui.guides/html/images/basic_layout_480x800.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.tutorials/html/images/basic_layout_480x800.png rename to org.tizen.ui.guides/html/images/basic_layout_480x800.png diff --git a/org.tizen.tutorials/html/images/basic_layout_720x1280.png b/org.tizen.ui.guides/html/images/basic_layout_720x1280.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.tutorials/html/images/basic_layout_720x1280.png rename to org.tizen.ui.guides/html/images/basic_layout_720x1280.png diff --git a/org.tizen.ui.guides/html/images/before_resize.png b/org.tizen.ui.guides/html/images/before_resize.png new file mode 100755 index 0000000..476210f Binary files /dev/null and b/org.tizen.ui.guides/html/images/before_resize.png differ diff --git a/org.tizen.guides/html/images/bg.png b/org.tizen.ui.guides/html/images/bg.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/bg.png rename to org.tizen.ui.guides/html/images/bg.png diff --git a/org.tizen.guides/html/images/bg_tree.png b/org.tizen.ui.guides/html/images/bg_tree.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/bg_tree.png rename to org.tizen.ui.guides/html/images/bg_tree.png diff --git a/org.tizen.ui.guides/html/images/bg_util_bar.gif b/org.tizen.ui.guides/html/images/bg_util_bar.gif new file mode 100755 index 0000000..977f94d Binary files /dev/null and b/org.tizen.ui.guides/html/images/bg_util_bar.gif differ diff --git a/org.tizen.guides/html/images/bg_wn.png b/org.tizen.ui.guides/html/images/bg_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/bg_wn.png rename to org.tizen.ui.guides/html/images/bg_wn.png diff --git a/org.tizen.tutorials/html/images/blue_box.png b/org.tizen.ui.guides/html/images/blue_box.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.tutorials/html/images/blue_box.png rename to org.tizen.ui.guides/html/images/blue_box.png diff --git a/org.tizen.guides/html/images/border.png b/org.tizen.ui.guides/html/images/border.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/border.png rename to org.tizen.ui.guides/html/images/border.png diff --git a/org.tizen.guides/html/images/bottom.png b/org.tizen.ui.guides/html/images/bottom.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/bottom.png rename to org.tizen.ui.guides/html/images/bottom.png diff --git a/org.tizen.guides/html/images/box.png b/org.tizen.ui.guides/html/images/box.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/box.png rename to org.tizen.ui.guides/html/images/box.png diff --git a/org.tizen.tutorials/html/images/box_model_properties.png b/org.tizen.ui.guides/html/images/box_model_properties.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.tutorials/html/images/box_model_properties.png rename to org.tizen.ui.guides/html/images/box_model_properties.png diff --git a/org.tizen.guides/html/images/box_model_properties_struct.png b/org.tizen.ui.guides/html/images/box_model_properties_struct.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/box_model_properties_struct.png rename to org.tizen.ui.guides/html/images/box_model_properties_struct.png diff --git a/org.tizen.ui.guides/html/images/btn_top.gif b/org.tizen.ui.guides/html/images/btn_top.gif new file mode 100755 index 0000000..d35e824 Binary files /dev/null and b/org.tizen.ui.guides/html/images/btn_top.gif differ diff --git a/org.tizen.guides/html/images/button.png b/org.tizen.ui.guides/html/images/button.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/button.png rename to org.tizen.ui.guides/html/images/button.png diff --git a/org.tizen.guides/html/images/button_anchor.png b/org.tizen.ui.guides/html/images/button_anchor.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/button_anchor.png rename to org.tizen.ui.guides/html/images/button_anchor.png diff --git a/org.tizen.guides/html/images/button_bottom_o_wn.png b/org.tizen.ui.guides/html/images/button_bottom_o_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/button_bottom_o_wn.png rename to org.tizen.ui.guides/html/images/button_bottom_o_wn.png diff --git a/org.tizen.guides/html/images/button_circle.png b/org.tizen.ui.guides/html/images/button_circle.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/button_circle.png rename to org.tizen.ui.guides/html/images/button_circle.png diff --git a/org.tizen.guides/html/images/button_default.png b/org.tizen.ui.guides/html/images/button_default.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/button_default.png rename to org.tizen.ui.guides/html/images/button_default.png diff --git a/org.tizen.guides/html/images/button_default_wn.png b/org.tizen.ui.guides/html/images/button_default_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/button_default_wn.png rename to org.tizen.ui.guides/html/images/button_default_wn.png diff --git a/org.tizen.guides/html/images/button_drawers.png b/org.tizen.ui.guides/html/images/button_drawers.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/button_drawers.png rename to org.tizen.ui.guides/html/images/button_drawers.png diff --git a/org.tizen.guides/html/images/button_dropdown.png b/org.tizen.ui.guides/html/images/button_dropdown.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/button_dropdown.png rename to org.tizen.ui.guides/html/images/button_dropdown.png diff --git a/org.tizen.guides/html/images/button_green_wn.png b/org.tizen.ui.guides/html/images/button_green_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/button_green_wn.png rename to org.tizen.ui.guides/html/images/button_green_wn.png diff --git a/org.tizen.guides/html/images/button_hover_v.png b/org.tizen.ui.guides/html/images/button_hover_v.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/button_hover_v.png rename to org.tizen.ui.guides/html/images/button_hover_v.png diff --git a/org.tizen.guides/html/images/button_hover_v_entry.png b/org.tizen.ui.guides/html/images/button_hover_v_entry.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/button_hover_v_entry.png rename to org.tizen.ui.guides/html/images/button_hover_v_entry.png diff --git a/org.tizen.guides/html/images/button_hoversel.png b/org.tizen.ui.guides/html/images/button_hoversel.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/button_hoversel.png rename to org.tizen.ui.guides/html/images/button_hoversel.png diff --git a/org.tizen.guides/html/images/button_hoversel_entry.png b/org.tizen.ui.guides/html/images/button_hoversel_entry.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/button_hoversel_entry.png rename to org.tizen.ui.guides/html/images/button_hoversel_entry.png diff --git a/org.tizen.guides/html/images/button_next_wn.png b/org.tizen.ui.guides/html/images/button_next_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/button_next_wn.png rename to org.tizen.ui.guides/html/images/button_next_wn.png diff --git a/org.tizen.guides/html/images/button_option.png b/org.tizen.ui.guides/html/images/button_option.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/button_option.png rename to org.tizen.ui.guides/html/images/button_option.png diff --git a/org.tizen.guides/html/images/button_orange_wn.png b/org.tizen.ui.guides/html/images/button_orange_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/button_orange_wn.png rename to org.tizen.ui.guides/html/images/button_orange_wn.png diff --git a/org.tizen.guides/html/images/button_recorder.png b/org.tizen.ui.guides/html/images/button_recorder.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/button_recorder.png rename to org.tizen.ui.guides/html/images/button_recorder.png diff --git a/org.tizen.guides/html/images/button_red_wn.png b/org.tizen.ui.guides/html/images/button_red_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/button_red_wn.png rename to org.tizen.ui.guides/html/images/button_red_wn.png diff --git a/org.tizen.guides/html/images/button_title_cancel.png b/org.tizen.ui.guides/html/images/button_title_cancel.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/button_title_cancel.png rename to org.tizen.ui.guides/html/images/button_title_cancel.png diff --git a/org.tizen.guides/html/images/button_title_done.png b/org.tizen.ui.guides/html/images/button_title_done.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/button_title_done.png rename to org.tizen.ui.guides/html/images/button_title_done.png diff --git a/org.tizen.guides/html/images/button_titleicon_wn.png b/org.tizen.ui.guides/html/images/button_titleicon_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/button_titleicon_wn.png rename to org.tizen.ui.guides/html/images/button_titleicon_wn.png diff --git a/org.tizen.guides/html/images/button_tree.png b/org.tizen.ui.guides/html/images/button_tree.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/button_tree.png rename to org.tizen.ui.guides/html/images/button_tree.png diff --git a/org.tizen.guides/html/images/button_wn.png b/org.tizen.ui.guides/html/images/button_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/button_wn.png rename to org.tizen.ui.guides/html/images/button_wn.png diff --git a/org.tizen.ui.guides/html/images/calculator_sd.png b/org.tizen.ui.guides/html/images/calculator_sd.png new file mode 100755 index 0000000..9434f41 Binary files /dev/null and b/org.tizen.ui.guides/html/images/calculator_sd.png differ diff --git a/org.tizen.guides/html/images/calling_img_sep.png b/org.tizen.ui.guides/html/images/calling_img_sep.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/calling_img_sep.png rename to org.tizen.ui.guides/html/images/calling_img_sep.png diff --git a/org.tizen.guides/html/images/captured_screen1.png b/org.tizen.ui.guides/html/images/captured_screen1.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/captured_screen1.png rename to org.tizen.ui.guides/html/images/captured_screen1.png diff --git a/org.tizen.guides/html/images/captured_screen2.png b/org.tizen.ui.guides/html/images/captured_screen2.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/captured_screen2.png rename to org.tizen.ui.guides/html/images/captured_screen2.png diff --git a/org.tizen.ui.guides/html/images/change_text_globally.png b/org.tizen.ui.guides/html/images/change_text_globally.png new file mode 100755 index 0000000..70880a1 Binary files /dev/null and b/org.tizen.ui.guides/html/images/change_text_globally.png differ diff --git a/org.tizen.ui.guides/html/images/changed_order.png b/org.tizen.ui.guides/html/images/changed_order.png new file mode 100755 index 0000000..93c9844 Binary files /dev/null and b/org.tizen.ui.guides/html/images/changed_order.png differ diff --git a/org.tizen.ui.guides/html/images/changing_opacity.png b/org.tizen.ui.guides/html/images/changing_opacity.png new file mode 100755 index 0000000..629eb70 Binary files /dev/null and b/org.tizen.ui.guides/html/images/changing_opacity.png differ diff --git a/org.tizen.guides/html/images/check.png b/org.tizen.ui.guides/html/images/check.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/check.png rename to org.tizen.ui.guides/html/images/check.png diff --git a/org.tizen.guides/html/images/check_default.png b/org.tizen.ui.guides/html/images/check_default.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/check_default.png rename to org.tizen.ui.guides/html/images/check_default.png diff --git a/org.tizen.guides/html/images/check_default_o_wn.png b/org.tizen.ui.guides/html/images/check_default_o_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/check_default_o_wn.png rename to org.tizen.ui.guides/html/images/check_default_o_wn.png diff --git a/org.tizen.guides/html/images/check_default_wn.png b/org.tizen.ui.guides/html/images/check_default_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/check_default_wn.png rename to org.tizen.ui.guides/html/images/check_default_wn.png diff --git a/org.tizen.guides/html/images/check_favorite.png b/org.tizen.ui.guides/html/images/check_favorite.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/check_favorite.png rename to org.tizen.ui.guides/html/images/check_favorite.png diff --git a/org.tizen.guides/html/images/check_on_off.png b/org.tizen.ui.guides/html/images/check_on_off.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/check_on_off.png rename to org.tizen.ui.guides/html/images/check_on_off.png diff --git a/org.tizen.guides/html/images/check_onoff_o_wn.png b/org.tizen.ui.guides/html/images/check_onoff_o_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/check_onoff_o_wn.png rename to org.tizen.ui.guides/html/images/check_onoff_o_wn.png diff --git a/org.tizen.guides/html/images/check_onoff_wn.png b/org.tizen.ui.guides/html/images/check_onoff_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/check_onoff_wn.png rename to org.tizen.ui.guides/html/images/check_onoff_wn.png diff --git a/org.tizen.guides/html/images/check_small_o_wn.png b/org.tizen.ui.guides/html/images/check_small_o_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/check_small_o_wn.png rename to org.tizen.ui.guides/html/images/check_small_o_wn.png diff --git a/org.tizen.guides/html/images/check_tree.png b/org.tizen.ui.guides/html/images/check_tree.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/check_tree.png rename to org.tizen.ui.guides/html/images/check_tree.png diff --git a/org.tizen.guides/html/images/check_wn.png b/org.tizen.ui.guides/html/images/check_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/check_wn.png rename to org.tizen.ui.guides/html/images/check_wn.png diff --git a/org.tizen.ui.guides/html/images/checkbox_button.png b/org.tizen.ui.guides/html/images/checkbox_button.png new file mode 100755 index 0000000..c716296 Binary files /dev/null and b/org.tizen.ui.guides/html/images/checkbox_button.png differ diff --git a/org.tizen.guides/html/images/circle_datetime.png b/org.tizen.ui.guides/html/images/circle_datetime.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/circle_datetime.png rename to org.tizen.ui.guides/html/images/circle_datetime.png diff --git a/org.tizen.guides/html/images/circle_genlist.png b/org.tizen.ui.guides/html/images/circle_genlist.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/circle_genlist.png rename to org.tizen.ui.guides/html/images/circle_genlist.png diff --git a/org.tizen.guides/html/images/circle_progressbar.png b/org.tizen.ui.guides/html/images/circle_progressbar.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/circle_progressbar.png rename to org.tizen.ui.guides/html/images/circle_progressbar.png diff --git a/org.tizen.guides/html/images/circle_scroller.png b/org.tizen.ui.guides/html/images/circle_scroller.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/circle_scroller.png rename to org.tizen.ui.guides/html/images/circle_scroller.png diff --git a/org.tizen.guides/html/images/circle_slider.png b/org.tizen.ui.guides/html/images/circle_slider.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/circle_slider.png rename to org.tizen.ui.guides/html/images/circle_slider.png diff --git a/org.tizen.guides/html/web/tizen/TAU/images/circular_support.png b/org.tizen.ui.guides/html/images/circular_support.png similarity index 100% rename from org.tizen.guides/html/web/tizen/TAU/images/circular_support.png rename to org.tizen.ui.guides/html/images/circular_support.png diff --git a/org.tizen.guides/html/images/coin_flip_effect.png b/org.tizen.ui.guides/html/images/coin_flip_effect.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/coin_flip_effect.png rename to org.tizen.ui.guides/html/images/coin_flip_effect.png diff --git a/org.tizen.guides/html/images/color_colorplane.png b/org.tizen.ui.guides/html/images/color_colorplane.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/color_colorplane.png rename to org.tizen.ui.guides/html/images/color_colorplane.png diff --git a/org.tizen.guides/html/images/colorsel.png b/org.tizen.ui.guides/html/images/colorsel.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/colorsel.png rename to org.tizen.ui.guides/html/images/colorsel.png diff --git a/org.tizen.guides/html/images/colorselector_tree.png b/org.tizen.ui.guides/html/images/colorselector_tree.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/colorselector_tree.png rename to org.tizen.ui.guides/html/images/colorselector_tree.png diff --git a/org.tizen.guides/html/images/column_break.png b/org.tizen.ui.guides/html/images/column_break.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/column_break.png rename to org.tizen.ui.guides/html/images/column_break.png diff --git a/org.tizen.guides/html/images/column_gap.png b/org.tizen.ui.guides/html/images/column_gap.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/column_gap.png rename to org.tizen.ui.guides/html/images/column_gap.png diff --git a/org.tizen.guides/html/images/column_rule.png b/org.tizen.ui.guides/html/images/column_rule.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/column_rule.png rename to org.tizen.ui.guides/html/images/column_rule.png diff --git a/org.tizen.tutorials/html/images/column_settings.png b/org.tizen.ui.guides/html/images/column_settings.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.tutorials/html/images/column_settings.png rename to org.tizen.ui.guides/html/images/column_settings.png diff --git a/org.tizen.guides/html/images/column_span.png b/org.tizen.ui.guides/html/images/column_span.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/column_span.png rename to org.tizen.ui.guides/html/images/column_span.png diff --git a/org.tizen.guides/html/images/column_width.png b/org.tizen.ui.guides/html/images/column_width.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/column_width.png rename to org.tizen.ui.guides/html/images/column_width.png diff --git a/org.tizen.guides/html/images/conformant.png b/org.tizen.ui.guides/html/images/conformant.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/conformant.png rename to org.tizen.ui.guides/html/images/conformant.png diff --git a/org.tizen.guides/html/images/contextual_bottom_o_wn.png b/org.tizen.ui.guides/html/images/contextual_bottom_o_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/contextual_bottom_o_wn.png rename to org.tizen.ui.guides/html/images/contextual_bottom_o_wn.png diff --git a/org.tizen.guides/html/images/contextual_select_o_wn.png b/org.tizen.ui.guides/html/images/contextual_select_o_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/contextual_select_o_wn.png rename to org.tizen.ui.guides/html/images/contextual_select_o_wn.png diff --git a/org.tizen.guides/html/images/contextual_top_o_wn.png b/org.tizen.ui.guides/html/images/contextual_top_o_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/contextual_top_o_wn.png rename to org.tizen.ui.guides/html/images/contextual_top_o_wn.png diff --git a/org.tizen.guides/html/images/contextual_wn.png b/org.tizen.ui.guides/html/images/contextual_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/contextual_wn.png rename to org.tizen.ui.guides/html/images/contextual_wn.png diff --git a/org.tizen.tutorials/html/images/copy_pasting.png b/org.tizen.ui.guides/html/images/copy_pasting.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.tutorials/html/images/copy_pasting.png rename to org.tizen.ui.guides/html/images/copy_pasting.png diff --git a/org.tizen.guides/html/images/css_bg1.png b/org.tizen.ui.guides/html/images/css_bg1.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/css_bg1.png rename to org.tizen.ui.guides/html/images/css_bg1.png diff --git a/org.tizen.tutorials/html/images/css_bg_tutorial1.png b/org.tizen.ui.guides/html/images/css_bg_tutorial1.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.tutorials/html/images/css_bg_tutorial1.png rename to org.tizen.ui.guides/html/images/css_bg_tutorial1.png diff --git a/org.tizen.tutorials/html/images/css_bg_tutorial2.png b/org.tizen.ui.guides/html/images/css_bg_tutorial2.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.tutorials/html/images/css_bg_tutorial2.png rename to org.tizen.ui.guides/html/images/css_bg_tutorial2.png diff --git a/org.tizen.tutorials/html/images/css_color_tutorial1.png b/org.tizen.ui.guides/html/images/css_color_tutorial1.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.tutorials/html/images/css_color_tutorial1.png rename to org.tizen.ui.guides/html/images/css_color_tutorial1.png diff --git a/org.tizen.guides/html/images/css_result.png b/org.tizen.ui.guides/html/images/css_result.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/css_result.png rename to org.tizen.ui.guides/html/images/css_result.png diff --git a/org.tizen.tutorials/html/images/css_transforms1.png b/org.tizen.ui.guides/html/images/css_transforms1.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.tutorials/html/images/css_transforms1.png rename to org.tizen.ui.guides/html/images/css_transforms1.png diff --git a/org.tizen.tutorials/html/images/css_transforms2.png b/org.tizen.ui.guides/html/images/css_transforms2.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.tutorials/html/images/css_transforms2.png rename to org.tizen.ui.guides/html/images/css_transforms2.png diff --git a/org.tizen.tutorials/html/images/css_transforms5.png b/org.tizen.ui.guides/html/images/css_transforms5.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.tutorials/html/images/css_transforms5.png rename to org.tizen.ui.guides/html/images/css_transforms5.png diff --git a/org.tizen.guides/html/images/ctxpopup1.png b/org.tizen.ui.guides/html/images/ctxpopup1.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/ctxpopup1.png rename to org.tizen.ui.guides/html/images/ctxpopup1.png diff --git a/org.tizen.guides/html/images/ctxpopup2.png b/org.tizen.ui.guides/html/images/ctxpopup2.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/ctxpopup2.png rename to org.tizen.ui.guides/html/images/ctxpopup2.png diff --git a/org.tizen.guides/html/images/ctxpopup3.png b/org.tizen.ui.guides/html/images/ctxpopup3.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/ctxpopup3.png rename to org.tizen.ui.guides/html/images/ctxpopup3.png diff --git a/org.tizen.guides/html/images/ctxpopup_default.png b/org.tizen.ui.guides/html/images/ctxpopup_default.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/ctxpopup_default.png rename to org.tizen.ui.guides/html/images/ctxpopup_default.png diff --git a/org.tizen.guides/html/images/ctxpopup_dropdown.png b/org.tizen.ui.guides/html/images/ctxpopup_dropdown.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/ctxpopup_dropdown.png rename to org.tizen.ui.guides/html/images/ctxpopup_dropdown.png diff --git a/org.tizen.guides/html/images/ctxpopup_dropdown_label.png b/org.tizen.ui.guides/html/images/ctxpopup_dropdown_label.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/ctxpopup_dropdown_label.png rename to org.tizen.ui.guides/html/images/ctxpopup_dropdown_label.png diff --git a/org.tizen.guides/html/images/ctxpopup_tree.png b/org.tizen.ui.guides/html/images/ctxpopup_tree.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/ctxpopup_tree.png rename to org.tizen.ui.guides/html/images/ctxpopup_tree.png diff --git a/org.tizen.guides/html/images/ctxpopup_wn.png b/org.tizen.ui.guides/html/images/ctxpopup_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/ctxpopup_wn.png rename to org.tizen.ui.guides/html/images/ctxpopup_wn.png diff --git a/org.tizen.ui.guides/html/images/dali_component.png b/org.tizen.ui.guides/html/images/dali_component.png new file mode 100755 index 0000000..db4bc0a Binary files /dev/null and b/org.tizen.ui.guides/html/images/dali_component.png differ diff --git a/org.tizen.guides/html/images/date2.png b/org.tizen.ui.guides/html/images/date2.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/date2.png rename to org.tizen.ui.guides/html/images/date2.png diff --git a/org.tizen.guides/html/images/datetime_date_layout.png b/org.tizen.ui.guides/html/images/datetime_date_layout.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/datetime_date_layout.png rename to org.tizen.ui.guides/html/images/datetime_date_layout.png diff --git a/org.tizen.guides/html/images/datetime_date_o_wn.png b/org.tizen.ui.guides/html/images/datetime_date_o_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/datetime_date_o_wn.png rename to org.tizen.ui.guides/html/images/datetime_date_o_wn.png diff --git a/org.tizen.guides/html/images/datetime_date_wn.png b/org.tizen.ui.guides/html/images/datetime_date_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/datetime_date_wn.png rename to org.tizen.ui.guides/html/images/datetime_date_wn.png diff --git a/org.tizen.guides/html/images/datetime_time_24h.png b/org.tizen.ui.guides/html/images/datetime_time_24h.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/datetime_time_24h.png rename to org.tizen.ui.guides/html/images/datetime_time_24h.png diff --git a/org.tizen.guides/html/images/datetime_time_layout.png b/org.tizen.ui.guides/html/images/datetime_time_layout.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/datetime_time_layout.png rename to org.tizen.ui.guides/html/images/datetime_time_layout.png diff --git a/org.tizen.guides/html/images/datetime_time_o_wn.png b/org.tizen.ui.guides/html/images/datetime_time_o_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/datetime_time_o_wn.png rename to org.tizen.ui.guides/html/images/datetime_time_o_wn.png diff --git a/org.tizen.guides/html/images/datetime_time_wn.png b/org.tizen.ui.guides/html/images/datetime_time_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/datetime_time_wn.png rename to org.tizen.ui.guides/html/images/datetime_time_wn.png diff --git a/org.tizen.guides/html/images/datetime_tree.png b/org.tizen.ui.guides/html/images/datetime_tree.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/datetime_tree.png rename to org.tizen.ui.guides/html/images/datetime_tree.png diff --git a/org.tizen.guides/html/images/datetime_wn.png b/org.tizen.ui.guides/html/images/datetime_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/datetime_wn.png rename to org.tizen.ui.guides/html/images/datetime_wn.png diff --git a/org.tizen.ui.guides/html/images/default_order.png b/org.tizen.ui.guides/html/images/default_order.png new file mode 100755 index 0000000..b57aebb Binary files /dev/null and b/org.tizen.ui.guides/html/images/default_order.png differ diff --git a/org.tizen.ui.guides/html/images/depth.png b/org.tizen.ui.guides/html/images/depth.png new file mode 100755 index 0000000..fcbf576 Binary files /dev/null and b/org.tizen.ui.guides/html/images/depth.png differ diff --git a/org.tizen.ui.guides/html/images/dimension_dependency.png b/org.tizen.ui.guides/html/images/dimension_dependency.png new file mode 100755 index 0000000..cc41c53 Binary files /dev/null and b/org.tizen.ui.guides/html/images/dimension_dependency.png differ diff --git a/org.tizen.ui.guides/html/images/display_text_classes.png b/org.tizen.ui.guides/html/images/display_text_classes.png new file mode 100755 index 0000000..6ebc34f Binary files /dev/null and b/org.tizen.ui.guides/html/images/display_text_classes.png differ diff --git a/org.tizen.tutorials/html/images/dynamic_layout_480x800.png b/org.tizen.ui.guides/html/images/dynamic_layout_480x800.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.tutorials/html/images/dynamic_layout_480x800.png rename to org.tizen.ui.guides/html/images/dynamic_layout_480x800.png diff --git a/org.tizen.tutorials/html/images/dynamic_layout_720x1280.png b/org.tizen.ui.guides/html/images/dynamic_layout_720x1280.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.tutorials/html/images/dynamic_layout_720x1280.png rename to org.tizen.ui.guides/html/images/dynamic_layout_720x1280.png diff --git a/org.tizen.ui.guides/html/images/edc_masking.png b/org.tizen.ui.guides/html/images/edc_masking.png new file mode 100755 index 0000000..0bc695d Binary files /dev/null and b/org.tizen.ui.guides/html/images/edc_masking.png differ diff --git a/org.tizen.ui.guides/html/images/edje_color.png b/org.tizen.ui.guides/html/images/edje_color.png new file mode 100755 index 0000000..72bd27c Binary files /dev/null and b/org.tizen.ui.guides/html/images/edje_color.png differ diff --git a/org.tizen.ui.guides/html/images/edje_message.png b/org.tizen.ui.guides/html/images/edje_message.png new file mode 100755 index 0000000..8f0dcfd Binary files /dev/null and b/org.tizen.ui.guides/html/images/edje_message.png differ diff --git a/org.tizen.ui.guides/html/images/edje_object_scales.png b/org.tizen.ui.guides/html/images/edje_object_scales.png new file mode 100755 index 0000000..a79d6de Binary files /dev/null and b/org.tizen.ui.guides/html/images/edje_object_scales.png differ diff --git a/org.tizen.ui.guides/html/images/edje_signal1.png b/org.tizen.ui.guides/html/images/edje_signal1.png new file mode 100755 index 0000000..afabbed Binary files /dev/null and b/org.tizen.ui.guides/html/images/edje_signal1.png differ diff --git a/org.tizen.ui.guides/html/images/edje_signal2.png b/org.tizen.ui.guides/html/images/edje_signal2.png new file mode 100755 index 0000000..5ba68a2 Binary files /dev/null and b/org.tizen.ui.guides/html/images/edje_signal2.png differ diff --git a/org.tizen.ui.guides/html/images/edje_text_main.png b/org.tizen.ui.guides/html/images/edje_text_main.png new file mode 100755 index 0000000..9021e98 Binary files /dev/null and b/org.tizen.ui.guides/html/images/edje_text_main.png differ diff --git a/org.tizen.ui.guides/html/images/efl_complex_clock.png b/org.tizen.ui.guides/html/images/efl_complex_clock.png new file mode 100755 index 0000000..28d02e8 Binary files /dev/null and b/org.tizen.ui.guides/html/images/efl_complex_clock.png differ diff --git a/org.tizen.ui.guides/html/images/efl_complex_clock_tree.png b/org.tizen.ui.guides/html/images/efl_complex_clock_tree.png new file mode 100755 index 0000000..2703c4a Binary files /dev/null and b/org.tizen.ui.guides/html/images/efl_complex_clock_tree.png differ diff --git a/org.tizen.guides/html/images/efl_layers.png b/org.tizen.ui.guides/html/images/efl_layers.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/efl_layers.png rename to org.tizen.ui.guides/html/images/efl_layers.png diff --git a/org.tizen.guides/html/images/efl_notilevels.png b/org.tizen.ui.guides/html/images/efl_notilevels.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/efl_notilevels.png rename to org.tizen.ui.guides/html/images/efl_notilevels.png diff --git a/org.tizen.guides/html/images/efl_phone.png b/org.tizen.ui.guides/html/images/efl_phone.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/efl_phone.png rename to org.tizen.ui.guides/html/images/efl_phone.png diff --git a/org.tizen.ui.guides/html/images/efl_simple_clock.png b/org.tizen.ui.guides/html/images/efl_simple_clock.png new file mode 100755 index 0000000..62092e6 Binary files /dev/null and b/org.tizen.ui.guides/html/images/efl_simple_clock.png differ diff --git a/org.tizen.ui.guides/html/images/efl_simple_clock_tree.png b/org.tizen.ui.guides/html/images/efl_simple_clock_tree.png new file mode 100755 index 0000000..9b4a6ed Binary files /dev/null and b/org.tizen.ui.guides/html/images/efl_simple_clock_tree.png differ diff --git a/org.tizen.guides/html/images/efl_windowlayer.png b/org.tizen.ui.guides/html/images/efl_windowlayer.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/efl_windowlayer.png rename to org.tizen.ui.guides/html/images/efl_windowlayer.png diff --git a/org.tizen.ui.guides/html/images/efllibs.png b/org.tizen.ui.guides/html/images/efllibs.png new file mode 100755 index 0000000..696f6bb Binary files /dev/null and b/org.tizen.ui.guides/html/images/efllibs.png differ diff --git a/org.tizen.guides/html/images/elementary.png b/org.tizen.ui.guides/html/images/elementary.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/elementary.png rename to org.tizen.ui.guides/html/images/elementary.png diff --git a/org.tizen.ui.guides/html/images/elementary_app.png b/org.tizen.ui.guides/html/images/elementary_app.png new file mode 100755 index 0000000..2e86785 Binary files /dev/null and b/org.tizen.ui.guides/html/images/elementary_app.png differ diff --git a/org.tizen.ui.guides/html/images/email_sample.png b/org.tizen.ui.guides/html/images/email_sample.png new file mode 100755 index 0000000..66204fb Binary files /dev/null and b/org.tizen.ui.guides/html/images/email_sample.png differ diff --git a/org.tizen.ui.guides/html/images/empty_window.png b/org.tizen.ui.guides/html/images/empty_window.png new file mode 100755 index 0000000..3fffe12 Binary files /dev/null and b/org.tizen.ui.guides/html/images/empty_window.png differ diff --git a/org.tizen.guides/html/images/enlarge_low_res_image.png b/org.tizen.ui.guides/html/images/enlarge_low_res_image.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/enlarge_low_res_image.png rename to org.tizen.ui.guides/html/images/enlarge_low_res_image.png diff --git a/org.tizen.guides/html/images/entry.png b/org.tizen.ui.guides/html/images/entry.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/entry.png rename to org.tizen.ui.guides/html/images/entry.png diff --git a/org.tizen.guides/html/images/entry2.png b/org.tizen.ui.guides/html/images/entry2.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/entry2.png rename to org.tizen.ui.guides/html/images/entry2.png diff --git a/org.tizen.guides/html/images/entry2_wn.png b/org.tizen.ui.guides/html/images/entry2_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/entry2_wn.png rename to org.tizen.ui.guides/html/images/entry2_wn.png diff --git a/org.tizen.guides/html/images/entry_default.png b/org.tizen.ui.guides/html/images/entry_default.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/entry_default.png rename to org.tizen.ui.guides/html/images/entry_default.png diff --git a/org.tizen.guides/html/images/entry_default_wn.png b/org.tizen.ui.guides/html/images/entry_default_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/entry_default_wn.png rename to org.tizen.ui.guides/html/images/entry_default_wn.png diff --git a/org.tizen.guides/html/images/entry_tree.png b/org.tizen.ui.guides/html/images/entry_tree.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/entry_tree.png rename to org.tizen.ui.guides/html/images/entry_tree.png diff --git a/org.tizen.guides/html/images/entry_wn.png b/org.tizen.ui.guides/html/images/entry_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/entry_wn.png rename to org.tizen.ui.guides/html/images/entry_wn.png diff --git a/org.tizen.ui.guides/html/images/evas_advanced.png b/org.tizen.ui.guides/html/images/evas_advanced.png new file mode 100755 index 0000000..5cad8b2 Binary files /dev/null and b/org.tizen.ui.guides/html/images/evas_advanced.png differ diff --git a/org.tizen.guides/html/images/evas_blur1.png b/org.tizen.ui.guides/html/images/evas_blur1.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/evas_blur1.png rename to org.tizen.ui.guides/html/images/evas_blur1.png diff --git a/org.tizen.guides/html/images/evas_blur2.png b/org.tizen.ui.guides/html/images/evas_blur2.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/evas_blur2.png rename to org.tizen.ui.guides/html/images/evas_blur2.png diff --git a/org.tizen.guides/html/images/evas_image_loader.png b/org.tizen.ui.guides/html/images/evas_image_loader.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/evas_image_loader.png rename to org.tizen.ui.guides/html/images/evas_image_loader.png diff --git a/org.tizen.guides/html/images/evas_image_scaling.png b/org.tizen.ui.guides/html/images/evas_image_scaling.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/evas_image_scaling.png rename to org.tizen.ui.guides/html/images/evas_image_scaling.png diff --git a/org.tizen.guides/html/images/evas_map_1.png b/org.tizen.ui.guides/html/images/evas_map_1.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/evas_map_1.png rename to org.tizen.ui.guides/html/images/evas_map_1.png diff --git a/org.tizen.guides/html/images/evas_map_10.png b/org.tizen.ui.guides/html/images/evas_map_10.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/evas_map_10.png rename to org.tizen.ui.guides/html/images/evas_map_10.png diff --git a/org.tizen.guides/html/images/evas_map_11.png b/org.tizen.ui.guides/html/images/evas_map_11.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/evas_map_11.png rename to org.tizen.ui.guides/html/images/evas_map_11.png diff --git a/org.tizen.guides/html/images/evas_map_2.png b/org.tizen.ui.guides/html/images/evas_map_2.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/evas_map_2.png rename to org.tizen.ui.guides/html/images/evas_map_2.png diff --git a/org.tizen.guides/html/images/evas_map_3.png b/org.tizen.ui.guides/html/images/evas_map_3.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/evas_map_3.png rename to org.tizen.ui.guides/html/images/evas_map_3.png diff --git a/org.tizen.guides/html/images/evas_map_4.png b/org.tizen.ui.guides/html/images/evas_map_4.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/evas_map_4.png rename to org.tizen.ui.guides/html/images/evas_map_4.png diff --git a/org.tizen.guides/html/images/evas_map_5.png b/org.tizen.ui.guides/html/images/evas_map_5.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/evas_map_5.png rename to org.tizen.ui.guides/html/images/evas_map_5.png diff --git a/org.tizen.guides/html/images/evas_map_6.png b/org.tizen.ui.guides/html/images/evas_map_6.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/evas_map_6.png rename to org.tizen.ui.guides/html/images/evas_map_6.png diff --git a/org.tizen.guides/html/images/evas_map_7.png b/org.tizen.ui.guides/html/images/evas_map_7.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/evas_map_7.png rename to org.tizen.ui.guides/html/images/evas_map_7.png diff --git a/org.tizen.guides/html/images/evas_map_8.png b/org.tizen.ui.guides/html/images/evas_map_8.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/evas_map_8.png rename to org.tizen.ui.guides/html/images/evas_map_8.png diff --git a/org.tizen.guides/html/images/evas_map_9.png b/org.tizen.ui.guides/html/images/evas_map_9.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/evas_map_9.png rename to org.tizen.ui.guides/html/images/evas_map_9.png diff --git a/org.tizen.ui.guides/html/images/evas_map_effect.png b/org.tizen.ui.guides/html/images/evas_map_effect.png new file mode 100755 index 0000000..3b144eb Binary files /dev/null and b/org.tizen.ui.guides/html/images/evas_map_effect.png differ diff --git a/org.tizen.guides/html/images/evas_object_display.png b/org.tizen.ui.guides/html/images/evas_object_display.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/evas_object_display.png rename to org.tizen.ui.guides/html/images/evas_object_display.png diff --git a/org.tizen.guides/html/images/evas_partial_update.png b/org.tizen.ui.guides/html/images/evas_partial_update.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/evas_partial_update.png rename to org.tizen.ui.guides/html/images/evas_partial_update.png diff --git a/org.tizen.guides/html/images/evas_scaling1.png b/org.tizen.ui.guides/html/images/evas_scaling1.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/evas_scaling1.png rename to org.tizen.ui.guides/html/images/evas_scaling1.png diff --git a/org.tizen.guides/html/images/evas_scaling2.png b/org.tizen.ui.guides/html/images/evas_scaling2.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/evas_scaling2.png rename to org.tizen.ui.guides/html/images/evas_scaling2.png diff --git a/org.tizen.guides/html/images/evas_scaling3.png b/org.tizen.ui.guides/html/images/evas_scaling3.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/evas_scaling3.png rename to org.tizen.ui.guides/html/images/evas_scaling3.png diff --git a/org.tizen.guides/html/images/evas_smooth_disabled.png b/org.tizen.ui.guides/html/images/evas_smooth_disabled.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/evas_smooth_disabled.png rename to org.tizen.ui.guides/html/images/evas_smooth_disabled.png diff --git a/org.tizen.guides/html/images/evas_smooth_enabled.png b/org.tizen.ui.guides/html/images/evas_smooth_enabled.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/evas_smooth_enabled.png rename to org.tizen.ui.guides/html/images/evas_smooth_enabled.png diff --git a/org.tizen.guides/html/images/events.png b/org.tizen.ui.guides/html/images/events.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/events.png rename to org.tizen.ui.guides/html/images/events.png diff --git a/org.tizen.guides/html/images/events2.png b/org.tizen.ui.guides/html/images/events2.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/events2.png rename to org.tizen.ui.guides/html/images/events2.png diff --git a/org.tizen.guides/html/images/events3.png b/org.tizen.ui.guides/html/images/events3.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/events3.png rename to org.tizen.ui.guides/html/images/events3.png diff --git a/org.tizen.guides/html/images/events_flow.png b/org.tizen.ui.guides/html/images/events_flow.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/events_flow.png rename to org.tizen.ui.guides/html/images/events_flow.png diff --git a/org.tizen.guides/html/images/events_scope.png b/org.tizen.ui.guides/html/images/events_scope.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/events_scope.png rename to org.tizen.ui.guides/html/images/events_scope.png diff --git a/org.tizen.tutorials/html/images/events_using_css3.png b/org.tizen.ui.guides/html/images/events_using_css3.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.tutorials/html/images/events_using_css3.png rename to org.tizen.ui.guides/html/images/events_using_css3.png diff --git a/org.tizen.tutorials/html/images/events_using_javascript.png b/org.tizen.ui.guides/html/images/events_using_javascript.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.tutorials/html/images/events_using_javascript.png rename to org.tizen.ui.guides/html/images/events_using_javascript.png diff --git a/org.tizen.tutorials/html/images/fade_affect_animation.png b/org.tizen.ui.guides/html/images/fade_affect_animation.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.tutorials/html/images/fade_affect_animation.png rename to org.tizen.ui.guides/html/images/fade_affect_animation.png diff --git a/org.tizen.ui.guides/html/images/fill_to_parent.png b/org.tizen.ui.guides/html/images/fill_to_parent.png new file mode 100755 index 0000000..12f3fe7 Binary files /dev/null and b/org.tizen.ui.guides/html/images/fill_to_parent.png differ diff --git a/org.tizen.ui.guides/html/images/first_screen_edc.png b/org.tizen.ui.guides/html/images/first_screen_edc.png new file mode 100755 index 0000000..04d6b7b Binary files /dev/null and b/org.tizen.ui.guides/html/images/first_screen_edc.png differ diff --git a/org.tizen.ui.guides/html/images/fit_to_children.png b/org.tizen.ui.guides/html/images/fit_to_children.png new file mode 100755 index 0000000..fcea3a4 Binary files /dev/null and b/org.tizen.ui.guides/html/images/fit_to_children.png differ diff --git a/org.tizen.ui.guides/html/images/fixed.png b/org.tizen.ui.guides/html/images/fixed.png new file mode 100755 index 0000000..c0eeb6c Binary files /dev/null and b/org.tizen.ui.guides/html/images/fixed.png differ diff --git a/org.tizen.guides/html/images/flex_container.png b/org.tizen.ui.guides/html/images/flex_container.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/flex_container.png rename to org.tizen.ui.guides/html/images/flex_container.png diff --git a/org.tizen.tutorials/html/images/flexcontainer_properties.png b/org.tizen.ui.guides/html/images/flexcontainer_properties.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.tutorials/html/images/flexcontainer_properties.png rename to org.tizen.ui.guides/html/images/flexcontainer_properties.png diff --git a/org.tizen.tutorials/html/images/flexible_box_allignment.png b/org.tizen.ui.guides/html/images/flexible_box_alignment.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.tutorials/html/images/flexible_box_allignment.png rename to org.tizen.ui.guides/html/images/flexible_box_alignment.png diff --git a/org.tizen.tutorials/html/images/flexible_default_structure.png b/org.tizen.ui.guides/html/images/flexible_default_structure.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.tutorials/html/images/flexible_default_structure.png rename to org.tizen.ui.guides/html/images/flexible_default_structure.png diff --git a/org.tizen.tutorials/html/images/flexible_screen_size.png b/org.tizen.ui.guides/html/images/flexible_screen_size.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.tutorials/html/images/flexible_screen_size.png rename to org.tizen.ui.guides/html/images/flexible_screen_size.png diff --git a/org.tizen.tutorials/html/images/flexitem_properties.png b/org.tizen.ui.guides/html/images/flexitem_properties.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.tutorials/html/images/flexitem_properties.png rename to org.tizen.ui.guides/html/images/flexitem_properties.png diff --git a/org.tizen.guides/html/images/flip_tree.png b/org.tizen.ui.guides/html/images/flip_tree.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/flip_tree.png rename to org.tizen.ui.guides/html/images/flip_tree.png diff --git a/org.tizen.guides/html/images/flipsel_default.png b/org.tizen.ui.guides/html/images/flipsel_default.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/flipsel_default.png rename to org.tizen.ui.guides/html/images/flipsel_default.png diff --git a/org.tizen.ui.guides/html/images/focal_length.png b/org.tizen.ui.guides/html/images/focal_length.png new file mode 100755 index 0000000..789ea75 Binary files /dev/null and b/org.tizen.ui.guides/html/images/focal_length.png differ diff --git a/org.tizen.tutorials/html/images/font_face.png b/org.tizen.ui.guides/html/images/font_face.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.tutorials/html/images/font_face.png rename to org.tizen.ui.guides/html/images/font_face.png diff --git a/org.tizen.tutorials/html/images/font_properties.png b/org.tizen.ui.guides/html/images/font_properties.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.tutorials/html/images/font_properties.png rename to org.tizen.ui.guides/html/images/font_properties.png diff --git a/org.tizen.tutorials/html/images/form_contact_layout.png b/org.tizen.ui.guides/html/images/form_contact_layout.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.tutorials/html/images/form_contact_layout.png rename to org.tizen.ui.guides/html/images/form_contact_layout.png diff --git a/org.tizen.guides/html/images/gengrid.png b/org.tizen.ui.guides/html/images/gengrid.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/gengrid.png rename to org.tizen.ui.guides/html/images/gengrid.png diff --git a/org.tizen.guides/html/images/gengrid_album_pre.png b/org.tizen.ui.guides/html/images/gengrid_album_pre.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/gengrid_album_pre.png rename to org.tizen.ui.guides/html/images/gengrid_album_pre.png diff --git a/org.tizen.guides/html/images/gengrid_block.png b/org.tizen.ui.guides/html/images/gengrid_block.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/gengrid_block.png rename to org.tizen.ui.guides/html/images/gengrid_block.png diff --git a/org.tizen.guides/html/images/gengrid_def.png b/org.tizen.ui.guides/html/images/gengrid_def.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/gengrid_def.png rename to org.tizen.ui.guides/html/images/gengrid_def.png diff --git a/org.tizen.guides/html/images/gengrid_def_gridtext.png b/org.tizen.ui.guides/html/images/gengrid_def_gridtext.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/gengrid_def_gridtext.png rename to org.tizen.ui.guides/html/images/gengrid_def_gridtext.png diff --git a/org.tizen.guides/html/images/gengrid_def_gridtext2.png b/org.tizen.ui.guides/html/images/gengrid_def_gridtext2.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/gengrid_def_gridtext2.png rename to org.tizen.ui.guides/html/images/gengrid_def_gridtext2.png diff --git a/org.tizen.guides/html/images/gengrid_def_style.png b/org.tizen.ui.guides/html/images/gengrid_def_style.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/gengrid_def_style.png rename to org.tizen.ui.guides/html/images/gengrid_def_style.png diff --git a/org.tizen.guides/html/images/gengrid_default.png b/org.tizen.ui.guides/html/images/gengrid_default.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/gengrid_default.png rename to org.tizen.ui.guides/html/images/gengrid_default.png diff --git a/org.tizen.guides/html/images/gengrid_grp_index.png b/org.tizen.ui.guides/html/images/gengrid_grp_index.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/gengrid_grp_index.png rename to org.tizen.ui.guides/html/images/gengrid_grp_index.png diff --git a/org.tizen.guides/html/images/gengrid_tree.png b/org.tizen.ui.guides/html/images/gengrid_tree.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/gengrid_tree.png rename to org.tizen.ui.guides/html/images/gengrid_tree.png diff --git a/org.tizen.guides/html/images/genlist.png b/org.tizen.ui.guides/html/images/genlist.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/genlist.png rename to org.tizen.ui.guides/html/images/genlist.png diff --git a/org.tizen.guides/html/images/genlist1_wn.png b/org.tizen.ui.guides/html/images/genlist1_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/genlist1_wn.png rename to org.tizen.ui.guides/html/images/genlist1_wn.png diff --git a/org.tizen.guides/html/images/genlist2_wn.png b/org.tizen.ui.guides/html/images/genlist2_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/genlist2_wn.png rename to org.tizen.ui.guides/html/images/genlist2_wn.png diff --git a/org.tizen.guides/html/images/genlist3_wn.png b/org.tizen.ui.guides/html/images/genlist3_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/genlist3_wn.png rename to org.tizen.ui.guides/html/images/genlist3_wn.png diff --git a/org.tizen.tutorials/html/images/genlist_1line.png b/org.tizen.ui.guides/html/images/genlist_1line.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.tutorials/html/images/genlist_1line.png rename to org.tizen.ui.guides/html/images/genlist_1line.png diff --git a/org.tizen.guides/html/images/genlist_1text1icon1_o_wn.png b/org.tizen.ui.guides/html/images/genlist_1text1icon1_o_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/genlist_1text1icon1_o_wn.png rename to org.tizen.ui.guides/html/images/genlist_1text1icon1_o_wn.png diff --git a/org.tizen.guides/html/images/genlist_1text1icon1_wn.png b/org.tizen.ui.guides/html/images/genlist_1text1icon1_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/genlist_1text1icon1_wn.png rename to org.tizen.ui.guides/html/images/genlist_1text1icon1_wn.png diff --git a/org.tizen.guides/html/images/genlist_1text1icon_o_wn.png b/org.tizen.ui.guides/html/images/genlist_1text1icon_o_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/genlist_1text1icon_o_wn.png rename to org.tizen.ui.guides/html/images/genlist_1text1icon_o_wn.png diff --git a/org.tizen.guides/html/images/genlist_1text1icon_wn.png b/org.tizen.ui.guides/html/images/genlist_1text1icon_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/genlist_1text1icon_wn.png rename to org.tizen.ui.guides/html/images/genlist_1text1icon_wn.png diff --git a/org.tizen.guides/html/images/genlist_1text1icondivider_o_wn.png b/org.tizen.ui.guides/html/images/genlist_1text1icondivider_o_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/genlist_1text1icondivider_o_wn.png rename to org.tizen.ui.guides/html/images/genlist_1text1icondivider_o_wn.png diff --git a/org.tizen.guides/html/images/genlist_1text1icondivider_wn.png b/org.tizen.ui.guides/html/images/genlist_1text1icondivider_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/genlist_1text1icondivider_wn.png rename to org.tizen.ui.guides/html/images/genlist_1text1icondivider_wn.png diff --git a/org.tizen.guides/html/images/genlist_1text_o_wn.png b/org.tizen.ui.guides/html/images/genlist_1text_o_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/genlist_1text_o_wn.png rename to org.tizen.ui.guides/html/images/genlist_1text_o_wn.png diff --git a/org.tizen.guides/html/images/genlist_1text_wn.png b/org.tizen.ui.guides/html/images/genlist_1text_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/genlist_1text_wn.png rename to org.tizen.ui.guides/html/images/genlist_1text_wn.png diff --git a/org.tizen.guides/html/images/genlist_2text1_wn.png b/org.tizen.ui.guides/html/images/genlist_2text1_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/genlist_2text1_wn.png rename to org.tizen.ui.guides/html/images/genlist_2text1_wn.png diff --git a/org.tizen.guides/html/images/genlist_2text1icon1_o_wn.png b/org.tizen.ui.guides/html/images/genlist_2text1icon1_o_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/genlist_2text1icon1_o_wn.png rename to org.tizen.ui.guides/html/images/genlist_2text1icon1_o_wn.png diff --git a/org.tizen.guides/html/images/genlist_2text1icon1_wn.png b/org.tizen.ui.guides/html/images/genlist_2text1icon1_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/genlist_2text1icon1_wn.png rename to org.tizen.ui.guides/html/images/genlist_2text1icon1_wn.png diff --git a/org.tizen.guides/html/images/genlist_2text_o_wn.png b/org.tizen.ui.guides/html/images/genlist_2text_o_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/genlist_2text_o_wn.png rename to org.tizen.ui.guides/html/images/genlist_2text_o_wn.png diff --git a/org.tizen.guides/html/images/genlist_2text_wn.png b/org.tizen.ui.guides/html/images/genlist_2text_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/genlist_2text_wn.png rename to org.tizen.ui.guides/html/images/genlist_2text_wn.png diff --git a/org.tizen.guides/html/images/genlist_def_o_wn.png b/org.tizen.ui.guides/html/images/genlist_def_o_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/genlist_def_o_wn.png rename to org.tizen.ui.guides/html/images/genlist_def_o_wn.png diff --git a/org.tizen.guides/html/images/genlist_def_wn.png b/org.tizen.ui.guides/html/images/genlist_def_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/genlist_def_wn.png rename to org.tizen.ui.guides/html/images/genlist_def_wn.png diff --git a/org.tizen.guides/html/images/genlist_edit_o_wn.png b/org.tizen.ui.guides/html/images/genlist_edit_o_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/genlist_edit_o_wn.png rename to org.tizen.ui.guides/html/images/genlist_edit_o_wn.png diff --git a/org.tizen.guides/html/images/genlist_group_o_wn.png b/org.tizen.ui.guides/html/images/genlist_group_o_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/genlist_group_o_wn.png rename to org.tizen.ui.guides/html/images/genlist_group_o_wn.png diff --git a/org.tizen.guides/html/images/genlist_group_wn.png b/org.tizen.ui.guides/html/images/genlist_group_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/genlist_group_wn.png rename to org.tizen.ui.guides/html/images/genlist_group_wn.png diff --git a/org.tizen.guides/html/images/genlist_htree.png b/org.tizen.ui.guides/html/images/genlist_htree.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/genlist_htree.png rename to org.tizen.ui.guides/html/images/genlist_htree.png diff --git a/org.tizen.tutorials/html/images/genlist_item.png b/org.tizen.ui.guides/html/images/genlist_item.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.tutorials/html/images/genlist_item.png rename to org.tizen.ui.guides/html/images/genlist_item.png diff --git a/org.tizen.guides/html/images/genlist_multi.png b/org.tizen.ui.guides/html/images/genlist_multi.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/genlist_multi.png rename to org.tizen.ui.guides/html/images/genlist_multi.png diff --git a/org.tizen.guides/html/images/genlist_multi1_wn.png b/org.tizen.ui.guides/html/images/genlist_multi1_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/genlist_multi1_wn.png rename to org.tizen.ui.guides/html/images/genlist_multi1_wn.png diff --git a/org.tizen.guides/html/images/genlist_multi2_wn.png b/org.tizen.ui.guides/html/images/genlist_multi2_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/genlist_multi2_wn.png rename to org.tizen.ui.guides/html/images/genlist_multi2_wn.png diff --git a/org.tizen.guides/html/images/genlist_title_o_wn.png b/org.tizen.ui.guides/html/images/genlist_title_o_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/genlist_title_o_wn.png rename to org.tizen.ui.guides/html/images/genlist_title_o_wn.png diff --git a/org.tizen.guides/html/images/genlist_tree.png b/org.tizen.ui.guides/html/images/genlist_tree.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/genlist_tree.png rename to org.tizen.ui.guides/html/images/genlist_tree.png diff --git a/org.tizen.tutorials/html/images/genlist_wn.png b/org.tizen.ui.guides/html/images/genlist_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.tutorials/html/images/genlist_wn.png rename to org.tizen.ui.guides/html/images/genlist_wn.png diff --git a/org.tizen.tutorials/html/images/gesture_view2.png b/org.tizen.ui.guides/html/images/gesture_view2.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.tutorials/html/images/gesture_view2.png rename to org.tizen.ui.guides/html/images/gesture_view2.png diff --git a/org.tizen.guides/html/images/gl-default.png b/org.tizen.ui.guides/html/images/gl-default.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/gl-default.png rename to org.tizen.ui.guides/html/images/gl-default.png diff --git a/org.tizen.guides/html/images/gl-double-label.png b/org.tizen.ui.guides/html/images/gl-double-label.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/gl-double-label.png rename to org.tizen.ui.guides/html/images/gl-double-label.png diff --git a/org.tizen.guides/html/images/gl-end-icon.png b/org.tizen.ui.guides/html/images/gl-end-icon.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/gl-end-icon.png rename to org.tizen.ui.guides/html/images/gl-end-icon.png diff --git a/org.tizen.ui.guides/html/images/global_scales.png b/org.tizen.ui.guides/html/images/global_scales.png new file mode 100755 index 0000000..849dd6d Binary files /dev/null and b/org.tizen.ui.guides/html/images/global_scales.png differ diff --git a/org.tizen.guides/html/images/globalize_folder_structure.png b/org.tizen.ui.guides/html/images/globalize_folder_structure.png similarity index 100% rename from org.tizen.guides/html/images/globalize_folder_structure.png rename to org.tizen.ui.guides/html/images/globalize_folder_structure.png diff --git a/org.tizen.guides/html/images/globalize_folder_structure_main.png b/org.tizen.ui.guides/html/images/globalize_folder_structure_main.png similarity index 100% rename from org.tizen.guides/html/images/globalize_folder_structure_main.png rename to org.tizen.ui.guides/html/images/globalize_folder_structure_main.png diff --git a/org.tizen.guides/html/images/glview.png b/org.tizen.ui.guides/html/images/glview.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/glview.png rename to org.tizen.ui.guides/html/images/glview.png diff --git a/org.tizen.guides/html/images/glview_tree.png b/org.tizen.ui.guides/html/images/glview_tree.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/glview_tree.png rename to org.tizen.ui.guides/html/images/glview_tree.png diff --git a/org.tizen.guides/html/images/glview_wn.png b/org.tizen.ui.guides/html/images/glview_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/glview_wn.png rename to org.tizen.ui.guides/html/images/glview_wn.png diff --git a/org.tizen.ui.guides/html/images/google_cardboard.png b/org.tizen.ui.guides/html/images/google_cardboard.png new file mode 100755 index 0000000..8ee3877 Binary files /dev/null and b/org.tizen.ui.guides/html/images/google_cardboard.png differ diff --git a/org.tizen.ui.guides/html/images/grid.png b/org.tizen.ui.guides/html/images/grid.png new file mode 100755 index 0000000..c9d22ae Binary files /dev/null and b/org.tizen.ui.guides/html/images/grid.png differ diff --git a/org.tizen.ui.guides/html/images/ico_arr_hidden.gif b/org.tizen.ui.guides/html/images/ico_arr_hidden.gif new file mode 100755 index 0000000..9a9d3ff Binary files /dev/null and b/org.tizen.ui.guides/html/images/ico_arr_hidden.gif differ diff --git a/org.tizen.ui.guides/html/images/ico_bullet_2_7.gif b/org.tizen.ui.guides/html/images/ico_bullet_2_7.gif new file mode 100755 index 0000000..8de872c Binary files /dev/null and b/org.tizen.ui.guides/html/images/ico_bullet_2_7.gif differ diff --git a/org.tizen.guides/html/images/icon.png b/org.tizen.ui.guides/html/images/icon.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon.png rename to org.tizen.ui.guides/html/images/icon.png diff --git a/org.tizen.guides/html/images/icon_apps.png b/org.tizen.ui.guides/html/images/icon_apps.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon_apps.png rename to org.tizen.ui.guides/html/images/icon_apps.png diff --git a/org.tizen.guides/html/images/icon_arrowdown.png b/org.tizen.ui.guides/html/images/icon_arrowdown.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon_arrowdown.png rename to org.tizen.ui.guides/html/images/icon_arrowdown.png diff --git a/org.tizen.guides/html/images/icon_arrowleft.png b/org.tizen.ui.guides/html/images/icon_arrowleft.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon_arrowleft.png rename to org.tizen.ui.guides/html/images/icon_arrowleft.png diff --git a/org.tizen.guides/html/images/icon_arrowright.png b/org.tizen.ui.guides/html/images/icon_arrowright.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon_arrowright.png rename to org.tizen.ui.guides/html/images/icon_arrowright.png diff --git a/org.tizen.guides/html/images/icon_arrowup.png b/org.tizen.ui.guides/html/images/icon_arrowup.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon_arrowup.png rename to org.tizen.ui.guides/html/images/icon_arrowup.png diff --git a/org.tizen.guides/html/images/icon_chat.png b/org.tizen.ui.guides/html/images/icon_chat.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon_chat.png rename to org.tizen.ui.guides/html/images/icon_chat.png diff --git a/org.tizen.guides/html/images/icon_clock.png b/org.tizen.ui.guides/html/images/icon_clock.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon_clock.png rename to org.tizen.ui.guides/html/images/icon_clock.png diff --git a/org.tizen.guides/html/images/icon_close.png b/org.tizen.ui.guides/html/images/icon_close.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon_close.png rename to org.tizen.ui.guides/html/images/icon_close.png diff --git a/org.tizen.guides/html/images/icon_delete.png b/org.tizen.ui.guides/html/images/icon_delete.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon_delete.png rename to org.tizen.ui.guides/html/images/icon_delete.png diff --git a/org.tizen.guides/html/images/icon_edit.png b/org.tizen.ui.guides/html/images/icon_edit.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon_edit.png rename to org.tizen.ui.guides/html/images/icon_edit.png diff --git a/org.tizen.guides/html/images/icon_file.png b/org.tizen.ui.guides/html/images/icon_file.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon_file.png rename to org.tizen.ui.guides/html/images/icon_file.png diff --git a/org.tizen.guides/html/images/icon_forward.png b/org.tizen.ui.guides/html/images/icon_forward.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon_forward.png rename to org.tizen.ui.guides/html/images/icon_forward.png diff --git a/org.tizen.guides/html/images/icon_home.png b/org.tizen.ui.guides/html/images/icon_home.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon_home.png rename to org.tizen.ui.guides/html/images/icon_home.png diff --git a/org.tizen.guides/html/images/icon_info.png b/org.tizen.ui.guides/html/images/icon_info.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon_info.png rename to org.tizen.ui.guides/html/images/icon_info.png diff --git a/org.tizen.guides/html/images/icon_menu_apps.png b/org.tizen.ui.guides/html/images/icon_menu_apps.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon_menu_apps.png rename to org.tizen.ui.guides/html/images/icon_menu_apps.png diff --git a/org.tizen.guides/html/images/icon_menu_arrdown.png b/org.tizen.ui.guides/html/images/icon_menu_arrdown.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon_menu_arrdown.png rename to org.tizen.ui.guides/html/images/icon_menu_arrdown.png diff --git a/org.tizen.guides/html/images/icon_menu_arrleft.png b/org.tizen.ui.guides/html/images/icon_menu_arrleft.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon_menu_arrleft.png rename to org.tizen.ui.guides/html/images/icon_menu_arrleft.png diff --git a/org.tizen.guides/html/images/icon_menu_arrright.png b/org.tizen.ui.guides/html/images/icon_menu_arrright.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon_menu_arrright.png rename to org.tizen.ui.guides/html/images/icon_menu_arrright.png diff --git a/org.tizen.guides/html/images/icon_menu_arrup.png b/org.tizen.ui.guides/html/images/icon_menu_arrup.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon_menu_arrup.png rename to org.tizen.ui.guides/html/images/icon_menu_arrup.png diff --git a/org.tizen.guides/html/images/icon_menu_chat.png b/org.tizen.ui.guides/html/images/icon_menu_chat.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon_menu_chat.png rename to org.tizen.ui.guides/html/images/icon_menu_chat.png diff --git a/org.tizen.guides/html/images/icon_menu_clock.png b/org.tizen.ui.guides/html/images/icon_menu_clock.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon_menu_clock.png rename to org.tizen.ui.guides/html/images/icon_menu_clock.png diff --git a/org.tizen.guides/html/images/icon_menu_close.png b/org.tizen.ui.guides/html/images/icon_menu_close.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon_menu_close.png rename to org.tizen.ui.guides/html/images/icon_menu_close.png diff --git a/org.tizen.guides/html/images/icon_menu_delete.png b/org.tizen.ui.guides/html/images/icon_menu_delete.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon_menu_delete.png rename to org.tizen.ui.guides/html/images/icon_menu_delete.png diff --git a/org.tizen.guides/html/images/icon_menu_edit.png b/org.tizen.ui.guides/html/images/icon_menu_edit.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon_menu_edit.png rename to org.tizen.ui.guides/html/images/icon_menu_edit.png diff --git a/org.tizen.guides/html/images/icon_menu_file.png b/org.tizen.ui.guides/html/images/icon_menu_file.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon_menu_file.png rename to org.tizen.ui.guides/html/images/icon_menu_file.png diff --git a/org.tizen.guides/html/images/icon_menu_folder.png b/org.tizen.ui.guides/html/images/icon_menu_folder.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon_menu_folder.png rename to org.tizen.ui.guides/html/images/icon_menu_folder.png diff --git a/org.tizen.guides/html/images/icon_menu_home.png b/org.tizen.ui.guides/html/images/icon_menu_home.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon_menu_home.png rename to org.tizen.ui.guides/html/images/icon_menu_home.png diff --git a/org.tizen.guides/html/images/icon_menu_nophoto.png b/org.tizen.ui.guides/html/images/icon_menu_nophoto.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon_menu_nophoto.png rename to org.tizen.ui.guides/html/images/icon_menu_nophoto.png diff --git a/org.tizen.guides/html/images/icon_menu_refresh.png b/org.tizen.ui.guides/html/images/icon_menu_refresh.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon_menu_refresh.png rename to org.tizen.ui.guides/html/images/icon_menu_refresh.png diff --git a/org.tizen.guides/html/images/icon_next.png b/org.tizen.ui.guides/html/images/icon_next.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon_next.png rename to org.tizen.ui.guides/html/images/icon_next.png diff --git a/org.tizen.guides/html/images/icon_pause.png b/org.tizen.ui.guides/html/images/icon_pause.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon_pause.png rename to org.tizen.ui.guides/html/images/icon_pause.png diff --git a/org.tizen.guides/html/images/icon_photo_nophoto.png b/org.tizen.ui.guides/html/images/icon_photo_nophoto.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon_photo_nophoto.png rename to org.tizen.ui.guides/html/images/icon_photo_nophoto.png diff --git a/org.tizen.guides/html/images/icon_play.png b/org.tizen.ui.guides/html/images/icon_play.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon_play.png rename to org.tizen.ui.guides/html/images/icon_play.png diff --git a/org.tizen.guides/html/images/icon_prev.png b/org.tizen.ui.guides/html/images/icon_prev.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon_prev.png rename to org.tizen.ui.guides/html/images/icon_prev.png diff --git a/org.tizen.guides/html/images/icon_refresh.png b/org.tizen.ui.guides/html/images/icon_refresh.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon_refresh.png rename to org.tizen.ui.guides/html/images/icon_refresh.png diff --git a/org.tizen.guides/html/images/icon_rewind.png b/org.tizen.ui.guides/html/images/icon_rewind.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon_rewind.png rename to org.tizen.ui.guides/html/images/icon_rewind.png diff --git a/org.tizen.guides/html/images/icon_stop.png b/org.tizen.ui.guides/html/images/icon_stop.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon_stop.png rename to org.tizen.ui.guides/html/images/icon_stop.png diff --git a/org.tizen.guides/html/images/icon_toolbar_apps.png b/org.tizen.ui.guides/html/images/icon_toolbar_apps.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon_toolbar_apps.png rename to org.tizen.ui.guides/html/images/icon_toolbar_apps.png diff --git a/org.tizen.guides/html/images/icon_toolbar_arrdown.png b/org.tizen.ui.guides/html/images/icon_toolbar_arrdown.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon_toolbar_arrdown.png rename to org.tizen.ui.guides/html/images/icon_toolbar_arrdown.png diff --git a/org.tizen.guides/html/images/icon_toolbar_arrleft.png b/org.tizen.ui.guides/html/images/icon_toolbar_arrleft.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon_toolbar_arrleft.png rename to org.tizen.ui.guides/html/images/icon_toolbar_arrleft.png diff --git a/org.tizen.guides/html/images/icon_toolbar_arrright.png b/org.tizen.ui.guides/html/images/icon_toolbar_arrright.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon_toolbar_arrright.png rename to org.tizen.ui.guides/html/images/icon_toolbar_arrright.png diff --git a/org.tizen.guides/html/images/icon_toolbar_arrup.png b/org.tizen.ui.guides/html/images/icon_toolbar_arrup.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon_toolbar_arrup.png rename to org.tizen.ui.guides/html/images/icon_toolbar_arrup.png diff --git a/org.tizen.guides/html/images/icon_toolbar_chat.png b/org.tizen.ui.guides/html/images/icon_toolbar_chat.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon_toolbar_chat.png rename to org.tizen.ui.guides/html/images/icon_toolbar_chat.png diff --git a/org.tizen.guides/html/images/icon_toolbar_clock.png b/org.tizen.ui.guides/html/images/icon_toolbar_clock.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon_toolbar_clock.png rename to org.tizen.ui.guides/html/images/icon_toolbar_clock.png diff --git a/org.tizen.guides/html/images/icon_toolbar_close.png b/org.tizen.ui.guides/html/images/icon_toolbar_close.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon_toolbar_close.png rename to org.tizen.ui.guides/html/images/icon_toolbar_close.png diff --git a/org.tizen.guides/html/images/icon_toolbar_delete.png b/org.tizen.ui.guides/html/images/icon_toolbar_delete.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon_toolbar_delete.png rename to org.tizen.ui.guides/html/images/icon_toolbar_delete.png diff --git a/org.tizen.guides/html/images/icon_toolbar_edit.png b/org.tizen.ui.guides/html/images/icon_toolbar_edit.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon_toolbar_edit.png rename to org.tizen.ui.guides/html/images/icon_toolbar_edit.png diff --git a/org.tizen.guides/html/images/icon_toolbar_file.png b/org.tizen.ui.guides/html/images/icon_toolbar_file.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon_toolbar_file.png rename to org.tizen.ui.guides/html/images/icon_toolbar_file.png diff --git a/org.tizen.guides/html/images/icon_toolbar_folder.png b/org.tizen.ui.guides/html/images/icon_toolbar_folder.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon_toolbar_folder.png rename to org.tizen.ui.guides/html/images/icon_toolbar_folder.png diff --git a/org.tizen.guides/html/images/icon_toolbar_moremenu.png b/org.tizen.ui.guides/html/images/icon_toolbar_moremenu.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon_toolbar_moremenu.png rename to org.tizen.ui.guides/html/images/icon_toolbar_moremenu.png diff --git a/org.tizen.guides/html/images/icon_toolbar_refresh.png b/org.tizen.ui.guides/html/images/icon_toolbar_refresh.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon_toolbar_refresh.png rename to org.tizen.ui.guides/html/images/icon_toolbar_refresh.png diff --git a/org.tizen.guides/html/images/icon_tree.png b/org.tizen.ui.guides/html/images/icon_tree.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/icon_tree.png rename to org.tizen.ui.guides/html/images/icon_tree.png diff --git a/org.tizen.guides/html/images/idlers.png b/org.tizen.ui.guides/html/images/idlers.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/idlers.png rename to org.tizen.ui.guides/html/images/idlers.png diff --git a/org.tizen.guides/html/images/image.png b/org.tizen.ui.guides/html/images/image.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/image.png rename to org.tizen.ui.guides/html/images/image.png diff --git a/org.tizen.tutorials/html/images/image_after.png b/org.tizen.ui.guides/html/images/image_after.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.tutorials/html/images/image_after.png rename to org.tizen.ui.guides/html/images/image_after.png diff --git a/org.tizen.tutorials/html/images/image_before.png b/org.tizen.ui.guides/html/images/image_before.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.tutorials/html/images/image_before.png rename to org.tizen.ui.guides/html/images/image_before.png diff --git a/org.tizen.guides/html/images/image_tree.png b/org.tizen.ui.guides/html/images/image_tree.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/image_tree.png rename to org.tizen.ui.guides/html/images/image_tree.png diff --git a/org.tizen.guides/html/images/image_wn.png b/org.tizen.ui.guides/html/images/image_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/image_wn.png rename to org.tizen.ui.guides/html/images/image_wn.png diff --git a/org.tizen.guides/html/images/immediate_mode.png b/org.tizen.ui.guides/html/images/immediate_mode.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/immediate_mode.png rename to org.tizen.ui.guides/html/images/immediate_mode.png diff --git a/org.tizen.guides/html/images/import_css_area.png b/org.tizen.ui.guides/html/images/import_css_area.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/import_css_area.png rename to org.tizen.ui.guides/html/images/import_css_area.png diff --git a/org.tizen.guides/html/images/import_linked_in_head.png b/org.tizen.ui.guides/html/images/import_linked_in_head.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/import_linked_in_head.png rename to org.tizen.ui.guides/html/images/import_linked_in_head.png diff --git a/org.tizen.guides/html/images/index.png b/org.tizen.ui.guides/html/images/index.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/index.png rename to org.tizen.ui.guides/html/images/index.png diff --git a/org.tizen.guides/html/images/index_circle_o_wn.png b/org.tizen.ui.guides/html/images/index_circle_o_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/index_circle_o_wn.png rename to org.tizen.ui.guides/html/images/index_circle_o_wn.png diff --git a/org.tizen.guides/html/images/index_default.png b/org.tizen.ui.guides/html/images/index_default.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/index_default.png rename to org.tizen.ui.guides/html/images/index_default.png diff --git a/org.tizen.guides/html/images/index_default02.png b/org.tizen.ui.guides/html/images/index_default02.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/index_default02.png rename to org.tizen.ui.guides/html/images/index_default02.png diff --git a/org.tizen.guides/html/images/index_pagecontrol.png b/org.tizen.ui.guides/html/images/index_pagecontrol.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/index_pagecontrol.png rename to org.tizen.ui.guides/html/images/index_pagecontrol.png diff --git a/org.tizen.guides/html/images/index_tab_wn.png b/org.tizen.ui.guides/html/images/index_tab_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/index_tab_wn.png rename to org.tizen.ui.guides/html/images/index_tab_wn.png diff --git a/org.tizen.guides/html/images/index_thumb_o_wn.png b/org.tizen.ui.guides/html/images/index_thumb_o_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/index_thumb_o_wn.png rename to org.tizen.ui.guides/html/images/index_thumb_o_wn.png diff --git a/org.tizen.guides/html/images/index_thumb_wn.png b/org.tizen.ui.guides/html/images/index_thumb_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/index_thumb_wn.png rename to org.tizen.ui.guides/html/images/index_thumb_wn.png diff --git a/org.tizen.guides/html/images/index_tree.png b/org.tizen.ui.guides/html/images/index_tree.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/index_tree.png rename to org.tizen.ui.guides/html/images/index_tree.png diff --git a/org.tizen.guides/html/images/index_wn.png b/org.tizen.ui.guides/html/images/index_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/index_wn.png rename to org.tizen.ui.guides/html/images/index_wn.png diff --git a/org.tizen.guides/html/images/label.png b/org.tizen.ui.guides/html/images/label.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/label.png rename to org.tizen.ui.guides/html/images/label.png diff --git a/org.tizen.guides/html/images/label_tree.png b/org.tizen.ui.guides/html/images/label_tree.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/label_tree.png rename to org.tizen.ui.guides/html/images/label_tree.png diff --git a/org.tizen.guides/html/images/label_wn.png b/org.tizen.ui.guides/html/images/label_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/label_wn.png rename to org.tizen.ui.guides/html/images/label_wn.png diff --git a/org.tizen.guides/html/images/layout_app.png b/org.tizen.ui.guides/html/images/layout_app.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/layout_app.png rename to org.tizen.ui.guides/html/images/layout_app.png diff --git a/org.tizen.guides/html/images/layout_calculator.png b/org.tizen.ui.guides/html/images/layout_calculator.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/layout_calculator.png rename to org.tizen.ui.guides/html/images/layout_calculator.png diff --git a/org.tizen.guides/html/images/layout_calculator_absolute.png b/org.tizen.ui.guides/html/images/layout_calculator_absolute.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/layout_calculator_absolute.png rename to org.tizen.ui.guides/html/images/layout_calculator_absolute.png diff --git a/org.tizen.guides/html/images/layout_calculator_relative.png b/org.tizen.ui.guides/html/images/layout_calculator_relative.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/layout_calculator_relative.png rename to org.tizen.ui.guides/html/images/layout_calculator_relative.png diff --git a/org.tizen.guides/html/images/layout_fixed_media.png b/org.tizen.ui.guides/html/images/layout_fixed_media.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/layout_fixed_media.png rename to org.tizen.ui.guides/html/images/layout_fixed_media.png diff --git a/org.tizen.guides/html/images/layout_flexible_media.png b/org.tizen.ui.guides/html/images/layout_flexible_media.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/layout_flexible_media.png rename to org.tizen.ui.guides/html/images/layout_flexible_media.png diff --git a/org.tizen.guides/html/images/layout_image.png b/org.tizen.ui.guides/html/images/layout_image.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/layout_image.png rename to org.tizen.ui.guides/html/images/layout_image.png diff --git a/org.tizen.guides/html/images/layout_image_scaled.png b/org.tizen.ui.guides/html/images/layout_image_scaled.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/layout_image_scaled.png rename to org.tizen.ui.guides/html/images/layout_image_scaled.png diff --git a/org.tizen.guides/html/images/layout_original.png b/org.tizen.ui.guides/html/images/layout_original.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/layout_original.png rename to org.tizen.ui.guides/html/images/layout_original.png diff --git a/org.tizen.guides/html/images/layout_original_scaled.png b/org.tizen.ui.guides/html/images/layout_original_scaled.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/layout_original_scaled.png rename to org.tizen.ui.guides/html/images/layout_original_scaled.png diff --git a/org.tizen.guides/html/images/layout_sample.png b/org.tizen.ui.guides/html/images/layout_sample.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/layout_sample.png rename to org.tizen.ui.guides/html/images/layout_sample.png diff --git a/org.tizen.guides/html/images/layout_sample_ok.png b/org.tizen.ui.guides/html/images/layout_sample_ok.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/layout_sample_ok.png rename to org.tizen.ui.guides/html/images/layout_sample_ok.png diff --git a/org.tizen.guides/html/images/layout_sample_ugly.png b/org.tizen.ui.guides/html/images/layout_sample_ugly.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/layout_sample_ugly.png rename to org.tizen.ui.guides/html/images/layout_sample_ugly.png diff --git a/org.tizen.guides/html/images/list.png b/org.tizen.ui.guides/html/images/list.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/list.png rename to org.tizen.ui.guides/html/images/list.png diff --git a/org.tizen.guides/html/images/list_tree.png b/org.tizen.ui.guides/html/images/list_tree.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/list_tree.png rename to org.tizen.ui.guides/html/images/list_tree.png diff --git a/org.tizen.guides/html/images/list_wn.png b/org.tizen.ui.guides/html/images/list_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/list_wn.png rename to org.tizen.ui.guides/html/images/list_wn.png diff --git a/org.tizen.ui.guides/html/images/main_app_layout.png b/org.tizen.ui.guides/html/images/main_app_layout.png new file mode 100755 index 0000000..5ea87a5 Binary files /dev/null and b/org.tizen.ui.guides/html/images/main_app_layout.png differ diff --git a/org.tizen.guides/html/images/map_tree.png b/org.tizen.ui.guides/html/images/map_tree.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/map_tree.png rename to org.tizen.ui.guides/html/images/map_tree.png diff --git a/org.tizen.guides/html/images/mapbuf_tree.png b/org.tizen.ui.guides/html/images/mapbuf_tree.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/mapbuf_tree.png rename to org.tizen.ui.guides/html/images/mapbuf_tree.png diff --git a/org.tizen.guides/html/images/mascot.gif b/org.tizen.ui.guides/html/images/mascot.gif old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/mascot.gif rename to org.tizen.ui.guides/html/images/mascot.gif diff --git a/org.tizen.tutorials/html/images/media_queries1.png b/org.tizen.ui.guides/html/images/media_queries1.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.tutorials/html/images/media_queries1.png rename to org.tizen.ui.guides/html/images/media_queries1.png diff --git a/org.tizen.tutorials/html/images/media_queries3.png b/org.tizen.ui.guides/html/images/media_queries3.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.tutorials/html/images/media_queries3.png rename to org.tizen.ui.guides/html/images/media_queries3.png diff --git a/org.tizen.guides/html/images/memory.png b/org.tizen.ui.guides/html/images/memory.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/memory.png rename to org.tizen.ui.guides/html/images/memory.png diff --git a/org.tizen.guides/html/images/memory2.png b/org.tizen.ui.guides/html/images/memory2.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/memory2.png rename to org.tizen.ui.guides/html/images/memory2.png diff --git a/org.tizen.guides/html/images/memory3.png b/org.tizen.ui.guides/html/images/memory3.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/memory3.png rename to org.tizen.ui.guides/html/images/memory3.png diff --git a/org.tizen.tutorials/html/images/memory_using_css3.png b/org.tizen.ui.guides/html/images/memory_using_css3.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.tutorials/html/images/memory_using_css3.png rename to org.tizen.ui.guides/html/images/memory_using_css3.png diff --git a/org.tizen.tutorials/html/images/memory_using_javascript.png b/org.tizen.ui.guides/html/images/memory_using_javascript.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.tutorials/html/images/memory_using_javascript.png rename to org.tizen.ui.guides/html/images/memory_using_javascript.png diff --git a/org.tizen.tutorials/html/images/menu_skeleton.png b/org.tizen.ui.guides/html/images/menu_skeleton.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.tutorials/html/images/menu_skeleton.png rename to org.tizen.ui.guides/html/images/menu_skeleton.png diff --git a/org.tizen.guides/html/images/migrate_move_to_top.png b/org.tizen.ui.guides/html/images/migrate_move_to_top.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/migrate_move_to_top.png rename to org.tizen.ui.guides/html/images/migrate_move_to_top.png diff --git a/org.tizen.guides/html/images/migrate_padding.png b/org.tizen.ui.guides/html/images/migrate_padding.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/migrate_padding.png rename to org.tizen.ui.guides/html/images/migrate_padding.png diff --git a/org.tizen.guides/html/images/migrate_scrollable_circle.png b/org.tizen.ui.guides/html/images/migrate_scrollable_circle.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/migrate_scrollable_circle.png rename to org.tizen.ui.guides/html/images/migrate_scrollable_circle.png diff --git a/org.tizen.guides/html/images/migrate_scrollable_rect.png b/org.tizen.ui.guides/html/images/migrate_scrollable_rect.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/migrate_scrollable_rect.png rename to org.tizen.ui.guides/html/images/migrate_scrollable_rect.png diff --git a/org.tizen.ui.guides/html/images/mn_division.png b/org.tizen.ui.guides/html/images/mn_division.png new file mode 100755 index 0000000..1f7e337 Binary files /dev/null and b/org.tizen.ui.guides/html/images/mn_division.png differ diff --git a/org.tizen.ui.guides/html/images/mn_icon.png b/org.tizen.ui.guides/html/images/mn_icon.png new file mode 100755 index 0000000..19a0fd3 Binary files /dev/null and b/org.tizen.ui.guides/html/images/mn_icon.png differ diff --git a/org.tizen.ui.guides/html/images/moving1.png b/org.tizen.ui.guides/html/images/moving1.png new file mode 100755 index 0000000..0aed153 Binary files /dev/null and b/org.tizen.ui.guides/html/images/moving1.png differ diff --git a/org.tizen.ui.guides/html/images/moving2.png b/org.tizen.ui.guides/html/images/moving2.png new file mode 100755 index 0000000..cc92469 Binary files /dev/null and b/org.tizen.ui.guides/html/images/moving2.png differ diff --git a/org.tizen.guides/html/images/multi_button_default.png b/org.tizen.ui.guides/html/images/multi_button_default.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/multi_button_default.png rename to org.tizen.ui.guides/html/images/multi_button_default.png diff --git a/org.tizen.ui.guides/html/images/multi_threading.png b/org.tizen.ui.guides/html/images/multi_threading.png new file mode 100755 index 0000000..2d481f1 Binary files /dev/null and b/org.tizen.ui.guides/html/images/multi_threading.png differ diff --git a/org.tizen.ui.guides/html/images/multi_threading2.png b/org.tizen.ui.guides/html/images/multi_threading2.png new file mode 100755 index 0000000..ebe0bef Binary files /dev/null and b/org.tizen.ui.guides/html/images/multi_threading2.png differ diff --git a/org.tizen.guides/html/images/multiple_layout_example.png b/org.tizen.ui.guides/html/images/multiple_layout_example.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/multiple_layout_example.png rename to org.tizen.ui.guides/html/images/multiple_layout_example.png diff --git a/org.tizen.tutorials/html/images/multipoint_touch.png b/org.tizen.ui.guides/html/images/multipoint_touch.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.tutorials/html/images/multipoint_touch.png rename to org.tizen.ui.guides/html/images/multipoint_touch.png diff --git a/org.tizen.ui.guides/html/images/mw_division.png b/org.tizen.ui.guides/html/images/mw_division.png new file mode 100755 index 0000000..8fc3efa Binary files /dev/null and b/org.tizen.ui.guides/html/images/mw_division.png differ diff --git a/org.tizen.ui.guides/html/images/mw_icon.png b/org.tizen.ui.guides/html/images/mw_icon.png new file mode 100755 index 0000000..a089898 Binary files /dev/null and b/org.tizen.ui.guides/html/images/mw_icon.png differ diff --git a/org.tizen.ui.guides/html/images/mw_icon_optional.png b/org.tizen.ui.guides/html/images/mw_icon_optional.png new file mode 100755 index 0000000..4fbf95b Binary files /dev/null and b/org.tizen.ui.guides/html/images/mw_icon_optional.png differ diff --git a/org.tizen.ui.guides/html/images/n_division.png b/org.tizen.ui.guides/html/images/n_division.png new file mode 100755 index 0000000..d687bc5 Binary files /dev/null and b/org.tizen.ui.guides/html/images/n_division.png differ diff --git a/org.tizen.guides/html/images/network.png b/org.tizen.ui.guides/html/images/network.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/network.png rename to org.tizen.ui.guides/html/images/network.png diff --git a/org.tizen.guides/html/images/network2.png b/org.tizen.ui.guides/html/images/network2.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/network2.png rename to org.tizen.ui.guides/html/images/network2.png diff --git a/org.tizen.guides/html/images/network3.png b/org.tizen.ui.guides/html/images/network3.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/network3.png rename to org.tizen.ui.guides/html/images/network3.png diff --git a/org.tizen.guides/html/images/network_speed_sprite.png b/org.tizen.ui.guides/html/images/network_speed_sprite.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/network_speed_sprite.png rename to org.tizen.ui.guides/html/images/network_speed_sprite.png diff --git a/org.tizen.guides/html/images/notify_tree.png b/org.tizen.ui.guides/html/images/notify_tree.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/notify_tree.png rename to org.tizen.ui.guides/html/images/notify_tree.png diff --git a/org.tizen.ui.guides/html/images/object_size_16.png b/org.tizen.ui.guides/html/images/object_size_16.png new file mode 100755 index 0000000..1e560bd Binary files /dev/null and b/org.tizen.ui.guides/html/images/object_size_16.png differ diff --git a/org.tizen.ui.guides/html/images/object_size_22.png b/org.tizen.ui.guides/html/images/object_size_22.png new file mode 100755 index 0000000..34e86ed Binary files /dev/null and b/org.tizen.ui.guides/html/images/object_size_22.png differ diff --git a/org.tizen.ui.guides/html/images/object_size_44.png b/org.tizen.ui.guides/html/images/object_size_44.png new file mode 100755 index 0000000..2512226 Binary files /dev/null and b/org.tizen.ui.guides/html/images/object_size_44.png differ diff --git a/org.tizen.ui.guides/html/images/padding-hints.png b/org.tizen.ui.guides/html/images/padding-hints.png new file mode 100755 index 0000000..3f29fae Binary files /dev/null and b/org.tizen.ui.guides/html/images/padding-hints.png differ diff --git a/org.tizen.tutorials/html/images/pane_tuto.png b/org.tizen.ui.guides/html/images/pane_tuto.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.tutorials/html/images/pane_tuto.png rename to org.tizen.ui.guides/html/images/pane_tuto.png diff --git a/org.tizen.guides/html/images/panel_default.png b/org.tizen.ui.guides/html/images/panel_default.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/panel_default.png rename to org.tizen.ui.guides/html/images/panel_default.png diff --git a/org.tizen.guides/html/images/panel_tree.png b/org.tizen.ui.guides/html/images/panel_tree.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/panel_tree.png rename to org.tizen.ui.guides/html/images/panel_tree.png diff --git a/org.tizen.guides/html/images/panes.png b/org.tizen.ui.guides/html/images/panes.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/panes.png rename to org.tizen.ui.guides/html/images/panes.png diff --git a/org.tizen.ui.guides/html/images/parent_origin.png b/org.tizen.ui.guides/html/images/parent_origin.png new file mode 100755 index 0000000..0317fe4 Binary files /dev/null and b/org.tizen.ui.guides/html/images/parent_origin.png differ diff --git a/org.tizen.ui.guides/html/images/path_animation.png b/org.tizen.ui.guides/html/images/path_animation.png new file mode 100755 index 0000000..0a2ca2e Binary files /dev/null and b/org.tizen.ui.guides/html/images/path_animation.png differ diff --git a/org.tizen.ui.guides/html/images/perspective_buttons.png b/org.tizen.ui.guides/html/images/perspective_buttons.png new file mode 100755 index 0000000..60c4fcc Binary files /dev/null and b/org.tizen.ui.guides/html/images/perspective_buttons.png differ diff --git a/org.tizen.ui.guides/html/images/perspective_screen.png b/org.tizen.ui.guides/html/images/perspective_screen.png new file mode 100755 index 0000000..f761980 Binary files /dev/null and b/org.tizen.ui.guides/html/images/perspective_screen.png differ diff --git a/org.tizen.ui.guides/html/images/perspective_swallow.png b/org.tizen.ui.guides/html/images/perspective_swallow.png new file mode 100755 index 0000000..298bf9b Binary files /dev/null and b/org.tizen.ui.guides/html/images/perspective_swallow.png differ diff --git a/org.tizen.guides/html/images/photo_tree.png b/org.tizen.ui.guides/html/images/photo_tree.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/photo_tree.png rename to org.tizen.ui.guides/html/images/photo_tree.png diff --git a/org.tizen.guides/html/images/photocam_tree.png b/org.tizen.ui.guides/html/images/photocam_tree.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/photocam_tree.png rename to org.tizen.ui.guides/html/images/photocam_tree.png diff --git a/org.tizen.guides/html/images/plug_tree.png b/org.tizen.ui.guides/html/images/plug_tree.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/plug_tree.png rename to org.tizen.ui.guides/html/images/plug_tree.png diff --git a/org.tizen.guides/html/images/popup.png b/org.tizen.ui.guides/html/images/popup.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/popup.png rename to org.tizen.ui.guides/html/images/popup.png diff --git a/org.tizen.guides/html/images/popup_circle_o_wn.png b/org.tizen.ui.guides/html/images/popup_circle_o_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/popup_circle_o_wn.png rename to org.tizen.ui.guides/html/images/popup_circle_o_wn.png diff --git a/org.tizen.guides/html/images/popup_default.png b/org.tizen.ui.guides/html/images/popup_default.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/popup_default.png rename to org.tizen.ui.guides/html/images/popup_default.png diff --git a/org.tizen.guides/html/images/popup_default_wn.png b/org.tizen.ui.guides/html/images/popup_default_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/popup_default_wn.png rename to org.tizen.ui.guides/html/images/popup_default_wn.png diff --git a/org.tizen.guides/html/images/popup_toast.png b/org.tizen.ui.guides/html/images/popup_toast.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/popup_toast.png rename to org.tizen.ui.guides/html/images/popup_toast.png diff --git a/org.tizen.guides/html/images/popup_toast_o_wn.png b/org.tizen.ui.guides/html/images/popup_toast_o_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/popup_toast_o_wn.png rename to org.tizen.ui.guides/html/images/popup_toast_o_wn.png diff --git a/org.tizen.guides/html/images/popup_toast_wn.png b/org.tizen.ui.guides/html/images/popup_toast_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/popup_toast_wn.png rename to org.tizen.ui.guides/html/images/popup_toast_wn.png diff --git a/org.tizen.guides/html/images/popup_tree.png b/org.tizen.ui.guides/html/images/popup_tree.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/popup_tree.png rename to org.tizen.ui.guides/html/images/popup_tree.png diff --git a/org.tizen.guides/html/images/popup_wn.png b/org.tizen.ui.guides/html/images/popup_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/popup_wn.png rename to org.tizen.ui.guides/html/images/popup_wn.png diff --git a/org.tizen.guides/html/images/pos_map_all.png b/org.tizen.ui.guides/html/images/pos_map_all.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/pos_map_all.png rename to org.tizen.ui.guides/html/images/pos_map_all.png diff --git a/org.tizen.guides/html/images/progressbar.png b/org.tizen.ui.guides/html/images/progressbar.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/progressbar.png rename to org.tizen.ui.guides/html/images/progressbar.png diff --git a/org.tizen.guides/html/images/progressbar_default.png b/org.tizen.ui.guides/html/images/progressbar_default.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/progressbar_default.png rename to org.tizen.ui.guides/html/images/progressbar_default.png diff --git a/org.tizen.guides/html/images/progressbar_default_wn.png b/org.tizen.ui.guides/html/images/progressbar_default_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/progressbar_default_wn.png rename to org.tizen.ui.guides/html/images/progressbar_default_wn.png diff --git a/org.tizen.guides/html/images/progressbar_group_wn.png b/org.tizen.ui.guides/html/images/progressbar_group_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/progressbar_group_wn.png rename to org.tizen.ui.guides/html/images/progressbar_group_wn.png diff --git a/org.tizen.guides/html/images/progressbar_pending_wn.png b/org.tizen.ui.guides/html/images/progressbar_pending_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/progressbar_pending_wn.png rename to org.tizen.ui.guides/html/images/progressbar_pending_wn.png diff --git a/org.tizen.guides/html/images/progressbar_process_o_wn.png b/org.tizen.ui.guides/html/images/progressbar_process_o_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/progressbar_process_o_wn.png rename to org.tizen.ui.guides/html/images/progressbar_process_o_wn.png diff --git a/org.tizen.guides/html/images/progressbar_process_wn.png b/org.tizen.ui.guides/html/images/progressbar_process_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/progressbar_process_wn.png rename to org.tizen.ui.guides/html/images/progressbar_process_wn.png diff --git a/org.tizen.guides/html/images/progressbar_small_o_wn.png b/org.tizen.ui.guides/html/images/progressbar_small_o_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/progressbar_small_o_wn.png rename to org.tizen.ui.guides/html/images/progressbar_small_o_wn.png diff --git a/org.tizen.guides/html/images/progressbar_tree.png b/org.tizen.ui.guides/html/images/progressbar_tree.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/progressbar_tree.png rename to org.tizen.ui.guides/html/images/progressbar_tree.png diff --git a/org.tizen.guides/html/images/progressbar_wheel.png b/org.tizen.ui.guides/html/images/progressbar_wheel.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/progressbar_wheel.png rename to org.tizen.ui.guides/html/images/progressbar_wheel.png diff --git a/org.tizen.guides/html/images/progressbar_wn.png b/org.tizen.ui.guides/html/images/progressbar_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/progressbar_wn.png rename to org.tizen.ui.guides/html/images/progressbar_wn.png diff --git a/org.tizen.tutorials/html/images/pseudo_elements_selector_range.png b/org.tizen.ui.guides/html/images/pseudo_elements_selector_range.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.tutorials/html/images/pseudo_elements_selector_range.png rename to org.tizen.ui.guides/html/images/pseudo_elements_selector_range.png diff --git a/org.tizen.tutorials/html/images/pseudo_elements_selector_required.png b/org.tizen.ui.guides/html/images/pseudo_elements_selector_required.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.tutorials/html/images/pseudo_elements_selector_required.png rename to org.tizen.ui.guides/html/images/pseudo_elements_selector_required.png diff --git a/org.tizen.ui.guides/html/images/push_button.png b/org.tizen.ui.guides/html/images/push_button.png new file mode 100755 index 0000000..08a8ef2 Binary files /dev/null and b/org.tizen.ui.guides/html/images/push_button.png differ diff --git a/org.tizen.guides/html/images/radio.png b/org.tizen.ui.guides/html/images/radio.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/radio.png rename to org.tizen.ui.guides/html/images/radio.png diff --git a/org.tizen.ui.guides/html/images/radio_button.png b/org.tizen.ui.guides/html/images/radio_button.png new file mode 100755 index 0000000..496adf3 Binary files /dev/null and b/org.tizen.ui.guides/html/images/radio_button.png differ diff --git a/org.tizen.guides/html/images/radio_default.png b/org.tizen.ui.guides/html/images/radio_default.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/radio_default.png rename to org.tizen.ui.guides/html/images/radio_default.png diff --git a/org.tizen.guides/html/images/radio_default_o_wn.png b/org.tizen.ui.guides/html/images/radio_default_o_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/radio_default_o_wn.png rename to org.tizen.ui.guides/html/images/radio_default_o_wn.png diff --git a/org.tizen.guides/html/images/radio_default_wn.png b/org.tizen.ui.guides/html/images/radio_default_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/radio_default_wn.png rename to org.tizen.ui.guides/html/images/radio_default_wn.png diff --git a/org.tizen.ui.guides/html/images/radio_state_changes.png b/org.tizen.ui.guides/html/images/radio_state_changes.png new file mode 100755 index 0000000..39cbffb Binary files /dev/null and b/org.tizen.ui.guides/html/images/radio_state_changes.png differ diff --git a/org.tizen.guides/html/images/radio_tree.png b/org.tizen.ui.guides/html/images/radio_tree.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/radio_tree.png rename to org.tizen.ui.guides/html/images/radio_tree.png diff --git a/org.tizen.guides/html/images/radio_wn.png b/org.tizen.ui.guides/html/images/radio_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/radio_wn.png rename to org.tizen.ui.guides/html/images/radio_wn.png diff --git a/org.tizen.guides/html/web/tizen/TAU/images/rectangular_footer.png b/org.tizen.ui.guides/html/images/rectangular_footer.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/web/tizen/TAU/images/rectangular_footer.png rename to org.tizen.ui.guides/html/images/rectangular_footer.png diff --git a/org.tizen.guides/html/web/tizen/TAU/images/rectangular_header.png b/org.tizen.ui.guides/html/images/rectangular_header.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/web/tizen/TAU/images/rectangular_header.png rename to org.tizen.ui.guides/html/images/rectangular_header.png diff --git a/org.tizen.guides/html/web/tizen/TAU/images/rectangular_snap.png b/org.tizen.ui.guides/html/images/rectangular_list.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/web/tizen/TAU/images/rectangular_snap.png rename to org.tizen.ui.guides/html/images/rectangular_list.png diff --git a/org.tizen.guides/html/web/tizen/TAU/images/rectangular_moreoption.png b/org.tizen.ui.guides/html/images/rectangular_moreoption.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/web/tizen/TAU/images/rectangular_moreoption.png rename to org.tizen.ui.guides/html/images/rectangular_moreoption.png diff --git a/org.tizen.guides/html/web/tizen/TAU/images/rectangular_multibtn.png b/org.tizen.ui.guides/html/images/rectangular_multibtn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/web/tizen/TAU/images/rectangular_multibtn.png rename to org.tizen.ui.guides/html/images/rectangular_multibtn.png diff --git a/org.tizen.guides/html/web/tizen/TAU/images/rectangular_popup_bottom.png b/org.tizen.ui.guides/html/images/rectangular_popup_bottom.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/web/tizen/TAU/images/rectangular_popup_bottom.png rename to org.tizen.ui.guides/html/images/rectangular_popup_bottom.png diff --git a/org.tizen.guides/html/web/tizen/TAU/images/rectangular_popup_side.png b/org.tizen.ui.guides/html/images/rectangular_popup_side.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/web/tizen/TAU/images/rectangular_popup_side.png rename to org.tizen.ui.guides/html/images/rectangular_popup_side.png diff --git a/org.tizen.guides/html/web/tizen/TAU/images/rectangular_processing.png b/org.tizen.ui.guides/html/images/rectangular_processing.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/web/tizen/TAU/images/rectangular_processing.png rename to org.tizen.ui.guides/html/images/rectangular_processing.png diff --git a/org.tizen.guides/html/web/tizen/TAU/images/rectangular_progress.png b/org.tizen.ui.guides/html/images/rectangular_progress.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/web/tizen/TAU/images/rectangular_progress.png rename to org.tizen.ui.guides/html/images/rectangular_progress.png diff --git a/org.tizen.guides/html/web/tizen/TAU/images/rectangular_thumbnail.png b/org.tizen.ui.guides/html/images/rectangular_thumbnail.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/web/tizen/TAU/images/rectangular_thumbnail.png rename to org.tizen.ui.guides/html/images/rectangular_thumbnail.png diff --git a/org.tizen.guides/html/images/redrawing01.png b/org.tizen.ui.guides/html/images/redrawing01.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/redrawing01.png rename to org.tizen.ui.guides/html/images/redrawing01.png diff --git a/org.tizen.guides/html/images/redrawing02.png b/org.tizen.ui.guides/html/images/redrawing02.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/redrawing02.png rename to org.tizen.ui.guides/html/images/redrawing02.png diff --git a/org.tizen.guides/html/images/redrawing03.png b/org.tizen.ui.guides/html/images/redrawing03.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/redrawing03.png rename to org.tizen.ui.guides/html/images/redrawing03.png diff --git a/org.tizen.guides/html/images/redrawing04.png b/org.tizen.ui.guides/html/images/redrawing04.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/redrawing04.png rename to org.tizen.ui.guides/html/images/redrawing04.png diff --git a/org.tizen.guides/html/images/redrawing05.png b/org.tizen.ui.guides/html/images/redrawing05.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/redrawing05.png rename to org.tizen.ui.guides/html/images/redrawing05.png diff --git a/org.tizen.ui.guides/html/images/rel1_rel2_offsets.png b/org.tizen.ui.guides/html/images/rel1_rel2_offsets.png new file mode 100755 index 0000000..bacdaab Binary files /dev/null and b/org.tizen.ui.guides/html/images/rel1_rel2_offsets.png differ diff --git a/org.tizen.ui.guides/html/images/rel1_rel2_offsets_and_relative.png b/org.tizen.ui.guides/html/images/rel1_rel2_offsets_and_relative.png new file mode 100755 index 0000000..51a9ec7 Binary files /dev/null and b/org.tizen.ui.guides/html/images/rel1_rel2_offsets_and_relative.png differ diff --git a/org.tizen.ui.guides/html/images/removing_padding.png b/org.tizen.ui.guides/html/images/removing_padding.png new file mode 100755 index 0000000..2a5dbfe Binary files /dev/null and b/org.tizen.ui.guides/html/images/removing_padding.png differ diff --git a/org.tizen.guides/html/images/rendering1.png b/org.tizen.ui.guides/html/images/rendering1.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/rendering1.png rename to org.tizen.ui.guides/html/images/rendering1.png diff --git a/org.tizen.guides/html/images/retained_mode.png b/org.tizen.ui.guides/html/images/retained_mode.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/retained_mode.png rename to org.tizen.ui.guides/html/images/retained_mode.png diff --git a/org.tizen.guides/html/images/rotary_event.png b/org.tizen.ui.guides/html/images/rotary_event.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/rotary_event.png rename to org.tizen.ui.guides/html/images/rotary_event.png diff --git a/org.tizen.guides/html/web/tizen/TAU/images/round_footer.png b/org.tizen.ui.guides/html/images/round_footer.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/web/tizen/TAU/images/round_footer.png rename to org.tizen.ui.guides/html/images/round_footer.png diff --git a/org.tizen.guides/html/web/tizen/TAU/images/round_header.png b/org.tizen.ui.guides/html/images/round_header.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/web/tizen/TAU/images/round_header.png rename to org.tizen.ui.guides/html/images/round_header.png diff --git a/org.tizen.guides/html/web/tizen/TAU/images/round_snap.png b/org.tizen.ui.guides/html/images/round_list.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/web/tizen/TAU/images/round_snap.png rename to org.tizen.ui.guides/html/images/round_list.png diff --git a/org.tizen.guides/html/web/tizen/TAU/images/round_moreoption.png b/org.tizen.ui.guides/html/images/round_moreoption.png similarity index 100% rename from org.tizen.guides/html/web/tizen/TAU/images/round_moreoption.png rename to org.tizen.ui.guides/html/images/round_moreoption.png diff --git a/org.tizen.guides/html/web/tizen/TAU/images/round_multibtn.png b/org.tizen.ui.guides/html/images/round_multibtn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/web/tizen/TAU/images/round_multibtn.png rename to org.tizen.ui.guides/html/images/round_multibtn.png diff --git a/org.tizen.guides/html/web/tizen/TAU/images/round_popup_bottom.png b/org.tizen.ui.guides/html/images/round_popup_bottom.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/web/tizen/TAU/images/round_popup_bottom.png rename to org.tizen.ui.guides/html/images/round_popup_bottom.png diff --git a/org.tizen.guides/html/web/tizen/TAU/images/round_popup_side.png b/org.tizen.ui.guides/html/images/round_popup_side.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/web/tizen/TAU/images/round_popup_side.png rename to org.tizen.ui.guides/html/images/round_popup_side.png diff --git a/org.tizen.guides/html/web/tizen/TAU/images/round_processing.png b/org.tizen.ui.guides/html/images/round_processing.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/web/tizen/TAU/images/round_processing.png rename to org.tizen.ui.guides/html/images/round_processing.png diff --git a/org.tizen.guides/html/web/tizen/TAU/images/round_progress.png b/org.tizen.ui.guides/html/images/round_progress.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/web/tizen/TAU/images/round_progress.png rename to org.tizen.ui.guides/html/images/round_progress.png diff --git a/org.tizen.guides/html/web/tizen/TAU/images/round_thumbnail.png b/org.tizen.ui.guides/html/images/round_thumbnail.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/web/tizen/TAU/images/round_thumbnail.png rename to org.tizen.ui.guides/html/images/round_thumbnail.png diff --git a/org.tizen.ui.guides/html/images/scalable_group1.png b/org.tizen.ui.guides/html/images/scalable_group1.png new file mode 100755 index 0000000..c9a6830 Binary files /dev/null and b/org.tizen.ui.guides/html/images/scalable_group1.png differ diff --git a/org.tizen.ui.guides/html/images/scalable_group2.png b/org.tizen.ui.guides/html/images/scalable_group2.png new file mode 100755 index 0000000..88a2d5f Binary files /dev/null and b/org.tizen.ui.guides/html/images/scalable_group2.png differ diff --git a/org.tizen.guides/html/images/scale.png b/org.tizen.ui.guides/html/images/scale.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/scale.png rename to org.tizen.ui.guides/html/images/scale.png diff --git a/org.tizen.guides/html/images/scale_1.3_finger_50.png b/org.tizen.ui.guides/html/images/scale_1.3_finger_50.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/scale_1.3_finger_50.png rename to org.tizen.ui.guides/html/images/scale_1.3_finger_50.png diff --git a/org.tizen.guides/html/images/scale_1_finger_50.png b/org.tizen.ui.guides/html/images/scale_1_finger_50.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/scale_1_finger_50.png rename to org.tizen.ui.guides/html/images/scale_1_finger_50.png diff --git a/org.tizen.guides/html/images/scale_1_finger_90.png b/org.tizen.ui.guides/html/images/scale_1_finger_90.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/scale_1_finger_90.png rename to org.tizen.ui.guides/html/images/scale_1_finger_90.png diff --git a/org.tizen.guides/html/images/scale_align_hint.png b/org.tizen.ui.guides/html/images/scale_align_hint.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/scale_align_hint.png rename to org.tizen.ui.guides/html/images/scale_align_hint.png diff --git a/org.tizen.guides/html/images/scale_box.png b/org.tizen.ui.guides/html/images/scale_box.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/scale_box.png rename to org.tizen.ui.guides/html/images/scale_box.png diff --git a/org.tizen.guides/html/images/scale_effect_1.png b/org.tizen.ui.guides/html/images/scale_effect_1.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/scale_effect_1.png rename to org.tizen.ui.guides/html/images/scale_effect_1.png diff --git a/org.tizen.guides/html/images/scale_effect_10.png b/org.tizen.ui.guides/html/images/scale_effect_10.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/scale_effect_10.png rename to org.tizen.ui.guides/html/images/scale_effect_10.png diff --git a/org.tizen.guides/html/images/scale_effect_2.png b/org.tizen.ui.guides/html/images/scale_effect_2.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/scale_effect_2.png rename to org.tizen.ui.guides/html/images/scale_effect_2.png diff --git a/org.tizen.guides/html/images/scale_effect_3.png b/org.tizen.ui.guides/html/images/scale_effect_3.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/scale_effect_3.png rename to org.tizen.ui.guides/html/images/scale_effect_3.png diff --git a/org.tizen.guides/html/images/scale_effect_4.png b/org.tizen.ui.guides/html/images/scale_effect_4.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/scale_effect_4.png rename to org.tizen.ui.guides/html/images/scale_effect_4.png diff --git a/org.tizen.guides/html/images/scale_effect_5.png b/org.tizen.ui.guides/html/images/scale_effect_5.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/scale_effect_5.png rename to org.tizen.ui.guides/html/images/scale_effect_5.png diff --git a/org.tizen.guides/html/images/scale_effect_6.png b/org.tizen.ui.guides/html/images/scale_effect_6.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/scale_effect_6.png rename to org.tizen.ui.guides/html/images/scale_effect_6.png diff --git a/org.tizen.guides/html/images/scale_effect_7.png b/org.tizen.ui.guides/html/images/scale_effect_7.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/scale_effect_7.png rename to org.tizen.ui.guides/html/images/scale_effect_7.png diff --git a/org.tizen.guides/html/images/scale_effect_8.png b/org.tizen.ui.guides/html/images/scale_effect_8.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/scale_effect_8.png rename to org.tizen.ui.guides/html/images/scale_effect_8.png diff --git a/org.tizen.guides/html/images/scale_effect_9.png b/org.tizen.ui.guides/html/images/scale_effect_9.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/scale_effect_9.png rename to org.tizen.ui.guides/html/images/scale_effect_9.png diff --git a/org.tizen.guides/html/images/scale_example_image.png b/org.tizen.ui.guides/html/images/scale_example_image.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/scale_example_image.png rename to org.tizen.ui.guides/html/images/scale_example_image.png diff --git a/org.tizen.guides/html/images/scale_example_image_set.png b/org.tizen.ui.guides/html/images/scale_example_image_set.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/scale_example_image_set.png rename to org.tizen.ui.guides/html/images/scale_example_image_set.png diff --git a/org.tizen.guides/html/images/scale_example_part.png b/org.tizen.ui.guides/html/images/scale_example_part.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/scale_example_part.png rename to org.tizen.ui.guides/html/images/scale_example_part.png diff --git a/org.tizen.guides/html/images/scale_example_part_aspect.png b/org.tizen.ui.guides/html/images/scale_example_part_aspect.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/scale_example_part_aspect.png rename to org.tizen.ui.guides/html/images/scale_example_part_aspect.png diff --git a/org.tizen.guides/html/images/scale_example_text.png b/org.tizen.ui.guides/html/images/scale_example_text.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/scale_example_text.png rename to org.tizen.ui.guides/html/images/scale_example_text.png diff --git a/org.tizen.guides/html/images/scale_example_text_fit.png b/org.tizen.ui.guides/html/images/scale_example_text_fit.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/scale_example_text_fit.png rename to org.tizen.ui.guides/html/images/scale_example_text_fit.png diff --git a/org.tizen.guides/html/images/scale_fixed.png b/org.tizen.ui.guides/html/images/scale_fixed.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/scale_fixed.png rename to org.tizen.ui.guides/html/images/scale_fixed.png diff --git a/org.tizen.guides/html/images/scale_fixed_flexible.png b/org.tizen.ui.guides/html/images/scale_fixed_flexible.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/scale_fixed_flexible.png rename to org.tizen.ui.guides/html/images/scale_fixed_flexible.png diff --git a/org.tizen.guides/html/images/scale_fixed_height.png b/org.tizen.ui.guides/html/images/scale_fixed_height.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/scale_fixed_height.png rename to org.tizen.ui.guides/html/images/scale_fixed_height.png diff --git a/org.tizen.guides/html/images/scale_flexible_height.png b/org.tizen.ui.guides/html/images/scale_flexible_height.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/scale_flexible_height.png rename to org.tizen.ui.guides/html/images/scale_flexible_height.png diff --git a/org.tizen.guides/html/images/scale_grid.png b/org.tizen.ui.guides/html/images/scale_grid.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/scale_grid.png rename to org.tizen.ui.guides/html/images/scale_grid.png diff --git a/org.tizen.guides/html/images/scale_original_image.png b/org.tizen.ui.guides/html/images/scale_original_image.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/scale_original_image.png rename to org.tizen.ui.guides/html/images/scale_original_image.png diff --git a/org.tizen.guides/html/images/scale_relative.png b/org.tizen.ui.guides/html/images/scale_relative.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/scale_relative.png rename to org.tizen.ui.guides/html/images/scale_relative.png diff --git a/org.tizen.guides/html/images/scale_relative_scaled.png b/org.tizen.ui.guides/html/images/scale_relative_scaled.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/scale_relative_scaled.png rename to org.tizen.ui.guides/html/images/scale_relative_scaled.png diff --git a/org.tizen.ui.guides/html/images/scale_testing_app.png b/org.tizen.ui.guides/html/images/scale_testing_app.png new file mode 100755 index 0000000..bd71b4f Binary files /dev/null and b/org.tizen.ui.guides/html/images/scale_testing_app.png differ diff --git a/org.tizen.ui.guides/html/images/scale_values.png b/org.tizen.ui.guides/html/images/scale_values.png new file mode 100755 index 0000000..84587f8 Binary files /dev/null and b/org.tizen.ui.guides/html/images/scale_values.png differ diff --git a/org.tizen.ui.guides/html/images/scale_values2.png b/org.tizen.ui.guides/html/images/scale_values2.png new file mode 100755 index 0000000..9770638 Binary files /dev/null and b/org.tizen.ui.guides/html/images/scale_values2.png differ diff --git a/org.tizen.guides/html/images/scale_weight_hint.png b/org.tizen.ui.guides/html/images/scale_weight_hint.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/scale_weight_hint.png rename to org.tizen.ui.guides/html/images/scale_weight_hint.png diff --git a/org.tizen.guides/html/images/scale_weight_hint_multiple.png b/org.tizen.ui.guides/html/images/scale_weight_hint_multiple.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/scale_weight_hint_multiple.png rename to org.tizen.ui.guides/html/images/scale_weight_hint_multiple.png diff --git a/org.tizen.guides/html/images/scaling.png b/org.tizen.ui.guides/html/images/scaling.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/scaling.png rename to org.tizen.ui.guides/html/images/scaling.png diff --git a/org.tizen.tutorials/html/images/screenshot_1.png b/org.tizen.ui.guides/html/images/screenshot_1.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.tutorials/html/images/screenshot_1.png rename to org.tizen.ui.guides/html/images/screenshot_1.png diff --git a/org.tizen.tutorials/html/images/screenshot_2.png b/org.tizen.ui.guides/html/images/screenshot_2.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.tutorials/html/images/screenshot_2.png rename to org.tizen.ui.guides/html/images/screenshot_2.png diff --git a/org.tizen.ui.guides/html/images/scrollview.png b/org.tizen.ui.guides/html/images/scrollview.png new file mode 100755 index 0000000..f302903 Binary files /dev/null and b/org.tizen.ui.guides/html/images/scrollview.png differ diff --git a/org.tizen.guides/html/images/segm_control_default.png b/org.tizen.ui.guides/html/images/segm_control_default.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/segm_control_default.png rename to org.tizen.ui.guides/html/images/segm_control_default.png diff --git a/org.tizen.guides/html/images/segment.png b/org.tizen.ui.guides/html/images/segment.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/segment.png rename to org.tizen.ui.guides/html/images/segment.png diff --git a/org.tizen.guides/html/images/segment_control_tree.png b/org.tizen.ui.guides/html/images/segment_control_tree.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/segment_control_tree.png rename to org.tizen.ui.guides/html/images/segment_control_tree.png diff --git a/org.tizen.guides/html/images/segment_text.png b/org.tizen.ui.guides/html/images/segment_text.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/segment_text.png rename to org.tizen.ui.guides/html/images/segment_text.png diff --git a/org.tizen.ui.guides/html/images/setting_sd.png b/org.tizen.ui.guides/html/images/setting_sd.png new file mode 100755 index 0000000..fd39a6e Binary files /dev/null and b/org.tizen.ui.guides/html/images/setting_sd.png differ diff --git a/org.tizen.ui.guides/html/images/show_frametime.png b/org.tizen.ui.guides/html/images/show_frametime.png new file mode 100755 index 0000000..04c1066 Binary files /dev/null and b/org.tizen.ui.guides/html/images/show_frametime.png differ diff --git a/org.tizen.ui.guides/html/images/signal_slot.png b/org.tizen.ui.guides/html/images/signal_slot.png new file mode 100755 index 0000000..18d2f4e Binary files /dev/null and b/org.tizen.ui.guides/html/images/signal_slot.png differ diff --git a/org.tizen.guides/html/images/slider.png b/org.tizen.ui.guides/html/images/slider.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/slider.png rename to org.tizen.ui.guides/html/images/slider.png diff --git a/org.tizen.guides/html/images/slider_hor.png b/org.tizen.ui.guides/html/images/slider_hor.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/slider_hor.png rename to org.tizen.ui.guides/html/images/slider_hor.png diff --git a/org.tizen.guides/html/images/slider_hor_center.png b/org.tizen.ui.guides/html/images/slider_hor_center.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/slider_hor_center.png rename to org.tizen.ui.guides/html/images/slider_hor_center.png diff --git a/org.tizen.guides/html/images/slider_hor_wn.png b/org.tizen.ui.guides/html/images/slider_hor_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/slider_hor_wn.png rename to org.tizen.ui.guides/html/images/slider_hor_wn.png diff --git a/org.tizen.guides/html/images/slider_tree.png b/org.tizen.ui.guides/html/images/slider_tree.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/slider_tree.png rename to org.tizen.ui.guides/html/images/slider_tree.png diff --git a/org.tizen.guides/html/images/slider_ver.png b/org.tizen.ui.guides/html/images/slider_ver.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/slider_ver.png rename to org.tizen.ui.guides/html/images/slider_ver.png diff --git a/org.tizen.guides/html/images/slider_ver_center.png b/org.tizen.ui.guides/html/images/slider_ver_center.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/slider_ver_center.png rename to org.tizen.ui.guides/html/images/slider_ver_center.png diff --git a/org.tizen.guides/html/images/slider_wn.png b/org.tizen.ui.guides/html/images/slider_wn.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/slider_wn.png rename to org.tizen.ui.guides/html/images/slider_wn.png diff --git a/org.tizen.guides/html/images/spin.png b/org.tizen.ui.guides/html/images/spin.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/spin.png rename to org.tizen.ui.guides/html/images/spin.png diff --git a/org.tizen.guides/html/images/spinner_hor.png b/org.tizen.ui.guides/html/images/spinner_hor.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/spinner_hor.png rename to org.tizen.ui.guides/html/images/spinner_hor.png diff --git a/org.tizen.guides/html/images/spinner_tree.png b/org.tizen.ui.guides/html/images/spinner_tree.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/spinner_tree.png rename to org.tizen.ui.guides/html/images/spinner_tree.png diff --git a/org.tizen.guides/html/images/spinner_ver.png b/org.tizen.ui.guides/html/images/spinner_ver.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/spinner_ver.png rename to org.tizen.ui.guides/html/images/spinner_ver.png diff --git a/org.tizen.ui.guides/html/images/spiral.png b/org.tizen.ui.guides/html/images/spiral.png new file mode 100755 index 0000000..05f4f02 Binary files /dev/null and b/org.tizen.ui.guides/html/images/spiral.png differ diff --git a/org.tizen.ui.guides/html/images/stereo_projection.png b/org.tizen.ui.guides/html/images/stereo_projection.png new file mode 100755 index 0000000..bb7ec22 Binary files /dev/null and b/org.tizen.ui.guides/html/images/stereo_projection.png differ diff --git a/org.tizen.guides/html/images/styleguide_genlist_def.png b/org.tizen.ui.guides/html/images/styleguide_genlist_def.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/styleguide_genlist_def.png rename to org.tizen.ui.guides/html/images/styleguide_genlist_def.png diff --git a/org.tizen.guides/html/images/styleguide_genlist_defstyle.png b/org.tizen.ui.guides/html/images/styleguide_genlist_defstyle.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/styleguide_genlist_defstyle.png rename to org.tizen.ui.guides/html/images/styleguide_genlist_defstyle.png diff --git a/org.tizen.guides/html/images/styleguide_genlist_doublelabel.png b/org.tizen.ui.guides/html/images/styleguide_genlist_doublelabel.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/styleguide_genlist_doublelabel.png rename to org.tizen.ui.guides/html/images/styleguide_genlist_doublelabel.png diff --git a/org.tizen.guides/html/images/styleguide_genlist_end.png b/org.tizen.ui.guides/html/images/styleguide_genlist_end.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/styleguide_genlist_end.png rename to org.tizen.ui.guides/html/images/styleguide_genlist_end.png diff --git a/org.tizen.guides/html/images/styleguide_genlist_full.png b/org.tizen.ui.guides/html/images/styleguide_genlist_full.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/styleguide_genlist_full.png rename to org.tizen.ui.guides/html/images/styleguide_genlist_full.png diff --git a/org.tizen.guides/html/images/styleguide_genlist_group.png b/org.tizen.ui.guides/html/images/styleguide_genlist_group.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/styleguide_genlist_group.png rename to org.tizen.ui.guides/html/images/styleguide_genlist_group.png diff --git a/org.tizen.guides/html/images/styleguide_genlist_message.png b/org.tizen.ui.guides/html/images/styleguide_genlist_message.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/styleguide_genlist_message.png rename to org.tizen.ui.guides/html/images/styleguide_genlist_message.png diff --git a/org.tizen.guides/html/images/styleguide_genlist_oneicon.png b/org.tizen.ui.guides/html/images/styleguide_genlist_oneicon.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/styleguide_genlist_oneicon.png rename to org.tizen.ui.guides/html/images/styleguide_genlist_oneicon.png diff --git a/org.tizen.ui.guides/html/images/tableview.png b/org.tizen.ui.guides/html/images/tableview.png new file mode 100755 index 0000000..46f4b71 Binary files /dev/null and b/org.tizen.ui.guides/html/images/tableview.png differ diff --git a/org.tizen.ui.guides/html/images/text_class_list.png b/org.tizen.ui.guides/html/images/text_class_list.png new file mode 100755 index 0000000..51abc95 Binary files /dev/null and b/org.tizen.ui.guides/html/images/text_class_list.png differ diff --git a/org.tizen.ui.guides/html/images/text_class_list_del.png b/org.tizen.ui.guides/html/images/text_class_list_del.png new file mode 100755 index 0000000..967cfa8 Binary files /dev/null and b/org.tizen.ui.guides/html/images/text_class_list_del.png differ diff --git a/org.tizen.ui.guides/html/images/text_class_properties.png b/org.tizen.ui.guides/html/images/text_class_properties.png new file mode 100755 index 0000000..146d0c9 Binary files /dev/null and b/org.tizen.ui.guides/html/images/text_class_properties.png differ diff --git a/org.tizen.tutorials/html/images/text_properties.png b/org.tizen.ui.guides/html/images/text_properties.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.tutorials/html/images/text_properties.png rename to org.tizen.ui.guides/html/images/text_properties.png diff --git a/org.tizen.ui.guides/html/images/text_screen_2.png b/org.tizen.ui.guides/html/images/text_screen_2.png new file mode 100755 index 0000000..8062f32 Binary files /dev/null and b/org.tizen.ui.guides/html/images/text_screen_2.png differ diff --git a/org.tizen.ui.guides/html/images/textfield.png b/org.tizen.ui.guides/html/images/textfield.png new file mode 100755 index 0000000..8da1e07 Binary files /dev/null and b/org.tizen.ui.guides/html/images/textfield.png differ diff --git a/org.tizen.ui.guides/html/images/textlabel.png b/org.tizen.ui.guides/html/images/textlabel.png new file mode 100755 index 0000000..d91cca2 Binary files /dev/null and b/org.tizen.ui.guides/html/images/textlabel.png differ diff --git a/org.tizen.guides/html/images/thread_pool_lifecycle_1.png b/org.tizen.ui.guides/html/images/thread_pool_lifecycle_1.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/thread_pool_lifecycle_1.png rename to org.tizen.ui.guides/html/images/thread_pool_lifecycle_1.png diff --git a/org.tizen.guides/html/images/thread_pool_lifecycle_2.png b/org.tizen.ui.guides/html/images/thread_pool_lifecycle_2.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/thread_pool_lifecycle_2.png rename to org.tizen.ui.guides/html/images/thread_pool_lifecycle_2.png diff --git a/org.tizen.guides/html/images/thread_pool_lifecycle_3.png b/org.tizen.ui.guides/html/images/thread_pool_lifecycle_3.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/thread_pool_lifecycle_3.png rename to org.tizen.ui.guides/html/images/thread_pool_lifecycle_3.png diff --git a/org.tizen.guides/html/images/toolbar.png b/org.tizen.ui.guides/html/images/toolbar.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/toolbar.png rename to org.tizen.ui.guides/html/images/toolbar.png diff --git a/org.tizen.guides/html/images/toolbar_default.png b/org.tizen.ui.guides/html/images/toolbar_default.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/toolbar_default.png rename to org.tizen.ui.guides/html/images/toolbar_default.png diff --git a/org.tizen.guides/html/images/toolbar_navigation.png b/org.tizen.ui.guides/html/images/toolbar_navigation.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/toolbar_navigation.png rename to org.tizen.ui.guides/html/images/toolbar_navigation.png diff --git a/org.tizen.guides/html/images/toolbar_tabbar.png b/org.tizen.ui.guides/html/images/toolbar_tabbar.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/toolbar_tabbar.png rename to org.tizen.ui.guides/html/images/toolbar_tabbar.png diff --git a/org.tizen.guides/html/images/toolbar_tree.png b/org.tizen.ui.guides/html/images/toolbar_tree.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/toolbar_tree.png rename to org.tizen.ui.guides/html/images/toolbar_tree.png diff --git a/org.tizen.tutorials/html/images/transit_rotation_zoom.png b/org.tizen.ui.guides/html/images/transit_rotation_zoom.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.tutorials/html/images/transit_rotation_zoom.png rename to org.tizen.ui.guides/html/images/transit_rotation_zoom.png diff --git a/org.tizen.tutorials/html/images/transitions1.png b/org.tizen.ui.guides/html/images/transitions1.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.tutorials/html/images/transitions1.png rename to org.tizen.ui.guides/html/images/transitions1.png diff --git a/org.tizen.tutorials/html/images/transitions2.png b/org.tizen.ui.guides/html/images/transitions2.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.tutorials/html/images/transitions2.png rename to org.tizen.ui.guides/html/images/transitions2.png diff --git a/org.tizen.tutorials/html/images/transitions3.png b/org.tizen.ui.guides/html/images/transitions3.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.tutorials/html/images/transitions3.png rename to org.tizen.ui.guides/html/images/transitions3.png diff --git a/org.tizen.tutorials/html/images/transitions5.png b/org.tizen.ui.guides/html/images/transitions5.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.tutorials/html/images/transitions5.png rename to org.tizen.ui.guides/html/images/transitions5.png diff --git a/org.tizen.ui.guides/html/images/ui_control_hierarchy.png b/org.tizen.ui.guides/html/images/ui_control_hierarchy.png new file mode 100755 index 0000000..f45a416 Binary files /dev/null and b/org.tizen.ui.guides/html/images/ui_control_hierarchy.png differ diff --git a/org.tizen.ui.guides/html/images/ui_controls.png b/org.tizen.ui.guides/html/images/ui_controls.png new file mode 100755 index 0000000..f5daefb Binary files /dev/null and b/org.tizen.ui.guides/html/images/ui_controls.png differ diff --git a/org.tizen.tutorials/html/images/uilayout_view2.png b/org.tizen.ui.guides/html/images/uilayout_view2.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.tutorials/html/images/uilayout_view2.png rename to org.tizen.ui.guides/html/images/uilayout_view2.png diff --git a/org.tizen.ui.guides/html/images/use_natural_size.png b/org.tizen.ui.guides/html/images/use_natural_size.png new file mode 100755 index 0000000..d314b04 Binary files /dev/null and b/org.tizen.ui.guides/html/images/use_natural_size.png differ diff --git a/org.tizen.ui.guides/html/images/using_clipper.png b/org.tizen.ui.guides/html/images/using_clipper.png new file mode 100755 index 0000000..e249cc9 Binary files /dev/null and b/org.tizen.ui.guides/html/images/using_clipper.png differ diff --git a/org.tizen.ui.guides/html/images/using_clipper2.png b/org.tizen.ui.guides/html/images/using_clipper2.png new file mode 100755 index 0000000..89ee144 Binary files /dev/null and b/org.tizen.ui.guides/html/images/using_clipper2.png differ diff --git a/org.tizen.guides/html/images/using_import_attribute.png b/org.tizen.ui.guides/html/images/using_import_attribute.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/using_import_attribute.png rename to org.tizen.ui.guides/html/images/using_import_attribute.png diff --git a/org.tizen.tutorials/html/images/view_main.png b/org.tizen.ui.guides/html/images/view_main.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.tutorials/html/images/view_main.png rename to org.tizen.ui.guides/html/images/view_main.png diff --git a/org.tizen.ui.guides/html/images/w_division.png b/org.tizen.ui.guides/html/images/w_division.png new file mode 100755 index 0000000..88d9959 Binary files /dev/null and b/org.tizen.ui.guides/html/images/w_division.png differ diff --git a/org.tizen.guides/html/images/win_tree.png b/org.tizen.ui.guides/html/images/win_tree.png old mode 100644 new mode 100755 similarity index 100% rename from org.tizen.guides/html/images/win_tree.png rename to org.tizen.ui.guides/html/images/win_tree.png diff --git a/org.tizen.ui.guides/html/images/wn_division.png b/org.tizen.ui.guides/html/images/wn_division.png new file mode 100755 index 0000000..11a7876 Binary files /dev/null and b/org.tizen.ui.guides/html/images/wn_division.png differ diff --git a/org.tizen.ui.guides/html/images/wn_icon.png b/org.tizen.ui.guides/html/images/wn_icon.png new file mode 100755 index 0000000..bb5c915 Binary files /dev/null and b/org.tizen.ui.guides/html/images/wn_icon.png differ diff --git a/org.tizen.ui.guides/html/images/ww_division.png b/org.tizen.ui.guides/html/images/ww_division.png new file mode 100755 index 0000000..65e7ab7 Binary files /dev/null and b/org.tizen.ui.guides/html/images/ww_division.png differ diff --git a/org.tizen.ui.guides/html/images/ww_icon.png b/org.tizen.ui.guides/html/images/ww_icon.png new file mode 100755 index 0000000..40de988 Binary files /dev/null and b/org.tizen.ui.guides/html/images/ww_icon.png differ diff --git a/org.tizen.ui.guides/html/images/ww_icon_optional.png b/org.tizen.ui.guides/html/images/ww_icon_optional.png new file mode 100755 index 0000000..464ba76 Binary files /dev/null and b/org.tizen.ui.guides/html/images/ww_icon_optional.png differ diff --git a/org.tizen.ui.guides/html/index.htm b/org.tizen.ui.guides/html/index.htm new file mode 100755 index 0000000..e93a5b0 --- /dev/null +++ b/org.tizen.ui.guides/html/index.htm @@ -0,0 +1,243 @@ + + + + + + + + + + + + + + UI Guides + + + + +
      +
      + +
      + +

      UI Guides

      + +

      Web Application

      + + +

      Native Application

      + + + + +
      + + + + + + + diff --git a/org.tizen.ui.guides/html/native/dali/actors_n.htm b/org.tizen.ui.guides/html/native/dali/actors_n.htm new file mode 100755 index 0000000..825357a --- /dev/null +++ b/org.tizen.ui.guides/html/native/dali/actors_n.htm @@ -0,0 +1,396 @@ + + + + + + + + + + + + + + Actors: Working with Basic DALi Components + + + + + + +
      +

      Actors: Working with Basic DALi Components

      + +

      Actor is the primary object in DALi application.

      + +

      Actor Basics

      + + +

      Actor is the basic component that composes the entire scene. It can have visible (for example, UI components, image actor) or invisible (for example, camera actor or layer) forms.

      +

      Actor is also the primary object with which DALi applications interact. Multiple types of event signals provided by actors can be handled in a application through user-defined callback functions.

      + +

      Actors and Stage

      + +

      Stage is a top-level object that represents the entire scene or screen. It is used for displaying a hierarchy of actors managed by the scene graph structure. An actor inherits a position relative to its parent, and can be moved in relation to this point.

      + +

      To display the contents of an actor, it must be added to a stage. The following example shows how to connect a new actor to the stage:

      + +
      Actor actor = Actor::New();
      +Stage::GetCurrent().Add(actor);
      +
      + +

      Coordinate System

      + +

      The stage has a 2D size that matches the size of the application window. The default unit 1 is 1 pixel with default camera.

      + +

      DALi uses a left-handed coordinate system with the origin at the top-left corner, with positive X to right, positive Y going downwards, and positive Z going outside the screen. This is convenient when creating 2D views.

      + +

      Figure: DALi coordinate system

      +

      DALi coordinate system

      + + +

      Positioning Actors

      +

      An actor inherits its parent's position. The relative position between the actor & parent is determined by the following properties:

      +
        +
      • Parent origin +

        This Vector3 property defines a point within the parent actor's area.

        + +

        Figure: Parent origin

        +

        Parent origin

        + +

        The default is top-left, which can be visualized in 2D as (0, 0), but is actually Vector3 (0, 0, 0.5) in the 3D DALi world. The actor position is relative to this point.

      • +
      • Anchor point +

        This Vector3 property defines a point within the child actor area.

        + +

        Figure: Anchor point

        +

        Anchor point

        + +

        The default is center, which can be visualized in 2D as (0.5, 0.5), but is actually Vector3 (0.5, 0.5, 0.5) in the 3D DALi world. The actor position is also relative to this point.

      • + +
      • Position +

        This is the position vector between the parent origin and anchor point.

        + +

        Figure: Position

        +

        Position

        + +

        By default, an actor's position is the distance between its center and the top-left corner of its parent.

        + +

        An actor added directly to the stage with position (X = stageWidth*0.5, Y = stageHeight*0.5) appears in the center of the screen. Likewise, an actor with the position (X = actorWidth*0.5, Y = actorWidth*0.5) appears at the top-left corner of the screen.

        + +

        Since DALi is a 3D toolkit, this behavior is the result of a default perspective camera setup.

        + +
      • +
      + +

      Event Handling for Actors

      +

      The Dali::Actor class provides following event signals:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      + Table: Event signals +
      Event signalDescription
      TouchedSignal()This signal is emitted when a touch input is received.
      HoveredSignal()This signal is emitted when a hover input is received.
      WheelEventSignal()This signal is emitted when a wheel event is received.
      OnStageSignal()This signal is emitted after the actor has been connected to the stage.
      OffStageSignal()This signal is emitted after the actor has been disconnected from the stage.
      OnRelayoutSignal()This signal is emitted after the size has been set on the actor during relayout.
      + +

      For example, a touch event can be handled as follows:

      +
      bool OnTouch(Actor actor, const TouchEvent& touch)
      +{
      +   bool handled = false;
      +
      +   switch(touch.GetPointCount())
      +   {
      +      case 1: // Single touch
      +         if (touch.GetPoint(0).GetState == TouchPoint::Down)
      +         {
      +            // Do action when first touches the touch screen.
      +            ...
      +            handled = true;
      +         }
      +
      +         break;
      +
      +      case 2: // Multi-touch event
      +
      +         break;
      +   }
      +
      +   return handled;   // true if the operation was successful
      +}
      +
      +// Elsewhere
      +Actor actor = Actor::New();
      +actor.TouchedSignal().Connect(&OnTouch);
      + +

      For more information, see Event Handling.

      + +

      Layout Management

      + +

      DALi provides rule-based layout management, size negotiation, which is used to allocate the sizes of the actors on the stage based on rules of dependency between the actors.

      + +

      Dimensions

      +

      The notion of width and height is generalized into the concept of a dimension. Several methods take the Dimension parameter. The Dimension enum specifies the available dimensions as bit fields:

      +
        +
      • Dimension::WIDTH
      • +
      • Dimension::HEIGHT
      • +
      +

      If a method can process width and height at the same time, the Dimension::ALL_DIMENSIONS mask can be specified.

      + +

      Resize Policies

      + +

      The ResizePolicy enum specifies a range of options for controlling the way actors resize. These rules enable automatic resizing.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      + Table: Resizing rules +
      Resize policyDescriptionIllustration
      ResizePolicy::FIXEDUse this option to maintain a specific size as set by the SetSize() function. This is the default for all actors.captured screen2
      ResizePolicy::USE_NATURAL_SIZEUse this option for objects, such as images or text to get their natural size. This can mean the dimensions of an image or the size of text with no wrapping. You can also use this option with table views when the size of the table depends on its children.captured screen2
      ResizePolicy::FILL_TO_PARENTThe size of the actor is similar to its parent's size with proportionate filling considered.captured screen2
      ResizePolicy::SIZE_RELATIVE_TO_PARENTThe size of the actor is similar to its parent's size with a relative scale. Use the SetSizeModeFactor() function to specify the ratio.
      ResizePolicy::SIZE_FIXED_OFFSET_FROM_PARENTThe size of the actor is similar to its parent's size with a fixed offset using the SetSizeModeFactor function.
      ResizePolicy::FIT_TO_CHILDRENThe size of the actor is scaled around the size of the its children. For example, the height of a pop-up can be resized according to its contents.captured screen2
      ResizePolicy::DIMENSION_DEPENDENCYThis option covers rules, such as width-for-height and height-for-width. You can specify that one dimension depends on another.captured screen2
      + + +

      Example with Actors

      + +

      This section describes a layout example with a actor.

      + +

      Enabling Size Negotiation

      + +

      Text and image actors have relayout enabled by default, while plain actors are disabled unless the SetResizePolicy() function is called.

      + +

      Specifying Size Policies

      + +

      Actors have different size policies by default. For example, the image actor is set to USE_NATURAL_SIZE. This ensures that an image actor uses its natural size by default when it is placed on the stage. However, if the SetSize() function is used with sizes other than 0 on the image actor, the current resize policy is overridden by the FIXED policy and the actor takes the specified size.

      + +

      You can specify how an actor is size-negotiated:

      + +
      void SetResizePolicy(ResizePolicy::Type policy, Dimension::Type dimension) @endcode
      + +

      It is possible to specify different policies for the different dimensions of width and height to archive different layouts. Different actors have different resize policies specified. For example, image actors are set to USE_NATURAL_SIZE by default.

      + +

      The following example shows the rootActor with its width set to ResizePolicy::FILL_TO_PARENT and its height set to ResizePolicy::FIT_TO_CHILDREN. It has an image actor added to it with an explicit call to USE_NATURAL_SIZE in both dimensions called on it. This creates an actor that fills the space of its parent in the width dimension and fits its child in the height dimension. As the image actor child is using its natural size, the height of the root actor fits the height of the child image.

      + +
      Actor rootActor = Actor::New();
      +rootActor.SetResizePolicy(ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH);
      +rootActor.SetResizePolicy(ResizePolicy::FIT_TO_CHILDREN, Dimension::HEIGHT);
      +ImageActor image = ImageActor::New(Image::New(MY_IMAGE_PATH));
      +image.SetResizePolicy(ResizePolicy::USE_NATURAL_SIZE, Dimension::ALL_DIMENSIONS);
      +rootActor.Add(image);
      + +

      The following images show the before and after layouts for this code example.

      + +

      Figure: Before and after setting the resize policy

      +

      Before and after setting the resize policy

      +

      Before and after setting the resize policy

      + + +

      This example shows a root actor set to expand to its parent's width and adjust around its child's height. The child image actor is set to its natural size.

      + +

      To specify that a dimension has a dependency on another dimension, use the ResizePolicy::DIMENSION_DEPENDENCY policy. For example, if the dimension is Dimension::HEIGHT and the dependency is Dimension::WIDTH, there is a height-for-width dependency in effect. You can use the policy in a text view that wraps its text. The following example shows a text view that expands its width according to the size of its parent, wraps its contents and then determines its height based on the width.

      + +
      TextLabel text = TextLabel::New("Example");
      +text.SetResizePolicy(ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH);
      +text.SetResizePolicy(ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT);
      + +

      Specifying Sizes and Size Limits

      + +

      To specify a fixed size for an actor, use the FIXED resize policy and set the desired size using the SetSize function. If only 1 dimension is FIXED, the other value in the size parameter is ignored, so it is safe to set it to 0.

      +

      To constrain the final negotiated size of an actor, set the following minimum and maximum sizes, respectively:

      + +
      void SetMinimumSize(const Vector2& size)
      +void SetMaximumSize(const Vector2& size)
      + +

      Adjusting the Negotiated Size

      + +

      When an actor must to maintain the aspect ratio of its natural size, use the SizeScalePolicy() function. This is useful to ensure that images maintain their aspect ratio while still fitting the bounds they have been allocated.

      +

      You can use the following resize policies:

      +
        +
      • SizeScalePolicy::USE_SIZE_SET +

        This is the default policy.

      • +
      • SizeScalePolicy::FIT_WITH_ASPECT_RATIO +

        Fits the actor within the bounds it has been allocated while maintaining the aspect ratio.

      • +
      • SizeScalePolicy::FILL_WITH_ASPECT_RATIO +

        Fills all available space, potentially overflowing its bounds, while maintaining aspect ratio.

      • +
      + +
      void SetSizeScalePolicy(SizeScalePolicy::Type policy)
      + +

      Using Actors in Containers

      + +

      When using actors in containers, such as a table view, you can specify the padding surrounding the actor. The padding specifies the left, right, bottom, and top padding value.

      + +
      void SetPadding(const Padding& padding)
      + + + + + + + + + + +
      Note

      Beware of infinite dependency loops!

      +

      The simplest form of this is shown when the resize policy of a parent actor is set to ResizePolicy::FIT_TO_CHILDREN with a child that has a resize policy of ResizePolicy::FILL_TO_PARENT.

      +

      A more complex loop occurs when a parent actor has a width policy of ResizePolicy::DIMENSION_DEPENDENCY with a height policy of ResizePolicy::FIT_TO_CHILDREN. The parent has a single child with a height policy ResizePolicy::DIMENSION_DEPENDENCY with width. If the child's width policy is ResizePolicy::FILL_TO_PARENT, a loop occurs.

      +

      Loops can occur over larger spreads of parent-child relationships. These loops are detected by the relayout algorithm, which allocates actors 0 sizes.

      + +

      Image Actor

      +

      An image can be displayed through an image actor. THe Dali::ImageActor class inherits from the Dali::Actor class and provides means to display resources, such as images on the stage.

      + +

      Construction

      + +

      The image actor is constructed by passing a Dali::Image object. The Dali::Image is an abstract base class with multiple derived classes, and the Dali::ResourceImage class is used for loading an image from a file.

      + +
      Dali::Image image = ResourceImage::New(myImageFilename);
      +Dali::ImageActor myImageActor = ImageActor::New(image);
      + +

      Style

      + +

      The image actor can render an image in 2 different ways. Although the nine-patch feature is supported by the image actor, using 9-patch image (.9.png or .9.jpg) is encouraged.

      +
        +
      • STYLE_QUAD: A simple flat quad style for rendering images.
      • +
      • STYLE_NINE_PATCH: This style gives the flexibility to stretch images by dividing it into 9 sections. The corners are not scaled; the edges are scaled on 1 axis, and the middle is scaled in both axes.
      • +
      + +
      myImageActor.SetStyle (Dali::ImageActor::STYLE_NINE_PATCH);
      + +

      Border

      + +

      The border is used in the ImageActor::STYLE_NINE_PATCH. It defines the border values of the image for stretching.

      + +
      Dali::ImageActor::Border border(0.45,0.15,0.45,0.15);
      +myImageActor.SetBorder(border);
      + +

      Pixel Area

      + +

      The area of the image to be displayed by the image actor can be set by setting the pixel area. The pixel area is relative to the top-left (0,0) coordinates of the image.

      + +
      Rect<int> pixel1(myX, myY, myWidth, myHeight);
      +if(!myImageActor.IsPixelAreaSet())
      +{
      +   myImageActor.SetPixelArea(pixel1);
      +}
      +
      +//Removes the pixel area setting
      +myImageActor.ClearPixelArea();
      + +

      Changing an Image

      + +

      The image actor needs a reference to a Dali::Image object on creation. However the Image object can be later changed by calling DaliActor:SetImage() function.

      + +
      myImageActor.SetImage(newImage);
      + + + + +
      + +Go to top + + + + + + + + diff --git a/org.tizen.ui.guides/html/native/dali/advanced_animation_n.htm b/org.tizen.ui.guides/html/native/dali/advanced_animation_n.htm new file mode 100755 index 0000000..cbfb7ca --- /dev/null +++ b/org.tizen.ui.guides/html/native/dali/advanced_animation_n.htm @@ -0,0 +1,133 @@ + + + + + + + + + + + + + + Advanced Animations + + + + + + +
      +

      Advanced Animations

      + +

      Frame Animation

      + +

      DALi provides support for animating between several different values, or key frames. A key frame takes a progress value between 0.0f and 1.0f (0 and 100% respectively) and portrays the value of the property when the animation has progressed that much. You can create several key frames:

      +
      +Dali::KeyFrames keyFrames = Dali::KeyFrames::New();
      +keyFrames.Add(0.0f, Vector3(10.0f, 10.0f, 10.0f));
      +keyFrames.Add(0.7f, Vector3(200.0f, 200.0f, 200.0f));
      +keyFrames.Add(1.0f, Vector3(100.0f, 100.0f, 100.0f));
      +
      + +

      Next, you can add them to your animation.

      +
      +animation.AnimateBetween(Property(actor1, Dali::Actor::Property::POSITION), keyFrames);
      +
      +

      When you play the animation, DALi animates the position of actor1 between the key frames specified. The actor1 animates from (10.0f, 10.0f, 10.0f) to (200.0f, 200.f, 200.0f) by 70% of the animation time, and then spends the remaining time animating back to (100.0f, 100.0f, 100.0f).

      +

      The advantage of specifying a key frame at 0% is that regardless of where the actor1 is, it starts from position (10.0f, 10.0f, 10.0f). If AnimateTo() is used, the start position is the actor1's current position.

      + +

      Path Animation

      +

      The Dali::Path API can be used to animate the position and orientation of actors.

      + +

      The black points in the following figure are points where the DALi logo travels to. The red points are the control points which express the curvature of the path on the black points.

      + +

      Figure: Path animation

      +

      Path animation

      + +

      In the code, this is represented as follows:

      +
      +Path path = Path::New();
      +path.AddPoint(Vector3(50.0f, 10.0f, 0.0f));
      +path.AddPoint(Vector3(90.0f, 50.0f, 0.0f));
      +path.AddPoint(Vector3(10.0f, 90.0f, 0.0f));
      +
      +

      The control points can be added manually using Dali::Path::AddControlPoint. The Path API can also auto-generate the control points for you.

      +
      +path.GenerateControlPoints(0.25f);
      +
      +

      Here 0.25f represents the curvature of the path you require. For more information, see the GenerateControlPoints() function in Dali::Path class (in mobile and wearable applications).

      +

      To animate actor1 along this path, use the following function:

      +
      +animation.Animate(actor1, path, Vector3::ZERO);
      +
      +

      The third parameter is the forward vector (in a local space coordinate system) that is oriented with the path's tangent direction.

      + + +

      Shader Effect Animation

      +

      Shader effects provide a visual effect for actors. In a shader, uniforms are set according to the purpose of applications. The uniforms of a shader can be animated using the Animation::AnimateTo() functions.

      +

      For example, to animate the center point of the Bendy shader effect:

      +
      +Dali::Animation animation = Dali::Animation::New(1.0f);
      +
      +Vector2 newPosition(0.0f, 0.0f);
      +animation.AnimateTo(Property(shaderEffect, shaderEffect.GetPositionPropertyName()), newPosition);
      +
      +

      To animate a uniform of a custom shader effect, you must use the name of the uniform:

      +
      +Dali::Animation animation = Dali::Animation::New(1.0f);
      +
      +// Set the initial value for the uniform
      +shaderEffect.SetUniform("myUniform", -0.5f);
      +
      +// Animate the uniform to a value
      +animation.AnimateTo(Property(shaderEffect, "myUniform"), 0.5f);
      +
      + + + + +
      + +Go to top + + + + + + + + diff --git a/org.tizen.ui.guides/html/native/dali/animation_n.htm b/org.tizen.ui.guides/html/native/dali/animation_n.htm new file mode 100755 index 0000000..5314cba --- /dev/null +++ b/org.tizen.ui.guides/html/native/dali/animation_n.htm @@ -0,0 +1,67 @@ + + + + + + + + + + + + + + Animations: Creating Transformations + + + + + + +
      +

      Animations: Creating Transformations

      + +

      Animation is an effect that shows sequential frames in quick succession to give the illusion of movement.

      + +

      DALi provides a rich and easy to use animation framework which allows you to create visually rich applications. The Dali::Animation API can be used to animate the properties of any number of objects, typically Actors. Animation components are shown in a following figure.

      + +

      Figure: DALi animation components

      +

      DALi animation components

      + +

      DALi animations occur in a dedicated thread. This allows animations to run smoothly, regardless of the time taken to process inputs events and other factors in the application code.

      + + + +
      + +Go to top + + + + + + + + diff --git a/org.tizen.ui.guides/html/native/dali/basic_framework_n.htm b/org.tizen.ui.guides/html/native/dali/basic_framework_n.htm new file mode 100755 index 0000000..bb026fb --- /dev/null +++ b/org.tizen.ui.guides/html/native/dali/basic_framework_n.htm @@ -0,0 +1,168 @@ + + + + + + + + + + + + + + Basic Framework + + + + + + +
      +

      Basic Framework

      + +

      Creating a Basic Animation

      + +

      Create an animation object that takes place over 3 seconds:

      +
      +Dali::Animation animation = Animation::New(3.0f);
      +
      + +

      Animating Properties

      + +

      There are two distinct methods to animate the properties within DALi:

      +
        +
      • AnimateTo(): The property animates TO the value in the given time.
      • +
      • AnimateBy(): The property animates BY the value in the given time.
      • +
      + +

      In the following example, it is assumed that actor1 and actor2 are at position 10.0f, 10.0f, 0.0f at the start of the animation.

      +
      +// Animate the position of actor1 TO 10.0f, 50.0f, 0.0f
      +animation.AnimateTo(Property(actor1, Dali::Actor::Property::POSITION), Vector3(10.0f, 50.0f, 0.0f)); 
      +// End Position: 10.0f, 50.0f, 0.0f
      +
      +// Animate the position of actor2 BY 10.0f, 50.0f, 0.0f
      +animation.AnimateBy(Property(actor2, Dali::Actor::Property::POSITION), Vector3(10.0f, 50.0f, 0.0f)); 
      +// End Position: 20.0f, 60.0f, 0.0f
      +
      + +

      Playback Control

      + +

      When an animation is created, it can be played using the Play() method.

      +
      +animation.Play();
      +
      +

      This is not a synchronous method. The Play() method returns after sending a message. After the message is processed in a separate thread, the animation starts. Blocking the application thread does not stop the animation from playing.

      +

      Stop() and Pause() methods are also supported.

      +
      +animation.Stop();
      +animation.Pause();
      +
      + +

      Notifications

      +

      Using DALi's signal framework applications can be notified when the animation finishes. The Dali::Animation API supports "fire and forget" behavior, which means that an animation continues to play if the handle is discarded. Note that in the following example, the "Finish" signal is emitted.

      +
      +void ExampleCallback(Animation& source)
      +{
      +   std::cout << "Animation has finished" << std::endl;
      +}
      +
      +void ExampleAnimation(Actor actor)
      +{
      +   Animation animation = Animation::New(2.0f); // Duration 2 seconds
      +   animation.AnimateTo(Property(actor, Actor::Property::POSITION), 10.0f, 50.0f, 0.0f);
      +   animation.FinishedSignal().Connect(ExampleCallback);
      +   animation.Play();
      +} // At this point the animation handle has gone out of scope
      +
      +Actor actor = Actor::New();
      +Stage::GetCurrent().Add(actor);
      +
      +// Fire the animation and forget about it
      +ExampleAnimation(actor);
      +
      +// The animation continues, and "Animation has finished" is printed after 2 seconds
      +
      + +

      Alpha Functions

      + +

      Alpha functions are used in animations to specify the rate of change of the animation parameter over time. This allows the animation to be, for example, accelerated, decelerated, repeated, or bounced. The built-in supported functions can be viewed in the Dali::AlphaFunction::BuiltinFunction class (in mobile and wearable applications).

      +
      +animation.SetDefaultAlphaFunction(Dali::AlphaFunction::EASE_IN);
      +
      +

      You can also create your own alpha function:

      +
      +float MyAlphaFunction(float progress)
      +{
      +   return progress;
      +}
      +
      +AlphaFunction alphaFunction(&MyAlphaFunction);
      +animation.SetDefaultAlphaFunction(alphaFunction);
      +
      +

      It is possible to specify a different alpha function for each animator in an Animation object.

      +
      +animation.AnimateTo(Property(actor1, Dali::Actor::Property::POSITION), Vector3(10.0f, 50.0f, 0.0f), Dali::AlphaFunction::EASE_IN);
      +
      + +

      Other Actions

      + +

      An animation can be looped:

      +
      +animation.SetLooping(true);
      +
      +

      By default, when an animation ends, the properties that it was animating are baked (saved). Using the following function, the property changes can be discarded when the animation ends or is stopped:

      +
      +animation.SetEndAction(Animation::Discard);
      +
      + + + + +
      + +Go to top + + + + + + + + diff --git a/org.tizen.ui.guides/html/native/dali/buttons_n.htm b/org.tizen.ui.guides/html/native/dali/buttons_n.htm new file mode 100755 index 0000000..b2f4b99 --- /dev/null +++ b/org.tizen.ui.guides/html/native/dali/buttons_n.htm @@ -0,0 +1,279 @@ + + + + + + + + + + + + + + Buttons + + + + + + +
      +

      Buttons

      + +

      Button is a small object on UI that you press in order to operate it. Dali provides button controls, such as PushButton , CheckBoxButton , and RadioButton . The base class for button controls is Toolkit::Button. The Toolkit::Button class provides the disabled property and the clicked signal. Basic signals provided by the Toolkit::Button class are listed in the following table.

      + + + + + + + + + + + + + + + + + + + + + + + + + +
      + Table: Toolkit::Button input signals +
      Input signalDescription
      PressedSignal()Emitted when the button is pressed. +
      ReleasedSignal()Emitted when the button is released. +
      ClickedSignal()Emitted when the button is clicked. +
      StateChangedSignal()Emitted when the button state is changed. +
      + +

      Push Button

      + +

      The PushButton class provides a button that can be pressed to operate it. A push button changes its appearance when is pressed and returns to its original when is released.

      + +

      Figure: Push button

      +

      Push button

      + +

      By default, a push button emits a Button::PressedSignal() signal when the button is pressed, a Button::ClickedSignal() signal when clicked, and a Button::ReleasedSignal() signal when released, or of the touch point leaves the boundary of the button. The following is a basic example of implementing a push button:

      + +
      class ButtonsController: public ConnectionTracker
      +{
      +   ButtonsController(Application& application)
      +      : mApplication(application)
      +   {
      +      mApplication.InitSignal().Connect(this, &ButtonsController::Create);
      +   }
      +
      +   void Create(Application& application)
      +   {
      +      Stage stage = Stage::GetCurrent();
      +
      +      PushButton button = PushButton::New();
      +      button.SetLabel("Select");
      +      button.SetResizePolicy(ResizePolicy::USE_NATURAL_SIZE, Dimension:;ALL_DIMENSIONS);
      +      button.SetSelectedImage(Dali::ResourceImage::New("pressedImage.png"));
      +      button.SetDisabledImage(Dali::ResourceImage::New("disabledImage.png"));
      +      button.SetButtonImage(Dali::ResourceImage::New("buttonImage.png"));
      +
      +      button.ClickedSignal().Connect(this, &ButtonsController::OnButtonClicked);
      +
      +      stage.Add(button);
      +   }
      +
      +   bool OnButtonClicked(Toolkit::Button button)
      +   {
      +      // Application developer code
      +      return true;
      +   }
      +
      +   Application& mApplication;
      +}
      + +

      CheckBox Button

      + +

      The CheckBoxButton class provides check box button which can be checked or unchecked.

      + +

      Figure: Checkbox button

      +

      Checkbox button

      + +

      By default, a checkbox button emits a Button::ClickedSignal() signal when the button changes its state to selected or unselected. The following is a basic example of implementing a checkbox button:

      + +
      class ButtonsController: public ConnectionTracker
      +{
      +   ButtonsController(Application& application)
      +      : mApplication(application)
      +   {
      +      mApplication.InitSignal().Connect(this, &ButtonsController::Create);
      +   }
      +
      +   void Create(Application& application)
      +   {
      +      Stage stage = Stage::GetCurrent();
      +
      +      Actor checkBoxBackground = Actor::New();
      +      stage.Add(checkBoxBackground);
      +      checkBoxBackground.SetParentOrigin(ParentOrigin::TOP_LEFT);
      +      checkBoxBackground.SetAnchorPoint(ParentOrigin::TOP_LEFT);
      +      checkBoxBackground.SetPosition(0.0f, 0.0f);
      +      checkBoxBackground.SetSize(400.0f, 400.0);
      +
      +      Dali::Image unselected = Dali::ResourceImage::New("UnSelectedImage.png");
      +      Dali::Image selected = Dali::ResourceImage::New("SelectedImage.png");
      +
      +      {
      +         Toolkit::CheckBoxButton checkBox = Toolkit::CheckBoxButton::New();
      +          checkBox.SetName("checkbox1");
      +           checkBox.SetBackgroundImage(unselected);
      +           checkBox.SetSelectedImage(selected);
      +           checkBox.SetLabel("CheckBox1 is unselected");
      +           checkBox.StateChangedSignal().Connect(this, &ButtonsController::OnCheckBoxesSelected);
      +
      +           checkBoxBackground.Add(checkBox);
      +      }
      +
      +      {
      +           Toolkit::CheckBoxButton checkBox = Toolkit::CheckBoxButton::New();
      +         checkBox.SetName("checkbox2");
      +         checkBox.SetBackgroundImage(unselected);
      +         checkBox.SetSelectedImage(selected);
      +         checkBox.SetLabel("CheckBox2 is selected");
      +         checkBox.SetSelected(true);
      +         checkBox.StateChangedSignal().Connect(this, &ButtonsController::OnCheckBoxesSelected);
      +
      +         checkBoxBackground.Add(checkBox);
      +      }
      +   }
      +
      +   bool OnCheckBoxesSelected(Toolkit::Button button)
      +   {
      +      if(button.GetName() == "checkbox1")
      +      {
      +         if(button.IsSelected())
      +         {
      +            button.SetLabel("CheckBox1 is selected");
      +         }
      +         else
      +         {
      +            button.SetLabel("CheckBox1 is unselected");
      +         }
      +      }
      +
      +      if(button.GetName() == "checkbox2")
      +      {
      +         if(button.IsSelected())
      +         {
      +            button.SetLabel("CheckBox2 is selected");
      +         }
      +         else
      +         {
      +            button.SetLabel("CheckBox2 is unselected");
      +         }
      +      }
      +      return true;
      +   }
      +
      +   Application& mApplication;
      +}
      + +

      Radio Button

      + +

      The RadioButton class provides a radio button with 2 states: selected and unselected.

      + +

      Figure: Radio button

      +

      Radio button

      + +

      Radio buttons can be grouped. 2 or more radio buttons are in the same group when they have the same parent. In each group, only 1 radio button can be selected at a given time. The following is a basic example of implementing a radio button:

      + +
      class ButtonsController: public ConnectionTracker
      +{
      +   ButtonsController(Application& application)
      +      : mApplication(application)
      +   {
      +      mApplication.InitSignal().Connect(this, &ButtonsController::Create);
      +   }
      +
      +   void Create(Application& application)
      +   {
      +      Stage stage = Stage::GetCurrent();
      +      Actor radioGroup = Actor::New();
      +      stage.Add(redioGroup);
      +      radioGroup.SetParentOrigin(ParentOrigin::TOP_LEFT);
      +      radioGroup.SetAnchorPoint(ParentOrigin::TOP_LEFT);
      +      radioGroup.SetPosition(0.0f, 0.0f);
      +      radioGroup.SetSize(400.0f, 400.0);
      +
      +      RadioButton radioButton1 = RadioButton::New("label");
      +      radioButton1.SetParentOrigin(ParentOrigin::TOP_LEFT);
      +      radioButton1.SetAnchorPoint(ParentOrigin::TOP_LEFT);
      +      radioButton1.SetPosition(0.0f, 0.0f);
      +
      +      RadioButton radioButton2 = RadioButton::New("label");
      +      radioButton2.SetParentOrigin(ParentOrigin::TOP_LEFT);
      +      radioButton2.SetAnchorPoint(ParentOrigin::TOP_LEFT);
      +      radioButton2.SetPosition(0.0f, 40.0f);
      +
      +      radioButton1.StateChangedSignal().Connect(this, &ButtonsController::EnableSelectButton);
      +
      +      radioGroup.Add(radioButton1);
      +      radioGroup.Add(radioButton2);
      +   }
      +
      +   Application& mApplication;
      +}
      + + + + +
      + +Go to top + + + + + + + + diff --git a/org.tizen.ui.guides/html/native/dali/constraints_n.htm b/org.tizen.ui.guides/html/native/dali/constraints_n.htm new file mode 100755 index 0000000..40c10c0 --- /dev/null +++ b/org.tizen.ui.guides/html/native/dali/constraints_n.htm @@ -0,0 +1,294 @@ + + + + + + + + + + + + + + Constraints + + + + + + +
      +

      Constraints

      + +

      Constraints are used to modify the property of an actor, based on other properties of the same actor; properties of the actor's parent; or properties of another actor altogether, when the modification needs to be at run-time. Custom functions or functors can be supplied, where the desired value of the property can be calculated. These functions (or functors) are called in every frame, therefore they must be fast and not too complex, otherwise they can affect performance.

      +

      Multiple constraints can be applied to the same actor at the same time. The order in which constraints are applied is important as this is the order in which they are processed in the update thread.

      +

      Constraints are applied after animations have been applied. This means that Constraints override the values set by Animations. Constraints are not applied to off-stage actors.

      +

      Not all properties can be used as a constraint input. For more details, see the IsPropertyAConstraintInput() function in the Dali::Handle class (in mobile and wearable applications).

      + +

      Using a Constraint

      + +

      Constraints are designed as a way of modifying properties that cannot be modified by any existing built-in functionality, such as animations, size negotiation, parent anchor, or origin settings. As they provide the ability for the application developer to execute their own code within the update thread, DALi can no longer guarantee the timeliness of this code, or how optimized it can be.

      +

      Generally, you must not use constraints with the size property as constraining the size and size negotiation are mutually exclusive. Consider the following use cases as an example of when and when not to use a constraint:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      + Table: Examples of constraint use +
      RequirementSolution
      Need a child to be 50% the size of it's parent.Use size negotiation.
      Need to zoom an actor in to the screen using its scale property.Use an animation.
      Need an actor to appear centered around the bottom-right corner of its parent.Use ParentOrigin and AnchorPoint.
      Need to lay out a series of controls with various alignment requirements.Use either Anchor and origin settings, or a TableView.
      Need to automatically modify the position property of one actor based on the position property of another actor, that is neither a parent OR a child.Use a constraint.
      Need to position an actor relative to its parent actor in a NON-UNIFORM way, or a non-linear calculation needs to be performed that requires a functor.Use a constraint.
      Need to modify an actor's property in real time based on some calculations that require additional data to be stored in-between frames.Use a constraint. The constraint functor can hold any variables within it that need to be preserved frame-to-frame.
      + +

      For most general cases, the position and size requirements of a child or parent actor (from its child or parent) can be calculated with size negotiation.

      + +

      Constraint Sources

      +

      These properties are used as input sources to the constraint. The constraint takes these values, optionally performs a calculation on them (if using a custom functor) and writes the result to the specified property of the target actor. The source actor is specified as either the same actor, its parent, or another actor.

      +
        +
      • Local source +

        A local source is based on the local properties (such as size, position, scale, orientation, or color) of an actor. For example, the actor's orientation can be used as a constraint input source.

        +
        +Dali::ConstraintSource source(Dali::LocalSource(Dali::Actor::Property::ORIENTATION));
        +
        +
      • +
      • Parent Source +

        A parent source is based on properties of the actor's parent. For example, a parent's position can be used as a constraint input source.

        +
        +Dali::ConstraintSource source(Dali::ParentSource(Dali::Actor::Property::POSITION));
        +
        +
      • +
      • Other Handle Source +

        You can base your source on the properties of another handle altogether. For example, a sibling actor's color can be used as a constraint input source.

        +
        +Dali::ConstraintSource source(Dali::Source(anotherHandle, Dali::Actor::Property::COLOR));
        +
        +
      • +
      + +

      Constraint Function

      + +

      The signature of the constraint function is:

      + +
      +void Function(PropertyType &current, const Dali::PropertyInputContainer &inputs);
      +
      +

      In this function the current parameter is a reference to the target property type, such as float, Vector2, or Vector3. This is an in or out parameter. It represents the current value of the property and the expectation is that it is modified by the function to the desired value.

      +

      The inputs parameter holds all the constraint input sources. Each element is a pointer to the property-input and can be accessed using the indexing operator [ ]. The order in which the sources are added is the order in which the property-inputs are sorted in the container. For example:

      +
      +constraint.AddSource(Dali::LocalSource(Dali::Actor::Property::POSITION));
      +constraint.AddSource(Dali::LocalSource(Dali::Actor::Property::SIZE));
      +constraint.AddSource(Dali::ParentSource(Dali::Actor::Property::POSITION));
      +constraint.AddSource(Dali::ParentSource(Dali::Actor::Property::SIZE));
      +
      +

      In the constraint function this equals to:

      +
      +const Dali::Vector3& position(inputs[0]->GetVector3());
      +const Dali::Vector3& size(inputs[1]->GetVector3());
      +const Dali::Vector3& parentPosition(inputs[2]->GetVector3());
      +const Dali::Vector3& parentSize(inputs[3]->GetVector3());
      +
      + + +

      Creating a Constraint

      +

      Using C Functions

      +

      If you do not have any data that is changed at runtime, C functions must be used. For example, the color of an actor can be changed based on its position along the x-axis to a preset distance of 100, beyond which it is transparent.

      +
      +Dali::Actor actor = Actor::New();
      +
      +// Create a constraint that targets actor
      +Dali::Constraint constraint = Dali::Constraint::New< Vector4 >(actor, Dali::Actor::Property::COLOR, MyConstraintFunction); 
      +
      +// Add the POSITION property as a constraint input
      +constraint.AddSource(Dali::LocalSource(Dali::Actor::Property::POSITION)); 
      +
      +// Apply the constraint
      +constraint.Apply(); 
      +
      + +

      The following example shows the actual C function:

      +
      +void MyConstraintFunction(Dali::Vector4& current, const Dali::PropertyInputContainer& inputs)
      +{
      +   const Dali::Vector3& position(inputs[0]->GetVector3());
      +
      +   float distance = fabs(position.x);
      +
      +   // More than 100.0f away, opacity is 0.0f
      +   if (distance > 100.0f)
      +   {
      +      current.a = 0.0f;
      +   }
      +   else
      +   {
      +      // Otherwise it blends between fully opaque and transparent
      +      current.a = (100.0f - distance) / 100.0f;
      +   }
      +}
      +
      + +

      For more information, see the New() function in the Dali::Constraint class (in mobile and wearable applications).

      + +

      Using Functors

      + +

      If you need to store some data in a struct or class, a functor can be used. Reusing the last example, the color of an actor is changed based on its position along the x-axis, but the distance when it is transparent is different for each applied constraint.

      +
      +Dali::Actor actor = Actor::New();
      +
      +// Create a constraint that targets actor, and uses MyFunctor with a distance of 200
      +Dali::Constraint constraint = Dali::Constraint::New< Vector4 >(actor, Dali::Actor::Property::COLOR, MyFunctor(200)); 
      +
      +// Add the POSITION property as a constraint input
      +constraint.AddSource(Dali::LocalSource(Dali::Actor::Property::POSITION)); 
      +
      +// Apply the constraint
      +constraint.Apply(); 
      +
      +

      The following example shows the structure:

      +
      +struct MyFunctor
      +{
      +   // Constructor which takes the distance at which the actor is fully transparent
      +   MyFunctor(float distance)
      +   : mDistance(distance)
      +   {
      +   }
      +
      +   // Functor
      +   void operator()(Dali::Vector4 &current, const Dali::PropertyInputContainer &inputs)
      +   {
      +      const Dali::Vector3& position(inputs[0]->GetVector3());
      +
      +      float distance = fabs(position.x);
      +
      +      // More than mDistance away, opacity is 0.0f
      +      if (distance > mDistance)
      +      {
      +         current.a = 0.0f;
      +      }
      +      else
      +      {
      +         // Otherwise it blends between fully opaque and transparent
      +         current.a = (100.0f - mDistance) / 100.0f;
      +      }
      +   }
      +
      +   // Data
      +   const float mDistance;
      +};
      +
      +

      MyFunctor() can be used also with another constraint with a different distance.

      +

      Instead of using the default functor, another method can be declared in the class or struct and used as the constraint function.

      +

      For more information, see the New() function in the Dali::Constraint class (in mobile and wearable applications).

      + + +

      Removing Constraints

      + +

      The actor's constraints can later be removed in several ways:

      +
      +mConstraint.Remove(); // mConstraint is a base-handle to a constraint
      +actor.RemoveConstraints(); // Removes ALL constraints applied to an actor
      +actor.RemoveConstraint(tag); // All constraints with the tag are removed from the actor (tag can be set using SetTag)
      +
      + + +

      Equal To Constraint

      + +

      The built-in Dali::EqualToConstraint function can be used if only setting a property equal to another property is required:

      +
      +Dali::Constraint constraint = Dali::Constraint::New< Vector3 >(actor, Dali::Actor::Property::POSITION, Dali::EqualToConstraint());
      +constraint.AddSource(Dali::Source(anotherActor, Dali::Actor::Property::POSITION));
      +constraint.Apply();
      +
      +

      Here actor's position is set to equal the position of anotherActor.

      + + +

      Relative To Constraint

      + +

      The built in Dali::RelativeToConstraint and Dali::RelativeToConstraintFloat functions can be used if only setting a property relative to another property is required:

      + +
      +Dali::Constraint constraint = Dali::Constraint::New< Vector3 >(actor, Dali::Actor::Property::POSITION, Dali::RelativeToConstraint(2.0f));
      +constraint.AddSource(Dali::Source(anotherActor, Dali::Actor::Property::POSITION));
      +constraint.Apply();
      +
      +

      Here the actor's position is relative to the position of anotherActor. If anotherActor is at (10.0f, 20.0f, 30.0f), actor is at (20.0f, 40.0f, 60.0f).

      + + + + + + +
      + +Go to top + + + + + + + + diff --git a/org.tizen.ui.guides/html/native/dali/dali_applications_n.htm b/org.tizen.ui.guides/html/native/dali/dali_applications_n.htm new file mode 100755 index 0000000..fd09eec --- /dev/null +++ b/org.tizen.ui.guides/html/native/dali/dali_applications_n.htm @@ -0,0 +1,94 @@ + + + + + + + + + + + + + + DALi Applications: Creating Your First DALi Application + + + + + + +
      +

      DALi Applications: Creating Your First DALi Application

      + +

      The Adaptor framework provides the Dali::Application class, which initializes and sets up DALi appropriately. The class provides many platform-related services.

      + +

      Several signals can be connected to keep you informed when certain platform-related activities occur. It also ensures that, upon system events, DALi is called in a thread-safe manner.

      + +

      The following example shows how to create a Dali::Application instance and connect to its initialize signal, where the Dali::Actor hierarchy is created:

      + +
      void CreateProgram(Application& app)
      +{
      +   // Create DALi components...
      +   Dali::Actor actor = Actor::New();
      +   ...
      +}
      +int main (int argc, char **argv)
      +{
      +   Dali::Application app = Application::New(&argc, &argv);
      +   app.InitSignal().Connect(&CreateProgram);
      +   app.MainLoop();
      +}
      + +

      Window

      + +

      DALi provides the Window class to manage drawing to a default surface. The class is also responsible for drawing the Indicator bar if required. The Application class automatically creates a Window which the you can access after the SignalInit() function has fired.

      + +
      void CreateProgram(Application& app)
      +{
      +   app.GetWindow().ShowIndicator(Dali::Window::VISIBLE);
      +}
      +int main (int argc, char **argv)
      +{
      +   Dali::Application app = Application::New(argc, argv);
      +   app.SignalInit().Connect(&CreateProgram);
      +   app.MainLoop();
      +}
      + + + + + +
      + +Go to top + + + + + + + + diff --git a/org.tizen.ui.guides/html/native/dali/dali_overview_n.htm b/org.tizen.ui.guides/html/native/dali/dali_overview_n.htm new file mode 100755 index 0000000..47184a2 --- /dev/null +++ b/org.tizen.ui.guides/html/native/dali/dali_overview_n.htm @@ -0,0 +1,192 @@ + + + + + + + + + + + + + + DALi Overview: Getting Started with DALi UI Programming + + + + + + +
      +

      DALi Overview: Getting Started with DALi UI Programming

      + +

      Dynamic Animation Library (DALi) internally defines a virtual 3D world (space) and maintains hierarchical objects in the 3D world. The hierarchical object tree is known as the scene graph. A node in the scene graph can have several children but often only a single parent, with the effect of a parent applied to all its child nodes; an operation performed on a group automatically propagates its effect to all of its members.

      +

      There are various types of nodes, such as image, text, and 3D object.

      + +

      DALi Fundamentals

      + +

      Before starting UI programming with DALi, familiarize yourself with the basic concepts.

      + +

      Actor and Stage

      + +

      Actor is the primary object for interaction in DALi applications. Actors are effective nodes that receive input (touch events) and act as a container for drawable elements and other actors. A DALi application uses a hierarchy of actor objects to position visible content. An actor inherits a position relative to its parent, and can be moved relative to this point. UI components can be built by combining multiple actors.

      +

      Stage is a top-level node of the scene graph used for displaying a tree of actors. To display an actor, add is to the stage.

      + +

      Signal and Slot

      + +

      Signals and slots are used in the QT GUI library for communication between objects. Objects can send signals containing event information, which can be received by other objects using special functions known as slots. The DALi event system follows the signal and slot mechanism.

      + +

      Signal events are emitted when a certain action or event occurs. The application can connect using these signals. Standard C-style functions can be used to connect to these signals if no local data needs to be accessed, otherwise a class method can also be connected.

      +

      Applications can manually disconnect from signals when required. However, DALi also provides safe signal disconnection. This means that when the connecting object is deleted, the signal is automatically disconnected.

      + +

      DALi Internal Structure

      + +

      DALi consists of the following modules:

      + +
        +
      • dali-core +

        This module provides scene graph -based rendering, animation, and event handling. It is a base module and forms the biggest part of +DALi.

        +
      • +
      • dali-toolkit +

        This module provides UI components and various effects on top of the dali-core.

      • +
      • dali-adaptor +

        dali-adaptor is a platform adaptation layer. It initializes and sets up DALi appropriately. The module provides many platform-related services. Several signals can be connected to it to keep you informed when certain platform-related activities occur.

      • +
      +

      Figure: DALi internal structure

      +

      DALi internal structure

      + +

      Creating a DALi Application

      + +

      To create a 'Hello World' application with Dali:

      +
        +
      1. Initialize the DALi application
      2. +
      3. Create an actor and add to a stage
      4. +
      + +
      #include < dali-toolkit/dali-toolkit.h>
      +
      +using namespace Dali;
      +using Dali::Toolkit::TextLabel;
      +
      +// This example shows how to create and display Hello World! using a simple TextActor
      +
      +class HelloWorldController : public ConnectionTracker
      +{
      +public:
      +
      +   HelloWorldController(Application& application) : mApplication(application)
      +   {
      +      // Connect to the Application's Init signal
      +      mApplication.InitSignal().Connect(this, &HelloWorldController::Create);
      +   }
      +
      +   ~HelloWorldController()
      +   {
      +      // Remove Hello World actor from stage
      +      Stage::GetCurrent().Remove(mTextLabel);
      +   }
      +
      +   // The Init signal is received once (only) during the Application lifetime
      +   void Create(Application& application)
      +   {
      +      // Get a handle to the stage
      +      Stage stage = Stage::GetCurrent();
      +      mTextLabel = TextLabel::New("Hello World");
      +      stage.Add(mTextLabel);
      +   }
      +
      +private:
      +   Application& mApplication;
      +   TextLabel mTextLabel;
      +};   
      +
      +// Entry point for Linux & Tizen applications
      +int main(int argc, char **argv)
      +{
      +
      +   Application application = Application::New(&argc, &argv);    
      +   HelloWorldController test(application); 
      +   application.MainLoop();
      +
      +   return 0;
      +}
      +
      + +

      Initializing the DALi Application

      + +

      To use DALi APIs, include the dali-toolkit.h header file. It includes the dali-core and dali-adaptor modules.

      + +
      #include < dali-toolkit/dali-toolkit.h>
      + +

      The Dali::Application class (in mobile and wearable applications) initializes and sets up DALi.

      +

      Several signals can be connected to keep you informed when certain platform related activities occur and ensure that, upon system events, DALi is called in a thread-safe manner.

      + +

      Create a Dali::Application instance:

      + +
      +Application application = Application::New(&argc, &argv);
      + +

      After getting the initialized signal from the Dali::Application instance, you can the DALi APIs for building the scene graph. Connect the HelloWorldController::Create callback to DALi::Application InitSignal() function:

      + +
      +mApplication.InitSignal().Connect(this, &HelloWorldController::Create);
      + +

      To run the application, start its main loop. This ensures that images are displayed and events as well as signals are dispatched and captured.

      +
      +application.MainLoop();
      + +

      Creating an Actor and Adding It to a Stage

      + +

      The TextLabel UI component renders a short text string. To display the TextLabel component, add it to a stage. The stage instance is a singleton object (the only instance of its class during the lifetime of the program), so you can get it using a static function:

      + +
      mTextLabel = TextLabel::New("Hello World");
      +
      +Stage stage = Stage::GetCurrent();
      +stage.Add(mTextLabel);
      + +

      The application stores actor and resource handles. DALi objects are reference-counted, which makes sure they exist only as long as they are needed. Therefore, store the actor handle. Even if the TextLabel component is removed from the stage, it remains alive through the reference.

      + + + + + +
      + +Go to top + + + + + + + + diff --git a/org.tizen.ui.guides/html/native/dali/event_handling_n.htm b/org.tizen.ui.guides/html/native/dali/event_handling_n.htm new file mode 100755 index 0000000..8eace44 --- /dev/null +++ b/org.tizen.ui.guides/html/native/dali/event_handling_n.htm @@ -0,0 +1,367 @@ + + + + + + + + + + + + + + Event Handling: Managing the Event Flow + + + + + + +
      + +

      Event Handling: Managing the Event Flow

      + +

      DALi event handling system is composed of 2 major concepts:

      + +
        +
      • Signal +

        Notifications containing event information emitted by GUI components. Similar to events or notifications.

      • +
      • Slot +

        Special functions receiving signals. Similar to event handlers, observer, listener, or callbacks.

      • +
      +

      DALi emits various types of signals to an application to inform it of user actions and the application can handle them through slots.

      + +

      The concept of signal and slots were introduced by Qt for communication between objects. The event mechanism of DALi is inspired by Qt.

      + +

      Figure: Signal and slot event handling

      +

      Signal and slot event handling

      + +

      The signal and slot system has following advantages:

      +
        +
      • Object-oriented: must support callbacks for C++ member functions
      • +
      • Type safe: compiler must be able to check for type safety
      • +
      • Non-coupling: no dependency between caller and callee
      • +
      • Non-type-intrusive: no modification to caller or callee types
      • +
      • Generic: must work for all types of call-backs
      • +
      • Many-to-many relationship: for example, 1 slot can connect to many signals and 1 signal can be connected to many slots
      • +
      + +

      Using Signals and Slots with Touch Events

      +

      The Dali::Actor class provides the TouchedSignal() function to inform the application that a user touches the actor. It is defined as follows:

      + +
      typedef Signal< bool (Actor, const TouchEvent&)> TouchSignalType;
      +TouchSignalType&TouchedSignal();
      + +

      This means that a slot of the following type can be connected to the TouchedSignal() function:

      + +
      bool YourCallbackName(Actor actor, const TouchEvent&event);
      + +

      The return value true indicates that the touch event can be consumed. Otherwise, the signal is emitted on the next sensitive parent of the actor. The return value is valid only for the TouchedSignal() function and other types of signals may not have a return values.

      + +

      Each point on the screen being or having been touched is represented by the Dali::TouchPoint object. This object stores information about the state of the touch point (such as down, up, or motion.) and the coordinates of the touch.

      + +

      A collection of touch points at a specific moment in time is collated into the Dali::TouchEvent object. When a multi-touch event occurs, each touch point represents the points that are currently being touched or the points where touch has stopped.

      + +

      The following example shows how a connection to a touch event signal can be established:

      + +
      bool OnTouch(Actor actor, const TouchEvent&touch)
      +{
      +   bool handled = false;
      +
      +   switch(touch.GetPointCount())
      +   {
      +      case 1: // Single touch
      +         if (touch.GetPoint(0).GetState == TouchPoint::Down)
      +         {
      +            // Do action when first touch on screen
      +
      +            handled = true;
      +         }
      +
      +         break;
      +
      +      case 2: // Multi-touch event
      +
      +         break;
      +
      +   }
      +
      +   return handled;   // true if we have handled the touch, false otherwise
      +}
      +
      +// Elsewhere
      +Actor actor = Actor::New();
      +actor.TouchedSignal().Connect(&OnTouch);
      + +

      The touch event is first emitted to the hit actor by the primary touch point, which is the first point that the user touches. If this hit actor does not handle the event, then the event is offered to the hit actor's parent. Again, if the parent does not handle this event, it is then offered to its parent and so on until the stage is reached or the event is consumed.

      + +

      If a parent and child both connect to the touch signal, the touch event is first offered to the child. If it is consumed by the child, the is not informed.

      + +

      Input Signals

      + +

      Many DALi classes provide various signals to notify events to the application. The basic DALi input signals are as follows:

      + +
        +
      • Touched signal: notify screen touch or mouse click
      • +
      • Hovered signal: notify mouse hovering
      • +
      • Wheel event signal: notify mouse wheel rolling
      • +
      • Key event signal: notify keyboard input
      • +
      • Key input focus signals: notify that a control is ready to receive key event signals
      • +
      • Keyboard focus signals: notify moved focus by navigation keys (such as left or right)
      • +
      +

      These signals are provided by the following classes:

      + +
        +
      • Dali::Actor + + + + + + + + + + + + + + + + + + + + + +
        + Table: Dali::Actor input signals +
        Input signalsDescription
        TouchedSignal()Emitted when touch input is received by the actor. +

        Callback: bool YourCallbackName(Actor actor, const TouchEvent&event);

        HoveredSignal()Emitted when hover input is received by the actor. +

        Callback: bool YourCallbackName(Actor actor, const HoverEvent&event);

        WheelEventSignal()Emitted when wheel event is received by the actor. +

        Callback: bool YourCallbackName(Actor actor, const WheelEvent&event);

        + +

        The actor receiving events is passed to the callbacks.

        +
      • + +
      • +Dali::Stage + + + + + + + + + + + + + + + + + + + + + +
        + Table: Dali::Stage input signals +
        Input signalsDescription
        TouchedSignal()Emitted when touch input is received by the actor. +

        Callback: void YourCallbackName(const TouchEvent&event)

        HoveredSignal()Emitted when hover input is received by the actor. +

        Callback: void YourCallbackName(const TouchEvent&event);

        KeyEventSignal()Emitted when a key event is received by the actor. +

        Callback: void YourCallbackName(const KeyEvent&event);

        + +

        Only events are passed to the callbacks since only a single stage instance can exist in DALi application. The callback return types are void because the stage has no parent to pass events to, even though it does not consume the events.

        +
      • + +
      • +Dali::Toolkit::Control + + + + + + + + + + + + + + + + + + + + + +
        + Table: Dali::Toolkit::Control input signals +
        Input signalsDescription
        KeyEventSignal()Emitted when touch input is received by the actor. +
        KeyInputFocusGainedSignal()Emitted when hover input is received by the actor. +
        KeyInputFocusLostSignal()Emitted when a key event is received by the actor. +
        + +

        The key event signal is provided by the Dali::Stage and Dali::Toolkit::Control classes, not by the Dali::Actor class. The Dali::Actor class is not designed to get key events. To receive key events, an actor must be an instance of the Dali::Toolkit::Control class or one of its subclasses.

        +

        The Dali::Toolkit::Control class can receive touch, hover, and wheel events as it inherits from the Dali::Actor class.

        +
      • + +
      • +Dali::Toolkit::KeyboardFocusManager + + + + + + + + + + + + + + + + + + + + + + + + + +
        + Table: Dali::Toolkit::KeyboardFocusManager input signals +
        Input signalsDescription
        PreFocusChangeSignal()Emitted when touch input is received by the actor. +
        FocusChangedSignal()Emitted when hover input is received by the actor. +
        FocusGroupChangedSignal()Emitted when a wheel event is received by the actor. +
        FocusedActorActivatedSignal()Emitted when a wheel event is received by the actor. +
        +
      • +
      + +The following DALi classes provide signals: +
        +
      • Dali::Window
      • +
      • Dali::Application
      • +
      • Dali::Timer
      • +
      • Dali::Actor
      • +
      • Dali::Image
      • +
      • Dali::ResourceImage
      • +
      • Dali::LongPressGestureDetector
      • +
      • Dali::TapGestureDetector
      • +
      • Dali::PanGestureDetector
      • +
      • Dali::PinchGestureDetector
      • +
      • Dali::RenderTask
      • +
      • Dali::Stage
      • +
      • Dali::ObjectRegistry
      • +
      • Dali::PropertyNotification
      • +
      • Dali::Animation
      • +
      • Dali::Toolkit::Button
      • +
      • Dali::Toolkit::Control
      • +
      • Dali::Toolkit::TextField
      • +
      • Dali::Toolkit::View
      • +
      • Dali::Toolkit::GaussianBlurViewSignal
      • +
      • Dali::ScrollBar
      • +
      • Dali::Toolkit::Scrollable
      • +
      • Dali::Toolkit::ScrollView
      • +
      • Dali::Toolkit::AccessibilityFocusManager
      • +
      • Dali::Toolkit::KeyboardFocusManager
      • +
      +

      For the signals of each class and their usage, see the API Reference.

      + +

      Gestures

      +

      Gesture is a user-friendly high-level event produced from a stream of touch events. The Dali::GestureDetector class analyzes a stream of touch events and attempts to determine the intention of the user.

      +

      If an actor is attached to a gesture detector and the detector recognizes a user intention (detects a predefined pattern in a stream of touch events), the actor emits a detected gesture signal to the application.

      + +

      DALi currently supports following gesture detectors:

      + +
        +
      • Dali::LongPressGestureDetector: detects when the user does a long-press action.
      • +
      • Dali::TapGestureDetector: detects when the user does a tap action.
      • +
      • Dali::PinchGestureDetector: detects when the user moves two fingers towards or away from each other.
      • +
      • Dali::PanGestureDetector: detects when the user moves one or more fingers in the same direction.
      • +
      + +

      The example below shows how an application can be notified of a pinch gesture:

      + +
      void OnPinch(Actor actor, PinchGesture pinch)
      +{
      +   // Scale your actor according to the pinch scale
      +   Vector3 newSize = actor.GetCurrentSize() * pinch.GetScale();
      +   actor.SetSize(newSize);
      +}
      +
      +// Elsewhere
      +PinchDetector detector = PinchDetector::New();
      +detector.Attach(myActor);
      +detector.DetectedSignal().Connect(&OnPinch);
      + + + + + +
      + +Go to top + + + + + + + + diff --git a/org.tizen.ui.guides/html/native/dali/guides_dali_n.htm b/org.tizen.ui.guides/html/native/dali/guides_dali_n.htm new file mode 100755 index 0000000..9bfd3d7 --- /dev/null +++ b/org.tizen.ui.guides/html/native/dali/guides_dali_n.htm @@ -0,0 +1,81 @@ + + + + + + + + + + + + + + DALi + + + + + + +
      +

      DALi

      + +

      DALi is a cross-platform 3D UI Toolkit for embedded systems. Its 3D user interface engine enables you to create rich and high-performance UI applications. DALi is based on OpenGL ES 2.0, but provides a clean cross-platform C++ framework. This means that you can use high-level DALi APIs instead of accessing low-level OpenGL APIs directly.

      + +

      When creating a DALi application, make sure you understand the following main features:

      + + + + + +
      + +Go to top + + + + + + + + diff --git a/org.tizen.ui.guides/html/native/dali/itemview_n.htm b/org.tizen.ui.guides/html/native/dali/itemview_n.htm new file mode 100755 index 0000000..2f1a533 --- /dev/null +++ b/org.tizen.ui.guides/html/native/dali/itemview_n.htm @@ -0,0 +1,145 @@ + + + + + + + + + + + + + + ItemView + + + + + + +
      +

      ItemView

      + +

      The ItemView class provides scrollable layout for item sets. The ItemView is a scrollable container that can contain many items. It can have several layouts. There are also built-in layouts that you can use, as illustrated in the following figure.

      + +

      Figure: ItemView layouts

      + + + + + + + + + + + + + + +
      GridSpiralDepth
      captured screen2captured screen2captured screen2
      +

      You can also create your own custom layout by inheriting from the Dali::Toolkit::ItemLayout class.

      + +

      Item Factory

      + +

      Before creating an ItemView, you must establish an ItemFactory. The ItemFactory provides functions to create items and to get the number of created items. The following is a basic example of implementing an ItemFactory:

      + +
      class MyFactory : public Dali::Toolkit::ItemFactory
      +{
      +public:  
      +   virtual unsigned int GetNumberOfItems()  
      +   {   
      +      // Return the number of items   
      +      return MY_ITEM_COUNT;  
      +   }  
      +
      +   virtual Actor NewItem(unsigned int itemId)  
      +   {   
      +      // Create the actor representing the item based on the itemId 
      +      std::ostringstream imageName;   
      +      imageName << "my-image-folder/" << itemId << ".png"; 
      +
      +      // If item is 10, this results in my-image-folder/10.png
      +      Dali::ResourceImage image = Dali::ResourceImage::New(imageName.str());
      +
      +      // Create an ImageActor from the image
      +      return Dali::ImageActor::New(image);
      +   }
      +};
      + +

      The overridden functions in the factory are called by the ItemView object.

      + +

      Creating an ItemView

      + +

      The following is a basic example of implementing an ItemView:

      + +
      // Store this as a member variable
      +MyFactory factory; 
      +
      +// Pass in the factory
      +Dali::Toolkit::ItemView itemView = Dali::Toolkit::ItemView::New(factory); 
      +
      +itemView.SetParentOrigin(ParentOrigin::CENTER);
      +itemView.SetAnchorPoint(AnchorPoint::CENTER);
      +
      +// Create a layout
      +Dali::Toolkit::ItemLayoutPtr spiralLayout = Dali::Toolkit::DefaultItemLayout::New(Dali::Toolkit::DefaultItemLayout::SPIRAL);
      +
      +// Add the layout to the ItemView
      +itemView.AddLayout(spiralLayout);
      +
      +// More layouts can be created and added to the ItemView
      +// Activate the layout
      +itemView.ActivateLayout(0, Dali::Stage::GetCurrent().GetSize(), 0);
      +
      +Dali::Stage::GetCurrent().Add(itemView);
      + + + +
      + +Go to top + + + + + + + + diff --git a/org.tizen.ui.guides/html/native/dali/multi_threading_n.htm b/org.tizen.ui.guides/html/native/dali/multi_threading_n.htm new file mode 100755 index 0000000..61c1110 --- /dev/null +++ b/org.tizen.ui.guides/html/native/dali/multi_threading_n.htm @@ -0,0 +1,119 @@ + + + + + + + + + + + + + + Multi-threading + + + + + + +
      +

      Multi-threading

      + +

      Multi-threaded Architecture

      + +

      DALi animations and rendering occur in a dedicated rendering thread. This allows animations to run smoothly, regardless of the time taken to process inputs events in the application code.

      + +

      Internally, DALi contains the scene graph that mirrors the actor hierarchy. The scene graph objects perform the actual animation and rendering, while the actors provide thread-safe access. Actors and scene graph objects communicate through messaging.

      + +

      The following figure shows an actor hierarchy, in which one of the actors is being animated. The green objects in are created by the application code, while the blue private objects are used in the dedicated rendering thread.

      + +

      Figure: Actor hierarchy with an animation

      +

      Actor hierarchy with an animation

      + +

      Reading an Animated Value

      + +

      When a property is animatable, it can only be modified in the rendering thread. The value returned from a getter method is the value used when the previous frame was rendered.

      + +

      For example, the GetCurrentPosition() function returns the position in which the actor was last rendered. Since the SetPosition() function is asynchronous, a call to GetCurrentPosition() function does not immediately return the same value.

      + +
      Actor actor = Actor::New();
      +Stage::GetCurrent().Add(actor); // Initial position is 0,0,0
      +
      +actor.SetPosition(Vector3(10,10,10));
      +
      +Vector3 current;
      +current = actor.GetCurrentPosition();
      +std::cout << "Current position: " << current.x << ", " << current.y << ", " << current.z << std::endl;
      +
      +std::cout << "..." << std::endl;
      +
      +// Handling another event
      +
      +current = actor.GetCurrentPosition();
      +std::cout << "Current position: " << current.x << ", " << current.y << ", " << current.z << std::endl;
      +
      + +

      The above code is likely to output:

      +
      Actor actor = Actor::New();
      +"Current position: 0,0,0"
      +// Other positions
      +"Current position: 10,10,10"
      + +

      Setting a Property during an Animation

      + +

      When a property is being animated, the animation overrides all values set with other functions, such as the SetPosition() function.

      + +

      Figure: Actor hierarchy with an animated property

      +

      Actor hierarchy with an animated property

      + +

      The order of execution in the render thread is:

      +
        +
      1. Process message and call the SetPosition() function
      2. +
      3. Apply animation and call the SetPosition() function
      4. +
      5. Render frame
      6. +
      + + + + +
      + +Go to top + + + + + + + + diff --git a/org.tizen.ui.guides/html/native/dali/rendering_effects_n.htm b/org.tizen.ui.guides/html/native/dali/rendering_effects_n.htm new file mode 100755 index 0000000..d62e239 --- /dev/null +++ b/org.tizen.ui.guides/html/native/dali/rendering_effects_n.htm @@ -0,0 +1,138 @@ + + + + + + + + + + + + + + Rendering and Effects: Managing Viewing Modes and Shader Effects + + + + + + +
      +

      Rendering and Effects: Managing Viewing Modes and Shader Effects

      + +

      Viewing Modes

      + +

      DALi supports the following viewing modes:

      +
        +
      • MONO
      • +
      • STEREO_HORIZONTAL
      • +
      • STEREO_VERTICAL
      • +
      + +

      MONO is the default viewing mode. When using the MONO mode, only 1 image per scene is produced in every update. In this setup, DALi creates a default render task, which renders everything added to the stage root layer, and 1 default camera for that render task.

      + +

      The STEREO_HORIZONTAL and STEREO_VERTICAL modes allow the application to produce stereo images. Stereoscopy is a technique for creating or enhancing the illusion of depth in an image. Stereo rendering technique produces 2 images of the scene with an slight offset between them, which is presented to the left and the right eye independently. In this setup, DALi creates 2 additional render tasks, 1 for the right eye and 1 for the left, each with its own camera. Those cameras are parented to the default camera. The method to generate the projection transformation for each camera is known as "parallel axis asymmetric frustum perspective projection" and is illustrated in the following figure.

      + +

      Figure: Stereoscopic projection

      +

      Stereoscopic projection

      + +

      The separation between the 2 cameras is configurable but, typically, it ranges between 50 and 70 millimeters. Too large a separation can be hard to resolve and is known as hyperstereo. The convergence plane for both frustums is the 2D plane, so the projection of anything lying in the 2D plane is coincident for both left and right eye, resulting in no parallax. Objects that lie in front of the projection plane appear to be in front of the screen and objects behind the projection plane appear to be "into" the screen. Objects behind the projection plane (positive parallax) are easier to look at without straining the eyes.

      + +

      To view stereoscopic images correctly, each image must be presented to each eye independently. There are devices on the market for this, such as a head-mounted display, which is a display device worn in the head that has 2 small displays, one for each eye. A cheaper alternative to this often expensive device is the Google cardboard viewer.

      + +

      Figure: Google cardboard viewer

      +

      Google cardboard viewer

      + +

      With the Google cardboard viewer or a similar device, you can transform your phone into a basic virtual reality headset.

      + +

      Stereoscopic Rendering in DALi

      + +

      THe STEREO_HORIZONTAL mode presents the left image on the top half of the screen and the right image on the bottom half. It is intended to be used in landscape orientation, so the images are rotated 90 degrees counter-clockwise. The STEREO_VERTICAL mode, on the other hand, renders the left image on the left half of the screen and the right image on the right half.

      + +

      To define the viewing mode to be used, use the SetViewMode() function of the Application class, passing the mode as a parameter. You can query the view mode being used by calling the GetViewMode() function. To define the separation between the left and right cameras, use the SetStereoBase()function, passing the distance in millimeters as a parameter. This distance can be queried using the GetStereoBase() function. You can also set the viewing mode and offset at initialization time using 2 command line arguments for this purpose: -view-mode (or -v) and 0 for MONO, 1 for STEREO_HORIZONTAL, 2 for STEREO_VERTICAL, and -stereo-base (or -s) and the separation in millimeters.

      + +

      Restrictions

      + +

      There are certain restrictions when writing stereoscopic applications using DALi:

      + +
        +
      • When a stereo mode is selected, the default render task source actor is set to an uninitialized actor so it does not render anything. Changing the default render task source actor later on produces undesired results, as the user does not want to see anything rendered by the default camera when stereo mode is on.
      • +
      • Stereo cameras are parented to the default camera, so if the application needs to change the camera position or orientation, it must change the default camera transformation. The handle to the default camera can be obtained from the default render task as follows: + +
        Dali::RenderTask defaultRenderTask = Dali::Stage::GetCurrent().GetRenderTaskList().GetTask(0); Dali::CameraActor defaultCamera = defaultRenderTask.GetCameraActor();
        +
      • +
      • Stereo render tasks render everything added to the stage's root layer. If the application must render an object hierarchy to an off-screen buffer, it must set the exclusive flag on that render task so that the stereo tasks do not render that particular subtree. To set the exclusive flag in a render task, use the SetExclusive() function defined in the render task.
      • +
      + +

      Shader Effects

      +

      The shader effects allow the developer to apply visual deformations on the actors. They can affect the geometry, the colors and textures of the actor.

      +
        +
      • Each actor has its own default shaders.
      • +
      • Those default shaders can be overridden by modified shader effects.
      • +
      • In an application, each actor might possess its own shader effect.
      • +
      • In an application, multiple actors might apply the same effect.
      • +
      + +

      Custom Shader Effects

      +

      The ShaderEffect enables you to create custom shader effects by specifying the vertex and pixel shaders. For a custom shader, you can provide the vertex and fragment shader code as strings. These shader snippets get concatenated with the default attributes and uniforms.

      + +

      Create a custom shader effect:

      + +
      String myVertexShader; // This variable would contain the code for a vertex shader.
      +Dali::ShaderEffect myEffect = Dali::ShaderEffect::New(myVertexShader,
      +   "" // use default pixel shader
      +);
      + +

      Set the value of a uniform:

      + +
      // if the uniform was declared like this in the shader: uniform float myUniform;
      +myEffect.SetUniform("myUniform", 0.5f);
      + +

      You can apply the custom shader effect to an actor like any other shader:

      + +
      actor.SetShaderEffect(myEffect);
      + + + + +
      + +Go to top + + + + + + + + diff --git a/org.tizen.ui.guides/html/native/dali/resources_n.htm b/org.tizen.ui.guides/html/native/dali/resources_n.htm new file mode 100755 index 0000000..d0a2575 --- /dev/null +++ b/org.tizen.ui.guides/html/native/dali/resources_n.htm @@ -0,0 +1,120 @@ + + + + + + + + + + + + + + Resources: Handling Images + + + + + + +
      +

      Resources: Handling Images

      + +

      Resource Image

      + +

      A resource image is an image that is loaded using a file path or a URL:

      + +
      Dali::ResourceImage image = Dali::ResourceImage::New("/my-path/my-image.png");
      + +

      The resource image can be used with actors, such as ImageActor.

      + +

      Resources are loaded in separate threads. The application can connect to the Dali::ResourceImage::LoadingFinishedSignal() signal to get notified when the image has loaded.

      + +

      By default, resource images start loading immediately and the data is released only when the ResourceImage handle is destroyed. To optimize the application's memory footprint, the application can ask resources to be loaded only when actually required and their data to be released automatically when they are no longer being used by actors.

      + +
      Dali::ResourceImage image = Dali::ResourceImage::New("/my-path/my-image.png", Dali::ResourceImage::ON_DEMAND, Dali::Image::UNUSED);
      + +

      If the Dali::Image::UNUSED property is used, when the image is used again, the resource data is reloaded automatically.

      + +

      If the application requires the image dimensions immediately, they can be retrieved synchronously:

      + +
      Dali::ImageDimensions dimensions = Dali::ResourceImage::GetImageSize("/my-path/my-image.png");
      + +

      This is a disk read which can be slow and block the event thread.

      + +

      9-patch Image

      + +

      DALi provides support for 9-patch images. These are stretchable, repeatable images which are reduced to their smallest size. Essentially, an image is sliced up into 9 squares and the 4 corners do not change size at all. The other 5 segments are stretched or repeated to allow the whole image to scale appropriately.

      + +

      DALi has inbuilt support for *.9.png and *.9.jpg images as well.

      + +

      The following is an example of a *.9.png image.

      + +

      Figure: 9-patch image

      +

      9-patch image

      + +

      Zoomed in, the red section shows the part that is repeated. The corner areas remain static. 1-pixel border is also stripped out.

      + +

      Figure: Zoomed 9-patch image

      +

      Zoomed 9-patch image

      + +

      The following is an example of a 200 x 200 image.

      + +

      Figure: 200 x 200 image

      +

      200 x 200 image

      + +

      Buffer Image

      + +

      A BufferImage represents an image resource in the form of a pixel buffer data. The application can write to this buffer as required and the image is updated on the screen.

      + +
      // Create a 200 by 200 pixel buffer with a color-depth of 32-bits (with alpha)
      +Dali::BufferImage image = Dali::BufferImage::New(200, 200);
      + + + + + +
      + +Go to top + + + + + + + + diff --git a/org.tizen.ui.guides/html/native/dali/scrollview_n.htm b/org.tizen.ui.guides/html/native/dali/scrollview_n.htm new file mode 100755 index 0000000..7be69a6 --- /dev/null +++ b/org.tizen.ui.guides/html/native/dali/scrollview_n.htm @@ -0,0 +1,198 @@ + + + + + + + + + + + + + + ScrollView + + + + + + +
      +

      ScrollView

      + +

      The ScrollView class provides scrollable view. The ScrollView contains actors that can be scrolled manually through touch or automatically.

      + +

      The following figure shows layouts that use the ScrollView.

      + +

      Figure: ScrollView

      +

      ScrollView

      + + +

      The snap-started signal is emitted using the SnapStartedSignal() function when the ScrollView has started to snap or flick. The signal informs the target of the scroll position, scale, and rotation.

      + +

      Creating a ScrollView

      + +

      The following example shows how to create a ScrollView:

      + +
      Dali::Toolkit::ScrollView scrollView;
      +
      +// Create a ScrollView instance
      +myScrollView = ScrollView::New();
      +
      +// Add it to the stage
      +Stage::GetCurrent().Add(scrollView);
      +
      +// Set the size of stage; it covers the entire stage 
      +Stage stage = Dali::Stage::GetCurrent();
      +Size size = stage.GetSize();
      +scrollView.SetSize(size);
      +
      +// Add actors to the ScrollView 
      +Image image = Image::New(DALI_IMAGE_DIR "button-background.png");
      +ImageActor imageActor = ImageActor::New(image);
      +scrollView.Add(imageActor);
      +// The ScrollView contents are now draggable
      +
      +// To enforce horizontal-only scrolling, the Y-axis ruler can be disabled 
      +RulerPtr rulerY = new DefaultRuler();
      +rulerY->Disable();
      +scrollView.SetRulerY(rulerY);
      +
      +// To enable snapping, a FixedRuler can be applied to the X-axis, with snap points spaced to the width of the stage. 
      +Size size = stage.GetSize();
      +RulerPtr rulerX = new FixedRuler(size.width);
      +scrollView.SetRulerX(rulerX);
      +
      +// A domain can be applied to rulers to prevent scrolling beyond this boundary
      +// In this case, to 4 times the width of the stage, allowing for 4 pages to be scrolled
      +Size size = stage.GetSize();
      +RulerPtr rulerX = new FixedRuler(size.width);
      +rulerX->SetDomain(RulerDomain(0.0f, size.width*4.0f));
      +scrollView.SetRulerX(rulerX);
      + +

      Ruler, RulerDomain, and Wrap

      + +

      The Ruler abstract class defines the scroll axes. The RulerDomain class specifies the minimum and maximum values of a ruler. The ScrollView class provides a wrap mode for ScrollView contents. When enabled, the ScrollView contents are wrapped over the x/y domain. The ScrollView behavior depends on a combination of the Ruler, RulerDomain, and Wrap modes. The following table shows ScrollView behavior according to the combination.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      + Table: Scrollview behavior in the Ruler, RulerDomain, and Wrap mode
      RulerDomainWrapBehavior
      DisabledDisabledWrapNo movement in axis
      DisabledEnabledNo wrapNo movement in axis
      DisabledEnabledWrapNo movement in axis
      EnabledDisabledNo wrapFree movement in axis
      EnabledDisabledWrapFree movement in axis, wrapped according to domain minimum and maximum
      EnabledEnabledNo wrapMovement limited to domain minimum and maximum
      EnabledEnabledWrapMovement limited to domain minimum and maximum
      + + + + + + + + + + +
      Note
      Actors within a ScrollView are controlled by constraints. If you apply constraints to these actors externally, undefined behavior can occur. Applying additional constraints can conflict with the ScrollView constraints, so place the actors within container actors. The container actors are affected by the constraints.
      + + + + +
      + +Go to top + + + + + + + + diff --git a/org.tizen.ui.guides/html/native/dali/tableview_n.htm b/org.tizen.ui.guides/html/native/dali/tableview_n.htm new file mode 100755 index 0000000..0287f7a --- /dev/null +++ b/org.tizen.ui.guides/html/native/dali/tableview_n.htm @@ -0,0 +1,105 @@ + + + + + + + + + + + + + + TableView + + + + + + +
      +

      TableView

      + +

      The TableView class is a layout container for aligning child actors in a grid like layout. TableView constraints the x and y position and width and height of the child actors.

      + +

      Figure: TableView

      +

      TableView

      + +

      Creating a TableView

      + +

      The following example shows how to create a TableView:

      + +
      class ButtonsController: public ConnectionTracker
      +{
      +   ButtonsController(Application& application)
      +      : mApplication(application)
      +   {
      +      mApplication.InitSignal().Connect(this, &ButtonsController::Create);
      +   }
      +
      +   void Create(Application& application)
      +   {
      +      Stage stage = Stage::GetCurrent();
      +
      +      TableView tableView = TableView::New(4,4);
      +      tableView.SetKeyboardFocusable(true);
      +      tableView.SetName("TableView");
      +
      +      for (int row = 0; row < 4; ++row)
      +      {
      +         for (int col = 0; col < 4; ++col)
      +         {
      +            Control control = Control::New();
      +            std::ostringstream str;
      +            str << row << "-" << col;
      +            control.SetName(str.str());
      +            control.SetKeyboardFocusable(true);
      +            tableView.AddChild(control, TableView::CellPosition(row, col));
      +         }
      +      }
      +      stage.Add(tableView);
      +   }
      +
      +   // Signal
      +
      +   Application& mApplication;
      +}
      + + + + + +
      + +Go to top + + + + + + + + diff --git a/org.tizen.ui.guides/html/native/dali/textfield_n.htm b/org.tizen.ui.guides/html/native/dali/textfield_n.htm new file mode 100755 index 0000000..bd44fec --- /dev/null +++ b/org.tizen.ui.guides/html/native/dali/textfield_n.htm @@ -0,0 +1,305 @@ + + + + + + + + + + + + + + TextField + + + + + + +
      +

      TextField

      + +

      The TextField class is a control providing a single-line editable text field.

      + +

      Figure: TextField

      +

      TextField

      + +

      Creating a TextField

      + +

      Before text has been entered, the TextField can display a placeholder text. An alternative placeholder can be displayed when the TextField has keyboard focus. For example, a TextField used to enter a username can initially show the text Unknown Name, and the text Enter Name.when the cursor is visible.

      + +
      TextField field = TextField::New();
      +field.SetProperty(TextField::Property::PLACEHOLDER_TEXT, "Unnamed Name");
      +field.SetProperty(TextField::Property::PLACEHOLDER_TEXT_FOCUSED, "Enter Name.");
      +Stage::GetCurrent().Add(field);
      +
      + +

      When the TextField is tapped, it automatically gets the keyboard focus. Key events enter text, and the placeholder text is removed. After text has been entered, it can be retrieved from the TEXT property.

      + +
      Property::Value fieldText = field.GetProperty(TextField::Property::TEXT);
      +std::cout << "Received text: " << fieldText.Get< std::string >() << std::endl;
      + +

      Font Selection

      + +

      The TextField automatically selects suitable fonts, in the same was as the TextLabel. The preferred font can also be selected from a JSON stylesheet:

      + +
      {  
      +   "styles":  
      +   {   
      +      "textfield":   
      +      {     
      +         "font-family":"Arial", "font-style":"Regular", "point-size":8
      +      }  
      +   }
      +}
      + +

      Text Alignment

      + +

      The TextField displays a single-line of text, which scrolls if there is not enough space for the text displayed. If there is enough space, the text can be aligned horizontally to the beginning, end, or center of the available area:

      + +
      field.SetProperty(TextField::Property::HORIZONTAL_ALIGNMENT, "BEGIN"); // "CENTER" or "END"
      + +

      Decorations

      + +

      For text decorations, the TextLabel class provides the properties listed in the following table.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      + Table: TextField properties +
      PropertyTypeWritableAnimatable
      RENDERING_BACKENDIntegerYesNo
      TEXTStringYesNo
      PLACEHOLDER_TEXTStringYesNo
      PLACEHOLDER_TEXT_FOCUSEDStringYesNo
      FONT_FAMILYStringYesNo
      FONT_STYLEStringYesNo
      POINT_SIZEFloatYesNo
      MAX_LENGTHIntegerYesNo
      EXCEED_POLICYIntegerYesNo
      HORIZONTAL_ALIGNMENTStringYesNo
      VERTICAL_ALIGNMENTStringYesNo
      COLORVector4YesNo
      SHADOW_OFFSETVector2YesNo
      SHADOW_COLORVector4YesNo
      PRIMARY_CURSOR_COLORVector4YesNo
      SECONDARY_CURSOR_COLORVector4YesNo
      ENABLE_CURSOR_BLINKBooleanYesNo
      CURSOR_BLINK_INTERVALFloatYesNo
      CURSOR_BLINK_DURATIONFloatYesNo
      GRAB_HANDLE_IMAGEStringYesNo
      GRAB_HANDLE_PRESSED_IMAGEStringYesNo
      SCROLL_THRESHOLDFloatYesNo
      SCROLL_SPEEDFloatYesNo
      SELECTION_HANDLE_IMAGE_RIGHTStringYesNo
      SELECTION_HANDLE_PRESSED_IMAGE_LEFTStringYesNo
      SELECTION_HANDLE_PRESSED_IMAGE_RIGHTStringYesNo
      SELECTION_HIGHLIGHT_COLORVector4YesNo
      DECORATION_BOUNDING_BOXRectangleYesNo
      INPUT_METHOD_SETTINGSMapYesNo
      + +

      To change the color of the text, use the TEXT_COLOR property. An alternative color can be used for placeholder text by setting the PLACEHOLDER_TEXT_COLOR property. Unlike the Actor::COLOR property, these properties do not affect child actors added to the TextField.

      + +
      field.SetProperty(TextField::Property::TEXT_COLOR, Color::CYAN);
      +field.SetProperty(TextField::Property::PLACEHOLDER_TEXT_COLOR, Color::BLACK);
      + + + + + + +
      + +Go to top + + + + + + + + diff --git a/org.tizen.ui.guides/html/native/dali/textlabel_n.htm b/org.tizen.ui.guides/html/native/dali/textlabel_n.htm new file mode 100755 index 0000000..1835665 --- /dev/null +++ b/org.tizen.ui.guides/html/native/dali/textlabel_n.htm @@ -0,0 +1,332 @@ + + + + + + + + + + + + + + TextLabel + + + + + + +
      +

      TextLabel

      + +

      The TextLabel class provides a control that renders a short text string. The text labels are lightweight, non-editable, and do not respond to user input.

      + +

      Figure: TextLabel

      +

      TextLabel

      + +

      Creating a TextLabel

      + +

      To display a TextLabel, the TEXT property must be set using a UTF-8 string.

      + +
      TextLabel label = TextLabel::New();
      +label.SetProperty(TextLabel::Property::TEXT, "Hello World");
      +Stage::GetCurrent().Add(label);
      + +

      The label must also be added to the stage, or to an actor on the stage. The position of the label on the screen depends on the parent-origin and anchor-point properties.

      + +

      Font Selection

      + +

      By default, the TextLabel automatically selects a suitable font from the platform. Typically, fonts do not support all scripts. For example, Latin fonts often do not provide Arabic glyphs. The TextLabel cannot select fonts for all scripts.

      + +

      Alternatively, you can request a font using the FONT_FAMILY, FONT_STYLE, and POINT_SIZE properties:

      + +
      label.SetProperty(TextLabel::Property::FONT_FAMILY, "HelveticaNue");
      +label.SetProperty(TextLabel::Property::FONT_STYLE,  "Regular");
      +label.SetProperty(TextLabel::Property::POINT_SIZE,  12.0f);
      + +

      The TextLabel falls back to using the default font if the requested font does not support the required scripts.

      + +

      Font Styles

      + +

      Setting the font size programmatically is not ideal for applications that support multiple screen resolutions. A more flexible approach is to prepare various JSON stylesheets and request a different style for each platform:

      + +
      StyleManager styleManager = StyleManager::Get();
      +styleManager.RequestThemeChange("example-path/example.json");
      + +

      To change the font for standard text labels, use JSON syntax:

      + +
      {  
      +   "styles":  
      +   {   
      +      "textlabel":   
      +      {     
      +         "font-family":"Arial",
      +         "font-style":"Regular",
      +         "point-size":8   
      +      }  
      +   }
      +}
      + +

      The same point size is unlikely to be suitable for all labels in an application. To set custom sizes, simply set a style name for each case and provide a style override in JSON:

      + +
      label.SetProperty(Control::Property::STYLE_NAME, "custom"); 
      + +

      In the example above, standard text labels have point size 8, and custom labels have point size 10.

      + +

      Text Alignment

      + +

      Wrapping can be enabled using the MULTI_LINE property:

      + +
      label.SetProperty(TextLabel::Property::MULTI_LINE, true);
      + +

      The text can be aligned horizontally to the beginning, end, or center of the available area:

      + +
      label.SetProperty(TextLabel::Property::HORIZONTAL_ALIGNMENT, "BEGIN"); // "CENTER" or "END"
      + +

      Negotiating Size

      + +

      Size negotiation is a layouting feature supported by UI controls, such as TextLabel.

      + +

      There are several resize policies commonly used with TextLabels. +The following examples show the actual size by setting a colored background, whilst the black area represents the size of the parent control.

      + +

      Using the Natural Size

      + +

      In its natural size, the TextLabel is large enough to display the text without wrapping, and does not have extra space to align the text within. In the following example, the same result is displayed regardless of the alignment or multi-line properties:

      + +
      TextLabel label = TextLabel::New("Hello World");
      +label.SetAnchorPoint(AnchorPoint::TOP_LEFT);
      +label.SetResizePolicy(ResizePolicy::USE_NATURAL_SIZE,Dimension::ALL_DIMENSIONS);
      +label.SetBackgroundColor(Color::BLUE);Stage::GetCurrent().Add(label);
      + +

      Height-for-width Negotiation

      + +

      To lay out text labels vertically, a fixed (maximum) width must be provided by the parent control. Each TextLabel reports the desired height for the given width. The following example uses TableView as the parent:

      + +
      TableView parent = TableView::New(3, 1);
      +parent.SetResizePolicy(ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH);
      +parent.SetResizePolicy(ResizePolicy::USE_NATURAL_SIZE, Dimension::HEIGHT);
      +parent.SetAnchorPoint(AnchorPoint::TOP_LEFT);
      +
      +Stage::GetCurrent().Add(parent);
      +
      +TextLabel label = TextLabel::New("Hello World");
      +label.SetAnchorPoint(AnchorPoint::TOP_LEFT);
      +label.SetResizePolicy(ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH);
      +label.SetResizePolicy(ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT);
      +label.SetBackgroundColor(Color::BLUE);
      +
      +parent.AddChild(label, TableView::CellPosition(0, 0));
      +parent.SetFitHeight(0);
      +
      +label = TextLabel::New("A Quick Brown Fox Jumps Over The Lazy Dog");
      +label.SetAnchorPoint(AnchorPoint::TOP_LEFT);
      +label.SetResizePolicy(ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH);
      +label.SetResizePolicy(ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT);
      +label.SetBackgroundColor(Color::GREEN);
      +label.SetProperty(TextLabel::Property::MULTI_LINE, true);
      +
      +parent.AddChild(label, TableView::CellPosition(1, 0));
      +parent.SetFitHeight(1);
      +
      +label = TextLabel::New("لإعادة ترتيب الشاشات، يجب تغيير نوع العرض إلى شبكة قابلة للتخصيص");
      +label.SetAnchorPoint(AnchorPoint::TOP_LEFT);
      +label.SetResizePolicy(ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH);
      +label.SetResizePolicy(ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT);
      +label.SetBackgroundColor(Color::BLUE);
      +label.SetProperty(TextLabel::Property::MULTI_LINE, true);
      +
      +parent.AddChild(label, TableView::CellPosition(2, 0));
      +parent.SetFitHeight(2);
      + +

      In the example, the "Hello World" text label has been given the full width, not the natural width.

      + +

      Decorations

      + +

      For text decorations, the TextLabel claSS provides several properties.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      + Table: TextLabel properties +
      PropertyTypeWritableAnimatable
      RENDERING_BACKENDIntegerYesNo
      TEXTStringYesNo
      FONT_FAMILYStringYesNo
      FONT_STYLEStringYesNo
      POINT_SIZEFloatYesNo
      MULTI_LINEBooleanYesNo
      HORIZONTAL_ALIGNMENTStringYesNo
      VERTICAL_ALIGNMENTStringYesNo
      TEXT_COLORVector4YesNo
      SHADOW_OFFSETVector2YesNo
      SHADOW_COLORVector4YesNo
      UNDERLINE_ENABLEDBooleanYesNo
      UNDERLINE_COLORVector4YesNo
      UNDERLINE_HEIGHTFloatYesNo
      + +

      Color

      + +

      To change the color of the text, use the TEXT_COLOR property. Unlike the Actor::COLOR property, this does not affect child actors added to the TextLabel.

      + +
      label.SetProperty(TextLabel::Property::TEXT, "Red Text");
      +label.SetProperty(TextLabel::Property::TEXT_COLOR, Color::RED);
      + +

      Drop Shadow

      + +

      To add a drop shadow to the text, set the SHADOW_OFFSET property with a non-zero values. The color can also be selected using the SHADOW_COLOR property.

      + +
      stage.SetBackgroundColor(Color::BLUE);
      +label1.SetProperty(TextLabel::Property::TEXT, "Plain Text");
      +label2.SetProperty(TextLabel::Property::TEXT, "Text with Shadow");
      +label2.SetProperty(TextLabel::Property::SHADOW_OFFSET, Vector2(1.0f, 1.0f));
      +label2.SetProperty(TextLabel::Property::SHADOW_COLOR, Color::BLACK);
      +label3.SetProperty(TextLabel::Property::TEXT, "Text with Bigger Shadow");
      +label3.SetProperty(TextLabel::Property::SHADOW_OFFSET, Vector2(2.0f, 2.0f));
      +label3.SetProperty(TextLabel::Property::SHADOW_COLOR, Color::BLACK);
      +label4.SetProperty(TextLabel::Property::TEXT, "Text with Color Shadow");
      +label4.SetProperty(TextLabel::Property::SHADOW_OFFSET, Vector2(1.0f, 1.0f));
      +label4.SetProperty(TextLabel::Property::SHADOW_COLOR, Color::RED);
      + +

      Underlining

      + +

      The text can be underlined by setting UNDERLINE_ENABLED. The color can also be selected using the UNDERLINE_COLOR property.

      + +
      label1.SetProperty(TextLabel::Property::TEXT, "Text with Underline");
      +label1.SetProperty(TextLabel::Property::UNDERLINE_ENABLED, true);
      +label2.SetProperty(TextLabel::Property::TEXT, "Text with Color Underline");
      +label2.SetProperty(TextLabel::Property::UNDERLINE_ENABLED, true);
      +label2.SetProperty(TextLabel::Property::UNDERLINE_COLOR, Color::GREEN); 
      + +

      By default, the underline height is based on the font metrics. This can be overridden using the UNDERLINE_HEIGHT property:

      + +
      label1.SetProperty(TextLabel::Property::UNDERLINE_HEIGHT, 1.0f);
      + + + + + +
      + +Go to top + + + + + + + + diff --git a/org.tizen.ui.guides/html/native/dali/ui_components_n.htm b/org.tizen.ui.guides/html/native/dali/ui_components_n.htm new file mode 100755 index 0000000..f9a3700 --- /dev/null +++ b/org.tizen.ui.guides/html/native/dali/ui_components_n.htm @@ -0,0 +1,114 @@ + + + + + + + + + + + + + + UI Components: Creating the Application Layout + + + + + + +
      +

      UI Components: Creating the Application Layout

      + +

      UI components are interactive components for layouting and scrolling the user interface. DALi provides UI components, such as buttons, item view, scroll view, table view, and text controls.

      + +

      Figure: DALi UI controls

      +

      DALi UI controls

      + +

      The following table lists the available UI controls.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      + Table: UI controls provided by Dali +
      ControlDescriptionRelated classes
      ButtonsA push button that can be pressed, a checkbox button that can be checked/unchecked,and a radio button that only one option can be selected.Button, PushButton, CheckBoxButton, RadioButton
      ItemViewAn item view that renders item sets in a scrollable layout.ItemView, ItemFactory, ItemLayout, Scrollable
      ScrollViewA scroll view to provide scrollable view.ScrollView, Scrollable, ScrollViewEffect, ScrollViewPagePathEffect
      TableViewA table view that can align child actors in a grid like layout.TableView
      TextFieldA text field that provides a single-line editable text field.TextField
      TextLabelA text label that renders a short text string.TextLabel
      + +

      The base class for the controls is Dali::Toolkit::Control (in mobile and wearable applications). This class can also be used as for creating new custom UI controls. The following figure illustrates the hierarchy of the UI controls.

      + +

      Figure: DALi UI control hierarchy

      +

      DALi UI control hierarchy

      + + + + +
      + +Go to top + + + + + + + + diff --git a/org.tizen.ui.guides/html/native/efl/animation_effects_n.htm b/org.tizen.ui.guides/html/native/efl/animation_effects_n.htm new file mode 100755 index 0000000..c6ee375 --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/animation_effects_n.htm @@ -0,0 +1,84 @@ + + + + + + + + + + + + + Animations and Effects: Creating Transformations + + + + + +
      + +

      Animations and Effects: Creating Transformations

      + +

      EFL provides the following animation functionalities: Ecore animators, Elementary transitions, Edje animations, and Evas Map animations.

      + +

      The first option for creating animations with EFL is to use Ecore animators. To create an Ecore animation, you must first determine the duration of the animation, and then define a callback function that performs the animation with that duration.

      + +

      You can also create animations using Elementary transitions. Elementary transitions allow you to apply various transition effects, such as translation and rotation, to Evas objects. Elementary transitions are mostly based on Ecore animators, but provide some transition methods at a higher level of abstraction. Elementary transitions provide a simpler way of animating objects than Ecore animators or Edje animations.

      + +

      A third option for animating objects is to use Edje animations, which are based on a simple principle: transitioning from one state to another. To animate an object with Edje, you have to first define the start and end states of the animation, and then transition the object from the start state to the end state.

      + +

      Finally, Evas Map animations allow you to apply transformations to all types of objects by way of UV mapping. In UV mapping, you map points in the source object to 3D space positions in the target object. This allows for rotation, perspective, scale, and other transformation effects, depending on the map. In addition, each map point can carry a multiplier color, which, if properly calculated, can be used to apply 3D shading effects on the target object.

      + + + + + + + + + + +
      Note
      Except as noted, this content is licensed under LGPLv2.1+.
      + + + +
      + +Go to top + + + + + + + \ No newline at end of file diff --git a/org.tizen.ui.guides/html/native/efl/basic_tutorial_mn.htm b/org.tizen.ui.guides/html/native/efl/basic_tutorial_mn.htm new file mode 100755 index 0000000..1e662b5 --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/basic_tutorial_mn.htm @@ -0,0 +1,285 @@ + + + + + + + + + + + + + + Creating Basic Mobile Interactions + + + + + + +
      +

      Creating Basic Mobile Interactions

      + + +

      This tutorial teaches the basics of UI components interactions. It builds upon the Hello World example.

      + + + + + + + + + + +
      Note
      This feature is supported in mobile applications only.
      + +

      Using Buttons

      + +

      The basic application code is the same as in the Hello World example.

      + +

      Button Styles

      +

      Basic Text Button

      + +

      To create a text-only button, use the following code.

      +
      Evas_Object* button;
      +
      +button = elm_button_add(box);
      +elm_object_text_set(button, "Click me");
      +evas_object_size_hint_weight_set(button, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +evas_object_size_hint_align_set(button, EVAS_HINT_FILL, 0.5);
      +elm_box_pack_end(box, button);
      +evas_object_show(button);
      +
      + +

      Basic Icon Button

      +

      Instead of a button with text, create a button with an icon.

      +
      Evas_Object* button2;
      +Evas_Object* icon2;
      +
      +button2 = elm_button_add(box);
      +icon2 = elm_icon_add(box);
      +elm_image_file_set(icon2, "icon.png", NULL);
      +elm_object_part_content_set(button2, "icon", icon2);
      +evas_object_size_hint_weight_set(button, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +evas_object_size_hint_align_set(button, EVAS_HINT_FILL, 0.5);
      +elm_box_pack_end(box, button);
      +evas_object_show(button);
      +
      + +

      Icon and Text Button

      +

      Create buttons with both an icon and a text label.

      +
      Evas_Object* button3;
      +Evas_Object* icon3;
      +button3 = elm_button_add(box);
      +icon3 = elm_icon_add(box);
      +elm_image_file_set(icon, "icon.png", NULL);
      +elm_object_part_content_set(button3, "icon", icon3);
      +elm_object_text_set(button3, "Press me");
      +evas_object_size_hint_weight_set(button, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +evas_object_size_hint_align_set(button, EVAS_HINT_FILL, 0.5);
      +elm_box_pack_end(box, button);
      +evas_object_show(button);
      +
      + +

      Disabled Button

      +

      To disable a button so that it is not in use, only shown.

      +
      elm_object_disabled_set(button2, EINA_TRUE);
      +
      + +

      Callbacks

      +

      The Elementary buttons respond to user interactions with several events.

      + +

      Click Event

      +

      The "click" event is the most basic and well-known one. The following code snippet changes the text of a button upon a click event: a press followed by an unpress.

      +
      +static void _button_click_cb(void *data, Evas_Object *button, void *ev) 
      +{
      +   elm_object_text_set(button, "Clicked!");
      +}
      +evas_object_smart_callback_add(button, "clicked", _button_click_cb, NULL);
      +
      + +

      Press/Unpress Events

      +

      The button can respond to the press and unpress events instead of the entire click event.

      +
      static void _button_press_cb(void *data, Evas_Object *button, void *ev) 
      +{
      +   elm_object_text_set(button, "Pressed!");
      +}
      +static void _button_unpress_cb(void *data, Evas_Object *button, void *ev) 
      +{
      +   elm_object_text_set(button, "Unpressed!");
      +}
      +
      +evas_object_smart_callback_add(button3, "pressed", _button_press_cb, NULL);
      +evas_object_smart_callback_add(button3, "unpressed", _button_unpress_cb, NULL);
      +
      + +

      Repeated Events

      +

      The button can receive several events in case it is being held by the user. Timings, such as the initial timeout and the repeat interval, can be set. In this example, the initial timeout is set to 1 second, and the repeat interval to half a second.

      +
      static void _button_repeat_cb(void *data, Evas_Object *button, void *ev) 
      +{
      +   static int count = 0;
      +   char buf[16];
      +
      +   snprintf(buf, sizeof(buf), "Repeat %d", count++);
      +
      +   elm_object_text_set(button, buf);
      +}
      +
      +elm_button_autorepeat_set(button3, EINA_TRUE);
      +elm_button_autorepeat_initial_timeout_set(button3, 1.0);
      +elm_button_autorepeat_gap_timeout_set(button3, 0.5);
      +evas_object_smart_callback_add(button3, "repeated", _button_repeat_cb, NULL);
      +
      + +

      Using Simple Text

      + +

      Basic Text

      +

      To create a label object, use the following code.

      +
      label = elm_label_add(ad->win);
      +elm_object_text_set(label, "My label");
      +evas_object_show(label);
      +
      + +

      Sliding Text

      +

      If your text is too long, set it to slide. The duration of the slide is set to five seconds in the following example. There are several styles available:

      +
        +
      • slide_short: The text stops at an edge, reverts to its initial position and slides again.
      • +
      • slide_long: The text is originally empty. It slides in, all the way to the edge, continues sliding until the label is empty, and loops.
      • +
      • slide_bounce: The text moves backwards after stopping at the edge. In the example, it is set to bounce.
      • +
      + +
      Evas_Object* label;
      +label = elm_label_add(->win);
      +elm_object_text_set(label, "This text is supposed to be really long.");
      +elm_label_slide_set(label, EINA_TRUE);
      +elm_label_slide_duration_set(label, 5.);
      +elm_object_style_set(label, "slide_bounce");
      +evas_object_show(label);
      +
      + +

      If needed, you can use the slide,end event to respond to the moment when the sliding text reaches its end.

      + +

      Marker Text

      +

      A marker is a text that is centered and bold by default. As the default color is white, set the blue color in this example.

      +
      elm_object_style_set(label, "marker");
      +evas_object_color_set(label, 0, 0, 255, 255);
      +
      + +

      Styling the Text

      +

      You can apply basic styles to the text. For a bolded text, do as follows.

      +
      elm_object_text_set(label, "<b>This text is bold.</b>");
      +
      + +

      Using Simple Lists

      + +

      Basic List

      +

      A list is a scrollable container, whose children are selected.

      +
      Evas_Object* list;
      +Evas_Object* icon;
      +list = elm_list_add(ad->win);
      +elm_list_item_append(list, "Text item", NULL, NULL, NULL, NULL);
      +icon = elm_icon_add(ad->win);
      +elm_icon_standard_set(icon, "chat");
      +elm_list_item_append(list, "Second item", icon, NULL, NULL, NULL);
      +Evas_Object* button;
      +button = elm_button_add();
      +elm_object_text_set(button, "Button");
      +elm_list_item_append(list, "Fourth item", NULL, button, NULL, NULL);
      +elm_list_go(list);
      +
      + +

      Any Evas Object can be added as an icon, either at the beginning (third parameter) or the end (fourth parameter).

      + +

      List Orientation

      +

      By default, a list is set vertically. This is how to display it horizontally.

      +
      elm_list_horizontal_set(list, EINA_TRUE);
      +
      + +

      List Mode

      +

      There are several modes for the list item dimensions.

      +
        +
      • ELM_LIST_COMPRESS: The list does not set any size measures to inform the container how to resize it. If the list is not created as a "resize object", its dimensions are zeroed. The list respects the container's geometry and if any of the list items do not fit into the container transverse axis, the list does not scroll in that direction.
      • +
      • ELM_LIST_SCROLL: This is the default value. This list is the same as ELM_LIST_COMPRESS, with the exception that if any of the list items do not fit into the container transverse axis, the list still scrolls in that direction.
      • +
      • ELM_LIST_LIMIT: This list sets a minimum size measure on the list object, so that containers may respect it (and resize themselves to fit the child properly). More specifically, a minimum size measure is set for its transverse axis, so that the largest item in that direction fits well. This feature is bound by the list object's maximum size measures that are set externally.
      • +
      • ELM_LIST_EXPAND: Besides setting a minimum size on the transverse axis, as in ELM_LIST_LIMIT, this list sets a minimum size on the longitudinal axis to reserve space for all its children to be visible at the same time. This feature is bound by the list object's maximum size measures that are set externally.
      • +
      +
      elm_list_mode_set(list, ELM_LIST_COMPRESS);
      +
      + +

      Scroller Policy

      +

      Several effects are shown on a list.

      +

      For example, the scroller is set to bounce at the end on either direction.

      +
      elm_scroller_bounce_set(list, EINA_TRUE, EINA_TRUE);
      +
      + + +

      This is how to control displaying scrollbars. The second argument is for the horizontal axis, the third one for the vertical axis.

      +
      elm_scroller_policy_set(list, ELM_SCROLLER_POLICY_AUTO, ELM_SCROLLER_POLICY_ON);
      +
      + +

      As for the bounce preference, the second argument is for the horizontal axis, the third one for the vertical axis.

      +
        +
      • ELM_SCROLLER_POLICY_OFF hides the scrollbar
      • +
      • ELM_SCROLLER_POLICY_ON shows the scrollbar
      • +
      • ELM_SCROLLER_POLICY_AUTO the scrollbar is shown only when needed and stays hidden at other times
      • +
      + +

      Events

      +

      A list responds to several events:

      +
        +
      • activated: The user clicks or presses an item.
      • +
      • selected: The user selects an item.
      • +
      • unselected: The user unselects an item.
      • +
      • longpressed: The user long-presses an item.
      • +
      • edge,top: The user scrolls the list to the top edge.
      • +
      • edge,bottom: The user scrolls the list to the bottom edge.
      • +
      • edge,left: The user scrolls the list to the left edge.
      • +
      • edge,right: The user scrolls the list to the right edge.
      • +
      • highlighted: An item is pressed and highlighted.
      • +
      • unhighlighted: The press and highlight is removed on an item.
      • +
      + + + + +
      + +Go to top + + + + + + + diff --git a/org.tizen.ui.guides/html/native/efl/button_tutorial_wn.htm b/org.tizen.ui.guides/html/native/efl/button_tutorial_wn.htm new file mode 100755 index 0000000..09fbae2 --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/button_tutorial_wn.htm @@ -0,0 +1,231 @@ + + + + + + + + + + + + + + Creating Wearable Buttons + + + + + + +
      +

      Creating Wearable Buttons

      + + +

      This tutorial teaches the basics of the button component interactions.

      + + + + + + + + + + +
      Note
      This feature is supported in wearable applications only.
      + + +

      Initializing the Button Application

      + +

      This use case creates an application with a window entitled "Button Basic Tutorial". The window consists of a box component, and a button is placed inside the box.

      + +

      To create a typical elementary application:

      +
      +static void
      +create_base_gui(appdata_s *ad) 
      +{
      +   // Window
      +   Evas_Object *btn1, *btn2, *btn3;
      +
      +   ad->win = elm_win_util_standard_add("main", "Button Basic Tutorial");
      +   elm_win_autodel_set(ad->win, EINA_TRUE);
      +
      +   evas_object_smart_callback_add(ad->win, "delete,request", win_delete_request_cb, NULL);
      +   eext_object_event_callback_add(ad->win, EEXT_CALLBACK_BACK, win_back_cb, ad);
      +
      +   ad->box = elm_box_add(ad->win);
      +   evas_object_size_hint_weight_set(ad->box, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +   evas_object_show(ad->box);
      +   elm_win_resize_object_add(ad->win, ad->box);
      +
      +   create_button(ad->box);
      +
      +   // Show the window after the base GUI is set up
      +   evas_object_show(ad->win);
      +}
      +
      +static bool
      +app_create(void *data)
      +{
      +   appdata_s *ad = data;
      +   create_base_gui(ad);
      +
      +   return true;
      +}
      +
      +int
      +main(int argc, char **argv)
      +{
      +   struct app_data ad = {0,};
      +   ui_app_lifecycle_callback_s event_callback = {0,};
      +
      +   event_callback.create = app_create;
      +
      +   return ui_app_main(&argc, &argv, &event_callback, &ad);
      +}
      + + +

      Using Button Styles

      + +

      The basic application code is the same as in the Hello World example.

      + +

      To use various button styles:

      + +
      1. To create buttons using various styles:

        + +
        • Create a basic text-only button: + +
          Evas_Object* button;
          +
          +button = elm_button_add(box);
          +elm_object_text_set(button, "Click me");
          +evas_object_size_hint_weight_set(button, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
          +evas_object_size_hint_align_set(button, EVAS_HINT_FILL, 0.5);
          +elm_box_pack_end(box, button);
          +evas_object_show(button);
          +
        • + +
        • Create a basic icon button (no text, just an icon): +
          Evas_Object* button2;
          +Evas_Object* icon2;
          +
          +button2 = elm_button_add(box);
          +icon2 = elm_icon_add(box);
          +elm_image_file_set(icon2, "icon.png", NULL);
          +elm_object_content_set(button2, icon2);
          +evas_object_size_hint_weight_set(button2, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
          +evas_object_size_hint_align_set(button2, EVAS_HINT_FILL, 0.5);
          +elm_box_pack_end(box, button2);
          +evas_object_show(button2);
          +
        • + +
        • Create a button with both an icon and a text label: +
          Evas_Object* button3;
          +Evas_Object* icon3;
          +button3 = elm_button_add(box);
          +icon3 = elm_icon_add(box);
          +elm_image_file_set(icon3, "icon.png", NULL);
          +elm_object_content_set(button3, icon3);
          +elm_object_text_set(button3, "Press me");
          +evas_object_size_hint_weight_set(button3, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
          +evas_object_size_hint_align_set(button3, EVAS_HINT_FILL, 0.5);
          +elm_box_pack_end(box, button3);
          +evas_object_show(button3);
          +
        • +
      2. +
      3. To disable a button so that it is not in use, only shown:

        +
        elm_object_disabled_set(button2, EINA_TRUE);
        +
      + +

      Managing Button Events

      +

      The Elementary buttons respond to user interactions with several events.

      +

      To manage button events:

      + +
        +
      • Handle click events: +

        The "click" event is the most basic and well-known one. The following code snippet changes the text of a button upon a click event: a press followed by an unpress.

        +
        +static void _button_click_cb(void *data, Evas_Object *button, void *ev) 
        +{
        +   elm_object_text_set(button, "Clicked!");
        +}
        +evas_object_smart_callback_add(button, "clicked", _button_click_cb, NULL);
        +
      • + +
      • Handle press and unpress events: +

        The button can respond to the separate press and unpress events instead of the entire click event.

        +
        static void _button_press_cb(void *data, Evas_Object *button, void *ev) 
        +{
        +   elm_object_text_set(button, "Pressed!");
        +}
        +static void _button_unpress_cb(void *data, Evas_Object *button, void *ev) 
        +{
        +   elm_object_text_set(button, "Unpressed!");
        +}
        +
        +evas_object_smart_callback_add(button3, "pressed", _button_press_cb, NULL);
        +evas_object_smart_callback_add(button3, "unpressed", _button_unpress_cb, NULL);
        +
      • + +
      • Handle repeated events: +

        The button can receive several events in case it is being held by the user. Timings, such as the initial timeout and the repeat interval, can be set. In this example, the initial timeout is set to 1 second, and the repeat interval to half a second.

        +
        static void _button_repeat_cb(void *data, Evas_Object *button, void *ev) 
        +{
        +   static int count = 0;
        +   char buf[16];
        +
        +   snprintf(buf, sizeof(buf), "Repeat %d", count++);
        +
        +   elm_object_text_set(button, buf);
        +}
        +
        +elm_button_autorepeat_set(button3, EINA_TRUE);
        +elm_button_autorepeat_initial_timeout_set(button3, 1.0);
        +elm_button_autorepeat_gap_timeout_set(button3, 0.5);
        +evas_object_smart_callback_add(button3, "repeated", _button_repeat_cb, NULL);
        +
      + + + + + +
      + +Go to top + + + + + + + diff --git a/org.tizen.ui.guides/html/native/efl/circle_components_wn.htm b/org.tizen.ui.guides/html/native/efl/circle_components_wn.htm new file mode 100755 index 0000000..e36f89b --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/circle_components_wn.htm @@ -0,0 +1,689 @@ + + + + + + + + + + + + + Creating Wearable Circle Components + + + + + +
      +

      Creating Wearable Circle Components

      + +

      Circle components extend the UI features and provide functionalities optimized for the circular UI.

      + + + + + + + + + + +
      Note
      This feature is supported in wearable applications only.
      + +

      Generally, circle components can be added with the eext_circle_object_[component_name]_add() function, which returns a circle object handle. Circle components are shown in a form of an arch with radius, line width, and color. These properties can be set with the eext_circle_object_item* APIs. The circle object can also take a rotary event. Generally, a clockwise rotary event increases the value of the rotary event activated by the circle object, and a counter clockwise rotary event decreases the value.

      + +

      Circle Datetime

      + + +

      Figure: Circle Datetime

      +

      Circle Datetime

      + +

      The circle datetime extends elm_datetime by visualizing the selected field. If a rotary event is activated by eext_rotary_object_event_activated_set(), a circle datetime increases or decreases value of selected field in elm_datetime by the clockwise or counter clockwise rotary event.

      + +

      Creating a Circle Datetime

      + +

      You can use the eext_circle_object_datetime_add() function to create a circle object. When creating a circle datetime, the elm_datetime handle must be passed as an argument. If a circle surface is passed as an argument, a circle object connected with a circle surface is created, and it is rendered by the circle surface. When NULL is passed as a surface argument, the new circle object is managed and rendered by itself.

      +
      +Evas_Object *datetime;
      +Evas_Object *circle_datetime;
      +
      +datetime = elm_datetime_add(parent);
      +circle_datetime = eext_circle_object_datetime_add(datetime, surface);
      +
      + +

      Activating a Rotary Event

      + +

      You can activate and deactivate the circle datetime by using the eext_rotary_object_event_activated_set() function. If the second parameter is EINA_TRUE, the circle datetime can receive the rotary event. Otherwise, the circle datetime cannot receive the rotary event.

      +
      +eext_rotary_object_event_activated_set(circle_datetime, EINA_TRUE);
      +
      + +

      Using the Circle Object Property

      + +

      A circle datetime has the following styles:

      +
        +
      • default
      • +
      +

      When created, the circle datetime has default style automatically.

      + +

      The circle datetime objects support the following circle object API calls:

      +
        +
      • eext_circle_object_line_width_set()
      • +
      • eext_circle_object_line_width_get()
      • +
      • eext_circle_object_radius_set()
      • +
      • eext_circle_object_radius_get()
      • +
      • eext_circle_object_color_set()
      • +
      • eext_circle_object_color_get()
      • +
      • eext_circle_object_disabled_set()
      • +
      • eext_circle_object_disabled_get()
      • +
      +

      A circle datetime has the following item:

      +
        +
      • default: Default circle item that draws a marker.
      • +
      + +

      You can change the properties of the items by using the eext_circle_object_item* APIs.

      +

      For more information, see the Efl Extension Circle Datetime API.

      + +

      Circle Genlist

      + +

      Figure: Circle Genlist

      +

      Circle Genlist

      + +

      Use the circle genlist to visualize and utilize the scroll effect for elm_genlist. While elm_genlist provides a scrollbar with straight horizontal and vertical movement, the circle genlist provides scrollbar with circular movement. It is also operated with rotary events to move to the next or previous item.

      + +

      Creating a Circle Genlist

      + +

      A genlist and a surface are necessary when creating the circle genlist. The circle genlist is added with the eext_circle_object_genlist_add() function.

      +
      +Evas_Object *genlist, *circle_genlist, *parent;
      +
      +genlist = elm_genlist_add(parent);
      +circle_genlist = eext_circle_object_genlist_add(genlist, surface);
      +
      + +

      Configuring the Circle Genlist

      + +

      You can set the circle genlist scroller policy by using the eext_circle_object_genlist_scroller_policy_set() function.

      +
      +eext_circle_object_genlist_scroller_policy_set(circle_genlist, 
      +                                               ELM_SCROLLER_POLICY_OFF, 
      +                                               ELM_SCROLLER_POLICY_ON);
      +
      +

      This sets the scrollbar visibility policy of a given scroller. ELM_SCROLLER_POLICY_AUTO indicates the scrollbar is made visible if it is needed, and otherwise is kept hidden. ELM_SCROLLER_POLICY_ON turns the scrollbar on all the time, and ELM_SCROLLER_POLICY_OFF turns it off. This applies to the horizontal and vertical scrollbars respectively.

      +

      The following enum values are available for circle genlist.

      +
        +
      • ELM_SCROLLER_POLICY_AUTO
      • +
      • ELM_SCROLLER_POLICY_ON
      • +
      • ELM_SCROLLER_POLICY_OFF
      • +
      + +

      Activating a Rotary Event

      + +

      You can activate and deactivate the circle genlist by using the eext_rotary_object_event_activated_set() function. If the second parameter is EINA_TRUE, the circle genlist can receive the rotary event. Otherwise, the circle genlist cannot receive the rotary event.

      +
      +eext_rotary_object_event_activated_set(circle_genlist, EINA_TRUE);
      +
      + +

      Using the Circle Object Property

      + +

      Circle genlist objects support the following circle object API calls:

      +
        +
      • eext_circle_object_line_width_set()
      • +
      • eext_circle_object_line_width_get()
      • +
      • eext_circle_object_radius_set()
      • +
      • eext_circle_object_radius_get()
      • +
      • eext_circle_object_color_set()
      • +
      • eext_circle_object_color_get()
      • +
      • eext_circle_object_disabled_set()
      • +
      • eext_circle_object_disabled_get()
      • +
      +

      A circle genlist has the following item:

      +
        +
      • default: Default circle item. It draws vertical scroll bar.
      • +
      • vertical,scroll,bg: Vertical scroll background circle item.
      • +
      +

      You can change the properties of the items by using the eext_circle_object_item* APIs.

      +

      For more information, see the Efl Extension Circle Genlist API.

      + + + +

      Circle Object

      + +

      A circle object extends elementary components in a form of circular design. Sometimes, a circle object merely provides additional UI features to elementary component, and sometimes it works as an independent component with UI and functionalities.

      + +

      Creating a Circle Object

      + +

      You can use the eext_circle_object_add() function to create a circle object. When creating a circle object, you can choose whether the circle object is rendered by itself or by the circle surface. If the circle surface is passed as an argument, a circle object connected with circle surface is created, and it is rendered by the circle surface.

      +
      +Evas_Object *circle_obj;
      +
      +circle_obj = eext_circle_object_add(parent, surface);
      +
      + +

      When NULL is passed as a surface argument, the new circle object is managed and rendered by itself. Here, a circle object without a circle surface is created and showed in a size of 360 x 360.

      +
      +Evas_Object *circle_obj;
      +
      +circle_obj = eext_circle_object_add(parent, NULL);
      +evas_object_size_hint_min_set(circle_obj, 360, 360);
      +evas_object_show(circle_obj);
      +
      + +

      Setting the Line Width

      + +

      You can set the line width of the circle object by using the eext_circle_object_line_width_set() function. Here, circle object with a surface is created and its line width set to 20. You can get the current line width of a circle object by using the eext_circle_object_line_width_get() function.

      +
      +Evas_Object *circle_obj;
      +
      +circle_obj = eext_circle_object_add(parent, surface);
      +eext_circle_object_line_width_set(circle_obj, 20);
      +
      + +

      You can set the line width of a certain item in a circle object by using the eext_circle_object_item_line_width_set() function. If the name of the item is passed as default, it works the same way as the eext_circle_object_line_width_set() function. Similar to the above example, a circle object with a surface is created and its line width is set to 20. You can get the current line width of the item by using the eext_circle_object_item_line_width_get() function.

      +
      Evas_Object *circle_obj;
      +
      +circle_obj = eext_circle_object_add(parent, surface);
      +eext_circle_object_item_line_width_set(circle_obj, "default", 20);
      +
      + +

      Setting the Angle

      + +

      You can set the angle of the circle object by using the eext_circle_object_angle_set() function. Here, circle object with surface is created and its angle set to a 45.0 degree angle. You can get the current angle of a circle object by using the eext_circle_object_angle_get() function.

      +
      +Evas_Object *circle_obj;
      +
      +circle_obj = eext_circle_object_add(parent, surface);
      +eext_circle_object_angle_set(circle_obj, 45.0);
      +
      + +

      You can set the angle of a certain item in a circle object by using the eext_circle_object_item_angle_set() function. If name of the item is passed as default, it works the same way as eext_circle_object_angle_set() function. Similar to the above example, a circle object with surface is created and its angle is set to a 45.0 degree angle. You can get the current angle of the item by using the eext_circle_object_item_angle_get() function.

      +
      +Evas_Object *circle_obj;
      +
      +circle_obj = eext_circle_object_add(parent, surface);
      +eext_circle_object_item_angle_set(circle_obj, "default", 45.0);
      +
      + +

      Setting the Angle Offset

      + +

      You can set the angle offset of the circle object by using the eext_circle_object_angle_offset_set() function. Here, a circle object with a 45.0 degree angle is created and its angle offset set to 30.0 degrees. As a result, the circle object has an arch of 45.0 degree angle line starting from 30.0 degrees to 75.0 degrees. You can get the current angle offset of a circle object by using the eext_circle_object_angle_offset_get() function.

      +
      +Evas_Object *circle_obj;
      +
      +circle_obj = eext_circle_object_add(parent, surface);
      +eext_circle_object_angle_set(circle_obj, 45.0);
      +eext_circle_object_angle_offset_set(circle_obj, 30.0);
      +
      + +

      You can set the angle offset of a certain item in a circle object by using the eext_circle_object_item_angle_offset_set() function. If name of the item is passed as default, it works the same way as eext_circle_object_angle_offset_set() function. The following code works the same way as in the above example. You can get the current angle of the item by using the eext_circle_object_item_angle_offset_get() function.

      +
      +Evas_Object *circle_obj;
      +
      +circle_obj = eext_circle_object_add(parent, surface);
      +eext_circle_object_item_angle_set(circle_obj, "default", 45.0); 
      +eext_circle_object_item_angle_offset_set(circle_obj, "default", 30.0);
      +
      + +

      Setting the Minimum and Maximum Angle

      + +

      You can set the minimum and maximum angle of the circle object by using the eext_circle_object_angle_min_max_set() function. Here, a circle object with a surface is created and its minimum angle set to 0.0 degrees and maximum angle to 90.0 degrees. You can get the current minimum and maximum angle of the circle object by using the eext_circle_object_angle_min_max_get() function.

      +
      +Evas_Object *circle_obj;
      +
      +circle_obj = eext_circle_object_add(parent, surface);
      +eext_circle_object_angle_min_max_set(circle_obj, 0.0, 90.0);
      +
      + +

      You can set the minimum and maximum angles of a certain item in a circle object by using the eext_circle_object_item_angle_min_max_set() function. If name of the item is passed as default, it works the same way as the eext_circle_object_angle_min_max_set() function. Similar to the above example, a circle object with a minimum and maximum angles of 0.0 and 90.0 is created. You can get the current minimum and maximum angle of the item by using the eext_circle_object_item_angle_min_max_get() function.

      +
      +Evas_Object *circle_obj;
      +
      +circle_obj = eext_circle_object_add(parent, surface);
      +eext_circle_object_item_angle_min_max_set(circle_obj, "default", 0.0, 90.0);
      +
      + +

      Setting the Minimum and Maximum Value

      + +

      You can set the minimum and maximum values of the circle object by using the eext_circle_object_value_min_max_set() function. Here, a circle object with a surface is created and its minimum value is set to 0.0 degrees and maximum value to 10.0 degrees. You can get the current minimum and maximum value of the circle object by using the eext_circle_object_value_min_max_get() function.

      +
      +Evas_Object *circle_obj;
      +
      +circle_obj = eext_circle_object_add(parent, surface);
      +eext_circle_object_value_min_max_set(circle_obj, 0.0, 10.0);
      +
      + +

      You can set the value of a certain item in a circle object by using the eext_circle_object_item_angle_min_max_set() function. If name of the item is passed as default, it works the same way as the eext_circle_object_value_min_max_set() function. Similar to the above example, a circle object with a minimum and maximum value of 0.0 to 10.0 degrees is created. You can get the current minimum and maximum values of the item by using the eext_circle_object_item_value_min_max_get() function.

      +
       
      +Evas_Object *circle_obj;
      +
      +circle_obj = eext_circle_object_add(parent, surface);
      +eext_circle_object_item_value_min_max_set(circle_obj, "default", 0.0, 10.0);
      +
      + +

      Setting the Value

      + +

      You can set the value of the circle object by using the eext_circle_object_value_set() function. Here, a circle object with a surface is created and its value set to 5.0. You can get the current value of the circle object by using the eext_circle_object_value_get() function.

      +
      +Evas_Object *circle_obj;
      +
      +circle_obj = eext_circle_object_add(parent, surface);
      +eext_circle_object_value_set(circle_obj, 5.0);
      +
      + +

      You can set the value of a certain item in a circle object by using the eext_circle_object_item_value_set() function. If name of the item is passed as default, it works the same as the eext_circle_object_value_set() function. Similar to the above example, a circle object with a surface is created and its value is set to 5.0 degree angle. You can get the current value of the item by using the eext_circle_object_item_value_get() function.

      +
      +Evas_Object *circle_obj;
      +
      +circle_obj = eext_circle_object_add(parent, surface);
      +eext_circle_object_item_value_set(circle_obj, "default", 5.0);
      +
      + + + + + + + + + + +
      Note
      The value cannot be lower than the minimum value or higher than the maximum value.
      + +

      Setting the Color

      + +

      You can set the color of the circle object by using the eext_circle_object_color_set() function. To set the color, red, green, blue, and alpha values in range from 0 to 255 must be passed. Here, a circle object with a surface is created and its color set to blue. You can get the current color of circle object by using the eext_circle_object_color_get() function.

      +
      +Evas_Object *circle_obj;
      +
      +circle_obj = eext_circle_object_add(parent, surface);
      +eext_circle_object_color_set(circle_obj, 255, 0, 0, 255);
      +
      + +

      You can set the color of a certain item in a circle object by using the eext_circle_object_item_color_set() function. If name of the item is passed as default, it works the same way as the eext_circle_object_color_set() function. Similar to the above example, a circle object with a surface is created and its color is set to red. You can get the current color of the item by using the eext_circle_object_item_color_get() function.

      +
      +Evas_Object *circle_obj;
      +
      +circle_obj = eext_circle_object_add(parent, surface);
      +eext_circle_object_item_value_set(circle_obj, "default", 255, 0, 0, 255);
      +
      + +

      Setting the Radius

      + +

      You can set the radius of the circle object by using the eext_circle_object_radius_set() function. Here, a circle object with radius of 50.0 is created. You can get the current radius of the circle object by using the eext_circle_object_radius_get() function.

      +
      +Evas_Object *circle_obj;
      +
      +circle_obj = eext_circle_object_add(parent, surface);
      +eext_circle_object_radius_set(circle_obj, 50.0);
      +
      + +

      You can set the radius of a certain item in a circle object by using the eext_circle_object_item_radius_set() function. If name of the item is passed as default, it works the same way as the eext_circle_object_radius_set() function. Similar to the above example, a circle object with a radius of 50.0 is created. You can get the current radius of the item by using the eext_circle_object_item_radius_get() function.

      +
      +Evas_Object *circle_obj;
      +
      +circle_obj = eext_circle_object_add(parent, surface);
      +eext_circle_object_item_radius_set(circle_obj, "default", 50.0);
      +
      + +

      Disabling a Circle Object

      + +

      You can disable the circle object by using the eext_circle_object_disabled_set() function. Here, a circle object is disabled. You can get the current disabled status of circle object by using the eext_circle_object_disabled_get() function.

      +
      +Evas_Object *circle_obj;
      +
      +circle_obj = eext_circle_object_add(parent, surface);
      +eext_circle_object_disabled_set(circle_obj, EINA_TRUE);
      +
      + +

      You can enable a disabled circle object by using the eext_circle_object_disabled_set() function with EINA_FALSE argument.

      +
      +eext_circle_object_disabled_set(circle_obj, EINA_FALSE);
      +
      + + + + +

      Circle Progressbar

      + +

      Figure: Circle Progressbar

      +

      Circle Progressbar

      + +

      The circle progressbar aims to show the progress status of a given task with circular design. It visualizes the progress status within a range.

      + +

      Creating a Circle Progressbar

      + +

      You can create the circle progressbar by using the eext_circle_object_progressbar_add() function. When creating the circle progressbar, a surface is necessary to render on the surface.

      +
      +Evas_Object *circle_progressbar, *parent;
      +circle_progressbar = eext_circle_object_progressbar_add(parent, surface);
      +
      + +

      Using the Circle Object Property

      +

      Circle progressbar supports the following circle object API calls:

      +
        +
      • eext_circle_object_value_min_max_set()
      • +
      • eext_circle_object_value_min_max_get()
      • +
      • eext_circle_object_value_set()
      • +
      • eext_circle_object_value_get()
      • +
      • eext_circle_object_angle_min_max_set()
      • +
      • eext_circle_object_angle_min_max_get()
      • +
      • eext_circle_object_angle_offset_set()
      • +
      • eext_circle_object_angle_offset_get()
      • +
      • eext_circle_object_angle_set()
      • +
      • eext_circle_object_angle_get()
      • +
      • eext_circle_object_line_width_set()
      • +
      • eext_circle_object_line_width_get()
      • +
      • eext_circle_object_radius_set()
      • +
      • eext_circle_object_radius_get()
      • +
      • eext_circle_object_color_set()
      • +
      • eext_circle_object_color_get()
      • +
      • eext_circle_object_disabled_set()
      • +
      • eext_circle_object_disabled_get()
      • +
      +

      A circle progressbar has the following items:

      +
        +
      • default: Default circle item that draws the progressbar.
      • +
      • bg: Progress bar background circle item.
      • +
      +

      You can change the properties of the items by using the eext_circle_object_item* APIs.

      +

      For more information, see the Efl Extension Circle Progressbar API.

      + +

      Configuring Circle Progressbar

      + +

      Before using the circle progressbar, its minimum and maximum values are set with the eext_circle_object_value_min_max_set() function. The current value is set with eext_circle_object_value_set().

      +

      Here, the minimum value is set to 0.0, the maximum value to 100.0, and the current value to 3.0.

      +
      +eext_circle_object_value_min_max_set(circle_progressbar, 0.0, 100.0);
      +eext_circle_object_value_set(circle_progressbar, 3.0);
      +
      + +

      Circle Scroller

      + +

      Figure: Circle Scroller

      +

      Circle Scroller

      + +

      The circle scroller changes corresponding to the rotary events. It shows the whole scrollable area with a circular scroll bar. It wraps the elm_scroller internally only to draw a circular scroll bar to the edge of the circular screen. This means you can use elm_scroller callbacks and APIs excluding elm_scroller_policy_set() and elm_scroller_policy_get() APIs.

      + +

      Creating a Circle Scroller

      + +

      To create a circle scroller, use the eext_circle_object_scroller_add() function. elm_scroller has to be passed by the first parameter of this function.

      +
      +Evas_Object *scroller;
      +Evas_Object *circle_scroller;
      +
      +scroller = elm_scroller_add(parent);
      +circle_scroller = eext_circle_object_scroller_add(scroller, surface);
      +
      + +

      Activating the Rotary Event

      + +

      You can activate and deactivate the circle scroller by using the eext_rotary_object_event_activated_set() function. If the second parameter is EINA_TRUE, the circle scroller can receive the rotary event. Otherwise, the circle scroller cannot receive the rotary event.

      +
      +eext_rotary_object_event_activated_set(circle_scroller, EINA_TRUE);
      +
      + +

      Using the Circle Object Property

      + +

      A circle scroller has the following styles:

      +
        +
      • default
      • +
      +

      When created, the circle scroller has default style automatically.

      + +

      Circle scroller objects support the following circle object API calls:

      +
        +
      • eext_circle_object_line_width_set()
      • +
      • eext_circle_object_line_width_get()
      • +
      • eext_circle_object_radius_set()
      • +
      • eext_circle_object_radius_get()
      • +
      • eext_circle_object_color_set()
      • +
      • eext_circle_object_color_get()
      • +
      • eext_circle_object_disabled_set()
      • +
      • eext_circle_object_disabled_get()
      • +
      +

      A circle slider has the following items:

      +
        +
      • default: Default circle item that draws the vertical scroll bar.
      • +
      • vertical,scroll,bg: Vertical scroll background circle item.
      • +
      • horizontal,scroll,bar: Horizontal scroll bar circle item.
      • +
      • horizontal,scroll,bg : Horizontal scroll background circle item.
      • +
      +

      You can change the properties of the items by using the eext_circle_object_item* APIs.

      +

      For more information, see the Efl Extension Circle Scroller API.

      + +

      Configuring the Circle Scroller

      + +

      You can use elm_scroller APIs to configure a circle scroller, except elm_scroller_policy_set() and elm_scroller_policy_get() APIs.

      +

      Instead of excluded APIs, eext_circle_object_scroller_policy_set() and eext_circle_object_scroller_policy_get() functions are provided for the circle scroller.

      +

      A policy parameter has the following value.

      +
        +
      • ELM_SCROLLER_POLICY_AUTO: indicates the scrollbar is made visible if it is needed, and otherwise is kept hidden.
      • +
      • ELM_SCROLLER_POLICY_ON: Turns the scrollbar on all the time.
      • +
      • ELM_SCROLLER_POLICY_OFF: Turns the scrollbar off. This applies to the horizontal and vertical scrollbars respectively.
      • +
      +

      The following example shows how to set the scroll bar visibility policy to ELM_SCROLLER_POLICY_AUTO for horizontal scroll bar and ELM_SCROLLER_POLICY_OFF for vertical scroll bar.

      +
      +eext_circle_object_scroller_policy_set(circle_scroller, ELM_SCROLLER_POLICY_AUTO, ELM_SCROLLER_POLICY_OFF);
      +
      + +

      Circle Slider

      + +

      Figure: Circle Slider

      +

      Circle Slider

      + +

      The circle slider changes corresponding to rotary events. The circle slider not only extends the UI feature of the elm_slider, but also replaces the functionalities of the elm_slider in a circular design.

      + +

      Adding an Eext Slider object

      + +

      To create a circle slider, use the eext_circle_object_slider_add() function.

      +
      +Evas_Object *circle_slider = NULL;
      +circle_slider = eext_circle_object_slider_add(parent, surface);
      +
      + +

      Activating the Rotary Event

      + +

      You can activate or deactivate the circle slider by using the eext_rotary_object_event_activated_set() function. If the second parameter is EINA_TRUE, the circle slider can receive the rotary event. Otherwise, the circle slider cannot receive the rotary event.

      +
      +eext_rotary_object_event_activated_set(circle_slider, EINA_TRUE);
      +
      + +

      Using the Circle Slider Property

      + +

      A circle slider has the following styles:

      +
        +
      • default
      • +
      + +

      When created, the circle slider has default style automatically.

      +

      Circle slider objects support the following circle object API calls:

      +
        +
      • eext_circle_object_value_min_max_set()
      • +
      • eext_circle_object_value_min_max_get()
      • +
      • eext_circle_object_value_set()
      • +
      • eext_circle_object_value_get()
      • +
      • eext_circle_object_angle_min_max_set()
      • +
      • eext_circle_object_angle_min_max_get()
      • +
      • eext_circle_object_angle_offset_set()
      • +
      • eext_circle_object_angle_offset_get()
      • +
      • eext_circle_object_angle_set()
      • +
      • eext_circle_object_angle_get()
      • +
      • eext_circle_object_line_width_set()
      • +
      • eext_circle_object_line_width_get()
      • +
      • eext_circle_object_radius_set()
      • +
      • eext_circle_object_radius_get()
      • +
      • eext_circle_object_color_set()
      • +
      • eext_circle_object_color_get()
      • +
      • eext_circle_object_disabled_set()
      • +
      • eext_circle_object_disabled_get()
      • +
      +

      A circle slider has the following items:

      +
        +
      • default: Default circle item, It draws slider bar.
      • +
      • bg: Background circle item.
      • +
      +

      You can change the properties of the items by using eext_circle_object_item* APIs.

      +

      For more information, see the Efl Extension Circle Slider API.

      + +

      Configuring the Circle Slider

      + +

      The circle slider step value is used when the rotary event increases or decreases the circle slider value. It can be set with the eext_circle_object_slider_step_set() function.

      +

      Here, the step value is set to 0.5.

      +
      +eext_circle_object_slider_step_set(circle_slider, 0.5);
      +
      +

      Before using the circle slider, its minimum and maximum values are set with eext_circle_object_value_min_max_set(). The current value is set with eext_circle_object_value_set().

      +

      Here, the minimum value is set to 0.0, the maximum value to 15.0, and the current value to 3.0.

      +
      +eext_circle_object_value_min_max_set(circle_slider, 0.0, 15.0);
      +eext_circle_object_value_set(circle_slider, 3.0);
      +
      +

      You can retrieve the current value of the circle slider with the eext_circle_object_value_get() function.

      +
      +double value = eext_circle_object_value_get(circle_slider);
      +
      + +

      Using Circle Slider Callbacks

      + +

      The circle slider emits the following signal:

      +
        +
      • value,changed: The rotary event changes the circle slider value.
      • +
      +

      For this signal, event_info is NULL.

      +

      This is how to register a callback on the value,changed signal.

      +
      +{
      +   evas_object_smart_callback_add(slider, "value,changed", _value_changed_cb, data);
      +}
      +
      +// Callback function for the "value,changed" signal
      +// This callback is called when a value of the circle slider is changed
      +static void
      +_value_changed_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   dlog_print(DLOG_INFO, LOG_TAG, "Circle slider value changed. \n");
      +}
      +
      + +

      Circle Surface

      + +

      The circle surface manages and renders circle objects. Multiple circle objects can be connected to one circle surface as candidates of an object to be rendered. When one of circle objects is set as visible, the surface renders the circle object and hides the others.

      + +

      Creating a Circle Surface

      + +

      To create a new circle surface:

      +
      +Eext_Circle_Surface *surface;
      +Evas_Object *conformant;
      +
      +conformant = elm_conformant_add(parent);
      +surface = eext_circle_surface_conformant_add(conformant);
      +
      + +

      The eext_circle_surface_conformant_add() function creates a circle surface in the conformant layer. If you want to create a circle surface in the layout layer, use the eext_circle_surface_layout_add() function:

      +
      +Eext_Circle_Surface *surface;
      +Evas_Object *layout;
      +
      +layout = elm_layout_add(parent);
      +surface = eext_circle_surface_layout_add(layout); 
      +
      + +

      If you want to create a circle surface in the naviframe layer, use the eext_circle_surface_naviframe_add() function:

      +
      +Eext_Circle_Surface *surface;
      +Evas_Object *naviframe;
      +
      +naviframe = elm_naviframe_add(parent);
      +surface = eext_circle_surface_naviframe_add(naviframe); 
      +
      + + + + + + + + + + +
      Note
      A circle surface is a non-graphical object. It adds no graphics to or around the objects it holds.
      + +

      Adding Circle Objects to the Circle Surface

      + +

      You can add any circle object to a circle surface. The following example shows how to create an eext_slider component and add it to a circle surface in conformant layer:

      +
      +Eext_Circle_Surface *surface;
      +Evas_Object *slider;
      +
      +surface = eext_circle_surface_conformant_add(conformant);
      +slider = eext_circle_object_slider_add(parent, surface);
      +
      + +

      Deleting Circle Surface

      + +

      Deleting an Evas object automatically deletes the circle surface in the same layer. However, you can explicitly use the eext_circle_surface_del() function to delete a circle surface.

      +
      +eext_circle_surface_del(surface);
      +
      + + + + + + + + + + +
      Note
      The eext_circle_surface_del() function does not delete the connected circle objects.
      + + + +
      + +Go to top + + + + + + + \ No newline at end of file diff --git a/org.tizen.ui.guides/html/native/efl/component_custom_n.htm b/org.tizen.ui.guides/html/native/efl/component_custom_n.htm new file mode 100755 index 0000000..d3f8043 --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/component_custom_n.htm @@ -0,0 +1,557 @@ + + + + + + + + + + + + + Customizing Components + + + + + +
      + +

      Customizing Components

      + + +

      Elementary UI components use the Edje library EDC themes to manage their look.

      + +

      Elementary Theme

      + +

      An Elementary theme is an Edje EDC file that contains groups composed of parts and programs. For more information about Edje, see Theme.

      + +

      Using Theme Styles

      + +

      Elementary UI components provide a way to modify only some parts of the styles using the default theme. A style is a part of the EDC theme (a group) that concerns only one UI component. For example, you can create a new style for a button component to change its appearance without modifying the default theme.

      + + + + + + + + + + +
      Note
      When creating a new style, knowledge of how each UI component is themed is required, because setting another style always replaces the entire group used by the UI component. Important signals and parts must be there for the object to behave properly.
      + +

      When several styles are loaded in the current theme, you can set a different style to a specific UI component using the elm_object_style_set() function. It is also possible to see the current style with the elm_object_style_get() function.

      + +

      The default theme specifies several styles for the button component. The code below shows how to set the "anchor" style of a newly created button component.

      + +
      +Evas_Object *parent, *button;
      +
      +// Create a button object 
      +button = elm_button_add(parent);
      +
      +// Set its style to "anchor""
      +elm_object_style_set(button, "anchor");
      +
      + +

      Loading Theme Styles

      + +

      Once written and compiled with Edje tools, the Elementary provides two methods to load the style in the application theme:

      +
        +
      • overlays
      • +
      • extensions
      • +
      + +

      When looking for a theme, the Elementary checks the list of overlays, if any are defined. Then it takes the default theme, and if it cannot find a theme for the UI component, it looks at the extensions list.

      + +

      Overlay

      + +

      An overlay can replace the look of all UI components by overriding the default style. If we create a new style called "default" for the button component and add it as an overlay, the Elementary uses the overlay for all button components overriding the default theme.

      + +

      Here is how to add an overlay to your application's theme.

      + +
      +elm_theme_overlay_add(NULL, "./theme_button.edj");
      +
      + + + + + + + + + + +
      Note
      Here we assume that the "theme_button.edj" file only contains a new theme for the button component.
      + + + + + + + + + + +
      Note
      Doing this is not recommended. Adding a file as an overlay makes the Elementary use the new theme for all the button components defined in the application. You must make sure that the "theme_button.edj" file reimplements everything that was previously defined in the default theme concerning the button component.
      + +

      This is how to remove the previously added overlay to return to the default theme.

      + +
      +elm_theme_overlay_del(NULL, "./theme_button.edj");
      +
      + +

      Extension

      + +

      With extensions, we can write styles that we can apply to some UI components (not all of them) by using the elm_object_style_set() function.

      + +

      The application adds a theme to the list of extensions with the following call.

      + +
      +elm_theme_extension_add(NULL, "./theme_button_style_custom.edj");
      +
      + + + + + + + + + + +
      Note
      Here we assume that the "theme_button_style_custom.edj" file contains a new button style called "custom".
      + +

      This is how to use the new "custom" style on a button component.

      + +
      +Evas_Object *parent, *button;
      +
      +// Create a button object 
      +button = elm_button_add(parent);
      +
      +// Set its style to "custom" 
      +elm_object_style_set(button, "custom");
      +
      + + + + + + + + + + +
      Note
      When using elm_theme_extension_add or elm_theme_overlay_add to add a new theme extension or overlay to a Theme object (here called the default theme), the Elementary calls the elm_theme_flush function to flush Elementary theme caches. Thus, the theme of all UI components that use the default theme is reloaded.
      + +

      Creating a New Theme

      + +

      This is how to create a new theme object.

      + +
      +Elm_Theme *new_theme = elm_theme_new();
      +
      + +

      This function creates an empty specific theme that only uses the default theme. It has its own private set of extensions and overlays (which are empty by default). Specific themes do not fall back to the themes of parent objects. They are not intended for this use.

      + +

      This is how to apply this theme to a UI component and its children (a button, for example).

      + +
      +// Create a button component 
      +Evas_Object *button = elm_button_add();
      +
      +// Set the new theme to the button component 
      +elm_object_theme_set(button, new_theme);
      +
      + +

      Customizing a UI Component Style

      + +

      UI component themes are written in Edje EDC source files (.edc). These files are compiled with Edje tools to make an .edj file that is used by the application. For more information on using the EDC language, see Theme.

      + +

      A new Edje style can be added for a UI component. The best way is to copy the existing "default" style, rename it, and update it to your needs.

      + +

      Creating a Customized Style for the Check Component

      + +

      As an example, we show how to create a new style for the check component. The aim is to update the background and the main pictures of this UI component with custom pictures.

      + +

      The EDC source file concerning the check component (check.edc file) is composed of several groups.

      + +
      +group 
      +{
      +   name: "elm/check/base/default";
      +}
      +
      +group 
      +{
      +   name: "elm/check/base/toggle";
      +}
      +
      + +

      Those two groups define two different styles for the check component (the "default" style and the "toggle" style).

      + +

      We copy the group corresponding to the "default" style in a new file to create a new style called "custom". This new style is saved in the "check_custom.edc" file.

      + +
      +group 
      +{
      +   name: "elm/check/base/custom";
      +   // Here is the copy of the content of "default" style 
      +}
      +
      + +

      In the new group ("elm/check/base/custom"), we have to find the parts we want to modify. Here, the appropriate parts are "bg" and "check" parts.

      + +
      +part 
      +{
      +   name: "bg";
      +   mouse_events: 0;
      +   scale: 1;
      +   description 
      +   {
      +      state: "default" 0.0;
      +      rel1.offset: 1 1;
      +      rel2.relative: 0.0 1.0;
      +      rel2.offset: 1 -2;
      +      align: 0.0 0.5;
      +      min: 16 16;
      +      max: 16 16;
      +      aspect: 1.0 1.0;
      +      aspect_preference: VERTICAL;
      +      image 
      +      {
      +         normal: "check_base.png";
      +         border: 5 5 5 5;
      +         middle: 0;
      +      }
      +      fill.smooth: 0;
      +   }
      +}
      +part 
      +{
      +   name: "check";
      +   mouse_events: 0;
      +   scale: 1;
      +   description 
      +   { 
      +      state: "default" 0.0;
      +      rel1 
      +      {
      +         to: "bg";
      +         offset: 1 1;
      +      }
      +      rel2 
      +      {
      +         to: "bg";
      +         offset: -2 -2;
      +      }
      +      visible: 0;
      +      color: 255 255 255 255;
      +      image.normal: "check.png";
      +   }
      +   description 
      +   {
      +      state: "visible" 0.0;
      +      inherit: "default" 0.0;
      +      visible: 1;
      +   }
      +   description 
      +   {
      +      state: "disabled" 0.0;
      +      inherit: "default" 0.0;
      +      visible: 0;
      +      color: 128 128 128 128;
      +   }
      +   description 
      +   {
      +      state: "disabled_visible" 0.0;
      +      inherit: "default" 0.0;
      +      color: 128 128 128 128;
      +      visible: 1;
      +   }
      +}
      +
      + +

      We do not detail all the options that can be modified here, but assume that the user is familiar with Edje and knows Edje basics.

      + +

      Our custom pictures filenames are:

      +
        +
      • check_base_custom.png for the bg part
      • +
      • check_custom.png for the check part
      + +

      We must update the image.normal attribute in both parts with our custom pictures filenames to modify the pictures of this style.

      + +
      +part 
      +{
      +   name: "bg";   
      +   description 
      +   {
      +      state: "default" 0.0;
      +
      +      image 
      +      {
      +         normal: "check_base_custom.png";
      +         border: 5 5 5 5;
      +         middle: 0;
      +      }
      +                
      +   }
      +}
      +part 
      +{
      +   name: "check";
      +        
      +   description 
      +   {
      +      state: "default" 0.0;
      +            
      +      image.normal: "check_custom.png";
      +   }
      +        
      +}
      +
      + + + + + + + + + + +
      Note
      Here, we assume that the custom images are the same size as the "default" images.
      + +

      Adding the Theme File to Your Project

      + +

      Once written, the check_custom.edc file is put in the /res/edje/. directory of the application project in the SDK.

      + +

      When building the application, the SDK calls the Edje tools automatically to build the final check_custom.edj file. This file can be loaded from our application.

      + +

      Using the New Style

      + +

      This is how to add the new theme file as an extension in the application.

      + +
      +char edj_path[PATH_MAX] = {0, };
      +
      +// Get the full path of the edj file 
      +app_get_resource("/edje/check_custom.edj", edj_path, (int)PATH_MAX);
      +
      +// Load check custom style as an extension 
      +elm_theme_extension_add(NULL, edj_path);
      +
      + +

      Use the "custom" style on a new check component.

      + +
      +Evas_Object *parent, *check;
      +
      +// Create a check object 
      +check = elm_check_add(parent);
      +
      +// Set its style to "custom" 
      +elm_object_style_set(check, "custom");
      +
      + +

      Special Theme Parts

      + +

      Some parts of the EDC file can be interacted with the Elementary. The content of parts of the type TEXT are modified using the elm_object_part_set_text() function. The content of SWALLOW parts is updated using the elm_object_part_content_set() function.

      + +

      Swallow Parts

      + +

      In the previous example (the check component "default" style), there is a part called "elm.swallow.content" that is of the type SWALLOW.

      + +
      +part 
      +{
      +   name: "elm.swallow.content";
      +   type: SWALLOW;
      +   scale: 1;
      +   description 
      +   {
      +      state: "default" 0.0;
      +      fixed: 1 0;
      +      visible: 0;
      +      align: 0.0 0.5;
      +      rel1.to_x: "bg";
      +      rel1.relative: 1.0 0.0;
      +      rel1.offset: 1 1;
      +      rel2.to_x: "bg";
      +      rel2.offset: 1 -2;
      +      rel2.relative: 1.0 1.0;
      +   }
      +   description
      +   {
      +      state: "visible" 0.0;
      +      inherit: "default" 0.0;
      +      fixed: 1 0;
      +      visible: 1;
      +      aspect: 1.0 1.0;
      +      min: 16 16;
      +   }
      +   description 
      +   {
      +      state: "disabled" 0.0;
      +      inherit: "default" 0.0;
      +      color: 255 255 255 128;
      +   }
      +   description 
      +   {
      +      state: "disabled_visible" 0.0;
      +      inherit: "default" 0.0;
      +      color: 255 255 255 128;
      +      fixed: 1 0;
      +      visible: 1;
      +      aspect: 1.0 1.0;
      +   }
      +}
      +
      + +

      We can push content (Evas_Object) to this part from the application anytime. The size and position of the content pushed is controlled by the EDC theme.

      + +
      +Evas_Object *parent, *check1, *content;
      +
      +// Create a check object 
      +check1 = elm_check_add(parent);
      +
      +// Set the content of the check object 
      +elm_object_part_content_set(check1, "elm.swallow.content", content);
      +
      + + + + + + + + + + +
      Note
      We can add new SWALLOW parts when customizing a UI component's style, if we want to be able to control more content from the application. Note that removing existing SWALLOW parts changes the UI component's behavior.
      + +

      Text Parts

      + +

      The same is done with parts of the type TEXT. The check "default" style contains a part named "elm.text".

      + +
      +part 
      +{
      +   name: "elm.text";
      +   type: TEXT;
      +   mouse_events: 0;
      +   scale: 1;
      +   description
      +   {
      +      state: "default" 0.0;
      +      visible: 0;
      +      rel1.to_x: "elm.swallow.content";
      +      rel1.relative: 1.0 0.0;
      +      rel1.offset: 1 1;
      +      rel2.relative: 1.0 1.0;
      +      rel2.offset: -2 -2;
      +      color: 0 0 0 255;
      +      text 
      +      {
      +         font: "Sans,Edje-Vera";
      +         size: 10;
      +         min: 0 1;
      +         align: -1.0 0.5;
      +      }
      +   }
      +   description
      +   {
      +      state: "visible" 0.0;
      +      inherit: "default" 0.0;
      +      visible: 1;
      +      text.min: 1 1;
      +   }
      +   description 
      +   {
      +      state: "disabled" 0.0;
      +      inherit: "default" 0.0;
      +      color: 0 0 0 128;
      +      color3: 0 0 0 0;
      +   }
      +   description
      +   {
      +      state: "disabled_visible" 0.0;
      +      inherit: "default" 0.0;
      +      color: 0 0 0 128;
      +      color3: 0 0 0 0;
      +      visible: 1;
      +      text.min: 1 1;
      +   }
      +}
      +
      + +

      This is how to modify the content of the "elm.text" part from the application. The position of the text, its size, color, look and feel are managed by the EDC theme.

      + +
      +Evas_Object *parent, *check2;
      +
      +// Create a check object 
      +check2 = elm_check_add(parent);
      +
      +// Set the text of the check object 
      +elm_object_part_text_set(check2, "elm.text", "Test text");
      +
      + + + + + + + + + + +
      Note
      Except as noted, this content is licensed under LGPLv2.1+.
      + + + +
      + +Go to top + + + + + + + \ No newline at end of file diff --git a/org.tizen.ui.guides/html/native/efl/component_focus_n.htm b/org.tizen.ui.guides/html/native/efl/component_focus_n.htm new file mode 100755 index 0000000..ee8ae76 --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/component_focus_n.htm @@ -0,0 +1,174 @@ + + + + + + + + + + + + + Managing Component Focus + + + + + +
      + +

      Managing Component Focus

      + + +

      Focus is a graphical user interface concept. A component, for example, a UI component, has a focus when it is selected to receive input from the user. The input can be an event, such as mouse button click or key press. A UI component application has, at all times, one (and only one) focused object. This is what determines where the input event goes to within the application window. Also, focused objects can be decorated differently, in order to signal to the user where the input is at any given moment.

      + +

      Focusing can be immediate (selected by the touchscreen or mouse) or relative (selected by a key press). There are mainly 2 ways to set focus on a graphical elements:

      + +
        +
      • Direct selection: this is done by clicking on the element. +

        Direct selection does not really need any kind of special treatment as the user explicitly selects the UI component to interact with.

      • +
      • Relative selection: this is done by moving the selection from a UI component to another, such as going to the previous or next one; this is done with a keyboard. +

        Relative selection' default order is the one in which the UI components have been added to the canvas. That may not be appropriate, if they are added programmatically in a different order than they appear on-screen.

      • +
      + + +

      Moving Focus

      + +

      Concept of Focus Chain

      +

      The order the focus goes from a UI component to another is called the focus chain. As said before, the default focus chain is set to the order the UI components have been added to the canvas.

      + +

      Focusable Objects

      +

      An object can be focused if the following conditions apply:

      + +
        +
      • object is visible
      • +
      • object is enabled
      • +
      • object accepts focus
      • +
      • object's subtree (if any) is focusable
      • +
      • all of object's parents have their subtrees focusable
      • +
      + +

      If any of these conditions do not apply, the object is unfocusable.

      + +

      Handling Key Input

      + +

      Handling of the keys is done automatically by Elementary. According to which key the user pressed, Elementary switches the focus in the selected direction. For example, using the Tab key the focus goes to the next object in the natural order, whereas using the direction keys the focus goes to the next object in the requested direction.

      + +

      Hiding, Deleting or Disabling a Focused Object

      + +

      When a UI component is hidden, deleted, or disabled, it becomes unfocusable.

      + +

      When a focused object is unfocusable, the focus is moved to another object.

      + +

      Selecting Next Object

      + +

      When the user wants to switch the focus to the next object (i.e. cycle focus), Elementary searches the first object which is focusable.

      + +

      If there is a disabled or read-only object in the focus chain, the focus goes to the following object in the requested direction.

      + +

      Customizing Focus

      + +

      There are several reasons why to customize the focus chain of an application, for example:

      + +
        +
      • If you have created a form with labels and text entries next to them, the focus moves to the entry field when the user clicks on the associated label.
      • +
      • If you have created an interface with several columns (table), set the focus chain as you wish, for example, going horizontally instead of going vertically, regardless whatever the order the UI components are added.
      • +
      + +

      Customizing Object's Focus Exit Chain

      + +

      Set the object to focus after other object in a specific direction using elm_object_focus_next_object_set(object, next, direction). Use the following directions:

      + +
        +
      • ELM_FOCUS_NEXT: next UI component in natural order
      • +
      • ELM_FOCUS_PREVIOUS: previous UI component in natural order
      • +
      • ELM_FOCUS_UP: UI component to focus when going up
      • +
      • ELM_FOCUS_DOWN: UI component to focus when going down
      • +
      • ELM_FOCUS_RIGHT: UI component to focus when going right
      • +
      • ELM_FOCUS_LEFT: UI component to focus when going left
      • +
      + +

      Set the object next to another in a specific direction using elm_object_focus_next_object_get(object, direction).

      + +

      Customizing Whole Application's Focus Chain

      + +

      To customize the application's custom chain:

      + +
      +Evas_Object *main, obj1, obj2, obj3, obj4, obj5;
      +
      +Eina_List *focus_chain = NULL;
      +focus_chain = eina_list_append(focus_chain, obj3);
      +focus_chain = eina_list_append(focus_chain, obj2);
      +// The chain is obj3, then obj2. Set the chain.
      +elm_object_focus_custom_chain_set(main, focus_chain);
      +// Prepend obj5 at the beginning of the chain
      +elm_object_focus_chain_prepend(main, NULL, obj5);
      +// Append obj1 after obj3
      +elm_object_focus_chain_append(main, obj3, obj1);
      +// Prepend obj4 before obj1
      +elm_object_focus_chain_prepend(main, obj1, obj4);
      +
      + +

      The focus chain is obj5, obj3, obj4, obj1, obj2.

      + +

      This actually applies to any container: it is possible to set the focus chain of, for example, a box.

      + +

      Customizing Collision of Both

      + +

      If an object is part of a focus chain and has the next focused object defined, the next object takes precedence over the focus chain.

      + +

      Following on the previous example, if obj4 has obj5 defined as its next object, the actual focus chain is obj5, obj3, obj4, and loop back to obj5.

      + +

      Focus on UI Component

      + +

      If your Evas object has several sub-objects, set its focus chain using the same functions as for the application. Elementary first follows the main focus chain, and then the focus chain of each UI component if applicable.

      + +

      Use elm_object_focus_get(object) to set whether a specific object has the focus. Set the focus to an object using elm_object_focus_set(object, set), where set is a Boolean value. If it is set to EINA_TRUE, the focus is set to that given object. If it is set to EINA_False, the focus is unset and passed back to the previous element in the focus chain. Set the focus only after the object is shown, that is, after evas_object_show(object) has been called. Call the function back when the object receives or loses focus by registering on smart event "focused" or "unfocused"

      + +

      Use elm_object_tree_focus_allow_set(object, focusable) to tell Elementary whether an object and its children are focusable, where focusable is a Boolean value. Get the current value using elm_object_tree_focus_allow_get(object).

      + +

      The similar functions for a specific object are elm_object_focus_allow_set(object, focusable) and elm_object_focus_allow_get(object).

      + + + +
      + +Go to top + + + + + + + \ No newline at end of file diff --git a/org.tizen.ui.guides/html/native/efl/component_infra_n.htm b/org.tizen.ui.guides/html/native/efl/component_infra_n.htm new file mode 100755 index 0000000..0c9a0ff --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/component_infra_n.htm @@ -0,0 +1,69 @@ + + + + + + + + + + + + + UI Component Infrastructure Modules: Managing Component Properties + + + + + +
      + +

      UI Component Infrastructure Modules: Managing Component Properties

      + +

      The Elementary library is composed of many UI components to support Tizen native applications. While using UI components, you must manage their common properties. To meet this requirement, Elementary creates some infrastructure modules in order to support many UI components. Currently, Elementary provides following infrastructure modules:

      +
      • Component focus +

        A UI component application always has 1 focused object, which is selected to receive input from the user. The focus can change between objects, and the focused object can be decorated on the screen to make it easily visible.

      • +
      • Handling touch gestures for components +

        UI components generally handle basic touch inputs, such as press, release and moving. However, in some use cases (for example, when the accessibility Assistive Technology (AT) client is working), handling for a variety of touch gesture events (such as tap, double-tap, triple-tap, double-tap and hold, and left/right/up/down swipe) is needed. Elementary can also create new touch gesture patterns according to application use cases.

        +
      • +
      • Customizing components +

        Elementary provides basic UI components based on the Tizen UX styles which you can use. Usually, you can use the supported UI components themselves to make your application. However, if you need to use other styles than the basic ones, you must customize the UI component style.

      • +
      • UI mirroring +

        Elementary provides UI mirroring, which allows you to set UI mirroring on specific UI components or the whole interface. This facility is very useful to support applications which need both right-to-left and left-to-right languages.

      + + + + +
      + +Go to top + + + + + + + \ No newline at end of file diff --git a/org.tizen.ui.guides/html/native/efl/components_mn.htm b/org.tizen.ui.guides/html/native/efl/components_mn.htm new file mode 100755 index 0000000..8dd78aa --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/components_mn.htm @@ -0,0 +1,3350 @@ + + + + + + + + + + + + + + Using Mobile UI Components + + + + + + +
      +

      Using Mobile UI Components

      + + + + + + + + + + +
      Note
      This feature is supported in mobile applications only.
      + +

      Background

      + +

      Figure: Red color background

      +

      Red color background

      + +

      Figure: Background hierarchy

      +

      Background hierarchy

      + +

      The background component can be used to set a solid background decoration to a window or to a container object. It works like an image, but has some background specific properties, for example it can be set to a tiled, centered, scaled, or stretched mode. There are no specific signals relative to background object.

      + +

      Adding a Background Component

      + +

      A background is created with the elm_bg_add() function.

      + +
      +Evas_Object *bg, *parent;
      +
      +// Create a background
      +bg = elm_bg_add(parent);
      +
      + +

      Changing the Color of the Background

      + +

      You can set the color of the background with the elm_bg_color_set() function. The following example sets the background color to red.

      + +
      +Evas_Object *bg;
      +
      +// Use red color for background
      +elm_bg_color_set(bg, 0xFF, 0x00, 0x00);
      +
      + +

      Changing the Image of the Background

      + +

      It is also possible to set an image or an Edje group as a background using the elm_bg_file_set() function. The display mode of the image in the background can be chosen with elm_bg_option_set(), where the following modes are available:

      + +
        +
      • ELM_BG_OPTION_CENTER: center the background image.
      • +
      • ELM_BG_OPTION_SCALE: scale the background image, retaining aspect ratio.
      • +
      • ELM_BG_OPTION_STRETCH: stretch the background image to fill the UI component's area.
      • +
      • ELM_BG_OPTION_TILE: tile the background image at its original size.
      • +
      + +
      +Evas_Object *bg;
      +
      +// Set a file on the disk as a background image
      +elm_bg_file_set(bg, "/path/to/the/image", NULL);
      +// Set an Edje group as a background image
      +elm_bg_file_set(bg, "/path/to/the/edje", "edje_group");
      +elm_bg_option_set(bg, ELM_BG_OPTION_STRETCH)
      +
      + +

      Using Overlay

      + +

      An overlay can be set using the overlay part name.

      + +
      +elm_object_part_content_set(bg, "overlay", over);
      +
      + +

      Here, the overlay is an Edje object that is displayed on top of the current background object.

      + + +

      Button

      + +

      Figure: Button component

      +

      Button component

      + +

      Figure: Button hierarchy

      +

      Button hierarchy

      + +

      The Elementary button component is a simple push button. It is composed of a label icon and an icon object and has an autorepeat feature.

      + +

      Adding a Button Component

      + +

      Create a button.

      +
      +Evas_Object *button, *parent;
      +
      +// Create a button
      +button = elm_button_add(parent);
      + +

      Adding an Icon Inside a Button

      + +

      The icon can be updated with elm_object_part_content_set() function with the icon part name.

      + +
      +Evas_Object *ic;
      +ic = elm_icon_add(button);
      +elm_image_file_set(ic, "icon.png", NULL);
      +elm_object_part_content_set(button, "icon", ic);
      +
      + +

      Adding Text Inside a Button

      + +

      The label can be modified using the elm_object_text_set() function.

      + +
      +elm_object_text_set(button, "Click me!");
      +
      + +

      Using Button Styles

      + +

      Various styles can be used on the button. Tizen supports the following styles:

      + +
        +
      • icon_reorder
      • +
      • icon_expand_add
      • +
      • icon_expand_delete
      • +
      • default
      • +
      • circle
      • +
      • bottom
      • +
      • contacts
      • +
      • option
      • +
      + +

      You can see these themes in action on the following screenshot (in the above order).

      + +

      Figure: Button component

      +

      Button component

      + +

      To change the style of the button, call the elm_object_style_set() function on the button object.

      + +
      +elm_object_style_set(button,"icon_expand_add");
      +
      + +

      Using the Button Callbacks

      + +

      The button emits the following signals:

      + +
        +
      • clicked: The user clicked the button (press/release).
      • +
      • repeated: The user pressed the button without releasing it.
      • +
      • pressed: The user pressed the button.
      • +
      • unpressed: The user released the button after pressing it.
      • +
      + +

      For all these signals the event_info parameter returned in the callback is NULL.

      + +

      This is an example to register and define a callback function called by the clicked signal.

      + +
      +{
      +   evas_object_smart_callback_add(button, "clicked", clicked_cb, data);
      +}
      +// Callback function for the "clicked" signal
      +// This callback is called when the button is clicked by the user
      +void clicked_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   dlog_print(DLOG_INFO, LOG_TAG, "Button clicked\n");
      +}
      +
      + +

      Using the Autorepeat Feature

      + +

      The autorepeat feature is enabled by default. It consists of calling the repeated signal when the user keeps the button pressed. This feature can be disabled with the elm_button_autorepeat_set() function. The autorepeat is configured with the following functions:

      +
        +
      • elm_button_autorepeat_initial_timeout_set(): to set the initial timeout before the autorepeat event is generated
      • +
      • elm_button_autorepeat_gap_timeout_set(): to set the interval between two autorepeat events
      • +
      + +

      Disable the autorepeat feature.

      +
      +elm_button_autorepeat_set(button, EINA_FALSE);
      +
      + +

      Enable the autorepeat feature.

      +
      +elm_button_autorepeat_set(button, EINA_TRUE);
      +
      + +

      Set the initial timeout to five seconds.

      +
      +elm_button_autorepeat_initial_timeout_set(button, 5.0);
      +
      + +

      Set the gap between two signals to 0.5 seconds.

      +
      +elm_button_autorepeat_gap_timeout_set(button, 0.5);
      +
      + + +

      Check

      + +

      Figure: Check component

      +

      Check component

      + +

      Figure: Check hierarchy

      +

      Check hierarchy

      + +

      The check component is similar to the radio component, except that it does not work as a group. It toggles the value of a boolean between true and false.

      + +

      This UI component inherits from the layout component. All layout functions can be used on the check component.

      + +

      Adding a Check Component

      + +

      The following example shows how to create a check component.

      + +
      +Evas_Object *check, *parent;
      +check = elm_check_add(parent);
      +
      + +

      Modifying the Check Styles

      + +

      The check component style can be set with the elm_object_style_set() function. The following styles are available:

      +
        +
      • default
      • +
      • favorite
      • +
      • on and off
      • +
      + +

      The following example sets the favorite style on our check object.

      +
      +elm_object_style_set(check, "favorite");
      +
      + +

      To get the current style, use the elm_object_style_get() function.

      +
      +char *style = elm_object_style_get(check);
      +
      + +

      Using the Check Component

      + +

      After having created a check object, it is possible to set its boolean value to EINA_TRUE.

      +
      +elm_check_state_set(check, EINA_TRUE);
      +
      + +

      You can also retrieve the current value of the check object.

      +
      +Eina_Bool value = elm_check_state_get(check);
      +
      + +

      As with a radio object, an icon and a label can be set.

      +
      +// Create a Home icon 
      +Evas_Object *icon;
      +
      +icon = elm_icon_add(parent);
      +elm_icon_standard_set(icon, "home");
      +
      +// Set it to the check object 
      +elm_object_part_content_set(check, "icon", icon);
      +
      +// Set the check label 
      +elm_object_text_set(check, "Check label");
      +
      + +

      You can also modify the on and off labels.

      + +
      +elm_object_part_text_set(check, "on", "True");
      +elm_object_part_text_set(check, "off", "False");
      +
      + +

      The get functions of the elementary object API can be used to retrieve the content set to the check object.

      + +
      +// Get the current set text of the check label 
      +char *text = elm_object_text_get(check);
      +
      +// Get the content set in the icon part 
      +Evas_Object *icon = elm_object_part_content_get(check, "icon");
      +
      + +

      Using the Check Callbacks

      + +

      When the value is changed by the user, the changed signal is emitted. The event_info parameter is NULL.

      + +

      The following example shows how to register a callback on this signal.

      +
      +{
      +   evas_object_smart_callback_add(check, "changed", changed_cb, data);
      +}
      +
      +// Callback function for the "changed" signal
      +// This callback is called when the check value changes
      +void changed_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   dlog_print(DLOG_INFO, LOG_TAG, "The value has changed\n");
      +}
      +
      + +

      Colorselector

      + +

      Figure: Colorselector component

      +

      Colorselector component

      + +

      Figure: Colorselector hierarchy

      +

      Colorselector hierarchy

      + + +

      The colorselector component provides a color selection solution to the user. There are different modes available, each of them showing a different configuration of the colorselector component.

      + +

      Currently only the Palette mode is available in Tizen.

      +
        +
      • ELM_COLORSELECTOR_PALETTE
      • +
      + +

      The Palette mode displays several color items that enable the user to choose a color in the items displayed. It is possible to add new items, or to update the color of the current item. The list of color items is called a palette, and it is associated with a unique identifier. This enables the developers to create new series of colors (a new palette) and save it under another identifier. By default, the color palette is using the default identifier.

      + +

      This UI component inherits from the layout component, so all function concerning the layout component can also be used on the colorselector component.

      + +

      Adding a Colorselector Component

      + +

      The following example shows how to create a colorselector object.

      + +
      +Evas_Object *colorsel, *parent;
      +
      +colorsel = elm_colorselector_add(parent);
      +
      + +

      Setting the Colorselector Modes

      + +

      The following example shows how to set the mode of the colorselector to the palette mode.

      + +
      +elm_colorselector_mode_set(colorsel, ELM_COLORSELECTOR_PALETTE);
      +
      + +

      The following example shows how to create a new palette called mypalette. This new palette is saved by elementary config and you can to load it again later. You then add three colors in mypalette: red, green, and blue.

      + +
      +elm_colorselector_palette_name_set(colorsel, "mypalette");
      +elm_colorselector_palette_color_add(colorsel, 255, 0, 0, 255);
      +elm_colorselector_palette_color_add(colorsel, 0, 255, 0, 255);
      +elm_colorselector_palette_color_add(colorsel, 0, 0, 255, 255);
      +
      + +

      The default palette already contains 14 colors.

      + +
      +elm_colorselector_palette_name_set(colorsel, "default");
      +
      + +

      When the user clicks on the color elements, the element changes the color that is set to the colorselector component. You can use the following function to retrieve the current selected color.

      +
      +int r, g, b, a;
      +
      +elm_colorselector_color_get(colorsel, &r, &g, &b, &a);
      +
      + +

      Using the Colorselector Callbacks

      + +

      You can register callbacks on the following signals:

      + +
        +
      • changed - The color value changes on the selector. event_info is NULL.
      • +
      • color,item,selected - The user clicks on a color item. The event_info parameter of the callback is the selected color item.
      • +
      • color,item,longpressed - The user long presses on a color item. The event_info parameter of the callback contains the selected color item.
      • +
      + +

      The following example shows how to register a callback on the changed signal.

      +
      +{
      +   evas_object_smart_callback_add(colorselector, "changed", changed_cb, data);
      +}
      +
      +// Callback function for the "changed" signal
      +// This callback is called when the colorselector value changes
      +void changed_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   dlog_print(DLOG_INFO, LOG_TAG, "The color has changed\n");
      +}
      +
      + + +

      Ctxpopup

      + +

      Figure: Context popup component

      +

      Context popup component

      + +

      Figure: Context popup hierarchy

      +

      Context popup hierarchy

      + + +

      Ctxpopup is a contextual popup that can show a list of items.

      + +

      Adding a Ctxpopup Component

      + +

      A ctxpopup can be created with the elm_ctxpopup_add() function, and when shown, it automatically chooses an area inside its parent object's view (set using elm_ctxpopup_hover_parent_set()) to optimally fit into it.

      + +
      +Evas_Object *ctxpopup, *parent;
      +
      +// Create a ctxpopup 
      +ctxpopup = elm_ctxpopup_add(parent);
      +
      + +

      Modifying the Ctxpopup Style

      + +

      The following styles are available:

      + +
        +
      • dropdown/list
      • +
      • dropdown/label
      • +
      • more/default
      • +
      + +

      Figure: Context popup more/default style

      +

      Context popup more/default style

      + +

      Figure: Context popup dropdown/list

      +

      Context popup dropdown/list

      + +

      Figure: Context popup dropdown/label

      +

      Context popup dropdown/label

      + +

      The following example shows how to set the more/default style.

      + +
      +elm_object_style_set(ctxpopup, "more/default");
      +
      + +

      Configuring the Ctxpopup

      + +

      The context popup orientation can be set with elm_ctxpopup_horizontal_set(). Here it is set to horizontal.

      +
      +elm_ctxpopup_horizontal_set(ctxpopup, EINA_TRUE);
      +
      + +

      Auto hide is enabled by default. You can also disable auto hiding if you want the ctxpopup never to be hidden.

      +
      +elm_ctxpopup_auto_hide_disabled_set(ctxpopup, EINA_TRUE);
      +
      + +

      Managing the Ctxpopup Items

      + +

      The ctxpopup can contain a small number of items. Each of them can have a label and an icon. The following example shows how to append an item with the Test label and no icon.

      +
      +Elm_Object_Item *it;
      +
      +it = elm_ctxpopup_item_append(ctxpopup, "test", NULL, _ctxpopup_item_cb,
      +                  NULL);
      +
      + +

      The _ctxpopup_item_cb() callback is called when the item is clicked. The following example shows how to write the definition of this callback.

      +
      +static void
      +_ctxpopup_item_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   dlog_print(DLOG_INFO, LOG_TAG, "ctxpopup item selected\n");
      +}
      +
      + +

      After that the item label is set to New label.

      + +
      elm_object_item_part_text_set(it, "default", "New label");
      +
      + +

      And its icon is modified to the standard home icon.

      + +
      +Evas_Object *home_icon = elm_icon_add(ctxpopup);
      +elm_icon_standard_set(home_icon, "home");
      +
      +elm_object_item_part_content_set(it, "icon", home_icon);
      +
      + +

      Using the Ctxpopup Callbacks

      + +

      The context popup emits the dismissed signal when it is dismissed. You can register a callback to this signal. The event_info parameter is NULL.

      + +
      +{
      +   evas_object_smart_callback_add(ctxpopup, "dismissed", dismissed_cb, data);
      +}
      +
      +// Callback function for the "dismissed" signal
      +// This callback is called when the ctxpopup is dismissed
      +void dismissed_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   dlog_print(DLOG_INFO, LOG_TAG, "Ctxpopup dismissed\n");
      +}
      +
      + +

      Datetime

      + +

      Figure: Datetime selection

      +

      Datetime selection

      + +

      Figure: Datetime hierarchy

      +

      Datetime hierarchy

      + +

      The datetime component displays and adds date and time values.

      + +

      Adding a Datetime Component

      + +

      The UI component is created with elm_datetime_add(). It is possible to select the visible fields with elm_datetime_field_visible_set(). The following fields can be controlled:

      +
        +
      • ELM_DATETIME_YEAR: the year field
      • +
      • ELM_DATETIME_MONTH: the month field
      • +
      • ELM_DATETIME_DATE: the date field
      • +
      • ELM_DATETIME_HOUR: the hour field
      • +
      • ELM_DATETIME_MINUTE: the minute field
      • +
      • ELM_DATETIME_AMPM: the AM/PM field
      • +
      + +

      The following example shows how to create a datetime component and set the HOUR and MINUTE fields visible.

      + +
      +Evas_Object *datetime, *parent;
      +
      +datetime = elm_datetime_add(parent);
      +
      +elm_datetime_field_visible_set(datetime, ELM_DATETIME_HOUR, EINA_TRUE);
      +elm_datetime_field_visible_set(datetime, ELM_DATETIME_MINUTE, EINA_TRUE);
      +
      +elm_datetime_field_visible_set(datetime, ELM_DATETIME_YEAR, EINA_FALSE);
      +elm_datetime_field_visible_set(datetime, ELM_DATETIME_MONTH, EINA_FALSE);
      +elm_datetime_field_visible_set(datetime, ELM_DATETIME_DATE, EINA_FALSE);
      +elm_datetime_field_visible_set(datetime, ELM_DATETIME_AMPM, EINA_FALSE);
      +
      + +

      Using the Datetime Styles

      + +

      The following styles are available:

      +
        +
      • date_layout
      • +
      • time_layout
      • +
      • time_layout_24h
      • +
      + +

      The following example creates the date_layout style:

      + +
      +elm_object_style_set(datetime, "date_layout");
      +
      + +

      Setting the Datetime Format

      + +

      The format of the date and time can be configured with elm_datetime_format_set() using a combination of allowed Libc date format specifiers. In the following example the format is set to HH : MM.

      + +
      +elm_datetime_format_set(datetime, "%H : %M");
      +
      + +

      Please refer to the API documentation for a complete list of all the options available.

      + +

      Using the Datetime Callbacks

      + +

      A callback can be registered on the changed signal to detect when the Datetime field values are changed. The event_info parameter is NULL.

      + +
      +{
      +   evas_object_smart_callback_add(datetime, "changed", changed_cb, data);
      +}
      +
      +// Callback function for the "changed" signal
      +// This callback is called when the datetime fields change
      +void changed_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   dlog_print(DLOG_INFO, LOG_TAG, "Datetime field changed. \n");
      +}
      + +

      The language,changed signal is emitted when the system locale changes.

      + + +

      UX Issue in Tizen 2.3

      + +
        +
      • date_layout (default): Year, Month, Day
      • +
      • time_layout: Hour, Minute, AM/PM button
      • +
      • time_layout_24hr: Hour, Minute
      • +
      + +

      Basically, the elm_datetime component needs a full-length format that includes the Year, Month, Day, Hour, Minute, and AM/PM. Each style then shows specific fields according their style, limited by the UX concept. If you call the elm_datetime_field_visible_set() function for a field that is not supported in the style, it does not work.

      + + +

      Entry

      + +

      Figure: Entry component

      +

      Entry component

      + +

      Figure: Entry component

      +

      Entry component

      + +

      Figure: Entry hierarchy

      +

      Entry hierarchy

      + +

      The entry component is a box where the user can enter text. It supports the following features:

      +
        +
      • text wrapping
      • +
      • multiline
      • +
      • scrolling
      • +
      • formatted markup text
      • +
      • password mode
      • +
      • filtering text
      • +
      • read/write from a file
      • +
      • theme style overrides
      • +
      + +

      Adding an Entry Component

      + +

      The entry component is created with the elm_entry_add() function, and the text inside the entry can be set with elm_entry_entry_set().

      + +
      +Evas_Object *entry, *parent;
      +
      +entry = elm_entry_add(parent);
      +elm_entry_entry_set(entry, "A short text.");
      +
      + +

      Using the Text Editor

      + +

      You can append text to the end of existing content.

      + +
      +elm_entry_entry_append(entry, "END");
      +
      + +

      You can also insert text at the current cursor position.

      + +
      +elm_entry_entry_insert(entry, "CURSOR");
      +Eina_Bool Empty = elm_entry_is_empty(entry);
      +
      + +

      Call elm_entry_is_empty() to see whether the entry is empty. Here, the boolean variable Empty returns EINA_FALSE.

      + +

      By default, the user can enter text in the entry component when it is in focus. It is possible to prevent the user from editing text if needed.

      + +
      +elm_entry_editable_set(entry, EINA_FALSE);
      +
      + + + + + + + + + + +
      Note
      It is still possible to use the previous functions to modify the text of a non-editable entry.
      + +

      Setting the Password Mode

      + +

      When dealing with password content, the password mode activates to hide what the user is typing. In this mode, the display of any text is replaced by asterisks (*), and the entry is single line (there is no line wrap).

      + +
      +elm_entry_password_set(entry, EINA_TRUE);
      +
      + +

      Entry Line Modes And Wrapping

      + +

      The entry component has two line modes:

      +
        +
      • single line mode
      • +
      • multiline mode
      • +
      + +

      First, set the entry in single line mode.

      + +
      +elm_entry_single_line_set(entry, EINA_TRUE);
      +
      + +

      In this mode, the text does not wrap when reaching the edge, but the entry grows horizontally instead. Pressing the Enter key in this mode generates an activate event instead of adding a new line.

      + +

      When the entry is set to multiline mode (single line off), the text wraps at the end of the entry and pressing Enter creates a new line.

      + +
      +elm_entry_single_line_set(entry, EINA_FALSE);
      +elm_entry_line_wrap_set(entry, ELM_WRAP_WORD);
      +
      + +

      In multiline entries, elm_entry_line_wrap_set() provides a way to cut the text implicitly into a new line when it reaches the far edge of the UI component. The following wrap modes are available:

      +
        +
      • ELM_WRAP_NONE: No wrap
      • +
      • ELM_WRAP_CHAR: Wrap between characters
      • +
      • ELM_WRAP_WORD: Wrap in allowed wrapping points (as defined in the unicode standard)
      • +
      • ELM_WRAP_MIXED: Word wrap, and if that fails, char wrap
      • +
      + +

      Selecting Text

      + +

      Text selections can be made with different functions:

      +
        +
      • To select all the content of the entry component: +
        +elm_entry_select_all(entry);
        +
        +
      • + +
      • To deselect the current selection: +
        +elm_entry_select_none(entry);
        +
        +
      • + +
      • To select part of the text, use elm_entry_select_region_set(). The following code selects the first twenty characters of the entry content. +
        +elm_entry_select_region_set(entry, 0, 20);
        +
        +
      • + +
      • To retrieve the currently selected text in an entry: +
        +const char *selection;
        +
        +selection = elm_entry_selection_get(entry);
        +
        +
      • +
      + +

      If the entry text is empty, elm_entry_selection_get() returns NULL.

      + +

      You can copy or cut the selection to the clipboard.

      +
      +elm_entry_selection_cut(entry);
      +
      + +

      The selection can be pasted in the same or a different entry.

      +
      +elm_entry_selection_paste(entry);
      +
      + +

      Controlling the Cursor

      + +

      The cursor represents the current position in the entry, where the next action, for example, text insertion or deletion, is done. Usually, the cursor is represented as a blinking character, but its appearance depends on the theme configuration. The cursor position can be modified by using several functions.

      +
        +
      • To move the cursor to the beginning of the entry: +
        +elm_entry_cursor_begin_set(entry);
        +
        +
      • + +
      • To move the cursor to the end of the entry: +
        +elm_entry_cursor_end_set(entry);
        +
        +
      • + +
      • To move the cursor one line down or up: +
        +elm_entry_cursor_down(entry);
        +elm_entry_cursor_up(entry);
        +
        +
      • +
      • To move the cursor one character to the left or right: +
        +elm_entry_cursor_prev(entry);
        +elm_entry_cursor_next(entry);
        +
        +
      • + +
      • To set the cursor at a specific position (15th character, for example): +
        +elm_entry_cursor_pos_set(entry, 15);
        +
        +
      • +
      + +

      It is possible to start a selection at the current cursor position, move five characters to the right and end the selection.

      + +
      +elm_entry_cursor_selection_begin(entry);
      +
      +for (i = 0; i < 5; i++)
      +{
      +   elm_entry_cursor_next(entry);
      +}
      +
      +elm_entry_cursor_selection_end(entry);
      +
      + +

      Formatting Text

      + +

      Text within an entry can be formatted by using markups tags that are defined in the theme. The following markups are available:

      +
        +
      • <br>: Inserts a line break.
      • +
      • <ps>: Inserts a paragraph separator. This is preferred over line breaks.
      • +
      • <tab>: Inserts a tab.
      • +
      • <em>...</em>: Emphasis. Sets the oblique style for the enclosed text.
      • +
      • <b>...</b>: Sets the bold style for the enclosed text.
      • +
      • <link>...</link>: Underlines the enclosed text.
      • +
      • <hilight>...</hilight>: Highlights the enclosed text.
      • +
      + +

      Using Special Markups

      + +

      Special markups can be added within the text of the entry:

      +
        +
      • <a href = ..>...</a>: Anchors
      • +
      • <item size = .. vsize = .. href = ..>...</item>: Items
      • +
      + +

      The anchors generate an anchor,clicked signal when the user clicks on them. The href attribute is used to identify the anchor. It also reacts to the anchor,in (mouse in), anchor,out (mouse out), anchor,down (mouse down), and anchor,up (mouse up) events.

      + +

      The item markup provides a way to insert any Evas_Object in the text. The Evas_Object name has to be specified in the href attribute.

      + +

      Overriding Style

      + +

      To tweak the style of the text within the entry component, it is possible to override parts of the theme style to the textblock object by using elm_entry_text_style_user_push(). This function pushes a new style on top of the user style stack that overrides the current style. Remove the style in the top of user style stack with elm_entry_text_style_user_pop().

      + +

      Filtering Text

      + +

      Text within an entry can be filtered in size. The following example sets the maximum number of characters allowed in the entry to 8.

      + +
      +static Elm_Entry_Filter_Limit_Size limit_size = 
      +{
      +   .max_char_count = 8,
      +   .max_byte_count = 0
      +};
      +
      +// Append a new callback to the list, this function is called each time
      +// a text is inserted in the entry. Pass the limit_size struct previously
      +// created to set the maximum number of characters allowed to 8
      + 
      +elm_entry_markup_filter_append(entry, elm_entry_filter_limit_size, limit_size);
      +
      + +

      The content can be filtered by passing an Elm_Entry_Filter_Accept_Set structure. This structure contains the accepted characters and rejected characters. The following example shows how to reject the '+', '-', '*', and '/' characters.

      +
      +static Elm_Entry_Filter_Accept_Set accept_set = 
      +{
      +   .accepted = NULL,
      +   .rejected = "+*-/"
      +};
      +
      +elm_entry_markup_filter_append(entry, elm_entry_filter_accept_set, accept_set);
      +
      + +

      Loading and Saving Files

      + +

      The entry content can be saved to a file (/tmp/test.txt, for example).

      + +
      +// Set the file in which the entry text is saved. This function
      +// implicitly loads the existing file content 
      +elm_entry_file_set(entry, "/tmp/test.txt", ELM_TEXT_FORMAT_MARKUP_UTF8);
      +
      + +

      Autosave is activated by default and changes are written back to the file after a short delay. This feature can be deactivated and you can manually save the content when needed.

      + +
      +// Disable autosaving 
      +elm_entry_autosave_set(entry, EINA_FALSE);
      +
      +// Trigger saving when needed 
      +elm_entry_file_save(entry);
      +
      + +

      Using Entry Theme Content

      + +

      Two content parts of the default theme are available: icon and end. The following example shows how to set an icon in the end content part.

      +
      +Evas_Object *icon;
      +
      +ic = elm_icon_add(entry);
      +elm_image_file_set(ic, "icon.png", NULL);
      +elm_object_part_content_set(entry, "end", icon);
      +
      + +

      Using Entry Theme Texts

      + +

      The default theme allows the use of the following text parts:

      +
        +
      • default - text of the entry
      • +
      • guide - placeholder of the entry
      • +
      + +

      The following example shows how to set the placeholder text of the entry to Hello World.

      + +
      +elm_object_part_text_set(entry, "Hello World");
      +
      + +

      Using Entry Callbacks

      + +

      The entry component emits the following signals:

      +
        +
      • aborted: The escape key is pressed on a single line entry.
      • +
      • activated: The enter key is pressed on a single line entry.
      • +
      • anchor,clicked: An anchor is clicked. event_info points to an object of the type Elm_Entry_Anchor_Info.
      • +
      • anchor,down: Mouse button is pressed on an anchor. event_info points to an object of the type Elm_Entry_Anchor_Info.
      • +
      • anchor,hover,opened: The anchor is clicked. event_info points to an object of the type Elm_Entry_Anchor_Info.
      • +
      • anchor,in: Mouse cursor is moved into an anchor. event_info points to an object of the type Elm_Entry_Anchor_Info.
      • +
      • anchor,out: Mouse cursor is moved out of an anchor. event_info points to an object of the type Elm_Entry_Anchor_Info.
      • +
      • anchor,up: Mouse button is unpressed on an anchor. event_info points to an object of the type Elm_Entry_Anchor_Info.
      • +
      • changed: The text within the entry is changed.
      • +
      • changed,user: The text within the entry is changed because of user interaction. event_info points to an object of the type Edje_Entry_Change_Info.
      • +
      • clicked: The entry is clicked (mouse press and release).
      • +
      • clicked,double: The entry is double clicked.
      • +
      • clicked,triple: The entry is triple clicked.
      • +
      • cursor,changed: The cursor position is changed.
      • +
      • cursor,changed,manual: The cursor position is changed manually.
      • +
      • focused: The entry receives focus. event_info points to an object of the type Elm_Focus_Info.
      • +
      • unfocused: The entry loses focus.
      • +
      • language,changed: Program language is changed.
      • +
      • longpressed: A mouse button is pressed and held for a couple of seconds.
      • +
      • maxlength,reached: A maximum length is reached.
      • +
      • preedit,changed: The preedit string is changed.
      • +
      • press: A mouse button is pressed on the entry.
      • +
      • redo,request: The request is redone.
      • +
      • selection,changed: The current selection is changed.
      • +
      • selection,cleared: The current selection is cleared.
      • +
      • selection,copy: A copy of the selected text into the clipboard is requested.
      • +
      • selection,cut: A cut of the selected text into the clipboard is requested.
      • +
      • selection,paste: A paste of the clipboard contents is requested.
      • +
      • selection,start: A selection is begun and no previous selection exists.
      • +
      • text,set,done: The whole text is set to the entry.
      • +
      • theme,changed: The theme is changed.
      • +
      • undo,request: The request is undone.
      • +
      + +

      For signals, where event_info has not been explicitly described, it is set to NULL.

      + +

      The following example shows how to register a callback to the focused signal.

      + +
      +{
      +   evas_object_smart_callback_add(entry, "focused", focused_cb, data);
      +}
      +
      +// Callback function for the "focused" signal
      +// This callback is called when the entry receive the focus
      +void focused_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   dlog_print(DLOG_INFO, LOG_TAG, "Entry focused\n");
      +} 
      +
      + + +

      Flip

      + +

      Figure: Flip hierarchy

      +

      Flip hierarchy

      + +

      The flip component can hold two Evas_Objects and allows the user flip between them using several pre-defined animations.

      + +

      Adding a Flip Component

      + +

      The following example shows how to create a flip component.

      + +
      +Evas_Object *flip, *parent, *content1, *content2;
      +flip = elm_flip_add(parent);
      +
      + +

      You can add content to the flip component. content1 is set to the front content and content2 is set to the back mode.

      + +
      +elm_object_part_content_set(flip, "front", content1);
      +elm_object_part_content_set(flip, "back", content2);
      +
      + +

      Configuring Flip Animation

      + +

      Now you can run an flip animation.

      +
      +elm_flip_go(flip, ELM_FLIP_CUBE_UP);
      +
      + +

      This animation flips up the front content object as if it was on a side of a cube, letting the down facing side of the cube appear with the back content object. Several animations are available:

      +
        +
      • ELM_FLIP_ROTATE_X_CENTER_AXIS: Rotate the content around a horizontal axis.
      • +
      • ELM_FLIP_ROTATE_Y_CENTER_AXIS: Rotate the content around a vertical axis.
      • +
      • ELM_FLIP_ROTATE_XZ_CENTER_AXIS: Rotate the content around a diagonal axis.
      • +
      • ELM_FLIP_ROTATE_YZ_CENTER_AXIS: Rotate the content around a diagonal axis.
      • +
      • ELM_FLIP_CUBE_LEFT: Rotate the content left as if it was on a side of a cube.
      • +
      • ELM_FLIP_CUBE_RIGHT: Rotate the content right as if it was on a side of a cube.
      • +
      • ELM_FLIP_CUBE_UP: Rotate the content up as if it was on a side of a cube.
      • +
      • ELM_FLIP_CUBE_DOWN: Rotate the content down as if it was on a side of a cube.
      • +
      • ELM_FLIP_PAGE_LEFT: Move the content to the left as if the flip was a book.
      • +
      • ELM_FLIP_PAGE_RIGHT: Move the content to the right as if the flip was a book.
      • +
      • ELM_FLIP_PAGE_UP: Move the content up as if the flip was a book.
      • +
      • ELM_FLIP_PAGE_DOWN: Move the content down as if the flip was a book.
      • +
      + +

      Interacting With the User

      + +

      By default, the user cannot interact with the flip. You can set the interaction to be possible, but you have to choose which animation appears on the interaction (rotation has been selected in the following example).

      + +
      +elm_flip_interaction_set(flip, ELM_FLIP_INTERACTION_ROTATE);
      +
      + +

      The available modes of interaction are

      +
        +
      • ELM_FLIP_INTERACTION_NONE: No interaction is allowed
      • +
      • ELM_FLIP_INTERACTION_ROTATE: Interaction causes a rotating animation
      • +
      • ELM_FLIP_INTERACTION_CUBE: Interaction causes a cube animation
      • +
      • ELM_FLIP_INTERACTION_PAGE: Interaction causes a page animation
      • +
      + +

      You must also choose which interaction directions are enabled. Only right and left are enabled in the following example.

      + +
      +elm_flip_interaction_direction_enabled_set(flip, ELM_FLIP_DIRECTION_LEFT, EINA_TRUE);
      +elm_flip_interaction_direction_enabled_set(flip, ELM_FLIP_DIRECTION_RIGHT, EINA_TRUE);
      +
      + +

      You can also set the amount of the flip that is sensitive to user interaction. In the following example, it is set to the entire flip (1) to make the flip easy to interact with.

      + +
      +elm_flip_interaction_direction_hitsize_set(flip, ELM_FLIP_DIRECTION_LEFT, 1);
      +elm_flip_interaction_direction_hitsize_set(flip, ELM_FLIP_DIRECTION_RIGHT, 1);
      +
      + +

      Using the Flip Callbacks

      + +

      Two signals are emitted by the flip: one when an animation starts and one when it ends. For these signals, event_info parameter is NULL.

      + +
      +"animate,begin" - A flip animation is started
      +"animate,done" - A flip animation is finished
      +
      + +

      You can register a callback on the "animation,begin" signal.

      + +
      +{
      +   evas_object_smart_callback_add(entry, "animate,begin", anim_start_cb, data);
      +}
      +
      +// Callback function for the "animate,begin" signal
      +// This callback is called when the flip animation starts
      +void anim_start_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   dlog_print(DLOG_INFO, LOG_TAG, "Animation starts\n");
      +}
      + +

      Gengrid

      + +

      Figure: Gengrid component

      +

      Gengrid component

      + +

      Figure: Gengrid hierarchy

      +

      Gengrid hierarchy

      + +

      Gengrid component is based on the same idea as the genlist. It aims at displaying objects on a grid layout and rendering only the visible ones. As for the genlist, callbacks are called at item creation or deletion.

      + +

      This UI component inherits from the layout component and implements the scroller interface. Because of this, the scroller and layout functions can be used with this UI component.

      + +

      A gengrid can display its items using a horizontal or vertical layout. In the first layout, the items are displayed in columns from top to bottom, starting a new column when the space for the current column is filled. In the second one, items are set in rows from left to right.

      + +

      Adding a Gengrid Component

      + +

      You can add a gengrid component with the following code.

      +
      +Evas_Object *gengrid, *parent;
      +gengrid = elm_gengrid_add(parent);
      +
      + +

      Gengrid Items

      + +

      A gengrid item is composed of 0 or more texts, 0 or more contents and 0 or more boolean states. The number of the text and content depends on the theme used for gengrid items. In the default Tizen gengrid item theme, items can have two content parts that can be set with the elm.swallow.icon and elm.swallow.end part names.

      + +

      Creating and Deleting Items

      + +

      As with genlists, the items are allocated and deleted on the go, while the user is scrolling the gengrid. The following example shows how to declare a Elm_Gengrid_Item_Class structure to inform the gengrid how to manage items.

      +
      +static Elm_Gengrid_Item_Class *gic = elm_gengrid_item_class_new();
      +gic->item_style = "default";
      +gic->func.text_get = _grid_label_get;
      +gic->func.content_get = _grid_content_get;
      +gic->func.state_get = _grid_state_get;
      +gic->func.del = _grid_del;
      +
      + +

      The parameters of this structure are not be detailed here, because they are very similar to that of the genlist. Please refer to the genlist component page for more detailed information.

      + +

      Managing Items

      + +

      As with genlists, items can be added with the elm_gengrid_item_append(), elm_gengrid_item_prepend(), elm_gengrid_item_insert_before(), and elm_gengrid_item_insert_after() functions. With the gengrid, there is no need to pass the type parameters. They can be cleared with the elm_gengrid_clear() function.

      + +

      You can set the multiselection mode on.

      +
      +elm_gengrid_multi_select_set(gengrid, EINA_TRUE);
      +
      + +

      When the multiselection mode is on, the selected items are retrieved with the elm_gengrid_selected_items_get() function. The function returns a list of all the selected items.

      + +

      When the content of an item changes, you can call elm_gengrid_item_update() to ask the gengrid to update this item's content.

      + +

      It is also possible to select or disable some items manually with the elm_gengrid_item_selected_set() and elm_object_item_disabled_set() functions.

      + +

      Using Gengrid Callbacks

      + +

      The gengrid component emits the following signals:

      +
        +
      • activated: The user has double-clicked or pressed (enter | return | spacebar) on an item. The event_info parameter is the gengrid item that is activated.
      • +
      • clicked,double: The user has double-clicked an item. The event_info parameter is the gengrid item that is double-clicked.
      • +
      • longpressed: The item is pressed for a certain amount of time. By default it is one second.
      • +
      • selected: The user has selected an item. The event_info parameter is the gengrid item that is selected.
      • +
      • unselected: The user has unselected an item. The event_info parameter is the gengrid item that is unselected.
      • +
      • realized: The item in the gengrid has its implementing Evas object instantiated, de facto. event_info is the gengrid item that is created. The object can be deleted at any time, so it is strongly advisable not to use the object pointer returned from elm_gengrid_item_object_get(), because it can point to freed objects.
      • +
      • unrealized: The implementing Evas object for this item is deleted. event_info is the gengrid item that is deleted.
      • +
      • changed: An item is added, removed, resized or moved and the gengrid is resized or has horizontal property changes.
      • +
      • scroll,anim,start: Scrolling animation starts.
      • +
      • scroll,anim,stop: Scrolling animation stops.
      • +
      • drag,start,up: The item in the gengrid is dragged (not scrolled) up.
      • +
      • drag,start,down: The item in the gengrid has dragged (not scrolled) down.
      • +
      • drag,start,left: The item in the gengrid is dragged (not scrolled) left.
      • +
      • drag,start,right: The item in the gengrid is dragged (not scrolled) right.
      • +
      • drag,stop: The item in the gengrid stops being dragged.
      • +
      • drag: The item in the gengrid is dragged.
      • +
      • scroll: The content is scrolled (moved).
      • +
      • scroll,drag,start: Dragging the content starts.
      • +
      • scroll,drag,stop: Dragging the content stops.
      • +
      • edge,top: The gengrid is scrolled to the top edge.
      • +
      • edge,bottom: The gengrid is scrolled to the bottom edge.
      • +
      • edge,left: The gengrid is scrolled to the left edge.
      • +
      • edge,right: The gengrid is scrolled to the right edge.
      • +
      + +

      Genlist

      + +

      Figure: Genlist component

      +

      Genlist component

      + +

      Figure: Genlist hierarchy

      +

      Genlist hierarchy

      + +

      Genlist is a UI component that displays a scrollable list of items. It allows a lot of entries while being fast and has a low memory footprint, as only the visible items are allocated in the memory.

      + +

      For more information, see Creating Mobile Genlists.

      + +

      Genlist Item Style

      + +

      An item can have 0 or more texts, 0 or more contents, and 0 or more boolean states. This is defined in the Edje item theme style. Genlist looks for data items named respectively labels, contents, and states in the Edje file. The default item style provides one text part (elm.text), two content parts (elm.swallow.icon and elm.swallow.end) and no state parts.

      + +

      The following item styles are available:

      +
        +
      • default
      • +
      • full
      • +
      • one_icon
      • +
      • end_icon
      • +
      • group_index
      • +
      • double_label
      • +
      + +

      Here are some examples of the item styles.

      + +

      Figure: Default item style

      +

      Default item style

      + +

      Figure: end_icon item style

      +

      end_icon item style

      + +

      Figure: double_label item style

      +

      double_label item style

      + +

      For more information on creating a new genlist item style, see Customizing Components.

      + +

      Adding a Genlist Component

      + +

      A genlist component is added with the elm_genlist_add() function.

      +
      +Evas_Object *genlist, *parent;
      +genlist = elm_genlist_add(parent);
      +
      + +

      Creating And Deleting Items

      + +

      To save up memory, genlist allocates and deletes items on the go, while the user is scrolling the list. To enable that, the user creates and fills a Elm_Genlist_Item_Class structure that informs the genlist component which callbacks to call when an item is created or deleted.

      + +
      +Elm_Genlist_Item_Class *itc = elm_genlist_item_class_new();
      +
      +itc->item_style = "default";
      +itc->decorate_item_style = NULL;
      +itc->decorate_all_item_style = NULL;
      +itc->func.text_get = _item_label_get;
      +itc->func.content_get = _item_content_get;
      +itc->func.state_get = _item_state_get;
      +itc->func.del = _item_del;
      +
      + +

      The item_style, decorate_item_style, and decorate_all_item_style attributes define the names of the item style, the decorate mode item style and the decorate all item style.

      + +

      The func structure contains pointers to functions that are called when an item is going to be created or deleted. All of them receive a data parameter that points to the same data passed to the elm_genlist_item_append() and related item creation functions, and an obj parameter that points to the genlist object itself.

      +
        +
      • text_get +

        This function receives a PART parameter that is the name string of one of the existing text parts in the Edje group implementing the item's theme. It has to return a string (duplicated with the strdup() function) corresponding to the PART parameter. The caller is in charge of freeing the string when done.

      • + +
      • content_get +

        The PART parameter is the name string of one of the existing swallow parts in the Edje group. When no content is desired, it must return NULL, or otherwise, a valid object handle. The object is deleted by the genlist on its deletion or when the item is unrealized.

      • + +
      • state_get +

        The PART parameter is the name string of one of the state parts in the Edje group implementing the item's theme. It returns EINA_FALSE for false/off or EINA_TRUE for true/on. The default is false. Genlists emit a signal to the PART parameter's theming Edje object with elm,state,xxx,active as emission and elm as source argument, when the state is true. xxx is the name of the (state) part.

      • + +
      • del +

        This function is called when the genlist item is deleted. It deletes any data that is allocated at the item creation.

      • +
      + +

      Managing Items

      + +

      To add an item, several functions can be used. elm_genlist_item_append() adds an item to the end of the list, or if there is a parent list, to the end of all the child items of the parent list. elm_genlist_item_prepend() is otherwise the same but adds to the beginning of the list or children lists. elm_genlist_item_insert_before() inserts an item before the indicated item and elm_genlist_item_insert_after() inserts an item after the indicated item.

      + +

      The previous functions take a type parameter that can be one of the following.

      +
        +
      • ELM_GENLIST_ITEM_NONE
      • +
      • ELM_GENLIST_ITEM_TREE
      • +
      • ELM_GENLIST_ITEM_GROUP
      • +
      + +

      If ELM_GENLIST_ITEM_TREE is set, this item is displayed as being able to expand and have child items. If ELM_GENLIST_ITEM_GROUP is set, this item is a group index item that is displayed at the top until the next group appears.

      + +

      Figure: Genlist tree

      +

      Genlist tree

      + +

      The application clears the list with elm_genlist_clear(), which deletes all the items in the list. elm_object_item_del() deletes a specific item. elm_genlist_item_subitems_clear() clears all items that are children of the indicated parent item.

      + +

      To help inspect the list items, move to the item at the top of the list with elm_genlist_first_item_get(), which returns the item pointer. elm_genlist_last_item_get() moves to the item at the end of the list. elm_genlist_item_next_get() and elm_genlist_item_prev_get() move to the next and previous items relative to the indicated item. Using these calls you can go through the entire item list or tree.

      + + + + + + + + + + +
      Note
      As a tree, the items are flattened on the list, so elm_genlist_item_parent_get() gives you the name of the parent item (even to skip them if needed).
      + +

      elm_genlist_item_show() scrolls the scroller to show the desired item as visible.

      +

      elm_object_item_data_get() returns the data pointer set by the item creation functions.

      + +

      If an item changes (state, boolean, text or content change), use elm_genlist_item_update() for the genlist to update the item. Genlist re-realizes the item and calls the functions in the _Elm_Genlist_Item_Class for it.

      + +

      Selection

      + +

      Items are manually selected or deselected with elm_genlist_item_selected_set() or disabled with elm_object_item_disabled_set(). In case there is a tree or a group item, the elm_genlist_item_expanded_set() function is used to expand or contract the item.

      + + + + + + + + + + +
      Note
      Calling this function does not show or hide any child of an item (if it is a parent). You must manually delete and create them on the callbacks of the expanded or contracted signals.
      + +

      By default, the genlist is in single-selection mode: only one item can be selected at a time. You can use elm_genlist_multi_select_set() to select multiple items. In the single-selection mode, the elm_genlist_selected_item_get() function can be called to retrieve the selected item. If several items are selected, the elm_genlist_selected_items_get() returns a list of the current selected items.

      + +

      In the following figure, there is a genlist in multi-selection mode with two items selected (#4 and #5) and one item disabled (#2).

      + +

      Figure: Genlist component

      +

      Genlist component

      + +

      Using Genlist Callbacks

      + +

      The genlist component emits the following signals:

      +
        +
      • activated: The user has double-clicked or pressed (enter | return | spacebar) on an item. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
      • +
      • clicked,double: The user has double-clicked an item. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
      • +
      • selected: The user selects an item. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
      • +
      • unselected: The user unselects an item. event_info in the callback function points at an object of type Elm_Object_Item that contains the activated item.
      • +
      • expanded: The item is to be expanded with elm_genlist_item_expanded_set(). This callback fills in the child items. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
      • +
      • contracted: The item is to be contracted with elm_genlist_item_expanded_set(). This callback deletes the child items. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
      • +
      • expand,request: The user wants to expand a tree branch item. The callback decides if the item can expand (if it has any children) and calls elm_genlist_item_expanded_set() to set the state. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
      • +
      • contract,request: The user wants to contract a tree branch item. The callback decides if the item can contract (if it has any children) and calls elm_genlist_item_expanded_set() to set the state. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
      • +
      • realized: The item is created as a real evas object. event_info in the callback function points at an object of the type Elm_Object_Item, that contains the activated item.
      • +
      • unrealized: An item is going to be unrealized. Content objects provided are deleted and the item object is deleted or put into a floating cache. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
      • +
      • drag,start,up: The item in the list is dragged (not scrolled) up. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
      • +
      • drag,start,down: The item in the list is dragged (not scrolled) down. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
      • +
      • drag,start,left: The item in the list is dragged (not scrolled) left. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
      • +
      • drag,start,right: The item in the list is dragged (not scrolled) right. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
      • +
      • drag,stop: The item in the list has stopped being dragged. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
      • +
      • drag: The item in the list is being dragged. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
      • +
      • longpressed: The item is pressed for a certain amount of time. The default specified time is one second. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
      • +
      • scroll,anim,start: The scrolling animation is started. event_info is NULL.
      • +
      • scroll,anim,stop: The scrolling animation is stopped. event_info is NULL.
      • +
      • scroll,drag,start: Dragging the content is started. event_info is NULL.
      • +
      • scroll,drag,stop: Dragging the content is stopped. event_info is NULL.
      • +
      • edge,top: The genlist is scrolled to the top edge. event_info is NULL.
      • +
      • edge,bottom: The genlist is scrolled to the bottom edge. event_info is NULL.
      • +
      • edge,left: The genlist is scrolled to the left edge. event_info is NULL.
      • +
      • edge,right: The genlist is scrolled to the right edge. event_info is NULL.
      • +
      • multi,swipe,left: The genlist is multi-touch swiped left. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
      • +
      • multi,swipe,right: The genlist is multi-touch swiped right. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
      • +
      • multi,swipe,up: The genlist is multi-touch swiped up. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
      • +
      • multi,swipe,down: The genlist is multi-touch swiped down. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
      • +
      • multi,pinch,out: The genlist is multi-touch pinched out. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
      • +
      • multi,pinch,in: The genlist is multi-touch pinched in. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
      • +
      • swipe: The genlist is swiped. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
      • +
      • moved: A genlist item is moved in the reorder mode. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
      • +
      • moved,after: A genlist item is moved after another item in the reorder mode. To access the relative previous item, use elm_genlist_item_prev_get(). This signal is called along with the moved signal. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
      • +
      • moved,before: A genlist item is moved before another item in the reorder mode. To access the relative previous item, use elm_genlist_item_next_get(). This signal is called along with the moved signal. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
      • +
      • language,changed The program's language is changed. event_info is NULL.
      • +
      • tree,effect,finished: A genlist tree effect is finished. event_info is NULL.
      • +
      + + +

      GLView

      + +

      Figure: GLView gears example

      +

      GLView gears example

      + +

      Figure: GLView hierarchy

      +

      GLView hierarchy

      + + +

      The GLView component renders OpenGL in an elementary object, which hides Evas GL complexity. For more information, see OpenGL ES.

      + +

      Adding a GLView Component

      + +

      Create a GLView component with the elm_glview_add() function.

      +
      +Evas_Object *glview, *parent;
      +
      +glview = elm_glview_add(parent);
      +
      + +

      In this example, the size of the GLView is set to 200x200 pixels.

      +
      +elm_glview_size_set(glview, 200, 200);
      +
      + +

      Using the GLView API

      + +

      You can configure the GLView rendering mode by activating the following rendering modes:

      + +
        +
      • ELM_GLVIEW_ALPHA: Alpha channel rendering mode
      • +
      • ELM_GLVIEW_DEPTH: Depth buffer rendering mode
      • +
      • ELM_GLVIEW_STENCIL: Stencil buffer rendering mode
      • +
      • ELM_GLVIEW_DIRECT: Direct rendering mode
      • +
      • ELM_GLVIEW_CLIENT_SIDE_ROTATION: The client handles the GL view rotation if direct rendering is enabled
      • +
      + +

      In the following example, the alpha channel and depth buffer rendering mode are enabled.

      +
      +elm_glview_mode_set(glview, ELM_GLVIEW_ALPHA | ELM_GLVIEW_DEPTH);
      +
      + +

      The following example shows how to decide what to do with the GL surface when the GLView component is resized.

      +
      +elm_glview_resize_policy_set(glview, ELM_GLVIEW_RESIZE_POLICY_RECREATE);
      +
      + +

      The GL surface is destroyed and recreated to the new size (default function). The resize policy can also be set to ELM_GLVIEW_RESIZE_POLICY_SCALE. In that case, only the image object is scaled, not the underlying GL surface.

      + +

      The following example shows how to set the GLView rendering policy.

      +
      +elm_glview_render_policy_set(glview, ELM_GLVIEW_RENDER_POLICY_ALWAYS);
      +
      + +

      The GLView object is always redrawn during the rendering loop. It can also be set to ELM_GLVIEW_RENDER_POLICY_ON_DEMAND (default function), where the GLView component is redrawn only when it is visible.

      + +

      Register the callbacks:

      + +
      elm_glview_init_func_set(glview, _init_gl_cb);
      +elm_glview_del_func_set(glview, _del_gl_cb);
      +elm_glview_resize_func_set(glview, _resize_gl_cb);
      +elm_glview_render_func_set(glview, _draw_gl_cb);
      +
      + +
        +
      • elm_glview_init_func_set() registers an init callback that is called at the GLView object creation.
      • +
      • elm_glview_del_func_set() registers a del function that is called when the GLView object is deleted.
      • +
      • elm_glview_resize_func_set() registers the resize function that is called during the rendering loop when the GLView object is resized.
      • +
      • elm_glview_render_func_set() registers the render function that is called when the GLView object must be redrawn.
      • +
      + +

      Using GLView Callbacks

      + +

      The GLView component emits the following signals:

      + +
        +
      • focused: The Glview component is focused. The event_info parameter points at an object of the type Elm_Focus_Info.
      • +
      • unfocused: The GLView object is unfocused.
      • +
      + +

      To register a callback:

      +
      +{
      +   evas_object_smart_callback_add(glview, "focused", focused_cb, data);
      +}
      +
      +// Callback function for the "focused" signal
      +// This callback is called when the GLView is focused
      +void focused_cb(void *data, Evas_Object *obj, void  *event_info)
      +{
      +   Elm_Focus_Info *fi = event_info;
      +
      +   dlog_print(DLOG_INFO, LOG_TAG, "GLView is focused\n");
      +}
      +
      + +

      Icon

      + +

      Figure: Icon component

      +

      Icon component

      + +

      Figure: Icon hierarchy

      +

      Icon hierarchy

      + +

      The icon component inherits from the image component. It is used to display images in an icon context.

      + +

      Adding an Icon Component

      + +

      You can create an icon and set it as a freedesktop.org Home standard icon.

      + +
      +Evas_Object *icon, *parent;
      +icon = elm_icon_add(parent);
      +elm_icon_standard_set(icon, "Home");
      +
      + +

      Changing Image File

      + +

      You can change the image by using an image in the filesystem (for example, /tmp/Home.png).

      +
      +elm_image_file_set(icon, "/tmp/Home.png", NULL);
      +
      + +

      You can also use a group in an Edje file (for example, /tmp/Home.edj).

      +
      +elm_image_file_set(icon, "/tmp/Home.edj", "elm/icon/Home/default");
      +
      + +

      A thumbnail can be generated and cached for future use. For this, you need the Ethumb library support.

      + +
      +elm_icon_thumb_set(icon, "/tmp/Home.png", NULL);
      +
      + +

      This function sets the file in the icon and enables the use of a cached thumbnail if it already exists. Otherwise, it creates a new thumbnail and caches it for future use.

      + +

      Using Icon Callbacks

      + +

      The icon component emits the following signals:

      +
        +
      • thumb,done: elm_icon_thumb_set() is completed with success.
      • +
      • thumb,error: elm_icon_thumb_set() fails.
      • +
      + +

      In both cases, event_info is NULL.

      + + +

      Image

      + +

      Figure: Image component

      +

      Image component

      + +

      Figure: Image hierarchy

      +

      Image hierarchy

      + +

      The image component can load and display an image from a disk file or a memory region.

      + +

      Adding an Image Component

      + +

      This object is created with elm_image_add().

      + +
      +Evas_Object *image, *parent;
      +image = elm_image_add(parent);
      +
      + +

      Configuring the Image Component

      + +

      Various properties of the image can be tuned. First, you can disable the elementary scaling so that the image does not scale but resizes on both directions.

      +
      +elm_image_no_scale_set(image, EINA_TRUE);
      +elm_image_resizable_set(image, EINA_TRUE, EINA_TRUE);
      +
      + +

      When scaling images, the smooth scaling algorithm can be used. It provides a better quality image but is slower than the default algorithm.

      +
      +elm_image_smooth_set(image, EINA_TRUE);
      +
      + +

      Preloading is used to load images without blocking the user interface. This preserves the reactivity of the user experience. The image is loaded in a thread. It can be disabled if desired.

      +
      +elm_image_preload_disabled_set(image, EINA_TRUE);
      +
      + +

      The image can be rotated or flipped. Here the image is rotated 180 degrees.

      +
      +elm_image_orient_set(image, ELM_IMAGE_ROTATE_180);
      +
      + +

      The following orientations are available:

      +
        +
      • ELM_IMAGE_ORIENT_0: No orientation change
      • +
      • ELM_IMAGE_ROTATE_90: Rotate the image 90 degrees clockwise
      • +
      • ELM_IMAGE_ROTATE_180: Rotate the image 180 degrees clockwise
      • +
      • ELM_IMAGE_ROTATE_270: Rotate the image 90 degrees counter-clockwise
      • +
      • ELM_IMAGE_FLIP_HORIZONTAL: Flip the image horizontally
      • +
      • ELM_IMAGE_FLIP_VERTICAL: Flip the image vertically
      • +
      • ELM_IMAGE_FLIP_TRANSPOSE: Flip the image along the bottom-left to top-right line
      • +
      • ELM_IMAGE_FLIP_TRANSVERSE: Flip the image along the top-left to bottom-right line
      • +
      + +

      If you want to keep the original aspect ration when resizing the image, you must define how the image fits into the object's area.

      +
      +// Tell the image to keep original aspect ratio 
      +elm_image_aspect_fixed_set(image, EINA_TRUE);
      +// Then let the image fill the entire object 
      +elm_image_fill_outside_set(image, EINA_TRUE);
      +
      + +

      In this configuration, part of the image can go outside the object. If elm_image_fill_outside_set is set to EINA_FALSE, the image stays inside the limits of the parent object.

      + +

      Using Image Callbacks

      + +

      The image component emits the following signals:

      +
        +
      • drop: The user drops an image typed object onto the object in question - the event info argument is the path to that image file
      • +
      • clicked: The user clicks the image. event_info is NULL.
      • +
      + +

      To register a callback when a user clicks on the image:

      +
      +{
      +   evas_object_smart_callback_add(image, "clicked", clicked_cb, data);
      +}
      +
      +// Callback function for the "clicked" signal
      +// This callback is called when the image is clicked
      +void clicked_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   dlog_print(DLOG_INFO, LOG_TAG, "Image clicked\n");
      +}
      +
      + +

      Index

      + +

      Figure: Index component

      +

      Index component

      + +

      Figure: Index hierarchy

      +

      Index hierarchy

      + +

      An index component gives you an index for fast access to whichever group of other UI items you have. The index component is by default hidden, but it appears when the user clicks over its reserved area in the canvas. In the default theme, it is a one finger wide area on the right side of the index component's container. Generally, an index is used together with lists, generic lists, or generic grids.

      + +

      Adding an Index Component

      + +

      Call the elm_index_add() function to create a new index component.

      +
      +Evas_Object *index, *parent;
      +index = elm_index_add(parent);
      +
      + +

      Adding Items

      + +

      The following example shows how to add the listitem object at the letter A, calling the smart callback it_select_cb() when this item is selected.

      +
      +Elm_Object_Item *list_item1, *list_item2;
      +elm_index_item_append(index, "A", it_select_cb, list_item1);
      +
      + +

      The following example shows how to define the smart callback.

      +
      +// Callback function called when the list_item1 object
      +// is selected
      +void it_select_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   dlog_print(DLOG_INFO, LOG_TAG, "Item1 selected\n");
      +}
      +
      + +

      In the previous case, the indexes are appended to the existing ones. It is also possible to prepend index items with elm_index_item_prepend().

      + +

      Sorting Index Items

      + +

      You can insert index items using a sorting function. Indexes can be sorted, for example, by alphabetic order.

      + +

      You must write a compare function that returns a positive int, 0 or a negative int when the data2 item parameter is respectively greater than, equal to or lower than the data1 parameter.

      + +
      +static int
      +_index_icmp(const void *data1,
      +      const void *data2)
      +{
      +   int result;
      +
      +   // Code that does the item comparison is written here
      +
      +   return result;
      +}
      +
      + +

      This example shows how to add a new item at the B index using the compare function to sort the indexes.

      + +
      +elm_index_item_sorted_insert(index, "B", NULL, list_item2, _index_icmp, NULL);
      +
      + +

      Using Index Callbacks

      + +

      The index component emits the following signals:

      +
        +
      • changed: The selected index item changes. event_info is the selected item's data pointer.
      • +
      • delay,changed: The selected index item changes, but after a small idling period. event_info is the selected item's data pointer.
      • +
      • selected: The user releases a mouse button and selects an item. event_info is the selected item's data pointer.
      • +
      • level,up: The user moves a finger from the first level to the second level.
      • +
      • level,down: The user moves a finger from the second level to the first level.
      • +
      + +

      When the user selects an item in the index, the selected signal is emitted. The developer can then implement the associated callback to do the appropriate action (to show a given area or child object depending on the index item selected, for example). Here is an example of such a callback.

      +
      +static void
      +_index_selected_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   Elm_Object_Item *lit = event_info;
      +
      +   // Code that does the desired action
      +}
      +
      + +

      After that, the callback to the selected signal is registered.

      +
      +evas_object_smart_callback_add(index, "selected", _index_selected_cb, NULL);
      +
      + + +

      Label

      + +

      Figure: Label component

      +

      Label component

      + +

      Figure: Label hierarchy

      +

      Label hierarchy

      + +

      The label component displays text with simple html-like markup.

      + +

      Adding a Label Component

      + +

      To add a label and set the text in it, use the following functions.

      + +
      +Evas_Object *label = elm_label_add(win);
      +
      +elm_object_text_set(label, "Some long text for our label, that is not so long");
      +
      + +

      Using the Label Styles

      + +

      Label displays the text with several predefined styles.

      +
        +
      • default: No animation
      • +
      • marker: The text is centered and bolded.
      • +
      • slide_long: The text appears from the right of the screen and slides until it disappears in the left of the screen(reappearing on the right again).
      • +
      • slide_short: The text appears in the left of the label and slides to the right to show the overflow. When all of the text has been shown the position is reset.
      • +
      • slide_bounce: The text appears in the left of the label and slides to the right to show the overflow. When all of the text has been shown, the animation reverses, moving the text to the left.
      • +
      + +

      Here the style is set to slide_long.

      + +
      +elm_object_style_set(label, "slide_long");
      +
      + +

      Configuring the Label

      + +

      The duration of the animation and the slide mode can be set with the following functions.

      +
      +elm_label_slide_duration_set(label, 3);
      +elm_label_slide_mode_set(label, ELM_LABEL_SLIDE_MODE_ALWAYS);
      +
      + +

      Use the following function to modify the style.

      +
      +elm_object_style_set(label, "slide_bounce");
      +
      + +

      Using the Label Callbacks

      + +

      This UI component emits the following signals:

      +
        +
      • language,changed: The program's language changes.
      • +
      • slide,end: The slide reaches the end.
      • +
      • anchor,clicked: The anchor is clicked. event_info points to an object of the type Elm_Label_Anchor_Info.
      • +
      • anchor,mouse,down event_info points to an object of the type Elm_Label_Anchor_Info.
      • +
      • anchor,mouse,up event_info points to an object of the type Elm_Label_Anchor_Info.
      • +
      + +

      The following example registers a callback on the slide,end signal.

      + +
      +{
      +   evas_object_smart_callback_add(label, "slide,end", slide_end_cb, data);
      +}
      +
      +// Callback function for the "slide,end" signal
      +// This callback is called when the label slide reaches the end
      +void slide_end_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   dlog_print(DLOG_INFO, LOG_TAG, "Slide has reach the end.\n");
      +}
      +
      + +

      List

      + +

      Figure: List component

      +

      List component

      + +

      Figure: List hierarchy

      +

      List hierarchy

      + + +

      This UI component is a very simple type of a list component. It is not to be used to manage a lot of items. For that, genlists are a better option.

      + +

      The list items can contain a text and two contents (start and end). These are set with the elm_object_item_*() functions.

      + +

      Adding a List Component

      + +
      +Evas_Object *list, *parent;
      +
      +// Create a list 
      +list = elm_list_add(parent);
      +
      + +

      Using the List

      + +

      This UI component implements the scrollable interface, so the scroller component functions can be used on it. For example, if you want to change the bounce property of the scroller or the scrolling policy:

      + +
      +Evas_Object *list;
      +
      +// Change the scroller policy to fix the scroll only vertically
      +elm_scroller_policy_set(list, ELM_SCROLLER_POLICY_ON, ELM_SCROLLER_POLICY_OFF);
      +// Enable bounce effect when the list reaches the upper and lower limits 
      +elm_scroller_bounce_set(list, EINA_TRUE, EINA_TRUE);
      +
      + +

      The elm_list_multi_select_set() function can be called to enable multi-selection of items. Each time an item is clicked, the state changes to selected.

      + +
      +Evas_Object *list;
      +
      +// Activate multi selection 
      +elm_list_multi_select_set(list, EINA_TRUE);
      +
      + +

      Adding Item to the List

      + +

      Items are added with elm_list_item_append() or elm_list_item_prepend(). Here an example of adding ten items with text and one icon on the front: The last two arguments are the callback function when the created item is clicked and the data passed to the callback function.

      + +
      +Evas_Object *list;
      +int i;
      +
      +// This function is called when the list item is selected 
      +static void _selected_item_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   Elm_Object_Item *list_it = elm_list_selected_item_get(obj);
      +   Eina_Bool selected = elm_list_item_selected_get(list_it);
      +   dlog_print(DLOG_INFO, LOG_TAG, "item is %s\n", selected? "selected": "unselected");
      +}
      +
      +for (i = 0; i < 10; i++)
      +{
      +   Evas_Object *ic;
      +   char tmp[8];
      +   snprintf(tmp, sizeof(tmp), "Item %02d", i);
      +   // Create an icon 
      +   ic = elm_icon_add(win);
      +   // Set the file to the icon file 
      +   elm_image_file_set(ic, "path/to/file", NULL);
      +   // Add item to the list 
      +   elm_list_item_append(list, tmp, ic, NULL, _selected_item_cb, NULL);
      +}
      +
      +
      + +

      Changing the Text or Icon of an Item

      + +

      If you want to change the state of an item, you can do it by using all the functions relative to Elm_Object_Item. Each item of the list contains two instances of an evas_object. Give those as the third and the fourth arguments when you append or prepend the item in the list. The evas_object instances are changed with elm_object_item_part_content_set. The first object is referenced as the start object in the theme, whereas the second one is referenced as the end object. Give these names when you use the elm_object_item_part_content_set. The label of the item is changed by using elm_object_item_text_set.

      + +
      +Evas_Object *list;
      +Eina_List *l;
      +Elm_Object_Item *it;
      +
      +// Retrieve the current selected item 
      +it = elm_list_selected_item_get(list);
      +if (!it)
      +   return;
      +
      +ic = elm_icon_add(win);
      +// Set the file to the icon file 
      +elm_image_file_set(ic, "path/to/file", NULL);
      +// Change the first icon 
      +elm_object_item_part_content_set(it, "start", ic);
      +// Change the second icon 
      +elm_object_item_part_content_set(it, "end", ic);
      +// Change the label 
      +elm_object_item_text_set(it, "I've been selected !");
      +
      + +

      Retrieving Selected Items

      + +

      The list of the currently selected items is retrieved with elm_list_selected_items_get(). If the multiselect mode is false, you can retrieve the only selected item with elm_list_selected_item_get(). For example, this is how to unselect all previously selected items.

      + +
      +Evas_Object *list; Eina_List *l;
      +Eina_List *selected_items;
      +// List of Elm_Object_Item 
      +Elm_Object_Item *it;
      +
      +selected_items = elm_list_selected_items_get(list);
      +EINA_LIST_FOREACH(selected_items, l, it)
      +   elm_list_item_selected_set(it, EINA_FALSE);
      +
      + +

      List Item Operations

      + +

      To find out if an item is selected, call elm_list_item_selected_get. This function returns EINA_TRUE if the item is selected, otherwise EINA_FALSE.

      + +

      Elementary list provides two functions for sliding a list to a specific item. elm_list_item_show shows the item passed as an argument, whereas elm_list_item_bring_in shows the item, but only after animating the slide.

      + +

      You can go to the item immediately preceding a specific item with the function elm_list_item_prev, or to the one immediately following a specific item with the function elm_list_item_next.

      + +

      The following example shows selecting the item immediately following the currently selected one, unselecting it, selecting the next one and bringing it to the screen.

      + +
      +Evas_Object *list;
      +Elm_Object_Item *current, *next;
      +current = elm_list_selected_item_get(list);
      +elm_list_item_selected_set(current, EINA_FALSE);
      +next = elm_list_item_next(current);
      +elm_list_item_selected_set(next, EINA_TRUE);
      +elm_list_item_bring_in(next);
      +
      + +

      Using List Callbacks

      + +

      The list emits the following signals:

      +
        +
      • activated: The user double-clicks or presses (enter | return | spacebar) on an item. The event_info parameter of the callback function contains a pointer to the item activated.
      • +
      • clicked,double: The user double-clicks an item. The event_info parameter of the callback function contains a pointer to the item activated.
      • +
      • selected: The user selects an item. The event_info parameter of the callback function contains a pointer to the item activated.
      • +
      • unselected: The user unselects an item. The event_info parameter of the callback function contains a pointer to the item activated.
      • +
      • longpressed: The user long-presses an item. The event_info parameter of the callback function contains a pointer to the item activated.
      • +
      • edge,top: The list is scrolled to the top edge.
      • +
      • edge,bottom: The list is scrolled to the bottom edge.
      • +
      • edge,left: The list is scrolled to the left edge.
      • +
      • edge,right: The list is scrolled to the right edge.
      • +
      • highlighted: The user highlights an item on the list. The event_info parameter of the callback function contains a pointer to the item activated.
      • +
      • unhighlighted: The user unhighlights an item in the list. The event_info parameter of the callback function contains a pointer to the item activated.
      • +
      + +

      You can register to the clicked,double signal with the following code. Note that the currently double-clicked item can be retrieved using the event_info pointer. This code registers to the double,clicked signal and unselects the item that has been double-clicked.

      + +
      +{
      +   Evas_Object *list;
      +
      +   evas_object_smart_callback_add(list, "clicked,double", double_clicked_cb, data);
      +}
      +
      +// Callback function for the "clicked" signal
      +// This callback is called when the button is clicked by the user
      +void double_clicked_cb(void *data, Evas_Object *obj, void  *event_info)
      +{
      +   elm_Object_Item *it = event_info;
      +   elm_list_selected_item_set(it,  EINA_FALSE);
      +}
      +
      + +

      Map

      + +

      Figure: Map hierarchy

      +

      Map hierarchy

      + +

      The map component displays a geographic map. The default map data are provided by the OpenStreetMap project (http://www.openstreetmap.org/). Custom providers can also be added.

      + +

      This UI component supports:

      +
        +
      • Zooming
      • +
      • Scrolling
      • +
      • Markers with content to be displayed when the user clicks over them
      • +
      • Group of markers
      • +
      • Routes
      • +
      + +

      The map component implements the scroller interface so that all the functions that work with the scroller component also work with maps.

      + +

      Adding a Map Component

      + +

      Once created with the elm_map_add() function, zoom level x12 can be set.

      + +
      +Evas_Object *map, *parent;
      +
      +map = elm_map_add(parent);
      +elm_map_zoom_mode_set(map, ELM_MAP_ZOOM_MODE_MANUAL);
      +elm_map_zoom_set(map, 12);
      +
      + +

      Here the zoom mode is set to manual, but it can also be set to the ELM_MAP_ZOOM_MODE_AUTO_FIT mode and the ELM_MAP_ZOOM_MODE_AUTO_FILL mode. In that case however, the elm_map_zoom_set() function cannot be used.

      + +

      Playing with the Map

      + +

      If you have coordinates of a specific area (2 2 N, 48 8 E), it can be shown on the map.

      +
      +elm_map_region_show(map, 2.2, 48.8);
      +
      + +

      This shows the desired coordinates. The location can also be shown with a bring-in animation.

      +
      +elm_map_region_bring_in(map, 2.2, 48.8);
      +
      + +

      The map is rotated 90 degrees around the current position.

      +
      +elm_map_rotate_set(map, 90, 2.2, 48.8);
      +
      + +

      Drawing Overlays

      + +

      Overlays are markers that can be placed anywhere on the map. They can represent any object you want to put on the map.

      + +

      Creating an Overlay Class

      + +

      Overlay classes can be created if several objects are of the same type. For example, you can create a forest overlay class to represent the forests visible on the map. To do this, set the minimum zoom level at which this class is visible. The forest class overlay is visible when the zoom level is superior to eight.

      + +

      Set an icon ("Home" icon) to the forest class. This icon is displayed in place of the forest class on the map.

      +
      +Evas_Object *icon;
      +Elm_Map_Overlay *forest_class = elm_map_overlay_class_add(map);
      +
      +// Set min zoom level at which class is displayed
      +elm_map_overlay_displayed_zoom_min_set(forest_class, 8);
      +
      +// Create a Home icon object and set it to the forest class 
      +icon = elm_icon_add(map);
      +elm_icon_standard_set(icon, "home");
      +elm_map_overlay_icon_set(forest_class, icon);
      +
      + +

      Adding Overlays to a Class

      + +

      After creating a forest class, it is possible to add overlay objects to it. Here an overlay for the Meudon forest is created. The data is linked to the overlay with the elm_map_overlay_data_set() function. Set the name of the forest in the data. The icon can be set to the overlay with the elm_map_overlay_icon_set() function.

      + + + + + + + + + + +
      Note
      Do not use the same icon object for two different overlays. Create a new icon object each time you need one.
      + +
      +Elm_Map_Overlay *ovl;
      +const char* data_meudon = "Meudon forest";
      +const char* data_fausses = "Fausse forest";
      +
      +// Add an overlay
      +ovl = elm_map_overlay_add(map, 2.20718, 48.79759);
      +icon = elm_icon_add(map);
      +elm_icon_standard_set(icon, "stop");
      +elm_map_overlay_icon_set(ovl, icon);
      +elm_map_overlay_data_set(ovl, &data_meudon);
      +
      +// Add the new ovl object to the forest class 
      +elm_map_overlay_class_append(forest_class, ovl);
      +
      +// Add another overlay next to the first one 
      +ovl = elm_map_overlay_add(map, 2.1699, 48.8189);
      +icon = elm_icon_add(map);
      +elm_icon_standard_set(icon, "stop");
      +elm_map_overlay_icon_set(ovl, icon);
      +elm_map_overlay_data_set(ovl, &data_fausses);
      +elm_map_overlay_class_append(forest_class, ovl);
      +
      + +

      If you add another overlay to the forest class, the two overlays can be grouped under the forest class icon on certain zoom level conditions. You can define on which zoom level items are grouped.

      +
      +elm_map_overlay_class_zoom_max_set(forest_class, 8);
      +
      + +

      In this case, overlay members of the forest class are grouped when the map is displayed at less than zoom level eight.

      + +

      Creating Bubbles Following Overlays

      + +

      The following example shows how to set a content in a bubble following an overlay.

      + +
      +// Add an overlay bubble object 
      +Elm_Map_Overlay *bubble = elm_map_overlay_bubble_add(map);
      +
      +// Set it to follow a specific overlay (the last created one here) 
      +elm_map_overlay_bubble_follow(bubble, ovl);
      +
      + +

      Once following an overlay, the bubble appears, moves or hides following the parent overlay's behavior.

      + +

      Content is added to the bubble with the elm_map_overlay_bubble_content_append() function.

      + +

      Adding Other Overlays

      + +

      You can draw a circle on the map with coordinates and a radius size.

      +
      +Elm_Map_Overlay *circle = elm_map_overlay_circle_add(map, 2.2, 48.8, 0.02);
      +
      + +

      You can also add a scale at the 200x0 coordinate (in pixels).

      +
      +Elm_Map_Overlay *scale = elm_map_overlay_scale_add(map, 200, 0);
      +
      + +

      You can also draw a line, a polygon, or a route. For a full description of these functions, see the Map API.

      + +

      Calculating Routes

      + +

      A route between a starting point and an ending point is calculated with the elm_map_route_add() call. The type of transport and the routing calculation method can be provided so as to have the desired result.

      + +

      The following example shows how to get a route calculation between the first and the second overlay. It is configured to use the bicycle, and to find the fastest route possible.

      + +
      +Elm_Map_Route *route = elm_map_route_add(map,
      +         ELM_MAP_ROUTE_TYPE_BICYCLE,
      +         ELM_MAP_ROUTE_METHOD_FASTEST,
      +         2.20718, 48.79759,
      +         2.1699, 48.8189,
      +         NULL, NULL);
      +
      +// Add a callback to when the route has been calculated and loaded 
      +evas_object_smart_callback_add(map, "route,loaded", _route_loaded_cb, route);
      +
      + +

      Once the route is calculated, create a route overlay object and change its color. In this example, the route,loaded callback is used.

      +
      +static void
      +_route_loaded_cb(void *data, Evas_Object *obj, void *ev)
      +{
      +   Elm_Map_Route *route = data;
      +
      +   Elm_Map_Overlay *route_ovl = elm_map_overlay_route_add(obj, route);
      +   elm_map_overlay_color_set(route_ovl, 0, 255, 0, 255);
      +}
      +
      + +

      Using Map Callbacks

      + +

      The map component emits the following callbacks:

      +
        +
      • clicked: The user has clicked the map without dragging around.
      • +
      • clicked,double: The user has double-clicked the map.
      • +
      • press: The user has pressed down on the map.
      • +
      • longpressed: The user has pressed down on the map for a long time without dragging around.
      • +
      • scroll: The content is scrolled (moved).
      • +
      • scroll,drag,start: Dragging the contents around starts.
      • +
      • scroll,drag,stop: Dragging the contents around stops.
      • +
      • scroll,anim,start: Scrolling animation starts.
      • +
      • scroll,anim,stop: Scrolling animation stops.
      • +
      • zoom,start: Zoom animation starts.
      • +
      • zoom,stop: Zoom animation stops.
      • +
      • zoom,change: The zoom is changed when using an auto zoom mode.
      • +
      • tile,load: A map tile image load begins.
      • +
      • tile,loaded: A map tile image load ends.
      • +
      • tile,loaded,fail: A map tile image load fails.
      • +
      • route,load: Route request begins.
      • +
      • route,loaded: Route request ends.
      • +
      • route,loaded,fail: Route request fails.
      • +
      • name,load: Name request begins.
      • +
      • name,loaded: Name request ends.
      • +
      • name,loaded,fail: Name request fails.
      • +
      • overlay,clicked: An overlay is clicked.
      • +
      • loaded: The map is loaded.
      • +
      + + +

      Notify

      + +

      Figure: Notify hierarchy

      +

      Notify hierarchy

      + +

      The notify component displays a container in a particular region of the parent object. It can receive some content, and can be automatically hidden after a certain amount of time.

      + +

      Adding a Notify Component

      + +

      The following example shows how to create a notify object.

      + +
      +Evas_Object *notify, *parent;
      +notify = elm_notify_add(parent);
      +
      + +

      Configuring the Notify Component

      + +

      Create a label and add it to the notify object.

      + +
      +Evas_Object *content;
      +
      +// Create the label and set some text to it 
      +content = elm_label_add(parent);
      +
      +elm_object_text_set(content, "A label text");
      +evas_object_show(content);
      +
      +// Add the label object to the notify component
      +elm_object_content_set(notify, content);
      +
      + +

      In the following example the notify object is shown on the bottom left corner of the parent object.

      + +
      +elm_notify_align_set(notify, 1.0, 1.0);
      +evas_object_show(notify);
      +
      + +

      Set a timeout interval, after which the notify component is hidden. In the following example the timeout interval is five seconds.

      + +
      +elm_notify_timeout_set(notify, 5.0);
      +
      + +

      Using Notify Callbacks

      + +

      The notify component emits the following signals:

      +
        +
      • timeout: The timeout count ends and the notify component is hidden
      • +
      • block,clicked: The user clicks outside of the notify component
      • +
      + +

      For both these signals event_info is NULL.

      + +

      The following example shows how to register a callback on the timeout signal.

      + +
      +{
      +   evas_object_smart_callback_add(notify, "timeout", timeout_cb, data);
      +}
      +
      +// Callback function for the "timeout" signal
      +// The timeout expires and the notify object is hidden
      + 
      +void timeout_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   dlog_print(DLOG_INFO, LOG_TAG, "Notify is hidden\n");
      +}
      +
      + + +

      Panel

      + + +

      Figure: Panel hierarchy

      +

      Panel hierarchy

      +

      The panel component is an animated object that can contain subobjects. It can be expanded or contracted by clicking on the button on its edge.

      + +

      Panel inherits from layout component, so the layout API can be used on this UI component.

      + +

      Adding a Panel Component

      + +

      The following example shows how to add a panel and set its orientation to the left.

      + +
      +Evas_Object *panel, *parent;
      +
      +panel = elm_panel_add(parent);
      +elm_panel_orient_set(panel, ELM_PANEL_ORIENT_LEFT);
      +
      + +

      Using the Panel

      + +

      The panel can be manually hidden.

      +
      +elm_panel_hidden_set(pan, EINA_TRUE);
      +
      + +

      The panel can be toggled if you do not know the hidden state of the UI component.

      +
      +elm_panel_toggle(pan);
      +
      + +

      The panel can be set scrollable.

      +
      +elm_panel_scrollable_set(pan, EINA_TRUE);
      +
      + +

      Creating a Drawer

      + +

      Tizen SDK has implemented a layout theme to add a drawer in the application. This example shows how to add a new Elementary layout object and set the theme of this layout to the drawer.

      + +
      +Evas_Object *layout;
      +
      +// Create a new layout object 
      +layout = elm_layout_add(parent);
      +
      +// Set the "drawer" group theme and "panel" style to it 
      +elm_layout_theme_set(layout,"layout", "drawer", "panel");
      +
      +// Show the new layout
      +evas_object_show(layout);
      +
      + +

      Once the panel object is created, it can be swallowed in the new layout.

      + +
      +elm_object_part_content_set(layout, "elm.swallow.left", pan);
      +
      + +

      You can set content to the elm.swallow.bg and elm.swallow.content parts of the layout.

      +
      +// Panel Background (Dimmed Area) 
      +Evas_Object *bg = create_bg(layout);
      +elm_object_part_content_set(layout, "elm.swallow.bg", bg);
      +
      +// Add content to the drawer 
      +Evas_Object *content;
      +elm_object_part_content_set(layout, "elm.swallow.content", content);
      +
      + +

      Using Panel Callbacks

      + +

      You can register a callback on the scroll signal, when the user scrolls the panel. The event_info parameter is of the type Elm_Panel_Scroll_Info.

      + +
      +{
      +   evas_object_smart_callback_add(pan, "scroll", scroll_cb, data);
      +}
      +// Callback function for the "scroll" signal
      +// This callback is called when the user scrolls the panel
      +void scroll_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   Elm_Panel_Scroll_Info *scrollinfo = event_info;
      +   dlog_print(DLOG_INFO, LOG_TAG, "The panel was scrolled.\n");
      +}
      +
      + + +

      Photo

      + +

      Figure: Photo hierarchy

      +

      Photo hierarchy

      + +

      The photo component is used to display a photo, such as a contact image. If no photo is set on it, it displays a person icon to show that it is a photo placeholder.

      + +

      Adding a Photo Component

      + +

      The following example shows how to create a photo object.

      + +
      +Evas_Object *photo, *parephotoslider = elm_photo_add(parent);
      +photo = elm_photo_add(parent);
      +
      + +

      Using a Photo Component

      + +

      A file can be set to the photo component. Here, PHOTO_FILENAME is a string corresponding to the photo file name on the system.

      +
      +elm_photo_file_set(photo, PHOTO_FILENAME);
      + +

      The photo can be set as editable, and it can be copied, cut, or dragged in another region of the screen.

      +
      +elm_photo_editable_set(photo, EINA_TRUE);
      + +

      The photo can also be completely visible on the screen.

      + +
      +elm_photo_fill_inside_set(photo, EINA_TRUE);
      + +

      Using Photo Callbacks

      + +

      The following callbacks are registered on the photo component.

      +
        +
      • clicked: The user has clicked the photo.
      • +
      • drag,start: The user starts dragging the inner image out of the photo's frame.
      • +
      • drag,end: The user drops the dragged image.
      • +
      + +

      event_info is always NULL.

      + + +

      Photocam

      + +

      Figure: Photocam hierarchy

      +

      Photocam hierarchy

      + +

      The photocam component displays high resolution photos taken from digital cameras. It provides a way to zoom in the photo, load it fast, and fit it nicely on the screen. It is optimized for .jpeg images format and has a low memory footprint.

      + +

      This UI component implements the scroller interface, so all the functions concerning the scroller can be used with the photocam component.

      + +

      Adding a Photocam Component

      + +

      The following example shows how to create a photocam component and set an image file on it.

      + +
      +Evas_Object *photocam;
      +photocam = elm_photocam_add(win);
      +elm_photocam_file_set(photocam, "/tmp/photo.jpeg");
      +
      + +

      Using Photocam Zoom

      + +

      You can choose between two automatic zoom modes and a manual zoom mode. In the following example the zoom mode is set to manual and a double zoom is requested.

      +
      +elm_photocam_zoom_mode_set(photocam, ELM_PHOTOCAM_ZOOM_MODE_MANUAL);
      +elm_photocam_zoom_set(photocam, 2.0);
      +
      + +

      The zoom mode can be set to ELM_PHOTOCAM_ZOOM_MODE_AUTO_FIT. In this case, the photo fits exactly inside the scroll frame with no pixels outside this region. The zoom mode can also be set to ELM_PHOTOCAM_ZOOM_MODE_AUTO_FILL to fill all the pixels of the photocam component.

      + +

      Multi-touch zooming is activated by enabling gestures.

      +
      +elm_photocam_gesture_enabled_set(photocam, EINA_TRUE);
      +
      + +

      You can zoom in a specific region. The following example shows how to zoom in the region starting at the coordinates (200x200), with a width of 400px and a height of 300px.

      + +
      +elm_photocam_image_region_bring_in(photocam, 200, 200, 400, 300);
      +
      + +

      Using Photocam Callbacks

      + +

      The photocam component emits the following signals:

      +
        +
      • clicked: The user has clicked the photo without dragging around.
      • +
      • press: The user has pressed down on the photo.
      • +
      • longpressed: The user has pressed down on the photo for a long time without dragging around.
      • +
      • clicked,double: The user has double-clicked the photo.
      • +
      • load: The photo load begins.
      • +
      • loaded: The image file load is complete for the first view (a low resolution blurry version).
      • +
      • load,detail: A photo detailed data load begins.
      • +
      • loaded,detail: The image file load is complete for the detailed image data (full resolution is needed).
      • +
      • zoom,start: Zoom animation starts.
      • +
      • zoom,stop: Zoom animation stops.
      • +
      • zoom,change: The zoom is changed when using an auto zoom mode.
      • +
      • scroll: The content is scrolled.
      • +
      • scroll,anim,start: Scrolling animation starts.
      • +
      • scroll,anim,stop: Scrolling animation stops.
      • +
      • scroll,drag,start: Dragging the content around starts.
      • +
      • scroll,drag,stop: Dragging the content around stops.
      • +
      + +

      For all these signals, event_info is NULL.

      + +

      The following example shows how to register a callback on the loaded signal.

      + +
      +void message_port_cb(int local_port_id, const char *remote_app_id, bundle *message)
      +{
      +   evas_object_smart_callback_add(photocam, "loaded", loaded_cb, data);
      +}
      +
      +// Callback function for the "loaded" signal
      +// The photocam has loaded the photo file in a low resolution
      + 
      +void loaded_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   dlog_print(DLOG_INFO, LOG_TAG, "The photo has been loaded\n");
      +}
      +
      + +

      Plug

      + +

      Figure: Plug hierarchy

      +

      Plug hierarchy

      + +

      The plug component shows an Evas_Object created by an other process. It can be used anywhere the same way as any other elementary UI component.

      + +

      Adding a Plug Component

      + +

      The following example shows how to create a plug.

      + +
      +Evas_Object *plug, *parent;
      +plug = elm_plug_add(parent);
      +
      + +

      Using the Plug

      + +

      The socket image provides the service where to connect the plug object with the elm_plug_connect() function. In this process, use the service name and number set by the socket you want to connect to.

      + +

      As an example, connect to a service named plug_test on the number 0.

      + +
      +elm_plug_connect(plug, "plug_test", 0, EINA_FALSE);
      +
      + +

      The Evas_Object corresponding to the distant image is retrieved with the elm_plug_image_object_get() function.

      + +
      +Evas_Object *plug_img = elm_plug_image_object_get(plug);
      +
      + + + + + + + + + + +
      Note
      The socket to connect to must be started with the elm_win_socket_listen() function in the other process on the remote window object (it is called remote_win here).
      + +
      +// Create a remote window in the other process 
      +Elm_Win *remote_win = elm_win_add(NULL, "Window Socket",
      +                                  ELM_WIN_SOCKET_IMAGE);
      +// Create a socket named "plug_test" and listen to it
      +elm_win_socket_listen(remote_win, "plug_test", 0, EINA_FALSE);
      +
      + + + +

      Figure: Popup component

      +

      Popup component

      + +

      Figure: Popup hierarchy

      +

      Popup hierarchy

      + + +

      The popup component shows a popup area that can contain:

      +
        +
      • a title area (optional)
      • +
      • a content area
      • +
      • an action area (optional)
      • +
      + +

      The optional title area can contain an icon and text, the action area can contain up to three buttons.

      + +

      Adding a Popup Component

      + +

      The following example shows how to create a popup component.

      +
      +Evas_Object *popup, *parent;
      +
      +// Create a popup 
      +popup = elm_popup_add(parent);
      +
      + +

      Using Popup Styles

      + +

      The following item styles are available for the popup:

      + +
        +
      • popup
      • +
      • toast
      • +
      + +

      The following example sets the style of the popup to toast.

      + +
      elm_object_style_set(popup, "toast");
      + +

      Setting the Popup Areas

      + +

      Configure the title area. Set the icon object using the part name title,icon. Set the title text to Test popup using the partname title,text.

      + +
      +Evas_Object *icon;
      +
      +// Add an icon to the title area 
      +elm_object_part_content_set(popup, "title,icon", icon);
      +
      +// Set the title text 
      +elm_object_part_text_set(popup, "title,text", "Test popup");
      +
      + +

      Set the content of the popup. The content can be simple text.

      + +
      +elm_object_part_text_set(popup, "default", "Test popup");
      +
      + +

      The content can also be an Evas object.

      + +
      +Evas_Object *content;
      +
      +elm_object_content_set(popup, content);
      +
      + +

      Set the buttons of the action area by creating an OK button, a Cancel button, and a Help button.

      + +
      +Evas_Object *button1, *button2, *button3;
      +
      +// Create the 3 buttons 
      +
      +button1 = elm_button_add(popup);
      +elm_object_text_set(button1, "OK");
      +
      +button2 = elm_button_add(popup);
      +elm_object_text_set(button2, "Cancel");
      +
      +button3 = elm_button_add(popup);
      +elm_object_text_set(button3, "Help");
      +
      +// Set the buttons to the action area 
      +elm_object_part_content_set(popup, "button1", button1);
      +elm_object_part_content_set(popup, "button2", button2);
      +elm_object_part_content_set(popup, "button3", button3);
      +
      + +

      Using Popup Callbacks

      +

      The popup emits the following signals:

      +
        +
      • timeout: The popup is closed as a result of timeout.
      • +
      • block,clicked: The user clicks on the Blocked Event area.
      • +
      + +

      elm_popup_timeout_set() is used to hide the popup after a certain time. In this example, the timeout is set to five seconds.

      + +
      +elm_popup_timeout_set(popup, 5.0);
      +
      + +

      When the timeout expires, the timeout signal is sent to the user.

      + +
      +{
      +   evas_object_smart_callback_add(popup, "timeout", _timeout_cb, data);
      +}
      +
      +static void
      +_timeout_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   dlog_print(DLOG_INFO, LOG_TAG, "Timeout \n");
      +}
      +
      + +

      The visible region of the popup is surrounded by a translucent region called Blocked Event area. By clicking on this area, the signal block,clicked is sent to the application.

      + + +

      Progressbar

      + +

      Figure: Progressbar component

      +

      Progressbar component

      + +

      Figure: Progressbar hierarchy

      +

      Progressbar hierarchy

      + + +

      Adding a Progressbar Component

      + +

      This UI component is used to display the progress status of a given job. It inherits from the layout component, so all function concerning the layout component is used on the progressbar component.

      +

      The following example shows how to create a progressbar component.

      + +
      +Evas_Object *pb = elm_progressbar_add(win);
      +
      + +

      Using the Progressbar Styles

      + +

      The progressbar has several styles:

      +
        +
      • default
      • +
      • pending_list
      • +
      • process_large
      • +
      • process_medium
      • +
      • process_small
      • +
      + +

      Set the style of the progressbar to pending_list.

      + +
      elm_object_style_set(pb, "pending_list");
      + +

      Using the Progressbar

      + +

      By default, the progressbar does not show a label or an icon, and the unit label is set to %.0f %%.

      + +

      The following example shows how to set a label. In this example it is named Test label.

      + +
      +elm_object_text_set(pb, "Test label");
      +
      + +

      An icon is set with elm_object_part_content_set() using the partname icon.

      +
      +elm_object_part_content_set(pb, "icon", icon_object);
      +
      + +

      The unit label format string can be modified using a printf style format. Set it to be a float number with two decimals.

      +
      +elm_progressbar_unit_format_set(pb, "%1.2f%%");
      +
      + +

      Configuring the Progressbar

      + +

      The progressbar pulse mode is activated to make the progressbar loop infinitely between the start and end position.

      +
      +elm_progressbar_pulse_set(pb, EINA_TRUE);
      +elm_progressbar_pulse(pb, EINA_TRUE);
      +
      + +

      The progressbar can be inverted. In that mode, the values are inverted so that the high values are on the left and the low values on the right.

      +
      +elm_progressbar_inverted_set(pb, EINA_TRUE);
      +
      + +

      The progressbar emits the changed signal when the progress value changes. The value is changed with the elm_progressbar_value_set() function. Here the pb progress value is set to 20%.

      +
      +elm_progressbar_value_set(pb, 0.2);
      +
      + +

      The current value can be read.

      +
      +double value = elm_progressbar_value_get(pb);
      +
      + +

      You can set the orientation of the progressbar to vertical instead of the default horizontal orientation.

      +
      +elm_progressbar_horizontal_set(pb, EINA_FALSE);
      +
      + +

      Using the Progressbar Callbacks

      + +

      The changed signal is the only signal specifically emitted by the progressbar component.

      + +

      The following example shows how to register a callback on this signal.

      + +
      +{
      +   evas_object_smart_callback_add(pb, "changed", changed_cb, data);
      +}
      +
      +// Callback function for the "changed" signal
      +// This callback is called when the progressbar value changes
      +void changed_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   dlog_print(DLOG_INFO, LOG_TAG, "The value has changed\n");
      +}
      +
      + + +

      Radio

      + +

      Figure: Radio component

      +

      Radio component

      + +

      Figure: Radio hierarchy

      +

      Radio hierarchy

      + +

      This UI component displays one or more options, but the user can only select one of them. It is composed of an indicator (selected or unselected), an optional icon and an optional label. Even though it is usually grouped with two or more other radio objects, it can also be used alone.

      +

      The radio component inherits from the layout component. All the layout functions can be used with radio objects.

      + +

      Adding a Radio Component

      + +

      Create a radio component and set a label to it.

      +
      +Evas_Object *radio, *parent;
      +
      +// Create a radio
      +radio = elm_radio_add(parent);
      +
      +// Set a label to it
      +elm_object_text_set(radio, "Radio component");
      +
      + +

      Set an icon to the radio object.

      +
      +// Create a Home icon 
      +Evas_Object *icon;
      +
      +icon = elm_icon_add(parent);
      +elm_icon_standard_set(icon, "home");
      +
      +// Set it to the radio component 
      +elm_object_part_content_set(radio, "icon", icon);
      +
      + +

      Changing the Radio Value

      + +

      The user can select one of a set of values with the radio component. Each radio object from a group of radio objects represents an integer value. Here the value 1 is set to the new radio object.

      +
      +elm_radio_state_value_set(radio, 1);
      +
      + +

      Managing the Radio Groups

      + +

      The following example shows how to create a group of radio objects with at least two radio components.

      + +
      +// Create another radio object 
      +Evas_Object *radio2 = elm_radio_add(parent);
      +elm_radio_state_value_set(radio2, 2);
      +
      +// Create a group composed of radio and radio2
      +Evas_Object *group = radio;
      +elm_radio_group_add(radio2, group);
      +
      + +

      Now that a group composed of two radio objects has been created, you can choose which one is selected. In this example radio2 is selected.

      + +
      +elm_radio_value_set(group, 2);
      +
      + +

      You can use elm_radio_value_get() to see the currently selected radio of the group.

      + +

      Using the Radio Callbacks

      + +

      When the state of a radio is modified in a group of radio objects, the changed signal is emitted.

      +

      The following example shows how to register a callback on this signal.

      + +
      +{
      +   evas_object_smart_callback_add(radio, "changed", changed_cb, data);
      +}
      +
      +// Callback function for the "changed" signal
      +// This callback is called when the radio value changes
      +void changed_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   dlog_print(DLOG_INFO, LOG_TAG, "The value has changed\n");
      +}
      +
      + + +

      Segmentcontrol

      + +

      Figure: Segmentcontrol with text

      +

      Segmentcontrol with text

      + +

      Figure: Segmentcontrol with icons

      +

      Segmentcontrol with icons

      + +

      Figure: Segmentcontrol hierarchy

      +

      Segmentcontrol hierarchy

      + +

      This UI component consists of several segment items. A segment item is similar to a discrete two state button. Any time, only one segment item can be selected. A segment item is composed of a label (text) and an icon.

      +

      This UI component inherits from the layout component, so all the layout components API can be used on segmentcontrol objects.

      + +

      Adding a Segmentcontrol Component

      + +

      The following example shows how to add a segmentcontrol component.

      + +
      +Evas_Object *segcontrol, *parent;
      +
      +segcontrol = elm_segment_control_add(parent);
      +
      + +

      Adding Items

      + +

      You can add items to the UI component. In the following example four items containing only text labels (no icons) are added.

      +
      +Elm_Object_Item *it;
      +
      +elm_segment_control_item_add(segcontrol, NULL, "item1");
      +elm_segment_control_item_add(segcontrol, NULL, "item2");
      +elm_segment_control_item_add(segcontrol, NULL, "item3");
      +it = elm_segment_control_item_add(segcontrol, NULL, "item4");
      +
      + +

      You can also:

      +
        +
      • Insert an item at a specific position starting at 0. +
        +elm_segment_control_item_insert_at(segcontrol, NULL, "item7", 2);
        +
      • + +
      • Delete an item. +
        +elm_segment_control_item_del_at(segcontrol, 2);
        +
      • + +
      • Set the selected state of an item manually. +
        +elm_segment_control_item_selected_set(it, EINA_TRUE);
        +
      • +
      • Disable the whole segment control. +
        elm_object_disabled_set(segcontrol, EINA_TRUE);
      • +
      + +

      Using the Segmentcontrol Callbacks

      + +

      This is how to register a callback on the changedsignal. It is called when the user clicks on a segment item which is not previously selected. The event_info parameter is the segment item pointer.

      +
      +{
      +   evas_object_smart_callback_add(segcontrol, "changed", changed_cb, data);
      +}
      +
      +// Callback function for the "changed" signal
      +// This callback is called when the segcontrol selected item changes
      +void changed_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   Elm_Segment_Item *it = event_info;
      +
      +   dlog_print(DLOG_INFO, LOG_TAG, "The selected segment item has changed\n");
      +}
      +
      + + +

      Slider

      + +

      Figure: Slider component

      +

      Slider component

      + +

      Figure: Slider hierarchy

      +

      Slider hierarchy

      + +

      The slider component is a draggable bar that is used to select a value within a certain range.

      + +

      Adding a Slider Component

      + +

      The following example shows how to create a slider object.

      +
      +Evas_Object *slider, *parent;
      +
      +slider = elm_slider_add(parent);
      +
      + +

      Using the Slider Styles

      + +

      A slider has the following styles:

      +
        +
      • default
      • +
      • center_point
      • +
      + +

      The following example sets the style to center_point.

      +
      +elm_object_style_set(slider, "center_point");
      +
      + +

      With this style, the slider 0 point is in the middle of the UI component.

      + +

      Configuring the Slider

      + +

      The orientation is set with the elm_slider_horizontal_set() function, and it is inverted the same way as the progressbar component. In the following example it is set to vertical and inverted.

      +
      +elm_slider_horizontal_set(slider, EINA_FALSE);
      +elm_slider_inverted_set(slider, EINA_TRUE);
      +
      + +

      The slider can contain icons (icon and end partnames), a label, a unit label, and an indicator label.

      +
      +Evas_Object *icon1, *icon2;
      +
      +// Set the icons 
      +elm_object_part_content_set(slider, "icon", icon1);
      +elm_object_part_content_set(slider, "end", icon2);
      +
      +// Set the label 
      +elm_object_part_text_set(slider, "default", "slider label");
      +
      +// Set the unit format 
      +elm_slider_unit_format_set(slider, "%1.2f meters");
      +
      + +

      Before using the slider, its minimum and maximum values are set with elm_slider_min_max_set(). The current value is set with (elm_slider_value_set()). The following example sets the minimum value to 0, the maximum value to 100, and the current value to 50.

      +
      +elm_slider_min_max_set(slider, 0.0, 100.0);
      +elm_slider_value_set(slider, 50.0);
      +
      + +

      The span of the slider represents its length horizontally or vertically. It is set with elm_slider_span_size_set() and is scaled by the object or applications scaling factor.

      +

      You can retrieve the current value of the slider anytime.

      +
      +double value = elm_slider_value_get(slider);
      +
      + +

      By default, the slider indicator becomes bigger when the user drags it. This can be disabled if you want the slider indicator to keep its default size. The following example sets the state of the indicator enlargement and then inverts the behavior.

      +
      +// Get the current state of the indicator 
      +Eina_Bool enlarge = elm_slider_indicator_show_get(slider);
      +
      +// Invert the behavior 
      +elm_slider_indicator_show_set(slider, !enlarge);
      +
      + +

      Using the Slider Callbacks

      + +

      This UI component emits the following signals:

      +
        +
      • changed: The user changes the slider value.
      • +
      • slider,drag,start: Dragging the slider indicator around starts.
      • +
      • slider,drag,stop: Dragging the slider indicator around stops.
      • +
      • delay,changed: A short time after the user changes the value. This is called only when the user stops dragging for a very short period or when releases the finger or mouse, so that it avoids possibly expensive reactions to the value change.
      • +
      + +

      For all these signals, event_info is NULL.

      +

      The following example shows how to register a callback on the changed signal.

      +
      +{
      +   evas_object_smart_callback_add(slider, "changed", changed_cb, data);
      +}
      +
      +// Callback function for the "changed" signal
      +// This callback is called when the slider value changes
      +void changed_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   dlog_print(DLOG_INFO, LOG_TAG, "The slider has changed\n");
      +}
      +
      + +

      Spinner

      + + +

      Figure: Spinner component

      +

      Spinner component

      + +

      Figure: Spinner hierarchy

      +

      Spinner hierarchy

      + +

      The spinner component increases or decreases a numeric value with the arrow buttons.

      + +

      This UI component inherits from the layout component, so all functions concerning the layout component are used on the spinner component.

      + +

      Adding a Spinner Component

      +

      The following example shows how to create a spinner object.

      + +
      +Evas_Object *spin, *parent;
      +
      +spin = elm_spinner_add(parent);
      +
      + +

      Configuring the Spinner

      + +

      The label format is set to a different value:

      +
      +elm_spinner_label_format_set(spin, "%1.2f meters");
      +
      + +

      You can determine the result of clicking the arrow buttons. In this example, a click on an arrow increases or decreases with 2.0 units:

      +
      +elm_spinner_step_set(spin, 2.0);
      +
      +

      The wrapping mode is activated. In this mode, the spinner wraps when it reaches its minimum or maximum value.

      +
      +elm_spinner_wrap_set(spin, EINA_TRUE);
      +
      + +

      You can set the minimum and maximum values of the spinner.

      +
      +elm_spinner_min_max_set(spin, -25.0, 100.0);
      +
      + +

      The spinner object can be set vertical, and the change interval when the user presses the arrows long can be modified so that it changes faster.

      +
      +elm_object_style_set(spin, "vertical");
      +elm_spinner_interval_set(spin, 0.1);
      +
      + +

      If the user has to select between text values instead of numerical values, it is possible to add our own text labels. Here spin2 object shows three numbers written in text characters.

      +
      Evas_Object *spin2 = elm_spinner_add(parent);
      +elm_spinner_min_max_set(spin2, 1, 3);
      +elm_spinner_special_value_add(spin2, 1, "One");
      +elm_spinner_special_value_add(spin2, 2, "Two");
      +elm_spinner_special_value_add(spin2, 3, "Three");
      +
      + +

      Using the Spinner Callbacks

      + +

      This UI component emits the following signals:

      +
        +
      • changed: The spinner value changes.
      • +
      • delay,changed: A short time after the user changes the value. This is called only when the user stops dragging for a very short period or releases the finger or mouse, so that it avoids possibly expensive reactions to the value change.
      • +
      + +

      The following example shows how to register a callback on the delay,changed signal.

      + +
      +{
      +   evas_object_smart_callback_add(spin, "delay,changed", delay_changed_cb, data);
      +}
      +
      +// Callback function for the "delay,changed" signal
      +// This callback is called a short time after the spinner value changes
      +void delay_changed_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   dlog_print(DLOG_INFO, LOG_TAG, "The spinner value has changed\n");
      +}
      +
      + +

      Toolbar

      + +

      Figure: Toolbar component

      +

      toolbar component

      + +

      Figure: Toolbar hierarchy

      +

      Toolbar hierarchy

      + + +

      This UI component is a scrollable list of items and shows a menu when an item is selected. Only one item can be selected at a time.

      + +

      Adding and Configuring a Toolbar Component

      + +

      Use the following function to create a toolbar.

      +
      +Evas_Object *toolbar, *parent;
      +
      +toolbar = elm_toolbar_add(parent);
      +
      + +

      Using the Toolbar Styles

      +

      The toolbar has the following styles:

      +
        +
      • default
      • +
      • tabbar
      • +
      • tabbar_with_title
      • +
      • navigationbar
      • +
      +

      The following example sets the style to navigationbar.

      +
      +elm_object_style_set(toolbar, "navigationbar");
      +
      + +

      Configuring the Toolbar

      +

      The toolbar displays its items in one of the following options.

      +
        +
      • ELM_TOOLBAR_SHRINK_NONE: The toolbar sets a minimum size to its items so that all of them fit without scrolling.
      • +
      • ELM_TOOLBAR_SHRINK_HIDE: The toolbar does not scroll or show the items that do not fit in.
      • +
      • ELM_TOOLBAR_SHRINK_SCROLL: The toolbar scrolls to show the items that do not fit in.
      • +
      • ELM_TOOLBAR_SHRINK_MENU: The toolbar creates a button to popup hidden items.
      • +
      + +

      Here the toolbar is set to ELM_TOOLBAR_SHRINK_NONE.

      +
      +elm_toolbar_shrink_mode_set(toolbar, ELM_TOOLBAR_SHRINK_NONE);
      +
      +

      By default, the toolbar displays items homogeneously. Items with long labels occupy a lot of space. To avoid that, you can disable the homogeneous mode.

      +
      +elm_toolbar_homogeneous_set(toolbar, EINA_FALSE);
      +
      + +

      Adding Items to the Toolbar

      +

      The following example shows how to add two items and choose the associated icon, label, and function to call when the item is clicked.

      +
      +{
      +   Elm_Object_Item *home_it, *help_it;
      +
      +   home_it = elm_toolbar_item_append(toolbar, "home", "Home",
      +                                    _home_item_pressed_cb, NULL);
      +   help_it = elm_toolbar_item_append(toolbar, "help", "Help",
      +                                    _help_item_pressed_cb, NULL);
      +}
      +
      +static void
      +_home_item_pressed_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   dlog_print(DLOG_INFO, LOG_TAG, "Home item clicked \n");
      +}
      +
      +static void
      +_help_item_pressed_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   dlog_print(DLOG_INFO, LOG_TAG, "Help item clicked \n");
      +}
      +
      + +

      An item can be disabled. This is how to disable the help item. The disabled item does not receive input and, if the theme supports it, is themed differently (usually greyed out) from its normal state.

      +
      +elm_object_item_disabled_set(help_it, EINA_TRUE);
      +
      + +

      Adding Items with States

      +

      Items have two or more states. Each state has its own icon, label, and function to call when an item is clicked. The following example shows how to create two states to the help item with the same icon but two different labels.

      +
      +elm_toolbar_item_state_add(help_it, "help", "Help state 1",
      +                           _help_item_pressed_cb, NULL);
      +elm_toolbar_item_state_add(help_it, "help", "Help state 2",
      +                           _help_item_pressed_cb, NULL);
      +
      +

      It is possible to cycle through the states of the help item by using the following code.

      +
      +elm_toolbar_item_state_set(help_it, elm_toolbar_item_state_next(help_it));
      +
      + +

      Using the Toolbar Callbacks

      +

      This UI component emits the following signals:

      +
        +
      • clicked: The user clicks on a toolbar item, which is selected. event_info is an object of the type Elm_Toolbar_Item.
      • +
      • clicked,double: The user double-clicks on a toolbar item. event_info is an object of the type Elm_Toolbar_Item.
      • +
      • longpressed: The toolbar is pressed for a certain amount of time. event_info is an object of the type Elm_Toolbar_Item.
      • +
      • language,changed: The program language changes.
      • +
      • item,focused: The item is highlighted. event_info is an object of the type Elm_Toolbar_Item.
      • +
      • item,unfocused: The highlight is removed from the item. event_info is an object of the type Elm_Toolbar_Item.
      • +
      • scroll: The toolbar scrolls. event_info is NULL.
      • +
      • scroll,anim,start: The toolbar scrolling animation starts. event_info is NULL.
      • +
      • scroll,anim,stop: The toolbar scrolling animation stops. event_info is NULL.
      • +
      • scroll,drag,start: The user starts dragging the toolbar. event_info is NULL.
      • +
      • scroll,drag,stop: The user stops dragging the toolbar. event_info is NULL.
      • +
      +

      The following example shows how to register a callback on the clicked signal.

      +
      +{
      +   evas_object_smart_callback_add(toolbar, "clicked", clicked_cb, data);
      +}
      +
      +// Callback function for the "clicked" signal
      +// This callback is called when a toolbar item is clicked
      +void clicked_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   Elm_Toolbar_Item * item = event_info;
      +
      +   dlog_print(DLOG_INFO, LOG_TAG, "Item clicked\n");
      +}
      +
      + +

      Tooltip

      + +

      The tooltip component is a smart object that shows a content in a frame when mouse hovers a parent object. The UI component provides tips or information about the parent object.

      + +

      Adding a Tooltip

      +

      The tooltip component cannot be created with the elm_tooltip_add() function. This component is already contained in a parent component when it is created. You can only activate or disable it.

      + +

      Activating the Tooltip

      +

      To activate the tooltip on a parent object, you can set a tooltip text to the parent object.

      +
      +Evas_Object *parent;
      +
      +elm_object_tooltip_text_set(parent, "The tooltip text";
      +
      +

      You can also set a content to the parent object.

      +
      +{
      +   elm_object_tooltip_content_cb_set(parent, tooltip_content_cb, NULL, tooltip_content_del_cb);
      +}
      +
      +Evas_Object*
      +tooltip_content_cb(void*data, Evas_Object *obj, Evas_Object *tooltip)
      +{
      +   // Create the tooltip content 
      +}
      +
      +void tooltip_content_del_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   // Destroy the tooltip content 
      +}
      +
      + +

      When passing content to the tooltip, the tooltip_content_cb function is called each time the tooltip is showed. The role of this function is to create the content to set in the tooltip. It returns a pointer to an Evas_Object.

      +

      When the tooltip disappears, the tooltip_content_del_cb function is called. This function is in charge of deleting the previously allocated Evas_Object.

      +

      Once set, the tooltip can be manually hidden or shown.

      + +
      +elm_object_tooltip_hide(parent);
      +elm_object_tooltip_show(parent);
      +
      + +

      The tooltip can be removed from the parent object when it is not needed.

      +
      +elm_object_tooltip_unset(parent);
      +
      + + + + + + + + + + +
      Note
      When content is set into the tooltip object, unsetting it calls the callback provided as del_cb to notify that the tooltip cannot be used any longer.
      + +

      A tooltip object is not a UI component, so it does not emit signals. There are no registered callbacks for it.

      + + +

      Win

      + +

      Figure: Win hierarchy

      +

      Win hierarchy

      + + +

      The window component is the root UI component that is often used in an application. It allows the developer create content in it, and it is handled by the window manager.

      +

      The window component is created with the elm_win_add() or elm_win_util_standard_add() function. The content can be added in the window with elm_win_resize_object_add() so that a window resize also resizes the content inside.

      + +

      Adding a Window Component

      + +

      Create a new window and change the title.

      +
      +Evas_Object *window;
      +
      +// Create a window 
      +window = elm_win_add(NULL, "main", ELM_WIN_BASIC);
      +
      +// Change the window title 
      +elm_win_title_set(window, "Example Window");
      +
      + +

      The first element of elm_win_add() is the parent window. For example, for a dialog you want to have the main window as the parent. Here, it is NULL, meaning there is no parent. main is the name of the window used by the window manager for identifying the window uniquely amongst all the windows within this application (and all instances of the application). The type is a basic window (the final parameter).

      + +

      Create a new window with a title and a background. This API is a shortcut of the previous one. It also creates a standard background to the window with elm_bg_add(). The window created is of the type ELM_WIN_BASIC.

      + +
      +Evas_Object *window;
      +
      +// Create a standard window 
      +window = elm_win_util_standard_add("main", "Example Window");
      +
      + +

      Closing a Window

      +

      When the user closes the window outside of the program control, a delete,request signal is emitted to indicate that this event occurred. The developer can take any action, for example, destroy the window object.

      +

      When the autodel parameter is set, the window is automatically destroyed after the signal is emitted. If autodel is EINA_FALSE, the window is not destroyed and the program does so when required. The default is EINA_FALSE, where the window is not destroyed automatically.

      +

      The autodel is set using the following call:

      +
      +elm_win_autodel_set(window, EINA_TRUE);
      +
      + +

      To close the window, use the evas_object_del() function. The window is destroyed and the signal delete,request is sent.

      + +

      Using the Window Callbacks

      +

      The window component emits the following signals:

      +
        +
      • focus,in: The window received focus.
      • +
      • focus,out: The window lost focus.
      • +
      • moved: The window that holds the canvas is moved.
      • +
      • withdrawn: The window is managed normally but is removed from the view.
      • +
      • iconified: The window is minimized (for example, into an icon or a taskbar).
      • +
      • normal: The window is in the normal state (not withdrawn or iconified).
      • +
      • stick: The window shows on all desktops.
      • +
      • unstick: The window shows only on one desktop.
      • +
      • fullscreen: The window is fullscreen.
      • +
      • unfullscreen: The window stops being fullscreen.
      • +
      • maximized: The window is maximized.
      • +
      • unmaximized: The window is diminished.
      • +
      • wm,rotation,changed: The rotation of the window is changed by the Windows Manager.
      • +
      • ioerr: A low-level I/O error occurred in the display system.
      • +
      +

      With all these signals, event_info is NULL.

      +

      The following example registers a callback function called on the fullscreen signal.

      +
      +{
      +   evas_object_smart_callback_add(window, "fullscreen", fullscreen_cb, data);
      +}
      +
      +// Callback function for the "fullscreen" signal
      +// This callback is called when the window becomes fullscreen
      +void fullscreen_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   dlog_print(DLOG_INFO, LOG_TAG, "Window fullscreen\n");
      +}
      +
      + + + + + + + + + + +
      Note
      Except as noted, this content is licensed under LGPLv2.1+.
      + + + + +
      + +Go to top + + + + + + + + diff --git a/org.tizen.ui.guides/html/native/efl/components_wn.htm b/org.tizen.ui.guides/html/native/efl/components_wn.htm new file mode 100755 index 0000000..07466b0 --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/components_wn.htm @@ -0,0 +1,2481 @@ + + + + + + + + + + + + + + Using Wearable UI Components + + + + + + +
      +

      Using Wearable UI Components

      + + + + + + + + + + +
      Note
      This feature is supported in wearable applications only.
      + +

      Background

      + +

      Figure: Red color background

      +

      Red color background

      + +

      Figure: Background hierarchy

      +

      Background hierarchy

      + +

      The background component can be used to set a solid background decoration to a window or to a container object. It works like an image, but has some background specific properties, for example it can be set to a tiled, centered, scaled, or stretched mode. There are no specific signals relative to background object.

      + +

      Adding a Background Component

      + +

      A background is created with the elm_bg_add() function.

      + +
      +Evas_Object *bg, *parent;
      +
      +// Create a background
      +bg = elm_bg_add(parent);
      +
      + +

      Changing the Color of the Background

      + +

      You can set the color of the background with the elm_bg_color_set() function. The following example sets the background color to red.

      + +
      +Evas_Object *bg;
      +
      +// Use red color for background
      +elm_bg_color_set(bg, 0xFF, 0x00, 0x00);
      +
      + +

      Changing the Image of the Background

      + +

      It is also possible to set an image or an Edje group as a background using the elm_bg_file_set() function. The display mode of the image in the background can be chosen with elm_bg_option_set(), where the following modes are available:

      + +
        +
      • ELM_BG_OPTION_CENTER: center the background image.
      • +
      • ELM_BG_OPTION_SCALE: scale the background image, retaining aspect ratio.
      • +
      • ELM_BG_OPTION_STRETCH: stretch the background image to fill the UI component's area.
      • +
      • ELM_BG_OPTION_TILE: tile the background image at its original size.
      • +
      + +
      +Evas_Object *bg;
      +
      +// Set a file on the disk as a background image
      +elm_bg_file_set(bg, "/path/to/the/image", NULL);
      +// Set an Edje group as a background image
      +elm_bg_file_set(bg, "/path/to/the/edje", "edje_group");
      +elm_bg_option_set(bg, ELM_BG_OPTION_STRETCH)
      +
      + +

      Using Overlay

      + +

      An overlay can be set using the overlay part name.

      + +
      +elm_object_part_content_set(bg, "overlay", over);
      +
      + +

      Here, the overlay is an Edje object that is displayed on top of the current background object.

      + + +

      Button

      + +

      Figure: Button component

      +

      Button component

      + +

      Figure: Button hierarchy

      +

      Button hierarchy

      + +

      The Elementary button component is a simple push button. It is composed of a label icon and an icon object and has an autorepeat feature.

      + +

      Adding a Button Component

      + +

      Create a button.

      +
      +Evas_Object *button, *parent;
      +
      +// Create a button
      +button = elm_button_add(parent);
      + +

      Adding an Icon Inside a Button

      + +

      The icon can be updated with elm_object_part_content_set() function with the icon part name.

      + +
      +Evas_Object *ic;
      +ic = elm_icon_add(button);
      +elm_image_file_set(ic, "icon.png", NULL);
      +elm_object_part_content_set(button, "icon", ic);
      + +

      Adding Text Inside a Button

      + +

      The label can be modified using the elm_object_text_set() function.

      + +
      +elm_object_text_set(button, "Click me!");
      +
      + +

      Using Button Styles

      + +

      Various styles can be used on the button. Tizen supports the following styles for wearable core controls:

      +
        +
      • default
      • +
      • green
      • +
      • orange
      • +
      • red
      • +
      • nextdepth
      • +
      +

      Tizen supports the following styles for Gear O:

      +
        +
      • default
      • +
      • bottom
      • +
      + +

      To change the style of the button, call the elm_object_style_set() function on the button object.

      + +
      +// Example for wearable core control
      +elm_object_style_set(button, "nextdepth");
      +
      +// Example for Gear O
      +elm_object_style_set(button, "bottom");
      +
      + +

      Using the Button Callbacks

      + +

      The button emits the following signals:

      + +
        +
      • clicked: The user clicked the button (press/release).
      • +
      • repeated: The user pressed the button without releasing it.
      • +
      • pressed: The user pressed the button.
      • +
      • unpressed: The user released the button after pressing it.
      • +
      + +

      For all these signals the event_info parameter returned in the callback is NULL.

      + +

      This is an example to register and define a callback function called by the clicked signal.

      +
      +{
      +   evas_object_smart_callback_add(button, "clicked", clicked_cb, data);
      +}
      +// Callback function for the "clicked" signal
      +// This callback is called when the button is clicked by the user
      +void clicked_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   dlog_print(DLOG_INFO, LOG_TAG, "Button clicked\n");
      +}
      +
      + +

      Using the Autorepeat Feature

      + +

      The autorepeat feature is enabled by default. It consists of calling the repeated signal when the user keeps the button pressed. This feature can be disabled with the elm_button_autorepeat_set() function. The autorepeat is configured with the following functions:

      +
        +
      • elm_button_autorepeat_initial_timeout_set(): to set the initial timeout before the autorepeat event is generated
      • +
      • elm_button_autorepeat_gap_timeout_set(): to set the interval between two autorepeat events
      • +
      + +

      Disable the autorepeat feature.

      +
      +elm_button_autorepeat_set(button, EINA_FALSE);
      +
      + +

      Enable the autorepeat feature.

      +
      +elm_button_autorepeat_set(button, EINA_TRUE);
      +
      + +

      Set the initial timeout to five seconds.

      +
      +elm_button_autorepeat_initial_timeout_set(button, 5.0);
      +
      + +

      Set the gap between two signals to 0.5 seconds.

      +
      +elm_button_autorepeat_gap_timeout_set(button, 0.5);
      +
      + + +

      Check

      + +

      Figure: Check component

      +

      Check component

      + +

      Figure: Check hierarchy

      +

      Check hierarchy

      + +

      The check component is similar to the radio component, except that it does not work as a group. It toggles the value of a boolean between true and false.

      + +

      This UI component inherits from the layout component. All layout functions can be used on the check component.

      + +

      Adding a Check Component

      + +

      The following example shows how to create a check component.

      +
      +Evas_Object *check, *parent;
      +check = elm_check_add(parent);
      +
      + +

      Modifying the Check Styles

      + +

      The check component style can be set with the elm_object_style_set() function.

      +

      The following styles are available for wearable core controls:

      +
        +
      • default
      • +
      • on and off
      • +
      +

      The following styles are available for Gear O:

      +
        +
      • default
      • +
      • small
      • +
      • on and off
      • +
      + +

      The following example sets the on and off style on our check object.

      +
      +elm_object_style_set(check, "on and off");
      +
      + +

      To get the current style, use the elm_object_style_get() function.

      +
      +char *style = elm_object_style_get(check);
      +
      + +

      Using the Check Component

      + +

      After having created a check object, it is possible to set its boolean value to EINA_TRUE.

      +
      +elm_check_state_set(check, EINA_TRUE);
      +
      + +

      You can also retrieve the current value of the check object.

      +
      +Eina_Bool value = elm_check_state_get(check);
      +
      + +

      As with a radio object, an icon can be set for the wearable core control.

      +
      +// Create a Home icon 
      +Evas_Object *icon;
      +
      +icon = elm_icon_add(parent);
      +elm_icon_standard_set(icon, "home");
      +
      +// Set it to the check object 
      +elm_object_part_content_set(check, "icon", icon);
      +
      + +

      The get functions of the elementary object API can be used to retrieve the content set to the check object.

      +
      +// Get the content set in the icon part 
      +Evas_Object *icon = elm_object_part_content_get(check, "icon");
      +
      + +

      Using the Check Callbacks

      + +

      When the value is changed by the user, the changed signal is emitted. The event_info parameter is NULL.

      + +

      The following example shows how to register a callback on this signal.

      + +
      +{
      +   evas_object_smart_callback_add(check, "changed", changed_cb, data);
      +}
      +
      +// Callback function for the "changed" signal
      +// This callback is called when the check value changes
      +void changed_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   dlog_print(DLOG_INFO, LOG_TAG, "The value has changed\n");
      +}
      +
      + +

      Ctxpopup

      + +

      Figure: Context popup component

      +

      Context popup component

      + +

      Figure: Context popup hierarchy

      +

      Context popup hierarchy

      + + +

      Ctxpopup is a contextual popup that can show a list of items.

      + +

      Adding a Ctxpopup Component

      + +

      A ctxpopup can be created with the elm_ctxpopup_add() function, and when shown, it automatically chooses an area inside its parent object's view (set using elm_ctxpopup_hover_parent_set()) to optimally fit into it.

      + +
      +Evas_Object *ctxpopup, *parent;
      +
      +// Create a ctxpopup 
      +ctxpopup = elm_ctxpopup_add(parent);
      +
      + +

      Modifying the Ctxpopup Style

      + +

      The following styles are available for wearable core controls:

      +
        +
      • default
      • +
      +

      The following styles are available for Gear O:

      +
        +
      • select_mode
      • +
      • select_mode/top, select_mode/bottom (These two styles can be used as a pair.)
      • +
      + + +

      The following example shows how to set the default style.

      +
      +elm_object_style_set(ctxpopup, "default");
      +
      + +

      Configuring the Ctxpopup

      + +

      The context popup orientation can be set with elm_ctxpopup_horizontal_set(). Here it is set to horizontal.

      +
      +elm_ctxpopup_horizontal_set(ctxpopup, EINA_TRUE);
      +
      + +

      Auto hide is enabled by default. You can also disable auto hiding if you want the ctxpopup never to be hidden.

      +
      +elm_ctxpopup_auto_hide_disabled_set(ctxpopup, EINA_TRUE);
      +
      + +

      Managing the Ctxpopup Items

      + +

      The ctxpopup can contain a small number of items. Each of them can have a label and an icon. The following example shows how to append an item with the Test label and no icon.

      +
      +Elm_Object_Item *it;
      +
      +it = elm_ctxpopup_item_append(ctxpopup, "test", NULL, _ctxpopup_item_cb, 
      +                  NULL);
      +
      + +

      The _ctxpopup_item_cb() callback is called when the item is clicked. The following example shows how to write the definition of this callback.

      +
      +static void
      +_ctxpopup_item_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   dlog_print(DLOG_INFO, LOG_TAG, "ctxpopup item selected\n");
      +}
      +
      + +

      After that the item label is set to New label.

      +
      elm_object_item_part_text_set(it, "default", "New label");
      +
      + +

      And its icon is modified to the standard home icon.

      +
      +Evas_Object *home_icon = elm_icon_add(ctxpopup);
      +elm_icon_standard_set(home_icon, "home");
      +
      +elm_object_item_part_content_set(it, "icon", home_icon);
      +
      + +

      Using the Ctxpopup Callbacks

      + +

      The context popup emits the dismissed signal when it is dismissed. You can register a callback to this signal. The event_info parameter is NULL.

      + +
      +{
      +   evas_object_smart_callback_add(ctxpopup, "dismissed", dismissed_cb, data);
      +}
      +
      +// Callback function for the "dismissed" signal
      +// This callback is called when the ctxpopup is dismissed
      +void dismissed_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   dlog_print(DLOG_INFO, LOG_TAG, "Ctxpopup dismissed\n");
      +}
      +
      + +

      Datetime

      + +

      Figure: Datetime selection

      +

      Datetime selection

      + +

      Figure: Datetime hierarchy

      +

      Datetime hierarchy

      + +

      The datetime component displays and adds date and time values.

      + +

      Adding a Datetime Component

      + +

      The UI component is created with elm_datetime_add().

      +

      The following fields can be controlled:

      +
        +
      • ELM_DATETIME_YEAR: the year field
      • +
      • ELM_DATETIME_MONTH: the month field
      • +
      • ELM_DATETIME_DATE: the date field
      • +
      • ELM_DATETIME_HOUR: the hour field
      • +
      • ELM_DATETIME_MINUTE: the minute field
      • +
      • ELM_DATETIME_AMPM: the AM/PM field
      • +
      + +

      Using the Datetime Styles

      + +

      The following styles are available:

      +
        +
      • datepicker_layout
      • +
      • timepicker_layout
      • +
      + +

      The following example creates the datepicker_layout style:

      +
      +elm_object_style_set(datetime, "datepicker_layout");
      +
      + +

      Setting the Datetime Format

      + +

      The format of the date and time can be configured with elm_datetime_format_set() using a combination of allowed Libc date format specifiers. In the following example the format is set to HH : MM.

      +
      +elm_object_style_set(datetime, "timepicker_layout");
      +elm_datetime_format_set(datetime, "%d/%b/%Y%I:%M");
      +
      +

      Please refer to the API documentation for a complete list of all the options available.

      + +

      Using the Datetime Callbacks

      + +

      A callback can be registered on the changed signal to detect when the Datetime field values are changed. The event_info parameter is NULL.

      +
      +{
      +   evas_object_smart_callback_add(datetime, "changed", changed_cb, data);
      +}
      +
      +// Callback function for the "changed" signal
      +// This callback is called when the datetime fields change
      +void changed_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   dlog_print(DLOG_INFO, LOG_TAG, "Datetime field changed. \n");
      +}
      + +

      The language,changed signal is emitted when the system locale changes.

      + + + +

      Entry

      + +

      Figure: Entry component

      +

      Entry component

      + +

      Figure: Entry component

      +

      Entry component

      + +

      Figure: Entry hierarchy

      +

      Entry hierarchy

      + +

      The entry component is a box where the user can enter text. It supports the following features:

      +
        +
      • text wrapping
      • +
      • multiline
      • +
      • scrolling
      • +
      • formatted markup text
      • +
      • password mode
      • +
      • filtering text
      • +
      • read/write from a file
      • +
      • theme style overrides
      • +
      + +

      Adding an Entry Component

      + +

      The entry component is created with the elm_entry_add() function, and the text inside the entry can be set with elm_entry_entry_set().

      +
      +Evas_Object *entry, *parent;
      +
      +entry = elm_entry_add(parent);
      +elm_entry_entry_set(entry, "A short text.");
      +
      + +

      Using the Text Editor

      + +

      You can append text to the end of existing content.

      +
      +elm_entry_entry_append(entry, "END");
      +
      + +

      You can also insert text at the current cursor position.

      +
      +elm_entry_entry_insert(entry, "CURSOR");
      +Eina_Bool Empty = elm_entry_is_empty(entry);
      +
      + +

      Call elm_entry_is_empty() to see whether the entry is empty. Here, the boolean variable Empty returns EINA_FALSE.

      +

      The user can enter text in the entry component when it is in focus. It is possible to prevent the user from editing text if needed.

      +
      +elm_entry_editable_set(entry, EINA_FALSE);
      +
      + + + + + + + + + + +
      Note
      It is still possible to use the previous functions to modify the text of a non-editable entry.
      + +

      Setting the Password Mode

      + +

      When dealing with password content, the password mode activates to hide what the user is typing. In this mode, the display of any text is replaced by asterisks (*), and the entry is single line (there is no line wrap).

      + +
      +elm_entry_password_set(entry, EINA_TRUE);
      +
      + +

      Entry Line Modes And Wrapping

      + +

      The entry component has two line modes:

      +
        +
      • single line mode
      • +
      • multiline mode
      • +
      + +

      First, set the entry in single line mode.

      + +
      +elm_entry_single_line_set(entry, EINA_TRUE);
      +
      + +

      In this mode, the text does not wrap when reaching the edge, but the entry grows horizontally instead. Pressing the Enter key in this mode generates an activate event instead of adding a new line.

      + +

      When the entry is set to multiline mode (single line off), the text wraps at the end of the entry and pressing Enter creates a new line.

      + +
      +elm_entry_single_line_set(entry, EINA_FALSE);
      +elm_entry_line_wrap_set(entry, ELM_WRAP_WORD);
      +
      + +

      In multiline entries, elm_entry_line_wrap_set() provides a way to cut the text implicitly into a new line when it reaches the far edge of the UI component. The following wrap modes are available:

      +
        +
      • ELM_WRAP_NONE: No wrap
      • +
      • ELM_WRAP_CHAR: Wrap between characters
      • +
      • ELM_WRAP_WORD: Wrap in allowed wrapping points (as defined in the unicode standard)
      • +
      • ELM_WRAP_MIXED: Word wrap, and if that fails, char wrap
      • +
      + +

      Selecting Text

      + +

      Text selections can be made with different functions:

      +
        +
      • To select all the content of the entry component: +
        +elm_entry_select_all(entry);
        +
        +
      • + +
      • To deselect the current selection: +
        +elm_entry_select_none(entry);
        +
        +
      • + +
      • To select part of the text, use elm_entry_select_region_set(). The following code selects the first twenty characters of the entry content. +
        +elm_entry_select_region_set(entry, 0, 20);
        +
        +
      • + +
      • To retrieve the currently selected text in an entry: +
        +const char *selection;
        +
        +selection = elm_entry_selection_get(entry);
        +
        +
      • +
      + +

      If the entry text is empty, elm_entry_selection_get() returns NULL.

      + +

      You can copy or cut the selection to the clipboard.

      +
      +elm_entry_selection_cut(entry);
      +
      + +

      The selection can be pasted in the same or a different entry.

      +
      +elm_entry_selection_paste(entry);
      +
      + +

      Controlling the Cursor

      + +

      The cursor represents the current position in the entry, where the next action, for example, text insertion or deletion, is done. Usually, the cursor is represented as a blinking character, but its appearance depends on the theme configuration. The cursor position can be modified by using several functions.

      +
        +
      • To move the cursor to the beginning of the entry: +
        +elm_entry_cursor_begin_set(entry);
        +
        +
      • + +
      • To move the cursor to the end of the entry: +
        +elm_entry_cursor_end_set(entry);
        +
        +
      • + +
      • To move the cursor one line down or up: +
        +elm_entry_cursor_down(entry);
        +elm_entry_cursor_up(entry);
        +
        +
      • +
      • To move the cursor one character to the left or right: +
        +elm_entry_cursor_prev(entry);
        +elm_entry_cursor_next(entry);
        +
        +
      • + +
      • To set the cursor at a specific position (15th character, for example): +
        +elm_entry_cursor_pos_set(entry, 15);
        +
        +
      • +
      + +

      It is possible to start a selection at the current cursor position, move five characters to the right and end the selection.

      +
      +elm_entry_cursor_selection_begin(entry);
      +
      +for (i = 0; i < 5; i++)
      +{
      +   elm_entry_cursor_next(entry);
      +}
      +
      +elm_entry_cursor_selection_end(entry);
      +
      + +

      Formatting Text

      + +

      Text within an entry can be formatted by using markups tags that are defined in the theme. The following markups are available in the default theme:

      +
        +
      • <br>: Inserts a line break.
      • +
      • <ps>: Inserts a paragraph separator. This is preferred over line breaks.
      • +
      • <tab>: Inserts a tab.
      • +
      • <em>...</em>: Emphasis. Sets the oblique style for the enclosed text.
      • +
      • <b>...</b>: Sets the bold style for the enclosed text.
      • +
      • <link>...</link>: Underlines the enclosed text.
      • +
      • <hilight>...</hilight>: Highlights the enclosed text.
      • +
      + +

      Using Special Markups

      + +

      Special markups can be added within the text of the entry:

      +
        +
      • <a href = ..>...</a>: Anchors
      • +
      • <item size = .. vsize = .. href = ..>...</item>: Items
      • +
      + +

      The anchors generate an anchor,clicked signal when the user clicks on them. The href attribute is used to identify the anchor. It also reacts to the anchor,in (mouse in), anchor,out (mouse out), anchor,down (mouse down), and anchor,up (mouse up) events.

      + +

      The item markup provides a way to insert any Evas_Object in the text. The Evas_Object name has to be specified in the href attribute.

      + +

      Overriding Style

      + +

      To tweak the style of the text within the entry component, it is possible to override parts of the theme style to the textblock object by using elm_entry_text_style_user_push(). This function pushes a new style on top of the user style stack that overrides the current style. Remove the style in the top of user style stack with elm_entry_text_style_user_pop().

      + +

      Filtering Text

      + +

      Text within an entry can be filtered in size. The following example sets the maximum number of characters allowed in the entry to 8.

      +
      +static Elm_Entry_Filter_Limit_Size limit_size = 
      +{
      +   .max_char_count = 8,
      +   .max_byte_count = 0
      +};
      +
      +// Append a new callback to the list, this function is called each time
      +// a text is inserted in the entry. Pass the limit_size struct previously
      +// created to set the maximum number of characters allowed to 8
      + 
      +elm_entry_markup_filter_append(entry, elm_entry_filter_limit_size, limit_size);
      +
      + +

      The content can be filtered by passing an Elm_Entry_Filter_Accept_Set structure. This structure contains the accepted characters and rejected characters. The following example shows how to reject the '+', '-', '*', and '/' characters.

      + +
      +static Elm_Entry_Filter_Accept_Set accept_set = 
      +{
      +   .accepted = NULL,
      +   .rejected = "+*-/"
      +};
      +
      +elm_entry_markup_filter_append(entry, elm_entry_filter_accept_set, accept_set);
      +
      + +

      Loading and Saving Files

      + +

      The entry content can be saved to a file (/tmp/test.txt, for example).

      + +
      +// Set the file in which the entry text is saved. This function
      +// implicitly loads the existing file content 
      +elm_entry_file_set(entry, "/tmp/test.txt", ELM_TEXT_FORMAT_MARKUP_UTF8);
      +
      + +

      Autosave is activated by default and changes are written back to the file after a short delay. This feature can be deactivated and you can manually save the content when needed.

      +
      +// Disable autosaving 
      +elm_entry_autosave_set(entry, EINA_FALSE);
      +
      +// Trigger saving when needed 
      +elm_entry_file_save(entry);
      +
      + +

      Using Entry Theme Content

      + +

      Two content parts of the default theme are available: icon and end. The following example shows how to set an icon in the end content part.

      + +
      +Evas_Object *icon;
      +
      +ic = elm_icon_add(entry);
      +elm_image_file_set(ic, "icon.png", NULL);
      +elm_object_part_content_set(entry, "end", icon);
      +
      + +

      Using Entry Theme Texts

      + +

      The default theme allows the use of the following text parts:

      +
        +
      • elm.text - text of the entry
      • +
      • elm.guide - placeholder of the entry
      • +
      + +

      The following example shows how to set the placeholder text of the entry to Hello World.

      +
      +elm_object_part_text_set(entry, "elm.guide", "Hello World");
      +
      + +

      Using Entry Callbacks

      + +

      The entry component emits the following signals:

      +
        +
      • aborted: The escape key is pressed on a single line entry.
      • +
      • activated: The enter key is pressed on a single line entry.
      • +
      • anchor,clicked: An anchor is clicked. event_info points to an object of the type Elm_Entry_Anchor_Info.
      • +
      • anchor,down: Mouse button is pressed on an anchor. event_info points to an object of the type Elm_Entry_Anchor_Info.
      • +
      • anchor,hover,opened: The anchor is clicked. event_info points to an object of the type Elm_Entry_Anchor_Info.
      • +
      • anchor,in: Mouse cursor is moved into an anchor. event_info points to an object of the type Elm_Entry_Anchor_Info.
      • +
      • anchor,out: Mouse cursor is moved out of an anchor. event_info points to an object of the type Elm_Entry_Anchor_Info.
      • +
      • anchor,up: Mouse button is unpressed on an anchor. event_info points to an object of the type Elm_Entry_Anchor_Info.
      • +
      • changed: The text within the entry is changed.
      • +
      • changed,user: The text within the entry is changed because of user interaction. event_info points to an object of the type Edje_Entry_Change_Info.
      • +
      • clicked: The entry is clicked (mouse press and release).
      • +
      • clicked,double: The entry is double clicked.
      • +
      • clicked,triple: The entry is triple clicked.
      • +
      • cursor,changed: The cursor position is changed.
      • +
      • cursor,changed,manual: The cursor position is changed manually.
      • +
      • focused: The entry receives focus. event_info points to an object of the type Elm_Focus_Info.
      • +
      • unfocused: The entry loses focus.
      • +
      • language,changed: Program language is changed.
      • +
      • longpressed: A mouse button is pressed and held for a couple of seconds.
      • +
      • maxlength,reached: A maximum length is reached.
      • +
      • preedit,changed: The preedit string is changed.
      • +
      • press: A mouse button is pressed on the entry.
      • +
      • redo,request: The request is redone.
      • +
      • selection,changed: The current selection is changed.
      • +
      • selection,cleared: The current selection is cleared.
      • +
      • selection,copy: A copy of the selected text into the clipboard is requested.
      • +
      • selection,cut: A cut of the selected text into the clipboard is requested.
      • +
      • selection,paste: A paste of the clipboard contents is requested.
      • +
      • selection,start: A selection is begun and no previous selection exists.
      • +
      • text,set,done: The whole text is set to the entry.
      • +
      • theme,changed: The theme is changed.
      • +
      • undo,request: The request is undone.
      • +
      + +

      For signals, where event_info has not been explicitly described, it is set to NULL.

      + +

      The following example shows how to register a callback to the focused signal.

      +
      +{
      +   evas_object_smart_callback_add(entry, "focused", focused_cb, data);
      +}
      +
      +// Callback function for the "focused" signal
      +// This callback is called when the entry receive the focus
      +void focused_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   dlog_print(DLOG_INFO, LOG_TAG, "Entry focused\n");
      +} 
      +
      + + +

      Genlist

      + +

      Figure: Genlist component

      +

      Genlist component

      + +

      Figure: Genlist hierarchy

      +

      Genlist hierarchy

      + +

      Genlist is a UI component that displays a scrollable list of items. It allows a lot of entries while being fast and has a low memory footprint, as only the visible items are allocated in the memory.

      + +

      For more information, see Creating Wearable Genlists.

      + +

      Genlist Item Style

      + +

      An item can have 0 or more texts, 0 or more contents, and 0 or more boolean states. This is defined in the Edje item theme style. Genlist looks for data items named respectively labels, contents, and states in the Edje file. The default item style provides one text part (elm.text), two content parts (elm.swallow.icon and elm.swallow.end) and no state parts.

      + +

      The following item styles are available:

      +
        +
      • default
      • +
      • groupindex
      • +
      • 1text
      • +
      • 1text.1icon
      • +
      • 2text
      • +
      • 2text.1
      • +
      • 1text.1icon.divider
      • +
      • 1text.1icon.1
      • +
      • 2text.1icon.1
      • +
      • multiline/1text
      • +
      • multiline/2text
      • +
      + +

      Here are some examples of the item styles.

      + +

      Figure: 1text item style

      +

      1 text item style

      + +

      Figure: 1text.1icon.1 item style

      +

      1text.1icon.1 item style

      + +

      Figure: 2text.1icon.1 item style

      +

      2text.1icon.1 item style

      + +

      For more information on creating a new genlist item style, see Customizing Components.

      + +

      Adding a Genlist Component

      + +

      A genlist component is added with the elm_genlist_add() function.

      +
      +Evas_Object *genlist, *parent;
      +genlist = elm_genlist_add(parent);
      +
      + +

      Creating And Deleting Items

      + +

      To save up memory, genlist allocates and deletes items on the go, while the user is scrolling the list. To enable that, the user creates and fills a Elm_Genlist_Item_Class structure that informs the genlist component which callbacks to call when an item is created or deleted.

      +
      +Elm_Genlist_Item_Class *itc = elm_genlist_item_class_new();
      +
      +itc->item_style = "default";
      +itc->decorate_item_style = NULL;
      +itc->decorate_all_item_style = NULL;
      +itc->func.text_get = _item_label_get;
      +itc->func.content_get = _item_content_get;
      +itc->func.state_get = _item_state_get;
      +itc->func.del = _item_del;
      +
      + +

      The item_style, decorate_item_style, and decorate_all_item_style attributes define the names of the item style, the decorate mode item style and the decorate all item style.

      + +

      The func structure contains pointers to functions that are called when an item is going to be created or deleted. All of them receive a data parameter that points to the same data passed to the elm_genlist_item_append() and related item creation functions, and an obj parameter that points to the genlist object itself.

      +
        +
      • text_get +

        This function receives a PART parameter that is the name string of one of the existing text parts in the Edje group implementing the item's theme. It has to return a string (duplicated with the strdup() function) corresponding to the PART parameter. The caller is in charge of freeing the string when done.

      • + +
      • content_get +

        The PART parameter is the name string of one of the existing swallow parts in the Edje group. When no content is desired, it must return NULL, or otherwise, a valid object handle. The object is deleted by the genlist on its deletion or when the item is unrealized.

      • + +
      • state_get +

        The PART parameter is the name string of one of the state parts in the Edje group implementing the item's theme. It returns EINA_FALSE for false/off or EINA_TRUE for true/on. The default is false. Genlists emit a signal to the PART parameter's theming Edje object with elm,state,xxx,active as emission and elm as source argument, when the state is true. xxx is the name of the (state) part.

      • + +
      • del +

        This function is called when the genlist item is deleted. It deletes any data that is allocated at the item creation.

      • +
      + +

      Managing Items

      + +

      To add an item, several functions can be used. elm_genlist_item_append() adds an item to the end of the list, or if there is a parent list, to the end of all the child items of the parent list. elm_genlist_item_prepend() is otherwise the same but adds to the beginning of the list or children lists. elm_genlist_item_insert_before() inserts an item before the indicated item and elm_genlist_item_insert_after() inserts an item after the indicated item.

      + +

      The previous functions take a type parameter that can be one of the following.

      +
        +
      • ELM_GENLIST_ITEM_NONE
      • +
      • ELM_GENLIST_ITEM_TREE
      • +
      • ELM_GENLIST_ITEM_GROUP
      • +
      + +

      If ELM_GENLIST_ITEM_TREE is set, this item is displayed as being able to expand and have child items. If ELM_GENLIST_ITEM_GROUP is set, this item is a group index item that is displayed at the top until the next group appears.

      + +

      Figure: Genlist tree

      +

      Genlist tree

      + +

      The application clears the list with elm_genlist_clear(), which deletes all the items in the list. elm_object_item_del() deletes a specific item. elm_genlist_item_subitems_clear() clears all items that are children of the indicated parent item.

      + +

      To help inspect the list items, move to the item at the top of the list with elm_genlist_first_item_get(), which returns the item pointer. elm_genlist_last_item_get() moves to the item at the end of the list. elm_genlist_item_next_get() and elm_genlist_item_prev_get() move to the next and previous items relative to the indicated item. Using these calls you can go through the entire item list or tree.

      + + + + + + + + + + +
      Note
      As a tree, the items are flattened on the list, so elm_genlist_item_parent_get() gives you the name of the parent item (even to skip them if needed).
      + +

      elm_genlist_item_show() scrolls the scroller to show the desired item as visible.

      +

      elm_object_item_data_get() returns the data pointer set by the item creation functions.

      + +

      If an item changes (state, boolean, text or content change), use elm_genlist_item_update() for the genlist to update the item. Genlist re-realizes the item and calls the functions in the _Elm_Genlist_Item_Class for it.

      + +

      Selection

      + +

      Items are manually selected or deselected with elm_genlist_item_selected_set() or disabled with elm_object_item_disabled_set(). In case there is a tree or a group item, the elm_genlist_item_expanded_set() function is used to expand or contract the item.

      + + + + + + + + + + +
      Note
      Calling this function does not show or hide any child of an item (if it is a parent). You must manually delete and create them on the callbacks of the expanded or contracted signals.
      + +

      By default, the genlist is in single-selection mode: only one item can be selected at a time. You can use elm_genlist_multi_select_set() to select multiple items. In the single-selection mode, the elm_genlist_selected_item_get() function can be called to retrieve the selected item. If several items are selected, the elm_genlist_selected_items_get() returns a list of the current selected items.

      + +

      In the following figure, there is a genlist in multi-selection mode with two items selected (#4 and #5) and one item disabled (#2).

      + +

      Figure: Genlist component

      +

      Genlist component

      + +

      Using Genlist Callbacks

      + +

      The genlist component emits the following signals:

      +
        +
      • activated: The user has double-clicked or pressed (enter | return | spacebar) on an item. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
      • +
      • clicked,double: The user has double-clicked an item. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
      • +
      • selected: The user selects an item. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
      • +
      • unselected: The user unselects an item. event_info in the callback function points at an object of type Elm_Object_Item that contains the activated item.
      • +
      • expanded: The item is to be expanded with elm_genlist_item_expanded_set(). This callback fills in the child items. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
      • +
      • contracted: The item is to be contracted with elm_genlist_item_expanded_set(). This callback deletes the child items. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
      • +
      • expand,request: The user wants to expand a tree branch item. The callback decides if the item can expand (if it has any children) and calls elm_genlist_item_expanded_set() to set the state. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
      • +
      • contract,request: The user wants to contract a tree branch item. The callback decides if the item can contract (if it has any children) and calls elm_genlist_item_expanded_set() to set the state. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
      • +
      • realized: The item is created as a real evas object. event_info in the callback function points at an object of the type Elm_Object_Item, that contains the activated item.
      • +
      • unrealized: An item is going to be unrealized. Content objects provided are deleted and the item object is deleted or put into a floating cache. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
      • +
      • drag,start,up: The item in the list is dragged (not scrolled) up. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
      • +
      • drag,start,down: The item in the list is dragged (not scrolled) down. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
      • +
      • drag,start,left: The item in the list is dragged (not scrolled) left. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
      • +
      • drag,start,right: The item in the list is dragged (not scrolled) right. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
      • +
      • drag,stop: The item in the list has stopped being dragged. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
      • +
      • drag: The item in the list is being dragged. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
      • +
      • longpressed: The item is pressed for a certain amount of time. The default specified time is one second. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
      • +
      • scroll,anim,start: The scrolling animation is started. event_info is NULL.
      • +
      • scroll,anim,stop: The scrolling animation is stopped. event_info is NULL.
      • +
      • scroll,drag,start: Dragging the content is started. event_info is NULL.
      • +
      • scroll,drag,stop: Dragging the content is stopped. event_info is NULL.
      • +
      • edge,top: The genlist is scrolled to the top edge. event_info is NULL.
      • +
      • edge,bottom: The genlist is scrolled to the bottom edge. event_info is NULL.
      • +
      • edge,left: The genlist is scrolled to the left edge. event_info is NULL.
      • +
      • edge,right: The genlist is scrolled to the right edge. event_info is NULL.
      • +
      • multi,swipe,left: The genlist is multi-touch swiped left. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
      • +
      • multi,swipe,right: The genlist is multi-touch swiped right. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
      • +
      • multi,swipe,up: The genlist is multi-touch swiped up. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
      • +
      • multi,swipe,down: The genlist is multi-touch swiped down. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
      • +
      • multi,pinch,out: The genlist is multi-touch pinched out. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
      • +
      • multi,pinch,in: The genlist is multi-touch pinched in. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
      • +
      • swipe: The genlist is swiped. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
      • +
      • moved: A genlist item is moved in the reorder mode. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
      • +
      • moved,after: A genlist item is moved after another item in the reorder mode. To access the relative previous item, use elm_genlist_item_prev_get(). This signal is called along with the moved signal. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
      • +
      • moved,before: A genlist item is moved before another item in the reorder mode. To access the relative previous item, use elm_genlist_item_next_get(). This signal is called along with the moved signal. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
      • +
      • language,changed The program's language is changed. event_info is NULL.
      • +
      • tree,effect,finished: A genlist tree effect is finished. event_info is NULL.
      • +
      + + +

      GLView

      + +

      Figure: GLView example

      +

      GLView example

      + +

      Figure: GLView hierarchy

      +

      GLView hierarchy

      + + +

      The GLView component renders OpenGL in an elementary object, which hides Evas GL complexity. For more information, see OpenGL ES.

      + +

      Adding a GLView Component

      + +

      Create a GLView component with the elm_glview_add() function.

      +
      +Evas_Object *glview, *parent;
      +
      +glview = elm_glview_add(parent);
      +
      + +

      In this example, the size of the GLView is set to 200x200 pixels.

      +
      +elm_glview_size_set(glview, 200, 200);
      +
      + +

      Using the GLView API

      + +

      You can configure the GLView rendering mode by activating the following rendering modes:

      +
        +
      • ELM_GLVIEW_ALPHA: Alpha channel rendering mode
      • +
      • ELM_GLVIEW_DEPTH: Depth buffer rendering mode
      • +
      • ELM_GLVIEW_STENCIL: Stencil buffer rendering mode
      • +
      • ELM_GLVIEW_DIRECT: Direct rendering mode
      • +
      • ELM_GLVIEW_CLIENT_SIDE_ROTATION: The client handles the GL view rotation if direct rendering is enabled
      • +
      + +

      In the following example, the alpha channel and depth buffer rendering mode are enabled.

      +
      +elm_glview_mode_set(glview, ELM_GLVIEW_ALPHA | ELM_GLVIEW_DEPTH);
      +
      + +

      The following example shows how to decide what to do with the GL surface when the GLView component is resized.

      +
      +elm_glview_resize_policy_set(glview, ELM_GLVIEW_RESIZE_POLICY_RECREATE);
      +
      + +

      The GL surface is destroyed and recreated to the new size (default function). The resize policy can also be set to ELM_GLVIEW_RESIZE_POLICY_SCALE. In that case, only the image object is scaled, not the underlying GL surface.

      + +

      The following example shows how to set the GLView rendering policy.

      +
      +elm_glview_render_policy_set(glview, ELM_GLVIEW_RENDER_POLICY_ALWAYS);
      +
      + +

      The GLView object is always redrawn during the rendering loop. It can also be set to ELM_GLVIEW_RENDER_POLICY_ON_DEMAND (default function), where the GLView component is redrawn only when it is visible.

      + +

      Register the callbacks:

      +
      elm_glview_init_func_set(glview, _init_gl_cb);
      +elm_glview_del_func_set(glview, _del_gl_cb);
      +elm_glview_resize_func_set(glview, _resize_gl_cb);
      +elm_glview_render_func_set(glview, _draw_gl_cb);
      +
      + +
        +
      • elm_glview_init_func_set() registers an init callback that is called at the GLView object creation.
      • +
      • elm_glview_del_func_set() registers a del function that is called when the GLView object is deleted.
      • +
      • elm_glview_resize_func_set() registers the resize function that is called during the rendering loop when the GLView object is resized.
      • +
      • elm_glview_render_func_set() registers the render function that is called when the GLView object must be redrawn.
      • +
      + +

      Using GLView Callbacks

      + +

      The GLView component emits the following signals:

      +
        +
      • focused: The GlView component is focused. The event_info parameter points at an object of the type Elm_Focus_Info.
      • +
      • unfocused: The GLView object is unfocused.
      • +
      + +

      To register a callback:

      +
      +{
      +   evas_object_smart_callback_add(glview, "focused", focused_cb, data);
      +}
      +
      +// Callback function for the "focused" signal
      +// This callback is called when the GLView is focused
      +void focused_cb(void *data, Evas_Object *obj, void  *event_info)
      +{
      +   Elm_Focus_Info *fi = event_info;
      +
      +   dlog_print(DLOG_INFO, LOG_TAG, "GLView is focused\n");
      +}
      +
      + +

      Icon

      + +

      Figure: Icon hierarchy

      +

      Icon hierarchy

      + +

      The icon component inherits from the image component. It is used to display images in an icon context.

      + +

      Adding an Icon Component

      + +

      You can create an icon and set it as a freedesktop.org Home standard icon.

      + +
      +Evas_Object *icon, *parent;
      +icon = elm_icon_add(parent);
      +elm_icon_standard_set(icon, "Home");
      +
      + +

      Changing Image File

      + +

      You can change the image by using an image in the filesystem (for example, /tmp/Home.png).

      +
      +elm_image_file_set(icon, "/tmp/Home.png", NULL);
      +
      + +

      You can also use a group in an Edje file (for example, /tmp/Home.edj).

      +
      +elm_image_file_set(icon, "/tmp/Home.edj", "elm/icon/Home/default");
      +
      + +

      A thumbnail can be generated and cached for future use. For this, you need the Ethumb library support.

      + +
      +elm_icon_thumb_set(icon, "/tmp/Home.png", NULL);
      +
      + +

      This function sets the file in the icon and enables the use of a cached thumbnail if it already exists. Otherwise, it creates a new thumbnail and caches it for future use.

      + +

      Using Icon Callbacks

      + +

      The icon component emits the following signals:

      +
        +
      • thumb,done: elm_icon_thumb_set() is completed with success.
      • +
      • thumb,error: elm_icon_thumb_set() fails.
      • +
      + +

      In both cases, event_info is NULL.

      + + +

      Image

      + +

      Figure: Image component

      +

      Image component

      + +

      Figure: Image hierarchy

      +

      Image hierarchy

      + +

      The image component can load and display an image from a disk file or a memory region.

      + +

      Adding an Image Component

      + +

      This object is created with elm_image_add().

      + +
      +Evas_Object *image, *parent;
      +image = elm_image_add(parent);
      +
      + +

      Configuring the Image Component

      + +

      Various properties of the image can be tuned. First, you can disable the elementary scaling so that the image does not scale but resizes on both directions.

      +
      +elm_image_no_scale_set(image, EINA_TRUE);
      +elm_image_resizable_set(image, EINA_TRUE, EINA_TRUE);
      +
      + +

      When scaling images, the smooth scaling algorithm can be used. It provides a better quality image but is slower than the default algorithm.

      +
      +elm_image_smooth_set(image, EINA_TRUE);
      +
      + +

      Preloading is used to load images without blocking the user interface. This preserves the reactivity of the user experience. The image is loaded in a thread. It can be disabled if desired.

      +
      +elm_image_preload_disabled_set(image, EINA_TRUE);
      +
      + +

      The image can be rotated or flipped. Here the image is rotated 180 degrees.

      +
      +elm_image_orient_set(image, ELM_IMAGE_ROTATE_180);
      +
      + +

      The following orientations are available:

      +
        +
      • ELM_IMAGE_ORIENT_0: No orientation change
      • +
      • ELM_IMAGE_ROTATE_90: Rotate the image 90 degrees clockwise
      • +
      • ELM_IMAGE_ROTATE_180: Rotate the image 180 degrees clockwise
      • +
      • ELM_IMAGE_ROTATE_270: Rotate the image 90 degrees counter-clockwise
      • +
      • ELM_IMAGE_FLIP_HORIZONTAL: Flip the image horizontally
      • +
      • ELM_IMAGE_FLIP_VERTICAL: Flip the image vertically
      • +
      • ELM_IMAGE_FLIP_TRANSPOSE: Flip the image along the bottom-left to top-right line
      • +
      • ELM_IMAGE_FLIP_TRANSVERSE: Flip the image along the top-left to bottom-right line
      • +
      + +

      If you want to keep the original aspect ration when resizing the image, you must define how the image fits into the object's area.

      +
      +// Tell the image to keep original aspect ratio 
      +elm_image_aspect_fixed_set(image, EINA_TRUE);
      +// Then let the image fill the entire object 
      +elm_image_fill_outside_set(image, EINA_TRUE);
      +
      + +

      In this configuration, part of the image can go outside the object. If elm_image_fill_outside_set is set to EINA_FALSE, the image stays inside the limits of the parent object.

      + +

      Using Image Callbacks

      + +

      The image component emits the following signals:

      +
        +
      • drop: The user drops an image typed object onto the object in question - the event info argument is the path to that image file
      • +
      • clicked: The user clicks the image. event_info is NULL.
      • +
      + +

      To register a callback when a user clicks on the image:

      +
      +{
      +   evas_object_smart_callback_add(image, "clicked", clicked_cb, data);
      +}
      +
      +// Callback function for the "clicked" signal
      +// This callback is called when the image is clicked
      +void clicked_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   dlog_print(DLOG_INFO, LOG_TAG, "Image clicked\n");
      +}
      +
      + +

      Index

      + +

      Figure: Index component

      +

      Index component

      + +

      Figure: Index hierarchy

      +

      Index hierarchy

      + +

      An index component gives you an index for fast access to whichever group of other UI items you have. The index component is by default hidden, but it appears when the user clicks over its reserved area in the canvas. In the default theme, it is a one finger wide area on the right side of the index component's container. Generally, an index is used together with lists, generic lists, or generic grids.

      + +

      Adding an Index Component

      + +

      Call the elm_index_add() function to create a new index component.

      +
      +Evas_Object *index, *parent;
      +index = elm_index_add(parent);
      +
      + +

      Adding Items

      + +

      The following example shows how to add the listitem object at the letter A, calling the smart callback it_select_cb() when this item is selected.

      +
      +Elm_Object_Item *list_item1, *list_item2;
      +elm_index_item_append(index, "A", it_select_cb, list_item1);
      +
      + +

      The following example shows how to add item objects, calling the smart callback it_select_cb() when the item is selected.

      +
      +Elm_Object_Item *it[5];
      +for (i = 0; i < 5; ++i)
      +{
      +   it[i] = elm_index_item_append(index, NULL, it_select_cb, (void *) i);
      +}
      + +

      The following example shows how to define the smart callback.

      +
      +// Callback function called when the list_item1 object
      +// is selected
      +void it_select_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   dlog_print(DLOG_INFO, LOG_TAG, "Item1 selected\n");
      +}
      +
      + +

      In the previous case, the indexes are appended to the existing ones. It is also possible to prepend index items with elm_index_item_prepend().

      + + +

      Using Index Callbacks

      + +

      The index component emits the following signals:

      +
        +
      • changed: The selected index item changes. event_info is the selected item's data pointer.
      • +
      • delay,changed: The selected index item changes, but after a small idling period. event_info is the selected item's data pointer.
      • +
      • selected: The user releases a mouse button and selects an item. event_info is the selected item's data pointer.
      • +
      • level,up: The user moves a finger from the first level to the second level.
      • +
      • level,down: The user moves a finger from the second level to the first level.
      • +
      + +

      When the user selects an item in the index, the selected signal is emitted. The developer can then implement the associated callback to do the appropriate action (to show a given area or child object depending on the index item selected, for example). Here is an example of such a callback.

      +
      +static void
      +_index_selected_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   Elm_Object_Item *lit = event_info;
      +
      +   // Code that does the desired action
      +}
      +
      + +

      After that, the callback to the selected signal is registered.

      +
      +evas_object_smart_callback_add(index, "selected", _index_selected_cb, NULL);
      +
      + + +

      Label

      + +

      Figure: Label component

      +

      Label component

      + +

      Figure: Label hierarchy

      +

      Label hierarchy

      + +

      The label component displays text with simple html-like markup.

      + +

      Adding a Label Component

      + +

      To add a label and set the text in it, use the following functions.

      + +
      +Evas_Object *label = elm_label_add(win);
      +
      +elm_object_text_set(label, "Some long text for our label, that is not so long");
      +
      + +

      Using the Label Styles

      + +

      Label displays the text with several predefined styles.

      +
        +
      • default: No animation
      • +
      • marker: The text is centered and bolded.
      • +
      • slide_long: The text appears from the right of the screen and slides until it disappears in the left of the screen(reappearing on the right again).
      • +
      • slide_roll: The text appears from the left of the label and slides to the right to show the overflow, and then appears from the right of the label again.
      • +
      • slide_short: The text appears in the left of the label and slides to the right to show the overflow. When all of the text has been shown the position is reset.
      • +
      • slide_bounce: The text appears in the left of the label and slides to the right to show the overflow. When all of the text has been shown, the animation reverses, moving the text to the left.
      • +
      + +

      Here the style is set to slide_roll.

      + +
      +elm_object_style_set(label, "slide_roll");
      +
      + +

      Configuring the Label

      + +

      The duration of the animation and the slide mode can be set with the following functions.

      +
      +elm_label_slide_duration_set(label, 3);
      +elm_label_slide_mode_set(label, ELM_LABEL_SLIDE_MODE_ALWAYS);
      +
      + +

      Use the following function to modify the style.

      +
      +elm_object_style_set(label, "slide_bounce");
      +
      + +

      Using the Label Callbacks

      + +

      This UI component emits the following signals:

      +
        +
      • language,changed: The program's language changes.
      • +
      • slide,end: The slide reaches the end.
      • +
      • anchor,clicked: The anchor is clicked. event_info points to an object of the type Elm_Label_Anchor_Info.
      • +
      • anchor,mouse,down event_info points to an object of the type Elm_Label_Anchor_Info.
      • +
      • anchor,mouse,up event_info points to an object of the type Elm_Label_Anchor_Info.
      • +
      + +

      The following example registers a callback on the slide,end signal.

      + +
      +{
      +   evas_object_smart_callback_add(label, "slide,end", slide_end_cb, data);
      +}
      +
      +// Callback function for the "slide,end" signal
      +// This callback is called when the label slide reaches the end
      +void slide_end_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   dlog_print(DLOG_INFO, LOG_TAG, "Slide has reach the end.\n");
      +}
      +
      + +

      List

      + +

      Figure: List component

      +

      List component

      + +

      Figure: List hierarchy

      +

      List hierarchy

      + + +

      This UI component is a very simple type of a list component. It is not to be used to manage a lot of items. For that, genlists are a better option.

      + +

      The list items can contain a text and two contents (start and end). These are set with the elm_object_item_*() functions.

      + +

      Adding a List Component

      + +
      +Evas_Object *list, *parent;
      +
      +// Create a list 
      +list = elm_list_add(parent);
      +
      + +

      Using the List

      + +

      This UI component implements the scrollable interface, so the scroller component functions can be used on it. For example, if you want to change the bounce property of the scroller or the scrolling policy:

      + +
      +Evas_Object *list;
      +
      +// Change the scroller policy to fix the scroll only vertically
      +elm_scroller_policy_set(list, ELM_SCROLLER_POLICY_OFF, ELM_SCROLLER_POLICY_AUTO);
      +// Enable bounce effect when the list reaches the upper and lower limits 
      +elm_scroller_bounce_set(list, EINA_FALSE, EINA_TRUE);
      +
      + +

      The elm_list_multi_select_set() function can be called to enable multi-selection of items. Each time an item is clicked, the state changes to selected.

      + +
      +Evas_Object *list;
      +
      +// Activate multi selection 
      +elm_list_multi_select_set(list, EINA_FALSE);
      +
      + +

      Adding Item to the List

      + +

      Items are added with elm_list_item_append() or elm_list_item_prepend(). Here an example of adding ten items with text and one icon on the front: The last two arguments are the callback function when the created item is clicked and the data passed to the callback function.

      + +
      +Evas_Object *list;
      +int i;
      +
      +// This function is called when the list item is selected 
      +static void _selected_item_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   Elm_Object_Item *list_it = elm_list_selected_item_get(obj);
      +   Eina_Bool selected = elm_list_item_selected_get(list_it);
      +   dlog_print(DLOG_INFO, LOG_TAG, "item is %s\n", selected? "selected": "unselected");
      +}
      +
      +for (i = 0; i < 10; i++)
      +{
      +   Evas_Object *ic;
      +   char tmp[8];
      +   snprintf(tmp, sizeof(tmp), "Item %02d", i);
      +   // Create an icon 
      +   ic = elm_icon_add(win);
      +   // Set the file to the icon file 
      +   elm_image_file_set(ic, "path/to/file", NULL);
      +   // Add item to the list 
      +   elm_list_item_append(list, tmp, ic, NULL, _selected_item_cb, NULL);
      +}
      +
      +
      + +

      Changing the Text or Icon of an Item

      + +

      If you want to change the state of an item, you can do it by using all the functions relative to Elm_Object_Item. Each item of the list contains two instances of an evas_object. Give those as the third and the fourth arguments when you append or prepend the item in the list. The evas_object instances are changed with elm_object_item_part_content_set. The first object is referenced as the start object in the theme, whereas the second one is referenced as the end object. Give these names when you use the elm_object_item_part_content_set. The label of the item is changed by using elm_object_item_text_set.

      + +
      +Evas_Object *list;
      +Eina_List *l;
      +Elm_Object_Item *it;
      +
      +// Retrieve the current selected item 
      +it = elm_list_selected_item_get(list);
      +if (!it)
      +   return;
      +
      +ic = elm_icon_add(win);
      +// Set the file to the icon file 
      +elm_image_file_set(ic, "path/to/file", NULL);
      +// Change the first icon 
      +elm_object_item_part_content_set(it, "start", ic);
      +// Change the second icon 
      +elm_object_item_part_content_set(it, "end", ic);
      +// Change the label 
      +elm_object_item_text_set(it, "I've been selected !");
      +
      + +

      Retrieving Selected Items

      + +

      The list of the currently selected items is retrieved with elm_list_selected_items_get(). If the multiselect mode is false, you can retrieve the only selected item with elm_list_selected_item_get(). For example, this is how to unselect all previously selected items.

      + +
      +Evas_Object *list; Eina_List *l;
      +Eina_List *selected_items;
      +// List of Elm_Object_Item 
      +Elm_Object_Item *it;
      +
      +selected_items = elm_list_selected_items_get(list);
      +EINA_LIST_FOREACH(selected_items, l, it)
      +   elm_list_item_selected_set(it, EINA_FALSE);
      +
      + +

      List Item Operations

      + +

      To find out if an item is selected, call elm_list_item_selected_get. This function returns EINA_TRUE if the item is selected, otherwise EINA_FALSE.

      + +

      Elementary list provides two functions for sliding a list to a specific item. elm_list_item_show shows the item passed as an argument, whereas elm_list_item_bring_in shows the item, but only after animating the slide.

      + +

      You can go to the item immediately preceding a specific item with the function elm_list_item_prev, or to the one immediately following a specific item with the function elm_list_item_next.

      + +

      The following example shows selecting the item immediately following the currently selected one, unselecting it, selecting the next one and bringing it to the screen.

      + +
      +Evas_Object *list;
      +Elm_Object_Item *current, *next;
      +current = elm_list_selected_item_get(list);
      +elm_list_item_selected_set(current, EINA_FALSE);
      +next = elm_list_item_next(current);
      +elm_list_item_selected_set(next, EINA_TRUE);
      +elm_list_item_bring_in(next);
      +
      + +

      Using List Callbacks

      + +

      The list emits the following signals:

      +
        +
      • activated: The user double-clicks or presses (enter | return | spacebar) on an item. The event_info parameter of the callback function contains a pointer to the item activated.
      • +
      • clicked,double: The user double-clicks an item. The event_info parameter of the callback function contains a pointer to the item activated.
      • +
      • selected: The user selects an item. The event_info parameter of the callback function contains a pointer to the item activated.
      • +
      • unselected: The user unselects an item. The event_info parameter of the callback function contains a pointer to the item activated.
      • +
      • longpressed: The user long-presses an item. The event_info parameter of the callback function contains a pointer to the item activated.
      • +
      • edge,top: The list is scrolled to the top edge.
      • +
      • edge,bottom: The list is scrolled to the bottom edge.
      • +
      • edge,left: The list is scrolled to the left edge.
      • +
      • edge,right: The list is scrolled to the right edge.
      • +
      • highlighted: The user highlights an item on the list. The event_info parameter of the callback function contains a pointer to the item activated.
      • +
      • unhighlighted: The user unhighlights an item in the list. The event_info parameter of the callback function contains a pointer to the item activated.
      • +
      + +

      You can register to the clicked,double signal with the following code. Note that the currently double-clicked item can be retrieved using the event_info pointer. This code registers to the double,clicked signal and unselects the item that has been double-clicked.

      + +
      +{
      +   Evas_Object *list;
      +
      +   evas_object_smart_callback_add(list, "clicked,double", double_clicked_cb, data);
      +}
      +
      +// Callback function for the "clicked" signal
      +// This callback is called when the button is clicked by the user
      +void double_clicked_cb(void *data, Evas_Object *obj, void  *event_info)
      +{
      +   elm_Object_Item *it = event_info;
      +   elm_list_selected_item_set(it,  EINA_FALSE);
      +}
      +
      + + +

      Map

      + +

      Figure: Map hierarchy

      +

      Map hierarchy

      + +

      The map component displays a geographic map. The default map data are provided by the OpenStreetMap project (http://www.openstreetmap.org/). Custom providers can also be added.

      + +

      This component supports:

      +
        +
      • Zooming
      • +
      • Scrolling
      • +
      • Markers with content to be displayed when the user clicks over them
      • +
      • Group of markers
      • +
      • Routes
      • +
      + +

      The map component implements the scroller interface so that all the functions that work with the scroller component also work with maps.

      + +

      Adding a Map Component

      + +

      Once created with the elm_map_add() function, zoom level x12 can be set.

      + +
      +Evas_Object *map, *parent;
      +
      +map = elm_map_add(parent);
      +elm_map_zoom_mode_set(map, ELM_MAP_ZOOM_MODE_MANUAL);
      +elm_map_zoom_set(map, 12);
      +
      + +

      Here the zoom mode is set to manual, but it can also be set to the ELM_MAP_ZOOM_MODE_AUTO_FIT mode and the ELM_MAP_ZOOM_MODE_AUTO_FILL mode. In that case however, the elm_map_zoom_set() function cannot be used.

      + +

      Playing with the Map

      + +

      If you have coordinates of a specific area (2 2 N, 48 8 E), it can be shown on the map.

      +
      +elm_map_region_show(map, 2.2, 48.8);
      +
      + +

      This shows the desired coordinates. The location can also be shown with a bring-in animation.

      +
      +elm_map_region_bring_in(map, 2.2, 48.8);
      +
      + +

      The map is rotated 90 degrees around the current position.

      +
      +elm_map_rotate_set(map, 90, 2.2, 48.8);
      +
      + +

      Drawing Overlays

      + +

      Overlays are markers that can be placed anywhere on the map. They can represent any object you want to put on the map.

      + +

      Creating an Overlay Class

      + +

      Overlay classes can be created if several objects are of the same type. For example, you can create a forest overlay class to represent the forests visible on the map. To do this, set the minimum zoom level at which this class is visible. The forest class overlay is visible when the zoom level is superior to eight.

      + +

      Set an icon ("Home" icon) to the forest class. This icon is displayed in place of the forest class on the map.

      +
      +Evas_Object *icon;
      +Elm_Map_Overlay *forest_class = elm_map_overlay_class_add(map);
      +
      +// Set min zoom level at which class is displayed
      +elm_map_overlay_displayed_zoom_min_set(forest_class, 8);
      +
      +// Create a Home icon object and set it to the forest class 
      +icon = elm_icon_add(map);
      +elm_icon_standard_set(icon, "home");
      +elm_map_overlay_icon_set(forest_class, icon);
      +
      + +

      Adding Overlays to a Class

      + +

      After creating a forest class, it is possible to add overlay objects to it. Here an overlay for the Meudon forest is created. The data is linked to the overlay with the elm_map_overlay_data_set() function. Set the name of the forest in the data. The icon can be set to the overlay with the elm_map_overlay_icon_set() function.

      + + + + + + + + + + +
      Note
      Do not use the same icon object for two different overlays. Create a new icon object each time you need one.
      + +
      +Elm_Map_Overlay *ovl;
      +const char* data_meudon = "Meudon forest";
      +const char* data_fausses = "Fausse forest";
      +
      +// Add an overlay
      +ovl = elm_map_overlay_add(map, 2.20718, 48.79759);
      +icon = elm_icon_add(map);
      +elm_icon_standard_set(icon, "stop");
      +elm_map_overlay_icon_set(ovl, icon);
      +elm_map_overlay_data_set(ovl, &data_meudon);
      +
      +// Add the new ovl object to the forest class 
      +elm_map_overlay_class_append(forest_class, ovl);
      +
      +// Add another overlay next to the first one 
      +ovl = elm_map_overlay_add(map, 2.1699, 48.8189);
      +icon = elm_icon_add(map);
      +elm_icon_standard_set(icon, "stop");
      +elm_map_overlay_icon_set(ovl, icon);
      +elm_map_overlay_data_set(ovl, &data_fausses);
      +elm_map_overlay_class_append(forest_class, ovl);
      +
      + +

      If you add another overlay to the forest class, the two overlays can be grouped under the forest class icon on certain zoom level conditions. You can define on which zoom level items are grouped.

      +
      +elm_map_overlay_class_zoom_max_set(forest_class, 8);
      +
      + +

      In this case, overlay members of the forest class are grouped when the map is displayed at less than zoom level eight.

      + +

      Creating Bubbles Following Overlays

      + +

      The following example shows how to set a content in a bubble following an overlay.

      + +
      +// Add an overlay bubble object 
      +Elm_Map_Overlay *bubble = elm_map_overlay_bubble_add(map);
      +
      +// Set it to follow a specific overlay (the last created one here) 
      +elm_map_overlay_bubble_follow(bubble, ovl);
      +
      + +

      Once following an overlay, the bubble appears, moves or hides following the parent overlay's behavior.

      + +

      Content is added to the bubble with the elm_map_overlay_bubble_content_append() function.

      + +

      Adding Other Overlays

      + +

      You can draw a circle on the map with coordinates and a radius size.

      +
      +Elm_Map_Overlay *circle = elm_map_overlay_circle_add(map, 2.2, 48.8, 0.02);
      +
      + +

      You can also add a scale at the 200x0 coordinate (in pixels).

      +
      +Elm_Map_Overlay *scale = elm_map_overlay_scale_add(map, 200, 0);
      +
      + +

      You can also draw a line, a polygon, or a route. For a full description of these functions, see the Map API.

      + +

      Calculating Routes

      + +

      A route between a starting point and an ending point is calculated with the elm_map_route_add() call. The type of transport and the routing calculation method can be provided so as to have the desired result.

      + +

      The following example shows how to get a route calculation between the first and the second overlay. It is configured to use the bicycle, and to find the fastest route possible.

      + +
      +Elm_Map_Route *route = elm_map_route_add(map,
      +         ELM_MAP_ROUTE_TYPE_BICYCLE,
      +         ELM_MAP_ROUTE_METHOD_FASTEST,
      +         2.20718, 48.79759,
      +         2.1699, 48.8189,
      +         NULL, NULL);
      +
      +// Add a callback to when the route has been calculated and loaded 
      +evas_object_smart_callback_add(map, "route,loaded", _route_loaded_cb, route);
      +
      + +

      Once the route is calculated, create a route overlay object and change its color. In this example, the route,loaded callback is used.

      +
      +static void
      +_route_loaded_cb(void *data, Evas_Object *obj, void *ev)
      +{
      +   Elm_Map_Route *route = data;
      +
      +   Elm_Map_Overlay *route_ovl = elm_map_overlay_route_add(obj, route);
      +   elm_map_overlay_color_set(route_ovl, 0, 255, 0, 255);
      +}
      +
      + +

      Using Map Callbacks

      + +

      The map component emits the following callbacks:

      +
        +
      • clicked: The user has clicked the map without dragging around.
      • +
      • clicked,double: The user has double-clicked the map.
      • +
      • press: The user has pressed down on the map.
      • +
      • longpressed: The user has pressed down on the map for a long time without dragging around.
      • +
      • scroll: The content is scrolled (moved).
      • +
      • scroll,drag,start: Dragging the contents around starts.
      • +
      • scroll,drag,stop: Dragging the contents around stops.
      • +
      • scroll,anim,start: Scrolling animation starts.
      • +
      • scroll,anim,stop: Scrolling animation stops.
      • +
      • zoom,start: Zoom animation starts.
      • +
      • zoom,stop: Zoom animation stops.
      • +
      • zoom,change: The zoom is changed when using an auto zoom mode.
      • +
      • tile,load: A map tile image load begins.
      • +
      • tile,loaded: A map tile image load ends.
      • +
      • tile,loaded,fail: A map tile image load fails.
      • +
      • route,load: Route request begins.
      • +
      • route,loaded: Route request ends.
      • +
      • route,loaded,fail: Route request fails.
      • +
      • name,load: Name request begins.
      • +
      • name,loaded: Name request ends.
      • +
      • name,loaded,fail: Name request fails.
      • +
      • overlay,clicked: An overlay is clicked.
      • +
      • loaded: The map is loaded.
      • +
      + + +

      Notify

      + +

      Figure: Notify hierarchy

      +

      Notify hierarchy

      + +

      The notify component displays a container in a particular region of the parent object. It can receive some content, and can be automatically hidden after a certain amount of time.

      + +

      Adding a Notify Component

      + +

      The following example shows how to create a notify object.

      +
      +Evas_Object *notify, *parent;
      +notify = elm_notify_add(parent);
      +
      + +

      Configuring the Notify Component

      + +

      Create a label and add it to the notify object.

      +
      +Evas_Object *content;
      +
      +// Create the label and set some text to it 
      +content = elm_label_add(parent);
      +
      +elm_object_text_set(content, "A label text");
      +evas_object_show(content);
      +
      +// Add the label object to the notify component
      +elm_object_content_set(notify, content);
      +
      + +

      In the following example the notify object is shown on the bottom left corner of the parent object.

      +
      +elm_notify_align_set(notify, 1.0, 1.0);
      +evas_object_show(notify);
      +
      + +

      Set a timeout interval, after which the notify component is hidden. In the following example the timeout interval is five seconds.

      +
      +elm_notify_timeout_set(notify, 5.0);
      +
      + +

      Using Notify Callbacks

      + +

      The notify component emits the following signals:

      +
        +
      • timeout: The timeout count ends and the notify component is hidden
      • +
      • block,clicked: The user clicks outside of the notify component
      • +
      + +

      For both these signals event_info is NULL.

      + +

      The following example shows how to register a callback on the timeout signal.

      + +
      +{
      +   evas_object_smart_callback_add(notify, "timeout", timeout_cb, data);
      +}
      +
      +// Callback function for the "timeout" signal
      +// The timeout expires and the notify object is hidden
      + 
      +void timeout_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   dlog_print(DLOG_INFO, LOG_TAG, "Notify is hidden\n");
      +}
      +
      + +

      Plug

      + +

      Figure: Plug hierarchy

      +

      Plug hierarchy

      + +

      The plug component shows an Evas_Object created by an other process. It can be used anywhere the same way as any other elementary UI component.

      + +

      Adding a Plug Component

      + +

      The following example shows how to create a plug.

      +
      +Evas_Object *plug, *parent;
      +plug = elm_plug_add(parent);
      +
      + +

      Using the Plug

      + +

      The socket image provides the service where to connect the plug object with the elm_plug_connect() function. In this process, use the service name and number set by the socket you want to connect to.

      + +

      As an example, connect to a service named plug_test on the number 0.

      + +
      +elm_plug_connect(plug, "plug_test", 0, EINA_FALSE);
      +
      + +

      The Evas_Object corresponding to the distant image is retrieved with the elm_plug_image_object_get() function.

      + +
      +Evas_Object *plug_img = elm_plug_image_object_get(plug);
      +
      + + + + + + + + + + +
      Note
      The socket to connect to must be started with the elm_win_socket_listen() function in the other process on the remote window object (it is called remote_win here).
      + +
      +// Create a remote window in the other process 
      +Elm_Win *remote_win = elm_win_add(NULL, "Window Socket",
      +                                  ELM_WIN_SOCKET_IMAGE);
      +// Create a socket named "plug_test" and listen to it
      +elm_win_socket_listen(remote_win, "plug_test", 0, EINA_FALSE);
      +
      + + + +

      Figure: Popup component

      +

      Popup component

      + +

      Figure: Popup hierarchy

      +

      Popup hierarchy

      + + +

      The popup component shows a popup area that can contain:

      +
        +
      • a title area (optional)
      • +
      • a content area
      • +
      • an action area (optional)
      • +
      + +

      The optional title area can contain an icon and text, the action area can contain up to three buttons.

      + +

      Adding a Popup Component

      + +

      The following example shows how to create a popup component.

      +
      +Evas_Object *popup, *parent;
      +
      +// Create a popup 
      +popup = elm_popup_add(parent);
      +
      + +

      Using Popup Styles

      + +

      The following item styles are available for wearable core controls:

      +
        +
      • popup
      • +
      • toast
      • +
      +

      The following item styles are available for Gear O:

      +
        +
      • circle
      • +
      • toast/circle
      • +
      +

      The following layout styles are available for Gear O:

      +
        +
      • content/circle
      • +
      • content/circle/buttons1
      • +
      • content/circle/buttons2
      • +
      + +

      The following example sets the style of the popup to toast.

      +
      +elm_object_style_set(popup, "toast");
      +
      + + +

      Setting the Popup Areas in Wearable Core Controls

      +

      Configure the title area. Set the title text to Test popup using the partname title,text.

      + +
      +elm_object_part_text_set(popup, "title,text", "Test popup");
      +
      +

      Set the content of the popup. The content can be simple text.

      +
      +elm_object_text_set(popup, "simple text");
      +
      +

      The content can also be an Evas object.

      +
      +Evas_Object *content;
      +
      +elm_object_content_set(popup, content);
      +
      +

      Set the buttons of the action area by creating an OK button and a Cancel button.

      +
      +Evas_Object *button1, *button2;
      +
      +// Create the two buttons 
      +button1 = elm_button_add(popup);
      +elm_object_style_set(button1, "popup");
      +evas_object_size_hint_weight_set(button1, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +elm_object_text_set(button1, "Cancel");
      +
      +button2 = elm_button_add(popup)
      +elm_object_style_set(button2, "popup");
      +evas_object_size_hint_weight_set(button2, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +elm_object_text_set(button2, "OK");
      +
      +evas_object_show(popup);
      +
      +// Set the buttons to the action area 
      +elm_object_part_content_set(popup, "button1", button1);
      +elm_object_part_content_set(popup, "button2", button2);
      +
      + +

      Setting the Popup Areas in Gear O

      +

      Set the circle style and the layout of the popup.

      +
      +// Setting the style
      +elm_object_style_set(popup, "circle");
      +
      +// Setting the layout
      +layout = elm_layout_add(popup);
      +elm_layout_theme_set(layout, "layout", "popup", "content/circle/buttons2");
      +
      + +

      To configure the title area, set the title text to Test popup using the partname elm.text.title.

      +
      +// Setting the title text 
      +elm_object_part_text_set(layout, "elm.text.title", "Text popup");
      +
      + +

      Set the content of the popup. The content can be simple text.

      +
      elm_object_part_text_set(layout, "elm.text.content", "Test popup");
      +
      + +

      The content of the popup can also be an Evas object.

      +
      +Evas_Object *content;
      +
      +elm_object_content_set(layout, content);
      +
      +

      Set the popup content.

      +
      +elm_object_content_set(popup, layout);
      +
      + +

      Set the buttons of the action area by creating an OK button, a Cancel button, and a Help button.

      + +
      +Evas_Object *button1, *button2, *icon;
      +
      +// Create the 2 buttons 
      +
      +button1 = elm_button_add(popup);
      +elm_object_style_set(button1, "popup/circle/left");
      +icon = elm_image_add(button1);
      +elm_image_file_set(icon, ICON_DIR"/b_option_list_icon_share.png", NULL);
      +evas_object_size_hint_weight_set(icon, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +elm_object_part_content_set(button1, "elm.swallow.content", icon);
      +evas_object_show(icon);
      +
      +button2 = elm_button_add(popup);
      +elm_object_style_set(button2, "popup/circle/right");
      +icon = elm_image_add(button2);
      +elm_image_file_set(icon, ICON_DIR"/b_option_list_icon_delete.png", NULL);
      +evas_object_size_hint_weight_set(icon, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +elm_object_part_content_set(button2, "elm.swallow.content", icon);
      +evas_object_show(icon);
      +
      +// Set the buttons to the action area 
      +elm_object_part_content_set(popup, "button1", button1);
      +elm_object_part_content_set(popup, "button2", button2);
      +
      +
      + +

      Using Popup Callbacks

      +

      The popup emits the following signals:

      +
        +
      • timeout: The popup is closed as a result of timeout.
      • +
      • block,clicked: The user clicks on the Blocked Event area.
      • +
      + +

      elm_popup_timeout_set() is used to hide the popup after a certain time. In the following example the timeout is set to five seconds.

      +
      elm_popup_timeout_set(popup, 5.0);
      + +

      When the timeout expires, the timeout signal is sent to the user.

      +
      +{
      +   evas_object_smart_callback_add(popup, "timeout", _timeout_cb, data);
      +}
      +
      +static void
      +_timeout_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   dlog_print(DLOG_INFO, LOG_TAG, "Timeout \n");
      +}
      +
      + +

      The visible region of the popup is surrounded by a translucent region called Blocked Event area. By clicking on this area, the signal block,clicked is sent to the application.

      + + +

      Progressbar

      + +

      Figure: Progressbar component

      +

      Progressbar component

      + +

      Figure: Progressbar hierarchy

      +

      Progressbar hierarchy

      + + +

      Adding a Progressbar Component

      + +

      This UI component is used to display the progress status of a given job. It inherits from the layout component, so all function concerning the layout component is used on the progressbar component.

      +

      The following example shows how to create a progressbar component.

      +
      +Evas_Object *pb = elm_progressbar_add(win);
      +
      + +

      Using the Progressbar Styles

      + +

      The progressbar has several styles for wearable core controls:

      +
        +
      • default
      • +
      • pending_list
      • +
      • process
      • +
      • process/groupindex
      • +
      • process/popup/small
      • +
      +

      The progressbar has several styles for Gear O:

      +
        +
      • process
      • +
      • process/small
      • +
      + +

      Set the style of the progressbar to pending_list.

      + +
      +elm_object_style_set(pb, "pending_list");
      +
      + +

      Configuring the Progressbar for Wearable Core Control

      + +

      The progressbar pulse mode is activated to make the progressbar loop infinitely between the start and end position.

      +
      elm_progressbar_pulse_set(pb, EINA_TRUE);
      +elm_progressbar_pulse(pb, EINA_TRUE);
      +
      + +

      The progressbar can be inverted. In that mode, the values are inverted so that the high values are on the left and the low values on the right.

      +
      elm_progressbar_inverted_set(pb, EINA_TRUE);
      + +

      The progressbar emits the changed signal when the progress value changes. The value is changed with the elm_progressbar_value_set() function. Here the pb progress value is set to 20%.

      +
      elm_progressbar_value_set(pb, 0.2);
      + +

      It is possible to read the current value.

      +
      double value = elm_progressbar_value_get(pb);
      + +

      Configuring the Progressbar for Gear O

      +

      The progressbar emits the changed signal when the progress value changes. The value is changed with the elm_progressbar_value_set() function. Here the pb progress value is set to 20%.

      + +
      +elm_progressbar_value_set(pb, 0.2);
      +
      +

      The current value can be read.

      +
      +double value = elm_progressbar_value_get(pb);
      +
      + + +

      Using the Progressbar Callbacks

      + +

      The changed signal is the only signal specifically emitted by the progressbar component.

      +

      The following example shows how to register a callback on this signal.

      + +
      +{
      +   evas_object_smart_callback_add(pb, "changed", changed_cb, data);
      +}
      +
      +// Callback function for the "changed" signal
      +// This callback is called when the progressbar value changes
      +void changed_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   dlog_print(DLOG_INFO, LOG_TAG, "The value has changed\n");
      +}
      +
      + + +

      Radio

      + +

      Figure: Radio component

      +

      Radio component

      + +

      Figure: Radio hierarchy

      +

      Radio hierarchy

      + +

      This UI component displays one or more options, but the user can only select one of them. It is composed of an indicator (selected or unselected). Even though it is usually grouped with two or more other radio objects, it can also be used alone. +

      +

      The radio component inherits from the layout component. All the layout functions can be used with radio objects.

      + +

      Adding a Radio Component

      + +

      Create a radio component.

      +
      +Evas_Object *radio, *parent;
      +
      +// Create a radio
      +radio = elm_radio_add(parent);
      +
      + +

      Changing the Radio Value

      + +

      The user can select one of a set of values with the radio component. Each radio object from a group of radio objects represents an integer value. Here the value 1 is set to the new radio object.

      +
      +elm_radio_state_value_set(radio, 1);
      +
      + +

      Managing the Radio Groups

      + +

      The following example shows how to create a group of radio objects with at least two radio components.

      + +
      +// Create another radio object 
      +Evas_Object *radio2 = elm_radio_add(parent);
      +elm_radio_state_value_set(radio2, 2);
      +
      +// Create a group composed of radio and radio2
      +Evas_Object *group = radio;
      +elm_radio_group_add(radio2, group);
      +
      + +

      Now that a group composed of two radio objects has been created, you can choose which one is selected. In this example radio2 is selected.

      + +
      elm_radio_value_set(group, 2);
      + +

      You can use elm_radio_value_get() to see the currently selected radio of the group.

      + +

      Using the Radio Callbacks

      + +

      This UI component emits the following signals:

      +
      • changed: The state of a radio is modified in a group of radio objects.
      + +

      The following example shows how to register a callback on this signal.

      +
      +{
      +   evas_object_smart_callback_add(radio, "changed", changed_cb, data);
      +}
      +
      +// Callback function for the "changed" signal
      +// This callback is called when the radio value changes
      +void changed_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   dlog_print(DLOG_INFO, LOG_TAG, "The value has changed\n");
      +}
      +
      + +

      Using the Radio Callbacks with Gear O

      + +

      This UI component emits the following signals:

      +
        +
      • changed: The user changes the slider value.
      • +
      • clicked: Radio was clicked.
      • +
      + +

      The following example shows how to register a callback on this signal.

      +
      +{
      +   evas_object_smart_callback_add(radio, "clicked", clicked_cb, data);
      +}
      +
      +// Callback function for the "changed" signal
      +// This callback is called when the radio value changes
      +void changed_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   dlog_print(DLOG_INFO, LOG_TAG, "This radio was clicked\n");
      +}
      +
      + + +

      Slider for the Wearable Core

      + +

      Figure: Slider component

      +

      Slider component

      + +

      Figure: Slider hierarchy

      +

      Slider hierarchy

      + +

      The slider component is a draggable bar that is used to select a value within a certain range.

      + +

      Adding a Slider Component

      + +

      The following example shows how to create a slider object.

      +
      +Evas_Object *slider, *parent;
      +
      +slider = elm_slider_add(parent);
      +
      + +

      Using the Slider Styles

      + +

      A slider has the following styles:

      +
        +
      • default
      • +
      + +

      Configuring the Slider

      + +

      It can contain icons (elm.swallow.icon partname), a label, a unit label and an indicator label.

      +
      +Evas_Object *icon1, *icon2;
      +
      +// Set the icons 
      +elm_object_part_content_set(slider, "elm.swallow.icon", icon1);
      +
      +// Set the unit format 
      +elm_slider_unit_format_set(slider, "%1.2f meters");
      +
      + +

      Before using the slider, its minimum and maximum values are set with elm_slider_min_max_set(). The current value is set with (elm_slider_value_set()). The following example sets the minimum value to 0, the maximum value to 100, and the current value to 50.

      +
      +elm_slider_min_max_set(slider, 0.0, 100.0);
      +elm_slider_value_set(slider, 50.0);
      +
      + +

      The span of the slider represents its length horizontally. It is set with elm_slider_span_size_set() and is scaled by the object or applications scaling factor.

      +

      You can retrieve the current value of the slider anytime.

      +
      +double value = elm_slider_value_get(slider);
      +
      + +

      By default, the slider indicator becomes bigger when the user drags it. This can be disabled if you want the slider indicator to keep its default size. The following example sets the state of the indicator enlargement and then inverts the behavior.

      +
      +// Get the current state of the indicator 
      +Eina_Bool enlarge = elm_slider_indicator_show_get(slider);
      +
      +// Invert the behavior 
      +elm_slider_indicator_show_set(slider, !enlarge);
      +
      + +

      Using the Slider Callbacks

      + +

      This UI component emits the following signals:

      +
        +
      • changed: The user changes the slider value.
      • +
      • slider,drag,start: Dragging the slider indicator around starts.
      • +
      • slider,drag,stop: Dragging the slider indicator around stops.
      • +
      • delay,changed: A short time after the user changes the value. This is called only when the user stops dragging for a very short period or when releases the finger or mouse, so that it avoids possibly expensive reactions to the value change.
      • +
      + +

      For all these signals, event_info is NULL.

      +

      The following example shows how to register a callback on the changed signal.

      +
      +{
      +   evas_object_smart_callback_add(slider, "changed", changed_cb, data);
      +}
      +
      +// Callback function for the "changed" signal
      +// This callback is called when the slider value changes
      +void changed_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   dlog_print(DLOG_INFO, LOG_TAG, "The slider has changed\n");
      +}
      +
      + + + +

      Win

      + +

      Figure: Win hierarchy

      +

      Win hierarchy

      + + +

      The window component is the root UI component that is often used in an application. It allows the developer create content in it, and it is handled by the window manager.

      +

      The window component is created with the elm_win_add() or elm_win_util_standard_add() function. The content can be added in the window with elm_win_resize_object_add() so that a window resize also resizes the content inside.

      + +

      Adding a Window Component

      + +

      Create a new window and change the title.

      +
      +Evas_Object *window;
      +
      +// Create a window 
      +window = elm_win_add(NULL, "main", ELM_WIN_BASIC);
      +
      +// Change the window title 
      +elm_win_title_set(window, "Example Window");
      +
      + +

      The first element of elm_win_add() is the parent window. For example, for a dialog you want to have the main window as the parent. Here, it is NULL, meaning there is no parent. main is the name of the window used by the window manager for identifying the window uniquely amongst all the windows within this application (and all instances of the application). The type is a basic window (the final parameter).

      + +

      Create a new window with a title and a background. This API is a shortcut of the previous one. It also creates a standard background to the window with elm_bg_add(). The window created is of the type ELM_WIN_BASIC.

      + +
      +Evas_Object *window;
      +
      +// Create a standard window 
      +window = elm_win_util_standard_add("main", "Example Window");
      +
      + +

      Closing a Window

      +

      When the user closes the window outside of the program control, a delete,request signal is emitted to indicate that this event occurred. The developer can take any action, for example, destroy the window object.

      +

      When the autodel parameter is set, the window is automatically destroyed after the signal is emitted. If autodel is EINA_FALSE, the window is not destroyed and the program does so when required. The default is EINA_FALSE, where the window is not destroyed automatically.

      +

      The autodel is set using the following call:

      +
      +elm_win_autodel_set(window, EINA_TRUE);
      +
      + +

      To close the window, use the evas_object_del() function. The window is destroyed and the signal delete,request is sent.

      + +

      Using the Window Callbacks

      +

      The window component emits the following signals:

      +
        +
      • delete,request: The window is requested delete.
      • +
      • focus,in: The window received focus.
      • +
      • focus,out: The window lost focus.
      • +
      • moved: The window that holds the canvas is moved.
      • +
      • withdrawn: The window is managed normally but is removed from the view.
      • +
      • iconified: The window is minimized (for example, into an icon or a taskbar).
      • +
      • normal: The window is in the normal state (not withdrawn or iconified).
      • +
      • stick: The window shows on all desktops.
      • +
      • unstick: The window shows only on one desktop.
      • +
      • fullscreen: The window is fullscreen.
      • +
      • unfullscreen: The window stops being fullscreen.
      • +
      • maximized: The window is maximized.
      • +
      • unmaximized: The window is diminished.
      • +
      • wm,rotation,changed: The rotation of the window is changed by the Windows Manager.
      • +
      • ioerr: A low-level I/O error occurred in the display system.
      • +
      • indicator,prop,changed: The property or indicator mode and indicator opacity are changed.
      • +
      • rotation,changed: The rotation of the window is changed.
      • +
      • profile,changed: The profile of the window is changed.
      • +
      • aux,hint,allowed: aux_hint of the window free.
      • +
      • access,changed: The access function of the window is changed.
      • +
      +

      With all these signals, event_info is NULL.

      +

      The following example registers a callback function called on the fullscreen signal.

      +
      +{
      +   evas_object_smart_callback_add(window, "fullscreen", fullscreen_cb, data);
      +}
      +
      +// Callback function for the "fullscreen" signal
      +// This callback is called when the window becomes fullscreen
      +void fullscreen_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   dlog_print(DLOG_INFO, LOG_TAG, "Window fullscreen\n");
      +}
      +
      + + + + + + + + + + +
      Note
      Except as noted, this content is licensed under LGPLv2.1+.
      + + + + +
      + +Go to top + + + + + + + + diff --git a/org.tizen.ui.guides/html/native/efl/containers_n.htm b/org.tizen.ui.guides/html/native/efl/containers_n.htm new file mode 100755 index 0000000..f9ad56d --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/containers_n.htm @@ -0,0 +1,608 @@ + + + + + + + + + + + + + + Using Container UI Components + + + + + + +
      +

      Using Container UI Components

      + +

      Box

      + + +

      Figure: Box container

      +

      Box container

      + + +

      Most of the time, you want to display UI components on the screen in a specific order. In a form container, for example, the user information is arranged vertically. This basic container is called a box. There is no theme for a box layout. It is just a linear method of arranging UI components horizontally or vertically.

      +

      Creating a Box

      +

      To create a new horizontal box:

      +
      Evas_Object *vbox;
      +
      +vbox = elm_box_add(parent);
      +
      +

      By default, the elm_box_add() function creates a vertical box. If you want to create a horizontal box, use the elm_box_horizontal_set() function:

      +
      Evas_Object *hbox;
      +
      +hbox = elm_box_add(parent);
      +elm_box_horizontal_set(hbox, EINA_TRUE);
      +
      + + + + + + + + + + +
      Note
      A box is a non-graphical object. It adds no graphics to or around the objects it holds.
      + +

      Adding Objects to the Box

      +

      You can add any Evas object to the box. Here, we create 5 button components and add them to a box:

      +
      int i;
      +Evas_Object *bt;
      +Evas_Object *vbox;
      +
      +vbox = elm_box_add(parent);
      +
      +for (i = 0; i < 5; i++)
      +{
      +   char tmp[16];
      +   snprintf(tmp, sizeof(tmp), "Button %d", i);
      +   bt = elm_button_add(vbox);
      +   elm_object_text_set(bt, tmp);
      +   elm_box_pack_end(vbox, bt);
      +   evas_object_show(bt);
      +}
      +evas_object_show(vbox);
      +
      +

      The most important function in the above code is elm_box_pack_end(), which is used to add the button component to the end of the box.

      + +

      Setting the Padding

      +

      You can set the padding between the objects in a box by using the elm_box_padding_set() function. The padding values are the number of pixels horizontally and vertically.

      +
      elm_box_padding_set(vbox, 16, 64);
      +
      + +

      Handling Element Size

      +

      You can add different-size elements to a container. For example, to add an image with a size of 128x128 pixels as the first element in a box, use the elm_box_pack_start() function:

      +
      ic = elm_icon_add(vbox);
      +elm_image_file_set(ic, "./c1.png", NULL);
      +evas_object_size_hint_min_set(ic, 128, 128);
      +evas_object_show(ic);
      +elm_box_pack_start(vbox, ic);
      +
      +

      We ask Evas to set the size hint for the icon object by using the elm_object_size_hint_min_set() function. Evas will try to set the minimum size of this object accordingly.

      +

      If you want to create a homogeneous box, where all objects have the same height or width, depending on the orientation of the box, use the elm_box_homogeneous_set() function:

      +
      elm_box_homogeneous_set(vbox, EINA_TRUE);
      +
      +

      Elementary will set the height of the tallest object as the height of all objects, or the width of the widest element as the width of all objects.

      +

      Setting the Alignment

      +

      You can set the alignment of UI components inside a box using the elm_box_align_set() function. The function takes two doubles values, a horizontal value and a vertical value, representing the percentage between 0 and 1.0 of the alignment in the horizontal and vertical axes. When you add a UI component with the elm_box_pack_end() or elm_box_pack_start() function, Elementary computes the global size of the box. If the global size is bigger than the size of the box's parent, the box will take up all the space occupied by the parent, and the size of the parent may be extended to hold the box. If the global size is smaller than the parent's size, the alignment values will set the position of the box inside the parent.

      + +

      Figure: Alignment

      +

      Alignment

      + +

      Here, we set an alignment of 0.8 vertically:

      +
      elm_box_align_set(vbox, 0.0, 0.8);
      +
      + + + + + + + + + + +
      Note
      The alignment only takes effect in the opposite direction than the one defined with the elm_box_horizontal_set() function.
      + + +

      The elm_box_layout_transition() function provides the ability to animate the motion of the objects in a box when switching from one layout to another.

      +

      Using Size Hints

      +

      Size hints are a set of functions that can be used on any Evas object. You request Evas to take care of various properties, and Evas will honor these requests if it can. This is why they are called "hints". The size hint functions are:

      +
        +
      • evas_object_size_hint_min_set()
      • +
      • evas_object_size_hint_max_set()
      • +
      • evas_object_size_hint_aspect_set()
      • +
      • evas_object_size_hint_align_set()
      • +
      • evas_object_size_hint_weight_set()
      • +
      +

      You can also use the respective get functions to get the current hint values.

      +

      In case of the evas_object_size_hint_min_set() function, you ask Evas to respect the minimum size you define for the object. For example, to set the minimum size of an icon to 64x46 pixels:

      +
      evas_object_size_hint_min_set(ic, 64, 64);
      +
      +

      You can also set a maximum size for the same icon:

      +
      evas_object_size_hint_max_set(ic, 128, 128);
      +
      +

      When you resize the parent of the icon, if there are no constraints to the parent, the minimum size of the parent will be the minimum hint size of the icon. If you increase the parent size, the icon will grow larger until its maximum hint size is reached. After this point, the icon will not grow any larger and there will be empty space around the icon within the parent.

      +

      When the aspect size hint is set, Evas tries to fix the dimensional proportions of the object. Here, the proportion of the icon is respected, and the width will be the same as the height:

      +
      evas_object_size_hint_aspect_set(ic, EVAS_ASPECT_CONTROL_VERTICAL, 1, 1);
      +
      +

      Here, the width will be twice the height:

      +
      evas_object_size_hint_aspect_set(ic, EVAS_ASPECT_CONTROL_VERTICAL, 2, 1);
      +
      +

      If we want to change the alignment of the icon relative to the parent, we can use the evas_object_size_hint_align() function. By default, the icon is centered, so it is aligned with a value of 0.5. You can change the alignment as follows:

      +
      evas_object_size_hint_align_set(ic, EVAS_HINT_FILL, EVAS_HINT_FILL);
      +
      +

      In the above case, the icon is aligned to the bottom left corner of the parent.

      +

      We can also play with the size of the icon inside its container by using the weight size hint. By default, the weight is not set, so the size of the icon will be the minimum size. But if you set this value to 1, the icon will be expand as much as it can inside the container:

      +
      evas_object_size_hint_weight_set(ic, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +
      +

      You can also use the alignment and weight hints together. Here, we want the icon to take up all the space in its parent:

      +
      evas_object_size_hint_align_set(ic, EVAS_HINT_FILL, EVAS_HINT_FILL);
      +evas_object_size_hint_weight_set(ic, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +
      + + +

      Conformant

      + +

      Figure: Conformant container

      +

      Conformant container

      + +

      A conformant is a container UI component that accounts for the space taken by the indicator, virtual keyboard, and softkey windows. The content area of the conformant is resized and positioned based on the space available. When the virtual keyboard is displayed, the content area is not resized.

      + +

      Creating a Conformant

      +

      To create a conformant, use the elm_conformant_add() function:

      +
      +Evas_Object *conformant;
      +
      +conformant = elm_conformant_add(parent);
      +
      + +

      Adding Content to the Conformant

      +

      To add content to the conformant, use the elm_object_content_set() function:

      +
      elm_object_content_set(conformant, main_view);
      +
      + +

      Signals

      +

      To receive notifications about the state of the virtual keyboard and clipboard, listen to the following Evas signals:

      +
        +
      • "virtualkeypad,state,on": The virtual keyboard has been switched on.
      • +
      • "virtualkeypad,state,off": The virtual keyboard has been switched off.
      • +
      • "virtualkeypad,size,changed": The virtual keyboard size has changed.
      • +
      • "clipboard,state,on": The clipboard has been switched on.
      • +
      • "clipboard,state,off": The clipboard has been switched off.
      • +
      + + +

      Grid

      + +

      In a grid, objects are placed at specific positions along a fixed grid, where the position of each object is given as a percentage of the full width and height of the grid. By default, the size of the grid is 100 x 100 pixels.

      + +

      Creating a Grid

      +

      To create a grid, use the elm_grid_add() function:

      +
      Evas_Object *grid;
      +
      +grid = elm_grid_add(parent);
      +

      Adding Items to the Grid

      +

      To add an item to the grid, use the elm_grid_pack_set() function. Provide the X and Y coordinates, and the width and height in the grid as parameters. The following code adds 12 icons in a circle formation:

      +
      for (i = 0; i < 12; i++)
      +{
      +   ic = elm_icon_add(grid);
      +   elm_image_file_set(ic, "c1.png", NULL);
      +   evas_object_size_hint_min_set(ic, 128, 128);
      +   evas_object_show(ic);
      +   x = 40 * cos(2.0 * M_PI / 12 * i);
      +   y = 40 * sin(2.0 * M_PI / 12 * i);
      +   elm_grid_pack(grid, ic,  40 + x,  40 + y,  20 , 20);
      +}
      +evas_object_show(grid);
      +
      + +

      Changing Position and Size

      +

      To change the position of an item in the grid, use the elm_grid_pack_set() function. The first parameter is the item you want to move, and the following parameters are the same as for the elm_grid_pack() function.

      +

      To change the size of the grid, use the elm_grid_size_set() function. You can set the new width and height for the grid. The position and size of the items in the grid are changed accordingly.

      +

      Clearing the Grid

      +

      To clear the grid, use the elm_grid_clear() function. All items are removed from the grid. If you set the clear parameter, all the items are also deleted, with the evas_object_del() function called on each item.

      + + +

      Layout

      + +

      A layout is a container that takes a standard Edje design file and wraps it very thinly in a UI component. Layouts are the basis of a lot of graphics components used in Elementary.

      + +

      An Edje design file describes how the elements of the UI are positioned and how they behave when interacted with. For more information about Edje, see Themes.

      + +

      Creating a Layout

      + +

      To create a new layout, use the elm_layout_add() function:

      +
      Evas_Object *layout;
      +
      +layout = elm_layout_add(parent);
      +
      +

      In Tizen, the layout component is extended to support different kinds of layouts. Rather than define layouts yourself, you can use the following predefined default layouts:

      +
        +
      • application/default: This layout can be used to display content inside a window.
      • +
      • drawer/panel: This layout can be used to create a 2-panel view.
      • +
      • nocontents/default: This layout can be used when there is no content to display, such as in a contact or email.
      • +
      +

      To use the application/default layout:

      +
      Evas_Object *ly;
      +
      +ly = elm_layout_add(parent);
      +elm_layout_theme_set(ly, "layout", "application", "default");
      +
      + +

      Adding Objects to the Layout

      +

      To add an Evas object to the layout:

      +
      elm_object_part_content_set(ly, "elm.swallow.content" view);
      +
      +

      elm.swallow.content is the swallow part of the application layout, and with this call you integrate the view inside the swallow object of the layout.

      +

      The drawer/panel layout can display 2 different views, the background and the main content:

      +
      Evas_Object *ly;
      +
      +ly = elm_layout_add(parent);
      +elm_layout_theme_set(ly, "layout", "drawer", "panel");
      +
      +

      To swallow an object inside the main content and background views:

      +
      elm_object_part_content_set(ly, "elm.swallow.content", main_view);
      +elm_object_part_content_set(ly, "elm.swallow.background", background);
      +
      +

      The nocontents/default layout is a special layout in that it does not contain any swallows. You can only set the text part. There are two different texts zones: elm.text and elm.help.text. To change the text:

      +
      elm_object_part_text_set(ly, "elm.text", "Hi All :)");
      +elm_object_part_text_set(ly, "elm.help.text", "Hi All :)");
      +
      +

      Using Layout Themes

      +

      The layout component supports the following predefined default themes:

      +
        +
      • toolbar-content: For applications with a toolbar and main content area.
      • +
      • toolbar-content-back: For applications with a toolbar, main content area (with a back button), and title area.
      • +
      • toolbar-content-back-next: For applications with a toolbar, main content area (with back and next buttons), and title area.
      • +
      • content-back: For applications with main content (with a back button) and title areas.
      • +
      • content-back-next: For applications with main content (with back and next buttons) and title areas.
      • +
      • toolbar-vbox: For applications with a toolbar and main content area as a vertical box.
      • +
      • toolbar-table: For applications with a toolbar and main content area as a table.
      • +
      +

      To set a theme to the layout, use the elm_layout_theme_set() function.

      + + +

      Mapbuf

      + +

      Figure: Mapbuf hierarchy

      +

      Mapbuf hierarchy

      + +

      A mapbuf component is a container UI component that uses an Evas map to hold a content object. This component is used to improve the moving and resizing performance of complex UI components.

      + +

      The content object is treated as a single image by the Evas map. If you have a content object containing several child objects, frequently moving the mapbuf component will be faster than frequently moving the content object.

      + +

      The mapbuf component inherits all the functions of the container class.

      + +

      Creating a Mapbuf

      +

      To create a mapbuf component, use the elm_mapbuf_add() function:

      +
      Evas_Object *mapbuf, *parent, *content;
      +
      +// Creating a mapbuf
      +mapbuf = elm_mapbuf_add(parent);
      +
      +

      Adding Content to the Mapbuf

      +

      To add content to the mapbuf component, use the elm_object_content_set() function with the "default" part:

      +
      elm_object_content_set(mapbuf, content);
      + + + + + + + + + + +
      Note
      Calling elm_object_content_set(mapbuf, content) is equivalent to calling elm_object_part_content_set(mapbuf, "default", content).
      + + +

      To activate smooth map rendering and alpha rendering for the mapbuf component:

      +
      elm_mapbuf_smooth_set(mapbuf, EINA_TRUE);
      +elm_mapbuf_alpha_set(mapbuf, EINA_TRUE);
      +
      + +

      Activating the Mapbuf

      +

      Finally, to use the mapbuf component, you must activate it:

      +
      elm_mapbuf_enabled_set (mapbuf, EINA_TRUE);
      + +

      Signals

      +

      The mapbuf component does not emit any signals and therefore does not provide any callbacks that you can register.

      + + + + +

      A naviframe component consists of a stack of views. New views are pushed on top of previous ones, and only the top-most view on the stack is displayed. The previous views are not deleted. A previous view is displayed when the view on top of it is popped. Transitions can be animated on a push or a pop, depending on the theme applied to the UI component.

      + +

      Creating a Naviframe

      +

      To create a naviframe, use the elm_naviframe_add() function:

      +
      Evas_Object *nav;
      +
      +nav = elm_naviframe_add(parent);
      +
      +

      Adding and Deleting Views

      +

      The naviframe is a stack of views. A new view is always pushed to the top of the stack. The top-most view is deleted by popping it.

      +

      To add a new view to the naviframe:

      +
      Elm_Object_Item *nav_it;
      +
      +nav_it = elm_naviframe_item_push(nav, NULL, NULL, NULL, view, NULL);
      +// In Tizen 2.3, the back button is not supported in the naviframe 
      +
      +

      When you push a new view to the stack, you receive an Elm_Object_Item for the view. You can use this item to modify the view.

      +

      To pop and delete the top-most view:

      +
      elm_naviframe_item_pop(nav);
      +
      + +

      Adding Fixed Content

      +

      The naviframe can also display fixed content on top of the current (top-most) view. Use the elm_object_item_part_content_set() function to set this content. Use the following part names to specify the location of the content:

      +
        +
      • "default": The main content area of the current view.
      • +
      • "icon": An icon in the title area of the current view.
      • +
      • "title_left_btn": A button on the left side of the naviframe.
      • +
      • "title_right_btn": A button on the right side of the naviframe.
      • +
      +

      For example, to add a button to the naviframe:

      +
      btn = elm_button_add(nav);
      +elm_object_style_set(btn, "naviframe/title_cancel");
      +elm_object_item_part_content_set(nav_it, "title_left_btn", btn);
      +
      +

      To set the title labels of the naviframe, use the elm_object_item_part_text_set() function and specify one of the following label locations:

      +
        +
      • "default": Sets the title label in the title area of the current view.
      • +
      • "subtitle": Sets the subtitle label in the title area of the current view.
      • +
      +

      Signals

      +

      The naviframe emits the following signals:

      +
        +
      • "transition,finished": The transition has finished changing the view.
      • +
      • "title,transition,finished": The title area transition has finished changing the state of the title.
      • +
      • "title,clicked": The user has clicked the title area.
      • +
      + + + +

      Panes in Mobile Applications

      + +

      Figure: Panes component

      +

      Panes component

      + +

      A panes component adds a draggable bar between two sections of content. The sections are resized when the bar is dragged.

      + +

      Creating Panes

      +

      To create a panes component, use the elm_panes_add() function:

      +
      Evas_Object *panes;
      +
      +panes = elm_panes_add(parent);
      +
      + +

      Adding Content to the Panes

      +

      To add content to the panes, use the elm_object_part_content_set() function. The following code adds an object to the left pane:

      +
      elm_object_part_content_set(panes, "left", obj);
      +
      + +

      Setting Panes Options

      +

      To set the orientation of the panes, use the elm_panes_horizontal_set() function.

      + +

      To set the size of the panes, use the elm_panes_content_left_size_set() and elm_panes_content_right_size_set() functions.

      + +

      Signals

      +

      The panes component emits the following signals:

      +
        +
      • "press": The panes component has been pressed (but the press has not been released yet).
      • +
      • "unpress": The press has been released.
      • +
      • "clicked": The panes component has been clicked.
      • +
      • "clicked,double": The panes component has been double-clicked.
      • +
      + + +

      Scroller

      + +

      A scroller holds (and clips) a single object and allows you to scroll across it. This means that the user can use a scroll bar or their finger to drag the viewable region across the object, moving through a much larger area than is contained in the viewport. The scroller will always have a default minimum size that is not limited by its contents.

      +

      The scroller component inherits all the functions of the Layout.

      +

      Creating a Scroller

      +

      To create a scroller, use the elm_scroller_add() function:

      +
      +Evas_Object *scroller;
      +
      +scroller = elm_scroller_add(parent);
      +
      +

      Adding Objects to the Scroller

      +

      To add an object to the scroller, use the elm_object_content_set() function:

      +
      Evas_Object *image;
      +
      +image = elm_image_add(parent);
      +elm_image_file_set(image, "image.png", NULL);
      +evas_object_show(image);
      +evas_object_size_hint_min_set(image, 2560, 1600);
      +elm_object_content_set(scroller, image);
      +
      +

      In the above code, we set a minimum size of 2560 x 1600 pixels for the image. The scroller is smaller than the image, so you can scroll across the image.

      +

      If you want to be informed when the user begins scrolling the image, use the following code:

      +
      +evas_object_smart_callback_add(scroller, "scroll,drag,start", _scroll_start_cb, NULL);
      +
      +// Callback function for the "animate,begin" signal
      +// This callback is called when the user begins scrolling the image
      +void _scroll_start_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   printf("Scroll starts\n");
      +}
      + +

      Managing the Properties of the Scroller

      +

      When scrolling content, the scroller may "bounce" when reaching the edge of the content. This is a visual way of indicating that there is no more content to scroll in that direction. Bounce is enabled by default for both axes. To enable or disable the bounce for either or both axes, use the elm_scroller_bounce_set() function. The following code disables the bounce for the horizontal axis and enables it for the vertical axis:

      + +
      elm_scroller_bounce_set(scroller, EINA_FALSE, EINA_TRUE);
      +
      +

      The scroller can limit the scrolling to "pages". In this case, the scrolling occurs in page-sized chunks of content rather than in a purely continuous fashion, with the scroller displaying a single "page" at a time. This feature sets the size of the page relative to the viewport of the scroller. A size of 1.0 equals 1 viewport (horizontally or vertically). A size of 0.0 disables paging for that axis. These settings are mutually exclusive with page size (see the elm_scroller_page_size_set() function). A size of 0.5 equals half a viewport. Usable size values are normally between 0.0 and 1.0, including 1.0. If you only want a single axis to scroll in pages, use 0.0 for the other axis.

      + +

      Signals

      + +

      The scroller emits the following signals, which you can catch in your application:

      + +
        +
      • "edge,left": The left edge of the content has been reached.
      • +
      • "edge,right": The right edge of the content has been reached.
      • +
      • "edge,top": The top edge of the content has been reached.
      • +
      • "edge,bottom": The bottom edge of the content has been reached.
      • +
      • "scroll": The content has been scrolled (moved).
      • +
      • "scroll,anim,start": The scrolling animation has started.
      • +
      • "scroll,anim,stop": The scrolling animation has stopped.
      • +
      • "scroll,drag,start": Dragging the contents has started.
      • +
      • "scroll,drag,stop": Dragging the contents has stopped.
      • +
      • "vbar,drag": The vertical scroll bar has been dragged.
      • +
      • "vbar,press": The vertical scroll bar has been pressed.
      • +
      • "vbar,unpress": The vertical scroll bar has been unpressed.
      • +
      • "hbar,drag": The horizontal scroll bar has been dragged.
      • +
      • "hbar,press": The horizontal scroll bar has been pressed.
      • +
      • "hbar,unpress": The horizontal scroll bar has been unpressed.
      • +
      • "scroll,page,changed": The visible page has changed.
      • +
      + +

      Example

      +

      A good example of the scroller is a picture slideshow: we add images to the scroller and limit the scrolling to pages (one picture at a time). In the following code, we disable the scroll bars for both axes, limit the scrolling to pages by using the elm_scroller_page_scroll_limit_set() function, and lock the scrolling on the Y axis by using the elm_object_scroll_lock_y_set() function:

      +
      elm_scroller_policy_set(scroller, ELM_SCROLLER_POLICY_OFF, ELM_SCROLLER_POLICY_OFF);
      +elm_scroller_page_scroll_limit_set(scroller, 1, 0);
      +elm_object_scroll_lock_y_set(scroller, EINA_TRUE);
      +
      +

      We create a horizontal box, which will contain all the images, and which itself will be contained by the scroller:

      +
      box = elm_box_add(scroller);
      +elm_box_horizontal_set(box, EINA_TRUE);
      +elm_object_content_set(scroller, box);
      +evas_object_show(box);
      +
      +

      We then create all the images and add them to the horizontal box:

      +
      img = elm_image_add(scroller);
      +snprintf(buf, sizeof(buf), IMAGE_DIR"/%d.jpg", i);
      +elm_image_file_set(img, buf, NULL);
      +evas_object_show(img);
      +pages = eina_list_append(pages, img);
      +elm_box_pack_end(box, img);
      +
      +

      We store references to the images in an eina_list for easy retrieval later.

      +

      Finally, we display the first page of the scroller:

      +
      elm_scroller_page_show(scroller, 0, 0);
      +
      +

      The size of the scroller depends on the size of the parent. When the parent changes, for example when the window is resized or rotated, the scroller is also resized. Since we need to be informed when the scroller is resized, we add a callback on the EVAS_CALLBACK_RESIZE event for the scroller:

      +
      evas_object_event_callback_add(scroller, EVAS_CALLBACK_RESIZE, _scroller_resize_cb, NULL);
      +

      The callback retrieves the new size of the scroller by using the evas_object_geometry_get() function on the object pointer. The pointer is relative to the object that has been resized, which in our case is the scroller itself. We can then iterate through the images of the scroller and set the minimum size to fit the scroller size:

      +
      EINA_LIST_FOREACH(images, l, page)
      +{
      +   evas_object_size_hint_min_set(page, w, h);
      +}
      +
      +

      Finally, we set the page size of the scroller to match the scroller size and display the first page:

      +
      elm_scroller_page_size_set(obj, w, h);
      +elm_scroller_page_show(obj, 0, 0);
      + +

      Table

      + +

      A table is like a box but with 2 dimensions. You have the same kind of APIs as with boxes. An item inside the table can span multiple columns and rows, and even overlap with other items (and it can then be raised or lowered accordingly to adjust stacking if there is overlap).

      + +

      Creating a Table

      + +

      To create a table, use the elm_table_add() function:

      +
      Evas_Object *table;
      +table = elm_table_add(parent);
      + +

      Adding Items to the Table

      + +

      Items are added to the table with the elm_table_pack() function. This function takes as parameters the table, the item to add to the table, and the position where to add the item: column, row, and the size of the item in number of rows and columns (colspan and rowspan). If we want to create an icon that takes 3 columns and rows and a button that only takes 1 row and column, the code will look like this:

      +
      ic = elm_icon_add(table);
      +elm_image_file_set(ic, "icon.png", NULL);
      +evas_object_show(ic);
      +elm_table_pack(table, ic, 0, 0, 3, 3);
      +
      +btn = elm_button_add(table);
      +elm_object_text_set(btn, "Click me i'm famous");
      +evas_object_show(btn);
      +elm_table_pack(table, btn, 3, 1, 1, 1);
      +evas_object_show(table);
      +
      + +

      Managing the Items

      + +

      If you want to change the position of the item after adding it, use the elm_table_pack_set() function. This function takes as parameters the item whose position to change, the new column, the new row, and the size of the item in number of rows and columns (colspan and rowspan).

      + +

      To add padding around the item, use the elm_table_padding_set() function. The second parameter is the padding between columns, and the third parameter is the padding between rows:

      +
      elm_table_padding_set(table, 10, 10);
      + +

      To change the alignment and size of an item, use the evas_object_size_hint parameters. They are used in the same way as with boxes. You can set the same size and weight to each item by using the homogeneous parameter:

      +
      elm_table_homogeneous_set(table, EINA_TRUE);
      +
      + +

      Clearing the Table

      + +

      To clear the table, use the elm_table_clear() function. If the clear parameter is EINA_TRUE, the table items are deleted. The evas_object_del() function will be called on each item.

      + + + + + + + + + + +
      Note
      Except as noted, this content is licensed under LGPLv2.1+.
      + + + + +
      + +Go to top + + + + + + + + diff --git a/org.tizen.ui.guides/html/native/efl/core_loop_n.htm b/org.tizen.ui.guides/html/native/efl/core_loop_n.htm new file mode 100755 index 0000000..fcd6f6d --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/core_loop_n.htm @@ -0,0 +1,87 @@ + + + + + + + + + + + + + Core Loop and OS Interfacing: Handling the Main Loop and Threads + + + + + +
      + +

      Core Loop and OS Interfacing: Handling the Main Loop and Threads

      +

      The Ecore library provides convenience functions, which allow you to manage the application main loop and threading.

      + +

      Tizen applications developed with EFL use the EDA (Event-driven Architecture) pattern. In EDA, applications reiterate the routine that checks input events, processes the events, and then displays the outputs. The main loop is the entity handling this sequence. It is the heart of any GUI based on EDA.

      + +

      Most applications start and end the main loop, which is used in special situations, such as propagation of events to UI components for handling and updating application appearance and state. That guarantees the delivery of all events received from low-level input devices and provides the accurate and speedy render event loop for synchronizing the application UI with events.

      + +

      The Ecore library provides main loop abstraction with a clean and tiny event loop library. Applications mainly deal with file descriptors handling, event handling, and timer handling from the beginning of the main loop.

      + +

      In addition, Ecore provides several modules related to, for example, Audio, Cocoa, Connection, Drm, FrameBuffer, Input, IPC, Wayland, Win32, and X11 with convenient methods to communicate with underlying operating systems, such as Linux, Windows®, or Mac OS® X.

      + +

      There are 2 types of threads in Tizen applications:

      +
        +
      • Main thread that contains the main loop
      • +
      • Worker threads that support concurrent processing. In parallel processing, applications must keep the GUI updating while processing the data related to the UI.
      • +
      + +

      The Ecore library provides these concurrent processing mechanisms through Ecore threads. An Ecore thread is not a simple wrapper for standard POSIX threads. It is not meant to be used to run parallel tasks throughout the entire duration of the application, especially when these tasks are performance-critical. Ecore manages these tasks using a pool of threads based on system configuration, such as the number of processors the system has, and the maximum amount of concurrent threads set for the application.

      + + + + + + + + + + +
      Note
      Except as noted, this content is licensed under LGPLv2.1+.
      + + + +
      + +Go to top + + + + + + + \ No newline at end of file diff --git a/org.tizen.ui.guides/html/native/efl/data_types_n.htm b/org.tizen.ui.guides/html/native/efl/data_types_n.htm new file mode 100755 index 0000000..f3dc7e0 --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/data_types_n.htm @@ -0,0 +1,1764 @@ + + + + + + + + + + + + + Data Types + + + + + +
      + +

      Data Types

      + +

      The Eina library is a central part of the EFL. It implements an API for data types, and allows you to create and manipulate several data types:

      + +
        +
      • Inline Array: standard array of inlined members
      • +
      • Array: standard array of void* data
      • +
      • Hash Table: standard hash of void* data
      • +
      • Inline List: list with nodes inlined into the user type
      • +
      • Compact List
      • +
      • List: standard list of void* data
      • +
      • Iterator Functions
      • +
      • Sparse Matrix: sparse matrix of void* data
      • +
      • Red-Black tree: red-black tree with nodes inlined into the user type
      • +
      • String Buffer: mutable string to prepend, insert, or append strings to a buffer
      • +
      • Stringshare: shares read-only string references
      • +
      • Tiler split: merges and navigates into 2D tiled regions
      • +
      • Trash: container of unused but allocated data
      • +
      • Generic Value Storage: container for generic value storage and access
      • +
      • Data Model API: container for data with a user-defined hierarchy or structure
      • +
      + + +

      Iterator Functions

      +

      Eina provides a set of iterator functions to manipulate data types, such as arrays.

      +

      These functions allow access to container elements in a generic way, without knowing which container is used (similar to iterators in the C++ STL). Iterators only allow sequential access (that is, from one element to the next one). For random access, Eina provides accessor functions.

      +

      Getting an iterator to access elements of a given container is done through the functions of that particular container. There is no function to create a generic iterator as iterators absolutely depend on the container. Note that all iterators, regardless of the container type, are always deleted with the same eina_iterator_free() function.

      +

      To get the data and iterate, use the eina_iterator_next() function. To call a function on every single element of a container, use the eina_iterator_foreach() function.

      +

      In addition to iterator functions, each data type also owns a set of macros that provide the iterators, such as FOREACH or REVERSE_FOREACH.

      + +

      Strings

      + +

      Stringshare

      + +

      The Eina_Stringshare data type functions allow you to store a single copy of a string and use it in multiple places throughout your program. This way you can save a lot of strings with less memory. It improves string creation and destruction speed, reduces memory use, and decreases memory fragmentation.

      +

      With this data type you can reduce the number of duplicated strings kept in memory. It is common for the same strings to be dynamically allocated repeatedly between applications and libraries, especially in circumstances where you can have multiple copies of a structure that allocates the string. Rather than duplicating and freeing these strings, request a read-only pointer to an existing string and only incur the overhead of a hash lookup. This can sound like micro-optimizing, but profiling has shown that this can have a significant impact as the number of copies grows.

      + +

      To manage stringshares:

      +
        +
      1. To create a stringshare, declare a string variable and call the eina_stringshare_add() function: +
        +const char *mystr;
        +const char *prologue = "Enlightenment is not just a window manager for Linux/X11 and others"
        +
        +mystr = eina_stringshare_add(prologue);
        +
      2. + +
      3. To retrieve or modify the string data: +
          +
        • Retrieve a string for use in a program from a format string using the eina_stringshare_printf() function. If you have a "format" string to pass to a function like printf, you can store it as a stringshare as well. +

          The following example produces "1 desktop manager to rule them all".

          +
          +const char *myfmtstr = "%d desktop manager to rule them all";
          +const char *str;
          +
          +str = eina_stringshare_printf(myfmtstr, 1);
          +
          +print(str)
          +
          +
        • + +
        • Replace the value of a stringshare with the eina_stringshare_replace() function. Pass the pointer address and the new value to the function. +
          +eina_stringshare_replace(&str,"One desktop manager to rule them all");
          +
          +
        • + +
        • Retrieve the length of the stringshare value with the eina_stringshare_strlen() function. +
          +printf("length: %d\n", eina_stringshare_strlen(str));
          +
          +
        • +
        +
      4. +
      5. When the string is no longer needed, delete it using the eina_stringshare_del() function: +
        +eina_stringshare_del(mystr);
        +
        +
      6. +
      + + + +

      String Buffer

      +

      The string buffer data type is designed to be a mutable string, allowing you to append, prepend or insert a string to a buffer. It allows easy handling of buffers in your applications.

      +

      To manage string buffers:

      +
        +
      1. Initialize the Eina_Strbuf instance and create the buffer: +
        +Eina_Strbuf *buf;
        +mybuffer = eina_strbuf_new();
        +
        +
      2. +
      3. Manage the buffer content: +
          +
        • To append characters to the buffer: +
            +
          • +

            For basic strings, use the eina_strbuf_append() function:

            +
            +eina_strbuf_append(mybuffer, "This is my string.");
            +
            +
          • +
          • To append 1 character to your buffer, use the eina_strbuf_append_char() function. You can also append a sized string to the buffer using the eina_strbuf_append_length() function. +
            +eina_strbuf_append_length(mybuffer, "Buffe", 5);
            +eina_strbuf_append_char(mybuffer, 'r');
            +
            +
          • +
          • To handle "printf" format strings, use the eina_strbuf_append_printf() function to add formatted strings to the buffer: +
            +eina_strbuf_append_printf(buf, "%s%c", "buffe", 'r');
            +
            +
          • +
          +
        • + +
        • To remove characters from one position to another, use the eina_strbuf_remove() function. The first parameter is the buffer, the second is the start position of the characters you want to delete, and the last the end position. +

          This example removes the first 19 characters of the buffer:

          +
          +eina_strbuf_remove(buf, 0, 18);
          +
          +
        • + +
        • To replace characters: + +
          • +eina_strbuf_replace() replaces a specific occurrence of a given string in the buffer with another string.
          • +
          • +eina_strbuf_replace_all() replaces all occurrences of a given string in the buffer with another string. +
          • +
          +
          +eina_strbuf_append(mybuffer, "buffer buffer buffer");
          +
          +// Replacing one occurrence of "buffer" by "B-U-F-F-E-R"
          +eina_strbuf_replace(mybuffer, "buffer", "B-U-F-F-E-R", 1);
          +
          +// Replacing all the occurrences of "buffer" by "B-U-F-F-E-R"
          +eina_strbuf_replace_all(mybuffer, "buffer", "B-U-F-F-E-R");
          +
          +// Replacing all the occurrences of "B-U-F-F-E-R" by "Buffer"
          +eina_strbuf_replace_all(mybuffer, "B-U-F-F-E-R", "Buffer");
          +
          +
        • +
        • To insert a string at the specified position, use the eina_strbuf_insert() function. Use the eina_strbuf_insert_printf() function with formatted strings. +
          +eina_strbuf_insert(mybuffer, "More buffer", 10);
          +
          +// Using eina_strbuf_length_get to get the buffer length
          +eina_strbuf_insert_printf(buf, " %s: %d", 6, "length", eina_strbuf_length_get(buf));
          +
          +
        • + +
        • To get the complete length of the string and the buffer, use the eina_strbuf_string_get() and eina_strbuf_length_get() functions: +
          +printf("%s : %d\n", eina_strbuf_string_get(mybuffer), eina_strbuf_length_get(buf));
          +
          +
        • +
        +
      4. + +
      5. When no longer needed, free the buffer with the eina_strbuf_free() function. You can also free the content of Eina_Strbuf without freeing the buffer itself using the eina_strbuf_string_free() function. +
        +eina_strbuf_free(mybuffer);
        +
        +
      6. +
      + +

      Arrays

      +

      An array is a data type which describes an ordered collection of values. The values are accessed by their index.

      +
      +INDEX | VALUE
      +--------------
      +0     | value0
      +1     | value1
      +2     | value2
      +3     | value3
      +4     | value4
      +5     | value5
      +6     | value6
      +7     | value7
      +
      +

      Eina provides 2 array types: the classic array and an inline array.

      + +

      Creating and Destroying a Classic Array

      + +

      The eina_array_new() function creates a new array. You can store strings or objects in the created array. The function returns a new array, or if memory allocation fails, NULL.

      +

      The first parameter of the eina_array_new() function defines the size of the array allocation step. For example, if you set it to 4, the function returns an array of 4 elements and the next time you grow the array it grows by 4 elements. Unless you have pushed 4 elements inside, it does not grow. But once you add the 5th element, it grows again and becomes an array of 8 elements. The allocation step feature is very useful for optimizing performance, and it also reduces memory fragmentation by having a size that fits the array usage. If you set the step to 0, the function sets a default safe value.

      + +

      To create an array to store strings:

      +
        +
      1. Create the array: +
        +// Strings to store in the array 
        +const char* strings[] = 
        +{
        +   "helo", "hera", "starbuck", "kat", "boomer",
        +   "hotdog", "longshot", "jammer", "crashdown", "hardball",
        +   "duck", "racetrack", "apolo", "husker", "freaker",
        +   "skulls", "bulldog", "flat top", "hammerhead", "gonzo"
        +};
        +// Declaring the array (type Eina_Array)
        +Eina_Array *array;
        +unsigned int i;
        +
        +// Creating the array
        +array = eina_array_new(20);
        +
        +// Inserting elements in the array
        +for (i = 0; i < 20; i++)
        +   eina_array_push(array, strdup(strings[i]));
        +
        +
      2. +
      3. To change the allocation step, use the eina_array_step_set() function: +
        • The first parameter is the array you want to change.
        • +
        • The second parameter is the size of that specific array (retrieved with the sizeof() function).
        • +
        • The last parameter is the new step size.
        +

        In this example, the array step changes from 20 to 30.

        +
        +eina_array_step_set(array, sizeof(*array), 30);
        +
        +
      4. +
      5. When no longer used, use the eina_array_free() function to free the array. It first calls the eina_array_flush() function and frees the memory of the pointer. It does not free the memory allocated for the elements of the array. To free them, use a while statement with the eina_array_pop function. +
        +// Freeing the array elements
        +while (eina_array_count(array))
        +   free(eina_array_pop(array));
        +
        +// Freeing the array itself
        +eina_array_free(array);
        +
        +
      6. +
      + +

      Modifying Classic Array Content

      + +

      To modify classic array content:

      +
        +
      • To set the data of an element, use the eina_array_data_set() function. The first parameter is the array, the second is the index of the element you want to set, and the last one is the data. You must first get the related pointer if you need to free it, as this function replaces the previously held data. Be careful, as there is no array or index check. If the value is NULL or invalid, the application can crash. +
        +free(eina_array_data_get(array, 0));
        +eina_array_data_set(array, 0, strdup(strings[3]);
        +
        +
      • +
      • To add elements to the end of the array, use the eina_array_push() function. The function returns EINA_TRUE on success, and EINA_FALSE on failure. The first parameter is the array to store the element, the second one is the data you want to store. If you store strings, remember to allocate the memory first. The example uses the strdup function to duplicate the string contained in strings[]. This function allocates the memory of the returned string, so you do not have to do it yourself. +
        +for (i = 0; i < 20; i++)
        +   eina_array_push(array, strdup(strings[i]));
        +
        +
      • + +
      • To remove the last element of an array, use the eina_array_pop() function. It takes the array as a parameter, and if the operation is successful, returns a pointer to the data of the removed element. +
        +while (eina_array_count(array))
        +   free(eina_array_pop(array));
        +
        +
      • + +
      • To rebuild the array by specifying the data to be kept, use the eina_array_remove() function: +
        • The first parameter is the array to be changed.
        • +
        • The second parameter is the function which selects the data to keep in the rebuilt array.
        • +
        • The last parameter is the data to pass to the selector function defined as the second parameter.
        +

        The selector function has to return an Eina_Bool, EINA_TRUE if the element stays, and EINA_FALSE if it has to be removed.

        +

        The following example shows how to remove all the elements of the array that are longer than 5.

        +
        +// Selector function 
        +Eina_Bool keep(void *data, void *gdata)
        +{
        +   if (strlen((const char*)data) <= 5)
        +      return EINA_TRUE;
        +
        +   return EINA_FALSE;
        +}
        +
        +int remove_array()
        +{
        +   Eina_Array *array;
        +   Eina_Array_Iterator iterator;
        +   const char *item;
        +   unsigned int i;
        +
        +   // Creating and populating an array
        +
        +   // Removing the undesired elements 
        +   eina_array_remove(array, keep, NULL);
        +
        +   // Flushing and freeing the array
        +
        +   return 0;
        +}
        +
        +
      • +
      • To completely wipe an array out, use the eina_array_flush() function. This function sets the count and total members of an array to 0, and frees and sets its data members to NULL. For performance reasons, there is no array check. If the value is NULL or invalid, the program can crash. The only parameter of this function is a pointer to the Eina_Array array you want to flush. +
        +eina_array_flush(array);
        +
        +
      • +
      • To empty an array quickly, use the eina_array_clean() function. This function sets the counting of members in the array to 0. It does not free any space so you have to use it carefully. For performance reasons, there is no array check. If the value is NULL or invalid, the program can crash. +
        +eina_array_clean(array);
        +
        +
      • +
      + +

      Accessing Classic Array Data

      + +

      To access classic array data:

      +
        +
      • To access the data in the array, use the eina_array_data_get() function with the array and the index of the element you want to get. The function returns a pointer to the data. +
        +// Getting the data of the first element 
        +char *mydata;
        +mydata = eina_array_data_get(array, 0);
        +
        +
      • + + +
      • To get the number of elements in an array, use the eina_array_count() function. The first parameter is a pointer to the array variable returned by the eina_array_new() function. +

        The function returns the number of elements.

        +
        +unsigned int nb_elm;
        +nb_elm = eina_array_count(array);
        +
        +
      • + +
      • To iterate through an array, you can use various methods: +
          +
        • Use the Eina_Array iterator called ITER_NEXT. +

          You can use the iterator by calling the macro EINA_ARRAY_ITER_NEXT(). It takes the array to iterate as the first parameter, a counter for the current index during the iteration, and a variable of the same type as the item data and an Eina_Iterator. To use it, declare an Eina_Iterator, an int counter, and, for example, a char * item if your array contains any strings.

          +
          +Eina_Array_Iterator iterator;
          +const char *item;
          +unsigned int i;
          +
          +EINA_ARRAY_ITER_NEXT(array, i, item, iterator)
          +   printf("item #%d: %s\n", i, item);
          +
          +
        • +
        • Use the eina_array_foreach() function to iterate over the array. +

          The first parameter is the array to iterate, the second is a callback function which determines whether the iteration can continue,and the last is the data passed to the callback function.

          +

          To iterate over the array and to print the data of each array element:

          +
          +// Callback function 
          +static Eina_Bool
          +elm_print(const void *container, void *data, void *fdata)
          +{
          +   printf("%s\n", (char *)data);
          +
          +   return EINA_TRUE;
          +}
          +
          +int iterating_array()
          +{
          +   Eina_Array *array;
          +   unsigned int i;
          +
          +   // Creating and populating an array
          +
          +   // Iterating over the array and calling elm_print on each element
          +   eina_array_foreach(array, elm_print, NULL);
          +
          +   // Freeing the element data and array
          +
          +   return 0;
          +}
          +
          +
        • + +
        • Use the eina_array_iterator_new() function to create an iterator for the array.

          The function returns a newly allocated iterator associated with the array. If the array is NULL or the count of the array members is less than or equal to 0, the function returns NULL. If the memory cannot be allocated, NULL is returned and EINA_ERROR_OUT_OF_MEMORY is thrown. Otherwise, a valid iterator is returned.

          +

          Pass to this function the array for which you want to create a new iterator. The iterator is used to run a sequential walk through the array, just like the eina_array_foreach() function.

          +

          To create an iterator and use it to print the data of each array element:

          +
          +static Eina_Bool
          +print_one(const void *container, void *data, void *fdata)
          +{
          +   printf("%s\n", (char*)data);
          +
          +   return EINA_TRUE;
          +}
          +
          +int new_iterator()
          +{
          +   Eina_Array *arra;
          +   Eina_Iterator *it;
          +   unsigned short int i;
          +   void *uninteresting;
          +   Eina_Bool rt;
          +
          +   // Creating and populating an array
          +
          +   it = eina_array_iterator_new(array);
          +
          +   it = eina_iterator_next(it, &uninteresting);
          +   eina_iterator_foreach(it, print_one, NULL);
          +   eina_iterator_free(it);
          +
          +   return 0;
          +}
          +
          +
        • +
        • Use the eina_array_accessor_new() function to get random access to the array elements. +

          The function returns a newly allocated accessor associated with the array. If the array is NULL or the counting of array members is less than or equal to 0, this function returns NULL. If the memory cannot be allocated, NULL is returned and EINA_ERROR_OUT_OF_MEMORY is thrown. Otherwise, a valid accessor is returned.

          +

          To use the accessor to retrieve and print the data of every other array element:

          +
          +int random_access()
          +{
          +   // Declaration of the array 
          +   Eina_Array *array;
          +   // Declaration of the accessor
          +   Eina_Accessor *acc;
          +
          +   // Generic counter
          +   unsigned short int i;
          +
          +   // Variable to put the data retrieved from an array element
          +   void *data;
          +
          +   // Creating and populating an array
          +
          +   // Creating the array accessor
          +   acc = eina_array_accessor_new(array);
          +
          +   // Random access to the data of the array elements
          +   for(i = 1; i < 10; i += 2)
          +   {
          +      // Putting the data in the variable 'data'
          +      eina_accessor_data_get(acc, i, &data);
          +      printf("%s\n", (const char *)data);
          +   }
          +
          +   // Freeing the accessor
          +   eina_accessor_free(acc);
          +
          +   // Freeing the array
          +
          +   return 0;
          +}
          +
          +
        • +
        +
      • +
      + + +

      Creating and Destroying an Inline Array

      + +

      An inline array is a container that stores the data itself, not the pointers to the data. This means there is no memory fragmentation, and for small data types, such as char, short, and int, it is more memory-efficient. This is because the data is stored in the cache and is faster to access. The bigger the data gets, however, the less likely it is and the less interesting it becomes.

      +

      To create an inline array, use the eina_inarray_new() function:

      +
      • The first parameter is the size of the value. In this example, only the characters are stored, and because of that, only sizeof(char) is passed to the function.
      • +
      • The second parameter defines the size of the array allocation step. For example, if you set it to 4, the function returns an inline array of 4 elements, and the next time you grow the inline array, it grows by 4 elements and becomes an array of 8 elements. If you set the step to 0, the function sets a default safe value. +

        The step can be changed later on using the eina_inarray_step_set() function.

      + +

      The eina_inarray_new() function returns a pointer to the new Eina_Inarray variable.

      +
      +int inline_array() 
      +{
      +   // Declare an inline array variable of the type Eina_Inarray
      +   Eina_Inarray *iarr;
      +
      +   // Create an inline array of "char"
      +   iarr = eina_inarray_new(sizeof(char), 0);
      +
      +   // When no longer needed, free the array memory
      +   eina_inarray_free(iarr);
      +
      +   return 0;
      +}
      +
      + +

      Modifying Inline Array Content

      + +

      To modify inline array content:

      +
        +
      • +

        To add data as the last element of the inline array, use the eina_inarray_push() function. The first parameter is a pointer to the array variable returned by the eina_inarray_new() function. The second parameter is the data you want to push to the inline array.

        +

        If everything runs fine, the function returns the index of the new element. If something goes wrong, it returns -1.

        +
        +ch = 'a';
        +eina_inarray_push(iarr, &ch);
        +
        +
      • +
      • +

        To insert data to a given position of the inline array, use the eina_inarray_insert_at() function:

        +
        • The first parameter is a pointer to the array variable returned by the eina_inarray_new() function.
        • +
        • The second parameter is the index of the element you want to add to the inline array.
        • +
        • The last parameter is a pointer to the content to be added.
        +

        The content of the pointer is copied to the given position in the inline array. All the members from the position to the end of the array are shifted towards the end. If the position is equal to the end of the array, the member is appended. If the position is bigger than the array length, the function fails.

        +
        +ch = 'a';
        +eina_inarray_push(iarr, &ch);
        +ch = 'b';
        +eina_inarray_push(iarr, &ch);
        +ch = 'd';
        +eina_inarray_push(iarr, &ch);
        +
        +// Adding data on position 3
        +ch = 'c';
        +eina_inarray_insert_at(iarr, 2, &ch)
        +
        +
      • +
      • +

        To insert data with your own position criteria, use the eina_inarray_insert() or eina_inarray_insert_sorted() function. The only difference between these functions is that the eina_inarray_insert_sorted() function assumes that the array is already sorted and consequently optimizes the insertion position by doing a binary search.

        +

        In both functions:

        +
        • The first parameter is a pointer to the array variable returned by the eina_inarray_new() function.
        • +
        • The second parameter is the data you want to push to the inline array.
        • +
        • The last parameter is the callback comparison function. +

          The Eina_Compare_Cb callback function compares data1 and data2. data1 is the value contained in the inline array and data2 is the data you pass to the eina_inarray_insert() or eina_inarray_insert_sorted() function as the second parameter. If data1 is less than data2, -1 must be returned, if it is greater, 1 must be returned, and if they are equal, 0 must be returned.

        +

        The following example shows how to insert a value before a greater value:

        +
        +// Defining the comparison function with the position criteria
        +Eina_Compare_Cb cmp(const void *a, const void *b)
        +{
        +   return *(int*)a > *(int*)b;
        +}
        +
        +int inline_insert()
        +{
        +   Eina_Inarray *iarr;
        +   char ch, *ch3;
        +   int a, *b;
        +
        +   // Creating an inline array
        +
        +   // Adding data to the inline array
        +   a = 97;
        +   eina_inarray_push(iarr, &a);
        +   a = 98;
        +   eina_inarray_push(iarr, &a);
        +   a = 100;
        +   eina_inarray_push(iarr, &a);
        +
        +   // Inserting data with the criteria
        +   a = 99;
        +   eina_inarray_insert_sorted(iarr, &a, cmp);
        +
        +   eina_inarray_free(iarr);
        +}
        +
        +
      • +
      • +

        To remove the last element of the inline array, use the eina_inarray_pop() function. The only parameter is a pointer to the array variable returned by the eina_inarray_new() function. This function returns the data removed from the inline array.

        +
        +eina_inarray_pop(iarr);
        +
        +
      • +
      • +

        To remove specific data from an inline array, use the eina_inarray_remove() function. The first parameter is a pointer to the array variable returned by the eina_inarray_new() function. The second parameter is the data you want to remove from the inline array.

        + +

        The eina_inarray_remove() function finds the data and removes the matching members from the array. The data can be an existing member of an inline array for optimized usage. In other cases, the content is matched using the memcmp() function.

        + + +

        The eina_inarray_remove() function returns the index of the removed member, or -1 if failed.

        +
        +iarr = eina_inarray_new(sizeof(char), 0);
        +
        +ch = 'a';
        +eina_inarray_push(iarr, &ch);
        +
        +// Removing data from the array
        +eina_inarray_remove(iarr, &ch);
        +
        +
      • + +
      • +

        To remove data from a defined position in an inline array, use the eina_inarray_remove_at() function. The first parameter is a pointer to the array variable returned by the eina_inarray_new() function. The second parameter is the index of the element you want to remove from the inline array.

        +

        The function returns EINA_TRUE on success and EINA_FALSE if something goes wrong. The member is removed from the inline array and any members after it are moved towards the array's head.

        +
        +// Removing data from position 2
        +eina_inarray_remove_at(iarr, 2);
        +
        +
      • +
      • To remove all the elements of the array, use the eina_inarray_flush() function. The first parameter is a pointer to the array variable returned by the eina_inarray_new() function. The function removes every member from the array.

        +
        +eina_inarray_flush(iarr);
        +
        +
      • + +
      • +

        To replace values in the inline array, use the eina_inarray_replace_at() function, which copies the data over the given position:

        +
        • The first parameter is a pointer to the array variable returned by the eina_inarray_new() function.
        • +
        • The second parameter is the index of the element you want to remove from the inline array.
        • +
        • The last parameter is the data you want to copy in place of the current data.
        +

        The function returns EINA_TRUE on success, and EINA_FALSE on failure. The given pointer content is copied to the given position in the array. The pointer is not referenced, instead its contents are copied to the member's array using the previously defined member_size. If the position does not exist, the function fails.

        +
        +// Replacing the member at position 3 
        +ch = 'd';
        +eina_inarray_replace_at(iarr, 3, &ch);
        +
        +
      • + +
      • +

        To sort an inline array, use the eina_inarray_sort() function, which applies a quick sorting algorithm to the inline array:

        +
        • The first parameter is a pointer to the array returned by the eina_inarray_new() function.
        • +
        • The last parameter is the Eina_Compare_Cb callback comparison function, which compares data1 and data2. +

          data1 and data2 are values contained in the inline array. If the data matches, the function must return 0, if data1 is less than data2, -1 must be returned and if it is greater, 1 must be returned.

        +
        +static int
        +short_cmp(const void *pa, const void *pb)
        +{
        +   const short *a = pa, *b = pb;
        +
        +   return *a - *b;
        +}
        +
        +int sorting_inline_array()
        +{
        +   Eina_Inarray *array;
        +   int i;
        +
        +   // Creating and populating the inline array
        +
        +   eina_inarray_sort(array, short_cmp);
        +   eina_inarray_free(array);
        +}
        +
        + +

        Be careful, the data given to the compare function is the pointer to the member memory itself. Do not change it.

        +
      • +
      + +

      Accessing Inline Array Data

      + +

      To access inline array data:

      +
        +
      • +

        To search a member in an inline array, use the eina_inarray_search() function that runs a linear walk looking for the given data:

        + +
        • The first parameter is a pointer to the array variable returned by the eina_inarray_new() function.
        • +
        • The second parameter is the data used by the callback function to run the comparison.
        • +
        • The last parameter is the Eina_Compare_Cb callback comparison function, which compares data1 and data2. +

          data1 is the value contained in the inline array and data2 is the data you pass to the eina_inarray_search() function as the second parameter. If the data matches, the function must return 0, if data1 is less than data2, -1 must be returned and if it is greater, 1 must be returned.

        +

        The function returns the member index, or -1 if not found.

        +
        +Eina_Compare_Cb
        +compare(const void *pa, const void *pb)
        +{
        +   const short *a = pa, *b = pb;
        +   if (*a == *b)
        +   {
        +      return EINA_TRUE;
        +   }
        +
        +   return EINA_FALSE;
        +}
        +
        +int search_inline_array()
        +{
        +   Eina_Inarray *array;
        +   int i;
        +   int elm_index;
        +   int to_search = 3;
        +
        +   // Creating and populating the inline array
        +
        +   elm_index = eina_inarray_search(array, &to_search, compare);
        +   eina_inarray_free(array);
        +}
        +
        + +

        Be careful, the data given to the compare function is the pointer to the member memory itself. Do not change it.

        +

        The eina_inarray_search_sorted() function does exactly the same as eina_inarray_search(), but uses a binary search for the given data.

        +
      • + +
      • +

        To get the number of elements in an inline array, use the eina_inarray_count(). The first parameter is a pointer to the array returned by the eina_inarray_new() function. The function returns an unsigned int, the number of elements.

        +
        +printf("Inline array of integers with %d elements:\n", eina_inarray_count(iarr));
        +
        +
      • + +
      • To iterate through an inline array, you can use various methods: +
          +
        • You can use the iterator macros for the inline arrays: FOREACH and REVERSE_FOREACH.

        • +
        • +

          To run a linear walk over an array of elements, use the EINA_INARRAY_FOREACH() macro. The first parameter is a pointer to the array variable returned by eina_inarray_new(), and the second parameter is the variable into which the current value is put during the walk. The EINA_INARRAY_REVERSE_FOREACH() macro does the same thing but starts from the last element.

          + +

          The following example illustrates the printing of each element and its pointer:

          +
          +iarr = eina_inarray_new(sizeof(char), 0);
          +int a, *b;
          +
          +a = 97;
          +eina_inarray_push(iarr, &a);
          +a = 98;
          +eina_inarray_push(iarr, &a);
          +a = 99;
          +eina_inarray_push(iarr, &a);
          +
          +EINA_INARRAY_FOREACH(iarr, b)
          +  printf("int: %d(pointer: %p)\n", *b, b);
          +
          +
        • +
        • To process the array data, use the eina_inarray_foreach() function, which invokes the given function on each element of the array with the given data: +
          • The first parameter is a pointer to the array variable returned by eina_inarray_new().
          • +
          • The second parameter is the function to run on each element. +

            The function must return EINA_TRUE as long as you want to continue iterating. By returning EINA_FALSE, you stop the iteration and make the eina_inarray_foreach() function return EINA_FALSE.

            +

            The data given to the function is the pointer to the member itself.

          • +
          • The last parameter is the data passed to the function called on each element.
          +

          The eina_inarray_foreach() function returns EINA_TRUE if it successfully iterates through all items of the array. Call the function for every given data in the array. This is a safe way to iterate over an array.

          +
          +static Eina_Bool
          +array_foreach(const void *array __UNUSED__, void *p, void *user_data __UNUSED__)
          +{
          +   short *member = p;
          +   int *i = user_data;
          +   (*p)++;
          +   (*i)++;
          +
          +   return EINA_TRUE;
          +}
          +
          +int inline_array_foreach()
          +{
          +   Eina_Inarray *iarr;
          +   iarr = eina_inarray_new(sizeof(char), 1);
          +   int i;
          +
          +   for (i = 0; i < numbers_count; i++)
          +   {
          +      short val = i;
          +      eina_inarray_push(iarr, &val);
          +   }
          +
          +   i = 0;
          +   eina_inarray_foreach(iarr, array_foreach, &i);
          +
          +   eina_inarray_free(iarr);
          +
          +   return 0;
          +}
          +
          +
        • + +
        • To remove some elements based on your own criteria, use the eina_inarray_foreach_remove() function, which walks through the array and, if the value matches in the callback function, removes the element: +
          • The first parameter is a pointer to the array returned by eina_inarray_new() function.
          • +
          • The second parameter is the callback function to run on each element. +

            The callback function returns EINA_TRUE if the value matches, or EINA_FALSE if it does not match.

          • +
          • The last parameter is the data passed to the callback function.
          +

          The function returns the number of removed entries or -1 if something goes wrong.

          +
          +static Eina_Bool
          +array_foreach(const void *array __UNUSED__, void *p, void *user_data __UNUSED__)
          +{
          +   short *member = p;
          +   int *i = user_data;
          +   if (*i == *p) 
          +   { 
          +      return EINA_TRUE;
          +   }
          +
          +   return EINA_FALSE;
          +}
          +
          +int inline_array_foreach_remove()
          +{
          +   Eina_Inarray *iarr;
          +   iarr = eina_inarray_new(sizeof(char), 1);
          +   int i;
          +
          +   for (i = 0; i < numbers_count; i++)
          +   {
          +      short val = i;
          +      eina_inarray_push(iarr, &val);
          +   }
          +
          +   i = 6;
          +   eina_inarray_foreach_remove(iarr, array_foreach, &i);
          +
          +   eina_inarray_free(iarr);
          +
          +   return 0;
          +}
          +
          + +
        • +
        +
      • +
      + + +

      Hash Tables

      +

      The Eina_Hash provides a way to store values in association with a key. For example, if you want to store some tuples into a table, you can do it using the Eina_Hash.

      +

      The Eina_Hash is implemented using an array of "buckets" where each bucket is a pointer to a structure that is the head of a red-black tree. This implementation makes it very robust against week keys as in the worst case scenario, you can still depend on an efficient binary tree implementation.

      + +

      Creating a Hash Table

      + +

      To create the hash table, use the eina_hash_new() function:

      +
        +
      • The first parameter is the function called when getting the size of the key.
      • +
      • The second parameter is the function called when comparing the keys.
      • +
      • The third parameter is the function called when getting the values.
      • +
      • The fourth parameter is the function called on each value when the hash table is freed, or when an item is deleted from it. NULL can be passed as the callback.
      • +
      • The last parameter is the size of the buckets.
      • +
      +

      When you create an Eina_Hash instance, you have to create 4 potentially long callback functions. To make the functions shorter, Eina_Hash offers some predefined functions to create the following kinds of hash tables:

      +
        +
      • eina_hash_string_djb2_new() creates a new hash table using the djb2 algorithm for strings.
      • +
      • eina_hash_string_superfast_new() creates a new hash table for use with strings (better with long strings).
      • +
      • eina_hash_string_small_new() creates a new hash table for use with strings with a small bucket size.
      • +
      • eina_hash_int32_new() and eina_hash_int64_new() create a new hash table for use with 32-bit and 64-bit integers.
      • +
      • eina_hash_pointer_new() creates a new hash table for use with pointers.
      • +
      • eina_hash_stringshared_new() creates a new hash table for use with shared strings.
      • +
      +

      All these predefined functions require only one parameter, which is the function to free the data you store in the hash table.

      +

      The following example shows how to manage a small phone book using the eina_hash_string_superfast_new() function to create the hash table.

      +
        +
      1. Create the phone book structure and some static data:

        +
        +struct _Phone_Entry 
        +{
        +   const char *name; // Full name
        +   const char *number; // Phone number
        +};
        +
        +typedef struct _Phone_Entry Phone_Entry;
        +
        +static Phone_Entry _start_entries[] = 
        +{
        +   { "Wolfgang Amadeus Mozart", "+01 23 456-78910" },
        +   { "Ludwig van Beethoven", "+12 34 567-89101" },
        +   { "Richard Georg Strauss", "+23 45 678-91012" },
        +   { "Heitor Villa-Lobos", "+34 56 789-10123" },
        +   { NULL, NULL }
        +};
        +
        +
      2. + +
      3. Create the callback to free the data:

        +
        +static void
        +_phone_entry_free_cb(void *data)
        +{
        +   free(data);
        +}
        +
        +

        The free callback can be changed later using the eina_hash_free_cb_set() function. You need to pass the hash and the new callback function.

        +
      4. + +
      5. Create and destroy the hash table.

        +

        The eina_hash_free_buckets() function frees all hash table buckets. It empties the hash but does not destroy it, and you can still use it for another purpose. When eina_hash_free() is called, the space allocated for the hash is freed.

        +
        +int free_data()
        +{
        +   Eina_Hash *phone_book = NULL;
        +   phone_book = eina_hash_string_superfast_new(_phone_entry_free_cb);
        +
        +   // Empty the phone book without destroying it
        +   eina_hash_free_buckets(phone_book);
        +   eina_hash_free(phone_book);
        +}
        +
        +
      6. +
      + + + + +

      Modifying Hash Table Content

      + +

      To modify hash table content:

      +
        +
      • +

        To add some data to a hash, use the eina_hash_add() function. This function takes the hash, the key to access the data, and the data as its parameters.

        +

        The following example shows how to add the initial data declared earlier to the hash:

        +
        +for (i = 0; _start_entries[i].name != NULL; i++)
        +{
        +   eina_hash_add(phone_book, _start_entries[i].name, strdup(_start_entries[i].number));
        +}
        +
        + +

        The Eina_Hash offers various ways to add elements to a hash, such as the eina_hash_direct_add() function, which adds the entry without duplicating the string key. The key is stored in the struct, so this function can be used with eina_stringshare to avoid key data duplication.

        +
        +for (i = 0; _start_entries[i].name != NULL; i++)
        +{
        +   // Allocating memory for the phone entry
        +   Phone_Entry *e = malloc(sizeof(Phone_Entry));
        +
        +   // Creating an eina_stringshare for the name and the phone number
        +   e->name = eina_stringshare_add(_start_entries[i].name);
        +   e->number = eina_stringshare_add(_start_entries[i].number);
        +
        +   // Adding the entry to the hash 
        +   eina_hash_direct_add(phone_book, e->name, e);
        +}
        +
        +
      • +
      • +

        To modify an entry, use eina_hash_modify() function passing the hash, the key of the data to change, and the new data. The function returns the old data on success.

        +

        The eina_hash_set() function does the same work as eina_hash_modify(), but if the entry does not exist, the function creates a new one.

        +
        +char *old_phone = NULL;
        +char *phone = NULL;
        +// Replace the phone number of Richard Strauss
        +old_phone = eina_hash_modify(phone_book, "Richard Georg Strauss", strdup("+23 45 111-11111"));
        +phone = eina_hash_set(phone_book, "Philippe de Magalhães", strdup("+33 6 111-11111"));
        +eina_hash_set(phone_book, "Richard Georg Strauss", strdup("+23 45 111-117711"));
        +
        +
      • +
      • +

        To change the key associated with the data without freeing and creating a new entry, use the eina_hash_move() function. You only have to pass the hash, the old key, and the new key. If the operation succeeds, the function returns EINA_TRUE, if not, it returns EINA_FALSE.

        +
        +Eina_Bool res;
        +res = eina_hash_move(phone_book, "Philippe de Magalhães", "Filipe de Magalhães");
        +
        +
      • +
      • +

        To delete entries from a hash table:

        +
        • Use the eina_hash_del() function to remove the entry identified by a key or data from the given hash table: +
          +Eina_Bool r;
          +const char *entry_name = "Heitor Villa-Lobos";
          +r = eina_hash_del(phone_book, entry_name, NULL);
          +
        • +
        • Use the eina_hash_del_by_key() function to remove an entry based on the key: +
          +r = eina_hash_del_by_key(phone_book, "Richard Georg Strauss");
          +
          +
        • +
        • +

          Use the eina_hash_del_by_data() function to remove an entry based on the data:

          +
          +r = eina_hash_del_by_data(phone_book, "+12 34 567-89101");
          +
          +
        • +
      + +

      Accessing Hash Table Data

      +

      To find hash table elements and get data based on the key name:

      +
        +
      • +

        To retrieve an entry based on its key, use the eina_hash_find() function by passing the hash and the key you are looking for:

        +
        +char *phone = NULL;
        +const char *entry_name = "Heitor Villa-Lobos";
        +
        +// Look for a specific entry and get its phone number
        +phone = eina_hash_find(phone_book, entry_name);
        +
        +
      • +
      • +

        To get the number of entries in a hash, use the eina_hash_population() function. Pass the hash as the only argument.

        +
        +unsigned int nb_elm;
        +nb_elm = eina_hash_population(phone_book);
        +
        +
      • + +
      • To iterate through a hash table, you can use various methods: +
          + +
        • to iterate over the hash table, use the eina_hash_foreach() function: + +
          • The first parameter is the hash.
          • +
          • The second parameter is the callback function called on each iteration. +

            The callback function has to return an Eina_Bool, EINA_TRUE if the iteration has to continue and EINA_FALSE if the iteration has to stop.

          • +
          • The last parameter one is the data passed to the callback function.
          + +

          The following example prints the key and the data of the hash entry (the name and the phone number):

          + +
          +static Eina_Bool
          +pb_foreach_cb(const Eina_Hash *phone_book, const void *key, void *data, void *fdata)
          +{
          +   const char *name = key;
          +   const char *number = data;
          +   printf("%s: %s\n", name, number);
          +
          +   // Return EINA_FALSE to stop this callback from being called
          +   return EINA_TRUE;
          +}
          +
          +printf("List of phones:\n");
          +
          +// Running the callback on the hash called phone_book 
          +eina_hash_foreach(phone_book, pb_foreach_cb, NULL);
          +printf("\n");
          +
          +
        • +
        • To iterate over the keys, use the eina_hash_iterator_key_new() function: +
          +// Declaration of the Eina_Iterator
          +Eina_Iterator *it;
          +
          +// Variable to handle the current iteration "data"
          +void *data;
          +
          +// Iterate over the keys (names)
          +printf("List of names in the phone book:\n");
          +
          +it = eina_hash_iterator_key_new(phone_book);
          +
          +// Use the generic eina_iterator_next()
          +while (eina_iterator_next(it, &data))
          +{
          +   const char *name = data;
          +   printf("%s\n", name);
          +}
          +
          +// Free the iterator
          +eina_iterator_free(it);
          +
          +
        • + +
        • To iterate over the hash data, use the eina_hash_iterator_data_new() function the same way as eina_hash_iterator_key_new(): +
          +// Declaration of the Eina_Iterator
          +Eina_Iterator *it;
          +
          +// Variable to handle the current iteration "data"
          +void *data;
          +
          +// Iterate over hash data 
          +printf("List of numbers in the phone book:\n");
          +
          +it = eina_hash_iterator_data_new(phone_book);
          +while (eina_iterator_next(it, &data))
          +{
          +   const char *number = data;
          +   printf("%s\n", number);
          +}
          +
          +// Free the iterator
          +eina_iterator_free(it);
          +
          +
        • +
        • To iterate over a tuple composed of keys and data, use the eina_hash_iterator_tuple_new() function: +
          +// Declaration of the Eina_Iterator
          +Eina_Iterator *tit;
          +
          +// Variable to handle the current iteration "data"
          +void *tuple;
          +
          +printf("List of phones:\n");
          +tit = eina_hash_iterator_tuple_new(phone_book);
          +while (eina_iterator_next(tit, &tuple))
          +{
          +   Eina_Hash_Tuple *t = tuple;
          +   const char *name = t->key;
          +   const char *number = t->data;
          +   printf("%s: %s\n", name, number);
          +}
          +
          +// Always free the iterator after its use
          +eina_iterator_free(tit); 
          +
          +
        • +
        +
      • +
      + + +

      Lists

      + +

      The Eina_List is a double-linked list that can store data of any type as void pointers. It provides a set of functions to create and manipulate the list to avoid the access to the struct's fields, similar to a self-made double-link list.

      +

      In addition to the previous and next node and its data, the Eina_List nodes keep a reference to an accounting structure. The accounting structure is used to improve the performance of some functions. The structure is private and must not be modified.

      + +

      In an Eina_List, everything is a "list": the list itself is a list where each node is a list as well.

      + +

      Eina provides 2 list types: the classic list (Eina_List) and an inline list (Eina_Inlist).

      + +

      Creating and Destroying a List

      +

      To use an Eina_List:

      + +
      1. Declare the list with NULL as the default value: +
        +int list()
        +{
        +   // Declaration of the Eina_List with NULL as default value;
        +   Eina_List *list = NULL;
        +
      2. + +
      3. Call the eina_list_append() function with the list and the data you want to append as parameters. +

        The list must be a pointer to the first element of the list (or NULL). The function returns a pointer to the list.

        +
        +   // Creating the first element of the list 
        +   list = eina_list_append(list, "watch");
        +
        +   // Adding more elements
        +   list = eina_list_append(list, "phone");
        +   list = eina_list_append(list, "ivi");
        +   list = eina_list_append(list, "notebook");
        +
      4. + +
      5. When you no longer need the list, free it: +
        +   // Free the Eina_List
        +   eina_list_free(list);
        +
        +   return 0;
        +}
        +
      6. +
      + + +

      Modifying List Content

      + +

      To modify list content:

      +
        +
      • +

        To add data to a list:

        + +
          +
        • To add data at the end of the list, use the eina_list_append() function. To add data at the top of the list, use eina_list_prepend(). The functions work in the same way, only adding the data to different places. +
          +list = eina_list_prepend(list, "set-top box");
          +
          +
        • + +
        • To insert data into the list after a specified data, use the eina_list_append_relative() function. As the last parameter, define the element after which the data is added. +

          For example to append data after the "phone" element:

          +
          +list = eina_list_append_relative(list, "single-board computer", "phone");
          +
          +
        • + +
        • To add a new entry before a specified data, use the eina_list_prepend_relative() function. It is similar to the eina_list_append_relative() function. +
          +list = eina_list_prepend_relative(list, "ultrabook", "ivi");
          +
          +
        • + +
        • To append a list node to a linked list after a specified member, use the eina_list_append_relative_list() function. To prepend a list node to a linked list before a specified member, use the Eina_List * eina_list_prepend_relative_list() function. +
        • +
        +
      • + +
      • To set data in a list member, use the eina_list_data_set() function. Pass the "list" (node) as the first argument and the data to set as the second. + +

        The following example also shows the usage of the eina_list_last() function, which returns the last element of an Eina_List.

        + +
        +// Setting new data for the last element
        +eina_list_data_set(eina_list_last(list), eina_stringshare_add("Boris"));
        +
        +
      • + +
      • To remove a node from the list, use the eina_list_remove() function. This function removes the first instance of the specified data from the given list. +
        +list = eina_list_remove(list, "ultrabook");
        +
        +

        You can also remove a "list" (node) from a list using the eina_list_remove_list() function. Pass the list you want to delete an element from and a 'list' (node) you want to delete.

        +
        +Eina_List *app_list = NULL;
        +Eina_List *to_remove = NULL;
        +
        +// Adding some elements to the list (using stringshares)
        +app_list = eina_list_append(app_list, eina_stringshare_add("enna"));
        +app_list = eina_list_append(app_list, eina_stringshare_add("ebird"));
        +app_list = eina_list_append(app_list, eina_stringshare_add("calaos"));
        +app_list = eina_list_append(app_list, eina_stringshare_add("rage"));
        +app_list = eina_list_append(app_list, eina_stringshare_add("terminology"));
        +app_list = eina_list_append(app_list, eina_stringshare_add("enlightenment"));
        +app_list = eina_list_append(app_list, eina_stringshare_add("eyelight"));
        +app_list = eina_list_append(app_list, eina_stringshare_add("ephoto"));
        +
        +// Finding the "list" to remove 
        +to_remove = eina_list_data_find_list(list, eina_string_share_add("enlightenment"));
        +
        +list = eina_list_remove_list(list, to_remove);
        +
        +
      • + +
      • To move elements in a list, you can use various function, such as eina_list_promote_list() that promotes an element to the top of the list or eina_list_demote_list() that puts the specified element at the end of the list. Remember that everything is a list so the second parameter represents the "list" (node) you want to move. Use the functions just like the eina_list_remove_list() function. +
        +list = eina_list_promote_list(list, eina_list_data_find_list(list, "ivi"));
        +
        +
      • +
      • To reverse all the elements of a list, use the eina_list_reverse() function. To obtain a reversed copy of the list while keeping the initial list unchanged, use the eina_list_reverse_clone() function. +
        +Eina_List *rev_copy;
        +
        +app_list = eina_list_reverse(app_list);
        +rev_copy = eina_list_reverse_clone(app_list);
        +
        +
      • +
      • To sort a list, use the eina_list_sort() function. This function takes a list which needs to be sorted, the maximum number of elements to be sorted, and a callback function that compares data. To sort all list elements, set the maximum number of elements to 0. +
        +int sort_cb(const void *d1, const void *d2)
        +{
        +   const char *txt = d1;
        +   const char *txt2 = d2;
        +   if(!txt) return(1);
        +   if(!txt2) return(-1);
        +
        +   return(strcmp(txt, txt2));
        +}
        +
        +extern Eina_List *list;
        +list = eina_list_sort(list, 0, sort_cb);
        +
        +
      • +
      • To merge 2 list into 1, use the eina_list_merge() function. The eina_list_sorted_merge() function merges 2 sorted lists according to the ordering function that you pass as the last argument. +
        +int sort_cb(void *d1, void *d2)
        +{
        +   const char *txt = NULL;
        +   const char *txt2 = NULL;
        +   if(!d1) return(1);
        +   if(!d2) return(-1);
        +
        +   return(strcmp((const char*)d1, (const char*)d2));
        +}
        +
        +Eina_List *sorted1;
        +Eina_List *sorted2;
        +Eina_List *newlist;
        +
        +// Insert some values and sort your lists
        +
        +// Simply merge 2 lists without any process
        +newlist = eina_list_merge(sorted1, sorted2);
        +
        +newlist = eina_list_sorted_merge(sorted1, sorted2, sort_cb);
        +
        +
      • +
      • To split a list, use the eina_list_split_list() function: +
        • The first parameter is the list to split.
        • +
        • The second parameter is the "list" (element) after which the list is split.
        • +
        • The last parameter is the head of the second list.
        +
        +// Original list (left list)
        +Eina_List *list = NULL;
        +
        +// New list (right list)
        +Eina_List *other_list = NULL;
        +
        +// Eina_List (element)
        +Eina_List *l;
        +
        +list = eina_list_append(list, "super tux");
        +list = eina_list_append(list, "frozen bubble");
        +list = eina_list_append(list, "lincity-ng");
        +
        +// Sorting the list (just for fun)
        +list = eina_list_sort(list, 0, cmp_func);
        +
        +// Looking for the 'split' element
        +l = eina_list_search_sorted_list(list, cmp_func, "frozen bubble");
        +
        +// Splitting the list
        +list = eina_list_split_list(list, l, &other_list);
        +
        +
      • +
      • To copy a list, use the eina_list_clone() function. The function copies all the elements in the list in the exact same order. +
        +Eina_List *app_list_copy;
        +
        +app_list_copy = eina_list_clone(app_list);
        +
        +
      • + +
      + + +

      Accessing List Data

      +

      To access list data:

      +
        +
      • To find some data on your list, use the eina_list_data_find() function. Pass the list containing your data as the first parameter and the data you are looking for as the last one. The function returns the found member data pointer if found, NULL otherwise. +

        The eina_list_data_find() function searches the list from the beginning to the end for the first member for which the data pointer is data. If it is found, the data is returned, otherwise NULL is returned. The function only compares pointers, which is why using Eina_Stringshare is very useful with lists, because it always returns the same pointer for the same string.

        +
        +Eina_List *app_list = NULL;
        +const char *res_str;
        +
        +// Adding some elements to the list (using stringshares)
        +app_list = eina_list_append(app_list, eina_stringshare_add("enna"));
        +app_list = eina_list_append(app_list, eina_stringshare_add("ebird"));
        +app_list = eina_list_append(app_list, eina_stringshare_add("calaos"));
        +app_list = eina_list_append(app_list, eina_stringshare_add("rage"));
        +app_list = eina_list_append(app_list, eina_stringshare_add("terminology"));
        +app_list = eina_list_append(app_list, eina_stringshare_add("enlightenment"));
        +app_list = eina_list_append(app_list, eina_stringshare_add("eyelight"));
        +app_list = eina_list_append(app_list, eina_stringshare_add("ephoto"));
        +
        +// Finding the data
        +res_str = eina_list_data_find(list, eina_string_share_add("enlightenment"));
        +if (res_str == eina_stringshare_add("enlightenment"))
        +   printf("Data is present");
        +else
        +   printf("Data not present");
        +
        + +

        The above example returns "Data is present".

        +

        The eina_list_data_find_list() function does the same thing as eina_list_data_find(), but returns an Eina_List. For an example, see the eina_list_remove_list() function.

        +

        You can access the data or a "list" (node) of an Eina_List using the eina_list_nth() and eina_list_nth_list() functions. The first one returns a pointer to the data of the "n" element and the second a pointer to the "list". To access the data of the 3rd element of an Eina_List:

        +
        +const char *res;
        +Eina_List *res_lst;
        +
        +res = eina_list_nth(app_list, 2);
        +res_lst = eina_list_nth_list(app_list, 2);
        +
        + +

        The res variable contains the pointer to the string "calaos". The res_lst variable is the list containing "calaos".

        +
      • + +
      • To search for data in a list, select your function based on whether the list is sorted or unsorted. +
          +
        • To search in an unsorted list, use the eina_list_search_unsorted() function: +
          • The first parameter is the list.
          • +
          • The second parameter is a callback function for comparison.
          • +
          • The last parameter is the data you are looking for.
          + +

          The eina_list_search_unsorted_list() function does the same but returns an "Eina_List".

          + + +

          The following example shows 2 searches using both the eina_list_search_unsorted() and eina_list_search_unsorted_list() functions:

          +
          +int search_list()
          +{
          +   // Declaring the list
          +   Eina_List *list = NULL; 
          +   Eina_List *l;
          +   // Little trick to use strcmp as Eina_Compare_Cb 
          +   Eina_Compare_Cb cmp_func = (Eina_Compare_Cb)strcmp;
          +
          +   void *data;
          +   int cmp_result;
          +
          +   list = eina_list_append(list, "debian");
          +   list = eina_list_append(list, "archlinux");
          +   list = eina_list_append(list, "centos");
          +
          +   data = eina_list_search_unsorted(list, cmp_func, "archlinux");
          +   l = eina_list_search_unsorted_list(list, cmp_func, "archlinux");
          +   if (l->data != data)
          +   {
          +      eina_list_free(list);
          +
          +      return 1;
          +   }
          +
          +   eina_list_free(list);
          +
          +   return 0;
          +}
          +
          + +
        • +
        • To search in sorted lists, use the eina_list_search_sorted_list() and eina_list_search_sorted() functions. They work similarly as the eina_list_search_unsorted() function. +
        • +
        +
      • + + +
      • To get data from a list element, use the eina_list_data_get() function. The function returns the data contained in the given list. + +

        The following example uses the eina_list_next() function to move through the list in a statement.

        +
        +int list_data_set()
        +{
        +   // Declaring the list
        +   Eina_List *list = NULL;
        +   // Eina_List in which to place the elements or lists
        +   Eina_List *l;
        +
        +   void *list_data;
        +
        +   list = eina_list_append(list, eina_stringshare_add("Bertrand"));
        +   list = eina_list_append(list, eina_stringshare_add("Cedric"));
        +   list = eina_list_append(list, eina_stringshare_add("Nicolas"));
        +   list = eina_list_append(list, eina_stringshare_add("Vincent"));
        +   list = eina_list_append(list, eina_stringshare_add("Raoul"));
        +   list = eina_list_append(list, eina_stringshare_add("Fabien"));
        +   list = eina_list_append(list, eina_stringshare_add("Philippe"));
        +   list = eina_list_append(list, eina_stringshare_add("billiob"));
        +
        +   for(l = list; l; l = eina_list_next(l))
        +      // Printing the data returned by eina_list_data_get
        +      printf("%s\n", (char*)eina_list_data_get(l));
        +
        +   EINA_LIST_FREE(list, list_data)
        +      eina_stringshare_del(list_data);
        +
        +   return 0;
        +}
        +
        +
      • + +
      • To move in a list, use the eina_list_last(), eina_list_next(), or eina_list_prev() functions to move to the last, next, or previous element in the list. +

        The following example scrolls backwards starting from the end of the list:

        +
        +for(l = eina_list_last(list); l; l = eina_list_prev(l))
        +   printf("%s\n", (char*)eina_list_data_get(l));
        +
        + +
      • + +
      • To count the list elements, use the eina_list_count() function. The function returns the number of items in a list. +
        +printf("List size: %d\n", eina_list_count(list));
        +
        +
      • +
      • To iterate through an array, you can use various iterators: +
          +
        • To iterate over a list from the beginning to the end, use the EINA_LIST_FOREACH macro: +
          • The first parameter is the list to iterate.
          • +
          • The second parameter is an Eina_List * to hold the current "List" (node).
          • +
          • The last parameter receives the current data during the run.
          + +

          The following example prints the data of each "List" (node) of the list:

          +
          +Eina_List *list = NULL;
          +Eina_List *l;
          +void *list_data;
          +
          +list = eina_list_append(list, "ls");
          +list = eina_list_append(list, "top");
          +list = eina_list_append(list, "rmdir");
          +list = eina_list_append(list, "uname");
          +
          +EINA_LIST_FOREACH(list, l, list_data)
          +   printf("%s\n", (char*)list_data);
          +
          +eina_list_free(list);
          +
          +
        • +
        • To iterate from the last element to the first, use the EINA_LIST_REVERSE_FOREACH macro. It works similarly as EINA_LIST_FOREACH(). +
        • +
        • To iterate over a list from the beginning to the end, you can also use the EINA_LIST_FOREACH_SAFE macro. It is called safe, because it stores the next "List" (node), so you can safely remove the current "List" (node) and continue the iteration. +
          +Eina_List *list;
          +Eina_List *l;
          +Eina_List *l_next;
          +char *data;
          +
          +list = eina_list_append(list, "tizen");
          +list = eina_list_append(list, "tizen");
          +list = eina_list_append(list, "tizen");
          +list = eina_list_append(list, "tizen");
          +
          +// Using EINA_LIST_FOREACH_SAFE to free the elements that match "tizen"
          +
          +EINA_LIST_FOREACH_SAFE(list, l, l_next, data)
          +   if (strcmp(data, "tizen") == 0) 
          +   {
          +      free(data);
          +      list = eina_list_remove_list(list, l);
          +   }
          +
          +
        • + + +
        • To remove each list element while having access to the node's data, use the EINA_LIST_FREE macro. Pass the list and a pointer to hold the current data. +
          +Eina_List *list;
          +char *data;
          +
          +// List is filled
          +
          +EINA_LIST_FREE(list, data)
          +   free(data);
          +
          +
        • +
        +
      • +
      + +

      Using an Inline List

      +

      The Eina_Inlist is a special data type drawn to store nodes pointers in the same memory as data. This way the memory is less fragmented, but operations, such as sort and count, are slower. The Eina_Inlist has its own purpose, but if you do not understand what the purpose is, use the regular Eina_List instead.

      + +

      The Eina_Inlist nodes can be part of a regular Eina_List, simply added with the eina_list_append() or eina_list_prepend() functions.

      + +

      To use the inline list:

      +
        +
      1. Define the structure of the data before creating the inline list: +
        +struct my_struct 
        +{
        +   EINA_INLIST;
        +   int a, b;
        +};
        +
        + +

        The structure is composed of 2 integers, the real data, and the EINA_INLIST type which is composed of 3 pointers defining the inline list structure:

        + +
          +
        • Eina_Inlist * next: next node
        • +
        • Eina_Inlist * prev: previous node
        • +
        • Eina_Inlist * last: last node
        • +
      2. + +
      3. +

        To create the inlist nodes, allocate the memory and use the eina_inlist_append() function:

        +
        • The first parameter is the existing list head or NULL to create a new list. +

          The following example passes NULL to create a new list.

        • +
        • The second parameter is the new list node, and it must not be NULL. +

          You must use the EINA_INLIST_GET() macro to get the inlist object of the datastruct.

        +
        +struct my_struct *d, *cur;
        +Eina_Inlist *list, *itr, *tmp;
        +
        +d = malloc(sizeof(*d));
        +d->a = 1;
        +d->b = 10;
        +
        +list = eina_inlist_append(NULL, EINA_INLIST_GET(d));
        +
        + +

        Repeat this operation for every new node:

        +
        +d = malloc(sizeof(*d));
        +d->a = 2;
        +d->b = 20;
        +list = eina_inlist_append(list, EINA_INLIST_GET(d));
        +
        +
      4. + +
      5. To add data to the inline list: +
        • Put data at the end of the inline list with the eina_inlist_prepend() function: +
          +d = malloc(sizeof(*d));
          +d->a = 3;
          +d->b = 30;
          +list = eina_inlist_prepend(list, EINA_INLIST_GET(d));
          +
          +
        • + +
        • Add a node before or after a given node with the eina_inlist_prepend_relative() and eina_inlist_append_relative() functions. +

          In both functions, the first parameter is the target list, the second is the element you want to add, and the last is the reference element to place data after (in this case). Similarly as in a regular Eina_List, everything is a list, so the last parameter is an Eina_Inlist typed variable.

          +
          d = malloc(sizeof(*d));
          +d->a = 4;
          +d->b = 40;
          +list = eina_inlist_append_relative(list, EINA_INLIST_GET(d), list);
          +
          +
      6. + +
      7. To sort and iterate an inline list, to find and move list elements, and to perform other inline list operations, see the Inline List API.
      8. + +
      9. When the inline list is no longer needed, destroy it by looping over the list to free each EINA_INLIST structure and the data using allocated memory. Use the eina_inlist_remove() function on each node. + +

        In the following example, the EINA_INLIST_CONTAINER_GET() macro returns the container object of an inlist (the EINA_INLIST of my_struc), and the list element is removed and the allocated memory of the container "object" is freed.

        + +
        while (list)
        +{
        +   struct my_struct *aux = EINA_INLIST_CONTAINER_GET(list, struct my_struct);
        +
        +   // Remove the current list element 
        +   list = eina_inlist_remove(list, list);
        +   free(aux);
        +}
        +
        +
      10. + + +
      + +

      Generic Value

      + +

      The Eina_Value object provides generic data storage and access, allowing you to store what you want in one single type of Eina_Value. It is meant for simple data types, providing uniform access and release functions, useful to exchange data preserving their types. The Eina_Value comes with predefined types for numbers, array, list, hash, blob, and structs, and it can convert between data types, including string.

      + +

      The Eina_Value can handle the following types:

      +
        +
      • EINA_VALUE_TYPE_UCHAR: unsigned char
      • +
      • EINA_VALUE_TYPE_USHORT: unsigned short
      • +
      • EINA_VALUE_TYPE_UINT: unsigned int
      • +
      • EINA_VALUE_TYPE_ULONG: unsigned long
      • +
      • EINA_VALUE_TYPE_TIMESTAMP: unsigned long used for timestamps
      • +
      • EINA_VALUE_TYPE_UINT64: unsigned integer of 64 bits
      • +
      • EINA_VALUE_TYPE_CHAR: char
      • +
      • EINA_VALUE_TYPE_SHORT: short
      • +
      • EINA_VALUE_TYPE_INT: int
      • +
      • EINA_VALUE_TYPE_LONG: long
      • +
      • EINA_VALUE_TYPE_INT64: integer of 64 bits
      • +
      • EINA_VALUE_TYPE_FLOAT: float
      • +
      • EINA_VALUE_TYPE_DOUBLE: double
      • +
      • EINA_VALUE_TYPE_STRINGSHARE: stringshared string
      • +
      • EINA_VALUE_TYPE_STRING: string
      • +
      • EINA_VALUE_TYPE_ARRAY: array
      • +
      • EINA_VALUE_TYPE_LIST: list
      • +
      • EINA_VALUE_TYPE_HASH: hash
      • +
      • EINA_VALUE_TYPE_TIMEVAL: 'struct timeval'
      • +
      • EINA_VALUE_TYPE_BLOB: blob of bytes
      • +
      • EINA_VALUE_TYPE_STRUCT: struct
      • +
      + + +

      To set up a generic value:

      +
        +
      1. Declare the necessary variables: +
        +// The Eina_Value itself
        +Eina_Value v;
        +// An integer 
        +int i;
        +// And a char *
        +char *newstr;
        +
        +
      2. + +
      3. To set up an Eina_Value for an integer, use the eina_value_setup() function. The first argument is the Eina_Value and the second is the type. +
        +eina_value_setup(&v, EINA_VALUE_TYPE_INT);
        +
        +
      4. +
      +

      To manage the generic value:

      +
        +
      • To set an integer, use the eina_value_set() function: +
        +eina_value_set(&v, 123);
        +
        +
      • + +
      • To get the value, use the eina_value_get() function. Pass the Eina_Value as the first argument, and a pointer to a variable to store the value (the target variable must have the same type as the Eina_Value). +
        +eina_value_get(&v, &i);
        +printf("v=%d\n", i);
        +
        +

        The above example prints "v=123".

        +
      • + +
      • To convert an Eina_Value to a string, use the eina_value_to_string() function. The code snippet above printed an int value. It is also possible to print the value as a string. +
        +newstr = eina_value_to_string(&v);
        +printf("v as string: %s\n", newstr);
        +
        +free(newstr);
        +
        +
      • + +
      • To free the memory allocated by eina_value_to_string(), use the eina_value_flush() function: +
        +eina_value_flush(&v);
        +
        +
      • + +
      • To store a string, get its value, and print it: +
        +const char *s;
        +
        +eina_value_setup(&v, EINA_VALUE_TYPE_STRING);
        +eina_value_set(&v, "My string");
        +eina_value_get(&v, &s);
        +
        +printf("v=%s (pointer: %p)\n", s, s);
        +
        +
      • + +
      • To set up a string, use the eina_value_to_string() function with an Eina_Value: +
        +char *newstr; 
        +
        +newstr = eina_value_to_string(&v);
        +printf("v as string: %s (pointer: %p)\n", newstr, newstr);
        +
        +// Free the memory allocated by eina_value_to_string
        +free(newstr);
        +
        +eina_value_flush(&v); 
        +
        +
      • + +
      • To convert from one Eina_Value to another, use the eina_value_convert() function. +

        The function puts the converted value into another Eina_Value. It accepts pointers, so you have to pass an Eina_Value pointer.

        +
        +Eina_Value v;
        +Eina_Value otherv;
        +
        +// Set up 2 Eina_Values: 1 int and 1 string
        +eina_value_setup(&otherv, EINA_VALUE_TYPE_STRING);
        +eina_value_setup(&v, EINA_VALUE_TYPE_INT);
        +
        +// Convert from int to string
        +eina_value_set(&v, 123);
        +eina_value_convert(&v, &otherv);
        +eina_value_get(&otherv, &s);
        +printf("otherv=%s\n", s);
        +
        +// Another way to do the same 
        +eina_value_set(&otherv, "33");
        +eina_value_convert(&otherv, &v);
        +eina_value_get(&v, &i);
        +printf("v=%d\n", i);
        +
        +// Clean your values
        +eina_value_flush(&otherv);
        +eina_value_flush(&v);
        +
        +
      • + +
      • To store an Eina_List, use the Eina_Value that corresponds to the EINA_VALUE_TYPE_LIST type. +
      • +
      • To create an Eina_Value_List, use the eina_value_list_setup() function. The function initializes a generic value storage of the list type. The first parameter is the "object" value, and the second one is the type (how to manage the stored list members). +
      • +
      + + + + + + + + + + +
      Note
      Except as noted, this content is licensed under LGPLv2.1+.
      + + + +
      + +Go to top + + + + + + + \ No newline at end of file diff --git a/org.tizen.ui.guides/html/native/efl/data_types_tools_n.htm b/org.tizen.ui.guides/html/native/efl/data_types_tools_n.htm new file mode 100755 index 0000000..a5bca4a --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/data_types_tools_n.htm @@ -0,0 +1,78 @@ + + + + + + + + + + + + + Data Types and Tools: Using Eina Resources + + + +
      +
      +

      Mobile native Wearable native

      +
      + + +
      + +
      + +

      Data Types and Tools: Using Eina Resources

      + +

      UI toolkits, such as Qt and Gtk, generally support their own data types, structures, functions, and macros in order for you to easily and efficiently make their applications. EFL, as one of Tizen native UI toolkits, provides data types and useful tools as well.

      + +

      The Eina library in EFL implements APIs for data types and structures easy to use and optimized in an efficient way. It also provides some useful tools, such as opening shared libraries, error management, type conversion, time accounting, and memory pool to help convenient application development.

      + +

      The main features of Eina are:

      +
        +
      • Data Types

        The Eina library is a central part of the EFL. It implements an API for data types, and allows you to create and manipulate several data types.

      • +
      • Tools

        Eina provides a number of tools, such as string manipulation, that make your life easier when coding applications.

      • +
      + + + + + + + + + + +
      Note
      Except as noted, this content is licensed under LGPLv2.1+.
      + + + +
      + +Go to top + + + + + + + \ No newline at end of file diff --git a/org.tizen.ui.guides/html/native/efl/datetime_tutorial_wn.htm b/org.tizen.ui.guides/html/native/efl/datetime_tutorial_wn.htm new file mode 100755 index 0000000..2febe03 --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/datetime_tutorial_wn.htm @@ -0,0 +1,111 @@ + + + + + + + + + + + + + + Creating Wearable Datetimes + + + + + + +
      +

      Creating Wearable Datetimes

      + + +

      This tutorial explains how you can create UI components that allow the user to select a date or time.

      + + + + + + + + + + +
      Note
      This feature is supported in wearable applications only.
      + + +

      Creating a Date Picker

      + +

      Use the elm_datetime component to add a date picker style (Year : Month : Day).

      +

      The following example creates the datepicker-styled Datetime and adds it in the conform.

      + +
      +// Add a datepicker style Datetime component
      +datetime = elm_datetime_add(ad->win);
      +evas_object_size_hint_align_set(datetime, EVAS_HINT_FILL, 0.5);
      +evas_object_size_hint_weight_set(datetime, EVAS_HINT_EXPAND, 1.0);
      +elm_object_style_set(datetime, "datepicker_layout");
      +evas_object_show(datetime);
      +
      +elm_object_content_set(ad->conform, datetime);
      +
      + +

      Creating a Time Picker

      +

      Use the elm_datetime component to add a time picker style (Hour(12) : Min : AM/PM, or Hour(24) : Min).

      +

      The following example creates the timepicker-styled Datetime and adds it in the conform.

      + +
      +// Add a timepicker style Datetime component
      +datetime = elm_datetime_add(ad->win);
      +evas_object_size_hint_align_set(datetime, EVAS_HINT_FILL, 0.5);
      +evas_object_size_hint_weight_set(datetime, EVAS_HINT_EXPAND, 1.0);
      +elm_object_style_set(datetime, "timepicker_layout");
      +evas_object_show(datetime);
      +
      +elm_object_content_set(ad->conform, datetime);
      +
      + + + + + +
      + +Go to top + + + + + + + diff --git a/org.tizen.ui.guides/html/native/efl/ecore_animation_n.htm b/org.tizen.ui.guides/html/native/efl/ecore_animation_n.htm new file mode 100755 index 0000000..944e05c --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/ecore_animation_n.htm @@ -0,0 +1,451 @@ + + + + + + + + + + + + + Ecore Animations + + + + + +
      + +

      Ecore Animations

      + +

      Ecore provides a facility for animations called Ecore_Animator. Ecore animators use the Ecore main loop for creating animations, running a specific action on each tick of a timer in the main loop.

      + +

      To create an Ecore animation:

      +
        +
      1. Determine the duration of the animation.
      2. +
      3. Define a callback function that performs the animation with that duration.
      4. +
      + +

      To use Ecore animators in your application, you must include the <Ecore.h> file. This file is included by default if you are already using the <Elementary.h> file in your application. You then declare an Ecore_Animator* variable and use the variable in the ecore_animator_* functions.

      + +

      The following example shows how to create a simple animation with a finite duration:

      + +
      +static Eina_Bool
      +_do_animation(void *data, double pos)
      +{
      +   evas_object_move(data, 100 * pos, 100 * pos);
      +   // Do some more animating...
      +}
      +ecore_animator_timeline_add(2, _do_animation, my_evas_object);
      +
      + +

      In the above example, we create a linear transition to move my_evas_object from position (0,0) to position (100,100) in 2 seconds.

      + +

      Creating an Animation with a Finite Duration

      + +

      Most of the time, you will want to create animations that last for a predefined time.

      + +

      The ecore_animator_timeline_add() function allows you to define an animator that is automatically deleted after the animation is finished:

      + +
      ecore_animator_timeline_add(double runtime, Ecore_Timeline_Cb func, const void *data)
      + +
        +
      • The first argument is the duration of the animation in seconds. The duration is not affected by frame rate.
      • +
      • The second argument is the callback function that performs the animation.
      • +
      • The third argument is the parameter passed to the callback function. This is usually the Evas object to animate.
      • +
      + + + + + + + + + + +
      Note
      The callback function can return ECORE_CALLBACK_RENEW to keep the animator running or ECORE_CALLBACK_CANCEL to stop the animator and have it be deleted automatically at any time. The callback function is also passed a timeline position parameter with a value between 0.0 (start) to 1.0 (end) to indicate where along the timeline the animator is running.
      + +

      The following example performs a linear horizontal translation of 500 pixels in 8 seconds:

      +
      +static Eina_Bool
      +_my_animation(void *data, double pos)
      +{
      +   Evas_Object *obj = data; // Get the target object
      +   int x, y, w, h; // Target object geometry
      +   evas_object_geometry_get(obj, &x, &y, &w, &h); // Get current object position and size attributes
      +   evas_object_move(obj, 500 * pos, y); // Linear translation of the Evas object
      +}
      +ecore_animator_timeline_add(8, _my_animation, my_evas_object);
      +
      + +

      Position Mappings

      + +

      The Ecore_Pos_Map position mappings are used to define the evolution of a given position in accordance with the desired effects. The value ranges from 0.0 to 1.0 on a given timeline. This position variation allows you to apply dynamic changes to any attribute of your Evas object, such as position, width, height, scale, angle, and color.

      + +

      Ecore supports the following position mappings (with the listed v1 and v2 parameters):

      + +
        +
      • ECORE_POS_MAP_LINEAR: linear 0.0 - 1.0 +
          +
        • v1: not used
        • +
        • v2: not used
        • +
        +
      • +
      • ECORE_POS_MAP_ACCELERATE: start slow, then speed up +
          +
        • v1: not used
        • +
        • v2: not used
        • +
        +
      • +
      • ECORE_POS_MAP_DECELERATE: start fast, then slow down +
          +
        • v1: not used
        • +
        • v2: not used
        • +
        +
      • +
      • ECORE_POS_MAP_SINUSOIDAL: start slow, speed up, then slow down at the end +
          +
        • v1: not used
        • +
        • v2: not used
        • +
        +
      • +
      • ECORE_POS_MAP_ACCELERATE_FACTOR: start slow, then speed up +
          +
        • v1: power factor: 0.0 is linear, 1.0 is standard acceleration, 2.0 is a much more pronounced acceleration (squared), 4.0 is cubed, and so on
        • +
        • v2: not used
        • +
        +
      • +
      • ECORE_POS_MAP_DECELERATE_FACTOR: start fast, then slow down +
          +
        • v1: power factor: 0.0 is linear, 1.0 is standard deceleration, 2.0 is a much more pronounced deceleration (squared), 3.0 is cubed, and so on
        • +
        • v2: not used
        • +
        +
      • +
      • ECORE_POS_MAP_SINUSOIDAL_FACTOR: start slow, speed up, then slow down at the end +
          +
        • v1: power factor: 0.0 is linear, 1.0 is a standard sinusoidal, 2.1 is a much more pronounced sinusoidal (squared), 3.0 is cubed, and so on
        • +
        • v2: not used
        • +
        +
      • +
      • ECORE_POS_MAP_DIVISOR_INTERP: start at gradient * v1, interpolated via power of v2 curve +
          +
        • v1: multiplication factor for gradient
        • +
        • v2: curve value
        • +
        +
      • +
      • ECORE_POS_MAP_BOUNCE: start at 0.0, then "drop" like a ball bouncing to the ground at 1.0, and bounce v2 times, with a decay factor of v1 +
          +
        • v1: bounce decay factor
        • +
        • v2: number of bounces
        • +
        +
      • +
      • ECORE_POS_MAP_SPRING: start at 0.0, then "wobble" like a spring until rest position at 1.0, and wobble v2 times, with a decay factor of v1 +
          +
        • v1: wobble decay factor
        • +
        • v2: number of wobbles
        • +
        +
      • +
      + +

      Figure: Position mappings

      +

      Position mappings

      + +

      Using Position Mappings

      +

      When using the animation callback function, the animator passes a timeline position parameter with a value between 0.0 (start) and 1.0 (end) to indicate where along the timeline the animator is running.

      + +

      If you want to create a non-linear animation, map the position value to one of several curves and mappings:

      +
      ecore_animator_pos_map(double pos, Ecore_Pos_Map map, double v1, double v2)
      +
        +
      • The first argument is the current position value, which ranges from 0.0 to 1.0.
      • +
      • The second argument is the position mapping you want to apply.
      • +
      • The third argument is the first parameter (v1) to pass to the position mapping.
      • +
      • The fourth argument is the second parameter (v2) to pass to the position mapping.
      • +
      + + + + + + + + + + +
      Note
      The v1 and v2 arguments are specific to the chosen position mapping. For example, if you are using ECORE_POS_MAP_BOUNCE, v1 represents the bouncing level and v2 the number of bounces.
      + +

      The following example performs a transition that bounces 7 times, diminishing by a factor of 1.8 over 5 seconds:

      + +
      static Eina_Bool
      +_my_animation_callback(void *data, double pos)
      +{
      +   Evas_Object *obj = data; // Get the target object
      +   int x, y, w, h; // Target object geometry
      +   double frame = pos; // Actual position variation
      +   // Get frame relative position depending on desired effect
      +   frame = ecore_animator_pos_map(pos, ECORE_POS_MAP_BOUNCE, 1.8, 7);
      +   evas_object_geometry_get(obj, &x, &y, &w, &h); // Get current object position and size attributes
      +   evas_object_move(obj, x, 600 * frame); // Move the Evas object according to desired effect
      +
      +   return EINA_TRUE;
      +}
      +ecore_animator_timeline_add(5, _my_animation_callback, my_evas_object);
      + +

      Creating an Infinite Animation

      + +

      If you want the animation to run for an unspecified amount of time, use the ecore_animator_add() function. This function works the same way as the ecore_animation_timeline_add() function, except its interval is based on frame rate. Using frame rate as the basis benefits performance, especially if you define multiple animations, since you may want to have a different timer for each callback function.

      + +
      +ecore_animator_add(Ecore_Task_Cb func, const void *data)
      +
      + +
        +
      • The first argument is the callback function that performs the animation.
      • +
      • The second argument is the parameter passed to the callback function. This is usually the Evas object to animate.
      • +
      + + + + + + + + + + +
      Note
      The function returns a pointer to an Ecore_Animator object, which you can use to adjust the animation.
      + +

      The following example creates a rectangle sliding from left to right and back again. When the rectangle hits one edge of the screen, it changes direction.

      + +
      static Eina_Bool
      +_slide_back_and_forth(void *data)
      +{
      +   typedef enum {LEFT, RIGHT} direction_t; // Direction datatype
      +   static int x = 0; // Initial position
      +   static direction_t direction = RIGHT; // Initial direction
      +   if (x >= 250)
      +      direction = LEFT; // Change direction
      +   else if (x <= 0)
      +      direction = RIGHT; // Change direction
      +   if (direction == RIGHT)
      +      evas_object_move(data, ++x, 350); // Slide to right
      +   else if (direction == LEFT)
      +      evas_object_move(data, --x, 350); // Slide to left
      +
      +   return EINA_TRUE;
      +}
      +int
      +main(int argc, char *argv[])
      +{
      +   // Declarations
      +
      +   // Ecore Evas init
      +
      +   // Draw Evas objects
      +
      +   // Animations go here
      +   anim = ecore_animator_add(_slide_back_and_forth, rectangle);
      +   // Ecore main loop
      +
      +   // Free memory
      +}
      + + + + + + + + + + +
      Note
      To use this code, you have to merge it with the Ecore transition example above.
      + +

      Chaining Animations

      + +

      You may sometimes want to delay animating an object. This can be useful if, for example, you want to start an animation only after another one has finished.

      + +

      You can simply set a delay to the second animation equal to the duration of the first animation:

      + +
      +static int runtime = 5;
      +static int delay = runtime;
      +static Eina_Bool
      +_start_fold_animation(void *data)
      +{
      +   ecore_animator_timeline_add(runtime, _fold_animation, data);
      +
      +   return EINA_FALSE;
      +}
      +static Eina_Bool
      +_start_unfold_animation(void *data)
      +{
      +   ecore_animator_timeline_add(runtime, _unfold_animation, data);
      +
      +   return EINA_FALSE;
      +}
      +_start_fold_animation(my_evas_object);
      +ecore_timer_add(delay, _start_unfold_animation, my_evas_object);
      +
      + +

      Pausing and Resuming Animations

      + +

      You can pause and resume Ecore animations. To pause a running animation, use the ecore_animator_freeze() function:

      + +
      ecore_animator_freeze(Ecore_Animator *animator)
      + +

      The parameter is the Ecore_Animator to pause.

      + +

      To resume the paused animation, use the ecore_animator_thaw() function:

      + +
      ecore_animation_thaw(Ecore_Animator *animator)
      + +

      The parameter is the Ecore_Animator to resume.

      + +

      The following example pauses a transition after 5 seconds and resumes it after 5 more seconds:

      + +
      +static Eina_Bool
      +_freeze_animation(void *data)
      +{
      +   ecore_animator_freeze(data);
      +
      +   return EINA_FALSE;
      +}
      +static Eina_Bool
      +_thaw_animation(void *data)
      +{
      +   ecore_animator_thaw(data);
      +
      +   return EINA_FALSE;
      +}
      +ecore_timer_add(5, _freeze_animation, animator);
      +ecore_timer_add(10, _thaw_animation, animator);
      +
      + +

      Freeing Up Memory

      + +

      When you create an animation that does not have a timeout, you will have to manually free up the memory allocated to the Ecore_Animator object. By comparison, if the animation has a timeout, Ecore implements the mechanisms to automatically delete the animator from the list of pointers: When your animation callback returns 0 or ECORE_CALLBACK_CANCEL, the animator manager takes care of freeing up the allocated memory.

      + +

      To manually free up the memory, delete the pointer by using the ecore_animator_del() function:

      + +
      ecore_animator_del(Ecore_Animator *animator)
      + +

      The argument is the Ecore_Animator whose memory allocation to free up.

      + +

      Regardless of the type of animation, it is good practice to always ensure that the allocated memory is freed up before the program exits:

      + +
      if (animator != NULL)
      +   ecore_animator_del(animator);
      + +

      Frametime

      +

      In most cases, you will want to use the default timer ECORE_ANIMATOR_SOURCE_TIMER. This timer ticks every "frametime" seconds and allows you to perform transitions within a predefined timeline. The timer uses the system clock to tick over every Nth second, with the default being 1/30th of a second.

      + +

      To tweak performance, you can change the frametime value:

      + +
      ecore_animator_frametime_set(double frametime)
      + +

      The argument is the new frametime value.

      + + + + + + + + + + +
      Note
      Too small a value can cause performance issues, whereas too high a value can cause your animation to seem jerky.
      + +

      If you want to get the current frametime value, use the ecore_animator_frametime_get() function.

      + +

      Custom Timer

      + +

      You may want to specify a custom timer to match your animation to third-party events. For example, the filling speed of a progress bar will mainly depend on the time it takes for a task to complete and the velocity at which the remaining time estimation evolves. This kind of animation requires you to use a custom timer.

      + +

      To use a custom timer, first set ECORE_ANIMATOR_SOURCE_CUSTOM as the timer source, and then drive the timer based on an input tick source (such as another application via IPC or a vertical blanking interrupt):

      + +
      ecore_animator_custom_source_tick_begin_callback_set(Ecore_Cb func, const void *data)
      + +

      The first argument is the callback function to call on the tick start. The second argument is the data to pass to the callback function.

      + +
      ecore_animator_custom_source_tick_end_callback_set(Ecore_Cb func, const void *data)
      + +

      The first argument is the callback function to call on the tick end. The second argument is the data to pass to the callback function to set the functions that will be called to start and stop the ticking source.

      + +

      Next, trigger a tick over one frame:

      + +
      ecore_animator_custom_tick(void)
      + +

      The following example supposes a progress bar that will be refreshed every time some progress occurs:

      + +
      ecore_animator_source_set(ECORE_ANIMATOR_SOURCE_CUSTOM);
      +void _on_progress_update()
      +{
      +   // Called when some progress occurs
      +   ecore_animator_custom_tick(); // Tick (next frame in progress bar animation)
      +}
      + +

      Finally, to get the current animator source, use the ecore_animator_source_get() function.

      + + + + + + + + + + +
      Note
      Except as noted, this content is licensed under LGPLv2.1+.
      + + + +
      + +Go to top + + + + + + + \ No newline at end of file diff --git a/org.tizen.ui.guides/html/native/efl/ecore_animation_tutorial_n.htm b/org.tizen.ui.guides/html/native/efl/ecore_animation_tutorial_n.htm new file mode 100755 index 0000000..dcd1204 --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/ecore_animation_tutorial_n.htm @@ -0,0 +1,417 @@ + + + + + + + + + + + + + + Creating Ecore Animations + + + + + + +
      +

      Creating Ecore Animations

      + + +

      This tutorial demonstrates how you can use Ecore animators to simplify the creation of animations. Using Ecore animators, you can manually create your own animations by changing and manipulating Evas object attributes. Ecore animators work like timers, running callback functions over a given duration (an animation timeline).

      + +

      Setting Up the Application

      + +

      In this part of the tutorial, we create a simple application that manipulates and animates an Evas object. We use a "Basic UI Application" as the basis for the application.

      +

      First, we set up the UI components we are going to use in the application:

      + +
      typedef struct appdata 
      +{
      +   // Main window
      +   Evas_Object *win;
      +   // Application title
      +   Evas_Object *label;
      +
      +   // Buttons
      +   Evas_Object *bt1;
      +   Evas_Object *bt2;
      +   Evas_Object *bt3;
      +
      +   // Animation target
      +   Evas_Object *target;
      +} appdata_s;
      +
      + +

      We then create the actual UI components in the create_base_gui() function, starting with the main window and application title:

      + +
      // Main window
      +ad->win = elm_win_util_standard_add(PACKAGE, PACKAGE);
      +elm_win_autodel_set(ad->win, EINA_TRUE);
      +
      +if (elm_win_wm_rotation_supported_get(ad->win)) 
      +{
      +   int rots[4] = { 0, 90, 180, 270 };
      +   elm_win_wm_rotation_available_rotations_set(ad->win, (const int *)(&rots), 4);
      +}
      +
      +evas_object_smart_callback_add(ad->win, "delete,request", win_delete_request_cb, NULL);
      +
      +// Application title
      +ad->label = elm_label_add(ad->win);
      +elm_object_text_set(ad->label, "Ecore Animator Tutorial");
      +evas_object_size_hint_weight_set(ad->label, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +elm_win_resize_object_add(ad->win, ad->label);
      +evas_object_show(ad->label);
      +
      + +

      Next, we create the animation target, which is an Evas object of type Elm_Image. The image that is used in the source code is stored in the res/images folder of the application. The image that is used in the EDC file is stored in the edje/images folder.

      + +
      // Animation target
      +// Setting the image path
      +char buf[PATH_MAX];
      +snprintf(buf, sizeof(buf), "/opt/usr/apps/%s/res/images/tizen-logo.png", PACKAGE);
      +// Adding the image
      +ad->target = elm_image_add(ad->win);
      +// Setting the image path
      +if (!elm_image_file_set(ad->target, buf, NULL))
      +   printf("error: could not load image \"%s\"\n", buf);
      +evas_object_size_hint_weight_set(ad->target, EVAS_HINT_FILL, EVAS_HINT_FILL);
      +// Moving the image
      +evas_object_move(ad->target, 130, 100);
      +// Resizing the image
      +evas_object_resize(ad->target, 200, 100);
      +// Showing the image
      +evas_object_show(ad->target);
      +
      + +

      All images are available in the /opt/usr/apps/<PACKAGE_NAME>/res/images folder of the application. The package name is defined at the begin of the application code:

      + +
      #if !defined(PACKAGE)
      +#define PACKAGE "org.tizen.ecoreanimator"
      +#endif
      +
      + +

      The image path is set by calling the elm_image_file_set() function. This function takes as arguments the ad->target Evas object and the path of the image file, built with the snprintf() function and stored in a buffer.

      + +
      // Setting the image path
      +char buf[PATH_MAX];
      +snprintf(buf, sizeof(buf), "/opt/usr/apps/%s/res/images/tizen-logo.png", PACKAGE);
      +// Adding the image
      +ad->target = elm_image_add(ad->win);
      +// Setting the image path
      +if (!elm_image_file_set(ad->target, buf, NULL))
      +   printf("error: could not load image \"%s\"\n", buf);
      +evas_object_size_hint_weight_set(ad->target, EVAS_HINT_FILL, EVAS_HINT_FILL);
      +
      + +

      The remaining code moves and resizes the image:

      + +
      //Moving the image
      +evas_object_move(ad->target, 130, 100);
      +//Resizing the image
      +evas_object_resize(ad->target, 200, 100);
      +//Showing the image
      +
      + +

      Creating a Rotation Effect

      + +

      After the animation target is created, we can create the first button and the associated rotation animation:

      + +
      // Button 1
      +ad->bt1 = elm_button_add(ad->win);
      +elm_object_text_set(ad->bt1, "Rotate");
      +evas_object_size_hint_weight_set(ad->bt1, EVAS_HINT_FILL, EVAS_HINT_FILL);
      +evas_object_move(ad->bt1, 25, 0);
      +evas_object_resize(ad->bt1, 90, 70);
      +evas_object_smart_callback_add(ad->bt1, "clicked", _btn_rotate_cb, ad);
      +evas_object_show(ad->bt1);
      +
      + +

      We create the button for triggering the rotation effect. The button is placed and resized, and associated with the _btn_rotate_cb() callback function. This callback function calls the animation on the animation target.

      + +
      static void _btn_rotate_cb(void *data, Evas_Object *btn, void *ev)
      +{
      +   appdata_s *ad = data;
      +
      +   ecore_animator_timeline_add(1, _do_rotate, ad->target);
      +}
      +
      + +

      In this callback function, we create an Ecore animator timeline using the ecore_animator_timeline_add() function. This function adds an animator that runs for a limited time: we run the _do_rotate() animation callback function for 1 second on the ad->target Evas object.

      + +

      Next, we write the animation callback function that actually runs the animation. This callback is an Ecore_Timeline_Cb function, meaning it returns an Eina_Bool value and takes as arguments some data and the current position along the animation timeline (pos).

      + +

      To create the rotation animation, we use an Evas Map. The map handles the necessary map points and allows you to manipulate the target Evas object on the X, Y, and Z axes.

      + +
      static Eina_Bool
      +_do_rotate(void *data, double pos)
      +{
      +   // Get the animation target
      +   Evas_Object *obj = data;
      +   // Declaration of an `Evas_Map`
      +   Evas_Map *m;
      +   // Variables to store the target size and position
      +   int x, y, w, h;
      +
      +   // Getting the size and position of the target
      +   evas_object_geometry_get(obj, &x, &y, &w, &h);
      +   // Creation of an `Evas_Map` of 4 points
      +   m = evas_map_new(4);
      +   // Populate source and destination map points to match exactly object.
      +   evas_map_util_points_populate_from_object(m, obj);
      +   // Create a rotation of 360° with x+(w/2) "x" center and y +(h/2) "y" center.
      +   evas_map_util_rotate(m, 360.0 * pos, x + (w / 2), y + (h / 2));
      +   // Setting the object to "animate" in the `Evas_Map`
      +   evas_object_map_set(obj, m);
      +   // Starting the Animation
      +   evas_object_map_enable_set(obj, EINA_TRUE);
      +   // Free used memory
      +   evas_map_free(m);
      +
      +   return EINA_TRUE;
      +}
      +
      + +

      In the animation callback function, we first declare the Evas Map. To implement the rotation, we need to set an X and Y center, so we create 4 integer variables to store the size and position of the target. This information is provided by the evas_object_geometry_get() function, which returns the X and Y coordinates and the weight and height of the target Evas object. Now we have all the required data to build the animation.

      + +

      We create an Evas Map consisting of four points, and we populate these points with the animation target:

      + +
      // Creation of an Evas_Map of 4 points
      +m = evas_map_new(4);
      +// Populate source and destination map points to match the object.
      +evas_map_util_points_populate_from_object(m, obj);
      +
      + +

      Now we can define the rotation using the evas_map_util_rotate() function:

      + +
      // Create a rotation of 360° with x+(w/2) "x" center and y +(h/2) "y" center.
      +evas_map_util_rotate(m, 360.0 * pos, x + (w / 2), y + (h / 2));
      +
      + +

      The animation callback function will be called at several points along the timeline, which is why we multiply the rotation angle (360°) by the timeline position (pos) to get the actual animation angle. If we do not do this, we will never see the animation take place. We then join the target object to the map and run the animation:

      + +
      // Setting the object to "animate" in the Evas Map
      +evas_object_map_set(obj, m);
      +// Starting the Animation
      +evas_object_map_enable_set(obj, EINA_TRUE);
      +
      + +

      Each call to the animation callback function will rotate the object (360 * timeline position) degrees.

      + +

      Finally, we free up the memory allocated to the Evas Map:

      + +
      // Free used memory
      +evas_map_free(m);
      +
      + +

      Creating a Zoom Effect

      + +

      The next animation is a zoom, for which we also use an Evas Map.

      + +

      First, we create the button in the create_base_gui() function:

      + +
      // Button 2
      +ad->bt2 = elm_button_add(ad->win);
      +elm_object_text_set(ad->bt2, "Zoom");
      +evas_object_size_hint_weight_set(ad->bt2, EVAS_HINT_FILL, EVAS_HINT_FILL);
      +evas_object_move(ad->bt2, 315, 0);
      +evas_object_resize(ad->bt2, 90, 70);
      +evas_object_smart_callback_add(ad->bt2, "clicked", _btn_zoom_cb, ad);
      +evas_object_show(ad->bt2);
      +
      + +

      We then create the button callback function with a new timeline:

      + +
      static void _btn_zoom_cb(void *data, Evas_Object *btn, void *ev)
      +{
      +   appdata_s *ad = data;
      +
      +   ecore_animator_timeline_add(1, _do_zoom, ad->target);
      +}
      +
      + +

      Next, we create the _do_zoom() animation callback function, which is almost identical to the _do_rotate() callback function, except that we use the evas_map_util_zoom() function to create the animation:

      + +
      static Eina_Bool
      +_do_zoom(void *data, double pos)
      +{
      +   Evas_Object *obj = data;
      +   Evas_Map *m;
      +   int x, y, w, h;
      +
      +   evas_object_geometry_get(obj, &x, &y, &w, &h);
      +   m = evas_map_new(4);
      +   evas_map_util_points_populate_from_object(m, obj);
      +   evas_map_util_zoom(m, 2 * pos, 2 * pos, x , y);
      +   evas_object_map_set(obj, m);
      +   evas_object_map_enable_set(obj, EINA_TRUE);
      +   evas_map_free(m);
      +
      +   return EINA_TRUE;
      +}
      +
      + +

      The evas_map_util_zoom() function takes the following arguments:

      + +
        +
      • The map to change
      • +
      • The horizontal zoom factor
      • +
      • The vertical zoom factor
      • +
      • The horizontal position (X coordinate) of the zooming center
      • +
      • The vertical position (Y coordinate) of the zooming center
      • +
      + +

      Here, we use a horizontal and vertical zoom factor of 2, and the X and Y coordinates of the target as the horizontal and vertical center coordinates.

      + +

      The _do_zoom() callback function is called at several points along the animation timeline, which is why we multiply the horizontal and vertical zoom factor values by the timeline position. Each call will zoom more than the previous one, thereby creating the animation effect.

      + +

      Creating a 3D Rotation Effect

      + +

      The last animation is a 3D rotation. For this one, we are going to rotate the Evas object on all three axes (X, Y, Z).

      + +

      First, we create the button and its callback function:

      + +
      // Button 3
      +ad->bt3 = elm_button_add(ad->win);
      +elm_object_text_set(ad->bt3, "3D");
      +evas_object_size_hint_weight_set(ad->bt3, EVAS_HINT_FILL, EVAS_HINT_FILL);
      +evas_object_move(ad->bt3, 170, 0);
      +evas_object_resize(ad->bt3, 90, 70);
      +evas_object_smart_callback_add(ad->bt3, "clicked", _btn_3d_cb, ad);
      +evas_object_show(ad->bt3);
      +
      + +
      static void _btn_3d_cb(void *data, Evas_Object *btn, void *ev)
      +{
      +   appdata_s *ad = data;
      +
      +   ecore_animator_timeline_add(1, _do_3d, ad->target);
      +}
      +
      + +

      Next, we create the _do_3d() animation callback function, which is very similar to the rotate and zoom callback functions. To create the animation, we use the evas_map_util_3d_rotate() function, which allows you to rotate any Evas object on all three axes.

      + +
      static Eina_Bool
      +_do_3d(void *data, double pos)
      +{
      +   Evas_Object *obj = data;
      +   Evas_Map *m;
      +   int x, y, w, h;
      +
      +   evas_object_geometry_get(obj, &x, &y, &w, &h);
      +   m = evas_map_new(4);
      +   evas_map_util_points_populate_from_object(m, obj);
      +   evas_map_util_3d_rotate(m, pos * 360, pos * 360, pos * 360, x + (w / 3), y + 60, 0);
      +   evas_object_map_set(obj, m);
      +   evas_object_map_enable_set(obj, EINA_TRUE);
      +   evas_map_free(m);
      +
      +   return EINA_TRUE;
      +}
      +
      + +

      The evas_map_util_3d_rotate() function takes the following arguments:

      + +
        +
      • The map to change
      • +
      • The angle (0-360°) to rotate around the X axis
      • +
      • The angle (0-360°) to rotate around the Y axis
      • +
      • The angle (0-360°) to rotate around the Z axis
      • +
      • The X coordinate of the rotation center
      • +
      • The Y coordinate of the rotation center
      • +
      • The Z coordinate of the rotation center
      • +
      + +

      Here, we rotate 360 degrees around each axis. The horizontal (X) rotation center is the X position of the target plus its width divided by 2. The vertical (Y) rotation center is the Y position of the target plus 60. The Z rotation center is 0.

      + +

      As with the rotation and zoom animations, we multiply the angles by the timeline position to gently rotate the target on each call to the _do_3d() callback function along the timeline.

      + +

      Creating Drop and Bounce Effects

      + +

      To finish, we add drop and bounce effects to our buttons at application start. To do this, we create one timeline per button after creating the buttons in the create_base_gui() function:

      + +
      ecore_animator_timeline_add(2, _do_drop, ad->bt1);
      +ecore_animator_timeline_add(2.3, _do_drop, ad->bt2);
      +ecore_animator_timeline_add(2.5, _do_drop, ad->bt3);
      +
      + +

      We call the same _do_drop() animation callback function for each timeline. In this callback, instead of using an Evas Map, we simply change the position of the target using the evas_object_move() function:

      + +
      static Eina_Bool
      +_do_drop(void *data, double pos)
      +{
      +   Evas_Object *obj = data;
      +   int x, y, w, h;
      +   double frame = pos;
      +   frame = ecore_animator_pos_map(pos, ECORE_POS_MAP_BOUNCE, 2, 4);
      +
      +   evas_object_geometry_get(obj, &x, &y, &w, &h);
      +   evas_object_move(obj, x, 600 * frame);
      +
      +   return EINA_TRUE;
      +}
      +
      + +

      To get the bounce effect, we use the ecore_animator_pos_map() function, which maps an input position from 0.0 to 1.0 along the timeline to a position on a different curve. The curve can be of different types, such as LINEAR, SINUSOIDAL, and BOUNCE. This function takes the following arguments:

      + +
        +
      • The input position to map
      • +
      • The mapping to use (LINEAR, SINUSOIDAL, and so on)
      • +
      • v1, which is the first parameter used by the mapping
      • +
      • v2, which is the second parameter used by the mapping
      • +
      + +

      The ECORE_POS_MAP_BOUNCE map we use starts at 0.0, then drops like a ball bouncing to the ground at 1.0, bouncing v2 times with a decay factor of v1. Here, we bounce 4 times with a decay factor of 2:

      + +
      frame = ecore_animator_pos_map(pos, ECORE_POS_MAP_BOUNCE, 2, 4);
      +
      + +

      This frame is used in the move function to create the animation. The value increases on each _do_drop() call along the timeline, which produces a nice drop of the buttons from their initial position to 600 pixels on the vertical axis.

      + + + + +
      + +Go to top + + + + + + + diff --git a/org.tizen.ui.guides/html/native/efl/edc_optimization_n.htm b/org.tizen.ui.guides/html/native/efl/edc_optimization_n.htm new file mode 100755 index 0000000..a7aa126 --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/edc_optimization_n.htm @@ -0,0 +1,556 @@ + + + + + + + + + + + + + + Optimizing EDC + + + + + + +
      +

      Optimizing EDC

      + + +

      To optimize EDC:

      + + + +

      Removing Unnecessary Parts

      +

      When you create EDC, there can be obsolete and unnecessary parts. Since they have an effect on performance, remove them.

      + + + + + + + + + + + + + + + +
      BeforeAfter
      +
      +collections 
      +{
      +   group 
      +   { 
      +      name: "main";
      +      parts 
      +      {
      +         part 
      +         { 
      +            name: "bg";
      +            type: RECT;
      +            description 
      +            { 
      +               state: "default" 0.0;
      +               rel1.relative: 0.0 0.0;
      +               rel2.relative: 1.0 1.0;
      +               color: 255 255 255 255;
      +            }
      +         }
      +         part 
      +         { 
      +            name: "new";
      +            type: RECT;
      +            scale: 1;
      +            mouse_events: 1;
      +            description 
      +            { 
      +               state: "default" 0.0;
      +               color: 255 255 0 255;
      +               rel1.relative: 0.2 0.2;
      +               rel2.relative: 0.8 0.8;
      +            }
      +         }
      +         part 
      +         { 
      +            name: "old";
      +            type: RECT;
      +            scale: 1;
      +            mouse_events: 1;
      +            description 
      +            { 
      +               state: "default" 0.0;
      +               color: 0 0 0 0;
      +               rel1.relative: 0.5 0.5;
      +               rel2.relative: 1.0 1.0;
      +            }
      +         }
      +      }
      +   }
      +}
      +
      +
      +collections 
      +{
      +   group 
      +   { 
      +      name: "main";
      +      parts 
      +      {
      +         part 
      +         { 
      +            name: "bg";
      +            type: RECT;
      +            description 
      +            { 
      +               state: "default" 0.0;
      +               rel1.relative: 0.0 0.0;
      +               rel2.relative: 1.0 1.0;
      +               color: 255 255 255 255;
      +            }
      +         }
      +         part 
      +         { 
      +            name: "new";
      +            type: RECT;
      +            scale: 1;
      +            mouse_events: 1;
      +            description 
      +            { 
      +               state: "default" 0.0;
      +               color: 255 255 0 255;
      +               rel1.relative: 0.2 0.2;
      +               rel2.relative: 0.8 0.8;
      +            }
      +         }  
      +
      +
      +
      +
      +
      +
      +
      +
      +
      +
      +
      +
      +
      +       
      +      }
      +   }
      +}
      +
      + +

      Using Text instead of Textblock

      + +

      The following EDCs lead to the same result. However, use TEXT for the simple texts for high performance apart from using tags or multiple lines.

      + + + + + + + + + + + + + + + +
      BeforeAfter
      +
      +collections 
      +{
      +   styles 
      +   {
      +      style 
      +      { 
      +         name: "text_style";
      +         base: "font="Sans" font_size=30 text_class=entry 
      +         color=#0088AA style=shadow,bottom 
      +         shadow_color=#00000080 valign=0.5 ellipsis=1.0 
      +         wrap=none align=center";
      +      }
      +   }
      +   group 
      +   { 
      +      name: "main";
      +      parts 
      +      {
      +         part 
      +         { 
      +            name: "text";
      +            type: TEXTBLOCK;
      +            scale: 1;
      +            description 
      +            { 
      +               state: "default" 0.0;
      +               text 
      +               {
      +                  style: "text_style";
      +                  text: "TEXT";
      +               }
      +            }
      +         }
      +      }
      +   }
      +}
      +
      +
      +collections 
      +{
      +   group 
      +   { 
      +      name: "main";
      +      part 
      +      { 
      +         name: "simple";
      +         type: TEXT;
      +         scale: 1;
      +         effect: SHADOW;
      +         description 
      +         { 
      +            state: "default" 0.0;
      +            align: 0.5 0.5;
      +            color: 0 136 170 255;
      +            visible: 1;
      +            text 
      +            {
      +               size: 30;
      +               font: "Sans";
      +               text: "TEXT";
      +            }
      +         }
      +      }
      +   }
      +}
      +
      + +

      Compressing Images and Embedding into EDC

      + +

      When you use a fixed image, it is more efficient to call an image within EDC. This save time in accessing the image data and is more suitable for the data size.

      + +
      +collections 
      +{
      +   images 
      +   {
      +      image: "logo.png" COMP;
      +   }
      +   group 
      +   { 
      +      name: "main";
      +      parts 
      +      {
      +         part 
      +         { 
      +            name: "logo";
      +            type: IMAGE;
      +            description 
      +            { 
      +               state: "default" 0.0;
      +               rel1.relative: 0.0 0.0;
      +               rel2.relative: 1.0 1.0;
      +               image.normal: "logo.png";
      +               aspect: 1 1;
      +               aspect_preference: BOTH;
      +            }
      +         }
      +      }
      +   }
      +}
      +
      + +

      Using a Spacer

      +

      When you use a part (such as Padding) which is invisible but has a size, using Spacer is more efficient. Since Spacer is invisible, it does not have the visible and color options.

      + + + + + + + + + + + + + + + + +
      BeforeAfter
      +
      +collections 
      +{
      +   group 
      +   { 
      +      name: "main";
      +      parts 
      +      {
      +         part 
      +         { 
      +            name: "bg";
      +            type: RECT;
      +            description 
      +            { 
      +               state: "default" 0.0;
      +               color: 255 255 255 255;
      +            }         
      +         }
      +         part 
      +         { 
      +            name: "padding_left_top";
      +            type: RECT;
      +            description 
      +            { 
      +               state: "default" 0.0;
      +               color: 0 0 0 0;
      +               rel1.to: "bg";
      +               rel2.to:"bg";
      +               rel2.relative: 0.0 0.0;
      +               align: 0.0 0.0;               
      +               min: 100 100;        
      +            }
      +         }
      +         part 
      +         { 
      +            name: "padding_right_bottom";
      +            type: RECT;
      +            description 
      +            { 
      +               state: "default" 0.0;
      +               color: 0 0 0 0;
      +               rel1.to: "bg";
      +               rel1.relative: 1.0 1.0;
      +               rel2.to:"bg";
      +               align: 1.0 1.0;               
      +               min: 100 100;
      +            }         
      +         }
      +         part 
      +         { 
      +            name: "content";
      +            type: RECT;
      +            description 
      +            { 
      +               state: "default" 0.0;
      +               color: 255 255 0 255;
      +               rel1.to: "padding_left_top";
      +               rel1.relative: 1.0 1.0;
      +               rel2.to:"padding_right_bottom";
      +               rel2.relative: 0.0 0.0;
      +            }         
      +         }
      +      }
      +   }
      +}
      +
      +
      +collections 
      +{
      +   group 
      +   { 
      +      name: "main";
      +      parts 
      +      {
      +         part 
      +         { 
      +            name: "bg";
      +            type: RECT;
      +            description 
      +            { 
      +               state: "default" 0.0;
      +               color: 255 255 255 255;
      +            }         
      +         }
      +         part 
      +         { 
      +            name: "padding_left_top";
      +            type: SPACER;
      +            description 
      +            { 
      +               state: "default" 0.0;
      +               rel1.to: "bg";
      +               rel2.to:"bg";
      +               rel2.relative: 0.0 0.0;
      +               align: 0.0 0.0;               
      +               min: 100 100;
      +            }         
      +         }
      +         part 
      +         { 
      +            name: "padding_right_bottom";
      +            type: SPACER;
      +            description 
      +            { 
      +               state: "default" 0.0;
      +               rel1.to: "bg";
      +               rel1.relative: 1.0 1.0;
      +               rel2.to:"bg";
      +               align: 1.0 1.0;               
      +               min: 100 100;
      +            }         
      +         }
      +         part 
      +         { 
      +            name: "content";
      +            type: RECT;
      +            description 
      +            { 
      +               state: "default" 0.0;
      +               color: 255 255 0 255;
      +               rel1.to: "padding_left_top";
      +               rel1.relative: 1.0 1.0;
      +               rel2.to:"padding_right_bottom";
      +               rel2.relative: 0.0 0.0;
      +            }         
      +         }
      +      }
      +   }
      +}
      +
      + +

      Using the Image Border Feature

      + +

      When you use an image, you do not need to use a full size or larger size image. As you can see below, it is much more efficient to scale the image using a border option.

      + + + + + + + + + + + + + + + + + + + +
      BeforeAfter
      +
      +collections 
      +{
      +   images 
      +   {
      +      image: "test.png" COMP;
      +   }
      +   group 
      +   { 
      +      name: "main";
      +      parts 
      +      {
      +         part 
      +         { 
      +            name: "test";
      +            type: IMAGE;
      +            description 
      +            { 
      +               state: "default" 0.0;
      +               rel1.relative: 0.2 0.2;
      +               rel2.relative: 0.8 0.8;
      +               image.normal: "test.png";
      +
      +            }
      +         }
      +      }
      +   }
      +}
      +
      +
      +collections 
      +{
      +   images 
      +   {
      +      image: "test.png" COMP;
      +   }
      +   group 
      +   { 
      +      name: "main";
      +      parts 
      +      {
      +         part 
      +         { 
      +            name: "test";
      +            type: IMAGE;
      +            description 
      +            { 
      +               state: "default" 0.0;
      +               rel1.relative: 0.2 0.2;
      +               rel2.relative: 0.8 0.8;
      +               image.normal: "test.png";
      +               image.border: 5 5 5 5;
      +            }
      +         }
      +      }
      +   }
      +}
      +

      Image before

      Image after

      + + + + +
      + +Go to top + + + + + + + \ No newline at end of file diff --git a/org.tizen.ui.guides/html/native/efl/edc_part_block_n.htm b/org.tizen.ui.guides/html/native/efl/edc_part_block_n.htm new file mode 100755 index 0000000..4b2c935 --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/edc_part_block_n.htm @@ -0,0 +1,2080 @@ + + + + + + + + + + + + + EDJE Data Collection Reference + + + + + +
      + +

      EDJE Data Collection Reference

      + + + +

      Edje Blocks

      + +

      A typical Edje file starts with the following definitions:

      + +
      +images {}
      +fonts {}
      +color_classes {}
      +styles {}
      +collections 
      +{
      +   sounds 
      +   {
      +      tone: "tone-1" 2300;
      +      tone: "tone-2" 2300;
      +      sample 
      +      {
      +         name: "sound1" RAW;
      +         source: "sound_file1.wav";
      +      }
      +   }
      +   group {}
      +   group {}
      +}
      +
      + +

      To get more details above each sub-block, click on the links inside the collections block above.

      + + + + + + + + + + +
      Note
      This guide is based on original work from Andres Blanc (dresb) andresblanc@gmail.com, it has been heavily expanded and edited since then.
      + +

      Images Block

      + +
      +images 
      +{
      +   image: "filename1.ext" COMP;
      +   image: "filename2.ext" LOSSY 99;
      +   set {}
      +   set {}
      +}
      +
      + +

      The images block is used to list each image file which are used in the theme. If any compression method is used, it is also defined here. Besides the document's root, additional images blocks can be included inside other blocks, usually collections, group, and part. This makes file list maintenance easier when the theme is split among multiple files.

      + +
        +
      • image [image file] [compression method] (compression level) +

        This is included in each image file. The full path to the directory holding the images can be defined later with edje_cc's "-id" option. Available compression methods are:

        +
          +
        • RAW: Uncompressed
        • +
        • COMP: Lossless compression
        • +
        • LOSSY [0-100]: JPEG lossy compression with quality from 0 to 100
        • +
        • USER: Not embedded to the file, refer to the external file instead
        • +
        +
      • +
      + +

      Images.set Block

      + +
      +set 
      +{
      +   name: "image_name_used";
      +   image {}
      +   image {}
      +}
      +
      + +

      The set block is used to define an image with different content depending on their size. Besides the document's root, additional set blocks can be included inside other blocks, normally collections, group, and part. This makes file list maintenance easier when the theme is split among multiple files.

      + +
        +
      • name [image name] +

        Defines the name that refer to this image description.

        +
      • +
      + +

      Images.set.image Block

      + +
      +image 
      +{
      +   image: "filename4.ext" COMP;
      +   size: 51 51 200 200;
      +   border: 0 0 0 0;
      +   border_scale_by: 0.0;
      +}
      +
      + +

      The image block inside a set block defines the characteristic of an image. Every block describes one image and the size rule to use it.

      + +

      For full documentation, see Image.

      + +
        +
      • image [image file] [compression method] (compression level) +

        This is included in each image file. The full path to the directory holding the images can be defined later with edje_cc's -id option. Available compression methods are:

        +
          +
        • RAW: Uncompressed
        • +
        • COMP: Lossless compression
        • +
        • LOSSY [0-100]: JPEG lossy compression with quality from 0 to 100
        • +
        • USER: Not embedded to the file, refer to the external file instead
        • +
        +
      • +
      • size [minw] [minh] [maxw] [maxh] +

        Defines the minimum and maximum size that selects the specified image.

        +
      • +
      • border [left] [right] [top] [bottom] +

        If set, the area (in pixels) of each side of the image is displayed as a fixed size border, from the side to inwards, preventing the corners from being changed on a resize.

        +
      • +
      • border_scale_by [value] +

        If border scaling is enabled then normally the OUTPUT border sizes (e.g. if 3 pixels on the left edge are set as a border, then normally at scale 1.0, those 3 columns are always the exact 3 columns of output, or at scale 2.0 they will be 6 columns, or 0.33 they will merge into a single column). This property multiplies the input scale factor by this multiplier, allowing the creation of supersampled borders to make much higher resolution outputs possible by always using the highest resolution artwork and then runtime scaling it down. Valid values are: 0.0 or bigger (0.0 or 1.0 to turn it off).

        +
      • +
      + +

      Fonts Block

      + +
      +fonts 
      +{
      +   font: "filename1.ext" "fontname";
      +   font: "filename2.ext" "otherfontname";
      +}
      +
      + +

      The fonts block is used to list each font file with an alias used later in the theme. As with the images block, additional fonts blocks can be included inside other blocks.

      + +
        +
      • font [font filename] [font alias] +

        Defines each font file and alias, the full path to the directory containing the font files can be defined with edje_cc's -fd option. +

      • +
      + +

      Data Block

      + +
      +data 
      +{
      +   item: "key" "value";
      +   file: "otherkey" "filename.ext";
      +}
      +
      + +

      This block behaves in the same way as the data block inside the parts, only the use-cases are different: this is useful for data that is for the whole theme, for instance license information, version, authors, and so on.

      + +

      Color_classes Block

      + +
      +color_classes 
      +{
      +   color_class 
      +   {
      +      name: "colorclassname";
      +      color: [0-255] [0-255] [0-255] [0-255];
      +      color2: [0-255] [0-255] [0-255] [0-255];
      +      color3: [0-255] [0-255] [0-255] [0-255];
      +   }
      +}
      +
      + +

      The color_classes block contains a list of one or more color_class blocks. Each color_class allows the designer to name an arbitrary group of colors to be used in the theme, the application can use that name to alter the color values at runtime.

      + +
        +
      • name [color class name] +

        Sets the name for the color class, used as reference by both the theme and the application.

        +
      • + +
      • color [red] [green] [blue] [alpha] +

        The main color.

        +
      • + +
      • color2 [red] [green] [blue] [alpha] +

        Used as outline in text and textblock parts.

        +
      • + +
      • color3 [red] [green] [blue] [alpha] +

        Used as shadow in text and textblock parts.

        +
      • +
      + +

      Styles Block

      + +
      +styles 
      +{
      +   style 
      +   {
      +      name: "stylename";
      +      base: "..default style properties..";
      +      tag: "tagname" "..style properties..";
      +   }
      +}
      +
      + +

      The styles block contains a list of one or more style blocks. A style block is used to create style <tags> for advanced TEXTBLOCK formatting.

      + +
        +
      • name [style name] +

        The name of the style to be used as reference later in the theme.

        +
      • + +
      • base [style properties string] +

        The default style properties that is applied to the complete text. The available tags that can be used in the style property are the following:

        +
          +
        • font
        • +
        • font_size + + + + + + + + + +
          Note
          The font size is a point size, and the size of the rendered text is affected by the ppi information. The system basic ppi is 96, and you can change it on the Emulator menu.
          + +
        • +
        • color
        • +
        • color_class
        • +
        • text_class
        • +
        • ellipsis
        • +
        • wrap
        • +
        • style
        • +
        • valign
        • +
        • align
        • + +
        + +
      • + +
      • tag [tag name] [style properties string] +

        Style to be applied only to text between style <tags>..</tags>. When creating paired tags, like <bold></bold>, a '+' sign must be added at the start of the style properties of the first part (<bold>). If the second part (</bold>) is also defined, a '-' sign must be added to its style properties. This applies only to paired tags; single tags, like <tab>, must not have a starting '+'.

        +
          +
        • br
        • +
        • tab
        • +
        • b
        • +
        • match
        • +
        + +
      • +
      + +

      The following code is the sample of a text style for the text style:

      + +
      +style 
      +{ 
      +   name: "list_text_main";
      +   base: "font=Tizen:style=Regular font_size=30 color=#ffffff ellipsis=1.0";
      +   tag: "br" "\n";\
      +   tag: "ps" "ps";\
      +   tag: "tab" "\t";\
      +   tag: "b" "+ font_weight=Bold";
      +}
      +
      + + + +

      Collections Block

      + +
      +collections 
      +{
      +   base_scale: 1.8;
      +   sounds 
      +   {
      +      tone: "tone-1" 2300;
      +      tone: "tone-2" 440;
      +      sample 
      +      {
      +         name: "sound_file1" RAW;
      +         source: "sound_file1.wav";
      +      }
      +   }
      +   group 
      +   {
      +      name: "groupname";
      +      alias: "anothername;"
      +      min: width height;
      +      max: width height;
      +      parts {}
      +      scripts {}
      +      limits {}
      +      data {}
      +      programs {}
      +   }
      +}
      +
      + +

      The collections block is used to list the groups that compose the theme. Additional collections blocks do not prevent overriding group names.

      + +

      The sounds block contains a list of one or more sound sample and tone items.

      + +

      Base Scale

      + +
        +
      • base_scale: [scale factor] +

        Information about the scale factor in the edc file.

        +
      • +
      + +

      Object scaling must be defined in the config.xml file of this application to show the application in a proper size in other devices. However, the scaling must be based on the scale 1.0 or, if the application is based on another scale, this scale must be defined in the config.xml file. This predefined scale is called the "base scale".

      + +

      The size of a scalable object is multiplied with the device scale value. If the scalable object with the size 10 is created in a device with the scale 1.0, the size of the object is 20 in a device with the scale 2.0, and 40 in a device with the scale 4.0.

      + +

      For more information about supporting multiple screens in one edc, see the Multiple Screen Support guide.

      + + +

      Sounds Block

      + +

      +
        +
      • tone [tone name] [frequency] +

        A sound of the given frequency.

        +
      • +
      + + +

      Sounds.sample Block

      + +

      The sample block defines the sound sample.

      + +

      +
        +
      • name [sample name] [compression type] (quality) +

        Used to include each sound file. The full path to the directory holding the sounds can be defined later with edje_cc's -sd option. Valid types are:

        +
          +
        • RAW: Uncompressed
        • +
        • COMP: Lossless compression
        • +
        • LOSSY [-0.1 - 1.0]: Lossy compression with quality from 0.0 to 1.0
        • +
        • AS_IS: No compression or encoding, write the file information as it is
        • +
        +
      • +
      + +

      +
        +
      • source [file name] +

        The sound source file name (source can be mono/stereo WAV file. Only files with 44.1 KHz sample rate are supported for now).

        +
      • +
      + + +

      Group Block

      + +
      +group 
      +{
      +   name: "nameusedbytheapplication";
      +   alias: "anothername";
      +   min: width height;
      +   max: width height;
      +   parts 
      +   {
      +      <definitions of parts>
      +   }
      +   script 
      +   {
      +      <embryo script>
      +   }
      +   limits 
      +   {
      +      vertical: "limit_name" height_barrier;
      +      horizontal: "limit_name" width_barrier;
      +   }
      +   data 
      +   {
      +      items: "key" "value";
      +      file: "key" "file";
      +   }
      +   programs {}
      +}
      +
      + +

      Group

      + +

      A group block contains the list of parts and programs that compose a given Edje Object.

      + +
        +
      • name [group name] +

        The name that is used by the application to load the resulting Edje object and to identify the group to swallow in a GROUP part. If a group with the same name exists already it will be completely overridden by the new group.

        +
      • + +
      • inherit_only [1 or 0] +

        This flags the group as being used only for inheriting, which will inhibit edje_cc resolving of programs and parts that may not exist in this group, but are located in the group which is inheriting this group.

        +
      • + +
      • inherit [parent group name] +

        Parent group name for inheritance. Group inherit is used to inherit any predefined group and change some property which belongs to part, description, items or program. The child group has the same properties as its parent group. If you specify the type again in an inherited part, it causes an error.

        + + + + + + + + + +
        Note
        When inheriting any parts, descriptions without state names are not allowed.
        +
      • + +
      • script_recursion [1/0] +

        This flag (1 or 0) determines whether to error on unsafe calls when recursively running Embryo programs. For example, running an Embryo script which calls EDC that has a script{} block is unsafe, and the outer-most (first) Embryo stack is corrupted. It is strongly unadvisable to use this flag.

      • + +
      • alias [additional group name] +

        Additional name to be used as an identifier. Defining multiple aliases is supported.

        +
      • + +
      • min [width] [height] +

        The minimum size for the container defined by the composition of the parts. It is not enforced.

        +
      • + +
      • max [width] [height] +

        The maximum size for the container defined by the totality of the parts. It is not enforced.

        +
      • + +
      • broadcast_signal [on/off] +

        Signal gets automatically broadcasted to all sub group parts. Default is "true".

        +
      • + +
      • orientation [AUTO/LTR/RTL] +

        This defines GROUP orientation. It is useful if you want match interface orientation with language.

        +
          +
        • AUTO: Follow system defaults
        • +
        • LTR: Used in Left To Right Languages (Latin)
        • +
        • RTL: Used in Right To Left Languages (Hebrew, Arabic interface)
        • +
        +
      • + +
      • mouse_events [1 or 0] +

        Changes the default value of mouse_events for every part in this group. Default is "1", to maintain compatibility.

        +
      • + +
      • program_source [source name] +

        Change the default value of source for every program in the current group which is declared after this value is set. Defaults to an unset value to maintain compatibility. The name of source can be set on every program, but if the name can be defined in the group level, it reduces the effort to indicate it in every program.

        +
      • +
      + +

      Group.parts

      + +
      +parts 
      +{
      +   part {}
      +   part {}
      +   part {}
      +}
      +
      + +

      The parts group contain one or more part. Each part describes a visual element and has a type: text, image, table, etc.

      + +

      For complete documentation, see the Part Block guide.

      + +

      Group.script

      + +
      +group 
      +{
      +   script 
      +   {
      +      <embryo script>
      +   }
      +   program 
      +   {
      +      script 
      +      {
      +         <embryo script>
      +      }
      +   }
      +}
      +
      + +

      This block is used to inject embryo scripts to a given Edje theme and it functions in two modalities. When it is included inside a program block, the script is executed every time the program is run, on the other hand, when included directly into a group, part, or description block, it is executed once at the load time, in the load order.

      + +

      For more information, see the Program guide.

      + +

      Group.limits

      + +
      +limits 
      +{
      +   vertical: "limit_name" height_barrier;
      +   horizontal: "limit_name" width_barrier;
      +}
      +
      + +

      This block is used to trigger signals when the Edje object is resized.

      +

      +
        +
      • vertical [name] [height barrier] +

        This sends a signal limit,name,over when the object is resized and passes the limit by growing over it. When the object's size is reduced below the limit, signal limit,name,below is sent. This limit is applied on the y axis and is given in pixels.

        +
      • +
      + +

      +
        +
      • horizontal [name] [width barrier] +

        This sends a signal limit,name,over when the object is resized and passes the limit by growing over it. When the object's size is reduced below the limit, signal limit,name,below is sent. This limit is applied on the x axis and is given in pixels.

        +
      • +
      + +

      Group.data

      + +
      +data 
      +{
      +   item: "key" "value";
      +   file: "key2" "somefile";
      +}
      +
      + +

      The data block is used to pass arbitrary parameters from the theme to the application. Unlike the images and fonts blocks, additional data blocks can only be included inside the group block.

      + +
        +
      • items: "key" "value"; +

        Defines a new parameter, the value is the string specified next to it.

        +
      • +
      • file: "key" "file"; +

        Defines a new parameter, the value is the contents of the specified file formatted as a single string of text. This property only works with plain text files.

        +
      • +
      + + + + + + + + + + +
      Note
      For genlist item styles, keys must be texts and icons, respectively for text parts and swallow parts; values must the names of the parts, separated with spaces.
      + +

      Group.programs

      + +
      +programs 
      +{
      +   program {}
      +   program {}
      +   program {}
      +}
      +
      + +

      The programs group contain one or more program.

      + +

      For more information about the program structure, see the Program guide.

      + + +

      Part Block

      + +
      +part 
      +{
      +   // inherit all the fields of another part
      +   inherit: "partname";
      +   // name the part
      +   name: "partname";
      +   // set the part type
      +   type: IMAGE;
      +   // enable mouse events on the part
      +   mouse_events: 0/1;
      +   // repeat mouse events to parts below the current one
      +   repeat_events: 0/1;
      +   ignore_flags: NONE;
      +   // whether the part sizes scale with the edje scaling factor
      +   scale: 0/1;
      +   // whether fully-transparent pixels are taken into account for collision detection
      +   precise_is_inside: 0/1;
      +   // only render the area of the part that coincides with the given part
      +   clip_to: "anotherpart";
      +   // for group/textblock parts: swallow the given group (for textblock: goes below text)
      +   source: "groupname";
      +   // same as source but goes on top of text
      +   source2: "groupname";
      +   // for textblock parts: swallow the given group below the mouse cursor when it hovers over the part
      +   source3: "groupname";
      +   // same as source3 but goes on top of the cursor
      +   source4: "groupname";
      +   // for textblock parts: swallow the given group below text anchors (<a>...</a>)
      +   source5: "groupname";
      +   // same as source5 but goes on to top of the anchor
      +   source6: "groupname";
      +   // add a shadow effect to the part
      +   effect: SOFT_SHADOW (BOTTOM_RIGHT);
      +   // for textblock parts: makes the text editable, possibly with a specific behavior
      +   entry_mode: PASSWORD;
      +   // for textblock parts: change how the tex selection is triggered
      +   select_mode: EXPLICIT;
      +   // for editable textblock parts: where to draw the (blinking) cursor
      +   cursor_mode: UNDER;
      +   // for editable textblock parts: allow multiple lines
      +   multiline: 0/1;
      +   // for textblock parts: accessibility features will be used
      +   access: 0/1;
      +   // no-one uses that
      +   pointer_mode: AUTOGRAB;
      +   use_alternate_font_metrics: 0/1;
      +   // remove the given program; useful when it was inherited
      +   program_remove: "programname";
      +   // remove the given part; useful when it was inherited
      +   part_remove: "partname";
      +   // insert the current part below the given part, as if it were declared before
      +   insert_before: "partname";
      +   // insert the current part above the given part, as if it were declared after
      +   insert_after: "partname";
      +   // define a new part inside this one
      +   part 
      +   {
      +      <part definition>
      +   }
      +   draggable 
      +   {
      +      // confine the current part to the given part
      +      confine: "another part";
      +      // only start drag when it would have moved enough to be outside of the given part
      +      threshold: "another part";
      +      // forward drag events to the given part instead of handling them
      +      events: "another draggable part";
      +      // enable horizontal drag of the part with steps each step_size or with steps_count steps
      +      x: 0/1 <step_size> <steps_count>;
      +      // same as x but vertical
      +      y: 1 0 100;
      +   }
      +   // for box or table parts
      +   box/table 
      +   {
      +      // list of items
      +      items 
      +      {
      +         item 
      +         {
      +            // define item type, can only be GROUP
      +            type: GROUP;
      +            // name the item
      +            name: "name";
      +            // set the source for this item, i.e. its contents
      +            source: "groupname";
      +            // minimum horizontal and vertical item sizes (-1 for expand)
      +            min: -1 -1;
      +            // maximum horizontal and vertical item sizes (-1 for ignore)
      +            max: 100 100;
      +            // set the item padding in pixels
      +            padding: 2 2 2 2;
      +            spread: 1 1;
      +            // set the item alignment
      +            align: 0.5 0.5;
      +            // set a weight hint in the box for the given object
      +            weight: 1 1;
      +            // set the aspect ratio hint
      +            aspect: 1 1;
      +            aspect_mode: BOTH;
      +            // number of columns and rows the item will take
      +            span: 1 1;
      +         }
      +      }
      +   }
      +   description 
      +   {
      +      // inherit another description
      +      inherit: "default" 1.0;
      +      // name the current description
      +      state: "default" 1.0;
      +      // use another part as content of the current "PROXY" part (This description only works in the PROXY part and the current part mirrors the rendering content of the source part)
      +      source: "partname";
      +      // make the part (in)visible (invisible parts emit no signals)
      +      visible: 0/1;
      +      // emit a signal when the given dimension becomes zero or stops being zero
      +      limit: WIDTH;
      +      // horizontal and vertical alignment of the part inside its parent
      +      align: 0.5 0.5;
      +      // set that the part does not change size
      +      fixed: 0/1 0/1;
      +      // set the minimum size for the part
      +      min: 200 200;
      +      // forcibly multiply the minimum sizes by the given factors
      +      minmul: 1.2 1.2;
      +      // set the maximum size for the part
      +      max: 400 400;
      +      // make vertical and horizontal resizes happen in steps
      +      step: 0 0;
      +      // force aspect ratio to be kept between min and max between resizes
      +      aspect: 0.8 1.2;
      +      // the dimension to which the aspect ratio applies
      +      aspect_preference: BOTH;
      +      // use the given color class which can be used to factor font colors
      +      color_class: "colorclassname";
      +      // set the text color
      +      color: 255 0 0 255;
      +      // set the color of the text's shadow
      +      color2: 0 255 0 255;
      +      // set the color of the text's outline
      +      color3: 0 0 255 255;
      +      // define the positions of the top-left (rel1) and bottom-right (rel2) corners
      +      rel1/rel2 
      +      {
      +         // make relative and offset use the given part for their positioning
      +         to: "partname";
      +         // position the corner relative to the part given through to (0.0 being axis beginning, 1.0 being its end)
      +         relative: 0.1 0.1;
      +         // add an absolute offset (in pixels) along each axis
      +         offset: 10 10;
      +         // same as to but only for the x axis
      +         to_x: "partname";
      +         // same as to but only for the y axis
      +         to_y: "partname";
      +      }
      +      // settings specific to parts of type image
      +      image 
      +      {
      +         // name (not path) of the regular image
      +         normal: "imagename";
      +         // image to use while transitioning to the normal image; use several times to create animations
      +         tween: "imagename2";
      +         // set the number of pixels that make up each border of the image, i.e. are not resized when the image is
      +         border: 4 4 4 4;
      +         // hide, strip from its alpha or show (default) the non-border part of the image
      +         middle: DEFAULT;
      +         border_scale_by: 1.0;
      +         // whether to scale the border or not
      +         border_scale: 0/1;
      +         scale_hint: STATIC;
      +         // set how the image is going to fill its part
      +         fill: 
      +         {
      +            // whether to smooth the image when scaling it
      +            smooth: 0/1;
      +            spread: ??;
      +            // whether to scale or tile to fit when resizing the image is needed
      +            type: SCALE/TILE;
      +            // only display the part of the image that is below and to the right of the given point
      +            origin 
      +            {
      +               // specify top-left point as relative coordinates
      +               relative: 0.1 0.1;
      +               // specify top-left point as a pixel offset
      +               offset: 10 10;
      +            }
      +            // specify bottom-right point as relative coordinates
      +            size 
      +            {
      +               relative: 0.1 0.1;
      +               // specify bottom-right point as a pixel offset
      +               offset: 10 10;
      +            }
      +         }
      +      }
      +      // settings specific to parts of type text and textblock
      +      text 
      +      {
      +         // set the part's text
      +         text: "some text";
      +         // set the text's font
      +         font: "Tizen Sans";
      +         // set the text's size
      +         size: 14;
      +         // set the text's class which can be used to factor font and font-size settings
      +         text_class: "classname";
      +         // use the styles defined in stylename
      +         style: "stylename";
      +         // for textblocks in password mode, replace characters to hide with this string
      +         repch: "*";
      +         // set the min and max font sizes allowed when resizing (default is 0 0, i.e. unrestricted)
      +         size_range: 6 18;
      +         // increase font size as much as possible while still remaining in the container for both axis
      +         fit: 0/1 0/1;
      +         // make the min size of the container equal to the min size of the current text (0 0 by default)
      +         min: 0/1 0/1;
      +         // make the max size of the container equal to the max size of the current text (0 0 by default)
      +         max: 0/1 0/1;
      +         // set the vertical and horizontal alignments of the text
      +         align: 0.5 0.5;
      +         // re-use the text of another part
      +         text_source: "partname";
      +         // when text is too long to fit, relative position at which to cut the text and put an ellipsis ("...")
      +         ellipsis: 0.9;
      +      }
      +      // settings specific to parts of type box
      +      box 
      +      {
      +         // set how children while be arranged in the box
      +         layout: horizontal_homogeneous;
      +         // set the vertical and horizontal alignments of box
      +         align: 0.5 0.5;
      +         // set the padding between items of the box
      +         padding: 1 1;
      +         // make the box' min size be the min size of its elements (i.e. make it shrinkable as much as its items)
      +         min: 0 1;
      +      }
      +      table 
      +      {
      +         // make items homogeneous
      +         homogeneous: NONE;
      +         // set the vertical and horizontal alignments of box
      +         align: 0.5 0.5;
      +         // set the padding between items of the box
      +         padding: 1 1;
      +         // make the table's min size be the min size of its elements (i.e. make it shrinkable as much as its items)
      +         min: 0 1;
      +      }
      +      map 
      +      {
      +         perspective: "partname";
      +         light: "partname";
      +         on: 0/1;
      +         smooth: 0/1;
      +         alpha: 0/1;
      +         backface_cull: 0/1;
      +         perspective_on: 0/1;
      +         color: 0/1;
      +         rotation 
      +         {
      +            center: "partname";
      +            x: 45;
      +            y: 120;
      +            z: 90;
      +         }
      +         perspective 
      +         {
      +            zplane: 0/1;
      +            focal: 20;
      +         }
      +         // simpler syntax to create transitions to the current part
      +         link 
      +         {
      +            base: "edje,signal" "edje";
      +         }
      +      }
      +   }
      +}
      +
      + +

      Part

      + +
      +part 
      +{
      +   name: "partname";
      +   type: IMAGE;
      +   mouse_events:  1;
      +   repeat_events: 0;
      +   ignore_flags: NONE;
      +   clip_to: "anotherpart";
      +   source:  "groupname";
      +   pointer_mode: AUTOGRAB;
      +   use_alternate_font_metrics: 0;
      +
      +   dragable {}
      +   items {}
      +   description {}
      +}
      +
      + +

      Parts are used to represent the most basic design elements of the theme, for example, a part can represent a line in a border or a label on a button.

      + +
        +
      • inherit [part name] +

        Copies all attributes except part name from referenced part into current part. All existing attributes, except part name, are overwritten.

        + + + + + + + + + +
        Note
        When inheriting any parts, descriptions without state names are not allowed.
        +
      • + +
      • program_remove [program name] (program name) (program name) ... +

        Removes the listed programs from an inherited group. Removing non-existing programs is not allowed.

        + + + + + + + + + +
        Note
        This breaks program sequences if a program in the middle of the sequence is removed.
        +
      • + +
      • part_remove [part name] (part name) (part name) ... +

        Removes the listed parts from an inherited group. Removing non-existing parts is not allowed.

        +
      • + +
      • name [part name] +

        The part's name is used as reference in the theme's relative positioning system, by programs and in some cases by the application. It must be unique within the group.

        +
      • + +
      • type [TYPE] +

        Sets the type. This is set to IMAGE by default. Valid types are:

        +
          +
        • RECT: Rectangle object in the screen
        • +
        • TEXT: Simple text
        • +
        • IMAGE: Image area
        • +
        • SWALLOW: Area where you can add the object
        • +
        • TEXTBLOCK: Complex text with multiple lines, mark-up elements, and such.
        • +
        • GROUP: Part which can include other groups in the same group.
        • +
        • BOX: Container object as a container. It has a row or column.
        • +
        • TABLE: Container object as a container. It has a row and column.
        • +
        • PROXY: Clone of another part in the same group. It shares the memory of the source part.
        • + +
        • SPACER: Rectangle object, but invisible. Recommended to padding because it does not allocate any memory.
        • + +
        +
      • + +
      • part [part declaration] +

        Nested parts adds hierarchy to Edje. Nested part inherits its location relatively to the parent part. To declare a nested part create a new part within current part declaration. Define parent part name before adding nested parts.

        +
        +part 
        +{
        +   name: "parent_rect";
        +   type: RECT;
        +   description {}
        +   part 
        +   {
        +      name: "nested_rect";
        +      type: RECT;
        +      description {}
        +   }
        +}
        +
        +
      • + +
      • insert_before [another part's name] +

        The part's name which this part is inserted before. One part cannot have both insert_before and insert_after. One part cannot refer more than one by insert_before.

        +
      • + +
      • insert_after [another part's name] +

        The part's name which this part is inserted after. One part cannot have both insert_before and insert_after. One part cannot refer more than one by insert_after.

        +
      • + +
      • mouse_events [1 or 0] +

        Specifies whether the part emits signals, although it is named mouse_events. Disabling it (0) prevents the part from emitting signal. It is set to 1 by default, or to the value set to mouse_events at the group level, if any.

        +
      • + +
      • repeat_events [1 or 0] +

        Specifies whether a part echoes a mouse event to other parts below the pointer (1), or not (0). It is set to 0 by default.

        +
      • + +
      • ignore_flags [FLAG] ... +

        Specifies whether events with the given flags are ignored, i.e., do not emit signals to the parts. Multiple flags must be separated by spaces, the effect is ignoring all events with one of the flags specified. Possible flags are:

        +
          +
        • NONE: Event is handled properly (default value)
        • +
        • ON_HOLD: Event is not handled or passed in this part
        • + +
        +
      • + +
      • scale [1 or 0] +

        Specifies whether the part scales its size with an Edje scaling factor. By default scale is off (0) and the default scale factor is 1.0 which means no scaling. This is used to scale properties such as font size, min/max size of the part, and it can also be used to scale based on DPI of the target device. The reason to be selective is that some parts are scaled well, others are not, so choose what works best.

        +
      • + +
      • pointer_mode [MODE] +

        Sets the mouse pointer behavior for a given part. The default value is AUTOGRAB. Available modes are:

        +
          +
        • AUTOGRAB, when the part is clicked and the button remains pressed, the part is the source of all future mouse signals emitted, even outside the object, until the button is released.
        • +
        • NOGRAB, the effect is limited to the part's container.
        • +
        +
      • + +
      • precise_is_inside [1 or 0] +

        Enables precise point collision detection for the part, which is more resource-intensive. It is disabled by default.

        +
      • + +
      • use_alternate_font_metrics [1 or 0] +

        Only affects text and textblock parts, when enabled Edje uses different size measurement functions. It is disabled by default.

        +
      • + +
      • clip_to [another part's name] +

        Only renders the area of part that coincides with another part's container. Overflowing content is not displayed. Note that the part being clipped to can only be a rectangle part.

        +
      • + +
      • source [another group's name] +

        Only available to GROUP or TEXTBLOCK parts. Swallows the specified group into the part's container if it is a GROUP. If TEXTBLOCK it is used for the group to be loaded and used for selection display UNDER the selected text. source2 is used for on top of the selected text, if source2 is specified.

        +
      • + +
      • source2 [another group's name] +

        Only available to TEXTBLOCK parts. It is used for the group to be loaded and used for selection display OVER the selected text. source is used for under of the selected text, if source is specified.

        +
      • + +
      • source3 [another group's name] +

        Only available to TEXTBLOCK parts. It is used for the group to be loaded and used for cursor display UNDER the cursor position. source4 is used for over the cursor text, if source4 is specified.

        +
      • + +
      • source4 [another group's name] +

        Only available to TEXTBLOCK parts. It is used for the group to be loaded and used for cursor display OVER the cursor position. source3 is used for under the cursor text, if source4 is specified.

        +
      • + +
      • source5 [another group's name] +

        Only available to TEXTBLOCK parts. It is used for the group to be loaded and used for anchors display UNDER the anchor position. source6 is used for over the anchors text, if source6 is specified.

        +
      • + +
      • source6 [another group's name] +

        Only available to TEXTBLOCK parts. It is used for the group to be loaded and used for anchor display OVER the anchor position. source5 is used for under the anchor text, if source6 is specified.

        +
      • + +
      • effect [effect] (shadow direction) +

        Apply the selected outline, shadow, or glow effect to "textblock" (take care that this effect only works for the textblock). The available effects are:

        +
          +
        • PLAIN
        • +
        • OUTLINE
        • +
        • SOFT_OUTLINE
        • +
        • SHADOW
        • +
        • SOFT_SHADOW
        • +
        • OUTLINE_SHADOW
        • +
        • OUTLINE_SOFT_SHADOW
        • +
        • FAR_SHADOW
        • +
        • FAR_SOFT_SHADOW
        • +
        • GLOW
        • +
        + +

        The available shadow directions definitions are (default is BOTTOM_RIGHT):

        +
          +
        • BOTTOM_RIGHT
        • +
        • BOTTOM
        • +
        • BOTTOM_LEFT
        • +
        • LEFT
        • +
        • TOP_LEFT
        • +
        • TOP
        • +
        • TOP_RIGHT
        • +
        • RIGHT
        • +
        +
      • + +
      • entry_mode [mode] +

        Sets the edit mode for a textblock part. The available modes are:

        +
          +
        • NONE: +

          The textblock is non-editable.

        • +
        • PLAIN: +

          The textblock is non-editable, but selectable.

        • +
        • EDITABLE: +

          The textblock is editable.

        • +
        • PASSWORD: +

          The textblock is editable if the Edje object has the keyboard focus and the part has the Edje focus (or selectable always regardless of focus). In the event of password mode, not selectable and all text chars replaced with *'s but editable and pastable.

        • +
        +
      • + +
      • select_mode [mode] +

        Sets the selection mode for a textblock part. The available modes are:

        +
          +
        • DEFAULT, selection mode is what you would expect on any desktop. Press mouse, drag and release to end.
        • +
        • EXPLICIT, this mode requires the application controlling the Edje object has to explicitly begin and end selection modes, and the selection itself is draggable at both ends.
        • +
        +
      • + +
      • cursor_mode [mode] +

        Sets the cursor mode for a textblock part. The available modes are:

        +
          +
        • UNDER, the cursor draws below the character pointed at. That is the default.
        • +
        • BEFORE, the cursor is drawn as a vertical line before the current character, just like many other GUI toolkits handle it.
        • +
        +
      • + +
      • multiline [1 or 0] +

        It causes a textblock that is editable to allow multiple lines for editing.

        +
      • + +
      • access [1 or 0] +

        Specifies whether the part uses accessibility feature (1), or not (0). It is set to 0 by default.

        +
      • +
      + +

      Draggable

      + +
      +dragable 
      +{
      +   confine: "another part";
      +   threshold: "another part";
      +   events:  "another draggable part";
      +   x: 0 0 0;
      +   y: 0 0 0;
      +}
      +
      + +

      When this block is used the part can be dragged around the interface, do not confuse with external drag and drop. By default Edje (and most applications) attempts to use the minimal size possible for a draggable part. If the min property is not set in the description the part is (most likely) set to 0px width and 0px height, thus invisible.

      + +
        + +
      • x [enable/disable] [step] [count] +

        Used to set up dragging events for the X axis. The first parameter is used to enable (1 or -1) and disable (0) dragging along the axis. When enabled, 1 sets the starting point at 0.0 and -1 at 1.0. The second parameter takes any integer and limits movement to values divisible by it, causing the part to jump from position to position. If step is set to 0 it is calculated as width of confine part divided by count.

        +
      • + +
      • y [enable/disable] [step] [count] +

        Used to set up dragging events for the Y axis. The first parameter is used to enable (1 or -1) and disable (0) dragging along the axis. When enabled, 1 sets the starting point at 0.0 and -1 at 1.0. The second parameter takes any integer and limits movement to values divisible by it, causing the part to jump from position to position. If step is set to 0 it is calculated as height of confine part divided by count.

        +
      • + +
      • confine [another part's name] +

        Limits the movement of the dragged part to another part's container. Set a min size for the part, or the dragged object will not show up.

        +
      • + +
      • threshold [another part's name] +

        When set, the movement of the dragged part can only start when it get moved enough to be outside of the threshold part.

        +
      • + +
      • events [another draggable part's name] +

        Causes the part to forward the drag events to another part, thus ignoring them for itself.

        +
      • + +
      + +

      Box/table

      + +

      Items

      + +
      +box/table 
      +{
      +   items 
      +   {
      +      item 
      +      {
      +         type: GROUP;
      +         source: "some source";
      +         min: -1 -1;
      +         max: 100 100;
      +         padding: 1 1 2 2;
      +      }
      +      item 
      +      {
      +         type: GROUP;
      +         source: "some other source";
      +         name: "some name";
      +         align: 1.0 0.5;
      +      }
      +   }
      +}
      +
      + +

      On a BOX part, this block is used to set other groups as elements of the box. These can be mixed with external objects set by the application through the edje_object_part_box*() functions.

      + +
      Item
      + +
        + +
      • type [item type] +

        Sets the type of the object this item holds. The supported type is:

        +
          +
        • GROUP (default)
        • +
        +
      • + +
      • name [name for the object] +

        Sets the name of the object via evas_object_name_set().

        +
      • + +
      • source [another group's name] +

        Sets the group this object is made of.

        +
      • + +
      • min [width] [height] +

        Sets the minimum size hints for this object.

        + + + + + + + + + +
        Note
        Must be -1 to get expand behavior.
        +
      • + +
      • spread [width] [height] +

        Replicates the item in a rectangle of size width x height box starting from the defined position of this item. The default value is 1 1;.

        +
      • + +
      • prefer [width] [height] +

        Sets the preferred size hints for this object.

        +
      • + +
      • max [width] [height] +

        Sets the maximum size hints for this object.

        +
      • + +
      • padding [left] [right] [top] [bottom] +

        Sets the padding hints for this object.

        +
      • + +
      • align [x] [y] +

        Sets the alignment hints for this object.

        +
      • + +
      • weight [x] [y] +

        Sets the weight hints for this object.

        +
      • + +
      • aspect [w] [h] +

        Sets the aspect width and height hints for this object.

        +
      • + +
      • aspect_mode [mode] +

        Sets the aspect control hints for this object. The available hints are:

        +
          +
        • NONE
        • +
        • NEITHER
        • +
        • HORIZONTAL
        • +
        • VERTICAL
        • +
        • BOTH
        • +
        +
      • + +
      • options [extra options] +

        Sets extra options for the object.

        +
      • + +
      • position [col] [row] +

        Sets the position this item has in the table. This is required for parts of type TABLE.

        +
      • + +
      • span [col] [row] +

        Sets how many columns and rows this item uses. The default value is 1 1.

        +
      • + +
      + +

      Description

      + +
      +description 
      +{
      +   inherit: "another_description" INDEX;
      +   state: "description_name" INDEX;
      +   visible: 1;
      +   min: 0 0;
      +   max: -1 -1;
      +   align: 0.5 0.5;
      +   fixed: 0 0;
      +   step: 0 0;
      +   aspect: 1 1;
      +
      +   rel1 
      +   {
      +      ...
      +   }
      +
      +   rel2 
      +   {
      +      ...
      +   }
      +}
      +
      + +

      Every part can have one or more description blocks. Each description is used to define style and layout properties of a part in a given "state".

      + +
        + +
      • inherit [another description's name] [another description's index] +

        Thee description inherits all the properties from the named description. The properties defined in this part override the inherited properties, reducing the amount of necessary code for simple state changes. Note: inheritance in Edje is single level only.

        +
      • + +
      • source [another part's name] +

        Causes the part to use another part's content as the content of this part. This works only with PROXY part.

        +
      • + +
      • state [name for the description] [index] +

        Sets a name used to identify a description inside a given part. Multiple descriptions are used to declare different states of the same part, like "clicked" or "invisible". All state declarations are also coupled with an index number between 0.0 and 1.0. All parts must have at least one description named "default 0.0".

        +
      • + +
      • visible [0 or 1] +

        Takes a Boolean value specifying whether part is visible (1) or not (0). Non-visible parts do not emit signals. The default value is 1.

        +
      • + +
      • limit [mode] +

        Emits a signal when the part size changes from zero or to a zero (limit,width,over, limit,width,zero). By default no signal are emitted. Valid values are:

        +
          +
        • NONE
        • +
        • WIDTH
        • +
        • HEIGHT
        • +
        • BOTH
        • +
        +
      • + +
      • align [X axis] [Y axis] +

        When the displayed object's size is smaller or bigger than its container, this property moves it relatively along both axis inside its container. "0.0" means left/top edges of the object touching container's respective ones, and "1.0" stands for right/bottom edges of the object (on horizontal/vertical axis, respectively). The default value is "0.5 0.5". For a more detailed explanation, see the Align Size Hint.

        +
      • + +
      • fixed [width, 0 or 1] [height, 0 or 1] +

        Sets the minimum size calculation. See edje_object_size_min_calc() and edje_object_size_min_restricted_calc(). This tells the min size calculation routine that this part does not change size in width or height (1 for it does not, 0 for it does), so the routine does not try to expand or contract the part.

        +
      • + +
      • min [width] [height] or SOURCE +

        Sets the minimum size of the state. When min is defined to SOURCE, it looks at the original image size and enforces its minimal size to match at least the original one. The part must be an IMAGE or a GROUP part.

        +
      • + +
      • minmul [width multiplier] [height multiplier] +

        A multiplier forcibly applied to whatever minimum size is only during minimum size calculation.

        +
      • + +
      • max [width] [height] or SOURCE +

        The maximum size of the state. A size of -1.0 means that it is ignored in one direction. When max is set to SOURCE, Edje enforces the part to be not more than the original image size. The part must be an IMAGE part.

        +
      • + +
      • step [width] [height] +

        Restricts resizing of each dimension to values divisible by its value. This causes the part to jump from value to value while resizing. The default value is "0 0" which disables stepping.

        +
      • + +
      • aspect [min] [max] +

        Normally width and height can be resized to any values independently. The aspect property forces the width to height ratio to be kept between the minimum and maximum set. For example, "1.0 1.0" increases the width a pixel for every pixel added to height. The default value is "0.0 0.0" which disables aspect. For a more detailed explanation, see the Min Size Hint .

        +
      • + +
      • aspect_preference [DIMENSION] +

        Set the dimensions to which the "aspect" property applies. Available options are:

        +
          +
        • BOTH
        • +
        • VERTICAL
        • +
        • HORIZONTAL
        • +
        • SOURCE
        • +
        • NONE
        • +
        +

        For a more detailed explanation, see Min Size Hint.

        +
      • + +
      • color_class [color class name] +

        The part uses the color values of the named color_class, these values can be overridden by the "color", "color2" and "color3" properties.

        +
      • + +
      • color [red] [green] [blue] [alpha] +

        Sets the main color to the specified values (between 0 and 255).

        + + + + + + + + + +
        Note
        The textblock part is not affected by the color description. Set the color in the text style.
        + +
      • + +
      • color2 [red] [green] [blue] [alpha] +

        Sets the text shadow color to the specified values (0 to 255).

        +
      • + +
      • color3 [red] [green] [blue] [alpha] +

        Sets the text outline color to the specified values (0 to 255).

        +
      • + +
      + +

      Rel1/rel2

      +
      +description 
      +{
      +   rel1 
      +   {
      +      relative: 0.0 0.0;
      +      offset:     0   0;
      +   }
      +   rel2 
      +   {
      +      relative: 1.0 1.0;
      +      offset:    -1  -1;
      +   }
      +}
      +
      + +

      The rel1 and rel2 blocks are used to define the position of each corner of the part's container. With rel1 being the left-up corner and rel2 being the right-down corner.

      + +
        + +
      • relative [X axis] [Y axis] +

        Moves the corner to a relative position inside the container of the relative "to" part. Values from 0.0 (0%, beginning) to 1.0 (100%, end) of each axis.

        +
      • + +
      • offset [X axis] [Y axis] +

        Affects the corner position a fixed number of pixels along each axis.

        +
      • + +
      • to [another part's name] +

        Positions the corner relatively to another part's container. Setting to "" resets this value for inherited parts.

        +
      • + +
      • to_x [another part's name] +

        Positions the corner relatively to the X axis of another part's container. This affects the first parameter of "relative". Setting to "" resets this value for inherited parts.

        +
      • + +
      • to_y [another part's name] +

        Positions the corner relatively to the Y axis of another part's container. This affects the second parameter of "relative". Setting to "" resets this value for inherited parts.

        +
      • + +
      + +

      Image

      + +
      +description 
      +{
      +   image 
      +   {
      +      normal: "filename.ext";
      +      tween:  "filename2.ext";
      +      tween:  "filenameN.ext";
      +      border:  left right top bottom;
      +      middle:  0/1/NONE/DEFAULT/SOLID;
      +      fill {}
      +   }
      +}
      +
      + +
        + +
      • normal [image's filename] +

        Name of image to be used as previously declared in the images block. In an animation, this is the first and last image displayed. It is required in any image part

        +
      • + +
      • tween [image's filename] +

        Name of an image to be used in an animation loop, an image block can have none, one or multiple tween declarations. Images are displayed in the order they are listed, during the transition to the state they are declared in; the "normal" image is the final state.

        +
      • + +
      • border [left] [right] [top] [bottom] +

        Sets the area (in pixels) of each side of the image is displayed as a fixed size border, from the side -> inwards, preventing the corners from being changed on a resize.

        +
      • + +
      • middle [mode] +

        If border is set, this value tells Edje if the rest of the image (not covered by the defined border) displayed or not or be assumed to be solid (without alpha). The default value is 1/DEFAULT. The available values are:

        +
          +
        • 0 or NONE
        • +
        • 1 or DEFAULT
        • +
        • SOLID (strip alpha from the image over the middle zone)
        • +
        +
      • + +
      • border_scale_by [value] +

        If border scaling is enabled then normally the OUTPUT border sizes (e.g. if 3 pixels on the left edge are set as a border, then normally at scale 1.0, those 3 columns are always exactly 3 columns of output, or at scale 2.0 they are 6 columns, or 0.33 they merge into a single column). This property multiplies the input scale factor by this multiplier, allowing the creation of supersampled borders to make higher resolution outputs possible by always using the highest resolution artwork and then runtime scaling it down. Value can be: 0.0 or bigger (0.0 or 1.0 to turn it off)

        +
      • + +
      • border_scale [0/1] +

        Tells Edje if the border is scaled by the object/global Edje scale factors.

        +
      • + +
      • scale_hint [mode] +

        Sets the evas image scale hint letting the engine more effectively save cached copies of the scaled image if it makes sense. Valid values are:

        +
          +
        • 0 or NONE
        • +
        • DYNAMIC
        • +
        • STATIC
        • +
        +
      • + +
      + +
      Image.fill
      + +
      +image 
      +{
      +   fill 
      +   {
      +      type: SCALE;
      +      smooth: 0-1;
      +      origin {}
      +      size {}
      +   }
      +}
      +
      + +

      The fill method is an optional block that defines the way an IMAGE part is going to be displayed inside its container. It can be used for tiling (repeating the image) or displaying only part of an image. See evas_object_image_fill_set() documentation for more details.

      + +
        + +
      • smooth [0 or 1] +

        The smooth property takes a boolean value to decide if the image will be smoothed on scaling (1) or not (0). The default value is 1.

        +
      • + +
      • spread +
      • + +
      • type [fill type] +

        Sets the image fill type. The part parameter "min" must be set, it is size of tiled image. If parameter "max" set tiled area has the size accordingly "max" values. SCALE is default type. Valid values are:

        +
          +
        • SCALE, image is scaled accordingly the value of the parameters "relative" and "offset" from "origin" and "size" blocks.
        • +
        • TILE, image is tiled accordingly parameters value "relative" and "offset" from "origin" and "size" blocks.
        • +
        +
      • + +
      + +
      Image.fill.origin
      + +
      +image 
      +{
      +   fill 
      +   {
      +      origin 
      +      {
      +         relative: 0.0 0.0;
      +         offset: 0 0;
      +      }
      +   }
      +}
      +
      + +

      The origin block is used to place the starting point, inside the displayed element, that is used to render the tile. By default, the origin is set at the element's left-up corner.

      + +
        + +
      • relative [X axis] [Y axis] +

        Sets the starting point relatively to displayed element's content.

        +
      • +
      • offset [X axis] [Y axis] +

        Affects the starting point a fixed number of pixels along each axis.

        +
      • + +
      + +
      Image.fill.size
      + +
      +image 
      +{
      +   fill 
      +   {
      +      size 
      +      {
      +         relative: 1.0 1.0;
      +         offset: -1 -1;
      +      }
      +   }
      +}
      +
      + +

      The size block defines the tile size of the content that are displayed.

      + +
        + +
      • relative [width] [height] +

        Takes a pair of decimal values that represent the percentage of the original size of the element. For example, "0.5 0.5" represents half the size, while "2.0 2.0" represents the double. The default value is "1.0 1.0".

        +
      • +
      • offset [X axis] [Y axis] +

        Affects the size of the tile a fixed number of pixels along each axis.

        +
      • + +
      + +

      Text

      + +
      +text 
      +{
      +   text: "some string of text to display";
      +   font: "font_name";
      +   size: SIZE;
      +   text_class: "class_name";
      +   fit: horizontal vertical;
      +   min: horizontal vertical;
      +   max: horizontal vertical;
      +   align: X-axis Y-axis;
      +   source: "part_name";
      +   text_source: "text_part_name";
      +   style: "stylename";
      +}
      +
      + + +
        + +
      • text [a string of text, or nothing] +

        Sets the default content of a text part, normally the application is the one changing its value.

        +
      • + +
      • text_class [text class name] +

        Similar to color_class, this is the name used by the application to alter the font family and size at runtime.

        +
      • + +
      • font [font alias] +

        This sets the font family to one of the aliases set up in the "fonts" block. Can be overridden by the application.

        +
      • + +
      • style [the style name] +

        Causes the part to use the default style and tags defined in the "style" block with the specified name.

        +
      • + +
      • repch [the replacement character string] +

        If this is a textblock and is in PASSWORD mode this string is used to replace every character to hide the details of the entry. Normally * is used, but you can use anything you like.

        +
      • + +
      • size [font size in points (pt)] +

        Sets the default font size for the text part. Can be overridden by the application.

        +
      • + +
      • size_range [font min size in points (pt)] [font max size in points (pt)] +

        Sets the allowed font size for the text part. Setting min and max to 0 means that sizing is not restricted. This is also the default value.

        +
      • + +
      • fit [horizontal] [vertical] +

        When any of the parameters is set to 1 Edje resizes the text for it to fit in its container. Both are disabled by default.

        +
      • + +
      • min [horizontal] [vertical] +

        When any of the parameters is enabled (1) it forces the minimum size of the container to be equal to the minimum size of the text. The default value is "0 0".

        +
      • + +
      • max [horizontal] [vertical] +

        When any of the parameters is enabled (1) it forces the maximum size of the container to be equal to the maximum size of the text. The default value is "0 0".

        +
      • + +
      • align [horizontal] [vertical] +

        Changes the position of the point of balance inside the container. The default value is 0.5 0.5.

        +
      • + +
      • source [another TEXT part's name] +

        Causes the part to use the text properties (like font and size) of another part and update them as they change.

        +
      • + +
      • text_source [another TEXT part's name] +

        Causes the part to display the text content of another part and update them as they change.

        +
      • + +
      • ellipsis [point of balance] +

        Balances the text in a relative point from 0.0 to 1.0, this point is the last section of the string to be cut out in case of a resize that is smaller than the text itself. The default value is 0.0.

        +
      • + +
      + + +

      Box

      + +
      +box 
      +{
      +   layout: "vertical";
      +   padding: 0 2;
      +   align: 0.5 0.5;
      +   min: 0 0;
      +}
      +
      + +

      A box block can contain other objects and display them in different layouts, any of the predefined set, or a custom one, set by the application.

      + +
        + +
      • layout [primary layout] (fallback layout) +

        Sets the layout for the box:

        +
          +
        • horizontal (default)
        • +
        • vertical
        • +
        • horizontal_homogeneous
        • +
        • vertical_homogeneous
        • +
        • horizontal_max (homogeneous to the max sized child)
        • +
        • vertical_max
        • +
        • horizontal_flow
        • +
        • vertical_flow
        • +
        • stack
        • +
        • some_other_custom_layout_set_by_the_application +

          Set a custom layout as a fallback. For more information, see edje_box_layout_register(). If an unregistered layout is used, it defaults to horizontal.

        • + +
        +
      • + +
      • align [horizontal] [vertical] +

        Changes the position of the point of balance inside the container. The default value is 0.5 0.5.

        +
      • + +
      • padding [horizontal] [vertical] +

        Sets the space between cells in pixels. The default value is 0 0.

        +
      • + +
      • min [horizontal] [vertical] +

        When any of the parameters is enabled (1) it forces the minimum size of the box to be equal to the minimum size of the items. The default value is 0 0.

        +
      • + +
      + +

      Table

      + +
      +table 
      +{
      +   homogeneous: TABLE;
      +   padding: 0 2;
      +   align: 0.5 0.5;
      +   min: 0 0;
      +}
      +
      + +

      A table block can contain other objects packed in multiple columns and rows, and each item can span across more than one column and/or row.

      + +
        + +
      • homogeneous [homogeneous mode] +

        Sets the homogeneous mode for the table:

        +
          +
        • NONE: default
        • +
        • TABLE: available space is evenly divided between children (which overflows onto other children if too little space is available)
        • +
        • ITEM: size of each item is the largest minimal size of all the items
        • +
        +
      • + +
      • align [horizontal] [vertical] +

        Changes the position of the point of balance inside the container. The default value is 0.5 0.5.

        +
      • + +
      • padding [horizontal] [vertical] +

        Sets the space between cells in pixels. The default value is 0 0.

        +
      • + +
      • min [horizontal] [vertical] +

        When any of the parameters is enabled (1), it forces the minimum size of the table to be equal to the minimum size of the items. The default value is 0 0.

        +
      • + +
      + +

      Map

      + +
      +map 
      +{
      +   perspective: "name";
      +   light: "name";
      +   on: 1;
      +   smooth: 1;
      +   perspective_on: 1;
      +   backface_cull: 1;
      +   alpha: 1;
      +
      +   rotation 
      +   {
      +      ...
      +   }
      +}
      +
      + +
        + +
      • perspective [another part's name] +

        This sets the part that is used as the perspective point for giving a part a 3D look. The perspective point must have a perspective section that provides zplane and focal properties. The center of this part is used as the focal point, thus size, color and visibility are not relevant, just center point, zplane and focal are used. This also implicitly enables perspective transforms.

        +
      • + +
      • light [another part's name] +

        This sets the part that is used as the light for calculating the brightness (based on how directly the part's surface is facing the light source point). Like the perspective point part, the center point is used and zplane is used for the z position (0 being the zero-plane where all 2D objects normally live) and positive values being further away into the distance. The light part color is used as the light color (alpha not used for light color). The color2 color is used for the ambient lighting when calculating brightness (alpha also not used).

        +
      • + +
      • on [1 or 0] +

        This enables mapping for the part. Default is 0.

        +
      • + +
      • smooth [1 or 0] +

        This enables smooth map rendering. This may be linear interpolation, anisotropic filtering or anything the engine decides is smooth. This is a best-effort hint and may not produce precisely the same results in all engines and situations. The default value is 1.

        +
      • + +
      • alpha [1 or 0] +

        This enables alpha channel when map rendering. The default value is 1.

        +
      • + +
      • backface_cull [1 or 0] +

        This enables backface culling (when the rotated part that normally faces the camera is facing away after being rotated etc.). This means that the object are hidden when backface is culled.

        +
      • + +
      • perspective_on [1 or 0] +

        This enables perspective when rotating even without a perspective point object. This uses perspective set for the object itself or for the canvas as a whole as the global perspective with edje_perspective_set() and edje_perspective_global_set().

        +
      • + +
      • color [point] [red] [green] [blue] [alpha] +

        This sets the color of a vertex in the map. Colors are linearly interpolated between vertex points through the map. The default color of a vertex in a map is white solid (255, 255, 255, 255) which means it has no affect on modifying the part pixels. Currently only four points are supported: 0 - Left-Top point of a part. 1 - Right-Top point of a part. 2 - Left-Bottom point of a part. 3 - Right-Bottom point of a part.

        +
      • + +
      + +
      Map.rotation
      + +
      +rotation 
      +{
      +   center: "name";
      +   x: 45.0;
      +   y: 45.0;
      +   z: 45.0;
      +}
      +
      + +

      Rotates the part, optionally with the center on another part.

      + +
        + +
      • center [another part's name] +

        This sets the part that is used as the center of rotation when rotating the part with this description. The part's center point is used as the rotation center when applying rotation around the x, y and z axes. If no center is given, the parts original center itself is used for the rotation center.

        +
      • + +
      • x [X degrees] +

        This sets the rotation around the x axis of the part considering the center set. The value is given in degrees.

        +
      • + +
      • y [Y degrees] +

        This sets the rotation around the y axis of the part considering the center set. The value is given in degrees.

        +
      • + +
      • z [Z degrees] +

        This sets the rotation around the z axis of the part considering the center set. The value is given in degrees.

        +
      • + +
      + +
      Perspective
      + +
      +perspective 
      +{
      +   zplane: 0;
      +   focal: 1000;
      +}
      +
      + +

      Adds focal and plane perspective to the part. Active if perspective_on is true. Must be provided if the part is being used by other part as it is perspective target.

      + +
        + +
      • zplane [unscaled Z value] +

        This sets the z value that is not scaled. Normally this is 0 as that is the z distance.

        +
      • + +
      • focal [distance] +

        This sets the distance from the focal z plane (zplane) and the camera - i.e. equating to focal length of the camera

        +
      • + +
      + + + +
      +link 
      +{
      +   base: "edje,signal" "edje";
      +   transition: LINEAR 0.2;
      +   in: 0.5 0.1;
      +   after: "some_program";
      +}
      +
      + +

      The link block can be used to create transitions to the enclosing part description state. The result of the above block is identical to creating a program with

      + + +
      +action: STATE_SET "default"";
      +signal: "edje,signal";
      +source: "edje";
      +
      + +
        + +
      • base [signal] [source] +

        Defines the signal and source which triggers the transition to this state. The source parameter is optional here and is filled with the current group's default value if it is not provided.

        +
      • +
      + +

      Program

      + +
      +program
      +{
      +   // name of the program
      +   name: "programname";
      +   // signals which trigger the program
      +   signal: "signalname";
      +   // filter incoming signals depending on the sender name
      +   source: "partname";
      +   // filter incoming signals depending on the part's state
      +   filter: "partname" "statename";
      +   // delay the program by X seconds plus a random time between 0 and Y
      +   in: 0.3 0.0;
      +   // action to perform
      +   action: STATE_SET "statename" state_value;
      +   // if action is STATE_SET, define a transition from the current to the target state
      +   transition: LINEAR 0.5;
      +   // if action is SIGNAL_EMIT, the name of the part which will receive the signal
      +   target: "partname";
      +   // run another program after the current one is done
      +   after: "programname";
      +   after: "anotherprogram";
      +}
      +
      + +

      Program

      + +

      Programs define how your interface reacts to events. Programs can change the state of parts or trigger other events.

      + +
        + +
      • name [program name] +

        Symbolic name of program as a unique identifier.

        +
      • + +
      • signal [signal name] +

        Specifies signals that cause the program to run. The signal received must match the specified source to run. There may be several signals, but only one signal keyword per program can be used. Also, there are some predefined signals for touch event handling. The predefined signals are:

        +
          +
        • "hold,on": Holding on the mouse event matching the source that starts the program.
        • +
        • "hold,off": Holding off the mouse event matching the source that starts the program.
        • +
        • "focus,part,in": Focusing in the matching source that starts the program.
        • +
        • "focus,part,out": Focusing out of the matching source that starts the program.
        • +
        • "mouse,in": Moving the mouse into the matching source that starts the program.
        • +
        • "mouse,out": Moving the mouse out of the matching source that starts the program.
        • +
        • "mouse,move": Moving the mouse in the matching source that starts the program.
        • +
        • "mouse,down,*": Pressing the mouse button in the matching source that starts the program.
        • +
        • "mouse,up,*": Releasing the mouse button in the matching source that starts the program.
        • +
        • "mouse,clicked,*": Clicking any mouse button in the matching source that starts the program.
        • +
        • "mouse,wheel,0,*": Moving the mouse wheel in the matching source that starts the program. A positive number moves up and a negative number moves down.
        • +
        • "drag,start": Starting a drag of the mouse in the matching source that starts the program. This signal works only in the draggable part.
        • +
        • "drag,stop": Stopping a drag of the mouse in the matching source that starts the program. This signal works only in the draggable part.
        • +
        • "drag": Dragging the mouse in the matching source that starts the program. This signal works only in the draggable part.
        • +
        +
      • + +
      • source [source name] +

        Source of accepted signal. There may be several signals, but only one source keyword per program can be used. For example, source: "button-*"; (signals from any part or program named "button-*" are accepted).

        +
      • + +
      • filter [part] [state] +

        Filter signals to be only accepted if the part is in state named [state]. Only one filter per program can be used. If [state] is not given, the source of the event is used instead.

        +
      • + +
      • in [from] [range] +

        Wait [from] seconds before executing the program and add a random number of seconds (from 0 to [range]) to the total waiting time.

        +
      • + +
      • action [type] (param1) (param2) (param3) (param4) +

        Action to be performed by the program. Valid actions (only one can be specified) are:

        +
          +
        • STATE_SET: Set "target part" state as "target state"
        • +
        • ACTION_STOP: Stop the ongoing transition.
        • +
        • SIGNAL_EMIT: Emit a signal to the application level. The application can register a callback for handling actions based on the EDC state.
        • +
        • DRAG_VAL_SET: Set a value for the dragable part (x, y values).
        • +
        • DRAG_VAL_STEP: Set a step for the dragable part (x, y values).
        • +
        • DRAG_VAL_PAGE: Set a page for the dragable part (x, y values).
        • +
        • FOCUS_SET: Set the focus to the target group.
        • +
        • PLAY_SAMPLE "sample name" speed (channel): Play a music sample clip. + +

          PLAY_SAMPLE's (optional) channel can be one of:

          +
            +
          • EFFECT/FX
          • +
          • BACKGROUND/BG
          • +
          • MUSIC/MUS
          • +
          • FOREGROUND/FG
          • +
          • INTERFACE/UI
          • +
          • INPUT
          • +
          • ALERT
          • +
          +
        • + +
        • PLAY_TONE "tone name" duration_in_seconds (Range 0.1 to 10.0): Play a predefined tone of a specific duration.
        • +
        • PLAY_VIBRATION "sample name" repeat (repeat count)
        • +
      • + + +
      • transition [type] [length] (interp val 1) (interp val 2) (option) +

        Defines how transitions occur using STATE_SET action. [type] is the style of the transition and [length] is a double specifying the number of seconds in which to preform the transition. Valid types are:

        +
          +
        • LIN or LINEAR
        • +
        • SIN or SINUSOIDAL
        • +
        • ACCEL or ACCELERATE
        • +
        • DECEL or DECELERATE
        • +
        • ACCEL_FAC or ACCELERATE_FACTOR
        • +
        • DECEL_FAC or DECELERATE_FACTOR
        • +
        • SIN_FAC or SINUSOIDAL_FACTOR
        • +
        • DIVIS or DIVISOR_INTERP
        • +
        • BOUNCE
        • +
        • SPRING
        • +
        + +

        ACCEL_FAC, DECEL_FAC and SIN_FAC need the extra optional "interp val 1" to determine the "factor" of curviness. 1.0 is the same as their non-factor counterparts and 0.0 is equal to linear. Numbers higher than 1.0 make the curve angles steeper with a more pronounced curve point.

        + +

        DIVIS, BOUNCE and SPRING also require "interp val 2" in addition to "interp val 1".

        + +

        DIVIS uses [val 1] as the initial gradient start (0.0 is horizontal, 1.0 is diagonal (linear), 2.0 is twice the gradient of linear, etc.). [val 2] is interpreted as an integer factor defining how much the value swings outside the gradient before going back to the final resting spot at the end. 0.0 for [val 2] is equivalent to linear interpolation. Note that DIVIS can exceed 1.0.

        + +

        BOUNCE uses [val 2] as the number of bounces (so it is rounded down to the nearest integer value), with [val 1] determining how much the bounce decays; 0.0 gives linear decay per bounce and higher values give much more decay.

        + +

        SPRING is similar to bounce; [val 2] specifies the number of spring swings and [val 1] specifies the decay, but it can exceed 1.0 on the outer swings.

        + +

        Valid options are:

        +
          +
        • CURRENT causes the object to move from its current position. Can be used as the last parameter of any transition type.
        • +
        +
      • + +
      • target [target] +

        Program or part on which the specified action acts.

        +
      • + +
      • after [after] +

        Specifies a program that is run after the current program completes. The source and signal parameters of a program run as an after are ignored. Multiple after statements can be specified per program.

        +
      • + +
      + + + + + + + + + + +
      Note
      Except as noted, this content is licensed under LGPLv2.1+.
      + + + +
      + +Go to top + + + + + + + \ No newline at end of file diff --git a/org.tizen.ui.guides/html/native/efl/edc_positioning_n.htm b/org.tizen.ui.guides/html/native/efl/edc_positioning_n.htm new file mode 100755 index 0000000..92c10a9 --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/edc_positioning_n.htm @@ -0,0 +1,492 @@ + + + + + + + + + + + + + Positioning Parts with the EDC File + + + + + +
      + +

      Positioning Parts with the EDC File

      + + +

      Positioning Basic Parts

      + +

      Size of a part (in pixels) is set using the min and max parameters. The following code example sets the minimum and maximum size of the rectangle part to 200x200 px.

      + +
      +part 
      +{ 
      +   name: "rectangle";
      +   type: RECT;
      +   description 
      +   { 
      +      state: "blue" 0.0;
      +      align: 0.0 0.0;
      +      // set the size to 200x200
      +      min: 200 200;
      +      max: 200 200;
      +      // blue color
      +      color: 0 0 255 255;
      +   }
      +}
      +
      + +

      Position of the parts is defined in the rel1 and rel2 blocks. rel1 and rel2 blocks are used to define respectively the upper-left corner and the lower-right corner of the part. Position can be defined relatively to other parts (with the relative parameter) as an offset (offset parameter). When using relative positioning, the to, to_x and to_y parameters are used to define to which part the relative positioning is done. If nothing else is specified, the positioning is relative to the parent's part.

      + +

      To demonstrate the relative positioning, here is a code example that creates another part and positions it under the first part (the upper-left corner of the new part will start at the lower-left corner of the previous one).

      + +
      +part 
      +{ 
      +   name: "rectangle2";
      +   type: RECT;
      +   description 
      +   { 
      +      state: "green" 0.0;
      +      align: 0.0 0.0;
      +      // set the size to 200x200
      +      min: 200 200;
      +      max: 200 200;
      +      // green color
      +      color: 0 255 0 255;
      +      // set the position
      +      // rel1 is relative to "rectangle"
      +      rel1 
      +      {
      +         relative: 0.0 1.0;
      +         to: "rectangle";
      +      }
      +      // rel2 is relative to the parent
      +      rel2 
      +      {
      +         relative: 1.0 1.0;
      +      }
      +   }
      +}
      +
      + + + + + + + + + + +
      Note
      The align parameter defines how the parts align themselves in the main window if their size is smaller than the main window. If nothing is specified, the parts are aligned in the center of the window.
      + +

      Adding Offset to Relative Positioning

      + +

      The rel1 and rel2 structures also support offset which is a complement to the relative positioning: the corners are first placed according to their relative parameters and then adjusted using the offsets.

      + +

      The picture below shows the pixel positions for a 4x4 rectangle. The indices start in the top-left corner at (0, 0) increase to the right and to the bottom. Since the indices have started at 0, the 4th pixel has an index of 3.

      + +

      Therefore, in order to create a 2x2 blue rectangle centered inside that green square, the top-left corner has to be (1, 1) and the bottom-right one has to be (2, 2).

      + +

      Figure: Offset indices

      +

      Offset indices

      + +

      Edje needs the following things defined:

      +
        +
      • the part coordinates depending on the size and position of the green rectangle
      • +
      • the relative component of positions is the same: the top-left corner of the green rectangle
      • +
      • the top-left pixel is (1, 1) and the bottom-right one is (2, 2)
      • +
      + +

      The following code example defines these things:

      + +
      +name: "blue rectangle";
      +
      +rel1.to: "green rectangle";
      +rel1.relative: 0 0;
      +rel1.offset: 1 1;
      +
      +rel2.to: "green rectangle";
      +rel2.relative: 0 0;
      +rel2.offset: 2 2;
      +
      + +

      For most tasks, relative positioning is simpler than using offsets. Offsets are usually left for fine-tuning and creating borders.

      + +

      The example below is similar to the previous one but uses relative positioning instead of offsets to achieve an equivalent at 4x4 but could scale to larger sizes.

      + +

      The blue square starts at 25% of the green square (both vertically and horizontally) and ends at 75% of it (again, both vertically and horizontally).

      + +

      Just like in the previous example, the blue rectangle is named and Edje is told what the object of reference is:

      + +
      +name: "blue rectangle";
      +rel1.to: "green rectangle";
      +rel2.to: "green rectangle";
      +
      + +

      The image below shows how to refer pixels using relative positioning when the offsets are (0, 0).

      + +

      Figure: Relative positioning

      +

      Relative positioning

      + +

      Note the addressing of pixels: (0, 0) is addressed through relative: 0 0; offset 0 0; and each additional 0.25 in the relative field gives a 1-pixel move. With this, the pixel addressed through relative: 0.75 0.75; offset: 0 0; is at (3, 3) and not (2, 2)!.

      + +

      This comes from a design choice in Evas and Edje which favor simplicity. In the examples shown in this guide, there are 4 pixels and therefore when the [0; 1) range is divided in 4, the result is [0; 0.25), [0.25; 0.50), [0.50; 0.75), [0.75; 0.100). With Edje, the value used to refer to each segment is the left bound and therefore, 0.75 refers to [0.75; 0.100), i.e. the bottom-right pixel of the green rectangle and not the 3/4th one.

      + +

      The way to refer to the pixel right before is to set the rel2 bound to relative: 0.75 0.75;, as would be expressed naturally, and offset: -1 -1;. This can also be understood as extending the rectangle up to 75% of its parent with the upper bound excluded (as shown in the [0.50; 0.75)).

      + +

      Since -1 -1 is the most common offset wanted for rel2, it is the default value; i.e. the default behavior is practical.

      + +

      Calculating Edje Object Total Size

      + +

      When the EDC file is composed of a lot of parts, Edje calculates the size of the global Edje object, by taking all the parts and their parameters into account. Some parameters have an role in this calculation and affect the global size:

      + +
        +
      • min and max: these define the minimum and the maximum size of a part.
      • +
      • rel1 and rel2: these specify the relative position of a part.
      • +
      • align: this relates to the alignment of the part in the parent's object.
      • +
      • fixed: this defines if the part has a fixed size.
      • +
      + + + + + + + + + + +
      Note
      fixed parameter can only be used on TEXTBLOCK type parts. Setting this parameter to fixed: 1 1 will not take into account the part for the calculation of the global size.
      + +

      Using Edje Size Hints

      + +

      Any Evas_Object can have hints, so that the object knows how to properly position and resize. Edje uses these hints when swallowing an Evas_Object to position and resize it in the SWALLOW part of the EDC file.

      + +

      Size hints are not a size enforcement, they just tell the parent object the desired size for this object. Then, the parent tries to get as close as possible to the hint.

      + +

      Hints are set in an Evas_Object using the evas_object_size_hint_*() functions.

      + +

      Min Size Hint

      + +

      This sets the hints for the object's minimum size, given in pixels.

      + +

      Here the horizontal and vertical min size hints of an Evas_Object are set to 0 pixels.

      + +
      +Evas_Object *object;
      +evas_object_size_hint_min_set(object, 0, 0);
      +
      + +

      Max Size Hint

      + +

      This sets the hints for the object's maximum size, given in pixels.

      + +

      Here the horizontal and vertical max size hints of an Evas_Object are set to 200 pixels.

      +
      evas_object_size_hint_max_set(object, 200, 200);
      + +

      Request Size Hint

      + +

      This sets the hints for the object's optimum size.

      + +

      The following code example defines that the optimum size of a part is 200x200 pixels.

      + +
      +evas_object_size_hint_request_set(object, 200, 200);
      +
      + +

      Aspect Size Hint

      + +

      This sets the hints for the object's aspect ratio. Available aspect size hints are:

      + +
        +
      • EVAS_ASPECT_CONTROL_NONE
      • +
      • EVAS_ASPECT_CONTROL_HORIZONTAL
      • +
      • EVAS_ASPECT_CONTROL_VERTICAL
      • +
      • EVAS_ASPECT_CONTROL_BOTH
      • +
      + +

      The other parameters are aspect width and height ratio. These integers are used to calculate the proportions of the object. If aspect ratio terms are null, the object's container ignores the aspect and scale of the object and occupies the whole available area.

      + +

      Figure: Aspect control

      +

      Aspect control

      + +

      Aspect control

      + +

      Aspect control

      + +

      The following code example sets the aspect size hint to EVAS_ASPECT_CONTROL_BOTH with a width of 100 and a height of 200. So aspect ratio should be 1/2.

      + +
      +evas_object_size_hint_aspect_set(object, EVAS_ASPECT_CONTROL_BOTH, 100, 200);
      +
      + +

      Align Size Hint

      +

      This sets the hints for the object's alignment. This hint is used when the object size is smaller than its parent's. The special EVAS_HINT_FILL parameter uses maximum size hints with higher priority, if they are set. Also, any padding hints set on objects are added up to the alignment space on the final scene composition.

      + +

      Figure: Alignment

      +

      Alignment

      + +

      In the code below, the special EVAS_HINT_FILL parameter is used.

      + +
      +evas_object_size_hint_align_set(object, EVAS_HINT_FILL, EVAS_HINT_FILL);
      +
      + +

      Weight Size Hint

      + +

      This sets the hints for the object's weight. The weight tells to a container object how the given child is resized. Using EVAS_HINT_EXPAND parameter asks to expand the child object's dimensions to fit the container's own.

      + +

      When several child objects have different weights in a container object, the container distributes the space it has to layout them by those factors. Most weighted children get larger in this process than the least ones.

      + +

      Here the container is asked to expand the object in both directions.

      + +
      +evas_object_size_hint_weight_set(object, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +
      + +

      Padding Size Hint

      + +

      This sets the hints for the object's padding space. Padding is extra space an object takes on each of its delimiting rectangle sides. The padding space is rendered transparent. Four hints can be defined, for the left, right, top, and bottom padding.

      + +

      Figure: Padding

      +

      Padding

      + +

      Here the padding hints are set to 5 pixels on each side of the object.

      + +
      +evas_object_size_hint_padding_set(object, 5, 5, 5, 5);
      +
      + + +

      Edje Swallow

      + +

      The parent of all layout components is Edje. Edje as explained in the Edje Blocks is a library which convert edc files into Evas object. EDC is a description language. It means that the objects of interface are described by using text description. One of its main features is the possibility to create "Swallows" objects. When this kind of object is added in an Evas, it contains any other Evas_Object. To create a swallow part, create first the EDC file:

      + +
      +collections
      +{
      +   group 
      +   { 
      +      name: "container";
      +      parts 
      +      {
      +         part 
      +         {
      +            name: "part.swallow"
      +            type: SWALLOW;
      +            description 
      +            {
      +               state: "default" 0.0;
      +               rel1.offset: 31 31;
      +               rel2.offset: -32 -32;
      +            }
      +         }
      +      }
      +   }
      +}
      +
      + +

      This EDC describes a group named "container", with one part inside of type SWALLOW and with the name part.swallow. This part is centered inside the parent (it is the default behavior) but there are 32 pixels free all around this part. Use edje_cc to compile the EDC file into a binary EDJ file:

      + +
      +edje_cc -o container.edj container.edc
      +
      + +

      Create an Edje object and load this file:

      + +
      +edje = edje_object_add(evas_object_evas_get(parent));
      +edje_object_file_set(edje, "container.edj", "container");
      +
      + + + + + + + + + + +
      Note
      edje_object_add as opposed as all elementary object, does not take an Evas_Object as a parent. Give it the Evas on which the object is added. As the parent is already added on an Evas by elementary, retrieve a reference on it by using the evas_object_evas_get() function.
      + +

      edje_object_file_set is used to set the Edje file from which the object is loaded. The object itself is the name of the group as defined in the EDC file, in this case it is "container".

      + +

      Use the API edje_object_swallow to swallow any kind of Evas_Object inside.

      + +
      +ic = elm_icon_add(parent);
      +elm_image_file_set(ic, "c1.png", NULL);
      +edje_object_part_swallow(edje, "part.swallow", ic);
      +
      + + + + + + + + + + +
      Note
      The elm_image_file_set() function parameters are linked to Edje. The second argument in this example is a PNG file; however, it can also be an Edje file. In that case, the third argument must be the Edje group to load, exactly as previously shown with the edje_object_file_set() function.
      + +

      Create complex layout for your application with Edje. It is may not be the most easy way, but it is the most powerful. This Edje layout is used all around elementary and is the basis of the layout component.

      + +

      ELM Layout

      + +

      Layout is a container component. For the basic use of the elm_layout with a default style, see Layout. Elm layout takes a standard Edje design file and wraps it in a UI component. Layouts are the basis of graphical UI components which are used in Elementary.

      + +

      Adding Layout

      + +

      Create a new elementary layout using elm_layout_add:

      + +
      +Evas_Object *layout;
      +layout = elm_layout_add(parent);
      +
      + +

      As for Edje swallows, load an Edje file. Create first an Edje file, that contains a black rectangle and an icon in the center.

      + +
      +images
      +{
      +   image: "c1.png" COMP;
      +}
      +
      +collections
      +{
      +   group 
      +   { 
      +      name: "my_layout";
      +      parts 
      +      {
      +         part 
      +         {
      +            name: "background";
      +            type: RECT; description 
      +            { 
      +               state: "default" 0.0; color: 0 0 0 255; 
      +            } 
      +         } 
      +         part 
      +         { 
      +            name: "background"; 
      +            type: IMAGE; 
      +            description 
      +            { 
      +               state: "default" 0.0; 
      +               rel1.offset: 31 31; 
      +               rel2.offset: -32 -32; 
      +               default.image: "c1.png"; 
      +            } 
      +         }
      +      } 
      +   } 
      +}
      +
      +

      Compile it with edje_cc -o edje_example.edj edje_example.edc.

      +

      This file can be loaded with elm_layout_file_set:

      + +
      +elm_layout_file_set(layout, "edje_example.edj", "my_layout");
      +
      + +

      The layout component may contain as many parts/children as described in its theme file (EDC). Some of these children can have special types:

      + +
        +
      • SWALLOW (content holder)
      • +
      • BOX
      • +
      • TABLE
      • +
      + +

      Only one object can be added to a SWALLOW. The elm_layout_content_set()/get/unset functions are used to manage objects in a SWALLOW part. After being set to this part, the object's size, position, visibility, clipping and other description properties are controlled by the description of the given part (inside the Edje theme file).

      + +

      The BOX layout can be used through the elm_layout_box_*() set of functions. It is very similar to the elm_box component but the BOX layout's behavior is completely controlled by the Edje theme. The TABLE layout is like the BOX layout, the difference is that it is used through the elm_layout_table_*() set of functions.

      + +

      Signals

      +

      Elm can send Edje signals to the EDC part by using the elm_layout_signal_emit. You can also use elm_layout_signal_callback_add to receive signals.

      + +

      Use the following code to listen to any signals sent by the layout:

      + +
      +elm_layout_signal_callback_add(layout, "*", "*", _signal_cb, NULL);
      +
      +static void _signal_cb(void *data, Evas_Object *obj, const char *emission, const char *source)
      +{
      +   printf("Info received from layout : %s %s\n", emission, source);
      +}
      +
      + +

      For more details on this, see the section on edje signals and layouts.

      + + + + + + + + + + +
      Note
      Except as noted, this content is licensed under LGPLv2.1+.
      + + + +
      + +Go to top + + + + + + + \ No newline at end of file diff --git a/org.tizen.ui.guides/html/native/efl/edje_animation_n.htm b/org.tizen.ui.guides/html/native/efl/edje_animation_n.htm new file mode 100755 index 0000000..3a64886 --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/edje_animation_n.htm @@ -0,0 +1,535 @@ + + + + + + + + + + + + + Edje Animations + + + + + +
      + +

      Edje Animations

      + +

      One of the greatest strengths of EFL and Edje is the ability to create animations. This tutorial demonstrates how Elm_Transit can create predefined animations, but you can also use the Edje library to create your own animations.

      + +

      The Edje animations are based on a very simple principle: going from one state to another. If you want to animate something with Edje, you must define two states and move from the first state to the second.

      + +

      Animating a Rectangle

      + +

      This example shows how to animate a rectangle. It is positioned in the top left corner of the window and is moved to the bottom right corner in five seconds. To do that with Edje, define a part called "rectangle" with the type RECT: this part has two descriptions (or states). In the first state, the rectangle is in is the top left corner. In the second state, it is in is the bottom right corner. To create the transition, set this EDC code for Edje to switch the object from its current state to another.

      + +
      +collections 
      +{
      +   group 
      +   { 
      +      name: "main";
      +      parts 
      +      {
      +         part 
      +         { 
      +            name: "rectangle";
      +            type: RECT;
      +            description 
      +            { 
      +               state: "default" 0.0;
      +               align: 0.0 0.0;
      +               rel1 {relative: 0.0 0.0;}
      +               rel2 {relative: 0.3 0.1;}
      +               color: 0 0 255 255;
      +            }
      +            description 
      +            { 
      +               state: "default" 0.5;
      +               align: 0.0 0.0;
      +               rel1 {relative: 0.7 0.9;}
      +               rel2 {relative: 1.0 1.0;}
      +               color: 0 0 255 255;
      +            }
      +         }
      +      }
      +      programs 
      +      {
      +         program 
      +         { 
      +            name: "animation,state1";
      +            source: "";
      +            signal: "load";
      +            action: STATE_SET "default" 0.5;
      +            target: "rectangle";
      +            transition: LINEAR 5;
      +         }
      +      }
      +   }
      +}
      +
      + +

      The "rectangle" part has two descriptions that share the same name, but have a different "version".

      + +
      +part 
      +{ 
      +   name: "rectangle";
      +   type: RECT;
      +   description 
      +   { 
      +      state: "default" 0.0;
      +   }
      +   description 
      +   { 
      +      state: "default" 0.5;
      +   }
      +}
      +
      + +

      The program defines when and how to move from one state to another. A program is called upon reception of a signal from a source. Here the program is called when the signal load is received from any source.

      + +
      +program 
      +{ 
      +   name: "animation,state1";
      +   source: "";
      +   signal: "load";
      +}
      +
      + +

      An action is performed upon the signal reception. In this example, the state is changed.

      + +
      +action: STATE_SET "default" 0.5;
      +
      + +

      The program has a target, here the "rectangle".

      + +
      +target: "rectangle";
      +
      + +

      The program uses a transition to perform the action.

      + +
      +transition: LINEAR 5;
      +
      + +

      This example produces a blue rectangle that moves from the upper left to the lower right corner with a linear transition in five seconds.

      + +

      Actions

      + +

      The Edje programs are not only for animations. There are different actions, for example STATE_SET and ACTION_STOP. You may also send signals with SIGNAL_EMIT.

      + +

      The STATE_SET action changes the state of the "target".

      + +

      In the following example, the state of the part named "image" changes to "default" "0.0".

      + +
      +program 
      +{
      +   name: "animate";
      +   signal: "animate";
      +   action: STATE_SET "default" 0.0;
      +   transition: LINEAR 3.0;
      +   target: "image";
      +}
      +
      + +

      The ACTION_STOP stops the program specified by "target".

      + +
      +program 
      +{
      +   name: "animate_stop";
      +   signal: "animate_stop";
      +   action: ACTION_STOP;
      +   target: "animate_loop";
      +}
      +
      + +

      The previous example stops the program defined as "target" named animate_loop. This program runs on the animate_stop signal.

      + +

      The SIGNAL_EMIT emits a signal that is used to communicate with the application directly from the theme.

      + +

      The following example emits a signal frame_move "start" when it receives the signal mouse,down,* from the video_over part. In other words, it sends the signal frame_move "start" when the mouse is pressed in the video_over part.

      + +
      +program 
      +{ 
      +   name: "video_move_start";
      +   signal: "mouse,down,*";
      +   source: "video_mover";
      +   action: SIGNAL_EMIT "frame_move" "start";
      +}
      +
      + +

      Transitions

      + +

      The transitions available are:

      +
        +
      • LIN or LINEAR: makes a linear transition and takes the duration in seconds as the parameter
      • +
      • SIN or SINUSOIDAL: makes a sinusoidal transition and takes the duration in seconds as the parameter
      • +
      • ACCEL or ACCELERATE: makes an accelerated transition and takes the duration in seconds as the parameter
      • +
      • DECEL or DECELERATE: makes a decelerated transition and takes the duration in seconds as the parameter
      • +
      • ACCEL_FAC or ACCELERATE_FACTOR: makes an accelerated transition and takes the duration and the factor as the parameters
      • +
      • DECEL_FAC or DECELERATE_FACTOR: makes a decelerated transition and takes the duration and the factor as the parameters
      • +
      • SIN_FAC or SINUSOIDAL_FACTOR: makes a sinusoidal transition and takes the duration and the factor as the parameters
      • +
      • DIVIS or DIVISOR_INTERP: takes 3 parameters: +
          +
        • the duration
        • +
        • the initial gradient start (0.0 is horizontal, 1.0 is diagonal (linear), 2.0 is twice the gradient of linear, and so on)
        • +
        • an integer factor that defines how much the value swings outside the gradient to come back to the final resting spot at the end. 0.0 for the third parameter is equivalent to linear interpolation. Note that DIVIS may exceed 1.0.
        • +
        +
      • +
      • BOUNCE: makes a bounce transition and takes 3 parameters: +
          +
        • the duration
        • +
        • how much the bounce decays, with 0.0 giving linear decay per bounce, and higher values giving more decay
        • +
        • the number of bounces (rounded down to the nearest integer value)
        • +
        +
      • +
      • SPRING: makes a spring transition and takes 3 parameters: +
          +
        • the duration
        • +
        • the decay, with the level exceeding 1.0 on the outer swings
        • +
        • the number of spring swings
        • +
        +
      • +
      + +

      There are graphical representations of these effects in the Ecore_Evas section above.

      + +

      Chaining Edje Programs

      + +

      To define a couple of Edje programs and chain them, we can, for example, create a program to make the rectangle return to its initial state with another transition (such as BOUNCE).

      + +

      Use the statement after in the first program. after takes the name of the transition to run when the program is done.

      + +
      +after: "animation,state0";
      +
      + +

      This is how to add the bounce animation. To return the blue rectangle to its initial position with a BOUNCE transition: it bounces with a factor of 1.8, six times. This program is only to be used at the end of the first one, so it does not have any signal statement.

      + +
      +program 
      +{ 
      +   name: "animation,state0";
      +   source: "";
      +   signal: "";
      +   action: STATE_SET "default" 0.0;
      +   target: "rectangle";
      +   transition: BOUNCE 5 1.8 6;
      +}
      +
      + +

      Playing on Signals

      + +

      The programs start when they receive a signal from a source. Edje handles many kind of signals, including mouse events.

      + + + + + + + + + + +
      Note
      To show the signals, use edje_player -p myfile.edj.
      + +

      For example, in another transition the rectangle is left clicked. The corresponding signal name is mouse,clicked,1.

      + +

      For this transition, define a new state. This state changes the color and the position of the rectangle.

      + +
      +// To be placed in the "part" definition
      +description 
      +{ 
      +   state: "color" 0.0;
      +   rel1 {relative: 0.3 0.3;}
      +   rel2 {relative: 0.7 0.4;}
      +   color: 255 0 0 255;
      +}
      +
      + +

      The program is as follows:

      + +
      +program 
      +{ 
      +   name: "animation,color";
      +   source: "rectangle";
      +   signal: "mouse,clicked,1";
      +   action: STATE_SET "color" 0.0;
      +   target: "rectangle";
      +   transition: SIN 2;
      +}
      +
      + +

      This starts when the rectangle is left clicked.

      + +

      If you want to send a signal from your application when you use signals to start transitions, create a program waiting for your own special signal. For example:

      + +
      +program 
      +{ 
      +   name: "animation,menu_side,hide";
      +   source: "MenuButton";
      +   signal: "hide,sidemenu";
      +   action: STATE_SET "default" 1.0;
      +   target: "menu/side";
      +   transition: LINEAR 0.2;
      +}
      +
      + +

      This program changes the state of the target named animation,menu_side,hide to "default" 1.0. It waits for the hide,sidemenu signal emitted by a source called MenuButton.

      + +
      +edje_object_signal_emit(layout, "hide,sidemenu", "MenuButton");
      +
      + +

      This statement sends a signal named hide,sidemenu with a source named MenuButton to the object called layout.

      + +

      The edje_object_signal_emit function emits a signal on an Evas_Object part of the application.

      + +
      +edje_object_signal_emit(Evas_Object *obj,
      +                        const char *emission,
      +                        const char *source)
      +
      + +
        +
      • The first parameter is the Evas_Object, which emits the signal (layout in the example).
      • +
      • The second parameter is the emission string (the name of the signal hide,sidemenu in the example).
      • +
      • The third parameter is the source of the signal (the name of the source, MenuButton in the example).
      • +
      + +

      If you use the Elementary in the application, you can use elm_object_signal_emit. It functions exactly the same way as edje_object_signal_emit and takes the same parameters.

      + + + + + + + + + + +
      Note
      To find a complete example, use elm_object_signal_emit in Creating Mobile Menus.
      + +

      Rotating with Edje

      + +

      The Edje library allows you to rotate objects, using the map statement. For example, if you want to rotate the blue rectangle on a right click, you must define a new rotate state. To enable the map on you object you must add a map part to your default state.

      + +
      +map 
      +{
      +   on: 1;
      +   smooth: 1;
      +   perspective_on: 1;
      +   rotation.x: 0;
      +   rotation.y: 0;
      +   rotation.z: 0;
      +}
      +
      + +
        +
      • on: 1; enables the map on the object
      • +
      • perspective_on: 1, enables the perspective when rotating, even without a perspective point object
      • +
      • smooth: 1; enables a smooth map rendering
      • +
      • The rotation statements define the default rotation of the object on x, y, and z axes.
      • +
      + +

      To add a new rotate state with a rotation around any axis, do the following.

      + +
      +description 
      +{ 
      +   state: "rotate" 0.0;
      +   inherit: "default" 0.0;
      +   map.rotation.z: 120;
      +}
      +
      + +

      This rotate state inherits all the default state properties, but changes the value of map.rotation.z from 0° to 120°.

      + +

      To set a program to run the rotate state, do the following.

      + +
      +program 
      +{ 
      +   name: "animation,rotate";
      +   source: "rectangle";
      +   signal: "mouse,clicked,3";
      +   action: STATE_SET "rotate" 0.0;
      +   target: "rectangle";
      +   transition: LIN 5;
      +}
      +
      + +

      This program runs on a right click on the rectangle object.

      + +

      The complete code of this example is as follows.

      + +
      +collections 
      +{
      +   group 
      +   { 
      +      name: "main";
      +      parts 
      +      {
      +         part 
      +         { 
      +            name: "rectangle";
      +            type: RECT;
      +            description 
      +            { 
      +               state: "default" 0.0;
      +               align: 0.0 0.0;
      +               rel1 {relative: 0.0 0.0;}
      +               rel2 {relative: 0.3 0.1;}
      +               map 
      +               {
      +                  on: 1;
      +                  smooth: 1;
      +                  perspective_on: 1;
      +                  rotation 
      +                  {
      +                     z: 0;
      +                     x: 0;
      +                     y: 0;
      +                  }
      +               }
      +               color: 0 0 255 255;
      +            }
      +            description 
      +            { 
      +               state: "default" 0.5;
      +               align: 0.0 0.0;
      +               rel1 {relative: 0.7 0.9;}
      +               rel2 {relative: 1.0 1.0;}
      +               color: 0 0 255 255;
      +            }
      +            description 
      +            { 
      +               state: "color" 0.0;
      +               rel1 {relative: 0.3 0.3;}
      +               rel2 {relative: 0.7 0.4;}
      +               color: 255 0 0 255;
      +            }
      +            description 
      +            { 
      +               state: "rotate" 0.0;
      +               inherit: "default" 0.0;
      +               map.rotation.z: 120;
      +            }
      +         }
      +      }
      +      programs 
      +      {
      +         program 
      +         { 
      +            name: "animation,state1";
      +            source: "";
      +            signal: "load";
      +            action: STATE_SET "default" 0.5;
      +            target: "rectangle";
      +            transition: LINEAR 1;
      +            after: "animation,state0";
      +         }
      +         program 
      +         { 
      +            name: "animation,state0";
      +            source: "";
      +            signal: "";
      +            action: STATE_SET "default" 0.0;
      +            target: "rectangle";
      +            transition: BOUNCE 2 1.8 26;
      +         }
      +         program 
      +         { 
      +            name: "animation,color";
      +            source: "rectangle";
      +            signal: "mouse,clicked,1";
      +            action: STATE_SET "color" 0.0;
      +            target: "rectangle";
      +            transition: SIN 2;
      +         }
      +         program 
      +         { 
      +            name: "animation,rotate";
      +            source: "rectangle";
      +            signal: "mouse,clicked,3";
      +            action: STATE_SET "rotate" 0.0;
      +            target: "rectangle";
      +            transition: LIN 5;
      +         }
      +      }
      +   }
      +}
      +
      + + + + + + + + + + +
      Note
      Except as noted, this content is licensed under LGPLv2.1+.
      + + + +
      + +Go to top + + + + + + + \ No newline at end of file diff --git a/org.tizen.ui.guides/html/native/efl/edje_animation_tutorial_n.htm b/org.tizen.ui.guides/html/native/efl/edje_animation_tutorial_n.htm new file mode 100755 index 0000000..aa85f96 --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/edje_animation_tutorial_n.htm @@ -0,0 +1,377 @@ + + + + + + + + + + + + + + Creating Edje Animations + + + + + + +
      +

      Creating Edje Animations

      + + +

      One of the greatest strengths of EFL and Edje is the ability to create animations. This tutorial demonstrates how Elm_Transit can create pre-defined animations, but you can also use the Edje library to create your own animations.

      + +

      Animating on Application Start-up

      + + +

      The goal of this tutorial is to create an animation target and buttons to start animations, all this in an EDC (Edje Data Collection) file.

      +

      First create an application using Basic EDC UI Application. This model provides a simple application just like the one used in the previous chapter, but with one more element: an .edc file.

      +

      Animations can be run at application startup. By default the Basic EDC UI Application model produces an empty window with a title. In this example a Tizen logo is added to the window and the behavior of the window title is changed.

      +

      The images used by the Edje file are stored in the edje/images directory of the application. Copy the Tizen logo available in shared/res/<yourapplicationname>.png into the Edje image directory edje/images. Then add the image to the Edje images collection.

      +
      images 
      +{
      +   image: "edceffects.png" COMP;
      +   image: "tizen-logo.png" COMP;
      +}
      +
      + +

      Then add an Edje part using the small logo: this part has two states. This is the first important notion for animations. The STATE describes the appearance of a part: size, position, color, etc.

      +

      In this example, the part has two states, default and down-state:

      +
      // An image using the tizen logo
      +part 
      +{ 
      +   name: "logo";
      +   type: IMAGE;
      +   description 
      +   { 
      +      state: "default" 0.0;
      +      max: 63 63;
      +      min: 63 63;
      +      image { normal: "small-logo.png"; }
      +      rel1.relative: 0.1 0.0;
      +      rel2.relative: 0.0 0.0;
      +   }
      +
      +   description 
      +   { 
      +      state: "down-state" 1.0;
      +      inherit: "default" 0.0;
      +      rel1.relative: 0.1 0.92;
      +      rel2.relative: 0.05 1.0;
      +   }
      +}
      +

      The logo part has the IMAGE type. The default state contains in the first description of the part sets:

      +
        +
      • the maximum and minimum size using the min and max statements
      • +
      • the image to use in this part
      • +
      • the default position.
      • +
      +

      The second state, down-state, inherits all of the default's attributes, and only changes the position to put the image at the bottom of the application window.

      +

      These two states are the start and end states of the animation. To actually create the animation, add a program to the Edge programs collection.

      +
      // Icon drop animation
      +program 
      +{ 
      +   name: "animation,state1";
      +   source: "";
      +   signal: "load";
      +   action: STATE_SET "down-state" 1.0;
      +   target: "logo";
      +   transition: BOUNCE 2.5 0.0 5.0;
      +}
      +

      This program is named animation,state1 and is started when the application receives the load signal immediately on startup. It runs the STATE_SET action so it changes the object state from default to down-state. The target of the program is the logo part.

      +

      In order to switch from one state to another, it uses a transition of the BOUNCE type with 3 parameters, the bounce_decay, the number_of_bounces, and the duration which here is set to five seconds.

      +

      This produces an falling and bouncing effect.

      +

      Also add an animation for the window title to make it move from the left to the right with a bounce effect while growing the font size.

      +

      Create a new state on the part called "txt_title" inside which both the font size and position are changed.

      +
      part 
      +{ 
      +   name: "txt_title";
      +   type: TEXT;
      +   mouse_events: 0;
      +
      +   // The default State
      +   description 
      +   { 
      +      state: "default" 0.0;
      +      align: 0.0 0.0;
      +      rel1 { relative: 0.0 0.0; }
      +      rel2 { relative: 0.0 0.0; }
      +      text 
      +      { 
      +         font: "Tizen:style=regular";
      +         size: 24;
      +         min: 1 1;
      +      }
      +      color: 0 0 0 255;
      +   }
      +
      +   // The "Bigger" state
      +   description 
      +   { 
      +      state: "Bigger" 0.0;
      +      align: 0.0 0.0;
      +      rel1 { relative: 0.75 0.0; }
      +      rel2 { relative: 0.0 0.0; }
      +      text 
      +      { 
      +         font: "Tizen:style=regular";
      +         size: 28;
      +         min: 1 1;
      +      }
      +      color: 0 0 0 255;
      +   }
      +}
      +
      +

      Create a program to animate this part on startup, just like the small Tizen logo.

      +
      // Make the title bigger
      +program 
      +{ 
      +   name: "animation,bigtitle";
      +   source: "";
      +   signal: "load";
      +   action: STATE_SET "Bigger" 1.0;
      +   target: "txt_title";
      +   transition: LINEAR 5.0;
      +}
      +
      +

      This program goes from the default state to the bigger state in five seconds with a LINEAR effect, automatically running on the application startup.

      + +

      Animating Object on Click

      + +

      All the previous animations are automatic and do not have any relation with the user's actions. Next animate a part by clicking on another one. Make the title restore its default aspect when clicking on the small logo.

      +

      The parts and the states are already defined. The animation goes back to the default state, there is no need to add any parts or states: only add a program which makes the transition when clicking on logo part.

      +
      // Make the title go back to normal
      +program 
      +{
      +   name: "animation,normaltitle";
      +   source: "logo";
      +   signal: "mouse,clicked,*";
      +   action: STATE_SET "default" 1.0;
      +   target: "txt_title";
      +   transition: LINEAR 0.5;
      +}
      +

      This program starts when the application receives the signal mouse,clicked,* (any button of the mouse is clicked) from the part called logo, (source). It performs the STATE_SET action and sets the default state on the target txt_file part with a LINEAR transition.

      +

      When clicking any mouse button on the small logo, the title goes back to its original state.

      +

      Rotating Parts

      +

      Next add two more buttons to the application and create programs to animate a target.

      +

      It is possible to create a button with Edje from scratch, but to save time, the SWALLOW part is used in this example to store Elementary UI components.

      +

      First create the SWALLOW parts, and then the Elementary UI components in the .c file.

      +
      // Container for the rotate button
      +part 
      +{
      +   type: SWALLOW;
      +   name: "btn/rotate";
      +   description 
      +   {
      +      state: "default" 0.0;
      +      rel1.relative: 0.10 0.80;
      +      rel2.relative: 0.30 0.90;
      +   }
      +}
      +

      This part is called btn/rotate, it only has a SWALLOW type and a default state with its position being on the bottom left of the screen.

      +
      // Container for the grow button
      +part 
      +{
      +   type: SWALLOW;
      +   name: "btn/grow";
      +   description 
      +   {
      +      state: "default" 0.0;
      +      rel1.relative: 1.02 0;
      +      rel1.to: "btn/rotate";
      +      rel2.relative: 2.02 1;
      +      rel2.to: "btn/rotate";
      +   }
      +}
      +

      This second SWALLOW part is very similar to the first one. It is placed relatively to btn/rotate, in order to remain next to it.

      +

      Next create the actual UI components. This is done in the .c file and is very similar to what is done for the buttons in the first chapter.

      +

      This code is added to the create_base_ui function.

      +
      // Creation button in the app window
      +ad->button = elm_button_add(ad->win);
      +elm_object_text_set(ad->button, "Rotate");
      +// Add the button to the edje layout container called "btn/rotate"
      +elm_object_part_content_set(ad->layout, "btn/rotate", ad->button);
      +evas_object_show(ad->button);
      +
      +// Creation a up button in the app window
      +ad->btn_up = elm_button_add(ad->win);
      +// Add the button to the edje layout container called "btn/grow"
      +elm_object_text_set(ad->btn_up, "Grow");
      +elm_object_part_content_set(ad->layout, "btn/grow", ad->btn_up);
      +evas_object_show(ad->btn_up);
      +

      In the default Basic EDC UI Application, the Edje layout is loaded by default. Create two Elementary buttons and add them to the SWALLOW containers, without having to setup sizes or positions as this is done in the SWALLOW container.

      +

      Note that the part name is very important because it is used to be merged the Elementary UI component and the SWALLOW part.

      +

      When the buttons placed and set, create the animation target. it is done in the EDC file.

      +

      Add the animation target part.

      +

      The part initialization and the default state:

      +
      // The animation target
      +part 
      +{
      +   name: "atarget";
      +   type: IMAGE;
      +
      +   // Default state
      +   description 
      +   {
      +      state: "default" 0.0;
      +      image { normal: "tizen-logo.png"; }
      +      color: 255 0 0 255; // red
      +      rel1 { relative: 0.3 0.3; }
      +      rel2 { relative: 0.7 0.4; }
      +   }
      +}
      +
      +

      This part is an image displaying a big Tizen logo, placed on the top of the screen more or less centered.

      +

      Create a state to change the color and add the map statement.

      +
      // The rotate state
      +description 
      +{
      +   state: "rotate" 0.0;
      +   inherit: "default" 0.0;
      +
      +   map 
      +   {
      +      // Enable Map on the part
      +      on: 1;
      +      // Enable smooth rendering
      +      smooth: 1;
      +      // Enable perspective
      +      perspective_on: 1;
      +
      +      // Apply rotations on the part
      +      rotation.x: 0;
      +      rotation.y: 0;
      +      rotation.z: 0;
      +   }
      +   color: 0 255 0 255; // green
      +}
      +

      This part changes the color to green and defines the map. This statement makes rotations possible on an Edje part. Rotations are done around the x, y or z axes. In this example, the map is enabled and a 0° rotation is applied around each axis.

      +

      Add a state with a rotation around the z axis of 360°.

      +
      description 
      +{
      +   state: "rotate" 1.0;
      +   inherit: "rotate" 0.0;
      +   map.rotation.z: 360;
      +}
      +

      This state inherits from the default state parameters and add a rotation around the z axis.

      +

      Finally add a state to the other button animation grow. Change the size of the animation target and add an offset.

      +
      // The grow state
      +description 
      +{
      +   state: "grow" 0.0;
      +   color: 0 0 255 255; // blue
      +   rel1 
      +   {
      +      relative: 0.2 0.2;
      +      offset: 0.3 0.3;
      +   }
      +   rel2 
      +   {
      +      relative: 0.7 0.4;
      +      offset: 0.3 0.3;
      +   }
      +}
      +

      The last step is to create the programs to make all these states animate.

      +

      To make the rotation animation smoother, create and chain several programs with different durations.

      +

      First create the main one: it goes from the default state to the rotate 0.0 state in 0.2 seconds.

      +

      Note that the states are all named the same way (rotate) but not with the same version. This version allows you to have more than one state with the same name, in fact the actual name of the state is the name plus the version.

      +
      // Change the color of target to green
      +program 
      +{
      +   name: "rotate,target";
      +   source: "btn/rotate";
      +   signal: "mouse,clicked,*";
      +   action: STATE_SET "rotate" 0.0;
      +   target: "atarget";
      +   transition: SIN 0.2;
      +   after: "rotate,target,2";
      +}
      +

      The program starts when the btn/rotate part is clicked with any mouse button. When the animation ends, it calls the next one called rotate,target,2.

      +
      // Rotate 360°
      +program 
      +{
      +   name: "rotate,target,2";
      +   action: STATE_SET "rotate" 1.0;
      +   target: "atarget";
      +   transition: SIN 0.7;
      +   after: "rotate,end";
      +}
      +

      This program sets the part state to rotate 1.0 in 0.7 seconds, and when done calls the next one rotate,end.

      +
      // Go back to the normal
      +program 
      +{
      +   name: "rotate,end";
      +   action: STATE_SET "rotate" 0.0;
      +   target: "atarget";
      +   transition: LINEAR 0.2;
      +}
      +

      rotate,end is the last program of the rotation effect: it sets the state to rotate 0.0 very fast.

      +

      The last program of this example is the grow effect, it switches from one state to another.

      +
      // Grow the target and go back to normal state
      +program 
      +{
      +   name: "grow,target";
      +   source: "btn/grow";
      +   signal: "mouse,clicked,*";
      +   action: STATE_SET "grow" 1.0;
      +   after: "go,default";
      +   target: "atarget";
      +   transition: SINUSOIDAL 1.0;
      +}
      +

      It starts when the btn/grow part is clicked, it goes from the current state to grow 1.0 in one second. It then calls the go,default program. In this program, both size and color change during the transition.

      +

      The go,default program sets the status back default for the animation target.

      +
      // Go back to normal (default) state
      +program 
      +{
      +   name: "go,default";
      +   action: STATE_SET "default" 1.0;
      +   target: "atarget";
      +   transition: SIN 1.0;
      +}
      +
      + + + + +
      + +Go to top + + + + + + + diff --git a/org.tizen.ui.guides/html/native/efl/edje_color_n.htm b/org.tizen.ui.guides/html/native/efl/edje_color_n.htm new file mode 100755 index 0000000..48d272a --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/edje_color_n.htm @@ -0,0 +1,354 @@ + + + + + + + + + + + + + + Using Edje Color Classes + + + + + + +
      +

      Using Edje Color Classes

      + +

      This tutorial demonstrates how you can change the color of 2 or more parts using Edje color classes.

      +

      If a part is assigned with a color class, setting color values to this class causes all those parts to have their colors multiplied by the values. Setting the values to a color class affects all parts within that color class at process level, while at object level, it only affects the parts inside a specified object.

      + +

      Create a simple application with a menu and separate screens for each Edje Animation function:

      + +
        +
      1. In the Tizen IDE, go to Tizen Native project > UI application > EDC and create a new project named colorclass.
      2. + +
      3. Open the colorclass.edc file and replace it with the following code: +
        color_classes 
        +{
        +   color_class 
        +   {
        +      name: "A";
        +      color: 255 255 0 255;
        +      color2: 255 0 0 255;
        +      color3: 0 0 255 255;
        +   }
        +   color_class 
        +   {
        +      name: "B";
        +      color: 0 255 0 255;
        +      color2: 0 0 255 255;
        +      color3: 255 0 0 255;
        +   }
        +   color_class 
        +   {
        +      name: "C";
        +      color: 125 0 0 255;
        +      color2: 255 0 0 255;
        +      color3: 0 0 255 255;
        +   }
        +}
        +
        +collections 
        +{
        +   group 
        +   { 
        +      name: "main";
        +      parts 
        +      {
        +         part 
        +         { 
        +            name: "bg";
        +            type: RECT;
        +            description 
        +            { 
        +               state: "default" 0.0;
        +            }
        +         }
        +         part 
        +         { 
        +            name: "textA";
        +            type: TEXT;
        +            effect: OUTLINE_SHADOW;
        +            description 
        +            { 
        +               state: "default" 0.0;
        +               color_class: "A";
        +               rel1.relative: 0.0 0.0;
        +               rel2.relative: 0.2 0.2;
        +               color2: 255 255 255 255;
        +               color3: 255 255 255 255;
        +               text 
        +               {
        +                  text: "A:";
        +                  size: 44;
        +               }
        +            }
        +         }
        +         part 
        +         { 
        +            name: "textB";
        +            type: TEXT;
        +            effect: OUTLINE_SHADOW;
        +            description 
        +            { 
        +               state: "default" 0.0;
        +               color_class: "B";
        +               rel1.relative: 0.0 0.2;
        +               rel2.relative: 0.2 0.4;
        +               color2: 255 255 255 255;
        +               color3: 255 255 255 255;
        +               text 
        +               {
        +                  text: "B:";
        +                  size: 44;
        +               }
        +            }
        +         }
        +         part 
        +         { 
        +            name: "textC";
        +            type: TEXT;
        +            effect: OUTLINE_SHADOW;
        +            description 
        +            { 
        +               state: "default" 0.0;
        +               color_class: "C";
        +               rel1.relative: 0.0 0.4;
        +               rel2.relative: 0.2 0.6;
        +               color2: 255 255 255 255;
        +               color3: 255 255 255 255;
        +               text 
        +               {
        +                  text: "C:";
        +                  size: 44;
        +               }
        +            }
        +         }
        +         part 
        +         { 
        +            name: "rect1";
        +            type: RECT;
        +            description 
        +            { 
        +               state: "default" 0.0;
        +               color_class: "A";
        +               rel1.relative: 0.2 0.0;
        +               rel2.relative: 0.4 0.2;
        +            }
        +         }
        +         part 
        +         { 
        +            name: "rect2";
        +            type: RECT;
        +            description 
        +            { 
        +               state: "default" 0.0;
        +               color_class: "B";
        +               rel1.relative: 0.4 0.2;
        +               rel2.relative: 0.6 0.4;
        +            }
        +         }
        +         part 
        +         { 
        +            name: "rect3";
        +            type: RECT;
        +            description 
        +            { 
        +               state: "default" 0.0;
        +               color_class: "A";
        +               rel1.relative: 0.6 0.0;
        +               rel2.relative: 0.8 0.2;
        +            }
        +         }
        +         part 
        +         { 
        +            name: "rect4";
        +            type: RECT;
        +            description 
        +            { 
        +               state: "default" 0.0;
        +               color_class: "B";
        +               rel1.relative: 0.8 0.2;
        +               rel2.relative: 1.0 0.4;
        +            }
        +         }
        +         part 
        +         { 
        +            name: "rect5";
        +            type: RECT;
        +            description 
        +            { 
        +               state: "default" 0.0;
        +               color: 125 0 0 255;
        +               color_class: "C";
        +               rel1.relative: 0.6 0.4;
        +               rel2.relative: 0.8 0.6;
        +            }
        +         }
        +         part 
        +         { 
        +            name: "rect6";
        +            type: RECT;
        +            description 
        +            { 
        +               state: "default" 0.0;
        +               color: 255 255 255 255;
        +               color_class: "C";
        +               rel1.relative: 0.8 0.4;
        +               rel2.relative: 1.0 0.6;
        +            }
        +         }
        +         part 
        +         { 
        +            name: "swallow.btn1";
        +            type: SWALLOW;
        +            description 
        +            { 
        +               state: "default" 0.0;
        +               rel1.relative: 0.0 0.8;
        +               rel2.relative: 0.45 1.0;
        +            }
        +         }
        +         part 
        +         { 
        +            name: "swallow.btn2";
        +            type: SWALLOW;
        +            description 
        +            { 
        +               state: "default" 0.0;
        +               rel1.relative: 0.55 0.8;
        +               rel2.relative: 1.0 1.0;
        +            }
        +         }
        +      }
        +   }
        +}
        + +

        Setting the color class of a part causes its colors to be multiplied by color_class color values. To see how the color class affects the shadow and outline colors, set those colors as white in the part:

        + +
        color2: 255 255 255 255;
        +color3: 255 255 255 255;
        + +

        Parts with color_class "C" have different colors because their base colors are different.

        +
      4. + +
      5. Replace the create_base_gui() function with the following code: + +
        static void
        +btn1_cb(void *data, Evas_Object *obj, void *event_info)
        +{
        +   edje_color_class_set("A", rand()%255, rand()%255, rand()%255, 255,
        +                        rand()%255, rand()%255, rand()%255, 255,
        +                        rand()%255, rand()%255, rand()%255, 255);
        +}
        +static void
        +btn2_cb(void *data, Evas_Object *obj, void *event_info)
        +{
        +   edje_color_class_set("B", rand()%255, rand()%255, rand()%255, 255,
        +                        rand()%255, rand()%255, rand()%255, 255,
        +                        rand()%255, rand()%255, rand()%255, 255);
        +}
        +
        +static void
        +create_base_gui(appdata_s *ad)
        +{
        +   char edj_path[PATH_MAX] = {0, };
        +
        +   // Window
        +   ad->win = elm_win_util_standard_add(PACKAGE, PACKAGE);
        +   elm_win_conformant_set(ad->win, EINA_TRUE);
        +   elm_win_autodel_set(ad->win, EINA_TRUE);
        +
        +   if (elm_win_wm_rotation_supported_get(ad->win)) 
        +   {
        +      int rots[4] = { 0, 90, 180, 270 };
        +      elm_win_wm_rotation_available_rotations_set(ad->win, (const int *)(&rots), 4);
        +   }
        +
        +   evas_object_smart_callback_add(ad->win, "delete,request", win_delete_request_cb, NULL);
        +
        +   // Conformant
        +   ad->conform = elm_conformant_add(ad->win);
        +   elm_win_indicator_mode_set(ad->win, ELM_WIN_INDICATOR_SHOW);
        +   elm_win_indicator_opacity_set(ad->win, ELM_WIN_INDICATOR_OPAQUE);
        +   evas_object_size_hint_weight_set(ad->conform, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
        +   elm_win_resize_object_add(ad->win, ad->conform);
        +   evas_object_show(ad->conform);
        +
        +   // Base layout
        +   app_get_resource(EDJ_FILE, edj_path, (int)PATH_MAX);
        +   ad->layout = elm_layout_add(ad->win);
        +   elm_layout_file_set(ad->layout, edj_path, GRP_MAIN);
        +   evas_object_size_hint_weight_set(ad->layout, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
        +   eext_object_event_callback_add(ad->layout, EEXT_CALLBACK_BACK, layout_back_cb, ad);
        +   elm_object_content_set(ad->conform, ad->layout);
        +
        +   // Buttons
        +   ad->btn1 = elm_button_add(ad->win);
        +   elm_object_part_content_set(ad->layout, "swallow.btn1", ad->btn1);
        +   evas_object_smart_callback_add(ad->btn1, "clicked", btn1_cb, ad);
        +   elm_object_part_text_set(ad->btn1, NULL, "Change A");
        +   ad->btn2 = elm_button_add(ad->win);
        +   elm_object_part_content_set(ad->layout, "swallow.btn2", ad->btn2);
        +   evas_object_smart_callback_add(ad->btn2, "clicked", btn2_cb, ad);
        +   elm_object_part_text_set(ad->btn2, NULL, "Change B");
        +
        +   // Show the window
        +   evas_object_show(ad->win);
        +}
        + +

        Pressing the Change A button changes all colors of all parts with color_class set as "A" but does not affect other parts. The actual color, color2, and color3 values remain unchanged but they are multiplied by values from the color class.

        +

        You can omit the color class declaration in the .edc file and still use it in parts. There are no visual effects unless you change the color class in the code. For example, you can comment out the color class "B" and see what happens when you press the Change B button.

        +
      6. + +

        Figure: Edje colorclass application

        +

        Edje colorclass application

        + +
      + + + + + + +
      + +Go to top + + + + + + + diff --git a/org.tizen.ui.guides/html/native/efl/edje_files_n.htm b/org.tizen.ui.guides/html/native/efl/edje_files_n.htm new file mode 100755 index 0000000..55b54b3 --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/edje_files_n.htm @@ -0,0 +1,213 @@ + + + + + + + + + + + + + + Handling Edje Files + + + + + + +
      +

      Handling Edje Files

      + +

      This tutorial demonstrates how you can manage EDJ files. An EDJ file is a specific eet file that collects layouts. The Edje layout is called Style and created using the EDC language. The file that contains the layout collection called Theme.

      + +

      Initializing the Application

      + +

      The following example shows a typical Elementary application that creates a window entitled Genlist Basic Tutorial. It is consisted of a conformant widget that contains a naviframe widget. The genlist goes inside the naviframe.

      + +
      static void
      +create_base_gui(appdata_s *ad)
      +{
      +   char edj_path[PATH_MAX] = {0, };
      +
      +   // Window
      +   ad->win = elm_win_util_standard_add(PACKAGE, PACKAGE);
      +   elm_win_conformant_set(ad->win, EINA_TRUE);
      +   elm_win_autodel_set(ad->win, EINA_TRUE);
      +
      +   if (elm_win_wm_rotation_supported_get(ad->win)) 
      +   {
      +      int rots[4] = {0, 90, 180, 270};
      +      elm_win_wm_rotation_available_rotations_set(ad->win, (const int *)(&rots), 4);
      +   }
      +   evas_object_smart_callback_add(ad->win, "delete,request", win_delete_request_cb, ad);
      +
      +   // Conformant
      +   ad->conform = elm_conformant_add(ad->win);
      +   elm_win_indicator_mode_set(ad->win, ELM_WIN_INDICATOR_SHOW);
      +   elm_win_indicator_opacity_set(ad->win, ELM_WIN_INDICATOR_OPAQUE);
      +   evas_object_size_hint_weight_set(ad->conform, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +   elm_win_resize_object_add(ad->win, ad->conform);
      +   evas_object_show(ad->conform);
      +
      +   // Naviframe
      +   ad->navifr = elm_naviframe_add(ad->win);
      +   elm_object_content_set(ad->conform, ad->navifr);
      +   eext_object_event_callback_add(ad->navifr, EEXT_CALLBACK_BACK, eext_naviframe_back_cb, ad);
      +
      +   // Genlist
      +   ad->itc = elm_genlist_item_class_new();
      +   ad->itc->func.text_get =_genlist_item_text_get;
      +
      +   ad->genlist = elm_genlist_add(ad->win);
      +   evas_object_size_hint_weight_set(ad->genlist, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +   elm_naviframe_item_simple_push(ad->navifr, ad->genlist);
      +
      +   // Show window after base GUI is set up
      +   evas_object_show(ad->win);
      +}
      +
      +static bool
      +app_create(void *data)
      +{
      +   // Initialize UI resources and application data
      +   // If this function returns true, the main loop of application starts
      +   // If this function returns false, the application is terminated
      +   appdata_s *ad = data;
      +
      +   create_base_gui(ad);
      +
      +   return true;
      +}
      + +

      Declare the struct appdata:

      + +
      typedef struct appdata
      +{
      +   Evas_Object *win;
      +   Evas_Object *conform;
      +   Evas_Object *navifr;
      +   Evas_Object *genlist;
      +   Eina_List *list;
      +   Elm_Genlist_Item_Class *itc;
      +} 
      +appdata_s;
      + +

      Loading the Collection List from an EDJ File

      + +

      Edje provides the functionality to manipulate the EDJ files. First, get the list of styles from EDJ file:

      + +
      // Get the collection list from the EDJ file
      +app_get_resource(EDJ_FILE, edj_path, (int)PATH_MAX);
      +ad->list = edje_file_collection_list(edj_path);
      + +

      When you do not use the collection list, delete it:

      + +
      static void
      +win_delete_request_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   appdata_s *ad = data;
      +   // Free the collection list
      +   edje_file_collection_list_free(ad->list);
      +   ui_app_exit();
      +}
      + + + + + + + + + + +
      Note
      The list returned after using the edje_file_collection_list() function must only be deleted using the edje_file_collection_list_free() function.
      + +

      Add the item in the genlist to display the list:

      + +
      EINA_LIST_FOREACH(ad->list, l, str)
      +{
      +   elm_genlist_item_append(ad->genlist, ad->itc, str, NULL, ELM_GENLIST_ITEM_NONE, _genlist_clicked, ad);
      +}
      + + +

      Creating an Edje Object

      + +

      Implement callbacks for the clicked (tapped) event. Check that the required style exists using the edje_file_group_exists() function. The first argument is the path to EDJ file and style name. Create the Edje object and load the given style.

      + +
      static void
      +_genlist_clicked(void *data, Evas_Object *obj, void *event_info)
      +{
      +   appdata_s *ad = data;
      +   Elm_Object_Item *eoi = NULL;
      +   const char *str;
      +   char edj_path[PATH_MAX] = {0, };
      +   Evas_Object *edje_object;
      +
      +   app_get_resource(EDJ_FILE, edj_path, (int)PATH_MAX);
      +   eoi = elm_genlist_selected_item_get(obj);
      +
      +   str = elm_object_item_part_text_get(eoi, "elm.text");
      +   // Check whether a group matching glob exists in an edje file
      +   // If there is no matching group
      +   if (!edje_file_group_exists(edj_path, str)) return;
      +
      +   // Load the given style to the object
      +   edje_object = edje_object_add(evas_object_evas_get(ad->win));
      +   edje_object_file_set(edje_object, edj_path, str);
      +   // Check object loading errors
      +   if (edje_object_load_error_get(edje_object) != EDJE_LOAD_ERROR_NONE)
      +   {
      +      evas_object_del(edje_object);
      +
      +      return;
      +   }
      +   evas_object_size_hint_weight_set(edje_object, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +   elm_naviframe_item_simple_push(ad->navifr, edje_object);
      +}
      + + + + +
      + +Go to top + + + + + + + diff --git a/org.tizen.ui.guides/html/native/efl/edje_intro_n.htm b/org.tizen.ui.guides/html/native/efl/edje_intro_n.htm new file mode 100755 index 0000000..dd8df7b --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/edje_intro_n.htm @@ -0,0 +1,285 @@ + + + + + + + + + + + + + Introduction to EDC Programming + + + + + +
      + +

      Introduction to EDC Programming

      + + + +

      This programming guide shows you how to write an EDC file that can be used to theme a Tizen application. It describes concepts about parts positioning and resizing. It also explains part animations that can be done through programs.

      + +

      What is an EDC File?

      + +

      An EDC file stands for Edje data collection. It is a text file that contains special code format describing the position, size, and other parameters of graphical elements that compose the visual aspect of your application. In addition to graphical elements, it can also handle sounds.

      + +

      The syntax for the Edje data collection files follows a simple structure of "blocks { .. }" that can contain "properties: ..", more blocks, or both.

      + +

      An EDC file has the ".edc" extension.

      + +

      Compiling the EDC File

      +

      EDC file needs to be compiled into a ".edj" file using Edje library tools. After compiling the ".edj" file can be used by a native Tizen application.

      + +

      Here is an example about compiling helloworld.edc to ".edj" file using edje_cc tool:

      + +
      +$ edje_cc helloworld.edc
      +
      + +

      This command creates a helloworld.edj file.

      + +

      An EDC file can use external files such as sounds, images, or fonts. The path to these resources are passed to the edje_cc tool so that they are included in the final ".edj" file.

      + +
      +$ edje_cc -sd $SOUNDS_DIR -fd $FONTS_DIR -id $IMAGES_DIR
      +
      + +

      SOUNDS_DIR, FONTS_DIR, and IMAGES_DIR are the paths for sounds, fonts, and images resources respectively.

      + +

      Tizen SDK calls edje_cc during the project building if it finds an EDC source file in the ./res/edje/ directory.

      + +
      +Building file: ../res/edje/helloworld.edc
      +Invoking: EDC Resource Compiler
      +edje_cc -sd ../edje/sounds -fd ../edje/fonts -id ../edje/images ../res/edje/helloworld.edc ../res/edje/helloworld.edj
      +
      + + +

      The Tizen SDK compilation log extract shows you that if your EDC file uses pictures, they must be copied to the ./edje/images directory. Fonts and sounds go to the ./edje/fonts and ./edje/sounds directory respectively. The SDK builds the helloworld.edj file in the ./res/edje/ folder.

      + +

      Writing a Simple EDC File

      +

      The code example below shows you the structure of an EDC file. It is a collection of groups that contain parts and programs.

      + +
      +collections 
      +{
      +   group 
      +   {
      +      name: "my_group";
      +      parts {}
      +      programs {}
      +   }
      +}
      +
      + +

      Groups are identified with a name, parts correspond to the graphical elements. Each one of them can have several states that describe a specific position, size, and visual aspect. Programs contain the program code, such as interaction with the main application through signals. Also animations are defined here (changing a part state using an animated transition).

      + +

      The description field is where the state of a part is written.

      + +
      +part
      +{
      +   description 
      +   { 
      +      state: "default" 0.0;
      +   }
      +   description 
      +   { 
      +      state: "state1" 0.0;
      +   }
      +   description 
      +   { 
      +      state: "state2" 0.0;
      +   }
      +}
      +
      + +

      As an example, here is a simple EDC file that contains only one part and one program. The part is a rectangle with blue state and red state, the program changes the state from blue to red when user clicks on the rectangle.

      + +
      +collections 
      +{
      +   group 
      +   {
      +      name: "example";
      +      parts 
      +      {
      +         // create the part
      +         part 
      +         { 
      +            name: "rectangle";
      +            // set the type to RECT (rectangle)
      +            type: RECT;
      +            // default state (blue color)
      +            description 
      +            { 
      +               state: "default" 0.0;
      +               align: 0.0 0.0;
      +               // blue color
      +               color: 0 0 255 255;
      +            }
      +            // second state (red color)
      +            description 
      +            { 
      +               state: "red" 0.0;
      +               align: 0.0 0.0;
      +               // red color
      +               color: 255 0 0 255;
      +            }
      +         }
      +      }
      +      programs 
      +      {
      +         // create a program
      +         program 
      +         { 
      +            name: "change_color";
      +            // program is triggered on mouse click
      +            signal: "mouse,clicked,*";
      +            source: "*";
      +            // set the red state of the "rectangle" part
      +            action: STATE_SET "red" 0.0;
      +            target: "rectangle";
      +         }
      +      }
      +   }
      +}
      +
      + +

      A program is triggered when receiving a signal from a specific source (here all the sources are taken into account). When launched, it does the action (changing the state of a part) on the target (the rectangle).

      + +

      Quick How-tos

      + +
      • Adding an element on the screen +

        Add a new part inside the parts block.

      • +
      • Using an image +

        List the image in the images block, make sure the part has type "IMAGE" and set the normal property inside description.image of part.

      • +
      • Using the same color definitions across multiple elements +

        Define a color class and set the description.color_class property.

      • +
      • Positioning or resizing a part (relative and absolute positioning) +

        Fill in the rel1 and rel2 structures inside the description block.

      • +
      • Hiding a part +

        Set the visible property to 0.

      • +
      • Animating a part +
        1. Create several description blocks inside your part and give each of them a different value for state. Set one description for the initial state and one for the end state.

        2. +
        3. Create a program with an action that is STATE_SET "end_state" 0.0; and with a target that is the name of the part. You can also set a non-default transition.

        4. +
        5. When defining the second description, inherit from the first part in order to re-use the values which are already defined.

        6. +
        7. The after property of the program block is used to trigger another program after the animation is done. It can be used to trigger another animation or to emit a signal to the C part of the program.

      • +
      • Making a genlist item theme +

        Create a group with one part element for each part that can be filed from the C code and set the items properties inside the group element:

        + +
        +items: "texts" "text_part_1 text_part_2";
        +items: "icons" "image_part_1 image_part_2";
        +
        +

        On the C side, the text_get and content_get callback are called respectively with text_part_1 and text_part_2, and image_part_1 and image_part_2.

      • + +
      • Using the image masking effect +

        EDC files support an image masking effect that applies the transparency of a mask image to a content object.

        + +

        Figure: Masking effect

        +

        Masking effect

        + +

        To use the image masking effect, add 2 new parts inside the parts block used as a content and mask. Set the mask using the clip_to keyword in the content part.

        +
        +part 
        +{
        +   name: "bg";
        +   type: RECT;
        +   description 
        +   {
        +      state: "default" 0.0;
        +   }
        +}
        +part 
        +{
        +   name: "text";
        +   type: TEXTBLOCK;
        +   clip_to: "mask";
        +   description 
        +   {
        +      state: "default" 0.0;
        +      align: 0.5 0.5;
        +      text 
        +      {
        +         style: "text_style";
        +         text: "TEXT<br>WITH<br>MASK";
        +      }
        +   }
        +}
        +part 
        +{
        +   name: "mask";
        +   type: IMAGE;
        +   description 
        +   {
        +      state: "default" 0.0;
        +      image.normal: "mask.png";
        +   }
        +}
        +
        +

        The content part is cropped off in the mask shape, which depends on the alpha value per pixel. The content part can be almost any type in the EDC files, but the mask part can only be the IMAGE type.

        +
      • +
      + + + + + + + + + + +
      Note
      Except as noted, this content is licensed under LGPLv2.1+.
      + + + +
      + +Go to top + + + + + + + \ No newline at end of file diff --git a/org.tizen.ui.guides/html/native/efl/edje_manage_animation_n.htm b/org.tizen.ui.guides/html/native/efl/edje_manage_animation_n.htm new file mode 100755 index 0000000..23049bf --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/edje_manage_animation_n.htm @@ -0,0 +1,728 @@ + + + + + + + + + + + + + Edje Animations + + + + + +
      + +

      Edje Animations

      + +

      This tutorial demonstrates how you can turn Edje animations on and off, pause, stop and resume them, and check the status of Edje parts.

      + + +

      Creating the Application Layout

      + +

      Create a simple application with a menu and separate screens for each Edje Animation function:

      + +
        +
      1. +

        Create a simple main layout with a swallow for demo animation and another for controls:

        + +
        collections 
        +{
        +   group 
        +   {
        +      name: "demo";
        +      parts 
        +      {
        +         part 
        +         {
        +            name: "swallow.demo";
        +            type: SWALLOW;
        +            description 
        +            {
        +               state: "default" 0.0;
        +               rel2 
        +               {
        +                  relative: 1.0 0.0;
        +                  to_y: "swallow.control";
        +               }
        +            }
        +         }
        +         part 
        +         {
        +            name: "swallow.control";
        +            type: SWALLOW;
        +            description 
        +            {
        +               state: "default" 0.0;
        +               rel1 
        +               {
        +                  relative: 0.0 0.8;
        +               }
        +            }
        +         }
        +      }
        +   }
        +}
        +
        +
      2. + +
      3. +

        Create a group for the cycled animation:

        +
        group 
        +{
        +   name: "cycled_animation";
        +   parts 
        +   {
        +      part 
        +      {
        +         name: "bg";
        +         type: RECT;
        +         description 
        +         {
        +            state: "default" 0.0;
        +            color: 100 100 100 255;
        +         }
        +         description 
        +         {
        +            state: "clicked" 0.0;
        +            color: 200 100 100 255;
        +         }
        +      }
        +      part 
        +      {
        +         name: "a";
        +         type: RECT;
        +         description 
        +         {
        +            state: "default" 0.0;
        +            color: 0 255 0 255;
        +            rel2 
        +            {
        +               relative: 0.3 0.3;
        +            }
        +         }
        +         description 
        +         {
        +            state: "red" 0.0;
        +            color: 255 0 0 255;
        +            rel1 
        +            {
        +               relative: 0.35 0.7;
        +            }
        +            rel2 
        +            {
        +               relative: 0.65 1.0;
        +            }
        +         }
        +         description 
        +         {
        +            state: "blue" 0.0;
        +            color: 0 0 255 255;
        +            rel1 
        +            {
        +               relative: 0.7 0.0;
        +            }
        +            rel2 
        +            {
        +               relative: 1.0 0.3;
        +            }
        +         }
        +      }
        +   }
        +   programs 
        +   {
        +      program 
        +      {
        +         name: "bg_click";
        +         signal: "mouse,clicked,*";
        +         source: "bg";
        +         action: STATE_SET "clicked" 0.0;
        +         target: "bg";
        +      }
        +      program 
        +      {
        +         name: "step1";
        +         signal: "load";
        +         source: "";
        +         action: STATE_SET "red" 0.0;
        +         transition: LINEAR 1.0;
        +         target: "a";
        +         after: "step2";
        +      }
        +      program 
        +      {
        +         name: "step2";
        +         action: STATE_SET "blue" 0.0;
        +         transition: LINEAR 1.0;
        +         target: "a";
        +         after: "step3";
        +      }
        +      program 
        +      {
        +         name: "step3";
        +         action: STATE_SET "default" 0.0;
        +         transition: LINEAR 1.0;
        +         target: "a";
        +         after: "step1";
        +      }
        +   }
        +}
        +
      4. + +
      5. +

        Create another group for animation that can be activated by clicking:

        +
        group 
        +{
        +   name: "clickme";
        +   parts 
        +   {
        +      part 
        +      {
        +         name: "bg";
        +         type: RECT;
        +         description 
        +         {
        +            state: "default" 0.0;
        +            color: 100 100 100 255;
        +         }
        +      }
        +      part 
        +      {
        +         name: "text_bg";
        +         type: RECT;
        +         description 
        +         {
        +            state: "default" 0.0;
        +            rel1 
        +            {
        +               to: "text";
        +            }
        +            rel2 
        +            {
        +               to: "text";
        +            }
        +         }
        +      }
        +      part 
        +      {
        +         name: "text";
        +         type: TEXT;
        +         description 
        +         {
        +            state: "default" 0.0;
        +            align: 0.0 0.0;
        +            color: 0 0 0 255;
        +            text 
        +            {
        +               text: ":-)";
        +               font: "Sans";
        +               size: 42;
        +               min: 1 1;
        +               max: 1 1;
        +            }
        +         }
        +         description 
        +         {
        +            state: "state2" 0.0;
        +            inherit: "default" 0.0;
        +            align: 1.0 1.0;
        +            text.text: ":-D";
        +         }
        +      }
        +      part 
        +      {
        +         name: "text_bg2";
        +         type: RECT;
        +         description 
        +         {
        +            state: "default" 0.0;
        +            color: 0 200 0 255;
        +            rel1 
        +            {
        +               to: "text2";
        +            }
        +            rel2 
        +            {
        +               to: "text2";
        +            }
        +         }
        +         description 
        +         {
        +            state: "state2" 0.0;
        +            inherit: "default" 0.0;
        +            color: 200 0 0 255;
        +         }
        +      }
        +      part 
        +      {
        +         name: "text2";
        +         type: TEXT;
        +         description 
        +         {
        +            state: "default" 0.0;
        +            align: 0.0 1.0;
        +            visible: 0;
        +            text 
        +            {
        +               text: "Click me";
        +               font: "Sans";
        +               size: 42;
        +               min: 1 1;
        +               max: 1 1;
        +            }
        +         }
        +         description 
        +         {
        +            state: "state2" 0.0;
        +            inherit: "default" 0.0;
        +            visible: 1;
        +         }
        +      }
        +      part 
        +      {
        +         name: "text3";
        +         type: TEXT;
        +         description 
        +         {
        +            state: "default" 0.0;
        +            align: 0.0 1.0;
        +            visible: 1;
        +            text 
        +            {
        +               text: "Click me";
        +               font: "Sans";
        +               size: 42;
        +               min: 1 1;
        +               max: 1 1;
        +            }
        +         }
        +         description 
        +         {
        +            state: "state2" 0.0;
        +            inherit: "default" 0.0;
        +            visible: 0;
        +         }
        +      }
        +   }
        +   programs 
        +   {
        +      program 
        +      {
        +         name: "clicked";
        +         signal: "mouse,clicked,1";
        +         source: "text3";
        +         action: STATE_SET "state2" 0.00;
        +         transition: LINEAR 3.00000;
        +         target: "text";
        +         target: "text2";
        +         target: "text3";
        +         target: "text_bg2";
        +      }
        +      program 
        +      {
        +         name: "return";
        +         signal: "mouse,clicked,1";
        +         source: "text2";
        +         action: STATE_SET "default" 0.00;
        +         transition: LINEAR 1.00000;
        +         target: "text";
        +         target: "text2";
        +         target: "text3";
        +         target: "text_bg2";
        +      }
        +   }
        +}
        +
      6. +
      + +

      Creating the Application Logic

      + +
        +
      1. Create new project named test.
      2. + +
      3. Add 2 new files to the application project:edje_animation.h and edje_animation.c.
      4. +
      5. To access the application data from the newly created files, move the appdata_s structure from the test.c file to the test.h file and remove the static specifier.
      6. + +
      7. Add the following code to the edje_animation.h file: +
        #ifndef __edje_animation_H__
        +#define __edje_animation_H__
        +#include "test.h"
        +
        +typedef struct _edje_animation_item_s 
        +{
        +   const char *name;
        +   Evas_Object* (*func)(appdata_s *ap);
        +} 
        +Edje_Animation_Menu_Item;
        +
        +#endif // __edje_animation_H__
        + +

        This structure will define menu items and their callbacks.

        +
      8. + +
      9. +

        Create a global menu array in the edje_animation.c file and fill it with necessary items:

        +
        Edje_Animation_Menu_Item edje_animation_items[] =
        +{
        +   {"test1", _test1_func },
        +   {"test2", _test2_func },
        +
        +   {NULL, NULL } // Do not delete
        +};
        +
      10. + +
      11. +

        Use the array to fill the main menu:

        +
        extern Edje_Animation_Menu_Item edje_animation_items[];
        +
        +static void
        +create_base_gui(appdata_s *ad)
        +{
        +   // Genlist
        +   ad->itc = elm_genlist_item_class_new();
        +   ad->itc->func.text_get =_genlist_item_text_get;
        +   ad->genlist = elm_genlist_add(ad->win);
        +   evas_object_size_hint_weight_set(ad->genlist, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
        +
        +   int i;
        +   Elm_Object_Item *eoi = NULL;
        +
        +   for (i = 0; edje_animation_items[i].name; ++i)
        +   {
        +      eoi = elm_genlist_item_append(ad->genlist, ad->itc, edje_animation_items[i].name, NULL,
        +                                    ELM_GENLIST_ITEM_NONE, _genlist_clicked, ad);
        +      elm_object_item_data_set(eoi, (void *)&edje_animation_items[i]);
        +   }
        +}
        +
      12. + +
      13. All examples use the same basic layout: +
        static void
        +app_get_resource(const char *edj_file_in, char *edj_path_out, int edj_path_max)
        +{
        +   char *res_path = app_get_resource_path();
        +   if (res_path) 
        +   {
        +        snprintf(edj_path_out, edj_path_max, "%s%s", res_path, edj_file_in);
        +        free(res_path);
        +   }
        +}
        +
        +static void
        +_example_layout_create(appdata_s *ad,
        +                       const char *layout_group,
        +                       const char *demo_group,
        +                       Evas_Object **layout_out,
        +                       Evas_Object **animation_out)
        +{
        +   char edj_path[PATH_MAX] = {0, };
        +
        +   app_get_resource(EDJ_FILE, edj_path, (int)PATH_MAX);
        +
        +   *layout_out = elm_layout_add(ad->win);
        +   elm_layout_file_set(*layout_out, edj_path, layout_group);
        +   evas_object_size_hint_weight_set(*layout_out, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
        +
        +   *animation_out = edje_object_add(evas_object_evas_get(ad->win));
        +   edje_object_file_set(*animation_out, edj_path, demo_group);
        +   evas_object_size_hint_weight_set(*animation_out, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
        +   elm_layout_content_set(*layout_out, SWALLOW_DEMO, *animation_out);
        +   evas_object_show(*animation_out);
        +}
        +
      14. + +
      15. You can try out the following operations to see how the application works: + +
          +
        • Check the time for each frame. + +

          The edje_frametime_get() function allows you to check how much time is elapsed for single frame. This is a value of an internal parameter and not actual frame time. You can change it using the edje_frametime_set() function.

          + + + + + + + + + + +
          Note
          Changing the frame time affects all objects on the same canvas, not only on the given one.
          + +

          Use the edje_frametime_get() function and edje_frametime_set() function in the edje_animation.c file:

          +
          // edje_frametime_set/get
          +static void
          +_frametime_test_spinner_changed_cb(void *data, Evas_Object *obj, void *event_info)
          +{
          +   edje_frametime_set(elm_spinner_value_get(obj));
          +}
          +
          +Evas_Object *
          +frametime_test(appdata_s *ad)
          +{
          +   Evas_Object *layout, *animation, *spinner;
          +   _example_layout_create(ad, GRP_DEMO, GRP_CYCLED_ANIM, &layout, &animation);
          +
          +   spinner = elm_spinner_add(ad->win);
          +   elm_spinner_label_format_set(spinner, "Frame_t: %1.3f");
          +   double framerate = edje_frametime_get();
          +   elm_spinner_min_max_set(spinner, 0.001, 2.0);
          +   elm_spinner_step_set(spinner, 0.005);
          +   elm_spinner_value_set(spinner, framerate);
          +   evas_object_smart_callback_add(spinner, "changed", _frametime_test_spinner_changed_cb, NULL);
          +   elm_layout_content_set(layout, SWALLOW_CONTROL, spinner);
          +   evas_object_show(spinner);
          +
          +   return layout;
          +}
          +
          +Edje_Animation_Menu_Item edje_animation_items[] =
          +{
          +   {"frametime test", frametime_test},
          +
          +   {NULL, NULL}
          +};
          + +

          The spinner displays the current frame time value and enables changing it. Extreme values (> 0.9) are affecting animation.

          + +

          Figure: Displaying the frame time

          +

          Displaying the frame time

          + +
        • + +
        • Pause and resume animation and check its status. + +

          The edje_object_play_set() function allows you to pause or resume animation for a given object. A resumed animation starts from the same point.

          +

          To check whether the animation is paused, use the edje_object_play_get() function.

          + +
          // edje_object_play_set/get
          +static void
          +_play_test_button_cb(void *data, Evas_Object *obj, void *event_info)
          +{
          +   Evas_Object *anim = data;
          +   if (edje_object_play_get(anim))
          +   {
          +      edje_object_play_set(anim, EINA_FALSE);
          +      elm_object_text_set(obj, "Play");
          +   }
          +   else
          +   {
          +      edje_object_play_set(anim, EINA_TRUE);
          +      elm_object_text_set(obj, "Pause");
          +   }
          +}
          +
          +Evas_Object *
          +play_test(appdata_s *ad)
          +{
          +   Evas_Object *layout, *animation, *button;
          +   _example_layout_create(ad, GRP_DEMO, GRP_CYCLED_ANIM, &layout, &animation);
          +   button = elm_button_add(ad->win);
          +   elm_object_text_set(button, "Pause");
          +   evas_object_smart_callback_add(button, "clicked", _play_test_button_cb, animation);
          +   elm_layout_content_set(layout, SWALLOW_CONTROL, button);
          +   evas_object_show(button);
          +
          +   return layout;
          +}
          +
          +Edje_Animation_Menu_Item edje_animation_items[] =
          +{
          +   {"frametime test", frametime_test},
          +   {"play test", play_test},
          +   
          +   {NULL, NULL}
          +};
          +
        • + +
        • Stop the animation. + +

          The edje_object_freeze() function allows you to stop animation rendering. This function puts all changes on hold. Successive freezes are nested, requiring an equal number of thaws. Using the edje_object_thaw() function, you can apply all changes immediately.

          + +
          // edje_object_freeze/thaw
          +static void
          +_freeze_test_button_cb(void *data, Evas_Object *obj, void *event_info)
          +{
          +   Evas_Object *anim = data;
          +   static int i = 0;
          +   if(!i)
          +   {
          +      i = edje_object_freeze(anim);
          +      elm_object_text_set(obj, "Thaw");
          +   }
          +   else
          +   {
          +      i = edje_object_thaw(anim);
          +      elm_object_text_set(obj, "Freeze");
          +   }
          +}
          +
          +Evas_Object *
          +freeze_test(appdata_s *ad)
          +{
          +   Evas_Object *layout, *animation, *button;
          +   _example_layout_create(ad, GRP_DEMO, GRP_CYCLED_ANIM, &layout, &animation);
          +
          +   button = elm_button_add(ad->win);
          +   elm_object_text_set(button, "Freeze");
          +   evas_object_smart_callback_add(button, "clicked", _freeze_test_button_cb, animation);
          +   elm_layout_content_set(layout, SWALLOW_CONTROL, button);
          +   evas_object_show(button);
          +
          +   return layout;
          +}
          +
          +Edje_Animation_Menu_Item edje_animation_items[] =
          +{
          +   {"frametime test", frametime_test},
          +   {"play test", play_test},
          +   {"freeze/thaw test", freeze_test},
          +
          +   {NULL, NULL}
          +};
          + +

          The edje_freeze() function and edje_thaw() function freeze or thaw all objects in the entire application.

          +
        • + +
        • Enable and disable the animation. + +

          All transitions in edje programs are ignored and parts go directly to their final states.

          + +
          // edje_object_animation_set/get
          +static void
          +_animation_test_button_cb(void *data, Evas_Object *obj, void *event_info)
          +{
          +   Evas_Object *anim = data;
          +   if (edje_object_animation_get(anim))
          +   {
          +      edje_object_animation_set(anim, EINA_FALSE);
          +      elm_object_text_set(obj, "Turn animation on");
          +   }
          +   else
          +   {
          +      edje_object_animation_set(anim, EINA_TRUE);
          +      elm_object_text_set(obj, "Turn animation off");
          +   }
          +}
          +
          +Evas_Object *
          +animation_test(appdata_s *ad)
          +{
          +   Evas_Object *layout, *animation, *button;
          +   _example_layout_create(ad, GRP_DEMO, GRP_CLICKME, &layout, &animation);
          +
          +   button = elm_button_add(ad->win);
          +   elm_object_text_set(button, "Turn animation off");
          +   evas_object_smart_callback_add(button, "clicked", _animation_test_button_cb, animation);
          +   elm_layout_content_set(layout, SWALLOW_CONTROL, button);
          +   evas_object_show(button);
          +
          +   return layout;
          +}
          +
          +Edje_Animation_Menu_Item edje_animation_items[] =
          +{
          +   {"frametime test", frametime_test},
          +   {"play test", play_test},
          +   {"freeze/thaw test", freeze_test},
          +   {"animation test", animation_test},
          +
          +   {NULL, NULL}
          +};
          +
        • + +
        • Get the current state of given part. + +

          Parts that are in transition return the transition's starting state.

          + +
          // edje_object_part_state_get
          +static void
          +_state_get_test_button_cb(void *data, Evas_Object *obj, void *event_info)
          +{
          +   Evas_Object *anim = data;
          +   const char *state;
          +   double state_val = 0;
          +   state = edje_object_part_state_get(anim, "text", &state_val);
          +   edje_object_part_text_set(anim, "text", state);
          +}
          +
          +Evas_Object *
          +state_get_test(appdata_s *ad)
          +{
          +   Evas_Object *layout, *animation, *button;
          +   _example_layout_create(ad, GRP_DEMO, GRP_CLICKME, &layout, &animation);
          +
          +   button = elm_button_add(ad->win);
          +   elm_object_text_set(button, "Get state");
          +   evas_object_smart_callback_add(button, "clicked", _state_get_test_button_cb, animation);
          +   elm_layout_content_set(layout, SWALLOW_CONTROL, button);
          +   evas_object_show(button);
          +
          +   return layout;
          +}
          +
          +Edje_Animation_Menu_Item edje_animation_items[] =
          +{
          +   {"frametime test", frametime_test},
          +   {"play test", play_test},
          +   {"freeze/thaw test", freeze_test},
          +   {"animation test", animation_test},
          +   {"part state get test", state_get_test},
          +
          +   {NULL, NULL}
          +};
          +
        • +
        +
      16. +
      + + + + + + +
      + +Go to top + + + + + + + \ No newline at end of file diff --git a/org.tizen.ui.guides/html/native/efl/edje_message_signal_n.htm b/org.tizen.ui.guides/html/native/efl/edje_message_signal_n.htm new file mode 100755 index 0000000..958a3fe --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/edje_message_signal_n.htm @@ -0,0 +1,457 @@ + + + + + + + + + + + + + Managing Signals and Messages + + + + + +
      + +

      Managing Signals and Messages

      + + +

      Edje objects have 2 communication interfaces between the application logic (code) and GUI (theme). You can either emit a signal from the code to the theme, or create handles for the signals emitted from the theme. Signals are identified by strings. With Edje messages, you can communicate values, such as strings, float numbers, and integer numbers. Messages can also be identified by integer numbers.

      + + +

      Signals

      +

      You can emit signals from code to a theme, or create handles for the signals emitted from themes. Signals are identified by strings.

      + +

      Using signals in the EDC file is simple. Create a program and set the signal name to the signal attribute.

      + +
      +group 
      +{ 
      +   name: "main";
      +   parts 
      +   {
      +      part 
      +      { 
      +         name: "rect1";
      +         type: RECT;
      +         description 
      +         { 
      +            state: "default" 0.0;
      +            min: 100 100;
      +            max: 100 100;
      +            color: 255 0 0 255;
      +         }
      +         description 
      +         { 
      +            state: "default" 1.0;
      +            min: 100 100;
      +            max: 100 100;
      +            color: 0 0 255 255;
      +         }
      +      }
      +      part 
      +      { 
      +         name: "swallow.check";
      +         type: SWALLOW;
      +         description 
      +         { 
      +            state: "default" 0.0;
      +            align: 0.5 0.0;
      +            rel2 
      +            {
      +               relative: 0.0 0.0;
      +               to_x: "swallow.slider_ver";
      +            }
      +         }
      +      }
      +   }
      +   programs 
      +   {
      +      program 
      +      { 
      +         name: "to_default_0";
      +         signal: "to,state,default,0";
      +         action: STATE_SET "default" 0.00;
      +         transition: ACCELERATE 0.5 CURRENT;
      +         target: "rect1";
      +      }
      +      program 
      +      { 
      +         name: "to_default_1";
      +         signal: "to,state,default,1";
      +         action: STATE_SET "default" 1.00;
      +         transition: ACCELERATE 0.5 CURRENT;
      +         target: "rect1";
      +      }
      +   }
      +}
      +
      + +

      Emitting Signals from the C Code

      + +

      Create the Edje Object and widget check. When a changed event is triggered, a signal is emitted from the C code to the EDC file.

      + +
      +static void
      +create_base_gui(appdata_s *ad)
      +{
      +   char edj_path[PATH_MAX] = {0, };
      +   
      +   // Window
      +   ad->win = elm_win_util_standard_add(PACKAGE, PACKAGE);
      +   elm_win_conformant_set(ad->win, EINA_TRUE);
      +   elm_win_autodel_set(ad->win, EINA_TRUE);
      +
      +   if (elm_win_wm_rotation_supported_get(ad->win)) 
      +   {
      +      int rots[4] = { 0, 90, 180, 270 };
      +      elm_win_wm_rotation_available_rotations_set(ad->win, (const int *)(&rots), 4);
      +   }
      +
      +   evas_object_smart_callback_add(ad->win, "delete,request", win_delete_request_cb, NULL);
      +   eext_object_event_callback_add(ad->win, EEXT_CALLBACK_BACK, win_back_cb, ad);
      +
      +   // Conformant
      +   ad->conform = elm_conformant_add(ad->win);
      +   elm_win_indicator_mode_set(ad->win, ELM_WIN_INDICATOR_SHOW);
      +   elm_win_indicator_opacity_set(ad->win, ELM_WIN_INDICATOR_OPAQUE);
      +   evas_object_size_hint_weight_set(ad->conform, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +   elm_win_resize_object_add(ad->win, ad->conform);
      +   evas_object_show(ad->conform);
      +
      +   // Base layout
      +   app_get_resource(EDJ_FILE, edj_path, (int)PATH_MAX);
      +   ad->edje_object = edje_object_add(evas_object_evas_get(ad->win));
      +   edje_object_file_set(ad->edje_object, edj_path, GRP_MAIN);
      +   evas_object_size_hint_weight_set(ad->edje_object, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +   
      +   ad->check = elm_check_add(ad->win);
      +   edje_object_part_swallow(ad->edje_object, "swallow.check", ad->check);
      +   evas_object_smart_callback_add(ad->check, "changed", _check_toggled, ad);
      +
      +   elm_object_content_set(ad->conform, ad->edje_object);
      +   // Show the window
      +   evas_object_show(ad->win);
      +}
      +
      + +

      The following figure displays the result.

      + +

      Figure: Signal implemented on the screen

      +

      Signal implemented on the screen

      + +

      The following example implements the callback for the changed event from the widget check.

      +
      +static void
      +_check_toggled(void *data, Evas_Object *obj, void *event_info)
      +{
      +   appdata_s *ad = data;
      +
      +   if (elm_check_state_get(obj))
      +      edje_object_signal_emit(ad->edje_object, "to,state,default,1", "");
      +   else
      +      edje_object_signal_emit(ad->edje_object, "to,state,default,0", "");
      +}
      +
      + +

      The following figure displays the result.

      + +

      Figure: Widget check status changed

      +

      Widget check status changed

      + + +

      Messages

      + +

      Edje messages are used for communication between code and a given Edje object's theme. With messages, you can communicate values, such as strings, float numbers, and integer numbers. Messages can also be identified by integer numbers.

      + +

      In the following example, the rect1 part is made draggable and 2 sliders added to change the part position.

      + +
      +group 
      +{ 
      +   name: "main";
      +   parts 
      +   {
      +      part 
      +      { 
      +         name: "drag_area";
      +         type: RECT;
      +         description 
      +         { 
      +            state: "default" 0.0;
      +            rel1 
      +            {
      +               relative: 0.0 1.0;
      +               to_y: "swallow.check";
      +            }
      +            rel2 
      +            {
      +               relative: 0.0 0.0;
      +               to_x: "swallow.slider_ver";
      +               to_y: "swallow.slider_hor";
      +            }
      +         }
      +      }
      +      part 
      +      { 
      +         name: "rect1";
      +         type: RECT;
      +         dragable 
      +         {
      +            x: 1 1 1;
      +            y: 1 1 1;
      +            confine: "drag_area";
      +         }
      +         description 
      +         { 
      +            state: "default" 0.0;
      +            min: 100 100;
      +            max: 100 100;
      +            color: 255 0 0 255;
      +         }
      +         description { state: "default" 1.0;
      +            min: 100 100;
      +            max: 100 100;
      +            color: 0 0 255 255;
      +         }
      +      }
      +      part 
      +      { 
      +         name: "swallow.check";
      +         type: SWALLOW;
      +         description 
      +         { 
      +            state: "default" 0.0;
      +            align: 0.5 0.0;
      +            rel2 
      +            {
      +               relative: 0.0 0.0;
      +               to_x: "swallow.slider_ver";
      +            }
      +         }
      +      }
      +      part 
      +      { 
      +         name: "swallow.slider_ver";
      +         type: SWALLOW;
      +         description 
      +         { 
      +            state: "default" 0.0;
      +            align: 1.0 0.5;
      +            rel1 
      +            {
      +               relative: 1.0 1.0;
      +               to_y: "swallow.check";
      +            }
      +            rel2 
      +            {
      +               relative: 1.0 0.0;
      +               to_y: "swallow.slider_hor";
      +            }
      +         }
      +      }
      +      part 
      +      { 
      +         name: "swallow.slider_hor";
      +         type: SWALLOW;
      +         description 
      +         { 
      +            state: "default" 0.0;
      +            align: 0.5 1.0;
      +            rel1 
      +            {
      +               relative: 0.0 1.0;
      +            }
      +            rel2 
      +            {
      +               relative: 0.0 1.0;
      +               to_x: "swallow.slider_ver";
      +            }
      +         }
      +      }
      +   }
      +   programs 
      +   {
      +      program 
      +      { 
      +         name: "to_default_0";
      +         signal: "to,state,default,0";
      +         action: STATE_SET "default" 0.00;
      +         transition: ACCELERATE 0.5 CURRENT;
      +         target: "rect1";
      +      }
      +      program 
      +      { 
      +         name: "to_default_1";
      +         signal: "to,state,default,1";
      +         action: STATE_SET "default" 1.00;
      +         transition: ACCELERATE 0.5 CURRENT;
      +         target: "rect1";
      +      }
      +      program 
      +      {
      +         signal: "drag";
      +         source: "rect1";
      +         script 
      +         {
      +               new Float:x, Float:y;
      +               get_drag(PART:"rect1", x, y);
      +               send_message(MSG_FLOAT, 2, x);
      +               send_message(MSG_FLOAT, 3, y);
      +         }
      +      }
      +   }
      +}
      +
      + +

      Add the sliders:

      + +
      +ad->slider_ver = elm_slider_add(ad->win);
      +edje_object_part_swallow(ad->edje_object, "swallow.slider_ver", ad->slider_ver);
      +elm_slider_horizontal_set(ad->slider_ver, EINA_FALSE);
      +evas_object_smart_callback_add(ad->slider_ver, "changed", _slider_changed, ad);
      +
      +ad->slider_hor = elm_slider_add(ad->win);
      +evas_object_smart_callback_add(ad->slider_hor, "changed", _slider_changed, ad);
      +
      + +

      The following figure displays the result.

      +

      Figure: Sliders added

      +

      Sliders added

      + +

      To handle the message in the Style, add the following script to the EDC file:

      + +
      +group 
      +{ 
      +   name: "main";
      +   script 
      +   {      	
      +      public message(Msg_Type:type, id, ...) 
      +      {
      +         if ((type == MSG_FLOAT_SET) && (id == 1)) 
      +         {
      +            new Float:x, Float:y;
      +            
      +            x = getfarg(2);
      +            y = getfarg(3);
      +            set_drag(PART:"rect1", x, y);
      +         }
      +      }
      +   }
      +}
      +
      + +

      This script is called when an incoming message is detected.

      + +

      Sending Messages

      + +

      Add a callback for the changed event to send a message to the Style:

      + +
      +static void
      +_slider_changed(void *data, Evas_Object *obj, void *event_info)
      +{
      +   appdata_s *ad = data;
      +   Edje_Message_Float_Set *msg;
      +   
      +   msg = malloc(sizeof(*msg) + 1 * sizeof(float));
      +   msg->count = 2;
      +   msg->val[0] = elm_slider_value_get(ad->slider_hor);
      +   msg->val[1] = elm_slider_value_get(ad->slider_ver);
      +   
      +   edje_object_message_send(ad->edje_object, EDJE_MESSAGE_FLOAT_SET, 1, msg);
      +   free(msg);
      +}
      +
      + +

      The same message can be sent in the opposite direction. To send messages in EDC script (Embryo – link to Embryo), use the sent_message() function.

      + +
      +program 
      +{
      +   signal: "drag";
      +   source: "rect1";
      +   script 
      +   {
      +      new Float:x, Float:y;
      +      get_drag(PART:"rect1", x, y);
      +      send_message(MSG_FLOAT, 2, x);
      +      send_message(MSG_FLOAT, 3, y);
      +   }
      +}
      +
      + +

      2 messages are sent using the drag signal from the rect1 part.

      + +

      Add a message handler in the C code:

      + +
      +edje_object_message_handler_set(ad->edje_object, _message_handle, ad);
      +
      + +

      Add a callback:

      + +
      +static void
      +_message_handle(void *data, Evas_Object *obj, Edje_Message_Type type,
      +                int id, void *msg)
      +{
      +   Edje_Message_Float *m;
      +   appdata_s *ad = data;
      +   
      +   if (type != EDJE_MESSAGE_FLOAT) return;
      +   m = msg;
      +   if (id == 2) elm_slider_value_set(ad->slider_hor, m->val);
      +   if (id == 3) elm_slider_value_set(ad->slider_ver, m->val);
      +}
      +
      + + + +
      + +Go to top + + + + + + + \ No newline at end of file diff --git a/org.tizen.ui.guides/html/native/efl/edje_objects_n.htm b/org.tizen.ui.guides/html/native/efl/edje_objects_n.htm new file mode 100755 index 0000000..0c0bb0b --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/edje_objects_n.htm @@ -0,0 +1,87 @@ + + + + + + + + + + + + + Edje Objects: Managing Layouts and Layout Components + + + + + +
      + +

      Edje Objects: Managing Layouts and Layout Components

      + + +

      You can build and handle layouts using Edje objects. An Edje object is a type of Evas object for displaying units, such as rectangles, lines, polygons, text, and images. Edje objects are only used in Edje and provide functions that deal with Edje layouts and layout components. Namely, there is no Edje object type in the source code for implementing an application. The objects are mainly layouts or themes defined by groups and parts, and declared in EDC files.

      +

      Edje provides functions for the following features:

      + +
        +
      • Handling Edje Files +

        Edje layouts are called themes and created using the EDC language. The EDC language is declarative and must be compiled before being used. The output of this compilation is an EDJ file, which can be loaded by Edje, and the result is an Edje object.

      • + +
      • Scaling Edje Objects +

        Edje enables you to build scalable interfaces. There are 2 types of scaling factors, which are set to neutral (1.0) values by default (no scaling, actual sizes): global and individual. Scaling affects the minimum and maximum values of the part sizes, which are multiplied. Font sizes are scaled, too.

      • + +
      • Using Edje Color Classes +

        To change the color and text of 2 or more parts simultaneously, you can use color classes. If parts are assigned with a color class, setting the color values to this class causes all the parts to have their colors multiplied by the values. Setting the values to a color class at a process level affects all parts with that color class, while at the object level, only the parts inside a specified object are affected.

      • + +
      • Using Edje Text Classes +

        To change the text of 2 or more parts simultaneously, you can use text classes. If parts are assigned with a text class, setting the font attributes to this class updates all these parts with the new font attributes. Setting the values to a text class at a process level affects all parts with that text class, while at the object level, only the parts inside a specified object are affected.

      • + +
      • Using Edje Perspective +

        Perspective is a graphical tool that makes 2D objects appear as 3D. The perspective can be used with all Edje objects.

      • + +
      • Managing Signals and Messages +

        Edje objects have 2 communication interfaces between the logic and GUI. You can either emit a signal from the logic to the GUI, or create handles for the signals emitted from the GUI. Signals are identified by strings. With Edje messages, you can communicate values, such as strings, float numbers, and integer numbers. Messages can also be identified by integer numbers.

      • + +
      • Managing Edje Animations +

        Edje has the ability to animate their objects. You can start, stop, play, pause, freeze, and thaw Edje animations, and check their status.

      • +
      + + + +
      + +Go to top + + + + + + + \ No newline at end of file diff --git a/org.tizen.ui.guides/html/native/efl/edje_perspective_n.htm b/org.tizen.ui.guides/html/native/efl/edje_perspective_n.htm new file mode 100755 index 0000000..cb50901 --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/edje_perspective_n.htm @@ -0,0 +1,486 @@ + + + + + + + + + + + + + Using Edje Perspective + + + + + +
      + +

      Using Edje Perspective

      + + +

      This tutorial demonstrates how you can create a 3D projection of a 2D object.

      +

      Edje Perspective is a graphical tool that makes 2D objects appear like they have a 3D appearance.

      +

      Edje Perspective can be used in all Edje objects to create and configure a perspective objects and to set the to an Edje object or a canvas, affecting all the objects within that have no specific perspective already defined.

      + +

      Creating the Basic Application

      +

      The perspective application has buttons to move the Edje object and change its perspective. The Edje object is a 2D object that changes its position so that the perspective point can be applied.

      + + + + + + + + + + +
      Note
      The loaded Edje object must have the perspective option enabled in its EDC source code.
      + +

      Create a simple Edje object that has 4 states: left-top, right-top, left-bottom, and right-bottom. Clicking a button emits signals into the object and makes the object move.

      + +
        +
      1. + +

        The following example implements the Edje object:

        + +
        +group 
        +{
        +   name: "example/group";
        +   min: 480 320;
        +   parts 
        +   {
        +      part 
        +      {
        +         name: "bg";
        +         type: RECT;
        +         mouse_events: 1;           
        +         description 
        +         {
        +            state: "default" 0.0;
        +         }
        +      }       
        +      part 
        +      {
        +         name: "rectangle";
        +         type: RECT;
        +         mouse_events: 0;
        +         description 
        +         {
        +            state: "default" 0.0;
        +            color: 255 0 0 128;
        +            rel1 
        +            {
        +               offset: -5 -5;
        +               to: "title";
        +            }
        +            rel2 
        +            {
        +               offset: 4 4;
        +               to: "title";
        +            }
        +            map 
        +            {
        +               on: 1;
        +               perspective_on: 1;
        +               rotation 
        +               {
        +                  x: 45;
        +                  y: 15;
        +               }
        +            }
        +         }
        +      }
        +      part 
        +      {
        +         name: "title";
        +         type: TEXT;
        +         mouse_events: 0;
        +         description 
        +         {
        +            state: "default" 0.0;
        +            color: 200 200 200 255;
        +            align: 0.0 0.5;
        +            rel1.relative: 0.2 0.2;
        +            rel2.relative: 0.2 0.2;
        +            text 
        +            {
        +               text: "Perspective example";
        +               font: "Sans";
        +               size: 16;
        +               min: 1 1;
        +            }
        +            map 
        +            {
        +               on: 1;
        +               perspective_on: 1;
        +               rotation 
        +               {
        +                  x: 45;
        +                  y: 15;
        +               }
        +            }
        +         }
        +         description 
        +         {
        +            state: "right" 0.0;
        +            inherit: "default" 0.0;
        +            rel1.relative: 0.5 0.2;
        +            rel2.relative: 0.5 0.2;
        +         }
        +         description 
        +         {
        +            state: "bottom" 0.0;
        +            inherit: "default" 0.0;
        +            rel1.relative: 0.2 0.8;
        +            rel2.relative: 0.2 0.8;
        +         }
        +         description 
        +         {
        +            state: "bottomright" 0.0;
        +            inherit: "default" 0.0;
        +            rel1.relative: 0.5 0.8;
        +            rel2.relative: 0.5 0.8;
        +         }
        +      }
        +   }
        +   programs 
        +   {
        +      program 
        +      {
        +         name: "move,right";
        +         signal: "move,1,0";
        +         action: STATE_SET "right" 0.0;
        +         transition: SINUSOIDAL 1.0;
        +         target: "title";
        +         after: "animation,end";
        +      }
        +      program 
        +      {
        +         name: "move,bottom";
        +         signal: "move,0,1";
        +         action: STATE_SET "bottom" 0.0;
        +         transition: SINUSOIDAL 1.0;
        +         target: "title";
        +         after: "animation,end";
        +      }
        +      program 
        +      {
        +         name: "move,bottomright";
        +         signal: "move,1,1";
        +         action: STATE_SET "bottomright" 0.0;
        +         transition: SINUSOIDAL 1.0;
        +         target: "title";
        +         after: "animation,end";
        +      }
        +      program 
        +      {
        +         name: "move,default";
        +         signal: "move,0,0";
        +         action: STATE_SET "default" 0.0;
        +         transition: SINUSOIDAL 1.0;
        +         target: "title";
        +         after: "animation,end";
        +      }
        +      program 
        +      {
        +         name: "animation,end";
        +         action: SIGNAL_EMIT "animation,end" "";
        +      }
        +   }
        +}
        +
        +
      2. + +
      3. +

        Create the application. Create a basic window widget that is going to be loaded and created in the main starting function:

        + +
        +// Window
        +ad->win = elm_win_util_standard_add(PACKAGE, PACKAGE);
        +elm_win_conformant_set(ad->win, EINA_TRUE);
        +elm_win_autodel_set(ad->win, EINA_TRUE);
        +
        +if (elm_win_wm_rotation_supported_get(ad->win)) 
        +{
        +   int rots[4] = 
        +   {
        +      0, 90, 180, 270 
        +   };
        +   elm_win_wm_rotation_available_rotations_set(ad->win, (const int *)(&rots), 4);
        +}
        +
        +
      4. + +
      5. +

        Add a conformant and set the main layout of the application.

        +

        The main layout is described in the EDC part and consists of 2 swallows. The first swallow has the Edje object loaded into it. The second contains a box of buttons to manipulate the perspective of the Edje object.

        + +
        +// Conformant
        +ad->conform = elm_conformant_add(ad->win);
        +elm_win_indicator_mode_set(ad->win, ELM_WIN_INDICATOR_SHOW);
        +elm_win_indicator_opacity_set(ad->win, ELM_WIN_INDICATOR_OPAQUE);
        +evas_object_size_hint_weight_set(ad->conform, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
        +elm_win_resize_object_add(ad->win, ad->conform);
        +evas_object_show(ad->conform);
        +
        +// Base layout
        +app_get_resource(EDJ_FILE, edj_path, (int)PATH_MAX);
        +ad->layout = elm_layout_add(ad->win);
        +elm_layout_file_set(ad->layout, edj_path, GRP_MAIN);
        +evas_object_size_hint_weight_set(ad->layout, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
        +evas_object_size_hint_weight_set(ad->layout, EVAS_HINT_FILL, EVAS_HINT_FILL);
        +eext_object_event_callback_add(ad->layout, EEXT_CALLBACK_BACK, layout_back_cb, ad);
        +elm_object_content_set(ad->conform, ad->layout);
        +
        +
      6. + +
      7. +

        Create the Edje object on Evas using the evas_object_evas_get() function. This function is very useful because you must operate on the canvas, but have only an object pointer to a window object.

        + +
        +Evas *evas;
        +evas = evas_object_evas_get(ad->win);
        +ad->edje_obj = edje_object_add(evas);
        +
        +
      8. + +
      9. +

        Instantiate a new Edje object by creating a new Edje smart object and returning its Evas_Object handle:

        + +
        +ad->edje_obj = edje_object_add(evas);
        +
        +
      10. + +
      11. +

        An Edje object is useless without a source file set to it, so use the edje_object_file_set() function to set the object into the main layout:

        + +
        +ad->edje_obj = edje_object_add(evas);
        +edje_object_file_set(ad->edje_obj, edj_path, "example/group");
        +evas_object_move(ad->edje_obj, 0, 0);
        +evas_object_show(ad->edje_obj);
        +elm_object_part_content_set(ad->layout, "swallow", ad->edje_obj);
        +
        + +

        Figure: Main layout with the swallow part highlighted

        +

        Main layout with the swallow part highlighted

        +
      12. + +
      13. +

        Create the actual perspective object, define its position, focal distance and Z plane position, and set it as global:

        + +
        +ad->ps = edje_perspective_new(evas);	
        +edje_perspective_set(ad->ps, 160, 320, 0, ad->focal);
        +edje_perspective_global_set(ad->ps, EINA_TRUE);
        +
        + +

        To set the perspective of the Edje object, instead of setting it as global to the entire canvas, you can use the edje_object_perspective_set() function. +

        +
      14. + +
      15. +

        Create a new perspective in the canvas by setting up the transformation for the perspective object:

        + +
        +void 
        +edje_perspective_set(Edje_Perspective * ps, Evas_Coord px, Evas_Coord py, Evas_Coord z0, Evas_Coord foc)
        +
        + +

        This sets the parameters of the perspective transformation. X, Y, and Z values are used. The px and py points specify the infinite distance point in the 3D conversion, where all lines converge. The z0 point specifies the Z value at which there is a 1:1 mapping between spatial coordinates and screen coordinates. Any points on the Z value do not have their X and Y values modified in the transformation. The points further away (with a higher Z value) shrink into the distance, and those that are closer expand and become bigger.

        +

        The foc value determines the focal length of the camera. This is the distance between the camera lens plane and the z0 Z value. This allows for some depth control. The foc value must be greater than 0.

        +
      16. + +
      17. +

        The Swallow buttons layout part contains a box of buttons to manipulate the perspective of the loaded Edje object.

        + +

        Figure: Main layout with swallow buttons highlighted

        +

        Main layout with swallow buttons highlighted

        + +

        Add the box and pack the buttons into it. Name the first button Global and register a callback for clicking:

        + +
        +Evas_Object *box, *button;
        +// Adding box
        +box = elm_box_add(ad->layout);
        +evas_object_size_hint_weight_set(box, EVAS_HINT_EXPAND, 0.0);
        +evas_object_size_hint_align_set(box, EVAS_HINT_FILL, 0.0);
        +elm_box_horizontal_set(box, EINA_TRUE);
        +evas_object_show(box);
        +elm_object_part_content_set(ad->layout, "swallow.buttons", box);
        +
        +button = elm_button_add(ad->layout);
        +evas_object_size_hint_align_set(button, EVAS_HINT_FILL, EVAS_HINT_FILL);
        +evas_object_size_hint_weight_set(button, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
        +elm_object_text_set(button, "move");
        +evas_object_show(button);
        +elm_box_pack_end(box, button);
        +evas_object_smart_callback_add(button, "clicked", _on_btn_clicked, ad);
        +
        +button = elm_button_add(ad->layout);
        +evas_object_size_hint_align_set(button, EVAS_HINT_FILL, EVAS_HINT_FILL);
        +evas_object_size_hint_weight_set(button, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
        +elm_object_text_set(button, "more");
        +evas_object_show(button);
        +elm_box_pack_end(box, button);
        +evas_object_smart_callback_add(button, "clicked", _on_btn_more_clicked, ad);
        +
        +button = elm_button_add(ad->layout);
        +evas_object_size_hint_align_set(button, EVAS_HINT_FILL, EVAS_HINT_FILL);
        +evas_object_size_hint_weight_set(button, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
        +elm_object_text_set(button, "less");
        +evas_object_show(button);
        +elm_box_pack_end(box, button);
        +evas_object_smart_callback_add(button, "clicked", _on_btn_less_clicked, ad);
        +
        +ad->edje_obj = edje_object_add(evas);
        +edje_object_file_set(ad->edje_obj, edj_path, "example/group");
        +evas_object_move(ad->edje_obj, 0, 0);
        +evas_object_show(ad->edje_obj);
        +elm_object_part_content_set(ad->layout, "swallow", ad->edje_obj);
        +
        +
      18. + +
      19. +

        Show the main window:

        + +
        +evas_object_show(ad->win);
        +
        + +

        Figure: Main screen

        +

        Figure: Main screen

        + +
      20. +
      + +

      Playing with the Perspective

      + +
        +
      1. +

        The callback for a clicked button is converted to a signal determining where the text and rectangle must be moved:

        + +
        +static void
        +_part_move(appdata_s *ad, int dx, int dy)
        +{
        +   char emission[64];
        +
        +   dlog_print(DLOG_ERROR, "AAAA", "x,y = %d, %d", dx, dy);
        +   snprintf(emission, sizeof(emission), "move,%d,%d", dx, dy);
        +   edje_object_signal_emit(ad->edje_obj, emission, "");
        +}
        +
        +
      2. + +
      3. +

        The callback representing the Edje object move calls the part_move() function that directly sends a signal to the Edje part. The moving action is treated in the program according to the passed signal.

        + +
        +static void
        +_on_btn_clicked(void *data, Evas_Object *obj, void *event_info)
        +{
        +   appdata_s *ad = data;
        +   static int i = 0;
        +   switch (i) 
        +   {
        +      case 0:
        +         _part_move(ad, 1, 0);
        +         break;
        +      case 1:
        +         _part_move(ad, 1, 1);
        +         break;
        +      case 2:
        +         _part_move(ad, 0, 1);
        +         break;
        +      case 3:
        +         _part_move(ad, 0, 0);
        +         break;
        +   }
        +   i++;
        +   i = i%4;
        +}
        +
        + +

        Figure: Moving process

        +

        ->Figure: Moving process Figure: Moving process

        +
      4. + +
      5. +

        By clicking the More and Less buttons, you can increase or decrease the focal length of the camera:

        + +
        +static void
        +_on_btn_more_clicked(void *data, Evas_Object *obj, void *event_info)
        +{
        +   appdata_s *ad = data;
        +   ad->focal += 5;
        +   edje_perspective_set(ad->ps, 160, 320, 0, ad->focal);
        +   edje_perspective_global_set(ad->ps, EINA_TRUE);
        +}
        +
        +static void
        +_on_btn_less_clicked(void *data, Evas_Object *obj, void *event_info)
        +{
        +   appdata_s *ad = data;
        +   ad->focal -= 5;
        +   edje_perspective_set(ad->ps,160, 320, 0, ad->focal);
        +   edje_perspective_global_set(ad->ps, EINA_TRUE);
        +}
        +
        + +

        Figure: Decreasing and increasing the focal length

        + +

        Decreasing and increasing the focal length

        +
      6. +
      + + + + +
      + +Go to top + + + + + + + \ No newline at end of file diff --git a/org.tizen.ui.guides/html/native/efl/edje_scaling_n.htm b/org.tizen.ui.guides/html/native/efl/edje_scaling_n.htm new file mode 100755 index 0000000..ff9b16e --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/edje_scaling_n.htm @@ -0,0 +1,794 @@ + + + + + + + + + + + + + + Scaling Edje Objects + + + + + + +
      +

      Scaling Edje Objects

      + +

      This demonstrates how you can scale Edje objects. Scalability is important when building user interfaces for different environments, such as mobile phones and laptops.

      +

      The natural value of scale factors is 1.0. Scaling affects minimum and maximum part size and font size, and multiplies them.

      + +

      You can disable scaling of certain parts.

      + +

      Initializing the EDC File

      + +

      Set up and prepare the EDC source code for loading the Edje objects in your application:

      + +
        +
      1. +

        To demonstrate Edje scale usability, set up 2 groups. The first group contains only one scalable part.

        + +
        group 
        +{ 
        +   name: "scale_group_1";
        +   parts 
        +   {
        +      part
        +      { 
        +         name: "scalable_rect";
        +         type: RECT;
        +         scale: 1;
        +         description 
        +         { 
        +            state: "default" 0.0;
        +            min: 16 16;
        +            max: 16 16;
        +            color: 0 0 255 255;
        +         }
        +      }
        +   }
        +}
        + +

        Figure: First scalable group

        +

        First scalable group

        + +

        For this example, the group is used for showing Edje's global scale.

        + +

        The other group is used for showing usability of the edje_object_scale function. The group has 2 non-scalable parts (not_scalable_rect1 and not scalable_rect2 ), which are related to the scalable parts. It can be seen that scalability actually changes the scalable parts and all UI can be changed according to new relatives.

        + +

        Scalability of certain parts is usually preset in the EDC source code with the scale property:

        + +
        +group 
        +{ 
        +   name: "scale_group_2";
        +   parts 
        +   {
        +      part 
        +      { 
        +         name: "not_scalable_rect1";
        +         type: RECT;
        +         scale: 0;
        +         description 
        +         { 
        +            state: "default" 0.0;
        +            align: 0.0 0.5;
        +            min: 40 40;
        +            max: 40 40;
        +            color: 255 0 255 255;
        +         }
        +      }
        +      part 
        +      { 
        +         name: "scalable_rect";
        +         type: RECT;
        +         scale: 1;
        +         description 
        +         { 
        +            state: "default" 0.0;
        +            align: 0.0 0.5;
        +            min: 25 19;
        +            max: 25 19;
        +            color: 0 255 255 255;
        +            rel1 
        +            {
        +               relative: 1.0 0.0;
        +               to_x: "not_scalable_rect1";
        +            }
        +         }
        +      }
        +      part 
        +      { 
        +         name: "not_scalable_rect2";
        +         type: RECT;
        +         scale: 0;
        +         description 
        +         { 
        +            state: "default" 0.0;
        +            align: 0.0 0.5;
        +            min: 40 40;
        +            max: 40 40;
        +            color: 255 0 255 255;
        +            rel1 
        +            {
        +               relative: 1.0 0.0;
        +               to_x: "scalable_rect";
        +            }
        +         }
        +      }
        +   }
        +}
        +
        + +

        Figure: Second scalable group

        +

        Second scalable group

        +
      2. + +
      3. + +

        The base_scale factor can be used when the whole collection in the EDC file contains it:

        + +
        collections 
        +{
        +   base_scale: 1.2;
        +   group 
        +   { 
        +      name: "scale_group_1";
        +   }
        +   group 
        +   { 
        +      name: "scale_group_2";
        +   }
        +   group 
        +   {
        +      name: "main_layout";
        +   }
        +}
        +
      4. + +
      5. +

        An application must contain controls, such as a spinner, to change the scale and see the result.

        + +

        Add a box with 2 groups loaded as edje objects, and spinners for changing the scale values:

        + +
        +group 
        +{ 
        +   name: "main_application";
        +   parts 
        +   {
        +      part 
        +      { 
        +         name: "edje.swallow.content";
        +         type: SWALLOW;
        +         description 
        +         { 
        +            state: "default" 0.0;
        +            align: 0.0 1.0;
        +            rel1 
        +            {
        +               relative: 0.0 1.0;
        +               offset: 0 20;
        +               to_y: "title2";
        +            }
        +         }
        +      }
        +      part 
        +      { 
        +         name: "title1";
        +         type: TEXT;
        +         scale: 1;
        +         description 
        +         { 
        +            state: "default" 0.0;
        +            align: 0.0 0.0;
        +            max: 100 32;
        +            color: 0 0 0 255;
        +            text 
        +            {
        +               text: "edje scale:";
        +               font: "Sans";
        +               size: 16;
        +            }
        +         }
        +      }
        +      part 
        +      { 
        +         name: "title2";
        +         type: TEXT;
        +         scale: 1;
        +         description
        +         { 
        +            state: "default" 0.0;
        +            align: 0.0 0.0;
        +            max: 150 32;
        +            color: 0 0 0 255;
        +            rel1 
        +            {
        +               relative: 0.0 1.0;
        +               to_y: "scale.swallow";
        +            }
        +            text 
        +            {
        +               text: "edje object scale:";
        +               font: "Sans";
        +               size: 16;
        +            }
        +         }
        +      }
        +      part 
        +      { 
        +         name: "scale.swallow";
        +         type: SWALLOW;
        +         scale: 1;
        +         description 
        +         { 
        +            state: "default" 0.0;
        +            align: 0.0 0.0;
        +            max: 200 48;
        +            rel1 
        +            {
        +               relative: 1.0 0.0;
        +               to_x: "title2";
        +               to_y: "title1";
        +            }
        +            rel2 
        +            {
        +               to_y: "title1";
        +            }
        +         }
        +      }
        +      part 
        +      { 
        +         name: "scale.swallow2";
        +         type: SWALLOW;
        +         scale: 1;
        +         description 
        +         { 
        +            state: "default" 0.0;
        +            align: 0.0 0.0;
        +            max: 200 48;
        +            rel1 
        +            {
        +               relative: 1.0 0.0;
        +               to: "title2";
        +            }
        +            rel2 
        +            {
        +               to_y: "title2";
        +            }
        +         }
        +      }
        +   }
        +}
        +
        + +

        Figure: Main application layout

        +

        Main application layout

        + +

        In the example, there are the following swallows:

        +
          +
        • edje.swallow.content is used for the box containing the Edje objects.
        • +
        • scale.swallow is used for the spinner that changes the scale value a loaded Edje object.
        • +
        • scale.swallow2 is used for the spinner that changes the global scale, so changing this value changes the scale of all Edje objects if they do not have their own scales set using the edje_object_scale_set() function.
        • +
        +
      6. +
      + +

      Initializing the Application

      + +

      All application code lays in the create_base_gui() function that creates and loads all objects and forms, and creates application's main look.

      + +
        +
      1. +

        Create a window and get the path to the EDJ file:

        + +
        +ad->win = elm_win_util_standard_add(PACKAGE, PACKAGE);   elm_win_conformant_set(ad->win, EINA_TRUE);
        +elm_win_autodel_set(ad->win, EINA_TRUE);
        +if (elm_win_wm_rotation_supported_get(ad->win))
        +{
        +   int rots[4] = 
        +   {
        +      0, 90, 180, 270
        +   };
        +   elm_win_wm_rotation_available_rotations_set(ad->win, (const int *)(&rots), 4);
        +}
        +// Path to edj group with three groups
        +app_get_resource(EDJ_FILE, edj_path, (int)PATH_MAX);
        +
        +
      2. + +
      3. +

        Set the conformant containing the main layout into the window:

        + +
        +ad->conform = elm_conformant_add(ad->win);
        +elm_win_indicator_mode_set(ad->win, ELM_WIN_INDICATOR_SHOW);
        +elm_win_indicator_opacity_set(ad->win, ELM_WIN_INDICATOR_OPAQUE);
        +evas_object_size_hint_weight_set(ad->conform, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
        +elm_win_resize_object_add(ad->win, ad->conform);
        +evas_object_show(ad->conform);
        +// Main layout
        +ad->main_layout = elm_layout_add(ad->win);
        +evas_object_size_hint_weight_set(ad->main_layout, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
        +elm_layout_file_set(ad->main_layout, edj_path, "main_application");
        +elm_object_content_set(ad->conform, ad->main_layout);
        +evas_object_show(ad->main_layout);
        +app_get_resource(EDJ_FILE, edj_path, (int)PATH_MAX);
        +
        + + + + + + + + + + +
        Note
        If you have layout for your window written in the EDC file, use and load it as Layout with Elementary layout API (using, for example, the elm_layout_add() , elm_object_style_set() , and elm_layout_file_set() functions).
        +
      4. + +
      5. +

        Add the box and set it into the edje.swallow.content main layout swallow:

        + +
        +// Add the box
        +ad->box = elm_box_add(ad->main_layout);
        +evas_object_size_hint_weight_set(ad->box, EVAS_HINT_EXPAND, 0.0);
        +evas_object_size_hint_align_set(ad->box, EVAS_HINT_FILL, 0.0);
        +elm_box_horizontal_set(ad->box, EINA_TRUE);
        +evas_object_show(ad->box);
        +// Set the box into the main layout
        +elm_object_part_content_set(ad->main_layout, "edje.swallow.content", ad->box);
        +
      6. + +
      7. +

        Load the Edje objects:

        + +
        +// Add group1
        +ad->edje_object_1 = edje_object_add(evas_object_evas_get(ad->win));
        +evas_object_size_hint_weight_set(ad->edje_object_1, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
        +edje_object_file_set(ad->edje_object_1, edj_path, "scale_group_1");
        +// Check object loading errors
        +if (edje_object_load_error_get(ad->edje_object_1) != EDJE_LOAD_ERROR_NONE)
        +{
        +   evas_object_del(ad->edje_object_1);
        +
        +   return;
        +}
        +evas_object_show(ad->edje_object_1);
        +
      8. + +
      9. +

        Pack the Edje objects into the box:

        + +
        +elm_box_pack_end(ad->box, ad->edje_object_1);
        +elm_box_pack_end(ad->box, ad->edje_object_2);
        +
      10. + +
      11. +

        Add 2 spinners that change the scale values:

        + +
        +ad->edje_scale = elm_spinner_add(ad->win);
        +evas_object_size_hint_weight_set(ad->edje_scale, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
        +evas_object_size_hint_align_set(ad->edje_scale, EVAS_HINT_FILL, EVAS_HINT_FILL);
        +elm_spinner_min_max_set(ad->edje_scale, 1, 300);
        +elm_spinner_step_set(ad->edje_scale, 10);
        +evas_object_show(ad->edje_scale);
        +elm_spinner_value_set(ad->edje_scale, 100);
        +elm_object_part_content_set(ad->main_layout, "scale.swallow", ad->edje_scale);
        +
        +ad->edje_object_scale = elm_spinner_add(ad->win);
        +evas_object_size_hint_weight_set(ad->edje_object_scale, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
        +evas_object_size_hint_align_set(ad->edje_object_scale, EVAS_HINT_FILL, EVAS_HINT_FILL);
        +elm_spinner_min_max_set(ad->edje_object_scale, 1, 300);
        +elm_spinner_step_set(ad->edje_object_scale, 10);
        +evas_object_show(ad->edje_object_scale);
        +elm_spinner_value_set(ad->edje_object_scale, 100);
        +elm_object_part_content_set(ad->main_layout, "scale.swallow2", ad->edje_scale);
        +
      12. + +
      13. Display the window:

        + +
        +evas_object_show(ad->win);
        + +

        Figure: Scale testing application

        +

        Scale testing application

        +
      14. +
      + + +

      Setting Global Scales

      + +
        +
      1. +

        Add a callback for the second spinner that changes Edje global scale value and, as a result, affects all loaded Edje objects:

        + +
        static void
        +create_base_gui(appdata_s *ad)
        +{
        +   // Add scale spinners
        +   ad->edje_object_scale = elm_spinner_add(ad->win);
        +   evas_object_size_hint_weight_set(ad->edje_object_scale, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
        +   evas_object_size_hint_align_set(ad->edje_object_scale, EVAS_HINT_FILL, EVAS_HINT_FILL);
        +   elm_spinner_min_max_set(ad->edje_object_scale, 1, 300);
        +   elm_spinner_step_set(ad->edje_object_scale, 10);
        +   evas_object_show(ad->edje_object_scale);
        +   elm_spinner_value_set(ad->edje_object_scale, 100);
        +   elm_object_part_content_set(ad->main_layout, "scale.swallow2", ad->edje_object_scale);
        +
        +   evas_object_smart_callback_add(ad->edje_object_scale, "changed", _on_global_scale_change, ad);
        +}
        +
      2. + +
      3. + +

        Set the scale using the edje_scale_set() function:

        + +
        static void
        +_on_global_scale_change(void *data, Evas_Object *obj, void *event_info)
        +{
        +   edje_scale_set(elm_spinner_value_get(obj) / 100);
        +}
        + +

        By clicking the spinner buttons, you can change the scale of all loaded Edje objects. The Edje object on the right has its own scale values, so global scale values do not apply to it.

        + +

        Figure: Different global scales

        +

        Different global scales

        +
      4. + +
      + + + + + + + + + +
      Note
      Using the edje_scale_set() function that changes the global scale values can affect your whole application and destroy the UI layout. Be careful with this function.
      + +

      Setting Scales for Edje Objects

      + +

      Add a callback to get the value of the first spinner and apply it to the Edje object on the right:

      + +
      static void
      +_on_scale_change(void *data, Evas_Object *obj, void *event_info)
      +{
      +   appdata_s *ad = data;
      +   edje_object_scale_set(ad->edje_object_2, elm_spinner_value_get(obj) / 100);
      +}
      +
      +static void
      +create_base_gui(appdata_s *ad)
      +{
      +   // Add scale spinners
      +   ad->edje_scale = elm_spinner_add(ad->win);
      +   evas_object_size_hint_weight_set(ad->edje_scale, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +   evas_object_size_hint_align_set(ad->edje_scale, EVAS_HINT_FILL, EVAS_HINT_FILL);
      +   elm_spinner_min_max_set(ad->edje_scale, 1, 300);
      +   elm_spinner_step_set(ad->edje_scale, 10);
      +   evas_object_show(ad->edje_scale);
      +   elm_spinner_value_set(ad->edje_scale, 100);
      +   elm_object_part_content_set(ad->main_layout, "scale.swallow", ad->edje_scale);
      +   evas_object_smart_callback_add(ad->edje_scale, "changed", _on_scale_change, ad);
      +}
      + + +

      By clicking on spinner buttons, you can change the scale of the second Edje object in the box.

      + +

      Figure: Edje object scales

      +

      Edje object scales

      + + +

      Personal, Global, and Base Scales

      + +

      Modify the main layout and add a swallow for the buttons. The buttons are used for showing the current scale:

      + +
        +
      1. +

        Modify the main layout EDC code by creating another swallow part, swallow.buttons , and modifying the edje.swallow.content part:

        + +
        +group 
        +{ 
        +   name: "main_application";
        +   parts 
        +   {
        +      part 
        +      { 
        +         name: "edje.swallow.content";
        +         type: SWALLOW;
        +         description 
        +         { 
        +            state: "default" 0.0;
        +            align: 0.0 1.0;
        +            rel1 
        +            {
        +               relative: 0.0 1.0;
        +               offset: 0 20;
        +               to_y: "title2";
        +            }
        +            rel2 
        +            {
        +               relative: 1.0 0.0;
        +               to_y: "swallow.buttons";
        +            }
        +         }
        +      }
        +      part 
        +      { 
        +         name: "title1";
        +         type: TEXT;
        +         scale: 1;
        +         description 
        +         { 
        +            state: "default" 0.0;
        +            align: 0.0 0.0;
        +            max: 100 32;
        +            color: 0 0 0 255;
        +            text 
        +            {
        +               text: "edje scale:";
        +               font: "Sans";
        +               size: 16;
        +            }
        +         }
        +      }
        +      part 
        +      { 
        +         name: "title2";
        +         type: TEXT;
        +         scale: 1;
        +         description 
        +         { 
        +            state: "default" 0.0;
        +            align: 0.0 0.0;
        +            max: 150 32;
        +            color: 0 0 0 255;
        +            rel1 
        +            {
        +               relative: 0.0 1.0;
        +               to_y: "scale.swallow";
        +            }
        +            text 
        +            {
        +               text: "edje object scale:";
        +               font: "Sans";
        +               size: 16;
        +            }
        +         }
        +      }
        +      part 
        +      { 
        +         name: "scale.swallow";
        +         type: SWALLOW;
        +         scale: 1;
        +         description 
        +         { 
        +            state: "default" 0.0;
        +            align: 0.0 0.0;
        +            max: 200 48;
        +            rel1 
        +            {
        +               relative: 1.0 0.0;
        +               to_x: "title2";
        +               to_y: "title1";
        +            }
        +            rel2 
        +            {
        +               to_y: "title1";
        +            }
        +         }
        +      }
        +      part 
        +      { 
        +         name: "scale.swallow2";
        +         type: SWALLOW;
        +         scale: 1;
        +         description 
        +         { 
        +            state: "default" 0.0;
        +            align: 0.0 0.0;
        +            max: 200 48;
        +            rel1 
        +            {
        +               relative: 1.0 0.0;
        +               to: "title2";
        +            }
        +            rel2 
        +            {
        +               to_y: "title2";
        +            }
        +         }
        +      }
        +      part 
        +      { 
        +         name: "swallow.buttons";
        +         type: SWALLOW;
        +         scale: 0;
        +         description 
        +         { 
        +            state: "default" 0.0;
        +            align: 0.0 1.0;
        +            min: 0 60;
        +            max: -1 60;
        +         }
        +      }
        +   }
        +}
        +
        +
      2. + +
      3. +

        Add a box with buttons and set it into the main layout:

        + +
        static void
        +_edje_object_scale_get(void *data, Evas_Object *obj, void *event_info)
        +{
        +   char title[PATH_MAX] = {0, };
        +   appdata_s *ad = data;
        +   snprintf(title, (int)PATH_MAX, "object %.2f", edje_object_scale_get(ad->edje_object_2));
        +   elm_object_text_set(obj, title);
        +}
        +static void
        +_edje_scale_get(void *data, Evas_Object *obj, void *event_info)
        +{
        +   char title[PATH_MAX] = {0, };
        +   snprintf(title, (int)PATH_MAX, "global %.2f", edje_scale_get());
        +   elm_object_text_set(obj, title);
        +}
        +static void
        +_edje_object_base_scale_get(void *data, Evas_Object *obj, void *event_info)
        +{
        +   char title[PATH_MAX] = {0, };
        +   appdata_s *ad = data;
        +   snprintf(title, (int)PATH_MAX, "base %.2f", edje_object_base_scale_get(ad->edje_object_2));
        +   elm_object_text_set(obj, title);
        +}
        +
        +static void
        +create_base_gui(appdata_s *ad) 
        +{
        +   Evas_Object *box, *button;
        +   // Add the box
        +   box = elm_box_add(ad->main_layout);
        +   evas_object_size_hint_weight_set(box, EVAS_HINT_EXPAND, 0.0);
        +   evas_object_size_hint_align_set(box, EVAS_HINT_FILL, 0.0);
        +   elm_box_horizontal_set(box, EINA_TRUE);
        +   evas_object_show(box);
        +   elm_object_part_content_set(ad->main_layout, "swallow.buttons", box);
        +
        +   button = elm_button_add(ad->main_layout);
        +   evas_object_size_hint_align_set(button, EVAS_HINT_FILL, EVAS_HINT_FILL);
        +   evas_object_size_hint_weight_set(button, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
        +   elm_object_text_set(button, "object ");
        +   evas_object_show(button);
        +   evas_object_smart_callback_add(button, "clicked", _edje_object_scale_get, ad);
        +   elm_box_pack_end(box, button);
        +
        +   button = elm_button_add(ad->main_layout);
        +   evas_object_size_hint_align_set(button, EVAS_HINT_FILL, EVAS_HINT_FILL);
        +   evas_object_size_hint_weight_set(button, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
        +   elm_object_text_set(button, "global ");
        +   evas_object_show(button);
        +   evas_object_smart_callback_add(button, "clicked", _edje_scale_get, ad);
        +   elm_box_pack_end(box, button);
        +
        +   button = elm_button_add(ad->main_layout);
        +   evas_object_size_hint_align_set(button, EVAS_HINT_FILL, EVAS_HINT_FILL);
        +   evas_object_size_hint_weight_set(button, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
        +   elm_object_text_set(button, "base ");
        +   evas_object_show(button);
        +   evas_object_smart_callback_add(button, "clicked", _edje_object_base_scale_get, ad);
        +   elm_box_pack_end(box, button);
        +}
        + + +

        Clicking a button gets a specific scale and prints its value on the button. For example, clicking the Global button shows the global scale value.

        + +

        Figure: Scale values

        +

        Scale values

        +
      4. + +
      5. +

        The loaded Edje object does not have its own scale value (0.00), so it uses the global scale value defined in the EFL configuration based on the device. A mobile device that is being used here, has the global scale ~1.8). The base scale is set to 1.2.

        + +
        collections 
        +{
        +   base_scale: 1.2;
        +   group 
        +   { 
        +      name: "scale_group_1";
        +   }
        +   group 
        +   { 
        +      name: "scale_group_2";
        +   }
        +   group 
        +   { 
        +      name: "main_layout";
        +   }
        +}
        + +

        Figure: Scale values after changing the Edle object scale

        +

        Figure: Scale values after changing the Edle object scale

        + +

        After applying the scale of the new object, the global scale does not apply to this Edje object anymore. While all other objects have the scale value 1.8, the new object has the scale value 1.37.

        + + + + + + + + + + +
        Note
        The default base scale value is 1.0. All scale values in Edje objects, either set with the global scale value using the edje_scale_set() function or with a personal scale factor using the edje_object_scale_set() function are divided by base scale.
        + +

        Figure: Base scale

        +

        Base scale

        + +

        Setting a scale value that is same as the base scale makes the layout appear as if it had the scale value 1.0.

        +
      6. +
      + + + + +
      + +Go to top + + + + + + + diff --git a/org.tizen.ui.guides/html/native/efl/edje_text_n.htm b/org.tizen.ui.guides/html/native/efl/edje_text_n.htm new file mode 100755 index 0000000..47ca76f --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/edje_text_n.htm @@ -0,0 +1,712 @@ + + + + + + + + + + + + + + Using Edje Text Classes + + + + + + +
      +

      Using Edje Text Classes

      + +

      This tutorial demonstrates how you can change the text of 2 or more parts using Edje text classes.

      +

      If a part is assigned with a text class, setting font attributes to this class updates all those parts with the new font attributes. Setting the values to a text class affects all parts in that text class at process level, while at the object level, it only affects the parts inside a specified object.

      + +

      Creating the Basic Application

      + +

      The example application has 2 screen with different UIs. The screens demonstrate different text class APIs. The screen contains a genlist with 2 items set into a naviframe. Clicking an item opens displays a screen. Pressing the hardware Back button displays the main screen with the genlist.

      + +
        +
      1. Create the basic application: + +
        static void
        +win_back_cb(void *data, Evas_Object *obj, void *event_info)
        +{
        +   appdata_s *ad = data;
        +   elm_naviframe_item_pop(ad->navifr);
        +}
        +
      2. + +
      3. +

        Get the path to the EDC file that contains the main layout and the Edje object to load:

        + +
        static void
        +app_get_resource(const char *edj_file_in, char *edj_path_out, int edj_path_max)
        +{
        +   char *res_path = app_get_resource_path();
        +   if (res_path) 
        +   {
        +      snprintf(edj_path_out, edj_path_max, "%s%s", res_path, edj_file_in);
        +      free(res_path);
        +   }
        +}
        + +

        Create a window and register an event callback that calls the win_back_cb() function after pressing the Back button on the device:

        + +
        static void
        +create_base_gui(appdata_s *ad)
        +{
        +   Elm_Object_Item *eoi = NULL;
        +
        +   // Window
        +   ad->win = elm_win_util_standard_add(PACKAGE, PACKAGE);
        +   elm_win_conformant_set(ad->win, EINA_TRUE);
        +   elm_win_autodel_set(ad->win, EINA_TRUE);
        +
        +   if (elm_win_wm_rotation_supported_get(ad->win)) 
        +   {
        +      int rots[4] = {0, 90, 180, 270};
        +      elm_win_wm_rotation_available_rotations_set(ad->win, (const int *)(&rots), 4);
        +   }
        +   eext_object_event_callback_add(ad->win, EEXT_CALLBACK_BACK, win_back_cb, ad);
        +}
        +
        +
      4. + +
      5. +

        Add a conformant that contains the naviframe and genlist. Add item selection callbacks for the genlist items to show different screens:

        + +
        static char *
        +_genlist_item_text_get(void *data, Evas_Object *obj, const char *part)
        +{
        +   Eina_Stringshare *text_class = (Eina_Stringshare *)data;
        +   if (strcmp(part, "elm.text") == 0)
        +      return strdup(text_class);
        +   else
        +      return NULL;
        +}
        +
        +static void
        +create_base_gui(appdata_s *ad)
        +{
        +   // Conformant
        +   ad->conform = elm_conformant_add(ad->win);
        +   elm_win_indicator_mode_set(ad->win, ELM_WIN_INDICATOR_SHOW);
        +   elm_win_indicator_opacity_set(ad->win, ELM_WIN_INDICATOR_OPAQUE);
        +   evas_object_size_hint_weight_set(ad->conform, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
        +   elm_win_resize_object_add(ad->win, ad->conform);
        +   evas_object_show(ad->conform);
        +
        +   // Naviframe
        +   ad->navifr = elm_naviframe_add(ad->win);
        +   elm_object_content_set(ad->conform, ad->navifr);
        +   eext_object_event_callback_add(ad->navifr, EEXT_CALLBACK_BACK, eext_naviframe_back_cb, ad);
        +
        +   // Genlist
        +   ad->itc = elm_genlist_item_class_new();
        +   ad->itc->func.text_get =_genlist_item_text_get;
        +
        +   ad->genlist = elm_genlist_add(ad->win);
        +   evas_object_size_hint_weight_set(ad->genlist, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
        +
        +   eoi = elm_genlist_item_append(ad->genlist, ad->itc, eina_stringshare_add("Text Class List"), NULL,
        +                                 ELM_GENLIST_ITEM_NONE, NULL, ad);
        +   eoi = elm_genlist_item_append(ad->genlist, ad->itc, eina_stringshare_add("Object Text Class API"), NULL,
        +                                 ELM_GENLIST_ITEM_NONE, NULL, ad);
        +   elm_naviframe_item_simple_push(ad->navifr, ad->genlist);
        +
        +   // Show the window
        +   evas_object_show(ad->win);
        +}
        + + +

        The following figure shows the result.

        + +

        Figure: Main screen

        +

        Main screen

      6. +
      + +

      Getting, Deleting, and Displaying Text Classes

      + +

      The first screen of the application shows an example of the edje_text_class_del(), edje_text_class_list(), and edje_text_class_get() functions.

      + +

      The following code implements the layout:

      + +
      +group 
      +{ 
      +   name: "class_list_application";
      +   parts 
      +   {
      +      part 
      +      { 
      +         name: "text_view";
      +         type: TEXT;
      +         description 
      +         { 
      +            state: "default" 0.0;
      +            visible: 1;
      +            color: 0 0 0 255;
      +            align: 0.5 0.0;
      +            text 
      +            {
      +               text: "text part number 3";
      +               font: "Sans";
      +               min: 1 1;
      +               max: 1 1;
      +               size: 20;
      +            }
      +         }
      +      }
      +      part 
      +      { 
      +         name: "edje.swallow.list";
      +         type: SWALLOW;
      +         description
      +         { 
      +            state: "default" 0.0;
      +            align: 0.5 0.0;
      +            color: 0 0 0 255;
      +            rel1 
      +            {
      +               relative: 0.0 1.0;
      +               to_y: "text_view";
      +            }
      +         }
      +      }
      +   }
      +}
      +
      + +

      Figure: First screen EDC layout

      +

      First screen EDC layout

      + +

      The first part (text_view) shows the properties of the selected text class. Clicking a text class in the genlist shows its properties, such as font, size, and name in the text part.

      + +
        +
      1. +

        Add the base genlist:

        + +
        +ad->genlist = elm_genlist_add(ad->win);
        +evas_object_size_hint_weight_set(ad->genlist, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
        +eoi = elm_genlist_item_append(ad->genlist, ad->itc, eina_stringshare_add("Text Class List"), NULL, 
        +                              ELM_GENLIST_ITEM_NONE, _create_class_list_gui, ad);
        +eoi = elm_genlist_item_append(ad->genlist, ad->itc, eina_stringshare_add("Object Text Class API"), 
        +                              NULL, ELM_GENLIST_ITEM_NONE, NULL, ad);
        +elm_naviframe_item_simple_push(ad->navifr, ad->genlist);
        +
        +
      2. + +
      3. +

        Load the layout:

        + +
        static void
        +_create_class_list_gui(void *data, Evas_Object *obj, void *event_info)
        +{
        +   appdata_s *ad = data; // Get application's data
        +   char edj_path[PATH_MAX] = {0, }; // path to edc file
        +   Eina_List *l;  //  Used later
        +   const char *str; // Used later
        +   Elm_Object_Item *eoi = NULL; // Used later
        +   app_get_resource(EDJ_FILE, edj_path, (int)PATH_MAX);
        +
        +   // Main layout
        +   ad->gui1_layout = elm_layout_add(ad->win);
        +   evas_object_size_hint_weight_set(ad->gui1_layout, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
        +   elm_layout_file_set(ad->gui1_layout, edj_path, "class_list_application");
        +}
        +
        +
      4. + +
      5. +

        Get a list of all text classes loaded into the system.In the following example, the Eina_List list is a field in application data.

        + +
        ad->list = edje_text_class_list();
        +
      6. + +
      7. +

        Create the genlist:

        + +
        // Genlist
        +ad->itc_text_classes = elm_genlist_item_class_new();
        +ad->itc_text_classes->func.text_get =_genlist_item_text_get;
        +
        +ad->genlist_text_classes = elm_genlist_add(ad->win);
        +evas_object_size_hint_weight_set(ad->genlist_text_classes, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
        +
        +
      8. + +
      9. +

        Go through the text class list and insert each text class to the genlist. Set the genlist into the main layout of the current screen and show it in the naviframe:

        + +
        +EINA_LIST_FOREACH(ad->list, l, str)
        +{
        +   eoi = elm_genlist_item_append(ad->genlist_text_classes, ad->itc_text_classes, str, NULL, ELM_GENLIST_ITEM_NONE, NULL, ad);
        +   elm_object_item_data_set(eoi, (void *)str);
        +}
        +elm_object_part_content_set(ad->gui1_layout, "edje.swallow.list", ad->genlist_text_classes);
        +evas_object_show(ad->genlist_text_classes);
        +elm_naviframe_item_simple_push(ad->navifr, ad->gui1_layout);
        +
        + + +

        Clicking Text Class List displays the screen with a genlist of text classes.

        + +

        Figure: Text class list

        +

        Text class list

        +
      10. + +
      11. +

        The edje_text_class_del() function deletes a text class (in the following example, T094):

        + +
        +// Main layout
        +ad->gui1_layout = elm_layout_add(ad->win);
        +evas_object_size_hint_weight_set(ad->gui1_layout, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
        +elm_layout_file_set(ad->gui1_layout, edj_path, "class_list_application");
        +evas_object_show(ad->gui1_layout);
        +
        +// Get the collection list
        +app_get_resource(EDJ_FILE, edj_path, (int)PATH_MAX);
        +edje_text_class_del("T094");
        +ad->list = edje_text_class_list();
        +
        +// Genlist
        +ad->itc_text_classes = elm_genlist_item_class_new();
        +ad->itc_text_classes->func.text_get =_genlist_item_text_get;
        +
        + +

        Figure: Text class list after deleting a class

        +

        Text class list after deleting a class

        +
      12. + +
      13. +

        Every text class contains specific information, such as the font name, font size, and text class name. To show the properties when the text class name is clicked, create a callback that uses the edje_text_class_get() function:

        + +
        static void
        +_genlist_clicked(void *data, Evas_Object *obj, void *event_info)
        +{
        +   appdata_s *ad = data;
        +   char text_class[PATH_MAX] = {0, };
        +   Elm_Object_Item *eoi = NULL;
        +   const char *str;
        +   char *font;
        +   Evas_Font_Size size;
        +
        +   eoi = elm_genlist_selected_item_get(obj);
        +   str = elm_object_item_data_get(eoi);
        +   edje_text_class_get(str, &font, &size);
        +   snprintf(text_class, PATH_MAX, "%s font{%s} size{%d}", str, font, size);
        +   elm_object_part_text_set(ad->gui1_layout, "text_view", text_class);
        +}
        +
      14. + +
      15. +

        Register the added callback function in the genlist:

        + +
        +EINA_LIST_FOREACH(ad->list, l, str)
        +{
        +   eoi = elm_genlist_item_append(ad->genlist_text_classes, ad->itc_text_classes, str, NULL, ELM_GENLIST_ITEM_NONE, _genlist_clicked, ad);
        +   elm_object_item_data_set(eoi, (void *)str);
        +}
        +elm_object_part_content_set(ad->gui1_layout, "edje.swallow.list", ad->genlist_text_classes);
        +
        +evas_object_show(ad->genlist_text_classes);
        +elm_naviframe_item_simple_push(ad->navifr, ad->gui1_layout);
        +
        + +

        Figure: Displaying text class properties

        +

        Displaying text class properties

        +
      16. +
      + + +

      Application Layout

      + +

      The second screen contains 2 Edje object with text parts containing the custom_text_class text class. When a text class is modified, all text parts assigned to it are changed as well.

      + +

      The following example shows a simple Edje object layout:

      + +
      +group 
      +{ 
      +   name: "edje_example";
      +   parts 
      +   {
      +      part 
      +      { 
      +         name: "text_example";
      +         type: TEXT;
      +         description 
      +         { 
      +            state: "default" 0.0;
      +            visible: 1;
      +            color: 0 0 0 255;
      +            text 
      +            {
      +               text: "text part number 3";
      +               font: "Sans";
      +               size: 10;
      +               text_class: "custom_text_class";
      +            }
      +         }
      +      }
      +   }
      +}
      + +
        +
      1. +

        After loading the Edje objects, add a spinner for changing the font size.

        + +

        Add 2 buttons for changing the text class of a specific object or setting the font size of the custom_text_class text class. The Set1 button sets a new size for the text class of the first Edje object and the Set2 button for the second object, respectively.

        + +

        The Get1 and Get2 buttons get the text class properties and display them on the screen.

        +

        The Global button changes the text class globally, causing all Edje object parts to be changed in case they contain the custom_text_class text class.

        + +
        +group 
        +{ 
        +   name: "class_list_application";
        +   parts 
        +   {
        +      part 
        +      { 
        +         name: "text_view";
        +         type: TEXT;
        +         description 
        +         { 
        +            state: "default" 0.0;
        +            visible: 1;
        +            color: 0 0 0 255;
        +            align: 0.5 0.0;
        +            text 
        +            {
        +               text: "text part number 3";
        +               font: "Sans";
        +               min: 1 1;
        +               max: 1 1;
        +               size: 20;
        +            }
        +         }
        +      }
        +      part 
        +      { 
        +         name: "edje.swallow.list";
        +         type: SWALLOW;
        +         description 
        +         { 
        +            state: "default" 0.0;
        +            align: 0.5 0.0;
        +            color: 0 0 0 255;
        +            rel1 
        +            {
        +               relative: 0.0 1.0;
        +               to_y: "text_view";
        +            }
        +      }
        +   }
        +}
        +
        +
      2. + +
      3. +

        Create a view for the new screen:

        + +
        static void
        +_create_text_class_gui(void *data, Evas_Object *obj, void *event_info)
        +{
        +   appdata_s *ad = data;
        +   char edj_path[PATH_MAX] = {0, };
        +
        +   app_get_resource(EDJ_FILE, edj_path, (int)PATH_MAX);
        +
        +   // Main Layout
        +   ad->gui2_layout = elm_layout_add(ad->win);
        +   evas_object_size_hint_weight_set(ad->gui2_layout, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
        +   elm_layout_file_set(ad->gui2_layout, edj_path, "object_text_class_application");
        +   evas_object_show(ad->gui2_layout);
        +
        +   // Add group1
        +   ad->edje_object_1 = edje_object_add(evas_object_evas_get(ad->win));
        +   evas_object_size_hint_weight_set(ad->edje_object_1, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
        +   edje_object_file_set(ad->edje_object_1, edj_path, "edje_example");
        +   // Check the object loading error
        +   if (edje_object_load_error_get(ad->edje_object_1) != EDJE_LOAD_ERROR_NONE)
        +   {
        +      evas_object_del(ad->edje_object_1);
        +
        +      return;
        +   }
        +   evas_object_show(ad->edje_object_1);
        +   elm_object_part_content_set(ad->gui2_layout, "edje.swallow.group1", ad->edje_object_1);
        +
        +   // Addgroup2
        +   ad->edje_object_2 = edje_object_add(evas_object_evas_get(ad->win));
        +   evas_object_size_hint_weight_set(ad->edje_object_2, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
        +   edje_object_file_set(ad->edje_object_2, edj_path, "edje_example");
        +   // Check object loading errors
        +   if (edje_object_load_error_get(ad->edje_object_2) != EDJE_LOAD_ERROR_NONE)
        +   {
        +      evas_object_del(ad->edje_object_2);
        +
        +      return;
        +   }
        +   evas_object_show(ad->edje_object_2);
        +   elm_object_part_content_set(ad->gui2_layout, "edje.swallow.group2", ad->edje_object_2);
        +
        +   // Add spinner
        +   ad->spinner = elm_spinner_add(ad->win);
        +   evas_object_size_hint_weight_set(ad->spinner, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
        +   evas_object_size_hint_align_set(ad->spinner, EVAS_HINT_FILL, EVAS_HINT_FILL);
        +   elm_spinner_min_max_set(ad->spinner, 1, 64);
        +   elm_spinner_step_set(ad->spinner, 1);
        +   evas_object_show(ad->spinner);
        +   elm_spinner_value_set(ad->spinner, 10);
        +   elm_object_part_content_set(ad->gui2_layout, "edje.swallow.spinner", ad->spinner);
        +   elm_naviframe_item_simple_push(ad->navifr, ad->gui2_layout);
        +}
        + + +

        Figure: Second application screen

        +

        Second application screen

      4. +
      + +

      Setting the Text Class for All Edje Objects

      + +

      To set the text class globally, use the edje_test_class_set() function:

      + +
        +
      1. +

        Add a box and pack the buttons into it. Add the Global button and register a callback for clicking:

        + +
        static void
        +_create_text_class_gui(void *data, Evas_Object *obj, void *event_info)
        +{
        +   Evas_Object *box, *button;
        +   // Add the box
        +   box = elm_box_add(ad->gui2_layout);
        +   evas_object_size_hint_weight_set(box, EVAS_HINT_EXPAND, 0.0);
        +   evas_object_size_hint_align_set(box, EVAS_HINT_FILL, 0.0);
        +   elm_box_horizontal_set(box, EINA_TRUE);
        +   evas_object_show(box);
        +
        +   button = elm_button_add(ad->gui2_layout);
        +   evas_object_size_hint_align_set(button, EVAS_HINT_FILL, EVAS_HINT_FILL);
        +   evas_object_size_hint_weight_set(button, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
        +   elm_object_text_set(button, "Global");
        +   evas_object_show(button);
        +   evas_object_smart_callback_add(button, "clicked", _edje_text_class_set, ad);
        +   elm_box_pack_end(box, button);
        +
        +   elm_object_part_content_set(ad->gui2_layout, "edje.swallow.buttons", box);
        +
        +   elm_naviframe_item_simple_push(ad->navifr, ad->gui2_layout);
        +}
        +
      2. + +
      3. +

        The callback contains functions for setting the text class globally:

        + +
        static void
        +_edje_text_class_set(void *data, Evas_Object *obj, void *event_info)
        +{
        +   appdata_s *ad = data;
        +   edje_text_class_set("custom_text_class", "Sans", elm_spinner_value_get(ad->spinner));
        +}
        + +

        Clicking the Global button recalculates all text parts in every Edje object that contains the custom_text_class text class and changes their size.

        + + +

        Figure: Changing the text class globally

        +

        Changing the text class globally

      4. + +
      + +

      Setting the Text Class of a Specific Object

      + +

      To set the text class of a specific Edje object, use the edje_object_test_class_set() function.

      + +
        +
      1. +

        Add 2 more buttons, Set1 and Set2.

        +

        The first button sets the text class of the first Edje object on the left, and the second sets the text class of the other object, respectively.

        + +
        static void
        +_create_text_class_gui(void *data, Evas_Object *obj, void *event_info)
        +{
        +   button = elm_button_add(ad->gui2_layout);
        +   evas_object_size_hint_align_set(button, EVAS_HINT_FILL, EVAS_HINT_FILL);
        +   evas_object_size_hint_weight_set(button, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
        +   elm_object_text_set(button, Set1);
        +   evas_object_show(button);
        +   evas_object_smart_callback_add(button, "clicked", _edje_object_text_class_set_1, ad);
        +   elm_box_pack_end(box, button);
        +
        +   button = elm_button_add(ad->gui2_layout);
        +   evas_object_size_hint_align_set(button, EVAS_HINT_FILL, EVAS_HINT_FILL);
        +   evas_object_size_hint_weight_set(button, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
        +   elm_object_text_set(button, Set2);
        +   evas_object_show(button); 
        +   evas_object_smart_callback_add(button, "clicked", _edje_object_text_class_set_2, ad);
        +   elm_box_pack_end(box, button);
        +}
        +
      2. + +
      3. +

        Add callbacks:

        + +
        static void
        +_edje_object_text_class_set_1(void *data, Evas_Object *obj, void *event_info)
        +{
        +   appdata_s *ad = data;
        +   edje_object_text_class_set(ad->edje_object_1, "custom_text_class", "Sans", elm_spinner_value_get(ad->spinner));
        +}
        +
        +static void
        +_edje_object_text_class_set_2(void *data, Evas_Object *obj, void *event_info)
        +{
        +   appdata_s *ad = data;
        +   edje_object_text_class_set(ad->edje_object_2, "custom_text_class", "Sans", elm_spinner_value_get(ad->spinner));
        +}
        +
      4. + +
      5. +

        Test the functionality:

        + +
          +
        1. Set the size of the left object to 16. + +

          Font size 16

        2. + +
        3. Set the size of the right object to 44. + +

          Font size 44

        4. + +
        5. Set the size of the right object to 22. + +

          Font size 22

        6. +
        +
      6. +
      + + +

      Getting the Text Class of an Object

      + +

      To get the text class of a specific Edje object, use the edje_object_test_class_get() function.

      + +
        +
      1. +

        Add 2 more buttons, Get1 and Get2. The first gets the text class of the first Edje object on the left and sets into that object result, and the second gets the text class of the other object, respectively.

        + +
        static void
        +_create_text_class_gui(void *data, Evas_Object *obj, void *event_info)
        +{
        +   button = elm_button_add(ad->gui2_layout);
        +   evas_object_size_hint_align_set(button, EVAS_HINT_FILL, EVAS_HINT_FILL);
        +   evas_object_size_hint_weight_set(button, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
        +   elm_object_text_set(button, Get1);
        +   evas_object_show(button); 
        +   evas_object_smart_callback_add(button, "clicked", _edje_object_text_class_get_1, ad);
        +   elm_box_pack_end(box, button);
        +
        +   button = elm_button_add(ad->gui2_layout);
        +   evas_object_size_hint_align_set(button, EVAS_HINT_FILL, EVAS_HINT_FILL);
        +   evas_object_size_hint_weight_set(button, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
        +   elm_object_text_set(button, Get2);
        +   evas_object_show(button); 
        +   evas_object_smart_callback_add(button, "clicked", _edje_object_text_class_get_2, ad);
        +   elm_box_pack_end(box, button);
        +}
        +
      2. + +
      3. +

        Add callbacks:

        +
        static void
        +_edje_object_text_class_get_1(void *data, Evas_Object *obj, void *event_info)
        +{
        +   appdata_s *ad = data;
        +   char *font;
        +   Evas_Font_Size size;
        +   char text_class[PATH_MAX] = {0, };
        +
        +   edje_object_text_class_get(ad->edje_object_1, "custom_text_class", &font, &size);
        +   snprintf(text_class, PATH_MAX, "font{%s} size{%d}", font, size);
        +   edje_object_part_text_set(ad->edje_object_1, "text_example", text_class);
        +}
        +
        +static void
        +_edje_object_text_class_get_2(void *data, Evas_Object *obj, void *event_info)
        +{
        +   appdata_s *ad = data;
        +   char *font;
        +   Evas_Font_Size size;
        +   char text_class[PATH_MAX] = {0, };
        +
        +   edje_object_text_class_get(ad->edje_object_2, "custom_text_class", &font, &size);
        +   snprintf(text_class, PATH_MAX, "font{%s} size{%d}", font, size);
        +   edje_object_part_text_set(ad->edje_object_2, "text_example", text_class);
        +}
        + + +

        The following figure shows the result.

        + +

        Figure: Displaying text class changes

        +

        Displaying text class changes

        + + +

        Changing the custom_text_class for the first object changed its font size to 16 size, while changing the custom_text_class for the second object changes its font size to 22.

      4. +
      + + + + + + +
      + +Go to top + + + + + + + diff --git a/org.tizen.ui.guides/html/native/efl/efl_overview_n.htm b/org.tizen.ui.guides/html/native/efl/efl_overview_n.htm new file mode 100755 index 0000000..80a2aef --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/efl_overview_n.htm @@ -0,0 +1,135 @@ + + + + + + + + + + + + + EFL Overview: Getting Started with EFL UI Programming + + + + + +
      + +

      EFL Overview: Getting Started with EFL UI Programming

      + +

      EFL stands for Enlightenment Foundation Libraries. Enlightenment is a project consisting of the Enlightenment window manager, EFL libraries, and various utilities and applications. The Enlightenment team needed powerful libraries to handle, among others, rendering, main loops, and events, so EFL was introduced during the development of the Enlightenment window manager to fill these gaps. EFL is now widely used outside of the Enlightenment window manager.

      + +

      EFL Features

      + +

      The general UI design features include:

      +
        +
      • UI component support +

        You can use basic core UI components, such as buttons, genlists, and sliders, and also create a layout for the Tizen native application by using container UI components.

      • +
      • Theme support +

        You can create and change a theme that is a preset package containing graphical details. Tizen supports specifying the UI look and feel through a default theme.

      • +
      • Font settings +

        Tizen supports various methods to change the font of your application to another system default font or your own font.

      • +
      • Scalability +

        Elementary provides a way to scale UI components in order to be comfortably used with a finger and to make the text more readable.

      • +
      • Event handling and main loop +

        The user interface relies on callbacks designed to react to EFL events generated by the system or the user. You can handle various events, from low-level Ecore system events to Evas smart object events that happen on object collections.

        +

        The Ecore library provides a main loop abstraction that gets you data when it is available and sends you events. You can handle the main loop and use threads with the Ecore main loop.

      • +
      • UI animating with animators and effects +

        Tizen supports various methods to create animations and effects in your application.

      • +
      • Data types and tools support +

        Tizen supports a core library for data types and some useful tools.

      • +
      • Hardware input event support +

        Tizen supports the handling of hardware input events.

      • +
      + +

      EFL Characteristics

      + +

      EFL is aimed at not only desktop computers but also touch-screen and embedded devices, making EFL applications portable to many different types of devices. Applications do not need to care about the types of devices and profiles they run on. Instead of changing the code, it is typically enough to simply configure the applications for different devices.

      + +

      The key characteristics of EFL include:

      + +
        +
      • Performance +

        The main reason Tizen adopted EFL as its native toolkit is its speed. EFL is highly optimized by using a scene graph and retained-mode rendering. EFL is fast even in software rendering.

      • +
      • Small memory footprint +

        Despite its fast performance, EFL's memory footprint is smaller than that of other toolkits with similar features. A small memory footprint is useful in the embedded world, since embedded devices do not normally have much memory.

      • +
      • Back-end engine support +

        EFL supports several back-end engines, such as X11 (OpenGL, Xlib, Xcb), Wayland (OpenGL, SHM), Direct Framebuffer, DRM, memory buffers, PS3 native, Windows, and Mac OS. Applications do not need to deal with each back-end engine separately.

      • +
      • GUI and logic separation +

        EFL supports GUI layout and logic separation by having the layout description in a plain text file and the logic code in the C or C++ source files.

      • +
      • Themeable +

        An EFL theme can be changed at runtime without restarting the application. UI components are customizable so that each application can create its own customized theme to overlay above the default theme, adding customized versions of UI components to achieve a specific look and feel.

      • +
      • Scalable +

        EFL supports a scale factor that affects the size of objects in the application at runtime. By configuring the scale factor, applications can scale up and down as needed. The scale factor also supports a default setting that allows applications to scale nicely out-of-the-box.

      • +
      • Animations +

        EFL supports different types of animations. Evas supports Evas maps with low-level APIs for performing 2D, 2.5D, and 3D object transformations. Edje supports pre-defined transitions and wrapping of Evas maps. Elementary supports transit APIs for various types of animations, which can be combined.

      • +
      • Hardware acceleration +

        EFL supports OpenGL® and OpenGL-ES acceleration.

      • +
      + + +

      EFL Libraries

      + +

      The EFL are a set of layered libraries, as shown in the following diagram:

      + +

      Figure: EFL layers

      +

      EFL layers

      + +

      When you create a basic EFL application, you use the following main libraries as a basis:

      + +
        +
      • Elementary is the top-most library with which you create your EFL application. It provides all the functions you need to create a window, create simple and complex layouts, manage the life cycle of a view, and add UI components. The full list of UI components that can be used in Tizen can be found in Mobile UI Components and Wearable UI Components.
      • +
      • Edje is the library used by Elementary to provide a powerful theme. You can also use Edje to create your own objects and use them in your application. You may also want to extend the default theme. You will find more information about Edje and the EDC format in Themes and Customizing Components.
      • +
      • Ecore is the library which manages the main loop of your application. The main loop is one of the most important concepts you need to know about to develop an application. The main loop is where events are handled, and where you interact with the user through the callback mechanism. The main loop mechanisms are explained in the Handling the Main Loop guide.
      • +
      • Evas is the canvas engine. Evas is responsible for managing the drawing of your content. All graphical objects that you create are Evas objects. Evas handles the entire state of the window by filling the canvas with objects and manipulating their states. In contrast to other canvas libraries, such as Cairo, OpenGL, and XRender, Evas is not a drawing library but a scene graph library that retains the state of all objects. The Evas concept is explained in Evas Rendering Concept and Method. Evas objects are created and then manipulated until they are no longer needed, at which point they are deleted. This allows the developer to work in the same terms that a designer thinks in: it is a direct mapping, as opposed to having to convert the concepts into drawing commands in the right order, calculate minimum drawing calls needed to get the job done, and so on.
      • +
      • Eina is the basis of all the EFL libraries. Eina is a toolbox that implements an API for data types in an efficient way. It contains all the functions needed to create lists and hashes, manage shared strings, open shared libraries, and manage errors and memory pools. Eina concepts are explained in Data Types and Tools.
      • +
      + +

      The EFL include more than just the above libraries, but the above are the most important libraries to get started with. The other libraries, such as Eet, Embryo, and Emotion, will be explored later in the programming guides and the API Reference (in mobile and wearable applications).

      + +

      The Hello World example shows you how to develop your first application with the EFL.

      + + + +
      + +Go to top + + + + + + + \ No newline at end of file diff --git a/org.tizen.ui.guides/html/native/efl/elementary_animation_n.htm b/org.tizen.ui.guides/html/native/efl/elementary_animation_n.htm new file mode 100755 index 0000000..f956971 --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/elementary_animation_n.htm @@ -0,0 +1,872 @@ + + + + + + + + + + + + + Elementary Animations + + + + + +
      + +

      Elementary Animations

      + +

      Elementary transitions (Elm_Transit) allow you to apply various transition effects, such as translation and rotation, to Evas objects. Elementary transitions are mostly based on Ecore animators, but provide some transition methods at a higher level of abstraction. Elementary transitions provide a simpler way of animating objects than Ecore animators or Edje animations.

      + +

      To use Elementary transitions, you must create an Elm_Transit object and define the desired transitions using the methods of this object. After the transitions are registered, they will be automatically managed: their callback functions will be called for the set duration, and they will be deleted upon completion.

      + +

      Use Elementary transitions only when Edje animations are not sufficient. Edje animations are better at handling transitions, have more flexibility, and can be manipulated inside themes. The only drawback is that Edje animations have their own definition language. If you want to code with the C language, use Elementary transitions.

      + +

      Getting Started

      +

      The first thing you need to do when creating an transition with Elm_Transit is to build your transit object using the elm_transit_add() function:

      + +
      Elm_Transit *transit = elm_transit_add();
      + +

      You now have an Elm_Transit instance that will allow you to perform transitions on one or more objects. The transit object holds the information about the target objects and the transition effects that will be used. The transit object also contains information about animation duration, number of repetitions, auto-reverse, and so on. The transit object starts playing as soon as the application enters the main loop.

      + +

      Adding Objects to an Animation

      + +

      You can add your Evas objects to your transition using the elm_transit_object_add() function:

      + +
      elm_transit_object_add(Elm_Transit *transit, Evas_Object *obj)
      + +

      The first argument is the Elm_Transit instance that handles the transition. The second argument is the Evas object to animate.

      + + + + + + + + + + +
      Note

      The Evas object can be a low-level component, such as a rectangle, but also a UI component, such as a button, image, or calendar.

      +

      If you want to animate an Evas object handled by a container, such as a box, you need to either unpack the object before the animation or animate the whole container.

      + +

      If you want to know which objects are currently in your transition, use the elm_transit_objects_get() function. You will get a list of all the objects that are subject to the transition.

      + +

      At any time, you can remove objects from the transition:

      + +
      elm_transit_object_remove(Elm_Transit *transit, Evas_Object *obj)
      + +

      The first argument is the Elm_Transit instance that handles the transition. The second argument is the Evas object to remove from the transition.

      + + + + + + + + + + +
      Note
      After you have added at least one Evas object to your transition, if the list of objects gets emptied somehow, be it because the transition has been terminated or all objects have been deleted, the transition will be automatically deleted. Otherwise, you will have to delete the transition by yourself using the elm_transit_del() function. If you delete the transit while the transition is running, the transition will stop.
      + +

      Adding Images to an Animation

      + +

      If you do not want to manage UI components for animating images, Elm_Transit provides a helper function for directly manipulating images:

      + +
      +elm_transit_effect_image_animation_add(Elm_Transit *transit, Eina_List *images)
      +
      + +

      The first argument is the Elm_Transit instance that handles the transition. The second argument is a list of the image paths.

      + + + + + + + + + + +
      Note
      This list and its contents will be deleted after the effect ends by the elm_transit_effect_image_animation_context_free() function.
      + +

      You can now define your image transitions exactly the same way as with any Evas object.

      + +

      The following example shows how to use Elm_Transit with images:

      + +
      char buf[PATH_MAX];
      +Eina_List *images = NULL;
      +Elm_Transit *transit = elm_transit_add();
      +snprintf(buf, sizeof(buf), "%s/images/btn_default.png", PACKAGE_DATA_DIR);
      +images = eina_list_append(images, eina_stringshare_add(buf));
      +snprintf(buf, sizeof(buf), "%s/images/btn_hover.png", PACKAGE_DATA_DIR);
      +images = eina_list_append(images, eina_stringshare_add(buf));
      +elm_transit_effect_image_animation_add(transit, images);
      + +

      Animation Duration

      + +

      With Elm_Transit, setting the transition duration is mandatory. To set the duration, use the elm_transit_duration_set() function:

      + +
      elm_transit_duration_set(Elm_Transit *transit, double duration)
      + +

      The first argument is the Elm_Transit instance that handles the transition. The second argument is the duration in seconds.

      + + + + + + + + + + +
      Note
      The purpose of Elm_Transit is to abstract the low-level details of object interpolation, so you cannot create an infinite transition by specifying the duration. However, you can make your transition last forever using the repeat function.
      + +

      The following example shows how to make a complete revolution of the target Evas object in 2 seconds:

      + +
      +Elm_Transit *transit = elm_transit_add();
      +elm_transit_object_add(transit, my_evas_object);
      +elm_transit_effect_rotation_add(transit, 0.0, 360);
      +elm_transit_duration_set(transit, 2.0);
      +elm_transit_go(transit);
      +
      + +

      To get the duration of the transition, use the elm_transit_duration_get() function.

      + +

      Animation Acceleration Mode ("Tween Mode")

      + +

      Elm_Transit supports a number of built-in interpolation methods. By default, all interpolations are linear. If you want to change the animation's dynamics, use the elm_transit_tween_mode_set() function:

      + +
      elm_transit_tween_mode_set(Elm_Transit *transit, Elm_Transit_Tween_Mode tween_mode)
      + +

      The first argument is the Elm_Transit instance that handles the transition. The second argument is the tween mode of the transition, which can be one of the following:

      +
        +
      • ELM_TRANSIT_TWEEN_MODE_LINEAR: The default mode.
      • +
      • ELM_TRANSIT_TWEEN_MODE_SINUSOIDAL: The transition starts with acceleration and ends with deceleration.
      • +
      • ELM_TRANSIT_TWEEN_MODE_DECELERATE: The transition decelerates over time.
      • +
      • ELM_TRANSIT_TWEEN_MODE_ACCELERATE: The transition accelerates over time.
      • +
      • ELM_TRANSIT_TWEEN_MODE_BEZIER_CURVE: The transition uses an interpolated cubic-bezier curve adjusted with parameters.
      • +
      + +

      To get the current tween mode, use the elm_transit_tween_mode_get() function.

      + +

      Animation Repeat

      + +

      To set a transition to repeat, use the elm_transit_repeat_times_set() function:

      + +
      elm_transit_repeat_times_set(Elm_Transit *transit, int repeat)
      + +

      The function takes the following arguments:

      +
        +
      • The transition you want to repeat.
      • +
      • The number of times the transition repeats.
      • +
      + + + + + + + + + + +
      Note
      If the repeat argument is set to 0, the transition will not loop at all. If set to 1, the transition will run twice. If set to a negative value, the transition will repeat forever.
      + +

      To get the repeat value, use the elm_transit_repeat_times_get() function. The default value is 0.

      + +

      The following example shows how to make an Evas object spin for 3 complete revolutions in 6 seconds:

      + +
      Elm_Transit *transit = elm_transit_add();
      +elm_transit_object_add(transit, my_evas_object);
      +elm_transit_effect_rotation_add(transit, 0.0, 360);
      +elm_transit_duration_set(transit, 2.0);
      +elm_transit_repeat_set(transit, 3.0);
      +elm_transit_go(transit);
      + +

      Animation Auto-reverse

      + +

      Elm_Transit provides a helper function for automatically reversing the transition once it finishes:

      + +
      elm_transit_auto_reverse_set(Elm_Transit *transit, Eina_Bool reverse)
      + +

      The first argument is the transition you want to reverse. The second argument is the reverse state. If the reverse state is set to EINA_TRUE, this function will perform the same transition backwards as soon as the first transition is complete.

      + + + + + + + + + + +
      Note
      +

      Reversing the transition doubles the duration of the transition. Moreover, if the transition is set to repeat, the transition will run back and forth until the repeat count is finished.

      +

      You can calculate the duration as follows if both auto-reverse and repeat are set: 2 * duration * repeat.

      +
      + +

      The following example shows how to make an object perform half a turn and then reverse the animation to its original position in 4 seconds:

      + +
      +Elm_Transit *transit = elm_transit_add();
      +elm_transit_object_add(transit, my_evas_object);
      +elm_transit_effect_rotation_add(transit, 0.0, 360);
      +elm_transit_duration_set(transit, 2.0);
      +elm_transit_auto_reverse_set(transit, EINA_TRUE);
      +elm_transit_go(transit);
      +
      + +

      To determine whether the auto-reverse mode is enabled, use the elm_transit_auto_reverse_get() function.

      + +

      Transitions

      + +

      We distinguish two main transition types:

      +
        +
      • Transitions that are applied to the properties of objects, such as position, size, angle, and color.
      • +
      • Transitions from one object to another, where the first object is hidden to let the second one appear.
      • +
      +

      All transitions are based on the same principle: we set the starting and the ending values for the properties we want to animate, we then set the lifespan of the animation, and finally we inquire the preferred interpolation method (such as linear, acceleration, or bounce).

      + +

      You must declare the transitions after the parent window has been created, since the transition effects make use of the geometric properties of the parent window. If the parent window does not yet exist when calculating the interpolation, the interpolation may end up being based on wrong information.

      + +

      Built-in Transitions

      + +

      Elm_Transit provides several built-in transition definitions that are useful for the most common cases, so you that will not have to code them from scratch.

      + +

      All these built-in effects are implemented as follows:

      + +
      Elm_Transit *transit = elm_transit_add();
      +elm_transit_effect_add(transit,
      +                       elm_transit_effect_translation_op,
      +                       elm_transit_effect_translation_context_new(),
      +                       elm_transit_effect_translation_context_free);
      + +
        +
      • transit: The Elm_Transit object that contains the target Evas objects and all the information needed to setup the transition.
      • +
      • elm_transit_effect_translation_op: The callback function that performs the transition (resizing interpolation in this example).
      • +
      • elm_transit_effect_translation_context_new(): The callback function that returns the context used in the transition for calculations. In this example, the context is the coordinates of the before and after objects.
      • +
      • elm_transit_effect_translation_context_free: The callback function that frees up the memory once the transition is complete.
      • +
      + +

      All the definitions above can be rewritten as follows:

      + +
      +Elm_Transit *transit = elm_transit_add();
      +elm_transit_effect_translation_add(transit, from_x, from_y, to_x, to_y);
      +
      + +

      Translation

      +

      To perform a translation on an Evas object, use the following method:

      + +
      +elm_transit_effect_translation_add(Elm_Transit *transit,
      +                                   Evas_Coord from_dx,
      +                                   Evas_Coord from_dy,
      +                                   Evas_Coord to_dx,
      +                                   Evas_Coord to_dy)
      +
      + +
        +
      • The first argument is the transit object that contains (among other things) all the Evas objects subject to the translation.
      • +
      • from_dx: The starting X coordinate (source).
      • +
      • from_dy: The starting Y coordinate (source).
      • +
      • to_dx: The ending X coordinate (destination).
      • +
      • to_dy: The ending Y coordinate (destination).
      • +
      + +

      The following example shows how to slide an Evas object (a rectangle) on a 45-degree diagonal, from bottom-left to top-right, at a constant speed, and in 1 second:

      + +
      +Elm_Transit *transit = elm_transit_add();
      +elm_transit_object_add(transit, rectangle);
      +elm_transit_effect_translation_add(transit, 0, 0, 280, 280);
      +elm_transit_duration_set(transit, 1);
      +elm_transit_go(transit);
      +
      + +

      Color Transition

      + +

      Color transitions allow you to dynamically change the color of Evas objects. The first argument is the transit object, while the other arguments will be used to define the color transition using RGB colors. There is also an alpha channel that controls the opacity of the color (the background of the object, not the object itself).

      + +
      +elm_transit_effect_color_add(Elm_Transit *transit,
      +                             unsigned int from_r,
      +                             unsigned int from_g,
      +                             unsigned int from_b,
      +                             unsigned int from_a,
      +                             unsigned int to_r,
      +                             unsigned int to_g,
      +                             unsigned int to_b,
      +                             unsigned int to_a)
      +
      + +
        +
      • transit: The transit object that contains (among other things) all the Evas objects subject to the translation.
      • +
      • from_r: The start value for "Red".
      • +
      • from_g: The start value for "Green".
      • +
      • from_b: The start value for "Blue".
      • +
      • from_a: The start value for "Alpha".
      • +
      • to_r: The end value for "Red".
      • +
      • to_g: The end value for "Green".
      • +
      • to_b: The end value for "Blue".
      • +
      • to_a: The end value for "Alpha".
      • +
      + +

      The following example shows how to transit a rectangle from red to blue in 3 seconds:

      + +
      +Elm_Transit *transit = elm_transit_add();
      +elm_transit_object_add(transit, rectangle);
      +elm_transit_effect_color_add(transit, // Target object
      +                             255, 0, 0, 255, // From color
      +                             0, 0, 255, 255); // To color
      +elm_transit_duration_set(transit, 3);
      +elm_transit_go(transit);
      +
      + +

      Rotation

      + +
      elm_transit_effect_rotation_add(Elm_Transit *transit, float from_degree, float to_degree)
      + +
        +
      • transit: The transit object that contains (among other things) all the Evas objects subject to the translation.
      • +
      • from_degree: The start degree of rotation.
      • +
      • to_degree: The end degree of rotation.
      • +
      + +

      This function can be used to perform a rotation on any Evas object. It works the same way as the other transit effects and takes two arguments for the starting and ending angles. Note that if you apply a rotation on multiple objects, they will individually mill around and not act as a group. If you want several objects to revolve around a common point, you must encapsulate the objects into a single parent object and apply the rotation to the parent object. The following example shows how to achieve this:

      + +
      +// Parent container
      +Evas_Object *parent = elm_box_add(my_window);
      +evas_object_show(parent);
      +elm_box_horizontal_set(parent, EINA_TRUE);
      +elm_box_homogeneous_set(parent, EINA_TRUE);
      +
      +// Button 1
      +Evas_Object *btn1 = elm_button_add(parent);
      +elm_object_text_set(btn1, "Btn1");
      +elm_box_pack_start(parent, btn1);
      +evas_object_show(btn1);
      +
      +// Button 2
      +Evas_Object *btn2 = elm_button_add(parent);
      +elm_object_text_set(btn2, "Btn2");
      +elm_box_pack_end(parent, btn2);
      +evas_object_show(btn2);
      +
      +// Make the parent container do a 360 degrees spin
      +Elm_Transit *transit = elm_transit_add();
      +elm_transit_object_add(transit, parent);
      +elm_transit_effect_rotation_add(transit, 0.0, 360);
      +elm_transit_duration_set(transit, 2.0);
      +elm_transit_go(transit);
      +
      + +

      Wipe Effect

      + +

      The wipe effect is designed to dynamically hide or show any element on the scene.

      + +
      +elm_transit_effect_wipe_add(Elm_Transit *transit,
      +                            Elm_Transit_Effect_Wipe_Type type,
      +                            Elm_Transit_Effect_Wipe_Dir dir)
      +
      + +

      In addition to the Elm_Transit instance passed as the first argument, the function takes the following arguments:

      + +
        +
      • type: The wipe type Elm_Transit_Effect_Wipe_Type defines whether to show or hide the target elements. The value can be one of the following: +
          +
        • ELM_TRANSIT_EFFECT_WIPE_TYPE_HIDE
        • +
        • ELM_TRANSIT_EFFECT_WIPE_TYPE_SHOW
        • +
        +
      • +
      • dir: The wipe direction Elm_Transit_Effect_Wipe_Dir defines in which direction the target will progressively appear or disappear. The value can be one of the following: +
          +
        • ELM_TRANSIT_EFFECT_WIPE_DIR_LEFT
        • +
        • ELM_TRANSIT_EFFECT_WIPE_DIR_RIGHT
        • +
        • ELM_TRANSIT_EFFECT_WIPE_DIR_UP
        • +
        • ELM_TRANSIT_EFFECT_WIPE_DIR_DOWN
        • +
        +
      • +
      + +

      The following example shows how to make an object disappear progressively from left to right:

      + +
      +Elm_Transit *transit = elm_transit_add();
      +elm_transit_object_add(transit, my_evas_object);
      +elm_transit_effect_wipe_add(transit,
      +                            ELM_TRANSIT_EFFECT_TYPE_HIDE,
      +                            ELM_TRANSIT_EFFECT_WIPE_DIR_RIGHT);
      +elm_transit_duration_set(transit, 2.0);
      +elm_transit_go(transit);
      +
      + +

      Zoom Effect

      +

      Elm_Transit provides a zoom function.

      + +
      +elm_transit_effect_zoom_add(Elm_Transit *transit,
      +                            float from_rate,
      +                            float to_rate)
      +
      + +
        +
      • transit: The transit object that contains (among other things) all the Evas objects subject to the translation.
      • +
      • from_rate: The starting level of the zoom.
      • +
      • to_rate: The ending level of the zoom.
      • +
      + +

      The from_rate argument defines the scale of the target objects at the beginning of the animation. A value of 1 represents the initial scale of the objects.

      + +

      Setting the value of the to_rate argument to 2 will double the size of the target objects (double the width and double the height). When using this effect, the width and height of a target object will remain proportional to one another. If you want to customize the zoom effect, use the elm_transit_effect_resizing_add() function.

      + +

      The following example shows how to implement a zoom-out transition. At the end of the 2-secondstransition, the animated object will be half its original size.

      + +
      +Elm_Transit *transit = elm_transit_add();
      +elm_transit_object_add(transit, my_evas_object);
      +elm_transit_effect_zoom_add(transit, 1, 0.5);
      +elm_transit_duration_set(transit, 2.0);
      +elm_transit_go(transit);
      +
      + +

      Resizing Effect

      + +

      The resizing effect allows you to design an interpolation of the width and height attributes of one or more target elements.

      + +
      +elm_transit_effect_resizing_add(Elm_Transit *transit,
      +                                Evas_Coord from_w,
      +                                Evas_Coord from_h,
      +                                Evas_Coord to_w,
      +                                Evas_Coord to_h)
      +
      + +
        +
      • transit: The transit object that contains (among other things) all the Evas objects subject to the translation.
      • +
      • from_w: The starting width.
      • +
      • from_h: The starting height.
      • +
      • to_w: The ending width.
      • +
      • to_h: The ending height.
      • +
      + +

      The from_w and from_h arguments define the size at the beginning of the animation. The to_w and to_h arguments define the size at the end.

      + + + + + + + + + + +
      Note
      If you are planning to use this method to hide an Evas object by setting one of the length attributes to zero, consider using the elm_transit_effect_wipe_add() function instead.
      + +

      The following example shows how to make a rectangle exchange its width and height properties in a 2-second transition:

      + +
      +Evas_Coord w, h;
      +evas_object_geometry_get(my_evas_object, NULL, NULL, &w, &h);
      +
      +Elm_Transit *transit = elm_transit_add();
      +elm_transit_object_add(transit, my_evas_object);
      +elm_transit_effect_resize_add(transit, // Transition object
      +                              w, h, // Original sizing
      +                              h, w); // Target sizing
      +elm_transit_duration_set(transit, 2.0);
      +elm_transit_go(transit);
      +
      + +

      Flip Effect

      +

      This transition combines the target Evas objects in pairs, so that one object will show up while the other one disappears. This association relates the even objects in the transit list of objects with the odd ones. The even objects are shown at the beginning of the animation, and the odd objects shown when the transition is complete. In other words, the effect applies to each pair of objects in the order in which they are listed in the transit list of objects.

      + +

      The flip effect itself is a pseudo-3D effect where the first object in the pair is the front object and the second one is the back object. When the transition launches, the front object rotates around a preferred axis in order to let the back object take its place.

      + +
      +elm_transit_effect_flip_add(Elm_Transit *transit,
      +                            Elm_Transit_Effect_Flip_Axis axis,
      +                            Eina_Bool cw)
      +
      + +

      The first argument is the transit object. The second argument is the preferred axis of rotation:

      +
        +
      • ELM_TRANSIT_EFFECT_FLIP_AXIS_X
      • +
      • ELM_TRANSIT_EFFECT_FLIP_AXIS_Y
      • +
      + +

      The third argument is the direction of the rotation:

      +
        +
      • EINA_TRUE is clockwise.
      • +
      • EINA_FALSE is counter-clockwise.
      • +
      + +

      The following example shows how to create a coin that flips indefinitely. Note that we use images as Elementary UI components for demonstration purposes. You can use the elm_transit_effect_image_animation_add() function if you do not want to bother creating UI components.

      + +
      +// Coin Heads
      +Evas_Object *coin_heads = elm_image_add(ad->win);
      +if (!elm_image_file_set(coin_heads, IMG_DIR"/coin_heads.png", NULL))
      +   printf("error: could not load image");
      +elm_win_resize_object_add(ad->win, coin_heads);
      +
      +// Coin Tails
      +Evas_Object *coin_tails = elm_image_add(ad->win);
      +if (!elm_image_file_set(coin_tails, IMG_DIR"/coin_tails.png", NULL))
      +   printf("error: could not load image");
      +elm_win_resize_object_add(ad->win, coin_tails);
      +
      +// Transition definition
      +Elm_Transit *transit = elm_transit_add();
      +elm_transit_object_add(transit, coin_heads);
      +elm_transit_object_add(transit, coin_tails);
      +elm_transit_duration_set(transit, 2.0);
      +elm_transit_auto_reverse_set(transit, EINA_TRUE);
      +elm_transit_repeat_times_set(transit, -1);
      +elm_transit_effect_flip_add(transit, ELM_TRANSIT_EFFECT_FLIP_AXIS_X, EINA_TRUE);
      +elm_transit_go(transit);
      +
      + +

      Figure: Coin flip

      +

      Coin flip

      + +

      Resizable Flip Effect

      +

      In the flip example above, we used two objects that have the same size. However, you may sometimes want to flip from one object to another object with different size attributes. The most common example would be using buttons with dimensions that depend on their contents (such as labels). If you decide to use the classic elm_transit_effect_flip_add() function, the size of the object will change at the moment one object becomes completely hidden and the other one begins to show up. If you wish to interpolate the size attributes as well, use the elm_transit_effect_resizable_flip_add() function:

      + +
      +elm_transit_effect_resizable_flip_add(Elm_Transit *transit,
      +                                      Elm_Transit_Effect_Flip_Axis axis,
      +                                      Eina_Bool cw)
      +
      + +

      The first argument is the transit object. The second argument is the preferred axis of rotation:

      +
        +
      • ELM_TRANSIT_EFFECT_FLIP_AXIS_X
      • +
      • ELM_TRANSIT_EFFECT_FLIP_AXIS_Y
      • +
      + +

      The third argument is the direction of the rotation:

      +
        +
      • EINA_TRUE is clockwise.
      • +
      • EINA_FALSE is counter-clockwise.
      • +
      + +

      This function works the exact same way as the standard flip effect function.

      + +

      Fade Effect

      + +

      This effect is used to transition from one Evas object to another one using a fading effect: the first object will slowly disappear to let the second object take its place.

      + +
      elm_transit_effect_fade_add(Elm_Transit *transit)
      + +

      This effect is applied to each pair of objects in the order in which they are listed in the transit list of objects. The first object in the pair will be the before object and the second one will be the after object.

      + +

      Building on the coin flip example, the following example shows how to fade out one face of the coin while fading in the other face:

      + +
      +Elm_Transit *transit = elm_transit_add();
      +elm_transit_object_add(transit, coin_heads);
      +elm_transit_object_add(transit, coin_tails);
      +elm_transit_duration_set(transit, 2.0);
      +elm_transit_effect_fade_add(transit);
      +elm_transit_go(transit);
      +
      + +

      If you simply want to hide an object with a fade transition, consider using a transparent after object.

      + +

      Blend Effect

      + +

      Another transition involving at least two Evas objects is the blend effect. This transition makes the before object blurry before the after object appears.

      + +
      elm_transit_effect_blend_add(Elm_Transit *transit)
      + +

      The argument is the transition target of the blend effect.

      + +

      Building on the coin flip example, the following example shows how to blur out one face of the coin while blurring in the other face:

      + +
      +Elm_Transit *transit = elm_transit_add();
      +elm_transit_object_add(transit, coin_heads);
      +elm_transit_object_add(transit, coin_tails);
      +elm_transit_duration_set(transit, 2.0);
      +elm_transit_effect_blend_add(transit);
      +elm_transit_go(transit);
      +
      + +

      If you simply want to hide an object with a blur transition, consider using a transparent after object.

      + +

      Combining Transitions

      + +

      To use multiple transitions at the same time on the same objects, simply declare the transitions one after the other.

      + +

      Building on the coin flip example, the following example shows how to roll the coin on the ground using a rotation and a translation effect:

      + +
      +Evas_Object *coin_heads = elm_image_add(ad->win);
      +if (!elm_image_file_set(coin_heads, IMG_DIR"/coin_heads.png", NULL))
      +   printf("error: could not load image");
      +evas_object_resize(coin_heads, 100, 100);
      +evas_object_show(coin_heads);
      +
      +Elm_Transit *transit = elm_transit_add();
      +elm_transit_object_add(transit, coin_heads);
      +elm_transit_duration_set(transit, 5.0);
      +elm_transit_effect_translation_add(transit, 0, 0, 3.1415 * 2 * 100, 0);
      +elm_transit_effect_rotation_add(transit, 0, 360);
      +elm_transit_go(transit);
      +
      + +

      Animation Chain

      + +

      Now that we have listed all the effects that can be implemented using Elm_Transit, we will see how to chain transitions into sequences. To create complex, chained animations without worrying about synchronization between the transitions, use the elm_transit_chain_transit_add() function. This function takes as arguments two Elm_Transit objects and will automatically take care of the chaining for you: the second transition will start as soon as the first transition is finished.

      + +

      The following example shows how to move a datetime component on a square trajectory:

      + +
      +Evas_Object *dt = elm_datetime_add(ad->win);
      +evas_object_resize(dt, 350, 50);
      +evas_object_show(dt);
      +
      +// The first transition
      +Elm_Transit *t1 = elm_transit_add();
      +elm_transit_object_add(t1, dt);
      +elm_transit_duration_set(t1, 2);
      +elm_transit_effect_translation_add(t1, 0, 0, 100, 0);
      +
      +// The second transition
      +Elm_Transit *t2 = elm_transit_add();
      +elm_transit_object_add(t2, dt);
      +elm_transit_duration_set(t2, 2);
      +elm_transit_effect_translation_add(t2, 100, 0, 100, 100);
      +
      +// The third transition
      +Elm_Transit *t3 = elm_transit_add();
      +elm_transit_object_add(t3, dt);
      +elm_transit_duration_set(t3, 2);
      +elm_transit_effect_translation_add(t3, 100, 100, 0, 100);
      +
      +// The fourth transition
      +Elm_Transit *t4 = elm_transit_add();
      +elm_transit_object_add(t4, dt);
      +elm_transit_duration_set(t4, 2);
      +elm_transit_effect_translation_add(t4, 0, 100, 0, 0);
      +
      +// Chaining the transitions
      +elm_transit_chain_transit_add(t1, t2);
      +elm_transit_chain_transit_add(t2, t3);
      +elm_transit_chain_transit_add(t3, t4);
      +
      +// Starting the transitions
      +elm_transit_go(t1);
      +
      + +

      Note that we cannot use transition chaining to make a loop animation, since the transit object is automatically destroyed as soon as the transition completes. Therefore, you cannot do something like this:

      + +
      elm_transit_chain_transit_add(t4, t1);
      + +

      To create a looped animation chain, you have to use low-level components provided by the Ecore and Evas transition libraries, or you can use the elm_transit_del_cb_set() function to define a callback function for when a transition gets deleted. This way, you could recreate your objects and reiterate the transition chain as soon as the last transition ends.

      + +
      +elm_transit_del_cb_set(Elm_Transit *transit, Elm_Transit_Del_Cb cb, void *data)
      +
      + +

      The first argument is the transition object. The second argument is the callback function to run on transition delete. The third argument is the data to pass to the callback function.

      + +

      You can severe the chain relationship between two transits by using the elm_transit_chain_transit_del() function:

      + +
      elm_transit_chain_transit_del(Elm_Transit *transit, Elm_Transit *chain_transit)
      + +

      The first argument is the first transition in the chain. The second argument is the second transition in the chain.

      + +

      To get the current chain transit list, use the elm_transit_chain_transits_get() function.

      + +

      Animation Timeline

      + +

      After you have defined all the properties that define your transition, start the transition with the elm_transit_go() function:

      + +
      elm_transit_go(Elm_Transit *transit)
      + +

      You can maintain full control over the execution process even after the transition has started. You can pause the transition by setting the paused argument to EINA_TRUE:

      + +
      elm_transit_paused_set(Elm_Transit *transit, Eina_Bool paused)
      + +

      You can resume the transition by using the same method but setting the paused argument to EINA_FALSE. If you want to know whether the transition is currently paused, use the elm_transit_paused_get() function.

      + +

      You can remain informed about the present transition flow and get the current frame by using the elm_transit_progress_value_get() function. This function will return the timeline position of the animation, ranging between 0.0 (start) and 1.0 (end).

      + +

      Custom Transitions

      + +

      Elm_Transit provides a standard function for defining any effect of your choosing that will be applied to some context data:

      + +
      +elm_transit_effect_add(Elm_Transit *transit,
      +                       Elm_Transit_Effect_Transition_Cb transition_cb,
      +                       Elm_Transit_Effect *effect,
      +                       Elm_Transit_Effect_End_Cb end_cb)
      +
      + +

      The first argument is the transition target of the new effect. The second argument is the transition callback function. The third argument is the new effect. The fourth argument is the callback function to call at the end of the effect.

      + +

      As described earlier in this programming guide, this function embraces three callbacks that will allow you to define every aspects of your transition from its creation to its deletion. The following is an example of how to build a custom resizing animation.

      + +

      First, we define a structure capable of holding the context information about resizing an Evas object:

      + +
      +typedef struct
      +{
      +   struct _size
      +   {
      +      Evas_Coord w, h;
      +   }
      +   from, to;
      +}
      +Custom_Effect;
      +
      + +

      We can now implement our custom resizing callback function. This function takes the following arguments:

      + +
        +
      • The context data that holds the custom properties of our transition, which are used as parameters to calculate the interpolation.
      • +
      • The transit object that contains the list of our Evas objects to animate and all the information about duration, auto-reverse, looping, and so on.
      • +
      • The progress (position along the animation timeline) that ranges from 0.0 to 1.0 and allows us to calculate the desired interpolation for each frame.
      • +
      + +
      +static void
      +_custom_op(void *data, Elm_Transit *transit, double progress)
      +{
      +   if (!data) return;
      +   Evas_Coord w, h;
      +   Evas_Object *obj;
      +   const Eina_List *elist;
      +   Custom_Effect *custom_effect = data;
      +   const Eina_List *objs = elm_transit_objects_get(transit);
      +   if (progress < 0.5)
      +   {
      +      h = custom_effect->from.h + (custom_effect->to.h * progress * 2);
      +      w = custom_effect->from.w;
      +   }
      +   else
      +   {
      +      h = custom_effect->from.h + custom_effect->to.h;
      +      w = custom_effect->from.w + (custom_effect->to.w * (progress - 0.5) * 2);
      +   }
      +   EINA_LIST_FOREACH(objs, elist, obj)
      +      evas_object_resize(obj, w, h);
      +}
      +
      + +

      The callback function above resizes our Evas objects in two steps. During the first half of the transition, only the height changes, while the width remains the same. During the second half, it is the other way around until we get to the desired size.

      + +

      You must then define the context used by your animation:

      + +
      +static void*
      +_custom_context_new(Evas_Coord from_w, Evas_Coord from_h, Evas_Coord to_w, Evas_Coord to_h)
      +{
      +   Custom_Effect *custom_effect;
      +
      +   custom_effect = calloc(1, sizeof(Custom_Effect));
      +   if (!custom_effect) return NULL;
      +
      +   custom_effect->from.w = from_w;
      +   custom_effect->from.h = from_h;
      +   custom_effect->to.w = to_w - from_w;
      +   custom_effect->to.h = to_h - from_h;
      +
      +   return custom_effect;
      +}
      +
      + +

      You must define the function that will take care of deleting all the context objects used by your custom transition and free up the allocated memory:

      + +
      +static void
      +_custom_context_free(void *data, Elm_Transit *transit __UNUSED__)
      +{
      +   free(data);
      +}
      +
      + +

      Finally, apply your custom transition to your Elm_Transit object:

      + +
      +Elm_Transit *transit = elm_transit_add();
      +elm_transit_effect_add(transit,
      +                       _custom_op,
      +                       _custom_context_new(),
      +                       _custom_context_free);
      +
      + +

      If you want to delete an effect from your effects list, use the elm_transit_effect_del() function.

      + + + + + + + + + + +
      Note
      Except as noted, this content is licensed under LGPLv2.1+.
      + + + +
      + +Go to top + + + + + + + \ No newline at end of file diff --git a/org.tizen.ui.guides/html/native/efl/elementary_animation_tutorial_n.htm b/org.tizen.ui.guides/html/native/efl/elementary_animation_tutorial_n.htm new file mode 100755 index 0000000..5f21d4c --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/elementary_animation_tutorial_n.htm @@ -0,0 +1,628 @@ + + + + + + + + + + + + + + Creating Elementary Animations + + + + + + +
      +

      Creating Elementary Animations

      + + +

      This tutorial demonstrates how you can use Elm Transit to create animated transitions effects, such as rotation, wiping, zooming, resizing, and fading, to an Evas_Object.

      + + +

      Setting Up the Application

      + +

      First create a basic application like explained in Creating Basic Mobile Interactions.

      + +

      When the application is ready, create Evas objects and animate them. In this example, one single object is animated with different type of animations.

      + +

      Create the structure of our application represented by a struct named appdata

      + +
      typedef struct appdata 
      +{
      +   Evas_Object *win;
      +   Evas_Object *label;
      +   Evas_Object *button;
      +   Evas_Object *buttonbck;
      +   Evas_Object *hbox;
      +   Evas_Object *left_vbox;
      +   Evas_Object *center_vbox;
      +   Evas_Object *right_vbox;
      +   float rt_angle, zto, zfrom;
      +} appdata_s;
      +
      + +

      This structure holds the main UI components of the application:

      + +
        +
      • win: the main window
      • +
      • label: the title label
      • +
      • button: a button object, the target of the animations
      • +
      • buttonbck: a button representing the back of the target button
      • +
      • left_vbox: a vertical box to place the first buttons column
      • +
      • center_vbox: a vertical box to store the second buttons column
      • +
      • right_vbox: a vertical box to store the last buttons column
      • +
      • hbox: a horizontal box to store the vertical boxes
      • +
      • rt_angle, zto, zfrom: these variables are used to store values for animations
      • +
      + +

      Place the UI components on the application's canvas. To make things easier, the UI component creation is split into two functions.

      + +

      The first function creates UI components on the main window, and the second in the boxes.

      + +
      create_base_gui(appdata_s *ad)
      +{
      +   ad->rt_angle = 360.0;
      +   ad->zfrom = 1.0;
      +   ad->zto = 2.0;
      +
      +   // Window
      +   ad->win = elm_win_util_standard_add(PACKAGE, PACKAGE);
      +   elm_win_autodel_set(ad->win, EINA_TRUE);
      +
      +   if (elm_win_wm_rotation_supported_get(ad->win)) 
      +   {
      +      int rots[4] = { 0, 90, 180, 270 };
      +      elm_win_wm_rotation_available_rotations_set(ad->win, (const int *)(&rots), 4);
      +   }
      +
      +   evas_object_smart_callback_add(ad->win, "delete,request", win_delete_request_cb, NULL);
      +
      +   // Label
      +   ad->label = elm_label_add(ad->win);
      +   elm_object_text_set(ad->label, "Effects Tutorial");
      +   evas_object_size_hint_weight_set(ad->label, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +   elm_win_resize_object_add(ad->win, ad->label);
      +   evas_object_show(ad->label);
      +
      +   // Show the window after the base GUI is set up
      +   evas_object_show(ad->win);
      +
      +   ecore_event_handler_add(ECORE_EVENT_KEY_DOWN, keydown_cb, ad);
      +
      +   // Creation a button in the app window
      +   ad->button = elm_button_add(ad->win);
      +
      +   // Moving the button to x=50 y=100
      +   evas_object_move(ad->button, 50, 100);
      +
      +   // Resizing the button 100x50
      +   evas_object_resize(ad->button, 200, 50);
      +
      +   // Showing the button
      +   evas_object_show(ad->button);
      +
      +   // Creation a back button in the app window
      +   ad->buttonbck = elm_button_add(ad->win);
      +   elm_object_text_set(ad->buttonbck, "Button back");
      +   evas_object_move(ad->buttonbck, 50, 100);
      +   evas_object_resize(ad->buttonbck, 200, 50);
      +
      +   _create_btn_box(ad);
      +
      +} // End of create_base_gui
      +
      + +

      This function takes appdata_s *ad as its only parameter. This function is called by the creation callback app_create of the Tizen application (event_callback.create = app_create;) in the main function of the application.

      + +

      Set up the needed values like the rotation angle, the original zoom value (zfrom), and the destination zoom value (zto).

      + +
      ad->rt_angle = 360.0;
      +ad->zfrom = 1.0;
      +ad->zto = 2.0;
      +
      + +

      Create the main window with a title and add the delete callback:

      + +
      // Window
      +ad->win = elm_win_util_standard_add(PACKAGE, PACKAGE);
      +elm_win_autodel_set(ad->win, EINA_TRUE);
      +
      +if (elm_win_wm_rotation_supported_get(ad->win)) 
      +{
      +   int rots[4] = { 0, 90, 180, 270 };
      +   elm_win_wm_rotation_available_rotations_set(ad->win, (const int *)(&rots), 4);
      +}
      +
      +evas_object_smart_callback_add(ad->win, "delete,request", win_delete_request_cb, NULL);
      +
      +// Label
      +ad->label = elm_label_add(ad->win);
      +elm_object_text_set(ad->label, "Effects Tutorial");
      +evas_object_size_hint_weight_set(ad->label, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +elm_win_resize_object_add(ad->win, ad->label);
      +evas_object_show(ad->label);
      +
      +// Show the window after the base GUI is set up
      +evas_object_show(ad->win);
      +
      +ecore_event_handler_add(ECORE_EVENT_KEY_DOWN, keydown_cb, ad);
      +
      + +

      Next create the animation target button and the back button. Call the button box creation function with the application data as its parameter.

      + +
      _create_btn_box(ad);
      +
      + +

      Add a set of buttons to this box that starts animations on the animation target.

      + +

      Create the structure of the buttons box with three columns (vertical boxes) and one horizontal for the main container.

      + +
      // Creation of the main container box
      +ad->hbox = elm_box_add(ad->win);
      +elm_box_horizontal_set(ad->hbox, EINA_TRUE);
      +elm_box_homogeneous_set(ad->hbox, EINA_TRUE);
      +evas_object_move(ad->hbox, 10, 500);
      +evas_object_show(ad->hbox);
      +
      +// Creation of the first column
      +ad->left_vbox = elm_box_add(ad->hbox);
      +elm_box_horizontal_set(ad->left_vbox, EINA_FALSE);
      +elm_box_homogeneous_set(ad->left_vbox, EINA_TRUE);
      +evas_object_show(ad->left_vbox);
      +elm_box_pack_start(ad->hbox, ad->left_vbox);
      +
      +// Creation of the second column
      +ad->center_vbox = elm_box_add(ad->hbox);
      +elm_box_horizontal_set(ad->center_vbox, EINA_FALSE);
      +elm_box_homogeneous_set(ad->center_vbox, EINA_TRUE);
      +evas_object_show(ad->center_vbox);
      +elm_box_pack_end(ad->hbox, ad->center_vbox);
      +
      +// Creation of the last column
      +ad->right_vbox = elm_box_add(ad->hbox);
      +elm_box_horizontal_set(ad->right_vbox, EINA_FALSE);
      +elm_box_homogeneous_set(ad->right_vbox, EINA_TRUE);
      +evas_object_show(ad->right_vbox);
      +elm_box_pack_end(ad->hbox, ad->right_vbox);
      +
      + +

      Then create the first action button for the resize effect.

      + +
      // Button creation
      +btn_resize = elm_button_add(ad->win);
      +// Setting the button text
      +elm_object_text_set(btn_resize, "Resize");
      +// Setting the hint weight policy
      +evas_object_size_hint_weight_set(btn_resize, EVAS_HINT_FILL, EVAS_HINT_FILL);
      +// Showing the button
      +evas_object_show(btn_resize);
      +// Setting the "clicked" callback
      +evas_object_smart_callback_add(btn_resize, "clicked", _btn_resize_cb, ad);
      +// Adding the button to the first column
      +elm_box_pack_end(ad->left_vbox, btn_resize);
      +
      + +

      evas_object_smart_callback_add defines the callback function that is to be called when the button is clicked. In this example, set a _btn_resize_cb function and pass the application data ad to this callback function.

      + +

      The callback by itself only sets a new text for the animation target button, and calls a function which will actually animate the button.

      + +
      static void _btn_resize_cb(void *data, Evas_Object *btn, void *ev)
      +{
      +   appdata_s *ad = data;
      +
      +   // Starting the rotation effect 360 degrees
      +   // evas_object_resize(ad->button, 100, 50);
      +   elm_object_text_set(ad->button, "Resize");
      +   _resize_effect(ad->button);
      +
      +}
      +
      + +

      This function is an evas_object_smart_callback and thus needs to have its specific prototype: it does not return anything and receives three parameters:

      + +
        +
      • data: data to be passed
      • +
      • btn: the object the callback is being called about
      • +
      • ev: the actual event, seldom used
      • +
      + +

      In this case, use data to pass the application data to the callback. However, the parameter's type is void * and not appdata_s *. Initialize a variable of the correct type with the pointer.

      +
      appdata_s *ad = data;
      +
      + +

      Then use the application data in the callback function. At this point create the animation directly in the callback function, but it is more straightforward to encapsulate the animation process into a dedicated function. _resize_effect implements the animation code:

      + +
      static void _resize_effect(Evas_Object *obj)
      +{
      +   // Elementary Transition declaration and creation
      +   Elm_Transit *trans = elm_transit_add();
      +
      +   // Adding the transition target object
      +   elm_transit_object_add(trans, obj);
      +
      +   // Setting the resize effect
      +   elm_transit_effect_resizing_add(trans, 100, 50, 300, 150);
      +
      +   // Setting the transition duration
      +   elm_transit_duration_set(trans, 3.0);
      +
      +   // Starting the transition
      +   elm_transit_go(trans);
      +}
      +
      + +

      Create an Elm_Transit * object representing the transition.

      + +
      Elm_Transit *trans = elm_transit_add();
      +
      + +

      Then add the target object to the transition

      + +
      elm_transit_object_add(trans, obj);
      +
      + +

      Add a resizing transition to the object with the origin and destination width and height in pixels.

      + +
      elm_transit_effect_resizing_add(trans, 100, 50, 300, 150);
      +
      +

      100 and 50 are respectively the object's width and height when the effect begins, whereas 300 and 150 are respectively the object's width and height when the effect ends: the object grows from 100×50 to 300×150.

      + +

      After that set the transition duration with elm_transit_duration_set.

      +
      elm_transit_duration_set(trans, 3.0);
      +
      + +

      The animation lasts three seconds. The duration parameter is a double.

      + +

      Now start the animation by calling elm_transit_go with the Elm_Transit object.

      + +
      elm_transit_go(trans);
      +
      + +

      When the resize button is clicked, the animation target button grows.

      + +

      All the action buttons are created exactly the same way as the resize button, with a callback and an animation function.

      + +

      Creating a Rotation Effect

      + +

      This effect rotates the animation target button with an angle of 360°. This angle is stored in the application data as ad->rt_angle.

      + +

      Create the button and add it to the center column in the _create_btn_box function.

      + +
      // The rotation button
      +btn_rotate = elm_button_add(ad->win);
      +elm_object_text_set(btn_rotate, "Rotate");
      +evas_object_size_hint_weight_set(btn_rotate, EVAS_HINT_FILL, EVAS_HINT_FILL);
      +evas_object_show(btn_rotate);
      +evas_object_smart_callback_add(btn_rotate, "clicked", _btn_rotate_cb, ad);
      +elm_box_pack_end(ad->center_vbox, btn_rotate);
      +
      + +

      In the rotate button callback, call the effect function with the target button as first parameter and the rotation angle as the second one.

      + +
      static void _btn_rotate_cb(void *data, Evas_Object *btn, void *ev)
      +{
      +   appdata_s *ad = data;
      +
      +   // Setting the button text
      +   elm_object_text_set(ad->button, "Rotate");
      +   _rotation_effect(ad->button, ad->rt_angle);
      +}
      +
      + +

      The animation function rotates the animation target by adding a rotation effect with elm_transit_effect_rotation_add. This function takes three parameters:

      + +
        +
      • Elm_Transit
      • +
      • the rotation position at which the effect begins
      • +
      • the rotation position at which the effect ends
      • +
      + +

      Rotation starts at 0° to finish at 360°. The animation lasts two seconds.

      + +
      static void _rotation_effect(Evas_Object *obj, float angle)
      +{
      +   Elm_Transit *trans = elm_transit_add();
      +   elm_transit_object_add(trans, obj);
      +
      +   // Rotates the object from its original angle to given degrees to the right
      +   elm_transit_effect_rotation_add(trans, 0.0, angle);
      +   elm_transit_duration_set(trans, 2.0);
      +   elm_transit_go(trans);
      +}
      +
      + +

      Creating a Zoom Effect

      + +

      The zoom effect zooms on the animation target to make it twice bigger. Store the source rate and the destination rate in the application data using ad->zfrom and ad->zto.

      +

      Create the button and add it to the center column in the _create_btn_box function.

      + +
      // The zoom button
      +btn_zoom = elm_button_add(ad->win);
      +elm_object_text_set(btn_zoom, "Zoom");
      +evas_object_size_hint_weight_set(btn_zoom, EVAS_HINT_FILL, EVAS_HINT_FILL);
      +evas_object_show(btn_zoom);
      +evas_object_smart_callback_add(btn_zoom, "clicked", _btn_zoom_cb, ad);
      +elm_box_pack_end(ad->right_vbox, btn_zoom);
      +
      + +

      Then add a callback function in order to perform the animation.

      + +
      static void _btn_zoom_cb(void *data, Evas_Object *btn, void *ev)
      +{
      +   appdata_s *ad = data;
      +
      +   // Starting the rotation effect 360 degrees
      +   // evas_object_resize(ad->button, 100, 50);
      +   elm_object_text_set(ad->button, "Zoom");
      +   _zoom_effect(ad->button, ad->zfrom, ad->zto);
      +}
      +
      + +

      To create the zoom effect, use elm_transit_effect_zoom_add with the start rate and the destination rate stored in application data (ad->zfrom and ad->zto)

      + +
      static void _zoom_effect(Evas_Object *obj, float from, float to)
      +{
      +   Elm_Transit *trans = elm_transit_add();
      +   elm_transit_object_add(trans, obj);
      +
      +   elm_transit_effect_zoom_add(trans, from, to);
      +   elm_transit_duration_set(trans, 2.0);
      +   elm_transit_go(trans);
      +}
      +
      + + +

      Creating a Flip Effect

      + +

      This effect is applied to a pair of objects, in the order they are added, to the Elm_Transit transition. In this example, add the animation target button and the button called buttonbck which represents the back of the target button.

      + +

      Create the action button for the flip effect:

      + +
      // The flip button
      +btn_flip = elm_button_add(ad->win);
      +elm_object_text_set(btn_flip, "Flip x");
      +evas_object_size_hint_weight_set(btn_flip, EVAS_HINT_FILL, EVAS_HINT_FILL);
      +evas_object_show(btn_flip);
      +evas_object_smart_callback_add(btn_flip, "clicked", _btn_flip_cb, ad);
      +elm_box_pack_end(ad->left_vbox, btn_flip);
      +
      + +

      The corresponding callback to create and start the animation with the two objects (target button and back button) to animate is like follows.

      + +
      static void _btn_flip_cb(void *data, Evas_Object *btn, void *ev)
      +{
      +   appdata_s *ad = data;
      +
      +   // Setting the button text
      +   elm_object_text_set(ad->button, "Flip");
      +   _flip_effect(ad->button, ad->buttonbck);
      +}
      +
      + +

      Create the function which runs the animation. This flip animation is created using elm_transit_effect_flip_add. The second parameter is the axis of the flip: in this example it is the X axis, so the button flips down to top to show the back button. The last parameter is the flip direction: EINA_TRUE means clockwise.

      + +
      static void _flip_effect(Evas_Object *obj, Evas_Object *obj2)
      +{
      +   Elm_Transit *trans;
      +
      +   trans = elm_transit_add();
      +   elm_transit_object_add(trans, obj);
      +   elm_transit_object_add(trans, obj2);
      +   elm_transit_effect_flip_add(trans, ELM_TRANSIT_EFFECT_FLIP_AXIS_X, EINA_TRUE);
      +
      +   elm_transit_duration_set(trans, 3.0);
      +   elm_transit_go(trans);
      +}
      +
      + +

      Creating a Blend Transition

      + +

      The blend effect also works the same way as the flip, but without the axes or direction information. Use the back button here as well. To create the blend effect button:

      + +
      // The blend button
      +btn_blend = elm_button_add(ad->win);
      +elm_object_text_set(btn_blend, "Blend");
      +evas_object_size_hint_weight_set(btn_blend, EVAS_HINT_FILL, EVAS_HINT_FILL);
      +evas_object_show(btn_blend);
      +evas_object_smart_callback_add(btn_blend, "clicked", _btn_blend_cb, ad);
      +elm_box_pack_end(ad->center_vbox, btn_blend);
      +
      + +

      The blend transition callback is:

      + +
      static void _btn_blend_cb(void *data, Evas_Object *btn, void *ev)
      +{
      +   appdata_s *ad = data;
      +
      +   // Setting the button text
      +   elm_object_text_set(ad->button, "Blend");
      +   _blend_effect(ad->button, ad->buttonbck);
      +}
      +
      + +

      Create and start the blend animation. This animation is created by adding it to and Elm_Transit with elm_transit_effect_blend_add. Add two objects, as for the flip.

      + +
      static void _blend_effect(Evas_Object *obj, Evas_Object *obj2)
      +{
      +   Elm_Transit *trans;
      +
      +   trans = elm_transit_add();
      +   elm_transit_object_add(trans, obj);
      +   elm_transit_object_add(trans, obj2);
      +   elm_transit_effect_blend_add(trans);
      +   elm_transit_duration_set(trans, 3.0);
      +   elm_transit_go(trans);
      +}
      +
      + +

      Creating a Fade Effect

      + +

      The fade effect works exactly the same way as the blend effect. First create the button:

      + +
      // The fade button
      +btn_fade = elm_button_add(ad->win);
      +elm_object_text_set(btn_fade, "Fade");
      +evas_object_size_hint_weight_set(btn_fade, EVAS_HINT_FILL, EVAS_HINT_FILL);
      +evas_object_show(btn_fade);
      +evas_object_smart_callback_add(btn_fade, "clicked", _btn_fade_cb, ad);
      +elm_box_pack_end(ad->right_vbox, btn_fade);
      +
      + +

      Then add the button's callback:

      + +
      static void _btn_fade_cb(void *data, Evas_Object *btn, void *ev)
      +{
      +   appdata_s *ad = data;
      +
      +
      +   // Setting the button text
      +   elm_object_text_set(ad->button, "Fade");
      +   _fade_effect(ad->button, ad->buttonbck);
      +}
      +
      + +

      The animation function calls elm_transit_effect_fade_add instead of elm_transit_effect_blend_add.

      + +
      static void _fade_effect(Evas_Object *obj, Evas_Object *obj2)
      +{
      +   Elm_Transit *trans;
      +
      +   trans = elm_transit_add();
      +   elm_transit_object_add(trans, obj);
      +   elm_transit_object_add(trans, obj2);
      +   elm_transit_effect_fade_add(trans);
      +   elm_transit_duration_set(trans, 3.0);
      +   elm_transit_go(trans);
      +}
      +
      + +

      Creating a Flip on y Axis

      + +

      This is same as the flip transition, but on y axis. To create a flip on y axis:

      + +
      // The flip y button
      +btn_flip_y = elm_button_add(ad->win);
      +elm_object_text_set(btn_flip_y, "Flip y");
      +evas_object_size_hint_weight_set(btn_flip_y, EVAS_HINT_FILL, EVAS_HINT_FILL);
      +evas_object_show(btn_flip_y);
      +evas_object_smart_callback_add(btn_flip_y, "clicked", _btn_flip_y_cb, ad);
      +elm_box_pack_end(ad->left_vbox, btn_flip_y);
      +
      +static void _btn_flip_y_cb(void *data, Evas_Object *btn, void *ev)
      +{
      +   appdata_s *ad = data;
      +
      +
      +   // Setting the button text
      +   elm_object_text_set(ad->button, "Flip 2");
      +   _flip_y_effect(ad->button, ad->buttonbck);
      +}
      +
      +static void _flip_y_effect(Evas_Object *obj, Evas_Object *obj2)
      +{
      +   Elm_Transit *trans;
      +
      +   trans = elm_transit_add();
      +   elm_transit_object_add(trans, obj);
      +   elm_transit_object_add(trans, obj2);
      +   elm_transit_effect_flip_add(trans, ELM_TRANSIT_EFFECT_FLIP_AXIS_Y, EINA_TRUE);
      +   elm_transit_duration_set(trans, 3.0);
      +   elm_transit_go(trans);
      +}
      +
      + +

      Creating a Wipe Effect

      + +

      The wipe transition is applied on an Evas object considering the wipe type and the direction. Use ELM_TRANSIT_EFFECT_WIPE_TYPE_HIDE to hide the button, and ELM_TRANSIT_EFFECT_WIPE_DIR_RIGHT to do it from left to right.

      + +

      The wipe animation button is as follows:

      + +
      // The wipe button
      +btn_wipe = elm_button_add(ad->win);
      +elm_object_text_set(btn_wipe, "Wipe");
      +evas_object_size_hint_weight_set(btn_wipe, EVAS_HINT_FILL, EVAS_HINT_FILL);
      +evas_object_show(btn_wipe);
      +evas_object_smart_callback_add(btn_wipe, "clicked", _btn_wipe_cb, ad);
      +elm_box_pack_end(ad->right_vbox, btn_wipe);
      +
      + +

      The wipe button callback looks like:

      + +
      static void _btn_wipe_cb(void *data, Evas_Object *btn, void *ev)
      +{
      +   appdata_s *ad = data;
      +
      +   // Starting the rotation effect 360 degrees
      +   // evas_object_resize(ad->button, 100, 50);
      +   // Setting the button text
      +   elm_object_text_set(ad->button, "Wipe");
      +   _wipe_effect(ad->button);
      +}
      +
      + +

      The animation function calls elm_transit_effect_wipe_add with ELM_TRANSIT_EFFECT_WIPE_TYPE_HIDE as the second parameter to hide the button and ELM_TRANSIT_EFFECT_WIPE_DIR_RIGHT as last parameter to set the direction (left to right).

      + +
      static void _wipe_effect(Evas_Object *obj)
      +{
      +    Elm_Transit *trans;
      +
      +    trans = elm_transit_add();
      +    elm_transit_object_add(trans, obj);
      +    elm_transit_effect_wipe_add(trans, ELM_TRANSIT_EFFECT_WIPE_TYPE_HIDE, ELM_TRANSIT_EFFECT_WIPE_DIR_RIGHT);
      +    elm_transit_duration_set(trans, 3.0);
      +    elm_transit_go(trans);
      +}
      +
      + + + + +
      + +Go to top + + + + + + + diff --git a/org.tizen.ui.guides/html/native/efl/elementary_transit_effect_tutorial_n.htm b/org.tizen.ui.guides/html/native/efl/elementary_transit_effect_tutorial_n.htm new file mode 100755 index 0000000..a4e7e9a --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/elementary_transit_effect_tutorial_n.htm @@ -0,0 +1,213 @@ + + + + + + + + + + + + + + Creating Elementary Transit Effects + + + + + + +
      +

      Creating Elementary Transit Effects

      + +

      This tutorial demonstrates how you can implement a variety of EFL animation effects using the APIs available in the EFL library.

      + +

      Initializing the Application Layout

      + +

      The application uses UI components, such as elm_conformant and elm_naviframe for view management, layout classes, such as elm_list for the composition of the screen, and UI components, such as elm_button and elm_image for the content inside the view.

      +

      The transit is designed to apply various animated transition effects to the Evas_Object. The following transition effects are supported in the Tizen native applications:

      +
        +
      • Blend
      • +
      • Color
      • +
      • Fade
      • +
      • Flip
      • +
      • Rotation
      • +
      • Transition
      • +
      • Wipe
      • +
      • Zoom
      • +
      + +

      The application layout is created by the create_base_gui() function. First, a window is created and the elm_conformant component is added to it to decorate the window with an indicator. It then adds the elm_naviframe component, which acts as a view manager for the window and provides the window title functionality.

      +
      +static void
      +create_base_gui(appdata_s *ad)
      +{
      +   // Window
      +   ad->win = elm_win_util_standard_add(PACKAGE, PACKAGE);
      +   elm_win_autodel_set(ad->win, EINA_TRUE);
      +
      +   if (elm_win_wm_rotation_supported_get(ad->win)) 
      +   {
      +      int rots[4] = { 0, 90, 180, 270 };
      +      elm_win_wm_rotation_available_rotations_set(ad->win, (const int *)(&rots), 4);
      +   }
      +
      +   evas_object_smart_callback_add(ad->win, "delete,request", win_delete_request_cb, NULL);
      +
      +   // Conformant
      +   ad->conform = elm_conformant_add(ad->win);
      +   evas_object_size_hint_weight_set(ad->conform, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +   elm_win_resize_object_add(ad->win, ad->conform);
      +   evas_object_show(ad->conform);
      +
      +   // Naviframe
      +   ad->nf = create_main_view(ad);
      +   elm_object_content_set(ad->conform, ad->nf);
      +
      +   // Show window after the base GUI is set up
      +   evas_object_show(ad->win);
      +
      +   ecore_event_handler_add(ECORE_EVENT_KEY_DOWN, keydown_cb, ad);
      +}
      +
      + +

      The create_main_view() function creates the main content. It consists of a naviframe containing a list. This function returns a list of naviframe object pointers for the content set.

      +
      +static Evas_Object*
      +create_main_view(appdata_s *ad)
      +{
      +   Elm_Object_Item *nf_it;
      +   Evas_Object *navi, *list;
      +
      +   navi = elm_naviframe_add(ad->conform);
      +
      +   list = elm_list_add(navi);
      +   elm_list_mode_set(list, ELM_LIST_COMPRESS);
      +
      +   elm_list_item_append(list, "Blend", NULL, NULL, blend_cb, navi);
      +   elm_list_item_append(list, "Color", NULL, NULL, color_cb, navi
      +   elm_list_item_append(list, "Fade", NULL, NULL, fade_cb, navi);
      +   elm_list_item_append(list, "Flip", NULL, NULL, flip_cb, navi);
      +   elm_list_item_append(list, "Rotation", NULL, NULL, rotation_cb, navi);
      +   elm_list_item_append(list, "ResizableFlip", NULL, NULL, resizable_flip_cb, navi);
      +   elm_list_item_append(list, "Translation", NULL, NULL, translation_cb, navi);
      +   elm_list_item_append(list, "Wipe", NULL, NULL, wipe_cb, navi);
      +   elm_list_item_append(list, "Zoom", NULL, NULL, zoom_cb, navi);
      +   elm_list_item_append(list, "Custom", NULL, NULL, custom_cb, navi);
      +   elm_list_go(list);
      +
      +   nf_it = elm_naviframe_item_push(navi, "Transit", NULL, NULL, list, NULL);
      +
      +   return navi;
      +}
      +
      + +

      This document describes only the rotation and zoom implementations. For more information about other effects, see the transit.c file and the elm_transit document. The following figure illustrates the rotation and zoom effects.

      + +

      Figure: Rotation and zoom

      +

      Rotation and zoom

      + +

      Implementing the Rotation Effect

      + +

      If the list item named by rotation includes the touch event, the callback function for this event is called.

      +

      The data is sent as an Evas_Object. This implements the animation effect.

      +

      To implement the rotation effect:

      +
        +
      1. Use the elm_transit object with the elm_transit_add() function to add the transit effect.
      2. +
      3. Set the transit rotation amount and duration.
      4. +
      5. To start the transit animation, use the elm_transit_go() function.
      6. +
      +
      +static void
      +rotation_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   Evas_Object *layout = (Evas_Object *) data;
      +   Elm_Transit *transit = elm_transit_add();
      +
      +   // 360 degree rotation effect in the clock-wise direction
      +   elm_transit_object_add(transit, layout);
      +   elm_transit_effect_rotation_add(transit, 0, 360);
      +   elm_transit_duration_set(transit, 1);
      +   elm_transit_del_cb_set(transit, transit_del_cb, NULL);
      +   elm_transit_go(transit);
      +}
      +
      + +

      Implementing the Zoom Effect

      + +

      If the list item named by zoom includes the touch event, the callback function for this event is called.

      +

      The data is sent as an Evas_Object. This implements the animation effect.

      +

      There are 2 transit functions: one is for the zoom effect and the other is for returning to the original effect:

      +
        +
      1. After adding the transit object, add an evas_object to get the effect.
      2. +
      3. Set the zoom from the original size (1.0) to 0.4 times the original size, and set the duration.
      4. +
      5. Similarly, set the zoom size (0.4) back to the original size (1.0), and set the duration.
      6. +
      7. Set both of effects to be applied in sequence.
      8. +
      +
      +static void
      +zoom_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   Evas_Object *layout = (Evas_Object *) data;
      +   // Zoom out to scale 0.6
      +   Elm_Transit *transit = elm_transit_add();
      +   elm_transit_smooth_set(transit, EINA_FALSE);
      +   elm_transit_object_add(transit, layout);
      +   elm_transit_effect_zoom_add(transit, 1.0, 0.4);
      +   elm_transit_duration_set(transit, 0.5);
      +
      +   // Zoom in to the original size
      +   Elm_Transit *transit2 = elm_transit_add();
      +   elm_transit_smooth_set(transit2, EINA_FALSE);
      +   elm_transit_object_add(transit2, layout);
      +   elm_transit_effect_zoom_add(transit2, 0.4, 1.0);
      +   elm_transit_duration_set(transit2, 0.5);
      +   elm_transit_del_cb_set(transit2, transit_del_cb, NULL);
      +
      +   elm_transit_chain_transit_add(transit, transit2);
      +   elm_transit_go(transit);
      +}
      +
      + + + + +
      + +Go to top + + + + + + + diff --git a/org.tizen.ui.guides/html/native/efl/evas_advanced_objects_n.htm b/org.tizen.ui.guides/html/native/efl/evas_advanced_objects_n.htm new file mode 100755 index 0000000..fd8c475 --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/evas_advanced_objects_n.htm @@ -0,0 +1,379 @@ + + + + + + + + + + + + + + Advanced Manipulation of Evas Objects + + + + + + +
      +

      Advanced Manipulation of Evas Objects

      + + +

      This tutorial demonstrates how you can use Evas object extra functions.

      + +

      This tutorial shows how to create an application that enables scaling of an Evas text object by clicking buttons. Data setter and getter functions are used to pass the scalable object through the clicked button object to a callback.

      +

      The tutorial also shows how to change the Evas object rendering mode using the extra object manipulation API.

      + +

      Figure: Advanced Evas application

      +

      Advanced Evas application

      + + +

      Creating the Basic Application

      +

      To create the basic application:

      +
        +
      1. +

        To use the required APIs, include the following libraries:

        + +
        #include <app.h>
        +#include <Elementary.h>
        +#include <system_settings.h>
        +#include <efl_extension.h>
        +
      2. + +
      3. +

        Create objects for an Elementary window and buttons for scaling and changing the object render mode. Also create a text object and 2 rectangle objects to connect to the application data structure:

        + +
        typedef struct appdata 
        +{
        +   Evas_Object *win;
        +   Evas_Object *scale_incr_button;
        +   Evas_Object *scale_decr_button;
        +
        +   Evas_Object *render_text;
        +   Evas_Object *blend_mode_button;
        +   Evas_Object *copy_mode_button;
        +   Evas_Object *render_rect1;
        +   Evas_Object *render_rect2;
        +} 
        +appdata_s;
        +
      4. +
      + +

      Creating the Elementary Window

      +

      To create an elementary window:

      +
        +
      1. +

        Use the elm_win_util_standard_add() function and give there the name and title of the application. To set a callback for the Back hardware button, use the eext_object_event_callback_add() function. To display the Evas object, use the evas_object_show() function.

        + +
        static void
        +create_base_gui(appdata_s *ad)
        +{
        +   // Window
        +   ad->win = elm_win_util_standard_add("Extra object function", "Extra object function");
        +   elm_win_autodel_set(ad->win, EINA_TRUE);
        +
        +   // Window callbacks
        +   evas_object_smart_callback_add(ad->win, "delete,request", win_delete_request_cb, NULL);
        +   eext_object_event_callback_add(ad->win, EEXT_CALLBACK_BACK, back_cb, ad);
        +
        +   // Show the window
        +   evas_object_show(ad->win);
        +}
        +
      2. + +
      3. + +

        Implement callback functions to enable closing the application:

        + +
        static void
        +back_cb(void *data, Evas_Object *obj, void *event_info)
        +{
        +   appdata_s *ad = data;
        +
        +   elm_win_lower(ad->win);
        +}
        +
        +static void
        +win_delete_request_cb(void *data, Evas_Object *obj, void *event_info)
        +{
        +   ui_app_exit();
        +}
        +
      4. +
      + +

      Creating an Application

      +

      Create an Elementary application with a GUI:

      + +
      static bool
      +app_create(void *data)
      +{
      +   appdata_s *ad = data;
      +
      +   // Create the application UI
      +   create_base_gui(ad);
      +
      +   return true;
      +}
      +
      +int
      +main(int argc, char *argv[])
      +{
      +   appdata_s ad = {0,};
      +
      +   ui_app_lifecycle_callback_s event_callback = {0,};
      +
      +   event_callback.create = app_create;
      +
      +   // Run the main loop
      +   return ui_app_main(argc, argv, &event_callback, &ad);
      +}
      + +

      Creating Buttons

      +

      To create buttons:

      +
        +
      1. +

        Create the scale buttons. The move() and resize() functions configure the buttons' custom geometry.

        + +
        // Scale increasing button
        +ad->scale_incr_button = elm_button_add(ad->win);
        +elm_object_text_set(ad->scale_incr_button, "Scale +");
        +evas_object_resize(ad->scale_incr_button, 120, 50);
        +evas_object_move(ad->scale_incr_button, 180, 20);
        +evas_object_show(ad->scale_incr_button);
        +
        +// Scale decreasing button
        +ad->scale_decr_button = elm_button_add(ad->win);
        +elm_object_text_set(ad->scale_decr_button, "Scale -");
        +evas_object_resize(ad->scale_decr_button, 120, 50);
        +evas_object_move(ad->scale_decr_button, 180, 170);
        +evas_object_show(ad->scale_decr_button);
        +
      2. + +
      3. +

        Create the render mode change buttons:

        + +
        // Blend render mode button
        +ad->blend_mode_button = elm_button_add(ad->win);
        +elm_object_text_set(ad->blend_mode_button, "BLEND Mode");
        +evas_object_resize(ad->blend_mode_button, 190, 50);
        +evas_object_move(ad->blend_mode_button, 30, 280);
        +evas_object_show(ad->blend_mode_button);
        +
        +// Copy render mode button
        +ad->copy_mode_button = elm_button_add(ad->win);
        +elm_object_text_set(ad->copy_mode_button, "COPY Mode");
        +evas_object_resize(ad->copy_mode_button, 190, 50);
        +evas_object_move(ad->copy_mode_button, 260, 280);
        +evas_object_show(ad->copy_mode_button);
        +
      4. +
      + +

      Creating Callbacks for the Button Click Signal

      +

      To create the callbacks:

      +
        +
      1. +

        Create callbacks:

        + +
        +evas_object_smart_callback_add(ad->scale_incr_button, "clicked", scale_incr_cb, NULL);
        +evas_object_smart_callback_add(ad->scale_decr_button, "clicked", scale_decr_cb, NULL);
        +evas_object_smart_callback_add(ad->blend_mode_button, "clicked", blend_mode_cb, ad);
        +evas_object_smart_callback_add(ad->copy_mode_button, "clicked", copy_mode_cb, ad);
        +
      2. + +
      3. +

        Implement callback functions to enable changing the scale and render mode:

        + +
        static void
        +scale_incr_cb(void *data, Evas_Object *obj, void *event_info)
        +{
        +   Evas_Object *evas_text = evas_object_data_get(obj, "evas_text");
        +   if (!evas_text)
        +      return;
        +
        +   double current_scale = evas_object_scale_get(evas_text);
        +
        +   if (current_scale >= 5.0)
        +      return;
        +
        +   evas_object_scale_set(evas_text, current_scale + 0.2);
        +}
        +
        +static void
        +scale_decr_cb(void *data, Evas_Object *obj, void *event_info)
        +{
        +   Evas_Object *evas_text = evas_object_data_get(obj, "evas_text");
        +   if (!evas_text)
        +      return;
        +
        +   double current_scale = evas_object_scale_get(evas_text);
        +
        +   if (current_scale <= 0.0)
        +   {
        +      return;
        +   }
        +
        +   evas_object_scale_set(evas_text, current_scale - 0.2);
        +}
        +
        +static void
        +blend_mode_cb(void *data, Evas_Object *obj, void *event_info)
        +{
        +   appdata_s *ad = data;
        +
        +   evas_object_text_text_set(ad->render_text, "EVAS_RENDER_BLEND: d = d * (1-sa) + s");
        +   evas_object_render_op_set(ad->render_rect2, EVAS_RENDER_BLEND);
        +}
        +
        +static void
        +copy_mode_cb(void *data, Evas_Object *obj, void *event_info)
        +{
        +   appdata_s *ad = data;
        +
        +   evas_object_text_text_set(ad->render_text, "EVAS_RENDER_COPY: d = s");
        +   evas_object_render_op_set(ad->render_rect2, EVAS_RENDER_COPY);
        +}
        +
      4. +
      + +

      Attaching Data to the Object

      +

      To attach data to the object:

      +
        +
      1. +

        Use the evas_object_data_set() function. To create the keyword to get the data, use the evas_object_data_get() function.

        + +

        Create the text object using the evas_object_text_add() function.

        + +
        +evas = evas_object_evas_get(ad->win);
        +
      2. + +
      3. +

        Create the Evas text object to be used as data attached to the button:

        + +
        +evas_text = evas_object_text_add(evas);
        +evas_object_text_text_set(evas_text, "Scalable Text Object");
        +evas_object_text_font_set(evas_text, "Sans", 10);
        +evas_object_color_set(evas_text, 50, 100, 200, 255);
        +evas_object_move(evas_text, 10, 90);
        +evas_object_show(evas_text);
        +
      4. +
      + +

      Attaching Data

      + +

      The data is passed to the function through buttons. Use the evas_object_data_set() function for the button. Give a pointer to the attach data, and the key name to associate it with the data.

      + +
      +evas_object_data_set(ad->scale_incr_button, "evas_text", evas_text);
      +evas_object_data_set(ad->scale_decr_button, "evas_text", evas_text);
      + +

      Getting data

      + +

      To get the file data attached to the object, use the evas_object_data_get() function and give the data key name added when you attached this data:

      + +
      Evas_Object *evas_text = evas_object_data_get(obj, "evas_text");
      + +

      Deleting data

      + +

      To delete the data attached to the object, use the evas_object_data_del() function and give the data key name added when you attached this data:

      + +
      evas_object_data_del(obj, "evas_text");
      + +

      Using Scale Functions

      + +

      To set the scale factor to a single Evas object instead of setting scale to the entire application, use the evas_object_scale_set() function. This is useful when you want scalable UI elements at runtime. However, only text and textblock objects have scaling change handlers. Other objects do not change visually on this call. In this application, the scale is defined in the button click callbacks.

      + +
      double current_scale = evas_object_scale_get(evas_text);
      +
      +if (current_scale >= 5.0)
      +   return;
      +
      +evas_object_scale_set(evas_text, current_scale + 0.2);
      + +

      Get the current scale of the Evas text object and check its maximum size. If the current size is smaller than the maximum size, the scale factor for the object is increased using the evas_object_scale_set function. The text object is updated on display and its size changes.

      + +

      Configuring the Evas Object Render Mode

      + +

      To change the render operation to be used for rendering the Evas object, use the evas_object_render_op_set() function. To get the current render operation, use the evas_object_render_op_get() function.

      + +

      Creating Rectangle Objects

      + +

      Creates Evas rectangle objects to change the Evas rendering mode for them:

      + +
      // Rectangle with yellow background
      +ad->render_rect1 = evas_object_rectangle_add(evas);
      +evas_object_color_set(ad->render_rect1, 240, 220, 50, 191);
      +evas_object_resize(ad->render_rect1, 260, 260);
      +evas_object_move(ad->render_rect1, 60, 400);
      +evas_object_show(ad->render_rect1);
      +
      +// Translucent rectangle with blue foreground
      +ad->render_rect2 = evas_object_rectangle_add(evas);
      +evas_object_color_set(ad->render_rect2, 25, 110, 220, 127);
      +evas_object_resize(ad->render_rect2, 260, 260);
      +evas_object_move(ad->render_rect2, 170, 500);
      +evas_object_show(ad->render_rect2);
      + +

      Changing the Render Operation

      + +

      To change the rendering mode, use the evas_object_render_op_set() function and give the render operation constant, which informs Evas of the function to use when drawing the eEvas object on canvas. By default, all evas objects use the EVAS_RENDER_BLEND mode and all colors are drawn using the "d = d*(1-sa) + s" formula, where "d" is destination color, "sa" is source alpha, and "s" is source color.

      + +

      Change the rendering mode to copy mode (d = s):

      + +
      evas_object_render_op_set(ad->render_rect2, EVAS_RENDER_COPY);
      + + + + + + + + + + +
      + +Go to top + + + + + + + diff --git a/org.tizen.ui.guides/html/native/efl/evas_basic_objects_n.htm b/org.tizen.ui.guides/html/native/efl/evas_basic_objects_n.htm new file mode 100755 index 0000000..80d5933 --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/evas_basic_objects_n.htm @@ -0,0 +1,349 @@ + + + + + + + + + + + + + + Basic Manipulation of Evas Objects + + + + + + +
      +

      Basic Manipulation of Evas Objects

      + + +

      Most Evas objects can be manipulated using generic functions.

      + +

      The list of available basic actions does not depend on the object's type. Evas implements functionality that allows performing basic manipulation, such as showing, hiding, setting, and getting geometry, bringing a layer up or down, managing color, clipping, and reference counting.

      + +

      This tutorial introduces the basic manipulations available for Evas_Object object.

      + + +

      Working with Evas

      + +
        +
      1. +

        To start interacting with Evas, first create an Evas instance or get a reference to an already allocated Evas object:

        + +
        ad->win = elm_win_util_standard_add(PACKAGE, PACKAGE);
        +elm_win_autodel_set(ad->win, EINA_TRUE);
        +
        +Evas *evas = evas_object_evas_get(ad->win);
        +
      2. + +
      3. +

        When an instance of Evas object exists, you can start creating basic Evas objects using obtained reference to Evas as a parent for child objects. The following example creates an Evas_Object with size 480x800, position on window at 0,0 by x and y axis, and set as a background:

        + +
        +ad->bg = evas_object_rectangle_add(evas);
        +evas_object_color_set(ad->bg, 255, 255, 255, 255);
        +evas_object_resize(ad->bg, 480, 800);
        +evas_object_move(ad->bg, 0, 0);
        +evas_object_show(ad->bg);
        +
        + +

        Figure: Empty window

        +

        Empty window

        + +
      4. +
      + + +

      Clipping an Object

      + +

      You can set an Evas object as a clipper for another Evas object. To obtain a clipper object, create an Evas object, set its width and height parameters, and call the evas_object_clip_set() function to set the object as a clipper for other Evas objects:

      + +
      ad->img = evas_object_image_filled_add(evas);
      +_app_get_resource("images/enlightenment.png", image_path, PATH_MAX);
      +evas_object_image_file_set(ad->img, image_path, NULL);
      +if (evas_object_image_load_error_get(ad->img) != EVAS_LOAD_ERROR_NONE)
      +   return;
      +
      +evas_object_geometry_get(ad->spacer, NULL, NULL, &w, &h);
      +evas_object_name_set(ad->img, "background");
      +evas_object_resize(ad->img, WIDTH, HEIGHT);
      +evas_object_move(ad->img, w, h);
      +evas_object_show(ad->img);
      +
      +ad->clipper = evas_object_rectangle_add(evas);
      +evas_object_geometry_get(ad->img, &x, &y, &w, &h);
      +evas_object_move(ad->clipper, WIDTH / 4 + x, HEIGHT / 4 + y);
      +evas_object_resize(ad->clipper, w / 2, h / 2);
      +evas_object_clip_set(ad->img, ad->clipper);
      +evas_object_show(ad->clipper);
      +
      + +

      Figure: Using the clipper

      +

      Using the clipper

      + + +

      You can also unset the clipper object using the evas_object_clip_unset() function. As a result, there are 2 objects, an image and a rectangle. The rectangle is on top of the image object according to the creation order.

      + +
      static void
      +_clipper_cb(void *data, Evas *e, Evas_Object *obj, void *event_info)
      +{
      +   App_Data *ad = (App_Data *)data;
      +
      +   const char *object_name = evas_object_name_get(ad->img);
      +   if (strcmp(object_name, "background") != 0)
      +      return;
      +
      +   if (evas_object_clip_get(ad->img) == ad->clipper)
      +      evas_object_clip_unset(ad->img);
      +   else
      +      evas_object_clip_set(ad->img, ad->clipper);
      +}
      + +

      Figure: Using the clipper

      +

      Using the clipper

      + +

      Changing Colors and Visibility

      + +

      You can manage the object colors and visibility. To change a color of a valid Evas_Object, use the evas_object_color_set() and pass a color value:

      + +
      static void
      +_color_cb(void *data, Evas *e, Evas_Object *obj, void *event_info)
      +{
      +   App_Data *ad = (App_Data *)data;
      +
      +   int alpha, r, g, b;
      +
      +   evas_object_color_get(ad->clipper, &r, &g, &b, &alpha);
      +   evas_color_argb_unpremul(alpha, &r, &g, &b);
      +
      +   if (g > 0)
      +      g = b = 0;
      +   else
      +      g = b = 255;
      +
      +   evas_color_argb_premul(alpha, &r, &g, &b);
      +   evas_object_color_set(ad->clipper, r, g, b, alpha);
      +}
      + +

      Figure: Applying color

      +

      Applying color

      + +

      You can also change the opacity of the object:

      + +
      static void
      +_opacity_cb(void *data, Evas *e, Evas_Object *obj, void *event_info)
      +{
      +   App_Data *ad = (App_Data *)data;
      +
      +   int alpha, r, g, b;
      +
      +   evas_object_color_get(ad->clipper, &r, &g, &b, &alpha);
      +   evas_color_argb_unpremul(alpha, &r, &g, &b);
      +
      +   alpha -= 20;
      +   if (alpha < 0)
      +      alpha = 255;
      +
      +   evas_color_argb_premul(alpha, &r, &g, &b);
      +   evas_object_color_set(ad->clipper, r, g, b, alpha);
      +}
      + +

      Figure: Changing opacity

      +

      Changing opacity

      + +

      You can also hide the object when it is not needed:

      + +
      static void
      +_visibility_cb(void *data, Evas *e, Evas_Object *obj, void *event_info)
      +{
      +   App_Data *ad = (App_Data *)data;
      +
      +   if (evas_object_visible_get(ad->clipper))
      +      evas_object_hide(ad->clipper);
      +   else
      +      evas_object_show(ad->clipper);
      +}
      + +

      Figure: Changing visibility

      +

       Changing visibility

      + +

      Reference Counting

      + +

      Evas has a simple reference counting mechanism that is useful for scenarios like inside a code block, callbacks exist which would possibly delete an object we are operating on afterwards.

      +

      To increment the reference count of an object, use the evas_object_ref() function. If the reference count is greater than 0, the evas_object_del() function is called until all references are released. References cannot go below 0 and are limited to 2^32 - 1 for each object:

      + +
      ad->spacer = evas_object_rectangle_add(evas);
      +evas_object_color_set(ad->spacer, 0, 255, 100, 255);
      +evas_object_move(ad->spacer, 0, 0);
      +evas_object_resize(ad->spacer, 120, 20);
      +evas_object_show(ad->spacer);
      +evas_object_ref(ad->spacer);
      +
      +static void
      +_unref_cb(void *data, Evas *e, Evas_Object *obj, void *event_info)
      +{
      +   App_Data *ad = (App_Data *)data;
      +
      +   if (!ad->spacer)
      +      return;
      +
      +   if (evas_object_ref_get(ad->spacer) != 0)
      +   {
      +      evas_object_unref(ad->spacer);
      +      return;
      +   }
      +
      +int x, y, w, h;
      +
      +evas_object_geometry_get(ad->spacer, &x, &y, NULL, NULL);
      +evas_object_move(ad->img, x, y);
      +evas_object_geometry_get(ad->img, &x, &y, &w, &h);
      +evas_object_move(ad->clipper, x + (w / 4), y + (h / 4));
      +evas_object_move(ad->clipper_border, x + (w / 4) - 3, y + (h / 4) - 3);
      +evas_object_del(ad->spacer);
      +ad->spacer = NULL;
      +}
      + + +

      A green rectangle is used as a padding and the clipper object calculates its x, y coordinates based on the rectangle position. The rectangle reference count is increased by calling the evas_object_ref() function and now it is equal to 1. When the _unref_cb callback is triggered, the reference count value is higher than 0 and the evas_object_del(ad->spacer) function has no effect on the object. After the second callback call, the evas_object_ref_get(ad->spacer) function returns 0 and the evas_object_del(ad->spacer) function marks the rectangle object for deletion.

      + +

      Figure: Removing padding

      +

      Removing padding

      + +

      Changing the Object Order on Canvas

      + +

      By default, the placing of objects on canvas is based on their creation order.

      + +
      +ad->order_rect1 = evas_object_rectangle_add(evas);
      +evas_object_name_set(ad->order_rect1, "red");
      +evas_object_color_set(ad->order_rect1, 255, 0, 0, 255);
      +evas_object_move(ad->order_rect1, 120, 310);
      +evas_object_resize(ad->order_rect1, 200, 200);
      +evas_object_show(ad->order_rect1);
      +
      +ad->order_rect2 = evas_object_rectangle_add(evas);
      +evas_object_name_set(ad->order_rect2, "blue");
      +evas_object_color_set(ad->order_rect2, 0, 0, 255, 255);
      +evas_object_move(ad->order_rect2, 180, 350);
      +evas_object_resize(ad->order_rect2, 200, 200);
      +evas_object_show(ad->order_rect2);
      +
      + +

      Figure: Default order of objects on canvas

      +

      Default order of objects on canvas

      + +

      You can change the object triggering the _object_order_cb() callback, which switches the order of the rectangles.

      + +
      static void
      +_object_order_cb(void *data, Evas *e, Evas_Object *obj, void *event_info)
      +{
      +   App_Data *ad = (App_Data *)data;
      +
      +   Evas_Object *rect = evas_object_below_get(ad->order_rect2);
      +   if (!rect)
      +      return;
      +
      +   const char *name = evas_object_name_get(rect);
      +   if (name)
      +      if (strcmp(name, "red") == 0)
      +      {
      +         evas_object_stack_below(ad->order_rect2, rect);
      +
      +         return;
      +      }
      +
      +   rect = evas_object_below_get(ad->order_rect1);
      +   if (!rect)
      +      return;
      +
      +   name = evas_object_name_get(rect);
      +   if (name)
      +      if (strcmp(name, "blue") == 0)
      +      {
      +         evas_object_stack_below(ad->order_rect1, rect);
      +
      +         return;
      +      }
      +}
      + +

      Figure: Changed order of objects on canvas

      +

      Changed order of objects on canvas

      + +

      Evas allows placing an object to top and bottom layer of the canvas object stack. The of _raise_cb callback puts the canvas background on the top position of the screen. The call of _lower_cb callback puts the background to the bottom.

      + +
      static void
      +_lower_cb(void *data, Evas *e, Evas_Object *obj, void *event_info)
      +{
      +   App_Data *ad = (App_Data *)data;
      +
      +   evas_object_lower(ad->bg);
      +}
      +
      +static void
      +_raise_cb(void *data, Evas *e, Evas_Object *obj, void *event_info)
      +{
      +   App_Data *ad = (App_Data *)data;
      +
      +   evas_object_raise(ad->bg);
      +   ad->isBgOnTop = EINA_TRUE;
      +}
      + +

      Figure: Canvas background by default and on top

      +

      Canvas background by default and on top

      + + + + + + + + + +
      + +Go to top + + + + + + + diff --git a/org.tizen.ui.guides/html/native/efl/evas_map_animation_n.htm b/org.tizen.ui.guides/html/native/efl/evas_map_animation_n.htm new file mode 100755 index 0000000..d265764 --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/evas_map_animation_n.htm @@ -0,0 +1,389 @@ + + + + + + + + + + + + + Evas Map Effects + + + + + +
      + +

      Evas Map Effects

      + +

      Evas Map animations allow you to apply transformations to all types of objects by way of UV mapping.

      + +

      In UV mapping, you map points in the source object to 3D space positions in the target object. This allows for rotation, perspective, scale, and other transformation effects, depending on the map. In addition, each map point can carry a multiplier color, which, if properly calculated, can be used to apply 3D shading effects on the target object.

      + +

      Evas provides both raw and easy-to-use functions for UV mapping. The raw functions allow you to create UV maps outside Evas and import them into your application, for example by loading them from an external file. The easy-to-use functions allow you to create UV maps directly in Evas by calculating the map points based on high-level parameters, such as rotation angle and ambient light.

      + +

      Map Points

      + +

      A map consists of a set of points. (Currently, only four points are supported.) Each point contains X and Y canvas coordinates that can be used to alter the geometry of the mapped object, and a Z coordinate that indicates the depth of the point. The Z coordinate does not normally affect the map, but several utility functions use it to calculate the right position of the point given the other parameters.

      + +

      First, create an Evas_Map object using the evas_map_new() function. This function creates the specified number of map points (currently only up to four points). Each point is empty and ready to be modified with Evas_Map functions.

      + +
      Evas_Map *m = evas_map_new(4);
      + +

      If you want to get the size (number of points) of an existing map, use the evas_map_count_get() function.

      + +

      To set the coordinates for each point, use the evas_map_point_coord_set() function:

      + +
      evas_map_point_coord_set(Evas_Map *m, int idx, Evas_Coord x, Evas_Coord y, Evas_Coord z)
      + +

      The following example shows a common way to define a map that matches the geometry of a rectangle (a square in this case):

      + +
      +evas_map_point_coord_set(m, 0, 100, 100, 0);
      +evas_map_point_coord_set(m, 1, 300, 100, 0);
      +evas_map_point_coord_set(m, 2, 300, 300, 0);
      +evas_map_point_coord_set(m, 3, 100, 300, 0);
      +
      + +

      Figure: Map

      +

      Map

      + +

      The following examples all produce the same result as the above example, but with simpler code:

      + +
        +
      • +

        To create a rectangle map using the starting X and Y coordinates combined with width and height, use the evas_map_util_points_populate_from_geometry() function:

        +
        evas_map_util_points_populate_from_geometry(Evas_Map *m, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas_Coord h, Evas_Coord z)
        +

        The following example creates the same map as above:

        +
        evas_map_util_points_populate_from_geometry(m, 100, 100, 200, 200, 0);
        +
      • +
      • +

        To create a map based on the geometry of a given object, use the evas_map_util_points_populate_from_object() or evas_map_util_points_populate_from_object_full() function. The former sets the Z coordinate of all points to 0, whereas the latter allows you to define the same custom Z coordinate for all points:

        +
        evas_map_util_points_populate_from_object(Evas_Map *m, const Evas_Object *obj)
        +
        evas_map_util_points_populate_from_object_full(Evas_Map *m, const Evas_Object *obj, Evas_Coord z)
        +

        The following example creates the same map as above:

        +
        +Evas_Object *o;
        +evas_object_move(o, 100, 100);
        +evas_object_resize(o, 200, 200);
        +evas_map_util_points_populate_from_object(m, o);
        +// OR
        +evas_map_util_points_populate_from_object_full(m, o, 0);
        +
      • +
      + +

      You can apply several effects to an object by simply setting each point of the map to the appropriate coordinates. The following example shows how to create a simulated perspective:

      + +

      Figure: Simulated perspective

      +

      Simulated perspective

      + +
      +evas_map_point_coord_set(m, 0, 100, 100, 0);
      +evas_map_point_coord_set(m, 1, 250, 120, 0);
      +evas_map_point_coord_set(m, 2, 250, 280, 0);
      +evas_map_point_coord_set(m, 0, 100, 300, 0);
      +
      + +

      In the above example, the Z coordinate is unused: when setting points by hand, the Z coordinate is irrelevant.

      + +

      If you want to get the actual coordinates of a map, use the evas_map_point_coord_get() function:

      + +
      evas_map_point_coord_get(const Evas_Map *m, int idx, Evas_Coord *x, Evas_Coord *y, Evas_Coord *z)
      + +

      After you have defined the map points, apply them to your map for transformation:

      + +
      +evas_object_map_set(o, m);
      +evas_object_map_enable_set(o, EINA_TRUE);
      +
      + +

      Finally, after you are done with the map, release the memory allocated to it using the evas_map_free() function:

      + +
      evas_map_free(m);
      + +

      The utility functions described in the next section allow you to perform the above tasks with less coding work.

      + +

      Utility Functions

      + +

      Utility functions take an already configured map and allow you to easily modify it to produce specific effects. For example, to rotate an object around its center, you need the rotation angle and the coordinates of each corner of the object to perform the math required to get the new set of coordinates that needs to be set for the map. Evas provides a utility function that does the math for you:

      + +
      evas_map_util_rotate(Evas_Map *m, double degrees, Evas_Coord cx, Evas_Coord cy)
      + +

      This function rotates the map based on the angle and the center coordinates of the rotation provided as arguments. A positive angle rotates the map clockwise, while a negative angle rotates the map counter-clockwise.

      + +

      The following example shows how to rotate an object around its center point by 45 degrees clockwise. In the following figure, the center of rotation is the red dot.

      + +
      +evas_object_geometry_get(o, &x, &y, &w, &h);
      +m = evas_map_new(4);
      +evas_map_util_points_populate_from_object(m, o);
      +evas_map_util_rotate(m, 45, x + (w / 2), y + (h / 2));
      +evas_object_map_set(o, m);
      +evas_object_map_enable_set(o, EINA_TRUE);
      +evas_map_free(m);
      +
      + +

      Figure: Rotating around the center point

      +

      Rotating around the center point

      + +

      You can rotate the object around any other point simply by setting the last two arguments of the evas_map_util_rotate() function to the appropriate values:

      + +
      evas_map_util_rotate(m, 45, x + w - 20, y + h - 20);
      + +

      Figure: Rotating around other points

      +

      Rotating around other points

      + +

      You can also set the center of the window as the center of the rotation using the appropriate coordinates of the Evas canvas:

      + +
      +evas_output_size_get(evas, &w, &h);
      +m = evas_map_new(4);
      +evas_map_util_points_populate_from_object(m, o);
      +evas_map_util_rotate(m, 45, w, h);
      +evas_object_map_set(o, m);
      +evas_object_map_enable_set(o, EINA_TRUE);
      +evas_map_free(m);
      +
      + +

      Zoom

      + +

      The evas_map_util_zoom() function zooms the points of the map from a center point, defined by cx and cy. The zoomx and zoomy arguments specify how much to zoom in on the X and Y axes. A value of 1.0 means no zoom, 2.0 means double the size, 0.5 means half the size, and so on. All the coordinates are global canvas coordinates.

      + +
      +evas_map_util_zoom(Evas_Map *m, double zoomx, double zoomy, Evas_Coord cx, Evas_Coord cy)
      +
      + +

      3D Maps

      + +

      Maps can also be used to achieve a 3D effect. In a 3D effect, the Z coordinate of each point is meaningful: the higher the value, the further back the point is located. Smaller values (usually negative) mean that the point is closer to the user.

      + +

      3D also introduces the concept of the back face of an object. An object is said to be facing the user when all its points are placed in a clockwise formation, as shown in the left map in the following figure. Rotating the map around its Y axis swaps the order of the points into a counter-clockwise formation, making the object face away from the user, as shown in the right map in the following figure. The back face is especially relevant in lighting (see below).

      + +

      Figure: Rotating around the Y axis

      +

      Rotating around the Y axis

      + +

      To determine whether a map is facing the user, use the evas_map_util_clockwise_get() function. This function returns EINA_TRUE if the map is facing the user and EINA_FALSE if the map is facing away from the user. This is normally done after all the other operations are applied to the map.

      + +
      evas_map_util_clockwise_get(Evas_Map *m)
      + +

      3D Rotation and Perspective

      + +

      The evas_map_util_3d_rotate() function transforms a map to apply a 3D rotation to the mapped object. You can apply the rotation around any point in the canvas (including a Z coordinate). You can also apply the rotation around any of the three axes.

      + +
      evas_map_util_3d_rotate(Evas_Map *m, double dx, double dy, double dz, Evas_Coord cx, Evas_Coord cy, Evas_Coord cz)
      + +

      Starting from this simple setup, and setting the maps so that the blue square rotates around the Y axis, we get the following:

      + +

      Figure: 3D rotation

      +

      3D rotation

      + +

      A simple overlay over the image shows the original geometry of each object and the axis around which they are being rotated. The Z axis is not shown, since it is orthogonal to the screen. To show the Z axis, that is, to add 3D perspective to the transformation, use the evas_map_util_3d_perspective() function on the map after its position has been set:

      + +
      evas_map_util_3d_perspective(Evas_Map *m, Evas_Coord px, Evas_Coord py, Evas_Coord z0, Evas_Coord foc)
      + +

      The result makes the vanishing point the center of each object:

      + +

      Figure: Adding perspective

      +

      Adding perspective

      + +

      Color and Lighting

      + +

      Each point in a map can be set to a color, which will be multiplied with the object’s own color and linearly interpolated between adjacent points. To set the color separately for each point, use the evas_map_point_color_set() function:

      + +
      evas_map_point_color_set(Evas_Map *m, int idx, int r, int g, int b, int a)
      + +

      To set the same color for every point, use the evas_map_util_points_color_set() function:

      + +
      evas_map_util_points_color_set(Evas_Map *m, int r, int g, int b, int a)
      + +

      When using a 3D effect, colors can be used to improve its look by simulating a light source. The evas_map_util_3d_lighting() function makes this task easier by taking the coordinates of the light source and its color, along with the color of the ambient light. Evas then sets the color of each point based on its distance to the light source, the angle at which the object is facing the light source, and the ambient light. Here, the orientation of each point is important.

      + +
      evas_map_util_3d_lighting(Evas_Map *m, Evas_Coord lx, Evas_Coord ly, Evas_Coord lz, int lr, int lg, int lb, int ar, int ag, int ab)
      + +

      If the map points are defined counter-clockwise, the object faces away from the user and is therefore obscured, since no light is reflecting back from it.

      + +

      Figure: Obscured object

      +

      Obscured object

      + +

      Mapping

      + +

      Images need special handling when mapped. While Evas can easily handle objects, it is completely oblivious to the contents of images. This means that each point in a map needs to be mapped to a specific pixel in the source image. Failing to do this can result in unexpected behavior.

      + +

      Let's get started with the following three images, each sized at 200 × 200 pixels:

      + +

      Figure: Starting point

      +

      Starting point

      + +

      The following three images illustrate the case where a map is set to an image object without setting the right UV mapping for each map point. The objects themselves are mapped properly to their new geometries, but the images are not displayed correctly within the mapped objects.

      + +

      Figure: Questionable result

      +

      Questionable result

      + +

      To transform an image correctly, Evas needs to know how to handle the image within the map. You can do this using the evas_map_point_image_uv_set() function, which allows you to map a given point in a map to a given pixel in a source image:

      + +
      +evas_map_point_image_uv_set(Evas_Map *m, int idx, double u, double v)
      +
      + +

      To match our example images to the maps above, all we need is the size of each image, which we can get using the evas_object_image_size_get() function.

      + +
      +// Tux 1: Some cropping and stretch up
      +evas_map_point_image_uv_set(m, 0, 0, 20);
      +evas_map_point_image_uv_set(m, 1, 200, 20);
      +evas_map_point_image_uv_set(m, 2, 200, 180);
      +evas_map_point_image_uv_set(m, 3, 0, 180);
      +evas_object_map_set(tux1, m);
      +evas_object_map_enable_set(tux1, EINA_TRUE);
      +
      +// Inverted texture for shadow:
      +evas_map_point_image_uv_set(m, 0, 0, 180);
      +evas_map_point_image_uv_set(m, 1, 200, 180);
      +evas_map_point_image_uv_set(m, 2, 200, 20);
      +evas_map_point_image_uv_set(m, 3, 0, 20);
      +evas_object_map_set(tux1_shadow, m);
      +evas_object_map_enable_set(tux1_shadow, EINA_TRUE);
      +
      +// Tux 2: Make it fit to the map:
      +evas_map_point_image_uv_set(m, 0, 0, 0);
      +evas_map_point_image_uv_set(m, 1, 200, 0);
      +evas_map_point_image_uv_set(m, 2, 200, 200);
      +evas_map_point_image_uv_set(m, 3, 0, 200);
      +evas_object_map_set(tux2, m);
      +evas_object_map_enable_set(tux2, EINA_TRUE);
      +
      +// Tux 3: Zoom and fit relatively to image size
      +evas_object_image_size_get(evas_object_image_source_get(tux3), &w, &h);
      +evas_map_point_image_uv_set(m, 0, 0.1 * w, 0.1 * h);
      +evas_map_point_image_uv_set(m, 1, 0.9 * w, 0.1 * h);
      +evas_map_point_image_uv_set(m, 2, 0.9 * w, 0.9 * h);
      +evas_map_point_image_uv_set(m, 3, 0.1 * w, 0.9 * h);
      +evas_object_map_set(tux3, m);
      +evas_object_map_enable_set(tux3, EINA_TRUE);
      +
      + +

      Figure: Correct result

      +

      Correct result

      + +

      You can also set a map to use only part of an image, or you can even map the points in inverted order. Combined with the evas_object_image_source_set() function, you can achieve more interesting results still.

      + +

      Lighting

      + +

      Evas_Map allows you to define an ambient light and a light source within the scene. Both of these light sources have their own colors.

      + +
      evas_map_util_3d_lighting(Evas_Map *m, Evas_Coord lx, Evas_Coord ly, Evas_Coord lz, int lr, int lg, int lb, int ar, int ag, int ab)
      + +

      The above function is used to apply lighting calculations (from a single light source) to a given map. The red, green, and blue values of each vertex will be modified to reflect the lighting based on the light source coordinates, its color, the ambient color, and the angle at which the map faces the light source. The points of a surface should be defined in a clockwise formation if the surface is facing the user, since faces have a logical side for lighting.

      + +

      To get the reflections (gradient) in the shadow of our previous example, you have to define a source of light close enough to the user and a very bright ambient light, for example:

      + +
      +evas_map_util_3d_lighting(m, // Evas_Map object
      +                          250/2, 150/2, -100, // Spot light coordinates
      +                          255, 255, 255, // Spot light color
      +                          200, 200, 200); // Ambient light color
      +
      + +

      Alpha Channel

      + +

      You can also use an alpha channel on your map by enabling the alpha channel feature:

      + +
      evas_map_alpha_set(Evas_Map *m, Eina_Bool enabled)
      + +

      Next, set the alpha value separately for each map point:

      + +
      evas_map_point_color_set(Evas_Map *m, int idx, int r, int g, int b, int a)
      + +

      Alternatively, you can set the same alpha value to all map points:

      + +
      evas_map_util_points_color_set(Evas_Map *m, int r, int g, int b, int a)
      + +

      The following code sets the shadow transparency for the first image in the above three-image example:

      + +
      +// Set object transparency to 50%:
      +evas_map_util_points_color_set(m, 255, 255, 255, 127);
      +
      +// Tux's head is almost invisible in the shadow:
      +evas_map_point_color_set(m, 3, 255, 255, 255, 15);
      +evas_map_point_color_set(m, 4, 255, 255, 255, 15);
      +
      + +

      Smoothing

      + +

      To enable smoothing when rendering a map, use the evas_map_smooth_set() function:

      + +
      evas_map_smooth_set(Evas_Map *m, Eina_Bool enabled)
      + +

      The first argument is the Evas_Map object to apply smoothing to. The second argument sets whether to enable the smoothing:

      + +
        +
      • EINA_TRUE: Enable smoothing.
      • +
      • EINA_FALSE: Disable smoothing.
      • +
      + +

      If the object is of a type that has its own smoothing settings, the smoothing settings must be disabled for both the object and the map. Map smoothing is enabled by default. To check whether map smoothing is enabled, use the evas_map_smooth_get() function.

      + + + + + + + + + + +
      Note
      Except as noted, this content is licensed under LGPLv2.1+.
      + + + +
      + +Go to top + + + + + + + \ No newline at end of file diff --git a/org.tizen.ui.guides/html/native/efl/evas_map_effects_n.htm b/org.tizen.ui.guides/html/native/efl/evas_map_effects_n.htm new file mode 100755 index 0000000..3184eee --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/evas_map_effects_n.htm @@ -0,0 +1,253 @@ + + + + + + + + + + + + + + Creating Evas Map Effects + + + + + + +
      +

      Creating Evas Map Effects

      + + +

      This tutorial demonstrates how you can use Evas map functions to create an application in which you can change the map point coordinates of Evas objects. You can modify the map point U and V texture source point using Evas map mapping APIs. "U" and "V" denote the axes of the 2D texture.

      + +

      Figure: Evas map mapping application

      +

      Evas map mapping application

      + +

      Creating the Basic Application

      +

      To create a basic application:

      +
        +
      1. +

        To use the required APIs, include the following libraries:

        + +
        #include <app.h>
        +#include <Elementary.h>
        +#include <system_settings.h>
        +#include <efl_extension.h>
        +
      2. + +
      3. +

        Create an Evas object for an Elementary window and a button for mapping the map information:

        + +
        typedef struct appdata 
        +{
        +   Evas_Object *win;
        +   Evas_Object *button;
        +Evas_Object *default_btn;
        +} 
        +appdata_s;
        +
      4. +
      5. +

        To create an Elementary window, use the elm_win_util_standard_add() function and give the name and title of the application. To set a callback on hardware Back button, the use eext_object_event_callback_add() function. To display the Evas object, use the evas_object_show() function.

        + +
        static void
        +create_base_gui(appdata_s *ad)
        +{
        +    Evas_Object *evas_text = NULL;
        +    Evas *evas                = NULL;
        +
        +   // Window
        +   ad->win = elm_win_util_standard_add("Extra object function", "Extra object function");
        +   elm_win_autodel_set(ad->win, EINA_TRUE);
        +
        +   // Window callbacks
        +   evas_object_smart_callback_add(ad->win, "delete,request", win_delete_request_cb, NULL);
        +   eext_object_event_callback_add(ad->win, EEXT_CALLBACK_BACK, back_cb, ad);
        +
        +   evas = evas_object_evas_get(ad->win);
        +
        +   evas_text = evas_object_text_add(evas);
        +   evas_object_text_text_set(evas_text, "Evas Map Mapping");
        +   evas_object_text_font_set(evas_text, "Sans", 18);
        +   evas_object_color_set(evas_text, 50, 100, 200, 255);
        +   evas_object_move(evas_text, 10, 90);
        +   evas_object_show(evas_text);
        +
        +   // Evas map source code
        +
        +   evas_object_show(ad->win);
        +}
        +
      6. + +
      7. +

        Implement callback functions to enable closing the application:

        + +
        static void
        +back_cb(void *data, Evas_Object *obj, void *event_info)
        +{
        +   appdata_s *ad = data;
        +
        +   elm_win_lower(ad->win);
        +}
        +
        +static void
        +win_delete_request_cb(void *data, Evas_Object *obj, void *event_info)
        +{
        +   ui_app_exit();
        +}
        +
      8. + +
      9. +

        Create an elementary application with a GUI:

        + +
        static bool
        +app_create(void *data)
        +{
        +   appdata_s *ad = data;
        +
        +   // Create the application UI
        +   create_base_gui(ad);
        +
        +   return true;
        +}
        +
        +int
        +main(int argc, char *argv[])
        +{
        +   appdata_s ad = {0,};
        +
        +   ui_app_lifecycle_callback_s event_callback = {0,};
        +
        +   event_callback.create = app_create;
        +
        +   // Run the main loop
        +   return ui_app_main(argc, argv, &event_callback, &ad);
        +}
        +
      10. + +
      11. +

        Create the button for mapping. Use the move and resize functions to configure the button's custom geometry:

        + +
        // Create a button for mapping
        +ad->button = elm_button_add(ad->win);
        +elm_object_text_set(ad->button, "Evas Map Mapping ");
        +evas_object_move(ad->button, 15, 100);
        +evas_object_resize(ad->button, ELM_SCALE_SIZE(250), ELM_SCALE_SIZE(200));
        +evas_object_show(ad->button);
        +
        +// Create a default button
        +ad->default_btn = elm_button_add(ad->win);
        +elm_object_text_set(ad->default_btn, "Default Button ");
        +evas_object_move(ad->default_btn, 15, 300);
        +evas_object_resize(ad->default_btn, ELM_SCALE_SIZE(250), ELM_SCALE_SIZE(200));
        +evas_object_show(ad->default_btn);
        +
      12. +
      + +

      Creating Map Data

      + +

      By using the evas_map_new() and evas_map_*() functions, you can create map data to be attached to the button:

      + +
        +
      1. +

        Get the Evas_Map object to create map data using the evas_map_new() function:

        + +
        +Evas_Map *map;
        +map = evas_map_new(4);
        + +

        The map of transformation points is used later with an Evas object.

        +
      2. + +
      3. +

        Set the coordinates for each point using the evas_map_point_coord_set() function. You can apply several effects to the Evas object by setting each point of the map to the right coordinates.

        + +
        // Set map coordinates
        +evas_map_point_coord_set(map, 0, 15, 100, 0);
        +evas_map_point_coord_set(map, 1, 265, 100, 0);
        +evas_map_point_coord_set(map, 2, 265, 300, 0);
        +evas_map_point_coord_set(map, 3, 15, 400, 0);
        +
      4. + +
      5. +

        Set UV data using the evas_map_point_image_uv_set() function, which informs the map of the correct pixels in the image it is mapping:

        + +
        // Set image UV
        +evas_map_point_image_uv_set(map, 0, 0, 0);
        +evas_map_point_image_uv_set(map, 1, 500, 50);
        +evas_map_point_image_uv_set(map, 2, 500, 400);
        +evas_map_point_image_uv_set(map, 3, 0, 200);
        +
      6. +
      + + +

      Applying the Map to the Evas Object

      + +

      To set the map on a given object, use the evas_object_map_set() function for the object. A map contains 4 points, each having canvas x, y coordinates with an optional z point value for perspective correction, if available. Each point also has U an V coordinates.

      + +
      // Apply map to button evas object
      +
      +evas_object_map_set(ad->button, map);
      + +

      Clearing Map Data and Enabling Map Features

      + +

      Free the map data and all memory associated with it when you no longer need it:

      + +
      // Free map resources
      +
      +evas_map_free(map);
      + +

      You can enable or disable the map features for the object. When enabled, the object geometry is saved, and the new geometry changes its position and size to reflect the set map geometry.

      + +
      // Enable map features
      +
      +evas_object_map_enable_set(ad->button, EINA_TRUE);
      + + + + + + + +
      + +Go to top + + + + + + + diff --git a/org.tizen.ui.guides/html/native/efl/evas_objects_n.htm b/org.tizen.ui.guides/html/native/efl/evas_objects_n.htm new file mode 100755 index 0000000..d0a4a7d --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/evas_objects_n.htm @@ -0,0 +1,824 @@ + + + + + + + + + + + + + Evas Objects + + + + + +
      + +

      Evas Objects

      + +

      An Evas object is the most basic visual entity used in Evas. Everything, be it a single line or a complex list of UI components, is an Evas object.

      + +

      Primitive Renderable Objects

      +

      Primitive objects are the base upon which to build a complex interface: rectangles, lines, polygons, images, textblocks, and texts.

      +

      Rectangle

      +

      There is only one function to deal with rectangle objects. However, the rectangle is manipulated using the generic evas object functions.

      +

      The evas rectangle serves a number of key functions when working on Evas programs.

      +
        +
      • background
      • +
      • debugging
      • +
      • clipper
      • +
      + +

      Background

      +

      A common requirement of Evas programs is to have a solid color background, which can be accomplished with the following code.

      +
      Evas_Object *bg = evas_object_rectangle_add(evas_canvas);
      +
      +// Here we set the rectangles red, green, blue and opacity levels
      +evas_object_color_set(bg, 255, 255, 255, 255); // opaque white background
      +evas_object_resize(bg, WIDTH, HEIGHT); // covers full canvas
      +evas_object_show(bg);
      +
      + +

      Debugging

      +

      When debugging visual issues with evas programs, the rectangle is a useful tool. The rectangle's simplicity means that it is easier to pinpoint issues with it than with more complex objects. A common technique to use when writing an evas program and not getting the desired visual result is to replace an object for a solid color rectangle and seeing how it interacts with the other elements. This often allows us to notice clipping, parenting or positioning issues. Once the issues are identified and corrected, the rectangle can be replaced for the original object, and in all likelihood any remaining issues are specific to that object's type.

      + +

      Clipping

      +

      Clipping serves two main functions:

      +
        +
      • limiting visibility
      • +
      • applying a layer of color to an object
      • +
      + + +

      Text

      +

      An Evas text object shows a basic single-line single-style text.

      +
      Evas_Object *text = evas_object_text_add(evas_canvas);
      +evas_object_text_text_set(text, "some text");
      +evas_object_color_set(text, 127, 0, 0, 127);
      +evas_object_show(text);
      +
      + +

      To set the text, use evas_object_text_text_set(text, some_text). You can set the current text with evas_object_text_text_get(text).

      +

      To set the font, use evas_object_text_font_set(text, font, size):

      +
        +
      • text: The text object
      • +
      • font: The font name you want to use
      • +
      • size: The font size you want to use. To query the current font, use evas_object_text_font_set(text, font, size).
      • +
      +

      To set the text style, use evas_object_text_style_set(text, style). The following styles are supported:

      +
        +
      • EVAS_TEXT_STYLE_PLAIN: Plain, standard text
      • +
      • EVAS_TEXT_STYLE_SHADOW: Text with shadow underneath
      • +
      • EVAS_TEXT_STYLE_OUTLINE: Text with an outline
      • +
      • EVAS_TEXT_STYLE_SOFT_OUTLINE: Text with a soft outline
      • +
      • EVAS_TEXT_STYLE_GLOW: Text with a glow effect
      • +
      • EVAS_TEXT_STYLE_OUTLINE_SHADOW: Text with both outline and shadow effects
      • +
      • EVAS_TEXT_STYLE_FAR_SHADOW: Text with (far) shadow underneath
      • +
      • EVAS_TEXT_STYLE_OUTLINE_SOFT_SHADOW: Text with outline and soft shadow effects combined
      • +
      • EVAS_TEXT_STYLE_SOFT_SHADOW: Text with (soft) shadow underneath
      • +
      • EVAS_TEXT_STYLE_FAR_SOFT_SHADOW: Text with (far soft) shadow underneath
      • +
      • EVAS_TEXT_STYLE_SHADOW_DIRECTION_BOTTOM_RIGHT: Shadow growing to bottom right
      • +
      • EVAS_TEXT_STYLE_SHADOW_DIRECTION_BOTTOM: Shadow growing to the bottom
      • +
      • EVAS_TEXT_STYLE_SHADOW_DIRECTION_BOTTOM_LEFT: Shadow growing to bottom left
      • +
      • EVAS_TEXT_STYLE_SHADOW_DIRECTION_LEFT: Shadow growing to the left
      • +
      • EVAS_TEXT_STYLE_SHADOW_DIRECTION_TOP_LEFT: Shadow growing to top left
      • +
      • EVAS_TEXT_STYLE_SHADOW_DIRECTION_TOP: Shadow growing to the top
      • +
      • EVAS_TEXT_STYLE_SHADOW_DIRECTION_TOP_RIGHT: Shadow growing to top right
      • +
      • EVAS_TEXT_STYLE_SHADOW_DIRECTION_RIGHT: Shadow growing to the right. To query the current style, use evas_object_text_style_get(text).
      • +
      +

      If the text does not fit, make an ellipsis on it by using evas_object_text_ellipsis_set(text, ellipsis). The (float) value specifies, which part of the text is shown.

      +
        +
      • 0.0: The beginning is shown and the end trimmed.
      • +
      • 1.0: The beginning is trimmed and the end shown.
      • +
      • Any value in between means that both ends of the text have ellipsis and the set part is shown.
      • +
      • -1.0: Ellipsis is disabled. To query the current ellipsis value, use evas_object_text_ellipsis_get(text).
      • +
      +

      When the text style is set to glow, set the glow color using evas_object_text_glow_color_set(text, r, g, b, a), where r, g, b, and a are respectively the red, green, blue, and alpha values. The effect is placed at a short distance from the text but not touching it. For glows set right at the text, use evas_object_text_glow2_color_set(text, r, g, b, a). To query the current color, use evas_object_text_glow_color_get(text, r, g, b, a), respectively evas_object_text_glow2_color_get(text, r, g, b, a).

      +

      If your text style is set to display a shadow, use evas_object_text_shadow_color_set(text, r, g, b, a), where r, g, b, and a are respectively the red, green, blue, and alpha values. To query the current color, use evas_object_text_shadow_color_get(text, r, g, b, a)

      +

      If your text style is set to display an outline, use evas_object_text_outline_color_set(text, r, g, b, a), where r, g, b, and a are respectively the red, green, blue, and alpha values. To query the current color, use evas_object_text_outline_color_get(text, r, g, b, a)

      + + +

      Primitive Smart Objects

      +

      A smart object is a special Evas object that provides custom functions to handle automatically clipping, hiding, moving, resizing color setting and more on child elements, for the smart object's user. They could be, for example, a group of objects that move together, or implementations of whole complex UI components, providing some intelligence and extension to simple Evas objects.

      + +

      Primitive Container Objects

      +

      A container is a Smart object that holds children Evas objects in a specific fashion.

      +

      Table

      +

      A table is a smart object that packs children using a tabular layout.

      +
      table = evas_object_table_add(evas);
      +evas_object_table_homogeneous_set(table, EVAS_OBJECT_TABLE_HOMOGENEOUS_NONE);
      +evas_object_table_padding_set(table, 0, 0);
      +evas_object_resize(table, WIDTH, HEIGHT);
      +evas_object_show(table);
      +
      +rect = evas_object_rectangle_add(evas);
      +evas_object_color_set(rect, 255, 0, 0, 255);
      +evas_object_size_hint_min_set(rect, 100, 50);
      +evas_object_show(rect);
      +evas_object_table_pack(table, rect, 1, 1, 2, 1);
      +
      +rect = evas_object_rectangle_add(d.evas);
      +evas_object_color_set(rect, 0, 255, 0, 255);
      +evas_object_size_hint_min_set(rect, 50, 100);
      +evas_object_show(rect);
      +evas_object_table_pack(table, rect, 1, 2, 1, 2);
      +
      +rect = evas_object_rectangle_add(d.evas);
      +evas_object_color_set(rect, 0, 0, 255, 255);
      +evas_object_size_hint_min_set(rect, 50, 50);
      +evas_object_show(rect);
      +evas_object_table_pack(table, rect, 2, 2, 1, 1);
      +
      +rect = evas_object_rectangle_add(d.evas);
      +evas_object_color_set(rect, 255, 255, 0, 255);
      +evas_object_size_hint_min_set(rect, 50, 50);
      +evas_object_show(rect);
      +evas_object_table_pack(table, rect, 2, 3, 1, 1);
      +
      + +

      In this example, we add a non-homogeneous table to the canvas with its padding set to 0.

      +

      We then add four different colored rectangles with different properties.

      +
        +
      • the first one, at the first column and first line, spans two columns and one line
      • +
      • the second one, at the first column and second line, spans one columns and two lines
      • +
      • the third one, at the second column and second line, fits in one cell
      • +
      • the fourth one, at the second column and third line, also fits in one cell
      • +
      +

      To create a table, use evas_object_table_add(evas).

      +

      To set the table layout (the cells), use evas_object_table_homogeneous_set(table, homogeneous). The following values can be homogeneous:

      +
        +
      • EVAS_OBJECT_TABLE_HOMOGENEOUS_NONE: This default value has columns and rows calculated based on hints of individual cells. This is flexible, but much heavier on computations.
      • +
      • EVAS_OBJECT_TABLE_HOMOGENEOUS_TABLE: The table size is divided equally among children, filling the whole table area. If the children have a minimum size that is larger than this (including padding), then the table overflows and is aligned respecting the alignment hint, possibly overlapping sibling cells.
      • +
      • EVAS_OBJECT_TABLE_HOMOGENEOUS_ITEM: The greatest minimum cell size is used: if no element is set to expand, the contents of the table are the minimum size and the bounding box of all the children is aligned relatively to the table object using evas_object_table_align_get(). If the table area is too small to hold this minimum bounding box, then the objects keep their size and the bounding box overflows the box area, still respecting the alignment. To set the current mode, use evas_object_table_homogeneous_get(table).
      • +
      +

      The table's content alignment is set using evas_object_table_align_set(table, horizontal, vertical), where horizontal and vertical are floating values. To see them, use evas_object_table_align_get(table, horizontal, vertical).

      +

      To set the padding, use evas_object_table_padding_set(table, horizontal, vertical). To see the current value, use evas_object_table_padding_get(table, horizontal, vertical).

      +

      _To see the current column and row count, use evas_object_table_col_row_size_get(table, columns, rows).

      + +

      Grid

      +

      A grid is a smart object that packs its children as with a regular grid layout.

      +

      Grids are added to the canvas with evas_object_grid_add(evas).

      +

      To change a grid's virtual resolution, use evas_object_grid_size_set(grid, width, height), to see it, use evas_object_grid_size_get(grid, width, height).

      +

      To add an object, use evas_object_grid_pack(grid, child, x, y, w, h), where

      +
        +
      • x is the virtual X coordinate of the child
      • +
      • y is the virtual y coordinate of the child
      • +
      • w is the virtual width of the child
      • +
      • h is the virtual height of the child
      • +
      +

      Box

      +

      A box is a simple container that sets its children objects linearly.

      +

      To add a box to your canvas, use evas_object_box_add(evas).

      +

      To add a child to the box, use

      +
        +
      • evas_object_box_append(box, child): The child is appended.
      • +
      • evas_object_box_insert_after(box, child, reference): The child is added after reference.
      • +
      • evas_object_box_insert_before(box, child, reference): The child is added before reference.
      • +
      • evas_object_box_insert_at(box, child, pos): The child is added at the specified position.
      • +
      +

      To set the alignment, use evas_object_box_align_set(box, horizontal, vertical).

      +
        +
      • horizontal: 0.0 means aligned to the left, 1.0 means to the right;
      • +
      • vertical: 0.0 means aligned to the top, 1.0 means to the bottom.
      • +
      +

      Evas has predefined box layouts available:

      +
        +
      • evas_object_box_layout_horizontal();
      • +
      • evas_object_box_layout_vertical();
      • +
      • evas_object_box_layout_homogeneous_horizontal();
      • +
      • evas_object_box_layout_homogeneous_vertical();
      • +
      • evas_object_box_layout_homogeneous_max_size_horizontal();
      • +
      • evas_object_box_layout_homogeneous_max_size_vertical();
      • +
      • evas_object_box_layout_flow_horizontal();
      • +
      • evas_object_box_layout_flow_vertical();
      • +
      • evas_object_box_layout_stack().
      • +
      + +

      Image Objects

      + + +

      Using Evas, you can create and manipulate image objects. Evas supports image loaders of various formats as plug-in modules.

      +

      The image formats that Evas supports include bmp, edj, gif, ico, jpeg, pmaps, png, psd, svg, tga, tiff, wbmp, webp, and xpm.

      + +

      Figure: Evas image loader

      +

      Evas image loader

      + +

      Evas Object Image Functions

      + +

      Evas has over 70 image object functions. The following functions are discussed in this document:

      +
      +Evas_Object *evas_object_image_add(Evas *e);
      +void evas_object_image_file_set(Evas_Object *obj, const char *file, const char *key);
      +void evas_object_image_fill_set(Evas_Object *obj, int x, int y, int w, int h);
      +void evas_object_image_filled_set(Evas *e, Eina_Bool setting);
      +Evas_Object *evas_object_image_filled_add(Evas *e);
      +void evas_object_image_smooth_scale_set(Evas_Object *obj, Eina_Bool smoothscale);
      +void evas_object_image_load_size_set(Evas_Object *obj, int w, int h);
      +void evas_object_image_data_set(Evas_Object *obj, void *data);
      +void *evas_object_image_data_get(const Evas_Object *obj, Eina_Bool for_writing);
      +void evas_object_image_size_set(Evas_Object *obj, int w, int h);
      +void evas_object_image_data_update_add(Evas_Object *obj, int x, int y, int w, int h);
      +Eina_Bool evas_object_image_save(const Evas_Object *obj, const char *file, const char *key, const char *flags);
      +
      + +

      Creating an Image Object and Setting the Image Data Source

      +

      A common use case of an image object is to set a file as the image data source. The process has 3 steps and each one involves the following API calls:

      +
        +
      • The evas_object_image_add() function creates an image object and returns the pointer. +
        Evas_Object *evas_object_image_add(Evas *e);
        +
      • +
      • The evas_object_image_file_set() function sets a source file on the image object. The object fetches the image pixel data from the source file. +
        void evas_object_image_file_set(Evas_Object *obj, const char *file, const char *key);
        +
      • +
      • The evas_object_image_fill_set() sets how to fill the image object's area with the given pixel data. +
        void evas_object_image_fill_set(Evas_Object *obj, int x, int y, int w, int h);
        +
      • +
      + +

      In the following code example, the main() function creates an image object and displays it on a window. The image object size is 300x300 and the source image resolution is 100x127. The image is scaled into 300 by 300 to fill the image object area using the evas_object_image_fill_set() function.

      +
      +#include <Elementary.h>
      +
      +int main(int argc, char **argv)
      +{
      +   elm_init(argc, argv);
      +
      +   // Create a window object
      +   Evas_Object *win = elm_win_add(NULL, "main", ELM_WIN_BASIC);
      +   evas_object_resize(win, 400, 400);
      +   evas_object_show(win);
      +
      +   // Return Evas handle from window
      +   Evas *e = evas_object_evas_get(win);
      +
      +   // Create an image object
      +   Evas_Object *img = evas_object_image_add(e);
      +
      +   // Set a source file to fetch pixel data
      +   evas_object_image_file_set(img, "./logo.png", NULL);
      +
      +   // Set the size and position of the image on the image object area
      +   evas_object_image_fill_set(img, 0, 0, 300, 300);
      +
      +   evas_object_move(img, 50, 50);
      +   evas_object_resize(img, 300, 300);
      +   evas_object_show(img);
      +
      +   elm_run();
      +
      +   elm_shutdown();
      +
      +   return 0;
      +}
      +
      +

      Figure: Image object display

      +

      Image object display

      + +

      Managing Images

      + +

      To manage image objects in Evas:

      + +

      Limiting Visibility

      +

      Evas always supports the image file type it was compiled with. Check your software packager for the information and use the evas_object_image_extension_can_load_get() function.

      + +

      Create the image object. Set a source file on it, so that the object knows where to fetch the image data.

      +

      Define how to fill the image object area with the given pixel data. You can use a sub-region of the original image, or have it tiled repeatedly on the image object.

      + +
      +img = evas_object_image_add(canvas);
      +evas_object_image_file_set(img, "path/to/img", NULL);
      +evas_object_image_fill_set(img, 0, 0, w, h);
      +
      + + +

      If the entire source image is to be displayed on the image object, stretched to the destination size, use the evas_object_image_filled_set() function helper that you can use instead of the evas_object_image_fill_set() function:

      + +
      +evas_object_image_filled_set(img, EINA_TRUE);
      +
      + +

      Scaling Images

      +

      Resizing image objects scales the source images to the image object size, if the source images are set to fill the object area using the evas_object_image_filled_set() function.

      +

      Control the aspect ratio of an image for different sizes with functions to load images scaled up or down in memory.

      + +

      Evas has a scale cache, which caches scaled versions of images used often. You can also have Evas rescale the images smoothly, however, that is computationally expensive.

      + +

      Users can decide how to fill the image object area with the given image pixel data by setting the position, width, and height of the image using the evas_object_image_fill_set() function. Without setting this information, the image is not displayed. If the size of the image is bigger than the image object area, only a sub-region of the original image is displayed. If the image is smaller than the area, images are tiled repeatedly to fill the object area.

      + +

      Figure: Image scaling

      +

      Image scaling

      + + + + + + + + + + + + + + +

      evas_object_image_fill_set(obj, 50, 0, 300, 300)evas_object_image_fill_set(obj, 0, 0, 200, 200)evas_object_image_fill_set(obj, 0, 0, 100, 127)
      + +

      The evas_object_image_filled_set() function scales the image to fit the object area. Resizing the image object automatically triggers an internal call to the evas_object_image_fill_set() function.

      +
      +void evas_object_image_filled_set(Evas *e, Eina_Bool setting);
      + +

      The evas_object_image_filled_add() function creates a new image object that automatically scales its bound image to the object area. This is a helper function around the evas_object_image_add() and evas_object_image_filled_set() functions.

      + +
      Evas_Object *evas_object_image_filled_add(Evas *e);
      + +

      Scaled images' quality can differ according to scaling algorithms. Smooth scaling improves the image quality in the process of size reducing or enlarging. Evas runs its own smooth scaling algorithm by default and provides an API so users can disable the function.

      + +
      +void evas_object_image_smooth_scale_set(Evas_Object *obj, Eina_Bool smoothscale);
      + +

      The algorithm is implemented using the SIMD (Single Instruction Multiple Data) vectorization in case of software rendering. It is optimized on Intel and ARM CPU through MMX and NEON command respectively.

      + +

      There is a trade-off between image smoothness and rendering performance. The load gets bigger as the image gets bigger. Users can avoid such scaling overload by using the same size of the image object and the source image.

      + +

      In the following code, 2 image objects are created to show the effects of smooth scaling. The one with smooth scaling applied appears softer on the screen.

      + +
      +#include <Elementary.h>
      +
      +int main(int argc, char **argv)
      +{
      +   elm_init(argc, argv);
      +
      +   // Create a window object
      +   Evas_Object *win = elm_win_add(NULL, "main", ELM_WIN_BASIC);
      +   evas_object_resize(win, 400, 200);
      +   evas_object_show(win);
      +
      +   // Return Evas handle from window
      +   Evas *e = evas_object_evas_get(win);
      +
      +   // Create an image object
      +   Evas_Object *img = evas_object_image_filled_add(e);
      +   evas_object_image_file_set(img, "./logo.png", NULL);
      +   evas_object_move(img, 0, 0);
      +   evas_object_resize(img, 200, 200);
      +   evas_object_show(img);
      +
      +   // Create another image object
      +   Evas_Object *img2 = evas_object_image_filled_add(e);
      +   evas_object_image_file_set(img2, "./logo.png", NULL);
      +
      +   // Disable smooth scaling
      +   evas_object_image_smooth_scale_set(img2, EINA_FALSE);
      +   evas_object_move(img2, 200, 0);
      +   evas_object_resize(img2, 200, 200);
      +   evas_object_show(img2);
      +
      +   elm_run();
      +
      +   elm_shutdown();
      +
      +   return 0;
      +}
      +
      + + + + + + + + + + + + +
      Figure: Smooth scaling effects

      Smooth scaling effects

      Smooth scaling effects

      Smooth scaling enabledSmooth scaling disabled
      + + +

      Evas caches scaled image data and reuses them. Users can save the memory by loading the image in the scaled size to the memory at the beginning. This option is available only for jpeg format at the moment.

      +
      +void evas_object_image_load_size_set(Evas_Object *obj, int w, int h);
      + +

      An example code is as follows.

      +
      +#include <Elementary.h>
      + 
      +int main(int argc, char **argv)
      +{
      +   elm_init(argc, argv);
      + 
      +   // Create a window object
      +   Evas_Object *win = elm_win_add(NULL, "main", ELM_WIN_BASIC);
      +   evas_object_resize(win, 400, 200);
      +   evas_object_show(win);
      + 
      +   // Return Evas handle from window
      +   Evas *e = evas_object_evas_get(win);
      + 
      +   // Create an image object
      +   Evas_Object *img = evas_object_image_filled_add(e); 
      + 
      +   // Load the image scaled into the object size 
      +   // before evas_object_image_file_set() is called
      +   evas_object_image_load_size_set(img, 300, 300);
      + 
      +   evas_object_image_file_set(img, "./logo.png", NULL); 
      +   
      +   evas_object_move(img, 50, 50);
      +   evas_object_resize(img, 300, 300);
      +   evas_object_show(img); 
      + 
      +   elm_run();
      + 
      +   elm_shutdown();
      +
      +   return 0;
      +}
      +
      + +

      Setting Raw Data to Image Object

      +

      Users can set raw data to the image object manually using the evas_object_image_data_set() function instead of setting an image file as the data source. The image data should be in raw data form. In case of an 200x200 sized image with alpha channel enabled (32 bits per pixel), the size of the image data is 14000 (=200*200*4) bytes.

      + +
      void evas_object_image_data_set(Evas_Object *obj, void *data);
      + +

      Image objects fetch metadata such as width or height from the header of the image files. Since the raw data does not have the metadata, users must set the size of the image using the evas_object_image_size_set() function.

      + +
      void evas_object_image_size_set(Evas_Object *obj, int w, int h);
      + +

      The evas_object_image_data_get() function returns the data pointer of an image object and requires a parameter to determine whether the data is modified or not. If users pass EINA_TRUE for for_writing, Evas updates the image pixels in the next rendering cycle.

      + +
      void *evas_object_image_data_get(const Evas_Object *obj, Eina_Bool for_writing);
      + +

      The evas_object_image_data_update_add() helps to mark the updated area for rendering efficiency.

      + +
      void evas_object_image_data_update_add(Evas_Object *obj, int x, int y, int w, int h);
      + +

      The following example code and figure show how to specify the area to update.

      +
      +evas_object_image_data_update_add(image, 100, 100, 50, 50);
      +evas_object_image_data_update_add(image, 180, 100, 50, 50);
      +evas_object_image_data_update_add(image, 85, 200, 160, 80);
      +
      + +

      Figure: Partial image update

      +

      Partial image update

      + +

      The following code creates an image object and sets a source file on it. Then it implements the blur effect to the pixel data and saves them using the evas_object_image_save() function.

      + +
      Eina_Bool evas_object_image_save(const Evas_Object *obj, const char *file, const char *key, const char *flags);
      + +
      +#include <Elementary.h>
      +
      +void image_blur(Evas_Object *img)
      +{
      +   unsigned char *img_src = evas_object_image_data_get(img, EINA_TRUE);
      +
      +   int w, h;
      +   evas_object_image_size_get(img, &w, &h);
      +   int blur_size = 4;
      +   int x, y, xx, yy;
      +   
      +   for (y = 0; y < h; y++)
      +   {
      +      for (x = 0; x < w; x++)
      +      {
      +         int avg_color[3] = {0, 0, 0};
      +         int blur_pixel_cnt = 0;
      +
      +         for (xx = x; (xx < x + blur_size) && (xx < w); xx++)
      +         {
      +            for (yy = y; (yy < y + blur_size) && (yy < h); yy++)
      +            {
      +               int idx = (yy * w * 4) + (xx * 4);
      +               avg_color[0] += img_src[idx + 0];
      +               avg_color[1] += img_src[idx + 1];
      +               avg_color[2] += img_src[idx + 2];
      +               ++blur_pixel_cnt;
      +            }
      +         }
      +         avg_color[0] /= blur_pixel_cnt;
      +         avg_color[1] /= blur_pixel_cnt;
      +         avg_color[2] /= blur_pixel_cnt;
      +
      +         for (xx = x; (xx < x + blur_size) && (xx < w); xx++)
      +         {
      +            for (yy = y; (yy < y + blur_size) && (yy < h); yy++)
      +            {
      +               int idx = (yy * w * 4) + (xx * 4);
      +               img_src[idx + 0] = avg_color[0];
      +               img_src[idx + 1] = avg_color[1];
      +               img_src[idx + 2] = avg_color[2];
      +            }
      +         }
      +      }
      +   }
      +   evas_object_image_data_update_add(img, 0, 0, w, h);
      +}
      +
      +int main(int argc, char **argv)
      +{
      +   elm_init(argc, argv);
      +
      +   Evas_Object *win = elm_win_add(NULL, "main", ELM_WIN_BASIC);
      +   evas_object_resize(win, 200, 200);
      +   evas_object_show(win);
      +
      +   Evas *e = evas_object_evas_get(win);
      +
      +   Evas_Object *img = evas_object_image_filled_add(e);
      +   evas_object_image_file_set(img, "./logo.png", NULL);
      +   evas_object_resize(img, 200, 200);
      +   evas_object_show(img);
      +
      +   image_blur(img);
      +
      +   evas_object_image_save(img, "logo2.png", NULL, "quality=100 compress=8");
      +
      +   elm_run();
      +
      +   elm_shutdown();
      +
      +   return 0;
      +}
      +
      + + + + + + + + + + + + +
      Figure: Blur effect

      Blur effect

      Blur effect

      BeforeAfter
      + +

      Giving Performance Hints

      +

      In image viewer applications, you can display an image in full size. The navigation to the adjacent images on your album must be fluid and fast. Thus, while displaying a given image, the program can load the next and previous image in the background to be able to immediately repaint the screen with a new image.

      + +

      Evas addresses this issue with image preloading:

      + +
      +prev = evas_object_image_filled_add(canvas);
      +evas_object_image_file_set(prev, "/path/to/prev", NULL);
      +evas_object_image_preload(prev, EINA_TRUE);
      +next = evas_object_image_filled_add(canvas);
      +evas_object_image_file_set(next, "/path/to/next", NULL);
      +evas_object_image_preload(next, EINA_TRUE);
      +
      + +

      If you are loading an image which is too big, set its loading size smaller.

      + +

      Load a scaled down version of the image in the memory if that is the size you are displaying (this can speed up the loading considerably):

      +
      evas_object_image_load_scale_down_set(img, zoom);
      +

      If you know you are showing a sub-set of the image pixels, you can avoid loading the complementary data:

      +
      evas_object_image_load_region_set(img, x, y, w, h);
      +
      + +

      Specifying Borders

      +

      With Evas, you can specify image margins to be treated as borders. The margins then maintain their aspects when the image is resized. This makes setting frames around other UI objects easier. The following figure illustrates the border behavior, when the image is resized.

      + +

      Figure: Borders in Evas

      +

      Borders in Evas

      + + +

      Textblock Objects

      + +

      Unlike basic text objects, a textblock handles complex text, managing multiple styles and multiline text based on HTML-like tags. However, these extra features are heavier on memory and processing cost.

      +

      The textblock objects is an object that shows big chunks of text. Textblock supports many features, including text formatting, automatic and manual text alignment, embedding items (icons, for example). Textblock has three important parts: the text paragraphs, the format nodes and the cursors.

      +

      To set markup to format text, use for example <font_size=50>Big!</font_size>. Set more than one style directive in one tag with <font_size=50 color=#F00>Big and Red!</font_size>. Please note that we used </font_size> although the format also included color. This is because the first format determines the matching closing tag's name. You can use anonymous tags, such as <font_size=30>Big</>, which pop any type of format, but it is advisable to use the named alternatives instead.

      +

      Textblock supports the following formats:

      +
        +
      • font: Font description in fontconfig such as format, for example "Sans:style=Italic:lang=hi". or "Serif:style=Bold".
      • +
      • font_weight: Overrides the weight defined in "font". For example, "font_weight=Bold" is the same as "font=:style=Bold". The supported weights are "normal", "thin", "ultralight", "light", "book", "medium", "semibold", "bold", "ultrabold", "black", and "extrablack".
      • +
      • font_style: Overrides the style defined in "font". For example, "font_style=Italic" is the same as "font=:style=Italic". The supported styles are "normal", "oblique", and "italic".
      • +
      • font_width: Overrides the width defined in "font". For example, "font_width=Condensed" is the same as "font=:style=Condensed". The supported widths are "normal", "ultracondensed", "extracondensed", "condensed", "semicondensed", "semiexpanded", "expanded", "extraexpanded", and "ultraexpanded".
      • +
      • lang: Overrides the language defined in "font". For example, "lang=he" is the same as "font=:lang=he".
      • +
      • font_fallbacks: A comma delimited list of fonts to try if finding the main font fails.
      • +
      • font_size: The font size in points.
      • +
      • font_source: The source of the font, for example an eet file.
      • +
      • color: The text color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", or "#RGBA".
      • +
      • underline_color: The color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", or "#RGBA".
      • +
      • underline2_color: The color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", or "#RGBA".
      • +
      • outline_color: The color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", or "#RGBA".
      • +
      • shadow_color: The color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", or "#RGBA".
      • +
      • glow_color: The color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", or "#RGBA".
      • +
      • glow2_color: The color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", or "#RGBA".
      • +
      • strikethrough_color: The color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", or "#RGBA".
      • +
      • align: The text alignment in one of the following formats: "auto" (according to text direction), "left", "right", "center" or "middle", which take a value between 0.0 and 1.0 or a value between 0% to 100%.
      • +
      • valign: The vertical text alignment in one of the following formats: "top", "bottom", "middle", "center", "baseline" or "base", which take a value between 0.0 and 1.0 or a value between 0% to 100%.
      • +
      • wrap: The text wrap in one of the following formats: "word", "char", "mixed", or "none".
      • +
      • left_margin: Either "reset" or a pixel value indicating the margin.
      • +
      • right_margin: Either "reset" or a pixel value indicating the margin.
      • +
      • underline: The style of underlining in one of the following formats: "on", "off", "single", or "double".
      • +
      • strikethrough: The style of text that is either "on" or "off".
      • +
      • backing_color: The background color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", or "#RGBA".
      • +
      • backing: The background color enabled or disabled: "on" or "off".
      • +
      • style: The style of the text in one of the following formats: "off", "none", "plain", "shadow", "outline", "soft_outline", "outline_shadow", "outline_soft_shadow", "glow", "far_shadow", "soft_shadow" or "far_soft_shadow". The direction is selected by adding "bottom_right", "bottom", "bottom_left", "left", "top_left", "top", "top_right" or "right". For example, "style=shadow,bottom_right".
      • +
      • tabstops: The pixel value for tab width.
      • +
      • linesize: To force a line size in pixels.
      • +
      • linerelsize: Either a floating point value or a percentage indicating the wanted size of the line relative to the calculated size.
      • +
      • linegap: To force a line gap in pixels.
      • +
      • linerelgap: Either a floating point value or a percentage indicating the wanted size of the line relative to the calculated size.
      • +
      • item: Creates an empty space that is filled by an upper layer. Use "size", "abssize", or "relsize" to define the item"s size, and an optional vsize = full/ascent to define the item's position in the line.
      • +
      • linefill: Either a float value or percentage indicating how much to fill the line.
      • +
      • ellipsis: A value between 0.0 and 1.0 to indicate the type of ellipsis, or -1.0 to indicate that an ellipsis is not wanted.
      • +
      • password: Either "on" or "off", this is used to specifically turn replacing chars with the password mode (that is, replacement char) on and off.
      • +
      + + +

      Clipping Objects

      + +

      Limiting Visibility

      +

      An Evas object can be clipped – in other words, its visible area is restricted with the clipper object.

      + +

      It is often necessary to show only parts of an object, and while it may be possible to create an object that corresponds only to the part that must be shown (which is not always possible), it is usually easier to use a clipper. A clipper is a rectangle that defines what is visible and what is not. The way to do this is to create a solid white rectangle (by default, so you need not use evas_object_color_set()) and give it a position and size of what is wanted visible. The following code exemplifies showing the center half of my_evas_object:

      +
      Evas_Object *clipper = evas_object_rectangle_add(evas_canvas);
      +evas_object_move(clipper, my_evas_object_x / 4, my_evas_object_y / 4);
      +evas_object_resize(clipper, my_evas_object_width / 2, my_evas_object_height / 2);
      +evas_object_clip_set(my_evas_object, clipper);
      +evas_object_show(clipper);
      +
      + +

      Layer of Color

      +

      A solid white clipper does not produce a change in the color of the clipped object, only hides what is outside the clipper's area. Changing the color of an object is accomplished by using a colored clipper. Clippers with color function by multiplying the colors of the clipped object. The following code shows how to remove all the red from an object.

      +
      Evas_Object *clipper = evas_object_rectangle_add(evas);
      +evas_object_move(clipper, my_evas_object_x, my_evas_object_y);
      +evas_object_resize(clipper, my_evas_object_width, my_evas_object_height);
      +evas_object_color_set(clipper, 0, 255, 255, 255);
      +evas_object_clip_set(obj, clipper);
      +evas_object_show(clipper);
      +
      + + +

      Mapping Objects

      + +

      Evas allows different transformations to be applied to all kinds of objects. These are applied by means of UV mapping. With UV mapping, one map points in the source object to a 3D space positioning at target. This allows rotation, perspective, scale, and many other effects depending on the map that is used.

      + +

      Creating a Map

      +

      A map consists of a set of points, but currently only four are supported. Each of these points contains a set of canvas coordinates x and y that are used to alter the geometry of the mapped object, and a z coordinate that indicates the depth of that point. This last coordinate does not normally affect the map, but is used by several of the utility functions to calculate the right position of the point given other parameters.

      +

      The coordinates for each point are set with evas_map_point_coord_set(map, index, x, y, z). In the example below, there is a rectangle whose coordinates are (100, 100) and (300, 300).

      +
      Evas_Object *object = evas_object_rectangle_add(evas);
      +evas_object_move(object, 100, 100);
      +evas_object_resize(object, 200, 200);
      +Evas_Map map = evas_map_new(4);
      +evas_map_point_coord_set(map, 0, 100, 100, 0);
      +evas_map_point_coord_set(map, 1, 300, 100, 0);
      +evas_map_point_coord_set(map, 2, 300, 300, 0);
      +evas_map_point_coord_set(map, 3, 100, 300, 0);
      +
      +

      There are functions to ease the process.

      +

      Use evas_map_util_points_populate_from_geometry(map, x, y, w, h, z), where the map coordinates are set to the given rectangle, and z is the coordinate in the Z axis, which is the same for all points.

      +
      Evas_Object *object = evas_object_rectangle_add(evas);
      +evas_object_move(object, 100, 100);
      +evas_object_resize(object, 200, 200);
      +Evas_Map map = evas_map_new(4);
      +evas_map_util_points_populate_from_geometry(map, 100, 100, 200, 200, 0);
      +
      + +

      You can also use evas_map_util_points_populate_from_object(map, object).

      +
      Evas_Object *object = evas_object_rectangle_add(evas);
      +evas_object_move(object, 100, 100);
      +evas_object_resize(object, 200, 200);
      +Evas_Map map = evas_map_new(4);
      +evas_map_util_points_populate_from_object(map, object);
      +
      + +

      You can also use evas_map_util_points_populate_from_object_full(map, object, z), where z is the coordinate in the Z axis, which is the same for all points.

      +
      Evas_Object *object = evas_object_rectangle_add(evas);
      +evas_object_move(object, 100, 100);
      +evas_object_resize(object, 200, 200);
      +Evas_Map map = evas_map_new(4);
      +evas_map_util_points_populate_from_object_full(map, object, 0);
      +
      + +

      Manual Point Setting

      +

      Several effects are applied to an object by setting each point of the map to the right coordinates. For example, a simulated perspective is achieved as follows.

      +
      evas_map_point_coord_set(map, 0, 300, 100, 0);
      +evas_map_point_coord_set(map, 1, 450, 120, 0);
      +evas_map_point_coord_set(map, 2, 450, 260, 0);
      +evas_map_point_coord_set(map, 3, 300, 300, 0);
      +
      + +

      The Z coordinate is not used when setting points by hand; thus its value is not important.

      + +

      Applying a Map

      +

      Regardless of the specific way you create a map, to apply it to a specific object, use

      +
      evas_object_map_set(object, map);
      +evas_object_map_enable_set(object, EINA_TRUE);
      +
      + +

      Basic Utility Functions

      +

      Evas provides utility functions for common transformations:

      +
        +
      • evas_map_util_rotate(map, angle, cx, cy): This performs a rotation of the angle degrees around the center point with the coordinates (cx, cy).
      • +
      • evas_map_util_zoom(map, zoomx, zoomy, cx, cy): This performs a zoomx and zoomy zoom in the X and Y directions respectively, with the center point with the coordinates (cx, cy).
      • +
      + +

      For example, the following code rotates an object around its center.

      +
      int x, y, w, h;
      +evas_object_geometry_get(object, &x, &y, &w, &h);
      +Evas_Map *map = evas_map_new(4);
      +evas_map_util_points_populate_from_object(map, object);
      +evas_map_util_rotate(map, 45, x + (w / 2), y + (h / 2));
      +evas_object_map_set(object, map);
      +evas_object_map_enable_set(object, EINA_TRUE);
      +evas_map_free(m);
      +
      + +

      The following code rotates an object around the center of the window.

      +
      int w, h;
      +evas_output_size_get(evas, &w, &h);
      +Evas_Map *map = evas_map_new(4);
      +evas_map_util_points_populate_from_object(map, object);
      +evas_map_util_rotate(map, 45, w / 2, h / 2);
      +evas_object_map_set(object, map);
      +evas_object_map_enable_set(object, EINA_TRUE);
      +evas_map_free(m);
      +
      + +

      3D Utility Functions

      +

      Evas provides utility functions for 3D transformations.

      +

      To make a 3D rotation, use evas_map_util_3d_rotate(map, anglex, angley, anglez, cx, cy, cz). With this code, you can set the Z coordinate of the rotation center, and the angles to rotate through around all axes.

      +

      Rotating in the 3D space does not look natural. A more natural look becomes by adding perspective to the transformation, which is done with evas_map_util_3d_perspective(map, px, py, z0, focal) on the map after its position has been set.

      + +
        +
      • px and py specify the "infinite distance" point in the 3D conversion, where all lines converge to.
      • +
      • z0 specifies the Z value at which there is a 1:1 mapping between spatial coordinates and screen coordinates: any points on this Z value do not have their X and Y coordinates modified in the transform, while those further away (Z value higher) shrink into the distance, and those less than this value expand.
      • +
      • focal determines the "focal length" of the camera: this is the distance in reality between the camera lens plane (the rendering results are undefined at or closer than this) and the z0 value; this function allows for some "depth" control.
      • +
      +

      Color and Lighting

      +

      Each point in a map can be set to a color, which is multiplied with the object's own color and linearly interpolated in between adjacent points. To do this, use evas_map_point_color_set(map, index, r, g, b, a) for each point of the map, or evas_map_util_points_color_set(map, r, g, b, a) to set every point into the same color.

      +

      To add lighting for the objects, which is useful with 3D transforms, use evas_map_util_3d_lighting(map, lightx, lighty, lightz, lightr, lightg, lightb, ambientr, ambientg, ambientb):

      +
        +
      • lightx, lighty and lightz are the local light source coordinates;
      • +
      • lightr, lightg and lightb are the local light source colors;
      • +
      • ambientr, ambientg and ambientb are the ambient light colors. Evas sets the color of each point based on the distance to the light source, the angle with which the object is facing the light and the ambient light. The orientation of each point is important. If the map is defined counter-clockwise, the object faces away from the user and becomes obscured, since no light does not reflect from it.
      • +
      + + + + + + + + + + +
      Note
      Except as noted, this content is licensed under LGPLv2.1+.
      + + + +
      + +Go to top + + + + + + + \ No newline at end of file diff --git a/org.tizen.ui.guides/html/native/efl/evas_optimization_n.htm b/org.tizen.ui.guides/html/native/efl/evas_optimization_n.htm new file mode 100755 index 0000000..622b72f --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/evas_optimization_n.htm @@ -0,0 +1,227 @@ + + + + + + + + + + + + + + Optimizing Evas + + + + + + +
      +

      Optimizing Evas

      + +

      To optimize Evas:

      + + + +

      Using a Rectangle Object instead of a Solid Color Image

      +

      When you need a solid color object, it is better (more efficient) to use a rectangle object than the image.

      + + + + + + + + + + + + + + + + + + +
      Before
      +
      +image = elm_image_add(win);
      +snprintf(buf, sizeof(buf), "%s/images/white_bg.png", elm_app_data_dir_get()); 
      +elm_image_file_set(image, buf, NULL);
      +evas_object_size_hint_weight_set(image, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +elm_win_resize_object_add(win, image);
      +evas_object_show(image);
      +
      After
      +
      +rect = evas_object_rectangle_add(evas_object_evas_get(win));
      +evas_object_color_set(rect, 255, 255, 255, 255);
      +evas_object_size_hint_weight_set(rect, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +elm_win_resize_object_add(win, rect);
      +evas_object_show(rect);
      +
      + + +

      Making an Object Invisible instead of Setting Alpha as 0

      + +

      To make an object invisible, it is more efficient to use evas_object_hide() instead of changing the alpha value to 0.

      + + + + + + + + + + + + + + + +
      BeforeAfter
      +
      +static void
      +_invisible_cb(void *data, Evas_Object *obj, void *ev)
      +{
      +   evas_object_color_set(obj, 0, 0, 0, 0);   
      +}
      +
      +
      +static void
      +_invisible_cb(void *data, Evas_Object *obj, void *ev)
      +{
      +   evas_object_hide(obj);   
      +}
      +
      + +

      Using evas_object_image for Maximum Optimization

      + +

      If you need maximum optimization, use evas_object_image instead of elm_image and elm_icon.

      + + + + + + + + + + + + + + + + + + +
      Before
      +
      +img = elm_image_add((parent);
      +snprintf(buf, sizeof(buf), "%s/images/white_bg.png", elm_app_data_dir_get()); 
      +elm_image_file_set(img, buf, NULL);
      +evas_object_size_hint_weight_set(img, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +evas_object_size_hint_align_set(img, EVAS_HINT_FILL, EVAS_HINT_FILL);
      +evas_object_show(img);
      +
      After
      +
      +img = evas_object_image_add(evas_object_evas_get(parent));
      +snprintf(buf, sizeof(buf), "%s/images/white_bg.png", elm_app_data_dir_get()); 
      +evas_object_image_file_set(img, buf, NULL);
      +evas_object_image_filled_set(img, EINA_TRUE);
      +evas_object_size_hint_weight_set(img, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +evas_object_size_hint_align_set(img, EVAS_HINT_FILL, EVAS_HINT_FILL);
      +evas_object_show(img);
      +
      + + +

      Setting the Parent to Avoid the Elementary Tree Reconstruction

      +

      Before creating an object, make sure that the relationship between parent and child is set correctly to avoid having to reconstruct later.

      + + + + + + + + + + + + + + + +
      BeforeAfter
      +
      +win = elm_win_add();
      +
      +scroller = elm_scroller_add(win);
      +
      +box = elm_box_add(win);
      +
      +button = elm_button_add(win);
      +
      +
      +win = elm_win_add();
      +
      +scroller = elm_scroller_add(win);
      +
      +box = elm_box_add(scroller);
      +
      +button = elm_button_add(box);
      +
      + + + + + +
      + +Go to top + + + + + + + \ No newline at end of file diff --git a/org.tizen.ui.guides/html/native/efl/evas_rendering_n.htm b/org.tizen.ui.guides/html/native/efl/evas_rendering_n.htm new file mode 100755 index 0000000..e265bf6 --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/evas_rendering_n.htm @@ -0,0 +1,288 @@ + + + + + + + + + + + + + Evas Rendering Concept and Method + + + + + +
      + +

      Evas Rendering Concept and Method

      + +

      Evas is a canvas display library. It is markedly different from most display and windowing systems as the canvas is structural and is also a state engine, whereas most display and windowing systems are immediate mode display targets. Evas handles the logic between a structural display via its state engine, and controls the target windowing system in order to produce rendered results of the current canvas' state on the display.

      +

      Immediate mode display systems retain very little or no state. A program executes a series of commands, as in the following pseudo code.

      +
      +draw line from position (0, 0) to position (100, 200);
      +
      +draw rectangle from position (10, 30) to position (50, 500);
      +
      +bitmap_handle = create_bitmap();
      +scale bitmap_handle to size 100 x 100;
      +draw image bitmap_handle at position (10, 30);
      +
      +

      The series of commands is executed by the windowing system and the results are typically displayed on the screen. Once the commands are executed, the display system does not know how to reproduce this image again, and has to be instructed by the application on how to redraw sections of the screen if needed. Each successive command is executed as instructed by the application and either emulated by software or sent to the graphics hardware on the device to be performed.

      +

      The advantage of such a system is that it is simple and gives a program tight control over how something looks and is drawn. Given the increasing complexity of displays and demands by users to have better looking interfaces, more work needs to be done at this level by the internals of UI component sets, custom display components and other programs. This means that more logic and display rendering code needs to be written again each time the application needs to figure out how to minimize redraws so that display is fast and interactive, and keep track of redraw logic.

      +

      For example, if in the scene below, the windowing system requires the application to redraw the area from 0, 0 to 50, 50 (also referred to as the "expose event"). Then the programmer calculates manually the updates and repaints it again.

      +
      +Redraw from position (0, 0) to position (50, 50):
      +
      +// What was in area (0, 0, 50, 50)?
      +
      +// 1. intersection part of line (0, 0) to (100, 200)?
      +   draw line from position (0, 0) to position (25, 50);
      +
      +// 2. intersection part of rectangle (10, 30) to (50, 500)?
      +   draw rectangle from position (10, 30) to position (50, 50)
      +
      +// 3. intersection part of image at (10, 30), size 100 x 100?
      +   bitmap_subimage = subregion from position (0, 0) to position (40, 20)
      +   draw image bitmap_subimage at position (10, 30);
      +
      + +

      If all elements in the above scene are opaque, the system is doing useless paints: part of the line is behind the rectangle, and part of the rectangle is behind the image. These useless paints tend to be very costly.

      +

      Evas is a structural system in which the programmer creates and manages display objects and their properties, and as a result of this higher level state management, the canvas is able to redraw the set of objects when needed to represent the current state of the canvas.

      +

      For example, see the following pseudo code.

      +
      +line_handle = create_line();
      +set line_handle from position (0, 0) to position (100, 200);
      +show line_handle;
      +
      +rectangle_handle = create_rectangle();
      +move rectangle_handle to position (10, 30);
      +resize rectangle_handle to size 40 x 470;
      +show rectangle_handle;
      +
      +bitmap_handle = create_bitmap();
      +scale bitmap_handle to size 100 x 100;
      +move bitmap_handle to position (10, 30);
      +show bitmap_handle;
      +
      +render scene;
      +
      + +

      This looks longer, but when the display needs to be refreshed or updated, the programmer only moves, resizes, shows, hides etc. the objects that need to change. The programmer thinks at the object logic level, and the canvas software does the rest of the work, figuring out what changed in the canvas since it was last drawn, how to most efficiently redraw the canvas and its contents to reflect the current state, and doing the actual drawing of the canvas.

      +

      This allows the programmer think in a more natural way when dealing with a display, and saves time and effort of working out how to load and display images, to render given the current display system etc. Since Evas is portable across different display systems, this gives the programmer the ability to port and display the code on different display systems with little work.

      +

      Evas is a display system somewhere between a UI component set and an immediate mode display system. It retains basic display logic, but does little high-level logic such as scrollbars, sliders, push buttons etc.

      + +

      For more information on the UI rendering modes (immediate and retained), see UI Rendering Mode.

      + + +

      Evas Engines Concept

      +

      Evas delegates most of the actual rendering work to its engines. Engines are the backends that Evas uses to render (primitive) objects on a canvas. The canvas can be the screen, or a buffer in the memory.

      +

      Evas can work with and provides multiple engines, such as (this list is non-exhaustive):

      +
        +
      • buffer: all the rendering takes place in a buffer
      • +
      • fb: the rendering takes place in the system's framebuffer
      • +
      • software_x11: this is the most used, using X11
      • +
      • gl_x11: this also renders to an X11 window, except that it uses OpenGL
      • +
      +

      These implement the rendering of all the basic objects by themselves, because they often can be accelerated by the hardware or backend software libraries to provide fast rendering.

      +

      If a particular engine does not have the provision for a certain primitive object, it reverts back to using a default software version.

      + +

      UI Rendering Mode

      + +

      Evas removes the need to know about the characteristics of your display system or what graphics calls are used to draw them and how. It deals on an object level where all you do is create and manipulate objects in a canvas, set their properties, and the rest is done for you. This rendering method is called the retained mode, whereas the immediate mode is an alternative rendering method.

      + +

      Immediate Mode

      + +

      The immediate mode is the most commonly used in graphics toolkit libraries, such as GTK+, GDI, and GDI+. The application is responsible for repainting the portion of the client area that is invalidated.

      + +

      Figure: Immediate mode

      +

      Immediate mode

      + +

      The application commands any drawing issues as it needs, and the display system draws some GUIs. After the drawing is done, it appears in the destination. This mode allows you to have a exact control over the render cycles. However, if the draw commands are misused, unnecessary drawing can be performed or drawing never happen at all.

      +

      The following example explains the common usage of the immediate mode:

      + +
      +void update()
      +{
      +   Image *img = load_image(NEW_IMG);
      +
      +   // Switch button image to new one
      +   update_button_image(img);
      +
      +   // Issue the invalidate area (button area) to be redrawn on the screen
      +   invalidate_area(button_x, button_y, button_w, button_h);
      +
      +   // Move rectangle from (200, 200) to (300, 300)
      +   int rect_prev_x = rect_x;
      +   int rect_prev_y = rect_y;
      +   rectangle_x = 300;
      +   rectangle_y = 300;
      +   set_rect_position(rect_x, rect_y);
      +   
      +   // Issue the invalidate area (changed area) to be redrawn on the screen
      +   int diff_x = rect_x – rect_prev_x;
      +   int diff_y = rect_y – rect_prev_y;
      +   invalidate_area(rect_prev_x, rect_prev_y, (rect_w + diff_x), (rect_h + diff_y));
      +
      +
      +   // After setting the invalidate area, request rendering to update the screen
      +   render();
      +
      +   // Now you can see how the button image and rectangle position are changed
      +}
      +
      + +

      Retained Mode

      + +

      A graphics system adopting the retained mode is basically responsible for responding to all repaint requests for rendering the application objects. Clients do not directly cause actual rendering, but objects are redrawn when parts of them are updated.

      + +

      Figure: Retained mode

      +

      Retained mode

      + +

      Since Evas works with the retained mode, there is no need to command any drawings. The following example shows how to write a GUI code with Evas for your application:

      + +
      +void create_image()
      +{
      +   // Initialize an image object to be displayed on the screen
      +   Evas_Object *img = evas_object_image_add(e);
      +
      +   // Set image resource
      +   evas_object_image_file_set(img, IMG, NULL);
      +
      +   // Set image position 
      +   evas_object_move(img, 100, 100);
      +
      +   // Set image size
      +   evas_object_resize(img, 200, 200);
      +
      +   // Set image visibility (show or hide)
      +   evas_object_show(img);
      +}
      +
      +void create_rectangle()
      +{
      +   // Initialize an rectangle object to be displayed on the screen
      +   Evas_Object *rect = evas_object_rectangle_add(e);
      +
      +   // Set rectangle color
      +   evas_object_color_set(rect, 255, 0, 0, 255);
      +
      +   // Set rectangle position
      +   evas_object_move(rect, 200, 200);
      +
      +   // Set rectangle size
      +   evas_object_resize(rect, 200, 200);
      +
      +   // Set rectangle visibility (show or hide)
      +   evas_object_show(rect);
      +}
      +
      + +

      A few main loops later you can replace the image with another one and move the rectangle. You only need to set a new image file to the image object and move the rectangle object. Evas computes the invalidate area and redraws the image and rectangle behind the application when it's on rendering time.

      + +
      +void update()
      +{
      +   // Set new image resource
      +   elm_image_file_set(img, NEW_IMG, NULL);
      +
      +   // Set new rectangle position
      +   evas_object_move(rect, 300, 300);
      +}
      +
      + +

      Evas Rendering

      + +

      Tizen Native applications work on the ecore main loop, and the loop goes on a few steps for every frame. Evas redraws some changes in the objects when the main loop goes to the idle enterer step. If there are no changes, Evas rendering is skipped. Otherwise, Evas calculates any changed portions of all display objects and redraws them.

      + +

      Figure: Evas rendering in the main loop

      +

      Evas rendering in the main loop

      + +

      To minimize the rendering, Evas tracks the states of all display objects, such as position, size, visibility, and color. Even if some of these states are changed but the object is hidden by other obscured objects, it is not redrawn. In other words, Evas draws only the necessary changes in the screen.

      + +

      The following figures illustrate how Evas redraws the changed area:

      + +
      • In the first example, there is a blue-color background object (a sky-blue color rectangle) and a partially hidden cloud image object. Above them, there are a red and green rectangle, and the "Hello out there" text is printed on the green rectangle.

        + +

        Figure: Evas redrawing example 1

        +

        Evas redrawing example 1

      • + +
      • In the second example, some of the objects have moved (the cloud image is moved to right and the green rectangle is moved downwards).

        + +

        Figure: Evas redrawing example 2

        +

        Evas redrawing example 2

      • + +
      • As a result, the third example illustrates some regions that require updates.

        + +

        Figure: Evas redrawing example 3

        +

        Evas redrawing example 3

      • + +
      • Evas decides which portions are invalid and to be redrawn. The fourth example shows the cleaned portion of the screen, which is the redrawn area.

        +

        Evas redraws the content only in the redrawn portions.

        +

        Figure: Evas redrawing example 4

        +

        Evas redrawing example 4

      • + +
      • Finally, the fifth example shows how the screen is updated and the result is visible.

        + +

        Figure: Evas redrawing example 5

        +

        Evas redrawing example 5

        + +

        If Evas worked in an immediate mode style, the application would need to calculate the changed areas themselves, adding extra work. With Evas, you can let Evas figure out the updates and you can yourself concentrate on the application and UI core and logic.

      + + + + + + + + + + +
      Note
      Except as noted, this content is licensed under LGPLv2.1+.
      + + + +
      + +Go to top + + + + + + + \ No newline at end of file diff --git a/org.tizen.ui.guides/html/native/efl/event_handling_n.htm b/org.tizen.ui.guides/html/native/efl/event_handling_n.htm new file mode 100755 index 0000000..03dc326 --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/event_handling_n.htm @@ -0,0 +1,119 @@ + + + + + + + + + + + + + Event Handling: Managing the Event Flow + + + + + +
      + +

      Event Handling: Managing the Event Flow

      + +

      The EFLs rely on events and callbacks. In case of an event, (for example, a key press, mouse click or a battery running low), the mainloop calls the callback functions that are associated to that specific event. After the callbacks have finished, the mainloop takes over and waits for new events, upon which to trigger new callbacks.

      +

      It is important to do light work in the callbacks and to return to the mainloop relatively quickly. If there is heavy work to do, it is best to use an asynchronous mechanism like Ecore_con for network I/O or threads for CPU-intensive tasks. Failure to return quickly to the mainloop blocks the application's UI and it appears frozen.

      + +

      EFL Event Types

      +

      There are several event types in the EFLs, and their use depends on the level of the event. The event types from lower- to higher-level are:

      +
        +
      • Evas smart events are the most often used and take place on collections of evas objects (which are most typically handled). They are called "smart" because they have internal logic and can define their own events while other event types are fixed.
      • +
      • Ecore events are the lowest-level events and come directly from the system. Except for application-wide shortcuts, it is not advisable to use them.
      • +
      • Evas object events concern the objects that are on the canvas.
      • +
      • Evas events are events on the graphical canvas as a whole. They are fairly low-level and mostly useful when drawing directly on the canvas.
      • +
      + +

      Figure: Event types in the EFLs: Inner boxes are more specific than outer ones

      +

      Event types in the EFLs: Inner boxes are more specific than outer ones

      + + + + + + + + + + + + +
      Note
      There are also Edje signals, which come from program sections in themes; they can be used from high-level Elementary APIs or a low-level Edje API.
      + +

      Basic Event Flow

      +

      A realistic scenario involving various types of events is an application showing a button, which triggers the download of a file to be processed. There are progress bars for the operations.

      +

      Create the window, create a box, set it vertical and add a button and two progress bars. At first, only the button is fully visible.

      +

      When the user clicks on the button, an evas smart object event named "clicked" is emitted. The callback then starts the download in Ecore_con, displays the first progress bar and adds a callback to monitor the download progress. When the download progress changes, the callback updates the progress bar.

      +

      After the download is finished, the second progress bar is displayed and the file processing is offloaded to another thread through Ecore_thread. The processing function regularly updates the progress bar (wrapped in ecore_main_loop_thread_safe_call_async() because GUI operations are not thread-safe).

      +

      Events enable operations taking more than a few milliseconds' time to be executed outside of the mainloop, therefore not blocking UI redraws.

      +

      Below is an illustration for the event flow that follows a click on the screen.

      + +

      Figure: Event flow for a user click

      +

      Event flow for a user click

      + + + + + + + + + + + +
      Note
      Except as noted, this content is licensed under LGPLv2.1+.
      + + + +
      + +Go to top + + + + + + + \ No newline at end of file diff --git a/org.tizen.ui.guides/html/native/efl/event_types_n.htm b/org.tizen.ui.guides/html/native/efl/event_types_n.htm new file mode 100755 index 0000000..31182d5 --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/event_types_n.htm @@ -0,0 +1,461 @@ + + + + + + + + + + + + + Event Types + + + + + +
      + +

      Event Types

      + +

      EFL provides various event types that you can use to monitor and react to user interactions and system events in the UI.

      + +

      Ecore Events

      + +

      Ecore events are used for low-level handling of events, such as key presses, network connections, and communication with sub-processes. In case of shortcuts, the low-level handling of key presses is particularly useful: instead of adding a signal handler to a specific graphical element, you can add one globally to guarantee that no matter which UI component is currently receiving events, the shortcut is caught correctly.

      +

      Ecore events can also be used to implement new graphical back-ends. However, they are low-level and not useful for most applications.

      + +

      In addition to using predefined Ecore events, you can create your own events with the ecore_event_type_new() function. The function generates a new unique identifier, which you can use as the event type parameter when managing your events and event handlers.

      + + +

      Shortcut Events

      + +

      The following Ecore events are available for shortcuts. The event callbacks receive additional data through a void * object, whose type depends on the received event.

      + +
        +
      • ECORE_EVENT_KEY_DOWN and ECORE_EVENT_KEY_UP events: +
        +typedef struct _Ecore_Event_Key Ecore_Event_Key;
        +
        +struct _Ecore_Event_Key 
        +{
        +   const char *keyname;
        +   const char *key;
        +   const char *string;
        +   const char *compose;
        +   Ecore_Window window;
        +   Ecore_Window root_window;
        +   Ecore_Window event_window;
        +
        +   unsigned int timestamp;
        +   unsigned int modifiers;
        +
        +   int same_screen;
        +};
        +
        + +
      • + +
      • ECORE_EVENT_MOUSE_BUTTON_DOWN and ECORE_EVENT_MOUSE_BUTTON_UP events: +
        typedef struct _Ecore_Event_Mouse_Button Ecore_Event_Mouse_Button;
        +struct _Ecore_Event_Mouse_Button 
        +{
        +   Ecore_Window window;
        +   Ecore_Window root_window;
        +   Ecore_Window event_window;
        +
        +   unsigned int timestamp;
        +   unsigned int modifiers;
        +   unsigned int buttons;
        +   unsigned int double_click;
        +   unsigned int triple_click;
        +   int same_screen;
        +
        +   int x;
        +   int y;
        +   struct 
        +   {
        +      int x;
        +      int y;
        +   } root;
        +
        +   struct 
        +   {
        +      // 0 if normal mouse, 1+ for other mouse-devices (such as multi-touch - other fingers)
        +      int device; 
        +      // Radius of press point - radius_x and radius_y if it is an ellipse (radius is the average of the 2)
        +      double radius, radius_x, radius_y; 
        +      // Pressure - 1.0 == normal, > 1.0 == more, 0.0 == none
        +      double pressure; 
        +      // Angle relative to perpendicular (0.0 == perpendicular), in degrees
        +      double angle; 
        +      // Same as x, y, root.x, root.y, but with sub-pixel precision, if available
        +      double x, y; 
        +      struct 
        +      {
        +         double x;
        +         double y;
        +      } root;
        +   } multi;
        +};
        +
        + +
      • +
      • ECORE_EVENT_MOUSE_MOVE and ECORE_EVENT_MOUSE_WHEEL events: +
        +typedef struct _Ecore_Event_Mouse_Wheel Ecore_Event_Mouse_Wheel;
        +struct _Ecore_Event_Mouse_Wheel 
        +{
        +   Ecore_Window window;
        +   Ecore_Window root_window;
        +   Ecore_Window event_window;
        +
        +   unsigned int timestamp;
        +   unsigned int modifiers;
        +
        +   int same_screen;
        +   int direction;
        +   int z;
        +
        +   int x;
        +   int y;
        +   struct 
        +   {
        +      int x;
        +      int y;
        +   } root;
        +};
        +
        +
      • +
      • ECORE_EVENT_MOUSE_IN and ECORE_EVENT_MOUSE_OUT events: +
        +typedef struct _Ecore_Event_Mouse_Move Ecore_Event_Mouse_Move;
        +struct _Ecore_Event_Mouse_Move 
        +{
        +   Ecore_Window window;
        +   Ecore_Window root_window;
        +   Ecore_Window event_window;
        +
        +   unsigned int timestamp;
        +   unsigned int modifiers;
        +
        +   int same_screen;
        +
        +   int x;
        +   int y;
        +   struct 
        +   {
        +      int x;
        +      int y;
        +   } root;
        +
        +   struct 
        +   {
        +      // 0 if normal mouse, 1+ for other mouse-devices (such as multi-touch - other fingers)
        +      int device; 
        +      // Radius of press point - radius_x and radius_y if it is an ellipse (radius is the average of the 2)
        +      double radius, radius_x, radius_y; 
        +      // Pressure - 1.0 == normal, > 1.0 == more, 0.0 == none
        +      double pressure; 
        +      // Angle relative to perpendicular (0.0 == perpendicular), in degrees
        +      double angle; 
        +      // Same as x, y, root.x, root.y, but with sub-pixel precision, if available
        +      double x, y; 
        +      struct 
        +      {
        +         double x, y;
        +      } root;
        +   } multi;
        +};
        +
        + +
      • +
      +

      Managing Ecore Event Handlers

      + +

      To manage Ecore event handlers:

      + +
      1. To add an Ecore event handler, register a callback for a specific event with the ecore_event_handler_add() function. +

        The function takes as parameters the event type (such as ECORE_EVENT_KEY_DOWN for key presses), callback function, and additional data delivered to the callback. The function returns an event handler pointer, which you can use to remove the handler later.

      2. + +
      3. Define the Ecore_Event_Handler_Cb() callback function. +

        The function takes as parameters the additional data defined in the ecore_event_handler_add() function parameters, the event type, and the event object (Ecore_Event_Key, Ecore_Event_Mouse_Button, Ecore_Event_Mouse_Wheel, or Ecore_Event_Mouse_Move). The function returns ECORE_CALLBACK_PASS_ON to allow other callbacks for that event be called, or ECORE_CALLBACK_DONE to not call them.

      4. + +
      5. When no longer needed, remove the event handler with the ecore_event_handler_del() function, using the event handler pointer as a parameter.
      + +

      The following example shows how you can set a global variable to EINA_TRUE when the Ctrl key is pressed:

      +
      +Eina_Bool ctrl_pressed = EINA_FALSE;
      +
      +static Eina_Bool
      +_key_down_cb(void *data __UNUSED__, int type __UNUSED__, void *ev)
      +{
      +   // The callback is used with the ECORE_EVENT_KEY_DOWN signal: the
      +   // parameter "void *ev" is therefore of the actual type Ecore_Event_Key
      +   // The following renders its fields accessible
      +   Ecore_Event_Key *event = ev;
      +
      +   // Test whether the key that is pressed is Ctrl.
      +   if (!strcmp("Control_L", event->key))
      +   {
      +      // If it is, store that piece of information
      +      ctrl_pressed = EINA_TRUE;
      +   }
      +
      +   // Let the event continue to other callbacks which have not been called yet
      +   return ECORE_CALLBACK_PASS_ON;
      +}
      +
      +ecore_event_handler_add(ECORE_EVENT_KEY_DOWN, _key_down_cb, NULL);
      +
      + +

      Sending Ecore Events to the Main Loop

      + +

      You can send Ecore events to the main loop yourself to handle actions of various origins through the same codepath. This is a thread-safe operation.

      +

      To send an event, use the ecore_event_add() function. The function takes as parameters the event type (such as ECORE_EVENT_KEY_DOWN for key presses), additional data delivered to the callback, the Ecore_End_Cb() function used to free the additional data after it is deliver to the callback function, and the pointer to additional data delivered to the free function. The free function and the pointer to its additional data are optional; use NULL if you do not need them.

      + + +

      Edje Events

      + +

      Edje themes have small program sections, which are triggered upon the reception of a signal that can execute actions, such as changing the state of an Edje part and running another program.

      + +

      Managing a Single Signal Emitter

      +

      The following example shoes a program section. The program is called "change_color", it is triggered on mouse clicks on the current part, and it emits a "got.a.click" signal where the source is set to "color_changer".

      +
      program 
      +{
      +   name: "change_color";
      +   signal: "mouse,clicked,*";
      +   source: "*";
      +   action: SIGNAL_EMIT "got.a.click" "color_changer";
      +}
      +
      + +

      To catch the emitted signal from the C side, use either the edje_object_signal_callback_add() or elm_object_signal_callback_add() function. Their only difference is that the previous one operates on an Edje object and the latter one on an Elementary object. Unless you do not use the Elementary library at all, use the Elementary variant.

      + +

      Both the functions take as parameters the object emitting the signal, the signal name ("*" acts as a wildcard), the signal source, the Edje_Signal_Cb() callback function called when the signal name and source match, and additional data delivered to the callback. For the signal name and source, "*" acts as a wildcard. The additional data is optional; use NULL if you do not need it.

      + +

      The callback function takes as parameters the additional data defined in the edje_object_signal_callback_add() or elm_object_signal_callback_add() function parameters, the object emitting the signal, the signal name, and the signal source.

      + + +

      Managing Multiple Signal Emitters in Layouts

      + +

      Most of the time, Edje and Elementary are used together. In particular, you can define a group in Edje and use it as a layout (containing several parts) in Elementary. The layouts enable you to perform theming and object placement in Edje while benefiting from the higher-level functions of Elementary.

      +

      Since the layout contains multiple parts, you cannot use the elm_object_signal_callback_add() and edje_object_signal_callback_add() functions, as they require a single emitter object. The solution is to use the dedicated elm_layout_signal_callback_add() function.

      + +

      The elm_layout_signal_callback_add() function works similarly as the elm_object_signal_callback_add() and edje_object_signal_callback_add() functions. The only difference is the type of the object in the first parameter. For elm_layout_signal_callback_add(), it is a pointer to an Evas_Object, which is obtained through the elm_layout_add() function. For more information, see Layout.

      + + +

      Evas Events

      + +

      Evas events happen on a canvas as a whole. These events are too low-level for writing applications and are mostly used when writing the graphical toolkit itself.

      + +

      The following Evas event types are available:

      + +
        +
      • EVAS_CALLBACK_RENDER_FLUSH_PRE: Rendering on the canvas is about to be updated.
      • +
      • EVAS_CALLBACK_RENDER_FLUSH_POST: Rendering on the canvas is updated.
      • +
      • EVAS_CALLBACK_CANVAS_FOCUS_IN: Canvas receives focus.
      • +
      • EVAS_CALLBACK_CANVAS_FOCUS_OUT: Canvas loses focus.
      • +
      • EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_IN: Any object on the canvas receives focus. +

        Instead of this event type, use the EVAS_CALLBACK_FOCUS_IN type with the evas_object_event_callback_add() function.

      • +
      • EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_OUT: Any object on the canvas loses focus. +

        Instead of this event type, use the EVAS_CALLBACK_FOCUS_OUT type with the evas_object_event_callback_add() function.

      • +
      • EVAS_CALLBACK_RENDER_PRE: Rendering on the canvas starts.
      • +
      • EVAS_CALLBACK_RENDER_POST: Rendering on the canvas finishes.
      • +
      + +

      To register the event handler, use the evas_event_callback_add() function. The function takes as parameters the Evas canvas on which the event happens (to obtain the canvas, use the Evas_Object through the evas_object_evas_get() function), the event type, the Evas_Event_Cb callback function, and the pointer to the additional data delivered to the callback. The additional data is optional; use NULL if you do not need it.

      + +

      The callback function takes as parameters the additional data defined in the evas_event_callback_add() function parameters, the canvas where the event happened, and the event info data, which depends on the object type and the event at play.

      + + +

      Evas Object Events

      + +

      Each Evas object on a specific Evas canvas can be manipulated independently. Each object can send events, which you can handle by registering callback functions for them. The events all relate to single objects, not the whole canvas.

      + +

      The following Evas object event types are available:

      +
        +
      • EVAS_CALLBACK_MOUSE_IN: Pointer got over an object (with no other object between the 2). This takes place no matter how the pointer becomes directly above the object. The event info parameter in the callback is a pointer to an Evas_Event_Mouse_In struct.
      • +
      • EVAS_CALLBACK_MOUSE_OUT: Triggered similarly to the EVAS_CALLBACK_MOUSE_IN event, but when the pointer goes outside the object area. The event info parameter in the callback is a pointer to an Evas_Event_Mouse_Out struct.
      • +
      • EVAS_CALLBACK_MOUSE_DOWN: Mouse button is pressed while the object is receiving events (either because the pointer is on top of the object or because the object had focus). The event info parameter in the callback is a pointer to an Evas_Event_Mouse_Down struct.
      • +
      • EVAS_CALLBACK_MOUSE_UP: Triggered similarly to the EVAS_CALLBACK_MOUSE_DOWN event. The event info parameter in the callback is a pointer to an Evas_Event_Mouse_Up struct.
      • +
      • EVAS_CALLBACK_MOUSE_MOVE: Triggered similarly to the EVAS_CALLBACK_MOUSE_DOWN event. The event info parameter in the callback is a pointer to an Evas_Event_Mouse_Move struct.
      • +
      • EVAS_CALLBACK_MOUSE_WHEEL: Triggered similarly to the EVAS_CALLBACK_MOUSE_DOWN event. The event info parameter in the callback is a pointer to an Evas_Event_Mouse_Wheel struct.
      • +
      • EVAS_CALLBACK_MULTI_DOWN: Triggered similarly to the EVAS_CALLBACK_MOUSE_DOWN event. The event info parameter in the callback is a pointer to an Evas_Event_Multi_Down struct.
      • +
      • EVAS_CALLBACK_MULTI_UP: Triggered similarly to the EVAS_CALLBACK_MOUSE_DOWN event. The event info parameter in the callback is a pointer to an Evas_Event_Multi_Up struct.
      • +
      • EVAS_CALLBACK_MULTI_MOVE: Triggered similarly to the EVAS_CALLBACK_MOUSE_DOWN event. The event info parameter in the callback is a pointer to an Evas_Event_Multi_Move struct.
      • +
      • EVAS_CALLBACK_KEY_DOWN: Triggered similarly to the EVAS_CALLBACK_MOUSE_DOWN event. The event info parameter in the callback is a pointer to an Evas_Event_Key_Down struct.
      • +
      • EVAS_CALLBACK_KEY_UP: Triggered similarly to the EVAS_CALLBACK_MOUSE_DOWN event. The event info parameter in the callback is a pointer to an Evas_Event_Key_Up struct.
      • +
      • EVAS_CALLBACK_FOCUS_IN: Object gained focus. The event info parameter in the callback is a pointer to an Evas_Event_Mouse_In struct.
      • +
      • EVAS_CALLBACK_FOCUS_OUT: Object lost focus. The event info parameter in the callback is a pointer to an Evas_Event_Mouse_In struct.
      • +
      • EVAS_CALLBACK_SHOW: Object is shown by a call to the evas_object_show() function. The event info parameter in the callback is NULL.
      • +
      • EVAS_CALLBACK_HIDE: Object is hidden by a call to the evas_object_hide() function. The event info parameter in the callback is NULL.
      • +
      • EVAS_CALLBACK_MOVE: Object origin was moved (origin is the top-left corner at the creation time of the object). The event info parameter in the callback is NULL.
      • +
      • EVAS_CALLBACK_RESIZE: Object is resized. The event info parameter in the callback is NULL.
      • +
      • EVAS_CALLBACK_RESTACK: Object is re-stacked by the evas_object_stack_below() or evas_object_stack_above() function, or other events. The event info parameter in the callback is NULL.
      • +
      • EVAS_CALLBACK_DEL: Object is deleted.
      • +
      • EVAS_CALLBACK_FREE: For internal use only. Do not use (the object resources are about to be freed). The event info parameter in the callback is NULL.
      • +
      • EVAS_CALLBACK_HOLD: For internal use only. The event info parameter in the callback is a pointer to an Evas_Event_Hold struct.
      • +
      • EVAS_CALLBACK_CHANGED_SIZE_HINTS: Object size hints changed.
      • +
      • EVAS_CALLBACK_IMAGE_PRELOADED: Image preloaded through the evas_object_image_preload() function is loaded. The event info parameter in the callback is NULL.
      • +
      • EVAS_CALLBACK_IMAGE_UNLOADED: Image data is unloaded. The event info parameter in the callback is NULL.
      • +
      + +

      To register the callback, use the evas_event_callback_add() function. The function takes as parameters the object to which the callback is attached, the event type, the Evas_Object_Event_Cb callback function, and the pointer to the additional data delivered to the callback. The additional data is optional; use NULL if you do not need it.

      + +

      The callback function takes as parameters the additional data defined in the evas_event_callback_add() function parameters, the canvas where the event happened, the object to which the event happened, and the event info data, which depends on the object type and the event at play.

      + +

      When no longer needed, remove the callback with the evas_object_event_callback_del() function.

      + + +

      Evas Smart Object Events

      + +

      Evas smart object events are the most widely-used type of events in graphical applications, since they are used for signals, such as "clicked", "clicked,double" (double-click), and "pressed". They are identified by strings, and each smart object is able to define its own events (although the names follow conventions).

      + +

      Managing Evas Smart Object Event Handlers

      + +
      1. To add an Evas Smart Object event handler, register a callback for a specific event to an object with the evas_object_smart_callback_add() function. +

        The function takes as parameters the object to which the callback is added, the event name, the callback function, and additional data delivered to the callback. The additional data is optional; use NULL if you do not need it.

      2. + +
      3. Define the Evas_Smart_Cb() callback function. +

        The function takes as parameters the additional data defined in the evas_object_smart_callback_add() function parameters, the object to which the event happened, and the event info data, which depends on the object type and the event at play.

        +

        If some of the parameters are not used by the callback function, the compiler can raise the "unused parameter" warning. To avoid it, annotate the parameter with the __UNUSED__ macro, which is a compiler-independent way to let the compiler know that the parameter is unused willingly, rather than by a mistake:

        +
        void cb(void *data __UNUSED__, Evas_Object *obj, void *event_info __UNUSED__);
        +
      4. + +
      5. When no longer needed, remove the event handler with the evas_object_smart_callback_del() function. +

        The function removes the first match for the given event and callback, and returns the data pointer that was used in the corresponding call to the evas_object_smart_callback_add() function.

      + +

      The following example shows the _button_clicked() function and sets it as the callback for the clicked event of an Evas_Object button:

      + +
      +static void
      +_button_clicked(void *data, Evas_Object *obj, void *event_info)
      +{
      +   // Insert function body here
      +}
      +
      +static void
      +some_function(void) 
      +{
      +   // Code to build the window object
      +   Evas_Object *button = elm_button_add(window);
      +   evas_object_smart_callback_add(button, "clicked", _button_clicked, NULL);
      +}
      +
      + +

      For a specific object and event, callbacks are called in the order they have been registered. The evas_object_smart_callback_add() function does not execute any special processing, if it is called several times with the same callback function or data. Callbacks are called as many times as they have been added and in the order they have been added.

      + + + +

      Evas Smart Object Event Handling Examples

      + +

      The following example shows a button with a callback for the "clicked" signal:

      + +
      static void
      +_button_clicked(void *data __UNUSED__, Evas_Object *obj __UNUSED__, void *event_info __UNUSED__)
      +{
      +   fprintf(stdout, "Button clicked.\n");
      +   fflush(stdout);
      +   elm_exit();
      +}
      +
      +static void
      +_add_button(Evas_Object *window) 
      +{
      +   Evas_Object *button;
      +
      +   button = elm_button_add(window);
      +   elm_object_text_set(button, "Click Me To Exit!");
      +   evas_object_smart_callback_add(button, "clicked", _button_clicked, NULL);
      +
      +   evas_object_show(button);
      +}
      +
      + +

      The following example shows a button with a callback for the "clicked" signal. Clicking the button removes the callback:

      + +
      static void
      +_button_clicked(void *data __UNUSED__, Evas_Object *obj, void *event_info __UNUSED__)
      +{
      +   fprintf(stdout, "Button clicked.\n");
      +   fflush(stdout);
      +   evas_object_smart_callback_del(obj, "clicked", _button_clicked);
      +}
      +
      +static void
      +_add_button(Evas_Object *window) 
      +{
      +   Evas_Object *button;
      +
      +   button = elm_button_add(window);
      +   elm_object_text_set(button, "Click Me!");
      +   evas_object_smart_callback_add(button, "clicked", _button_clicked, NULL);
      +
      +   evas_object_show(button);
      +}
      +
      + + + + + + + + + + +
      Note
      Except as noted, this content is licensed under LGPLv2.1+.
      + + + +
      + +Go to top + + + + + + + \ No newline at end of file diff --git a/org.tizen.ui.guides/html/native/efl/font_setting_n.htm b/org.tizen.ui.guides/html/native/efl/font_setting_n.htm new file mode 100755 index 0000000..2f3125a --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/font_setting_n.htm @@ -0,0 +1,450 @@ + + + + + + + + + + + + + Fonts: Setting Application Text Fonts + + + + + +
      + +

      Fonts: Setting Application Text Fonts

      + + +

      Tizen provides various methods for setting fonts of the application text. Basically, all UI components have a default font, which can be changed according to the system settings.

      + +

      The font handling methods include:

      + +
        +
      • Setting the font for a UI component using the Elementary Fonts API (in mobile and wearable applications)
      • +
      • Setting the font using EDC
      • +
      • Changing the font and text size using the Edje Class: Text API (in mobile and wearable applications) + +

        In the application, you can set a system-wide font and font size to text(textblock) parts with text classes (except tizen). When the system applies a new system-wide font and font size to the application, the font size of text(textblock) parts with the tizen text class are not affected.

        +

        The following words in the text_class definition are reserved for the system:

        + +
          +
        • button
        • +
        • label
        • +
        • entry
        • +
        • title_bar
        • +
        • list_item
        • +
        • grid_item
        • +
        • toolbar_item
        • +
        • menu_item
        • +
        • tizen
        • +
        + + +

        Set a specific ratio to a given font size for each object through the text class. If you give a negative value as font size, it is used as the percentage of the originally given font size. The following example code show set the font size as 150% of the given font size.

        +
        +elm_config_font_overlay_set("my_class", "TizenSans:style=Bold", -150);
        +elm_config_font_overlay_apply();
        +
        +
      • +
      + + +

      You can also set your own font.

      + +

      Applying System Font Settings

      + +

      Tizen provides a special "Tizen" font name. The "Tizen" font name does not match with any specific font; it is just an alias for a system-defined font (system font). When you create a text(textblock) part with the "Tizen" font name in the application's EDC, the system font is loaded into the user application when those objects are created. Additionally, you can apply the system font to a text or textblock part by using the text class, as described above.

      + +

      The following EDC example shows how to apply the system font to a TEXT or TEXTBLOCK part by using the "Tizen" font name and the tizen text class. As font name is "Tizen" and the font size is set to 36, the system font is loaded in size 36. If the system setting changes, this part loads the new system font. However, its font size is not changed, because the text class is tizen.

      + +
      +description 
      +{
      +   text 
      +   {
      +      font: "Tizen:style=Regular";
      +      font_size: 36;
      +      text_class: "tizen";
      +   }
      +}
      + +

      If the part has a predefined text classes other than tizen, its font size is resized as well.

      + +
      +description 
      +{
      +   text 
      +   {
      +      font: "Tizen:style=Regular";
      +      font_size: 36;
      +      text_class: "label";
      +   }
      +}
      + + +

      Supported Font Styles

      +

      The font styles supported by the EFL are listed in the following table.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Table: Supported font styles
      Font featureStyle attribute
      font_stylenormal
      oblique
      italic
      font_widthnormal
      ultracondensed
      extracondensed
      condensed
      semicondensed
      semiexpanded
      expanded
      extraexpanded
      ultraexpanded
      font_weightnormal
      thin
      ultralight
      light
      book
      medium
      semibold
      bold
      ultrabold
      black
      extrablack
      + +

      The style attributes are not case-sensitive (however, the font feature names are).

      +

      If you set the weight or width attribute to style=, it is processed to the right attribute.

      +
      +font=TizenSans:style=Bold // Textblock
      +"TizenSans:style=Bold"; // Text font
      +<font=TizenSans:style=Bold> // Markup tag
      +
      + +

      You can also use each attribute separately:

      + +
      +font=TizenSans font_style=Regular font_weight=Bold // Textblock
      +<font=TizenSans font_style=Regular font_weight=Bold> // Markup tag
      +
      + + +

      Setting the Font for a UI Component

      + +

      You can use the Elementary Fonts API (in mobile and wearable applications) to set the font for an application.

      +

      To set a font for a UI component:

      +
        +
      • Set the font for a common UI component: + + + + + + + + + + +
        Note
        You can set the font for a textblock in the code, but not in EDC (Edje Data Collection). If you add markup tags for the font inside the text, you can change the font of the text. However, you cannot set the font for a text part in this way because the TEXT type does not support markup tags.
        + +
        +char *buf = "<font=Sans:style=Regular font_size=50>Hello</font/>Font";
        +elm_object_part_text_set(layout, "textblock1", buf);
        +
        +
      • +
      • Set the font for an entry component (in mobile and wearable applications) using the elm_entry_text_style_user_push() function. It overrides the default style of the entry component for each attribute. + + + + + + + + + + +
        Note
        The elm_entry_text_style_user_push() function only affects the main text of the UI component. To change the font of the guide text, you have to add markup tags.
        +
        +char *user_style = "DEFAULT='font=Sans:style=Regular font_size=40'";
        +elm_entry_text_style_user_push(entry, user_style);
        +elm_object_part_text_set(entry, "elm.guide",
        +   "<font=Sans:style=Regular font_size=40>Guide Text</font>");
        +
        +
      • +
      + +

      Setting the Font Using EDC

      + +

      To create a layout with text using the EDC, you can set the font for each text part or textblock:

      +
        +
      • Set the font of a text part using the font family name and a specific style of the font family: +
        +part 
        +{ 
        +   name: "text";
        +   type: TEXT;
        +   scale: 1;
        +   description 
        +   { 
        +      state: "default" 0.0;
        +      rel1.relative: 0.0 0.5;
        +      rel2.relative: 0.5 1.0;
        +      color: 0 136 170 255;
        +      color2: 0 136 170 50;
        +      color3: 0 136 170 25;
        +      text 
        +      {
        +         size: 25;
        +         font: "Sans:style=Bold";
        +         text: "Enventor";
        +         align: 0.5 0.5;
        +      }
        +   }
        +}
        +
        +
      • + +
      • Add style information, which can be used for multiple textblock parts: +
        +styles 
        +{
        +   style 
        +   { 
        +      name: "textblock_style1";
        +      base: "font=Sans:style=Regular font_size=30";
        +   }
        +}
        +
        +part 
        +{ 
        +   name: "textblock";
        +   type: TEXTBLOCK;
        +   scale: 1;
        +   description 
        +   { 
        +      state: "default" 0.0;
        +      align: 0.5 0.5;
        +      fixed: 0 0;
        +      min: 0 0;
        +      visible: 1;
        +      text.text: "TEXTBLOCK";
        +      text.style: "textblock_style1";
        +      rel1.relative: 0.16 0.18;
        +      rel2.relative: 0.88 0.38;
        +   }
        +}
        +
        +
      • +
      + +

      Using the Edje Text Class

      + +

      You can use the Edje Class: Text API (in mobile and wearable applications) to change multiple text occurrences as a batch. If you set a new font or font size to a text class, the change is applied to multiple objects.

      + + + + + + + + + + +
      Note
      Note that the text_class cannot be used in a UI component with markup text or the elm_entry_text_style_user_push() function. You must set the text_class in EDC.
      + + +

      To set the text class, you can use reserved words for text class, but you can also make your own text class:

      + +
        +
      • Set a class for a text part: + +
        +part 
        +{ 
        +   name: "text";
        +   type: TEXT;
        +   scale: 1;
        +   description 
        +   { 
        +      state: "default" 0.0;
        +      rel1.relative: 0.0 0.5;
        +      rel2.relative: 0.5 1.0;
        +      color: 0 136 170 255;
        +      color2: 0 136 170 50;
        +      color3: 0 136 170 25;
        +      text 
        +      {
        +         size: 25;
        +         font: "Sans:style=Bold";
        +         text: "Enventor";
        +         align: 0.5 0.5;
        +         text_class: "my_class";
        +      }
        +   }
        +}
        +
        +
      • +
      • Set a class for a textblock: +
        +styles 
        +{
        +   style 
        +   { 
        +      name: "textblock_style1";
        +      base: "font=Sans:style=Regular font_size=30 ... text_class=my_class";
        +   }
        +}
        +
        +part 
        +{ 
        +   name: "textblock";
        +   type: TEXTBLOCK;
        +   scale: 1;
        +   description 
        +   { 
        +      state: "default" 0.0;
        +      align: 0.5 0.5;
        +      fixed: 0 0;
        +      min: 0 0;
        +      visible: 1;
        +      text.text: "TEXTBLOCK";
        +      text.style: "textblock_style1";
        +      rel1.relative: 0.16 0.18;
        +      rel2.relative: 0.88 0.38;
        +   }
        +}
        +
        +
      • +
      • +

        You can handle font and font style per text_class. If you set your own text_class in the EDC, you can change the font and font size:

        + +
        +elm_config_font_overlay_set("my_class", "TizenSans:style=Bold", 30);
        +elm_config_font_overlay_apply();
        +
        +
      • +
      • +

        Set a specific ratio to a given font size for each object through the text class. If you give a negative value as font size, it is used as the percentage of the originally given font size. The following example code show set the font size as 150% of the given font size.

        +
        +elm_config_font_overlay_set("my_class", "TizenSans:style=Bold", -150);
        +elm_config_font_overlay_apply();
        +
        +
      • +
      + +

      Setting Your Own Font

      + +

      You can create your own font and use them in your application. Before using your fonts, set the path for the fonts. Use the evas_font_path_global_append() or prepend function once when the application is launched.

      +
      +char *font_path = "/opt/usr/apps/org.tizen.myapp/res/fonts/";
      +evas_font_path_global_append(font_path);
      +
      + +

      After calling the evas_font_path_global_append() function, you can load your fonts including the family name and style.

      + + + +
      + +Go to top + + + + + + + \ No newline at end of file diff --git a/org.tizen.ui.guides/html/native/efl/form_tutorial_n.htm b/org.tizen.ui.guides/html/native/efl/form_tutorial_n.htm new file mode 100755 index 0000000..f4487a5 --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/form_tutorial_n.htm @@ -0,0 +1,316 @@ + + + + + + + + + + + + + + Creating a Form for a Basic Application Layout + + + + + + +
      +

      Creating a Form for a Basic Application Layout

      + + +

      This tutorial explains how to create a basic application for displaying a list of contacts, and a form for displaying and editing contact information when an item is selected on the contact list.

      + +

      Creating the Basic Application

      + +

      To create an elementary application with a single window, use the following code.

      +
      static bool
      +app_create(void *data)
      +{
      +   appdata_s *ad = data;
      +   create_gui(ad);
      +   return true;
      +}
      +
      +int
      +main(int argc, char **argv)
      +{
      +   appdata_s ad = { 0 };
      +   ui_app_lifecycle_callback_s event_callback = { 0 };
      +
      +   event_callback.create = app_create;
      +
      +   // Zero out the structure
      +   memset(&ad, 0x0, sizeof(struct appdata));
      +
      +   // Run the mainloop
      +   return ui_app_main(&argc, &argv, &event_callback, &ad);
      +}
      +
      + + + +

      Use a naviframe in this application to switch between different views. The first view that is displayed is the list of contacts. When a user selects an item on this list, information on the contact is displayed in a form. Both the view list and the form are opened in a naviframe, which handles the animations between the views for you. It also manages creating a back button in the top bar and launching the back animation when you select it, deletes the form view, and shows the list of contacts again.

      + +

      Naviframe

      +

      The naviframe is the main layout of the window, so it takes all the space available. To configure this, use the elm_win_resize_object_add function. The first parameter is the main window, the second is the naviframe object. The naviframe is to be resized along with the window. The object (the naviframe) fills its parent (the main window) by calling the evas_object_resize_hint_weight_set function on the naviframe object. The naviframe object expands in both x and y directions. In the end, evas shows the naviframe object on the screen.

      +
       // Create the naviframe
      +nav = elm_naviframe_add(win);
      +evas_object_size_hint_weight_set(nav, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +elm_win_resize_object_add(win, nav);
      +evas_object_show(nav);
      +
      + +

      Contact List

      +

      Handle the contact list with the _create_contact_list function. This function takes the parent object as the parameter (in this case the naviframe) and returns the genlist. To create the genlist, use the following code.

      +
      static Evas_Object *
      +_create_contact_list(Evas_Object *parent)
      +{
      +   Evas_Object *list;
      +   int i;
      +
      +   // Create a new genlist
      +   list = elm_genlist_add(parent);
      +   evas_object_show(list);
      +
      +   // Create a new item class for the genlist
      +   itc = elm_genlist_item_class_new();
      +   itc->item_style = "default";
      +   // Set the callback used when the genlist text is created
      +   itc->func.text_get = _genlist_text_get;
      +   // Set the callback be used when the content of the item is created
      +   itc->func.content_get   = _genlist_content_get;
      +   itc->func.state_get = NULL;
      +   itc->func.del = NULL;
      +}
      +
      + +

      itc is a static variable containing the item class. The item class contains all functions that are called back when an item is created. In this case, create the callbacks _genlist_text_get (for labels) and _genlist_content_get (for icons). These functions are called when labels and icons of the genlist item are created.

      +

      The list of contacts is contained in an array of Contacts.

      +
      typedef struct _Contact Contact;
      +
      +struct _Contact
      +{
      +   const char *name;
      +   const char *mobile;
      +   const char *address;
      +   const char *email;
      +   const char *icon;
      +};
      +
      +static Contact contacts[] = 
      +{
      +   {"Alexander Holmes", "+1234567896", "", "alexander_holmes@tizen.org", "c1.png"},
      +   {"Lara Alvaréz",    "+9876543216", "", "lara_alvares@tizen.org", "c2.png"   },
      +   {"Aksel Møller",    "+1679432846", "", "aksel_moller@tizen.org", "c3.png"   },
      +   {"Anir Amghar",      "+1679432846", "", "anir_amghar@tizen.org", "c4.png"    },
      +   {"Noémie Cordier",    "+1679432846", "", "noemie_cordier@tizen.org", "c5.png"   },
      +   {"Henry Thompson",    "+1679432846", "", "henry_thompson@tizen.org", "c6.png"   },
      +   {"Mai Phan",       "+1679432846", "", "mai_phan@tizen.org", "c7.png"      },
      +};
      +
      + +

      Create a genlist item for each item of the array with the following code.

      +
      +// Create a genlist item for each item in the contacts array
      +for (i = 0; i < EINA_C_ARRAY_LENGTH(contacts); i++)
      +{
      +   // Append the item, add a callback when the item is selected, and use the
      +   // current contact item as data pointer for the callbacks
      +   elm_genlist_item_append(list, itc,
      +                     &contacts[i],
      +                  NULL,
      +                     ELM_GENLIST_ITEM_NONE,
      +                     _contact_selected_cb,
      +                     &contacts[i]);
      +}
      +
      + +

      Attach the _contact_selected_cb callback function to the genlist item. When an item is selected in the list, the data pointer passed as the argument calls this function. Here it is a pointer on the contact. Pass the contact in the array to all the Item Class callbacks.

      +

      Push the list at the top of the naviframe with the following code.

      +
      +// Create the list of contacts
      +list = _create_contact_list(win);
      +
      +// Push the list on top of the naviframe
      +elm_naviframe_item_push(nav, NULL, NULL, NULL, list, NULL);
      +
      + +

      The Item class functions are called, the _genlist_text_get first.

      +
      +static char *
      +_genlist_text_get(void *data, Evas_Object *obj EINA_UNUSED, const char *part)
      +{
      +   Contact *contact = data;
      +
      +   // Return a new allocated string for the contact name
      +   return strdup(contact->name);
      +}
      +
      + +

      These functions show the index of the contact in the array and return a freshly allocated string with the name of the contact.

      +

      When the user selects an item in the list, a callback registers on the select signal and calls the corresponding function; in this case, _contact_selected_cb(). The user retrieves the index of the array passed in the data and creates the form on contact information based on this index.

      +

      The _genlist_content_get function is called several times depending on the style of the created item. In this case, with the default style for the genlist item, there are two different swallow parts. A swallow part is a container in the edje file of the genlist item, which may contain an evas object. The following figure shows the layout of different parts in the theme.

      + + +

      Figure: Genlist item

      +

      Genlist item

      + + +

      There are two elm.swallow parts. When the callback function for the creation of icons is called, the part name is passed via the part variable. Compare this variable to elm.swallow.icon for the first object and to elm.swallow.end for the icon at the end.

      + +

      Icon

      +

      Create the icon when the callback is recognized. In this example, we use an elm_icon object.

      +
      +static Evas_Object *
      +_genlist_content_get(void *data, Evas_Object *obj, const char *part)
      +{
      +   Contact *contact = data;
      +
      +   // Test which part is being created
      +   if (!strcmp(part, "elm.swallow.icon"))
      +   {
      +         char filename[PATH_MAX];
      +      // Create a new icon
      +      Evas_Object *ic = elm_icon_add(obj);
      +      // Set the filename of the file which is to be loaded
      +      snprintf(filename, sizeof(filename), "%s%s", ICON_PATH, contact->icon);
      +      elm_image_file_set(ic, filename, NULL);
      +      // Keep the ratio squared
      +      evas_object_size_hint_aspect_set(ic, EVAS_ASPECT_CONTROL_VERTICAL, 1, 1);
      +
      +      // Return the icon
      +      return ic;
      +   }
      +
      +   return NULL;
      +}
      +
      + +

      Note that in case of elm.swallow.end the return is NULL, and no icon is added.

      +

      The user may question the complexity of creating a genlist, and the benefits of callbacks for the creation of items. In a genlist with thousands of elements, graphical items are not created. Only the ones currently displayed on the screen are created with the callbacks in the Genlist Item Class. Otherwise, objects are created by calling the respective callback function when the user scrolls the list.

      + + + + + + + + + + +
      Note
      When the genlist is first created, the Elementary needs to know the height of the list. All elements in the list are not necessarily the same size due to different kind of styles. Thus, the Elementary creates all elements once to know the size, and displays the scroll bars correctly. If all your items have the same height, use the elm_genlist_homogeneous_set to impose the same height to all items. The Elementary does not create the complete list as the global size is a multiple of the height of the first item. It saves you cpu time.
      + +

      Contact Form

      +

      The contact list is created inside the _create_contact_form function. This function takes a parent Evas_Object and a contact item as parameters, and returns an Evas_Object. The parent is the naviframe object, and the contact item contains the information on the contact.

      +

      To display the various information about the contact, we use boxes in this example.

      + +

      Figure: Form contact layout

      +

      Form contact layout

      + + +

      The first box is an vertical box.

      +
      vbox = elm_box_add(parent);
      +elm_box_align_set(vbox, 0, 0);
      +evas_object_show(vbox);
      +
      + +

      elm_box_align_set keeps the box element aligned to the top left corner.

      +

      To add an icon, use the _genlist_content_get function to create the icon in the genlist item. For a bigger icon, set the minimum size of the icon object to 96x96 px.

      +

      The most important function in this case is elm_box_pack_end. It adds the icon object at the end of the vbox. As the icon is the first object added, it is displayed on top of the box.

      +
      +ic = elm_icon_add(vbox);
      +snprintf(filename, sizeof(filename), "%s%s", ICON_PATH, contact->icon);
      +elm_image_file_set(ic, filename, NULL);
      +evas_object_size_hint_min_set(ic, 96, 96);
      +evas_object_show(ic);
      +elm_box_pack_end(vbox, ic);
      +
      + +

      In the following example, add the information on the contact: the name, the mobile phone number, the postal address and the e-mail address. For each information item, create a label and an edit line. The label contains the kind of the information, and the edit box, the information itself. To set the UI components in a horizontal layout, use a horizontal box.

      +
      +hbox = elm_box_add(vbox);
      +elm_box_horizontal_set(hbox, EINA_TRUE);
      +elm_box_padding_set(hbox, 32, 32);
      +evas_object_size_hint_weight_set(hbox, EVAS_HINT_EXPAND, 0);
      +evas_object_size_hint_align_set(hbox, EVAS_HINT_FILL, 0);
      +evas_object_show(hbox);
      +
      + +

      Change the orientation of the box with elm_box_horizontal_set. To get space between the elements of the vbox, set the padding to 32px. To set the item of the box not to expand vertically, use evas_object_size_hint_weight_set.

      +

      Create the label object, which is an elm_label. Set its text, and do not align or expand it.

      +
      +label = elm_label_add(hbox);
      +elm_object_text_set(label, form_items[i]);
      +evas_object_size_hint_weight_set(label, 0, 0);
      +evas_object_size_hint_align_set(label, 0, 0);
      +evas_object_show(label);
      +
      + +

      Create the edit line, which is an elm_entry.

      +
      +edit = elm_entry_add(hbox);
      +evas_object_size_hint_weight_set(edit, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +evas_object_size_hint_align_set(edit, EVAS_HINT_FILL, EVAS_HINT_FILL);
      +evas_object_show(edit);
      +
      + +

      Add the label and the edit inside the horizontal box and add the horizontal box to the vertical box.

      +
      +elm_box_pack_end(hbox, label);
      +elm_box_pack_end(hbox, edit);
      +
      +elm_box_pack_end(vbox, hbox);
      +
      + +

      Figure: Form tutorial: form

      +

      Form tutorial: form

      + +

      Figure: Form tutorial: list

      +

      Form tutorial: list

      + + + + +
      + +Go to top + + + + + + + diff --git a/org.tizen.ui.guides/html/native/efl/genlist_tutorial_mn.htm b/org.tizen.ui.guides/html/native/efl/genlist_tutorial_mn.htm new file mode 100755 index 0000000..7e89479 --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/genlist_tutorial_mn.htm @@ -0,0 +1,457 @@ + + + + + + + + + + + + + + Creating Mobile Genlists + + + + + + +
      +

      Creating Mobile Genlists

      + + +

      This tutorial deals with genlists, a list component for large sets of elements. It uses callbacks to populate entries. The same UI component handles both flat lists and trees.

      + + + + + + + + + + +
      Note
      This feature is supported in mobile applications only.
      + + +

      Initializing the Application

      + +

      Figure: Example of a genlist

      +

      Example of a genlist

      +

      The code below shows a typical elementary application that creates a window entitled "Genlist Basic Tutorial". It is consisted of a conformant component that contains a naviframe component. The genlist goes inside the naviframe.

      +
      static bool
      +_app_create(void *data)
      +{
      +   appdata_s *app = data;
      +
      +   app->win = elm_win_util_standard_add("main", "Genlist Basic Tutorial");
      +   elm_win_conformant_set(app->win, EINA_TRUE);
      +   evas_object_show(app->win);
      +   evas_object_resize(app->win, 480, 800);
      +   elm_win_autodel_set(app->win, EINA_TRUE);
      +
      +   app->conformant = elm_conformant_add(app->win);
      +   evas_object_size_hint_weight_set(app->conformant, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +   elm_win_resize_object_add(app->win, app->conformant);
      +   evas_object_show(app->conformant);
      +
      +   app->naviframe = elm_naviframe_add(app->win);
      +   evas_object_size_hint_weight_set(app->naviframe, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +   elm_win_resize_object_add(app->win, app->naviframe);
      +   evas_object_show(app->naviframe);
      +   elm_object_content_set(app->conformant, app->naviframe);
      +
      +   _create_list(app);
      +   elm_naviframe_item_push(app->naviframe, NULL, NULL, NULL, app->list, NULL);
      +
      +   return true;
      +}
      +
      +int
      +main(int argc, char **argv)
      +{
      +   // Declare a few structures and zero-initialize (C99 feature)
      +   struct app_data app = { 0 };
      +   ui_app_lifecycle_callback_s event_callback = { 0 };
      +
      +   event_callback.create = _app_create;
      +
      +   // Run the mainloop
      +   return ui_app_main(&argc, &argv, &event_callback, &ad);
      +}
      +
      +

      The declaration of the struct app_data is shown below:

      +
      struct app_data
      +{
      +   Evas_Object *win;
      +   Evas_Object *naviframe;
      +   Evas_Object *conformant;
      +   Evas_Object *list;
      +   Elm_Genlist_Item_Class *itc;
      +   Elm_Genlist_Item_Class *itc2;
      +};
      +
      + +

      Creating a Genlist

      + +

      Call elm_genlist_add() to create a genlist. Then new entries can be added. In this example, first the basic windows is created, then a genlist is added to it, and then 10000 elements with text and a colored block on each side of it.

      +
      Evas_Object *list = elm_genlist_add(parent);
      +
      + +

      Adding New Entries

      + +

      Use elm_genlist_item_append() to add new elements. Its second parameter is a structure which describes how to populate entries. Typically this structure is built once and re-used across calls to elm_genlist_item_append().

      +

      +Building a Basic Item Class

      +

      The code for the minimal genlist item class is below:

      + +
      Elm_Genlist_Item_Class *itc = elm_genlist_item_class_new();
      +itc->item_style = "default";
      +itc->func.text_get = NULL;
      +itc->func.content_get = NULL;
      +itc->func.state_get = NULL;
      +itc->func.del = NULL;
      +
      + +

      It creates a simple item class, sets the item_style to "default" and every other field to NULL. However, this leaves out the text_get and content_get fields which are used to add text and an icon to the list entry. This is explained in another section.

      +

      Adding the Element

      +

      Once the genlist item class object is created, a new element is added to the list by calling elm_genlist_item_append().

      +
      elm_genlist_item_append(list,
      +   itc,
      +   NULL,                    // Item data
      +   NULL,                    // Parent item for trees, NULL if none
      +   ELM_GENLIST_ITEM_NONE,   // Item type; this is the common one
      +   NULL,                    // Callback on selection of the item
      +   NULL                     // Data for that callback function
      +);
      +
      +

      With most parameters as NULL and itc having most of its members NULL, too, the elements of that list are blank and will not trigger anything when selected. This shows the APIs that are used.

      +

      Text in the List Elements

      +

      Use text_get callback to add text in the elements in the Elm_Genlist_Item_Class structure. These callbacks must have a prototype matching to the following:

      + +
      char * text_get(void *data, Evas_Object *obj, const char *part);
      +
      +

      This callbacks returns a C string that is displayed in the part named after the part parameter. This callback is called for each user-settable text part according to the current theme.

      +

      If you are not familiar with the concept of parts in the EFLs, see Writing a Simple EDC File.

      + + + + + + + + + + + +
      Note
      The value returned is freed by the EFLs: the value must be freshly-allocated, do not free it yourself and do not re-use it across list elements.
      + +

      For the default theme there is one part named elm.text. A possible implementation of the text_get callback is therefore:

      +
      static char *
      +_genlist_text_get(void *data, Evas_Object *obj, const char *part)
      +{
      +   // Check this is text for the part we're expecting
      +   if (strcmp(part, "elm.text") == 0) 
      +   {
      +      return strdup("Some text");
      +   }
      +   else 
      +   {
      +      return NULL;
      +   }
      +}
      +
      + + + + + + + + + + +
      Note
      The names and positions of parts depends on the item_style chosen when adding new items to the genlist. Setting a custom theme makes it possible to completely change genlists by adding and moving parts. Introduction to EDC Programming explains how to do that.
      + +

      The data parameter makes it possible to behave differently according to data that is given to the EFLs during the call to elm_genlist_item_append() in the data parameter. For example, given an integer in that field through casting with (void *)(uintptr_t) i, it is possible to get its value back using (int)(uintptr_t)data:

      +
      static char *
      +_genlist_text_get(void *data, Evas_Object *obj__UNUSED__, const char *part)
      +{
      +   if (strcmp(part, "elm.text") == 0) 
      +   {
      +      char *buf = malloc(16);
      +      snprintf(buf, 16, "Entry %d.", (int)(uintptr_t)data);
      +
      +      return buf;
      +   }
      +   else 
      +   {
      +      return NULL;
      +   }
      +}
      +
      + +

      Evas_Objects in the List Elements

      +

      Icons are added in a similar fashion: there is a callback named content_get which returns a pointer to an Evas_Object and is called for each part which contents can be set.

      +

      The prototype of the callback must match this one:

      +
      Evas_Object * content_get(void *data, Evas_Object *obj, const char *part);
      +
      + +

      The only difference with the text_get callback is that it returns an Evas_Object* rather than a char *.

      +

      This leads to a fairly simple dummy implementation with colored rectangles in the parts that are to be set:

      +
      +static Evas_Object *
      +_genlist_content_get(void *data, Evas_Object *obj, const char *part)
      +{
      +   int i = (int) (uintptr_t) data;
      +
      +   if (strcmp(part, "elm.swallow.icon") == 0) 
      +   {
      +      Evas_Object *bg = elm_bg_add(obj);
      +      elm_bg_color_set(bg, 255 * cos(i / (double) 10), 0, i % 255);
      +
      +      return bg;
      +   }
      +   else if (strcmp(part, "elm.swallow.end") == 0) 
      +   {
      +      Evas_Object *bg = elm_bg_add(obj);
      +      elm_bg_color_set(bg, 0, 255 * sin(i / (double) 10), i % 255);
      +
      +      return bg;
      +   }
      +   else 
      +   {
      +      return NULL;
      +   }
      +}
      +
      +

      For the default theme, this displays a red rectangle on the left of each list item and a green one on their right.

      +

      Events on Genlist Items

      +

      Genlist items triggers a callback when clicked. This callback is chosen when adding the new item (for example, when calling elm_genlist_item_append()):

      +
      elm_genlist_item_append(list,
      +   itc,
      +   NULL,                    // Item data
      +   NULL,                    // Parent item for trees, NULL if none
      +   ELM_GENLIST_ITEM_NONE,   // Item type, other values are used for trees
      +   _genlist_selected_cb,    // Callback on selection of the item
      +   NULL                     // Data for that callback function
      +);
      +
      + +

      This callback adheres to the following prototype:

      +
      void _contact_selected_cb(void *data, Evas_Object *obj, void *event_info)
      +
      + +

      The implementation below changes the item style of items when they are selected:

      +
      static void
      +_genlist_selected_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   struct app_data *app = data;
      +
      +   Elm_Object_Item *it = (Elm_Object_Item*) event_info;
      +
      +   elm_genlist_item_item_class_update(it, app->itc2);
      +}
      +
      + +

      Choosing Another Item Style to Add or Remove Parts

      + +

      As mentioned above, the number of parts to fill depends on the item style that is chosen when adding a new item. This is simply a matter of setting the right value when filling the Elm_Genlist_Item_Class struct:

      +
      app->itc->item_style = "default";
      +
      +

      The Genlist component lists all available item styles.

      +

      Further customization is achieved by modifying the theme as explained in Introduction to EDC Programming.

      +

      In case the customization is only visual, it is good practice to keep the same item style names for new themes. This makes it possible to change theme and keep the code the same while also retaining the same overall item placement.

      + +

      Using Item Modes

      + +

      So far the genlist examples have all featured bare lists while the genlist component is able to display trees or even a "group" mode where scrolling keeps the item at the top of the UI component until another group comes and replaces it.

      +

      Group Mode

      +

      The group mode makes it possible to keep an element visible as long as one of its children is visible. This is most useful for "title" items.

      +

      Mark some elements as ELM_GENLIST_ITEM_GROUP and use the returned Elm_Object_Item to establish the parent-children relationship when adding the children items.

      +

      Since there are two kind of items, create two item classes. Give them different styles and callback functions. The callback functions are visible in the example, they have no functionalities:

      +
      +app->itc = elm_genlist_item_class_new();
      +app->itc->item_style = "default_style";
      +app->itc->func.text_get = _genlist_text_get_size;
      +app->itc->func.content_get = _genlist_content_get_bg;
      +app->itc->func.state_get = NULL;
      +app->itc->func.del = NULL; 
      +
      +app->itc2 = elm_genlist_item_class_new();
      +app->itc2->item_style = "icon_top_text_bottom";
      +app->itc2->func.text_get = _genlist_text_get_nosize;
      +app->itc2->func.content_get = _genlist_content_get_icon;
      +app->itc2->func.state_get = NULL;
      +app->itc2->func.del = NULL; 
      +
      + +

      Then add a group header and follow it with 10 children. This is repeated 1000 times.

      +

      The parent has type ELM_GENLIST_ITEM_GROUP while the children have type ELM_GENLIST_ITEM_NONE.

      +

      The other important point is that the value returned by lm_genlist_item_append() is stored in it and then sent to the elm_genlist_item_append() call that adds the children. This creates the parent-children relationship.

      +
      +for (i = 0; i < 1000; i++) 
      +{
      +   it = elm_genlist_item_append(app->list, app->itc2, (void *)(uintptr_t) (10 * i), NULL,
      +                                ELM_GENLIST_ITEM_GROUP, NULL, NULL);
      +   for (j = 0; j < 10; j++)
      +   {
      +      elm_genlist_item_append(app->list, app->itc, (void *)(uintptr_t) (10 * i + j), it,
      +                              ELM_GENLIST_ITEM_NONE, NULL, NULL);
      +   }
      +}
      +
      + +

      Tree Mode

      +

      Like group mode, tree mode uses the parenting relationship with other items. Unlike group mode, the child elements are created on-demand when their parent is expanded and deleted when it is contracted. This is done by using smart callbacks: expand,request, expanded, contract,request, and contracted. Like any smart callback, they are registered through evas_object_smart_callback_add on the genlist object:

      +
      evas_object_smart_callback_add(app->list, "expand,request",
      +   _tree_item_expand_request, NULL);
      +evas_object_smart_callback_add(app->list, "expanded",
      +   _tree_item_expanded, NULL);
      +
      +evas_object_smart_callback_add(app->list, "contract,request",
      +   _tree_item_contract_request, NULL);
      +evas_object_smart_callback_add(app->list, "contracted",
      +   _tree_item_contracted, NULL);
      +
      + +

      The callbacks expand,request and contract,request do only one thing: decide whether the element is expanded or contracted. This is done by using elm_genlist_item_expanded_set() function; if it changes the expansion status of the item, the next callback is called (either expanded or contracted, depending on whether it was an expand,request or contract,request event). A minimal implementation of these callbacks is therefore:

      +
      +static void
      +_tree_item_expand_request(void *data, Evas_Object *o, void *event_info)
      +{
      +   Elm_Object_Item *it = (Elm_Object_Item*) event_info;
      +
      +   elm_genlist_item_item_class_update(it, app->itc2);
      +
      +   elm_genlist_item_expanded_set(it, EINA_TRUE);
      +}
      +
      + + + + + + + + + + +
      Note
      The example above has an extra line: the call to elm_genlist_item_item_class_update(). It changes the item style and is explained in the Changing the item class of an item after its creation section.
      + +
      +static void
      +_tree_item_contract_request(void *data, Evas_Object *o, void *event_info)
      +{
      +   Elm_Object_Item *it = (Elm_Object_Item*) event_info;
      +
      +   elm_genlist_item_item_class_update(it, app->itc);
      +
      +   elm_genlist_item_expanded_set(it, EINA_FALSE);
      +}
      +
      + +

      As said above, once the genlist item status is set to expanded, the expanded event is triggered and it is the duty of a callback for that event to populate the list with the item's children. This relies on the parent parameter of functions like elm_genlist_item_append(), like for the group mode.

      +

      The function below is a callback implementation for the expanded event. It adds items that are built similarly to previous items, the only change is the parent parameter which is not NULL. Conveniently, the parent Elm_Object_Item pointer that is passes to the elm_genlist_item_append() function is given in the event_info callback and needs to be cast.

      +
      static void
      +_tree_item_expanded(void *data, Evas_Object *o, void *event_info)
      +{
      +   Elm_Object_Item *it_parent = (Elm_Object_Item*) event_info;
      +   int i_parent = (int)(uintptr_t) data;
      +   int i;
      +
      +   for (i = 0; i < 10; i++) 
      +   {
      +      elm_genlist_item_append(app->list, app->itc, (void *)(uintptr_t) (i + i_parent), it_parent,
      +                              ELM_GENLIST_ITEM_NONE, NULL, NULL);
      +   }
      +}
      +
      + +

      The following code has the callback function for the contracted event. It imply calls elm_genlist_item_subitems_clear() to clear all children (including their own children if they have any) of the given item. Again, the item that is being contracted is available through the event_info parameter to the callback.

      +
      static void
      +_tree_item_contracted(void *data, Evas_Object *o, void *event_info)
      +{
      +   Elm_Object_Item *it_parent = (Elm_Object_Item*) event_info;
      +
      +   elm_genlist_item_subitems_clear(it_parent);
      +}
      +
      + +

      Mixing Group and Tree Modes

      +

      A common UI design is to mix group and tree modes. It allows for a tree behavior while also keeping the group header item. The EFLs do not do any magic here and the way to get such a behavior is to create an item of type group, an item of type tree which parent is the group item. Then add the callbacks to populate the children of the tree item in the regular way.

      + +

      Using Other APIs

      + +

      Homogeneous Item Size

      +

      Because of the scroller, the actual height and/or width of the genlist must be computed. This means summing the sizes of all the items, the sizes must be computed. This obviously has a cost and slows down adding items to the genlist.

      +

      The elm_genlist_homogeneous_set() function alleviates this issue by assuming all the items are the same size as the first one of the list. It speeds up large insertions. However, it may lead to serious graphical issues if the items are not actually the same size. Use with care.

      + +

      Changing the Item Class of an Item After Its Creation

      +

      Changing the item class of a UI component is an easy way to change its appearance upon selection or other actions of the user. This is done by calling elm_genlist_item_class_update():

      +
      static void
      +_tree_item_expand_request(void *data, Evas_Object *o, void *event_info)
      +{
      +   Elm_Object_Item *it = (Elm_Object_Item*) event_info;
      +
      +   // Change the appearance and possibly content of the item being expanded.
      +   elm_genlist_item_item_class_update(it, app->itc2);
      +
      +   elm_genlist_item_expanded_set(it, EINA_TRUE);
      +}
      +
      + + + + +
      + +Go to top + + + + + + + diff --git a/org.tizen.ui.guides/html/native/efl/genlist_tutorial_wn.htm b/org.tizen.ui.guides/html/native/efl/genlist_tutorial_wn.htm new file mode 100755 index 0000000..7f9a993 --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/genlist_tutorial_wn.htm @@ -0,0 +1,469 @@ + + + + + + + + + + + + + + Creating Wearable Genlists + + + + + + +
      +

      Creating Wearable Genlists

      + +

      This tutorial deals with genlists, a list component for large sets of elements. It uses callbacks to populate entries. The same UI component handles both flat lists and trees.

      + + + + + + + + + + +
      Note
      This feature is supported in wearable applications only.
      + + +

      Initializing the Application

      + +

      Figure: Example of a genlist

      +

      Example of a genlist

      +

      The code below shows a typical elementary application that creates a window entitled "Genlist Basic Tutorial". It is consisted of a conformant component that contains a naviframe component. The genlist goes inside the naviframe.

      +
      static bool
      +_app_create(void *data)
      +{
      +   appdata_s *app = data;
      +
      +   app->win = elm_win_util_standard_add("main", "Genlist Basic Tutorial");
      +   elm_win_conformant_set(app->win, EINA_TRUE);
      +   evas_object_show(app->win);
      +   evas_object_resize(app->win, 480, 800);
      +   elm_win_autodel_set(app->win, EINA_TRUE);
      +
      +   app->conformant = elm_conformant_add(app->win);
      +   evas_object_size_hint_weight_set(app->conformant, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +   elm_win_resize_object_add(app->win, app->conformant);
      +   evas_object_show(app->conformant);
      +
      +   app->naviframe = elm_naviframe_add(app->win);
      +   evas_object_size_hint_weight_set(app->naviframe, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +   elm_win_resize_object_add(app->win, app->naviframe);
      +   evas_object_show(app->naviframe);
      +   elm_object_content_set(app->conformant, app->naviframe);
      +
      +   _create_list(app);
      +   elm_naviframe_item_push(app->naviframe, NULL, NULL, NULL, app->list, NULL);
      +
      +   return true;
      +}
      +
      +int
      +main(int argc, char **argv)
      +{
      +   // Declare a few structures and zero-initialize (C99 feature)
      +   struct app_data app = { 0 };
      +   ui_app_lifecycle_callback_s event_callback = { 0 };
      +
      +   event_callback.create = _app_create;
      +
      +   // Run the mainloop
      +   return ui_app_main(&argc, &argv, &event_callback, &ad);
      +}
      +
      +

      The declaration of the struct app_data is shown below:

      +
      struct app_data
      +{
      +   Evas_Object *win;
      +   Evas_Object *naviframe;
      +   Evas_Object *conformant;
      +   Evas_Object *list;
      +   Elm_Genlist_Item_Class *itc;
      +   Elm_Genlist_Item_Class *itc2;
      +};
      +
      + +

      Creating a Genlist

      + +

      Call elm_genlist_add() to create a genlist. Then new entries can be added. In this example, first the basic windows is created, then a genlist is added to it, and then 10000 elements with text and a colored block on each side of it.

      +
      Evas_Object *list = elm_genlist_add(parent);
      +
      + +

      Adding New Entries

      + +

      Use elm_genlist_item_append() to add new elements. Its second parameter is a structure which describes how to populate entries. Typically this structure is built once and re-used across calls to elm_genlist_item_append().

      +

      +Building a Basic Item Class

      +

      The code for the minimal genlist item class is below:

      + +
      Elm_Genlist_Item_Class *itc = elm_genlist_item_class_new();
      +itc->item_style = "default";
      +itc->func.text_get = NULL;
      +itc->func.content_get = NULL;
      +itc->func.state_get = NULL;
      +itc->func.del = NULL;
      +
      + +

      It creates a simple item class, sets the item_style to "default" and every other field to NULL. However, this leaves out the text_get and content_get fields which are used to add text and an icon to the list entry. This is explained in another section.

      +

      Adding the Element

      +

      Once the genlist item class object is created, a new element is added to the list by calling elm_genlist_item_append().

      +
      elm_genlist_item_append(list,
      +   itc,
      +   NULL,                    // Item data
      +   NULL,                    // Parent item for trees, NULL if none
      +   ELM_GENLIST_ITEM_NONE,   // Item type; this is the common one
      +   NULL,                    // Callback on selection of the item
      +   NULL                     // Data for that callback function
      +);
      +
      +

      With most parameters as NULL and itc having most of its members NULL, too, the elements of that list are blank and will not trigger anything when selected. This shows the APIs that are used.

      +

      Text in the List Elements

      +

      Use text_get callback to add text in the elements in the Elm_Genlist_Item_Class structure. These callbacks must have a prototype matching to the following:

      + +
      char * text_get(void *data, Evas_Object *obj, const char *part);
      +
      +

      This callbacks returns a C string that is displayed in the part named after the part parameter. This callback is called for each user-settable text part according to the current theme.

      +

      If you are not familiar with the concept of parts in the EFLs, see Writing a Simple EDC File.

      + + + + + + + + + + + +
      Note
      The value returned is freed by the EFLs: the value must be freshly-allocated, do not free it yourself and do not re-use it across list elements.
      + +

      For the default theme there is one part named elm.text. A possible implementation of the text_get callback is therefore:

      +
      static char *
      +_genlist_text_get(void *data, Evas_Object *obj, const char *part)
      +{
      +   // Check this is text for the part we're expecting
      +   if (strcmp(part, "elm.text") == 0) 
      +   {
      +      return strdup("Some text");
      +   }
      +   else 
      +   {
      +      return NULL;
      +   }
      +}
      +
      + + + + + + + + + + +
      Note
      The names and positions of parts depends on the item_style chosen when adding new items to the genlist. Setting a custom theme makes it possible to completely change genlists by adding and moving parts. Introduction to EDC Programming explains how to do that.
      + +

      The data parameter makes it possible to behave differently according to data that is given to the EFLs during the call to elm_genlist_item_append() in the data parameter. For example, given an integer in that field through casting with (void *)(uintptr_t) i, it is possible to get its value back using (int)(uintptr_t)data:

      +
      static char *
      +_genlist_text_get(void *data, Evas_Object *obj__UNUSED__, const char *part)
      +{
      +   if (strcmp(part, "elm.text") == 0) 
      +   {
      +      char *buf = malloc(16);
      +      snprintf(buf, 16, "Entry %d.", (int)(uintptr_t)data);
      +
      +      return buf;
      +   }
      +   else 
      +   {
      +      return NULL;
      +   }
      +}
      +
      + +

      Evas_Objects in the List Elements

      +

      Icons are added in a similar fashion: there is a callback named content_get which returns a pointer to an Evas_Object and is called for each part which contents can be set.

      +

      The prototype of the callback must match this one:

      +
      Evas_Object * content_get(void *data, Evas_Object *obj, const char *part);
      +
      + +

      The only difference with the text_get callback is that it returns an Evas_Object* rather than a char *.

      +

      This leads to a fairly simple dummy implementation with colored rectangles in the parts that are to be set:

      +
      +static Evas_Object *
      +_genlist_content_get(void *data, Evas_Object *obj, const char *part)
      +{
      +   int i = (int) (uintptr_t) data;
      +
      +   if (strcmp(part, "elm.swallow.icon") == 0) 
      +   {
      +      Evas_Object *bg = elm_bg_add(obj);
      +      elm_bg_color_set(bg, 255 * cos(i / (double) 10), 0, i % 255);
      +
      +      return bg;
      +   }
      +   else if (strcmp(part, "elm.swallow.end") == 0) 
      +   {
      +      Evas_Object *bg = elm_bg_add(obj);
      +      elm_bg_color_set(bg, 0, 255 * sin(i / (double) 10), i % 255);
      +
      +      return bg;
      +   }
      +   else 
      +   {
      +      return NULL;
      +   }
      +}
      +
      +

      For the default theme, this displays a red rectangle on the left of each list item and a green one on their right.

      +

      Events on Genlist Items

      + + + + + + + + + + +
      Note
      The swallow parts have no minimum size. This means that if you do not fix the minimum size, the part cannot be seen.
      + +

      Genlist items triggers a callback when clicked. This callback is chosen when adding the new item (for example, when calling elm_genlist_item_append()):

      +
      elm_genlist_item_append(list,
      +   itc,
      +   NULL,                    // Item data
      +   NULL,                    // Parent item for trees, NULL if none
      +   ELM_GENLIST_ITEM_NONE,   // Item type, other values are used for trees
      +   _genlist_selected_cb,    // Callback on selection of the item
      +   NULL                     // Data for that callback function
      +);
      +
      + +

      This callback adheres to the following prototype:

      +
      void _contact_selected_cb(void *data, Evas_Object *obj, void *event_info)
      +
      + +

      The implementation below changes the item style of items when they are selected:

      +
      static void
      +_genlist_selected_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   appdata_s *app = data;
      +
      +   Elm_Object_Item *it = (Elm_Object_Item*) event_info;
      +
      +   elm_genlist_item_item_class_update(it, app->itc2);
      +}
      +
      + +

      Choosing Another Item Style to Add or Remove Parts

      + +

      As mentioned above, the number of parts to fill depends on the item style that is chosen when adding a new item. This is simply a matter of setting the right value when filling the Elm_Genlist_Item_Class struct:

      +
      app->itc->item_style = "default";
      +
      +

      The Genlist component lists all available item styles.

      +

      Further customization is achieved by modifying the theme as explained in Introduction to EDC Programming.

      +

      In case the customization is only visual, it is good practice to keep the same item style names for new themes. This makes it possible to change theme and keep the code the same while also retaining the same overall item placement.

      + +

      Using Item Modes

      + +

      So far the genlist examples have all featured bare lists while the genlist component is able to display trees or even a "group" mode where scrolling keeps the item at the top of the UI component until another group comes and replaces it.

      +

      Group Mode

      +

      The group mode makes it possible to keep an element visible as long as one of its children is visible. This is most useful for "title" items.

      +

      Mark some elements as ELM_GENLIST_ITEM_GROUP and use the returned Elm_Object_Item to establish the parent-children relationship when adding the children items.

      +

      Since there are two kind of items, create two item classes. Give them different styles and callback functions. The callback functions are visible in the example, they have no functionalities:

      +
      +app->itc = elm_genlist_item_class_new();
      +app->itc->item_style = "default";
      +app->itc->func.text_get = _genlist_text_get_size;
      +app->itc->func.content_get = _genlist_content_get_bg;
      +app->itc->func.state_get = NULL;
      +app->itc->func.del = NULL; 
      +
      +app->itc2 = elm_genlist_item_class_new();
      +app->itc2->item_style = "1text.1icon";
      +app->itc2->func.text_get = _genlist_text_get_nosize;
      +app->itc2->func.content_get = _genlist_content_get_icon;
      +app->itc2->func.state_get = NULL;
      +app->itc2->func.del = NULL; 
      +
      + +

      Then add a group header and follow it with 10 children. This is repeated 1000 times.

      +

      The parent has type ELM_GENLIST_ITEM_GROUP while the children have type ELM_GENLIST_ITEM_NONE.

      +

      The other important point is that the value returned by lm_genlist_item_append() is stored in it and then sent to the elm_genlist_item_append() call that adds the children. This creates the parent-children relationship.

      +
      +for (i = 0; i < 1000; i++) 
      +{
      +   it = elm_genlist_item_append(app->list, app->itc2, (void *)(uintptr_t) (10 * i), NULL,
      +                                ELM_GENLIST_ITEM_GROUP, NULL, NULL);
      +   for (j = 0; j < 10; j++)
      +   {
      +      elm_genlist_item_append(app->list, app->itc, (void *)(uintptr_t) (10 * i + j), it,
      +                              ELM_GENLIST_ITEM_NONE, NULL, NULL);
      +   }
      +}
      +
      + +

      Tree Mode

      +

      Like group mode, tree mode uses the parenting relationship with other items. Unlike group mode, the child elements are created on-demand when their parent is expanded and deleted when it is contracted. This is done by using smart callbacks: expand,request, expanded, contract,request, and contracted. Like any smart callback, they are registered through evas_object_smart_callback_add on the genlist object:

      +
      evas_object_smart_callback_add(app->list, "expand,request",
      +   _tree_item_expand_request, NULL);
      +evas_object_smart_callback_add(app->list, "expanded",
      +   _tree_item_expanded, NULL);
      +
      +evas_object_smart_callback_add(app->list, "contract,request",
      +   _tree_item_contract_request, NULL);
      +evas_object_smart_callback_add(app->list, "contracted",
      +   _tree_item_contracted, NULL);
      +
      + +

      The callbacks expand,request and contract,request do only one thing: decide whether the element is expanded or contracted. This is done by using elm_genlist_item_expanded_set() function; if it changes the expansion status of the item, the next callback is called (either expanded or contracted, depending on whether it was an expand,request or contract,request event). A minimal implementation of these callbacks is therefore:

      +
      +static void
      +_tree_item_expand_request(void *data, Evas_Object *o, void *event_info)
      +{
      +   Elm_Object_Item *it = (Elm_Object_Item*) event_info;
      +
      +   elm_genlist_item_item_class_update(it, app->itc2);
      +
      +   elm_genlist_item_expanded_set(it, EINA_TRUE);
      +}
      +
      + + + + + + + + + + +
      Note
      The example above has an extra line: the call to elm_genlist_item_item_class_update(). It changes the item style and is explained in the Changing the item class of an item after its creation section.
      + +
      +static void
      +_tree_item_contract_request(void *data, Evas_Object *o, void *event_info)
      +{
      +   Elm_Object_Item *it = (Elm_Object_Item*) event_info;
      +
      +   elm_genlist_item_item_class_update(it, app->itc);
      +
      +   elm_genlist_item_expanded_set(it, EINA_FALSE);
      +}
      +
      + +

      As said above, once the genlist item status is set to expanded, the expanded event is triggered and it is the duty of a callback for that event to populate the list with the item's children. This relies on the parent parameter of functions like elm_genlist_item_append(), like for the group mode.

      +

      The function below is a callback implementation for the expanded event. It adds items that are built similarly to previous items, the only change is the parent parameter which is not NULL. Conveniently, the parent Elm_Object_Item pointer that is passes to the elm_genlist_item_append() function is given in the event_info callback and needs to be cast.

      +
      static void
      +_tree_item_expanded(void *data, Evas_Object *o, void *event_info)
      +{
      +   Elm_Object_Item *it_parent = (Elm_Object_Item*) event_info;
      +   int i_parent = (int)(uintptr_t) data;
      +   int i;
      +
      +   for (i = 0; i < 10; i++) 
      +   {
      +      elm_genlist_item_append(app->list, app->itc, (void *)(uintptr_t) (i + i_parent), it_parent,
      +                              ELM_GENLIST_ITEM_NONE, NULL, NULL);
      +   }
      +}
      +
      + +

      The following code has the callback function for the contracted event. It imply calls elm_genlist_item_subitems_clear() to clear all children (including their own children if they have any) of the given item. Again, the item that is being contracted is available through the event_info parameter to the callback.

      +
      static void
      +_tree_item_contracted(void *data, Evas_Object *o, void *event_info)
      +{
      +   Elm_Object_Item *it_parent = (Elm_Object_Item*) event_info;
      +
      +   elm_genlist_item_subitems_clear(it_parent);
      +}
      +
      + +

      Mixing Group and Tree Modes

      +

      A common UI design is to mix group and tree modes. It allows for a tree behavior while also keeping the group header item. The EFLs do not do any magic here and the way to get such a behavior is to create an item of type group, an item of type tree which parent is the group item. Then add the callbacks to populate the children of the tree item in the regular way.

      + +

      Using Other APIs

      + +

      Homogeneous Item Size

      +

      Because of the scroller, the actual height and/or width of the genlist must be computed. This means summing the sizes of all the items, the sizes must be computed. This obviously has a cost and slows down adding items to the genlist.

      +

      The elm_genlist_homogeneous_set() function alleviates this issue by assuming all the items are the same size as the first one of the list. It speeds up large insertions. However, it may lead to serious graphical issues if the items are not actually the same size. Use with care.

      + +

      Changing the Item Class of an Item After Its Creation

      +

      Changing the item class of a UI component is an easy way to change its appearance upon selection or other actions of the user. This is done by calling elm_genlist_item_class_update():

      +
      static void
      +_tree_item_expand_request(void *data, Evas_Object *o, void *event_info)
      +{
      +   Elm_Object_Item *it = (Elm_Object_Item*) event_info;
      +
      +   // Change the appearance and possibly content of the item being expanded.
      +   elm_genlist_item_item_class_update(it, app->itc2);
      +
      +   elm_genlist_item_expanded_set(it, EINA_TRUE);
      +}
      +
      + + + + +
      + +Go to top + + + + + + + diff --git a/org.tizen.ui.guides/html/native/efl/graphical_objects_n.htm b/org.tizen.ui.guides/html/native/efl/graphical_objects_n.htm new file mode 100755 index 0000000..6f3c87f --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/graphical_objects_n.htm @@ -0,0 +1,78 @@ + + + + + + + + + + + + + Graphical Objects: Managing and Rendering Evas Objects + + + + + +
      + +

      Graphical Objects: Managing and Rendering Evas Objects

      + +

      Evas is a clean display canvas API for several target display systems that can draw anti-aliased text, smooth super and sub-sampled scaled images, alpha-blend objects and much more.

      +

      It abstracts any need to know much about what the characteristics of your display system are, what graphics calls are used to draw them, and how. It deals on an object level where all you do is create and manipulate objects in a canvas and set their properties.

      +

      Evas optimizes the rendering pipeline to minimize effort in redrawing changes made to the canvas and so takes this work out of the programmers hand, saving a lot of time and energy.

      +

      It is designed to work on embedded systems all the way to large and powerful multi-cpu workstations. It can be compiled to only have the features you need for your target platform if you so wish. It has several display back-ends, allowing it display on several display systems, making it portable for cross-device and cross-platform development.

      + +

      Evas is not a UI component set or a UI component toolkit, but it is their base. See Elementary for a toolkit based on Evas, Edje, Ecore and other Enlightenment technologies.

      +

      It is not dependent or aware of main loops, input or output systems. Input must be polled from various sources and fed to Evas. It does not create windows or report windows updates to your system, but draws the pixels and reports to the user the areas that are changed. These operations are ready to be used in Ecore, particularly in Ecore_Evas wrapper/helper set of functions.

      + + + + + + + + + + +
      Note
      Except as noted, this content is licensed under LGPLv2.1+.
      + + + +
      + +Go to top + + + + + + + \ No newline at end of file diff --git a/org.tizen.ui.guides/html/native/efl/guides_efl_n.htm b/org.tizen.ui.guides/html/native/efl/guides_efl_n.htm new file mode 100755 index 0000000..2e2ae38 --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/guides_efl_n.htm @@ -0,0 +1,95 @@ + + + + + + + + + + + + + + EFL + + + + + + +
      +

      EFL

      + +

      EFL is an open-source UI toolkit that provides a set of libraries that offer useful features to applications. EFL covers a number of areas from UI component sets to data structures. EFL is one of the Tizen native UI modules and is available in various Tizen profiles. In Tizen, EFL is commonly used for UI applications, although you can also use it for non-UI applications.

      + +

      When creating an EFL application, make sure you understand the following main features:

      + + + + + +
      + +Go to top + + + + + + + + diff --git a/org.tizen.ui.guides/html/native/efl/hw_input_n.htm b/org.tizen.ui.guides/html/native/efl/hw_input_n.htm new file mode 100755 index 0000000..27f1a9f --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/hw_input_n.htm @@ -0,0 +1,64 @@ + + + + + + + + + + + + + Hardware Input Handling: Managing Hardware Events with EFL Extension + + + + + +
      + +

      Hardware Input Handling: Managing Hardware Events with EFL Extension

      + +

      The Tizen platform offers the Menu, Back, and Home keys as physical hardware keys for mobile devices and rotary component parts for wearable devices.

      + +

      Basically, EFL does not depend on any specific hardware input methods, such as hardware keys, to generate back and home events, or rotary component parts to generate rotary events. Instead these hardware input events have tightly related to the Tizen UX. As a result, EFL has created the EFL extension library to support common UX behavior between applications and hardware events.

      + +

      When the user presses the Menu or Back key, the key generates a signal with its key property. The Ecore library receives the signal and propagates it to application layers as an event. The EFL extension library consumes the events and handles the views of the application according to key properties. Otherwise, EFL extension manages the rotary events, which are generated from rotary components in wearable devices and delivered to application layers by defining an event callback or a handler function, and registering it.

      + + + +
      + +Go to top + + + + + + + \ No newline at end of file diff --git a/org.tizen.ui.guides/html/native/efl/key_events_n.htm b/org.tizen.ui.guides/html/native/efl/key_events_n.htm new file mode 100755 index 0000000..ff158e2 --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/key_events_n.htm @@ -0,0 +1,188 @@ + + + + + + + + + + + + + Managing Menu and Back Key Events + + + + + +
      +

      Managing Menu and Back Key Events

      + +

      The Menu and Back functions are common UX behaviors in applications. Generally, the user taps the Back hardware key to return to the previous screen. The applications usually also provide option menus to manipulate their functions through the tapping of the Menu hardware key.

      + + + + + + + + + + +
      Note
      Hardware key events are only supported in mobile devices.
      + +

      Normally, the key events are only delivered to the object in focus. However, with the EFL Extension functions, you can let visible objects without focus get events from the Menu and Back keys.

      + +

      Figure: Menu and Back keys

      +

      Menu and Back keys

      + +

      The EFL Extension maintains its own object stack for determining which object to deliver events to. Only visible objects are added to this stack. The stack is based on the Evas layer. It means that if 2 objects are registered for the same EFL Extension event, the object on the higher Evas layer gets the event.

      + +

      The following figure shows an example of objects and their layers. Objects 1, 2, and 3 are registered with EFL Extension callbacks for the same event, such as a Back key event. When the event occurs, object 3, which is on the highest layer (layer 3), gets the event callback.

      + +

      Figure: Objects with layers

      +

      Objects with layers

      + +

      If objects stay on the same layer, the object which is registered to the callback first gets the event.

      + +

      To register a callback for the Menu or Back key, use the eext_object_event_callback_add() function with the application callback type:

      +
        +
      • EEXT_CALLBACK_BACK: Hardware Back key event
      • +
      • EEXT_CALLBACK_MORE: Hardware Menu key event
      • +
      + +

      To delete a registered event in the EFL Extension, use the eext_object_event_callback_del() function.

      + +

      The EFL Extension also provides other convenient functions to work with the Menu and Back keys for popup (in mobile and wearable applications), ctxpopup (in mobile and wearable applications), naviframe, and entry (in mobile and wearable applications) components.

      + +

      Managing Hardware Key Events

      + +

      The application has a window that contains a naviframe and registers the EFL Extension Menu and Back key events for the naviframe.

      +

      When the Menu key is pressed, a popup is created and an EFL Extension Back key event for this popup is registered. If the popup is shown and the Back key is pressed, the popup is removed. Otherwise, if the Back key is pressed and there is no popup, the application is hidden.

      + +

      To manage hardware key events:

      +
        +
      1. +

        To use the functions and data types of the Efl Extension API (in mobile and wearable applications), include the <efl_extension.h> header file in your application:

        +
        +#include <efl_extension.h>
        +
        +
      2. + +
      3. Create objects using the window and naviframe: +
        +static void
        +create_base_gui(appdata_s *ad)
        +{
        +   Evas_Object *win = NULL;
        +
        +   // Create the window
        +   win = elm_win_util_standard_add(NULL, "extension sample");
        +   evas_object_smart_callback_add(win, "delete,request", _win_del, NULL);
        +
        +   // Create the naviframe
        +   Evas_Object *nf = NULL;
        +   nf = elm_naviframe_add(win);
        +   evas_object_size_hint_weight_set(win, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
        +   elm_win_resize_object_add(win, nf);
        +   evas_object_show(nf);
        +
        +   // Content
        +   Evas_Object *label = NULL;
        +   label = elm_label_add(nf);
        +   elm_object_text_set(label, "Press menu key to show popup,<br/>back key to exit.");
        +   elm_naviframe_item_push(nf, "Efl Extension usage", NULL, NULL, label, NULL);
        +
        +   // Show the window
        +   evas_object_show(win);
        +}
        +
        +
      4. + +
      5. Register EFL Extension callbacks for the naviframe: +
        +static void
        +create_base_gui(appdata_s *ad)
        +{
        +   // Register the EFL extension callbacks for Menu and Back key events
        +   eext_object_event_callback_add(nf, EEXT_CALLBACK_MORE, _create_popup, NULL);
        +   eext_object_event_callback_add(nf, EEXT_CALLBACK_BACK, _nf_back_cb, win);
        +}
        +
        +
      6. + +
      7. Create a popup and register EFL Extension Back key event callbacks for it: +
        +static void
        +_create_popup(void *data, Evas_Object *obj, void *event_info)
        +{
        +   Evas_Object *parent = obj;
        +
        +   Evas_Object *popup = NULL, *content = NULL;
        +   popup = elm_popup_add(parent);
        +   elm_object_part_text_set(popup, "title,text", "Title");
        +   elm_popup_orient_set(popup, ELM_POPUP_ORIENT_CENTER);
        +
        +   // Popup content
        +   content = elm_label_add(parent);
        +   elm_object_text_set(content, "Press back key to remove popup.");
        +   elm_object_content_set(popup, content);
        +
        +   // Register the EFL extension callback for the Back key event
        +   eext_object_event_callback_add(popup, EEXT_CALLBACK_BACK, eext_popup_back_cb, NULL);
        +   evas_object_show(popup);
        +}
        +
        + +

        To remove the popup when a Back key event occurs, use the eext_popup_back_cb callback.

        + +

        The callback function for menu key callback:

        +
        +static void
        +_nf_back_cb(void *data, Evas_Object *obj, void *event_info)
        +{
        +   Evas_Object *win = data;
        +
        +   // Hide the window
        +   elm_win_lower(win);
        +}
        +
        +
      8. +
      + + + +
      + +Go to top + + + + + + + \ No newline at end of file diff --git a/org.tizen.ui.guides/html/native/efl/layout_tutorial_n.htm b/org.tizen.ui.guides/html/native/efl/layout_tutorial_n.htm new file mode 100755 index 0000000..905fd28 --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/layout_tutorial_n.htm @@ -0,0 +1,752 @@ + + + + + + + + + + + + + + Creating UI Screen Layouts + + + + + + +
      + +

      Creating UI Screen Layouts

      + + +

      This tutorial demonstrates how you can compose a UI screen using the layout classes available in the EFL UI component library. It also highlights the capabilities of the EFL layout classes in free style layouting as well as layouting in a particular sequence (such as linear or grid).

      + + +

      Creating the UI Layout

      + +

      The sample application uses UI components, such as elm_naviframe and elm_toolbar for the view management, layout classes, such as elm_table, elm_box, and elm_grid for the composition of the screen, and UI components, such as elm_label and elm_image for the content inside the view.

      + +

      The create_base_gui() function creates the application layout. It starts by creating a window, then adds the elm_conformant component to it to decorate the window with an indicator. It then adds the elm_naviframe component which acts as a view manager for the window and provides the window title functionality. After this it creates the toolbar using the create_toolbar() function and adds it to naviframe.

      +
      +static void
      +create_base_gui(appdata_s *ad)
      +{
      +   Elm_Object_Item *nf_it, *tabbar_it;
      +   // Window
      +   ad->win = elm_win_util_standard_add(PACKAGE, PACKAGE);
      +   elm_win_wm_desktop_layout_support_set(ad->win, EINA_TRUE);
      +   elm_win_autodel_set(ad->win, EINA_TRUE);
      +
      +   evas_object_smart_callback_add(ad->win, "delete,request", win_delete_request_cb, NULL);
      +
      +   // Conformant
      +   ad->conform = elm_conformant_add(ad->win);
      +   evas_object_size_hint_weight_set(ad->conform, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +   elm_win_resize_object_add(ad->win, ad->conform);
      +   evas_object_show(ad->conform);
      +
      +   // Naviframe
      +   ad->nf = elm_naviframe_add(ad->conform);
      +   elm_object_content_set(ad->conform, ad->nf);
      +   evas_object_show(ad->nf);
      +   nf_it = elm_naviframe_item_push(ad->nf, "UiLayout", NULL, NULL, NULL, "tabbar/icon/notitle");
      +
      +   // Tabbar
      +   ad->tabbar = create_toolbar(ad);
      +   elm_object_item_part_content_set(nf_it, "tabbar", ad->tabbar);
      +
      +   // Set the first view
      +   tabbar_it = elm_toolbar_first_item_get(ad->tabbar);
      +   elm_toolbar_item_selected_set(tabbar_it, EINA_TRUE);
      +
      +   // Show the window after the base GUI is set up
      +   evas_object_show(ad->win);
      +
      +   ecore_event_handler_add(ECORE_EVENT_KEY_DOWN, keydown_cb, NULL);
      +}
      +
      + +

      The create_toolbar() function creates the toolbar which is then added to the naviframe.

      +
      +static Evas_Object*
      +create_toolbar(appdata_s *ad)
      +{
      +   Evas_Object *tabbar;
      +
      +   tabbar = elm_toolbar_add(ad->nf);
      +   elm_object_style_set(tabbar, "tabbar");
      +   elm_toolbar_shrink_mode_set(tabbar, ELM_TOOLBAR_SHRINK_EXPAND);
      +   elm_toolbar_transverse_expanded_set(tabbar, EINA_TRUE);
      +
      +   elm_toolbar_item_append(tabbar, NULL, "Box", tabbar_item_cb, ad);
      +   elm_toolbar_item_append(tabbar, NULL, "Grid", tabbar_item_cb, ad);
      +   elm_toolbar_item_append(tabbar, NULL, "Table", tabbar_item_cb, ad);
      +
      +   return tabbar;
      +}
      +
      + +

      The following figure illustrates the UI Layout.

      + +

      Figure: UI Layout screen

      +

      UI Layout screen

      + +

      Adding Content to the Screen

      + +

      The create_box_view() function creates the screen using a recursive composition of the box layout.

      + +
      static Evas_Object*
      +create_box_view(Evas_Object *parent)
      +{
      +   Evas_Object *box, *box1, *box2, *box3;
      +
      +   box = elm_box_add(parent);
      +   elm_box_padding_set(box, 10, 10);
      +   evas_object_size_hint_weight_set(box, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +   evas_object_size_hint_align_set(box, EVAS_HINT_FILL, EVAS_HINT_FILL);
      +
      +   box1 = elm_box_add(box);
      +   elm_box_horizontal_set(box1, EINA_TRUE);
      +   elm_box_padding_set(box1, 8, 8);
      +   evas_object_size_hint_weight_set(box1, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +   evas_object_size_hint_align_set(box1, EVAS_HINT_FILL, EVAS_HINT_FILL);
      +   evas_object_show(box1);
      +
      +   box2 = elm_box_add(box);
      +   elm_box_padding_set(box2, 6, 6);
      +   evas_object_size_hint_weight_set(box2, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +   evas_object_size_hint_align_set(box2, EVAS_HINT_FILL, EVAS_HINT_FILL);
      +   evas_object_show(box2);
      +
      +   box3 = elm_box_add(box);
      +   elm_box_padding_set(box3, 5, 5);
      +   evas_object_size_hint_weight_set(box3, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +   evas_object_size_hint_align_set(box3, EVAS_HINT_FILL, EVAS_HINT_FILL);
      +   elm_box_homogeneous_set(box3, EINA_FALSE);
      +   evas_object_show(box3);
      +} 
      +
      + +

      Once the box layout is created, content or another box layout is added to the box. Box implements the size policy during the size calculation.

      + +
      // Add an item to the box
      +Evas_Object *item1 = create_content(box, "Item 1");
      +evas_object_size_hint_min_set(item1, 0, 40);
      +elm_box_pack_end(box, item1);
      +elm_box_pack_end(box, box1);
      +elm_box_pack_end(box, box3);
      +elm_box_pack_end(box, create_content(box, "Item 4"));
      +
      +// Add an item to the box1
      +elm_box_pack_end(box1, create_content(box1, "Item 2.1"));
      +elm_box_pack_end(box1, box2);
      +elm_box_pack_end(box1, create_content(box1, "Item 2.3"));
      +
      +// Add an item to the box2
      +elm_box_pack_end(box2, create_content(box2, "Item 2.2.1"));
      +elm_box_pack_end(box2, create_content(box2, "Item 2.2.2"));
      +
      +// Add an item to the box3
      +elm_box_pack_end(box3, create_content(box3, "Item 3.1"));
      +elm_box_pack_end(box3, create_content(box3, "Item 3.2"));
      +
      + +

      The create_table_view() function creates the screen by composing table layout with content and grid view.

      + +
      static Evas_Object*
      +create_table_view(Evas_Object *parent)
      +{
      +   Evas_Object *table, *item;
      +
      +   table = elm_table_add(parent);
      +   elm_table_padding_set(table, 10, 10);
      +   elm_table_homogeneous_set(table, EINA_TRUE);
      +   evas_object_size_hint_weight_set(table, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +   evas_object_size_hint_align_set(table, EVAS_HINT_FILL, EVAS_HINT_FILL);
      +
      +   item = create_content(table, "Item 1");
      +   elm_table_pack(table, item, 0, 0, 2, 1);
      +
      +   item = create_content(table, "Item 2");
      +   elm_table_pack(table, item, 2, 0, 1, 1);
      +
      +   item = create_content(table, "Item 3");
      +   elm_table_pack(table, item, 0, 1, 3, 1);
      +
      +   // Add a grid view item
      +   item = create_grid_view(table);
      +   evas_object_show(item);
      +   elm_table_pack(table, item, 0, 2, 3, 10);
      +
      +   return table;
      +}
      +
      + +

      The table layout can be used for freestyle layouting, and for standard layouts, such as lists and grids. It does not consider the size policy of the child item during size calculation.

      +

      The create_grid_view() function composes a screen using the grid layout and also uses box and table layout as a child item to pack inside a grid. It uses free style layouting, and during size evaluation of the child item, it does not take the size policy of the child item into consideration.

      + +
      static Evas_Object*
      +create_grid_view(Evas_Object *parent)
      +{
      +   Evas_Object *grid, *item;
      +
      +   grid = elm_grid_add(parent);
      +   evas_object_size_hint_weight_set(grid, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +   evas_object_size_hint_align_set(grid, EVAS_HINT_FILL, EVAS_HINT_FILL);
      +
      +   // Red background for the grid
      +   item = create_bg(grid, 255, 0, 0);
      +   elm_grid_pack(grid, item, 0, 0, 100, 100);
      +
      +   // Add the item to the grid
      +   item = create_content(grid, "Item1");
      +   elm_grid_pack(grid, item, 1, 1, 98, 98);
      +
      +   item = create_content(grid, "Item2");
      +   elm_grid_pack(grid, item, 2, 5, 20, 20);
      +
      +   item = create_content(grid, "Item3");
      +   elm_grid_pack(grid, item, 23, 5, 76, 94);
      +
      +   item = create_content(grid, "Item4");
      +   elm_grid_pack(grid, item, 2, 27, 20, 70);
      +
      +   // Black background for the box view item
      +   item = create_bg(grid, 40, 40, 40);
      +   elm_grid_pack(grid, item, 25, 10, 73, 87);
      +
      +   // Add the box view item to the grid
      +   item = create_box_view(grid);
      +   evas_object_show(item);
      +   elm_grid_pack(grid, item, 26, 11, 71, 85);
      +
      +   return grid;
      +}
      +
      + +

      Using the Base Layout

      + +

      When developing a Tizen native application, it is recommended that you base your application layout on the base layout. The base layout supports the indicator and view management. The following figure shows the wireframe and UI component hierarchy of the base layout:

      + +

      Figure: Base layout wireframe and UI component hierarchy

      +

      Base layout wireframe and UI component hierarchy

      + +

      The UI components have the following roles:

      + +
        +
      • Window (Elm_win): Every UI component from Elementary is rendered in a Window.
      • +
      • Conformant (Elm_Conformant): The Conformant supports the indicator area and resizing the application due to rotation or the ISF (keypad).
      • +
      • Naviframe (Elm_Naviframe): The Naviframe acts as a view manager and optionally provides the application title. The main layout of the application is added to the Naviframe's view area.
      • +
      + + +

      Sample Applications with the Base Layout

      + +

      Setting

      + +

      The Setting application consists of a list to show as a menu. For organizing the application, create the application layout with a screen-size-list and place the layout into the Naviframe's view area.

      + +

      Figure: Setting UI and layout

      +

      Settings UI and layout

      + +

      For more information, see the Setting sample application.

      + +

      Application Store

      + +

      For organizing the Application Store application, you need to add a scroller to the base layout, since the total height of the layout will be greater than the screen size, and you will therefore need to scroll the screen contents up and down. If the layout is larger than the screen, the scroller makes the view itself scrollable.

      + +

      You can use a list or grid if the same objects are shown repeatedly. In this sample application, however, the various items are shown in a layout.

      + +

      Figure: Application Store UI and layout

      +

      Application Store UI and layout

      + +

      For more information, see the Application Store sample application.

      + +

      Sample Applications with a Custom Layout

      + +

      Calculator - No Naviframe

      + +

      The Calculator is a good example of an exception to the base layout. The application has no view changes and no application title. As these are the two reasons why you should use a Naviframe, you do not need to add a Naviframe to the Calculator.

      + +

      You can organize the application layout with container components. Container components are used for arranging UI components, both basic UI components and other container components.

      + +

      Figure: Calculator UI and layout

      +

      Calculator UI and layout

      + +

      For more information, see the Calculator sample application.

      + +

      Email - Drawer

      + +

      The Email application shows information using a list. The main view is the same as in the Setting application, consisting of a screen-size-list for displaying emails. However, the Email application has an additional feature: the Drawer, which is used for displaying the menu with a hierarchy.

      + +

      To develop the application as a Tizen native application, add a layout on the Conformant, and add a Naviframe to the layout. This layout has a content area for the Drawer and Naviframe, and its style name is "layout/drawer/panel". To use this layout, use the following code:

      + +
      +layout = elm_layout_add(parent);
      +elm_layout_theme_set(layout, "layout", "drawer", "panel");
      +
      + +

      The style includes parts for locating the Drawer and the main view. In the Drawer area, you can add a list to indicate the menu. In the main view, you can add a Naviframe to organize the view of the layout.

      + +

      Figure: Email UI and layout

      +

      Email UI and layout

      + +

      For more information, see the Email sample application.

      + +

      Creating a Simple Clock View

      + +

      This sample creates a basic clock view that shows the time, current city, and date. This sample demonstrates how to use a box, container component, and label to create a basic layout. The application includes the following UI components:

      + +
        +
      • Elm_window: Basic canvas for rendering the screen
      • +
      • Elm_conformant: Support indicator area
      • +
      • Elm_naviframe: View manager component
      • +
      • Elm_box: Container component for layouting other UI components
      • +
      • Elm_label: Basic UI component for showing text with a tag
      • +
      + +

      The following figure illustrates the main view of the simple clock sample application and its wireframe structure.

      + +

      Figure: Simple clock screen

      +

      Simple clock screen

      + +

      The basic clock is implemented in the world_clock.c file. In this application, the data structure for application is following:

      + +
      typedef struct appdata
      +{
      +   // Save the window
      +   Evas_Object *win;
      +} 
      +appdata_s;
      +
      + +

      The information in appdata is used for the entire system. In this sample application, the information is related to handling the HW back key.

      + +

      The single callback function for application handling is app_create, and it only creates the basic GUI:

      + +
      int
      +main(int argc, char *argv[])
      +{
      +   appdata_s *ad = {0,};
      +   app_event_callback_s event_callback = {0,};
      +   int ret = 0;
      +
      +   event_callback.create = app_create;
      +   event_callback.terminate = app_terminate;
      +   event_callback.pause = app_pause;
      +   event_callback.resume = app_resume;
      +   event_callback.app_control = app_control;
      +
      +   ui_app_add_event_handler(&handlers[APP_EVENT_LOW_BATTERY], APP_EVENT_LOW_BATTERY, ui_app_low_battery, &ad);
      +   ui_app_add_event_handler(&handlers[APP_EVENT_LOW_MEMORY], APP_EVENT_LOW_MEMORY, ui_app_low_memory, &ad);
      +   ui_app_add_event_handler(&handlers[APP_EVENT_DEVICE_ORIENTATION_CHANGED], APP_EVENT_DEVICE_ORIENTATION_CHANGED, ui_app_orient_changed, &ad);
      +   ui_app_add_event_handler(&handlers[APP_EVENT_LANGUAGE_CHANGED], APP_EVENT_LANGUAGE_CHANGED, ui_app_lang_changed, &ad);
      +   ui_app_add_event_handler(&handlers[APP_EVENT_REGION_FORMAT_CHANGED], APP_EVENT_REGION_FORMAT_CHANGED, ui_app_region_changed, &ad);
      +   ui_app_remove_event_handler(handlers[APP_EVENT_LOW_MEMORY]);
      +
      +   ret = app_main(argc, argv, &event_callback, &ad);
      +   if (ret != APP_ERROR_NONE) 
      +   {
      +      LOGE("app_main() is failed. err = %d", ret);
      +   }
      +
      +   return ret;
      +}
      +
      +static bool
      +app_create(void *data)
      +{
      +   appdata_s *ad = data;
      +   create_base_gui(ad);
      +
      +   return true;
      +}
      +
      + +

      Use the create_base_gui() function to create a basic layout with a window, conformant and naviframe. This is the basic layout in the Tizen mobile environment.

      + +
      ad->win = elm_win_util_standard_add(PACKAGE, PACKAGE);
      +elm_win_autodel_set(ad->win, EINA_TRUE);
      +
      +// Conformant
      +conform = elm_conformant_add(ad->win);
      +elm_win_conformant_set(ad->win, EINA_TRUE);
      +evas_object_size_hint_weight_set(conform, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +elm_win_resize_object_add(ad->win, conform);
      +evas_object_show(conform);
      +
      +// Naviframe
      +nf = elm_naviframe_add(conform);
      +elm_object_content_set(conform, nf);
      +evas_object_show(nf);
      +
      + +

      After creating a basic layout, create the main layout for the application. In this sample, it contains a box with 3 labels. The labels show the time, city and date. To add the labels to the box, use the elm_box_pack_end() function.

      + +

      After adding the labels, you must set their text. You can set or decorate the text in the labels using the elm_object_text_set() function. You can modify the text size (font_size), color (color), and thickness (b).

      + +
      +// Add the box
      +box = elm_box_add(nf);
      +// Create a label
      +label1 = elm_label_add(box);
      +// Set text to the label with a tag
      +elm_object_text_set(label1, "<font_size=110><color=#000000>07:26</color></font_size>");
      +// Add the label to the box
      +elm_box_pack_end(box, label1);
      +// Change label visibility
      +evas_object_show(label1);
      +
      +// Repeat with other labels
      +
      +evas_object_show(box);
      +
      + +

      After creating the box with labels, set the box as a new view. You can also set the title of the application. These operations are handled by the naviframe using the elm_naviframe_item_push() function:

      + +
      elm_naviframe_item_push(nf, _("World Clock"), NULL, NULL, box, "basic");
      + +

      The parameters include the title, the name of the UI component added as a new view, and the naviframe style. The basic style is used for a simple view with normal title.

      + +

      The following figure illustrates the UI component hierarchy of the application.

      + +

      Figure: Simple clock components

      +

      Simple clock components

      + +

      Set the HW key handler. The Tizen mobile environment supports the More and back keys, but only the back key is handled in this sample.

      +
      eext_object_event_callback_add(ad->win, EEXT_CALLBACK_BACK, win_back_cb, ad);
      +
      + +

      After setting the callback function, the win_back_cb callback is invokes when a back key is pressed. The win_back_cb callback will hide the window:

      +
      static void
      +win_back_cb(void *data , int type , void *event)
      +{
      +   appdata_s *ad = data;
      +   elm_win_lower(ad->win);
      +}
      +
      + +

      Creating a Complex Clock View

      + +

      This sample creates a complex clock view. The sample demonstrates how to organize a basic layout using boxes. The application includes the following UI components:

      + + +
        +
      • Elm_window: Basic canvas for rendering the screen
      • +
      • Elm_conformant: Support indicator area
      • +
      • Elm_naviframe: View manager component
      • +
      • Elm_box: Container component for layouting other UI components
      • +
      • Elm_label: Basic UI component for showing text with a tag
      • +
      • Elm_genlist: List component
      • +
      • Elm_button: Simple push button
      • +
      + +

      The following figure illustrates the main view of the complex clock sample application and its wireframe structure.

      + +

      Figure: Complex clock screen

      +

      Complex clock screen

      + +

      Basic GUI

      + +

      The basic clock is implemented in the world_clock.c file. In this application, the data structure for application is following:

      + +
      typedef struct appdata
      +{
      +   // Save the window
      +   Evas_Object *win;
      +} 
      +appdata_s;
      +
      + +

      The information in appdata is used for the entire system. In this sample application, the information is related to handling the HW back key.

      + +

      The single callback function for application handling is app_create, and it only creates the basic GUI:

      + +
      int
      +main(int argc, char *argv[])
      +{
      +   appdata_s *ad = {0,};
      +   app_event_callback_s event_callback = {0,};
      +   int ret = 0;
      +
      +   event_callback.create = app_create;
      +   event_callback.terminate = app_terminate;
      +   event_callback.pause = app_pause;
      +   event_callback.resume = app_resume;
      +   event_callback.app_control = app_control;
      +
      +   ui_app_add_event_handler(&handlers[APP_EVENT_LOW_BATTERY], APP_EVENT_LOW_BATTERY, ui_app_low_battery, &ad);
      +   ui_app_add_event_handler(&handlers[APP_EVENT_LOW_MEMORY], APP_EVENT_LOW_MEMORY, ui_app_low_memory, &ad);
      +   ui_app_add_event_handler(&handlers[APP_EVENT_DEVICE_ORIENTATION_CHANGED], APP_EVENT_DEVICE_ORIENTATION_CHANGED, ui_app_orient_changed, &ad);
      +   ui_app_add_event_handler(&handlers[APP_EVENT_LANGUAGE_CHANGED], APP_EVENT_LANGUAGE_CHANGED, ui_app_lang_changed, &ad);
      +   ui_app_add_event_handler(&handlers[APP_EVENT_REGION_FORMAT_CHANGED], APP_EVENT_REGION_FORMAT_CHANGED, ui_app_region_changed, &ad);
      +   ui_app_remove_event_handler(handlers[APP_EVENT_LOW_MEMORY]);
      +
      +   ret = app_main(argc, argv, &event_callback, &ad);
      +   if (ret != APP_ERROR_NONE) 
      +   {
      +      LOGE("app_main() is failed. err = %d", ret);
      +   }
      +
      +   return ret;
      +}
      +
      +static bool
      +app_create(void *data)
      +{
      +   appdata_s *ad = data;
      +   create_base_gui(ad);
      +
      +   return true;
      +}
      +
      + +

      The base GUI of the application contains the following elements:

      + +
        +
      • Clock
      • +
      • List
      • +
      • Main layout with buttons
      • +
      + +

      Clock

      + +

      The clock element contains 3 labels. The labels are packed as a single box component, which is part of the main layout.

      +
      static Evas_Object *
      +create_clock(Evas_Object *nf)
      +{
      +   Evas_Object *box, *label1, *label2, *label3;
      +
      +   // Box
      +   box = elm_box_add(nf);
      +
      +   label1 = elm_label_add(box);
      +   elm_object_text_set(label1, "<font_size=110><color=#000000>07:26</color></font_size>");
      +   elm_box_pack_end(box, label1);
      +   evas_object_show(label1);
      +
      +   evas_object_show(box);
      +
      +   return box;
      +}
      +
      + +

      List

      + +

      This element contains a list of cities. The UI component used is genlist, which is a complex list able to show information with various styles.

      +
      static Evas_Object *
      +create_list(Evas_Object *nf)
      +{
      +   Evas_Object* list;
      +   Elm_Genlist_Item_Class *itc = NULL;
      +   int i, num_of_item;
      +   Elm_Object_Item *it;
      +   
      +   list = elm_genlist_add(nf);
      +
      + +

      To add items to the list, use the Elm_Genlist_Item_Class class. After adding a new class, set callback function to detect, when the item is rendered.

      +
      itc = elm_genlist_item_class_new();
      +   itc->item_style = "2line.top.4";
      +   itc->func.text_get = gl_text_get_cb;
      +   itc->func.content_get = NULL;
      +   itc->func.del = NULL;
      +
      + +

      In this application, all the list items are similar and use the same callback function (gl_text_get_cb()) for setting text, so only 1 item class is created:

      +
      static char*
      +gl_text_get_cb(void *data, Evas_Object *obj, const char *part)
      +{
      +   item_data_s *id = data;
      +   char buf[1024];
      +
      +   if (id->index == 0) 
      +   {
      +      if (!strcmp(part, "elm.text.main.left.top")) 
      +      {
      +         snprintf(buf, 1023, "%s", "07:26");
      +
      +         return strdup(buf);
      +      }
      +      else if (!strcmp(part, "elm.text.sub.right.top")) 
      +      {
      +         snprintf(buf, 1023, "%s", "Cardiff");
      +
      +         return strdup(buf);
      +      }
      +      else if (!strcmp(part, "elm.text.sub.left.bottom")) 
      +      {
      +         snprintf(buf, 1023, "%s", "Wen, Jan 1");
      +
      +         return strdup(buf);
      +      }
      +      else if (!strcmp(part, "elm.text.sub.right.bottom")) 
      +      {
      +         snprintf(buf, 1023, "%s", "wales");
      +
      +         return strdup(buf);
      +      }
      +   }
      +
      +   return NULL;
      +}
      +
      + +

      Append items using the elm_genlist_item_append() function. In this application, 3 items are added:

      +
      num_of_item = 3;
      +
      +   for (i = 0; i < num_of_item; i++) 
      +   {
      +      item_data_s *id = calloc(sizeof(item_data_s), 1);
      +      id->index = i;
      +      it = elm_genlist_item_append(list,
      +                                   itc,
      +                                   id,
      +                                   NULL,
      +                                   ELM_GENLIST_ITEM_NONE,
      +                                   NULL,
      +                                   id);
      +      id->item = it;
      +   }
      +
      + +

      Main Layout with a Button

      + +

      In the main layout, the other layout elements are merged together and a button added. The following example describes handling the main layout:

      + +
      static void
      +create_base_gui(appdata_s *ad)
      +{
      +   Evas_Object *conform, *nf, *box, *clock, *layout, *rect, *button;
      +   // Window
      +   ad->win = elm_win_util_standard_add(PACKAGE, PACKAGE);
      +   elm_win_autodel_set(ad->win, EINA_TRUE);
      +
      +   // Conformant
      +   conform = elm_conformant_add(ad->win);
      +   elm_win_conformant_set(ad->win, EINA_TRUE);
      +   evas_object_size_hint_weight_set(conform, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +   elm_win_resize_object_add(ad->win, conform);
      +   evas_object_show(conform);
      +
      +   // Naviframe
      +   nf = elm_naviframe_add(conform);
      +   elm_object_content_set(conform, nf);
      +   evas_object_show(nf);
      +}
      +
      + +

      The box component is used to organize the main layout. The box is expanded as much as possible to fill the entire view.

      +
         // Box
      +   box = elm_box_add(nf);
      +   evas_object_size_hint_weight_set(box, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +   evas_object_size_hint_align_set(box, EVAS_HINT_FILL, EVAS_HINT_FILL);
      +
      + +

      The box contains the following elements:

      + +
        + +
      • The clock element contains 3 labels. The parameter for the evas_object_size_hint_weight_set() function is 0.1 meaning that the height of the clock box occupies 30% of the available area.

        +
           clock = create_clock(nf);
        +   evas_object_size_hint_weight_set(clock, EVAS_HINT_EXPAND, 0.3);
        +   evas_object_size_hint_align_set(clock, EVAS_HINT_FILL, EVAS_HINT_FILL);
        +   elm_box_pack_end(box, clock);
        +
        +
      • + +
      • The list element is packed into the box. As the genlist elements does not have a determined size, its size depends on the layout parameter.

        +
        +   layout = elm_layout_add(box);
        +   elm_layout_theme_set(layout, "layout", "application", "default");
        +   evas_object_size_hint_weight_set(layout, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
        +   evas_object_size_hint_align_set(layout, EVAS_HINT_FILL, EVAS_HINT_FILL);
        +   rect = create_list(nf);
        +   elm_layout_content_set(layout, "elm.swallow.content", rect);
        +   evas_object_show(rect);
        +   evas_object_show(layout);
        +   elm_box_pack_end(box, layout);
        +
        +
      • + +
      • The button element has a callback function to detect, when the button is clicked.

        +
        button = elm_button_add(box);
        +   evas_object_smart_callback_add(button, "clicked", btn_clicked_cb, NULL);
        +   evas_object_size_hint_weight_set(button, EVAS_HINT_EXPAND, 0.1);
        +   evas_object_size_hint_align_set(button, EVAS_HINT_FILL, EVAS_HINT_FILL);
        +   elm_object_text_set(button, "Terminate");
        +   evas_object_show(button);
        +   elm_box_pack_end(box, button);
        +
        +
      • +
      + +

      The following figure illustrates the UI component hierarchy of the application.

      + +

      Figure: Complex clock components

      +

      Complex clock components

      + +

      Add the main layout to the naviframe, and set the HW key handler:

      +
      eext_object_event_callback_add(ad->win, EEXT_CALLBACK_BACK, win_back_cb, ad);
      +
      + +

      After setting the callback function, the win_back_cb callback is invokes when a back key is pressed. The win_back_cb callback will hide the window:

      +
      static void
      +win_back_cb(void *data , int type , void *event)
      +{
      +   appdata_s *ad = data;
      +   elm_win_lower(ad->win);
      +}
      +
      + + + + +
      + +Go to top + + + + + + + diff --git a/org.tizen.ui.guides/html/native/efl/main_loop_n.htm b/org.tizen.ui.guides/html/native/efl/main_loop_n.htm new file mode 100755 index 0000000..0b1eb5e --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/main_loop_n.htm @@ -0,0 +1,409 @@ + + + + + + + + + + + + + Handling the Main Loop + + + + + +
      + +

      Handling the Main Loop

      + +

      The EFL is event-driven. This means that the application polls for data, and listens for events to interact with it.

      + +

      The Ecore library provides the main loop abstraction. It gets data when data is available and sends the events so that costly polling threads are not needed. Ecore manages polling, timers, events, and file descriptors. When there is no ongoing event, the main loop automatically enters an idle mode, minimizing the power consumption. The loop wakes up when needed.

      + +

      Starting the Main Loop

      + +

      To start the Ecore main loop and move your application into the running state, call the ui_app_main() function. The Ecore main loop handles all general events, such as touch, mouse, key, and network events.

      + +
      +int
      +main(int argc, char *argv[])
      +{
      +   ret = ui_app_main(argc, argv, &event_callback, &ad);
      +
      +   return ret;
      +}
      +
      + +

      When your application is running:

      +
      1. Create a window and organize the UI components inside the window.
      2. +
      3. Create the application logic code to be called when callbacks or timed events occurs (for example, animators for animations and timers for timeouts).
      + + +

      Timers

      + +

      Ecore provides timers, which schedule events that are executed later at a specific time. The event can occur once or several times at specific intervals.

      + +

      A timer callback prototype looks like the my_timed_cb() callback function. This function receives data from the application, and returns a Boolean value to specify whether it is called again or completed. The following macros are also provided:

      + +
        +
      • ECORE_CALLBACK_RENEW: the function is called again after the timeout.
      • +
      • ECORE_CALLBACK_CANCEL: the function is not called again, Ecore destroys automatically everything associated with the timer.
      • +
      + +

      To create and destroy a timer:

      + +
        +
      • To create a timer, use the ecore_timer_add() function. The interval, specified in seconds, indicates when the given function is called, and receives the specified data as a parameter. It returns an Ecore_Timer object. +

        In the following example, the my_timed_cb() function is run after 2 seconds and it receives my_data. It is renewed while its count variable value is under 5, and stops after that.

        +
        +Eina_Bool my_timed_cb(void *data)
        +{
        +   static int count = 0;
        +   count++;
        +
        +   if (count < 5) 
        +      return ECORE_CALLBACK_RENEW;
        +
        +   return ECORE_CALLBACK_CANCEL;
        +}
        +ecore_timer_add(2.0, my_timed_cb, my_data);
        +
        +
      • + +
      • To delete the timer, use the ecore_timer_del() function. The timer to delete must still be running, that is, it has not returned a false value. If the timer is not running, the function cannot be called.
      • +
      + +

      To manage a timer:

      +
        +
      • To change the timer's interval, use the ecore_timer_interval_set() function. The interval is specified in seconds. If set during a timer call, this affects the next interval. Use the ecore_timer_interval_get() function to get the timer's current interval.
      • + +
      • To get the timer's pending time, use the ecore_timer_pending_get() function.
      • + +
      • To delay the timer's next occurrence, use the ecore_timer_delay() function. The function adds the specified time to the current interval. It does not change the future occurrences' interval. You can also reset the current interval to its full value by using the ecore_timer_reset() function.
      • + +
      • To pause the currently running timer, use the ecore_timer_freeze() function. The remaining time is saved and used again when the timer is resumed with the ecore_timer_thaw() function.
      • + +
      • To query the current value of the defined timer infrastructure precision, use the ecore_timer_precision_get() function. A higher delay means that more timers can be run together. It diminishes the need to use system wake-ups and thus lowers the power consumption. +

        To set the precision, use the ecore_timer_precision_set() function. This sets the precision for all timers. For example, there are 2 timers, one that expires in 2.0 seconds and another that expires in 2.1 seconds. If the precision is set to 0.1 seconds, Ecore requests the next expiration to happen in 2.1 seconds and runs both callbacks at once, instead of one at 2.0 seconds and the other one 0.1 seconds later. However, if there is no timer expiring in 2.1 seconds, the timeout is at the minimum interval, 2 seconds.

      • +
      + +

      Animators

      + +

      Animators are a specific type of timer, specially designed for on-screen animation purposes:

      + +
        +
      • The time interval is usually known when they are created.
      • +
      • They are called at each screen refresh and their interval can vary. The interval can depend on the system load, the target power consumption, and other factors. The exact interval is not relevant.
      • +
      + +

      To implement animators, Ecore provides the Ecore animator subsystem.

      + +

      Forever-running Animator

      + +

      To create an animation that runs for an indefinite time:

      + +
      +Eina_Bool my_anim_cb(void *data)
      +{
      +   static int count = 0;
      +   count++;
      +   if (count < 5) 
      +      return ECORE_CALLBACK_RENEW;
      +
      +   return ECORE_CALLBACK_CANCEL;
      +}
      +ecore_animator_add(my_anim_cb, my_data);
      +
      + +

      This example looks the same as the one using an Ecore timer. The ecore_animator_add() function takes the callback function and data to pass to it, and returns an Ecore_Animator object. The function is called at a system-defined interval until it returns ECORE_CALLBACK_CANCEL instead of ECORE_CALLBACK_RENEW.

      + +

      Specific-duration Animator

      + +

      An animator callback for an animator running a specific time has a different prototype than the forever running animator.

      + +

      This callback function receives both data and a position which represents the current time among the full timeline, 0 meaning the beginning of the animation, and 1 meaning the end of the animation, returning ECORE_CALLBACK_CANCEL to abort, or ECORE_CALLBACK_RENEW to continue.

      + +

      To create and destroy the animator:

      +
        +
      • To create the animator, use the ecore_animator_timeline_add() function. The first parameter specifies the animator duration, the second parameter is the callback function, and the third parameter is the data to pass to the callback. The data parameter is optional. +
        +Eina_Bool my_anim_cb(void *data, double position)
        +{
        +   if (position < .5) 
        +      return ECORE_CALLBACK_RENEW;
        +
        +   return ECORE_CALLBACK_CANCEL;
        +}
        +ecore_animator_timeline_add(5., my_anim_cb, my_data);
        +
        + +

        In this example, the animator is specified to run for five seconds. The function returns ECORE_CALLBACK_CANCEL as soon as the position among the timeline passes half of the duration, 2.5 seconds.

        + +

        Ecore can generate a virtual position from the original one using ecore_animator_pos_map(position, map, v1, v2). Several maps are available:

        + +
          +
        • ECORE_POS_MAP_LINEAR: linear from 0.0 to 1.0.
        • +
        • ECORE_POS_MAP_ACCELERATE: start slow, then speed up.
        • +
        • ECORE_POS_MAP_DECELERATE: start fast, then slow down.
        • +
        • ECORE_POS_MAP_SINUSOIDAL: start slow, speed up, then slow down at the end.
        • +
        • ECORE_POS_MAP_ACCELERATE_FACTOR: start slow, then speed up, v1 being a power factor: 0.0 is linear, 1.0 is standard acceleration, 2.0 is a much more pronounced acceleration (squared), and 3.0 is cubed.
        • +
        • ECORE_POS_MAP_DECELERATE_FACTOR: start fast, then slow down, v1 being a power factor: 0.0 is linear, 1.0 is standard deceleration, 2.0 is a much more pronounced deceleration (squared), and 3.0 is cubed.
        • +
        • ECORE_POS_MAP_SINUSOIDAL_FACTOR: start slow, speed up, then slow down at the end, v1 being a power factor: 0.0 is linear, 1.0 is a standard sinusoidal, 2.0 is a much more pronounced sinusoidal (squared), and 3.0 is cubed.
        • +
        • ECORE_POS_MAP_DIVISOR_INTERP: start at gradient * v1, interpolated with the power of v2 curve.
        • +
        • ECORE_POS_MAP_BOUNCE: start at 0.0, then drop like a ball bouncing to the ground at 1.0, and bounce v2 times, with a decay factor of v1.
        • +
        • ECORE_POS_MAP_SPRING: start at 0.0, then wobble like a spring to the rest position 1.0, and wobble v2 times, with a decay factor of v1.
        • +
        + +

        Figure: Position maps

        +

        Position maps

        +
      • + +
      • To destroy the animator, use the ecore_animator_del() function. The animator to destroy must be running, that is, it has not returned a false value. If the animator is not running, the function cannot be called.
      • +
      + +

      To manage the animator:

      +
        +
      • To pause the currently running animator, use the ecore_animator_freeze() function. Note that time continues ticking even if the animator is frozen, and that resuming the animation using the ecore_animator_thaw() function does not actually resume, if the full runtime has been passed in the meanwhile.
      • + +
      • To query Ecore for the interval between 2 animator calls, use the ecore_animator_frametime_get() function.
      • + +
      • To change the interval, use the ecore_animator_frametime_set(interval) function. Note that too small a value causes performance and power consumption issues, and too high a value makes the animation jerky.
      • +
      + +

      File Descriptors

      + +

      Ecore provides an infrastructure to monitor file descriptors, so that files do not have to be blocked or polled to read or write on them. Instead, monitor sockets, pipes, or other streams are used to get a file descriptor.

      + +

      To manage the file descriptors:

      +
        +
      • To set a callback, use the _my_cb_func() function. Its first parameter is the data passed to it (optional), and the second one is the Ecore file descriptor handler. Its return value is, as in most Ecore callbacks, ECORE_CALLBACK_RENEW or ECORE_CALLBACK_CANCEL. It tells Ecore whether it wants to be called again or whether its treatment is finished.
      • + +
      • To listen to events, use the ecore_main_fd_handler_add() function.
      • + +
      • To wait for incoming data (that is, to read data) on the my_fd file descriptor, passing my_data: + +
        +Eina_Bool my_fd_cb(void *data, Ecore_Fd_Handler *handler)
        +{
        +   int fd;
        +   fd = ecore_main_fd_handler_fd_get(handler);
        +   count = read(fd, buf, sizeof(buf)); // This is guaranteed not to block
        +
        +   return ECORE_CALLBACK_RENEW;
        +}
        +ecore_main_fd_handler_add(my_fd, ECORE_FD_READ, my_fd_cb, my_data, NULL, NULL);
        +
        +
      • + +
      • To delete a file descriptor handler, use the ecore_main_fd_handler_del() function. This does not close the file descriptor. Always delete the handlers before closing the actual file descriptors.
      • + +
      • To get the handler's file descriptor, use the ecore_main_fd_handler_fd_get() function.
      • + +
      • To select whether a flag is active on a handler, use the ecore_main_fd_handler_active_get() function. For example, the handler is set to monitor both ECORE_FD_READ and ECORE_FD_ERROR. The following example finds out whether the function was called because of an error: + +
        +Eina_Bool my_fd_cb(void *data, Ecore_Fd_Handler *handler)
        +{
        +   int fd;
        +   fd = ecore_main_fd_handler_fd_get(handler);
        +   if (ecore_main_fd_handler_active_get(handler, ECORE_FD_ERROR) == EINA_TRUE) 
        +   {
        +      // We have an error!
        +
        +      return ECORE_CALLBACK_CANCEL;
        +   }
        +   count = read(fd, buf, sizeof(buf)); // This is guaranteed not to block
        +
        +   return ECORE_CALLBACK_RENEW;
        +}
        +ecore_main_fd_handler_add(my_fd, ECORE_FD_READ | ECORE_FD_ERROR, my_fd_cb, my_data, NULL, NULL);
        +
        +
      • + +
      • To change the flags the handler is monitoring, use the ecore_main_fd_handler_active_set() function.
      • +
      + +

      Threads

      + +

      EFL is not entirely thread-safe. This means that if a task is running in another thread and, for example, an Evas object shows the status progress of this task, the object cannot be updated from within the thread. Updating can only be done from the main thread that runs the main loop.

      + +

      Ecore provides a facility to perform tasks on separate worker threads. It is not a simple wrapper around standard threads provided by the operating system. With Ecore threads, it is easier to dispatch a worker function to perform some heavy tasks and get the result once it completes. It does not block the application UI. It is also easy to cancel and reschedule threads. Several threads can be launched simultaneously, since Ecore schedules them according to the number of processors the system has and the maximum amount of concurrent threads set for the application.

      + +

      Ecore has 2 kinds of threads:

      +
        +
      • Short jobs do not give any kind of information on their status to the parent. They are best used for short computing-intensive snippets of code.
      • +
      • Feedback jobs give information on their status to the parent. They are best used for longer snippets requiring a feedback loop, such as an ongoing file download.
      • +
      + +

      Ecore creates a pool of worker threads. The exact count is computed from the number of CPUs or cores, or it can be specified by the application itself.

      + +

      When a worker thread is idle, it picks a job to execute from the waiting list until there is none left. In the following example, there are 2 threads defined by my_short_job() and my_feedback_job(). Both threads take 2 parameters: some data passed to them, and the actual thread running. Call a callback when the jobs end, whether they are cancelled (my_job_cancel()) or end normally (my_job_end()).

      + +
      +struct feedback_msg
      +{
      +   int pos;
      +};
      +
      +void my_short_job(void *data, Ecore_Thread *thread)
      +{
      +   usleep(200000);
      +}
      +
      +void my_feedback_job(void *data, Ecore_Thread *thread)
      +{
      +   int i;
      +   for (i = 0; i < 100; i++) 
      +   {
      +      usleep(50000); // You can have some real computation done
      +      struct feedback_msg *message = malloc(sizeof(struct feedback_msg));
      +      if (message) 
      +      {
      +         message->pos = i;
      +         ecore_thread_feedback(thread, message);
      +      }
      +      if (ecore_thread_check(thread))
      +         return;
      +   }
      +}
      +
      +void my_feedback_job_notify(void *data, Ecore_Thread *thread, void *msg)
      +{
      +   struct feedback_msg *message = msg;
      +   free(message);
      +}
      +
      +void my_job_end(void *data, Ecore_Thread *thread)
      +{
      +   dlog_print(DLOG_INFO, LOG_TAG, "Thread has normally ended.\n");
      +}
      +
      +void my_job_cancel(void *data, Ecore_Thread *thread)
      +{
      +   dlog_print(DLOG_INFO, LOG_TAG, "Thread has been cancelled.\n");
      +}
      +
      +ecore_thread_run(my_short_job, my_job_end, my_job_cancel, my_data);
      +ecore_thread_feedback_run(my_feedback_job, my_feedback_job_notify, my_job_end, 
      +                          my_job_cancel, my_data, EINA_FALSE);
      +
      + +

      To manage threads:

      + +
        +
      • To cancel a thread, use the ecore_thread_cancel() function. However, note that this is done cooperatively: the thread continues to run until it exists. Call the ecore_thread_check() function regularly to check whether the thread has been marked for cancellation and exit if true.
      • + +
      • To run threads that are not accounted for in the worker thread pool, use the ecore_thread_feedback_run() function with the last parameter set to EINA_TRUE. + +

        The feedback message a thread sends as notification can be any kind of data. In the above example, it is a simple integer, but it can be as complex as needed.

        +
      • + +
      • To execute a thread later, use the ecore_thread_reschedule() function. This function is added to the end of the pending tasks.
      • + +
      • To get the maximum number of concurrent threads, use the ecore_thread_max_get() function. If needed, set it by using the ecore_thread_max_set() function, or reset the default value using the ecore_thread_max_reset() function.
      • + +
      • To query the number of active threads, use the ecore_thread_active_get() function. To query the number of available worker threads, use the ecore_thread_available_get() function, which is basically the same as the ecore_thread_max_get() - ecore_thread_active_get().
      • +
      + +

      Idlers

      + +

      When the rendering is done and all work is finished, the main loop enters its idle state until the next loop. You can get the functions of your application called back before the main loop enters or exits the idle state, or when it is in the idle state. They are respectively called Ecore_Idle_Enterer, Ecore_Idle_Exiter, and Ecore_Idler.

      + +

      Figure: Idle loop

      +

      Idle loop

      + +

      The idle enterers, exiters, and idlers all have the same prototype, my_idler(), which receives data and returns ECORE_CALLBACK_RENEW or ECORE_CALLBACK_CANCEL to tell Ecore whether it wants to be called again or is finished.

      + +

      To manage the idlers:

      +
        +
      • To add an idler, use the ecore_idler_add() function.
      • +
      • To delete an idler, use the ecore_idler_del() function.
      • + +
      • To add and delete idle exiters, use the ecore_idle_exiter_add() and ecore_idle_exiter_del() functions.
      • + +
      • To add and delete idle enterers, use the ecore_idle_enterer_add() and ecore_idle_enterer_del() functions. The ecore_idle_enterer_before_add() function is also available, if you want your function to be added at the top of the list so that it is called before the others.
      • +
      + +
      +Eina_Bool my_idle_enterer_cb(void *data)
      +{
      +   return ECORE_CALLBACK_RENEW;
      +}
      +
      +Eina_Bool my_idle_exiter_cb(void *data)
      +{
      +   return ECORE_CALLBACK_CANCEL;
      +}
      +
      +Eina_Bool my_idler(void *data)
      +{
      +   return ECORE_CALLBACK_RENEW;
      +}
      +
      +ecore_idle_enterer_add(my_idle_enterer_cb, my_data);
      +ecore_idle_exiter_add(my_idle_exiter_cb, my_data);
      +ecore_idler_add(my_idler_cb, my_data);
      +
      + + + + + + + + + + +
      Note
      Except as noted, this content is licensed under LGPLv2.1+.
      + + + +
      + +Go to top + + + + + + + \ No newline at end of file diff --git a/org.tizen.ui.guides/html/native/efl/menu_tutorial_mn.htm b/org.tizen.ui.guides/html/native/efl/menu_tutorial_mn.htm new file mode 100755 index 0000000..2ea5471 --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/menu_tutorial_mn.htm @@ -0,0 +1,541 @@ + + + + + + + + + + + + + + Creating Mobile Menus + + + + + + +
      +

      Creating Mobile Menus

      + + +

      This tutorial shows how to add menus to the application. The example code creates an application with 3 views, these views are showed by an interaction with a menu bar, placed on the top of the application. The application has also a hidden menu that appears only when the menu button is pressed.

      + + + + + + + + + + +
      Note
      This feature is supported in mobile applications only.
      + + +

      Defining the Application "Structure"

      + +

      Define the structure of the application:

      +
      typedef struct appdata
      +{
      +   Evas_Object* win; // The main window
      +   Evas_Object* layout; // The Edje layout
      +   Evas_Object* conform; // The conform
      +   Evas_Object *nf; // The Naviframe to handle the views
      +   appmenu_s *menu; // The main menu
      +   appmenu_s *sidemenu; // The side menu
      +   mainview_s *main_view; // The main view (dayselector)
      +   calview_s *cal_view; // The calendar view
      +   dateview_s *date_view; // The date and time view
      +   settview_s *settings_view; // The settings view
      +   Eina_Bool sdmenu_up; // A Boolean variable to keep the side menu status
      +} appdata_s;
      +
      +

      This structure contains some specific variables for the views and the menus.

      +

      Define the main view by using the structure mainview, it is composed of a box (the main container), a dayselector, an image img, and a label lb_main.

      +
      typedef struct mainview
      +{
      +   Evas_Object *box; // The main container of the view
      +   Evas_Object *colorselector; // A color selector
      +   Evas_Object *img; // An image 
      +   Evas_Object *lb_day; // A label
      +} mainview_s;
      +
      +

      The date view is very similar, it contains a box, a datetime component and a label lb_date.

      +
      typedef struct dateview
      +{
      +   Evas_Object *box; // The main container of the view 
      +   Evas_Object *datetime; // A datetime component 
      +   Evas_Object *lb_date; // A label 
      +} dateview_s;
      +
      +

      The last view is the calendar, it contains a box, a calendar and a label lb_cal.

      +
      typedef struct calview
      +{
      +   Evas_Object *box; // The main container of the view 
      +   Evas_Object *calendar; // A calendar component  
      +   Evas_Object *lb_cal; // A label component
      +} calview_s;
      +
      +

      The last members of the application structure are the 2 menus. The main menu is fixed and visible, and the side menu is hidden on application starts. These menus are represented by the appmenu structure.

      +
      typedef struct appmenu
      +{
      +   Evas_Object *tb; // The toolbar
      +   Elm_Object_Item *submenu; // The submenu item
      +} appmenu_s;
      +
      + +

      Defining the Application Theme

      + +

      After the structure is defined, define the UI. In this tutorial, Basic EDC UI Application is used.

      +

      This application structure is based on this skeleton:

      + +

      Figure: Menu skeleton

      +

      Menu skeleton

      + + +

      The window, the conformant and the layout are set by the Basic EDC UI Application skeleton. Setup the containers for UI components and views.

      +

      Create the main_menu SWALLOW part in the .edc file.

      +
      +part
      +{
      +   name: "menu/main";
      +   type: SWALLOW;            
      +   description 
      +   {
      +      state: "default" 0.0;
      +      rel1.relative: 0.0 1.0;
      +      rel2.relative: 1.0 1.0;
      +   }
      +   description 
      +   {
      +      state: "up" 0.0;
      +      rel1.relative: 0.0 0.01;
      +      rel2.relative: 1.0 0.18;
      +      
      +   }
      +} // End menu/main
      +
      +

      This part has two descriptions, one for the real position named up and another out of the screen as the default position. Create these states to animate the menu on application start. The animation is run by animation,menu_main.

      +
      program
      +{ 
      +   name: "animation,menu_main";
      +   source: "";
      +   signal: "load";
      +   action: STATE_SET "up" 1.0;
      +   target: "menu/main";
      +   transition: LINEAR 0.5;
      +} // END animation,menu_main
      +
      +

      For more information about animations, see the Effects tutorial.

      +

      Create another container for the views. This container is also a "SWALLOW" part.

      +
      part 
      +{
      +   name: "view/main";
      +   type: SWALLOW;            
      +   description 
      +   {
      +      state: "default" 0.0;
      +      rel1.relative: 0.0 1.0;
      +      rel2.relative: 1.0 1.0;
      +   }
      +   description 
      +   {
      +      state: "up" 0.0;
      +      rel1.relative: 0.0 1.1;
      +      rel1.to: "menu/main";
      +      rel2.relative: 1.0 1.0;
      +      color: 0 255 0 255; 
      +   }
      +} // END view/main 
      +
      +

      This part has also two descriptions for animation purpose, like the main_menu part.

      +

      The program:

      +
      program 
      +{ 
      +   name: "animation,view_main";
      +   source: "";
      +   signal: "load";
      +   action: STATE_SET "up" 1.0;
      +   target: "view/main";
      +   transition: LINEAR 0.2;
      +} // END animation,view_main
      +
      +

      The last container is the side menu called menu/side.

      +
      +part 
      +{ 
      +   name: "menu/side";
      +   type: SWALLOW;
      +   description 
      +   { 
      +      state: "default" 0.0;
      +      rel1.relative: -0.3 0.0;
      +      rel2.relative: -0.3 1.0;
      +      color: 255 0 0 255; 
      +   }
      +   description 
      +   {
      +      state: "up" 0.0;
      +      rel1.relative: 0.0 0.01;
      +      rel2.relative: 0.3 1.0;
      +     color: 255 0 0 255;
      +   }
      +} // END menu/side
      +
      +

      By default, this container is hidden. Clicking menu button makes it appear. The second description places the container on the left of the screen. Here is the program to run animation:

      +
      + program 
      +{ 
      +   name: "animation,menu_side";
      +   source: "MenuButton";
      +   signal: "show,sidemenu";
      +   action: STATE_SET "up" 1.0;
      +   target: "menu/side";
      +   transition: LINEAR 0.2;
      +} // END animation,menu_side
      +
      +

      This program runs when it receives an event called show,sidemenu from MenuButton source.

      +

      Create a program that does the opposite and starts when it receives a signal called hide,menu_side from MenuButton source.

      +
      +program 
      +{ 
      +   name: "animation,menu_side,hide";
      +   source: "MenuButton";
      +   signal: "hide,sidemenu";
      +   action: STATE_SET "default" 1.0;
      +   target: "menu/side";
      +   transition: LINEAR 0.2;
      +} // END animation,menu_side,hide
      +
      +program 
      +{ 
      +   name: "animation,menu_side";
      +   source: "MenuButton";
      +   signal: "show,sidemenu";
      +   action: STATE_SET "up" 1.0;
      +   target: "menu/side";
      +   transition: LINEAR 0.2;
      +} // END animation,menu_side
      +
      + +

      Creating the Basic UI

      + +

      The view container view/main is structured like this:

      + + +

      Figure: Main view

      +

      Main view

      + +

      The naviframe contains and manages the boxes. For more information, see the Container programming guide. This UI component handle views. In this example each view is contained in a box and the box is contained in the naviframe.

      +

      Create the naviframe in the create_base_gui function and allocate the memory to handle the views and menus of the application.

      +
      +// Memory allocation
      +ad->main_view = calloc(1, sizeof(mainview_s)); // Allocating memory for the main view 
      +ad->cal_view = calloc(1, sizeof(calview_s));   // Allocating memory for the calendar view 
      +ad->date_view = calloc(1, sizeof(dateview_s)); // allocating memory for the date view 
      +ad->settings_view = calloc(1, sizeof(settview_s)); // allocating memory for the Settings view
      +// END of Memory allocation
      +
      +

      Use app_terminate function to free the memory:

      +
      app_terminate(void *data)
      +{
      +   // Release all resources
      +   appdata_s *ad = data;
      +
      +   free(ad->menu);
      +   free(ad->sidemenu);
      +   free(ad->main_view);
      +   free(ad->cal_view);
      +   free(ad->settings_view);
      +} // END of app_terminate
      +
      +

      Create the naviframe:

      + +

      Create the main menu after most of the containers are created. First create a new _build_main_menu function, it takes an appdata_s as a parameter. This function is called by create_base_gui.

      +
      static void _build_main_menu(appdata_s *ad)
      +{
      +   // Memory allocation for the main menu function
      +   appmenu_s *menu = calloc(1, sizeof(appmenu_s));
      +   // Putting the "main" menu in the application data
      +   ad->menu = menu;
      +
      +   // Creation of the "Menu" toolbar
      +   menu->tb = elm_toolbar_add(ad->win);
      +
      +   // Setting the "Menu" Toolbar properties
      +   elm_toolbar_shrink_mode_set(menu->tb, ELM_TOOLBAR_SHRINK_NONE);
      +   elm_toolbar_transverse_expanded_set(menu->tb, EINA_TRUE);
      +   elm_toolbar_homogeneous_set(menu->tb, EINA_FALSE);
      +
      +   // Adding menu items to the "Menu" toolbar
      +   elm_toolbar_item_append(menu->tb, ICON_DIR"/home.png", "Home", _menu_item_selected_cb, ad);
      +   elm_toolbar_item_append(menu->tb, ICON_DIR"/calendar.png", "Calendar", _menu_item_selected_cb, ad);
      +   elm_toolbar_item_append(menu->tb, ICON_DIR"/clock.png", "Date", _menu_item_selected_cb, ad);
      +   elm_toolbar_item_append(menu->tb, ICON_DIR"/settings.png", "Settings", _menu_item_selected_cb, ad);
      +
      +   // Showing the UI component
      +   evas_object_show(menu->tb);
      +
      +   // Adding the UI component to the "menu/main" SWALLOW container defined in the .edc theme file.
      +   elm_object_part_content_set(ad->layout, "menu/main", menu->tb);
      +
      +   // Set the default view 
      +   elm_toolbar_item_selected_set(elm_toolbar_first_item_get(menu->tb), EINA_TRUE);
      +}
      +
      +

      Create a toolbar with elm_toolbar_add. This toolbar is a child of the main window so set ad->win as parameter.

      +

      Setup the behavior of the toolbar, the display mode is set by using elm_toolbar_shrink_mode_set. The toolbar does not scroll under #ELM_TOOLBAR_SHRINK_NONE mode, but it enforces a minimum size, so that all the items fit inside it. It does not scroll or show the items that do not fit under #ELM_TOOLBAR_SHRINK_HIDE mode. Finally, it scrolls under #ELM_TOOLBAR_SHRINK_SCROLL mode, and it creates a button to aggregate items which did not fit with the #ELM_TOOLBAR_SHRINK_MENU mode.

      + +

      In this example, there is only a limited number of menu elements and thus ELM_TOOLBAR_SHRINK_NONE is used.

      + +

      Expand the transverse length of the item according the transverse length of the toolbar, giving EINA_TRUE as second parameter of elm_toolbar_transverse_expanded_set.

      + +

      Make the menu items have the same size by setting EINA_TRUE to elm_toolbar_homogeneous_set. This activates the homogeneous mode of the toolbar.

      +

      Add menu items to the toolbar using elm_toolbar_item_append. This function takes 4 parameters:

      +
        +
      • the target toolbar
      • +
      • the icon path for the menu item
      • +
      • the item label
      • +
      • the function to call when the item is clicked
      • +
      • the data to associate with the item for related callbacks.
      • +
      +

      For the icons, add some images in the resource directory of the application res/images and define a macro to contain this path in the application .h file. In this example it is inc/menututorial.h.

      + +
      #define ICON_DIR "/opt/usr/apps/"PACKAGE"/res/images"
      +
      +

      Use the PACKAGE macro to setup this ICON_DIR macro. This way you can add items to the toolbar using icon images placed in the resource directory of the application.

      + +

      The item label is very important, it is used in the item callback function.

      + +

      In this example, only one callback is created to manage all the items but there can be several callback functions. Pass the application data to the callback.

      + +

      This callback is an Evas_Smart_Cb, it must have this prototype:

      +
      +_mycallback(void *data, Evas_Object *obj, void *ev)
      +
      + +

      In this example, the aim of the callback is to create the view which the user has requested. It is named _menu_item_selected_cb, and in this function we recover the calling object text to call the correct view creation function.

      +
      +it = ev;
      +
      +// Get the menu item text
      +str = elm_object_item_text_get(it);
      +
      +// Comparing with the possible view names
      +if (!strcmp(str, "Calendar")) 
      +{
      +   // Build the "Calendar View"
      +   _build_calendar_view(ad);
      +   // Set the view from the application data
      +   view = ad->cal_view->box;
      +}
      +else if (!strcmp(str, "Date")) 
      +{
      +   // Build the "Date View"
      +   _build_date_view(ad);
      +   // Set the view from the application data
      +   view = ad->date_view->box;
      +}
      +else if (!strcmp(str, "Home")) 
      +{
      +   // Build the "Home or main View"
      +   _build_main_view(ad);
      +   // Set the view from the application data
      +   view = ad->main_view->box;
      +}
      +else if (!strcmp(str, "Settings")) 
      +{
      +   // Build the "Settings" view
      +   _build_settings_view(ad);
      +   // Set the view from the application data
      +   view = ad->settings_view->box;
      +}
      +else if (!strcmp(str, "Clock")) 
      +{
      +   // Build the "Date View" 
      +   _build_date_view(ad);
      +   // Set the view from the application data
      +   view = ad->date_view->box;
      +}
      +
      +// Show the view in the naviframe 
      +elm_object_content_set(ad->nf, view);
      +
      +

      The menu has views, Calendar, Date, Settings, and Home (main view). The view names are stored in the menu item label, to get the label compare the returned string with the view names. When the name matches, the view is built by calling the correct function. Store the view in the application data and set up a new content to the naviframe before exit.

      +

      This way when the user clicks a menu item, the view changes. The naviframe component destroys its content on each call of elm_object_content_set. That is why the content must be built again on each item click.

      +

      Create the functions which create the views.

      +
      static void _build_main_view(appdata_s *ad)
      +{
      +   mainview_s *view = ad->main_view;
      +   char buf[PATH_MAX];
      +
      +   // Main box
      +   view->box = elm_box_add(ad->nf);
      +   elm_box_horizontal_set(view->box, EINA_FALSE);
      +   elm_box_homogeneous_set(view->box, EINA_TRUE);
      +
      +   view->colorselector = elm_colorselector_add(view->box);
      +   elm_colorselector_mode_set(view->colorselector, ELM_COLORSELECTOR_PALETTE);
      +   elm_box_pack_start(view->box, view->colorselector);
      +   evas_object_show(view->colorselector);
      +
      +   view->img = elm_image_add(view->box);
      +   evas_object_size_hint_weight_set(view->img, EVAS_HINT_FILL, EVAS_HINT_FILL);
      +   evas_object_size_hint_align_set(view->img, 0.5, 0.5);
      +   evas_object_size_hint_min_set(view->img, 256, 256);
      +   ;snprintf(buf, sizeof(buf), "%s/%s", ICON_DIR, "tizen-logo.png");
      +   if (!elm_image_file_set(view->img, buf, NULL))
      +      elm_object_text_set(view->lb_day, "Problem loading image");
      +   elm_box_pack_start(view->box, view->img);
      +   evas_object_show(view->img);
      +
      +   view->lb_day = elm_label_add(view->box);
      +   elm_object_text_set(view->lb_day, "Main view");
      +   evas_object_size_hint_weight_set(view->lb_day, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +   elm_box_pack_end(view->box, view->lb_day);
      +   evas_object_show(view->lb_day);
      +}
      +
      +static void
      +_build_calendar_view(appdata_s *ad)
      +{
      +   calview_s *view = ad->cal_view;
      +
      +   // Main box image = elm_image_add(win);
      +
      +   view->box = elm_box_add(ad->nf);
      +   elm_box_horizontal_set(view->box, EINA_FALSE);
      +   elm_box_homogeneous_set(view->box, EINA_TRUE);
      +
      +   view->calendar = elm_image_add(ad->nf);
      +   evas_object_size_hint_weight_set(view->calendar, EVAS_HINT_FILL, EVAS_HINT_FILL);
      +   evas_object_size_hint_align_set(view->calendar, 0.5, 0.5);
      +   evas_object_size_hint_min_set(view->calendar, 256, 256);
      +   elm_image_file_set(view->calendar, ICON_DIR"/calendar.png", NULL);
      +   elm_box_pack_start(view->box, view->calendar);
      +   evas_object_show(view->calendar);
      +
      +   view->lb_cal = elm_label_add(view->box);
      +   elm_object_text_set(view->lb_cal, "The calendar view");
      +   evas_object_size_hint_weight_set(view->lb_cal, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +   elm_box_pack_end(view->box, view->lb_cal);
      +   evas_object_show(view->lb_cal);
      +} // End of_build_calendar_view
      +
      +

      Each function creates a view and stores it in the application data.

      + +

      Creating a Hidden Menu

      + +

      Add a new function called _build_side_menu to create the side Menu toolbar and add some items to it. This function takes the application data as parameter and stores the built menu in the sidemenu attribute of the structure.

      +
      static void _build_side_menu(appdata_s *ad)
      +{
      +   appmenu_s *sidemenu = calloc(1, sizeof(appmenu_s));
      +   ad->sidemenu = sidemenu;
      +
      +   sidemenu->tb = elm_toolbar_add(ad->win);
      +
      +   elm_toolbar_shrink_mode_set(sidemenu->tb, ELM_TOOLBAR_SHRINK_EXPAND);
      +   elm_toolbar_transverse_expanded_set(sidemenu->tb, EINA_TRUE);
      +
      +   elm_toolbar_item_append(sidemenu->tb, ICON_DIR"/home.png", "Home", _menu_item_selected_cb, ad);
      +   elm_toolbar_item_append(sidemenu->tb, ICON_DIR"/account.png", "Account", NULL, NULL);
      +   elm_toolbar_item_append(sidemenu->tb, ICON_DIR"/contacts.png", "Friends", NULL, NULL);
      +   elm_toolbar_item_append(sidemenu->tb, ICON_DIR"/clock.png", "Clock", _menu_item_selected_cb, ad);
      +   elm_toolbar_homogeneous_set(sidemenu->tb, EINA_FALSE);
      +   evas_object_show(sidemenu->tb);
      +   elm_object_part_content_set(ad->layout, "menu/side", sidemenu->tb);
      +   elm_toolbar_horizontal_set(sidemenu->tb, EINA_FALSE);
      +   elm_toolbar_item_selected_set(elm_toolbar_first_item_get(sidemenu->tb), EINA_TRUE);
      +}
      +
      +

      The side menu is created but hidden by default, to make it appear the use must click Home button.

      + +

      By default the Basic EDC UI application creates a function keydown_cb to handle the key down events. In the create_base_gui function an ecore_event_handler_add function is called with the ECORE_EVENT_KEY_DOWN macro and with keydown_cb as callback. In this callback, the KEY_END event puts the window on the lower state.

      +
      keydown_cb(void *data , int type , void *event)
      +{
      +   appdata_s *ad = data;
      +   Ecore_Event_Key *ev = event;
      +   if (!strcmp(ev->keyname, KEY_END)) 
      +   {
      +      // Let window go to hide state
      +      elm_win_lower(ad->win);
      +   }
      +
      +   return ECORE_CALLBACK_DONE;
      +}
      +
      +

      The key name of menu button is XF86Send. Add the menu button key press handling to the keydown_cb. The menu is shown on the first press and hidden it on the second press. Use Eina_Bool sdmenu_up on the application data to store the menu status during the application execution. If ad->sdmenu_up is EINA_TRUE the menu is visible.

      + +

      A program animation,menu_side is defined in the .edc theme file. This program is run when the signal show,sidemenu is received with the source MenuButton. Also the program who hides the side menu is defined and is called animation,menu_side,hide which start on signal hide,sidemenu.

      + +

      Test side menu status by sending the signals using elm_object_signal_emit

      +
      +if (!strcmp(ev->keyname, "XF86Send")) 
      +{
      +   if (ad->sdmenu_up == EINA_TRUE) 
      +   {
      +      // If the menu is visible send a "hide,sidemenu" signal
      +      elm_object_signal_emit(ad->layout, "hide,sidemenu", "MenuButton");
      +      // Store the new menu status (hidden)
      +      ad->sdmenu_up = EINA_FALSE;
      +   }
      +}
      +
      +

      Now the menu appears and disappears when the menu button is pressed.

      +

      The first side menu button sends back to the main view:

      +
      +// Hide the side menu if it's visible
      +if (ad->sdmenu_up == EINA_TRUE) 
      +{
      +   elm_object_signal_emit(ad->layout, "hide,sidemenu", "MenuButton");
      +      ad->sdmenu_up = EINA_FALSE;
      +}
      +
      +

      This way the menu disappears when the view is selected by the user.

      + + + + +
      + +Go to top + + + + + + + diff --git a/org.tizen.ui.guides/html/native/efl/multiple_screens_n.htm b/org.tizen.ui.guides/html/native/efl/multiple_screens_n.htm new file mode 100755 index 0000000..9fe2826 --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/multiple_screens_n.htm @@ -0,0 +1,261 @@ + + + + + + + + + + + + + Multiple Screen Support + + + + + +
      + +

      Multiple Screen Support

      + +

      Tizen is available in various devices which support different screen sizes and resolutions. When developing Tizen applications, you must take this into account if you want your application to function well in various device models.

      +

      Before implementing multiple screen support, make sure you are familiar with the key concepts of multiple screen support.

      + +

      Key Concepts

      +

      Before building a native application for multiple resolutions using Tizen native UI framework, make sure you are familiar with the following concepts:

      + + +

      Multi-scale in Tizen Native UI Framework

      +

      Tizen native UI framework supports multiple scaling. If the application is implemented considering scalability, it is enough to change the elm_scale value in different device environments without modifying the application code.

      + +

      Scale 1.0 in Tizen native UI framework means that the application is displayed in a set size and is not scaled. Scale 1.0 is used in a display environment, such as a desktop. In the desktop environment, the monitor has a resolution between 1280 x 800 and 1920 x 1080, with a size between 20 and 27 inch, and the dpi between 80 and 100.

      + +

      If an application is scaled up or down after implementing it in a desktop environment, it can be used in another device without modifying the code. Each device has a proper scale value for adjusting the application size. Edje, which handles layout and themes in Tizen native UI framework, gets the size of an object by multiplying the size specified by an application using the scale value.

      + +

      The following figure illustrates a 50 px wide object in a 1280 px wide monitor. If the same object is displayed with not scaling in mobile environment, it looks very small. To show the object in mobile environment in the similar size as in the monitor, define the scale is 2.0, so that the object size is 100 px instead of 50 px.

      + +

      Figure: Scaling from desktop to mobile

      +

      Scaling from desktop to mobile

      + +

      Base Scale

      +

      The object scaling must be defined in the config.xml file of this application to show the application in a proper size in other devices. However, the scaling must be based on scale 1.0 or, if the application is based on another scale, this scale must be defined in the config.xml file. This predefined scale is called the "base scale".

      + +

      The size of a scalable object is multiplied with the device scale value, as illustrated in the following figure. If the scalable object (on the left) with the size 10 is created in a device with scale 1.0, the size of the object is 20 in a device with scale 2.0, and 40 in a device with scale 4.0.

      + +

      Figure: Base scale

      +

      Base scale

      + +

      The middle object has a base scale 2.0. The following example shows its scaling in a device with scale 4.0:

      + + + + + + + +
      Scale = Device scale (information in the target) / Base scale (information in the application) +

      For example: 2.0 = 4.0 / 2.0

      +
      + +

      You must declare the following values as base scale:

      +
        +
      • WVGA: 1.8
      • +
      • HD: 2.4
      • +
      + + + +

      Applying the Base Scale

      +

      To create an application that supports multiple screen sizes, you must learn how to set the base scale in:

      + + +

      Calculating the Base Scale

      + +

      To get the base scale value of your own display, you must know the DPI of the display. Based on the display DPI, you can calculate the base scale, since it is basically proportional to the display DPI with the following formula:

      + +
      +base_scale = (DPI / 90) * profile_factor
      + +

      The profile factor is the value for fitting the object size as a profile. The distance between the user eye and the display differs for each profile. This means that the object size must be different if the device display is changed.

      + +

      The following table lists the profile factors for various profiles.

      + + + + + + + + + + + + + + + + + + + + +
      Table: Profile factors
      ProfileProfile factor
      Wearable0.4
      Mobile0.7
      Desktop1.0
      + +

      For example, if your display has 233 dpi and the platform uses the mobile profile, the base scale is calculated like this:

      +
      +1.8 = (233 / 90) * 0.7
      + +

      The base scale of the device is 1.8. If the application is made in the environment using 233 dpi and mobile profile, its base scale must be set to 1.8. For a desktop, the DPI is 90, and its base scale is 1.0.

      + + +

      Setting the Base Scale in EDC

      +

      The application must specify the scale its base scale. The edje objects are scaled properly if the base scale is set in the collection of the edc file, as in the following example:

      + + + + + + + + +
      Note
      The base scale for WVGA is 1.8, and for HD application, 2.4.
      +
      collections 
      +{
      +   base_scale: 1.8; // This value is for WVGA application
      +   parts 
      +   {
      +      part 
      +      {
      +         name: "box"; 
      +         type: RECT;
      +         min: 100 100;
      +         scale: 1;
      +      }
      +   }
      +}
      +
      +

      Setting the Base Scale in C

      +

      The size of the object must be specified in EDC. However, sometimes it is better for an application to the object size in a C file. If the size is defined with no scaling in the C file, the application is displayed in the same size even if the scale changes. To avoid this, use the ELM_SCALE_SIZE macro, as in the following example:

      + +
      #define ELM_SCALE_SIZE(x) x / elm_app_base_scale_get() * elm_config_scale_get()
      + +

      in the definition, the size (x) is changed to a size based on 1.0 (x/elm_app_base_scale_get()) and it is multiplied with the scale of the current target (elm_config_scale_get()).

      + +

      Set the base scale using the elm_app_base_scale_set() function:

      + +
      int app_create(void *data)
      +{
      +   elm_app_base_scale_set(1.8); // This value is for WVGA application
      +}
      +
      +

      After setting the base scale, use the ELM_SCALE_SIZE macro to set the size of an object in the application:

      + +
      evas_object_size_hint_min_set(object, ELM_SCALE_SIZE(100), ELM_SCALE_SIZE(100));
      +evas_object_resize(object, ELM_SCALE_SIZE(50), ELM_SCALE_SIZE(50));
      +
      + +

      You can use ELM_SCALE_SIZE macro in any API related with setting objects sizes in Tizen native applications.

      + +

      Scaling without the Base Scale

      + +

      In Tizen, each device has a scale value in proportion to the display. If scaling is enabled, the objects are drawn on the display by multiplying with the user-defined object size and the device scale. If the base scale is set, the objects are drawn by dividing the user-defined object size with the base scale and multiplying it by the device scale.

      + +

      If you use the scale feature without setting the base scale, the result is the same as if you set the base scale to 1.0. Then you do not need to care about the base scale variables, because the pixels roll like a virtual pixel. For example, if you set 1 pixel in 129 dpi without setting the base scale value, the 1 pixel before scaling is equivalent to 1 real physical pixel after scaling. In case of 233 dpi, it is the same with 1.8 pixels after scaling.

      + +

      Always consider the pixel before scaling when defining the application UI, in order to ensure a proper UI display on the screen with a diversity of densities.

      + +
      int app_create(void *data)
      +[ Conversion Formula ]
      +Real physical pixel = (a pixel before scaling) x (dpi / 90) x 0.7
      +
      +

      Where 90 is the default DPI on a desktop and 0.7 is the mobile profile factor.

      + +

      The following table shows some examples.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Table: Pixel conversions
      BaseLow-density device (such as WVGA)High-density device (such as HD)
      DPI129233306
      A pixel before scaling100100100
      Real physical pixel100180240
      Actual base scale1.01.82.4
      + + + + +
      + +Go to top + + + + + + + \ No newline at end of file diff --git a/org.tizen.ui.guides/html/native/efl/multipoint_touch_n.htm b/org.tizen.ui.guides/html/native/efl/multipoint_touch_n.htm new file mode 100755 index 0000000..3b15f01 --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/multipoint_touch_n.htm @@ -0,0 +1,266 @@ + + + + + + + + + + + + + + Tracking Multi-point Touch Events + + + + + + +
      +

      Tracking Multi-point Touch Events

      + + +

      This tutorial demonstrates how you can use the Evas_Object to paint on a canvas and track touch events.

      + +

      Initializing Multi-point Touch

      + +

      This sample is a fully functional application able to track multiple simultaneous clicks. For every click, a black rectangle spot is drawn on the screen. This way it is easy to test the multi-point touch operation with the application.

      + +

      Initialization is implemented in the multitouch.c file.

      +

      The appdata structure includes Evas_Object pointers, a list, and a Boolean flag.

      +
      +typedef struct appdata 
      +{
      +   Evas_Object *win;
      +   Evas_Object *conform;
      +   Evas_Object *nf;
      +   Evas_Object *button;
      +   Evas_Object *box;
      +   Evas_Object *rect;
      +   Evas_Object *label;
      +
      +   // List of mouse spots
      +   Eina_List *spots;
      +
      +   // Flag for checking the mouse down event
      +   Eina_Bool down; 
      +} 
      +appdata_s;
      +
      + +

      The main() function initializes event callbacks and calls the ui_app_main() function to start the EFL application.

      +
      +int
      +main(int argc, char *argv[])
      +{
      +   appdata_s *ad = {0,};
      +   int ret = 0;
      +
      +   ui_app_lifecycle_callback_s event_callback = {0,};
      +   app_event_handler_h handlers[5] = {NULL,};
      +
      +   event_callback.create = app_create;
      +   event_callback.terminate = app_terminate;
      +   event_callback.pause = app_pause;
      +   event_callback.resume = app_resume;
      +   event_callback.app_control = app_control;
      +
      +   ui_app_add_event_handler(&handlers[APP_EVENT_LOW_BATTERY], APP_EVENT_LOW_BATTERY, ui_app_low_battery, &ad);
      +   ui_app_add_event_handler(&handlers[APP_EVENT_LOW_MEMORY], APP_EVENT_LOW_MEMORY, ui_app_low_memory, &ad);
      +   ui_app_add_event_handler(&handlers[APP_EVENT_DEVICE_ORIENTATION_CHANGED], APP_EVENT_DEVICE_ORIENTATION_CHANGED, ui_app_orient_changed, &ad);
      +   ui_app_add_event_handler(&handlers[APP_EVENT_LANGUAGE_CHANGED], APP_EVENT_LANGUAGE_CHANGED, ui_app_lang_changed, &ad);
      +   ui_app_add_event_handler(&handlers[APP_EVENT_REGION_FORMAT_CHANGED], APP_EVENT_REGION_FORMAT_CHANGED, ui_app_region_changed, &ad);
      +   ui_app_remove_event_handler(handlers[APP_EVENT_LOW_MEMORY]);
      +
      +   ret = ui_app_main(argc, argv, &event_callback, &ad);
      +
      +   return ret;
      +}
      +
      + + +

      The following figure illustrates the Multi-point Touch.

      + +

      Figure: Multi-point Touch screens

      +

      Multi-point Touch screens

      + +

      Handling the Canvas

      + +

      The create_base_gui() function creates base GUI elements including Naviframe and the Naviframe button. Naviframe includes each view screen as an item, which in turn includes the title and a button which clears spots when clicked.

      + +
      static void
      +create_base_gui(appdata_s *ad)
      +{
      +   Elm_Object_Item *nf_it;
      +
      +   // Naviframe
      +   ad->nf = elm_naviframe_add(ad->conform);
      +   elm_object_content_set(ad->conform, ad->nf);
      +   evas_object_show(ad->nf);
      +
      +   // Button
      +   ad->button = elm_button_add(ad->nf);
      +   elm_object_text_set(ad->button, "Clear");
      +   evas_object_smart_callback_add(ad->button, "clicked", button_clicked_cb, ad);
      +
      +   // Create main view
      +   ad->box = create_main_view(ad);
      +   nf_it = elm_naviframe_item_push(ad->nf, "Multi-point Touch",
      +                                   NULL, NULL, ad->box, NULL);
      +   elm_object_item_part_content_set(nf_it, "title_right_btn", ad->button);
      +} 
      +
      + +

      The create_main_view() function creates the main view including the label and an event rectangle.

      +

      The label displays information on mouse event status and coordinates (x, y positions). The event rectangle is received completely through mouse (touch) events. To show 2 elements in a Naviframe content area, a container combining those elements is necessary. A box container functions in that role. The label and rectangle pack end the box and the box is embedded into the Naviframe content area.

      + +
      static Evas_Object *
      +create_main_view(appdata_s *ad)
      +{
      +   Evas_Object *box;
      +
      +   // Box
      +   box = elm_box_add(ad->nf);
      +   evas_object_size_hint_weight_set(box, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +   evas_object_show(box);
      +
      +   // Label
      +   ad->label = elm_label_add(box);
      +   elm_object_text_set(ad->label, "None");
      +   evas_object_size_hint_weight_set(ad->label, EVAS_HINT_EXPAND, 0);
      +   evas_object_size_hint_align_set(ad->label, EVAS_HINT_FILL, EVAS_HINT_FILL);
      +   evas_object_repeat_events_set(ad->label, EINA_TRUE);
      +   elm_box_pack_end(box, ad->label);
      +   evas_object_show(ad->label);
      +
      +   // Event Rect
      +   ad->rect = evas_object_rectangle_add(evas_object_evas_get(box));
      +   evas_object_size_hint_weight_set(ad->rect, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +   evas_object_size_hint_align_set(ad->rect, EVAS_HINT_FILL, EVAS_HINT_FILL);
      +   evas_object_color_set(ad->rect, 204, 204, 204, 255);
      +   evas_object_repeat_events_set(ad->rect, EINA_TRUE);
      +   elm_box_pack_end(box, ad->rect);
      +   evas_object_show(ad->rect);
      +}
      +
      + +

      The create_spot() function creates a rectangle, resizes the rectangle according to received size input, and moves the rectangle according to received coordinates (x, y positions) input.

      + +
      Evas_Object *
      +create_spot(Evas_Object *parent, Evas_Coord x, Evas_Coord y, int size)
      +{
      +   Evas_Object *spot;
      +   spot = evas_object_rectangle_add(evas_object_evas_get(parent));
      +   evas_object_resize(spot, size, size);
      +   // Adjust x, y positions to be center of object
      +   evas_object_move(spot, x - (size/2), y - (size/2));
      +   evas_object_show(spot);
      +
      +   return spot;
      +}
      +
      + +

      The rectangle object is stored in Eina_List (ad->spots) for managing other functions. The button_clicked_cb() function removes all evas_objects into the ad->spots list, meaning all spot rectangles are cleared.

      + +
      static void
      +button_clicked_cb(void *data, Evas *evas, Evas_Object *object, void *event_info)
      +{
      +   appdata_s *ad = data;
      +   Evas_Object *spot;
      +
      +   EINA_LIST_FREE(ad->spots, spot)
      +   {
      +      evas_object_del(spot);
      +      spot = NULL;
      +   }
      +   elm_object_text_set(ad->label, "Clear");
      +}
      +
      + +

      Managing Touch Events

      + +

      On the bottom of the create_main_view() function, event callbacks are added to the event rectangle. An event callback is added using the evas_object_event_callback_add() function.

      + +

      The following touch event types are supported:

      +
        +
      • EVAS_CALLBACK_MOUSE_DOWN: This event is called when the given object receives the mouse down event.
      • +
      • EVAS_CALLBACK_MOUSE_UP: This event is called when the given object receives the mouse up event.
      • +
      • EVAS_CALLBACK_MOUSE_MOVE: This event is called when the given object receives the mouse move event.
      • +
      • EVAS_CALLBACK_MULTI_DOWN: This event is called when the given object has already received the mouse down event and receives the multi-mouse down event.
      • +
      • EVAS_CALLBACK_MULTI_UP: This event is called when the given object receives the multi-mouse up event.
      • +
      • EVAS_CALLBACK_MULTI_MOVE: This event is called when the given object receives the multi-mouse move event.
      • +
      +

      If the given object receives a mouse event, a callback function is called, and event information, such as coordinates (x, y positions) is passed. The mousemove_cb() function sets the mouse status, positions text in the label, and draws a spot rectangle. To distinguish down and up positions, set different colors for the down and up rectangles.

      + +
      +static void
      +mousemove_cb(void *data, Evas *evas, Evas_Object *obj, void *event_info)
      +{
      +   appdata_s *ad = data;
      +   Evas_Object *spot;
      +   char buf[1024];
      +   Evas_Event_Mouse_Move *ev = event_info;
      +   Evas_Coord x = ev->cur.canvas.x;
      +   Evas_Coord y = ev->cur.canvas.y;
      +   int size = (int) 5 * elm_config_scale_get();
      +
      +   if (!ad->down)
      +      return;
      +
      +   snprintf(buf, sizeof(buf), "Mouse Move, %d, %d", x, y);
      +   elm_object_text_set(ad->label, buf);
      +
      +   // Draw spot on event position
      +   spot = create_spot(ad->rect, x, y, size);
      +   evas_object_color_set(spot, 0, 0, 0, 255);
      +   ad->spots= eina_list_append(ad->spots, spot);
      +}
      +
      + + + + +
      + +Go to top + + + + + + + diff --git a/org.tizen.ui.guides/html/native/efl/naviframe_tutorial_n.htm b/org.tizen.ui.guides/html/native/efl/naviframe_tutorial_n.htm new file mode 100755 index 0000000..206759b --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/naviframe_tutorial_n.htm @@ -0,0 +1,252 @@ + + + + + + + + + + + + + + Creating a Naviframe for Navigation + + + + + + +
      +

      Creating a Naviframe for Navigation

      + + +

      Naviframes are containers useful for implementing interfaces with several screens having a previous/next relationship.

      + + +

      Creating Naviframes

      + +

      Naviframes are containers useful for implementing interfaces with several screens having a previous/next relationship.

      + +

      This tutorial shows a UI with three naviframes. Each naviframe is made of 20 screens, each made up of a label with the text "label +<n>", a title with the same text, and previous and next buttons, which are used to navigate between the screens.

      +

      TODO: screenshots of the staged interface

      +

      The naviframe is "one-way": elements are added, and when the user clicks on the "previous" button, they are removed; there is no "next" button by default. To add it, we define a structure that holds the naviframe object along with a stack of the elements that the user has popped by using the "previous" button.

      +

      Note that it is possible to create the elements on-the-fly each time the "next" button is pressed. Both approaches are valid.

      +
      // NOTE: A zipper is a datastructure for an ordered set of elements and a
      +// cursor in this set, meaning there are elements before the cursor (which are
      +// stored inside the naviframe) and after (which are stored in the "popped"
      +// list.
      +struct naviframe_zipper 
      +{
      +   Evas_Object *naviframe;
      +   Eina_List *popped;
      +};
      +
      + +

      To add several naviframes, create a function that factors their creation and initializes the naviframe_zipper structure defined above.

      +
      static struct naviframe_zipper *
      +_naviframe_add(Evas_Object *parent)
      +{
      +   struct naviframe_zipper *z = malloc(sizeof(struct naviframe_zipper));
      +   z->naviframe = elm_naviframe_add(parent);
      +   z->popped = NULL;
      +
      +   evas_object_size_hint_weight_set(z->naviframe, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +   evas_object_size_hint_align_set(z->naviframe, EVAS_HINT_FILL, EVAS_HINT_FILL);
      +   evas_object_show(z->naviframe);
      +   // By default, objects are destroyed when they are popped from the naviframe
      +   // To save and re-use them, enable "preserve_on_pop"
      +   elm_naviframe_content_preserve_on_pop_set(z->naviframe, EINA_TRUE);
      +
      +   return z;
      +}
      +
      +

      Create buttons that are at the top of the naviframe and allow the user to go back and forth between the screens. The naviframe component builds a button for "previous" by default, but allows the programmers to provide their own buttons. It has a specific slot for the "next" button.

      +
      // Save the element that is popped from the naviframe
      +static void
      +_naviframe_prev(void *data, Evas_Object *o __UNUSED__, void *event_info __UNUSED__)
      +{
      +   struct naviframe_zipper *z = data;
      +   z->popped = eina_list_prepend(z->popped, elm_naviframe_item_pop(z->naviframe));
      +}
      +
      +// Set the first element after the current one available and push it to the
      +// naviframe
      +static void
      +_naviframe_next(void *data, Evas_Object *o __UNUSED__, void *event_info __UNUSED__)
      +{
      +   struct naviframe_zipper *z = data;
      +   Evas_Object *label, *prev, *next;
      +   const char *text;
      +   Elm_Object_Item *it;
      +
      +   label = eina_list_data_get(z->popped);
      +   z->popped = eina_list_remove_list(z->popped, z->popped);
      +   if (label != NULL) 
      +   {
      +      // The UI component is saved inside the naviframe but nothing more; we need
      +      // to create new buttons and set the title text again (copy the one
      +      // from the label that is saved).
      +      text = elm_object_text_get(label);
      +      // The _button function creates a button which is either "Previous" (-1) or
      +      // "Next" (1)
      +      prev = _button(z, -1);
      +      next = _button(z, 1);
      +      it = elm_naviframe_item_push(z->naviframe, text, prev, next, label, NULL);
      +   }
      +}
      +
      +

      When a naviframe and the pages that go inside it are built, populate it.

      +

      Remember that three naviframes are created, each populated in a different way. The common bits have been factored out as a function and the specific parts are executed through a callback. The generic function is shown below.

      +
      // Generic naviframe-populate function:
      +// Its third (and last) parameter is a callback for customization, i.e. pushes
      +// the new items to a specific position; it returns a "context" value that is
      +// used between its calls and enables behaviors such as "push after the
      +// previously-pushed item" 
      +static struct naviframe_zipper*
      +_naviframe_populate_gen(Evas_Object *parent, const char *id,
      +      void * (*populate_cb) (Evas_Object *nav, const char *title, Evas_Object
      +         *prev, Evas_Object *next, Evas_Object *label, Elm_Object_Item *context)
      +      )
      +{
      +   struct naviframe_zipper *z;
      +   Evas_Object *label, *prev, *next;
      +   Elm_Object_Item *context = NULL;
      +   char buf[256];
      +   int i;
      +
      +   z = _naviframe_add(parent);
      +
      +   for (i = 0; i < 20; i++) 
      +   {
      +      label = elm_label_add(z->naviframe);
      +      snprintf(buf, sizeof(buf), "%s [%d]", id, i);
      +      elm_object_text_set(label, buf);
      +      evas_object_show(label);
      +      evas_object_size_hint_weight_set(label, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +      evas_object_size_hint_align_set(label, EVAS_HINT_FILL, EVAS_HINT_FILL);
      +      // The _button function creates a button which is either "Previous" (-1) or
      +      // "Next" (1)
      +      prev = _button(z, -1);
      +      next = _button(z, 1);
      +      // Use the populate_cb callback to provide the customization of the way the
      +      // elements are added inside the naviframe
      +      context = populate_cb(z->naviframe, buf, prev, next, label, context);
      +   }
      +
      +   return z;
      +}
      +
      +

      The prototype of the callbacks is fairly large, but that is because of the syntax for callbacks in C.

      +
      // Push items one after the other
      +static Elm_Object_Item *
      +_populate_cb__push(Evas_Object *nav, const char *title,
      +      Evas_Object *prev, Evas_Object *next, Evas_Object *label,
      +      Elm_Object_Item *context)
      +{
      +   return elm_naviframe_item_push(nav, title, prev, next, label, NULL);
      +}
      +
      +// Push items one after the other but use insert_after for it
      +static Elm_Object_Item *
      +_populate_cb__push_then_insert_after(Evas_Object *nav, const char *title,
      +      Evas_Object *prev, Evas_Object *next, Evas_Object *label,
      +      Elm_Object_Item *context)
      +{
      +   if (context == NULL) 
      +   {
      +      return elm_naviframe_item_push(nav, title, prev, next, label, NULL);
      +   }
      +   else 
      +   {
      +      return elm_naviframe_item_insert_after(nav, context, title, prev, next, label, NULL);
      +   }
      +}
      +
      +// Push one item and repeatedly insert new items before the last inserted
      +// item
      +static Elm_Object_Item *
      +_populate_cb__push_then_insert_before(Evas_Object *nav, const char *title,
      +      Evas_Object *prev, Evas_Object *next, Evas_Object *label,
      +      Elm_Object_Item *context)
      +{
      +   if (context == NULL) 
      +   {
      +      return elm_naviframe_item_push(nav, title, prev, next, label, NULL);
      +   }
      +   else 
      +   {
      +      return elm_naviframe_item_insert_before(nav, context, title, prev, next, label, NULL);
      +   }
      +}
      +
      +

      Create a window with a vertical box, which holds the three naviframes from the Appcore's app_create callback.

      + +
      static bool
      +_app_create(void *data)
      +{
      +   Evas_Object *w, *box;
      +   struct naviframe_zipper *z;
      +
      +   w = elm_win_util_standard_add("Naviframe Test", "Naviframe Test");
      +
      +   box = elm_box_add(w);
      +   elm_box_horizontal_set(box, EINA_FALSE);
      +   elm_box_homogeneous_set(box, EINA_TRUE);
      +   evas_object_size_hint_weight_set(box, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +   evas_object_size_hint_align_set(box, EVAS_HINT_FILL, EVAS_HINT_FILL);
      +   evas_object_show(box);
      +   elm_win_resize_object_add(w, box);
      +
      +   z = _naviframe_populate_gen(w, "Before", _populate_cb__push_then_insert_before);
      +   elm_box_pack_end(box, z->naviframe);
      +
      +   z = _naviframe_populate_gen(w, "After", _populate_cb__push_then_insert_after);
      +   elm_box_pack_end(box, z->naviframe);
      +
      +   z = _naviframe_populate_gen(w, "Push", _populate_cb__push);
      +   elm_box_pack_end(box, z->naviframe);
      +
      +   evas_object_show(w);
      +}
      +
      + + + + +
      + +Go to top + + + + + + + diff --git a/org.tizen.ui.guides/html/native/efl/notification_window_n.htm b/org.tizen.ui.guides/html/native/efl/notification_window_n.htm new file mode 100755 index 0000000..a5d1ede --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/notification_window_n.htm @@ -0,0 +1,384 @@ + + + + + + + + + + + + + Notification Windows: Supporting Notification Levels, Screenshots, and Input Generators + + + + + +
      + +

      Notification Windows: Supporting Notification Levels, Screenshots, and Input Generators

      + +

      The EFL UTIL utility package supports the following EFL functionalities:

      + + + + +

      Notification Window and Level

      + +

      The EFL UTIL API allows you to set and get the notification level of the notification window (which is of the EFL window type):

      + +
      • efl_util_set_notification_window_level()
      • +
      • efl_util_get_notification_window_level()
      + +

      To understand notification levels, you must first learn about the Tizen window layer hierarchy. Window layers are logical containers used to control the window stack order. Each window belongs to 1 layer and can change the stack order in the layer. Windows in same layer are always placed on or under a window in another layer. In addition to the default "normal layer", there exists a "notification layer", which is always placed above the normal layer.

      + + +

      Figure: Window layers

      +

      Window layers

      + + +

      Each window is set to a specific layer according to its type or properties. Most application windows belong to the normal layer. However, in case of an important alarm or other information crucial to the user, you can set the window to belong to the notification layer. This ensures that the user notices the information immediately, because the window belonging to the notification layer is always shown above the windows in the normal layer.

      + +

      Using the Notification Windows

      + +

      A window that belongs to the notification layer is called a "notification window". To make a notification window:

      + +
      1. Set the window type to NOTIFICATION, by calling the elm_win_add() function with the third parameter set to ELM_WIN_NOTIFICATION.
      2. +
      3. Set the notification level by calling the efl_util_set_notification_window_level() function. +

        The notification level defines the priority of the window, and the notification layer contains 3 levels (EFL_UTIL_NOTIFICATION_LEVEL_1, EFL_UTIL_NOTIFICATION_LEVEL_2, and EFL_UTIL_NOTIFICATION_LEVEL_3).

        +

        The default notification window level is EFL_UTIL_NOTIFICATION_LEVEL_1. Most of notification windows can be set to this level. The EFL_UTIL_NOTIFICATION_LEVEL_2 is a higher level than EFL_UTIL_NOTIFICATION_LEVEL_1, which means that the window set to EFL_UTIL_NOTIFICATION_LEVEL_2 is always on the EFL_UTIL_NOTIFICATION_LEVEL_1 level window. The EFL_UTIL_NOTIFICATION_LEVEL_3 is the highest level in notification windows. Very few applications can use this level.

        + +

        If there are notification windows that have the same level, the most recently created notification window is placed on top of the other window.

        + +
      + +

      Figure: Notification levels

      +

      Notification levels

      + + +

      The following code snippets shown how to make a notification window with a higher level.

      + +
      +#include <Elementary.h>
      +#include <efl_util.h>
      +#include <dlog.h>
      +
      +static Evas_Object *create_win(const char *name)
      +{
      +   Evas_Object *eo;
      +   efl_util_error_e error;
      +   // Create the NOTIFICATION window object
      +   eo = elm_win_add(NULL, name, ELM_WIN_NOTIFICATION);
      +
      +   if (!eo) return NULL;
      +
      +   // Set the NOTIFICATION level
      +   error = efl_util_set_notification_window_level(eo, EFL_UTIL_NOTIFICATION_LEVEL_1);
      +
      +   elm_win_title_set(eo, name);
      +   elm_win_autodel_set(eo, EINA_TRUE); 
      +   evas_object_smart_callback_add(eo, "delete,request", _quit_cb, NULL); 
      +	
      +   return eo;
      +}
      + +

      Use the efl_util_get_notification_window_level() function to get the currently set notification level of a window. If the window is not of the notification type, the function returns the -EFL_UTIL_ERROR_NOT_SUPPORTED_WINDOW_TYPE error.

      +
      +#include <Elementary.h>
      +#include <efl_util.h>
      +#include <dlog.h>
      +
      +void get_notification_level (Evas_Object *eo)
      +{
      +   efl_util_error_e error;
      +   efl_util_notification_level_e  notification_level;
      +
      +   if (!eo) return;
      +
      +   // Get the window notification level
      +   error = efl_util_get_notification_window_level (eo, &notification_level);
      +
      +   // Check the return value
      +   if (error== EFL_UTIL_ERROR_NONE)
      +   {
      +      switch (notification_level)
      +      {
      +         case EFL_UTIL_NOTIFICATION_LEVEL_1:
      +            // Do something for level 1
      +            break;
      +
      +         case EFL_UTIL_NOTIFICATION_LEVEL_2:
      +            // Do something for level 2
      +            break;
      +      }
      +   }
      +   else
      +   {
      +      // Error handling
      +   }
      +}
      + +

      Screenshot

      + +

      The EFL UTIL SCREENSHOT API (in mobile and wearable applications) allows you to get the screen image to the user.

      + +

      First you must make the efl_util_screenshot_h structure and initialize the structure members with the efl_util_screenshot_initialize() function. To take the actual screenshot, create screen capture data and return it to the tbm_surface handler with the efl_util_screenshot_take_tbm_surface() function.

      +

      When no longer needed, remember to free the efl_util_screenshot_h structure with the efl_util_screenshot_deinitialize() function.

      + + +

      Input Generator

      + +

      The EFL UTIL INPUT API (in mobile and wearable applications) allows you to generate input events (such as key and touch events).

      + +

      First you initialize the input generator and select a device type with the efl_util_input_initialize_generator() function. To generate actual key or touch events, use the efl_util_input_generate_key() or efl_util_input_generate_touch() function.

      +

      When no longer needed, remember to free the input generator with the efl_util_input_deinitialize_generator() function.

      + + + +

      Initializing EFL Utility

      + +

      To use the EFL UTIL API, the following header file has to be included:

      +
      #include <efl_util.h>
      + +

      Creating a Notification Window and Setting a Notification Window Level

      + +

      To create a notification window and set the window level, use the efl_util_set_notification_window_level() function. If the window type is not notification type, the function returns an error.

      +
      #include <Elementary.h>
      +#include <dlog.h>
      +
      +void create_win() 
      +{
      +   Evas_Object *eo;
      +   efl_util_error_e error;
      +   char *name = "Notification window";
      +   
      +   // Create notification window
      +   eo = elm_win_add(NULL, name, ELM_WIN_NOTIFICATION);
      +   if (!eo) return;
      +   
      +   // Set notification level
      +   error = efl_util_set_notification_window_level
      +           (eo, EFL_UTIL_NOTIFICATION_LEVEL_1);
      +   if (error != EFL_UTIL_ERROR_NONE)
      +   {
      +      // Do error handling
      +   }
      +}
      +
      + +

      Getting the Notification Window Level

      + +

      To get the notification window level, use the efl_util_get_notification_window_level() function:

      + +
      void create_win() 
      +{
      +   Evas_Object *eo;
      +   efl_util_error_e error;
      +   efl_util_notification_level_e notification_level;
      +   char *name = "Notification window";
      +   
      +   // Create notification window
      +   eo = elm_win_add(NULL, name, ELM_WIN_NOTIFICATION);
      +   if (!eo) return;
      +   
      +   // Get notification level
      +   error = efl_util_get_notification_window_level
      +           (eo, &notification_level);
      +   if (error == EFL_UTIL_ERROR_NONE) 
      +   {
      +      switch (notification_level) 
      +      {
      +         case EFL_UTIL_NOTIFICATION_LEVEL_1:
      +            // Do something for notification level 1
      +            break;
      +         case EFL_UTIL_NOTIFICATION_LEVEL_2:
      +            // Do something for notification level 2
      +            break;
      +      }
      +   }
      +}
      + +

      Getting a Screenshot

      + +

      To get a screenshot:

      + +
      1. Initialize with the efl_util_screenshot_initialize() function: +
        +#include <tbm_surface.h>
        +#include <X11/Xlib.h>
        +
        +void capture()
        +{
        +   efl_util_screenshot_h screenshot = NULL;
        +   tbm_surface_h tbm_surface = NULL;
        +   tbm_surface_info_s tsuri;
        +
        +   screenshot = efl_util_screenshot_initialize(width, height);
        +
      2. + +
      3. After getting the efl_util_screenshot_h structure, execute the efl_util_screenshot_take_tbm_surface() function to get the tbm_surface handler which has the screenshot data. +
        +   if (screenshot) 
        +   {
        +      tbm_surface = efl_util_screenshot_take_tbm_surface(screenshot);
        +      if (tbm_surface) 
        +      {
        +         // Treat tbm_surface handler (screenshot data)
        +      }
        +
      4. + +
      5. Free the resources with the efl_util_screenshot_deinitialize() function: +
        +      efl_util_screenshot_deinitialize(screenshot);
        +   }
        +}
      + +

      Generating a Key Input Event

      + +

      To generate key input events:

      + +
      1. Execute the efl_util_input_initialize_generator() function: +
        +void key_event_generator()
        +{
        +   int ret = EFL_UTIL_ERROR_NONE;
        +
        +   ret = efl_util_input_initialize_generator(EFL_UTIL_INPUT_DEVTYPE_KEYBOARD);
        +
      2. +
      3. After setting input device type, execute the efl_util_input_generate_key() function to generate key input events: +
        +   if (ret != EFL_UTIL_ERROR_NONE) 
        +   {
        +      // Failed to initialize input generator
        +
        +      return;
        +   }
        +   ret = efl_util_input_generate_key("XF86Menu", 1);
        +   if (ret != EFL_UTIL_ERROR_NONE) 
        +   {
        +      // Failed to generate a "XF86Menu" key press event
        +      efl_util_input_deinitialize_generator();
        +
        +      return;
        +   }
        +   ret = efl_util_input_generate_key("XF86Menu", 0);
        +   if (ret != EFL_UTIL_ERROR_NONE) 
        +   {
        +      // Failed to generate a "XF86Menu" key release event
        +      efl_util_input_deinitialize_generator();
        +
        +      return;
        +   }
        +
      4. +
      5. Free the resources with the efl_util_input_deinitialize_generator() function: +
        +   efl_util_input_deinitialize_generator();
        +}
      + + +

      Generating a Touch Input Event

      + +

      To generate touch input events:

      + +
      1. Execute the efl_util_input_initialize_generator() function: +
        +void touch_event_generator()
        +{
        +   int ret = EFL_UTIL_ERROR_NONE;
        +
        +   ret = efl_util_input_initialize_generator(EFL_UTIL_INPUT_DEVTYPE_TOUCHSCREEN);
        +
      2. +
      3. After setting input device type, execute the efl_util_input_generate_touch() function to generate touch input events: +
        +   if (ret != EFL_UTIL_ERROR_NONE) 
        +   {
        +      // Failed to initialize input generator
        +
        +      return;
        +   }
        +   ret = efl_util_input_generate_touch(0, EFL_UTIL_INPUT_TOUCH_BEGIN, 100, 100);
        +   if (ret != EFL_UTIL_ERROR_NONE) 
        +   {
        +      // Failed to generate a first finger touch press event on (100, 100)
        +      efl_util_input_deinitialize_generator();
        +
        +      return;
        +   }
        +   ret = efl_util_input_generate_touch(0, EFL_UTIL_INPUT_TOUCH_UPDATE, 110, 110);
        +   if (ret != EFL_UTIL_ERROR_NONE) 
        +   {
        +      // Failed to generate a first finger touch move event to (110, 110)
        +      efl_util_input_deinitialize_generator();
        +
        +      return;
        +   }
        +   ret = efl_util_input_generate_touch(0, EFL_UTIL_INPUT_TOUCH_END, 110, 110);
        +   if (ret != EFL_UTIL_ERROR_NONE) 
        +   {
        +      // Failed to generate a first finger touch release event to (110, 110)
        +      efl_util_input_deinitialize_generator();
        +
        +      return;
        +   }
        +
      4. +
      5. Free the resources with the efl_util_input_deinitialize_generator() function: +
        +   efl_util_input_deinitialize_generator();
        +}
      + + + +
      + +Go to top + + + + + + + \ No newline at end of file diff --git a/org.tizen.ui.guides/html/native/efl/panes_tutorial_mn.htm b/org.tizen.ui.guides/html/native/efl/panes_tutorial_mn.htm new file mode 100755 index 0000000..f53dd1f --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/panes_tutorial_mn.htm @@ -0,0 +1,324 @@ + + + + + + + + + + + + + + Creating Panes + + + + + + +
      +

      Creating Panes

      + + +

      This tutorial explains how to use Panes in the application.

      + + + + + + + + + + +
      Note
      This feature is supported in mobile applications only.
      + +

      Initializing the Application

      + +

      This is how to start an Appcore application.

      +
      #include <Elementary.h>
      +#include <app.h>
      +
      +struct _appdata 
      +{
      +   const char *name;
      +   Evas_Object *win;
      +};
      +
      +static void app_terminate(void *user_data)
      +{
      +   struct _appdata *ad;
      +
      +   if (!user_data)
      +      return;
      +
      +   ad = user_data;
      +
      +   if (ad->win)
      +      evas_object_del(ad->win);
      +}
      +
      +static bool app_create(void *user_data)
      +{
      +   struct _appdata *ad;
      +   Evas_Object *win, *conformant, *naviframe, *panes, *panes_h, *nav_it, *bt;
      +
      +   if (!user_data)
      +      return false;
      +
      +   ad = user_data;
      +
      +   // Create window 
      +   elm_policy_set(ELM_POLICY_QUIT, ELM_POLICY_QUIT_LAST_WINDOW_CLOSED);
      +   win = elm_win_util_standard_add("panes", "Panes tutorial");
      +   elm_win_autodel_set(win, EINA_TRUE);
      +
      +   if (!win)
      +      return false;
      +
      +   ad->win = win;
      +
      +   // Add elm_conformant 
      +   conformant = elm_conformant_add(win);
      +   elm_win_resize_object_add(win, conformant);
      +   evas_object_size_hint_weight_set(conformant, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +   evas_object_show(conformant);
      +
      +   // Add naviframe to conformant 
      +   naviframe = elm_naviframe_add(conformant);
      +   elm_object_content_set(conformant, naviframe);
      +   evas_object_show(naviframe);
      +
      +   evas_object_resize(win, 320, 400);
      +   evas_object_show(win);
      +
      +   return true;
      +}
      +
      +int main(int argc, char **argv)
      +{
      +   appdata_s *ad = {0,};
      +   int ret = 0;
      +
      +   ui_app_lifecycle_callback_s event_callback = {0,};
      +   app_event_handler_h handlers[5] = {NULL,};
      +
      +   event_callback.create = app_create;
      +   event_callback.terminate = app_terminate;
      +   event_callback.pause = app_pause;
      +   event_callback.resume = app_resume;
      +   event_callback.app_control = app_control;
      +
      +   ui_app_add_event_handler(&handlers[APP_EVENT_LOW_BATTERY], APP_EVENT_LOW_BATTERY, ui_app_low_battery, &ad);
      +   ui_app_add_event_handler(&handlers[APP_EVENT_LOW_MEMORY], APP_EVENT_LOW_MEMORY, ui_app_low_memory, &ad);
      +   ui_app_add_event_handler(&handlers[APP_EVENT_DEVICE_ORIENTATION_CHANGED], APP_EVENT_DEVICE_ORIENTATION_CHANGED, ui_app_orient_changed, &ad);
      +   ui_app_add_event_handler(&handlers[APP_EVENT_LANGUAGE_CHANGED], APP_EVENT_LANGUAGE_CHANGED, ui_app_lang_changed, &ad);
      +   ui_app_add_event_handler(&handlers[APP_EVENT_REGION_FORMAT_CHANGED], APP_EVENT_REGION_FORMAT_CHANGED, ui_app_region_changed, &ad);
      +   ui_app_remove_event_handler(handlers[APP_EVENT_LOW_MEMORY]);
      +
      +   ret = ui_app_main(argc, argv, &event_callback, &ad);
      +
      +   return ret;
      +}
      +
      +

      The code above creates a window entitled "Panes tutorial", composed of a conformant component that contains a naviframe component. To add a new Panes object, use the _create() function.

      + +

      Creating a Panes Component

      + +

      The elm_panes component adds a draggable bar between two contents. When dragged, this bar resizes the contents' size. To create a new Panes into an Elementary object, use the elm_panes_add() function:

      +
      // Add an elm_panes 
      +panes = elm_panes_add(naviframe);
      +evas_object_size_hint_weight_set(panes, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +elm_win_resize_object_add(win, panes);
      +evas_object_show(panes);
      +
      +nav_it = elm_naviframe_item_push (naviframe, "Panes view", NULL, NULL, panes, NULL);
      +
      +

      Here the Panes is created and added in the naviframe.

      + +

      Configuring the Panes

      + +

      By default, the orientation of the Panes is vertical. To modify the orientation, use the elm_panes_horizontal_set() function.

      +
      // Add a horizontal elm_panes 
      +panes_h = elm_panes_add(naviframe);
      +elm_panes_horizontal_set(panes_h, EINA_TRUE);
      +
      +

      The code above creates another Panes object and sets the horizontal orientation. To add content in a panes, use the elm_object_part_content_set() function. Here we add the horizontal Panes (panes_h) to the "left" part of the first created Panes (panes).

      +
      elm_object_part_content_set(panes, "left", panes_h);
      +
      + +

      This is how to set a button object to the "right" side of our vertical Panes component.

      +
      // Create a button object 
      +bt = elm_button_add(naviframe);
      +elm_object_text_set(bt, "Right");
      +evas_object_size_hint_weight_set(bt, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +evas_object_size_hint_align_set(bt, EVAS_HINT_FILL, EVAS_HINT_FILL);
      +evas_object_show(bt);
      +
      +// and set it to the "right" part of the vertical Panes 
      +elm_object_part_content_set(panes, "right", bt);
      +
      + +

      The content of the horizontal Panes is set with two button objects (up and down). When populating a vertically displayed Panes, the left content is placed at the top, and the right content is placed at the bottom.

      +
      // Create a "Up" button 
      +bt = elm_button_add(naviframe);
      +elm_object_text_set(bt, "Up");
      +evas_object_size_hint_weight_set(bt, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +evas_object_size_hint_align_set(bt, EVAS_HINT_FILL, EVAS_HINT_FILL);
      +evas_object_show(bt);
      +elm_object_part_content_set(panes_h, "left", bt);
      +
      +// Create a "Down" button 
      +bt = elm_button_add(naviframe);
      +elm_object_text_set(bt, "Down");
      +evas_object_size_hint_weight_set(bt, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +evas_object_size_hint_align_set(bt, EVAS_HINT_FILL, EVAS_HINT_FILL);
      +evas_object_show(bt);
      +elm_object_part_content_set(panes_h, "right", bt);
      +
      + +

      The elm_panes can be dragged with the mouse but the proportion can also be set with the elm_panes_content_left_size_set() and elm_panes_content_right_size_set() functions. As an example, this is how to set the left size of both panes to 80%.

      +
      // Set the proportion of the panes to 80% 
      +elm_panes_content_left_size_set(panes, 0.8);
      +elm_panes_content_left_size_set(panes_h, 0.8);
      +
      + +

      The Panes proportions can also be fixed so that the user is not able to drag them. To do this, use the elm_panes_fixed_set() function.

      +
      // Fix the Panes proportion 
      +elm_panes_fixed_set(panes_h, EINA_TRUE);
      +
      + +

      Handling Signals

      + +

      The Panes components emit four different signals, depending on the users' interaction with the draggable bar.

      +
        +
      • "press" - The pane is pressed.
      • +
      • "unpressed" - The pane is released after being pressed.
      • +
      • "clicked" - The pane is clicked.
      • +
      • "clicked,double" - The pane is double clicked.
      • +
      +

      We add a callback function for each of them.

      + +

      "clicked" Signal

      + +

      The callback function for the clicked signal prints "Clicked" to standard output.

      +
      // clicked callback 
      +static void
      +_clicked_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   dlog_print(DLOG_INFO, PANES_TAG, "Clicked\n");
      +}
      +
      + +

      This is how to register this callback function to the vertical panes.

      +
      evas_object_smart_callback_add(panes, "clicked", _clicked_cb, panes);
      +
      + +

      "press" Signal

      + +

      The callback function for the "press" signal prints "Pressed" to the standard output.

      +
      // press callback 
      +static void
      +_press_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   dlog_print(DLOG_INFO, PANES_TAG, "Pressed\n");
      +}
      +
      + +

      This is how to register this callback function to the vertical panes.

      +
      evas_object_smart_callback_add(panes, "press", _press_cb, panes);
      +
      + +

      "unpress" Signal

      + +

      For the "unpress" signal, the proportion size of the left content of the Panes component is printed to the standard output. To do this, use the elm_panes_content_left_size_get() function.

      +
      // unpress callback 
      +static void
      +_unpress_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   dlog_print(DLOG_INFO, PANES_TAG, "Unpressed, size : %f\n",
      +      elm_panes_content_left_size_get(obj));
      +}
      +
      +

      This is how to register this callback function to the Panes.

      +
      evas_object_smart_callback_add(panes, "unpress", _unpress_cb, panes);
      +
      + +

      "clicked,double" Signal

      + +

      Hide the left part of the Panes component on the "clicked,double" signal and set the left proportion to 0.0. To restore the left part proportion with a double click on the hidden part of the Panes component, use the elm_panes_content_left_size_get() and elm_panes_content_left_size_set() functions, and a variable to store the value of the current proportion.

      + +
      // double clicked callback 
      +static void
      +_clicked_double_cb(void *data, Evas_Object *obj, void *event_info)
      +{
      +   static double size = 0.0;
      +   double tmp_size = 0.0;
      +   tmp_size = elm_panes_content_left_size_get(obj);
      +   if (tmp_size > 0)
      +   {
      +      elm_panes_content_left_size_set(obj, 0.0);
      +      dlog_print(DLOG_INFO, PANES_TAG, "Double clicked, hidden.\n");
      +   }
      +   else
      +   {
      +      elm_panes_content_left_size_set(obj, size);
      +      dlog_print(DLOG_INFO, PANES_TAG,
      +            "Double clicked, restoring size.\n");
      +   }
      +   size = tmp_size;
      +}
      +
      + +

      This is how to register this callback function to the Panes.

      +
      evas_object_smart_callback_add(panes, "clicked,double", _clicked_double_cb,
      +            panes);
      +
      + +

      Figure: Panes tutorial in action

      +

      Panes tutorial in action

      + + + + +
      + +Go to top + + + + + + + diff --git a/org.tizen.ui.guides/html/native/efl/popup_tutorial_wn.htm b/org.tizen.ui.guides/html/native/efl/popup_tutorial_wn.htm new file mode 100755 index 0000000..37b4ad8 --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/popup_tutorial_wn.htm @@ -0,0 +1,244 @@ + + + + + + + + + + + + + + Creating Wearable Popups + + + + + + +
      +

      Creating Wearable Popups

      + + +

      This tutorial teaches the basics of the popup component interactions.

      + + + + + + + + + + +
      Note
      This feature is supported in wearable applications only.
      + +

      Initializing the Popup Application

      + +

      This use case creates an application with a window entitled "Popup Basic Tutorial". The window consists of a conformant component, and a popup is placed inside the conformant.

      + +

      To create a typical elementary application:

      + +
      +static void
      +create_base_gui(appdata_s *ad)
      +{
      +   // Window
      +   ad->win = elm_win_util_standard_add("main", "Popup Basic Tutorial");
      +   elm_win_autodel_set(ad->win, EINA_TRUE);
      +
      +   evas_object_smart_callback_add(ad->win, "delete,request", win_delete_request_cb, NULL);
      +   eext_object_event_callback_add(ad->win, EEXT_CALLBACK_BACK, win_back_cb, ad);
      +
      +   // Conformant
      +   ad->conform = elm_conformant_add(ad->win);
      +   elm_win_indicator_mode_set(ad->win, ELM_WIN_INDICATOR_SHOW);
      +   elm_win_indicator_opacity_set(ad->win, ELM_WIN_INDICATOR_OPAQUE);
      +   evas_object_size_hint_weight_set(ad->conform, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +   elm_win_resize_object_add(ad->win, ad->conform);
      +   evas_object_show(ad->conform);
      +
      +   create_popup(ad->conform);
      +
      +   // Show the window after the base GUI is set up
      +   evas_object_show(ad->win);
      +}
      +
      +static bool
      +app_create(void *data)
      +{
      +   appdata_s *ad = data;
      +   create_base_gui(ad);
      +
      +   return true;
      +}
      +
      +int
      +main(int argc, char **argv)
      +{
      +   struct app_data ad = {0,};
      +   ui_app_lifecycle_callback_s event_callback = {0,};
      +
      +   event_callback.create = app_create;
      +
      +   return ui_app_main(&argc, &argv, &event_callback, &ad);
      +}
      + +

      Using Popup Styles

      + +

      To create popups using various styles:

      + +
      • Create a basic text-only popup: + +
        +Evas_Object *popup;
        +struct appdata *ad;
        +ad = (struct appdata *) data;
        +
        +popup = elm_popup_add(ad->win_main);
        +evas_object_size_hint_weight_set(popup, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
        +elm_popup_align_set(popup, ELM_NOTIFY_ALIGN_FILL, 1.0);
        +eext_object_event_callback_add(popup, EEXT_CALLBACK_BACK, eext_popup_back_cb, NULL);
        +elm_object_text_set(popup, "This has only texts");
        +evas_object_show(popup);
        +
      • + +
      • Create a popup with a title and text. The title,text attribute is the title area text part that defines the title label. +
        +Evas_Object *popup;
        +struct appdata *ad;
        +ad = (struct appdata *) data;
        +
        +popup = elm_popup_add(ad->win_main);
        +evas_object_size_hint_weight_set(popup, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
        +elm_popup_align_set(popup, ELM_NOTIFY_ALIGN_FILL, 1.0);
        +elm_object_part_text_set(popup, "title,text", "Title");
        +elm_object_text_set(popup,"This Popup has title area and text");
        +eext_object_event_callback_add(popup, EEXT_CALLBACK_BACK, eext_popup_back_cb, NULL);
        +evas_object_show(popup);
        +
      • + +
      • Create a popup with a title, text, and 2 buttons: +
        +Evas_Object *popup;
        +Evas_Object *btn;
        +struct appdata *ad = (struct appdata *) data;
        +
        +popup = elm_popup_add(ad->win_main);
        +evas_object_size_hint_weight_set(popup, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
        +elm_popup_align_set(popup, ELM_NOTIFY_ALIGN_FILL, 1.0);
        +elm_object_part_text_set(popup, "title,text", "Title");
        +eext_object_event_callback_add(popup, EEXT_CALLBACK_BACK, eext_popup_back_cb, NULL);
        +elm_object_text_set(popup, "This is title text 2button popup");
        +
        +btn = elm_button_add(popup);
        +elm_object_style_set(btn, "popup");
        +evas_object_size_hint_weight_set(btn, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
        +elm_object_text_set(btn, "Cancel");
        +elm_object_part_content_set(popup, "button1", btn);
        +evas_object_smart_callback_add(btn, "clicked", _response_cb, popup);
        +
        +btn = elm_button_add(popup);
        +elm_object_style_set(btn, "popup");
        +evas_object_size_hint_weight_set(btn, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
        +elm_object_text_set(btn, "OK");
        +elm_object_part_content_set(popup, "button2", btn);
        +evas_object_smart_callback_add(btn, "clicked", _response_cb, popup);
        +
        +evas_object_show(popup);
        +
      • + +
      • Create a toast popup: +
        +Evas_Object *popup;
        +struct appdata *ad = (struct appdata *) data;
        +
        +popup = elm_popup_add(ad->win_main);
        +elm_object_style_set(popup, "toast");
        +elm_popup_orient_set(popup, ELM_POPUP_ORIENT_BOTTOM);
        +evas_object_size_hint_weight_set(popup, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
        +elm_popup_align_set(popup, ELM_NOTIFY_ALIGN_FILL, 1.0);
        +eext_object_event_callback_add(popup, EEXT_CALLBACK_BACK, eext_popup_back_cb, NULL);
        +elm_object_part_text_set(popup,"elm.text", "Saving Contacts to sim");
        +
        +evas_object_smart_callback_add(popup, "block,clicked", _block_clicked_cb, NULL);
        +elm_popup_timeout_set(popup, 2.0);
        +evas_object_smart_callback_add(popup, "timeout", _timeout_cb, NULL);
        +
        +evas_object_show(popup);
        +
      • +
      + +

      Managing Popup Events

      +

      The Elementary popups respond to user interactions with several events.

      +

      To manage popup events:

      + +
        +
      • Handle timeout events: +

        The "timeout" event is triggered whenever a popup is closed as a result of timeout.

        +
        +static void _timeout_cb(void *data, Evas_Object *obj, void *event_info)
        +{
        +   evas_object_del(obj);
        +}
        +elm_popup_timeout_set(popup, 3.0);
        +evas_object_smart_callback_add(popup, "timeout", _timeout_cb, NULL);
        +
      • + +
      • Handle the block,clicked events: +

        The "block,clicked" event is triggered whenever the user taps on a blocked event area.

        +
        +static void _block_clicked_cb(void *data, Evas_Object *obj, void *event_info)
        +{
        +   evas_object_del(obj);
        +}
        +evas_object_smart_callback_add(popup, "block,clicked", _block_clicked_cb, NULL);
        +
      • + +
      + + + + + +
      + +Go to top + + + + + + + diff --git a/org.tizen.ui.guides/html/native/efl/rotary_events_n.htm b/org.tizen.ui.guides/html/native/efl/rotary_events_n.htm new file mode 100755 index 0000000..f6342f3 --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/rotary_events_n.htm @@ -0,0 +1,287 @@ + + + + + + + + + + + + + Managing Rotary Events + + + + + +
      +

      Managing Rotary Events

      + + +

      You can use various functions to work with the rotary events. The functions manage the rotary events, which are fired from the rotary device and delivered to a suitable target. To receive rotary events, you must define an event callback or a handler function, and register it using the EFL Extension functions. There are 2 ways to receive the rotary events: the rotary event handler and the rotary object event callback.

      + + + + + + + + + + + +
      Note
      Rotary events are only supported in devices with a circular screen.
      + +

      Rotary Event Handler

      + +

      The rotary event handler is suitable when you want to handle rotary events without taking care about an Evas Object or when the application is not implemented using an Evas Object. The handler works like the Ecore event in EFL:

      + +
      • The application registers a rotary event handler with the eext_rotary_event_handler_add() function.

        + +

        The rotary event handlers are treated "first come first served". It means that the first registered handler is called first when rotary events happens. If the handler returns EINA_TRUE, the next handler is called. Otherwise, EFL Extension stops delivering the rotary events.

        +
      • +
      • To remove a rotary event handler, use the eext_rotary_event_handler_del() function.

      + + + +

      Rotary Object Event Callback

      + +

      The rotary object event callback is suitable when you want EFL Extension to handle the event delivery between objects. It means that EFL Extension manages a callback and an object list and decides which object's callback must be called when rotary events happen:

      + +
      • The application registers a callback using the eext_rotary_object_event_callback_add() function.

        + +

        EFL Extension treats callbacks based on the callback priority. If the application registers callbacks for a same object, the callback with the lowest priority number is called first. If this callback returns EINA_TRUE, the higher priority number is called. The above function registers the rotary event callback with a default priority number (value is 0). To register the rotary event callback with another priority number, use the eext_rotary_object_event_callback_priority_add() function.

      • +
      • To remove a registered callback from an object, use the eext_rotary_object_event_callback_del() function:

      + +

      The rotary events are only delivered to 1 object named the activated object. If there is no activated object, the rotary event is not delivered to any object. If the activated object has registered callbacks and the callbacks return EINA_TRUE, the rotary events are delivered to the upper parents of the activated object until there is 1 callback that consumes the rotary event or it reaches the top parent object.

      +

      To set the object as the activated object, use the eext_rotary_object_event_activated_set() function.

      + +

      Providing the activated parameter with the EINA_TRUE value sets the object as the activated object. Providing the EINA_FALSE value deactivates the object. Since there is only 1 object which is the activated object, if an object is set as the activated object, the previously activated object is deactivated and becomes a normal object. An activated signal named rotary,activated is sent when an object is set as the activated object, and the rotary,deactivated signal is sent when an object is deactivated.

      + +

      You can register callbacks for activated or deactivated signals with the evas_object_smart_callback_add() function.

      + +

      For more information, see the Evas smart callback function (in mobile and wearable applications).

      + +

      Managing Rotary Events

      + +

      To manage rotary events:

      +
        +
      1. Create the rotary event handler: +
          +
        1. Create the window: +
          +static void
          +create_base_gui(appdata_s *ad)
          +{
          +Evas_Object *win = NULL;
          +
          +   // Window
          +   win = elm_win_util_standard_add(NULL, "extension circle sample");
          +   elm_win_autodel_set(win, EINA_TRUE);
          +   evas_object_smart_callback_add(win, "delete,request", win_delete_request_cb, NULL);
          +
          +   // Show the window after base gui is set up
          +   evas_object_show(win);
          +}
          +
          +
        2. + +
        3. Register the rotary event handler: +
          +static void
          +create_base_gui(appdata_s *ad)
          +{
          +   // Register the rotary event handler
          +   eext_rotary_event_handler_add(_rotary_handler_cb, NULL);
          +}
          +
        4. +
        5. Define the callback function: +
          +Eina_Bool _rotary_handler_cb(void *data, Eext_Rotary_Event_Info *ev)
          +{
          +   if (ev->direction == EEXT_ROTARY_DIRECTION_CLOCKWISE)
          +   {
          +      LOGD("Rotary device rotated in clockwise direction");
          +   }
          +   else
          +   {
          +      LOGD("Rotary device rotated in counter clockwise direction");
          +   }
          +
          +   return EINA_FALSE;
          +}
          +
          +
        6. + +
        7. Remove the rotary event handler and release all resources when you do not need it anymore. +
          +static void
          +app_terminate(void *data)
          +{
          +   // Release all resources
          +   eext_rotary_event_handler_del(_rotary_handler_cb);
          +}
          +
          +
        8. +
        +
      2. +
      3. Create a rotary event callback for a normal Evas object. +

        When a rotary event occurs, the slider value is adjusted accordingly.

        +
          +
        1. Create the objects. +

          The window and the slider are created using the Elementary APIs.

          +
          +static void
          +create_base_gui(appdata_s *ad)
          +{
          +   Evas_Object *win = NULL, *slider = NULL;
          +
          +   // Window 
          +   win = elm_win_util_standard_add(NULL, "extension sample");
          +   elm_win_autodel_set(win, EINA_TRUE);
          +   evas_object_smart_callback_add(win, "delete,request", win_delete_request_cb, NULL);
          +
          +   // Slider
          +   slider = elm_slider_add(win);
          +   evas_object_size_hint_weight_set(slider, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
          +   elm_slider_min_max_set(slider, 0, 50);
          +   elm_slider_step_set(slider, 1.0);
          +   evas_object_show(slider);
          +   elm_win_resize_object_add(win, slider);
          +
          +   // Show the window after the base GUI is set up 
          +   evas_object_show(win);
          +}
          +
          +
        2. +
        3. Register the rotary event callback. +

          To receive the rotary event, register the rotary event callback and set the activated object as the slider object.

          +
          +static void
          +create_base_gui(appdata_s *ad)
          +{
          +   // Register rotary event callback 
          +   ext_rotary_object_event_callback_add(slider, _rotary_event_cb, NULL);
          +   eext_rotary_object_event_activated_set(slider, EINA_TRUE);
          +}
          +
          +

          Define the rotary callback function:

          +
          +Eina_Bool _rotary_event_cb(void *data, Evas_Object *obj, Eext_Rotary_Event_Info *ev)
          +{
          +   Evas_Object *slider = obj;
          +   int val = elm_slider_value_get(slider);
          +   if (ev->direction == EEXT_ROTARY_DIRECTION_CLOCKWISE)
          +   {
          +      elm_slider_value_set(slider, val + 1);
          +   }
          +   else
          +   {
          +      elm_slider_value_set(slider, val - 1);
          +   }
          +
          +   return EINA_FALSE;
          +}
          +
          +
        4. +
        +
      4. +
      5. Create a rotary event callback for an EFL Extension object. +

        When a rotary event occurs, the slider value is adjusted accordingly.

        +
          +
        1. Create the objects: +
          +static void
          +create_base_gui(appdata_s *ad)
          +{
          +   Evas_Object *win = NULL, *conform = NULL;
          +   Eext_Circle_Surface *sur = NULL;
          +
          +   // Window 
          +   win = elm_win_util_standard_add(NULL, "extension circle sample");
          +   elm_win_autodel_set(win, EINA_TRUE);
          +   evas_object_smart_callback_add(win, "delete,request", win_delete_request_cb, NULL);
          +
          +   // Conformant
          +   conform = elm_conformant_add(win);
          +   elm_win_indicator_mode_set(win, ELM_WIN_INDICATOR_SHOW);
          +   elm_win_indicator_opacity_set(win, ELM_WIN_INDICATOR_OPAQUE);
          +   evas_object_size_hint_weight_set(conform, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
          +   elm_win_resize_object_add(win, conform);
          +   evas_object_show(conform);
          +
          +   // Surface 
          +   sur = eext_circle_surface_conformant_add(conform);
          +
          +   // Slider
          +   slider = eext_circle_object_slider_add(conform, sur);
          +   eext_circle_object_value_min_max_set(slider, 0.0, 30.0);
          +   eext_circle_object_value_set(slider, 0.0);
          +
          +   // Show the window after the base GUI is set up
          +   evas_object_show(win);
          +}
          +
          +
        2. +
        3. Set the activated object. +

          Since the EFL Extension API is used to create the slider object, the created slider object already registers the rotary event callbacks internally. To receive a rotary event, you only need to set the activated object as the desired object (slider).

          +
          +static void
          +create_base_gui(appdata_s *ad)
          +{
          +   // Activate circle slider's rotary object event
          +   // Its value increases/decreases its value by 1.0 to clockwise or 
          +   // counter-clockwise rotary event
          +   eext_rotary_object_event_activated_set(slider, EINA_TRUE);
          +   eext_circle_object_slider_step_set(slider, 1.0);
          +}
          +
          +
        4. +
        +
      6. +
      + + + + +
      + +Go to top + + + + + + + \ No newline at end of file diff --git a/org.tizen.ui.guides/html/native/efl/scalability_n.htm b/org.tizen.ui.guides/html/native/efl/scalability_n.htm new file mode 100755 index 0000000..de81e0a --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/scalability_n.htm @@ -0,0 +1,762 @@ + + + + + + + + + + + + + Scalability Support + + + + + +
      + +

      Scalability Support

      +

      To ensure that your application works well in diverse devices, you must consider scalability when designing the application layout:

      + + +

      Key Concepts

      + +

      When designing the application layout to be scalable, you must pay attention to the following key concepts:

      + +
      • Understand the character of the relative position and the fixed position + +

        In the relative position, the size is determined in proportion to the size of the referred object. For example, if an orange rectangle occupies 30% of the green rectangle, and the green rectangle is expanded, the orange rectangle is expanded accordingly. However, if the scaling value is changed and the green rectangle is not scaled, the orange rectangle remains unchanged too.

        + +

        Figure: Relative position

        +

        Relative position

        + +

        In the fixed position, the size is determined by a value set for the object. For example, the orange rectangle set to the size of 10. If the green rectangle is expanded, the orange rectangle does not change. However, if the scaling value is, for example, doubled, the size of the orange rectangle grows to 20.

        + +

        Figure: Fixed position

        +

        Fixed position

      • + +
      • Use the relative position +

        If you set the object size as a percentage, the ratio remains fixed regardless of the changes in the screen size or resolution. If you want the object size changed in proportion of the window size, use the relative position.

        + +

        Figure: Scaling relative position

        +

        Scaling relative position

      • + +
      • Multiply the scaling value, if you use the fixed size +

        If you use the EDC file to set up the layout, you can set the scale in the part element:

        +
        +parts 
        +{
        +   part 
        +   { 
        +      name: "box"; 
        +      type: RECT;
        +      scale: 1;
        +   }
        +}
        +
        + +

        If you set the fixed size in C code, you can use the ELM_SCALE_SIZE macro:

        +
        evas_object_size_hint_min_set(object, ELM_SCALE_SIZE(100), ELM_SCALE_SIZE(100));
        + +

        For more information see Applying the Base Scale.

      • + +
      • Do not fill the width or height out with a fixed size only +

        If you fill the entire height out with a fixed size only and it is scaled, the end result can be larger than the screen size.

        + +

        Figure: Height filled with a fixed size

        +

        Height filled with a fixed size

        + +

        If you set a partial width or height with a fixed size and leave the remaining area flexible, the layout does not expand outside the screen.

        + +

        Figure: Height with a flexible area

        +

        Height with a flexible area

      + + + +

      Scalability Using Elementary UI Components

      + +

      The Tizen platform provides a UI component toolkit library, called Elementary, that includes an extensive set of UI components. You can use elementary UI components to compose your application user interface (UI). While creating the UI, you can set specific properties for the UI components to control the scalable behavior of the UI. Before you try to create a scalable UI using elementary UI components, make sure you understand the following core concepts on how scalability works with elementary UI components.

      + + + + + + + + + + +
      Note
      The Elementary library provides 3 groups of APIs: +
      • Infrastructure: to control the behavior of elementary.
      • +
      • Container: UI components that can contain other UI components.
      • +
      • UI components: elementary UI components, such as buttons, lists, and check and radio boxes.
      + +

      Using Containers for Effective Layouts

      + +

      The Elementary library provides several containers to display UI components in an effective layout. The containers have no visual identity of their own.

      + +
      • Box + +

        The box container makes a layout where child UI components are stacked in either horizontal or vertical direction. The box size is the sum of its child UI components' size:

        +
        • A vertical box calculates its height as the sum of its children's height and its width as the width of the widest child.
        • +
        • A horizontal box calculates its width as the sum of its children's width and its height as the height of the tallest child.
        + +

        Figure: Box layout

        +

        Box layout

        + +

        The box-based linear layout is the best solution to ensure a minimum size for the child UI components in any device or any orientation.

      • + +
      • Grid + +

        The grid container makes a layout where child UI components set their position and size relative to the container position and size. You can define the virtual width and height of the grid (by default: 100 x 100). You then packs the child UI components into the grid while setting their position and size based on the virtual size of the grid.

        + +

        Figure: Grid layout

        +

        Grid layout

        + +

        The grid-based relative layout can always fill the full screen in any device or any orientation. However, the size of the child UI components is changed based on the screen size.

      + + +

      Using Weight and Align Properties

      + +

      To make a layout scalable with UI components, the UI components must be packed into a container using only the weight and align properties based on their minimum size. Do not resize the UI components directly using pixels.

      + +

      The weight and align properties are associated with every elementary UI component, and they serve as hints for the container they are in. They tell the container how the UI component wants to occupy the space and pack itself with other UI components in the container.

      + +

      Weight

      + +

      You can set the weight property with the evas_object_size_hint_weight_set(x_weight, y_weight) function:

      + +
      • Containers use the weights of the child UI components by normalizing them across all child UI components along both X and Y directions.
      • +
      • The parameter values can be 0 or positive values (default: 0.0). +

        0.0 means that the container allocates a minimum size of the UI component area.

        +

        1.0 (EVAS_HINT_EXPAND) means that the container allocates all of the remaining area to the UI component.

      • +
      • If the container has several UI components, it allocates the UI component area relative to the weights of other UI components.
      + +

      Figure: Weight hint

      +

      Weight hint

      + +

      Figure: Weight hint across multiple child UI components

      +

      Weight hint across multiple child UI components

      + +

      Align

      + +

      You can set the align property with the evas_object_size_hint_align_set(x_align, y_align) function:

      + +
      • UI components use the alignment for their position or size along both X and Y directions.
      • +
      • The parameter values can be from 0.0 to 1.0 or -1.0 (default: 0.5).
      • +
      • The values define positions as follows: left is (x=0.0), right is (x=1.0), top is (y=0.0), and bottom is (y=1.0). The center is (x=0.5, y=0.5). +

        -1.0 (EVAS_HINT_FILL) means that the UI component fills all of the allocated area.

      + +

      Figure: Alignment hint

      +

      Alignment hint

      + +

      Scalability Using Edje

      + +

      The Tizen platform provides a complex graphical design and layout library called Edje, which provides an abstraction layer between the application code and the interface. You can use Edje in your Tizen applications to create visual elements and control the layout, look, and feel.

      +

      Internally, Edje holds a geometry state machine and a state graph that defines, for example, what is visible, where, at what size, and with what colors. These details are described to Edje using an Edje .edj file. The file can be produced by using Edje_cc to take a text file (a .edc file) and "compile" an output .edj file that contains the state graph information, images, and any other needed data.

      + +

      While creating Edje, you set specific element properties to control the scalable behavior of the UI. Before creating a scalable UI using Edje, you must be familiar with the following scalability properties and part types.

      + +

      Part

      +

      Parts are used to represent the most basic layout elements, such as a line in a border or a text on an image.

      +

      The parts can have the following property:

      +
      • scale: 0-1 +

        Specifies whether the part scales its size with the scaling factor (Tizen has a scaling factor to resize the application layout and object). This property is used to scale properties, such as font size or min/max size of the part.

        +

        The default value is 0 (off) and the default scaling factor is 1.0. To make a part scalable, set the property to 1 (on).

        +
      + +

      Description

      +

      Every part can have one or more description blocks to define the layout properties of the part.

      +

      The descriptions can have the following properties:

      + +
      • min/max: width height +

        Specifies the minimum or maximum size of the part in pixels. It has no effect on the container size.

        +

        When the scale property of the part is set to 1 (on), the size is multiplied by the scaling factor.

      • + +
      • fixed: 0-1 0-1 +

        When the min or max property is set, this property sets a boolean value for each dimension (horizontal and vertical, respectively) that tells the application whether it must be scaled when resized.

        +

        The default value is 0 0. To fix a part size to its min or max, set the value to 1.

      • + +
      • align: X-axis Y-axis +

        When the displayed object size is smaller than its container, this property moves it along both axes using the relative position.

        +

        To move the property, use x = 0.0 to move to left, x = 1.0 to move to right, y = 0.0 to move to the top, and y = 1.0 to move to the bottom. The x = 0.5, y = 0.5 value sets the object at the center of its container.

        +

        The default value is 0.5 0.5.

      • + +
      • rel1/rel2 +

        Specifies the position of the left-top and bottom-right corners of the part's container.

        +
        • relative: X-axis Y-axis +

          Specifies the relative position of the part's container.

          +

          The default value is 0.0 0.0 for rel1.relative and 1.0 1.0 for rel2.relative.

        • +
        • to/to_x/to_y +

          Specified that a corner must be positioned relatively to another part's container.

          +

          By default, the corners of a part are placed to the whole interface.

        + + + + + + + + +
        Table: Edje part property example
        +
        +collections 
        +{
        +   group 
        +   {
        +      name: "property_test";
        +                                                                 
        +      images 
        +      {
        +         image: "panorama.png" COMP;
        +      }  
        +                                                                 
        +      parts 
        +      {
        +         part 
        +         {
        +            name: "rect1";
        +            type: RECT;
        +            description 
        +            {
        +               state: "default" 0.0;
        +               rel1 {relative: 0.3 0.4;}
        +               rel2 {relative: 0.7 0.6;}
        +               color: 0 127 255 255;
        +            }
        +         }
        +         part 
        +         {
        +            name: "rect2";
        +            type: RECT;
        +            // Affected by scaling factor
        +            scale: 1; 
        +            description 
        +            {
        +               state: "default" 0.0;
        +               fixed: 0 1;
        +               // Height: 100 pixels (when the scaling factor is 1.0)
        +               min: 0 100;
        +               rel1 {relative: 0.0 1.0;}
        +               rel2 {relative: 1.0 1.0;}
        +               // Bottom-aligned
        +               align: 0.5 1.0;
        +               color: 255 127 0 255;
        +            }
        +         }
        +         part 
        +         {
        +            name: "image";
        +            // Affected by scaling factor
        +            scale: 1;
        +            description 
        +            {
        +               state: "default" 0.0;
        +               fixed: 1 1;
        +               // Image size: 720 x 180 pixels (when the scaling factor is 1.0)
        +               min: 720 180;
        +               // Y-axis is positioned relative to "rect2" part
        +               rel1 {relative: 0.5 0.0; to_y: "rect2";}
        +               rel2 {relative: 0.5 0.0; to_y: "rect2";}
        +               // Bottom-aligned
        +               align: 0.5 1.0;
        +               image.normal: "panorama.png";
        +            }
        +         }
        +      }
        +   }
        +}
        +

        Part example

        +
      • + +
      • aspect: min max +

        Specifies the width to height ratio to keep when the part is resized. When both values are the same, the ratio is fixed. When they differ, the part is forced to keep the ratio between the min and max properties when resized.

        +

        The default value is 0.0 0.0.

      • + +
      • aspect_preference: dimension +

        Specifies the scope of the aspect property to a given dimension.

        +

        The possible values are BOTH, VERTICAL, HORIZONTAL, and NONE. The default is NONE.

        + + + + + + + + +
        Table: Edje part property aspect example
        +
        +collections 
        +{
        +   group 
        +   {
        +      name: "property_test";
        +
        +      images 
        +      {
        +         image: "island.png" COMP;
        +      }
        +   
        +      parts 
        +      {
        +         part 
        +         {
        +            name: "image";
        +            description 
        +            {
        +               state: "default" 0.0;
        +               rel1 {relative: 0.0 0.0;}
        +               rel2 {relative: 1.0 1.0;}
        +               image.normal: "island.png";
        +               aspect: 8/5 8/5;
        +               // Keep the aspect ratio based on the part width
        +               aspect_preference: HORIZONTAL;
        +            }
        +         }
        +      }
        +   }
        +}
        +

        Part aspect example

        +
      + +

      Text

      +

      The text elements are used to display text on the screen.

      +

      The texts can have the following properties:

      + +
      • size: font-size +

        Specifies the font size for the text. When the scale property of the part is set to 1 (on), the size is multiplied by the scaling factor.

      • + +
      • min: horizontal vertical +

        Specifies a pair of boolean values that define whether the container can be reduced further than the text size. The property is used to prevent the container from chopping the text.

        +

        When min is set horizontally or vertically, the minimum height or width of the part is decided by the text size.

        +

        The default value is 0 0.

      • + +
      • max: horizontal vertical +

        Specifies a pair of boolean values that define whether the container can be expanded further than the text size.

        +

        When max is set horizontally or vertically, the maximum height or width of the part is decided by the text size.

        +

        The default value is 0 0.

        + + + + + + + + +
        Table: Edje text property example
        +
        +collections 
        +{
        +   group 
        +   {
        +      name: "property_test";
        +
        +      parts 
        +      {
        +         part 
        +         {
        +            name: "text";
        +            type: TEXT;
        +            scale: 1;
        +            description 
        +            {
        +               state: "default" 0.0;
        +               rel1 {relative: 0.0 0.0;}
        +               rel2 {relative: 1.0 0.0;}
        +               align: 0.5 0.0;
        +               color: 108 108 108 255;
        +               text 
        +               {
        +                  font: "TIZEN";
        +                  // Affected by scaling factor
        +                  size: 80;
        +                  // Minimum height of the part container is decided by the text size
        +                  min: 0 1;
        +                  text: "Test properties!!";
        +               }
        +            }
        +         }
        +      }
        +   }
        +}
        +

        Text example

        + +
      • +
      • fit: horizontal vertical +

        Specifies a pair of values that define whether the text is scaled to fill its container horizontally and/or vertically.

        +

        The default value is 0 0.

        + + + + + + + + +
        Table: Edje text property fit example
        +
        +collections 
        +{
        +   group 
        +   {
        +      name: "property_test";
        +
        +      parts 
        +      {
        +         part 
        +         {
        +            name: "text";
        +            type: TEXT;
        +            description 
        +            {
        +               state: "default" 0.0;
        +               rel1 {relative: 0.0 0.0;}
        +               rel2 {relative: 1.0 0.1;}
        +               color: 108 108 108 255;
        +               text 
        +               {
        +                  font: "TIZEN";
        +                  // Resize text to fill the container height
        +                  fit: 0 1;
        +                  text: "Test properties!!";
        +               }
        +            }
        +         }
        +      }
        +   }
        +}
        +

        Text fit example

      + + +

      Image

      +

      The image elements are used to display images on the screen.

      +

      The images can have the following properties:

      + +
      • border: left right top bottom +

        Specifies the border size of the image in pixels. This property sets the area of each side of the image to be displayed as a fixed size border, preventing the corners from being changed on a resize.

      • + +
      • border_scale +

        Specifies whether the border scales its size according to the scaling factor.

        +

        The default value is 0 (off). To make the border scalable, the value must be set to 1 (on).

        + + + + + + + + +
        Table: Edje image property example
        +
        +collections 
        +{
        +   group 
        +   {
        +      name: "property_test";
        +
        +      images 
        +      {
        +         image: "00_button_01_normal.png" COMP;
        +      }
        +
        +      parts 
        +      {
        +         part 
        +         {
        +            name: "image";
        +            description 
        +            {
        +               state: "default" 0.0;
        +               rel1 {relative: 0.0 0.6;}
        +               rel2 {relative: 1.0 0.7;}
        +               image.normal: "00_button_01_normal.png";
        +            }
        +         }
        +         part 
        +         {
        +            name: "ninepatch_image";
        +            description 
        +            {
        +               state: "default" 0.0;
        +               rel1 {relative: 0.0 0.8;}
        +               rel2 {relative: 1.0 0.9;}
        +               image 
        +               {
        +                  normal: "00_button_01_normal.png";
        +                  border: 4 4 0 0;
        +                  // Affected by scaling factor
        +                  border_scale: 1;
        +               }
        +            }
        +         }
        +      }
        +   }
        +}
        +

        Image example

        + +
      +

      Image Set

      +

      The image set elements are used to display a specific image on the screen based on the container size.

      +

      The image sets can have the following properties:

      + +
      • name: image-name +

        Specifies the name of the image file.

      • + +
      • size: minw minh maxw maxh +

        Specifies the minimum and maximum size that causes a specified image to be selected and shown.

        +

        The image set is used to control resource quality when the image part is scaled to multiple devices. According to the size of the part's container, an appropriate image is loaded.

        + + + + + + + + +
        Table: Edje image set property example
        +
        +collections 
        +{
        +   group 
        +   {
        +      name: "property_test";
        +
        +      images 
        +      {
        +         set 
        +         {
        +            name: "alternative_animal";
        +            image 
        +            {
        +               image: "pig.png" COMP;
        +               size: 640 800 1200 1500;
        +            }
        +            image 
        +            {
        +               image: "monkey.png" COMP;
        +               size: 400 500 639 799;
        +            }
        +            image 
        +            {
        +               image: "cat.png" COMP;
        +               size: 240 300 399 499;
        +            }
        +            image 
        +            {
        +               image: "mouse.png" COMP;
        +               size: 80 100 239 299;
        +            }
        +            image 
        +            {
        +               image: "snail.png" COMP;
        +               size: 0 0 79 99;
        +            }
        +         }
        +      }
        +
        +      parts 
        +      {
        +         part 
        +         {
        +            name: "image1";
        +            description 
        +            {
        +               state: "default" 0.0;
        +               rel1 {relative: 0.0 0.0;}
        +               rel2 {relative: 1.0 0.45;}
        +               image.normal: "alternative_animal";
        +               aspect: 4/5 4/5;
        +               aspect_preference: BOTH;
        +            }
        +         }
        +         part 
        +         {
        +            name: "image2";
        +            description 
        +            {
        +               state: "default" 0.0;
        +               rel1 {relative: 0.0 0.5;}
        +               rel2 {relative: 1.0 0.75;}
        +               image.normal: "alternative_animal";
        +               aspect: 4/5 4/5;
        +               aspect_preference: BOTH;
        +            }
        +         }
        +         part 
        +         {
        +            name: "image3";
        +            description 
        +            {
        +               state: "default" 0.0;
        +               rel1 {relative: 0.0 0.8;}
        +               rel2 {relative: 1.0 1.0;}
        +               image.normal: "alternative_animal";
        +               aspect: 4/5 4/5;
        +               aspect_preference: BOTH;
        +            }
        +         }
        +      }
        +   }
        +}
        +

        Image set example

        +
      + +

      Part Types

      +

      You can use fixed and flexible parts:

      + +
      • Fixed parts + +
        • Fixed parts have a minimum size (at least width or height).
        • +
        • When the part scale property is set to 1 (on), the scaling factor has an effect on the minimum size.
        • +
        • Fixed parts are used when the parts must keep a fixed size in any device or any orientation.
      • +
      • Flexible parts +
        • Flexible parts resize according to the container size and other fixed parts' size.
        • +
        • Flexible parts are used when the parts can be resized in any device or any orientation.
      + +

      Figure: Fixed and flexible parts

      +

      Fixed and flexible parts

      + + +

      Aspect Ratio

      + +

      In Tizen, the application generally fills out the screen. However, sometimes you want the application to be shown in a specific aspect ratio, regardless of the screen size.

      +

      As images are scaled in different devices, they are resized based on the container size. The images have specific properties that define the area to be shown when resized.

      + +

      For example, the following table illustrates what happens to the parts marked with yellow rectangles in the following figures, when scaling properties are applied.

      + +

      Figure: Original image [1920x1280 (8:5)]

      +

      Original image [1920x1280 (8:5)]

      + + + + + + + + + + + +
      Note
      To set the required aspect ratio, use the evas_object_size_hint_aspect_set() function or the aspect_preference attribute in the EDC.
      + + + ++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Table: Image resizing effects with a specific aspect ratio
      AspectContainer area
      720x384 (15:8)720x640 (9:8)
      HORIZONTAL +

      Resizing based on the container width while keeping the image aspect ratio.

      +

      Extra height goes outside the image area and is clipped.

      Scaling effect

      Scaling effect

      VERTICAL +

      Resizing based on the container height while keeping the image aspect ratio.

      +

      Extra width goes outside the image area and is clipped.

      Scaling effect

      Scaling effect

      BOTH +

      Resizing based on the container area while keeping the image aspect ratio.

      +

      No extra width or height goes outside the image area, so the entire image is always shown.

      Scaling effect

      Scaling effect

      NONE +

      Resizing to fill the available area while keeping the image aspect ratio.

      +

      Extra width or height goes outside the image area and is clipped.

      Scaling effect

      Scaling effect

      + +

      Setting the Image Aspect Ratio

      +

      In case of an image object, you can set its aspect ratio with additional APIs:

      + +
      • elm_image_fill_outside_set() +

        If the function is set to TRUE, the image resizes to fill the entire area while keeping its aspect ratio. It lets the extra width or height go outside of the area (same result as with the aspect NONE in the above table).

      • + +
      • elm_image_aspect_fixed_set() + +

        If the function is set to FALSE, the image resizes to fill the entire area without keeping its original aspect ratio. The image can be distorted to fit the area.

        + + + + + + + + + + + + + + +
        Table: Image resizing without keeping the aspect ratio
        Container area
        720x384 (15:8)720x640 (9:8)

        Scaling effect

        Scaling effect

        +
      + + + + + +
      + +Go to top + + + + + + + \ No newline at end of file diff --git a/org.tizen.ui.guides/html/native/efl/theme_n.htm b/org.tizen.ui.guides/html/native/efl/theme_n.htm new file mode 100755 index 0000000..00ac2ce --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/theme_n.htm @@ -0,0 +1,72 @@ + + + + + + + + + + + + + Themes: Specifying the UI Look and Feel + + + + + +
      + +

      Themes: Specifying the UI Look and Feel

      + + +

      Tizen provides powerful theme features you can use to easily change your applications' UI look and feel. A theme is a collection of visual identities, which provide the graphical appearance of applications. A theme comprises a layout, shapes, fonts, and colors for the UI components.

      + +

      The Tizen platform provides a default theme for UI components implemented based on the Tizen UX design concept (AIR – light and simple). To change the current look and feel, you can replace the default theme with a customized theme package.

      + +

      The Edje library used by Elementary provides themes. You can also use Edje to create your own objects to modify the application appearance with a unique GUI. The UI components are customizable so that each application can have its own customized theme to overlay the default theme.

      + +

      Edje supports separation between layout and logic. While it is possible to implement both GUI and logic in the C code, a loose coupling of GUI and logic is more convenient when you want to revise, add, or delete application UI components. In EFL, the GUI is handled by Edje, while application logic is handled in the C code.

      + +

      Edje was designed as a theme layer for moving the look, feel, and animation of objects into separate data files loaded at runtime. Using a plain text EDC file you can create your application's layout without writing a single line of code. EFL can even change the theme of application at runtime without restarting the application.

      + + + + +
      + +Go to top + + + + + + + \ No newline at end of file diff --git a/org.tizen.ui.guides/html/native/efl/threads_n.htm b/org.tizen.ui.guides/html/native/efl/threads_n.htm new file mode 100755 index 0000000..0e837b2 --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/threads_n.htm @@ -0,0 +1,507 @@ + + + + + + + + + + + + + Using Threads + + + + + +
      + +

      Using Threads

      + +

      Threads are concurrent execution environments that are lighter than full-blown processes because they share some operating system resources. Threads make it possible to do several things at the same time while using less resources and offering simpler synchronization and data exchange compared to processes.

      + +

      If you move a blocking operation to a separate thread, it cannot block the event loop and keeps the user interface reactive. Blocking the event loop and using long-running callbacks means the application cannot update its graphical user interface.

      + +

      While threads can be useful, they are not always the best choice:

      + +
      • The first rule to using threads is to avoid them as much as possible, as there are often better tools and approaches. For example, to do network transfers, use Ecore_Con that integrates with the event loop to use a function based on callbacks. Being able to use such a function means that specific support work has been done in libraries. In some cases, using a function and libraries is impossible, and in those situations threads are required.
      • +
      • Use threads in CPU-intensive tasks and disk IOs. For example, a thread is the appropriate way to apply filters to an image or to a video without blocking the interface.
      • +
      • Use threads to take advantage of multiple available CPU cores, if the workload can be split into several units of work and spread across the cores. A typical example for an image processing application on a quad-core CPU is to process 4 images at once, each on 1 thread. For such tasks, the thread pool helps with the creation and scheduling of the threads, handling all the grunt work.
      + +

      Thread Safety

      + +

      If several strings have to work on the same resources, conflicts can happen as the threads are run in parallel. For example, if thread A modifies several values while thread B is reading them, it is likely that some of the values read by B are outdated. Similar issues can happen if both threads are modifying data concurrently.

      + +

      These kinds of conflicts are called race-conditions: depending on which thread is faster, the output changes and can be incorrect. Avoiding such issues is called thread safety. Thread safety involves critical sections, which are blocks of code that operate on shared resources and must not be accessed concurrently by another thread.

      + +

      The usual solution for ensuring exclusive access to shared resources is mutual exclusion: only 1 thread can operate on the data at any given time. Mutual exclusion is often implemented through locks. Before attempting to operate on a shared resource, the thread waits until it can lock something called a mutex (stands for mutual exclusion), then operates on the resource, and unlocks the mutex. Operating systems guarantee that only 1 thread can lock a mutex at a given time: this ensures that only 1 thread operates on the shared resource at one time.

      + +

      For more information on thread safety, see Low-level Functions.

      + +

      Thread Pools

      + +

      Threads are operating system resources: while much lighter than processes, they still have a cost. Moreover, spawning a thousand threads means that each of them only gets 1/1000th of the total CPU time: each thread is progressed slowly and, in the worst case, the system wastes all of its time switching between threads without doing any actual work.

      + +

      Thread pools solve this problem. In thread pools, upto a maximum number of threads are created on-demand and used to execute tasks. When the tasks are finished, they are kept alive but sleeping. This avoids the cost of creating and destroying them.

      + +

      In EFL, the thread pool is controlled by a thread_max parameter, which defines the maximum number of threads running at the same time. Another control feature is the func_end() callback that runs from the main loop thread after a task has completed and is typically used to extract the data from the finished task and make it available to the main loop.

      + +

      To manage the maximum number of threads:

      + +
        +
      • To retrieve the current value, use the ecore_thread_max_get() function. +
      • + +
      • To set the value, use the ecore_thread_max_set() function. The value has a maximum of 16 times the CPU count. +
      • + +
      • To reset the maximum number of threads, use the ecore_thread_max_reset() function. + +
      • + +
      • To get the number of available threads in the pool, use the ecore_thread_available_get() function. The function returns the current maximum number of threads minus the number of running threads. The number can be a negative value, if the maximum number of threads has been lowered. +
      • +
      + +

      The following figures illustrate the thread pool. The first figure shows the occupancy of a hypothetical thread pool. There are several tasks, of which 4 are running. The thread_max parameter of the pool is 4, and the other tasks are waiting. There is no thread with its func_end() callback currently called.

      + +

      Figure: Thread pool, step 1

      +

      Thread pool, step 1

      + +

      When a task, applying the sepia filter on image1, finishes, the corresponding func_end() function is invoked from the main loop.

      + +

      Figure: Thread pool, step 2

      +

      Thread pool, step 2

      + +

      With the task done, one of the threads from the pool becomes available, and another thread, adding the reverberation effect on audio3, can run in it.

      + +

      Figure: Thread pool, step 3

      +

      Thread pool, step 3

      + +

      As long as there are tasks to be done, the thread pool continues the same way, running tasks in its threads whenever a thread is available.

      + + +

      Thread Management with Ecore

      + +

      Ecore offers a simplified API for managing threads in EFL applications. The Ecore API applies to a typical scenario where the main thread creates another thread, which in turn sends data back to the main thread or calls GUI-related functions. GUI-related functions are not thread-safe.

      + +

      Creating Threads with Ecore

      + +

      The threads created with Ecore are by default integrated with the thread pool and offer simple callback-based ways to interact with the main loop. New threads are created as needed until the maximum capacity of the thread pool is reached.

      + +
      • To return values to the main thread: +

        Use the ecore_thread_feedback_run() function to send intermediate feedback from the thread to the main loop.

      • + +
      • To return only the final value to the main thread: +

        To create and run a thread, use the ecore_thread_run() function. It runs a function inside a thread from the thread pool and takes care of all the low-level work. It returns the corresponding thread handler or NULL on failure.

        + +

        The most common way to return data from one thread to the main thread is to put a pointer to it in the data. When the thread is aborted or finishes, either func_cancel() or func_end() is called from the main loop. The functions are running in the simpler context of a single thread running at once and therefore avoid race-conditions.

        + +

        The data pointer approach can only be used when the data is shared between the one thread and the main thread only. However, this does not prevent you from using the func_end() callback to merge the results into a single data structure. For example, you can add all the values computed by the threads to an Eina_List, as all the operations on the list happen from a single thread and therefore one after the other and not concurrently.

      + + +

      Running Callbacks from the Main Loop

      + +

      If you are performing operations in another thread and want to update a progress bar, the update operation must be done from the main thread. The simplest way is to use the ecore_main_loop_thread_safe_call_async() function, which takes a function and some data as parameters and instructs the main loop to execute the given function with the given data.

      + +

      Depending on the kind of thread the function is called from, the process differs:

      +
        +
      • If the function is called from a thread that is not the main one, the function sends a message to the main loop and returns quickly. The message is processed in order, similarly to others.
      • + +
      • If the function is called from the main thread, the function is called immediately as if it were a direct call.
      • +
      + +

      If you want to wait until the callback is called and returns, use the ecore_main_loop_thread_safe_call_sync() function, which is similar but synchronous. Since it is synchronous, it can also return the value returned by the callback.

      + +

      Low-level Functions

      + +

      Eina offers low-level functions that are portable across the operating system, such as locks, conditions, semaphores, barriers, and spinlocks. The functions follow closely the logic of pthreads.

      + +

      While these functions are useful, they are building blocks and not usually useful in EFL applications considering the higher-level functions that are available in Ecore.

      + +

      For an introduction to threads and pthreads in particular, see:

      + + + +

      If you are already familiar with threads, see the standard pthreads documentation and the Eina reference documentation, or the following function lists. Remember that the Eina functions map very closely to the pthreads functions.

      + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Locks (mutual exclusions)
      pthreads functionEina equivalent
      pthread_mutex_new()eina_lock_new()
      pthread_mutex_destroy()eina_lock_free()
      pthread_mutex_lock()eina_lock_take()
      pthread_mutex_trylock()eina_lock_take_try()
      pthread_mutex_unlock()eina_lock_release()
      none (prints debug information on the lock)eina_lock_debug()
      + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Conditions (notifications when condition objects change)
      pthreads functionEina equivalent
      pthread_cond_init()eina_condition_new()
      pthread_cond_destroy eina_condition_free()
      pthread_cond_wait()eina_condition_wait()
      pthread_cond_timedwait()eina_condition_timedwait()
      pthread_cond_broadcast()eina_condition_broadcast()
      pthread_cond_signal()eina_condition_signal()
      + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + +
      RWLocks (Read-write locks, for multiple-readers/single-writer scenarios)
      pthreads functionEina equivalent
      pthread_rwlock_init() +eina_rwlock_new()
      pthread_rwlock_destroy()eina_rwlock_free()
      pthread_rwlock_rwlock_rdlock() +eina_rwlock_take_read()
      pthread_rwlock_rwlock_wrlock() +eina_rwlock_take_write()
      pthread_rwlock_unlock() +eina_rwlock_release()
      + + + ++++ + + + + + + + + + + + + + + + + + + + + + + +
      TLS (Thread-Local Storage)
      pthreads functionEina equivalent
      pthread_key_create()eina_tls_new()
      pthread_key_delete()eina_tls_free()
      pthread_getspecific()eina_tls_get()
      pthread_setspecificeina_tls_set()
      + + + ++++ + + + + + + + + + + + + + + + + + + + + + + +
      Semaphores (access restrictions for a set of resources)
      pthreads functionEina equivalent
      sem_init()eina_semaphore_new()
      sem_destroy()eina_semaphore_free()
      sem_wait()eina_semaphore_lock()
      sem_post()eina_semaphore_release()
      + + + ++++ + + + + + + + + + + + + + + + + + + +
      Barriers
      pthreads functionEina equivalent
      pthread_barrier_init()eina_barrier_new()
      pthread_barrier_destroy()eina_barrier_free()
      pthread_barrier_wait()eina_barrier_wait()
      + +

      Thread Use Examples

      + +

      The following examples display a window with a label. An auxiliary thread semi-regularly changes the text of the label. If you want to display a regular animation, use the Ecore animators described in the Main Loop guide.

      + +

      To use the ecore_thread_feedback() function:

      + +
        + +
      1. Implement the GUI function that sets the text of a label and can be called from the main thread. + +
        +static void
        +_set_label_text(void *data, Ecore_Thread *thread __UNUSED__, void *msgdata)
        +{
        +   char buf[64];
        +   appdata_s *ad = data;
        +   snprintf(buf, sizeof(buf), "Tick %d", (int)(uintptr_t)msgdata);
        +   elm_object_text_set(ad->label, buf);
        +}
        +
        +
      2. +
      3. Send the feedback from the other thread using the ecore_thread_feedback() function. The following function does nothing besides sending the feedback and sleeping. + +
        +static void
        +_long_function(void *data __UNUSED__, Ecore_Thread *thread)
        +{
        +   int iteration;
        +   // Change the text roughly every 1 second. This is only an example; if you
        +   // want regular animations, use Ecore animators!
        +   for (iteration = 0; ; iteration++) 
        +   {
        +      // Since you are running from another thread, you need to take special
        +      // care and instead send data to the main thread and have it run the
        +      // feedback function given when creating the thread
        +      ecore_thread_feedback(thread, (void*)(uintptr_t)iteration);
        +      // Sleep for roughly one second
        +      sleep(1);
        +   }
        +}
        +
        +
      4. + +
      5. Create an end function that is called when the thread exits. In this example, the end function is called only right before the application exits. However, if the blocking function is more complex, it can trigger the end function. + +
        +static void
        +_end_func(void *data, Ecore_Thread *thread __UNUSED__)
        +{
        +   appdata_s *ad = data;
        +   elm_object_text_set(ad->label, "Ticks over");
        +}
        +
        +
      6. + +
      7. Call the ecore_thread_feedback_run() function to start the thread: + +
        +ecore_thread_feedback_run(_long_function, _set_label_text, _end_func, NULL, ad, EINA_FALSE);
        +
        +
      8. +
      + +

      To use the ecore_main_loop_thread_safe_call_sync() function:

      + +
        +
      1. Implement the GUI function that sets the text of a label and can be called from the main thread. The function receives data as a structure and alternatively displays "Tick d" or "Tock d". + +
        +struct thd 
        +{
        +   appdata_s *ad;
        +   Eina_Bool tick_not_tock;
        +   int iteration;
        +};
        +static void *
        +_set_label_text_tick_tock(void *data)
        +{
        +   char buf[64];
        +   struct thd *thd = data;
        +   snprintf(buf, sizeof(buf), "%s %d", (thd->tick_not_tock ? "Tick" : "Tock"), thd->iteration);
        +   elm_object_text_set(thd->ad->label, buf);
        +
        +   return NULL;
        +}
        +
        +
      2. + +
      3. Use the ecore_main_loop_thread_safe_call_sync() function call the GUI function. Differentiate between the ticks and the tocks: + +
        +static void
        +_long_function_tick_tock(void *data, Ecore_Thread *thread __UNUSED__)
        +{
        +   struct thd *thd = malloc(sizeof(struct thd));
        +   thd->ad = data;
        +   for (thd->iteration = 0; ; (thd->iteration)++) 
        +   {
        +      thd->tick_not_tock = EINA_TRUE;
        +      ecore_main_loop_thread_safe_call_sync(_set_label_text_tick_tock, thd);
        +      sleep(1);
        +      thd->tick_not_tock = EINA_FALSE;
        +      ecore_main_loop_thread_safe_call_sync(_set_label_text_tick_tock, thd);
        +      sleep(1);
        +   }
        +   free(thd);
        +}
        +
        +
      4. + +
      5. Start the thread through the ecore_thread_run() function: + +
        +ecore_thread_run(_long_function_tick_tock, _end_func, NULL, ad);
        +
        +
      6. +
      + + + + + + + + + + +
      Note
      Except as noted, this content is licensed under LGPLv2.1+.
      + + + +
      + +Go to top + + + + + + + \ No newline at end of file diff --git a/org.tizen.ui.guides/html/native/efl/tools_n.htm b/org.tizen.ui.guides/html/native/efl/tools_n.htm new file mode 100755 index 0000000..eba7d01 --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/tools_n.htm @@ -0,0 +1,243 @@ + + + + + + + + + + + + + Tools + + + +
      +
      +

      Mobile native Wearable native

      +
      + + +
      + +
      + +

      Tools

      +

      Eina provides a number of tools, such as string manipulation, that make your life easier when coding applications:

      + +
        +
      • Convert fast: conversion from, for example, strings to integers and double
      • +
      • Counter: measures the number of calls and their time
      • +
      • Error: error identifiers
      • +
      • File: file list and path split
      • +
      • Lazy allocator: lazy allocator
      • +
      • Log: full-featured logging system
      • +
      • Magic: provides runtime type checking
      • +
      • Memory Pool: abstraction for various memory allocators
      • +
      • Module lists: loads and shares modules using the Eina_Module standard
      • +
      • Rectangle: rectangle structure and standard manipulation methods
      • +
      • Safety Checks: extra checks that report unexpected conditions and can be disabled during compilation
      • +
      • String: set of functions that manage C strings
      • +
      + +

      String

      + +

      When creating applications, you always need to manipulate strings. Eina provides a very useful API for manipulating C strings:

      + +
      • + +

        The most common string manipulation is the "split". If you have a string, such as "Rasterman:Bluebugs:Tasn:Illogict:billiob:Puppet_Master", and you want to print it in an easily readable format, you can use the eina_str_split() function to split the string using a delimiter. The first parameter is the string to split, the second determines where to split the string, and the final parameter is the maximum number of strings to split the string into. If you set a number less than 1, it splits the string as many times as possible.

        +

        The function returns a newly-allocated NULL-terminated array of strings, or NULL, if it fails to allocate the array. Always remember to free the memory allocated by the eina_str_split() function.

        + +
        +char *nicks = "Rasterman:Bluebugs:Tasn:Illogict:billiob:Puppet_Master";
        +char **result_arr;
        +int i;
        +
        +// Splitting the string with ':' delimiter
        +result_arr = eina_str_split(names, ":", 0);
        +// Printing the result
        +for (i = 0; result_arr[i]; i++)
        +   printf("Nick : %s\n", result_arr[i]);
        +// Remember to free memory
        +free(arr[0]);
        +free(arr);
        +
      • + + +
      • To change the string to lowercase or uppercase, use the eina_str_tolower() and eina_str_toupper() functions. They change the case for all characters of the given string. These functions modify the original strings.

        + +
        +char *str;
        +// Initialize the string
        +str = malloc(sizeof(char) * 4);
        +strcpy(str, "bsd");
        +// Change the string to uppercase
        +eina_str_toupper((char **)&str);
        +printf("%s\n", str);
        +// Change the string to lowercase
        +eina_str_tolower(&str);
        +printf("%s\n", str);
        +// Free the allocated memory
        +free(str);
        +
      • +
      • If you need to "join" 2 strings of known length, use the eina_str_join() function. The fist parameter is the buffer to store the result, the second is the size of the buffer, the third is the separator between the 2 strings, and the 2 final parameters are the stings to be joined.

        + +
        +char *part1 = "Tizen powered by";
        +char *part2 = "Enlightenment Foundation Libraries";
        +char *res;
        +size_t size;
        +// Calculate the string size + 1 for the delimiter
        +size = strlen(part1) + strlen(part2) + 1
        +// Allocate memory for the result
        +res = malloc(sizeof(char) * size);
        +// Join the strings
        +eina_str_join(res, size, ' ', part1, part2);
        +printf("%s\n", res);
        +// Free the allocated memory
        +free(res):
        +
      • +
      • To check whether a string starts or ends with another string, use the eina_str_has_prefix() or eina_str_has_suffix() function. You can also check whether a string has a particular extension with the eina_str_has_extension() function.

        + +

        These functions return EINA_TRUE if the given string contains the specified prefix, suffix, or extension, and EINA_FALSE if it does not.

        + +
        +char *names = "Carsten;Cedric;Tom;Chidambar;Boris;Philippe"
        +if (eina_str_has_prefix(names, "Carsten"))
        +   printf("String starts with 'Carsten'")
        +if (eina_str_has_suffix(names, "Philippe"))
        +   printf("String ends with 'Philippe'")
        +if (eina_str_has_extension(names, "philippe"))
        +   printf("String has extension 'philippe'")
        +else
        +   printf("String does not have extension "philippe)
        +
      + +

      Memory Pool

      + +

      The Eina_Mempool tool provides memory pool functionality. With a memory pool, you can preallocate fixed-size memory spaces for easy memory management.

      + +

      The following mempools are available:

      +
        +
      • buddy
      • +
      • chained_pool
      • +
      • ememoa_fixed and ememoa_unknown
      • +
      • fixed_bitmap
      • +
      • pass_through
      • +
      • one_big
      • +
      + +

      Safety Checks

      + +

      Eina safety checks are a set of macros that can be used to check for parameters or values that must never occur. The concept is similar to the assert() function, but safety checks log the parameter or value and return instead of aborting your program.

      + +

      The following safety checks are available:

      +
        +
      • EINA_SAFETY_ON_NULL_RETURN(exp)
      • +
      • EINA_SAFETY_ON_NULL_RETURN_VAL(exp, val)
      • +
      • EINA_SAFETY_ON_NULL_GOTO(exp, label)
      • +
      • EINA_SAFETY_ON_TRUE_RETURN(exp)
      • +
      • EINA_SAFETY_ON_TRUE_RETURN_VAL(exp, val)
      • +
      • EINA_SAFETY_ON_TRUE_GOTO(exp, label)
      • +
      • EINA_SAFETY_ON_FALSE_RETURN(exp)
      • +
      • EINA_SAFETY_ON_FALSE_RETURN_VAL(exp, val)
      • +
      • EINA_SAFETY_ON_FALSE_GOTO(exp, label)
      • +
      • EINA_ARG_NONNULL(...)
      • +
      + +

      To return if a variable is NULL, use the EINA_SAFETY_ON_NULL_RETURN() function. This macro calls return if the given parameter is NULL.

      + +
      +Eina_Bool myfunction(char *param) 
      +{
      +   // If my param is NULL, EINA_SAFETY_ON_NULL_RETURN calls "return"
      +   EINA_SAFETY_ON_NULL_RETURN(param);
      +
      +   printf("My pram is : %s\n", param);
      +
      +   return EINA_TRUE;
      +} 
      +
      + +

      To return a specific value, use the EINA_SAFETY_ON_NULL_RETURN_VAL() function instead of the EINA_SAFETY_ON_NULL_RETURN() function. This macro returns the given value.

      + +
      +Eina_Bool void myfunction(char *param)
      +{
      +   // If the parameter is NULL, return EINA_FALSE;
      +   EINA_SAFETY_ON_NULL_RETURN_VAL(param, EINA_FALSE);
      +   printf("My pram is : %s\n", param);
      +
      +   return EINA_TRUE;
      +}
      +
      + +

      To call another function if a parameter is NULL, use the EINA_SAFETY_ON_NULL_GOTO() function. This macro works similarly to the EINA_SAFETY_ON_NULL_RETURN() function except that it calls goto with the given function instead of return.

      + +
      +static void isnullcb()
      +{
      +   printf("The parameter is NULL\n");
      +}
      +Eina_Bool void myfunction(char *param)
      +{
      +   // If the parameter is NULL we return EINA_FALSE;
      +   EINA_SAFETY_ON_NULL_GOTO(param, isnullcb);
      +   printf("My pram is : %s\n", param);
      +
      +   return EINA_TRUE;
      +}
      +
      + +

      Eina also provides macros that check whether a given value is TRUE or FALSE. For example, to call return if a given value is TRUE, use the EINA_SAFETY_ON_TRUE_RETURN() function. To call "goto" in a given function if a given value is TRUE, use the EINA_SAFETY_ON_NULL_GOTO() function.

      + + + + + + + + + + + +
      Note
      Except as noted, this content is licensed under LGPLv2.1+.
      + + + +
      + +Go to top + + + + + + + \ No newline at end of file diff --git a/org.tizen.ui.guides/html/native/efl/touch_gesture_n.htm b/org.tizen.ui.guides/html/native/efl/touch_gesture_n.htm new file mode 100755 index 0000000..e295894 --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/touch_gesture_n.htm @@ -0,0 +1,265 @@ + + + + + + + + + + + + + + Handling Component Touch Gestures + + + + + + +
      +

      Handling Component Touch Gestures

      + + +

      This tutorial demonstrates how you can implement different types of gestures provided by the EFL library and instructions on how to use them.

      + +

      Initializing Touch Gestures

      + +

      The EFL library provides a wide range of touch gestures, such as tap, double tap, triple tap, long tap, momentum, line, zoom and rotate, which can be used by the application to build a dynamic user interface interaction which is simple to use as well as intuitive.

      +

      The create_base_gui function creates the application layout. It starts by creating a window, then adds the elm_conformant component to it to decorate the window with an indicator. It then adds the elm_naviframe component which acts as a view manager for the window and provides the window title functionality. After this it creates a gesture view by using the create_main_view() function and adds it to naviframe.

      +
      +static void
      +create_base_gui(appdata_s *ad)
      +{
      +   Elm_Object_Item *nf_it, *tabbar_it;
      +   // Window
      +   ad->win = elm_win_util_standard_add(PACKAGE, PACKAGE);
      +   elm_win_autodel_set(ad->win, EINA_TRUE);
      +   evas_object_smart_callback_add(ad->win, "delete,request", win_delete_request_cb, NULL);
      +   // Conformant
      +   ad->conform = elm_conformant_add(ad->win);
      +   elm_win_conformant_set(ad->win, EINA_TRUE);
      +   evas_object_size_hint_weight_set(ad->conform, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
      +   elm_win_resize_object_add(ad->win, ad->conform);
      +   evas_object_show(ad->conform);
      +   // Naviframe
      +   ad->nf = elm_naviframe_add(ad->layout);
      +   // Calendar View
      +   create_main_view(ad);
      +   elm_naviframe_item_push(ad->nf, "Calendar", NULL, NULL, ad->calendar, NULL);
      +   elm_object_part_content_set(ad->layout, "elm.swallow.content", ad->nf);
      +   // Show window after the base GUI is set up
      +   evas_object_show(ad->win);
      +}
      +
      + +

      The create_main_view function creates the application layout by arranging the labels and rectangles by using recursive composition of the box layout:

      +
      +static void
      +create_main_view(appdata_s *ad)
      +{
      +   // Box
      +   ad->box = elm_box_add(ad->nf);
      +   evas_object_size_hint_weight_set(ad->box, EVAS_HINT_EXPAND, VAS_HINT_EXPAND);
      +   elm_box_padding_set(ad->box, 0, 5 * elm_config_scale_get());
      +   evas_object_show(ad->box);
      +   // Event Rect
      +   ad->rect = evas_object_rectangle_add(evas_object_evas_get(ad->box));
      +   evas_object_size_hint_weight_set(ad->rect, EVAS_HINT_EXPAND, VAS_HINT_EXPAND);
      +   evas_object_size_hint_align_set(ad->rect, EVAS_HINT_FILL, EVAS_HINT_FILL);
      +   evas_object_color_set(ad->rect, 204, 204, 204, 255);
      +   evas_object_repeat_events_set(ad->rect, EINA_TRUE);
      +
      +   ad->gl = create_gesture_layer(ad);
      +
      +   elm_box_pack_end(ad->box, ad->rect);
      +   evas_object_show(ad->rect);
      +}
      +
      + +

      A gesture layer is added to the rectangle object. This layer is able to receive the gesture event:

      +
      +static Evas_Object *
      +create_gesture_layer(appdata_s *ad)
      +{
      +   Evas_Object *g = elm_gesture_layer_add(ad->win);
      +   elm_gesture_layer_attach(g, ad->rect);
      +}
      +
      + +

      The following figure illustrates the Gesture Detector.

      + +

      Figure: Gesture Detector screen

      +

      Gesture Detector screen

      + +

      Implementing Touch Gestures

      + +

      The elm_gesture_layer_attach() is the function to which a gesture layer for a particular object is attached.

      +

      A gesture can have 4 different states:

      +
        +
      • ELM_GESTURE_STATE_START
      • +
      • ELM_GESTURE_STATE_MOVE
      • +
      • ELM_GESTURE_STATE_ABORT
      • +
      • ELM_GESTURE_STATE_END
      +

      Every gesture starts with the ELM_GESTURE_STATE_START state and finishes with either the ELM_GESTURE_STATE_END or ELM_GESTURE_STATE_ABORT state depending on whether the gesture is completed or aborted on that object.

      +

      If an application only needs to track a finished gesture, it can listen for the finished state only. For a more complete control of the gesture, an application can listen for all state changes for that particular gesture.

      +

      The elm_gesture_layer_cb_set() function is used for registering state change callback for a particular gesture.

      +

      For more information about the gestures, see the gesture documentation.

      + +

      To detect touch gestures:

      +
        +
      • The following example adds callbacks for listening to the tap gesture:

        +
        +elm_gesture_layer_cb_set(g, ELM_GESTURE_N_TAPS,
        +   ELM_GESTURE_STATE_START, n_finger_tap_start, ad);
        +elm_gesture_layer_cb_set(g, ELM_GESTURE_N_TAPS,
        +   ELM_GESTURE_STATE_END, n_finger_tap_end, ad);
        +elm_gesture_layer_cb_set(g, ELM_GESTURE_N_TAPS,
        +   ELM_GESTURE_STATE_ABORT, n_finger_tap_abort, ad);
        +
      • +
      • The following example adds callbacks for listening to the double tap gesture:

        +
        +elm_gesture_layer_cb_set(g, ELM_GESTURE_N_DOUBLE_TAPS,
        +   ELM_GESTURE_STATE_START, dbl_click_start, ad);
        +elm_gesture_layer_cb_set(g, ELM_GESTURE_N_DOUBLE_TAPS,
        +   ELM_GESTURE_STATE_MOVE, dbl_click_move, ad);
        +elm_gesture_layer_cb_set(g, ELM_GESTURE_N_DOUBLE_TAPS,
        +   ELM_GESTURE_STATE_END, dbl_click_end, ad);
        +elm_gesture_layer_cb_set(g, ELM_GESTURE_N_DOUBLE_TAPS,
        +   ELM_GESTURE_STATE_ABORT, dbl_click_abort, ad);
        +
      • + +
      • The following example adds callbacks for listening to the triple tap gesture:

        +
        +elm_gesture_layer_cb_set(g, ELM_GESTURE_N_TRIPLE_TAPS,
        +   ELM_GESTURE_STATE_START, triple_click_start, ad);
        +elm_gesture_layer_cb_set(g, ELM_GESTURE_N_TRIPLE_TAPS,
        +   ELM_GESTURE_STATE_MOVE, triple_click_move, ad);
        +elm_gesture_layer_cb_set(g, ELM_GESTURE_N_TRIPLE_TAPS,
        +   ELM_GESTURE_STATE_END, triple_click_end, ad);
        +elm_gesture_layer_cb_set(g, ELM_GESTURE_N_TRIPLE_TAPS,
        +   ELM_GESTURE_STATE_ABORT, triple_click_abort, ad);
        +
      • +
      • The following example adds callbacks for listening to the long tap gesture:

        +
        +elm_gesture_layer_cb_set(g, ELM_GESTURE_MOMENTUM,
        +   ELM_GESTURE_STATE_START, momentum_start, ad);
        +elm_gesture_layer_cb_set(g, ELM_GESTURE_MOMENTUM,
        +   ELM_GESTURE_STATE_END, momentum_end, ad);
        +elm_gesture_layer_cb_set(g, ELM_GESTURE_MOMENTUM,
        +   ELM_GESTURE_STATE_ABORT, momentum_abort, ad);
        +elm_gesture_layer_cb_set(g, ELM_GESTURE_MOMENTUM,
        +   ELM_GESTURE_STATE_MOVE, momentum_move, ad);
        +
      • + +
      • The following example adds callbacks for listening to the momentum gesture:

        +
        +elm_gesture_layer_cb_set(g, ELM_GESTURE_MOMENTUM,
        +   ELM_GESTURE_STATE_START, momentum_start, ad);
        +elm_gesture_layer_cb_set(g, ELM_GESTURE_MOMENTUM,
        +   ELM_GESTURE_STATE_END, momentum_end, ad);
        +elm_gesture_layer_cb_set(g, ELM_GESTURE_MOMENTUM,
        +   ELM_GESTURE_STATE_ABORT, momentum_abort, ad);
        +elm_gesture_layer_cb_set(g, ELM_GESTURE_MOMENTUM,
        +   ELM_GESTURE_STATE_MOVE, momentum_move, ad);
        +
      • + +
      • The following example adds callbacks for listening to the line gesture:

        +
        +elm_gesture_layer_cb_set(g, ELM_GESTURE_N_LINES,
        +   ELM_GESTURE_STATE_START, line_start, ad);
        +elm_gesture_layer_cb_set(g, ELM_GESTURE_N_LINES,
        +   ELM_GESTURE_STATE_MOVE, line_move, ad);
        +elm_gesture_layer_cb_set(g, ELM_GESTURE_N_LINES,
        +   ELM_GESTURE_STATE_END, line_end, ad);
        +elm_gesture_layer_cb_set(g, ELM_GESTURE_N_LINES,
        +   ELM_GESTURE_STATE_ABORT, line_abort, ad);
        +
      • + +
      • The following examples add callbacks for listening to the flick gesture:

        +
        +elm_gesture_layer_cb_set(g, ELM_GESTURE_N_FLICKS,
        +   ELM_GESTURE_STATE_START, flick_start, ad);
        +elm_gesture_layer_cb_set(g, ELM_GESTURE_N_FLICKS,
        +   ELM_GESTURE_STATE_END, flick_end, ad);
        +elm_gesture_layer_cb_set(g, ELM_GESTURE_N_FLICKS,
        +   ELM_GESTURE_STATE_ABORT, flick_abort, ad);
        +
      • + +
      • The following examples add callbacks for listening to the zoom gesture:

        +
        +elm_gesture_layer_cb_set(g, ELM_GESTURE_ZOOM,
        +   ELM_GESTURE_STATE_START, zoom_start, ad);
        +elm_gesture_layer_cb_set(g, ELM_GESTURE_ZOOM,
        +   ELM_GESTURE_STATE_END, zoom_end, ad);
        +elm_gesture_layer_cb_set(g, ELM_GESTURE_ZOOM,
        +   ELM_GESTURE_STATE_ABORT, zoom_abort, ad);
        +elm_gesture_layer_cb_set(g, ELM_GESTURE_ZOOM,
        +   ELM_GESTURE_STATE_MOVE, zoom_move, ad);
        +
      • + +
      • The following example adds callbacks for listening to the rotate gesture:

        +
        +elm_gesture_layer_cb_set(g, ELM_GESTURE_ROTATE,
        +   ELM_GESTURE_STATE_START, rotate_start, ad);
        +elm_gesture_layer_cb_set(g, ELM_GESTURE_ROTATE,
        +   ELM_GESTURE_STATE_END, rotate_end, ad);
        +elm_gesture_layer_cb_set(g, ELM_GESTURE_ROTATE,
        +   ELM_GESTURE_STATE_ABORT, rotate_abort, ad);
        +elm_gesture_layer_cb_set(g, ELM_GESTURE_ROTATE,
        +   ELM_GESTURE_STATE_MOVE, rotate_move, ad);
        +
      • + +
      • The following example adds a callback for getting the tap gesture finishing notification:

        +
        +static Evas_Event_Flags
        +n_finger_tap_end(void *data, void *event_info)
        +{
        +   appdata_s *ad = data;
        +   Elm_Gesture_Taps_Info *p = (Elm_Gesture_Taps_Info *) event_info;
        +   return EVAS_EVENT_FLAG_ON_HOLD;
        +}
        +
      • +
      + + + + +
      + +Go to top + + + + + + + diff --git a/org.tizen.ui.guides/html/native/efl/ui_components_mn.htm b/org.tizen.ui.guides/html/native/efl/ui_components_mn.htm new file mode 100755 index 0000000..385a8c1 --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/ui_components_mn.htm @@ -0,0 +1,1090 @@ + + + + + + + + + + + + + Mobile UI Components + + + +
      +
      +

      Mobile native

      +
      + + +
      + +
      + +

      Mobile UI Components

      + +

      The EFL Elementary is a set of fast, finger-friendly, scalable, and themeable UI component libraries. The number of supported UI components is around 80, including both containers and non-containers. Originally, the Elementary was developed as part of the Window Manager development on Desktop devices. For the mobile profile, Tizen reused the proper UI components and created new ones, and then enhanced and adjusted all of them for Tizen native applications.

      + + + + + + + + + + +
      Note
      This feature is supported in mobile applications only.
      + +

      The UI components are mobile-friendly: for example, the Naviframe component supports view-managing for multiple views, the Entry component supports many modes (such as Password, Single/Multi-line, Edit/No-Edit), the Index component supports fast access to another group of UI items, and the Toolbar component shows a menu when an item is selected.

      +

      The mobile UI components were designed to allow the user to interact with touch screen-equipped mobile devices. Therefore, when developing mobile applications, you can easily use them through the mobile-related infrastructure in company with view managing and when reacting to touch events and the user finger size.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      + Table: Available UI components +
      Component nameDescription
      BackgroundThe background component can be used to set a solid background decoration to a window or a container object. It works like an image, but has some background specific properties, such as setting it to tiled, centered, scaled, or stretched.
      ButtonThe button component is a simple push button. It is composed of a label icon and an icon object, and has an auto-repeat feature.
      CheckThe check component toggles the value of a Boolean between true and false.
      ColorselectorThe colorselector component provides a color selection solution to the user. It has different modes available, each of them showing a different configuration of the color selection.
      CtxpopupThe ctxpopup component is a contextual popup that can show a list of items.
      DatetimeThe datetime component can display and input date and time values.
      EntryThe entry component is a box to which the user can enter text.
      FlipThe flip component can hold two Evas objects and let the user flip between these objects using a variety of predefined animations.
      GengridThe gengrid component displays objects on a grid layout and renders only the visible objects.
      GenlistThe genlist component displays a scrollable list of items. It can hold a lot of items while still being fast and memory-efficient (only the visible items are allocated memory).
      GLViewThe GLView component can render OpenGL in an Elementary object, hiding EvasGL complexity.
      IconThe icon component inherits from the image component. It is used to display images in an icon context.
      ImageThe image component can load and display an image from a file or from memory.
      IndexThe index component provides an index for fast access to another group of UI items.
      LabelThe label component displays text with simple HTML-like markup.
      ListThe list component is a very simple list for managing a small number of items. If you need to manage a lot of items, use the genlist component instead.
      MapThe map component can display a geographic map. The default map data is provided by the OpenStreetMap project (http://www.openstreetmap.org/).
      NotifyThe notify component displays a container in a specific region of the parent object. It can receive some content, and it can be automatically hidden after a certain amount of time.
      PanelThe panel component is an animated object that can contain child objects. It can be expanded or contracted by clicking on the button on its edge.
      PhotoThe photo component can be used to display a photo, such as a contact image. If no photo is set, the UI component displays a person icon to show that it is a photo placeholder.
      PhotocamThe photocam component is designed to display high-resolution photos taken with a digital camera. It allows you to zoom photos, load photos fast, and fit photos. It is optimized for JPEG images and has a low memory footprint.
      PlugThe plug component allows you to show an Evas object created by another process. It can be used anywhere like any other Elementary UI component.
      PopupThe popup component shows a pop-up area that can contain a title area, a content area, and an action area.
      ProgressbarThe progressbar component can be used to display the progress status of a given job.
      RadioThe radio component can display 1 or more options, but the user can only select one of them. The UI component is composed of an indicator (selected/unselected), an optional icon, and an optional label. Even though it is usually grouped with 2 or more other radio components, it can also be used alone.
      SegmentcontrolThe slider component is a draggable bar that is used to select a value from a range of values.
      SliderThe slider component is a draggable bar that is used to select a value from a range of values.
      SpinnerThe spinner component enables the user to increase or decrease a numeric value by using arrow buttons.
      ToolbarThe toolbar component is a scrollable list of items. It can also show a menu when an item is selected. Only one item can be selected at a time.
      TooltipThe tooltip component is a smart object used to show tips or information about a parent object when the mouse hovers over the parent object.
      TransitThe transit component can apply several transition effects to an Evas object, such as translations and rotations.
      WinThe win component is the root window component that will be often used in an application. It allows you to create some content in it, and it is handled by the window manager.
      + +

      Mobile UI Component Styles

      + +

      EFL can separate the GUI and logic of each UI component, resulting in each component having a different style of look. To change the styles of UI components, use the elm_object_style_get() and elm_object_style_set() functions to get and apply the style for a specific UI component.

      + +

      The following tables list the styles for each winset, including the names of the styles, and the name of the part where to set text or some other Evas_Object in the UI component. For more detailed information, see the Themes.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Table: Button styles
      StyleSampleText partSwallow partNotes
      elm/button/base/default elm.textelm.swallow.content
      elm/button/base/anchorelm.textelm.swallow.content
      elm/button/base/bottomelm.textelm.swallow.contentThis style is used widely at the bottom of the screen.
      elm/button/base/circleelm.textelm.swallow.content
      elm/button/base/dropdownelm.text
      elm/button/base/hoversel_horizontal/defaultelm.textelm.swallow.content
      elm/button/base/hoversel_horizontal_entry/defaultelm.textelm.swallow.content
      elm/button/base/hoversel_vertical/defaultelm.textelm.swallow.content
      elm/button/base/hoversel_vertical_entry/defaultelm.textelm.swallow.content
      elm/button/base/icon_reorder
      elm/button/base/naviframe/drawers
      elm/button/base/naviframe/title_cancel
      elm/button/base/naviframe/title_done
      elm/button/base/option
      + + + +++ + + + + + + + + + + + + + + + + + +
      Table: Check styles
      StyleSample
      elm/check/base/default
      elm/check/base/favorite
      elm/check/base/on&off
      + + + + + + + + + + + + + + + +
      Table: Colorselector styles
      StyleSampleNotes
      elm/colorselector/item/color/colorplaneUse the following command: elm_colorselector_mode_set(colorselector, ELM_COLORSELECTOR_PALETTE);
      + + + + + + + + + + + + + + + + + +
      Table: Progressbar styles
      StyleSample
      default
      wheel
      + + + +++ + + + + + + + + + +
      Table: Radio styles
      StyleSample
      default
      + + + + + + + + + + + + + + + + + +
      Table: List styles
      StyleSampleText partSwallow part
      defaultelm.textelm.swallow.icon: for the icon on the left. +

      elm.swallow.end: for the icon on the right.

      + + + + + + + + + + + + + + + + + +
      Table: Multi Button Entry styles
      StyleSampleText partNotes
      elm/multibuttonentry/base/defaultelm.text, guideThe guide text part is used when there is no item in the Multi Button Entry. It is removed automatically when an item is appended in the Multi Button Entry.
      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Table: Toolbar styles
      StyleSampleText partSwallow partNotes
      elm/toolbar/base/default
      elm/toolbar/base/navigationbar
      elm/toolbar/base/tabbar_with_title
      elm/toolbar/item/defaultelm.textelm.swallow.iconThis style is for the toolbar's item. Check the elm_toolbar_item_append() function to set the text and the icon.
      elm/toolbar/item/navigationbarelm.textThis style is for the toolbar's item. Check the elm_toolbar_item_append() function to set the text and the icon.
      + + + +++ + + + + + + + + + +
      Table: Flipselector styles
      StyleSample
      default
      + +

      The style of the genlist's item is not set by external APIs. Check the guide of Genlist to check how to use the item class to set the item's style.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Table: Genlist styles
      StyleSampleText partSwallow partNotes
      defaultelm.textelm.swallow.icon: for the icon on the left. +

      elm.swallow.end: for the icon on the right.

      default_styleelm.textelm.swallow.icon: for the icon on the left. +

      elm.swallow.end: for the icon on the right.

      double_labelelm.text: for the main text. +

      elm.text.sub: for the sub text.

      elm.swallow.icon: for the icon on the left. +

      elm.swallow.end: for the icon on the right.

      end_iconelm.textelm.swallow.icon
      fullelm.swallow.contentThe swallow part is the full size of the item. There is no padding in the item.
      group_indexelm.textelm.swallow.icon: for the icon on the left. +

      elm.swallow.end: for the icon on the right.

      one_iconelm.textelm.swallow.icon
      messageelm.text: for the text on the top. +

      elm.title.1: for the text in the middle.

      +

      elm.title.2: for the text on the bottom.

      + +

      The style of the gengrid's item is not set by external APIs. For more information on using the item class to set the item's style, see the guide of gengrid.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Table: Gengrid styles
      StyleSampleText partSwallow partNotes
      defaultelm.swallow.icon
      album-previewelm.textelm.swallow.icon
      blockThis style is used to show an empty area.
      group_indexelm.textelm.swallow.icon
      default_gridelm.swallow.icon
      default_gridtext2elm.textelm.swallow.icon
      default_gridtextelm.textelm.swallow.icon
      default_styleelm.textelm.swallow.icon
      + + + + + + + + + + + + + +
      Table: Segmentation Control styles
      StyleSample
      default
      + + + + + + + + + + + + + + + + + + + + + + + + + +
      Table: Index styles
      StyleSampleNotes
      defaultThis style is for supporting the vertical style.
      defaultThis style is for supporting the horizontal style. To set a horizontal index, use the elm_index_horizontal_set.
      pagecontrolThis style is used for the "page control" layout. For more information, refer to the Core Control sample application.
      + + + + + + + + + + + + + + + + + + + + + + + + + +
      Table: Contextual Popup (Ctxpopup) styles
      StyleSampleNotes
      default
      dropdown/listThe size of the item and the ctxpopup follow the size of the screen.
      dropdown/labelThe size of the item and the ctxpopup follow the maximum length of the item.
      + + + +++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Table: Icon styles
      StyleSample
      apps
      arrow_down
      arrow_left
      arrow_right
      arrow_up
      chat
      clock
      close
      delete
      edit
      file
      home
      media_player/forward
      media_player/info
      media_player/next
      media_player/pause
      media_player/play
      media_player/prev
      media_player/rewind
      media_player/stop
      menu/apps
      menu/arrow_down
      menu/arrow_left
      menu/arrow_right
      menu/arrow_up
      menu/chat
      menu/clock
      menu/close
      menu/delete
      menu/edit
      menu/file
      menu/folder
      menu/home
      menu/refresh
      no_photo
      photo/no_photo
      refresh
      toolbar/apps
      toolbar/arrow_down
      toolbar/arrow_left
      toolbar/arrow_right
      toolbar/arrow_up
      toolbar/chat
      toolbar/clock
      toolbar/close
      toolbar/delete
      toolbar/edit
      toolbar/file
      toolbar/folder
      toolbar/home
      toolbar/more_menu
      toolbar/refresh
      + + + + + + + + + + + + + + + + + + + +
      Table: Entry styles
      StyleSampleText partSwallow partNotes
      defaultelm.guide: for the guide text. +

      elm.text: for the main text.

      The guide text is automatically erased when the main text is entered.
      + + + +++ + + + + + + + + + + + + + + + + + +
      Table: Datetime styles
      StyleSample
      date_layout
      time_layout
      time_layout_24hr
      + + + + + + + + + + + + + + + + + +
      Table: Panel (drawer) styles
      StyleSampleSwallow partNotes
      defaultelm.swallow.contentFor more information on the drawer, see the [UI Sample] Core Control guide.
      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Table: Slider styles
      StyleSampleSwallow part
      horizontal/defaultelm.swallow.icon
      horizontal/center_pointelm.swallow.icon
      vertical/center_point
      vertical/default
      + + + +++ + + + + + + + + + + + + + +
      Table: Popup styles
      StyleSample
      default
      toast
      + + + +++ + + + + + + + + + + + + + +
      Table: Spinner styles
      StyleSample
      base/horizontal
      base/vertical
      + + + + + + + + + + +
      Note
      Except as noted, this content is licensed under LGPLv2.1+.
      + + + +
      + +Go to top + + + + + + + \ No newline at end of file diff --git a/org.tizen.ui.guides/html/native/efl/ui_components_n.htm b/org.tizen.ui.guides/html/native/efl/ui_components_n.htm new file mode 100755 index 0000000..20103e4 --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/ui_components_n.htm @@ -0,0 +1,700 @@ + + + + + + + + + + + + + UI Components: Handling Elementary UI Component Libraries + + + + + +
      + +

      UI Components: Handling Elementary UI Component Libraries

      + +

      Before writing an application, you should already have an answer to the following question: What is an application? An application is a process launched by the user. Every application has at least one window for presenting its content. Users can interact with the content through events. Different sources of events can modify the life cycle of the application. The application may receive data from a network connection, and it may also receive touch and key events. From the computer's point of view, an application is a collection of code that reacts to events and displays content on the screen. Elementary bridges this divide between the user and the code.

      + +

      Elementary provides a variety of pre-built UI components, such as layout objects and components, that allow you to build rich graphical user interfaces for your applications. Every Elementary application has at least one window for presenting its content. The window provides the area in which to display the content and where the Evas canvas is placed.

      + +

      There are three main groups of objects provided by Elementary:

      + +
        +
      • UI components: These are the components with which you build your application UI.
      • +
      • Containers: These are the containers that hold the components.
      • +
      • Infrastructure: These are the modules that deal with Elementary as a whole.
      • +
      + +

      Using UI Components

      + +

      The Elementary library is a simple toolkit. It provides several UI components than can be used to compose the user interface of your application. UI components allow you to build your application without having to reinvent basic objects, such as buttons, lists, or text entries. UI components will often generate signals that can be caught in the application when the user interacts with the UI components. This guide teaches you the basics of Elementary, describes selected concepts of the Elementary configuration framework, and describes the most common UI components.

      + +

      Figure: Elementary

      +

      Elementary

      + + +

      Getting Started with the Elementary Library

      + + +

      Elementary UI components are built in a hierarchical fashion. The idea is to factorize as much code as possible between UI components that behave in a similar manner to facilitate the creation of new UI components. The Elementary UI components inherit a lot of their code from the container UI components and the layout component (a container component that takes a standard Edje design file and wraps it very thinly). You can use the container and layout functions on the Elementary UI components, as well as the Elementary object functions, such as elm_object_part_content_set(), elm_object_part_content_get(), and elm_object_part_content_unset().

      + +

      To use the Elementary library:

      + +
      1. Initialize the Elementary library with the elm_init() function.
      2. +
      3. Start the Elementary main loop with the elm_run() function. +

        The function does not return, instead, it constantly loops and runs the event and the processing tasks.

      4. +
      5. Add Elementary UI components in the main loop. +

        Generally, an Elementary UI component can be added with the elm_<UI component name>_add() function, which returns an Evas object (Evas_Object*). The Evas object is passed to the functions that are used to configure the UI component.

      6. +
      7. Stop the main loop and return to the main() function with the elm_exit() function.
      8. +
      9. When your application terminates, shut down the Elementary library with the elm_shutdown() function. +

        The function frees the Elementary objects that were allocated in the main loop, so you do not need to separately deallocate them.

      + + +

      The following code snippet shows the main() function of a minimal Elementary application:

      + +
      +#include <Elementary.h>
      +int main(int argc, char **argv)
      +{
      +   elm_init(argc, argv);
      +   elm_run();
      +   elm_shutdown();
      +
      +   return 0;
      +}
      + + +

      Elementary Objects

      + +

      All objects created using Elementary are of the Evas_Object* type. This means that both Evas and Elementary functions can be used on an Elementary object. However, use Elementary functions on Elementary objects only when you do not know which API to use.

      + +

      Since an Elementary object can take up a lot of memory, the Elm_Object_Item type has been created for situations where you need to use a lot of items, such as in a genlist or gengrid component, and to save memory. Using the Elm_Object_Item type, an Elementary UI component can, in theory, contain a lot of items while maintaining a small memory footprint. In practice, the Elm_Object_Item instance is bigger than expected, but can still help in saving memory.

      + +

      For more information, see Evas Objects.

      + +

      Elementary Callbacks

      + +

      Several callbacks can be registered to handle Elementary object events:

      + +
        +
      • Evas event callback +

        Use the evas_object_event_callback_add() function to add a callback for input events (key up, key down, mouse wheel) on an Evas object. In case of an Elementary object, the callback is registered on the underlying Evas object without considering the Elementary object infrastructure (no event propagation).

        +
      • + +
      • Evas smart callback +

        Use the evas_object_smart_callback_add() function to add a callback for a smart event emitted by an Elementary object. Smart callbacks can only be registered on smart objects, and the "smart event" to register must be implemented by the corresponding smart object. Otherwise, the callback does nothing. The callback does not apply to input events (keyboard or mouse).

        +
      • + +
      • Edje signal callback +

        Use the edje_object_signal_callback_add() function to add a callback for a signal coming from an Edje object (a theme object).

        +
      • + +
      • Elementary signal callback +

        Use the elm_object_signal_callback_add() function to add a callback for a signal coming from an Elementary UI component's theme. The callback does not apply to input events (keyboard or mouse).

        +
      • + +
      • Elementary event callback +

        Use the elm_object_event_callback_add() function to add a callback for an input event (keyboard or mouse) coming from an Elementary object. In contrast to the Evas event callback, the Elementary event callback takes the hierarchy of the object into account: the event can be propagated to the parents of the object, and the parents can process the event.

        +
      • +
      + +

      For more information about events related to Elementary objects, see Event Handling. For more information about Evas objects and smart objects, see Evas Rendering Concept and Method.

      + +

      Managing Elementary Profiles

      + +

      An Elementary profile is a set of preconfigured options that affects the entire look and feel of an application. The options linked to a specific profile form an Elementary configuration, which can be used to store the desired set of options for use in multiple sessions. Once loaded, the Elementary profile configures all the options and sets the look and feel of your Elementary application.

      + +

      To manage Elementary profiles:

      +
        +
      • List the existing profiles: +
        +Eina_List *list = elm_config_profile_list_get();
        +
        +
      • +
      • Set a particular profile: +
        +elm_config_profile_set("myprofile");
        +
        +
      • +
      • Get the current profile: +
        +char *profile = elm_config_profile_get();
        +
        +
      • +
      • To save the current option values as an Elementary configuration for later use, use the elm_config_save() function: +
        +elm_config_save();
        +
        +
      • +
      • To reload the Elementary configuration saved for the current profile: +
        +elm_config_reload();
        +
        +
      • +
      + +

      Configuring Elementary Options

      + +

      You can set the following options in the Elementary configuration. In addition, you can customize themes and manage focus.

      +
        + +
      • To scale UI components: +

        You can configure UI component scaling in terms of both interactive and readable areas.

        +
          +
        • Set the global scaling factor (for example, setting it to 2.0 doubles the size of all scalable UI components): +
          +elm_config_scale_set(2.0);
          +
          +
        • + +
        • Set the finger size: +
          +elm_config_finger_size_set(1.5);
          +
          +
        • +
        +
      • + +
      • To manage caches: +
          +
        • Enable the globally configured cache flush, and set the flush interval (in this example, to 60 seconds): +
          +elm_config_cache_flush_enabled_set(EINA_TRUE);
          +elm_config_cache_flush_interval_set(60);
          +
          +
        • + +
        • Configure the font and image cache sizes (to 500 and 5 000 000 bytes, respectively): +
          +elm_config_cache_font_cache_size_set(500);
          +elm_config_cache_image_cache_size_set(5000000);
          +
          +
        • + +
        • Set the Edje collection and Edje file cache sizes: +
          +elm_config_cache_edje_file_cache_size_set(500);
          +elm_config_cache_edje_collection_cache_size_set(500);
          +
          +
        • +
        +
      • + + +
      • To configure the gesture layer: +

        You can set the duration of the long tap and double tap events on the gesture layer objects. The following example sets the duration to 500 ms.

        + +
        +elm_config_glayer_long_tap_start_timeout_set(0.5);
        +elm_config_glayer_double_tap_timeout_set(0.5);
        +
        +
      • +
      • To manage scrolling: +
          +
        • Make the scroller bounce when it reaches its viewport's edge during scrolling by using the elm_config_scroll_bounce_enabled_set() function: +
          +elm_config_scroll_bounce_enabled_set(EINA_TRUE);
          +
          +
        • + +
        • Control the inertia of the bounce animation by using the elm_config_scroll_bounce_friction_set() function: +
          +elm_config_scroll_bounce_friction_set(0.5);
          +
          +

          You can also set the friction for a page scroll, include animations, and zoom animations.

          +
        • + +
        • Set the scroller to be draggable by using the elm_config_scroll_thumbscroll_enabled_set() function. You can configure several drag options, such as friction, sensitivity, acceleration, and momentum. + +

          The following example sets the scroller to be draggable, defines that the number of pixels one must travel while dragging the scroller view to actually trigger scrolling is 20 pixels.

          +
          +elm_config_scroll_thumbscroll_enabled_set(EINA_TRUE);
          +elm_config_scroll_thumbscroll_threshold_set(20);
          +
          +
        • +
        +
      • + +
      • To configure long press events: +

        Get the current timeout before a long press event is retrieved, and modify it. The following example increases the timeout by 1 second.

        +
        +double lp_timeout = elm_config_longpress_timeout_get();
        +elm_config_longpress_timeout_set(lp_timeout + 1.0);
        +
        +
      • + +
      • To configure tooltips: +

        Set the duration after which a tooltip is shown. The following example sets the delay to 2 seconds.

        + +
        +elm_config_tooltip_delay_set(2.0);
        +
        +
      • + +
      • To configure the password show last feature: +

        The password show last feature enables the user to view the last input entered for a few seconds before it is masked.

        + +
          +
        • Enable the password show last feature: +
          +elm_config_password_show_last_set(EINA_TRUE);
          +
          +
        • +
        • Set the visibility timeout (how many seconds the input is visible): +
          +elm_config_password_show_last_timeout_set(5.0);
          +
          +
        • +
        +
      • +
      • To set the Elementary engine: +

        You can define the rendering engine that Elementary uses to draw the windows. The following rendering engines are supported:

        + +
          +
        • "software_x11"
        • +
        • "fb"
        • +
        • "directfb"
        • +
        • "software_16_x11"
        • +
        • "software_8_x11"
        • +
        • "xrender_x11"
        • +
        • "opengl_x11"
        • +
        • "software_gdi"
        • +
        • "software_16_wince_gdi"
        • +
        • "sdl"
        • +
        • "software_16_sdl"
        • +
        • "opengl_sdl"
        • +
        • "buffer"
        • +
        • "ews"
        • +
        • "opengl_cocoa"
        • +
        • "psl1ght"
        • +
        + +
        +elm_config_engine_set("opengl_x11");
        +
        +
      • + +
      • To activate the access mode: +

        Set the access mode as active, so that information about an Elementary object is read when the object receives an EVAS_CALLBACK_MOUSE_IN event:

        + +
        +elm_config_access_set(EINA_TRUE);
        +
        +
      • + +
      • To configure the selection mode: +

        Set the selection mode so that the selection is cleared when the entry component is unfocused:

        +
        +elm_config_selection_unfocused_clear_set(EINA_TRUE);
        +
        +
      • + +
      • To enable mirroring: +

        Elementary allows UI mirroring both on a single object and on the entire UI. If mirroring is enabled, an Elementary UI component displays as if there was a vertical mirror in the middle of it. Only the controls and the disposition of the UI component are mirrored. Text is not mirrored.

        + +
        +elm_config_mirrored_set(EINA_TRUE);
        +
        +
      • + +
      • To set the frame rate: +

        Define the frames per second (FPS) value for the ecore_animator_frametime and edje_frametime calculations. This example sets the FPS 60.

        + +
        +elm_config_fps_set(60.0);
        +
        +
      • +
      + +

      Customizing Themes

      + +

      Elementary uses Edje to theme its UI components. Edje provides a default theme for each UI component in an application. You can change the theme using the ELM_THEME environment variable. You can also modify the theme globally with the elementary_config utility.

      + +

      For custom styles, use extensions. Extensions allow you to write styles for specific UI components. Add a new extension to the list of Elementary themes with the elm_theme_extension_add() function, and apply the new style to the UI component with the elm_object_style_set() function. Once set, the extension replaces the default theme of the UI component.

      + + + + + + + + + + +
      Note
      When developing an extension, to respect the signals emitted and the elements that need to be in place, you must know how the UI component is themed. If something is missing from the extension, it can break the UI component's behavior.
      + +

      To modify Elementary themes, you can also use overlays. An overlay can replace the look of all UI components by overriding the default styles. As with extensions, you must write the correct overlay theme for a UI component. When looking for a theme to apply, Elementary first checks the list of overlays, then the set theme, and finally the list of extensions. To add or remove an overlay, use the elm_theme_overlay_add() and elm_theme_overlay_del() functions.

      + + + + + + + + + + +
      Note
      With overlays, you can replace the default view and affect every UI component. This is very similar to setting the theme for the whole application, and probably clashes with end user options. Using overlays also runs the risk of non-matching styles across the application. Unless you have a very good reason to use them, avoid overlays.
      + +

      Managing Focus

      + +

      When an Elementary object has the focus, input events are directly passed to that object in the application window. The focused object can also change its decoration to show the user where the focus is. In an Elementary application, only one object can have the focus at a time.

      + +

      To set the focus to a new Elementary object and take the focus away from the previous focused object, use the elm_object_focus_set() function. You can make an object unfocusable with the elm_object_focus_allow_set() function.

      + + + + + + + + + + +
      Note
      Only visible objects can have the focus.
      + +

      Elementary supports focus chains that allow you to cycle through all the focusable objects in a window. By default, the focus chain is defined by the order in which the UI components are added to the code. It is also possible to define custom focus chains, when needed.

      + +

      For more information on focus, see Component Focus.

      + +

      To manage the focus:

      + +
        +
      • To define a custom focus chain, create an Eina_List, and add the Elementary objects to it in the desired focus order. Use the elm_object_focus_custom_chain_set() function to set the final list as the custom focus chain of the parent object (in the following example, container_object is the parent object). + +
        Eina_List *obj_list = NULL;
        +
        +list = eina_list_append(list, obj1); 
        +list = eina_list_append(list, obj4);
        +list = eina_list_append(list, obj2); 
        +list = eina_list_append(list, obj3);
        +
        +elm_object_focus_custom_chain_set(container_object, list);
        +
      • + +
      • To remove the custom focus chain and use the default focus chain instead, use the elm_object_focus_custom_chain_unset() function. +
      • + +
      • To programmatically cycle through the focus chain, use the elm_object_focus_next() function. +
      • + +
      • To show a highlight on the focused object: + +
        +elm_config_focus_highlight_enabled_set(EINA_TRUE);
        +
        +
      • + +
      • To activate an animation when the focus shifts from one object to another: + +
        +elm_config_focus_highlight_animate_set(EINA_TRUE);
        +
        +
      • +
      + +

      Scaling UI Components

      + +

      Elementary, through its configuration API (elm_config), provides a way to scale UI components with two different parameters. Finger size parameter is used when the interactive zones (clickable, editable) of the UI components need to be scaled in order to be comfortably used with a finger. Scale parameter is responsible for scaling readable parts of a UI component (text or icons for example), so that it is more visible in the user interface.

      + +

      Finger Size

      + +

      Finger size parameter scales UI components based on the user's finger size. This is useful when using a touchscreen with a finger rather than with a stylus. The finger size parameter is in pixels and determines the minimum size of a square on the screen that is reliably hittable with a finger. This parameter scales the input and interactive areas.

      + +

      The global finger size is set with the elm_config_finger_size_set() function. This adjusts the size and hit area of UI components so they are easy to hit with a finger. The current value is retrieved with the elm_config_finger_size_get() call. The finger size is always in pixel.

      + +

      To increase the current global finger size by 20px:

      + +
      +Evas_Coord finger_size;
      +
      +// Get the current finger size
      +finger_size = elm_config_finger_size_get();
      +
      +// Add 20px to finger size parameter and set it 
      +// to the global Elementary configuration
      +elm_config_finger_size_set(finger_size + 20);
      +
      + +

      Scale

      + +

      This parameter only scales the readable areas of the UI component (text, icons). Parts that must stay pixel-perfect like the highlights, shading, textures and decorations stay as they are.

      + +

      elm_config_scale_set() function is used to set the global scaling factor, that affects to all the UI components. It is also possible to use elm_object_scale_set() to set the scaling factor on a given Elementary UI component and all its children.

      + + + + + + + + + + +
      Note
      The scaling factor is multiplicative, if a child already has a scale size set, it is multiplied by its parent's scale size.
      + +

      The following example sets the global scaling factor to 2.0. Then, the scaling factor of an existing Elementary object is set to 2.0, meaning that this object appears as if it had a 4.0 scale factor, the rest of the application is displayed with a 2.0 scaling factor:

      + +
      +Evas_Object *button;
      +
      +// The button object is created and configured
      +
      +// Set the global scale factor to 2.0
      +elm_config_scale_set(2.0);
      +
      +// Set the scaling factor of the button component to 2.0, this component
      +// appears 4 times bigger than its initial size
      +elm_object_scale_set(button, 2.0);
      +
      + +

      Example

      + +

      This chapter shows the visual result of finger size and scaling factors modification.

      + +

      Figure: elementary_config application

      +

      elementary_config application

      + +

      The previous picture shows the elementary_config application that enables the user to set global scale factor and finger size parameter. As the user drags the sliders, the UI is updated, directly showing the result of the new parameter value.

      + +

      The next picture shows the behavior when the finger size parameter has been increased to 1.30. The text of the sliders and the text of the items in the toolbar are bigger.

      + +

      Figure: Scale increased (1.30)

      +

      Scale increased (1.30)

      + +

      A finger size increase is showed in the image below (increase from 50px to 90 px). Now, the buttons in the toolbar are bigger, so the user can more reliably hit them with a big finger.

      + +

      Figure: Finger size increased (90px)

      +

      Finger size increased (90px)

      + + + + + + + + + + +
      Note
      It is up to the theme (Edje file) to set the parts that are scalable. This is something that needs to be taken into account when developing a new Edje theme. This can be done in EDC with the scale parameter. For more information on how to do that, see Introduction to EDC Programming.
      + +

      Creating Scalable EDC Objects

      + +

      Scale Parameter

      + +

      This chapter explains how to make a scalable Edje object and give hints how to write an EDC file that is scalable. The example shows a basic button that is composed of a background image part and a swallow part that can receive some content.

      + +
      +group 
      +{ 
      +   name: "button";
      +   images 
      +   {
      +      image: "bg.png" COMP;
      +   }
      +   parts 
      +   {
      +      part 
      +      { 
      +         name: "bg";
      +         type: IMAGE;
      +         description 
      +         { 
      +            state: "default" 0.0;
      +            image.normal: "bg.png";
      +         }
      +      }
      +      part 
      +      { 
      +         name: "elm.swallow.content";
      +         type: SWALLOW;
      +         description 
      +         { 
      +            state: "default" 0.0;
      +            visible: 0;
      +         }
      +         description 
      +         { 
      +            state: "visible" 0.0;
      +            visible:1;
      +         }
      +      }
      +   }
      +}
      +
      + +

      To have a scalable object, set the scale parameter to 1 on the parts you want to be scalable. Here the bg and elm.swallow.content parts must be scalable.

      + +
      +group 
      +{ 
      +   name: "button";
      +   images 
      +   {
      +      image: "bg.png" COMP;
      +   }
      +   parts
      +   {
      +      part 
      +      { 
      +         name: "bg";
      +         type: IMAGE;
      +         scale: 1;
      +         description 
      +         { 
      +            state: "default" 0.0;
      +            image.normal: "bg.png";
      +         }
      +      }
      +      part 
      +      { 
      +         name: "elm.swallow.content";
      +         type: SWALLOW;
      +         scale: 1;
      +         description 
      +         { 
      +            state: "default" 0.0;
      +            visible: 0;
      +         }
      +         description 
      +         { 
      +            state: "visible" 0.0;
      +            visible:1;
      +         }
      +      }
      +   }
      +}
      +
      + +

      Image Set

      + +

      If your application needs to be used at different resolutions it is recommended to have 2 images for the background image bg.png. Here the bg_low.png is added to the application. It is used when the size of the image is under 500 px, and a bg_high.png image is for higher resolutions. Use a set on the bg.png image.

      + +
      +group 
      +{ 
      +   name: "button";
      +   images 
      +   {
      +      set 
      +      {
      +         name: "bg.png";
      +         image
      +         {
      +            image: "bg_low.png" COMP;
      +            size: 0 0 200 100;
      +         }
      +         image
      +         {
      +            image: "bg_high.png" COMP;
      +            size: 201 101 5000 5000;
      +         }
      +      }
      +   }
      +}
      +
      + +

      The image below shows three buttons with only a background part visible (the SWALLOW part is empty).

      + +

      Figure: Image set example

      +

      Image set example

      + +

      The first button's size is 100x50 pixels, the background image (bg_low.png) is the same size. The second button is twice bigger than the first one (200x100 pixels). The image is scaled and it does not render well, the borders are quite blurry.

      + +

      To prevent this, the image set has a bigger image to use when the size is bigger than 200x100 pixels (bg_high.png). The third button size is 201x101 pixels and it uses the new image, which has a better quality than the scaled image.

      + +

      Image Borders

      + +

      When the button is resized, the image part is also resized because it is marked as scalable. To get the image resized but to keep the image border as it is, use the border parameter. It specifies the border size which is not resized even if the image is.

      + +

      To add a 40 pixel border on the left and right part of the bg image and a 20 pixel border on top and bottom borders:

      + +
      +parts 
      +{
      +   part 
      +   { 
      +      name: "bg";
      +      type: IMAGE;
      +      scale: 1;
      +      description 
      +      { 
      +         state: "default" 0.0;
      +         image.normal: "bg.png";
      +         image.border: 40 40 20 20;
      +      }
      +   }
      +}
      +
      + +

      The image below shows that when resizing the button, the corners keep their initial ratio. Only the middle part of the button is resized.

      + +

      Figure: Border example

      +

      Border example

      + + + + + + + + + + + +
      Note
      Except as noted, this content is licensed under LGPLv2.1+.
      + + + +
      + +Go to top + + + + + + + \ No newline at end of file diff --git a/org.tizen.ui.guides/html/native/efl/ui_components_wn.htm b/org.tizen.ui.guides/html/native/efl/ui_components_wn.htm new file mode 100755 index 0000000..b79e119 --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/ui_components_wn.htm @@ -0,0 +1,874 @@ + + + + + + + + + + + + + Wearable UI Components + + + + + +
      + +

      Wearable UI Components

      + +

      The EFL Elementary is a set of fast, finger-friendly, scalable, and themeable UI component libraries. The number of supported UI components is around 80, including both containers and non-containers. Originally, the Elementary was developed as part of the Window Manager development on Desktop devices. For the wearable profile, Tizen reused the proper UI components and created new UI styles for rectangular and circular wearable devices, and then enhanced and adjusted all of them for Tizen native applications.

      + + + + + + + + + + +
      Note
      This feature is supported in wearable applications only.
      + +

      The UI components are wearable-friendly: for example, the Circle Datetime component extends the elm_date_time by visualizing the selected field, the Circle Genlist component provides a scrollbar with circular movement, and the Circle progress bar/scroller/slider components are adjusted to the circular design.

      +

      The wearable UI components were designed to allow the user to interact with small touch screen-equipped wearable devices with rotary component parts. Therefore, when developing wearable applications, you can easily use them through the wearable-related infrastructure in company with full notification and when reacting to touch and rotary events and the user finger size.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      + Table: Available UI components +
      Component nameDescription
      BackgroundThe background component can be used to set a solid background decoration to a window or a container object. It works like an image, but has some background specific properties, such as setting it to tiled, centered, scaled, or stretched.
      ButtonThe button component is a simple push button. It is composed of a label icon and an icon object, and has an auto-repeat feature.
      CheckThe check component toggles the value of a Boolean between true and false.
      CtxpopupThe ctxpopup component is a contextual popup that can show a list of items.
      DatetimeThe datetime component can display and input date and time values.
      EntryThe entry component is a box to which the user can enter text.
      GenlistThe genlist component displays a scrollable list of items. It can hold a lot of items while still being fast and memory-efficient (only the visible items are allocated memory).
      GLViewThe GLView component can render OpenGL in an Elementary object, hiding EvasGL complexity.
      IconThe icon component inherits from the image component. It is used to display images in an icon context.
      ImageThe image component can load and display an image from a file or from memory.
      IndexThe index component provides an index for fast access to another group of UI items.
      LabelThe label component displays text with simple HTML-like markup.
      ListThe list component is a very simple list for managing a small number of items. If you need to manage a lot of items, use the genlist component instead.
      NotifyThe notify component displays a container in a specific region of the parent object. It can receive some content, and it can be automatically hidden after a certain amount of time.
      PlugThe plug component allows you to show an Evas object created by another process. It can be used anywhere like any other Elementary UI component.
      PopupThe popup component shows a pop-up area that can contain a title area, a content area, and an action area.
      ProgressbarThe progressbar component can be used to display the progress status of a given job.
      RadioThe radio component can display 1 or more options, but the user can only select one of them. The UI component is composed of an indicator (selected/unselected), an optional icon, and an optional label. Even though it is usually grouped with 2 or more other radio components, it can also be used alone.
      SliderThe slider component is a draggable bar that is used to select a value from a range of values.
      TransitThe transit component can apply several transition effects to an Evas object, such as translations and rotations. The use of the transit component is documented in the Creating Animations and Effects guide.
      WinThe win component is the root window component that will be often used in an application. It allows you to create some content in it, and it is handled by the window manager.
      + +

      The following UI components were designed for specific circular wearable devices which have rotary component parts. In a circular device, you can draw round UI components, such as a slider, progressbar, and scroller. Generally, wearable UI components provide compatibility between the rectangular and circular wearable devices. However, use circular UI components for circular wearable devices only, because they have a dependency with the round UX and rotary events. For more information on the compatibility of the UI components between rectangular and circular, see the Wearable Design Guidelines.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      + Table: Available circular UI components +
      Component nameDescription
      Circle DatetimeThe circle datetime extends elm_datetime by visualizing the selected field.
      Circle GenlistThe circle genlist provides a scrollbar with circular movement. It is also operated with rotary events to move to the next or previous item.
      Circle ObjectThe circle object extends elementary components in a form of circular design. Sometimes a circle object merely provides additional UI features to elementary component, and sometimes it works as an independent component with UI and functionalities.
      Circle ProgressbarThe circle progressbar aims to show the progress status of a given task with circular design. It visualizes the progress status within a range.
      Circle ScrollerThe circle scroller changes corresponding to the rotary events. It shows the whole scrollable area with a circular scroll bar.
      Circle SliderThe circle slider changes corresponding to rotary events. The circle slider not only extends the UI feature of the elm_slider, but also replaces the functionalities of the elm_slider in a circular design.
      Circle SurfaceThe circle surface manages and renders circle objects. Multiple circle objects can be connected to one circle surface as candidates of an object to be rendered.
      + +

      Wearable Rectangular UI Component Styles

      + +

      EFL can separate the GUI and logic of each UI component, resulting in each component having a different style of look. To change the styles of UI components, use the elm_object_style_get() and elm_object_style_set() functions to get and apply the style for a specific UI component.

      + +

      The following tables list the styles for each winset, including the names of the styles, and the name of the part where to set text or some other Evas_Object in the UI component. For more detailed information, see the Themes.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Table: Button styles (wearable core)
      StyleSampleText partSwallow partNotes
      default elm.textelm.swallow.content
      greenelm.textelm.swallow.content
      orangeelm.textelm.swallow.content
      redelm.textelm.swallow.content
      nextdepth
      naviframe/title_iconelm.swallow.contentThe icon can be set with the elm_object_part_content_set(btn, "icon", ic) function.
      + + + +++ + + + + + + + + + + + + + +
      Table: Check styles (wearable core)
      StyleSample
      default
      on&off
      + + + + + + + + + + + + + + + +
      Table: Contextual popup (Ctxpopup) styles (wearable core)
      StyleSampleNotes
      defaultUse the elm_ctxpopup_item_append() function to add both text and an icon to the list.
      + + + +++ + + + + + + + + + + + + + +
      Table: Datetime styles (wearable core)
      StyleSample
      datepicker_layout
      timepicker_layout
      + + + + + + + + + + + + + + + + + + + +
      Table: Entry styles
      StyleSampleText partSwallow partNotes
      defaultelm.guide: for the guide text. +

      elm.text: for the main text.

      The guide text is automatically erased when the main text is entered.
      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Table: Genlist styles (wearable core)
      StyleSampleText partSwallow partNotes
      defaultelm.textelm.swallow.icon: for the icon on the left. +

      elm.swallow.end: for the icon on the right.

      group_indexelm.text: for the main text. +

      elm.text.1: for the sub text.

      elm.icon
      1textelm.text
      1text.1iconelm.textelm.icon
      2textelm.text: for the main text. +

      elm.text.1: for the sub text.

      2text.1elm.text: for the main text. +

      elm.text.1: for the sub text.

      1text.1icon.dividerelm.textelm.icon: for the icon. +

      elm.divider: for the icon divider.

      1text.1icon.1elm.textelm.icon
      2text.1icon.1elm.text: for the main text. +

      elm.text.1: for the sub text.

      elm.icon
      multiline/1textelm.text: for the multi-line text.
      multiline/2textelm.text: for the main text. +

      elm.text.1: for the multi-line sub text.

      + + + + + + + + + + + + + + + + + + +
      Table: Index styles (wearable core)
      StyleSample
      thumbnail
      tab
      + + + +++ + + + + + + + + + + + + + +
      Table: Popup styles (wearable core)
      StyleSample
      default
      toast
      + + + + + + + + + + + + + + + + + + + + + + + + + +
      Table: Progressbar styles (wearable core)
      StyleSample
      default
      pending_list
      process
      process/groupindex
      + + + +++ + + + + + + + + + +
      Table: Radio styles (wearable core)
      StyleSample
      default
      + + + + + + + + + + + + + + + + +
      Table: Slider styles
      StyleSampleSwallow part
      horizontal/defaultelm.swallow.icon
      + + +

      Wearable Circular UI Component Styles

      + +

      EFL can separate the GUI and logic of each UI component, resulting in each component having a different style of look. To change the styles of UI components, use the elm_object_style_get() and elm_object_style_set() functions to get and apply the style for a specific UI component.

      + +

      The following tables list the styles for each winset, including the names of the styles, and the name of the part where to set text or some other Evas_Object in the UI component.

      + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Table: Button styles (Gear O)
      StyleSampleText partSwallow partNotes
      default elm.textelm.swallow.content
      bottomelm.textelm.swallow.content
      + + + +++ + + + + + + + + + + + + + + + + + +
      Table: Check styles (Gear O)
      StyleSample
      default
      small
      on&off
      + + + + + + + + + + + + + + + + + + + + + + + + + +
      Table: Contextual popup (Ctxpopup) styles (Gear O)
      StyleSampleNotes
      select_mode
      select_mode/topPair this style with select_mode/bottom.
      select_mode/bottomPair this style with select_mode/top.
      + + + +++ + + + + + + + + + + + + + +
      Table: Datetime styles (Gear O)
      StyleSample
      datepicker/circle
      timepicker/circle
      + + + + + + + + + + + + + + + + + + + +
      Table: Entry styles
      StyleSampleText partSwallow partNotes
      defaultelm.guide: for the guide text. +

      elm.text: for the main text.

      The guide text is automatically erased when the main text is entered.
      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Table: Genlist styles (Gear O)
      StyleSampleText partSwallow partNotes
      defaultelm.textelm.swallow.icon: for the icon on the left. +

      elm.swallow.end: for the icon on the right.

      titleelm.text
      groupindexelm.text
      1textelm.text
      1text.1iconelm.textelm.icon
      2textelm.text: for the main text. +

      elm.text.1: for the sub text.

      1text.1icon.dividerelm.textelm.icon: for the icon. +

      elm.divider: for the icon divider.

      1text.1icon.1elm.textelm.icon
      2text.1icon.1elm.text: for the main text. +

      elm.text.1: for the sub text.

      elm.icon
      editfieldelm.text
      + + + + + + + + + + + + + + + + + + +
      Table: Index styles (Gear O)
      StyleSample
      thumbnail
      circle
      + + + +++ + + + + + + + + + + + + + +
      Table: Popup styles (Gear O)
      StyleSample
      circle
      toast/circle
      + + + + + + + + + + + + + + + + + +
      Table: Progressbar styles (Gear O)
      StyleSample
      process
      process/small
      + + + +++ + + + + + + + + + +
      Table: Radio styles (Gear O)
      StyleSample
      default
      + + + + + + + + + + + + + + + + +
      Table: Slider styles
      StyleSampleSwallow part
      horizontal/defaultelm.swallow.icon
      + + + + + + + + + + +
      Note
      Except as noted, this content is licensed under LGPLv2.1+.
      + + + +
      + +Go to top + + + + + + + \ No newline at end of file diff --git a/org.tizen.ui.guides/html/native/efl/ui_containers_n.htm b/org.tizen.ui.guides/html/native/efl/ui_containers_n.htm new file mode 100755 index 0000000..5db93d6 --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/ui_containers_n.htm @@ -0,0 +1,131 @@ + + + + + + + + + + + + + UI Containers: Creating Layouts Using Container UI Components + + + + + +
      + +

      UI Containers: Creating Layouts Using Container UI Components

      + +

      All applications use containers to create the layout of the UI. The EFL and Elementary support several ways to create this layout. You can use predefined layouts or animated layouts, or you can create your own layouts. It is important to note that container UI components do not have their own visual identity - only logical structures for assignment or placement of the UI components.

      + +

      When you use container components, such as naviframe, conformant, button, and box, you need to understand certain APIs related to alignment, and EDC parts for, for example, the core layout and animated layout. For more information on the containers EDC parts, see Positioning and Laying out Parts Using the EDC File. The use of the container UI components only differs from the use of the UI components through their absence of a visual identity.

      + +

      Most of the time, your application has to manage multiple views. The easiest way to handle them with the EFL is to create a naviframe object. This object is a container. At first, it is used to contain the pages your application is composed of. Every Tizen application can use this top-layer object to facilitate navigation. More details can be found in Creating a Naviframe for Navigation.

      + +

      Another interesting object that has to be present in every application is the conformant object. Conformant is a container component that accounts for the space taken up by the indicator, virtual keyboard, and softkey windows. The conformant content will be resized and positioned based on the space available. When the virtual keyboard is displayed, the content does not change.

      + +

      Figure: Basic EFL application structure

      +

      Basic EFL application structure

      + +

      Container Components

      + +

      The following table lists the available UI container components.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      + Table: Available container components +
      Container nameDescription
      BoxOne of the most simple containers in the EFL is a box.
      ConformantA conformant is a container component that accounts for the space taken by the indicator, virtual keyboard, and softkey windows.
      GridIn a grid, objects are placed at specific positions along a fixed grid.
      LayoutA layout is a container component that takes a standard Edje design file and wraps it very thinly in a UI component.
      MapbufA mapbuf is a container component that uses an Evas map to hold a content object. This UI component is used to improve the moving and resizing performance of complex UI components.
      NaviframeA naviframe component consists of a stack of views. New views are pushed on top of previous ones, and only the top-most view is displayed.
      Panes
      (in mobile applications only)
      A panes component adds a draggable bar between two sections of content. The sections are resized when the bar is dragged.
      ScrollerA scroller holds (and clips) a single object and allows you to scroll across it.
      TableA table is like a box but with 2 dimensions.
      + + + + + + +
      + +Go to top + + + + + + + \ No newline at end of file diff --git a/org.tizen.ui.guides/html/native/efl/ui_scalability_n.htm b/org.tizen.ui.guides/html/native/efl/ui_scalability_n.htm new file mode 100755 index 0000000..483202a --- /dev/null +++ b/org.tizen.ui.guides/html/native/efl/ui_scalability_n.htm @@ -0,0 +1,69 @@ + + + + + + + + + + + + + Scaling: Handling Screen and Object Sizes + + + + + +
      + +

      Scaling: Handling Screen and Object Sizes

      + +

      Supporting UI scalability in a user interface toolkit means that container components and UI components are scaled properly when the resolution or screen size changes. The Elementary library allows you to manipulate scaling on a per-UI-component basis using a scale factor based on the screen resolution, size, and profile configurations.

      + +

      Tizen native applications can run on different types of devices, such as wearable, phone, tablets, and TVs. Tizen also supports various resolutions (WVGA - XQXGA) with the same layouts and resources. However, remember that you must always polish your work to create an optimal application for each device.

      + +

      The main scalability features are:

      +
        +
      • Multiple Screen Support

        Enables you to design applications for different kinds of screens.

      • +
      • Scalability Support

        Enables you to design applications so that their UI can be scaled for diverse devices without problems.

      • +
      + + + +
      + +Go to top + + + + + + + \ No newline at end of file diff --git a/org.tizen.ui.guides/html/native/guides_n.htm b/org.tizen.ui.guides/html/native/guides_n.htm new file mode 100755 index 0000000..76cfcde --- /dev/null +++ b/org.tizen.ui.guides/html/native/guides_n.htm @@ -0,0 +1,77 @@ + + + + + + + + + + + + + + Tizen Native UI Guides + + + + + + +
      +

      Tizen
      +Native UI Guides

      + +

      The UI framework features include various aspects of creating a visual outlook for the user application to ensure the best possible user experience.

      + +

      The UI framework is a universal, reusable software environment that provides the essential building blocks as part of the Tizen platform to facilitate the development of Tizen native applications. The framework provides the window, UI components, and scene-based graphic rendering architecture needed to manage your application user interface. In addition, the framework provides animations and effects needed to make your application more fresh and vivid, event handling and the main loop to interact with the user and system, and more features, such as scalability, and font setting.

      + +

      The Tizen platform provides the following native UI toolkit frameworks for developing a native application:

      + +
        +
      • EFL (Enlightenment Foundation Libraries) +

        EFL provides streamlined graphic core libraries you need to create powerful applications. EFL needs lower memory but provides high performance, and supports a retained mode graphics system and user-centric features, such as themes, 2D/3D effects, and accessibility. In addition, EFL supports various resolutions with the same layout, fast and small file systems, a variety of programming language bindings, and a separate UI and logic.

        +

        Generally, select the EFL UI toolkit if you are creating a 2D-based Tizen native application. However, EFL supports 2.5D and 3D effects and 3D objects as well.

      • +
      • DALi (Dynamic Animation Library) +

        DALi is based on OpenGL ES 2.0 and 3.0; however it hides the complexity of the OpenGL ES API from you. DALi requires a GPU (Graphical Processing Unit) on the device.

        +

        Select the DALi 3D UI toolkit if you are creating a high-performance rich UI application.

      • +
      + + + + +
      + +Go to top + + + + + + + + diff --git a/org.tizen.ui.guides/html/scripts/common.js b/org.tizen.ui.guides/html/scripts/common.js new file mode 100755 index 0000000..d46479a --- /dev/null +++ b/org.tizen.ui.guides/html/scripts/common.js @@ -0,0 +1,1752 @@ +$(document).ready(function(){ + $('#contents table').each(function(){ + if (!$(this).parent().hasClass('table')) { + $(this).wrap('
      '); + } + }); + + // Lnb Menu Initialize + if($('div#contents').find('.lnb').length){ + if($("ul li.events_news").size() > 0) { + $("ul.lnb").after("

      \"Samsung

      "); + } + initLnb(); + initScript(staticURL + "/js/fixednavbar.js", function(){}); + } + + //family site + if($('div#footer').find('dl#familySlider').length){ + fn_rollToEx('familySlider', 'sliderBanner', 1, true); + } + + // Svn Commit Test + + // Language Selection + if($('div#header').find('.util').length){ + var $lang = $('div#header').find('.util'); + $lang.find('a.lang').toggle(function(){ + $(this).css('background-image', $(this).css('background-image').replace('.gif','_.gif')).next('ul.language').show(); + },function(){ + $(this).css('background-image', $(this).css('background-image').replace('_.gif','.gif')).next('ul.language').hide(); + }); + + $lang.bind('mouseleave',function(){ + $(this).find('ul.language').hide(); + $lang.find('a.lang').css('background-image', $lang.find('a.lang').css('background-image').replace('_.gif','.gif')); + }); + + $lang.find('ul.language').children().last().on("keydown", function(e) { + if(e.which == 9 && e.shiftKey) { + return true; + } + + if(e.which == 9) { + e.preventDefault(); + $lang.find('ul.language').hide(); + $lang.find('a.lang').css('background-image', $lang.find('a.lang').css('background-image').replace('_.gif','.gif')); + setTimeout(function() { + $("#searchTop").focus(); + }, 1); + } + }); + } + + // Open the Sitemap + var $open = $('div#header').find('.bt-open'); + $open.bind('click',function(){ + var $self = $(this); + var $sitemap = $('div#wrapper').find('div#sitemap'); + //var source = $sitemap.is(':visible') ? $self.css('background-image').replace('_.gif','.gif') : $self.css('background-image').replace('.gif','_.gif'); + + if($sitemap.is(':visible')){ + var source = $self.css('background-image').replace('_.gif','.gif'); + //if($('body#main').length) $('#header .util').css('border-bottom','3px solid #e4e4e4'); + + $self.attr('title','open sitemap'); + }else{ + var source = $self.css('background-image').replace('.gif','_.gif'); + //if($('body#main').length) $('#header .util').css('border-bottom','3px solid #114196'); + + $self.attr('title','close sitemap'); + } + + $self.css('background-image',source); + $sitemap.slideToggle('fast'); + + $sitemap.find('ul').filter(':last').children().filter(':last').focusout(function(){ + var source = $self.css('background-image').replace('_.gif','.gif'); + $self.css('background-image',source); + $sitemap.slideToggle('fast'); + }); + + }); + + // Search Auto Complete + var $search = $('div#header').find('fieldset.search'); + var $searchList = $search.find('#topAutocomplete>ul'); + + if($search.length){ + $search.find('> input').each(function(){ + $(this).bind({ + keydown : function(e){ + + if(e.type=='keydown'&& $(this).val().length!=0){ + $search.find('#topAutocomplete').show(); + var hei = $searchList.outerHeight(); + if(hei>400){ + $searchList.css({'height':'400px','overflow-y':'auto'}); + } + } + if(e.keyCode==9){ + $search.unbind('focusout.search'); + } + if(e.keyCode==40){ + $search.find('#topAutocomplete>ul').children(':first').find('a').focus(); + //window.scrollTo(0,0); + } + }, + focusin : function(e){ + if($(this).val()==='Search'){ + $(this).val(''); + } + }, + focusout : function(e){ + if($(this).val().length==0) $(this).val('Search'); + } + }); + }); + + //$('#topAutocomplete>ul').children().find('a').bind('focusin',function(e){ + // if(e.keyCode==40){ + // $(this).parent().next().css('border','1px solid red').find('a').focus(); + // } + //}); + + $search.find('#topAutocomplete').bind('mouseleave',function(e){ + if($search.find('> input').val().length==0){ + $search.find('> input').val('Search'); + } + $search.find('#topAutocomplete').hide(); + }); + + $search.find('#topAutocomplete>ul').children().last().focusout(function(){ + $search.find('> input').val('Search'); + $search.find('#topAutocomplete').hide(); + + //$search.bind('focusout.search', function(){ + // $(this).find('> input').val('Search'); + // $(this).find('#topAutocomplete').hide(); + //}); + }); + } +}); + +// 비차단 동적 스크립트 로딩 +function initScript(url, callback){ + var script = document.createElement("script"); + script.type = "text/javascript"; + + if(script.readyState){ // 인터넷 익스플로러 + script.onreadystatechange = function(){ + if(script.readyState=="loaded" || script.readyState=="complete"){ + script.onreadystatechange = null; + callback(); + } + }; + }else{ // 다른 브라우저 + script.onload = function(){ + callback(); + }; + } + + script.src = url; + document.getElementsByTagName("head")[0].appendChild(script); +} + + +// lnb +function initLnb(){ + var sMenu = $('.lnb'); + var sItem = sMenu.find('>li'); + + sItem.each(function(){ + if($(this).find('a').hasClass('more')){ + if($(this).find('ul').is(":visible")) { + $('').insertAfter($(this).find('a').eq(0)); + } else { + $('').insertAfter($(this).find('a').eq(0)); + } + } + }); + + var setIcoArrText = function(obj) { + if(obj.next().is(":visible")) { + obj.text("close submenu"); + } else { + obj.text("open submenu"); + } + } + + sItem.find('.ico-arr').on("click", function() { + var $that = $(this); + var liBox = $that.parent(); + var ulBox = $that.next(); + + sItem.not(liBox).not(".on").find("a.more").next().next().hide(); + sItem.not(liBox).removeClass("active").find("a").removeClass("bov"); + + if(liBox.hasClass("on")) { + if(ulBox.is(":visible")) { + ulBox.hide(); + $that.addClass("ico-on"); + } else { + ulBox.show(); + $that.removeClass("ico-on"); + } + setIcoArrText($that); + return true; + } + + if(liBox.hasClass("active")) { + liBox.removeClass("active").find("a").eq(0).removeClass("bov"); + ulBox.hide(); + } else { + liBox.addClass("active").find("a").eq(0).addClass("bov"); + ulBox.show(); + } + setIcoArrText($that); + }); + + sItem.hover(function(){ + if($(this).hasClass('on')||$(this).hasClass('active')) return false; + $(this).find("a").eq(0).addClass("bov"); + },function(){ + if($(this).hasClass('on')||$(this).hasClass('active')) return false; + $(this).find("a").eq(0).removeClass("bov"); + + }); +} + +//footer rolling banner +function fn_rollToEx(container,objectId,step,auto){ + + // 롤링할 객체를 변수에 담아둔다. + var el = $('#'+container).find('#'+objectId); + var lastChild; + var speed = 3000; + var timer = 0; + var autoplay = false; + + el.data('prev', $('#'+container).find('.prev')); //이전버튼을 data()메서드를 사용하여 저장한다. + el.data('next', $('#'+container).find('.next')); //다음버튼을 data()메서드를 사용하여 저장한다. + el.data('size', el.children().outerWidth()); //롤링객체의 자식요소의 넓이를 저장한다. + el.data('len', el.children().length); //롤링객체의 전체요소 개수 + el.data('animating',false); + el.data('step', step); //매개변수로 받은 step을 저장한다. + el.data('autoStart', false); //매개변수로 받은 step을 저장한다. + + el.css('width',el.data('size')*el.data('len')); //롤링객체의 전체넓이 지정한다. + + if(arguments.length==4){ + el.data('autoStart', auto); + } + + if(el.data('autoStart')){ + if(timer==0){ + timer = setInterval(moveNextSlide, speed); + autoplay = true; + } + } + + el.bind({ + mouseenter:function(){ + if(!autoplay) return false; + + if(timer!=0 && el.data('autoStart')){ + clearInterval(timer); + timer=0; + } + }, + mouseleave:function(){ + if(!autoplay) return false; + + if(timer==0 && el.data('autoStart')){ + timer = setInterval(moveNextSlide, speed); + } + } + }); + + + //el에 첨부된 prev 데이타를 클릭이벤트에 바인드한다. + el.data('prev').bind({ + click:function(e){ + e.preventDefault(); + movePrevSlide(); + }, + mouseenter:function(){ + + $(this).find('img').addClass('btnOn'); + + if(!autoplay) return false; + + if(timer!=0 && el.data('autoStart')){ + clearInterval(timer); + timer=0; + } + }, + mouseleave:function(){ + + $(this).find('img').removeClass('btnOn'); + + if(!autoplay) return false; + + if(timer==0 && el.data('autoStart')){ + timer = setInterval(moveNextSlide, speed); + } + } + }); + + //el에 첨부된 next 데이타를 클릭이벤트에 바인드한다. + el.data('next').bind({ + click:function(e){ + e.preventDefault(); + moveNextSlide(); + }, + mouseenter:function(){ + + $(this).find('img').addClass('btnOn'); + + if(!autoplay) return false; + + if(timer!=0 && el.data('autoStart')){ + clearInterval(timer); + timer=0; + } + }, + mouseleave:function(){ + + $(this).find('img').removeClass('btnOn'); + + if(!autoplay) return false; + + if(timer==0 && el.data('autoStart')){ + timer = setInterval(moveNextSlide, speed); + } + } + }); + + function movePrevSlide(){ + if(!el.data('animating')){ + //전달된 step개수 만큼 롤링객체의 끝에서 요소를 선택하여 복사한후 변수에 저장한다. + var lastItem = el.children().eq(-(el.data('step')+1)).nextAll().clone(true); + lastItem.prependTo(el); //복사된 요소를 롤링객체의 앞에 붙여놓는다. + el.children().eq(-(el.data('step')+1)).nextAll().remove(); //step개수만큼 선택된 요소를 끝에서 제거한다 + el.css('left','-'+(el.data('size')*el.data('step'))+'px'); //롤링객체의 left위치값을 재설정한다. + + el.data('animating',true); //애니메이션 중복을 막기 위해 첨부된 animating 데이타를 true로 설정한다. + + el.animate({'left': '0px'},'normal',function(){ //롤링객체를 left:0만큼 애니메이션 시킨다. + el.data('animating',false); + }); + } + return false; + } + + function moveNextSlide(){ + if(!el.data('animating')){ + el.data('animating',true); + + el.animate({'left':'-'+(el.data('size')*el.data('step'))+'px'},'normal',function(){ //롤링객체를 첨부된 size와 step을 곱한 만큼 애니메이션 시킨다. + //전달된 step개수 만큼 롤링객체의 앞에서 요소를 선택하여 복사한후 변수에 저장한다. + var firstChild = el.children().filter(':lt('+el.data('step')+')').clone(true); + firstChild.appendTo(el); //복사된 요소를 롤링객체의 끝에 붙여놓는다. + el.children().filter(':lt('+el.data('step')+')').remove(); //step개수만큼 선택된 요소를 앞에서 제거한다 + el.css('left','0px'); ////롤링객체의 left위치값을 재설정한다. + + el.data('animating',false); + }); + } + return false; + } + +} + +function fn_slide(options){ + + var opts = jQuery.extend({},options); + + var $bt = $('#'+opts.container).find('#'+opts.bt).children(); //롤링버튼에 대한 선택자 + var $obj = $('#'+opts.container).find('#'+opts.obj); //objectId를 id로 갖는 롤링객체의 선택자 + var $prev = $('#'+opts.container).find('#'+opts.prev).hide(); //이전버튼에 대한 선택자 + var $next = $('#'+opts.container).find('#'+opts.next); //다음버튼에 대한 선택자 + var size = $obj.children().outerWidth(); //롤링객체의 각 이미지 넓이값 + var len = $obj.children().length; //롤링객체의 이미지 갯수 + var effect = false; //슬라이드효과를 위한 boolean변수 + var auto = false; + var current = 0; //현재 보여지는 이미지의 인덱스값을 저장하기 위한 변수 + var time; + + + $obj.css('width',size*len); //롤링객체의 전체넓이 지정 + effect = opts.effect; + auto = opts.auto; + + if(auto){ + time = setTimeout('slideShow()',3000); + } + + slideShow = function(){ + + if(current < len-1){ + current++; + }else{ + current=0; + } + + controllStatus(); + + moveControl('next'); + + time = setTimeout('slideShow()',3000); + } + + controllStatus = function(){ + //이미지의 인덱스값에 따라 이전,다음 버튼 활성여부 지정 + if(current>0||current=len-1){ + $prev.show(); + $next.hide(); + } + } + + moveControl = function(msg){ + if(opts.bt!=null){ + msg=='next'? $bt.eq(current-1).find('img').attr('src', $bt.eq(current-1).find('img').attr('src').replace('_.png','.png')) + :$bt.eq(current+1).find('img').attr('src', $bt.eq(current-1).find('img').attr('src').replace('_.png','.png')); //이전에 활성화된 롤링버튼을 비활성화 + $bt.eq(current).find('img').attr('src', $bt.eq(current).find('img').attr('src').replace('.png','_.png')); //현재 인덱스값을 가지는 롤링버튼을 활성화 + } + + if(effect!=true){ //action변수가 true가 아닐경우 슬라이드 효과없이 현재의 인덱스값을 갖는 이미지를 보여줌. + $obj.children().hide(); + $obj.children().eq(current).show(); + }else{ //action변수가 true일 경우 현재의 인덱스값을 갖는 이미지로 슬라이드됨 + $obj.animate({'left':'-'+size*current},'slow'); + } + } + + $obj.bind({ + mouseenter:function(){ + if(!auto) return false; + clearTimeout(time); + }, + mouseleave:function(){ + if(!auto) return false; + time = setTimeout('slideShow()',3000); + } + }); + + //롤링 버튼 클릭시 + $bt.bind({ + mouseenter:function(){ + if(!auto) return false; + clearTimeout(time); + }, + mouseleave:function(){ + if(!auto) return false; + time = setTimeout('slideShow()',3000); + }, + click:function(){ + var idx = $bt.index(this); //클릭한 롤링버튼의 인덱스값 저장 + + current = idx; //롤링버튼의 인덱스값을 이미지의 인덱스값으로 지정 + + controllStatus(); + + if(effect!=true){ //action변수가 true가 아닐경우 슬라이드 효과없이 현재의 인덱스값을 갖는 이미지를 보여줌. + $obj.children().hide(); + $obj.children().eq(current).show(); + }else{ //action변수가 true일 경우 현재의 인덱스값을 갖는 이미지로 슬라이드됨 + $obj.animate({'left':'-'+size*current},'slow'); + } + + // 모든 롤링 버튼을 비활성화 + $bt.each(function(){ + var source = $(this).find('img').attr('src').replace('_.png','.png'); + $(this).find('img').attr('src',source); + }); + + // 선택한 롤링버튼을 활성화 + var source = $(this).find('img').attr('src').replace('.png','_.png'); + $(this).find('img').attr('src',source); + + return false; + } + }); + + //이전 버튼 클릭시 + $prev.bind({ + mouseenter:function(){ + var source = $(this).find('img').attr('src').replace('.png','_.png'); + $(this).find('img').attr('src',source); + if(!auto) return false; + clearTimeout(time); + }, + mouseleave:function(){ + var source = $(this).find('img').attr('src').replace('_.png','.png'); + $(this).find('img').attr('src',source); + if(!auto) return false; + time = setTimeout('slideShow()',3000); + }, + click:function(){ + if(current==len-1) $next.show(); //이미지 인덱스값이 마지막이 아닐경우 비활성화된 다음버튼을 활성화 + current--; //이미지 인덱스값 1씩 감소 + + moveControl('prev'); + + if(current==0) $(this).hide(); //이미지 인덱스값이 0일 경우, 즉 현재 첫번째 이미지가 활성화될 경우 이전버튼을 비활성화 + + return false; + } + }); + + //다음 버튼 클릭시 + $next.bind({ + mouseenter:function(){ + var source = $(this).find('img').attr('src').replace('.png','_.png'); + $(this).find('img').attr('src',source); + if(!auto) return false; + clearTimeout(time); + }, + mouseleave:function(){ + var source = $(this).find('img').attr('src').replace('_.png','.png'); + $(this).find('img').attr('src',source); + if(!auto) return false; + time = setTimeout('slideShow()',3000); + }, + click:function(){ + current++; //이미지 인덱스값 1씩 증가 + + moveControl('next'); + + if(current>=len-1) $(this).hide(); //이미지인덱스값이 마지막일 경우, 즉 현재 마지막 이미지가 활성화될 경우 다음버튼을 비활성화 + if(current>0) $prev.show(); //이미지인덱스값이 0이 아닌경우 이전버튼 활성화 + + return false; + } + }); + +} + +// main rolling banner +function slideMotion1(){ + var $banner = $('#rolling .motionview'), + //$nav = $('#rolling ul.nav'), + banner = {prev:null, next:null}, + size = $banner.children().length; + index = 1, + speed = 3000, + timer = null, + auto = true, + width = parseInt(100/size), + rest = parseInt(100%size); + + var $nav = $('