Package limn.components

Class Popover

java.lang.Object
limn.components.Popover
public final class Popover extends Object
A panel of controls that hangs from a widget and closes when it is done with: a filter panel from a tool bar's button, a column chooser, a short form. Not a widget, as PopupMenu and Dialog are not: it shows one, its content, on the raised surface with the overlay's shadow, below the anchor unless it does not fit there and above has more room.

It takes the keyboard. On open the focus goes to the widget the content asked for as it joined (Scene.requestFocus(limn.scene.Widget<?>) from its onAttached), else to the content's first focusable widget, or, when it has none, to the popover itself, which a reader is then on; Tab and Shift+Tab cycle inside it, as in a dialog; on close the focus is where it was, the anchor for a popover opened from a button. It shows in a window of its own where the platform allows (DisplayMode.NATIVE_WINDOW, the default, as its siblings), so it can pass the window's edge; that window never takes the desktop's keyboard, and the owner's keys, characters and input-method composition are delivered into it, so a field inside types as any field does, a Japanese or a Chinese input method included.

It closes on a press outside it or Escape (the user's); on the application losing the keyboard, the owner's fullscreen changing, or the anchor leaving the window or no longer shown (an adjustment): the anchor taken out of the tree by itself, with a container or a dialog it is in, or with the window, even to be put back elsewhere in the window as a tool bar moves a button into its overflow; hidden, itself or with a container, a tab strip's page or an expander; on a face a transform no longer draws, turned away or scaled to nothing; and the popover it lies in closing, so a popover opened from another goes with it. The keyboard, when it was in the panel, then goes where a focused widget's goes when it is taken out or hidden: to nobody. And on close() (the code's). onClose hears each with that origin. It is not modal: a press outside closes it and reaches nothing else, as a combo box's list does. A question that must be answered is a Dialog. It opens from showFor(limn.scene.Widget<?>) or from the button attachTo(limn.components.Button) gave it, and never on hover or focus: a surface that opens as the pointer passes is a tooltip.

To a reader the panel is a Accessible.Role.GROUP named by setAccessibleName(limn.i18n.I18nString), or by the anchor when none is set, offering the cancel that Escape performs; an attached button says it opens a popup and whether it is open, the shape a combo box's button has. 


 Button filter = new Button("Filter").setStyle(Button.Style.SECONDARY);
 new Popover(filterPanel).setAccessibleName("Filter orders").attachTo(filter);

  • Constructor Details

    • Popover

      public Popover(Widget<?> content)
      A popover showing content, which the popover lays out at its own measure within the room there is: a long one is the application's ScrollView.
      Parameters:
      content - what the panel holds; never null, and in no other parent

  • Method Details

    • content

      public Widget<?> content()
      Returns:
      what the panel holds

    • showFor

      public void showFor(Widget<?> anchor)
      Shows the panel against anchor. A no-op while open; nothing shows for an anchor that is in no scene, is hidden, or is being taken out of its window.
      Parameters:
      anchor - the widget the panel hangs from

    • close

      public void close()
      Takes the panel down; onClose hears it as the code's. A no-op while closed.

    • isOpen

      public boolean isOpen()
      Returns:
      whether the panel is showing, or about to in a window being made

    • setDisplayMode

      public Popover setDisplayMode(DisplayMode mode)
      Asks for a window of its own (DisplayMode.NATIVE_WINDOW, the default) or the owner's scene (DisplayMode.IN_SCENE). A window is used only where the platform can place one against the anchor and the owner is not fullscreen; elsewhere the scene is.
      Parameters:
      mode - the presentation asked for; never null
      Returns:
      this popover

    • displayMode

      public DisplayMode displayMode()
      Returns:
      what the panel was last shown as, which is the scene where no window could be placed; the mode asked for until it has been shown

    • setAlignment

      public Popover setAlignment(Popover.Alignment value)
      Lines the panel up with the anchor's leading edge (Popover.Alignment.START, the default) or its trailing one.
      Parameters:
      value - the edge; never null
      Returns:
      this popover

    • alignment

      public Popover.Alignment alignment()
      Returns:
      the edge of the anchor the panel lines up with

    • setAccessibleName

      public Popover setAccessibleName(@Nullable I18nString value)
      Names the panel for a reader ("Filter orders"); null names it by its anchor.
      Parameters:
      value - the name, or null
      Returns:
      this popover

    • setAccessibleName

      public Popover setAccessibleName(@Nullable String value)
      Names the panel with a fixed string; see setAccessibleName(I18nString).
      Parameters:
      value - the name, or null
      Returns:
      this popover

    • clearAccessibleName

      public Popover clearAccessibleName()
      Takes the accessible name away, as setAccessibleName(null) would: that call does not compile, because null fits more than one of the overloads.
      Returns:
      this popover

    • onClose

      public Popover onClose(@Nullable Consumer<Change.Origin> handler)
      Hears the panel close, with who closed it: USER for a press outside or Escape, ADJUSTMENT for the application losing the keyboard, the owner's fullscreen changing or the anchor leaving the window (with a dialog it was in, say, or a popover it was in closing), CODE for close().
      Parameters:
      handler - the handler, or null to clear the slot
      Returns:
      this popover
      Throws:
      IllegalStateException - if a handler is already registered

    • attachTo

      public Popover attachTo(Button button)
      Makes button open the panel when pressed, and close it when pressed while it is open. The button then tells a reader it opens a popup and whether it is open, and offers expand and collapse in place of press.

      A button opens one popover, and a popover is attached to one button: a popover already on button is detached from it, and this one is detached from the button it was on, so attachTo on another button moves it there. Attaching it to the button it is on changes nothing.

      Parameters:
      button - the button; never null
      Returns:
      this popover

    • detach

      public Popover detach()
      Lets go of the button attachTo(limn.components.Button) gave it: the button opens nothing any more and is a plain button again, to a reader as well. A panel open from that button closes, as the code's (onClose hears CODE); one shown for another widget stays. The popover still opens from showFor(limn.scene.Widget<?>), and can be attached again. A no-op when it is on no button.

      The popover is off the button before onClose hears the close, so what the handler does is the end state: attaching it again puts it back on a button, and showing it for the button shows it as showFor(limn.scene.Widget<?>) does for any widget, from a button that does not open it.

      Returns:
      this popover