schrodinger.ui.qt.standard.positioner module

class schrodinger.ui.qt.standard.positioner.Origin

Bases: Enum

A point on a widget rectangle.

Pass an anchor and target origin to calc_pos_at_widget or calc_pos_at_index to align any point on the target with any point on the anchor. For example, aligning BottomRight on an anchor with TopRight on a target places the target below the anchor with their right edges flush.

Auto chooses origins based on the anchor’s position within its window (for widget anchors) or screen (for point and cell anchors). It divides that area into a 3x3 grid and makes the target expand toward the center:

+-----------+-----------+-----------+
| Expand SE | Expand S  | Expand SW |
+-----------+-----------+-----------+
| Expand E  | Expand N* | Expand W  |
+-----------+-----------+-----------+
| Expand NE | Expand N  | Expand NW |
+-----------+-----------+-----------+
* Center expands north to avoid covering the anchor.

For widget and cell anchors, Auto selects the anchor origin facing the expansion direction and the opposite target origin. Both origins must be Auto together. For point anchors, the anchor is already fixed and Auto selects only the target origin.

Auto = None
TopLeft = AlignmentFlag.AlignLeft|AlignTop
TopCenter = AlignmentFlag.AlignHCenter|AlignTop
TopRight = AlignmentFlag.AlignRight|AlignTop
CenterLeft = AlignmentFlag.AlignLeft|AlignVCenter
Center = AlignmentFlag.AlignCenter
CenterRight = AlignmentFlag.AlignRight|AlignVCenter
BottomLeft = AlignmentFlag.AlignLeft|AlignBottom
BottomCenter = AlignmentFlag.AlignHCenter|AlignBottom
BottomRight = AlignmentFlag.AlignRight|AlignBottom
exception schrodinger.ui.qt.standard.positioner.MixedAutoOriginsError

Bases: ValueError

Raised when exactly one origin uses automatic positioning.

schrodinger.ui.qt.standard.positioner.calc_pos_at_point(target: QWidget, anchor_pos: QPoint, target_origin: Origin = Origin.Auto, offset: int = 4) → QPoint

Calculate the position for a target widget anchored at a global point.

Parameters:

  • target – The widget to be positioned (only its size is used).

  • anchor_pos – Global screen coordinates of the anchor point.

  • target_origin – Point on target to align with anchor_pos. Auto chooses an origin that expands the target toward the center of the screen.

  • offset – Per-axis gap in pixels. The target moves away from anchor_pos along each non-centered axis selected by target_origin; centered axes receive no offset.

Returns:

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

schrodinger.ui.qt.standard.positioner.calc_pos_at_widget(target: QWidget, anchor: QWidget, anchor_origin: Origin = Origin.Auto, target_origin: Origin = Origin.Auto, offset: int = 4) → QPoint

Calculate the position for a target widget anchored at another widget.

Parameters:

  • target – The widget to be positioned (only its size is used).

  • anchor – The widget the target anchors to.

  • anchor_origin – Point on anchor to attach to.

  • target_origin – Point on target to align with anchor_origin.

  • offset – Per-axis gap in pixels. On an axis where the two origins differ, the target moves offset pixels in the direction from its origin toward the anchor origin. Matching origins receive no offset on that axis.

Returns:

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

schrodinger.ui.qt.standard.positioner.calc_pos_at_index(target: QWidget, view: QAbstractItemView, index: QModelIndex, anchor_origin: Origin = Origin.Auto, target_origin: Origin = Origin.Auto, offset: int = 4) → QPoint

Calculate the position for a target widget anchored at an item-view cell.

Use this for popups, menus, or tooltips raised from clicks or context-menu requests on a cell – e.g. a context menu raised from a right-click on a row, a popup raised from a left-click on a cell, or a tooltip raised from a delegate event.

Parameters:

  • target – The widget to be positioned (only its size is used).

  • view – The item view (table/list/tree) that contains index.

  • index –

    Points to the cell where the target should anchor. Common ways to obtain one:

    • In a delegate’s paint/editorEvent/createEditor/etc.: use the index parameter Qt passes in (also available as option.index).

    • In a customContextMenuRequested(viewport_pos) handler on a view: use view.indexAt(viewport_pos).

  • anchor_origin – Point on the cell to attach to.

  • target_origin – Point on target to align with anchor_origin.

  • offset – Per-axis gap in pixels, with the same origin-relative behavior as calc_pos_at_widget.

Returns:

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

Raises:

ValueError – If index is invalid, or its visual rect is empty (e.g. scrolled out of view, or in a collapsed tree branch).

schrodinger.ui.qt.standard.positioner.get_viewport_global_pos(view: QAbstractScrollArea, viewport_pos: QPoint) → QPoint

Convert a viewport-local point to global screen coordinates.

Use this when you have a raw QPoint in viewport coordinates with no associated cell – for example, a click on empty space in a table or list view. The returned point can be passed to calc_pos_at_point via anchor_pos. For anchoring to a specific cell or model index, use calc_pos_at_index instead.

Parameters:

  • view – The scroll area whose viewport viewport_pos is in.

  • viewport_pos – A point in viewport-local coordinates.

Returns:

The same point in global screen coordinates.

schrodinger.ui.qt.standard.positioner.constrain_to_screen(top_left: QPoint, size: QSize, screen: PyQt6.QtGui.QScreen | None) → QPoint

Constrain a rectangle’s origin to a screen’s available geometry.

The rectangle is moved but not resized. If it is wider or taller than the available geometry, its origin is placed at the corresponding screen boundary and it may extend past the opposite boundary.

Parameters:

  • top_left – Proposed global position for the rectangle’s origin.

  • size – Size of the rectangle to constrain.

  • screen – Screen to constrain the rectangle to. If None, return the proposed position unchanged.

Returns:

The constrained global position for the rectangle’s origin.

schrodinger.ui.qt.standard.positioner.validate_origin(origin: Origin, name: str = 'origin') → None

Raise a stable TypeError when origin is not an Origin.

schrodinger.ui.qt.standard.positioner.validate_origin_pair(anchor_origin: Origin, target_origin: Origin) → None

Validate an anchor/target origin pair.

Raises: