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: 03. July 2025
25 * $Revision: V.0.7.8
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] __START the start node of a traversal
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(__START, __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 *)(__START)); \
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 *ptStart);
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 union {
126 arm_2d_control_node_t *ptRoot;
127 arm_2d_control_node_t *ptStart;
128 };
129 arm_2d_control_node_t *ptCurrent;
130 union {
131 uint32_t : 32;
132 struct {
133 bool bFirstNode;
134 } Preorder;
135 struct {
136 bool bFirstNode;
137 } BottomUp;
138 struct {
139 uint8_t chPTState;
140 } Postorder;
141 };
142};
143
144/*============================ GLOBAL VARIABLES ==============================*/
145
146/*!
147 * \brief The Preorder traversal is suitable for the following operations in the
148 * control (element tree) management
149 * - Element-Tree-Refresh Event Handling
150 * - Element-Tree-Construction Event Handling
151 * - Element-Tree-Onload Event Handling
152 */
153extern
154const arm_2d_control_enumeration_policy_t
155ARM_2D_CONTROL_ENUMERATION_POLICY_PREORDER_TRAVERSAL;
156
157/*!
158 * \brief The Postorder traversal is suitable for the following operations in the
159 * control (element tree) management:
160 * - Element-Tree-Updating Event Handling (Including Resize etc.)
161 * - Element-Tree-Destruction Event Handling
162 * - Element-Tree-OnDepose Event Handling
163 *
164 */
165extern
166const arm_2d_control_enumeration_policy_t
167ARM_2D_CONTROL_ENUMERATION_POLICY_POSTORDER_TRAVERSAL;
168
169/*!
170 * \brief The Bottom-Up traversal is suitable for the normal message handling in
171 * the control (element tree) management.
172 *
173 */
174extern
175const arm_2d_control_enumeration_policy_t
176ARM_2D_CONTROL_ENUMERATION_POLICY_BOTTOM_UP_TRAVERSAL;
177
178/*============================ PROTOTYPES ====================================*/
179
180/*!
181 * \brief Initialize a enumerator for the target element tree with a given
182 * traversal policy.
183 *
184 * \param[in] ptThis an arm_2d_control_enumerator_t object
185 * \param[in] ptPolicy the policy
186 * \param[in] ptRoot the root of the target element tree
187 * \return arm_2d_err_t
188 */
189extern
190ARM_NONNULL(1,2)
191arm_2d_err_t arm_2d_helper_control_enum_init(
192 arm_2d_control_enumerator_t *ptThis,
193 const arm_2d_control_enumeration_policy_t *ptPolicy,
194 const arm_2d_control_node_t *ptRoot);
195
196/*!
197 * \brief get the next node of the target enumerator
198 *
199 * \param[in] ptThis the target enumerator
200 * \return arm_2d_control_node_t* the next node
201 */
202extern
203ARM_NONNULL(1)
204arm_2d_control_node_t *arm_2d_helper_control_enum_get_next_node(
205 arm_2d_control_enumerator_t *ptThis);
206
207/*!
208 * \brief depose (de-initialize) a given enumerator
209 *
210 * \param[in] ptThis the target enumerator
211 * \return arm_2d_err_t the operation result
212 */
213extern
214ARM_NONNULL(1)
215arm_2d_err_t arm_2d_helper_control_enum_depose(
216 arm_2d_control_enumerator_t *ptThis);
217
218/*!
219 * \brief find the top node on the screen with a given touch location.
220 *
221 * \param[in] ptRoot the root of the target element tree
222 * \param[in] tLocation the touch coordinate
223 * \return arm_2d_control_node_t* the target node
224 */
225extern
226ARM_NONNULL(1)
227arm_2d_control_node_t *arm_2d_helper_control_find_node_with_location(
228 arm_2d_control_node_t *ptRoot,
229 arm_2d_location_t tLocation);
230
231/*!
232 * \brief get the absolute region of a given target control in an element tree
233 *
234 * \param[in] ptNode the target control in an element tree
235 * \param[in] ptOutRegion the object buffer to hold the result
236 * \param[in] bClip whether clip the control region during the calculation
237 * \retval NULL the target control is out of the container area
238 * \retval !NULL the ptOutRegion
239 */
240extern
241ARM_NONNULL(1,2)
242arm_2d_region_t *arm_2d_helper_control_get_absolute_region(
243 arm_2d_control_node_t *ptNode,
244 arm_2d_region_t *ptOutRegion,
245 bool bClip);
246
247#undef __ARM_2D_HELPER_CONTROL_IMPLEMENT__
248#undef __ARM_2D_HELPER_CONTROL_INHERIT__
249
250/*! @} */
251
252#ifdef __cplusplus
253}
254#endif
255
256#endif