1 /*
2  * Copyright (C) 2022 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 
17 package android.graphics.text;
18 
19 import android.annotation.IntDef;
20 import android.annotation.NonNull;
21 
22 import java.lang.annotation.Retention;
23 import java.lang.annotation.RetentionPolicy;
24 import java.util.Objects;
25 
26 /**
27  * Specifies the line-break strategies for text wrapping.
28  *
29  * <p>See the
30  * <a href="https://www.w3.org/TR/css-text-3/#line-break-property" class="external">
31  * line-break property</a> for more information.
32  */
33 public final class LineBreakConfig {
34 
35     /**
36      * No line-break rules are used for line breaking.
37      */
38     public static final int LINE_BREAK_STYLE_NONE = 0;
39 
40     /**
41      * The least restrictive line-break rules are used for line breaking. This
42      * setting is typically used for short lines.
43      */
44     public static final int LINE_BREAK_STYLE_LOOSE = 1;
45 
46     /**
47      * The most common line-break rules are used for line breaking.
48      */
49     public static final int LINE_BREAK_STYLE_NORMAL = 2;
50 
51     /**
52      * The most strict line-break rules are used for line breaking.
53      */
54     public static final int LINE_BREAK_STYLE_STRICT = 3;
55 
56     /** @hide */
57     @IntDef(prefix = { "LINE_BREAK_STYLE_" }, value = {
58             LINE_BREAK_STYLE_NONE, LINE_BREAK_STYLE_LOOSE, LINE_BREAK_STYLE_NORMAL,
59             LINE_BREAK_STYLE_STRICT
60     })
61     @Retention(RetentionPolicy.SOURCE)
62     public @interface LineBreakStyle {}
63 
64     /**
65      * No line-break word style is used for line breaking.
66      */
67     public static final int LINE_BREAK_WORD_STYLE_NONE = 0;
68 
69     /**
70      * Line breaking is based on phrases, which results in text wrapping only on
71      * meaningful words.
72      *
73      * <p>Support for this line-break word style depends on locale. If the
74      * current locale does not support phrase-based text wrapping, this setting
75      * has no effect.
76      */
77     public static final int LINE_BREAK_WORD_STYLE_PHRASE = 1;
78 
79     /** @hide */
80     @IntDef(prefix = { "LINE_BREAK_WORD_STYLE_" }, value = {
81         LINE_BREAK_WORD_STYLE_NONE, LINE_BREAK_WORD_STYLE_PHRASE
82     })
83     @Retention(RetentionPolicy.SOURCE)
84     public @interface LineBreakWordStyle {}
85 
86     /**
87      * A builder for creating a {@code LineBreakConfig} instance.
88      */
89     public static final class Builder {
90         // The line break style for the LineBreakConfig.
91         private @LineBreakStyle int mLineBreakStyle = LineBreakConfig.LINE_BREAK_STYLE_NONE;
92 
93         // The line break word style for the LineBreakConfig.
94         private @LineBreakWordStyle int mLineBreakWordStyle =
95                 LineBreakConfig.LINE_BREAK_WORD_STYLE_NONE;
96 
97         /**
98          * Builder constructor.
99          */
Builder()100         public Builder() {
101         }
102 
103         /**
104          * Sets the line-break style.
105          *
106          * @param lineBreakStyle The new line-break style.
107          * @return This {@code Builder}.
108          */
setLineBreakStyle(@ineBreakStyle int lineBreakStyle)109         public @NonNull Builder setLineBreakStyle(@LineBreakStyle int lineBreakStyle) {
110             mLineBreakStyle = lineBreakStyle;
111             return this;
112         }
113 
114         /**
115          * Sets the line-break word style.
116          *
117          * @param lineBreakWordStyle The new line-break word style.
118          * @return This {@code Builder}.
119          */
setLineBreakWordStyle(@ineBreakWordStyle int lineBreakWordStyle)120         public @NonNull Builder setLineBreakWordStyle(@LineBreakWordStyle int lineBreakWordStyle) {
121             mLineBreakWordStyle = lineBreakWordStyle;
122             return this;
123         }
124 
125         /**
126          * Builds a {@link LineBreakConfig} instance.
127          *
128          * @return The {@code LineBreakConfig} instance.
129          */
build()130         public @NonNull LineBreakConfig build() {
131             return new LineBreakConfig(mLineBreakStyle, mLineBreakWordStyle);
132         }
133     }
134 
135     /**
136      * Creates a {@code LineBreakConfig} instance with the provided line break
137      * parameters.
138      *
139      * @param lineBreakStyle The line-break style for text wrapping.
140      * @param lineBreakWordStyle The line-break word style for text wrapping.
141      * @return The {@code LineBreakConfig} instance.
142      * @hide
143      */
getLineBreakConfig(@ineBreakStyle int lineBreakStyle, @LineBreakWordStyle int lineBreakWordStyle)144     public static @NonNull LineBreakConfig getLineBreakConfig(@LineBreakStyle int lineBreakStyle,
145             @LineBreakWordStyle int lineBreakWordStyle) {
146         LineBreakConfig.Builder builder = new LineBreakConfig.Builder();
147         return builder.setLineBreakStyle(lineBreakStyle)
148                 .setLineBreakWordStyle(lineBreakWordStyle)
149                 .build();
150     }
151 
152     /** @hide */
153     public static final LineBreakConfig NONE =
154             new Builder().setLineBreakStyle(LINE_BREAK_STYLE_NONE)
155                     .setLineBreakWordStyle(LINE_BREAK_WORD_STYLE_NONE).build();
156 
157     private final @LineBreakStyle int mLineBreakStyle;
158     private final @LineBreakWordStyle int mLineBreakWordStyle;
159 
160     /**
161      * Constructor with line-break parameters.
162      *
163      * <p>Use {@link LineBreakConfig.Builder} to create the
164      * {@code LineBreakConfig} instance.
165      */
LineBreakConfig(@ineBreakStyle int lineBreakStyle, @LineBreakWordStyle int lineBreakWordStyle)166     private LineBreakConfig(@LineBreakStyle int lineBreakStyle,
167             @LineBreakWordStyle int lineBreakWordStyle) {
168         mLineBreakStyle = lineBreakStyle;
169         mLineBreakWordStyle = lineBreakWordStyle;
170     }
171 
172     /**
173      * Gets the current line-break style.
174      *
175      * @return The line-break style to be used for text wrapping.
176      */
getLineBreakStyle()177     public @LineBreakStyle int getLineBreakStyle() {
178         return mLineBreakStyle;
179     }
180 
181     /**
182      * Gets the current line-break word style.
183      *
184      * @return The line-break word style to be used for text wrapping.
185      */
getLineBreakWordStyle()186     public @LineBreakWordStyle int getLineBreakWordStyle() {
187         return mLineBreakWordStyle;
188     }
189 
190     @Override
equals(Object o)191     public boolean equals(Object o) {
192         if (o == null) return false;
193         if (this == o) return true;
194         if (!(o instanceof LineBreakConfig)) return false;
195         LineBreakConfig that = (LineBreakConfig) o;
196         return (mLineBreakStyle == that.mLineBreakStyle)
197                 && (mLineBreakWordStyle == that.mLineBreakWordStyle);
198     }
199 
200     @Override
hashCode()201     public int hashCode() {
202         return Objects.hash(mLineBreakStyle, mLineBreakWordStyle);
203     }
204 }
205