What exactly is "label" parameter in ClipData in Android?

According to the Android documentation, ClipData use "label" as a kind of representation to the copied data.

> ClippedData is a complex type containing one or Item instances, each of which can hold one or more representations of an item of data. For display to the user, it also has a label and iconic representation.

And then it further explains "label" as User-visible label for the clip data in some API docs. However, I'm still confused about the usage of the label.

How is this label visible to users? How should I use it? What should I set for this label when I call the ClipData factory method newPlainText(CharSequence label, CharSequence text)? for example:

private void copyToClipBoard() {

    ClipboardManager clipboard = (ClipboardManager) getSystemService(CLIPBOARD_SERVICE);
    ClipData clip = ClipData.newPlainText(
            "text label", // What should I set for this "label"?
            "content to be copied");
    clipboard.setPrimaryClip(clip);
    Toast.makeText(AboutActivity.this, "Saved to clip board", Toast.LENGTH_SHORT).show();
}

ClipData clip = ClipData.newPlainText(
            "text label", 
            "content to be copied");

here text label describes what data is in clip

eg.

ClipData clip = ClipData.newPlainText(
            "user Name",
            user.getName()); 

we can retrive this by using

clip.getDescription ();

It seems like the "User-visible label for the clip data" description in the documentation should be interpreted as something you as a developer can set and then show to the user yourself and not as something that the Android system will show to the user.

When looking at the Android source code the ClipDescription.getLabel() method seems to be unused before Android 5.0. In 5.0 RemoteInput, RemoteInputCompatJellybean and com.android.mail.compose.ComposeActivity stated using the method.

If you look at the usage all these set a label that is not meant to be seen by the user but instead used to programatically identify the clip at a different place in the code.

When looking at how ClipData.newPlainText() is used within Android, most of the time null is given as label, suggesting the label is not really used for anything.

It is of course possible that some phone manufacturer or some other app developer takes the label and displays it to the user in some situation. But in general it should be safe to assume that the label of a clip will only be shown to the user in your app if you show it yourself.

Today while working on my app I discovered one use case for ClipData label. Some apps set it to null while other apps use it pretty much.

In the case of my app I am listening to the ClipManager's addPrimaryClipChangedListener

I am doing this in a service class that runs in the background almost all the time. I want to treat data added to the primaryClip from within my app different from data added in another app (lets say text copied in a web browser).

Here is an extract of my code and how I am using ClipData label:

mClipBoardManager.addPrimaryClipChangedListener(new ClipboardManager.OnPrimaryClipChangedListener() {
            @Override
            public void onPrimaryClipChanged() {
                String clipLabel = "default";
                if (mClipBoardManager.getPrimaryClip().getDescription().getLabel() != null) {
                    clipLabel = mClipBoardManager.getPrimaryClip().getDescription().getLabel().toString();
                }
                if (clipLabel.equals("auto_copy_text")) {
                    //TODO: Text from my app do stuffs you will do with text from my app
                } else {
                    //TODO: Text from some other app
                }

            }
        });

In my app when I am adding data to primaryClip I include the label like this:

private void addToClipboard(String text) {
        mClipboardManager = (ClipboardManager) getSystemService(CLIPBOARD_SERVICE);
        mClipboardManager.setPrimaryClip(ClipData.newPlainText("auto_copy_text", text));
    }

I hope this helps

One more thing I noticed is that if users copy data with the same label again then previous text with the same label will be overwritten. So one label can keep only one copy of data & will be helpful in clearing the previous clutter. Also label can be used for identifying your unique text & can be used to retrieve your text data even if its the not last thing user copied.