pgwidgets-js 0.3.3__tar.gz → 0.3.4__tar.gz

{pgwidgets_js-0.3.3 → pgwidgets_js-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pgwidgets-js
-Version: 0.3.3
+Version: 0.3.4
 Summary: pgwidgets JavaScript widget library — static assets for use with Python servers
 Author: PGWidgets Developers
 License: BSD-3-Clause
@@ -26,7 +26,7 @@ Requires-Dist: pytest; extra == "test"
 Dynamic: license-file
 
 <p align="center">
-  <img src="pgwidgets_js/static/icons/pgwidgets-logo.png" alt="pgwidgets logo" width="300">
+  <img src="pgwidgets_js/static/icons/pgwidgets-logo.png" alt="pgwidgets logo" width="500">
 </p>
 
 <p align="center">

{pgwidgets_js-0.3.3 → pgwidgets_js-0.3.4}/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="pgwidgets_js/static/icons/pgwidgets-logo.png" alt="pgwidgets logo" width="300">
+  <img src="pgwidgets_js/static/icons/pgwidgets-logo.png" alt="pgwidgets logo" width="500">
 </p>
 
 <p align="center">

{pgwidgets_js-0.3.3 → pgwidgets_js-0.3.4}/docs/WhatsNew.rst

@@ -1,6 +1,80 @@
 What's New
 ==========
 
+Recent changes — since ``v0.3.3``
+---------------------------------
+
+TextSource: text no longer clipped when scrolling long files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A ``TextSource`` holding more than a screenful of text showed only the
+first screen -- the scrollbar reported the full length, but scrolling
+past the first page revealed blank space.  The edit area is now laid out
+so it grows to the full content height, and the widget scrolls through
+all of it.
+
+TextSource: fonts, hover tooltips, and scroll helpers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``set_font(family, size)`` sets the editor font.  Hover tooltips can be
+enabled with ``set_tooltips_enabled(True)``: while enabled the widget
+fires a ``tooltip`` callback carrying the line, column and text under the
+pointer, leaving the host to decide what (if anything) to display.  New
+scroll helpers address the buffer by offset (used by ``scroll_to_ref``
+and the remote-driver scroll methods), and ``set_wrap`` now also accepts
+a boolean.
+
+TextSource: selection and tag-region queries
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Four query methods now match Ginga's qt/gtk ``TextSource``:
+``has_selection()``; ``get_selection_bounds()`` returning the selected
+``[start, end]`` refs (or ``None``); ``get_tag_region(name)`` returning a
+tag's overall span; and ``get_tag_regions(name)`` returning one
+``[start, end]`` pair per contiguous run of the tag.  They are declared in
+the widget spec, so the Python proxy -- and thus Ginga's pgw
+``TextSource`` -- can call them.
+
+New widget: Separator
+~~~~~~~~~~~~~~~~~~~~~
+
+``Separator`` is a thin horizontal or vertical rule for visually
+dividing a layout.
+
+Button: per-button hover highlight (``set_hover``)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``set_hover(bg, fg)`` mirrors the qt/gtk backends' per-button hover:
+while the pointer is over the button its colors switch to the supplied
+values and revert on mouse-out.  Passing ``(None, None)`` clears it.  It
+is a setter, so it round-trips and replays on browser reconnect (like
+``set_color``).
+
+ButtonBox: ``min_button_width`` option
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A ``ButtonBox`` already sizes its buttons to the widest member; the new
+``min_button_width`` constructor option sets a floor so buttons never
+render narrower than the given width.
+
+Dialog: ``set_title``, and correct content-area handling
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``set_title`` is now callable on a ``Dialog`` across all wrappers;
+previously the method was undeclared on the ``Dialog`` spec and raised
+``AttributeError``.  Also, ``remove_all`` / ``remove_widget`` /
+``get_children`` / ``num_children`` now target the dialog's content area,
+matching ``add_widget``.  Previously ``remove_all`` tore out the whole
+content-plus-buttons layout, so a rebuilt dialog (e.g. a ``MessageDialog``
+re-showing its message) could leave its content orphaned and blank.
+
+TableView: ``set_row_spacing`` / ``set_column_spacing``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Python proxy for ``TableView`` now exposes ``set_row_spacing`` and
+``set_column_spacing`` (already implemented by its ``TreeView`` base), so
+cell spacing can be set on a ``TableView``.
+
 Recent changes — since ``v0.3.2``
 ---------------------------------
 

{pgwidgets_js-0.3.3 → pgwidgets_js-0.3.4}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pgwidgets",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "A native JavaScript widget library with Qt/GTK-style layout and controls",
   "type": "module",
   "main": "Widgets.js",

{pgwidgets_js-0.3.3 → pgwidgets_js-0.3.4}/pgwidgets_js/defs.py

@@ -109,7 +109,7 @@ WIDGETS = {
     "ButtonBox": {
         "base": "container",
         "args": [],
-        "options": ["orientation", "halign"],
+        "options": ["orientation", "halign", "min_button_width"],
         "methods": {
             "add_widget": ["child", "stretch"],
             "insert_widget": ["index", "child", "stretch"],
@@ -179,6 +179,17 @@ WIDGETS = {
         "callbacks": [],
     },
 
+    "Separator": {
+        # A thin horizontal or vertical rule (like an HTML <hr>).
+        "base": "widget",
+        "args": ["orientation"],
+        "options": [],
+        "methods": {
+            "set_orientation": ["orientation"],
+        },
+        "callbacks": [],
+    },
+
     "Expander": {
         # JS Expander extends ContainerWidget (single child via set_widget),
         # so it needs the container method set (get_children, num_children,
@@ -366,6 +377,8 @@ WIDGETS = {
             "set_position": ["x", "y"],
             "popup": ["x", "y"],
             "set_modal": ["tf"],
+            # inherited from TopLevel on the JS side (Dialog extends TopLevel)
+            "set_title": ["title"],
         },
         "callbacks": [*CONTAINER_CALLBACKS, "activated", "move", "close"],
     },
@@ -409,6 +422,7 @@ WIDGETS = {
             "set_icon": ["url", "size"],
             "get_icon": [],
             "set_color": ["bg", "fg"],
+            "set_hover": ["bg", "fg"],
         },
         "callbacks": ["activated"],
     },
@@ -547,10 +561,14 @@ WIDGETS = {
             "set_wrap": ["mode"],
             "set_line_numbers": ["tf"],
             "set_icon_gutter": ["tf"],
+            "set_font": ["family", "size"],
+            "set_tooltips_enabled": ["tf"],
             "set_icon": ["ref", "icon_url"],
             "get_cursor": [],
             "set_cursor": ["ref"],
             "get_selection_range": [],
+            "has_selection": [],
+            "get_selection_bounds": [],
             "set_selection_range": ["start_ref", "end_ref"],
             # Tags
             "create_tag": ["name", "attrs"],
@@ -560,6 +578,8 @@ WIDGETS = {
             "remove_tag": ["name", "start_ref", "end_ref"],
             "get_tags_at": ["ref"],
             "get_tags_range": ["start_ref", "end_ref"],
+            "get_tag_region": ["name"],
+            "get_tag_regions": ["name"],
             # Live refs
             "create_ref": ["offset", "gravity"],
             "remove_ref": ["ref"],
@@ -594,7 +614,7 @@ WIDGETS = {
             "get_scroll_position": [],
         },
         "callbacks": ["changed", "cursor_moved", "line_clicked",
-                      "icon_clicked", "scrolled"],
+                      "icon_clicked", "scrolled", "tooltip"],
     },
 
     # A live position handle into a TextSource buffer.  Extends the
@@ -830,6 +850,8 @@ WIDGETS = {
             "select_all": ["state"],
             "set_column_width": ["col_index", "width"],
             "set_optimal_column_widths": [],
+            "set_row_spacing": ["px"],
+            "set_column_spacing": ["px"],
             "sort_by_column": ["col_index", "ascending"],
             "scroll_to_path": ["path"],
             "scroll_to_end": [],

{pgwidgets_js-0.3.3 → pgwidgets_js-0.3.4}/pgwidgets_js/static/Widgets.js

@@ -33,6 +33,7 @@ import {ToggleButton} from "./modules/ToggleButton.js";
 import {RadioButton} from "./modules/RadioButton.js";
 import {ProgressBar} from "./modules/ProgressBar.js";
 import {Frame} from "./modules/Frame.js";
+import {Separator} from "./modules/Separator.js";
 import {FixedLayout} from "./modules/FixedLayout.js";
 import {GridBox} from "./modules/GridBox.js";
 import {Image} from "./modules/Image.js";
@@ -61,7 +62,7 @@ const Widgets = {Callback, Widget, ContainerWidget, Box, VBox, HBox, ButtonBox,
                  TopLevel, AbstractScrollArea, ScrollArea, MDIWidget, Splitter, TabWidget,
                  StackWidget, Expander, Page, Text, Label, StatusBar, TextArea, TextSource,
                  TextBufferRef,
-                 Frame, FixedLayout, GridBox, Button, ToggleButton, CheckBox,
+                 Frame, Separator, FixedLayout, GridBox, Button, ToggleButton, CheckBox,
                  RadioButton, ComboBox, ComboBoxNative, TextEntry,
                  Slider, Canvas, SpinBox, ProgressBar, Image, Dial,
                  MenuBar, Menu, MenuAction, ToolBar, ToolBarAction,

{pgwidgets_js-0.3.3 → pgwidgets_js-0.3.4}/pgwidgets_js/static/css/TextSource.css

@@ -29,6 +29,14 @@
     grid-column: 1;
     display: flex;
     flex-direction: row;
+    /* Top-align children so the edit wrap grows to its full content
+       height instead of being stretched (and clipped) to the visible
+       height.  With the default `stretch`, `.textsource-edit-wrap`
+       (overflow: hidden) gets capped at the viewport height and clips
+       the text to one screenful, while the number gutter (overflow
+       visible) still reports the full height -- so the scrollbar looks
+       right but scrolling reveals blank space. */
+    align-items: flex-start;
     overflow-y: auto;
     overflow-x: hidden;
     min-height: 0;
@@ -47,6 +55,8 @@
     background: #f4f4f4;
     border-right: 1px solid #e0e0e0;
     user-select: none;
+    /* fill the viewport height for short documents (see .textsource-main) */
+    min-height: 100%;
 }
 
 .textsource-icon-cell {
@@ -75,6 +85,8 @@
     font-size: 12px;
     text-align: right;
     user-select: none;
+    /* fill the viewport height for short documents (see .textsource-main) */
+    min-height: 100%;
 }
 
 .textsource-line-number {
@@ -88,6 +100,12 @@
     flex: 1 1 auto;
     position: relative;
     overflow: hidden;
+    /* Fill the viewport height for short documents (children are
+       top-aligned in .textsource-main, so without this the box would
+       shrink to its content height). For tall documents the box grows
+       past this to its full content height, letting .textsource-main
+       be the single vertical scroller. */
+    min-height: 100%;
     min-width: 0;
     /* hide native horizontal scrollbar; we use ScrollBar widget */
     scrollbar-width: none;

{pgwidgets_js-0.3.3 → pgwidgets_js-0.3.4}/pgwidgets_js/static/modules/Box.js

@@ -214,6 +214,9 @@ class ButtonBox extends Box {
     constructor(options = { orientation: 'horizontal' }) {
         super(options);
         this._halign = this.get_option(options, 'halign', 'center');
+        // optional lower bound: buttons are never narrower than this, even
+        // if the widest button's natural size is smaller
+        this._minButtonWidth = this.get_option(options, 'min_button_width', null);
         this._applyAlign();
 
     }
@@ -281,8 +284,9 @@ class ButtonBox extends Box {
                 let w = elt.getBoundingClientRect().width;
                 if (w > maxW) maxW = w;
             }
-            if (maxW > 0) {
-                let px = Math.ceil(maxW) + 'px';
+            let target = Math.max(Math.ceil(maxW), this._minButtonWidth || 0);
+            if (target > 0) {
+                let px = target + 'px';
                 for (let child of this.children) {
                     let elt = child.get_element();
                     elt.style.minWidth = px;

{pgwidgets_js-0.3.3 → pgwidgets_js-0.3.4}/pgwidgets_js/static/modules/Button.js

@@ -35,6 +35,11 @@ class Button extends Widget {
 
         this.element.onclick = () => this._cb_redirect('clicked');
         this.enable_callback('activated');
+
+        // hover highlight colors (see set_hover); null = no hover override
+        this._hoverBg = null;
+        this._hoverFg = null;
+        this._hoverInstalled = false;
     }
 
     /**
@@ -114,6 +119,58 @@ class Button extends Widget {
         }
     }
 
+    /**
+     * Give this button a hover highlight: while the pointer is over the
+     * button its background/foreground switch to the supplied colors,
+     * reverting on mouse-out.  Mirrors the qt/gtk backends' per-button
+     * hover.  Pass ``(null, null)`` or empty strings to clear it.
+     *
+     * Implemented with mouseenter/mouseleave that swap (and restore) the
+     * inline style, because an inline base background set via set_color
+     * would otherwise win over a CSS ``:hover`` rule.
+     *
+     * @param {string|null} [bg=null] - Hover background CSS color.
+     * @param {string|null} [fg=null] - Hover foreground (text) CSS color.
+     */
+    set_hover(bg=null, fg=null) {
+        this._hoverBg = (bg === '') ? null : bg;
+        this._hoverFg = (fg === '') ? null : fg;
+        if (!this._hoverInstalled) {
+            this._hoverInstalled = true;
+            this.element.addEventListener('mouseenter',
+                                          () => this._applyHover());
+            this.element.addEventListener('mouseleave',
+                                          () => this._restoreHover());
+        }
+    }
+
+    _applyHover() {
+        if (this._hoverBg === null && this._hoverFg === null) {
+            return;
+        }
+        // remember whatever inline colors are in effect (e.g. a base color
+        // from set_color, or '' for the default look) so we can restore them
+        this._savedBg = this.element.style.background;
+        this._savedFg = this.element.style.color;
+        if (this._hoverBg !== null) {
+            this.element.style.background = this._hoverBg;
+        }
+        if (this._hoverFg !== null) {
+            this.element.style.color = this._hoverFg;
+        }
+    }
+
+    _restoreHover() {
+        if (this._savedBg !== undefined) {
+            this.element.style.background = this._savedBg;
+            this._savedBg = undefined;
+        }
+        if (this._savedFg !== undefined) {
+            this.element.style.color = this._savedFg;
+            this._savedFg = undefined;
+        }
+    }
+
     _cb_redirect(action) {
         if (action === 'clicked') {
             this.make_callback('activated');

{pgwidgets_js-0.3.3 → pgwidgets_js-0.3.4}/pgwidgets_js/static/modules/Dialog.js

@@ -149,6 +149,42 @@ class Dialog extends TopLevel {
         this._contentArea.set_spacing(gap);
     }
 
+    /**
+     * Removes a widget from the dialog's content area.
+     * @param {Widget} child - The widget to remove.
+     * @param {boolean} [destroy=false] - If true, also destroy the child.
+     */
+    remove_widget(child, destroy = false) {
+        this._contentArea.remove_widget(child, destroy);
+    }
+
+    /**
+     * Removes all widgets from the dialog's content area, leaving the
+     * button bar intact.  (The base implementation would clear the
+     * dialog's own children -- the content area + button bar -- which
+     * detaches the layout; delegate here to match add_widget().)
+     * @param {boolean} [destroy=false] - If true, also destroy each child.
+     */
+    remove_all(destroy = false) {
+        this._contentArea.remove_all(destroy);
+    }
+
+    /**
+     * Returns the content area's child widgets.
+     * @returns {Widget[]} The children array.
+     */
+    get_children() {
+        return this._contentArea.get_children();
+    }
+
+    /**
+     * Returns the number of widgets in the dialog's content area.
+     * @returns {number} The child count.
+     */
+    num_children() {
+        return this._contentArea.num_children();
+    }
+
     /**
      * Adds a button widget to the dialog's button bar.
      * Clicking the button fires the dialog's 'activated' callback

pgwidgets_js-0.3.4/pgwidgets_js/static/modules/Separator.js

@@ -0,0 +1,55 @@
+"use_strict";
+
+import {Widget} from "./Widget.js";
+
+/**
+ * A thin separator rule (like an HTML <hr>).  Rendered as a 1px border on
+ * one edge of a zero-thickness div so it takes essentially no space along
+ * its thin axis while stretching along the other.
+ * @extends Widget
+ */
+class Separator extends Widget {
+
+    /**
+     * @param {string} [orientation='horizontal'] - 'horizontal' or 'vertical'.
+     * @param {Object} [options]
+     */
+    constructor(orientation='horizontal', options={}) {
+        super();
+        // orientation may arrive positionally or in the options dict
+        if (orientation != null && typeof orientation === 'object') {
+            options = orientation;
+            orientation = null;
+        }
+        this._orientation = orientation
+            || this.get_option(options, 'orientation', 'horizontal');
+
+        this.element = document.createElement('div');
+        this.element.className = 'separator-widget';
+        this._applyOrientation();
+
+        super.init_style();
+    }
+
+    _applyOrientation() {
+        let s = this.element.style;
+        s.borderTop = s.borderLeft = '';
+        s.width = s.height = '';
+        if (this._orientation === 'vertical') {
+            s.width = '0px';
+            s.height = '100%';
+            s.borderLeft = '1px solid #888';
+        } else {
+            s.height = '0px';
+            s.width = '100%';
+            s.borderTop = '1px solid #888';
+        }
+    }
+
+    set_orientation(orientation) {
+        this._orientation = orientation || 'horizontal';
+        this._applyOrientation();
+    }
+}
+
+export { Separator };

{pgwidgets_js-0.3.3 → pgwidgets_js-0.3.4}/pgwidgets_js/static/modules/TextSource.js

@@ -454,6 +454,14 @@ class TextSource extends Widget {
                 this._captureSelection();
             }
         });
+
+        // -- hover tooltips (fire 'tooltip'; the page decides what to show) --
+        this._tooltipsEnabled = false;
+        this._tooltipTimer = null;
+        this._tooltipEl = null;
+        this._edit.addEventListener('mousemove', (e) => this._onHoverMove(e));
+        this._edit.addEventListener('mouseleave', () => this._hideTooltip());
+
         requestAnimationFrame(() => { this._scrollReady = true; });
     }
 
@@ -816,6 +824,25 @@ class TextSource extends Widget {
                 this.create_ref(e, 'right')];
     }
 
+    /**
+     * Whether there is a non-empty selection.
+     * @returns {boolean}
+     */
+    has_selection() {
+        return this._selStart !== this._selEnd;
+    }
+
+    /**
+     * Canonical accessor used by page-level code.  Returns
+     * ``[startRef, endRef]`` for the current selection, or ``null``
+     * when there is no selection (guard with ``has_selection()``).
+     * Alias of ``get_selection_range``; does not throw.
+     * @returns {?[TextBufferRef, TextBufferRef]}
+     */
+    get_selection_bounds() {
+        return this.get_selection_range();
+    }
+
     /**
      * Set the selection to span ``[startRef, endRef]``.  The cursor
      * lands at *endRef*'s position.
@@ -841,6 +868,9 @@ class TextSource extends Widget {
     }
 
     set_wrap(mode) {
+        // Tolerate a boolean (some callers pass true/false): map to a mode.
+        if (mode === true) mode = 'word';
+        else if (mode === false) mode = 'none';
         if (!['none', 'hard', 'word'].includes(mode)) {
             throw new Error(`Invalid wrap mode: ${mode}`);
         }
@@ -861,6 +891,106 @@ class TextSource extends Widget {
         this._render();
     }
 
+    /**
+     * Set the editor font.  ``family`` and/or ``size`` (px) may be null to
+     * leave that dimension unchanged.  The line-number gutter is kept in the
+     * same font so its rows stay aligned with the text.
+     * @param {?string} family
+     * @param {?number} size
+     */
+    set_font(family, size) {
+        if (family != null) this._fontFamily = family;
+        if (size != null) this._fontSize = size;
+        for (let el of [this._edit, this._numberGutter]) {
+            if (el) {
+                el.style.fontFamily = this._fontFamily;
+                el.style.fontSize = this._fontSize + 'px';
+            }
+        }
+        this._render();
+    }
+
+    /** Enable/disable hover tooltips (which fire the 'tooltip' callback). */
+    set_tooltips_enabled(tf) {
+        this._tooltipsEnabled = !!tf;
+        if (!this._tooltipsEnabled) this._hideTooltip();
+    }
+
+    _onHoverMove(e) {
+        if (!this._tooltipsEnabled) return;
+        // Hide any showing tooltip while the pointer moves, and (re)arm a
+        // timer so we only query once the pointer settles -- like a native
+        // tooltip.
+        this._hideTooltip();
+        let x = e.clientX, y = e.clientY;
+        this._tooltipTimer = setTimeout(() => {
+            this._tooltipTimer = null;
+            let hit = this._lineColFromPoint(x, y);
+            if (hit === null) return;
+            // The page appends a string to the callback's result list (on the
+            // Python side) and calls _showTooltip() if it wants one shown.
+            this.make_callback('tooltip', hit.line, hit.col, hit.text, x, y);
+        }, 400);
+    }
+
+    _lineColFromPoint(x, y) {
+        let cp = null;
+        if (document.caretPositionFromPoint) {
+            let p = document.caretPositionFromPoint(x, y);
+            if (p) cp = {node: p.offsetNode, offset: p.offset};
+        } else if (document.caretRangeFromPoint) {
+            let r = document.caretRangeFromPoint(x, y);
+            if (r) cp = {node: r.startContainer, offset: r.startOffset};
+        }
+        if (!cp || !cp.node) return null;
+        let el = cp.node.nodeType === Node.TEXT_NODE ? cp.node.parentNode
+                                                     : cp.node;
+        let lineDiv = el && el.closest ? el.closest('.textsource-line') : null;
+        if (!lineDiv) return null;
+        // column = length of text from the line start up to the caret point
+        let range = document.createRange();
+        range.selectNodeContents(lineDiv);
+        try {
+            range.setEnd(cp.node, cp.offset);
+        } catch (err) {
+            return null;
+        }
+        return {line: parseInt(lineDiv.dataset.lineIndex, 10) || 0,
+                col: range.toString().length,
+                text: lineDiv.textContent};
+    }
+
+    /** Show (non-empty text) or hide (empty) a tooltip near (x, y). */
+    _showTooltip(text, x, y) {
+        if (!text) { this._hideTooltip(); return; }
+        if (this._tooltipEl === null) {
+            let el = document.createElement('div');
+            el.className = 'textsource-tooltip';
+            Object.assign(el.style, {
+                position: 'fixed', zIndex: '10000', background: '#ffffe0',
+                color: '#000', border: '1px solid #888', padding: '2px 6px',
+                font: '12px sans-serif', pointerEvents: 'none',
+                maxWidth: '400px', whiteSpace: 'pre-wrap',
+            });
+            document.body.appendChild(el);
+            this._tooltipEl = el;
+        }
+        this._tooltipEl.textContent = text;
+        this._tooltipEl.style.left = (x + 12) + 'px';
+        this._tooltipEl.style.top = (y + 16) + 'px';
+        this._tooltipEl.style.display = 'block';
+    }
+
+    _hideTooltip() {
+        if (this._tooltipTimer !== null) {
+            clearTimeout(this._tooltipTimer);
+            this._tooltipTimer = null;
+        }
+        if (this._tooltipEl !== null) {
+            this._tooltipEl.style.display = 'none';
+        }
+    }
+
     /**
      * Set (or clear) the icon associated with a TextBufferRef.  The
      * icon is displayed on the line that contains the ref's current
@@ -1728,6 +1858,48 @@ class TextSource extends Widget {
         return Array.from(names);
     }
 
+    /**
+     * Returns the overall ``[startRef, endRef]`` span of a named tag —
+     * from the first occurrence of the tag to the last — or ``null`` if
+     * the tag is not applied anywhere.  This is the replacement for the
+     * old GTK ``get_region`` helper used by page-level code.
+     * @param {string} name
+     * @returns {?[TextBufferRef, TextBufferRef]}
+     */
+    get_tag_region(name) {
+        let spans = this._tags.filter(t => t.name === name);
+        if (spans.length === 0) return null;
+        let start = Math.min(...spans.map(t => t.start));
+        let end = Math.max(...spans.map(t => t.end));
+        return [this.create_ref(start, 'right'),
+                this.create_ref(end, 'right')];
+    }
+
+    /**
+     * Returns an array of ``[startRef, endRef]`` pairs, one per maximal
+     * contiguous run of the named tag.  Empty array if unapplied.
+     * @param {string} name
+     * @returns {Array<[TextBufferRef, TextBufferRef]>}
+     */
+    get_tag_regions(name) {
+        let spans = this._tags.filter(t => t.name === name)
+                              .sort((a, b) => a.start - b.start);
+        if (spans.length === 0) return [];
+        let merged = [];
+        let curStart = spans[0].start, curEnd = spans[0].end;
+        for (let t of spans.slice(1)) {
+            if (t.start <= curEnd) {
+                curEnd = Math.max(curEnd, t.end);
+            } else {
+                merged.push([curStart, curEnd]);
+                curStart = t.start; curEnd = t.end;
+            }
+        }
+        merged.push([curStart, curEnd]);
+        return merged.map(([s, e]) => [this.create_ref(s, 'right'),
+                                       this.create_ref(e, 'right')]);
+    }
+
     _updateTagsOnInsert(offset, n) {
         for (let t of this._tags) {
             if (t.start >= offset) t.start += n;
@@ -1826,8 +1998,18 @@ class TextSource extends Widget {
      * @param {TextBufferRef} ref
      */
     scroll_to_ref(ref) {
-        let offset = this._offsetOf(ref);
-        let line = this._lineOfOffset(offset);
+        this._scrollToOffset(this._offsetOf(ref));
+    }
+
+    /**
+     * Scroll so the line containing *offset* is visible.  Reconstruction /
+     * remote-driver counterpart to ``scroll_to_ref`` that avoids minting a
+     * ref over the wire (the Python side owns the ref and passes its offset).
+     * @private
+     * @param {number} offset
+     */
+    _scrollToOffset(offset) {
+        let line = this._lineOfOffset(this._clampOffset(offset));
         let lineDiv = this._edit.children[line];
         if (lineDiv && lineDiv.scrollIntoView) {
             lineDiv.scrollIntoView({ block: 'nearest' });