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: 28. Dec 2024
25 * $Revision: V.2.3.1
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 : 5; /*!< reserved */
292
293 struct {
294 int16_t iSteps; /*!< steps to move */
295 int32_t nFinishInMs; /*!< finish in ms */
296 } MoveReq;
297 )
298
299 } Runtime; /*!< list runtime */
300
301ARM_PROTECTED(
302
303 uint8_t chState;
304 bool bListSizeChanged;
305 int16_t iStartOffset;
306 int32_t nOffset;
307
308 union {
309 struct {
310 int16_t iTopVisibleOffset;
311 uint16_t hwTopVisibleItemID;
312
313 int16_t iBottomVisibleOffset;
314 uint16_t hwBottomVisibleItemID;
315 } CalMidAligned;
316 };
317)
318
319};
320
321
322/*============================ GLOBAL VARIABLES ==============================*/
323
324/*!
325 * \brief a list calculator for vertical lists, which puts selected item
326 * in the centre of the target list
327 */
328extern
329arm_2d_i_list_region_calculator_t
330 ARM_2D_LIST_CALCULATOR_MIDDLE_ALIGNED_VERTICAL;
331
332/*!
333 * \brief a list calculator for horizontal lists, which puts selected item
334 * in the centre of the target list
335 */
336extern
337arm_2d_i_list_region_calculator_t
338 ARM_2D_LIST_CALCULATOR_MIDDLE_ALIGNED_HORIZONTAL;
339
340/*!
341 * \brief a list calculator for vertical lists, which puts selected item
342 * in the centre of the target list, item size is fixed and no status
343 * checking (i.e. visible or enabled).
344 */
345extern
346arm_2d_i_list_region_calculator_t
347ARM_2D_LIST_CALCULATOR_MIDDLE_ALIGNED_FIXED_SIZED_ITEM_NO_STATUS_CHECK_VERTICAL;
348
349/*!
350 * \brief a list calculator for horizontal lists, which puts selected item
351 * in the centre of the target list, item size is fixed and no status
352 * checking (i.e. visible or enabled).
353 */
354extern
355arm_2d_i_list_region_calculator_t
356ARM_2D_LIST_CALCULATOR_MIDDLE_ALIGNED_FIXED_SIZED_ITEM_NO_STATUS_CHECK_HORIZONTAL;
357
358/*!
359 * \brief a list calculator for vertical lists, which uses the normal water
360 * fall style
361 */
362extern
363arm_2d_i_list_region_calculator_t
364 ARM_2D_LIST_CALCULATOR_NORMAL_VERTICAL;
365
366/*!
367 * \brief a list calculator for horizontal lists, which uses the normal water
368 * fall style
369 */
370extern
371arm_2d_i_list_region_calculator_t
372 ARM_2D_LIST_CALCULATOR_NORMAL_HORIZONTAL;
373
374/*!
375 * \brief a list calculator for vertical lists, which uses the normal water
376 * fall style, item size is fixed and no status checking (i.e. visible
377 * or enabled).
378 */
379extern
380arm_2d_i_list_region_calculator_t
381ARM_2D_LIST_CALCULATOR_NORMAL_FIXED_SIZED_ITEM_NO_STATUS_CHECK_VERTICAL;
382
383/*!
384 * \brief a list calculator for horizontal lists, which uses the normal water
385 * fall style, item size is fixed and no status checking (i.e. visible
386 * or enabled).
387 */
388extern
389arm_2d_i_list_region_calculator_t
390ARM_2D_LIST_CALCULATOR_NORMAL_FIXED_SIZED_ITEM_NO_STATUS_CHECK_HORIZONTAL;
391
392/*!
393 * \brief a list iterator for the list that stores items in an array
394 */
395extern __arm_2d_list_item_iterator ARM_2D_LIST_ITERATOR_ARRAY;
396
397/*============================ LOCAL VARIABLES ===============================*/
398/*============================ PROTOTYPES ====================================*/
399
400/*!
401 * \brief initialize a target list core object
402 * \param[in] ptThis the target list core object
403 * \param[in] ptCFG the user specified configuration
404 * \return arm_2d_err_t the operation result
405 */
406extern
407ARM_NONNULL(1,2)
408arm_2d_err_t __arm_2d_list_core_init( __arm_2d_list_core_t *ptThis,
409 __arm_2d_list_core_cfg_t *ptCFG);
410
411/*!
412 * \brief get the size of the target list
413 *
414 * \param[in] ptThis the target list core object
415 * \return arm_2d_size_t the list size
416 */
417extern
418ARM_NONNULL(1)
419arm_2d_size_t __arm_2d_list_core_get_list_size(__arm_2d_list_core_t *ptThis);
420
421/*!
422 * \brief get the region for drawing the item selection indicator
423 *
424 * \param[in] ptThis the target list core object
425 * \param[in] ptRegionBuffer a region object for reading the result
426 * \return arm_2d_region_t* the address of the region buffer
427 */
428extern
429ARM_NONNULL(1,2)
430arm_2d_region_t *__arm_2d_list_core_get_selection_region(
431 __arm_2d_list_core_t *ptThis,
432 arm_2d_region_t *ptRegionBuffer);
433
434/*!
435 * \brief get the inner list tile
436 *
437 * \param[in] ptThis the target list core object
438 * \return arm_2d_tile_t* the inner list tile
439 */
440extern
441ARM_NONNULL(1)
442arm_2d_tile_t *__arm_2d_list_core_get_inner_tile(__arm_2d_list_core_t *ptThis);
443
444/*!
445 * \brief enable or disable the PI mode for the indicator
446 *
447 * \param[in] ptThis the target list core object
448 * \param[in] bEnable a boolean value to enable or disable the PI mode
449 * \param[in] ptNewCFG an optional new PI configuration
450 * \note If the PI mode has never been enabled before, when the first time of calling
451 * this function, the ptNewCFG must point to a valid configuration structure
452 *
453 * \return true the PI mode was previously enabled
454 * \return false the PI mode was previously disabled
455 */
456extern
457ARM_NONNULL(1)
458bool __arm_2d_list_core_indicator_pi_mode_config(
459 __arm_2d_list_core_t *ptThis,
460 bool bEnable,
461 arm_2d_helper_pi_slider_cfg_t *ptNewCFG);
462
463/*!
464 * \brief show a given list core
465 * \param[in] ptThis the target list core object
466 * \param[in] ptTarget the target framebuffer
467 * \param[in] ptRegion the target region
468 * \param[in] bIsNewFrame a flag to indicate whether current iteration is the
469 * first one of a new frame.
470 * \return arm_fsm_rt_t the fsm status
471 */
472extern
473ARM_NONNULL(1,2)
474arm_fsm_rt_t __arm_2d_list_core_show( __arm_2d_list_core_t *ptThis,
475 const arm_2d_tile_t *ptTarget,
476 const arm_2d_region_t *ptRegion,
477 bool bIsNewFrame);
478
479/*!
480 * \brief request to move selection with specified steps
481 * \param[in] ptThis the target list core object
482 * \param[in] iSteps number of steps, here negative value means move to previous
483 * items and positive value means move to next items
484 * \note for current stage, ring mode is permanently enabled.
485 * \param[in] nFinishInMs
486 * - (nFinishInMs > 0) the list should turn to those
487 * steps in specified time (ms)
488 * - (nFinishInMs < 0) use the configuration passed at the
489 * initialisation stage.
490 * - (nFinishInMs == 0) do not change current configuration
491 */
492extern
493ARM_NONNULL(1)
494void __arm_2d_list_core_move_request( __arm_2d_list_core_t *ptThis,
495 int16_t iSteps,
496 int32_t nFinishInMs);
497
498#if 0
499/*!
500 * \brief move selection with specified pixel offset
501 * \param[in] ptThis the target list core object
502 * \param[in] iOffset number of pixels, here negative value means move to previous
503 * items and positive value means move to next items
504 * \note for current stage, ring mode is permanently enabled.
505 *
506 * \return arm_2d_err_t the operation result
507 */
508extern
509ARM_NONNULL(1)
510void __arm_2d_list_core_move_offset(__arm_2d_list_core_t *ptThis,
511 int16_t iOffset);
512#endif
513
514/*!
515 * \brief get the currently selected item id
516 *
517 * \param[in] ptThis the target list core object
518 * \return uint16_t the item ID
519 */
520extern
521ARM_NONNULL(1)
522uint16_t __arm_2d_list_core_get_selected_item_id(__arm_2d_list_core_t *ptThis);
523
524/*!
525 * \brief get the currently selected item
526 *
527 * \param[in] ptThis the target list core object
528 * \return arm_2d_list_item_t* the selected item
529 */
530extern
531ARM_NONNULL(1)
532arm_2d_list_item_t *__arm_2d_list_core_get_selected_item(__arm_2d_list_core_t *ptThis);
533
534/*!
535 * \brief check whether the list need a redraw
536 *
537 * \param[in] ptThis the target list core object
538 * \param[in] bAutoreset a flag to indicate whether we have to clear the redraw flag
539 * automatically when calling this function.
540 * \return true the list need a redraw
541 * \return false the list has no change.
542 */
543extern
544ARM_NONNULL(1)
545bool __arm_2d_list_core_need_redraw(__arm_2d_list_core_t *ptThis, bool bAutoreset);
546
547/*!
548 * \brief check whether the list is moving its items
549 *
550 * \param[in] ptThis the target list core object
551 * \return true the list is moving
552 * \return false the list has no change.
553 */
554extern
555ARM_NONNULL(1)
556bool __arm_2d_list_core_is_list_moving(__arm_2d_list_core_t *ptThis);
557
558/*!
559 * \brief check whether the list is scrolling or not
560 *
561 * \param[in] ptThis the target list core object
562 * \return true the list is scrolling
563 * \return false the list isn't scrolling.
564 */
565extern
566ARM_NONNULL(1)
567bool __arm_2d_list_core_is_list_scrolling(__arm_2d_list_core_t *ptThis);
568
569extern
570ARM_NONNULL(1,2)
571/*!
572 * \brief get list item with a specified direction instruction
573 *
574 * \param[in] ptThis the target list core object
575 * \param[in] fnIterator a list iterator
576 * \param[in] tDirection the direction instruction
577 * \param[in] hwID the item ID (when required by the direction instruction)
578 * \param[in] bIgnoreStatusCheck whether ignore the status checking
579 * \param[in] bForceRingMode whether force to enable ring mode anyway
580 * \return arm_2d_list_item_t*
581 */
582arm_2d_list_item_t *__arm_2d_list_core_get_item(
583 __arm_2d_list_core_t *ptThis,
584 __arm_2d_list_item_iterator *fnIterator,
585 arm_2d_list_iterator_dir_t tDirection,
586 uint16_t hwID,
587 bool bIgnoreStatusCheck,
588 bool bForceRingMode);
589
590/*! @} */
591
592#if defined(__clang__)
593# pragma clang diagnostic pop
594#endif
595
596#ifdef __cplusplus
597}
598#endif
599
600#endif