Arm-2D  
2D Image Processing Library for Cortex-M Processors
 
Loading...
Searching...
No Matches
arm_2d_helper_control.h
1/*
2 * Copyright (c) 2009-2021 Arm Limited. All rights reserved.
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 *
6 * Licensed under the Apache License, Version 2.0 (the License); you may
7 * not use this file except in compliance with the License.
8 * You may obtain a copy of the License at
9 *
10 * www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing, software
13 * distributed under the License is distributed on an AS IS BASIS, WITHOUT
14 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 * See the License for the specific language governing permissions and
16 * limitations under the License.
17 */
18
19/* ----------------------------------------------------------------------
20 * Project: Arm-2D Library
21 * Title: #include "arm_2d_helper_control.h"
22 * Description: the helper service header file for control management
23 *
24 * $Date: 15. May 2025
25 * $Revision: V.0.7.7
26 *
27 * Target Processor: Cortex-M cores
28 * -------------------------------------------------------------------- */
29
30#ifndef __ARM_2D_HELPER_CONTROL_H__
31#define __ARM_2D_HELPER_CONTROL_H__
32
33/*============================ INCLUDES ======================================*/
34#include "arm_2d.h"
35
36#ifdef __cplusplus
37extern "C" {
38#endif
39
40/*!
41 * \addtogroup gHelper 8 Helper Services
42 * @{
43 */
44
45/*============================ MACROS ========================================*/
46/* OOC header, please DO NOT modify */
47#ifdef __ARM_2D_HELPER_CONTROL_IMPLEMENT__
48# define __ARM_2D_IMPL__
49#endif
50#ifdef __ARM_2D_HELPER_CONTROL_INHERIT__
51# define __ARM_2D_INHERIT__
52#endif
53#include "arm_2d_utils.h"
54
55/*============================ MACROFIED FUNCTIONS ===========================*/
56
57/*!
58 * \brief a helper macro to enumerate nodes in the target element tree with a
59 * given traversal policy
60 * \param[in] __ROOT the root node of the target element tree
61 * \param __ITEM_NAME the pointer variable name represents the current node
62 * \param[in] a traversal policy. Please ignore the prefix
63 * ARM_2D_CONTROL_ENUMERATION_POLICY_xxxxx
64 *
65 * \example enumerate each nodes in ptRoot using preorder traversal policy:
66 * arm_ctrl_foreach(ptRoot, ptItem, PREORDER_TRAVERSAL) {
67 * ...
68 * ptItem->tRegion.xxxx ...
69 * ptItem->xxxx ...
70 * ...
71 * }
72 */
73#define ARM_CONTROL_ENUMERATE(__ROOT, __ITEM_NAME, __POLICY ) \
74 for ( \
75 arm_2d_control_enumerator_t ARM_2D_SAFE_NAME(tEnum), \
76 *ARM_2D_SAFE_NAME(ptPointer) = NULL; \
77 (({ \
78 arm_2d_helper_control_enum_init( \
79 &ARM_2D_SAFE_NAME(tEnum), \
80 &(ARM_2D_CONTROL_ENUMERATION_POLICY_##__POLICY), \
81 (const arm_2d_control_node_t *)(__ROOT)); \
82 ARM_2D_SAFE_NAME(ptPointer)++; \
83 }) == NULL); \
84 ({ \
85 arm_2d_helper_control_enum_depose(&ARM_2D_SAFE_NAME(tEnum)); \
86 })) for ( \
87 arm_2d_control_node_t *(__ITEM_NAME) = NULL; \
88 (NULL != ((__ITEM_NAME) = arm_2d_helper_control_enum_get_next_node( \
89 &ARM_2D_SAFE_NAME(tEnum))) \
90 ); \
91 )
92
93#define arm_control_enumerate ARM_CONTROL_ENUMERATE
94#define arm_ctrl_enum ARM_CONTROL_ENUMERATE
95#define ARM_CTRL_ENUM ARM_CONTROL_ENUMERATE
96#define arm_ctrl_foreach ARM_CONTROL_ENUMERATE
97#define ARM_CTRL_FOREACH ARM_CONTROL_ENUMERATE
98
99/*============================ TYPES =========================================*/
100
101typedef struct arm_2d_control_node_t arm_2d_control_node_t;
102
103struct arm_2d_control_node_t {
104
105ARM_PROTECTED(
106 arm_2d_control_node_t *ptNext; /*!< points to the next peer */
107 arm_2d_control_node_t *ptParent; /*!< points to the parent */
108 arm_2d_control_node_t *ptChildList; /*!< NULL: leaf, !NULL: container */
109)
110
111 arm_2d_region_t tRegion;
112};
113
114typedef struct arm_2d_control_enumerator_t arm_2d_control_enumerator_t;
115
116typedef struct arm_2d_control_enumeration_policy_t {
117 arm_2d_err_t (*fnInit) (arm_2d_control_enumerator_t *ptThis,
118 const arm_2d_control_node_t *ptRoot);
119 arm_2d_err_t (*fnDepose) (arm_2d_control_enumerator_t *ptThis);
120 arm_2d_control_node_t * (*fnGetNextNode) (arm_2d_control_enumerator_t *ptThis);
121} arm_2d_control_enumeration_policy_t;
122
123struct arm_2d_control_enumerator_t {
124 const arm_2d_control_enumeration_policy_t *ptPolicy;
125 arm_2d_control_node_t *ptRoot;
126 arm_2d_control_node_t *ptCurrent;
127 union {
128 uint32_t : 32;
129 struct {
130 bool bFirstNode;
131 } Preorder;
132 struct {
133 bool bFirstNode;
134 } BottomUp;
135 struct {
136 uint8_t chPTState;
137 } Postorder;
138 };
139};
140
141/*============================ GLOBAL VARIABLES ==============================*/
142
143/*!
144 * \brief The Preorder traversal is suitable for the following operations in the
145 * control (element tree) management
146 * - Element-Tree-Refresh Event Handling
147 * - Element-Tree-Construction Event Handling
148 * - Element-Tree-Onload Event Handling
149 */
150extern
151const arm_2d_control_enumeration_policy_t
152ARM_2D_CONTROL_ENUMERATION_POLICY_PREORDER_TRAVERSAL;
153
154/*!
155 * \brief The Postorder traversal is suitable for the following operations in the
156 * control (element tree) management:
157 * - Element-Tree-Updating Event Handling (Including Resize etc.)
158 * - Element-Tree-Destruction Event Handling
159 * - Element-Tree-OnDepose Event Handling
160 *
161 */
162extern
163const arm_2d_control_enumeration_policy_t
164ARM_2D_CONTROL_ENUMERATION_POLICY_POSTORDER_TRAVERSAL;
165
166/*!
167 * \brief The Bottom-Up traversal is suitable for the normal message handling in
168 * the control (element tree) management.
169 *
170 */
171extern
172const arm_2d_control_enumeration_policy_t
173ARM_2D_CONTROL_ENUMERATION_POLICY_BOTTOM_UP_TRAVERSAL;
174
175/*============================ PROTOTYPES ====================================*/
176
177/*!
178 * \brief Initialize a enumerator for the target element tree with a given
179 * traversal policy.
180 *
181 * \param[in] ptThis an arm_2d_control_enumerator_t object
182 * \param[in] ptPolicy the policy
183 * \param[in] ptRoot the root of the target element tree
184 * \return arm_2d_err_t
185 */
186extern
187ARM_NONNULL(1,2)
188arm_2d_err_t arm_2d_helper_control_enum_init(
189 arm_2d_control_enumerator_t *ptThis,
190 const arm_2d_control_enumeration_policy_t *ptPolicy,
191 const arm_2d_control_node_t *ptRoot);
192
193/*!
194 * \brief get the next node of the target enumerator
195 *
196 * \param[in] ptThis the target enumerator
197 * \return arm_2d_control_node_t* the next node
198 */
199extern
200ARM_NONNULL(1)
201arm_2d_control_node_t *arm_2d_helper_control_enum_get_next_node(
202 arm_2d_control_enumerator_t *ptThis);
203
204/*!
205 * \brief depose (de-initialize) a given enumerator
206 *
207 * \param[in] ptThis the target enumerator
208 * \return arm_2d_err_t the operation result
209 */
210extern
211ARM_NONNULL(1)
212arm_2d_err_t arm_2d_helper_control_enum_depose(
213 arm_2d_control_enumerator_t *ptThis);
214
215/*!
216 * \brief find the top node on the screen with a given touch location.
217 *
218 * \param[in] ptRoot the root of the target element tree
219 * \param[in] tLocation the touch coordinate
220 * \return arm_2d_control_node_t* the target node
221 */
222extern
223ARM_NONNULL(1)
224arm_2d_control_node_t *arm_2d_helper_control_find_node_with_location(
225 arm_2d_control_node_t *ptRoot,
226 arm_2d_location_t tLocation);
227
228/*!
229 * \brief get the absolute region of a given target control in an element tree
230 *
231 * \param[in] ptNode the target control in an element tree
232 * \param[in] ptOutRegion the object buffer to hold the result
233 * \param[in] bClip whether clip the control region during the calculation
234 * \retval NULL the target control is out of the container area
235 * \retval !NULL the ptOutRegion
236 */
237extern
238ARM_NONNULL(1,2)
239arm_2d_region_t *arm_2d_helper_control_get_absolute_region(
240 arm_2d_control_node_t *ptNode,
241 arm_2d_region_t *ptOutRegion,
242 bool bClip);
243
244#undef __ARM_2D_HELPER_CONTROL_IMPLEMENT__
245#undef __ARM_2D_HELPER_CONTROL_INHERIT__
246
247/*! @} */
248
249#ifdef __cplusplus
250}
251#endif
252
253#endif