reis-mobile 0.3.6 → 0.4.0

package/skills/android-display-glasses-with-jetpack-compose-glimmer/references/android/develop/xr/jetpack-xr-sdk/request-hardware-permissions.md

@@ -0,0 +1,213 @@
+Applicable XR devices This guidance helps you build experiences for these types of XR devices. [Learn about XR device types →](https://developer.android.com/develop/xr/devices) ![](https://developer.android.com/static/images/develop/xr/ai-glasses-icon.svg) Audio \&  
+Display Glasses [](https://developer.android.com/develop/xr/devices#audio-display) [Learn about XR device types →](https://developer.android.com/develop/xr/devices)
+
+<br />
+
+Just like on a phone, accessing sensitive hardware like the camera and
+microphone on audio glasses and display glasses requires explicit user consent.
+These are considered
+**glasses-specific permissions**, and your app must request them at runtime,
+even if it already has the corresponding permissions on the phone.
+
+## Declare the permissions in your app's manifest
+
+Before requesting permissions, you must [declare them in your app's manifest](https://developer.android.com/training/permissions/declaring)
+file using the [`<uses-permission>`](https://developer.android.com/guide/topics/manifest/uses-permission-element) element. This declaration remains the
+same whether the permission is for a phone or a glasses-specific feature, but
+you must still explicitly request it for glasses-specific hardware or
+functionality.
+
+    <manifest ...>
+        <!-- Only declare permissions that your app actually needs. In this example,
+        we declare permissions for the camera. -->
+        <uses-permission android:name="android.permission.CAMERA"/>
+        <application ...>
+            ...
+        </application>
+    </manifest>
+
+## Before requesting glasses permissions
+
+Review the [permission principles and workflows](https://developer.android.com/training/permissions/requesting#principles) to make sure you provide the
+best experience for your users, like [checking whether the user has already
+granted the runtime permissions](https://developer.android.com/training/permissions/requesting#already-granted) your app requires and [whether your app
+should show a rationale](https://developer.android.com/training/permissions/requesting#explain) to the user before requesting glasses-specific
+permissions.
+
+## Permission scenarios
+
+There are different scenarios you might encounter when requesting [dangerous
+runtime permissions](https://developer.android.com/guide/topics/permissions/requesting#normal-dangerous) on audio and display glasses:
+
+- Request runtime permissions from a projected activity
+- Request runtime permissions from a phone activity
+
+See the following sections in this guide for details about each scenario.
+
+### Request and handle runtime permissions from a projected activity
+
+To request permissions for audio glasses and display glasses, first use the
+[`ActivityResultLauncher`](https://developer.android.com/reference/kotlin/androidx/activity/result/ActivityResultLauncher) with the
+[`ProjectedPermissionsResultContract`](https://developer.android.com/reference/kotlin/androidx/xr/projected/permissions/ProjectedPermissionsResultContract#ProjectedPermissionsResultContract()) method to register the permissions
+launcher. When the user has acted on the permission request, the callback
+receives a map of permission names to their granted status.
+
+
+```kotlin
+// Register the permissions launcher using the ProjectedPermissionsResultContract.
+private val requestPermissionLauncher: ActivityResultLauncher<List<ProjectedPermissionsRequestParams>> =
+    registerForActivityResult(ProjectedPermissionsResultContract()) { results ->
+        if (results[Manifest.permission.CAMERA] == true) {
+            isPermissionDenied = false
+            initializeGlassesFeatures()
+        } else {
+            // Handle permission denial.
+            isPermissionDenied = true
+        }
+    }
+```
+
+<br />
+
+#### Key points about the code
+
+- You need to specify which permissions your app requires, such as [`Manifest.permission.CAMERA`](https://developer.android.com/reference/kotlin/android/Manifest.permission#camera) or [`Manifest.permission.RECORD_AUDIO`](https://developer.android.com/reference/kotlin/android/Manifest.permission#record_audio).
+- Your app should handle both granted and denied results gracefully in the launcher's callback.
+
+To trigger the permission request flow, pass a list of
+[`ProjectedPermissionsRequestParams`](https://developer.android.com/reference/kotlin/androidx/xr/projected/permissions/ProjectedPermissionsRequestParams) to your registered permission
+launcher's `launch` method. The `ProjectedPermissionsRequestParams` object
+bundles the requested manifest permissions together with a custom `rationale`
+string. The `rationale` string must clearly and concisely explain why the app
+requires access to the glasses' hardware features (such as the camera or
+microphone).
+
+
+```kotlin
+private fun requestHardwarePermissions() {
+    val params = ProjectedPermissionsRequestParams(
+        permissions = listOf(Manifest.permission.CAMERA),
+        rationale = "Camera access is required to overlay digital content on your physical environment."
+    )
+    requestPermissionLauncher.launch(listOf(params))
+}
+```
+
+<br />
+
+#### Key points about the code
+
+- Calling `launch` on the launcher triggers the [permission request user
+  flow](https://developer.android.com/develop/xr/jetpack-xr-sdk/request-hardware-permissions#permissions-user-flow).
+
+#### Understand the permission request user flow
+
+When you launch a permission request using the
+[`ProjectedPermissionsResultContract`](https://developer.android.com/reference/kotlin/androidx/xr/projected/permissions/ProjectedPermissionsResultContract#ProjectedPermissionsResultContract()) method, the system initiates a
+coordinated user flow across both the glasses and the phone.
+
+During the permissions user flow, here is what your app and the user can expect:
+
+1. **On the glasses** : An activity appears on the **projected device
+   (glasses)**, instructing the user to look at their phone to continue.
+
+   <br />
+
+   > [!WARNING]
+   > **Preview:** Currently, the instructions and rationale provided by the system are not audible to the user. To provide an audible rationale to the user, we recommend using [Text to Speech
+   > (TTS)](https://developer.android.com/develop/xr/jetpack-xr-sdk/tts). For example:
+   >
+   > <br />
+   >
+   >     tts?.speak("Please review the permission request on your host device",
+   >     TextToSpeech.QUEUE_ADD,
+   >     null,
+   >     "permission_request")
+   >
+   > <br />
+   >
+   <br />
+
+2. **On the phone** : Concurrently, an activity launches on the **host device
+   (phone)**. This screen displays the rationale string you provided and gives
+   the user the option to proceed or cancel.
+
+3. **On the phone** : If the user accepts the rationale, a modified Android
+   system permission dialog appears on the phone telling the user that they are
+   granting the permission **for the glasses** (not the phone), and the user
+   can formally grant or deny the permission.
+
+4. **Receiving the result** : After the user makes their final choice, the
+   activities on both the phone and glasses are dismissed. Your
+   [`ActivityResultLauncher`](https://developer.android.com/reference/kotlin/androidx/activity/result/ActivityResultLauncher) callback is then invoked with a map
+   containing the granted status for each requested permission.
+
+### Request runtime permissions in a phone activity
+
+If your app is running in a phone activity but requires permissions for audio or
+display glasses---for example, to let a user switch a video stream to the glasses'
+camera for a first-person point of view---request the permissions using the
+device-specific [`Activity#requestPermissions(permissions, requestCode,
+deviceId)`](https://developer.android.com/reference/kotlin/android/app/Activity#requestpermissions_1) method.
+
+To target audio and display glasses, obtain the appropriate device ID by calling
+[`getDeviceId`](https://developer.android.com/reference/kotlin/android/content/Context#getdeviceid) on a projected device context. Pass this ID when requesting
+permissions from your phone activity, as shown in the following example:
+
+
+```kotlin
+// Request the projected permission from phone activity
+requestPermissions(
+    arrayOf(Manifest.permission.CAMERA),
+    // REQUEST_CODE_GLASSES_CAMERA is a developer-defined constant
+    REQUEST_CODE_GLASSES_CAMERA,
+    projectedDeviceId
+)
+```
+
+<br />
+
+#### Handle the permission results
+
+Once the user responds to the permission dialog on the phone, their decision is
+delivered to your app by invoking the onRequestPermissionsResult callback.
+
+To handle the response, override [`onRequestPermissionsResult`](https://developer.android.com/reference/kotlin/androidx/core/app/ActivityCompat.OnRequestPermissionsResultCallback#onRequestPermissionsResult(int,java.lang.String%5B%5D,int%5B%5D)) within the
+`Activity` instance that initiated the permission request.
+
+The following code snippet shows how to handle the callback and verify whether
+the user granted the requested permissions:
+
+
+```kotlin
+private companion object {
+    // REQUEST_CODE_GLASSES_CAMERA is a developer-defined constant.
+    const val REQUEST_CODE_GLASSES_CAMERA = 1001
+}
+
+@RequiresApi(Build.VERSION_CODES.VANILLA_ICE_CREAM)
+override fun onRequestPermissionsResult(
+    requestCode: Int,
+    permissions: Array<out String>,
+    grantResults: IntArray,
+    deviceId: Int
+) {
+    super.onRequestPermissionsResult(requestCode, permissions, grantResults, deviceId)
+
+    // Handle the result of the permission request
+    if (requestCode == REQUEST_CODE_GLASSES_CAMERA && deviceId == projectedDeviceId) {
+        if (grantResults.isNotEmpty() && grantResults[0] == PackageManager.PERMISSION_GRANTED) {
+            // Proceed with glasses camera features
+        } else {
+            // Handle glasses permission denied
+        }
+    }
+}
+```
+
+<br />
+
+##### Key points about the code
+
+- Use the `deviceId` overload with the `onRequestPermissionsResult` callback to ensure the permission status is correctly mapped to the specific context, such as the audio or display glasses rather than the host phone.
+- Your app should handle both granted and denied results gracefully.

package/skills/android-display-glasses-with-jetpack-compose-glimmer/references/button-samples-source.md

@@ -0,0 +1,176 @@
+When creating a Glimmer Button component, refer to the following implementation
+samples in `ButtonSamples.kt`:
+
+
+```kotlin
+/*
+ * Copyright 2025 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package androidx.xr.glimmer.samples
+
+import androidx.annotation.Sampled
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.wrapContentSize
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.tooling.preview.Preview
+import androidx.xr.glimmer.Button
+import androidx.xr.glimmer.ButtonSize
+import androidx.xr.glimmer.GlimmerTheme
+import androidx.xr.glimmer.Icon
+import androidx.xr.glimmer.Text
+import androidx.xr.glimmer.list.GlimmerLazyColumn
+
+@Composable
+fun ButtonSampleUsage() {
+    GlimmerLazyColumn(
+        horizontalAlignment = Alignment.CenterHorizontally,
+        modifier = Modifier.fillMaxSize().wrapContentSize(Alignment.Center),
+    ) {
+        item { ButtonSample() }
+        item { ButtonWithLeadingIconSample() }
+        item { ButtonWithTrailingIconSample() }
+        item { ButtonWithLeadingAndTrailingIconSample() }
+        item { LargeButtonSample() }
+        item { LargeButtonWithLeadingIconSample() }
+        item { LargeButtonWithTrailingIconSample() }
+        item { LargeButtonWithLeadingAndTrailingIconSample() }
+    }
+}
+
+@Sampled
+@Composable
+fun ButtonSample() {
+    Button(onClick = {}) { Text("Send") }
+}
+
+@Sampled
+@Composable
+fun ButtonWithLeadingIconSample() {
+    Button(onClick = {}, leadingIcon = { Icon(FavoriteIcon, "Localized description") }) {
+        Text("Send")
+    }
+}
+
+@Composable
+private fun ButtonWithTrailingIconSample() {
+    Button(onClick = {}, trailingIcon = { Icon(FavoriteIcon, "Localized description") }) {
+        Text("Send")
+    }
+}
+
+@Composable
+private fun ButtonWithLeadingAndTrailingIconSample() {
+    Button(
+        onClick = {},
+        leadingIcon = { Icon(FavoriteIcon, "Localized description") },
+        trailingIcon = { Icon(FavoriteIcon, "Localized description") },
+    ) {
+        Text("Send")
+    }
+}
+
+@Sampled
+@Composable
+fun LargeButtonSample() {
+    Button(onClick = {}, buttonSize = ButtonSize.Large) { Text("Send") }
+}
+
+@Composable
+private fun LargeButtonWithLeadingIconSample() {
+    Button(
+        onClick = {},
+        buttonSize = ButtonSize.Large,
+        leadingIcon = { Icon(FavoriteIcon, "Localized description") },
+    ) {
+        Text("Send")
+    }
+}
+
+@Composable
+private fun LargeButtonWithTrailingIconSample() {
+    Button(
+        onClick = {},
+        buttonSize = ButtonSize.Large,
+        trailingIcon = { Icon(FavoriteIcon, "Localized description") },
+    ) {
+        Text("Send")
+    }
+}
+
+@Composable
+private fun LargeButtonWithLeadingAndTrailingIconSample() {
+    Button(
+        onClick = {},
+        buttonSize = ButtonSize.Large,
+        leadingIcon = { Icon(FavoriteIcon, "Localized description") },
+        trailingIcon = { Icon(FavoriteIcon, "Localized description") },
+    ) {
+        Text("Send")
+    }
+}
+
+@Preview
+@Composable
+private fun ButtonPreview() {
+    GlimmerTheme { ButtonSample() }
+}
+
+@Preview
+@Composable
+private fun ButtonWithLeadingIconPreview() {
+    GlimmerTheme { ButtonWithLeadingIconSample() }
+}
+
+@Preview
+@Composable
+private fun ButtonWithTrailingIconPreview() {
+    GlimmerTheme { ButtonWithTrailingIconSample() }
+}
+
+@Preview
+@Composable
+private fun ButtonWithLeadingAndTrailingIconPreview() {
+    GlimmerTheme { ButtonWithLeadingAndTrailingIconSample() }
+}
+
+@Preview
+@Composable
+private fun LargeButtonPreview() {
+    GlimmerTheme { LargeButtonSample() }
+}
+
+@Preview
+@Composable
+private fun LargeButtonWithLeadingIconPreview() {
+    GlimmerTheme { LargeButtonWithLeadingIconSample() }
+}
+
+@Preview
+@Composable
+private fun LargeButtonWithTrailingIconPreview() {
+    GlimmerTheme { LargeButtonWithTrailingIconSample() }
+}
+
+@Preview
+@Composable
+private fun LargeButtonWithLeadingAndTrailingIconPreview() {
+    GlimmerTheme { LargeButtonWithLeadingAndTrailingIconSample() }
+}
+```
+
+<br />

package/skills/android-display-glasses-with-jetpack-compose-glimmer/references/button-source.md

@@ -0,0 +1,203 @@
+When creating a Glimmer Button component, refer to the following source code in
+`Button.kt`:
+
+
+```kotlin
+/*
+ * Copyright 2025 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package androidx.xr.glimmer
+
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.interaction.MutableInteractionSource
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.PaddingValues
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.RowScope
+import androidx.compose.foundation.layout.defaultMinSize
+import androidx.compose.foundation.layout.padding
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.CompositionLocalProvider
+import androidx.compose.runtime.Immutable
+import androidx.compose.runtime.remember
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.graphics.Shape
+import androidx.compose.ui.semantics.Role
+import androidx.compose.ui.semantics.role
+import androidx.compose.ui.semantics.semantics
+import androidx.compose.ui.unit.Dp
+import androidx.compose.ui.unit.dp
+
+/**
+ * Button is a component used for exposing actions to a user.
+ *
+ * @sample androidx.xr.glimmer.samples.ButtonSample
+ *
+ * Buttons can use icons to provide more context about the action:
+ *
+ * @sample androidx.xr.glimmer.samples.ButtonWithLeadingIconSample
+ *
+ * There are multiple button size variants - providing a different [ButtonSize] will affect default
+ * values used inside this button, such as the minimum height. Note that you can still provide a
+ * size modifier such as [androidx.compose.foundation.layout.size] to change the layout size of this
+ * button, [buttonSize] affects default values and values internal to the button.
+ *
+ * @sample androidx.xr.glimmer.samples.LargeButtonSample
+ * @param onClick called when this button is clicked
+ * @param modifier the [Modifier] to be applied to this button
+ * @param enabled controls the enabled state of this button. When `false`, this button will not
+ *   respond to user input
+ * @param buttonSize the size variant of this button, represented as a [ButtonSize]. Changing
+ *   [buttonSize] will affect some default values used by this button - but the final resulting size
+ *   of the button will still be calculated based on the content of the button, and any provided
+ *   size modifiers such as [androidx.compose.foundation.layout.size]. For example, setting a 100.dp
+ *   size using a size modifier will result in the same layout size regardless of [buttonSize], but
+ *   the provided [buttonSize] will affect other properties such as padding values and the size of
+ *   icons.
+ * @param leadingIcon optional leading icon to be placed before the [content]. This is typically an
+ *   [Icon] tinted with [contentColor] by default.
+ * @param trailingIcon optional trailing icon to be placed after the [content]. This is typically an
+ *   [Icon] tinted with [contentColor] by default.
+ * @param shape the [Shape] used to clip this button, and also used to draw the background and
+ *   border
+ * @param color background color of this button
+ * @param contentColor content color used by components inside [content], [leadingIcon], and
+ *   [trailingIcon].
+ * @param contentPadding the spacing values to apply internally between the container and the
+ *   content
+ * @param interactionSource an optional hoisted [MutableInteractionSource] for observing and
+ *   emitting Interactions for this button. You can use this to change the button's appearance or
+ *   preview the button in different states. Note that if `null` is provided, interactions will
+ *   still happen internally.
+ * @param content the main content, typically [Text], to display inside this button
+ */
+@Composable
+public fun Button(
+    onClick: () -> Unit,
+    modifier: Modifier = Modifier,
+    enabled: Boolean = true,
+    buttonSize: ButtonSize = ButtonSize.Medium,
+    leadingIcon: @Composable (() -> Unit)? = null,
+    trailingIcon: @Composable (() -> Unit)? = null,
+    shape: Shape = GlimmerTheme.shapes.large,
+    color: Color = GlimmerTheme.colors.surface,
+    contentColor: Color = calculateContentColor(color),
+    contentPadding: PaddingValues = ButtonDefaults.contentPadding(buttonSize),
+    interactionSource: MutableInteractionSource? = null,
+    content: @Composable RowScope.() -> Unit,
+) {
+    val iconSize = ButtonDefaults.iconSize
+    val iconSpacing = ButtonDefaults.iconSpacing
+    val minHeight = ButtonDefaults.minimumHeight(buttonSize)
+
+    val internalInteractionSource = interactionSource ?: remember { MutableInteractionSource() }
+
+    CompositionLocalProvider(LocalTextStyle provides GlimmerTheme.typography.bodySmall) {
+        Row(
+            modifier
+                .semantics { role = Role.Button }
+                .surface(
+                    enabled = enabled,
+                    shape = shape,
+                    color = color,
+                    contentColor = contentColor,
+                    depthEffect = null,
+                    interactionSource = internalInteractionSource,
+                )
+                .clickable(
+                    enabled = enabled,
+                    interactionSource = internalInteractionSource,
+                    onClick = onClick,
+                )
+                .defaultMinSize(minHeight = minHeight)
+                .padding(contentPadding),
+            horizontalArrangement = Arrangement.Center,
+            verticalAlignment = Alignment.CenterVertically,
+        ) {
+            if (leadingIcon != null) {
+                Box(Modifier.padding(end = iconSpacing)) {
+                    CompositionLocalProvider(LocalIconSize provides iconSize, content = leadingIcon)
+                }
+            }
+            content()
+            if (trailingIcon != null) {
+                Box(Modifier.padding(start = iconSpacing)) {
+                    CompositionLocalProvider(
+                        LocalIconSize provides iconSize,
+                        content = trailingIcon,
+                    )
+                }
+            }
+        }
+    }
+}
+
+/**
+ * ButtonSize represents the different size variants of a [Button]. ButtonSize will affect default
+ * values used inside a [Button], such as the minimum height and the size of icons.
+ */
+@Immutable
+@JvmInline
+public value class ButtonSize internal constructor(private val value: Int) {
+    public companion object {
+        /** ButtonSize representing a medium [Button]. This is the default size. */
+        public val Medium: ButtonSize = ButtonSize(1)
+        /** ButtonSize representing a large [Button]. */
+        public val Large: ButtonSize = ButtonSize(2)
+    }
+}
+
+/** Default values used for [Button]. */
+public object ButtonDefaults {
+    /** Default content padding used for a [Button] with the specified [buttonSize]. */
+    @Composable
+    public fun contentPadding(buttonSize: ButtonSize): PaddingValues {
+        val componentSpacingValues = GlimmerTheme.componentSpacingValues
+        return if (buttonSize == ButtonSize.Medium) {
+            PaddingValues(
+                horizontal = componentSpacingValues.large,
+                vertical = componentSpacingValues.small,
+            )
+        } else {
+            PaddingValues(componentSpacingValues.large)
+        }
+    }
+
+    /** Default minimum height for [Button] and [ToggleButton] with the specified [buttonSize]. */
+    internal fun minimumHeight(buttonSize: ButtonSize): Dp {
+        return when (buttonSize) {
+            ButtonSize.Medium -> 48.dp
+            ButtonSize.Large -> 72.dp
+            else -> throw IllegalArgumentException("Unknown size $buttonSize.")
+        }
+    }
+
+    /** Default icon size for buttons with non-icon content: [Button], [ToggleButton]. */
+    @get:Composable
+    internal val iconSize: Dp
+        get() = GlimmerTheme.iconSizes.small
+
+    /** Default spacing between icon and content for [Button] and [ToggleButton]. */
+    @get:Composable
+    internal val iconSpacing: Dp
+        get() = GlimmerTheme.componentSpacingValues.extraSmall
+}
+```
+
+<br />