1 /*
2  * Copyright (c) 2020 Huawei Device Co., Ltd.
3  * Licensed under the Apache License, Version 2.0 (the "License");
4  * you may not use this file except in compliance with the License.
5  * You may obtain a copy of the License at
6  *
7  *     http://www.apache.org/licenses/LICENSE-2.0
8  *
9  * Unless required by applicable law or agreed to in writing, software
10  * distributed under the License is distributed on an "AS IS" BASIS,
11  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12  * See the License for the specific language governing permissions and
13  * limitations under the License.
14 */
15 
16 /**
17  * @addtogroup AbilityKit
18  * @{
19  *
20  * @brief Provides ability-related functions, including ability lifecycle callbacks and functions for connecting to or
21  *        disconnecting from Particle Abilities.
22  *
23  * Abilities are classified into Feature Abilities and Particle Abilities. Feature Abilities support the Page template,
24  * and Particle Abilities support the Service template. An ability using the Page template is called a Page ability for
25  * short and that using the Service template is called a Service ability.
26  *
27  * @since 1.0
28  * @version 1.0
29  */
30 
31 /**
32  * @file ability_slice.h
33  *
34  * @brief Declares ability slice-related functions, including ability slice lifecycle callbacks and functions for
35  *        connecting to or disconnecting from ability slices.
36  *
37  * <b>AbilitySlice</b> instances, which are specific to Feature Abilities (abilities using the Page template),
38  * are used to present different screens on an application's user interface.
39  * A Feature Ability can have multiple ability slices.
40  *
41  * @since 1.0
42  * @version 1.0
43  */
44 #ifndef OHOS_ABILITY_SLICE_H
45 #define OHOS_ABILITY_SLICE_H
46 
47 #include "ability.h"
48 
49 namespace OHOS {
50 class AbilitySliceManager;
51 
52 /**
53  * @brief Provides ability slice-related functions, including ability slice lifecycle callbacks and functions for
54  *        connecting to or disconnecting from ability slices.
55  *
56  * <b>AbilitySlice</b> instances, which are specific to Feature Abilities (abilities using the Page template),
57  * are used to present different screens on an application's user interface.
58  * A Feature Ability can have multiple ability slices.
59  *
60  * @since 1.0
61  * @version 1.0
62  */
63 class AbilitySlice : public AbilityContext {
64 public:
65     AbilitySlice() = default;
66     virtual ~AbilitySlice() = default;
67 
68     /**
69      * @brief Called when this ability slice is started. You must override this function if you want to perform some
70      *        initialization operations during ability slice startup.
71      *
72      * This function can be called only once in the entire lifecycle of an ability slice.
73      * You can override this function to implement your own processing logic.
74      * @param want Indicates the {@link Want} structure containing startup information about the ability slice.
75      */
76     virtual void OnStart(const Want &want);
77 
78     /**
79      * @brief Called when this ability slice enters the <b>STATE_INACTIVE</b> state.
80      *
81      * <b>STATE_INACTIVE</b> is an instantaneous state. The ability slice in this state may be visible but does not
82      * have focus. You can override this function to implement your own processing logic.
83      */
84     virtual void OnInactive();
85 
86     /**
87      * @brief Called when this ability slice enters the <b>STATE_ACTIVE</b> state.
88      *
89      * The ability slice in the <b>STATE_ACTIVE</b> state is visible and has focus.
90      * You can override this function to implement your own processing logic.
91      *
92      * @param want Indicates the {@link Want} structure containing activation information about the ability slice.
93      */
94     virtual void OnActive(const Want &want);
95 
96     /**
97     * @brief Called when this ability slice enters the <b>STATE_BACKGROUND</b> state.
98     *
99     * The ability slice in the <b>STATE_BACKGROUND</b> state is invisible.
100     * You can override this function to implement your own processing logic.
101     */
102     virtual void OnBackground();
103 
104     /**
105     * @brief Called when this ability slice enters the <b>STATE_STOP</b> state.
106     *
107     * The ability slice in the <b>STATE_STOP</b> state is being destroyed.
108     * You can override this function to implement your own processing logic.
109     */
110     virtual void OnStop();
111 
112     /**
113      * @brief Presents another ability slice, which can be an ability slice that is not started or an existing ability
114      *        slice in the host ability.
115      *
116      * @attention This function can be called only when both of the following conditions are met:
117      * <ul><li>The host ability is in the <b>STATE_ACTIVE</b> state.</li>
118      * <li>The target ability slice is not started or destroyed.</li></ul>
119      *
120      * @param abilitySlice Indicates the target ability slice. This parameter cannot be null.
121      * @param want Indicates the {@link Want} structure containing startup information about the target ability slice.
122      */
123     void Present(AbilitySlice &abilitySlice, const Want &want);
124 
125     /**
126      * @brief Destroys this ability slice.
127      *
128      * This ability slice can call this function to destroy itself. If the ability slice to destroy is the only
129      * running one in the host ability, the host ability will also be destroyed. Otherwise, the host ability will
130      * not be affected.
131      */
132     void Terminate();
133 
134     /**
135      * @brief Sets the UI layout for the host ability of this ability slice.
136      *
137      * You can call {@link GetWindowRootView()} to create a layout and add controls.
138      *
139      * @param rootView Indicates the pointer to the custom layout view you have created.
140      */
141     void SetUIContent(RootView *rootView);
142 private:
143     void Init(AbilitySliceManager &abilitySliceManager);
144     int GetState() const;
145 
146     AbilitySliceManager *abilitySliceManager_ { nullptr };
147     RootView *curRootView_ { nullptr };
148     int sliceState_ { 0 };
149 
150     friend class AbilitySliceScheduler;
151 };
152 } // namespace OHOS
153 #endif // OHOS_ABILITY_SLICE_H