schrodinger.ui.qt.standard.widgets.positioner module

class schrodinger.ui.qt.standard.widgets.positioner.Placement

Bases: Enum

Placement options for positioning a target widget relative to an anchor.

When using an anchor widget, the placement determines which point on the widget the target attaches to (e.g., BottomRight attaches to the bottom-right corner). When using an anchor position, the placement determines which direction the target expands from that point.

Use Auto (the default) to let the positioner automatically choose the best placement based on the anchor’s position within the window or screen.

Auto = None
TopLeft = AlignmentFlag.AlignLeft|AlignTop
TopCenter = AlignmentFlag.AlignHCenter|AlignTop
TopRight = AlignmentFlag.AlignRight|AlignTop
CenterLeft = AlignmentFlag.AlignLeft|AlignVCenter
CenterRight = AlignmentFlag.AlignRight|AlignVCenter
BottomLeft = AlignmentFlag.AlignLeft|AlignBottom
BottomCenter = AlignmentFlag.AlignHCenter|AlignBottom
BottomRight = AlignmentFlag.AlignRight|AlignBottom
schrodinger.ui.qt.standard.widgets.positioner.calculate_position(target: QWidget, anchor: PyQt6.QtWidgets.QWidget | None = None, anchor_pos: PyQt6.QtCore.QPoint | None = None, placement: Placement = Placement.Auto, offset: int = 4) → QPoint

Calculate position for a target widget relative to an anchor.

The anchor can be specified in two ways:

  1. Anchor widget: A reference widget passed via the anchor parameter. The placement determines which point on the widget to attach to.

  2. Anchor position: A QPoint in global screen coordinates passed via the anchor_pos parameter. The placement determines which direction the target expands from that point.

Placement options: Use the placement parameter to control positioning:

  • Placement.Auto (default): Automatically choose placement that maximizes visibility by expanding toward the center.

  • Placement.BottomRight: Attach to bottom-right (or expand SE)

  • Placement.TopLeft: Attach to top-left (or expand NW)

  • etc.

Automatic placement: When set to Auto, the function divides the window (or screen for anchor positions) into a 3x3 grid and selects the placement that causes the target to expand toward the center:

+───────────+───────────+───────────+
| Expand    | Expand    | Expand    |
| SE (BR)   | S (B)     | SW (BL)   |
+───────────+───────────+───────────+
| Expand    | Expand    | Expand    |
| E (R)     | S (T)*    | W (L)     |
+───────────+───────────+───────────+
| Expand    | Expand    | Expand    |
| NE (TR)   | N (T)     | NW (TL)   |
+───────────+───────────+───────────+
* Center defaults to Top to avoid blocking the anchor

The same logic applies to explicit positions, but uses screen geometry instead of window geometry.

Offset: The offset parameter specifies a gap in pixels between the anchor and target. The offset adds a gap that pushes the target away from the anchor in the direction of the placement while respecting the alignment.

E.g. If the placement is BottomRight, the offset will push the target further in that direction. If the placement is BottomCenter, the offset applies only to the Y-axis (moving it down), to keep the target centered horizontally.

Parameters:

  • target – Widget to position (needed for size).

  • anchor – Anchor widget to position relative to.

  • anchor_pos – Explicit global position (alternative to anchor widget).

  • placement – Placement strategy (default: Auto).

  • offset – Gap in pixels between anchor and target (default: 4).

Returns:

Global screen coordinates for target’s top-left corner.

Raises:

ValueError – If neither anchor nor anchor_pos is provided.