1 /* 2 * Copyright 2019 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.car.ui; 17 18 import android.text.SpannableStringBuilder; 19 20 import androidx.annotation.NonNull; 21 22 import java.util.Collections; 23 import java.util.List; 24 25 /** 26 * Text that includes rendering information. 27 */ 28 public class CarUiText { 29 private final int mMaxLines; 30 private final int mMaxChars; 31 private final List<CharSequence> mVariants; 32 33 /** 34 * Convenience method that returns a single {@link CharSequence} that is a combination of the 35 * preferred text of a list of {@link CarUiText}, separated by line breaks. 36 */ combineMultiLine(@onNull List<CarUiText> lines)37 public static CharSequence combineMultiLine(@NonNull List<CarUiText> lines) { 38 SpannableStringBuilder builder = new SpannableStringBuilder(); 39 CharSequence delimiter = ""; 40 for (CarUiText line : lines) { 41 builder.append(delimiter) 42 .append(line.getPreferredText() == null ? " " : line.getPreferredText()); 43 delimiter = "\n"; 44 } 45 return builder; 46 } 47 CarUiText(Builder builder)48 private CarUiText(Builder builder) { 49 mVariants = builder.mVariants; 50 mMaxChars = builder.mMaxChars; 51 mMaxLines = builder.mMaxLines; 52 } 53 54 /** 55 * Create a new {@link CarUiText}. 56 * 57 * @param text text to display 58 * 59 * @deprecated Use {@link Builder} to instantiate {@link CarUiText} instances 60 */ 61 @Deprecated CarUiText(@onNull CharSequence text)62 public CarUiText(@NonNull CharSequence text) { 63 this(text, Integer.MAX_VALUE); 64 } 65 66 /** 67 * Create a new {@link CarUiText}. 68 * 69 * @param text text to display 70 * @param maxLines the maximum number of lines the text should be displayed on when width 71 * constraints force the text to be wrapped. Text that exceeds the maximum 72 * number of lines is ellipsized 73 * 74 * @deprecated Use {@link Builder} to instantiate {@link CarUiText} instances 75 */ 76 @Deprecated CarUiText(@onNull CharSequence text, int maxLines)77 public CarUiText(@NonNull CharSequence text, int maxLines) { 78 mVariants = Collections.singletonList(text); 79 mMaxLines = maxLines; 80 mMaxChars = Integer.MAX_VALUE; 81 } 82 83 /** 84 * Create a new {@link CarUiText}. 85 * 86 * @param variants list of text variants. Variants provide alternative text to be used to avoid 87 * truncation. Provide variants in order of preference. 88 * @param maxLines the maximum number of lines the text should be displayed on when width 89 * constraints force the text to be wrapped. Text that exceeds the maximum 90 * number of lines is ellipsized 91 * 92 * @deprecated Use {@link Builder} to instantiate {@link CarUiText} instances 93 */ 94 @Deprecated CarUiText(@onNull List<CharSequence> variants, int maxLines)95 public CarUiText(@NonNull List<CharSequence> variants, int maxLines) { 96 mVariants = variants; 97 mMaxLines = maxLines; 98 mMaxChars = Integer.MAX_VALUE; 99 } 100 101 /** 102 * Create a new {@link CarUiText}. 103 * 104 * @param variants list of text variants. Variants provide alternative text to be used to avoid 105 * truncation. Provide variants in order of preference. 106 * @param maxLines the maximum number of lines the text should be displayed on when width 107 * constraints force the text to be wrapped. Text that exceeds the maximum 108 * number of lines is ellipsized 109 * @param maxChars the maximum number of characters that should be displayed 110 * 111 * @deprecated Use {@link Builder} to instantiate {@link CarUiText} instances 112 */ 113 @Deprecated CarUiText(@onNull List<CharSequence> variants, int maxLines, int maxChars)114 public CarUiText(@NonNull List<CharSequence> variants, int maxLines, int maxChars) { 115 mVariants = variants; 116 mMaxLines = maxLines; 117 mMaxChars = maxChars; 118 } 119 120 /** 121 * Returns the maximum number of lines the text should be displayed on when width constraints 122 * force the text to be wrapped 123 */ getMaxLines()124 public int getMaxLines() { 125 return mMaxLines; 126 } 127 128 /** 129 * Returns the maximum number of characters that should be displayed for the text 130 */ getMaxChars()131 public int getMaxChars() { 132 return mMaxChars; 133 } 134 135 /** 136 * Returns the list of text variants for this {@link CarUiText}. 137 */ getTextVariants()138 public List<CharSequence> getTextVariants() { 139 return mVariants; 140 } 141 142 /** 143 * Returns the preferred text to render for this {@link CarUiText}. 144 */ getPreferredText()145 public CharSequence getPreferredText() { 146 return mVariants.get(0); 147 } 148 149 /** 150 * A builder of {@link CarUiText}. 151 */ 152 public static final class Builder { 153 private int mMaxLines = Integer.MAX_VALUE; 154 private int mMaxChars = Integer.MAX_VALUE; 155 private final List<CharSequence> mVariants; 156 157 /** 158 * Returns a new instance of a {@link Builder}. 159 * 160 * @param text text to display 161 */ Builder(CharSequence text)162 public Builder(CharSequence text) { 163 this(Collections.singletonList(text)); 164 } 165 166 /** 167 * Returns a new instance of a {@link Builder}. 168 * 169 * @param variants list of text variants. Variants provide alternative text to be used to 170 * avoid truncation. Provide variants in order of preference. 171 */ Builder(@onNull List<CharSequence> variants)172 public Builder(@NonNull List<CharSequence> variants) { 173 mVariants = variants; 174 } 175 176 /** 177 * Sets the maximum number of characters that should be displayed. 178 */ setMaxChars(int chars)179 public Builder setMaxChars(int chars) { 180 mMaxChars = chars; 181 return this; 182 } 183 184 /** 185 * Sets the maximum number of lines the text should be displayed on when width constraints 186 * force the text to be wrapped. Text that exceeds the maximum number of lines is 187 * ellipsized. 188 */ setMaxLines(int lines)189 public Builder setMaxLines(int lines) { 190 mMaxLines = lines; 191 return this; 192 } 193 194 /** 195 * Returns a {@link CarUiText} for this {@link Builder}. 196 */ build()197 public CarUiText build() { 198 return new CarUiText(this); 199 } 200 } 201 } 202