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