Applet Migration Guide

Overview

HyperView 3.2 can host application-level applets: programs originally written as java.applet.Applet subclasses (games, demos, visual tools) that use the applet lifecycle, drawing, sound, images, parameters, the mouse and the keyboard. With some code changes they run inside the HyperView desktop application, not a browser. The framework keeps applet-style APIs under HyperView names: Orange (applet-like base component), OrangeStub (in place of AppletStub), OrangeContext (in place of AppletContext), AudioClip/SoundClip (sound), and HyperFrame (a frame that runs an Orange as an application).

The reference port is Asteroids: Mike Hall’s 1998 applet, ported by Tony Swain (not MIT; it keeps Mike Hall’s notice and terms). Every statement in this guide is based on the 3.2 source, with file and line references.

In one sentence: a ported applet is a class that extends ViewMain. It overrides main() in place of init(), draws in a ViewPane, and gets HyperView’s normal mouse, keyboard and event handling.

No source file in the 3.2 tree imports java.applet or javax.swing.JApplet. Names like getAppletContext() are HyperView’s own methods.

Why migration is required on JDK 26

• JEP 504, “Remove the Applet API”, was delivered in JDK 26. It removes the whole java.applet package (Applet, AppletContext, AppletStub, AudioClip) plus javax.swing.JApplet and java.beans.AppletInitializer. The API was deprecated in JDK 9 (JEP 289) and deprecated for removal in JDK 17 (JEP 398).
• Oracle’s JDK 26 “Removed APIs” list also includes java.lang.Thread.stop, which many old applets call in stop().
• HyperView 3.2 is built with JDK 26 (compile26), so an unmodified applet will not compile against it. The steps below replace every removed type with HyperView equivalents.

How hosting works

The host class: extend ViewMain

• HyperView is the abstract base: public abstract class HyperView extends Orange implements Runnable, … (HyperView.java line 24) with abstract public boolean main(); (line 3500).
• ViewMain is the application class built on it: public class ViewMain extends HyperView (ViewMain.java line 8), with a public no-argument constructor (line 13) and public boolean main() (line 18), which builds the HyperView screen and its gadgets and returns true.
• A ported applet extends ViewMain; that is how HyperView hosts it. Your class overrides main() in place of the applet’s init(). Call super.main() first to keep the normal ViewMain screen, or leave it out to start with an empty view.
• HyperFrame is the window and the AppletStub replacement. makeOrange() calls setStub(this) (HyperFrame.java line 102), turns name=value arguments into parameters, adds your view to a JFrame (BorderLayout.CENTER), then calls init() and start() (lines 182–183). HyperView then calls your main() once (“Call the implementer’s ViewMain.main()”, HyperView.java lines 1529–1530).
• HyperView.main(String[]) always starts a plain ViewMain (HyperView.java lines 6720–6747). Your class has its own static main(String[]) doing the same two steps with your class: IncrementalID.reset(0), then new HyperFrame(new MyApplet(), tID, args, 640, 480).

The drawing surface: a ViewPane (how Asteroids works)

• The applet’s animation becomes a ViewPane (a Gadget → Gob, a HyperView graphic object), constructed with (HyperView tView, int x, int y, int width, int height). It runs its own thread, draws into its pane image (graphics), and HyperView composites it on screen.
• A Dispatch subclass (for example AsteroidsDispatch) creates the pane, calls its start(), adds an abort gadget, waits for the first frame, shows it (GOB_ON_DISPLAY), gives it keyboard focus and calls curView.runView(). That runs HyperView one stack frame deeper until an Abort, after which the Dispatch calls halt().
• The Dispatch is attached to a clickable Gadget in main(). ViewMain does exactly this for Asteroids (the “ Asteroids ” button, ViewMain.java lines 192–195).

Mouse and keyboard: the event path

Because your class extends ViewMain, input reaches your panes through HyperView’s normal event handling. Nothing extra has to be registered. The path in the 3.2 code:

1. HyperFrame captures the events. It registers itself as an AWTEventListener for mouse, mouse-motion, mouse-wheel, key and window events (HyperFrame.java lines 187–190). eventDispatched() (line 209) puts MOUSE_MOVED, MOUSE_DRAGGED, MOUSE_PRESSED, MOUSE_RELEASED and MOUSE_EXITED events into the HyperMouse ring buffer (mouse.msg[]), and KEY_PRESSED/KEY_RELEASED into the HyperKeyboard ring buffer (keyMsg[], lines 270–293), then wakes that thread.
2. The HyperMouse thread (started by HyperView, HyperView.java lines 1229–1238) converts each event to view coordinates and stores them in curView.mouseX/curView.mouseY (HyperMouse.java lines 179–184). On a move it calls onMouseOver() on the gadget under the pointer if GAD_MOUSEOVER_ENA is set (lines 225–233). On a left-button press it finds the top enabled, displayed gadget under the pointer (lines 490–580):
   • if the gadget has GAD_KEYBOARD_ENA, it gets keyboard focus (keyboard.focus, lines 520–522);
   • if it has GOB_CLICK_METHOD, clickX/clickY are set relative to the gadget and GOB_DO_ONCLICK is flagged (lines 558–563);
   • otherwise, if a Dispatch was attached with addDispatch(), the Dispatch is flagged to run (lines 567–570).
   On release it flags GOB_DO_RELEASE for the clicked gadget if GOB_RELEASE_METHOD is set in gobFlags2 (lines 685–688). The right button (BUTTON3) grabs and moves gadgets and opens menus (“Right Mouse to grab”).
3. The HyperView display loop calls onClick() and onRelease() on the flagged gadgets while holding the view monitor, so they don’t need to synchronize with drawing (HyperView.java lines 1885–1903). Flagged Dispatches run from the same loop (line 2477).
4. The mouse wheel: HyperView is registered as the frame’s MouseWheelListener (line 1261). mouseWheelMoved() forwards the event to the gadget with keyboard focus if it has GAD_MOUSE_WHEEL_ENA in gadFlags2 (lines 1097–1106).
5. The keyboard thread calls inKey() on the focused gadget. If that leaves keys in the buffer, curView.inKey() (your view’s default handler) gets them (HyperKeyboard.java lines 105–123).

What the ported classes override:

Pointer position at any time: curView.mouseX, curView.mouseY (view coordinates). Asteroids uses the keyboard path: GAD_KEYBOARD_ENA, focus set by AsteroidsDispatch (line 72), and Asteroids.inKey() (lines 863–1072).

What is supported — and what isn’t

Supported (with the modifications below)

• The lifecycle (init / start / stop→halt / destroy→expunge), your own animation threads, off-screen double-buffered drawing with java.awt.Graphics, Image loading, sound via javax.sound.sampled (.au, including μ-law), mouse input (clicks, release, pointer position, mouse-over, wheel) and keyboard input through HyperView’s event path (details), parameters, code base and document base.
• Media bundled in the jar under com/multiversesocial/hyperview/res/, with a fallback to loose files in the working directory.

Not supported

• Browser embedding: no <applet>/<object> tags and no browser plug-in. showDocument() only prints a status line.
• LiveConnect / netscape.javascript.JSObject: nothing in the tree provides it.
• Applet sandbox: HyperView has no security manager or sandbox, so ported code runs with the same permissions as the application.
• AWT/Swing child components inside the applet (add(new Button()), layouts, JApplet content panes). A ViewPane is not an AWT component, and Orange extends Component, not Container. Use HyperView gadgets instead: Gadget, GetString, RadioButton, HyperMenu, HyperScrollbar, and so on.
• The JDK 1.0 event methods (keyDown, mouseDown, handleEvent) are replaced by HyperView’s handlers: inKey(), onClick(), onRelease(), onMouseOver(), mouseWheelMoved() (see the event path).
• getParameterInfo() returns an empty array; isActive() is always true under HyperFrame.

API mapping: Applet → HyperView

Step-by-step port checklist

1. Copy the applet source to src/com/multiversesocial/hyperview/ and add package com.multiversesocial.hyperview;. The ViewPane, Dispatch and HyperView constructors and fields such as curView and graphics are package-private, so the class must be in this package.
2. Delete import java.applet.* / javax.swing.JApplet. Change extends Applet to extends ViewMain. Move the drawing and animation code into a new ViewPane subclass (your applet’s pane).
3. Move the body of init() into public boolean main() in your ViewMain subclass (call super.main() first to keep the ViewMain screen) and return true. Add a public static void main(String[] args) that does new HyperFrame(new MyApplet(), (byte) IncrementalID.reset(0), args, 640, 480).
4. Give the pane a constructor MyGame(HyperView tView, int x, int y, int w, int h) that calls super(tView, x, y, w, h). Use the inherited graphics field in place of getGraphics(), getSize() in place of size(), and curView.createImage() for off-screen images.
5. Set the gadget flags Asteroids uses: gadFlags |= GADGETON | GAD_KEYBOARD_ENA | GAD_LAYER_ENA | GAD_MOUSEOVER_ENA; gobFlags |= GOB_NO_SELECT;, and take keyboard = (HyperKeyboard) curView.keyboard.
6. Rename stop() to halt() and remove every Thread.stop(). Stop loops cooperatively (set the thread field to null and have the loop test Thread.currentThread() == loopThread).
7. Replace repaint() / paint(Graphics) / update(Graphics) with a no-argument update() called from your loop. Draw off-screen, blit into graphics with curView as the ImageObserver, and set a flag such as updated = true after the first frame.
8. Replace java.applet.AudioClip / getAudioClip() with new SoundClip("name.au", curView). Rename stop() on clips to halt(). Put the media files in src/com/multiversesocial/hyperview/res/.
9. Replace mouseDown() with onClick() (set GOB_CLICK_METHOD; read clickX/clickY), mouseUp() with onRelease() (GOB_RELEASE_METHOD in gobFlags2), mouseMove()/mouseDrag() with reads of curView.mouseX/mouseY, mouseEnter() with onMouseOver(), and wheel listeners with mouseWheelMoved() (GAD_MOUSE_WHEEL_ENA in gadFlags2).
10. Replace keyDown/keyUp(Event,int) with public void inKey(), which drains keyboard.keyMsg[] and advances keyboard.mainBufferIndex. Map Event.LEFT and character codes to KeyEvent.VK_*.
11. Replace getParameter() calls with curView.getParameter() and supply values as -Dparameter.<name>=value (see Parameters).
12. Write a Dispatch launcher for the pane and attach it to a Gadget in your main() (see Launch).
13. Build with compile26, start your class with java -cp dist/hyperview-3.2.jar com.multiversesocial.hyperview.MyApplet (run26 starts the plain ViewMain), click your gadget, then leave with the “x” gadget or the abort CLI command.

Before / after skeleton

Before — classic applet (illustrative; typical 1990s applet structure, as in Mike Hall’s Asteroids)

// Classic applet (runs only on JDK 8 or older; java.applet is gone in JDK 26)
import java.applet.Applet;
import java.applet.AudioClip;
import java.awt.*;

public class MyGame extends Applet implements Runnable {
   Thread loop;
   AudioClip boom;
   Image offImage; Graphics offGraphics;
   int shotX, shotY;
   boolean left;

   public void init()  { boom = getAudioClip(getDocumentBase(), "boom.au"); }
   public void start() { loop = new Thread(this); loop.start(); }
   public void stop()  { loop.stop(); loop = null; }      // Thread.stop: removed in JDK 26
   public void run() {
      while (Thread.currentThread() == loop) {
         step();
         repaint();
         try { Thread.sleep(50); } catch (InterruptedException e) { break; }
      }
   }
   public void paint(Graphics g)  { update(g); }
   public void update(Graphics g) {
      Dimension d = size();
      if (offImage == null) { offImage = createImage(d.width, d.height); offGraphics = offImage.getGraphics(); }
      /* ... draw into offGraphics ... */
      g.drawImage(offImage, 0, 0, this);
   }
   public boolean mouseDown(Event e, int x, int y) { shotX = x; shotY = y; boom.play(); return true; }
   public boolean keyDown(Event e, int key) { if (key == Event.LEFT) left = true; return true; }
   public boolean keyUp(Event e, int key)   { if (key == Event.LEFT) left = false; return true; }
}

After (1 of 2) — the applet class extends ViewMain (illustrative; compiled against the 3.2 classes)

// Your applet class: extends ViewMain (the class HyperView starts; HyperView is the abstract base)
package com.multiversesocial.hyperview;        // required: ViewPane/Dispatch constructors are package-private

public class MyApplet extends ViewMain {
   public MyApplet() { }

   public boolean main() {                     // was init(); HyperView calls main() once
      super.main();                            // keep the normal ViewMain screen (omit to start from an empty view)
      setTitle(" My Applet ");
      Gadget myGameGadget = new Gadget(this, " My Game ", 387, 96);
      myGameGadget.addDispatch(new MyGameDispatch(this));   // click it to run the game
      myGameGadget.enable();
      return true;                             // false = fatal error ("Fatal error in ViewMain.main()")
   }

   public static void main(String[] args) {    // same steps as HyperView.main(), with your class
      int tID = (byte) IncrementalID.reset(0);
      new HyperFrame(new MyApplet(), tID, args, 640, 480);
   }
}

After (2 of 2) — the pane, with mouse and keyboard handlers (illustrative; calls taken from Asteroids.java, HyperMouse.java and HyperView.java; compiled against the 3.2 classes)

// The drawing surface: a ViewPane (the pattern of Asteroids.java), with mouse and keyboard input
package com.multiversesocial.hyperview;

import java.awt.*;
import java.awt.event.KeyEvent;
import java.awt.event.MouseWheelEvent;

public class MyGame extends ViewPane implements Runnable {
   Thread loopThread;
   SoundClip boom;                             // HyperView's replacement for java.applet.AudioClip
   Image offImage; Graphics offGraphics;
   boolean updated = false;                    // the launcher waits for the first frame
   boolean left = false;
   int shotX, shotY;

   MyGame(HyperView tView, int tx, int ty, int tWidth, int tHeight) {
      super(tView, tx, ty, tWidth, tHeight);
      curView = tView;
      keyboard = (HyperKeyboard) curView.keyboard;
      gadFlags  |= GADGETON | GAD_KEYBOARD_ENA | GAD_LAYER_ENA | GAD_MOUSEOVER_ENA;
      gadFlags2 |= GAD_MOUSE_WHEEL_ENA;        // mouseWheelMoved() while this pane has keyboard focus
      gobFlags  |= GOB_NO_SELECT | GOB_CLICK_METHOD;   // onClick() on a left click
      gobFlags2 |= GOB_RELEASE_METHOD;                 // onRelease() when the button is let go
      boom = new SoundClip("boom.au", curView);        // looks in res/ inside the jar first
   }
   public void start() { loopThread = new Thread(this); loopThread.start(); }
   public void halt()  { loopThread = null; }          // was stop(); the loop checks loopThread
   public void run() {
      long startTime = curView.now;                    // HyperView's clock (Asteroids uses it)
      while (Thread.currentThread() == loopThread) {
         step();
         update();                                     // was repaint(): draw directly
         startTime += 21;
         long val = Math.max(0L, startTime - curView.now);
         if (val > 0) synchronized (this) { try { wait(val); } catch (InterruptedException e) { break; } }
      }
   }
   public void update() {                              // was update(Graphics g)
      if (offImage == null) { offImage = curView.createImage(width, height); offGraphics = offImage.getGraphics(); }
      /* ... draw into offGraphics ... */
      graphics.drawImage(offImage, mpX, mpY, mpX2, mpY2, mpX, mpY, mpX2, mpY2, curView);
      updated = true;
   }
   public void onClick() {                             // was mouseDown(Event e, int x, int y)
      shotX = clickX;                                  // relative to this pane
      shotY = clickY;
      boom.play();
   }
   public void onRelease() { }                         // was mouseUp(Event e, int x, int y)
   public void onMouseOver() { }                       // was mouseEnter()/mouseMove(): pointer is over the pane
   public void mouseWheelMoved(MouseWheelEvent e) { }  // wheel, while this pane has keyboard focus
   public void inKey() {                               // was keyDown()/keyUp()
      while (keyboard.mainBufferIndex != keyboard.intBufferIndex) {
         int index = keyboard.mainBufferIndex;
         KeyEvent e = keyboard.keyMsg[index].keyEvent;
         if (e != null) {
            boolean pressed = (keyboard.keyMsg[index].flags & KeyboardConstants.PRESSED) != 0;
            if (e.getKeyCode() == KeyEvent.VK_LEFT) left = pressed;
         }
         keyboard.mainBufferIndex++;                   // consume the key (see Asteroids.inKey())
         if (!(keyboard.mainBufferIndex < keyboard.MAX_KEYS)) keyboard.mainBufferIndex = 0;
      }
   }
   void step() { /* game logic, unchanged; pointer position is curView.mouseX / curView.mouseY */ }
}

Launching it in HyperView

The launcher follows AsteroidsDispatch.run(). Your main() (above) attaches it to a gadget, as ViewMain does for Asteroids. The class and gadget names are illustrative; the code compiles against the 3.2 classes.

// Launcher: a Dispatch run when the gadget is clicked (pattern of AsteroidsDispatch.java)
package com.multiversesocial.hyperview;

public class MyGameDispatch extends Dispatch {
   MyGame game = null;
   MyGameDispatch(HyperView tView) { super(tView); }

   public boolean run() {
      game = new MyGame(curView, 1, 16, 640, 460);   // (HyperView, x, y, width, height)
      game.start();                                  // starts, but not shown yet
      curView.addAbortRight(game);                   // "x" gadget to leave the stack frame
      while (!game.updated) {                        // wait for the first frame (avoids a white flash)
         synchronized (this) { try { wait(75); } catch (InterruptedException ie) { } notifyAll(); }
      }
      game.gobFlags |= GOB_ON_DISPLAY;               // show it
      curView.keyboard.focus = game;                 // route keys (and the wheel) to the game
      curView.runView();                             // run until an Abort (the "x" gadget or the "abort" CLI command)
      game.halt();                                   // stop the thread when leaving
      game = null;
      return true;                                   // false tells HyperView an error happened
   }
}

./compile26
java -Dsun.net.useExclusiveBind=false -Xms1000m -Xmx1000m -cp dist/hyperview-3.2.jar com.multiversesocial.hyperview.MyApplet

These are the same JVM options run26 uses. run26 itself runs -jar dist/hyperview-3.2.jar, which starts the plain ViewMain. The runView() call is required: the comments in AsteroidsDispatch explain that without it the Dispatch returns at once and “it would look like nothing happened”. curView.setBackImage("hdf.gif") (Asteroids) changes the background behind the pane.

Parameters (in place of <param> tags)

• getParameter(name) returns the system property parameter. + name.toLowerCase() (HyperFrame.getParameter), so names are case-insensitive.
• Two ways to set them: java -Dparameter.speed=3 -jar dist/hyperview-3.2.jar, or name=value program arguments, which HyperFrame.parseArgs() copies into system properties. run26 passes no arguments, so run java directly (your own static main passes args to HyperFrame). With exactly one argument, HyperView.main first tries it as a class name and prints a ClassNotFoundException trace before continuing, so -D is the cleaner option.
• HyperView itself reads ORANGE_WIDTH (1–1024, default 640) and ORANGE_HEIGHT (1–1500, default 480) in init(). HyperFrame reads width/height/peerMenuEna, but it sizes the window from its constructor arguments (640×480 from HyperView.main).
• -Dcodebase=<URL> overrides getCodeBase().

Adding images and sounds

• Put files in src/com/multiversesocial/hyperview/res/. compile26 copies them to build/classes/com/multiversesocial/hyperview/res/, so they end up in dist/hyperview-3.2.jar.
• Images: curView.getImageFromJar("x.gif"), or resolveResourceURL / resolveResourceURLStatic. Search order: res/<name> next to the class, then <name>, then a loose file in the working directory. resolveResourceURL uses getClass(), so it resolves relative to the calling class’s package; the static version is anchored at HyperView.class.
• Sounds: new SoundClip("x.au", curView). It tries the bundled resource first, then the document base (so the code-base and local-file branches are not reached once a document base exists), and converts μ-law/A-law to 16-bit PCM.
• Files a program writes (prefs, .dat) stay on disk in the working directory, never in the jar (BUILD.md notes).

Building

A new .java file in src/com/multiversesocial/hyperview/ is compiled automatically. compile26 compiles every src/**/*.java:

./compile26          # MSYS/bash      (compile26.bat on Windows cmd)
./run26              # then click your gadget in the HyperView window

# the compile step compile26 runs (from README.md):
find src -name '*.java' > build/sources.txt
javac -encoding US-ASCII -Xmaxerrs 5 -g -d build/classes -cp "lib/comm.jar" -sourcepath src @build/sources.txt

Sources must be US-ASCII (-encoding US-ASCII). lib/comm.jar is on the compile classpath because SerialHandler imports javax.comm; your port does not need it.

Worked example: what changed in Asteroids

These are the changes found by comparing HyperView’s Asteroids.java with the copy of Mike Hall’s 1998 Asteroids.java published at wpollock.com/Java/Asteroids/ (“courtesy of The Java Boutique”; other copies may differ slightly). Line numbers refer to the 3.2 file.

The game logic (sprites, collisions, scoring, the update* methods) is almost unchanged. The work is in the base class, lifecycle, drawing, sound, input and launching, which is the checklist above.

Troubleshooting

• package java.applet does not exist / cannot find symbol: class Applet: JDK 26 removed it. Delete the import and extend ViewMain (drawing in a ViewPane).
• cannot find symbol: method stop() on a Thread: Thread.stop is removed. Use the null-the-reference pattern in halt().
• stop() not found on a clip: HyperView’s AudioClip uses halt().
• “ViewPane(...) is not public … cannot be accessed from outside package”: put your class in com.multiversesocial.hyperview.
• SoundClip: Could not find - x.au or missing images: the file isn’t in src/com/multiversesocial/hyperview/res/ (rebuild so it is copied into the jar) or in the working directory.
• A white pane flashes on start: show the pane only after your first update(), as AsteroidsDispatch does by waiting on updated.
• Keys do nothing: set curView.keyboard.focus = pane and GAD_KEYBOARD_ENA. Consume keys by advancing keyboard.mainBufferIndex; keys you leave go to HyperView’s default handler.
• Clicking your gadget shows nothing: the Dispatch must call curView.runView(); without it the Dispatch returns at once.
• You can’t leave the applet: add curView.addAbortRight(pane), or type abort in the HyperView CLI.
• The game thread keeps running after leaving: call halt() after runView() returns.
• onClick() is not called: set gobFlags |= GOB_CLICK_METHOD, make sure the pane has GADGETON and GOB_ON_DISPLAY, and click with the left button (the right button grabs and moves gadgets).
• onRelease() / mouseWheelMoved() not called: GOB_RELEASE_METHOD goes in gobFlags2 and GAD_MOUSE_WHEEL_ENA in gadFlags2; the wheel goes to the gadget with keyboard focus.
• Your screen doesn’t appear, only the normal ViewMain: start your class (-cp dist/hyperview-3.2.jar com.multiversesocial.hyperview.MyApplet). run26 and HyperView.main always start ViewMain.
• “Fatal error in ViewMain.main()”: your main() returned false.
• getParameter() returns null: set -Dparameter.<lowercase-name>=value; run26 does not forward arguments.

Related pages & sources

Class pages: Orange · OrangeStub · OrangeContext · Haltable · HyperFrame · HyperView · ViewMain · ViewPane · Gadget · Dispatch · HyperKeyboard · HyperMouse · AudioClip · SoundClip · Asteroids · AsteroidsDispatch

• JEP 504, Remove the Applet API (Status: Closed / Delivered, Release 26): https://openjdk.org/jeps/504
• Oracle JDK 26 Migration Guide, Removed APIs (java.applet, JApplet, Thread.stop): https://docs.oracle.com/en/java/javase/26/migrate/removed-apis.html
• Mike Hall’s Asteroids applet source (copy used for the comparison): https://wpollock.com/Java/Asteroids/