1 /*
2  * Copyright (c) 2020-2021 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 Window
18  * @{
19  *
20  * @brief Provides window management capabilities, including creating, destroying, showing, hiding, moving,
21  *        resizing a window, raising a window to the top, and lowering a window to the bottom.
22  *
23  * @since 1.0
24  * @version 1.0
25  */
26 
27 /**
28  * @file window.h
29  *
30  * @brief Declares the <b>Window</b> class that provides a drawing canvas for the <b>RootView</b>,
31  *        which represents the root node of a view tree.
32  *
33  * Each window is bound to a <b>RootView</b>. For details, see {@link RootView}.
34  * The <b>Window</b> class also provides window management capabilities, including creating, destroying, showing,
35  * hiding, moving, resizing a window, raising a window to the top, and lowering a window to the bottom.
36  *
37  * @since 1.0
38  * @version 1.0
39  */
40 
41 #ifndef GRAPHIC_LITE_WINDOW_H
42 #define GRAPHIC_LITE_WINDOW_H
43 
44 #include "gfx_utils/color.h"
45 #include "components/root_view.h"
46 
47 namespace OHOS {
48 /**
49  * @brief Enumerates the pixel formats of this window.
50  *
51  * @since 1.0
52  * @version 1.0
53  */
54 enum WindowPixelFormat {
55     /** RGB565 format */
56     WINDOW_PIXEL_FORMAT_RGB565 = 101,
57     /** ARGB1555 format */
58     WINDOW_PIXEL_FORMAT_ARGB1555,
59     /** RGB888 format */
60     WINDOW_PIXEL_FORMAT_RGB888,
61     /** ARGB8888 format */
62     WINDOW_PIXEL_FORMAT_ARGB8888,
63 };
64 
65 /**
66  * @brief Sets the attributes for this window.
67  *
68  * This structure stores the attributes such as the rectangle, opacity, and pixel format of this window.
69  *
70  * @since 1.0
71  * @version 1.0
72  */
73 struct WindowConfig {
WindowConfigWindowConfig74     WindowConfig() : rect(),
75                      opacity(OPA_OPAQUE),
76                      pixelFormat(WINDOW_PIXEL_FORMAT_ARGB8888),
77                      compositeMode(COPY),
78                      isModal(false)
79     {
80     }
~WindowConfigWindowConfig81     ~WindowConfig() {}
82     enum CompositeMode {
83         COPY,
84         BLEND
85     };
86     /** Rectangle */
87     Rect rect;
88     /** Opacity, within [0, 255] */
89     uint8_t opacity;
90     /** Pixel format */
91     WindowPixelFormat pixelFormat;
92     CompositeMode compositeMode;
93     bool isModal;
94 };
95 
96 /**
97  * @brief Provides a drawing canvas for the <b>RootView</b>, which represents the root node of a view tree.
98  *
99  * Each window is bound to a <b>RootView</b>. For details, see {@link RootView}.
100  * This class also provides window management capabilities, including creating, destroying, showing, hiding,
101  * moving, resizing a window, raising a window to the top, and lowering a window to the bottom.
102  *
103  * @since 1.0
104  * @version 1.0
105  */
106 class Window {
107 public:
108     /**
109      * @brief A constructor used to create a <b>Window</b> instance.
110      *
111      * @since 1.0
112      * @version 1.0
113      */
114     Window() = default;
115 
116     /**
117      * @brief A destructor used to delete the <b>Window</b> instance.
118      *
119      * @since 1.0
120      * @version 1.0
121      */
122     virtual ~Window() = default;
123 
124     /**
125      * @brief Creates a <b>Window</b> instance.
126      *
127      * @param config Indicates the window configuration. For details, see {@link WindowConfig}.
128      * @return Returns the <b>Window</b> instance if the operation is successful; returns <b>nullptr</b> otherwise.
129      * @since 1.0
130      * @version 1.0
131      */
132     static Window* CreateWindow(const WindowConfig& config);
133 
134     /**
135      * @brief Destroys a specified window.
136      *
137      * @param window Indicates the <b>Window</b> instance to destroy.
138      * @since 1.0
139      * @version 1.0
140      */
141     static void DestroyWindow(Window* window);
142 
143     /**
144      * @brief Binds the <b>RootView</b> to this window.
145      *
146      * @param rootView Indicates the <b>RootView</b> to bind.
147      * @since 1.0
148      * @version 1.0
149      */
150     virtual void BindRootView(RootView* rootView) = 0;
151 
152     /**
153      * @brief Unbinds the <b>RootView</b> from this window.
154      *
155      * @since 1.0
156      * @version 1.0
157      */
158     virtual void UnbindRootView() = 0;
159 
160     /**
161      * @brief Obtains the <b>RootView</b> bound to this window.
162      *
163      * @return Returns the <b>RootView</b> if available; returns <b>nullptr</b> otherwise.
164      * @since 1.0
165      * @version 1.0
166      */
167     virtual RootView* GetRootView() = 0;
168 
169     /**
170      * @brief Obtains the rectangle information (position, width, and height) of this window.
171      *
172      * @return Returns the rectangle information of this window.
173      * @since 1.0
174      * @version 1.0
175      */
176     virtual Rect GetRect() = 0;
177 
178     /**
179      * @brief Shows this window.
180      *
181      * @since 1.0
182      * @version 1.0 */
183     virtual void Show() = 0;
184 
185     /**
186      * @brief Hides this window.
187      *
188      * @since 1.0
189      * @version 1.0
190      */
191     virtual void Hide() = 0;
192 
193     /**
194      * @brief Moves this window to a specified position.
195      *
196      * @param x Indicates the x-coordinate of the target position.
197      * @param y Indicates the y-coordinate of the target position.
198      * @since 1.0
199      * @version 1.0
200      */
201     virtual void MoveTo(int16_t x, int16_t y) = 0;
202 
203     /**
204      * @brief Resizes this window.
205      *
206      * @param width Indicates the new window width.
207      * @param height Indicates the new window height.
208      * @since 1.0
209      * @version 1.0
210      */
211     virtual void Resize(int16_t width, int16_t height) = 0;
212 
213     /**
214      * @brief Raises this window to the top.
215      *
216      * @since 1.0
217      * @version 1.0
218      */
219     virtual void RaiseToTop() = 0;
220 
221     /**
222      * @brief Lowers this window to the bottom.
223      *
224      * @since 1.0
225      * @version 1.0
226      */
227     virtual void LowerToBottom() = 0;
228 
229     /**
230      * @brief Obtains the unique ID of this window.
231      *
232      * The window ID is within [0, 31]. An ID will be reused after the current window is destroyed.
233      * A maximum of 32 windows can be displayed at the same time.
234      *
235      * @return Returns the unique ID of this window if the operation is successful; returns <b>-1</b> otherwise.
236      * @since 1.0
237      * @version 1.0
238      */
239     virtual int32_t GetWindowId() = 0;
240 };
241 }
242 #endif
243