modules/midp-lcdui/src/main/java/cc/squirreljme/runtime/lcdui/mle/UIBackend.java

   1 // -*- Mode: Java; indent-tabs-mode: t; tab-width: 4 -*-
   2 // ---------------------------------------------------------------------------
   3 // SquirrelJME
   4 //     Copyright (C) Stephanie Gawroriski <xer@multiphasicapps.net>
   5 // ---------------------------------------------------------------------------
   6 // SquirrelJME is under the GNU General Public License v3+, or later.
   7 // See license.mkd for licensing and copyright information.
   8 // ---------------------------------------------------------------------------
   9
  10 package cc.squirreljme.runtime.lcdui.mle;
  11
  12 import cc.squirreljme.jvm.mle.UIFormShelf;
  13 import cc.squirreljme.jvm.mle.brackets.UIDisplayBracket;
  14 import cc.squirreljme.jvm.mle.brackets.UIDrawableBracket;
  15 import cc.squirreljme.jvm.mle.brackets.UIFormBracket;
  16 import cc.squirreljme.jvm.mle.brackets.UIItemBracket;
  17 import cc.squirreljme.jvm.mle.brackets.UIWidgetBracket;
  18 import cc.squirreljme.jvm.mle.callbacks.UIDisplayCallback;
  19 import cc.squirreljme.jvm.mle.callbacks.UIFormCallback;
  20 import cc.squirreljme.jvm.mle.constants.UIItemPosition;
  21 import cc.squirreljme.jvm.mle.constants.UIItemType;
  22 import cc.squirreljme.jvm.mle.constants.UIMetricType;
  23 import cc.squirreljme.jvm.mle.constants.UIWidgetProperty;
  24 import cc.squirreljme.jvm.mle.exceptions.MLECallError;
  25 import cc.squirreljme.runtime.cldc.annotation.Exported;
  26
  27 /**
  28  * This interface is used as a wrapper around {@link UIFormShelf}, it is
  29  * implemented by a class and essentially is used to forward calls to the
  30  * true backing implementation. This is here so that in the event that
  31  * {@link UIFormShelf} is not supported, that there is a fall-back.
  32  *
  33  * @since 2020/06/30
  34  */
  35 @Exported
  36 public interface UIBackend
  37 {
  38         /**
  39          * Registers a callback for a display when it needs to be drawn or the
  40          * display state changes.
  41          *
  42          * @param __display The display that the callback will act under.
  43          * @param __callback The callback to register.
  44          * @throws MLECallError If {@code __display} is {@code null}.
  45          * @see UIDisplayCallback
  46          * @since 2023/01/14
  47          */
  48         @Exported
  49         void callback(UIDisplayBracket __display,
  50                 UIDisplayCallback __callback)
  51                 throws MLECallError;
  52
  53         /**
  54          * This is used to register the callback which is called with the user
  55          * interface events and otherwise.
  56          *
  57          * @param __form The form that the callback will act under.
  58          * @param __callback The callback to register.
  59          * @throws MLECallError If {@code __form} is {@code null}.
  60          * @since 2020/07/03
  61          */
  62         @Exported
  63         void callback(UIFormBracket __form, UIFormCallback __callback)
  64                 throws MLECallError;
  65
  66         /**
  67          * Returns the displays which are attached to the system.
  68          *
  69          * @return The display heads which are attached to a system, these objects
  70          * here represent physical displays.
  71          * @throws MLECallError If there are no displays.
  72          * @since 2020/07/01
  73          */
  74         @Exported
  75         UIDisplayBracket[] displays()
  76                 throws MLECallError;
  77
  78         /**
  79          * Returns the form that is currently being shown on the display.
  80          *
  81          * @param __display The display to query.
  82          * @return The form that is currently shown or {@code null}.
  83          * @throws MLECallError On null arguments.
  84          * @since 2020/07/01
  85          */
  86         @Exported
  87         UIFormBracket displayCurrent(UIDisplayBracket __display)
  88                 throws MLECallError;
  89
  90         /**
  91          * Shows the given display without having a form be displayed on the
  92          * display, this can be used for raw graphics operations such as canvases
  93          * and otherwise.
  94          *
  95          * @param __display The display to show.
  96          * @param __show Should the display be shown or hidden?
  97          * @throws MLECallError If {@code __display} is {@code null} or there was
  98          * an error showing the display.
  99          * @since 2023/01/14
 100          */
 101         @Exported
 102         void displayShow(UIDisplayBracket __display,
 103                 boolean __show)
 104                 throws MLECallError;
 105
 106         /**
 107          * Show the given form on the display.
 108          *
 109          * @param __display The form to display on screen.
 110          * @param __form The form to display, if {@code null} then no item is
 111          * shown on the display.
 112          * @throws MLECallError On {@code __display} is {@code null}.
 113          * @since 2020/07/01
 114          */
 115         @Exported
 116         void displayShow(UIDisplayBracket __display, UIFormBracket __form)
 117                 throws MLECallError;
 118
 119         /**
 120          * Checks if the two displays represent the same {@link UIDisplayBracket}.
 121          *
 122          * @param __a The first.
 123          * @param __b The second.
 124          * @return If these are the same display.
 125          * @throws MLECallError If either is {@code null}.
 126          * @since 2020/07/01
 127          */
 128         @Exported
 129         boolean equals(UIDisplayBracket __a, UIDisplayBracket __b)
 130                 throws MLECallError;
 131
 132         /**
 133          * Checks if the two drawables represent the same
 134          * {@link UIDrawableBracket}.
 135          *
 136          * @param __a The first.
 137          * @param __b The second.
 138          * @return If these are the same drawable.
 139          * @throws MLECallError If either is {@code null}.
 140          * @since 2023/01/13
 141          */
 142         @Exported
 143         boolean equals(UIDrawableBracket __a, UIDrawableBracket __b)
 144                 throws MLECallError;
 145
 146         /**
 147          * Checks if the two displays represent the same {@link UIFormBracket}.
 148          *
 149          * @param __a The first.
 150          * @param __b The second.
 151          * @return If these are the same form.
 152          * @throws MLECallError If either is {@code null}.
 153          * @since 2020/07/01
 154          */
 155         @Exported
 156         boolean equals(UIFormBracket __a, UIFormBracket __b)
 157                 throws MLECallError;
 158
 159         /**
 160          * Checks if the two displays represent the same {@link UIItemBracket}.
 161          *
 162          * @param __a The first.
 163          * @param __b The second.
 164          * @return If these are the same item.
 165          * @throws MLECallError If either is {@code null}.
 166          * @since 2020/07/01
 167          */
 168         @Exported
 169         boolean equals(UIItemBracket __a, UIItemBracket __b)
 170                 throws MLECallError;
 171
 172         /**
 173          * Checks if the two displays represent the same {@link UIWidgetBracket}.
 174          *
 175          * @param __a The first.
 176          * @param __b The second.
 177          * @return If these are the same item.
 178          * @throws MLECallError If either is {@code null}.
 179          * @since 2020/09/20
 180          */
 181         @Exported
 182         boolean equals(UIWidgetBracket __a, UIWidgetBracket __b)
 183                 throws MLECallError;
 184
 185         /**
 186          * Flushes all of the events and forces them to be processed.
 187          *
 188          * @throws MLECallError If events could not be flushed.
 189          * @since 2020/07/26
 190          */
 191         @Exported
 192         void flushEvents()
 193                 throws MLECallError;
 194
 195         /**
 196          * Deletes the given form.
 197          *
 198          * @param __form The form to delete.
 199          * @throws MLECallError On null arguments or the form could not be deleted.
 200          * @since 2020/07/01
 201          */
 202         @Exported
 203         void formDelete(UIFormBracket __form)
 204                 throws MLECallError;
 205
 206         /**
 207          * Returns the item at the given location.
 208          *
 209          * @param __form The form to check.
 210          * @param __pos The position to check, may be {@link UIItemPosition}.
 211          * @return The item at the given position or {@code null} if it is not
 212          * there.
 213          * @throws MLECallError If the form is not valid or if the position is
 214          * not valid.
 215          * @since 2020/07/19
 216          */
 217         @Exported
 218         UIItemBracket formItemAtPosition(UIFormBracket __form, int __pos)
 219                 throws MLECallError;
 220
 221         /**
 222          * Returns the number of items on the form.
 223          *
 224          * @param __form The form to get the count from.
 225          * @return The number of normal items on the form.
 226          * @throws MLECallError If the form is null or not valid.
 227          * @since 2020/07/19
 228          */
 229         @Exported
 230         int formItemCount(UIFormBracket __form)
 231                 throws MLECallError;
 232
 233         /**
 234          * Returns the position of the item on the given form, or if it is not
 235          * on the form.
 236          *
 237          * @param __form The form to get from.
 238          * @param __item The item being queried.
 239          * @return The position of the item, may be one of
 240          * {@link UIItemPosition} or
 241          * {@link UIItemPosition#NOT_ON_FORM} if not on the form.
 242          * @throws MLECallError If the form and item are null.
 243          * @since 2020/07/18
 244          */
 245         @Exported
 246         int formItemPosition(UIFormBracket __form, UIItemBracket __item)
 247                 throws MLECallError;
 248
 249         /**
 250          * Sets the position of a form's item.
 251          *
 252          * @param __form The form to set on.
 253          * @param __item The item to set.
 254          * @param __pos The position to set the item at, may be one of
 255          * {@link UIItemPosition}.
 256          * @throws MLECallError If the form or item are null, or the position
 257          * is not valid.
 258          * @since 2020/07/18
 259          */
 260         @Exported
 261         void formItemPosition(UIFormBracket __form, UIItemBracket __item,
 262                 int __pos)
 263                 throws MLECallError;
 264
 265         /**
 266          * Removes the item at the given position on the form.
 267          *
 268          * @param __form The form to remove from.
 269          * @param __pos The item to be removed.
 270          * @return The item that was removed.
 271          * @throws MLECallError If the form or item are null, the position is
 272          * not valid, or there was no item at the position.
 273          * @since 2020/07/18
 274          */
 275         @Exported
 276         UIItemBracket formItemRemove(UIFormBracket __form, int __pos)
 277                 throws MLECallError;
 278
 279         /**
 280          * Creates a new form.
 281          *
 282          * @return The newly created form.
 283          * @throws MLECallError If the form could not be created.
 284          * @since 2020/07/01
 285          */
 286         @Exported
 287         UIFormBracket formNew()
 288                 throws MLECallError;
 289
 290         /**
 291          * Forces a form to be refreshed.
 292          *
 293          * @param __form The form to refresh
 294          * @throws MLECallError On null arguments or the form is not valid.
 295          * @since 2022/07/20
 296          */
 297         @Exported
 298         void formRefresh(UIFormBracket __form)
 299                 throws MLECallError;
 300
 301         /**
 302          * Returns the injector for forms, which is used for testing purposes.
 303          *
 304          * @return The injector for the shelf.
 305          * @throws MLECallError If injecting is not supported.
 306          * @since 2020/07/26
 307          */
 308         @Exported
 309         UIFormCallback injector()
 310                 throws MLECallError;
 311
 312         /**
 313          * Deletes the specified item.
 314          *
 315          * @param __item The item to delete.
 316          * @throws MLECallError On null arguments, if the item could not be
 317          * deleted, if the item was already deleted, or if the item is currently
 318          * active within a form.
 319          * @since 2020/07/18
 320          */
 321         @Exported
 322         void itemDelete(UIItemBracket __item)
 323                 throws MLECallError;
 324
 325         /**
 326          * Returns the form the item is on.
 327          *
 328          * @param __item The item to get.
 329          * @return The form the item is on.
 330          * @throws MLECallError If {@code __item} is {@code null}.
 331          * @since 2021/01/03
 332          */
 333         @Exported
 334         UIFormBracket itemForm(UIItemBracket __item)
 335                 throws MLECallError;
 336
 337         /**
 338          * Creates a new item.
 339          *
 340          * @param __type The {@link UIItemType} to create.
 341          * @return The newly created item.
 342          * @throws MLECallError If the item could not be created or the type was
 343          * not valid.
 344          * @since 2020/07/17
 345          */
 346         @Exported
 347         UIItemBracket itemNew(int __type)
 348                 throws MLECallError;
 349
 350         /**
 351          * Calls the given method serially within the main event handler.
 352          *
 353          * @param __display The display identifier.
 354          * @param __serialId The serial identifier.
 355          * @throws MLECallError If the call is not valid.
 356          * @since 2020/10/03
 357          */
 358         @Exported
 359         void later(UIDisplayBracket __display, int __serialId)
 360                 throws MLECallError;
 361
 362         /**
 363          * Returns a metric which describes something about the user interface
 364          * forms implementation or other details about the system.
 365          *
 366          * @param __display The display to get the metric of.
 367          * @param __metric One of {@link UIMetricType}. The metric
 368          * {@link UIMetricType#UIFORMS_SUPPORTED} is always a valid metric and
 369          * must be supported, even if the implementation lacks forms.
 370          * @return The value of the metric.
 371          * @throws MLECallError If the metric is out of range or forms are not
 372          * supported and the metric is not {@link UIMetricType#UIFORMS_SUPPORTED}.
 373          * @since 2020/06/30
 374          */
 375         @Exported
 376         int metric(UIDisplayBracket __display, int __metric)
 377                 throws MLECallError;
 378
 379         /**
 380          * Sets the given item property.
 381          *
 382          * @param __item The item to set.
 383          * @param __intProp The {@link UIWidgetProperty}.
 384          * @param __sub The sub-index.
 385          * @param __newValue The new value to set.
 386          * @throws MLECallError If the item is not valid or the property is not
 387          * valid or not an integer property.
 388          * @since 2020/09/13
 389          */
 390         @Exported
 391         void widgetProperty(UIWidgetBracket __item, int __intProp, int __sub,
 392                 int __newValue);
 393
 394         /**
 395          * Sets the given item property.
 396          *
 397          * @param __item The item to set.
 398          * @param __strProp The {@link UIWidgetProperty}.
 399          * @param __sub The sub-index.
 400          * @param __newValue The new value to set.
 401          * @throws MLECallError If the item is not valid or the property is not
 402          * valid or not a string property.
 403          * @since 2020/09/13
 404          */
 405         @Exported
 406         void widgetProperty(UIWidgetBracket __item, int __strProp, int __sub,
 407                 String __newValue);
 408
 409         /**
 410          * Gets a property of the given widget.
 411          *
 412          * @param __widget The widget to get from.
 413          * @param __intProp The {@link UIWidgetProperty}.
 414          * @param __sub The sub-index.
 415          * @return The value of the property.
 416          * @throws MLECallError If the widget or property is not valid.
 417          * @since 2020/09/21
 418          */
 419         @Exported
 420         int widgetPropertyInt(UIWidgetBracket __widget, int __intProp, int __sub)
 421                 throws MLECallError;
 422
 423         /**
 424          * Gets a property of the given widget.
 425          *
 426          * @param __widget The widget to get from.
 427          * @param __strProp The {@link UIWidgetProperty}.
 428          * @param __sub The sub-index.
 429          * @return The value of the property.
 430          * @throws MLECallError If the widget or property is not valid.
 431          * @since 2020/09/21
 432          */
 433         @Exported
 434         String widgetPropertyStr(UIWidgetBracket __widget, int __strProp,
 435                 int __sub)
 436                 throws MLECallError;
 437 }