1 /* 2 * Copyright (C) 2021 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.car.ui; 18 19 import android.view.View; 20 21 import androidx.annotation.NonNull; 22 import androidx.annotation.Nullable; 23 24 /** 25 * An interface used for rotary controller navigation. When a class implements this interface and 26 * extends a subclass of {@link android.view.ViewGroup}, the class can be used as a navigation 27 * block for the rotary controller. For example, the {@link FocusArea} class, which extends 28 * {@link android.widget.LinearLayout}. 29 * <p> 30 * The {@link com.android.car.rotary.RotaryService} looks for instances of IFocusArea in 31 * the view hierarchy when handling rotate and nudge actions. When receiving a rotation event 32 * ({@link android.car.input.RotaryEvent}), RotaryService will move the focus to another 33 * {@link View} that can take focus within the same IFocusArea. When receiving a nudge event 34 * ({@link android.view.KeyEvent#KEYCODE_SYSTEM_NAVIGATION_UP}, 35 * {@link android.view.KeyEvent#KEYCODE_SYSTEM_NAVIGATION_DOWN}, 36 * {@link android.view.KeyEvent#KEYCODE_SYSTEM_NAVIGATION_LEFT}, or 37 * {@link android.view.KeyEvent#KEYCODE_SYSTEM_NAVIGATION_RIGHT}), 38 * RotaryService will move the focus to another view that can take focus in another (typically 39 * adjacent) IFocusArea. 40 * <p> 41 * If enabled, IFocusArea can draw highlights when one of its descendants has focus and it's not in 42 * touch mode. 43 * <p> 44 * DO NOT nest an IFocusArea inside another IFocusArea because it will result in undefined 45 * navigation behavior. 46 */ 47 public interface IFocusArea { 48 49 /** Gets the {@link FocusAreaHelper} of this IFocusArea. */ 50 @NonNull getHelper()51 FocusAreaHelper getHelper(); 52 53 /** Gets the default focus view in this IFocusArea. */ 54 @Nullable getDefaultFocusView()55 View getDefaultFocusView(); 56 57 /** Sets the default focus view in this IFocusArea. */ setDefaultFocus(@onNull View defaultFocus)58 void setDefaultFocus(@NonNull View defaultFocus); 59 60 /** 61 * Sets the padding (in pixels) of the IFocusArea highlight. 62 * <p> 63 * It doesn't affect other values, such as the paddings on its child views. 64 */ setHighlightPadding(int left, int top, int right, int bottom)65 void setHighlightPadding(int left, int top, int right, int bottom); 66 67 /** 68 * Sets the offset (in pixels) of the IFocusArea's perceived bounds. 69 * <p> 70 * It only affects the perceived bounds for the purposes of finding the nudge target. It doesn't 71 * affect the IFocusArea's view bounds or highlight bounds. The offset should only be used when 72 * IFocusAreas are overlapping and nudge interaction is ambiguous. 73 */ setBoundsOffset(int left, int top, int right, int bottom)74 void setBoundsOffset(int left, int top, int right, int bottom); 75 76 /** Sets whether wrap-around is enabled for this IFocusArea. */ setWrapAround(boolean wrapAround)77 void setWrapAround(boolean wrapAround); 78 79 /** 80 * Sets the nudge shortcut for the given {@code direction}. Removes the nudge shortcut if 81 * {@code view} is {@code null}. 82 */ setNudgeShortcut(int direction, @Nullable View view)83 void setNudgeShortcut(int direction, @Nullable View view); 84 85 /** 86 * Sets the nudge target IFocusArea for the given {@code direction}. Removes the 87 * existing target if {@code target} is {@code null}. 88 */ setNudgeTargetFocusArea(int direction, @Nullable IFocusArea target)89 void setNudgeTargetFocusArea(int direction, @Nullable IFocusArea target); 90 91 /** 92 * Sets whether to focus on the default focus view when nudging to the IFocusArea, even if there 93 * was another view in the IFocusArea focused before. 94 */ setDefaultFocusOverridesHistory(boolean override)95 void setDefaultFocusOverridesHistory(boolean override); 96 } 97