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 java.util.List;
24 
25 /**
26  * Defines the interfaces for a card on the home app.
27  * The cards follow a Model-View-Presenter architectural design pattern to separate functionality
28  * into discrete components to be extensible and easily testable.
29  *
30  * The layout of a card is distinguished into two parts:
31  * (1) Header - the source of the card's data. This is the source app's name and app icon.
32  * (2) Content - the data itself. This could include text, an image, etc.
33  */
34 public interface HomeCardInterface {
35 
36     /**
37      * The View is what the user interacts with.
38      *
39      * The methods that the View exposes will be called by its Presenter. The View should
40      * only be responsible for providing a UI; the logic for determining the card's layout and
41      * content is handled by the presenter.
42      */
43     interface View {
44 
45         /**
46          * Called by the Presenter to remove the entire card from view if there is no data to
47          * display.
48          */
hideCard()49         void hideCard();
50 
51         /**
52          * Returns the {@link Fragment} with which the View is associated.
53          */
getFragment()54         Fragment getFragment();
55     }
56 
57     /**
58      * The Presenter connects the View to the Model.
59      *
60      * It accesses and formats the data from a Model and updates the View to display the data
61      */
62     interface Presenter {
63 
64         /**
65          * Sets the {@link View}, which is the card's UI that the Presenter will update.
66          */
setView(View view)67         void setView(View view);
68 
69         /**
70          * Sets the list of {@link Model} that the Presenter will use as sources of content.
71          */
setModels(List<Model> models)72         void setModels(List<Model> models);
73     }
74 
75     /**
76      * The Model defines the data to be displayed in a card on the home screen.
77      *
78      * The card's header is distinguished from the body as the body may update more frequently.
79      * For example, as a user listens to media from a single app, the header (source app)
80      * remains the same while the body (song title) changes.
81      */
82     interface Model {
83 
84         /**
85          * Interface definition for a callback to be invoked for when model has updates.
86          */
87         interface OnModelUpdateListener {
88             /**
89              * Called when model is updated.
90              */
onModelUpdate(HomeCardInterface.Model model)91             void onModelUpdate(HomeCardInterface.Model model);
92         }
93 
94         /**
95          * Registers OnModelUpdateListener on the model.
96          */
setOnModelUpdateListener(OnModelUpdateListener onModelUpdateListener)97         void setOnModelUpdateListener(OnModelUpdateListener onModelUpdateListener);
98 
99         /**
100          * Called by the Presenter to create the Model when the View is created.
101          * Should be called after the Model's Presenter has been set with setPresenter
102          */
onCreate(Context context)103         default void onCreate(Context context) {
104         }
105 
106         /**
107          * Called by the Presenter to destroy the Model when the View is destroyed
108          */
onDestroy(Context context)109         default void onDestroy(Context context) {
110         }
111     }
112 }
113