Crea un'app per scrivere note

L'aggiunta di note è una funzionalità di base di Android che migliora la produttività degli utenti sui dispositivi con schermi di grandi dimensioni. Le app per la creazione di note consentono agli utenti di scrivere e disegnare in una finestra mobile o a schermo intero, acquisire e annotare i contenuti dello schermo e salvare note per la revisione e la revisione successive.

Gli utenti possono accedere alle app per creare note dalla schermata di blocco o mentre eseguono altre app.

Il supporto dello stilo per l'aggiunta di note offre un'esperienza utente eccezionale.

Ruolo Note

Il ruolo RoleManager.ROLE_NOTES identifica le app per prendere appunti e concede loro l'autorizzazione LAUNCH_CAPTURE_CONTENT_ACTIVITY_FOR_NOTE.

Per acquisire il ruolo per le note per la tua app:

1. Chiama isRoleAvailable() per controllare lo stato del ruolo.
2. Se è disponibile il ruolo per le note, chiama createRequestRoleIntent() per ottenere un intent specifico per le note.
3. Chiama startActivityForResult() con l'intento di chiedere all'utente di concedere il ruolo Note alla tua app.

Solo un'app può possedere il ruolo per le note.

L'app si apre in risposta a un'azione dell'intent ACTION_CREATE_NOTE implicita. Se richiamata dalla schermata di blocco del dispositivo, l'app si apre a schermo intero; se richiamata mentre lo schermo è sbloccato, in una finestra mobile.

Nota: nelle impostazioni di sistema, gli utenti possono disattivare un'app predefinita per la creazione di note, nel qual caso nessuna app risponde all'ACTION_CREATE_NOTE azione intent.

File manifest dell'app

Per avere diritto al ruolo Note, la tua app deve includere la seguente dichiarazione nel file manifest dell'app:

<activity
    android:name="YourActivityName"
    android:exported="true"
    android:showWhenLocked="true"
    android:turnScreenOn="true">
    <intent-filter>
        <action android:name="android.intent.action.CREATE_NOTE" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

La dichiarazione consente agli utenti di assegnare il ruolo per le note alla tua app, rendendola l'applicazione predefinita per l'aggiunta di note:

• ACTION_CREATE_NOTE imposta l'azione intent a cui risponde l'app

• showWhenLocked rende l'app accessibile dalla schermata di blocco del dispositivo

• turnScreenOn consente all'app di attivare lo schermo del dispositivo quando l'app è in esecuzione

Funzionalità dell'app

Un'app per la creazione di note differenziata su ampio schermo offre una serie completa di funzionalità per la creazione di note.

Supporto per stilo

Quando la tua app viene richiamata con l'intent extra EXTRA_USE_STYLUS_MODE impostato su true, l'app dovrebbe aprire una nota che accetta l'input dello stilo (o del tocco delle dita).

Se l'intent aggiuntivo è impostato su false, la tua app dovrebbe aprire una nota che accetta l'input da tastiera.

Accesso alla schermata di blocco

L'app deve fornire un'attività a schermo intero che viene eseguita quando viene aperta dalla schermata di blocco del dispositivo.

L'app dovrebbe mostrare le note storiche solo se l'utente ha acconsentito (nello stato del dispositivo sbloccato) a mostrare le note precedenti. Altrimenti, quando viene aperta dalla schermata di blocco, l'app dovrebbe sempre creare una nuova nota.

Puoi controllare se la tua app è stata avviata dalla schermata di blocco con KeyguardManager#isKeyguardLocked(). Per chiedere all'utente di autenticare e sbloccare il dispositivo, chiama KeyguardManager#requestDismissKeyguard():

Kotlin

val keyguardManager = getSystemService(KEYGUARD_SERVICE) as KeyguardManager

keyguardManager.requestDismissKeyguard(
    this,
    object : KeyguardDismissCallback() {

    override fun onDismissError() {
        // Unlock failed. Dismissing keyguard is not feasible.
    }

    override fun onDismissSucceeded() {
        // Unlock succeeded. Device is now unlocked.
    }

    override fun onDismissCancelled() {
        // Unlock failed. User cancelled operation or request otherwise cancelled.
    }
})

Java

KeyguardManager keyguardManager = (KeyguardManager) getSystemService(KEYGUARD_SERVICE);

boolean isLocked = keyguardManager.isKeyguardLocked();

keyguardManager.requestDismissKeyguard(
    this,
    new KeyguardManager.KeyguardDismissCallback() {

  @Override
  public void onDismissError() {
      // Unlock failed. Dismissing keyguard is not feasible.
  }

  @Override
  public void onDismissSucceeded() {
      // Unlock succeeded. Device is now unlocked.
  }

  @Override
  public void onDismissCancelled() {
      // Unlock failed. User cancelled operation or request otherwise cancelled.
  }
});

Avviso: se avviata dalla schermata di blocco del dispositivo, l'app deve garantire la privacy dell'utente.

Finestre mobili

Per la creazione di note contestuali, l'app deve fornire un'attività che si apre in una finestra mobile quando è in esecuzione un'altra applicazione.

La tua app dovrebbe supportare la modalità multi-instance in modo che gli utenti possano creare più note in più finestre mobili anche quando l'app per creare note viene avviata a schermo intero o in modalità schermo diviso.

Acquisizione dei contenuti

L'acquisizione di contenuti è una funzionalità chiave delle app per prendere appunti. Con l'acquisizione di contenuti, gli utenti possono acquisire screenshot del display dietro la finestra mobile dell'app per scrivere note. Gli utenti possono acquisire parzialmente o interamente il display, incollare il contenuto nella nota e annotare o evidenziare i contenuti acquisiti.

L'app per prendere appunti deve fornire un'offerta dell'interfaccia utente che avvia un elemento ActivityResultLauncher creato da registerForActivityResult(). L'azione dell'intent ACTION_LAUNCH_CAPTURE_CONTENT_ACTIVITY_FOR_NOTE viene fornita ad Avvio app direttamente o tramite un ActivityResultContract.

Un'attività di sistema acquisisce i contenuti, li salva sul dispositivo e restituisce l'URI dei contenuti alla tua app nell'argomento callback di registerForActivityResult().

L'esempio seguente utilizza un contratto StartActivityForResult generico:

Kotlin

private val startForResult = registerForActivityResult(
    ActivityResultContracts.StartActivityForResult()) {
        result: ActivityResult ->
            if (result.resultCode == Intent.CAPTURE_CONTENT_FOR_NOTE_SUCCESS) {
                val uri = result.data?.data
                // Use the URI to paste the captured content into the note.
            }
    }

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContent {
        NotesTheme {
            Surface(color = MaterialTheme.colorScheme.background) {
                CaptureButton(
                    onClick = {
                        Log.i("ContentCapture", "Launching intent...")
                        startForResult.launch(Intent(ACTION_LAUNCH_CAPTURE_CONTENT_ACTIVITY_FOR_NOTE))
                    })
            }
        }
    }
}

@Composable
fun CaptureButton(onClick: () -> Unit) {
    Button(onClick = onClick)
    {Text("Capture Content")}
}

Java

private final ActivityResultLauncher<Intent> startForResult = registerForActivityResult(
    new ActivityResultContracts.StartActivityForResult(),
    result -> {
        if (result.getResultCode() == Intent.CAPTURE_CONTENT_FOR_NOTE_SUCCESS) {
            Uri uri = result.getData() != null ? result.getData().getData() : null;
            // Use the URI to paste the captured content into the note.
        }
    });

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

    Button captureButton = findViewById(R.id.capture_button);

    captureButton.setOnClickListener(
        view -> {
            Log.i("ContentCapture", "Launching intent...");
            startForResult.launch(new Intent(ACTION_LAUNCH_CAPTURE_CONTENT_ACTIVITY_FOR_NOTE));
        });
}

L'app deve gestire tutti i codici risultato:

• CAPTURE_CONTENT_FOR_NOTE_SUCCESS
• CAPTURE_CONTENT_FOR_NOTE_FAILED
• CAPTURE_CONTENT_FOR_NOTE_USER_CANCELED
• CAPTURE_CONTENT_FOR_NOTE_WINDOW_MODE_UNSUPPORTED
• CAPTURE_CONTENT_FOR_NOTE_BLOCKED_BY_ADMIN

Una volta completata l'acquisizione dei contenuti, incolla l'immagine acquisita nella nota, ad esempio:

Kotlin

registerForActivityResult(ActivityResultContracts.StartActivityForResult()) {
    result: ActivityResult ->
        if (result.resultCode == Intent.CAPTURE_CONTENT_FOR_NOTE_SUCCESS) {
            val uri = result.data?data
            // Use the URI to paste the captured content into the note.
        }
}

Java

registerForActivityResult(new ActivityResultContracts.StartActivityForResult(),
    result -> {
        if (result.getResultCode() == Intent.CAPTURE_CONTENT_FOR_NOTE_SUCCESS) {
            Uri uri = result.getData() != null ? result.getData().getData() : null;
            // Use the URI to paste the captured content into the note.
        }
    });

La funzionalità di acquisizione dei contenuti deve essere esposta tramite un'offerta dell'interfaccia utente solo quando l'app di creazione di note è in esecuzione in una finestra mobile, non quando è in esecuzione a schermo intero e viene avviata dalla schermata di blocco del dispositivo. Gli utenti possono acquisire screenshot dell'app stessa per creare note con funzionalità di screenshot del dispositivo.

Per determinare se la tua app si trova in una finestra mobile (o in una bolla), chiama i metodi seguenti:

• isLaunchedFromBubble() per verificare che l'app per creare note non sia stata avviata a schermo intero dalla schermata di blocco del dispositivo
• isRoleHeld(RoleManager.ROLE_NOTES) per verificare che la tua app sia l'app predefinita per la creazione di note (l'app può essere eseguita in una conversazione o in un altro tipo di fumetto se l'app non ha il ruolo Note)

Nota: la tua app deve controllare se l'acquisizione di contenuti è consentita dai criteri di amministrazione del dispositivo. Chiama getScreenCaptureDisabled() con null come argomento.

Risorse aggiuntive

• Ottenere un risultato da un'attività