1 /* 2 * Copyright (C) 2020 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.carlauncher.homescreen; 18 19 import android.content.Context; 20 21 import androidx.fragment.app.Fragment; 22 23 import com.android.car.carlauncher.homescreen.ui.CardContent; 24 import com.android.car.carlauncher.homescreen.ui.CardHeader; 25 26 import java.util.List; 27 28 /** 29 * Defines the interfaces for a card on the home app. 30 * The cards follow a Model-View-Presenter architectural design pattern to separate functionality 31 * into discrete components to be extensible and easily testable. 32 * 33 * The layout of a card is distinguished into two parts: 34 * (1) Header - the source of the card's data. This is the source app's name and app icon. 35 * (2) Content - the data itself. This could include text, an image, etc. 36 */ 37 public interface HomeCardInterface { 38 39 /** 40 * The View is what the user interacts with. 41 * 42 * The methods that the View exposes will be called by its Presenter. The View should 43 * only be responsible for providing a UI; the logic for determining the card's layout and 44 * content is handled by the presenter. 45 */ 46 interface View { 47 48 /** 49 * Sets the {@link Presenter} that will manage this View. 50 */ setPresenter(Presenter presenter)51 void setPresenter(Presenter presenter); 52 53 /** 54 * Called by the Presenter to remove the entire card from view if there is no data to 55 * display. 56 */ hideCard()57 void hideCard(); 58 59 /** 60 * Called by the Presenter when there is a change in the source of the card's content. 61 * This updates the app name and app icon displayed on the card. 62 */ updateHeaderView(CardHeader header)63 void updateHeaderView(CardHeader header); 64 65 /** 66 * Called by the Presenter to update the card's content. 67 */ updateContentView(CardContent content)68 void updateContentView(CardContent content); 69 70 /** 71 * Returns the {@link Fragment} with which the View is associated. 72 */ getFragment()73 Fragment getFragment(); 74 } 75 76 /** 77 * The Presenter connects the View to the Model. 78 * 79 * It accesses and formats the data from a Model and updates the View to display the data 80 */ 81 interface Presenter { 82 83 /** 84 * Sets the {@link View}, which is the card's UI that the Presenter will update. 85 */ setView(View view)86 void setView(View view); 87 88 89 /** 90 * Sets the list of {@link Model} that the Presenter will use as sources of content. 91 */ setModels(List<Model> models)92 void setModels(List<Model> models); 93 94 /** 95 * Called by the View when its view has been created. 96 * This signals the presenter to initialize the relevant models it will use as data sources 97 * and start listening for updates. 98 */ onViewCreated()99 void onViewCreated(); 100 101 /** 102 * Called by the View when it is destroyed to allow the presenter to clean up any models 103 */ onViewDestroyed()104 void onViewDestroyed(); 105 106 /** 107 * Called by the View when it is clicked 108 */ onViewClicked(android.view.View v)109 default void onViewClicked(android.view.View v) {}; 110 111 /** 112 * Called by one of the Presenter's models when it has updated information to display on 113 * the card. 114 */ onModelUpdated(Model model)115 void onModelUpdated(Model model); 116 } 117 118 /** 119 * The Model defines the data to be displayed in a card on the home screen. 120 * 121 * The card's header is distinguished from the body as the body may update more frequently. 122 * For example, as a user listens to media from a single app, the header (source app) 123 * remains the same while the body (song title) changes. 124 */ 125 interface Model { 126 127 /** 128 * Gets the {@link CardHeader} to display for the model. 129 * If there is no content to display, this returns null. 130 */ getCardHeader()131 CardHeader getCardHeader(); 132 133 /** 134 * Gets the {@link CardContent} to display for the model 135 */ getCardContent()136 CardContent getCardContent(); 137 138 /** 139 * Sets the Presenter for the model. The model updates its presenter of changes and the 140 * presenter manages updating the UI. 141 */ setPresenter(HomeCardInterface.Presenter presenter)142 void setPresenter(HomeCardInterface.Presenter presenter); 143 144 /** 145 * Called by the Presenter to create the Model when the View is created. 146 * Should be called after the Model's Presenter has been set with setPresenter 147 */ onCreate(Context context)148 default void onCreate(Context context) {}; 149 150 /** 151 * Called by the Presenter to destroy the Model when the View is destroyed 152 */ onDestroy(Context context)153 default void onDestroy(Context context) {}; 154 155 /** 156 * Called by the Presenter to handle when the View is clicked 157 */ onClick(android.view.View view)158 default void onClick(android.view.View view) {}; 159 } 160 } 161