Debian Codegraph @

layoutlib-api/src/main/java/com/android/ide/common/rendering/api/RenderSession.java

raw
1 /*
2 * Copyright (C) 2010 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 com.android.ide.common.rendering.api;
18
19 import static com.android.ide.common.rendering.api.Result.Status.NOT_IMPLEMENTED;
20
21 import com.android.ide.common.rendering.api.Result.Status;
22 import com.android.util.PropertiesMap;
23
24 import java.awt.image.BufferedImage;
25 import java.util.List;
26 import java.util.Map;
27
28 /**
29 * An object allowing interaction with an Android layout.
30 *
31 * This is returned by {@link Bridge#createSession(SessionParams)}.
32 * and can then be used for subsequent actions on the layout.
33 *
34 * @since 5
35 *
36 */
37 public class RenderSession {
38
39 /**
40 * Returns the last operation result.
41 */
42 public Result getResult() {
43 return NOT_IMPLEMENTED.createResult();
44 }
45
46 /**
47 * Returns the {@link ViewInfo} objects for the top level views.
48 * <p>
49 * It contains {@code ViewInfo} for only the views in the layout. For {@code ViewInfo} of the
50 * System UI surrounding the layout use {@link #getSystemRootViews()}. In most cases the list
51 * will only contain one item. If the top level node is a {@code merge} though then it will
52 * contain all the items under the {@code merge} tag.
53 * <p>
54 * This is reset to a new instance every time {@link #render()} is called and can be
55 * <code>null</code> if the call failed (and the method returned a {@link Result} with
56 * {@link Status#ERROR_UNKNOWN} or {@link Status#NOT_IMPLEMENTED}.
57 * <p>
58 * This can be safely modified by the caller, but {@code #getSystemRootViews} and
59 * {@code #getRootViews} share some view infos, so modifying one result can affect the other.
60 *
61 * @return the list of {@link ViewInfo} or null if there aren't any.
62 *
63 * @see #getSystemRootViews()
64 */
65 public List<ViewInfo> getRootViews() {
66 return null;
67 }
68
69 /**
70 * Returns the {@link ViewInfo} objects for the system decor views, like the ActionBar.
71 * <p>
72 * This is reset to a new instance every time {@link #render()} is called and can be
73 * <code>null</code> if the call failed, or there was no system decor.
74 * <p>
75 * This can be safely modified by the caller, but {@code #getSystemRootViews} and
76 * {@code #getRootViews} share some view infos, so modifying one result can affect the other.
77 *
78 * @return the list of {@link ViewInfo} or null if there aren't any.
79 */
80 public List<ViewInfo> getSystemRootViews() {
81 return null;
82 }
83
84 /**
85 * Returns the rendering of the full layout.
86 * <p>
87 * This is reset to a new instance every time {@link #render()} is called and can be
88 * <code>null</code> if the call failed (and the method returned a {@link Result} with
89 * {@link Status#ERROR_UNKNOWN} or {@link Status#NOT_IMPLEMENTED}.
90 * <p>
91 * This can be safely modified by the caller.
92 */
93 public BufferedImage getImage() {
94 return null;
95 }
96
97 /**
98 * Returns true if the current image alpha channel is relevant.
99 *
100 * @return whether the image alpha channel is relevant.
101 */
102 public boolean isAlphaChannelImage() {
103 return true;
104 }
105
106 /**
107 * Returns a map of (XML attribute name, attribute value) containing only default attribute
108 * values, for the given view Object.
109 * @param viewObject the view object.
110 * @return a map of the default property values or null.
111 * @deprecated use {@link #getDefaultProperties()}
112 */
113 @Deprecated
114 public Map<String, String> getDefaultProperties(Object viewObject) {
115 return null;
116 }
117
118 /**
119 * Returns the map of View Cookie → properties (attribute name, attribute value) for all the
120 * views that have a view cookie.
121 */
122 public Map<Object, PropertiesMap> getDefaultProperties() {
123 return null;
124 }
125
126 /**
127 * Re-renders the layout as-is.
128 * In case of success, this should be followed by calls to {@link #getRootViews()} and
129 * {@link #getImage()} to access the result of the rendering.
130 *
131 * This is equivalent to calling <code>render(SceneParams.DEFAULT_TIMEOUT)</code>
132 *
133 * @return a {@link Result} indicating the status of the action.
134 */
135 public Result render() {
136 return render(RenderParams.DEFAULT_TIMEOUT);
137 }
138
139 /**
140 * Re-renders the layout as-is, with a given timeout in case other renderings are being done.
141 * In case of success, this should be followed by calls to {@link #getRootViews()} and
142 * {@link #getImage()} to access the result of the rendering.
143 *
144 * The {@link Bridge} is only able to inflate or render one layout at a time. There
145 * is an internal lock object whenever such an action occurs. The timeout parameter is used
146 * when attempting to acquire the lock. If the timeout expires, the method will return
147 * {@link Status#ERROR_TIMEOUT}.
148 *
149 * @param timeout timeout for the rendering, in milliseconds.
150 *
151 * @return a {@link Result} indicating the status of the action.
152 */
153 public Result render(long timeout) {
154 return render(timeout, false);
155 }
156
157 /**
158 * Re-renders the layout as-is, with a given timeout in case other renderings are being done.
159 * In case of success, this should be followed by calls to {@link #getRootViews()} and
160 * {@link #getImage()} to access the result of the rendering.
161 * This call also allows triggering a forced measure.
162 *
163 * The {@link Bridge} is only able to inflate or render one layout at a time. There
164 * is an internal lock object whenever such an action occurs. The timeout parameter is used
165 * when attempting to acquire the lock. If the timeout expires, the method will return
166 * {@link Status#ERROR_TIMEOUT}.
167 *
168 * @param timeout timeout for the rendering, in milliseconds.
169 * @param forceMeasure force running measure for the layout.
170 *
171 * @return a {@link Result} indicating the status of the action.
172 */
173 public Result render(long timeout, boolean forceMeasure) {
174 return NOT_IMPLEMENTED.createResult();
175 }
176
177 /**
178 * Sets the value of a given property on a given object.
179 * <p>
180 * This does nothing more than change the property. To render the scene in its new state, a
181 * call to {@link #render()} is required.
182 * <p>
183 * Any amount of actions can be taken on the scene before {@link #render()} is called.
184 *
185 * @param objectView
186 * @param propertyName
187 * @param propertyValue
188 *
189 * @return a {@link Result} indicating the status of the action.
190 *
191 * @throws IllegalArgumentException if the view object is not an android.view.View
192 */
193 public Result setProperty(Object objectView, String propertyName, String propertyValue) {
194 return NOT_IMPLEMENTED.createResult();
195 }
196
197 /**
198 * returns the value of a given property on a given object.
199 * <p>
200 * This returns a {@link Result} object. If the operation of querying the object for its
201 * property was successful (check {@link Result#isSuccess()}), then the property value
202 * is set in the result and can be accessed through {@link Result#getData()}.
203 *
204 * @param objectView
205 * @param propertyName
206 *
207 * @return a {@link Result} indicating the status of the action.
208 *
209 * @throws IllegalArgumentException if the view object is not an android.view.View
210 */
211 public Result getProperty(Object objectView, String propertyName) {
212 return NOT_IMPLEMENTED.createResult();
213 }
214
215 /**
216 * Inserts a new child in a ViewGroup object, and renders the result.
217 * <p>
218 * The child is first inflated and then added to its new parent, at the given <var>index</var>
219 * position. If the <var>index</var> is -1 then the child is added at the end of the parent.
220 * <p>
221 * If an animation listener is passed then the rendering is done asynchronously and the
222 * result is sent to the listener.
223 * If the listener is null, then the rendering is done synchronously.
224 * <p>
225 * The child stays in the view hierarchy after the rendering is done. To remove it call
226 * {@link #removeChild(Object, IAnimationListener)}
227 * <p>
228 * The returned {@link Result} object will contain the android.view.View object for
229 * the newly inflated child. It is accessible through {@link Result#getData()}.
230 *
231 * @param parentView the parent View object to receive the new child.
232 * @param childXml an {@link ILayoutPullParser} containing the content of the new child,
233 * including ViewGroup.LayoutParams attributes.
234 * @param index the index at which position to add the new child into the parent. -1 means at
235 * the end.
236 * @param listener an optional {@link IAnimationListener}.
237 *
238 * @return a {@link Result} indicating the status of the action.
239 */
240 public Result insertChild(Object parentView, ILayoutPullParser childXml, int index,
241 IAnimationListener listener) {
242 return NOT_IMPLEMENTED.createResult();
243 }
244
245 /**
246 * Move a new child to a different ViewGroup object.
247 * <p>
248 * The child is first removed from its current parent, and then added to its new parent, at the
249 * given <var>index</var> position. In case the <var>parentView</var> is the current parent of
250 * <var>childView</var> then the index must be the value with the <var>childView</var> removed
251 * from its parent. If the <var>index</var> is -1 then the child is added at the end of
252 * the parent.
253 * <p>
254 * If an animation listener is passed then the rendering is done asynchronously and the
255 * result is sent to the listener.
256 * If the listener is null, then the rendering is done synchronously.
257 * <p>
258 * The child stays in the view hierarchy after the rendering is done. To remove it call
259 * {@link #removeChild(Object, IAnimationListener)}
260 * <p>
261 * The returned {@link Result} object will contain the android.view.ViewGroup.LayoutParams
262 * object created from the <var>layoutParams</var> map if it was non <code>null</code>.
263 *
264 * @param parentView the parent View object to receive the child. Can be the current parent
265 * already.
266 * @param childView the view to move.
267 * @param index the index at which position to add the new child into the parent. -1 means at
268 * the end.
269 * @param layoutParams an optional map of new ViewGroup.LayoutParams attribute. If non null,
270 * then the current layout params of the view will be removed and a new one will
271 * be inflated and set with the content of the map.
272 * @param listener an optional {@link IAnimationListener}.
273 *
274 * @return a {@link Result} indicating the status of the action.
275 */
276 public Result moveChild(Object parentView, Object childView, int index,
277 Map<String, String> layoutParams, IAnimationListener listener) {
278 return NOT_IMPLEMENTED.createResult();
279 }
280
281 /**
282 * Removes a child from a ViewGroup object.
283 * <p>
284 * This does nothing more than change the layout. To render the scene in its new state, a
285 * call to {@link #render()} is required.
286 * <p>
287 * Any amount of actions can be taken on the scene before {@link #render()} is called.
288 *
289 * @param childView the view object to remove from its parent
290 * @param listener an optional {@link IAnimationListener}.
291 *
292 * @return a {@link Result} indicating the status of the action.
293 */
294 public Result removeChild(Object childView, IAnimationListener listener) {
295 return NOT_IMPLEMENTED.createResult();
296 }
297
298 /**
299 * Starts playing an given animation on a given object.
300 * <p>
301 * The animation playback is asynchronous and the rendered frame is sent vi the
302 * <var>listener</var>.
303 *
304 * @param targetObject the view object to animate
305 * @param animationName the name of the animation (res/anim) to play.
306 * @param listener the listener callback.
307 *
308 * @return a {@link Result} indicating the status of the action.
309 */
310 public Result animate(Object targetObject, String animationName,
311 boolean isFrameworkAnimation, IAnimationListener listener) {
312 return NOT_IMPLEMENTED.createResult();
313 }
314
315 /**
316 * Sets the current system time in nanos.
317 * <p>Calls to this method must check that layoutlib supports {@link Features#SYSTEM_TIME}
318 */
319 public void setSystemTimeNanos(long nanos) {
320 throw new UnsupportedOperationException(
321 "Current layoutlib version doesn't support Features.SYSTEM_TIME");
322 }
323
324 /**
325 * Sets the system boot time in nanos.
326 * <p>Calls to this method must check that layoutlib supports {@link Features#SYSTEM_TIME}
327 */
328 public void setSystemBootTimeNanos(long nanos) {
329 throw new UnsupportedOperationException(
330 "Current layoutlib version doesn't support Features.SYSTEM_TIME");
331 }
332
333 /**
334 * Sets the time for which the next frame will be selected. The time is the elapsed time from
335 * the current system nanos time.
336 * <p>Calls to this method must check that layoutlib supports {@link Features#SYSTEM_TIME}
337 */
338 public void setElapsedFrameTimeNanos(long nanos) {
339 throw new UnsupportedOperationException(
340 "Current layoutlib version doesn't support Features.SYSTEM_TIME");
341 }
342
343 /**
344 * Discards the layout. No more actions can be called on this object.
345 */
346 public void dispose() {
347 }
348 }