DropHelper per il trascinamento semplificato

La classe DropHelper semplifica l'implementazione delle funzionalità di trascinamento. Membro della libreria Jetpack DragAndDrop, DropHelper fornisce la compatibilità con le versioni precedenti fino al livello API 24.

Usa DropHelper per specificare i target di rilascio, personalizzare l'evidenziazione dei target di rilascio e definire le modalità di gestione dei dati eliminati.

Imposta l'origine del trascinamento

Per iniziare, crea DragStartHelper trascinando la vista origine e OnDragStartListener.

In OnDragStartListener, esegui l'override del metodo onDragStart(). Crea un oggetto ClipData e un oggetto ClipData.Item per i dati da spostare. Come parte di ClipData, fornisci i metadati archiviati in un oggetto ClipDescription all'interno di ClipData. Per un'operazione di trascinamento che non rappresenta lo spostamento di dati, è consigliabile utilizzare null anziché un oggetto reale.

DragStartHelper(draggableView)
    { view: View, _: DragStartHelper ->
        val item = ClipData.Item(view.tag as? CharSequence)
        val dragData = ClipData(
            view.tag as? CharSequence,
            arrayOf(ClipDescription.MIMETYPE_TEXT_PLAIN),
            item
        )
        view.startDragAndDrop(
            dragData,
            View.DragShadowBuilder(view),
            null,
            0
        )
    }.attach()

new DragStartHelper(draggableView, new DragStartHelper.OnDragStartListener() {
    @Override
    public void onDragStart(View view, DragStartHelper helper) {
        CharSequence tag = (CharSequence) view.getTag();
        ClipData.Item item = new ClipData.Item(tag);
        ClipData dragData = new ClipData(
          tag, new String[]{ClipDescription.MIMETYPE_TEXT_PLAIN}, item);
        view.startDragAndDrop(
          dragData, new View.DragShadowBuilder(view), null, 0);
    }
});

Specifica i target di rilascio

Quando un utente rilascia un'ombra su una vista, quest'ultima deve essere configurata correttamente per accettare i dati e rispondere correttamente.

DropHelper.configureView() è un metodo statico e sovraccarico che ti consente di specificare i target di rilascio. I suoi parametri includono:

• L'attuale Activity, utilizzato per le autorizzazioni URI.
  • Una View che funge da target di rilascio.
    • I tipi MIME che la destinazione di rilascio può accettare dai dati eliminati.
• Opzioni di configurazione per la destinazione di lancio, in particolare un elenco di campi EditText incorporati.
• Un elemento OnReceiveContentListener per gestire i dati eliminati.

Ad esempio, per creare una destinazione che accetti le immagini, utilizza una delle seguenti chiamate al metodo:

configureView(
    myActivity,
    targetView,
    arrayOf("image/*"),
    options,
    onReceiveContentListener)

// or

configureView(
    myActivity,
    targetView,
    arrayOf("image/*"),
    onReceiveContentListener)

DropHelper.configureView(
    myActivity,
    targetView,
    new String[] {"image/*"},
    options,
    onReceiveContentlistener);

// or

DropHelper.configureView(
    myActivity,
    targetView,
    new String[] {"image/*"},
    onReceiveContentlistener);

Nella seconda chiamata le opzioni di configurazione della destinazione del rilascio sono omesse, nel qual caso il colore di evidenziazione della destinazione di rilascio è impostato sul colore secondario (o intenso) del tema, il raggio dell'angolo di evidenziazione è impostato su 16 dp e l'elenco di componenti EditText è vuoto. Per informazioni dettagliate, consulta la sezione che segue.

Configura target di rilascio

La classe interna DropHelper.Options consente di configurare le destinazioni di rilascio. Fornisci un'istanza della classe al metodo DropHelper.configureView(Activity, View, String[], Options, OnReceiveContentListener). Per saperne di più, consulta la sezione precedente.

Personalizza l'evidenziazione del target di rilascio

DropHelper configura i rilasci dei target in modo da visualizzare un'evidenziazione quando gli utenti trascinano i contenuti sopra i target. DropHelper fornisce uno stile predefinito e DropHelper.Options consente di impostare il colore dell'evidenziazione e specificare il raggio angolare del rettangolo dell'evidenziazione.

Utilizza la classe DropHelper.Options.Builder per creare un'istanza DropHelper.Options e impostare le opzioni di configurazione, come mostrato nell'esempio seguente:

val options: DropHelper.Options = DropHelper.Options.Builder()
                                      .setHighlightColor(getColor(R.color.purple_300))
                                      .setHighlightCornerRadiusPx(resources.getDimensionPixelSize(R.dimen.drop_target_corner_radius))
                                      .build()

DropHelper.Options options = new DropHelper.Options.Builder()
                                     .setHighlightColor(getColor(R.color.purple_300))
                                     .setHighlightCornerRadiusPx(getResources().getDimensionPixelSize(R.dimen.drop_target_corner_radius))
                                     .build();

Gestire i componenti EditText nelle destinazioni di rilascio

DropHelper controlla anche lo stato attivo all'interno della destinazione di rilascio quando quest'ultima contiene campi di testo modificabili.

Le destinazioni possono essere una singola visualizzazione o una gerarchia di viste. Se la gerarchia della vista della destinazione di rilascio contiene uno o più componenti EditText, fornisci un elenco dei componenti per DropHelper.Options.Builder.addInnerEditTexts(EditText...) per assicurarti che l'evidenziazione della destinazione e la gestione dei dati di testo funzionino correttamente.

DropHelper impedisce che i componenti EditText all'interno della gerarchia della visualizzazione della destinazione di rilascio sottraggano lo stato attivo alla vista contenitore durante le interazioni con il trascinamento.

Inoltre, se il trascinamento ClipData include dati di testo e URI, DropHelper seleziona uno dei componenti EditText nella destinazione del rilascio per gestire i dati di testo. La selezione si basa sul seguente ordine di precedenza:

1. L'elemento EditText in cui viene rilasciato il valore ClipData.
2. EditText che contiene il cursore di testo (accento circonflesso).
3. Il primo elemento EditText fornito alla chiamata a DropHelper.Options.Builder.addInnerEditTexts(EditText...).

Per impostare un EditText come gestore dei dati di testo predefinito, passa EditText come primo argomento della chiamata a DropHelper.Options.Builder.addInnerEditTexts(EditText...). Ad esempio, se la destinazione del lancio gestisce le immagini, ma contiene i campi di testo modificabili T1, T2 e T3, rendi T2 il valore predefinito come segue:

val options: DropHelper.Options = DropHelper.Options.Builder()
                                      .addInnerEditTexts(T2, T1, T3)
                                      .build()

DropHelper.Options options = new DropHelper.Options.Builder()
                                     .addInnerEditTexts(T2, T1, T3)
                                     .build();

Gestire i dati nelle destinazioni di rilascio

Il metodo DropHelper.configureView() accetta un OnReceiveContentListener che crei per gestire i ClipData di trascinamento. I dati di trascinamento vengono forniti al listener in un oggetto ContentInfoCompat. Nell'oggetto sono presenti dati di testo. I contenuti multimediali, come le immagini, sono rappresentati da URI.

L'OnReceiveContentListener gestisce anche i dati forniti alla destinazione di rilascio anche dalle interazioni dell'utente diverse dal trascinamento, ad esempio copia e incolla, quando DropHelper.configureView() viene utilizzato per configurare i seguenti tipi di viste:

• Tutte le visualizzazioni, se l'utente utilizza Android 12 o versioni successive.
• AppCompatEditText, se l'utente utilizza una versione di Android fino ad Android 7.0.

Tipi MIME, autorizzazioni e convalida dei contenuti

Il controllo del tipo MIME da parte di DropHelper si basa sul trascinamento ClipDescription, creato dall'app che fornisce i dati di trascinamento. Convalida ClipDescription per assicurarti che i tipi MIME siano impostati correttamente.

DropHelper richiede tutte le autorizzazioni di accesso per gli URI dei contenuti contenuti nella funzionalità ClipData di trascinamento. Per maggiori informazioni, consulta DragAndDropPermissions. Le autorizzazioni consentono di risolvere gli URI dei contenuti durante l'elaborazione dei dati di trascinamento.

DropHelper non convalida i dati restituiti dai fornitori di contenuti durante la risoluzione degli URI nei dati eliminati. Controllate che non ci siano valori nulli e verificate la correttezza di tutti i dati risolti.