Module jetbrains.runtime.api
Package com.jetbrains

Interface WindowDecorations.CustomTitleBar

Enclosing interface:
WindowDecorations
@Provided public static interface WindowDecorations.CustomTitleBar
Custom title bar allows merging of window content with native title bar, which is done by treating title bar as part of client area, but with some special behavior like dragging or maximizing on double click. Custom title bar has height and controls. Behavior is platform-dependent, only macOS and Windows are supported.
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    forceHitTest(boolean client)
    By default, any component which has no cursor or mouse event listeners set is considered transparent for native title bar actions.
    Window
    getContainingWindow()
    Get window, title bar is attached to.
    float
    getHeight()
    Get title bar height, measured in pixels from the top of client area, i.e.
    float
    getLeftInset()
    Get space occupied by title bar controls on the left (px).
    Map<String,Object>
    getProperties()
    Get all properties set for the title bar.
    float
    getRightInset()
    Get space occupied by title bar controls on the right (px).
    void
    putProperties(Map<String,?> m)
    Put all properties from the map.
    void
    putProperty(String key, Object value)
    Windows and macOS properties: controls.visible : Boolean - whether title bar controls (minimize/maximize/close buttons) are visible, default = true. Windows properties: controls.width : Number - width of block of buttons (not individual buttons).
    void
    setHeight(float height)
    Set title bar height, measured in pixels from the top of client area, i.e.

  • Method Details

    • getHeight

      float getHeight()
      Get title bar height, measured in pixels from the top of client area, i.e. excluding top frame border.
      Returns:
      title bar height

    • setHeight

      void setHeight(float height)
      Set title bar height, measured in pixels from the top of client area, i.e. excluding top frame border. Must be > 0.
      Parameters:
      height - new title bar height

    • getProperties

      Map<String,Object> getProperties()
      Get all properties set for the title bar.
      Returns:
      map of properties
      See Also:

    • putProperties

      void putProperties(Map<String,?> m)
      Put all properties from the map.
      Parameters:
      m - map of properties
      See Also:

    • putProperty

      void putProperty(String key, Object value)
      Windows and macOS properties:
      • controls.visible : Boolean - whether title bar controls (minimize/maximize/close buttons) are visible, default = true.
      Windows properties:
      • controls.width : Number - width of block of buttons (not individual buttons). Note that dialogs have only one button, while frames usually have 3 of them.
      • controls.dark : Boolean - whether to use dark or light color theme (light or dark icons respectively).
      • controls.<layer>.<state> : Color - precise control over button colors, where <layer> is one of:
        • foreground
        • background
        and <state> is one of:
        • normal
        • hovered
        • pressed
        • disabled
        • inactive
      Parameters:
      key - property key
      value - property value

    • getLeftInset

      float getLeftInset()
      Get space occupied by title bar controls on the left (px).
      Returns:
      left inset

    • getRightInset

      float getRightInset()
      Get space occupied by title bar controls on the right (px).
      Returns:
      right inset

    • forceHitTest

      void forceHitTest(boolean client)
      By default, any component which has no cursor or mouse event listeners set is considered transparent for native title bar actions. That is, dragging simple JPanel in title bar area will drag the window, but dragging a JButton will not. Adding mouse listener to a component will prevent any native actions inside bounds of that component.

      This method gives you precise control of whether to allow native title bar actions or not.

      • client=true means that mouse is currently over a client area. Native title bar behavior is disabled.
      • client=false means that mouse is currently over a non-client area. Native title bar behavior is enabled.
      Intended usage:
      • This method must be called in response to all mouse events except MouseEvent.MOUSE_EXITED and MouseEvent.MOUSE_WHEEL.
      • This method is called per-event, i.e. when component has multiple listeners, you only need to call it once.
      • If this method hadn't been called, title bar behavior is reverted back to default upon processing the event.
      Note that hit test value is relevant only for title bar area, e.g. calling forceHitTest(false) will not make window draggable via non-title bar area.

      Example:

      Suppose you have a JPanel in the title bar area. You want it to respond to right-click for some popup menu, but also retain native drag and double-click behavior. 
           CustomTitleBar titlebar = ...;
     JPanel panel = ...;
     MouseAdapter adapter = new MouseAdapter() {
         private void hit() { titlebar.forceHitTest(false); }
         public void mouseClicked(MouseEvent e) {
             hit();
             if (e.getButton() == MouseEvent.BUTTON3) ...;
         }
         public void mousePressed(MouseEvent e) { hit(); }
         public void mouseReleased(MouseEvent e) { hit(); }
         public void mouseEntered(MouseEvent e) { hit(); }
         public void mouseDragged(MouseEvent e) { hit(); }
         public void mouseMoved(MouseEvent e) { hit(); }
     };
     panel.addMouseListener(adapter);
     panel.addMouseMotionListener(adapter);
      Parameters:
      client - whether to force client, or non-client area response

    • getContainingWindow

      Window getContainingWindow()
      Get window, title bar is attached to.
      Returns:
      parent window