1 /*
2  * Copyright (c) 2021-2024 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 #ifndef C_INCLUDE_DRAWING_PEN_H
17 #define C_INCLUDE_DRAWING_PEN_H
18 
19 /**
20  * @addtogroup Drawing
21  * @{
22  *
23  * @brief Provides functions such as 2D graphics rendering, text drawing, and image display.
24  *
25  * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
26  *
27  * @since 8
28  * @version 1.0
29  */
30 
31 /**
32  * @file drawing_pen.h
33  *
34  * @brief Declares functions related to the <b>pen</b> object in the drawing module.
35  *
36  * @since 8
37  * @version 1.0
38  */
39 
40 #include "drawing_types.h"
41 
42 #ifdef __cplusplus
43 extern "C" {
44 #endif
45 
46 /**
47  * @brief Creates an <b>OH_Drawing_Pen</b> object.
48  *
49  * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
50  * @return Returns the pointer to the <b>OH_Drawing_Pen</b> object created.
51  * @since 8
52  * @version 1.0
53  */
54 OH_Drawing_Pen* OH_Drawing_PenCreate(void);
55 
56 /**
57  * @brief Creates an <b>OH_Drawing_Pen</b> copy object.
58  *
59  * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
60  * @param OH_Drawing_Pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object.
61  * @return Returns the pointer to the <b>OH_Drawing_Pen</b> object created.
62  * @since 12
63  * @version 1.0
64  */
65 OH_Drawing_Pen* OH_Drawing_PenCopy(OH_Drawing_Pen*);
66 
67 /**
68  * @brief Destroys an <b>OH_Drawing_Pen</b> object and reclaims the memory occupied by the object.
69  *
70  * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
71  * @param OH_Drawing_Pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object.
72  * @since 8
73  * @version 1.0
74  */
75 void OH_Drawing_PenDestroy(OH_Drawing_Pen*);
76 
77 /**
78  * @brief Checks whether anti-aliasing is enabled for a pen. If anti-aliasing is enabled,
79  * edges will be drawn with partial transparency.
80  *
81  * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
82  * @param OH_Drawing_Pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object.
83  * @return Returns <b>true</b> if anti-aliasing is enabled; returns <b>false</b> otherwise.
84  * @since 8
85  * @version 1.0
86  */
87 bool OH_Drawing_PenIsAntiAlias(const OH_Drawing_Pen*);
88 
89 /**
90  * @brief Enables or disables anti-aliasing for a pen. If anti-aliasing is enabled,
91  * edges will be drawn with partial transparency.
92  *
93  * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
94  * @param OH_Drawing_Pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object.
95  * @param bool Specifies whether to enable anti-aliasing. The value <b>true</b> means
96  *             to enable anti-aliasing, and <b>false</b> means the opposite.
97  * @since 8
98  * @version 1.0
99  */
100 void OH_Drawing_PenSetAntiAlias(OH_Drawing_Pen*, bool);
101 
102 /**
103  * @brief Obtains the color of a pen. The color is used by the pen to outline a shape.
104  *
105  * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
106  * @param OH_Drawing_Pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object.
107  * @return Returns a 32-bit (ARGB) variable that describes the color.
108  * @since 8
109  * @version 1.0
110  */
111 uint32_t OH_Drawing_PenGetColor(const OH_Drawing_Pen*);
112 
113 /**
114  * @brief Sets the color for a pen. The color is used by the pen to outline a shape.
115  *
116  * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
117  * @param OH_Drawing_Pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object.
118  * @param color Indicates the color to set, which is a 32-bit (ARGB) variable.
119  * @since 8
120  * @version 1.0
121  */
122 void OH_Drawing_PenSetColor(OH_Drawing_Pen*, uint32_t color);
123 
124 /**
125  * @brief Obtains the alpha of a pen. The alpha is used by the pen to outline a shape.
126  *
127  * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
128  * @param OH_Drawing_Pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object.
129  * @return Returns a 8-bit variable that describes the alpha.
130  * @since 11
131  * @version 1.0
132  */
133 uint8_t OH_Drawing_PenGetAlpha(const OH_Drawing_Pen*);
134 
135 /**
136  * @brief Sets the alpha for a pen. The alpha is used by the pen to outline a shape.
137  *
138  * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
139  * @param OH_Drawing_Pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object.
140  * @param alpha Indicates the alpha to set, which is a 8-bit variable.
141  * @since 11
142  * @version 1.0
143  */
144 void OH_Drawing_PenSetAlpha(OH_Drawing_Pen*, uint8_t alpha);
145 
146 /**
147  * @brief Obtains the thickness of a pen. This thickness determines the width of the outline of a shape.
148  *
149  * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
150  * @param OH_Drawing_Pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object.
151  * @return Returns the thickness.
152  * @since 8
153  * @version 1.0
154  */
155 float OH_Drawing_PenGetWidth(const OH_Drawing_Pen*);
156 
157 /**
158  * @brief Sets the thickness for a pen. This thickness determines the width of the outline of a shape.
159  *
160  * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
161  * @param OH_Drawing_Pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object.
162  * @param width Indicates the thickness to set, which is a variable.
163  * @since 8
164  * @version 1.0
165  */
166 void OH_Drawing_PenSetWidth(OH_Drawing_Pen*, float width);
167 
168 /**
169  * @brief Obtains the stroke miter limit of a polyline drawn by a pen.
170  *
171  * When the corner type is bevel, a beveled corner is displayed if the miter limit is exceeded,
172  * and a mitered corner is displayed if the miter limit is not exceeded.
173  *
174  * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
175  * @param OH_Drawing_Pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object.
176  * @return Returns the miter limit.
177  * @since 8
178  * @version 1.0
179  */
180 float OH_Drawing_PenGetMiterLimit(const OH_Drawing_Pen*);
181 
182 /**
183  * @brief Sets the stroke miter limit for a polyline drawn by a pen.
184  *
185  * When the corner type is bevel, a beveled corner is displayed if the miter limit is exceeded,
186  * and a mitered corner is displayed if the miter limit is not exceeded.
187  *
188  * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
189  * @param OH_Drawing_Pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object.
190  * @param miter Indicates a variable that describes the miter limit.
191  * @since 8
192  * @version 1.0
193  */
194 void OH_Drawing_PenSetMiterLimit(OH_Drawing_Pen*, float miter);
195 
196 /**
197  * @brief Enumerates line cap styles of a pen. The line cap style defines
198  * the style of both ends of a line segment drawn by the pen.
199  *
200  * @since 8
201  * @version 1.0
202  */
203 typedef enum {
204     /**
205      * There is no cap style. Both ends of the line segment are cut off square.
206      */
207     LINE_FLAT_CAP,
208     /**
209      * Square cap style. Both ends have a square, the height of which
210      * is half of the width of the line segment, with the same width.
211      */
212     LINE_SQUARE_CAP,
213     /**
214      * Round cap style. Both ends have a semicircle centered, the diameter of which
215      * is the same as the width of the line segment.
216      */
217     LINE_ROUND_CAP
218 } OH_Drawing_PenLineCapStyle;
219 
220 /**
221  * @brief Obtains the line cap style of a pen.
222  *
223  * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
224  * @param OH_Drawing_Pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object.
225  * @return Returns the line cap style.
226  * @since 8
227  * @version 1.0
228  */
229 OH_Drawing_PenLineCapStyle OH_Drawing_PenGetCap(const OH_Drawing_Pen*);
230 
231 /**
232  * @brief Sets the line cap style for a pen.
233  *
234  * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
235  * @param OH_Drawing_Pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object.
236  * @param OH_Drawing_PenLineCapStyle Indicates a variable that describes the line cap style.
237  * @since 8
238  * @version 1.0
239  */
240 void OH_Drawing_PenSetCap(OH_Drawing_Pen*, OH_Drawing_PenLineCapStyle);
241 
242 /**
243  * @brief Enumerates pen line join styles. The line join style defines
244  * the shape of the joints of a polyline segment drawn by the pen.
245  *
246  * @since 8
247  * @version 1.0
248  */
249 typedef enum {
250     /**
251      * Mitered corner. If the angle of a polyline is small, its miter length may be inappropriate.
252      * In this case, you need to use the miter limit to limit the miter length.
253      */
254     LINE_MITER_JOIN,
255     /** Round corner. */
256     LINE_ROUND_JOIN,
257     /** Beveled corner. */
258     LINE_BEVEL_JOIN
259 } OH_Drawing_PenLineJoinStyle;
260 
261 /**
262  * @brief Obtains the line join style of a pen.
263  *
264  * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
265  * @param OH_Drawing_Pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object.
266  * @return Returns the line join style.
267  * @since 8
268  * @version 1.0
269  */
270 OH_Drawing_PenLineJoinStyle OH_Drawing_PenGetJoin(const OH_Drawing_Pen*);
271 
272 /**
273  * @brief Sets the line join style for a pen.
274  *
275  * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
276  * @param OH_Drawing_Pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object.
277  * @param OH_Drawing_PenLineJoinStyle Indicates a variable that describes the line join style.
278  * @since 8
279  * @version 1.0
280  */
281 void OH_Drawing_PenSetJoin(OH_Drawing_Pen*, OH_Drawing_PenLineJoinStyle);
282 
283 /**
284  * @brief Sets the shaderEffect for a pen.
285  *
286  * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
287  * @param OH_Drawing_Pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object.
288  * @param OH_Drawing_ShaderEffect Indicates the pointer to an <b>OH_Drawing_ShaderEffect</b> object.
289  * @since 11
290  * @version 1.0
291  */
292 void OH_Drawing_PenSetShaderEffect(OH_Drawing_Pen*, OH_Drawing_ShaderEffect*);
293 
294 /**
295  * @brief Sets the shadowLayer for a pen.
296  *
297  * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
298  * @param OH_Drawing_Pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object.
299  * @param OH_Drawing_ShadowLayer Indicates the pointer to an <b>OH_Drawing_ShadowLayer</b> object.
300  * @since 12
301  * @version 1.0
302  */
303 void OH_Drawing_PenSetShadowLayer(OH_Drawing_Pen*, OH_Drawing_ShadowLayer*);
304 
305 /**
306  * @brief Sets the pathEffect for a pen.
307  *
308  * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
309  * @param OH_Drawing_Pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object.
310  * @param OH_Drawing_PathEffect Indicates the pointer to an <b>OH_Drawing_PathEffect</b> object.
311  * @since 12
312  * @version 1.0
313  */
314 void OH_Drawing_PenSetPathEffect(OH_Drawing_Pen*, OH_Drawing_PathEffect*);
315 
316 /**
317  * @brief Sets the filter for a pen.
318  *
319  * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
320  * @param OH_Drawing_Pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object.
321  * @param OH_Drawing_Filter Indicates the pointer to an <b>OH_Drawing_Filter</b> object.
322  * @since 11
323  * @version 1.0
324  */
325 void OH_Drawing_PenSetFilter(OH_Drawing_Pen*, OH_Drawing_Filter*);
326 
327 /**
328  * @brief Gets the filter from a pen.
329  *
330  * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
331  * @param OH_Drawing_Pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object.
332  * @param OH_Drawing_Filter Indicates the pointer to an <b>OH_Drawing_Filter</b> object.
333  * @since 12
334  * @version 1.0
335  */
336 void OH_Drawing_PenGetFilter(OH_Drawing_Pen*, OH_Drawing_Filter*);
337 
338 /**
339  * @brief Sets a blender that implements the specified blendmode enum for a pen.
340  *
341  * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
342  * @param OH_Drawing_Pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object.
343  * @param OH_Drawing_BlendMode Indicates the blend mode.
344  * @since 12
345  * @version 1.0
346  */
347 void OH_Drawing_PenSetBlendMode(OH_Drawing_Pen*, OH_Drawing_BlendMode);
348 
349 /**
350  * @brief Gets the filled equivalent of the src path.
351  *
352  * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
353  * @param OH_Drawing_Pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object.
354  * @param src Indicates the Path read to create a filled version.
355  * @param dst Indicates the resulting Path.
356  * @param OH_Drawing_Rect Indicates the pointer to an <b>OH_Drawing_Rect</b> object that limits the PathEffect area if
357                           Pen has PathEffect.
358  * @param OH_Drawing_Matrix Indicates the pointer to an <b>OH_Drawing_Matrix</b> object that tranfomation applied to
359                           PathEffect if Pen has PathEffect.
360  * @return true if get success, otherwise false.
361  * @since 12
362  * @version 1.0
363  */
364 bool OH_Drawing_PenGetFillPath(OH_Drawing_Pen*, const OH_Drawing_Path* src, OH_Drawing_Path* dst,
365     const OH_Drawing_Rect*, const OH_Drawing_Matrix*);
366 
367 /**
368  * @brief Resets all pen contents to their initial values.
369  *
370  * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
371  * @param OH_Drawing_Pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object.
372  * @since 12
373  * @version 1.0
374  */
375 void OH_Drawing_PenReset(OH_Drawing_Pen*);
376 
377 #ifdef __cplusplus
378 }
379 #endif
380 /** @} */
381 #endif
382