Create a Modal ‘Hello’ Window with a Button in Dyalog APL

Desired Outcome

Show a modal window titled Hello that contains a button labeled Click me. When the button is pressed, a message box should appear with the text Button pressed. The window and button should be created using Dyalog APL’s ⎕WC system function.

Prerequisites

• Dyalog APL 12.0 or newer with GUI support enabled (e.g., running in Dyalog RIDE or a Windows GUI session).
• Running in a session that can display Windows GUI elements; a pure console or non‑GUI RIDE will cause ⎕WC to fail with error 11 (DOMAIN ERROR).
• Basic familiarity with Dyalog’s ⎕WC syntax and the ⎕WS property‑value mapping.

Focused Procedure

1. Create the form (window). In a Dyalog session, run:

   f←⎕WC 'Form' 'Hello' (•⎕WS 'size' 200 150)
   

   This calls ⎕WC with the arguments:

   • 'Form' – request a form object.
   • 'Hello' – the title of the window.
   • (•⎕WS 'size' 200 150) – a property‑value list setting the window size to 200×150 pixels.
   The result is a reference to the new form stored in variable f. If the call fails, f will be ⍬ and ⎕EN will contain an error number.

2. Add the button. Create a button inside the form and attach a callback that shows a message box:

   b←⎕WC 'Button' 'Click me' f (
       •⎕WS 'position' 50 50 \
       •⎕WS 'size' 100 30 \
       •⎕WS 'event' 'Select' '⎕←' '⎕MSGBOX ''Button pressed'''
   )
   

   Explanation of the arguments:

   • 'Button' – request a button object.
   • 'Click me' – the button’s label.
   • f – the parent form where the button will be placed.
   • The property list:
     • 'position' – x,y coordinates relative to the form’s client area.
     • 'size' – width and height of the button.
     • 'event' – the event name to listen for; Select fires when the user clicks the button.
     • '⎕←' – the action to execute when the event occurs; here it calls ⎕MSGBOX with the desired text.

3. Verify the interface. After running the two commands above:
   • The Hello window should appear in the foreground, blocking input to other windows until closed.
   • The button labeled Click me should be visible and enabled.
   • Clicking the button should open a modal message box that reads Button pressed.

Expected Checks

• Check that ⎕NC 'f' returns 1 (object exists) and ⎕NC 'b' returns 1.
• Verify that ⎕WC returned a non‑null reference: ⎕WC 'Form' … and ⎕WC 'Button' … should not be ⍬.
• After closing the window, run ⎕EX f b to free resources and confirm ⎕NC 'f b' returns 0.

Recovery Options

If the window does not appear, follow these steps:

1. Check the return value of ⎕WC. If it is ⍬, examine ⎕EN for an error number. Common errors:
   • 11 – DOMAIN ERROR: no GUI support in the current session.
   • Property name typos (e.g., 'size' vs 'Size') cause ⎕EN 15 (PROPERTY ERROR).
2. Ensure you are running in a GUI‑enabled Dyalog environment. In RIDE, switch to the GUI tab or start a new session with the -g flag.
3. If the button click triggers an error, verify the callback string. The callback must be a valid APL expression; for complex logic, consider defining a function and passing its name instead of an inline expression.

Practical Tips

• Keep button callbacks short. Long calculations block the GUI thread. Use ⎕DL to delay or spawn a separate thread with ⎕TS if needed.
• Use ⎕MSGBOX for simple notifications; for richer dialogs, explore the Dialog or MessageBox objects available in newer Dyalog releases.
• To adjust layout automatically, replace absolute position and size with a layout manager (e.g., ⎕WC 'FlowLayout') if you plan to add more controls.

Limitations

• Running this code in a console‑only session (e.g., dyalog -c) will fail because ⎕WC cannot create GUI objects.
• The example uses hard‑coded pixel values; on high‑DPI displays the button may appear too small. Consider using logical units or querying the display scaling factor via ⎕WS 'dpi'.
• Callback strings are evaluated in the global context; if you need access to local variables, bind them via ⎕UP or use a closure.

Conclusion

With just a few lines of Dyalog APL, you can create a modal window with a button and a simple callback. The ⎕WC system function exposes a flexible, declarative way to build GUI elements. By following the checks and recovery steps above, you can troubleshoot common pitfalls and ensure a responsive interface.