Skip to main content
Samsung Developer Program

Integrating SmartClip

SmartClip enables your app users to screen capture metadata (text, title, URL, and deep link URI data, such as product detail information, websites, and web locations) that your app assigns to screen-captured views. SmartClip also enables your app users to capture the cropped displayed text. SmartClip makes captured metadata and user-cropped display text available to screen capture and management apps. Your app can control what captured data is available. Without SmartClip, users can only capture displayed text and images using traditional screen capture apps.  

Your app can integrate SmartClip API methods to do the following:

  • For any view (custom or default), your app can directly assign metadata.
  • For custom views only, your app can indirectly assign metadata by specifying the metadata in a view-call listener registered to a custom view.  
    Note: BOTH direct metadata and indirect metadata assigned to a custom view cannot be available to screen capture management apps and your users.
    When both are assigned to a custom view, only the indirect metadata will be available.
  • Your app can control how direct metadata, indirect metadata, and user-cropped display text is made available via a listener registered to a custom view.
  • When a listener is not registered to a view (custom or default), directly assigned metadata and user-cropped display text are always available.

For details about the SmartClip API class and interface methods, see SmartClip API Structure.

Metadata Screen Capture, Collecting, and Managing

After your app has integrated SmartClip, your users can screen capture views and review and act on their assigned metadata and display text.

Metadata and user-cropped display text availability depends on your app and the functionality of screen capture and management apps. This document explains SmartClip functionality as provided by the following screen capture and management apps. In Air command Smart select, your users can capture metadata that your app assigns. In the Collect screen capture management app, your users can review and copy text metadata, and manage URL and URI metadata.

Samsung Look S-Pen SmartClip User Capture Call Sequence Diagram for Views without Listeners.png

 

 

Samsung Look S-Pen SmartClip User Capture Call Sequence Diagram for Views with Listeners

The user initiates screen capture by cropping a screen area with their S-Pen. The device platform issues a user-crop call with the screen coordinates. SmartClip determines all of the views that are partially or entirely within the cropped area (including all partially- or fully-overlapping larger views back to and including the root parent view). SmartClip calls each view-call listener registered to captured custom views.  

If there are no listeners registered to the captured views, custom or default, SmartClip gets the directly assigned metadata and determines the user-cropped display text of each captured view. SmartClip then makes this available to screen capture management apps.

If there are listeners registered to captured custom views, SmartClip calls each view's listener and processes its callback, which controls what is to be made available: either direct or indirect metadata and/or user-cropped display text.

As specified by each captured view's listener, SmartClip ensures that directly and indirectly assigned metadata and user-cropped display text are made available to screen capture management apps for your users to review and manage.  

Your users can then review, act on, and manage each view's metadata and display text that is available.

Note: Screen capture, collection, and management functionality depends on the application being used.

The following Samsung device apps support SmartClip: 

Model Screen Capture Collection Management
Samsung Note2 Easy Clip    
Samsung Note3 Easy Clip (SM-N900 devices)
Air command Screen write
 
  Air command Scrap booker
Samsung Note4 Air command Screen select Collect Scrapbook

Metadata Screen Capturing and Collecting

For SmartClip-integrated apps, Air command Smart select enables your users to quickly capture a rectangular area and initiate screen capture management via the Collect utility and Scrapbook.

Note: In this section, SmartClip support is illustrated using the Air command Smart select, Collection, and Scrapbook applications.  

In Air command Smart select, your users can capture metadata that your app assigns. In the Collect screen capture management app, your users can review and copy text metadata, and manage URL and URI metadata.

Metadata Screen Capture via Samsung AirCommand SmartSelect, with Review and Management

You capture all or part of the display screen by:

  1. Hover your S-Pen anywhere above the display screen and pressing the S-Pen button.
  2. In the Air command selection popup, hover your S-Pen over and pressing it on Smart select icon.
  3. In the screen to be captured, press your S-Pen on the initial corner of the area to be captured, drag your S-Pen to cover the area, and pick up your S-Pen.
  4. In the Collect utility, review and manage the capture.

The Collect utility provides your users with quick management of screen captures and their metadata. Collect is automatically made available to your users after screen capture via Air command Smart select. Up to 10 screen captures can be in one collection, which can be saved to the user's My Scrapbook. However, users can capture, review, copy, and act on the metadata of more screen captures than the maximum of 10, without being able to save the extra captures. Users can copy Metadata and displayed text in the Metadata and Text window.  

Metadata Screen Capture and Collection via Samsung Collect.png

Metadata Screen Capture / Collection Management 

After saving individual screen captures and collections of screen captures, My Scrapbook provides management of collections, and individual screen captures and their metadata. After collecting one or more screen captures, your users can review, share, mark as a favorite, edit, and act on captured metadata and displayed content in each collection and its individual captures.

Metadata Screen Capture and Collection Management via Samsung Scrapbook.png

Setting Up SmartClip Metadata Capture

To enable your users to capture text, title, URL, and/or deep link URI metadata associated with your app's UI views, assign metadata to a view using only one of the following methods: 

  • Directly assign metadata to a custom or default view.
    • Integrate SmartClip API methods into a view object.
    • Assign metadata content and type via one or more meta-tags to a view object.
  • Indirectly assign metadata to a custom view via a view-call listener registered to the view.
    • Integrate SmartClip API methods into the listener.
    • One or more listeners can be registered to a custom view. However, only one listener can respond to a SmartClip call. For example, regional customer support contact information can be metadata specified in several listeners, where each listener is assigned metadata for one region and your app determines which listener responds based on the user's home address.

Note: If metadata is BOTH directly and indirectly assigned to a custom view, only the indirect metadata will be available.

Direct and indirect assignment produces the same results for user management of captured metadata. The only processing difference is that directly assigned metadata (viat addMetaTag) is added when the method is called. Indirectly assigned metadata (via setDataExtractionListener) is added when a screen area is captured. 

If a custom or default view does not have a listener, upon screen capture of the view:

  • Directly assigned metadata is made available.
  • Metadata cannot be indirectly assigned.
  • User-cropped display text is automatically made available, without any specification by your app, unless prevented by the view's listener.  
  Custom View Default View
Direct Metadata When assigned When assigned
Indirect Metadata Not available Not available
Cropped Display Text Always available Always available

If a custom view has a listener, upon screen capture of the view:

  • Directly assigned metadata is made available when the listener does not indirectly assign metadata.
  • Directly assigned metadata will NOT be made available when the listener indirectly assigns metadata.
  • Indirectly assigned metadata will be made available when the listener specifies EXTRACTION_DEFAULT.
  • Indirectly assigned metadata will NOT be made available when the listener specifies EXTRACTION_DISCARD.
  • User-cropped display text will be made available when the listener specifies extractDefaultSmartClipData().
  • User-cropped display text will NOT be made available when the listener indirectly assigns metadata AND does NOT specify extractDefaultSmartClipData().
  Availability  Listener
Methods / Settings
       
    onExtractDefault
SmartClipData()
SlookSmartClip
​MetaTag()
addTag() extractDefault
SmartClipData()
EXTRACTION
_DEFAULT
Direct Metadata When allowed by the listener n/a Must NOT be specified Must NOT be specified n/a Makes direct metadata available
Indirect Metadata When assigned
and allowed by the listener
Assigns variable to 
listener data container
Specifies metadata in a meta-tag Assigns metadata to listener's view by adding a meta-tag to listener data container n/a Makes indirect metadata available
Cropped
Display Text 
When allowed by the listener n/a n/a n/a Makes user-cropped display text available n/a

SmartClip gives your app control of what metadata and/or user-cropped display text is available to users:

To make the following available
for a captured view:
For custom views: For any view (custom or default):
Only indirectly assigned metadata Do NOT directly assign metadata.
Register a listener by specifying setDataExtractionListener() and onExtractDefaultSmartClipData().
Do NOT specify extractDefaultSmartClipData().
Specify SlookSmartClipMetaTag(), addTag(), and EXTRACTION_DEFAULT.
 
Only user-cropped display text Do NOT directly assign metadata.
Register a listener by specifying setDataExtractionListener and onExtractDefaultSmartClipData().
Do NOT specify SlookSmartClipMetaTag() or addTag().
Specify extractDefaultSmartClipData() and EXTRACTION_DEFAULT.
Do NOT directly assign metadata.
Do NOT register a listener.
User-cropped display text and directly assigned metadata Directly assign metadata.
Register a listener by specifying setDataExtractionListener() and onExtractDefaultSmartClipData().
Do NOT specify SlookSmartClipMetaTag(), or addTag().
Specify extractDefaultSmartClipData() and EXTRACTION_DEFAULT.
Directly assign metadata.
Do NOT register a listener.
User-cropped display text and indirectly assigned metadata Do NOT directly assign metadata.
Register a listener by specifying setDataExtractionListener and onExtractDefaultSmartClipData().
Specify extractDefaultSmartClipData(), SlookSmartClipMetaTag(), addTag(), 
and EXTRACTION_DEFAULT.
 

To directly assign metadata to a custom or default view without a listener to make the metadadata and user-cropped display text available:

  1. Create a SmartClip instance that targets a view for metadata assignment (SlookSmartClip).
  2. Directly assign metadata to the view via one or more added meta-tags:
    1. Unassign all direct metadata previously assigned to the view (clearAllMetaTag).
    2. For each meta-tag:
      1. Specify its metadata type and value (SlookSmartClipMetaTag).
      2. Directly assign the meta-tag metadata to the view (addMetaTag).

To indirectly assign metadata to a view and/or register a view-call listener that specifies what is to be available:

  1. Create a SmartClip instance that targets a view for metadata assignment (SlookSmartClip).
  2. Register a view-call listener to the custom view (setDataExtractionListener):
    1. Assign variable names to data provided by SmartClip: the captured view, its listener data container, and the user-crop area (onExtractSmartClipData).
    2. Conditional  Indirectly assign metadata to the listener's view by specifying one or more meta-tags:
      Note: This step is required when making user-cropped display text NOT available.  When not doing that, this step is optional.
      1. Specify its metadata type and value (SlookSmartClipMetaTag).
      2. Indirectly assign the meta-tag's metadata to the view (addTag).
    3. Specify whether or not user-cropped display text is to be made available:
      1. To make it available, specify extractDefaultSmartClipData().
      2. To make it NOT available: indirectly assign metadata (step 2.) and do NOT specify extractDefaultSmartClipData().
    4. Specify the type of data to be made available (setDataExtractionListener return statement):
      1. To make all indirect metadata and user-cropped display text available, specify EXTRACTION_DEFAULT.
      2. To make ONLY user-cropped display text available, specify EXTRACTION_DISCARD

Example Code:  Directly Assign Metadata to a Any View (Text View in the Example Below)

...

<TextView
android:id="@+id/text_static"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:background="#FFDDDDDD"
android:text="Displayed text for text view A"/>
...

package com.samsung.android.example.slookdemos; 

import com.samsung.android.sdk.look.smartclip.SlookSmartClip; 
import com.samsung.android.sdk.look.smartclip.SlookSmartClipMetaTag; 

import android.app.Activity; 
import android.content.ActivityNotFoundException; 
import android.content.ComponentName; 
import android.content.Intent; 
import android.os.Bundle; 
import android.view.View; 
import android.widget.Button; 
import android.widget.TextView; 
import android.widget.Toast; 

public class SmartClipActivity extends Activity { 

    @Override 
    public void onCreate(Bundle savedInstanceState) { 
        super.onCreate(savedInstanceState); 

        setContentView(R.layout.activity_smartclip); 

        TextView tv = (TextView) findViewById(R.id.text_static); 

        ​/* Create an SlookSmartClip instance and set the view. */
        SlookSmartClip sc = new SlookSmartClip(tv); 
        
        ​/* UNassign all metadata that was previously directly assigned to the view. */
        sc.clearAllMetaTag(); 
        
        /* Create a SmartClip meta-tag and assign its metadata to the view. */
        sc.addMetaTag(new SlookSmartClipMetaTag( 
            SlookSmartClipMetaTag.TAG_TYPE_URL, 
            "http://www.samsung.com")); 
            
        /* Create another SmartClip meta-tag and assign its metadata to the view. */
        sc.addMetaTag(new SlookSmartClipMetaTag( 
            SlookSmartClipMetaTag.TAG_TYPE_PLAIN_TEXT, 
            "Direct text metadata for text view A")); 
    }
}

Example Code:  Indirectly Assign Metadata to a Custom View via its Listener that Makes Indirect Metadata and User-Cropped Display Text Available

...

<com.samsung.android.example.slookdemos.CustomTextView
android:id="@+id/text_dynamic"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:layout_marginBottom="100dip"
android:
    }); 
}
...

void init() {
    /* Create an SlookSmartClip instance and set the target view. */
    vSmartClip = new SlookSmartClip(this);
    
    /* Register to the target view a listener that sends captured view information to SmartClip. */
    vSmartClip.setDataExtractionListener(new
        SlookSmartClip.DataExtractionListener() {

        @Override
        /* Assign variables to the captured view, the listener data container, and the screen crop area. */
        public int onExtractSmartClipData(View view,
            SlookSmartClipDataElement resultElement,
                SlookSmartClipCroppedArea arg) {

            /* Make user-cropped display text available. */
            vSmartClip.extractDefaultSmartClipData(resultElement, arg);

            /* Create a meta-tag and indirectly assign its metadata to the listener's view. */
            SlookSmartClipMetaTagmetaTag = new
                SlookSmartClipMetaTag(SlookSmartClipMetaTag.TAG_TYPE_URL,
                 “http://www.samsung.com”);

            resultElement.addTag(metaTag);

            /* Have SmartClip make the listener's indirect metadata  and the user-cropped display text available. */
            return SlookSmartClip.DataExtractionListener.EXTRACTION_DEFAULT;
        }
    });
}

Example Code:  Custom View Listener that Makes Indirect Metadata Available and User-cropped Display Text NOT Available:

void init() {
    mSmartClip = new SlookSmartClip(this);

    mSmartClip.setDataExtractionListener(new SlookSmartClip.DataExtractionListener() {

        public int onExtractSmartClipData(View view, SlookSmartClipDataElement resultElement,
                SlookSmartClipCroppedArea arg2) {
           
           /* Do not specify extractDefaultSmartClipData(). */
           
           /* Create a meta-tag and indirectly assign its metadata to the listener's view. */
           resultElement.addTag(new SlookSmartClipMetaTag(
                SlookSmartClipMetaTag.TAG_TYPE_PLAIN_TEXT, "Indirect metadata for custom view B."));
           resultElement.addTag(new SlookSmartClipMetaTag(
                SlookSmartClipMetaTag.TAG_TYPE_URL, "http://www.google.com"));

            return SlookSmartClip.DataExtractionListener.EXTRACTION_DEFAULT;
        }
    });
}

Example Code:  Custom View Listener that Only Makes User-cropped Display Text Available:

void init() {
    mSmartClip = new SlookSmartClip(this);

    mSmartClip.setDataExtractionListener(new SlookSmartClip.DataExtractionListener() {

        public int onExtractSmartClipData(View view, SlookSmartClipDataElement resultElement,
                SlookSmartClipCroppedArea arg2) {
           
           mSmartClip.extractDefaultSmartClipData(resultElement, arg2);

           /* Do not indirectly assign metadata to the listener's view. */
           
            return SlookSmartClip.DataExtractionListener.EXTRACTION_DEFAULT;
        }
    });
}
  • Was this article helpful?