diff --git a/docs/TODO.md b/docs/TODO.md deleted file mode 100644 index 9c357b9241..0000000000 --- a/docs/TODO.md +++ /dev/null @@ -1,111 +0,0 @@ -# Developer Guide Cleanup Plan - -## Tooling & Build Flow Modernization - -- [ ] Retire or substantially revise `Travis-CI-Integration.asciidoc` to highlight our current CI guidance (GitHub Actions templates, self-hosted options) and archive Travis-specific screenshots and steps.【F:docs/developer-guide/Travis-CI-Integration.asciidoc†L1-L112】 -- [ ] Update the Designer/tooling coverage in `basics.asciidoc` so it walks through launching the modern Designer distribution from Maven projects without relying on `designer_1.jar` shell commands.【F:docs/developer-guide/basics.asciidoc†L1050-L1070】 -- [ ] Rebuild `Working-With-The-GUI-Builder.asciidoc` around the current GUI Builder experience (with Java 11+ support, IntelliJ/VScode integration), moving legacy troubleshooting for `guibuilder_1.jar` into an appendix or "legacy" callout.【F:docs/developer-guide/Working-With-The-GUI-Builder.asciidoc†L1-L126】 - -## Platform & Distribution Chapters - -- [ ] Audit `Working-with-UWP.asciidoc` to determine whether Codename One still targets UWP; either replace it with Windows desktop packaging guidance (MSIX, Windows Store status) or mark it as deprecated content with clear banners.【F:docs/developer-guide/Working-with-UWP.asciidoc†L1-L200】 -- [ ] Rename and modernize `Working-with-Mac-OS-X.asciidoc` for contemporary macOS terminology, update certificate instructions, and verify any 2020-era warnings (e.g., `mac.desktop-vm`) still apply.【F:docs/developer-guide/Working-with-Mac-OS-X.asciidoc†L1-L109】 -- [ ] Overhaul `Working-With-iOS.asciidoc` to drop 32-bit troubleshooting guidance, incorporate current minimum OS versions, and replace the deprecated screenshot-generation section with Launch Screen storyboard best practices (including updated asset tables).【F:docs/developer-guide/Working-With-iOS.asciidoc†L3-L166】 -- [ ] Refresh `Working-With-Javascript.asciidoc` to document the current TeaVM capabilities, known limitations, and deployment formats without referencing Codename One 3.6-era constraints.【F:docs/developer-guide/Working-With-Javascript.asciidoc†L1-L120】 -- [ ] Update `signing.asciidoc` terminology (App Store Connect vs. iTunes Connect), confirm current device/certificate limits, and streamline the wizard walkthrough to match today’s Codename One Settings UI.【F:docs/developer-guide/signing.asciidoc†L46-L120】 -- [ ] Expand the manual signing section to spell out the `codenameone_settings.properties` keys for debug/release certificates and provisioning profiles on both iOS (`codename1.ios.*`) and Android (`codename1.android.keystore*`), so the instructions match what the builders actually read during packaging.【F:Samples/SampleProjectTemplate/codenameone_settings.properties†L3-L30】【F:maven/codenameone-maven-plugin/src/main/resources/com/codename1/maven/buildxml-template.xml†L20-L56】【F:maven/codenameone-maven-plugin/src/main/java/com/codename1/maven/CN1BuildMojo.java†L762-L813】 -- [ ] Update the push entitlement checklist to explain that LocalNotification usage causes the iOS builder to auto-enable notification capabilities even when `ios.includePush` is false, so developers don’t disable the entitlement by mistake.【F:maven/codenameone-maven-plugin/src/main/java/com/codename1/builders/IPhoneBuilder.java†L599-L600】【F:maven/codenameone-maven-plugin/src/main/java/com/codename1/builders/IPhoneBuilder.java†L1209-L1233】 - -## Assets & Cross-Cutting Tasks - -- [ ] Inventory the screenshots referenced across the platform chapters (e.g., Windows/UWP dashboards, Travis panels, Codename One Settings) and plan replacements that match the current dashboard/IDE UI after the written updates land.【F:docs/developer-guide/Working-with-UWP.asciidoc†L18-L146】【F:docs/developer-guide/Travis-CI-Integration.asciidoc†L30-L106】 -- [ ] Add a short "How to contribute updates" section that links to CONTRIBUTING guidelines and explains our review process, so readers know how to submit documentation fixes through PRs instead of the deprecated wiki flow.【F:docs/developer-guide/About-This-Guide.asciidoc†L6-L15】【F:CONTRIBUTING.md†L1-L120】 - -## CSS Chapter Updates - -- [ ] Extend the `RoundBorder` shadow guidance to mention the `cn1-box-shadow-inset` flag so designers know how to request inset shadows instead of only the outer spread documented today.【F:docs/developer-guide/css.asciidoc†L432-L448】【F:CodenameOneDesigner/src/com/codename1/designer/css/CSSTheme.java†L6277-L6315】 -- [ ] Document the per-corner elliptical radius controls (`cn1-border-top-left-radius-x/y`, etc.) and how they’re populated from the CSS `border-radius` shorthand, since the chapter currently stops at basic radius examples.【F:docs/developer-guide/css.asciidoc†L404-L438】【F:CodenameOneDesigner/src/com/codename1/designer/css/CSSTheme.java†L6153-L6214】 - -## Graphics Chapter Updates - -- [ ] Refresh the shapes/transforms device support copy and table so it matches today’s active ports (Android, iOS, JavaScript, desktop, and UWP) instead of legacy targets like J2ME, BlackBerry 4.x, or Windows Phone “pending” entries.【F:docs/developer-guide/graphics.asciidoc†L135-L348】【F:README.md†L14-L32】 -- [ ] Expand the painting primer to cover gradient paints (`setColor(Paint)`, `LinearGradientPaint`, `fillLinearGradient()`, `fillRadialGradient()`/`fillRectRadialGradient()`) rather than stopping at solid-color fills in the manual’s basic drawing section.【F:docs/developer-guide/graphics.asciidoc†L40-L140】【F:CodenameOne/src/com/codename1/ui/Graphics.java†L187-L205】【F:CodenameOne/src/com/codename1/ui/Graphics.java†L945-L1029】【F:CodenameOne/src/com/codename1/ui/LinearGradientPaint.java†L32-L109】 -- [ ] Add guidance on global alpha and anti-aliasing toggles (`isAlphaSupported()`, `setAlpha()`, `concatenateAlpha()`, `setAntiAliased*()`), which are missing even though the chapter already discusses alpha channels for images.【F:docs/developer-guide/graphics.asciidoc†L1001-L1087】【F:CodenameOne/src/com/codename1/ui/Graphics.java†L1110-L1225】 - -## IO Chapter Updates - -- [ ] Update the SQLite portability callout so it reflects current platform support—including Windows/UWP—rather than warning that Codename One still lacks Windows database support.【F:docs/developer-guide/io.asciidoc†L251-L259】【F:Ports/UWP/VSProjectTemplate/UWPApp/src/com/codename1/impl/SilverlightImplementation.cs†L4215-L4243】 -- [ ] Expand the Preferences section to cover advanced helpers (`setPreferencesLocation(...)`, batched `set(Map)`, and `PreferenceListener` callbacks) so readers can take advantage of the storage customization and change-notification hooks already in the runtime.【F:docs/developer-guide/io.asciidoc†L113-L132】【F:CodenameOne/src/com/codename1/io/Preferences.java†L67-L136】【F:CodenameOne/src/com/codename1/io/Preferences.java†L435-L491】 -- [ ] Document the per-request timeout and retry knobs (`setTimeout(...)`, `setSilentRetryCount(...)`) that were added to `ConnectionRequest`, since the current networking section stops at thread counts and fail-silent flags.【F:docs/developer-guide/io.asciidoc†L358-L415】【F:CodenameOne/src/com/codename1/io/ConnectionRequest.java†L2088-L2110】【F:CodenameOne/src/com/codename1/io/ConnectionRequest.java†L2388-L2416】 -- [ ] Extend the REST builder coverage with the newer configuration hooks (e.g., `.priority(...)`, `.cookiesEnabled(...)`, `.useBoolean(...)`, `.useLongs(...)`) so the examples match what `RequestBuilder` exposes today.【F:docs/developer-guide/io.asciidoc†L1274-L1338】【F:CodenameOne/src/com/codename1/io/rest/RequestBuilder.java†L79-L148】【F:CodenameOne/src/com/codename1/io/rest/RequestBuilder.java†L165-L212】 - -## Performance Chapter Updates - -- [ ] Expand the Performance Monitor section to cover the simulator's newer tooling—`Pause/Continue`, `Clear Data`, the `GC` trigger, and the live "Image Memory Overhead" meter—so the text reflects what developers see today instead of only listing the two default tabs.【F:docs/developer-guide/performance.asciidoc†L48-L76】【F:Ports/JavaSE/src/com/codename1/impl/javase/PerformanceMonitor.java†L124-L220】 -- [ ] Update the error-reporting walkthrough to mention `Log.sendLogAsync()` as the non-blocking alternative that Codename One’s lifecycle helper already uses for network failures, rather than implying `Log.sendLog()` is the only option.【F:docs/developer-guide/performance.asciidoc†L132-L141】【F:CodenameOne/src/com/codename1/io/Log.java†L192-L213】【F:CodenameOne/src/com/codename1/system/Lifecycle.java†L112-L120】 -- [ ] Document how `Display.setCrashReporter(CrashReport)` lets apps plug in their own crash reporting pipeline alongside `Log.bindCrashProtection(...)`, completing the guide’s coverage of EDT error handlers.【F:docs/developer-guide/performance.asciidoc†L128-L143】【F:CodenameOne/src/com/codename1/ui/Display.java†L4582-L4598】【F:CodenameOne/src/com/codename1/system/CrashReport.java†L23-L37】 - -## Components Chapter Updates - -- [ ] Expand the `InputComponent` theme constant list to cover the newer error-line toggle (`textComponentErrorLineBorderBool`) and multiline error label flag (`inputComponentErrorMultilineBool`) so the guidance mirrors the current API surface.【F:docs/developer-guide/The-Components-Of-Codename-One.asciidoc†L656-L705】【F:CodenameOne/src/com/codename1/ui/InputComponent.java†L48-L149】 -- [ ] Document the `MultiButton` badge helpers (`setBadgeText()`, `setBadgeUIID()`, `getBadgeStyleComponent()`) and styling expectations that were added after the existing MultiButton section was written.【F:docs/developer-guide/The-Components-Of-Codename-One.asciidoc†L926-L982】【F:CodenameOne/src/com/codename1/components/MultiButton.java†L1494-L1546】 -- [ ] Update the `InteractionDialog` coverage to describe pointer-outside auto-dismiss (`setDisposeWhenPointerOutOfBounds()`), the form-layered-pane mode, and the animation toggles introduced in the component implementation.【F:docs/developer-guide/The-Components-Of-Codename-One.asciidoc†L300-L328】【F:CodenameOne/src/com/codename1/components/InteractionDialog.java†L135-L152】【F:CodenameOne/src/com/codename1/components/InteractionDialog.java†L544-L606】【F:CodenameOne/src/com/codename1/components/InteractionDialog.java†L884-L916】 - -## Advanced Theming Updates - -- [ ] Expand the `Theme Constants` table in `Advanced-Theming.asciidoc` to cover the newer Infinite Progress options (`infiniteMaterialDesignSize`, `infiniteMaterialImageSize`, `infiniteDefaultColor`) alongside the existing `infiniteImage` entry.【F:docs/developer-guide/Advanced-Theming.asciidoc†L267-L343】【F:CodenameOne/src/com/codename1/components/InfiniteProgress.java†L245-L276】 -- [ ] Document the toolbar navigation constants now used at runtime—`landscapeTitleUiidBool`, `iosStyleBackArrowBool`, `hideRightSideMenuBool`, plus the right-side menu image overrides—so the table matches current `Toolbar` behavior.【F:docs/developer-guide/Advanced-Theming.asciidoc†L249-L344】【F:CodenameOne/src/com/codename1/ui/Toolbar.java†L146-L149】【F:CodenameOne/src/com/codename1/ui/Toolbar.java†L492-L535】【F:CodenameOne/src/com/codename1/ui/Toolbar.java†L1411-L1439】 -- [ ] Add an entry for `interactionDialogSpeedInt` (and related Interaction Dialog animation guidance) that reflects the timings pulled from theme constants today.【F:docs/developer-guide/Advanced-Theming.asciidoc†L321-L380】【F:CodenameOne/src/com/codename1/components/InteractionDialog.java†L318-L417】 -- [ ] Introduce the signature capture button UIID constants (`sigButtonOKUIID`, `sigButtonResetUIID`, `sigButtonCancelUIID`) so designers know they can theme the `SignatureComponent` controls.【F:docs/developer-guide/Advanced-Theming.asciidoc†L321-L400】【F:CodenameOne/src/com/codename1/components/SignatureComponent.java†L344-L350】 -- [ ] Cover the composite component UIID hooks (`iconUiid`, `textUiid`, `emblemUiid`) exposed by `SpanLabel`, `SpanButton`, `MultiButton`, and `SpanMultiButton` to round out the constants table.【F:docs/developer-guide/Advanced-Theming.asciidoc†L321-L400】【F:CodenameOne/src/com/codename1/components/SpanLabel.java†L134-L136】【F:CodenameOne/src/com/codename1/components/SpanButton.java†L194-L196】【F:CodenameOne/src/com/codename1/components/MultiButton.java†L952-L1052】【F:CodenameOne/src/com/codename1/components/SpanMultiButton.java†L902-L1002】 - -## Animations Chapter Updates - -- [ ] Refresh the `Layout Animations` walkthrough so it acknowledges the `Form.animateLayout*()` wrappers instead of claiming you must animate the content pane directly, and update the sample call accordingly.【F:docs/developer-guide/Animations.asciidoc†L48-L57】【F:CodenameOne/src/com/codename1/ui/Form.java†L1873-L1895】 -- [ ] Align the `Unlayout Animations` guidance with today’s API surface by documenting the non-blocking `animateUnlayout(int, int, Runnable)`/`Form.animateUnlayout*()` variants rather than stating no “standard” unlayout exists.【F:docs/developer-guide/Animations.asciidoc†L102-L188】【F:CodenameOne/src/com/codename1/ui/Form.java†L1898-L1908】【F:CodenameOne/src/com/codename1/ui/Container.java†L3810-L3846】 -- [ ] Correct the `Hiding & Visibility` section to reflect the current `Component.setHidden(boolean, boolean)` implementation that caches/restores margins (without UIID resets) and mention the optional margin flag accurately.【F:docs/developer-guide/Animations.asciidoc†L124-L140】【F:CodenameOne/src/com/codename1/ui/Component.java†L7880-L7904】 - -## Events Chapter Updates - -- [ ] Expand the high-level events coverage in `Events.asciidoc` to cover the cross-platform message bus APIs (`Display.postMessage()`, `addMessageListener()`, and `MessageEvent` prompts) so native-to-Java bridging is documented alongside `NetworkEvent`.【F:docs/developer-guide/Events.asciidoc†L105-L150】【F:CodenameOne/src/com/codename1/ui/Display.java†L3269-L3323】【F:CodenameOne/src/com/codename1/ui/events/MessageEvent.java†L28-L117】 -- [ ] Document the component lifecycle hooks introduced with `Component.addStateChangeListener()`/`ComponentStateChangeEvent` so initialization events appear next to the existing listener guidance.【F:docs/developer-guide/Events.asciidoc†L152-L232】【F:CodenameOne/src/com/codename1/ui/Component.java†L5593-L5629】【F:CodenameOne/src/com/codename1/ui/events/ComponentStateChangeEvent.java†L24-L44】 -- [ ] Update the low-level pointer callback list to include the hover variants (`pointerHover`, `pointerHoverPressed`, `pointerHoverReleased`) that desktop and pen devices fire today.【F:docs/developer-guide/Events.asciidoc†L301-L324】【F:CodenameOne/src/com/codename1/ui/Component.java†L4578-L4648】【F:CodenameOne/src/com/codename1/ui/Form.java†L3510-L3557】 -- [ ] Add coverage of `Component.addDragFinishedListener()` and the `ActionEvent.Type.DragFinished` dispatch so drag-and-drop cleanup hooks are explained with the other pointer events.【F:docs/developer-guide/Events.asciidoc†L301-L344】【F:CodenameOne/src/com/codename1/ui/Component.java†L5560-L5603】【F:CodenameOne/src/com/codename1/ui/events/ActionEvent.java†L456-L548】 -- [ ] Introduce the swipe action events emitted by `SwipeableContainer` (`ActionEvent.Type.Swipe`) so the chapter points to the modern gesture listener APIs beyond scroll and selection changes.【F:docs/developer-guide/Events.asciidoc†L32-L220】【F:CodenameOne/src/com/codename1/ui/events/ActionEvent.java†L456-L476】【F:CodenameOne/src/com/codename1/ui/SwipeableContainer.java†L220-L239】 -- [ ] Call out the dedicated `Component.addLongPressListener()` helper as the preferred way to capture long presses instead of overriding `longPointerPress` directly.【F:docs/developer-guide/Events.asciidoc†L301-L324】【F:CodenameOne/src/com/codename1/ui/Component.java†L5633-L5655】 - -## Advanced Topics / Under the Hood Updates - -- [ ] Replace the Marshmallow-era target SDK guidance in `Advanced-Topics-Under-The-Hood.asciidoc` so it documents the current Gradle 8/target SDK defaults instead of claiming the build still targets API 21 by default.【F:docs/developer-guide/Advanced-Topics-Under-The-Hood.asciidoc†L681-L687】【F:maven/codenameone-maven-plugin/src/main/java/com/codename1/builders/AndroidGradleBuilder.java†L637-L663】【F:maven/codenameone-maven-plugin/src/main/java/com/codename1/builders/AndroidGradleBuilder.java†L900-L923】 -- [ ] Refresh the Android permissions mapping to cover new runtime prompts (e.g., `POST_NOTIFICATIONS`, background location) and remove stale entries like `ACCESS_MOCK_LOCATION` so it reflects what the builder and Android implementation request now.【F:docs/developer-guide/Advanced-Topics-Under-The-Hood.asciidoc†L632-L660】【F:maven/codenameone-maven-plugin/src/main/java/com/codename1/builders/AndroidGradleBuilder.java†L123-L299】【F:Ports/Android/src/com/codename1/impl/android/AndroidImplementation.java†L8731-L8734】 - -## Miscellaneous Features Chapter Updates - -- [ ] Rewrite the SMS example in `Miscellaneous-Features.asciidoc` to use the current `Display.sendSMS()/CN.sendSMS` APIs (with `IOException` handling) instead of the nonexistent `setSMS` call, and update the platform notes to reflect today’s Android/iOS support rather than legacy Windows Phone/BlackBerry behavior.【F:docs/developer-guide/Miscellaneous-Features.asciidoc†L9-L48】【F:CodenameOne/src/com/codename1/ui/Display.java†L4010-L4050】【F:CodenameOne/src/com/codename1/ui/CN.java†L898-L921】 -- [ ] Fix the Contacts samples so they call the static `ContactsManager.getContacts(...)` helper (instead of the deprecated `getAllContacts(...)` overload) and refer to `ContactsManager.isAllContactsFast()` when describing the fast-path query, matching the API surface in `ContactsManager`.【F:docs/developer-guide/Miscellaneous-Features.asciidoc†L121-L193】【F:CodenameOne/src/com/codename1/contacts/ContactsManager.java†L112-L178】 -- [ ] Update the email section to explain that `Message.sendMessageViaCloud()`/`sendMessageViaCloudSync()` are deprecated and no longer functional, and point readers to supported alternatives for server-side email delivery.【F:docs/developer-guide/Miscellaneous-Features.asciidoc†L88-L99】【F:CodenameOne/src/com/codename1/messaging/Message.java†L158-L190】 - -## Monetization Chapter Updates - -- [ ] Refresh the `PurchaseCallback` walkthrough in `Monetization.asciidoc` so it no longer instructs developers to implement the deprecated `itemRefunded()`, `subscriptionStarted()`, and `subscriptionCanceled()` hooks, and instead emphasizes receipt-based state checks.【F:docs/developer-guide/Monetization.asciidoc†L62-L95】【F:CodenameOne/src/com/codename1/payment/PurchaseCallback.java†L52-L73】 -- [ ] Document the promotional-offer overloads for `Purchase.purchase()`/`subscribe()` and the `ApplePromotionalOffer` helper so iOS readers know how to wire discounted subscription campaigns.【F:docs/developer-guide/Monetization.asciidoc†L212-L248】【F:CodenameOne/src/com/codename1/payment/Purchase.java†L324-L375】【F:CodenameOne/src/com/codename1/payment/ApplePromotionalOffer.java†L26-L141】 -- [ ] Expand the subscription management section to cover the runtime restore/manage hooks—`Purchase.isRestoreSupported()`, `Purchase.restore()`, `RestoreCallback`, and `Purchase.isManageSubscriptionsSupported()/manageSubscriptions(String)`—highlighting the built-in flows provided on iOS and Android.【F:docs/developer-guide/Monetization.asciidoc†L212-L248】【F:CodenameOne/src/com/codename1/payment/Purchase.java†L832-L868】【F:CodenameOne/src/com/codename1/payment/RestoreCallback.java†L33-L58】【F:Ports/iOSPort/src/com/codename1/impl/ios/ZoozPurchase.java†L227-L245】【F:Ports/Android/src/com/codename1/impl/android/ZoozPurchase.java†L190-L202】 - -## Push Notifications Chapter Updates - -- [ ] Extend the push type reference in `Push-Notifications.asciidoc` to document type `102` (badge + title + body) so it matches the payloads supported by `PushBuilder` today.【F:docs/developer-guide/Push-Notifications.asciidoc†L143-L162】【F:CodenameOne/src/com/codename1/push/PushBuilder.java†L102-L185】 -- [ ] Introduce the `PushBuilder` helper class when covering rich notifications and client-to-client pushes, illustrating how to build XML payloads without hand-coding strings.【F:docs/developer-guide/Push-Notifications.asciidoc†L657-L682】【F:CodenameOne/src/com/codename1/push/PushBuilder.java†L42-L200】 -- [ ] Document how to retrieve hidden metadata, titles, and text responses from `PushContent` (e.g., `getMetaData()`, `getTextResponse()`) so developers know how to read the full payload their actions deliver.【F:docs/developer-guide/Push-Notifications.asciidoc†L379-L399】【F:CodenameOne/src/com/codename1/push/PushContent.java†L36-L302】 -- [ ] Update the push actions section to cover text-input actions (`PushAction` placeholder/button properties) and explain how to read the user’s reply via `PushContent.getTextResponse()`.【F:docs/developer-guide/Push-Notifications.asciidoc†L321-L399】【F:CodenameOne/src/com/codename1/push/PushAction.java†L32-L133】【F:CodenameOne/src/com/codename1/push/PushContent.java†L248-L302】 - -## Security Chapter Updates - -- [ ] Rewrite the storage encryption walkthrough so it reflects the runtime’s current API surface (custom `Storage` subclasses via `Storage.setStorageInstance(...)`) instead of instructing developers to call the non-existent `EncryptedStorage.install(...)` helper from the deprecated Bouncy Castle cn1lib.【F:docs/developer-guide/security.asciidoc†L86-L128】【a9c60a†L1-L5】【F:CodenameOne/src/com/codename1/io/Storage.java†L70-L113】 -- [ ] Replace the external `SSLCertificateFingerprint` cn1lib recommendation with guidance that leverages `ConnectionRequest`’s built-in certificate introspection and pinning hooks (`setCheckSSLCertificates(...)`, `checkSSLCertificates(...)`, and the nested `SSLCertificate` helper).【F:docs/developer-guide/security.asciidoc†L203-L247】【F:CodenameOne/src/com/codename1/io/ConnectionRequest.java†L535-L585】【F:CodenameOne/src/com/codename1/io/ConnectionRequest.java†L2911-L2970】 - -## EDT Chapter Updates - -- [ ] Update the EDT helper overview so it acknowledges `Display.callSeriallyOnIdle()` alongside the existing `isEDT()`/`callSerially()`/`callSeriallyAndWait()` discussion, and explain when deferring work to the idle queue helps avoid starving animations.【F:docs/developer-guide/The-EDT---Event-Dispatch-Thread.asciidoc†L37-L89】【F:CodenameOne/src/com/codename1/ui/Display.java†L775-L813】 -- [ ] Document the `callSeriallyAndWait(Runnable, int timeout)` overload so background threads know how to cap wait times when marshaling results back to the EDT.【F:docs/developer-guide/The-EDT---Event-Dispatch-Thread.asciidoc†L71-L89】【F:CodenameOne/src/com/codename1/ui/Display.java†L915-L930】 -- [ ] Add coverage of `Display.invokeWithoutBlocking()`/`invokeWithoutBlockingWithResultSync()` and the `BlockingDisallowedException` so the guide reflects how frameworks can guard against nested `invokeAndBlock` usage.【F:docs/developer-guide/The-EDT---Event-Dispatch-Thread.asciidoc†L205-L279】【F:CodenameOne/src/com/codename1/ui/Display.java†L1316-L1360】【F:CodenameOne/src/com/codename1/ui/BlockingDisallowedException.java†L37-L38】 -- [ ] Expand the `invokeAndBlock` section to mention the `dropEvents` flag and how blocking is now prevented when invoked under `invokeWithoutBlocking`, matching the current Display implementation.【F:docs/developer-guide/The-EDT---Event-Dispatch-Thread.asciidoc†L205-L279】【F:CodenameOne/src/com/codename1/ui/Display.java†L1370-L1417】 diff --git a/docs/developer-guide/The-EDT---Event-Dispatch-Thread.asciidoc b/docs/developer-guide/The-EDT---Event-Dispatch-Thread.asciidoc index 4cf5cfa32f..a75111d6f3 100644 --- a/docs/developer-guide/The-EDT---Event-Dispatch-Thread.asciidoc +++ b/docs/developer-guide/The-EDT---Event-Dispatch-Thread.asciidoc @@ -34,8 +34,7 @@ Codename One’s networking code automatically spawns its own network thread (se Codename One assumes all modifications to the UI are performed on the EDT but if we spawned a separate thread. How do we force our modifications back into the EDT? -Codename One includes 3 methods in the https://www.codenameone.com/javadoc/com/codename1/ui/Display.html[Display] class to help in these situations: `isEDT()`, `callSerially(Runnable`) & -`callSeriallyAndWait(Runnable)`. +Codename One includes helper methods in the https://www.codenameone.com/javadoc/com/codename1/ui/Display.html[Display] class to help in these situations: `isEDT()`, `callSerially(Runnable)`, `callSeriallyOnIdle(Runnable)`, and `callSeriallyAndWait(Runnable)` (with an optional timeout overload). `isEDT()` is useful for generic code that needs to test whether the current code is executing on the EDT. @@ -86,7 +85,9 @@ if(!globalFlag) { otherMethod(); ---- -TIP: If you are unsure use `callSerially`. The use cases for `callSeriallyAndWait` are very rare. +TIP: If you are unsure use `callSerially`. The use cases for `callSeriallyAndWait` are very rare. When you do need to wait, the overload that accepts a timeout lets background threads marshal results back to the EDT without risking an indefinite stall if the EDT is busy. + +If the work you are posting back to the EDT is expensive and can wait until the UI finishes its current pass, use `callSeriallyOnIdle()`. This queues the runnable for execution only after the EDT completes painting, animations, and any other queued tasks. Deferring longer tasks to the idle queue helps avoid starving animations and transitions when bursts of background callbacks arrive together. ==== callSerially On The EDT @@ -111,6 +112,8 @@ you run into issues in event processing we suggest trying this to see if its the IMPORTANT: You should never invoke callSeriallyAndWait on the EDT since this would effectively mean sleeping on the EDT. We made that method throw an exception if its invoked from the EDT. +If you need to run logic on the EDT but must ensure nothing inside it blocks, the `Display` class also provides `invokeWithoutBlocking()` and `invokeWithoutBlockingWithResultSync()`. These helpers temporarily disable `invokeAndBlock()` for the duration of the runnable. Any nested call to `invokeAndBlock()` while blocking is disabled results in a `BlockingDisallowedException`. Framework code that wraps user callbacks can use these methods to guard against accidental nested blocking that would otherwise deadlock or stall the UI, yet still safely obtain a return value when needed via `invokeWithoutBlockingWithResultSync()`. + === Debugging EDT Violations There are two types of EDT violations: