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 or item-view cell, the placement determines which point on the anchor 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 (for widget anchors) or screen (for point and cell anchors). It divides the relevant area into a 3x3 grid and picks 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
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.calc_pos_at_point(target: QWidget, anchor_pos: QPoint, placement: Placement = Placement.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.

  • placement – Direction the target expands from anchor_pos. See Placement for the full set of options, including Auto’s screen-aware behavior.

  • offset – Gap in pixels between anchor_pos and the target, applied in the direction of placement. For edge-centered placements (e.g. BottomCenter) the offset only applies to the perpendicular axis so the target stays centered along the parallel axis.

Returns:

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

schrodinger.ui.qt.standard.widgets.positioner.calc_pos_at_widget(target: QWidget, anchor: QWidget, placement: Placement = Placement.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.

  • placement – Which point on anchor to attach to (e.g. BottomRight attaches to the anchor’s bottom-right corner). See Placement for the full set of options, including Auto’s window-aware behavior.

  • offset – Gap in pixels between anchor and the target. See calc_pos_at_point for the full offset semantics.

Returns:

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

schrodinger.ui.qt.standard.widgets.positioner.calc_pos_at_index(target: QWidget, view: QAbstractItemView, index: QModelIndex, placement: Placement = Placement.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).

  • placement – Which point of the cell to attach to (e.g. BottomRight attaches to the cell’s bottom-right corner). See Placement for the full set of options, including Auto’s screen-aware behavior.

  • offset – Gap in pixels between the cell and the target. See calc_pos_at_point for the full offset semantics.

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.widgets.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.