Arm-2D  
2D Image Processing Library for Cortex-M Processors
 
Loading...
Searching...
No Matches
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: 21 Oct 2025
25 * $Revision: V.2.4.2
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 * \addtogroup Deprecated
62 * @{
63 */
64#define ARM_2D_LIST_VIEW_CALCULATOR_MIDDLE_ALIGNED_VERTICAL \
65 ARM_2D_LIST_CALCULATOR_MIDDLE_ALIGNED_VERTICAL
66
67#define ARM_2D_LIST_VIEW_CALCULATOR_MIDDLE_ALIGNED_HORIZONTAL \
68 ARM_2D_LIST_CALCULATOR_MIDDLE_ALIGNED_HORIZONTAL
69
70#define __arm_2d_list_region_calculator_t \
71 arm_2d_i_list_region_calculator_t
72
73/*! @} */
74
75/*!
76 * \addtogroup gHelper 8 Helper Services
77 * @{
78 */
79/*============================ MACROFIED FUNCTIONS ===========================*/
80/*============================ TYPES =========================================*/
81
82typedef struct __arm_2d_list_core_t __arm_2d_list_core_t;
83
84
85typedef struct arm_2d_list_item_t arm_2d_list_item_t;
86
87/*!
88 * \brief runtime parameters passed to on-draw-list-item event handler
89 */
90typedef struct arm_2d_list_item_param_t {
91 uint8_t bIsChecked : 1; /*!< is this item checked */
92 uint8_t bIsSelected : 1; /*!< is this item seleteced */
93 uint8_t : 6; /*!< reserved */
94 uint8_t chOpacity; /*!< opacity proposal */
95 uint16_t hwRatio; /*!< other ratio proposal */
96} arm_2d_list_item_param_t;
97
98/*!
99 * \brief the prototype of On-Drawing-List-Item event handler
100 *
101 * \param[in] ptThis the current list core item object.
102 * \param[in] ptTile a tile for the virtual screen
103 * \param[in] bIsNewFrame a flag indicate the starting of a new frame
104 * \param[in] ptParam the runtime paramters
105 * \return arm_fsm_rt_t the status of the FSM.
106 */
107typedef arm_fsm_rt_t arm_2d_draw_list_item_handler_t(
108 arm_2d_list_item_t *ptThis,
109 const arm_2d_tile_t *ptTile,
110 bool bIsNewFrame,
111 arm_2d_list_item_param_t *ptParam);
112
113/*!
114 * \brief the list core item class
115 */
116struct arm_2d_list_item_t {
117
118ARM_PROTECTED(
119 arm_2d_list_item_t *ptNext; /*!< list item pointer */
120)
121
122 uint16_t hwID; /*!< the ID used by the list iterator */
123
124 union {
125 uint16_t hwAttribute; /*!< 16bit attribute value */
126 struct {
127 uint16_t bIsEnabled : 1; /*!< whether this item is enabled or not */
128 uint16_t bIsVisible : 1; /*!< visibility */
129 uint16_t bIsReadOnly : 1; /*!< indicate whether this item is readonly or not */
130 uint16_t : 1; /*!< reserved */
131 uint16_t u4Alignment : 4; /*!< alignment: see ARM_2D_ALIGN_xxxx */
132 uint16_t : 8; /*!< reserved */
133 };
134 };
135
136 __arm_2d_list_core_t *ptListView; /*!< the parent list core */
137 arm_2d_draw_list_item_handler_t *fnOnDrawItem; /*!< on-draw-list-view-item event handler */
138
139 struct {
140 int8_t chPrevious; /*!< padding between this item and the previous one */
141 int8_t chNext; /*!< padding between this item and the next one */
142 } Padding;
143
144 arm_2d_margin_t Margin;
145 arm_2d_size_t tSize; /*!< the size of the item */
146
147 uintptr_t pTarget; /*!< user specified object */
148};
149
150
151/*!
152 * \brief intructions for how to move the list core item iterator
153 * \note For internal use only
154 */
155typedef enum {
156 __ARM_2D_LIST_GET_ITEM_WITH_ID_WITHOUT_MOVE_POINTER = 0,
157 __ARM_2D_LIST_GET_ITEM_AND_MOVE_POINTER,
158 __ARM_2D_LIST_GET_PREVIOUS,
159 __ARM_2D_LIST_GET_NEXT,
160
161 __ARM_2D_LIST_GET_FIRST_ITEM_WITHOUT_MOVE_POINTER,
162 __ARM_2D_LIST_GET_FIRST_ITEM,
163 __ARM_2D_LIST_GET_CURRENT,
164 __ARM_2D_LIST_GET_LAST_ITEM_WITHOUT_MOVE_POINTER,
165 __ARM_2D_LIST_GET_LAST_ITEM,
166} arm_2d_list_iterator_dir_t;
167
168/*!
169 * \brief the list core interator prototype
170 *
171 * \param[in] ptThis the target list core object
172 * \param[in] tDirection the direction for fetching a list item.
173 * \param[in] hwID the ID of the target item
174 * \return arm_2d_list_item_t* a list item
175 */
176typedef arm_2d_list_item_t *__arm_2d_list_item_iterator(
177 __arm_2d_list_core_t *ptThis,
178 arm_2d_list_iterator_dir_t tDirection,
179 uint_fast16_t hwID
180 );
181
182typedef enum {
183 ARM_2D_LIST_VERTICAL,
184 ARM_2D_LIST_HORIZONTAL,
185} arm_2d_list_dir_t;
186
187/*!
188 * \brief the target working area for one list core item
189 */
190typedef struct __arm_2d_list_work_area_t {
191 arm_2d_list_item_t *ptItem; /*!< the target item */
192 arm_2d_region_t tRegion; /*!< the target region on the list */
193 arm_2d_list_item_param_t tParam; /*!< paramters for the target item */
194 arm_2d_list_dir_t tDirection; /*!< list direction (only region calculator knows ) */
195} __arm_2d_list_work_area_t;
196
197
198/*!
199 * \brief the list region calculaor prototype
200 * \param[in] ptThis the target list core object
201 * \param[in] iOffset the offset in the list core
202 * \return __arm_2d_list_core_target_area_t* the working area for a target list core item
203 */
204typedef const struct arm_2d_i_list_region_calculator_t {
205 __arm_2d_list_work_area_t *(*fnCalculator)(
206 __arm_2d_list_core_t *ptThis,
207 __arm_2d_list_item_iterator *fnIterator,
208 int32_t nOffset
209 );
210 int16_t (*fnSelectionCompensation)(__arm_2d_list_core_t *ptThis,
211 arm_2d_list_item_t *ptItem);
212 arm_2d_list_dir_t tDirection;
213} arm_2d_i_list_region_calculator_t;
214
215/*!
216 * \brief list core configuration structure
217 */
218typedef struct __arm_2d_list_core_cfg_t {
219 arm_2d_size_t tListSize; /*!< the size of the list */
220 __arm_2d_list_item_iterator *fnIterator; /*!< the item iterator */
221 union {
222 arm_2d_i_list_region_calculator_t *ptCalculator; /*!< the region calculator */
223 arm_2d_i_list_region_calculator_t *fnCalculator; /*!< deprecated alias */
224 };
225 arm_2d_draw_list_item_handler_t *fnOnDrawListItemBackground; /*!< the On-Draw-List-Item-Background event handler */
226 arm_2d_helper_draw_handler_t *fnOnDrawListBackground; /*!< the On-Draw-List-Background event handler */
227 arm_2d_helper_draw_handler_t *fnOnDrawListCover; /*!< the On-Draw-List-Cover event handler */
228
229 int32_t nTotalLength; /*!< the total length of the list in pixel, 0 means update later */
230 arm_2d_list_item_t *ptItems; /*!< an optional pointer for items (array/list) */
231 uint16_t hwItemSizeInByte; /*!< the size of the item (in byte) */
232 uint16_t hwItemCount; /*!< the total number of items, 0 means update later */
233 uint16_t hwSwitchingPeriodInMs; /*!< A constant period (in ms) for switching item, zero means using default value */
234
235 uint16_t bDisableRingMode : 1; /*!< whether disable ring mode */
236 uint16_t bDisableStatusCheck : 1; /*!< whether disable the item status */
237 uint16_t bUsePISliderForSelectionIndicator : 1;
238 uint16_t : 5;
239 uint16_t : 8;
240
241 arm_2d_helper_pi_slider_cfg_t *ptPISliderCFG; /*!< the configuration for PI slider */
242} __arm_2d_list_core_cfg_t;
243
244/*!
245 * \brief the list core class
246 */
247struct __arm_2d_list_core_t {
248
249ARM_PROTECTED(
250 __arm_2d_list_core_cfg_t tCFG; /*!< list core configuration */
251)
252
253 struct {
254
255 ARM_PROTECTED(
256 arm_2d_tile_t tileTarget; /*!< the target draw area */
257 arm_2d_tile_t tileList; /*!< the target tile for the list */
258 __arm_2d_list_work_area_t tWorkingArea; /*!< the working area */
259 uint8_t bIsRegCalInit : 1; /*!< indicate whether the region calcluator is initialized or not */
260 uint8_t : 7;
261 union {
262 struct {
263 uint16_t hwIndex; /*!< array iterator index */
264 } Array; /*!< array iterator */
265 /* put other iterator structure here
266 * ...
267 */
268 } Iterator; /*!< iterator control block */
269
270 )
271
272 ARM_PRIVATE(
273 arm_2d_tile_t tileItem; /*!< the target tile for list items */
274 int64_t lPeriod; /*!< time to run target distance */
275 int64_t lTimestamp; /*!< timestamp used by animation */
276
277 arm_2d_helper_pi_slider_t tPISlider; /*!< PI slider for generating movement animation */
278
279 struct {
280 int32_t nOffset; /*!< list offset */
281 int32_t nStartOffset; /*!< the start offset */
282 int32_t nTargetOffset; /*!< the target list offset */
283 arm_2d_region_t tRegion;
284 } Selection;
285
286 uint16_t hwSelection; /*!< item selection */
287 uint8_t chState; /*!< state used by list core task */
288 uint8_t bIsMoving : 1; /*!< a flag to indicate whether the list is moving */
289 uint8_t bNeedRedraw : 1; /*!< a flag to indicate whether a redraw is requested, this is a sticky flag */
290 uint8_t bScrolling : 1; /*!< a flag to indicate whether the list is scrolling or not */
291 uint8_t bListSizeChanged : 1; /*!< a flag to indicate the list size has been changed */
292 uint8_t : 4; /*!< reserved */
293
294 struct {
295 int16_t iSteps; /*!< steps to move */
296 int32_t nFinishInMs; /*!< finish in ms */
297 } MoveReq;
298 )
299
300 } Runtime; /*!< list runtime */
301
302ARM_PROTECTED(
303
304 uint8_t chState;
305 uint8_t chDrawingState;
306 int16_t iStartOffset;
307 int32_t nOffset;
308
309 union {
310 struct {
311 int16_t iTopVisibleOffset;
312 uint16_t hwTopVisibleItemID;
313 uint16_t hwTopDistance;
314
315 int16_t iBottomVisibleOffset;
316 uint16_t hwBottomVisibleItemID;
317 uint16_t hwBottomDistance;
318 } CalMidAligned;
319 };
320)
321
322};
323
324
325/*============================ GLOBAL VARIABLES ==============================*/
326
327/*!
328 * \brief a list calculator for vertical lists, which puts selected item
329 * in the centre of the target list
330 */
331extern
332arm_2d_i_list_region_calculator_t
333 ARM_2D_LIST_CALCULATOR_MIDDLE_ALIGNED_VERTICAL;
334
335/*!
336 * \brief a list calculator for horizontal lists, which puts selected item
337 * in the centre of the target list
338 */
339extern
340arm_2d_i_list_region_calculator_t
341 ARM_2D_LIST_CALCULATOR_MIDDLE_ALIGNED_HORIZONTAL;
342
343/*!
344 * \brief a list calculator for vertical lists, which puts selected item
345 * in the centre of the target list, item size is fixed and no status
346 * checking (i.e. visible or enabled).
347 */
348extern
349arm_2d_i_list_region_calculator_t
350ARM_2D_LIST_CALCULATOR_MIDDLE_ALIGNED_FIXED_SIZED_ITEM_NO_STATUS_CHECK_VERTICAL;
351
352/*!
353 * \brief a list calculator for horizontal lists, which puts selected item
354 * in the centre of the target list, item size is fixed and no status
355 * checking (i.e. visible or enabled).
356 */
357extern
358arm_2d_i_list_region_calculator_t
359ARM_2D_LIST_CALCULATOR_MIDDLE_ALIGNED_FIXED_SIZED_ITEM_NO_STATUS_CHECK_HORIZONTAL;
360
361/*!
362 * \brief a list calculator for vertical lists, which uses the normal water
363 * fall style
364 */
365extern
366arm_2d_i_list_region_calculator_t
367 ARM_2D_LIST_CALCULATOR_NORMAL_VERTICAL;
368
369/*!
370 * \brief a list calculator for horizontal lists, which uses the normal water
371 * fall style
372 */
373extern
374arm_2d_i_list_region_calculator_t
375 ARM_2D_LIST_CALCULATOR_NORMAL_HORIZONTAL;
376
377/*!
378 * \brief a list calculator for vertical lists, which uses the normal water
379 * fall style, item size is fixed and no status checking (i.e. visible
380 * or enabled).
381 */
382extern
383arm_2d_i_list_region_calculator_t
384ARM_2D_LIST_CALCULATOR_NORMAL_FIXED_SIZED_ITEM_NO_STATUS_CHECK_VERTICAL;
385
386/*!
387 * \brief a list calculator for horizontal lists, which uses the normal water
388 * fall style, item size is fixed and no status checking (i.e. visible
389 * or enabled).
390 */
391extern
392arm_2d_i_list_region_calculator_t
393ARM_2D_LIST_CALCULATOR_NORMAL_FIXED_SIZED_ITEM_NO_STATUS_CHECK_HORIZONTAL;
394
395/*!
396 * \brief a list iterator for the list that stores items in an array
397 */
398extern __arm_2d_list_item_iterator ARM_2D_LIST_ITERATOR_ARRAY;
399
400/*============================ LOCAL VARIABLES ===============================*/
401/*============================ PROTOTYPES ====================================*/
402
403/*!
404 * \brief initialize a target list core object
405 * \param[in] ptThis the target list core object
406 * \param[in] ptCFG the user specified configuration
407 * \return arm_2d_err_t the operation result
408 */
409extern
410ARM_NONNULL(1,2)
411arm_2d_err_t __arm_2d_list_core_init( __arm_2d_list_core_t *ptThis,
412 __arm_2d_list_core_cfg_t *ptCFG);
413
414/*!
415 * \brief get the size of the target list
416 *
417 * \param[in] ptThis the target list core object
418 * \return arm_2d_size_t the list size
419 */
420extern
421ARM_NONNULL(1)
422arm_2d_size_t __arm_2d_list_core_get_list_size(__arm_2d_list_core_t *ptThis);
423
424/*!
425 * \brief get the region for drawing the item selection indicator
426 *
427 * \param[in] ptThis the target list core object
428 * \param[in] ptRegionBuffer a region object for reading the result
429 * \return arm_2d_region_t* the address of the region buffer
430 */
431extern
432ARM_NONNULL(1,2)
433arm_2d_region_t *__arm_2d_list_core_get_selection_region(
434 __arm_2d_list_core_t *ptThis,
435 arm_2d_region_t *ptRegionBuffer);
436
437/*!
438 * \brief get the inner list tile
439 *
440 * \param[in] ptThis the target list core object
441 * \return arm_2d_tile_t* the inner list tile
442 */
443extern
444ARM_NONNULL(1)
445arm_2d_tile_t *__arm_2d_list_core_get_inner_tile(__arm_2d_list_core_t *ptThis);
446
447/*!
448 * \brief enable or disable the PI mode for the indicator
449 *
450 * \param[in] ptThis the target list core object
451 * \param[in] bEnable a boolean value to enable or disable the PI mode
452 * \param[in] ptNewCFG an optional new PI configuration
453 * \note If the PI mode has never been enabled before, when the first time of calling
454 * this function, the ptNewCFG must point to a valid configuration structure
455 *
456 * \return true the PI mode was previously enabled
457 * \return false the PI mode was previously disabled
458 */
459extern
460ARM_NONNULL(1)
461bool __arm_2d_list_core_indicator_pi_mode_config(
462 __arm_2d_list_core_t *ptThis,
463 bool bEnable,
464 arm_2d_helper_pi_slider_cfg_t *ptNewCFG);
465
466/*!
467 * \brief show a given list core
468 * \param[in] ptThis the target list core object
469 * \param[in] ptTarget the target framebuffer
470 * \param[in] ptRegion the target region
471 * \param[in] bIsNewFrame a flag to indicate whether current iteration is the
472 * first one of a new frame.
473 * \return arm_fsm_rt_t the fsm status
474 */
475extern
476ARM_NONNULL(1,2)
477arm_fsm_rt_t __arm_2d_list_core_show( __arm_2d_list_core_t *ptThis,
478 const arm_2d_tile_t *ptTarget,
479 const arm_2d_region_t *ptRegion,
480 bool bIsNewFrame);
481
482/*!
483 * \brief request to move selection with specified steps
484 * \param[in] ptThis the target list core object
485 * \param[in] iSteps number of steps, here negative value means move to previous
486 * items and positive value means move to next items
487 * \note for current stage, ring mode is permanently enabled.
488 * \param[in] nFinishInMs
489 * - (nFinishInMs > 0) the list should turn to those
490 * steps in specified time (ms)
491 * - (nFinishInMs < 0) use the configuration passed at the
492 * initialisation stage.
493 * - (nFinishInMs == 0) do not change current configuration
494 */
495extern
496ARM_NONNULL(1)
497void __arm_2d_list_core_move_request( __arm_2d_list_core_t *ptThis,
498 int16_t iSteps,
499 int32_t nFinishInMs);
500
501#if 0
502/*!
503 * \brief move selection with specified pixel offset
504 * \param[in] ptThis the target list core object
505 * \param[in] iOffset number of pixels, here negative value means move to previous
506 * items and positive value means move to next items
507 * \note for current stage, ring mode is permanently enabled.
508 *
509 * \return arm_2d_err_t the operation result
510 */
511extern
512ARM_NONNULL(1)
513void __arm_2d_list_core_move_offset(__arm_2d_list_core_t *ptThis,
514 int16_t iOffset);
515#endif
516
517/*!
518 * \brief get the currently selected item id
519 *
520 * \param[in] ptThis the target list core object
521 * \return uint16_t the item ID
522 */
523extern
524ARM_NONNULL(1)
525uint16_t __arm_2d_list_core_get_selected_item_id(__arm_2d_list_core_t *ptThis);
526
527/*!
528 * \brief get the currently selected item
529 *
530 * \param[in] ptThis the target list core object
531 * \return arm_2d_list_item_t* the selected item
532 */
533extern
534ARM_NONNULL(1)
535arm_2d_list_item_t *__arm_2d_list_core_get_selected_item(__arm_2d_list_core_t *ptThis);
536
537/*!
538 * \brief check whether the list need a redraw
539 *
540 * \param[in] ptThis the target list core object
541 * \param[in] bAutoreset a flag to indicate whether we have to clear the redraw flag
542 * automatically when calling this function.
543 * \return true the list need a redraw
544 * \return false the list has no change.
545 */
546extern
547ARM_NONNULL(1)
548bool __arm_2d_list_core_need_redraw(__arm_2d_list_core_t *ptThis, bool bAutoreset);
549
550/*!
551 * \brief check whether the list is moving its items
552 *
553 * \param[in] ptThis the target list core object
554 * \return true the list is moving
555 * \return false the list has no change.
556 */
557extern
558ARM_NONNULL(1)
559bool __arm_2d_list_core_is_list_moving(__arm_2d_list_core_t *ptThis);
560
561/*!
562 * \brief check whether the list is scrolling or not
563 *
564 * \param[in] ptThis the target list core object
565 * \return true the list is scrolling
566 * \return false the list isn't scrolling.
567 */
568extern
569ARM_NONNULL(1)
570bool __arm_2d_list_core_is_list_scrolling(__arm_2d_list_core_t *ptThis);
571
572extern
573ARM_NONNULL(1,2)
574/*!
575 * \brief get list item with a specified direction instruction
576 *
577 * \param[in] ptThis the target list core object
578 * \param[in] fnIterator a list iterator
579 * \param[in] tDirection the direction instruction
580 * \param[in] hwID the item ID (when required by the direction instruction)
581 * \param[in] bIgnoreStatusCheck whether ignore the status checking
582 * \param[in] bForceRingMode whether force to enable ring mode anyway
583 * \return arm_2d_list_item_t*
584 */
585arm_2d_list_item_t *__arm_2d_list_core_get_item(
586 __arm_2d_list_core_t *ptThis,
587 __arm_2d_list_item_iterator *fnIterator,
588 arm_2d_list_iterator_dir_t tDirection,
589 uint16_t hwID,
590 bool bIgnoreStatusCheck,
591 bool bForceRingMode);
592
593/*! @} */
594
595#if defined(__clang__)
596# pragma clang diagnostic pop
597#endif
598
599#ifdef __cplusplus
600}
601#endif
602
603#endif