nanocoat/include/lib/scritchui/scritchui.h

   1 /* -*- Mode: C; indent-tabs-mode: t; tab-width: 4 -*-
   2 // ---------------------------------------------------------------------------
   3 // SquirrelJME
   4 //     Copyright (C) Stephanie Gawroriski <xer@multiphasicapps.net>
   5 // ---------------------------------------------------------------------------
   6 // SquirrelJME is under the Mozilla Public License Version 2.0.
   7 // See license.mkd for licensing and copyright information.
   8 // -------------------------------------------------------------------------*/
   9
  10 /**
  11  * ScritchUI Library Header.
  12  *
  13  * @since 2024/03/27
  14  */
  15
  16 #ifndef SQUIRRELJME_SCRITCHUI_H
  17 #define SQUIRRELJME_SCRITCHUI_H
  18
  19 #include "sjme/config.h"
  20 #include "sjme/multithread.h"
  21 #include "sjme/tokenUtils.h"
  22 #include "sjme/gfxConst.h"
  23 #include "sjme/stdTypes.h"
  24 #include "sjme/list.h"
  25 #include "sjme/native.h"
  26 #include "lib/scritchinput/scritchinput.h"
  27 #include "sjme/alloc.h"
  28 #include "sjme/dylib.h"
  29
  30 /* Anti-C++. */
  31 #ifdef __cplusplus
  32         #ifndef SJME_CXX_IS_EXTERNED
  33                 #define SJME_CXX_IS_EXTERNED
  34                 #define SJME_CXX_SQUIRRELJME_SCRITCHUI_H
  35 extern "C" {
  36         #endif /* #ifdef SJME_CXX_IS_EXTERNED */
  37 #endif     /* #ifdef __cplusplus */
  38
  39 /*--------------------------------------------------------------------------*/
  40
  41 /**
  42  * Represents the type that this is.
  43  *
  44  * @since 2024/04/02
  45  */
  46 typedef enum sjme_scritchui_uiType
  47 {
  48         /** Reserved. */
  49         SJME_SCRITCHUI_TYPE_RESERVED,
  50
  51         /** Font. */
  52         SJME_SCRITCHUI_TYPE_FONT,
  53
  54         /** List. */
  55         SJME_SCRITCHUI_TYPE_LIST,
  56
  57         /** Menu. */
  58         SJME_SCRITCHUI_TYPE_MENU,
  59
  60         /** Menu bar. */
  61         SJME_SCRITCHUI_TYPE_MENU_BAR,
  62
  63         /** Menu item. */
  64         SJME_SCRITCHUI_TYPE_MENU_ITEM,
  65
  66         /** Panel. */
  67         SJME_SCRITCHUI_TYPE_PANEL,
  68
  69         /** Pencil. */
  70         SJME_SCRITCHUI_TYPE_PENCIL,
  71
  72         /** Root state. */
  73         SJME_SCRITCHUI_TYPE_ROOT_STATE,
  74
  75         /** Screen. */
  76         SJME_SCRITCHUI_TYPE_SCREEN,
  77
  78         /** Scroll Panel. */
  79         SJME_SCRITCHUI_TYPE_SCROLL_PANEL,
  80
  81         /** Window. */
  82         SJME_SCRITCHUI_TYPE_WINDOW,
  83
  84         /** The number of possible types. */
  85         SJME_NUM_SCRITCHUI_UI_TYPES
  86 } sjme_scritchui_uiType;
  87
  88 /** Generic cast check. */
  89 #define SJME_SUI_CAST(uiType, type, v) \
  90         ((type)sjme_scritchui_checkCast((type), (v)))
  91
  92 /** Common type. */
  93 #define SJME_SUI_CAST_COMMON(v) \
  94         ((sjme_scritchui_uiCommon)(v))
  95
  96 /** Check cast to menu kind. */
  97 #define SJME_SUI_CAST_MENU_KIND(v) \
  98         ((sjme_scritchui_uiMenuKind)sjme_scritchui_checkCast_menuKind((v)))
  99
 100 /** Check cast to component kind. */
 101 #define SJME_SUI_CAST_COMPONENT(v) \
 102         ((sjme_scritchui_uiComponent)sjme_scritchui_checkCast_component((v)))
 103
 104 /** Check cast to panel. */
 105 #define SJME_SUI_CAST_PANEL(v) \
 106         SJME_SUI_CAST(SJME_SCRITCHUI_TYPE_PANEL, \
 107         sjme_scritchui_uiPanel, (v))
 108
 109 /** Check cast to menu. */
 110 #define SJME_SUI_CAST_MENU(v) \
 111         SJME_SUI_CAST(SJME_SCRITCHUI_TYPE_MENU, \
 112         sjme_scritchui_uiMenu, (v))
 113
 114 /** Check cast to menu bar. */
 115 #define SJME_SUI_CAST_MENU_BAR(v) \
 116         SJME_SUI_CAST(SJME_SCRITCHUI_TYPE_MENU_BAR, \
 117         sjme_scritchui_uiMenuBar, (v))
 118
 119 /** Check cast to menu item. */
 120 #define SJME_SUI_CAST_MENU_ITEM(v) \
 121         SJME_SUI_CAST(SJME_SCRITCHUI_TYPE_MENU_Item, \
 122         sjme_scritchui_uiMenuItem, (v))
 123
 124 /**
 125  * An opaque native handle.
 126  *
 127  * @since 2024/04/02
 128  */
 129 typedef sjme_pointer sjme_scritchui_handle;
 130
 131 /**
 132  * API Flags for ScritchUI.
 133  *
 134  * @since 2024/03/29
 135  */
 136 typedef enum sjme_scritchui_apiFlag
 137 {
 138         /** Only panels are supported for this interface. */
 139         SJME_SCRITCHUI_API_FLAG_PANEL_ONLY = 1,
 140 } sjme_scritchui_apiFlag;
 141
 142 /**
 143  * Which type of screen update has occurred?
 144  *
 145  * @since 2024/04/09
 146  */
 147 typedef enum sjme_scritchui_screenUpdateType
 148 {
 149         /** Unknown. */
 150         SJME_SCRITCHUI_SCREEN_UPDATE_UNKNOWN,
 151
 152         /** New screen. */
 153         SJME_SCRITCHUI_SCREEN_UPDATE_NEW,
 154
 155         /** Deleted screen. */
 156         SJME_SCRITCHUI_SCREEN_UPDATE_DELETED,
 157
 158         /** Updated screen (resolution, color, etc.) */
 159         SJME_SCRITCHUI_SCREEN_UPDATE_CHANGED,
 160
 161         /** The number of update types. */
 162         SJME_SCRITCHUI_NUM_SCREEN_UPDATE
 163 } sjme_scritchui_screenUpdateType;
 164
 165 /**
 166  * The type of window manager that is used.
 167  *
 168  * @since 2024/04/15
 169  */
 170 typedef enum sjme_scritchui_windowManagerType
 171 {
 172         /** One frame per screen. */
 173         SJME_SCRITCHUI_WM_TYPE_ONE_FRAME_PER_SCREEN = 0,
 174
 175         /** Standard desktop interface. */
 176         SJME_SCRITCHUI_WM_TYPE_STANDARD_DESKTOP = 1,
 177
 178         /** The number of window manager types. */
 179         SJME_SCRITCHUI_NUM_WM_TYPES
 180 } sjme_scritchui_windowManagerType;
 181
 182 /**
 183  * Font style for pencil fonts.
 184  *
 185  * @since 2024/06/13
 186  */
 187 typedef enum sjme_scritchui_pencilFontStyle
 188 {
 189         /** Bold text. */
 190         SJME_SCRITCHUI_PENCIL_FONT_STYLE_BOLD = 1,
 191
 192         /** Italic (slanted) text. */
 193         SJME_SCRITCHUI_PENCIL_FONT_STYLE_ITALIC = 2,
 194
 195         /** Underlined text. */
 196         SJME_SCRITCHUI_PENCIL_FONT_STYLE_UNDERLINED = 4,
 197
 198         /** All styles. */
 199         SJME_SCRITCHUI_PENCIL_FONT_STYLE_ALL =
 200                 SJME_SCRITCHUI_PENCIL_FONT_STYLE_BOLD |
 201                 SJME_SCRITCHUI_PENCIL_FONT_STYLE_ITALIC |
 202                 SJME_SCRITCHUI_PENCIL_FONT_STYLE_UNDERLINED,
 203 } sjme_scritchui_pencilFontStyle;
 204
 205 /**
 206  * Represents the type of choice that a choice selection may be.
 207  *
 208  * @since 2024/07/17
 209  */
 210 typedef enum sjme_scritchui_choiceType
 211 {
 212         /** Only one element may be selected at a time. */
 213         SJME_SCRITCHUI_CHOICE_TYPE_EXCLUSIVE = 0,
 214
 215         /**
 216          * The item that is focused is always the only one selected, pressing an
 217          * action key (like enter/space) will activate the item.
 218          */
 219         SJME_SCRITCHUI_CHOICE_TYPE_IMPLICIT = 1,
 220
 221         /** Any number of items may be selected. */
 222         SJME_SCRITCHUI_CHOICE_TYPE_MULTIPLE = 2,
 223
 224         /** The number of choice types. */
 225         SJME_SCRITCHUI_NUM_CHOICE_TYPES = 3,
 226 } sjme_scritchui_choiceType;
 227
 228 /**
 229  * The element color type for look and feel.
 230  *
 231  * @since 2024/07/27
 232  */
 233 typedef enum sjme_scritchui_lafElementColorType
 234 {
 235         /** Background color. */
 236         SJME_SCRITCHUI_LAF_ELEMENT_COLOR_BACKGROUND = 0,
 237
 238         /** Border color. */
 239         SJME_SCRITCHUI_LAF_ELEMENT_COLOR_BORDER = 1,
 240
 241         /** Foreground color. */
 242         SJME_SCRITCHUI_LAF_ELEMENT_COLOR_FOREGROUND = 2,
 243
 244         /** Highlighted background color. */
 245         SJME_SCRITCHUI_LAF_ELEMENT_COLOR_HIGHLIGHTED_BACKGROUND = 3,
 246
 247         /** Highlighted border color. */
 248         SJME_SCRITCHUI_LAF_ELEMENT_COLOR_HIGHLIGHTED_BORDER = 4,
 249
 250         /** Highlighted foreground color. */
 251         SJME_SCRITCHUI_LAF_ELEMENT_COLOR_HIGHLIGHTED_FOREGROUND = 5,
 252
 253         /** Focus border. */
 254         SJME_SCRITCHUI_LAF_ELEMENT_COLOR_FOCUS_BORDER = 6,
 255
 256         /** Panel background color. */
 257         SJME_SCRITCHUI_LAF_ELEMENT_COLOR_PANEL_BACKGROUND = 7,
 258
 259         /** Panel foreground color. */
 260         SJME_SCRITCHUI_LAF_ELEMENT_COLOR_PANEL_FOREGROUND = 8,
 261
 262         /** Top accent color. */
 263         SJME_SCRITCHUI_LAF_ELEMENT_COLOR_ACCENT_TOP = 9,
 264
 265         /** Bottom accent color. */
 266         SJME_SCRITCHUI_LAF_ELEMENT_COLOR_ACCENT_BOTTOM = 10,
 267
 268         /** The number of element colors. */
 269         SJME_SCRITCHUI_NUM_LAF_ELEMENT_COLOR = 11,
 270 } sjme_scritchui_lafElementColorType;
 271
 272 /**
 273  * Represents a point.
 274  *
 275  * @since 2024/07/12
 276  */
 277 typedef struct sjme_scritchui_point
 278 {
 279         /** X coordinate. */
 280         sjme_jint x;
 281
 282         /** Y coordinate. */
 283         sjme_jint y;
 284 } sjme_scritchui_point;
 285
 286 /**
 287  * Represents a line.
 288  *
 289  * @since 2024/07/12
 290  */
 291 typedef struct sjme_scritchui_line
 292 {
 293         /** Starting point. */
 294         sjme_scritchui_point s;
 295
 296         /** End point. */
 297         sjme_scritchui_point e;
 298 } sjme_scritchui_line;
 299
 300 /**
 301  * Represents a dimension.
 302  *
 303  * @since 2024/07/12
 304  */
 305 typedef struct sjme_scritchui_dim
 306 {
 307         /** The width. */
 308         sjme_jint width;
 309
 310         /** The height. */
 311         sjme_jint height;
 312 } sjme_scritchui_dim;
 313
 314 /**
 315  * Represents a rectangle.
 316  *
 317  * @since 2024/04/26
 318  */
 319 typedef struct sjme_scritchui_rect
 320 {
 321         /** The starting point of the rectangle. */
 322         sjme_scritchui_point s;
 323
 324         /** The dimension of the rect. */
 325         sjme_scritchui_dim d;
 326 } sjme_scritchui_rect;
 327
 328 /**
 329  * ScritchUI state.
 330  *
 331  * @since 2024/03/27
 332  */
 333 typedef struct sjme_scritchui_stateBase* sjme_scritchui;
 334
 335 /**
 336  * ScritchUI API functions, implemented by a native library accordingly.
 337  *
 338  * @since 2024/03/27
 339  */
 340 typedef struct sjme_scritchui_apiFunctions sjme_scritchui_apiFunctions;
 341
 342 /**
 343  * ScritchUI implementation functions.
 344  *
 345  * @since 2024/04/06
 346  */
 347 typedef struct sjme_scritchui_implFunctions sjme_scritchui_implFunctions;
 348
 349 /**
 350  * Internal ScritchUI API functions.
 351  *
 352  * @since 2024/04/15
 353  */
 354 typedef struct sjme_scritchui_internFunctions sjme_scritchui_internFunctions;
 355
 356 /**
 357  * Common data structure shared by everything in ScritchUI.
 358  *
 359  * @since 2024/04/02
 360  */
 361 typedef struct sjme_scritchui_uiCommonBase sjme_scritchui_uiCommonBase;
 362
 363 /**
 364  * Common data pointer, which is shared by everything in ScritchUI.
 365  *
 366  * @since 2024/04/02
 367  */
 368 typedef sjme_scritchui_uiCommonBase* sjme_scritchui_uiCommon;
 369
 370 /**
 371  * Represents a choice of options such as those in a list.
 372  *
 373  * @since 2024/04/20
 374  */
 375 typedef struct sjme_scritchui_uiChoiceBase* sjme_scritchui_uiChoice;
 376
 377 /**
 378  * Represents a single choice item.
 379  *
 380  * @since 2024/04/25
 381  */
 382 typedef struct sjme_scritchui_uiChoiceItemBase sjme_scritchui_uiChoiceItemBase;
 383
 384 /**
 385  * Represents a single choice item.
 386  *
 387  * @since 2024/04/20
 388  */
 389 typedef struct sjme_scritchui_uiChoiceItemBase* sjme_scritchui_uiChoiceItem;
 390
 391 /**
 392  * Component within ScritchUI.
 393  *
 394  * @since 2024/03/27
 395  */
 396 typedef struct sjme_scritchui_uiComponentBase* sjme_scritchui_uiComponent;
 397
 398 /**
 399  * Represents a container which can contain other components.
 400  *
 401  * @since 2024/04/20
 402  */
 403 typedef struct sjme_scritchui_uiContainerBase* sjme_scritchui_uiContainer;
 404
 405 /**
 406  * Represents a component which can have a label.
 407  *
 408  * @since 2024/07/22
 409  */
 410 typedef struct sjme_scritchui_uiLabeledBase sjme_scritchui_uiLabeledBase;
 411
 412 /**
 413  * Represents a component which can have a label.
 414  *
 415  * @since 2024/07/22
 416  */
 417 typedef sjme_scritchui_uiLabeledBase* sjme_scritchui_uiLabeled;
 418
 419 /**
 420  * Base paintable for ScritchUI.
 421  *
 422  * @since 2024/04/06
 423  */
 424 typedef struct sjme_scritchui_uiPaintableBase* sjme_scritchui_uiPaintable;
 425
 426 /**
 427  * A panel within ScritchUI.
 428  *
 429  * @since 2024/07/28
 430  */
 431 typedef struct sjme_scritchui_uiPanelBase sjme_scritchui_uiPanelBase;
 432
 433 /**
 434  * A panel within ScritchUI.
 435  *
 436  * @since 2024/03/27
 437  */
 438 typedef sjme_scritchui_uiPanelBase* sjme_scritchui_uiPanel;
 439
 440 /**
 441  * A list within ScritchUI.
 442  *
 443  * @since 2024/07/16
 444  */
 445 typedef struct sjme_scritchui_uiListBase* sjme_scritchui_uiList;
 446
 447 /**
 448  * A menu that has children.
 449  *
 450  * @since 2024/07/23
 451  */
 452 typedef struct sjme_scritchui_uiMenuHasChildrenBase
 453         sjme_scritchui_uiMenuHasChildrenBase;
 454
 455 /**
 456  * A ScritchUI menu kind
 457  *
 458  * @since 2024/07/21
 459  */
 460 typedef struct sjme_scritchui_uiMenuKindBase sjme_scritchui_uiMenuKindBase;
 461
 462 /**
 463  * A ScritchUI menu kind
 464  *
 465  * @since 2024/07/21
 466  */
 467 typedef sjme_scritchui_uiMenuKindBase* sjme_scritchui_uiMenuKind;
 468
 469 /**
 470  * A menu that has children.
 471  *
 472  * @since 2024/07/23
 473  */
 474 typedef sjme_scritchui_uiMenuHasChildrenBase* sjme_scritchui_uiMenuHasChildren;
 475
 476 /**
 477  * A menu that has a parent.
 478  *
 479  * @since 2024/07/23
 480  */
 481 typedef struct sjme_scritchui_uiMenuHasParentBase
 482         sjme_scritchui_uiMenuHasParentBase;
 483
 484 /**
 485  * A menu that has a parent.
 486  *
 487  * @since 2024/07/23
 488  */
 489 typedef sjme_scritchui_uiMenuHasParentBase* sjme_scritchui_uiMenuHasParent;
 490
 491 /**
 492  * A menu within ScritchUI.
 493  *
 494  * @since 2024/07/21
 495  */
 496 typedef struct sjme_scritchui_uiMenuBase* sjme_scritchui_uiMenu;
 497
 498 /**
 499  * A menu bar within ScritchUI.
 500  *
 501  * @since 2024/07/21
 502  */
 503 typedef struct sjme_scritchui_uiMenuBarBase* sjme_scritchui_uiMenuBar;
 504
 505 /**
 506  * A menu item within ScritchUI.
 507  *
 508  * @since 2024/07/21
 509  */
 510 typedef struct sjme_scritchui_uiMenuItemBase* sjme_scritchui_uiMenuItem;
 511
 512 /**
 513  * A single monitor screen on the display for ScritchUI.
 514  *
 515  * @since 2024/04/06
 516  */
 517 typedef struct sjme_scritchui_uiScreenBase* sjme_scritchui_uiScreen;
 518
 519 /** A list of screens. */
 520 SJME_LIST_DECLARE(sjme_scritchui_uiScreen, 0);
 521
 522 /**
 523  * A panel which can also be scrolled.
 524  *
 525  * @since 2024/07/28
 526  */
 527 typedef struct sjme_scritchui_uiScrollPanelBase* sjme_scritchui_uiScrollPanel;
 528
 529 /**
 530  * Viewport manager information for any widget that is a viewport.
 531  *
 532  * @since 2024/07/29
 533  */
 534 typedef struct sjme_scritchui_uiViewBase sjme_scritchui_uiViewBase;
 535
 536 /**
 537  * Viewport manager information for any widget that is a viewport.
 538  *
 539  * @since 2024/07/29
 540  */
 541 typedef sjme_scritchui_uiViewBase* sjme_scritchui_uiView;
 542
 543 /**
 544  * A window within ScritchUI.
 545  *
 546  * @since 2024/03/27
 547  */
 548 typedef struct sjme_scritchui_uiWindowBase* sjme_scritchui_uiWindow;
 549
 550 /**
 551  * ScritchUI Pencil state.
 552  *
 553  * @since 2024/05/01
 554  */
 555 typedef struct sjme_scritchui_pencilBase* sjme_scritchui_pencil;
 556
 557 /**
 558  * Font structure for ScritchUI Pencil.
 559  *
 560  * @since 2024/05/12
 561  */
 562 typedef struct sjme_scritchui_pencilFontBase* sjme_scritchui_pencilFont;
 563
 564 /**
 565  * A single link within a loaded/known font chain.
 566  *
 567  * @since 2024/06/10
 568  */
 569 typedef struct sjme_scritchui_pencilFontLink sjme_scritchui_pencilFontLink;
 570
 571 /**
 572  * Utility functions to help in implementations or otherwise perform some
 573  * common logic.
 574  *
 575  * @since 2024/07/12
 576  */
 577 typedef struct sjme_scritchui_pencilUtilFunctions
 578         sjme_scritchui_pencilUtilFunctions;
 579
 580 /**
 581  * Functions which are used to lock and unlock access to the backing pencil
 582  * buffer, if applicable.
 583  *
 584  * @since 2024/07/08
 585  */
 586 typedef struct sjme_scritchui_pencilLockFunctions
 587         sjme_scritchui_pencilLockFunctions;
 588
 589 /** Arguments to pass for setting of listeners. */
 590 #define SJME_SCRITCHUI_SET_LISTENER_ARGS(what) \
 591         sjme_attrInNullable SJME_TOKEN_PASTE3(sjme_scritchui_, what, \
 592                 ListenerFunc) inListener, \
 593         sjme_attrInNullable sjme_frontEnd* copyFrontEnd
 594
 595 /**
 596  * Listener that is called when an item is activated.
 597  *
 598  * @param inState The input state.
 599  * @param inComponent The item which was activated.
 600  * @return Any resultant error, if any.
 601  * @since 2024/07/16
 602  */
 603 typedef sjme_errorCode (*sjme_scritchui_activateListenerFunc)(
 604         sjme_attrInNotNull sjme_scritchui inState,
 605         sjme_attrInNotNull sjme_scritchui_uiComponent inComponent);
 606
 607 /**
 608  * Listener that is called when a window closes.
 609  *
 610  * @param inState The input state.
 611  * @param inWindow The window being closed.
 612  * @return Any resultant error, @c SJME_ERROR_CANCEL_WINDOW_CLOSE is handled
 613  * specifically in that it will not be treated as an error however normal
 614  * application exit will not happen.
 615  * @since 2024/05/13
 616  */
 617 typedef sjme_errorCode (*sjme_scritchui_closeListenerFunc)(
 618         sjme_attrInNotNull sjme_scritchui inState,
 619         sjme_attrInNotNull sjme_scritchui_uiWindow inWindow);
 620
 621 /**
 622  * Listener for input events.
 623  *
 624  * @param inState The input state.
 625  * @param inComponent The component this event is for.
 626  * @param inEvent The event which occurred.
 627  * @return Any resultant error, if any.
 628  * @since 2024/06/29
 629  */
 630 typedef sjme_errorCode (*sjme_scritchui_inputListenerFunc)(
 631         sjme_attrInNotNull sjme_scritchui inState,
 632         sjme_attrInNotNull sjme_scritchui_uiComponent inComponent,
 633         sjme_attrInNotNull const sjme_scritchinput_event* inEvent);
 634
 635 /**
 636  * This is called when a menu item has been activated.
 637  *
 638  * @param inState The input state.
 639  * @param inWindow The window this is activating under.
 640  * @param activatedItem The menu item that was activated.
 641  * @return Any resultant error, if any.
 642  * @since 2024/07/30
 643  */
 644 typedef sjme_errorCode (*sjme_scritchui_menuItemActivateListenerFunc)(
 645         sjme_attrInNotNull sjme_scritchui inState,
 646         sjme_attrInNotNull sjme_scritchui_uiWindow inWindow,
 647         sjme_attrInNotNull sjme_scritchui_uiMenuKind activatedItem);
 648
 649 /**
 650  * Callback that is used to draw the given component.
 651  *
 652  * @param inState The ScritchUI state.
 653  * @param inComponent The component to draw on.
 654  * @param g The graphics used for drawing.
 655  * @param sw Surface width.
 656  * @param sh Surface height.
 657  * @param special Special value for painting, may be @c 0 or any
 658  * other value if it is meaningful to what is being painted.
 659  * @return Any error as required.
 660  * @since 2024/04/06
 661  */
 662 typedef sjme_errorCode (*sjme_scritchui_paintListenerFunc)(
 663         sjme_attrInNotNull sjme_scritchui inState,
 664         sjme_attrInNotNull sjme_scritchui_uiComponent inComponent,
 665         sjme_attrInNotNull sjme_scritchui_pencil g,
 666         sjme_attrInPositive sjme_jint sw,
 667         sjme_attrInPositive sjme_jint sh,
 668         sjme_attrInValue sjme_jint special);
 669
 670 /**
 671  * Listener callback for when a screen has been queried or it has been
 672  * updated.
 673  *
 674  * @param inState The input state.
 675  * @param updateType The type of update this is for.
 676  * @param inScreen The screen that has been updated.
 677  * @return Any error code if applicable.
 678  * @since 2024/04/09
 679  */
 680 typedef sjme_errorCode (*sjme_scritchui_screenListenerFunc)(
 681         sjme_attrInNotNull sjme_scritchui inState,
 682         sjme_attrInValue sjme_scritchui_screenUpdateType updateType,
 683         sjme_attrInNotNull sjme_scritchui_uiScreen inScreen);
 684
 685 /**
 686  * Listener that is called when the size of a component changes.
 687  *
 688  * @param inState The input state.
 689  * @param inComponent The component that was resized.
 690  * @param newWidth The new component width.
 691  * @param newHeight The new component height.
 692  * @return On any error if applicable.
 693  * @since 2024/04/26
 694  */
 695 typedef sjme_errorCode (*sjme_scritchui_sizeListenerFunc)(
 696         sjme_attrInNotNull sjme_scritchui inState,
 697         sjme_attrInNotNull sjme_scritchui_uiComponent inComponent,
 698         sjme_attrInPositiveNonZero sjme_jint newWidth,
 699         sjme_attrInPositiveNonZero sjme_jint newHeight);
 700
 701 /**
 702  * Listener for views so that a sub-component can suggest a size that it
 703  * could be.
 704  *
 705  * @param inState The ScritchUI state.
 706  * @param inView The view this is in.
 707  * @param subComponent The component that is suggesting a size.
 708  * @param subDim The size of the sub-component.
 709  * @return Any resultant error, if any.
 710  * @since 2024/07/29
 711  */
 712 typedef sjme_errorCode (*sjme_scritchui_sizeSuggestListenerFunc)(
 713         sjme_attrInNotNull sjme_scritchui inState,
 714         sjme_attrInNotNull sjme_scritchui_uiComponent inView,
 715         sjme_attrInNotNull sjme_scritchui_uiComponent subComponent,
 716         sjme_attrInNotNull const sjme_scritchui_dim* subDim);
 717
 718 /**
 719  * Listener that is called before and after the state within a component
 720  * has changed, when @c isAfterUpdate is @c SJME_JNI_FALSE then the component
 721  * is about to be updated.
 722  *
 723  * @param inState The input state.
 724  * @param inComponent The component where this event occurred.
 725  * @param isAfterUpdate Is this after the update has occurred?
 726  * @return Any resultant error, if any.
 727  * @since 2024/07/16
 728  */
 729 typedef sjme_errorCode (*sjme_scritchui_valueUpdateListenerFunc)(
 730         sjme_attrInNotNull sjme_scritchui inState,
 731         sjme_attrInNotNull sjme_scritchui_uiComponent inComponent,
 732         sjme_attrInValue sjme_jboolean isAfterUpdate);
 733
 734 /**
 735  * Listener for view rectangle changes.
 736  *
 737  * @param inState The input state.
 738  * @param inComponent The component that triggered this.
 739  * @param inViewRect The new view rectangle.
 740  * @return Any resultant error, if any.
 741  * @since 2024/07/28
 742  */
 743 typedef sjme_errorCode (*sjme_scritchui_viewListenerFunc)(
 744         sjme_attrInNotNull sjme_scritchui inState,
 745         sjme_attrInNotNull sjme_scritchui_uiComponent inComponent,
 746         sjme_attrInNotNull const sjme_scritchui_rect* inViewRect);
 747
 748 /**
 749  * Listener for changes in if a component becomes visible or not.
 750  *
 751  * @param inState The input state.
 752  * @param inComponent The component which has its visibility changed.
 753  * @param fromVisible The previous visible state.
 754  * @param toVisible The current visible state.
 755  * @return Any resultant error, if any.
 756  * @since 2024/06/28
 757  */
 758 typedef sjme_errorCode (*sjme_scritchui_visibleListenerFunc)(
 759         sjme_attrInNotNull sjme_scritchui inState,
 760         sjme_attrInNotNull sjme_scritchui_uiComponent inComponent,
 761         sjme_attrInValue sjme_jboolean fromVisible,
 762         sjme_attrInValue sjme_jboolean toVisible);
 763
 764 /** Void listener function. */
 765 typedef sjme_errorCode (*sjme_scritchui_voidListenerFunc)(void);
 766
 767 /**
 768  * Obtains the flags which describe the interface.
 769  *
 770  * @param inState The input ScritchUI state.
 771  * @param outFlags The output flags for this interface.
 772  * @return Any error code if applicable.
 773  * @since 2024/03/29
 774  */
 775 typedef sjme_errorCode (*sjme_scritchui_apiFlagsFunc)(
 776         sjme_attrInNotNull sjme_scritchui inState,
 777         sjme_attrOutNotNull sjme_jint outFlags);
 778
 779 /**
 780  * Initializes the native UI interface needed by ScritchUI.
 781  *
 782  * @param inPool The allocation pool to use.
 783  * @param outState The resultant state.
 784  * @param inImplFunc The implementation functions to use.
 785  * @param loopExecute Optional callback for loop execution, may be @c NULL ,
 786  * the passed argument is always the state.
 787  * @param initFrontEnd Optional initial front end data.
 788  * @return Any error code if applicable.
 789  * @since 2024/03/27
 790  */
 791 typedef sjme_errorCode (*sjme_scritchui_apiInitFunc)(
 792         sjme_attrInNotNull sjme_alloc_pool* inPool,
 793         sjme_attrInOutNotNull sjme_scritchui* outState,
 794         sjme_attrInNotNull const sjme_scritchui_implFunctions* inImplFunc,
 795         sjme_attrInNullable sjme_thread_mainFunc loopExecute,
 796         sjme_attrInNullable sjme_frontEnd* initFrontEnd);
 797
 798 /**
 799  * Gets the first selected index of a choice or otherwise @c -1 .
 800  *
 801  * @param inState The input state.
 802  * @param inComponent The choice to read from.
 803  * @param outIndex The resultant index.
 804  * @return Any resultant error, if any.
 805  * @since 2024/07/28
 806  */
 807 typedef sjme_errorCode (*sjme_scritchui_choiceGetSelectedIndexFunc)(
 808         sjme_attrInNotNull sjme_scritchui inState,
 809         sjme_attrInNotNull sjme_scritchui_uiComponent inComponent,
 810         sjme_attrOutNotNull sjme_jint* outIndex);
 811
 812 /**
 813  * Gets the specified item template.
 814  *
 815  * @param inState The input state.
 816  * @param inComponent The choice to read from.
 817  * @param atIndex The index to obtain the template of.
 818  * @param inItemTemplate A copy of the item template.
 819  * @return Any resultant error, if any.
 820  * @since 2024/07/17
 821  */
 822 typedef sjme_errorCode (*sjme_scritchui_choiceItemGetFunc)(
 823         sjme_attrInNotNull sjme_scritchui inState,
 824         sjme_attrInNotNull sjme_scritchui_uiComponent inComponent,
 825         sjme_attrInPositive sjme_jint atIndex,
 826         sjme_attrOutNotNull sjme_scritchui_uiChoiceItem outItemTemplate);
 827
 828 /**
 829  * Inserts a blank item at the given index.
 830  *
 831  * @param inState The input state.
 832  * @param inComponent The choice to modify.
 833  * @param inOutIndex The input index to insert at, then resultant index
 834  * where it was added.
 835  * @return Any resultant error, if any.
 836  * @since 2024/07/17
 837  */
 838 typedef sjme_errorCode (*sjme_scritchui_choiceItemInsertFunc)(
 839         sjme_attrInNotNull sjme_scritchui inState,
 840         sjme_attrInNotNull sjme_scritchui_uiComponent inComponent,
 841         sjme_attrInOutNotNull sjme_jint* inOutIndex);
 842
 843 /**
 844  * Removes the specified item at the given index.
 845  *
 846  * @param inState The input state.
 847  * @param inComponent The choice to modify.
 848  * @param atIndex The index to remove.
 849  * @return Any resultant error, if any.
 850  * @since 2024/07/17
 851  */
 852 typedef sjme_errorCode (*sjme_scritchui_choiceItemRemoveFunc)(
 853         sjme_attrInNotNull sjme_scritchui inState,
 854         sjme_attrInNotNull sjme_scritchui_uiComponent inComponent,
 855         sjme_attrInPositive sjme_jint atIndex);
 856
 857 /**
 858  * Removes all items from the given choice.
 859  *
 860  * @param inState The input state.
 861  * @param inComponent The choice to modify.
 862  * @return Any resultant error, if any.
 863  * @since 2024/07/17
 864  */
 865 typedef sjme_errorCode (*sjme_scritchui_choiceItemRemoveAllFunc)(
 866         sjme_attrInNotNull sjme_scritchui inState,
 867         sjme_attrInNotNull sjme_scritchui_uiComponent inComponent);
 868
 869
 870 /**
 871  * Sets whether the specified choice item is enabled.
 872  *
 873  * @param inState The input state.
 874  * @param inComponent The choice to modify.
 875  * @param atIndex The index to modify.
 876  * @param isEnabled If the item should be enabled.
 877  * @return Any resultant error, if any.
 878  * @since 2024/07/25
 879  */
 880 typedef sjme_errorCode (*sjme_scritchui_choiceItemSetEnabledFunc)(
 881         sjme_attrInNotNull sjme_scritchui inState,
 882         sjme_attrInNotNull sjme_scritchui_uiComponent inComponent,
 883         sjme_attrInPositive sjme_jint atIndex,
 884         sjme_attrInNotNull sjme_jboolean isEnabled);
 885
 886 /**
 887  * Sets the image of the specified choice item.
 888  *
 889  * @param inState The input state.
 890  * @param inComponent The choice to modify.
 891  * @param atIndex The index to modify.
 892  * @param inRgb The RGB data, may be @c NULL to clear the image.
 893  * @param inRgbOff The offset in the RGB data.
 894  * @param inRgbDataLen The data length of the RGB data.
 895  * @param inRgbScanLen The scanline length of the RGB data.
 896  * @param width The width of the image.
 897  * @param height The height of the image.
 898  * @return Any resultant error, if any.
 899  * @since 2024/07/25
 900  */
 901 typedef sjme_errorCode (*sjme_scritchui_choiceItemSetImageFunc)(
 902         sjme_attrInNotNull sjme_scritchui inState,
 903         sjme_attrInNotNull sjme_scritchui_uiComponent inComponent,
 904         sjme_attrInPositive sjme_jint atIndex,
 905         sjme_attrInNullable sjme_jint* inRgb,
 906         sjme_attrInPositive sjme_jint inRgbOff,
 907         sjme_attrInPositiveNonZero sjme_jint inRgbDataLen,
 908         sjme_attrInPositiveNonZero sjme_jint inRgbScanLen,
 909         sjme_attrInPositiveNonZero sjme_jint width,
 910         sjme_attrInPositiveNonZero sjme_jint height);
 911
 912 /**
 913  * Sets whether the specified choice item is selected.
 914  *
 915  * @param inState The input state.
 916  * @param inComponent The choice to modify.
 917  * @param atIndex The index to modify.
 918  * @param isSelected If the item should be selected.
 919  * @return Any resultant error, if any.
 920  * @since 2024/07/25
 921  */
 922 typedef sjme_errorCode (*sjme_scritchui_choiceItemSetSelectedFunc)(
 923         sjme_attrInNotNull sjme_scritchui inState,
 924         sjme_attrInNotNull sjme_scritchui_uiComponent inComponent,
 925         sjme_attrInPositive sjme_jint atIndex,
 926         sjme_attrInNotNull sjme_jboolean isSelected);
 927
 928 /**
 929  * Sets the string of the specified choice item.
 930  *
 931  * @param inState The input state.
 932  * @param inComponent The choice to modify.
 933  * @param atIndex The index to modify.
 934  * @param inString The string to set, @c NULL will clear it.
 935  * @return Any resultant error, if any.
 936  * @since 2024/07/25
 937  */
 938 typedef sjme_errorCode (*sjme_scritchui_choiceItemSetStringFunc)(
 939         sjme_attrInNotNull sjme_scritchui inState,
 940         sjme_attrInNotNull sjme_scritchui_uiComponent inComponent,
 941         sjme_attrInPositive sjme_jint atIndex,
 942         sjme_attrInNullable sjme_lpcstr inString);
 943
 944 /**
 945  * Returns the length of the choice list.
 946  *
 947  * @param inState The input state.
 948  * @param inComponent The choice to get the length of.
 949  * @param outLength The resultant length.
 950  * @return Any resultant error, if any.
 951  * @since 2024/07/17
 952  */
 953 typedef sjme_errorCode (*sjme_scritchui_choiceLengthFunc)(
 954         sjme_attrInNotNull sjme_scritchui inState,
 955         sjme_attrInNotNull sjme_scritchui_uiComponent inComponent,
 956         sjme_attrOutNotNull sjme_jint* outLength);
 957
 958 /**
 959  * Grabs the focus onto this item.
 960  *
 961  * @param inState The input state.
 962  * @param inComponent The input component.
 963  * @return Any resultant error, if any.
 964  * @since 2024/07/26
 965  */
 966 typedef sjme_errorCode (*sjme_scritchui_componentFocusGrabFunc)(
 967         sjme_attrInNotNull sjme_scritchui inState,
 968         sjme_attrInNotNull sjme_scritchui_uiComponent inComponent);
 969
 970 /**
 971  * Checks whether the given component has focus.
 972  *
 973  * @param inState The input state.
 974  * @param inComponent The input component.
 975  * @param outHasFocus The result of whether the component has focus.
 976  * @return Any resultant error, if any.
 977  * @since 2024/07/26
 978  */
 979 typedef sjme_errorCode (*sjme_scritchui_componentFocusHasFunc)(
 980         sjme_attrInNotNull sjme_scritchui inState,
 981         sjme_attrInNotNull sjme_scritchui_uiComponent inComponent,
 982         sjme_attrOutNotNull sjme_jboolean* outHasFocus);
 983
 984 /**
 985  * Gets the parent of this component.
 986  *
 987  * @param inState The ScritchUI state.
 988  * @param inComponent The component to get the parent of.
 989  * @param outParent The resultant parent that contains this, or @c NULL if
 990  * there is no parent.
 991  * @return Any resultant error, if any.
 992  * @since 2024/07/29
 993  */
 994 typedef sjme_errorCode (*sjme_scritchui_componentGetParentFunc)(
 995         sjme_attrInNotNull sjme_scritchui inState,
 996         sjme_attrInNotNull sjme_scritchui_uiComponent inComponent,
 997         sjme_attrOutNotNull sjme_scritchui_uiComponent* outParent);
 998
 999 /**
1000  * Returns the position of the given component.
1001  *
1002  * @param inState The input state.
1003  * @param inComponent The component to get the position of.
1004  * @param outX The output X coordinate.
1005  * @param outY The output Y coordinate.
1006  * @return Any resultant error, if any.
1007  * @since 2024/08/06
1008  */
1009 typedef sjme_errorCode (*sjme_scritchui_componentPositionFunc)(
1010         sjme_attrInNotNull sjme_scritchui inState,
1011         sjme_attrInNotNull sjme_scritchui_uiComponent inComponent,
1012         sjme_attrOutNullable sjme_jint* outX,
1013         sjme_attrOutNullable sjme_jint* outY);
1014
1015 /**
1016  * Repaints the given component.
1017  *
1018  * @param inState The input state.
1019  * @param inComponent The input component.
1020  * @param x The X position.
1021  * @param y The Y position.
1022  * @param width The width.
1023  * @param height The height.
1024  * @return Any error code if applicable.
1025  * @since 2024/04/24
1026  */
1027 typedef sjme_errorCode (*sjme_scritchui_componentRepaintFunc)(
1028         sjme_attrInNotNull sjme_scritchui inState,
1029         sjme_attrInNotNull sjme_scritchui_uiComponent inComponent,
1030         sjme_attrInPositive sjme_jint x,
1031         sjme_attrInPositive sjme_jint y,
1032         sjme_attrInPositiveNonZero sjme_jint width,
1033         sjme_attrInPositiveNonZero sjme_jint height);
1034
1035 /**
1036  * Revalidates the given component.
1037  *
1038  * @param inState The input state.
1039  * @param inComponent The component to be revalidated.
1040  * @return On any error if applicable.
1041  * @since 2024/04/21
1042  */
1043 typedef sjme_errorCode (*sjme_scritchui_componentRevalidateFunc)(
1044         sjme_attrInNotNull sjme_scritchui inState,
1045         sjme_attrInNotNull sjme_scritchui_uiComponent inComponent);
1046
1047 /**
1048  * Sets the activation listener for the given choice.
1049  *
1050  * @param inState The input state.
1051  * @param inComponent The choice to update.
1052  * @param inListener The listener to set.
1053  * @param copyFrontEnd Any front end data to copy.
1054  * @return Any resultant error, if any.
1055  * @since 2024/07/17
1056  */
1057 typedef sjme_errorCode (*sjme_scritchui_componentSetActivateListenerFunc)(
1058         sjme_attrInNotNull sjme_scritchui inState,
1059         sjme_attrInNotNull sjme_scritchui_uiComponent inComponent,
1060         SJME_SCRITCHUI_SET_LISTENER_ARGS(activate));
1061
1062 /**
1063  * Sets the input listener for the given component.
1064  *
1065  * @param inState The input state.
1066  * @param inComponent The component to set the listener for.
1067  * @param inListener The listener for events, may be @c NULL to clear
1068  * the existing listener.
1069  * @param copyFrontEnd The front end data to copy, may be @c NULL .
1070  * @return Any resultant error, if any.
1071  * @since 2024/06/29
1072  */
1073 typedef sjme_errorCode (*sjme_scritchui_componentSetInputListenerFunc)(
1074         sjme_attrInNotNull sjme_scritchui inState,
1075         sjme_attrInNotNull sjme_scritchui_uiComponent inComponent,
1076         SJME_SCRITCHUI_SET_LISTENER_ARGS(input));
1077
1078 /**
1079  * Sets the paint listener for the given component.
1080  *
1081  * @param inState The input state.
1082  * @param inComponent The component to set the listener for.
1083  * @param inListener The listener for paint events, may be @c NULL to clear
1084  * the existing listener.
1085  * @param copyFrontEnd The front end data to copy, may be @c NULL .
1086  * @return Any error code if applicable.
1087  * @since 2024/04/06
1088  */
1089 typedef sjme_errorCode (*sjme_scritchui_componentSetPaintListenerFunc)(
1090         sjme_attrInNotNull sjme_scritchui inState,
1091         sjme_attrInNotNull sjme_scritchui_uiComponent inComponent,
1092         SJME_SCRITCHUI_SET_LISTENER_ARGS(paint));
1093
1094 /**
1095  * Sets the listener for size events.
1096  *
1097  * @param inState The input state.
1098  * @param inComponent The component to set the listener for.
1099  * @param inListener The listener to set to or to clear.
1100  * @param copyFrontEnd Any front end data to be copied.
1101  * @return Any resultant error, if any.
1102  * @since 2024/04/26
1103  */
1104 typedef sjme_errorCode (*sjme_scritchui_componentSetSizeListenerFunc)(
1105         sjme_attrInNotNull sjme_scritchui inState,
1106         sjme_attrInNotNull sjme_scritchui_uiComponent inComponent,
1107         SJME_SCRITCHUI_SET_LISTENER_ARGS(size));
1108
1109 /**
1110  * Sets the update listener for the given choice.
1111  *
1112  * @param inState The input state.
1113  * @param inComponent The choice to update.
1114  * @param inListener The listener to set.
1115  * @param copyFrontEnd Any front end data to copy.
1116  * @return Any resultant error, if any.
1117  * @since 2024/07/17
1118  */
1119 typedef sjme_errorCode (*sjme_scritchui_componentSetValueUpdateListenerFunc)(
1120         sjme_attrInNotNull sjme_scritchui inState,
1121         sjme_attrInNotNull sjme_scritchui_uiComponent inComponent,
1122         SJME_SCRITCHUI_SET_LISTENER_ARGS(valueUpdate));
1123
1124 /**
1125  * Sets the listener to call when the visibility of a component changes.
1126  *
1127  * @param inState The input state.
1128  * @param inComponent The component to set for.
1129  * @param inListener The listener to use.
1130  * @param copyFrontEnd The front end data to use.
1131  * @return Any resultant error, if any.
1132  * @since 2024/06/28
1133  */
1134 typedef sjme_errorCode (*sjme_scritchui_componentSetVisibleListenerFunc)(
1135         sjme_attrInNotNull sjme_scritchui inState,
1136         sjme_attrInNotNull sjme_scritchui_uiComponent inComponent,
1137         SJME_SCRITCHUI_SET_LISTENER_ARGS(visible));
1138
1139 /**
1140  * Returns the size of the given component.
1141  *
1142  * @param inState The input state.
1143  * @param inComponent The component to get the size of.
1144  * @param outWidth The output width.
1145  * @param outHeight The output height.
1146  * @return Any resultant error, if any.
1147  * @since 2024/05/12
1148  */
1149 typedef sjme_errorCode (*sjme_scritchui_componentSizeFunc)(
1150         sjme_attrInNotNull sjme_scritchui inState,
1151         sjme_attrInNotNull sjme_scritchui_uiComponent inComponent,
1152         sjme_attrOutNullable sjme_jint* outWidth,
1153         sjme_attrOutNullable sjme_jint* outHeight);
1154
1155 /**
1156  * Adds the given component to the specified container.
1157  *
1158  * @param inState The input state.
1159  * @param inContainer The container to place the component within.
1160  * @param addComponent The component to add to the container.
1161  * @return Any error code if applicable.
1162  * @since 2024/04/20
1163  */
1164 typedef sjme_errorCode (*sjme_scritchui_containerAddFunc)(
1165         sjme_attrInNotNull sjme_scritchui inState,
1166         sjme_attrInNotNull sjme_scritchui_uiComponent inContainer,
1167         sjme_attrInNotNull sjme_scritchui_uiComponent addComponent);
1168
1169 /**
1170  * Removes the given component from the specified container.
1171  *
1172  * @param inState The input state.
1173  * @param inContainer The container to remove the component from.
1174  * @param removeComponent The component to remove from the container.
1175  * @return Any error code if applicable.
1176  * @since 2024/07/15
1177  */
1178 typedef sjme_errorCode (*sjme_scritchui_containerRemoveFunc)(
1179         sjme_attrInNotNull sjme_scritchui inState,
1180         sjme_attrInNotNull sjme_scritchui_uiComponent inContainer,
1181         sjme_attrInNotNull sjme_scritchui_uiComponent removeComponent);
1182
1183 /**
1184  * Removes all components from the container.
1185  *
1186  * @param inState The input state.
1187  * @param inContainer The container to remove everything from.
1188  * @return Any error code if applicable.
1189  * @since 2024/07/15
1190  */
1191 typedef sjme_errorCode (*sjme_scritchui_containerRemoveAllFunc)(
1192         sjme_attrInNotNull sjme_scritchui inState,
1193         sjme_attrInNotNull sjme_scritchui_uiComponent inContainer);
1194
1195 /**
1196  * Sets the bounds of a component within the container.
1197  *
1198  * @param inState The input state.
1199  * @param inContainer The container to set the component within.
1200  * @param inComponent The component to be placed and resized.
1201  * @param x The X position.
1202  * @param y The Y position.
1203  * @param width The width.
1204  * @param height The height.
1205  * @return Any error code if applicable.
1206  * @since 2024/04/28
1207  */
1208 typedef sjme_errorCode (*sjme_scritchui_containerSetBoundsFunc)(
1209         sjme_attrInNotNull sjme_scritchui inState,
1210         sjme_attrInNotNull sjme_scritchui_uiComponent inContainer,
1211         sjme_attrInNotNull sjme_scritchui_uiComponent inComponent,
1212         sjme_attrInPositive sjme_jint x,
1213         sjme_attrInPositive sjme_jint y,
1214         sjme_attrInPositiveNonZero sjme_jint width,
1215         sjme_attrInPositiveNonZero sjme_jint height);
1216
1217 /**
1218  * Returns the default built-in font.
1219  *
1220  * @param inState The input state.
1221  * @param outFont The resultant font.
1222  * @return Any resultant error, if any.
1223  * @since 2024/06/12
1224  */
1225 typedef sjme_errorCode (*sjme_scritchui_fontBuiltinFunc)(
1226         sjme_attrInNotNull sjme_scritchui inState,
1227         sjme_attrOutNotNull sjme_scritchui_pencilFont* outFont);
1228
1229 /**
1230  * Derives a new font from an existing font.
1231  *
1232  * @param inState The input state.
1233  * @param inFont The input font to derive.
1234  * @param inStyle The style to switch to.
1235  * @param inPixelSize The pixel size to use.
1236  * @param outDerived The resultant derived font.
1237  * @return Any resultant error, if any.
1238  * @since 2024/06/14
1239  */
1240 typedef sjme_errorCode (*sjme_scritchui_fontDeriveFunc)(
1241         sjme_attrInNotNull sjme_scritchui inState,
1242         sjme_attrInNotNull sjme_scritchui_pencilFont inFont,
1243         sjme_attrInValue sjme_scritchui_pencilFontStyle inStyle,
1244         sjme_attrInPositiveNonZero sjme_jint inPixelSize,
1245         sjme_attrOutNotNull sjme_scritchui_pencilFont* outDerived);
1246
1247 /**
1248  * Creates a hardware reference bracket to the native hardware graphics.
1249  *
1250  * @param inState The UI state.
1251  * @param outPencil The resultant pencil.
1252  * @param outWeakPencil The weak reference to the pencil.
1253  * @param pf The @c sjme_gfx_pixelFormat used for the draw.
1254  * @param bw The buffer width, this is the scanline width of the buffer.
1255  * @param bh The buffer height.
1256  * @param inLockFuncs The locking functions to use for buffer access.
1257  * @param inLockFrontEndCopy Front end copy data for locks.
1258  * @param sx Starting surface X coordinate.
1259  * @param sy Starting surface Y coordinate.
1260  * @param sw Surface width.
1261  * @param sh Surface height.
1262  * @param pencilFrontEndCopy Front end data that goes into the pencil.
1263  * @return An error if the requested graphics are not valid.
1264  * @since 2024/05/01
1265  */
1266 typedef sjme_errorCode (*sjme_scritchui_hardwareGraphicsFunc)(
1267         sjme_attrInNotNull sjme_scritchui inState,
1268         sjme_attrOutNotNull sjme_scritchui_pencil* outPencil,
1269         sjme_attrOutNullable sjme_alloc_weak* outWeakPencil,
1270         sjme_attrInValue sjme_gfx_pixelFormat pf,
1271         sjme_attrInPositiveNonZero sjme_jint bw,
1272         sjme_attrInPositiveNonZero sjme_jint bh,
1273         sjme_attrInNullable const sjme_scritchui_pencilLockFunctions* inLockFuncs,
1274         sjme_attrInNullable const sjme_frontEnd* inLockFrontEndCopy,
1275         sjme_attrInValue sjme_jint sx,
1276         sjme_attrInValue sjme_jint sy,
1277         sjme_attrInPositiveNonZero sjme_jint sw,
1278         sjme_attrInPositiveNonZero sjme_jint sh,
1279         sjme_attrInNullable const sjme_frontEnd* pencilFrontEndCopy);
1280
1281 /**
1282  * Sets the label of the specified component.
1283  *
1284  * @param inState The input state.
1285  * @param inCommon The item to set the label for.
1286  * @param inString The label to set.
1287  * @return Any resultant error, if any.
1288  * @since 2024/07/21
1289  */
1290 typedef sjme_errorCode (*sjme_scritchui_labelSetStringFunc)(
1291         sjme_attrInNotNull sjme_scritchui inState,
1292         sjme_attrInNotNull sjme_scritchui_uiCommon inCommon,
1293         sjme_attrInNullable sjme_lpcstr inString);
1294
1295 /**
1296  * Returns the color for the given element based on the current look and feel.
1297  *
1298  * @param inState The current state.
1299  * @param inContext Optional context that can be targetted at a widget to get
1300  * its color themeing.
1301  * @param outRGB The resultant RGB color.
1302  * @param elementColor The color to request.
1303  * @return On any resultant error, if any.
1304  * @since 2024/07/27
1305  */
1306 typedef sjme_errorCode (*sjme_scritchui_lafElementColorFunc)(
1307         sjme_attrInNotNull sjme_scritchui inState,
1308         sjme_attrInNullable sjme_scritchui_uiComponent inContext,
1309         sjme_attrOutNotNull sjme_jint* outRGB,
1310         sjme_attrInValue sjme_scritchui_lafElementColorType elementColor);
1311
1312 /**
1313  * Creates a new list.
1314  *
1315  * @param inState The input state.
1316  * @param outPanel The resultant list.
1317  * @param inChoiceType The type of choice this is.
1318  * @return Any error code if applicable.
1319  * @since 2024/07/16
1320  */
1321 typedef sjme_errorCode (*sjme_scritchui_listNewFunc)(
1322         sjme_attrInNotNull sjme_scritchui inState,
1323         sjme_attrInOutNotNull sjme_scritchui_uiList* outList,
1324         sjme_attrInValue sjme_scritchui_choiceType inChoiceType);
1325
1326 /**
1327  * Execute the given callback within the event loop of the GUI.
1328  *
1329  * @param inState The input state.
1330  * @param callback The callback to execute.
1331  * @param anything A value that can be passed to the listener.
1332  * @return Any error code if applicable.
1333  * @since 2024/04/09
1334  */
1335 typedef sjme_errorCode (*sjme_scritchui_loopExecuteFunc)(
1336         sjme_attrInNotNull sjme_scritchui inState,
1337         sjme_attrInNotNull sjme_thread_mainFunc callback,
1338         sjme_attrInNullable sjme_thread_parameter anything);
1339
1340 /**
1341  * Determines whether the current thread is in the event loop or not.
1342  *
1343  * @param inState The input state.
1344  * @param outInThread The result of whether this is in the event loop.
1345  * @return Any error code if applicable.
1346  * @since 2024/04/09
1347  */
1348 typedef sjme_errorCode (*sjme_scritchui_loopIsInThreadFunc)(
1349         sjme_attrInNotNull sjme_scritchui inState,
1350         sjme_attrInOutNotNull sjme_jboolean* outInThread);
1351
1352 /**
1353  * Iterates a single run of the event loop.
1354  *
1355  * @param inState The input ScritchUI state.
1356  * @param blocking If the iteration should block for something to happen.
1357  * @param outHasTerminated Has the GUI interface terminated?
1358  * @return Any error code if applicable.
1359  * @since 2024/04/02
1360  */
1361 typedef sjme_errorCode (*sjme_scritchui_loopIterateFunc)(
1362         sjme_attrInNotNull sjme_scritchui inState,
1363         sjme_attrInValue sjme_jboolean blocking,
1364         sjme_attrOutNullable sjme_jboolean* outHasTerminated);
1365
1366 /**
1367  * Creates a new menu bar.
1368  *
1369  * @param inState The input state.
1370  * @param outMenuBar The resultant menu bar.
1371  * @return Any error code if applicable.
1372  * @since 2024/07/21
1373  */
1374 typedef sjme_errorCode (*sjme_scritchui_menuBarNewFunc)(
1375         sjme_attrInNotNull sjme_scritchui inState,
1376         sjme_attrInOutNotNull sjme_scritchui_uiMenuBar* outMenuBar);
1377
1378 /**
1379  * Inserts the given menu item into the menu at the specified index.
1380  *
1381  * @param inState The ScritchUI state.
1382  * @param intoMenu The menu to insert into.
1383  * @param atIndex The index to insert at.
1384  * @param childItem The child menu item to add.
1385  * @return Any resultant error, if any.
1386  * @since 2024/07/23
1387  */
1388 typedef sjme_errorCode (*sjme_scritchui_menuInsertFunc)(
1389         sjme_attrInNotNull sjme_scritchui inState,
1390         sjme_attrInNotNull sjme_scritchui_uiMenuKind intoMenu,
1391         sjme_attrInPositive sjme_jint atIndex,
1392         sjme_attrInNotNull sjme_scritchui_uiMenuKind childItem);
1393
1394 /**
1395  * Creates a new menu item.
1396  *
1397  * @param inState The input state.
1398  * @param outMenuItem The resultant menu item.
1399  * @return Any error code if applicable.
1400  * @since 2024/07/21
1401  */
1402 typedef sjme_errorCode (*sjme_scritchui_menuItemNewFunc)(
1403         sjme_attrInNotNull sjme_scritchui inState,
1404         sjme_attrInOutNotNull sjme_scritchui_uiMenuItem* outMenuItem);
1405
1406 /**
1407  * Creates a new menu.
1408  *
1409  * @param inState The input state.
1410  * @param outMenu The resultant menu.
1411  * @return Any error code if applicable.
1412  * @since 2024/07/21
1413  */
1414 typedef sjme_errorCode (*sjme_scritchui_menuNewFunc)(
1415         sjme_attrInNotNull sjme_scritchui inState,
1416         sjme_attrInOutNotNull sjme_scritchui_uiMenu* outMenu);
1417
1418 /**
1419  * Removes the item at the specified index from this menu.
1420  *
1421  * @param inState The ScritchUI state.
1422  * @param fromMenu The menu to remove from.
1423  * @param atIndex The index to remove.
1424  * @return Any resultant error, if any.
1425  * @since 2024/07/23
1426  */
1427 typedef sjme_errorCode (*sjme_scritchui_menuRemoveFunc)(
1428         sjme_attrInNotNull sjme_scritchui inState,
1429         sjme_attrInNotNull sjme_scritchui_uiMenuKind fromMenu,
1430         sjme_attrInPositive sjme_jint atIndex);
1431
1432 /**
1433  * Removes all items from the given menu.
1434  *
1435  * @param inState The ScritchUI state.
1436  * @param fromMenu The menu to remove from.
1437  * @return Any resultant error, if any.
1438  * @since 2024/07/23
1439  */
1440 typedef sjme_errorCode (*sjme_scritchui_menuRemoveAllFunc)(
1441         sjme_attrInNotNull sjme_scritchui inState,
1442         sjme_attrInNotNull sjme_scritchui_uiMenuKind fromMenu);
1443
1444 /**
1445  * Deletes the given object.
1446  *
1447  * @param inState The input state.
1448  * @param inOutObject The object to delete.
1449  * @return Any resultant error, if any.
1450  * @since 2024/07/20
1451  */
1452 typedef sjme_errorCode (*sjme_scritchui_objectDeleteFunc)(
1453         sjme_attrInNotNull sjme_scritchui inState,
1454         sjme_attrInOutNotNull sjme_scritchui_uiCommon* inOutObject);
1455
1456 /**
1457  * Enables or disables focus on a panel.
1458  *
1459  * @param inState The input state.
1460  * @param inPanel The input panel.
1461  * @param enableFocus Should focus be enabled?
1462  * @return Any error code if applicable.
1463  * @since 2024/04/06
1464  */
1465 typedef sjme_errorCode (*sjme_scritchui_panelEnableFocusFunc)(
1466         sjme_attrInNotNull sjme_scritchui inState,
1467         sjme_attrInNotNull sjme_scritchui_uiPanel inPanel,
1468         sjme_attrInValue sjme_jboolean enableFocus,
1469         sjme_attrInValue sjme_jboolean defaultFocus);
1470
1471 /**
1472  * Creates a new panel.
1473  *
1474  * @param inState The input state.
1475  * @param outPanel The resultant panel.
1476  * @return Any error code if applicable.
1477  * @since 2024/04/02
1478  */
1479 typedef sjme_errorCode (*sjme_scritchui_panelNewFunc)(
1480         sjme_attrInNotNull sjme_scritchui inState,
1481         sjme_attrInOutNotNull sjme_scritchui_uiPanel* outPanel);
1482
1483 /**
1484  * Sets the screen listener callback for screen changes.
1485  *
1486  * @param inState The input state.
1487  * @param callback The callback for screen information and changes.
1488  * @return Any error code if applicable.
1489  * @since 2024/04/06
1490  */
1491 typedef sjme_errorCode (*sjme_scritchui_screenSetListenerFunc)(
1492         sjme_attrInNotNull sjme_scritchui inState,
1493         SJME_SCRITCHUI_SET_LISTENER_ARGS(screen));
1494
1495 /**
1496  * Obtains and queries the screens which are attached to the system displays.
1497  *
1498  * @param inState The input state.
1499  * @param outScreens The resultant screens.
1500  * @param inOutNumScreens The number of screens for input and output.
1501  * @return Any error code if applicable.
1502  * @since 2024/04/06
1503  */
1504 typedef sjme_errorCode (*sjme_scritchui_screensFunc)(
1505         sjme_attrInNotNull sjme_scritchui inState,
1506         sjme_attrOutNotNull sjme_scritchui_uiScreen* outScreens,
1507         sjme_attrInOutNotNull sjme_jint* inOutNumScreens);
1508
1509 /**
1510  * Creates a new scroll panel which contains other components within a viewport
1511  * with scrollbars.
1512  *
1513  * @param inState The ScritchUI state.
1514  * @param outScrollPanel The newly created scroll panel.
1515  * @return Any resultant error, if any.
1516  * @since 2024/07/29
1517  */
1518 typedef sjme_errorCode (*sjme_scritchui_scrollPanelNewFunc)(
1519         sjme_attrInNotNull sjme_scritchui inState,
1520         sjme_attrOutNotNull sjme_scritchui_uiScrollPanel* outScrollPanel);
1521
1522 /**
1523  * Gets the current view rectangle of a viewport.
1524  *
1525  * @param inState The ScritchUI state.
1526  * @param inComponent The viewport.
1527  * @param outViewRect The current view rectangle.
1528  * @return Any resultant error, if any.
1529  * @since 2024/07/29
1530  */
1531 typedef sjme_errorCode (*sjme_scritchui_viewGetViewFunc)(
1532         sjme_attrInNotNull sjme_scritchui inState,
1533         sjme_attrInNotNull sjme_scritchui_uiComponent inComponent,
1534         sjme_attrOutNotNull sjme_scritchui_rect* outViewRect);
1535
1536 /**
1537  * Sets the area that the scroll panel provides a viewport area, this area
1538  * may be larger than the viewport and widgets may be placed inside.
1539  *
1540  * @param inState The ScritchUI state.
1541  * @param inComponent The viewport.
1542  * @param inViewArea The view area to set.
1543  * @return Any resultant error, if any.
1544  * @since 2024/07/29
1545  */
1546 typedef sjme_errorCode (*sjme_scritchui_viewSetAreaFunc)(
1547         sjme_attrInNotNull sjme_scritchui inState,
1548         sjme_attrInNotNull sjme_scritchui_uiComponent inComponent,
1549         sjme_attrInNotNull const sjme_scritchui_dim* inViewArea);
1550
1551 /**
1552  * Sets the view rectangle of a viewport.
1553  *
1554  * @param inState The ScritchUI state.
1555  * @param inComponent The viewport.
1556  * @param inViewPos The new view position to set.
1557  * @return Any resultant error, if any.
1558  * @since 2024/07/29
1559  */
1560 typedef sjme_errorCode (*sjme_scritchui_viewSetViewFunc)(
1561         sjme_attrInNotNull sjme_scritchui inState,
1562         sjme_attrInNotNull sjme_scritchui_uiComponent inComponent,
1563         sjme_attrInNotNull const sjme_scritchui_point* inViewPos);
1564
1565 /**
1566  * Sets the listener which is called for a viewport when a contained component
1567  * has a suggestion as to how large it should be to contain it.
1568  *
1569  * @param inState The ScritchUI state.
1570  * @param inComponent The viewport.
1571  * @param inListener The listener to set.
1572  * @param copyFrontEnd Any front-end data needed for the listener.
1573  * @return Any resultant error, if any.
1574  * @since 2024/07/29
1575  */
1576 typedef sjme_errorCode (*sjme_scritchui_viewSetSizeSuggestListenerFunc)(
1577         sjme_attrInNotNull sjme_scritchui inState,
1578         sjme_attrInNotNull sjme_scritchui_uiComponent inComponent,
1579         SJME_SCRITCHUI_SET_LISTENER_ARGS(sizeSuggest));
1580
1581 /**
1582  * Sets the listener which is called whenever the viewport changes such as it
1583  * being scrolled.
1584  *
1585  * @param inState The ScritchUI state.
1586  * @param inComponent The viewport.
1587  * @param inListener The listener to set.
1588  * @param copyFrontEnd Any front-end data needed for the listener.
1589  * @return Any resultant error, if any.
1590  * @since 2024/07/29
1591  */
1592 typedef sjme_errorCode (*sjme_scritchui_viewSetViewListenerFunc)(
1593         sjme_attrInNotNull sjme_scritchui inState,
1594         sjme_attrInNotNull sjme_scritchui_uiComponent inComponent,
1595         SJME_SCRITCHUI_SET_LISTENER_ARGS(view));
1596
1597 /**
1598  * Void listener set.
1599  *
1600  * @param inState The ScritchUI state.
1601  * @param inComponent The component.
1602  * @param inListener The listener to set.
1603  * @param copyFrontEnd Any front-end data needed for the listener.
1604  * @return Any resultant error, if any.
1605  * @since 2024/07/29
1606  */
1607 typedef sjme_errorCode (*sjme_scritchui_voidSetVoidListenerFunc)(
1608         sjme_attrInNotNull sjme_scritchui inState,
1609         sjme_attrInNotNull sjme_scritchui_uiComponent inComponent,
1610         SJME_SCRITCHUI_SET_LISTENER_ARGS(void));
1611
1612 /**
1613  * Sets the minimum content size for windows.
1614  *
1615  * @param inState The input state.
1616  * @param inWindow The window to set the minimum content size for.
1617  * @param width The width to set.
1618  * @param height The height to set.
1619  * @return Any error code if applicable, such as if the width and/or height
1620  * are zero or negative.
1621  * @since 2024/04/21
1622  */
1623 typedef sjme_errorCode (*sjme_scritchui_windowContentMinimumSizeFunc)(
1624         sjme_attrInNotNull sjme_scritchui inState,
1625         sjme_attrInNotNull sjme_scritchui_uiWindow inWindow,
1626         sjme_attrInPositiveNonZero sjme_jint width,
1627         sjme_attrInPositiveNonZero sjme_jint height);
1628
1629 /**
1630  * Creates a new window.
1631  *
1632  * @param inState The input state.
1633  * @param outWindow The resultant newly created window.
1634  * @return Any error code if applicable.
1635  * @since 2024/04/16
1636  */
1637 typedef sjme_errorCode (*sjme_scritchui_windowNewFunc)(
1638         sjme_attrInNotNull sjme_scritchui inState,
1639         sjme_attrInOutNotNull sjme_scritchui_uiWindow* outWindow);
1640
1641 /**
1642  * Sets the close listener for a window.
1643  *
1644  * @param inState The input state.
1645  * @param inWindow The window to set for.
1646  * @param inListener The listener to use.
1647  * @param copyFrontEnd The front end data to use.
1648  * @return Any resultant error, if any.
1649  * @since 2024/05/13
1650  */
1651 typedef sjme_errorCode (*sjme_scritchui_windowSetCloseListenerFunc)(
1652         sjme_attrInNotNull sjme_scritchui inState,
1653         sjme_attrInNotNull sjme_scritchui_uiWindow inWindow,
1654         SJME_SCRITCHUI_SET_LISTENER_ARGS(close));
1655
1656 /**
1657  * Sets the menu bar for a window.
1658  *
1659  * @param inState The input state.
1660  * @param inWindow The window to set the menu bar of.
1661  * @param inMenuBar The menu bar to set, if @c NULL then it is removed.
1662  * @return Any resultant error, if any.
1663  * @since 2024/07/23
1664  */
1665 typedef sjme_errorCode (*sjme_scritchui_windowSetMenuBarFunc)(
1666         sjme_attrInNotNull sjme_scritchui inState,
1667         sjme_attrInNotNull sjme_scritchui_uiWindow inWindow,
1668         sjme_attrInNullable sjme_scritchui_uiMenuBar inMenuBar);
1669
1670 /**
1671  * Sets the menu item activation listener for a window.
1672  *
1673  * @param inState The input state.
1674  * @param inWindow The window to set for.
1675  * @param inListener The listener to use.
1676  * @param copyFrontEnd The front end data to use.
1677  * @return Any resultant error, if any.
1678  * @since 2024/07/30
1679  */
1680 typedef sjme_errorCode (*sjme_scritchui_windowSetMenuItemActivateListenerFunc)(
1681         sjme_attrInNotNull sjme_scritchui inState,
1682         sjme_attrInNotNull sjme_scritchui_uiWindow inWindow,
1683         SJME_SCRITCHUI_SET_LISTENER_ARGS(menuItemActivate));
1684
1685 /**
1686  * Sets the visibility of a window.
1687  *
1688  * @param inState The input state.
1689  * @param inWindow The input window.
1690  * @param isVisible Should the window be visible?
1691  * @return Any error code if applicable.
1692  * @since 2024/04/21
1693  */
1694 typedef sjme_errorCode (*sjme_scritchui_windowSetVisibleFunc)(
1695         sjme_attrInNotNull sjme_scritchui inState,
1696         sjme_attrInNotNull sjme_scritchui_uiWindow inWindow,
1697         sjme_attrInValue sjme_jboolean isVisible);
1698
1699 /** Quicker API declaration in struct. */
1700 #define SJME_SCRITCHUI_QUICK_API(x) \
1701         SJME_TOKEN_PASTE3(sjme_scritchui_, x, Func) x
1702
1703 struct sjme_scritchui_apiFunctions
1704 {
1705         /** API flags. */
1706         SJME_SCRITCHUI_QUICK_API(apiFlags);
1707
1708         /** Get the first selected index of a choice. */
1709         SJME_SCRITCHUI_QUICK_API(choiceGetSelectedIndex);
1710
1711         /** Gets the item information. */
1712         SJME_SCRITCHUI_QUICK_API(choiceItemGet);
1713
1714         /** Inserts an item into the given choice. */
1715         SJME_SCRITCHUI_QUICK_API(choiceItemInsert);
1716
1717         /** Removes an item from the given choice. */
1718         SJME_SCRITCHUI_QUICK_API(choiceItemRemove);
1719
1720         /** Removes all items from the given choice. */
1721         SJME_SCRITCHUI_QUICK_API(choiceItemRemoveAll);
1722
1723         /** Sets whether the given choice item is enabled. */
1724         SJME_SCRITCHUI_QUICK_API(choiceItemSetEnabled);
1725
1726         /** Sets the image of the given choice item. */
1727         SJME_SCRITCHUI_QUICK_API(choiceItemSetImage);
1728
1729         /** Sets whether the given choice item is selected. */
1730         SJME_SCRITCHUI_QUICK_API(choiceItemSetSelected);
1731
1732         /** Sets the string of the given choice item. */
1733         SJME_SCRITCHUI_QUICK_API(choiceItemSetString);
1734
1735         /** Gets the choice length. */
1736         SJME_SCRITCHUI_QUICK_API(choiceLength);
1737
1738         /** Grabs the focus for this component. */
1739         SJME_SCRITCHUI_QUICK_API(componentFocusGrab);
1740
1741         /** Checks if this component has focus. */
1742         SJME_SCRITCHUI_QUICK_API(componentFocusHas);
1743
1744         /** Gets the parent component of this one. */
1745         SJME_SCRITCHUI_QUICK_API(componentGetParent);
1746
1747         /** Get size of component. */
1748         SJME_SCRITCHUI_QUICK_API(componentPosition);
1749
1750         /** Repaints the given component. */
1751         SJME_SCRITCHUI_QUICK_API(componentRepaint);
1752
1753         /** Revalidates the given component. */
1754         SJME_SCRITCHUI_QUICK_API(componentRevalidate);
1755
1756         /** Set listener for when a component is activated. */
1757         SJME_SCRITCHUI_QUICK_API(componentSetActivateListener);
1758
1759         /** Sets the input listener for a component. */
1760         SJME_SCRITCHUI_QUICK_API(componentSetInputListener);
1761
1762         /** Sets the paint listener for a component. */
1763         SJME_SCRITCHUI_QUICK_API(componentSetPaintListener);
1764
1765         /** Sets the listener for component size events. */
1766         SJME_SCRITCHUI_QUICK_API(componentSetSizeListener);
1767
1768         /** Set listener for when a component value has updated. */
1769         SJME_SCRITCHUI_QUICK_API(componentSetValueUpdateListener);
1770
1771         /** Sets the listener for component visible events. */
1772         SJME_SCRITCHUI_QUICK_API(componentSetVisibleListener);
1773
1774         /** Get size of component. */
1775         SJME_SCRITCHUI_QUICK_API(componentSize);
1776
1777         /** Adds component to container. */
1778         SJME_SCRITCHUI_QUICK_API(containerAdd);
1779
1780         /** Remove component from container. */
1781         SJME_SCRITCHUI_QUICK_API(containerRemove);
1782
1783         /** Remove all components from a container. */
1784         SJME_SCRITCHUI_QUICK_API(containerRemoveAll);
1785
1786         /** Set bounds of component in a container. */
1787         SJME_SCRITCHUI_QUICK_API(containerSetBounds);
1788
1789         /** Returns the default built-in font. */
1790         SJME_SCRITCHUI_QUICK_API(fontBuiltin);
1791
1792         /** Derive a similar font. */
1793         SJME_SCRITCHUI_QUICK_API(fontDerive);
1794
1795         /** Hardware graphics support on arbitrary buffers. */
1796         SJME_SCRITCHUI_QUICK_API(hardwareGraphics);
1797
1798         /** Sets the close listener for a window. */
1799         SJME_SCRITCHUI_QUICK_API(labelSetString);
1800
1801         /** Returns the element color for the look and feel. */
1802         SJME_SCRITCHUI_QUICK_API(lafElementColor);
1803
1804         /** Creates a new list. */
1805         SJME_SCRITCHUI_QUICK_API(listNew);
1806
1807         /** Execute callback within the event loop. */
1808         SJME_SCRITCHUI_QUICK_API(loopExecute);
1809
1810         /** Execute callback later in the event loop. */
1811         sjme_scritchui_loopExecuteFunc loopExecuteLater;
1812
1813         /** Execute callback within the event loop and wait until termination. */
1814         sjme_scritchui_loopExecuteFunc loopExecuteWait;
1815
1816         /** Is the current thread in the loop? */
1817         SJME_SCRITCHUI_QUICK_API(loopIsInThread);
1818
1819         /** Iterates a single run of the event loop. */
1820         SJME_SCRITCHUI_QUICK_API(loopIterate);
1821
1822         /** Creates a new menu bar. */
1823         SJME_SCRITCHUI_QUICK_API(menuBarNew);
1824
1825         /** Insert the given menu item into a menu. */
1826         SJME_SCRITCHUI_QUICK_API(menuInsert);
1827
1828         /** Creates a new menu item. */
1829         SJME_SCRITCHUI_QUICK_API(menuItemNew);
1830
1831         /** Creates a new menu. */
1832         SJME_SCRITCHUI_QUICK_API(menuNew);
1833
1834         /** Removes an item from the menu. */
1835         SJME_SCRITCHUI_QUICK_API(menuRemove);
1836
1837         /** Removes all items from the menu. */
1838         SJME_SCRITCHUI_QUICK_API(menuRemoveAll);
1839
1840         /** Deletes an object. */
1841         SJME_SCRITCHUI_QUICK_API(objectDelete);
1842
1843         /** Enable focus on a panel. */
1844         SJME_SCRITCHUI_QUICK_API(panelEnableFocus);
1845
1846         /** Creates a new panel. */
1847         SJME_SCRITCHUI_QUICK_API(panelNew);
1848
1849         /** Register listener. */
1850         SJME_SCRITCHUI_QUICK_API(screenSetListener);
1851
1852         /** Screens available. */
1853         SJME_SCRITCHUI_QUICK_API(screens);
1854
1855         /** Create a new scroll panel. */
1856         SJME_SCRITCHUI_QUICK_API(scrollPanelNew);
1857
1858         /** Get the current view rect of a viewport. */
1859         SJME_SCRITCHUI_QUICK_API(viewGetView);
1860
1861         /** Set the area of the viewport's bounds, the entire scrollable area. */
1862         SJME_SCRITCHUI_QUICK_API(viewSetArea);
1863
1864         /** Sets the view rect of a viewport. */
1865         SJME_SCRITCHUI_QUICK_API(viewSetView);
1866
1867         /** Sets the size suggestion for this view. */
1868         SJME_SCRITCHUI_QUICK_API(viewSetSizeSuggestListener);
1869
1870         /** Sets the listener for tracking scrolling and viewport changes. */
1871         SJME_SCRITCHUI_QUICK_API(viewSetViewListener);
1872
1873         /** Sets minimum size of the window contents. */
1874         SJME_SCRITCHUI_QUICK_API(windowContentMinimumSize);
1875
1876         /** Creates a new window. */
1877         SJME_SCRITCHUI_QUICK_API(windowNew);
1878
1879         /** Sets the close listener for a window. */
1880         SJME_SCRITCHUI_QUICK_API(windowSetCloseListener);
1881
1882         /** Sets the menu bar for a window. */
1883         SJME_SCRITCHUI_QUICK_API(windowSetMenuBar);
1884
1885         /** Sets the activation listener for menu items in a window. */
1886         SJME_SCRITCHUI_QUICK_API(windowSetMenuItemActivateListener);
1887
1888         /** Sets visibility of window. */
1889         SJME_SCRITCHUI_QUICK_API(windowSetVisible);
1890 };
1891
1892 #undef SJME_SCRITCHUI_QUICK_API
1893
1894 /**
1895  * Opaque internal implementation functions.
1896  *
1897  * @since 2024/05/14
1898  */
1899 typedef struct sjme_scritchui_implInternFunctions
1900         sjme_scritchui_implInternFunctions;
1901
1902 /** The number of common handles. */
1903 #define SJME_SCRITCHUI_NUM_COMMON_HANDLES 4
1904
1905 /** The number of common values. */
1906 #define SJME_SCRITCHUI_NUM_COMMON_VALUES SJME_SCRITCHUI_NUM_COMMON_HANDLES
1907
1908 struct sjme_scritchui_uiCommonBase
1909 {
1910         /** The type of what this is. */
1911         sjme_scritchui_uiType type;
1912
1913         /** The state which owns this. */
1914         sjme_scritchui state;
1915
1916         /**
1917          * Front-end data for this, note that ScritchUI implementations must not
1918          * use this for information as this is only to be used by front-ends.
1919          */
1920         sjme_frontEnd frontEnd;
1921
1922         /** Opaque native handles for this, as needed. */
1923         sjme_scritchui_handle handle[SJME_SCRITCHUI_NUM_COMMON_HANDLES];
1924
1925         /** Other value storage, as needed. */
1926         sjme_jint intVals[SJME_SCRITCHUI_NUM_COMMON_VALUES];
1927 };
1928
1929 /**
1930  * Window manager details to use.
1931  *
1932  * @since 2024/04/24
1933  */
1934 typedef struct sjme_scritchui_wmInfo
1935 {
1936         /** Default title. */
1937         sjme_lpcstr defaultTitle;
1938
1939         /** X Window System Class. */
1940         sjme_lpcstr xwsClass;
1941 } sjme_scritchui_wmInfo;
1942
1943 /**
1944  * Windowing system specific bugs.
1945  *
1946  * @since 2024/08/15
1947  */
1948 typedef struct sjme_scritchui_bugs
1949 {
1950         /** Do not set content size when the window is made visible. */
1951         sjme_jboolean noContentSizeWhenVisible;
1952 } sjme_scritchui_bugs;
1953
1954 struct sjme_scritchui_stateBase
1955 {
1956         /** Common data. */
1957         sjme_scritchui_uiCommonBase common;
1958
1959         /** Window manager information. */
1960         const sjme_scritchui_wmInfo* wmInfo;
1961
1962         /** API functions to use. */
1963         const sjme_scritchui_apiFunctions* api;
1964
1965         /** In thread API functions. */
1966         const sjme_scritchui_apiFunctions* apiInThread;
1967
1968         /** Internal implementation functions to use. */
1969         const sjme_scritchui_internFunctions* intern;
1970
1971         /** Implementation functions to use. */
1972         const sjme_scritchui_implFunctions* impl;
1973
1974         /** Internal implementation functions, which are opaque. */
1975         const sjme_scritchui_implInternFunctions* implIntern;
1976
1977         /** The allocation pool to use for allocations. */
1978         sjme_alloc_pool* pool;
1979
1980         /** The event loop thread, if applicable. */
1981         sjme_thread loopThread;
1982
1983         /** The current loop thread ID, if applicable. */
1984         sjme_intPointer loopThreadId;
1985
1986         /** Loop thread initializer if one was passed. */
1987         sjme_thread_mainFunc loopThreadInit;
1988
1989         /** Indicator that the main loop is ready for execution. */
1990         sjme_atomic_sjme_jint loopThreadReady;
1991
1992         /** The available screens. */
1993         sjme_list_sjme_scritchui_uiScreen* screens;
1994
1995         /** The window manager type used. */
1996         sjme_scritchui_windowManagerType wmType;
1997
1998         /** The internal built-in font. */
1999         sjme_scritchui_pencilFont builtinFont;
2000
2001         /** The fonts which are loaded and known to the state. */
2002         sjme_scritchui_pencilFontLink* fontChain;
2003
2004         /** Function to obtain the current nanotime, for input events. */
2005         sjme_nal_nanoTimeFunc nanoTime;
2006
2007         /** Is this a panel only interface? */
2008         sjme_jboolean isPanelOnly;
2009
2010         /** Wrapped ScritchUI state, if this is a wrapper. */
2011         sjme_scritchui wrappedState;
2012
2013         /** Reference to owning state. */
2014         sjme_atomic_sjme_pointer topState;
2015
2016         /** The next ID for opaque menu items. */
2017         sjme_jint nextMenuItemId;
2018
2019         /** Windowing system specific bugs. */
2020         sjme_scritchui_bugs bugs;
2021 };
2022
2023 /* If dynamic libraries are not supported, we cannot do this. */
2024 #if !defined(SJME_CONFIG_SCRITCHUI_NO_DYLIB)
2025
2026 /**
2027  * Initializes the API through the dynamic library.
2028  *
2029  * @param inPool The pool to allocate within.
2030  * @param loopExecute Optional callback for loop execution, may be @c NULL ,
2031  * the passed argument is always the state.
2032  * @param initFrontEnd Optional initial front end data.
2033  * @param outState The resultant newly created ScritchUI state.
2034  * @return Any error code that may occur.
2035  * @since 2024/03/29
2036  */
2037 typedef sjme_errorCode (*sjme_scritchui_dylibApiFunc)(
2038         sjme_attrInNotNull sjme_alloc_pool* inPool,
2039         sjme_attrInNullable sjme_thread_mainFunc loopExecute,
2040         sjme_attrInNullable sjme_frontEnd* initFrontEnd,
2041         sjme_attrInOutNotNull sjme_scritchui* outState);
2042
2043 /** The base name for the ScritchUI dynamic library. */
2044 #define SJME_SCRITCHUI_DYLIB_NAME_BASE \
2045         "squirreljme-scritchui-"
2046
2047 /** The name of the dynamic library for ScritchUI. */
2048 #define SJME_SCRITCHUI_DYLIB_NAME(x) \
2049         SJME_SCRITCHUI_DYLIB_NAME_BASE SJME_TOKEN_STRING_PP(x)
2050
2051 /** The path name for the dynamic library for ScritchUI. */
2052 #define SJME_SCRITCHUI_DYLIB_PATHNAME(x) \
2053         SJME_CONFIG_DYLIB_PATHNAME(SJME_SCRITCHUI_DYLIB_NAME(x))
2054
2055 /** The symbol to use with @c sjme_scritchui_dylibApiFunc . */
2056 #define SJME_SCRITCHUI_DYLIB_SYMBOL(x) \
2057         SJME_TOKEN_PASTE(sjme_scritchui_dylibApi, x)
2058
2059 #endif
2060
2061 /**
2062  * Check cast of a given type.
2063  *
2064  * @param inType The input type.
2065  * @param inPtr The input pointer.
2066  * @return Always @c inPtr .
2067  * @since 2024/07/23
2068  */
2069 sjme_pointer sjme_scritchui_checkCast(sjme_scritchui_uiType inType,
2070         sjme_pointer inPtr);
2071
2072 /**
2073  * Check cast of a given type against a component.
2074  *
2075  * @param inPtr The input pointer.
2076  * @return Always @c inPtr .
2077  * @since 2024/07/23
2078  */
2079 sjme_pointer sjme_scritchui_checkCast_component(sjme_pointer inPtr);
2080
2081 /**
2082  * Check cast of a given type against a menu kind.
2083  *
2084  * @param inPtr The input pointer.
2085  * @return Always @c inPtr .
2086  * @since 2024/07/23
2087  */
2088 sjme_pointer sjme_scritchui_checkCast_menuKind(sjme_pointer inPtr);
2089
2090 /*--------------------------------------------------------------------------*/
2091
2092 /* Anti-C++. */
2093 #ifdef __cplusplus
2094         #ifdef SJME_CXX_SQUIRRELJME_SCRITCHUI_H
2095 }
2096                 #undef SJME_CXX_SQUIRRELJME_SCRITCHUI_H
2097                 #undef SJME_CXX_IS_EXTERNED
2098         #endif /* #ifdef SJME_CXX_SQUIRRELJME_SCRITCHUI_H */
2099 #endif     /* #ifdef __cplusplus */
2100
2101 #endif /* SQUIRRELJME_SCRITCHUI_H */