Interface Window

All Superinterfaces:
BasePane, Composite
All Known Implementing Classes:
AbstractWindow, ActionListDialog, BasicWindow, ComboBox.PopupWindow, DialogWindow, DirectoryDialog, FileDialog, ListSelectDialog, MenuPopupWindow, MessageDialog, TextInputDialog, WaitingDialog

public interface Window extends BasePane
Window is a base unit in the TextGUI system, it represents a collection of components grouped together, usually surrounded by a border and a title. Modern computer system GUIs are normally based around the metaphor of windows, so I don't think you should have any problems understanding what this means.
  • Method Details

    • getTextGUI

      WindowBasedTextGUI getTextGUI()
      Description copied from interface: BasePane
      Returns the TextGUI this BasePane belongs to or null if none. One example of when this method returns null is when calling it on a Window that hasn't been displayed yet.
      Specified by:
      getTextGUI in interface BasePane
      Returns:
      The TextGUI this BasePane belongs to
    • setTextGUI

      void setTextGUI(WindowBasedTextGUI textGUI)
      DON'T CALL THIS METHOD YOURSELF, it is called automatically by the TextGUI system when you add a window. If you call it with the intention of adding the window to the specified TextGUI, you need to read the documentation on how to use windows.
      Parameters:
      textGUI - TextGUI this window belongs to from now on
    • getTitle

      String getTitle()
      This method returns the title of the window, which is normally drawn at the top-left corder of the window decoration, but depending on the WindowDecorationRenderer used by the TextGUI
      Returns:
      title of the window
    • isVisible

      boolean isVisible()
      This values is optionally used by the window manager to decide if the windows should be drawn or not. In an invisible state, the window is still considered active in the TextGUI but just not drawn and not receiving any input events. Please note that window managers may choose not to implement this.
      Returns:
      Whether the window wants to be visible or not
    • setVisible

      void setVisible(boolean visible)
      This values is optionally used by the window manager to decide if the windows should be drawn or not. In an invisible state, the window is still considered active in the TextGUI but just not drawn and not receiving any input events. Please note that window managers may choose not to implement this.
      Parameters:
      visible - whether the window should be visible or not
    • isInvalid

      boolean isInvalid()
      This method is used to determine if the window requires re-drawing. The most common cause for this is the some of its components has changed and we need a re-draw to make these changes visible.
      Specified by:
      isInvalid in interface BasePane
      Returns:
      true if the window would like to be re-drawn, false if the window doesn't need
    • invalidate

      void invalidate()
      Invalidates the whole window (including all of its child components) which will cause it to be recalculated and redrawn.
      Specified by:
      invalidate in interface BasePane
    • getBounds

      default TerminalRectangle getBounds()
      Return the last known size of the window including window decoration and the window position as a TerminalRectangle.
      Returns:
      the decorated size and position of the window
    • getPreferredSize

      TerminalSize getPreferredSize()
      Returns the size this window would like to be
      Returns:
      Desired size of this window
    • close

      void close()
      Closes the window, which will remove it from the GUI
    • setHints

      void setHints(Collection<Window.Hint> hints)
      Updates the set of active hints for this window. Please note that it's up to the window manager if these hints will be honored or not.
      Parameters:
      hints - Set of hints to be active for this window
    • getHints

      Set<Window.Hint> getHints()
      Returns a set of window hints that can be used by the text gui system, the window manager or any other part that is interacting with windows.
      Returns:
      Set of hints defined for this window
    • getPosition

      TerminalPosition getPosition()
      Returns the position of the window, as last specified by the window manager. This position does not include window decorations but is the top-left position of the first usable space of the window.
      Returns:
      Position, relative to the top-left corner of the terminal, of the top-left corner of the window
    • setPosition

      void setPosition(TerminalPosition topLeft)
      This method is called by the GUI system to update the window on where the window manager placed it. Calling this yourself will have no effect other than making the getPosition() call incorrect until the next redraw, unless you have specified through window hints that you don't want the window manager to automatically place the window. Notice that the position here is expressed in "global" coordinates, which means measured from the top-left corner of the terminal itself.
      Parameters:
      topLeft - Global coordinates of the top-left corner of the window
    • getSize

      TerminalSize getSize()
      Returns the last known size of the window. This is in general derived from the last drawing operation, how large area the window was allowed to draw on. This size does not include window decorations.
      Returns:
      Size of the window
    • setSize

      @Deprecated void setSize(TerminalSize size)
      Deprecated.
      This method is deprecated now as it probably doesn't do what you think. Please use setFixedSize or setDecoratedSize instead, depending on what you are trying to do.
      This method is called by the GUI system to update the window on how large it is, excluding window decorations. Calling this yourself will generally make no difference in the size of the window, since it will be reset on the next redraw based on how large area the TextGraphics given is covering. However, if you add the FIXED_SIZE window hint, the auto-size calculation will be turned off and you can use this method to set how large you want the window to be.

      Important: if you are writing your own WindowManager, you should call setDecoratedSize instead of this when decided the size of the window.

      Parameters:
      size - New size of your fixed-size window
    • setFixedSize

      void setFixedSize(TerminalSize size)
      Calling this method will add the FIXED_SIZE window hint (if it wasn't present already) and attempt to force the window to always have the size specified. Notice that it's up to the WindowManager if this size and hint are going to be honored.
      Parameters:
      size - New size of your fixed-size window
    • getDecoratedSize

      TerminalSize getDecoratedSize()
      Returns the last known size of the window including window decorations put on by the window manager. The value returned here is passed in during drawing by the TextGUI through setDecoratedSize(..).
      Returns:
      Size of the window, including window decorations
    • setDecoratedSize

      void setDecoratedSize(TerminalSize decoratedSize)
      This method is called by the GUI system to update the window on how large it is, counting window decorations too. Calling this yourself will have no effect other than making the getDecoratedSize() call incorrect until the next redraw.

      Important: if you are writing your own WindowManager, you should call this method instead of setSize when decided the size of the window.

      Parameters:
      decoratedSize - Size of the window, including window decorations
    • setContentOffset

      void setContentOffset(TerminalPosition offset)
      This method is called by the GUI system to update the window on, as of the last drawing operation, the distance from the top-left position of the window including decorations to the top-left position of the actual content area. If this window has no decorations, it will be always 0x0. Do not call this method yourself.
      Parameters:
      offset - Offset from the top-left corner of the window (including decorations) to the top-left corner of the content area.
    • waitUntilClosed

      void waitUntilClosed()
      Waits for the window to close. Please note that this can cause deadlocks if care is not taken. Also, this method will swallow any interrupts, if you need a wait method that throws InterruptedException, you'll have to implement this yourself.
    • getPostRenderer

      WindowPostRenderer getPostRenderer()
      Returns a post-renderer the GUI system should invoke after the window has been drawn. This can be used to creating effects like shadows, overlays, etc. If this returns null, the GUI system will fall back to it's own global override and after that to the current theme. If these are all null, no post-rendering is done.
      Returns:
      WindowPostRenderer to invoke after this window is drawn, or null fallback to the GUI system's default.
    • addWindowListener

      void addWindowListener(WindowListener windowListener)
      Adds a WindowListener to this Window. If it has already been added, the call will do nothing.
      Parameters:
      windowListener - Listener to attach to this Window
    • removeWindowListener

      void removeWindowListener(WindowListener windowListener)
      Removes a WindowListener from this Window. If the listener isn't in the list of listeners, this call does nothing.
      Parameters:
      windowListener - Listener to remove from this Window
    • draw

      void draw(TextGUIGraphics graphics)
      Called by the GUI system (or something imitating the GUI system) to draw the window. The TextGUIGraphics object should be used to perform the drawing operations.
      Specified by:
      draw in interface BasePane
      Parameters:
      graphics - TextGraphics object to draw with
    • handleInput

      boolean handleInput(KeyStroke key)
      Called by the GUI system's window manager when it has decided that this window should receive the keyboard input. The window will decide what to do with this input, usually sending it to one of its sub-components, but if it isn't able to find any handler for this input it should return false so that the window manager can take further decisions on what to do with it.
      Specified by:
      handleInput in interface BasePane
      Parameters:
      key - Keyboard input
      Returns:
      true If the window could handle the input, false otherwise
    • setComponent

      void setComponent(Component component)
      Sets the top-level component in the window, this will be the only component unless it's a container of some kind that you add child-components to.
      Specified by:
      setComponent in interface BasePane
      Specified by:
      setComponent in interface Composite
      Parameters:
      component - Component to use as the top-level object in the Window
    • getComponent

      Component getComponent()
      Returns the component which is the top-level in the component hierarchy inside this window.
      Specified by:
      getComponent in interface BasePane
      Specified by:
      getComponent in interface Composite
      Returns:
      Top-level component in the window
    • getFocusedInteractable

      Interactable getFocusedInteractable()
      Returns the component in the window that currently has input focus. There can only be one component at a time being in focus.
      Specified by:
      getFocusedInteractable in interface BasePane
      Returns:
      Interactable component that is currently in receiving input focus
    • setFocusedInteractable

      void setFocusedInteractable(Interactable interactable)
      Sets the component currently in focus within this window, or sets no component in focus if null is passed in.
      Specified by:
      setFocusedInteractable in interface BasePane
      Parameters:
      interactable - Interactable to focus, or null to clear focus
    • getCursorPosition

      TerminalPosition getCursorPosition()
      Returns the position of where to put the terminal cursor according to this window. This is typically derived from which component has focus, or null if no component has focus or if the window doesn't want the cursor to be visible. Note that the coordinates are in local coordinate space, relative to the top-left corner of the window. You can use your TextGUI implementation to translate these to global coordinates.
      Specified by:
      getCursorPosition in interface BasePane
      Returns:
      Local position of where to place the cursor, or null if the cursor shouldn't be visible
    • toGlobal

      Deprecated.
      This is deprecated in favor of calling either of: toGlobalFromContentRelative() or toGlobalFromDecoratedRelative().
      Description copied from interface: BasePane
      Returns a position in a root container's local coordinate space to global coordinates
      Specified by:
      toGlobal in interface BasePane
      Parameters:
      localPosition - The local position to translate
      Returns:
      The local position translated to global coordinates
      See Also:
    • toGlobalFromContentRelative

      TerminalPosition toGlobalFromContentRelative(TerminalPosition localPosition)
      Returns a position in the window content's local coordinate space to global coordinates
      Parameters:
      localPosition - The local position to translate
      Returns:
      The local position translated to global coordinates
    • toGlobalFromDecoratedRelative

      TerminalPosition toGlobalFromDecoratedRelative(TerminalPosition decoratedPosition)
      Returns a position in the decorated window local coordinate space to global coordinates
      Parameters:
      decoratedPosition - The local position to translate
      Returns:
      The local position translated to global coordinates
    • fromGlobal

      Deprecated.
      This is deprecated in favor of calling either of: fromGlobalToContentRelative() or fromGlobalToDecoratedRelative()
      Description copied from interface: BasePane
      Returns a position expressed in global coordinates, i.e. row and column offset from the top-left corner of the terminal into a position relative to the top-left corner of the base pane. Calling fromGlobal(toGlobal(..)) should return the exact same position.
      Specified by:
      fromGlobal in interface BasePane
      Parameters:
      position - Position expressed in global coordinates to translate to local coordinates of this BasePane
      Returns:
      The global coordinates expressed as local coordinates
      See Also:
    • fromGlobalToContentRelative

      TerminalPosition fromGlobalToContentRelative(TerminalPosition position)
      Returns a position expressed in global coordinates, i.e. row and column offset from the top-left corner of the terminal into a position relative to the top-left corner of the window's content. Calling fromGlobalToContentRelative(toGlobalFromContentRelative(..)) should return the exact same position.
      Parameters:
      position - Position expressed in global coordinates to translate to local coordinates of this Window's content.
      Returns:
      The global coordinates expressed as local coordinates
    • fromGlobalToDecoratedRelative

      TerminalPosition fromGlobalToDecoratedRelative(TerminalPosition position)
      Returns a position expressed in global coordinates, i.e. row and column offset from the top-left corner of the terminal into a position relative to the top-left corner of the window including it's decoration. Calling fromGlobalToDecoratedRelative(toGlobalFromDecoratedRelative(..)) should return the exact same position.
      Parameters:
      position - Position expressed in global coordinates to translate to local coordinates of this window including it's decoration.
      Returns:
      The global coordinates expressed as local coordinates
    • setMenuBar

      void setMenuBar(MenuBar menubar)
      Sets the active MenuBar for this window. The menu will be rendered at the top, inside the window decorations, if set. If called with null, any previously set menu bar is removed.
      Specified by:
      setMenuBar in interface BasePane
      Parameters:
      menubar - The MenuBar to assign to this window
    • getMenuBar

      MenuBar getMenuBar()
      Returns the MenuBar assigned to this window, if any, otherwise returns {code null}.
      Specified by:
      getMenuBar in interface BasePane
      Returns:
      The active menu bar or null