1 /* 2 * Copyright (C) 2024 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 package com.android.internal.widget.remotecompose.core.semantics; 17 18 import android.annotation.Nullable; 19 20 /** 21 * Interface representing an accessible component in the UI. This interface defines properties and 22 * methods related to accessibility semantics for a component. It extends the {@link 23 * AccessibilitySemantics} interface to inherit semantic properties. 24 * 25 * <p>This is similar to {@link CoreSemantics} but handles built in operations that also expose 26 * those core semantics. 27 */ 28 public interface AccessibleComponent extends AccessibilitySemantics { 29 /** 30 * Returns the ID of the content description for this item. 31 * 32 * <p>The content description is used to provide textual information about the item to 33 * accessibility services, such as screen readers. This allows users with visual impairments to 34 * understand the purpose and content of the item. 35 * 36 * <p>This is similar to AccessibilityNodeInfo.getContentDescription(). 37 * 38 * @return The ID of a RemoteString for the content description, or null if no content 39 * description is provided. 40 */ getContentDescriptionId()41 default @Nullable Integer getContentDescriptionId() { 42 return null; 43 } 44 45 /** 46 * Gets the text ID associated with this object. 47 * 48 * <p>This method is intended to be overridden by subclasses that need to associate a specific 49 * text ID with themselves. The default implementation returns null, indicating that no text ID 50 * is associated with the object. 51 * 52 * <p>This is similar to AccessibilityNodeInfo.getText(). 53 * 54 * @return The text ID, or null if no text ID is associated with this object. 55 */ getTextId()56 default @Nullable Integer getTextId() { 57 return null; 58 } 59 60 /** 61 * Retrieves the role associated with this object. The enum type deliberately matches the 62 * Compose Role. In the platform it will be applied as ROLE_DESCRIPTION_KEY. 63 * 64 * <p>The default implementation returns {@code null}, indicating that no role is assigned. 65 * 66 * @return The role associated with this object, or {@code null} if no role is assigned. 67 */ getRole()68 default @Nullable Role getRole() { 69 return null; 70 } 71 72 /** 73 * Checks if the element is clickable. 74 * 75 * <p>By default, elements are not considered clickable. Subclasses should override this method 76 * to indicate clickability based on their specific properties and behavior. 77 * 78 * <p>This is similar to AccessibilityNodeInfo.isClickable(). 79 * 80 * @return {@code true} if the element is clickable, {@code false} otherwise. 81 */ isClickable()82 default boolean isClickable() { 83 return false; 84 } 85 86 /** 87 * Gets the merge mode of the operation. 88 * 89 * <p>The mode indicates the type of operation being performed. By default it returns {@link 90 * CoreSemantics.Mode#SET}, indicating a "set" operation. 91 * 92 * <p>{@link CoreSemantics.Mode#CLEAR_AND_SET} matches a Compose modifier of 93 * `Modifier.clearAndSetSemantics {}` 94 * 95 * <p>{@link CoreSemantics.Mode#MERGE} matches a Compose modifier of 96 * `Modifier.semantics(mergeDescendants = true) {}` 97 * 98 * @return The mode of the operation, which defaults to {@link CoreSemantics.Mode#SET}. 99 */ getMode()100 default CoreSemantics.Mode getMode() { 101 return CoreSemantics.Mode.SET; 102 } 103 104 /** 105 * Represents the role of an accessible component. 106 * 107 * <p>The enum type deliberately matches the Compose Role. In the platform it will be applied as 108 * ROLE_DESCRIPTION_KEY. 109 * 110 * @link <a 111 * href="https://developer.android.com/reference/androidx/compose/ui/semantics/Role">Compose 112 * Semantics Role</a> 113 */ 114 enum Role { 115 BUTTON("Button"), 116 CHECKBOX("Checkbox"), 117 SWITCH("Switch"), 118 RADIO_BUTTON("RadioButton"), 119 TAB("Tab"), 120 IMAGE("Image"), 121 DROPDOWN_LIST("DropdownList"), 122 PICKER("Picker"), 123 CAROUSEL("Carousel"), 124 UNKNOWN(null); 125 126 @Nullable private final String mDescription; 127 Role(@ullable String description)128 Role(@Nullable String description) { 129 this.mDescription = description; 130 } 131 132 @Nullable getDescription()133 public String getDescription() { 134 return mDescription; 135 } 136 137 /** 138 * Map int value to Role enum value 139 * 140 * @param i int value 141 * @return corresponding enum value 142 */ fromInt(int i)143 public static Role fromInt(int i) { 144 if (i < UNKNOWN.ordinal()) { 145 return Role.values()[i]; 146 } 147 return Role.UNKNOWN; 148 } 149 } 150 151 /** 152 * Defines the merge mode of an element in the semantic tree. 153 * 154 * <p>{@link CoreSemantics.Mode#CLEAR_AND_SET} matches a Compose modifier of 155 * `Modifier.clearAndSetSemantics {}` 156 * 157 * <p>{@link CoreSemantics.Mode#MERGE} matches a Compose modifier of 158 * `Modifier.semantics(mergeDescendants = true) {}` 159 * 160 * <p>{@link CoreSemantics.Mode#SET} adds or overrides semantics on an element. 161 */ 162 enum Mode { 163 SET, 164 CLEAR_AND_SET, 165 MERGE 166 } 167 } 168