Arm-2D  
2D Image Processing Library for Cortex-M Processors
arm_2d_helper_list.h
1/*
2 * Copyright (C) 2022 Arm Limited or its affiliates. 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_list.h"
22 * Description: Public header file for list core related services
23 *
24 * $Date: 10. May 2024
25 * $Revision: V.1.1.4
26 *
27 * Target Processor: Cortex-M cores
28 * -------------------------------------------------------------------- */
29
30#ifndef __ARM_2D_HELPER_LIST_H__
31#define __ARM_2D_HELPER_LIST_H__
32
33/*============================ INCLUDES ======================================*/
34#include "arm_2d.h"
35#include "__arm_2d_helper_common.h"
36
37#ifdef __cplusplus
38extern "C" {
39#endif
40
41#if defined(__clang__)
42# pragma clang diagnostic push
43# pragma clang diagnostic ignored "-Wgnu-zero-variadic-macro-arguments"
44# pragma clang diagnostic ignored "-Wunused-function"
45# pragma clang diagnostic ignored "-Wpadded"
46#endif
47
48/*============================ MACROS ========================================*/
49
50/* OOC header, please DO NOT modify */
51#ifdef __ARM_2D_HELPER_LIST_VIEW_IMPLEMENT__
52# undef __ARM_2D_HELPER_LIST_VIEW_IMPLEMENT__
53# define __ARM_2D_IMPL__
54#elif defined(__ARM_2D_HELPER_LIST_VIEW_INHERIT__)
55# undef __ARM_2D_HELPER_LIST_VIEW_INHERIT__
56# define __ARM_2D_INHERIT__
57#endif
58#include "arm_2d_utils.h"
59
60
61/*!
62 * \addtogroup Deprecated
63 * @{
64 */
65#define ARM_2D_LIST_VIEW_CALCULATOR_MIDDLE_ALIGNED_VERTICAL \
66 ARM_2D_LIST_CALCULATOR_MIDDLE_ALIGNED_VERTICAL
67
68#define ARM_2D_LIST_VIEW_CALCULATOR_MIDDLE_ALIGNED_HORIZONTAL \
69 ARM_2D_LIST_CALCULATOR_MIDDLE_ALIGNED_HORIZONTAL
70
71/*! @} */
72
73/*!
74 * \addtogroup gHelper 8 Helper Services
75 * @{
76 */
77/*============================ MACROFIED FUNCTIONS ===========================*/
78/*============================ TYPES =========================================*/
79
81
82
84
85/*!
86 * \brief runtime parameters passed to on-draw-list-item event handler
87 */
89 uint8_t bIsChecked : 1; /*!< is this item checked */
90 uint8_t bIsSelected : 1; /*!< is this item seleteced */
91 uint8_t chOpacity; /*!< opacity proposal */
92 uint16_t hwRatio; /*!< other ratio proposal */
94
95/*!
96 * \brief the prototype of On-Drawing-List-Item event handler
97 *
98 * \param[in] ptThis the current list core item object.
99 * \param[in] ptTile a tile for the virtual screen
100 * \param[in] bIsNewFrame a flag indicate the starting of a new frame
101 * \param[in] ptParam the runtime paramters
102 * \return arm_fsm_rt_t the status of the FSM.
103 */
105 arm_2d_list_item_t *ptThis,
106 const arm_2d_tile_t *ptTile,
107 bool bIsNewFrame,
108 arm_2d_list_item_param_t *ptParam);
109
110/*!
111 * \brief the list core item class
112 */
114
116 arm_2d_list_item_t *ptNext; /*!< list item pointer */
117)
118
119 uint16_t hwID; /*!< the ID used by the list iterator */
120
121 union {
122 uint16_t hwAttribute; /*!< 16bit attribute value */
123 struct {
124 uint16_t bIsEnabled : 1; /*!< whether this item is enabled or not */
125 uint16_t bIsVisible : 1; /*!< visibility */
126 uint16_t bIsReadOnly : 1; /*!< indicate whether this item is readonly or not */
127 uint16_t : 1; /*!< reserved */
128 uint16_t u4Alignment : 4; /*!< alignment: see ARM_2D_ALIGN_xxxx */
129 uint16_t : 8; /*!< reserved */
130 };
131 };
132 __arm_2d_list_core_t *ptListView; /*!< the parent list core */
133
134 struct {
135 int8_t chPrevious; /*!< padding between this item and the previous one */
136 int8_t chNext; /*!< padding between this item and the next one */
137 } Padding;
138
139 arm_2d_margin_t Margin;
140 arm_2d_size_t tSize; /*!< the size of the item */
141
142 uintptr_t pTarget; /*!< user specified object */
143 arm_2d_draw_list_item_handler_t *fnOnDrawItem; /*!< on-draw-list-view-item event handler */
144};
145
146
147/*!
148 * \brief intructions for how to move the list core item iterator
149 * \note For internal use only
150 */
151typedef enum {
152 __ARM_2D_LIST_GET_ITEM_WITH_ID_WITHOUT_MOVE_POINTER = 0,
153 __ARM_2D_LIST_GET_ITEM_AND_MOVE_POINTER,
154 __ARM_2D_LIST_GET_PREVIOUS,
155 __ARM_2D_LIST_GET_NEXT,
156
157 __ARM_2D_LIST_GET_FIRST_ITEM_WITHOUT_MOVE_POINTER,
158 __ARM_2D_LIST_GET_FIRST_ITEM,
159 __ARM_2D_LIST_GET_CURRENT,
160 __ARM_2D_LIST_GET_LAST_ITEM_WITHOUT_MOVE_POINTER,
161 __ARM_2D_LIST_GET_LAST_ITEM,
163
164/*!
165 * \brief the list core interator prototype
166 *
167 * \param[in] ptThis the target list core object
168 * \param[in] tDirection the direction for fetching a list item.
169 * \param[in] hwID the ID of the target item
170 * \return arm_2d_list_item_t* a list item
171 */
173 __arm_2d_list_core_t *ptThis,
175 uint_fast16_t hwID
176 );
177
178typedef enum {
179 ARM_2D_LIST_VERTICAL,
180 ARM_2D_LIST_HORIZONTAL,
181} arm_2d_list_dir_t;
182
183/*!
184 * \brief the target working area for one list core item
185 */
187 arm_2d_list_item_t *ptItem; /*!< the target item */
188 arm_2d_region_t tRegion; /*!< the target region on the list */
189 arm_2d_list_item_param_t tParam; /*!< paramters for the target item */
190 arm_2d_list_dir_t tDirection; /*!< list direction (only region calculator knows ) */
192
193
194/*!
195 * \brief the list region calculaor prototype
196 * \param[in] ptThis the target list core object
197 * \param[in] iOffset the offset in the list core
198 * \return __arm_2d_list_core_target_area_t* the working area for a target list core item
199 */
200typedef
202 __arm_2d_list_core_t *ptThis,
203 __arm_2d_list_item_iterator *fnIterator,
204 int32_t nOffset
205 );
206
207/*!
208 * \brief list core configuration structure
209 */
211 arm_2d_size_t tListSize; /*!< the size of the list */
212 __arm_2d_list_item_iterator *fnIterator; /*!< the item iterator */
213 __arm_2d_list_region_calculator_t *fnCalculator; /*!< the region calculator */
214 arm_2d_draw_list_item_handler_t *fnOnDrawListItemBackground; /*!< the On-Draw-List-Item-Background event handler */
215 arm_2d_helper_draw_handler_t *fnOnDrawListBackground; /*!< the On-Draw-List-Background event handler */
216 arm_2d_helper_draw_handler_t *fnOnDrawListCover; /*!< the On-Draw-List-Cover event handler */
217 int32_t nTotalLength; /*!< the total length of the list in pixel, 0 means update later */
218 arm_2d_list_item_t *ptItems; /*!< an optional pointer for items (array/list) */
219 uint16_t hwItemSizeInByte; /*!< the size of the item (in byte) */
220 uint16_t hwItemCount; /*!< the total number of items, 0 means update later */
221 uint16_t hwSwitchingPeriodInMs; /*!< A constant period (in ms) for switching item, zero means using default value */
222
223 uint16_t bDisableRingMode : 1; /*!< whether disable ring mode */
224
226
227/*!
228 * \brief the list core class
229 */
231
233 __arm_2d_list_core_cfg_t tCFG; /*!< list core configuration */
234)
235
236 struct {
237
239 arm_2d_tile_t tileTarget; /*!< the target draw area */
240 arm_2d_tile_t tileList; /*!< the target tile for the list */
241 __arm_2d_list_work_area_t tWorkingArea; /*!< the working area */
242 uint8_t bIsRegCalInit; /*!< indicate whether the region calcluator is initialized or not */
243 union {
244 struct {
245 uint16_t hwIndex; /*!< array iterator index */
246 } Array; /*!< array iterator */
247 /* put other iterator structure here
248 * ...
249 */
250 } Iterator; /*!< iterator control block */
251 )
252
253 ARM_PRIVATE(
254 arm_2d_tile_t tileItem; /*!< the target tile for list items */
255 int64_t lPeriod; /*!< time to run target distance */
256 int64_t lTimestamp; /*!< timestamp used by animation */
257 int32_t nOffset; /*!< list offset */
258 int32_t nStartOffset; /*!< the start offset */
259 int32_t nTargetOffset; /*!< the target list offset */
260 uint16_t hwSelection; /*!< item selection */
261 uint8_t chState; /*!< state used by list core task */
262 uint8_t bIsMoving : 1; /*!< a flag to indicate whether the list is moving */
263 uint8_t bNeedRedraw : 1; /*!< a flag to indicate whether a redraw is requested, this is a sticky flag */
264 uint8_t : 6; /*!< reserved */
265 struct {
266 int16_t iSteps; /*!< steps to move */
267 int32_t nFinishInMs; /*!< finish in ms */
268 } MoveReq;
269 )
270
271 } Runtime; /*!< list runtime */
272
274
275 uint8_t chState;
276 bool bListSizeChanged;
277 int16_t iStartOffset;
278 int32_t nOffset;
279
280 union {
281 struct {
282
283 int16_t iTopVisiableOffset;
284 uint16_t hwTopVisibleItemID;
285
286 int16_t iBottomVisibleOffset;
287 uint16_t hwBottomVisibleItemID;
288 } CalMidAligned;
289 };
290)
291
292};
293
294
295/*============================ GLOBAL VARIABLES ==============================*/
296
297/*!
298 * \brief a list calculator for vertical lists, which puts selected item
299 * in the centre of the target list
300 */
301extern
304
305/*!
306 * \brief a list calculator for horizontal lists, which puts selected item
307 * in the centre of the target list
308 */
309extern
312
313/*!
314 * \brief a list calculator for vertical lists, which puts selected item
315 * in the centre of the target list, item size is fixed and no status
316 * checking (i.e. visible or enabled).
317 */
318extern
321
322/*!
323 * \brief a list calculator for horizontal lists, which puts selected item
324 * in the centre of the target list, item size is fixed and no status
325 * checking (i.e. visible or enabled).
326 */
327extern
330
331/*!
332 * \brief a list iterator for the list that stores items in an array
333 */
335
336/*============================ LOCAL VARIABLES ===============================*/
337/*============================ PROTOTYPES ====================================*/
338
339/*!
340 * \brief initialize a target list core object
341 * \param[in] ptThis the target list core object
342 * \param[in] ptCFG the user specified configuration
343 * \return arm_2d_err_t the operation result
344 */
345extern
346ARM_NONNULL(1,2)
349
350/*!
351 * \brief show a given list core
352 * \param[in] ptThis the target list core object
353 * \param[in] ptTarget the target framebuffer
354 * \param[in] ptRegion the target region
355 * \param[in] bIsNewFrame a flag to indicate whether current iteration is the
356 * first one of a new frame.
357 * \return arm_fsm_rt_t the fsm status
358 */
359extern
360ARM_NONNULL(1,2)
362 const arm_2d_tile_t *ptTarget,
363 const arm_2d_region_t *ptRegion,
364 bool bIsNewFrame);
365
366/*!
367 * \brief request to move selection with specified steps
368 * \param[in] ptThis the target list core object
369 * \param[in] iSteps number of steps, here negative value means move to previous
370 * items and positive value means move to next items
371 * \note for current stage, ring mode is permanently enabled.
372 * \param[in] nFinishInMs
373 * - (nFinishInMs > 0) the list should turn to those
374 * steps in specified time (ms)
375 * - (nFinishInMs < 0) use the configuration passed at the
376 * initialisation stage.
377 * - (nFinishInMs == 0) do not change current configuration
378 */
379extern
380ARM_NONNULL(1)
382 int16_t iSteps,
383 int32_t nFinishInMs);
384
385/*!
386 * \brief move selection with specified pixel offset
387 * \param[in] ptThis the target list core object
388 * \param[in] iOffset number of pixels, here negative value means move to previous
389 * items and positive value means move to next items
390 * \note for current stage, ring mode is permanently enabled.
391 *
392 * \return arm_2d_err_t the operation result
393 */
394extern
395ARM_NONNULL(1)
397 int16_t iOffset);
398
399/*!
400 * \brief get the currently selected item id
401 *
402 * \param[in] ptThis the target list core object
403 * \return uint16_t the item ID
404 */
405extern
406ARM_NONNULL(1)
408
409/*!
410 * \brief get the currently selected item
411 *
412 * \param[in] ptThis the target list core object
413 * \return arm_2d_list_item_t* the selected item
414 */
415extern
416ARM_NONNULL(1)
418
419/*!
420 * \brief check whether the list need a redraw
421 *
422 * \param[in] ptThis the target list core object
423 * \param[in] bAutoreset a flag to indicate whether we have to clear the redraw flag
424 * automatically when calling this function.
425 * \return true the list need a redraw
426 * \return false the list has no change.
427 */
428extern
429ARM_NONNULL(1)
431
432/*!
433 * \brief check whether the list is moving its items
434 *
435 * \param[in] ptThis the target list core object
436 * \return true the list is moving
437 * \return false the list has no change.
438 */
439extern
440ARM_NONNULL(1)
442
443/*! @} */
444
445#if defined(__clang__)
446# pragma clang diagnostic pop
447#endif
448
449#ifdef __cplusplus
450}
451#endif
452
453#endif