UIForAnyWindow.java

  1. package swingtree;

  3. import org.jspecify.annotations.Nullable;
  4. import sprouts.Val;
  5. import swingtree.input.Keyboard;

  7. import javax.swing.*;
  8. import java.awt.Component;
  9. import java.awt.Window;
  10. import java.awt.event.*;
  11. import java.util.Optional;
  12. import java.util.function.Consumer;

  14. /**
  15.  *  A SwingTree builder node for configuring any kind of {@link Window} type.
  16.  *  Take a look at the {@link UIForJDialog} and {@link UIForJFrame} classes,
  17.  *  which are specialized subtypes of this class.
  18.  *
  19.  * @param <I> The type of the builder itself.
  20.  * @param <W> The type of the window which is being configured by this builder.
  21.  */
  22. public abstract class UIForAnyWindow<I extends UIForAnyWindow<I,W>, W extends Window> extends UIForAnything<I,W,Component>
  23. {
  24.     private static final org.slf4j.Logger log = org.slf4j.LoggerFactory.getLogger(UIForAnyWindow.class);

  26.     /**
  27.      *  Adds a title to the window. <br>
  28.      *  Note that the way this is displayed depends on the window type and the
  29.      *  operating system.
  30.      *
  31.      * @param title The title to be shown in the top bar of the window.
  32.      * @return This builder.
  33.      */
  34.     public final I withTitle( String title ) {
  35.         return _with( thisWindow -> {
  36.                     _setTitleOf( thisWindow, title );
  37.                })
  38.                ._this();
  39.     }

  41.     /**
  42.      *  Binds a text property to the window determining the title displayed in the top bar of the window. <br>
  43.      *  Note that the way this is displayed depends on the window type and the
  44.      *  operating system.
  45.      *
  46.      * @param title The title property whose text will be shown in the top bar of the window.
  47.      * @return This builder.
  48.      */
  49.     public final I withTitle( Val<String> title ) {
  50.         NullUtil.nullArgCheck(title, "title", Val.class);
  51.         NullUtil.nullPropertyCheck(title, "title");
  52.         return _withOnShow( title, (thisWindow,v) -> {
  53.                    _setTitleOf(thisWindow, v);
  54.                })
  55.                ._with( thisWindow -> {
  56.                    _setTitleOf( thisWindow, title.orElseThrowUnchecked() );
  57.                })
  58.                ._this();
  59.     }

  61.     /**
  62.      *  Sets the {@link UI.OnWindowClose} operation for the window. <br>
  63.      *  This translates to {@link JFrame#setDefaultCloseOperation(int)} or
  64.      *  {@link JDialog#setDefaultCloseOperation(int)} depending on the window type.
  65.      *  The following operations are supported:
  66.      *  <ul>
  67.      *      <li>{@link UI.OnWindowClose#DO_NOTHING} - Do nothing when the window is closed.</li>
  68.      *      <li>{@link UI.OnWindowClose#HIDE} - Hide the window when it is closed.</li>
  69.      *      <li>{@link UI.OnWindowClose#DISPOSE} - Dispose the window when it is closed.</li>
  70.      *  </ul>
  71.      * @param onClose The operation to be executed when the window is closed.
  72.      * @return This declarative builder instance to enable method chaining.
  73.      */
  74.     public final I withOnCloseOperation(UI.OnWindowClose onClose ) {
  75.         NullUtil.nullArgCheck(onClose, "onClose", UI.OnWindowClose.class);
  76.         return _with( thisWindow -> {
  77.                     if ( thisWindow instanceof JFrame )
  78.                         ((JFrame)thisWindow).setDefaultCloseOperation(onClose.forSwing());
  79.                     else if ( thisWindow instanceof JDialog )
  80.                         ((JDialog)thisWindow).setDefaultCloseOperation(onClose.forSwing());
  81.                     else
  82.                         log.warn("Cannot set close operation on window of type: {}", thisWindow.getClass().getName());
  83.                })
  84.                ._this();
  85.     }

  87.     /**
  88.      *  Makes the window visible in the center of the screen.
  89.      */
  90.     public abstract void show();

  92.     protected abstract Optional<JRootPane> _getRootPaneOf(W thisWindow);

  94.     protected abstract void _setTitleOf( W thisWindow, String title );

  96.     private void _onKeyStroke( int code, Consumer<ActionEvent> action, W thisWindow ) {
  97.         _getRootPaneOf(thisWindow).ifPresent(rootPane -> {
  98.             KeyStroke k = KeyStroke.getKeyStroke(code, 0);
  99.             int w = JComponent.WHEN_IN_FOCUSED_WINDOW;
  100.             rootPane.registerKeyboardAction(action::accept, k, w);
  101.         });
  102.     }

  104.     /**
  105.      * Adds the supplied {@link sprouts.Action} wrapped in a {@link KeyListener} to the component,
  106.      * to receive key events triggered when the wrapped component receives a particular
  107.      * keyboard input matching the provided {@link swingtree.input.Keyboard.Key}.
  108.      * <br><br>
  109.      * @param key The {@link swingtree.input.Keyboard.Key} which should be matched to the key event.
  110.      * @param onKeyPressed The {@link sprouts.Action} which will be executed once the wrapped component received the targeted key press.
  111.      * @return This very instance, which enables builder-style method chaining.
  112.      */
  113.     public final I onPressed( Keyboard.Key key, sprouts.Action<WindowDelegate<W, ActionEvent>> onKeyPressed ) {
  114.         NullUtil.nullArgCheck(key, "key", Keyboard.Key.class);
  115.         NullUtil.nullArgCheck(onKeyPressed, "onKeyPressed", sprouts.Action.class);
  116.         return _with( thisWindow -> {
  117.                     _onKeyStroke( key.code, e -> {
  118.                         try {
  119.                             onKeyPressed.accept(_createDelegate(thisWindow, null));
  120.                         } catch (Exception ex) {
  121.                             log.error("Error occurred while processing key press event.", ex);
  122.                         }
  123.                     }, thisWindow );
  124.                })
  125.                ._this();
  126.     }

  128.     /**
  129.      * Adds the supplied {@link sprouts.Action} wrapped in a {@link java.awt.event.FocusListener}
  130.      * to the component, to receive those focus events where the wrapped component gains input focus.
  131.      *
  132.      * @param onFocus The {@link sprouts.Action} which should be executed once the input focus was gained on the wrapped component.
  133.      * @return This very instance, which enables builder-style method chaining.
  134.      */
  135.     public final I onFocusGain( sprouts.Action<WindowDelegate<W, FocusEvent>> onFocus ) {
  136.         NullUtil.nullArgCheck(onFocus, "onFocus", sprouts.Action.class);
  137.         return _with( thisWindow -> {
  138.                     thisWindow.addFocusListener(new FocusAdapter() {
  139.                         @Override public void focusGained(FocusEvent e) {
  140.                             _runInApp(()->{
  141.                                 try {
  142.                                     onFocus.accept(_createDelegate(thisWindow, e));
  143.                                 } catch (Exception ex) {
  144.                                     log.error("Error occurred while processing focus gain event.", ex);
  145.                                 }
  146.                             });
  147.                         }
  148.                     });
  149.                })
  150.                ._this();
  151.     }

  153.     /**
  154.      * Adds the supplied {@link sprouts.Action} wrapped in a focus listener
  155.      * to receive those focus events where the wrapped component loses input focus.
  156.      *
  157.      * @param onFocus The {@link sprouts.Action} which should be executed once the input focus was lost on the wrapped component.
  158.      * @return This very instance, which enables builder-style method chaining.
  159.      */
  160.     public final I onFocusLoss( sprouts.Action<WindowDelegate<W, FocusEvent>> onFocus ) {
  161.         NullUtil.nullArgCheck(onFocus, "onFocus", Action.class);
  162.         return _with( thisWindow -> {
  163.                     thisWindow.addFocusListener(new FocusAdapter() {
  164.                         @Override public void focusLost(FocusEvent e) {
  165.                             _runInApp(()->{
  166.                                 try {
  167.                                     onFocus.accept(_createDelegate(thisWindow, e));
  168.                                 } catch (Exception ex) {
  169.                                     log.error("Error occurred while processing focus loss event.", ex);
  170.                                 }
  171.                             });
  172.                         }
  173.                     });
  174.                })
  175.                ._this();
  176.     }

  178.     /**
  179.      * Adds the supplied {@link sprouts.Action} wrapped in a {@link java.awt.event.WindowListener}
  180.      * to the component, to receive {@link WindowListener#windowClosing(WindowEvent)} events
  181.      * which are invoked when a window is in the process of being closed.
  182.      * The close operation can be overridden at this point (see {@link JFrame#DO_NOTHING_ON_CLOSE}). <br>
  183.      * Note that this kind of event is typically triggered when the user clicks
  184.      * the close button in the top bar of the window.
  185.      *
  186.      * @param onClose The {@link sprouts.Action} which should be invoked when the wrapped component is in the process of being closed.
  187.      * @return This very instance, which enables builder-style method chaining.
  188.      */
  189.     public final I onClose( sprouts.Action<WindowDelegate<W, WindowEvent>> onClose ) {
  190.         NullUtil.nullArgCheck(onClose, "onClose", Action.class);
  191.         return _with( thisWindow -> {
  192.                     thisWindow.addWindowListener(new WindowAdapter() {
  193.                         @Override public void windowClosing( WindowEvent e ) {
  194.                             _runInApp(()->{
  195.                                 try {
  196.                                     onClose.accept(_createDelegate(thisWindow, e));
  197.                                 } catch (Exception ex) {
  198.                                     log.error("Error occurred while processing window closing event.", ex);
  199.                                 }
  200.                             });
  201.                         }
  202.                     });
  203.                })
  204.                ._this();
  205.     }

  207.     /**
  208.      * Adds the supplied {@link sprouts.Action} wrapped in a {@link java.awt.event.WindowListener}
  209.      * to the component, to receive {@link WindowListener#windowClosed(WindowEvent)} events
  210.      * which are invoked when a window has been closed. <br>
  211.      * Note that this kind of event is typically triggered when the user clicks
  212.      * the close button in the top bar of the window.
  213.      *
  214.      * @param onClose The {@link sprouts.Action} which should be invoked when the wrapped component has been closed.
  215.      * @return This very instance, which enables builder-style method chaining.
  216.      */
  217.     public final I onClosed( sprouts.Action<WindowDelegate<W, WindowEvent>> onClose ) {
  218.         NullUtil.nullArgCheck(onClose, "onClose", Action.class);
  219.         return _with( thisWindow -> {
  220.                     thisWindow.addWindowListener(new WindowAdapter() {
  221.                         @Override public void windowClosed( WindowEvent e ) {
  222.                             _runInApp(()->{
  223.                                 try {
  224.                                     onClose.accept(_createDelegate(thisWindow, e));
  225.                                 } catch (Exception ex) {
  226.                                     log.error("Error occurred while processing window closed event.", ex);
  227.                                 }
  228.                             });
  229.                         }
  230.                     });
  231.                })
  232.                ._this();
  233.     }

  235.     /**
  236.      * Adds the supplied {@link sprouts.Action} wrapped in a {@link java.awt.event.WindowListener}
  237.      * to the component, to receive {@link WindowListener#windowOpened(WindowEvent)} events
  238.      * which are invoked when a window has been opened. <br>
  239.      * Note that this kind of event is typically triggered when the user clicks
  240.      * the close button in the top bar of the window.
  241.      *
  242.      * @param onOpen The {@link sprouts.Action} which should be invoked when the wrapped component has been opened.
  243.      * @return This very instance, which enables builder-style method chaining.
  244.      */
  245.     public final I onOpened( sprouts.Action<WindowDelegate<W, WindowEvent>> onOpen ) {
  246.         NullUtil.nullArgCheck(onOpen, "onOpen", Action.class);
  247.         return _with( thisWindow -> {
  248.                     thisWindow.addWindowListener(new WindowAdapter() {
  249.                         @Override public void windowOpened( WindowEvent e ) {
  250.                             _runInApp(()->{
  251.                                 try {
  252.                                     onOpen.accept(_createDelegate(thisWindow, e));
  253.                                 } catch (Exception ex) {
  254.                                     log.error("Error occurred while processing window opened event.", ex);
  255.                                 }
  256.                             });
  257.                         }
  258.                     });
  259.                })
  260.                ._this();
  261.     }

  263.     /**
  264.      * Adds the supplied {@link sprouts.Action} wrapped in a {@link java.awt.event.WindowListener}
  265.      * to the component, to receive {@link WindowListener#windowIconified(WindowEvent)} events
  266.      * which are invoked when a window is changed from a normal to a minimized state.
  267.      * For many platforms, a minimized window is displayed as the icon
  268.      * specified in the window's iconImage property.
  269.      * <br>
  270.      * Minification is usually triggered when the user clicks the minimize button
  271.      * in the top bar of the window. But this depends on the operating system.
  272.      *
  273.      * @param onIconify The {@link sprouts.Action} which should be invoked when the wrapped component has been iconified.
  274.      * @return This very instance, which enables builder-style method chaining.
  275.      */
  276.     public final I onIconified( sprouts.Action<WindowDelegate<W, WindowEvent>> onIconify ) {
  277.         NullUtil.nullArgCheck(onIconify, "onIconify", Action.class);
  278.         return _with( thisWindow -> {
  279.                     thisWindow.addWindowListener(new WindowAdapter() {
  280.                         @Override public void windowIconified( WindowEvent e ) {
  281.                             _runInApp(()->{
  282.                                 try {
  283.                                     onIconify.accept(_createDelegate(thisWindow, e));
  284.                                 } catch (Exception ex) {
  285.                                     log.error("Error occurred while processing window iconified event.", ex);
  286.                                 }
  287.                             });
  288.                         }
  289.                     });
  290.                })
  291.                ._this();
  292.     }

  294.     /**
  295.      * Adds the supplied {@link sprouts.Action} wrapped in a {@link java.awt.event.WindowListener}
  296.      * to the component, to receive {@link WindowListener#windowDeiconified(WindowEvent)} events
  297.      * which are invoked when a window is changed from a minimized
  298.      * to a normal state, usually by the user restoring it from the task bar.
  299.      *
  300.      * @param onDeiconify The {@link sprouts.Action} which should be invoked when the wrapped component has been deiconified.
  301.      * @return This very instance, which enables builder-style method chaining.
  302.      */
  303.     public final I onDeiconified( sprouts.Action<WindowDelegate<W, WindowEvent>> onDeiconify ) {
  304.         NullUtil.nullArgCheck(onDeiconify, "onDeiconify", Action.class);
  305.         return _with( thisWindow -> {
  306.                     thisWindow.addWindowListener(new WindowAdapter() {
  307.                         @Override public void windowDeiconified( WindowEvent e ) {
  308.                             _runInApp(()->{
  309.                                 try {
  310.                                     onDeiconify.accept(_createDelegate(thisWindow, e));
  311.                                 } catch (Exception ex) {
  312.                                     log.error("Error occurred while processing window deiconified event.", ex);
  313.                                 }
  314.                             });
  315.                         }
  316.                     });
  317.                })
  318.                ._this();
  319.     }

  321.     /**
  322.      * Adds the supplied {@link sprouts.Action} wrapped in a {@link java.awt.event.WindowListener}
  323.      * to the component, to receive {@link WindowListener#windowActivated(WindowEvent)} events
  324.      * which are invoked when the Window is set to be the active Window.
  325.      * Only a Frame or a Dialog can be the active Window.
  326.      * The native windowing system may denote the active Window or
  327.      * its children with special decorations, such as a highlighted title bar.
  328.      * The active Window is always either the focused Window,
  329.      * or the first Frame or Dialog that is an owner of the focused Window.
  330.      * So this kind of event is usually triggered when the user makes the window active
  331.      * by clicking it.
  332.      *
  333.      * @param onActivate The {@link sprouts.Action} which should be invoked when the wrapped component has been activated.
  334.      * @return This very instance, which enables builder-style method chaining.
  335.      */
  336.     public final I onActivated( sprouts.Action<WindowDelegate<W, WindowEvent>> onActivate ) {
  337.         NullUtil.nullArgCheck(onActivate, "onActivate", Action.class);
  338.         return _with( thisWindow -> {
  339.                     thisWindow.addWindowListener(new WindowAdapter() {
  340.                         @Override public void windowActivated( WindowEvent e ) {
  341.                             _runInApp(()->{
  342.                                 try {
  343.                                     onActivate.accept(_createDelegate(thisWindow, e));
  344.                                 } catch (Exception ex) {
  345.                                     log.error("Error occurred while processing window activated event.", ex);
  346.                                 }
  347.                             });
  348.                         }
  349.                     });
  350.                })
  351.                ._this();
  352.     }

  354.     /**
  355.      * Adds the supplied {@link sprouts.Action} wrapped in a {@link java.awt.event.WindowListener}
  356.      * to the component, to receive {@link WindowListener#windowDeactivated(WindowEvent)} events
  357.      * which are invoked when a Window is no longer the active Window. Only a Frame or a
  358.      * Dialog can be the active Window. The native windowing system may denote
  359.      * the active Window or its children with special decorations, such as a
  360.      * highlighted title bar. The active Window is always either the focused
  361.      * Window, or the first Frame or Dialog that is an owner of the focused
  362.      * Window.
  363.      * This kind of event typically occurs when the user clicks another window
  364.      * in the task bar of the operating system.
  365.      *
  366.      * @param onDeactivate The {@link sprouts.Action} which should be invoked when the wrapped component has been deactivated.
  367.      * @return This very instance, which enables builder-style method chaining.
  368.      */
  369.     public final I onDeactivated( sprouts.Action<WindowDelegate<W, WindowEvent>> onDeactivate ) {
  370.         NullUtil.nullArgCheck(onDeactivate, "onDeactivate", Action.class);
  371.         return _with( thisWindow -> {
  372.                     thisWindow.addWindowListener(new WindowAdapter() {
  373.                         @Override public void windowDeactivated( WindowEvent e ) {
  374.                             _runInApp(()->{
  375.                                 try {
  376.                                     onDeactivate.accept(_createDelegate(thisWindow, e));
  377.                                 } catch (Exception ex) {
  378.                                     log.error("Error occurred while processing window deactivated event.", ex);
  379.                                 }
  380.                             });
  381.                         }
  382.                     });
  383.                })
  384.                ._this();
  385.     }

  387.     /**
  388.      * Adds the supplied {@link sprouts.Action} wrapped in a {@link java.awt.event.WindowListener}
  389.      * to the component, to receive {@link WindowStateListener#windowStateChanged(WindowEvent)} events
  390.      * which are invoked when a window has been changed. <br>
  391.      * Note that this kind of event is typically invoked when the window is
  392.      * iconified, minimized, maximized or restored.
  393.      *
  394.      * @param onStateChanged The {@link sprouts.Action} which should be invoked when the wrapped component has been changed.
  395.      * @return This very instance, which enables builder-style method chaining.
  396.      */
  397.     public final I onStateChanged( sprouts.Action<WindowDelegate<W, WindowEvent>> onStateChanged ) {
  398.         NullUtil.nullArgCheck(onStateChanged, "onStateChanged", Action.class);
  399.         return _with( thisWindow -> {
  400.                     thisWindow.addWindowListener(new WindowAdapter() {
  401.                         @Override public void windowStateChanged( WindowEvent e ) {
  402.                             _runInApp(()->{
  403.                                 try {
  404.                                     onStateChanged.accept(_createDelegate(thisWindow, e));
  405.                                 } catch (Exception ex) {
  406.                                     log.error("Error occurred while processing window state changed event.", ex);
  407.                                 }
  408.                             });
  409.                         }
  410.                     });
  411.                })
  412.                ._this();
  413.     }

  415.     /**
  416.      * Adds the supplied {@link sprouts.Action} wrapped in a {@link java.awt.event.WindowListener}
  417.      * to the component, to receive {@link WindowFocusListener#windowGainedFocus(WindowEvent)} events
  418.      * which are invoked when the window is set to be gaining input focus, which means
  419.      * that the Window, or one of its subcomponents, will receive keyboard
  420.      * events.
  421.      * This event is typically triggered when the user clicks the window.
  422.      *
  423.      * @param onFocusGained The {@link sprouts.Action} which should be invoked when the wrapped component has gained input focus.
  424.      * @return This very instance, which enables builder-style method chaining.
  425.      */
  426.     public final I onInputFocusGained( sprouts.Action<WindowDelegate<W, WindowEvent>> onFocusGained ) {
  427.         NullUtil.nullArgCheck(onFocusGained, "onFocusGained", Action.class);
  428.         return _with( thisWindow -> {
  429.                     thisWindow.addWindowFocusListener(new WindowFocusListener() {
  430.                         @Override public void windowGainedFocus( WindowEvent e ) {
  431.                             _runInApp(()->{
  432.                                 try {
  433.                                     onFocusGained.accept(_createDelegate(thisWindow, e));
  434.                                 } catch (Exception ex) {
  435.                                     log.error("Error occurred while processing focus gain event.", ex);
  436.                                 }
  437.                             });
  438.                         }
  439.                         @Override public void windowLostFocus( WindowEvent e ) {}
  440.                     });
  441.                })
  442.                ._this();
  443.     }

  445.     /**
  446.      * Adds the supplied {@link sprouts.Action} wrapped in a {@link java.awt.event.WindowListener}
  447.      * to the component, to receive {@link WindowFocusListener#windowLostFocus(WindowEvent)} events
  448.      * which are invoked when the window is set to be losing input focus, which means
  449.      * that input focus is being transferred to another Window or no Window at all and
  450.      * that keyboard events will no longer be delivered to the Window or any of
  451.      * its subcomponents.
  452.      *
  453.      * @param onFocusLost The {@link sprouts.Action} which should be invoked when the wrapped component has lost input focus.
  454.      * @return This very instance, which enables builder-style method chaining.
  455.      */
  456.     public final I onInputFocusLost( sprouts.Action<WindowDelegate<W, WindowEvent>> onFocusLost ) {
  457.         NullUtil.nullArgCheck(onFocusLost, "onFocusLost", Action.class);
  458.         return _with( thisWindow -> {
  459.                     thisWindow.addWindowFocusListener(new WindowFocusListener() {
  460.                         @Override public void windowGainedFocus( WindowEvent e ) {}
  461.                         @Override public void windowLostFocus( WindowEvent e ) {
  462.                             _runInApp(()->{
  463.                                 try {
  464.                                     onFocusLost.accept(_createDelegate(thisWindow, e));
  465.                                 } catch (Exception ex) {
  466.                                     log.error("Error occurred while processing focus loss event.", ex);
  467.                                 }
  468.                             });
  469.                         }
  470.                     });
  471.                })
  472.                ._this();
  473.     }

  475.     private <E> WindowDelegate<W, E> _createDelegate( W window, @Nullable E event ) {
  476.         return new WindowDelegate<W, E>() {
  477.             @Override public W get() { return window; }
  478.             @Override public @Nullable E getEvent() { return event; }
  479.         };
  480.     }

  482. }
Created with JaCoCo 0.8.11.202310140853