Skip to content

Match the declarations to GNOME Shell 51 - #147

Open
JumpLink wants to merge 2 commits into
v51.x.xfrom
fix/gnome-51-api-drift
Open

Match the declarations to GNOME Shell 51#147
JumpLink wants to merge 2 commits into
v51.x.xfrom
fix/gnome-51-api-drift

Conversation

@JumpLink

@JumpLink JumpLink commented Aug 29, 2026

Copy link
Copy Markdown
Collaborator

GNOME 51 moved event handling off actor vfuncs and onto Clutter actions, gestures and key binding pools. The shell classes stopped overriding vfunc_*_event and grew signal handlers instead. Those vfuncs still exist on Clutter.Actor, so nothing fails to compile. The declarations just stopped describing the shell, quietly.

Stacked on #145, which is stacked on #144. Merge those first and this diff is only the two commits below.

First commit, sync with 51

Checked module by module against gnome-shell at tag 51.beta, for every declared name that changed between 50.4 and 51.beta.

module what changed
appDisplay BaseAppView / AppDisplay._onScroll now takes the ScrollController::scroll arguments, and _onKeyPressEvent became a binding pool closure
boxpointer _muteKeys is a Clutter.KeyController and _muteInput a Clutter.ClickGesture, both were boolean
calendar vfunc_scroll_event became _onScroll
dialog vfunc_event became a KeyController
layout HotCorner.vfunc_leave_event is gone
messageList URLHighlighter motion and leave became a MotionController, Message.vfunc_key_press_event became _closeIfAllowed
messageTray _onNotificationKeyRelease became a binding pool closure
modalDialog vfunc_captured_event is gone
search new exported SearchEntry, with its activate-new-instance signal
slider scroll and key vfuncs became _onScroll, _moveLeft, _moveRight
status/backlight SliderItem forwards vfunc_navigate_focus to the slider
status/volume _handleScrollEvent became _onScroll plus _handleScroll
switcherPopup key and scroll vfuncs became _onKeyPress, _onModifierChange, _onScroll
userWidget new showAvatar and hideAvatar

Everything added carries @version 51, per the convention. I applied it to the handlers whose arguments 51 reshaped as well, appDisplay._onScroll for one, since the declared contract is the 51 one. Trim those if you read the tag more strictly.

Two additions I left out, because those classes declare no members at all and one more private helper would not help anyone. ActivitiesButton._toggleAction in panel, declared as class ActivitiesButton extends Button {}, and WindowPreview._onEnter / _onLeave in windowPreview, which declares exactly two members.

Second commit, names 51 did not remove but an earlier release did

Checking those modules turned up a second group, absent at 50.4 as well. They describe an API no supported shell has. Same files, so the same PR, but a separate commit, because it is a different claim and you may want to judge it separately.

slider is the worst of them. startDragging, _endDragging, _motionEvent, scroll and three vfuncs all went away when the pan gesture landed, and step(nSteps), the method status/volume actually calls, was never declared. That one I added. It predates 51, so it carries no @version tag.

What is still wrong after this PR

The same check across the whole package still reports 37 stale member declarations in 12 files. All of them are in modules GNOME 51 did not touch, so they are outside this PR's scope, but they are the same defect.

  • misc/systemActions: _loginManager
  • ui/animation: _animationsLoaded, _init, _loadFile, _onDestroy, _showFrame, _syncAnimationSize, _update
  • ui/closeDialog: _onFocusChanged, _tracked
  • ui/components: _sessionUpdated
  • ui/dnd: _dragState, _eventIsRelease, _grabActor, _grabDevice, _maybeStartDrag, _onButtonPress, _onTouchEvent, _ungrabActor, _ungrabDevice
  • ui/iconGrid: _childAdded, _childRemoved
  • ui/messageList: _closeButton, _getIcon, _onUpdated, _secondaryBin
  • ui/status/accessibility: _buildItemExtended
  • ui/status/brightness: _changeSlider, _proxy, _sliderChanged, _sliderChangedId
  • ui/status/network: _closeConnectivityCheck, _flushConnectivityQueue, _portalHelperDone
  • ui/status/remoteAccess: vfunc_event
  • ui/status/thunderbolt: _ensureSource, _source

ui/animation is the striking one. Spinner uses a constructor now, and the Animation base class the declaration describes is not in js/ui/animation.js at all any more.

There is a stale export too. search.d.ts exports MaxWidthBox, which upstream has kept module-private since at least 50.4. Removing an export breaks consumers, so I left it alone.

The part worth automating

I found all of this with a throwaway script. Parse the declared members out of each .d.ts, parse the defined names out of the matching js/ file at a given tag, print the difference. It found the 51 drift and the older drift in one run, and it is the only reason this PR is a list rather than a guess.

It could live in the repo as scripts/check-shell-api.mjs, run against a shallow git clone --depth 1 --branch <tag> of gnome-shell, so each cycle starts from a diff instead of from whatever the compiler happens to notice. It cannot be a required check until the 37 above are dealt with, but it can run and report. Say the word and I will send it.

One caveat, so nobody over-trusts it. It matches names, not shapes. It cannot see a method whose signature changed, and it has false positives around static class fields. _mediaSource in messageList was one, a static _mediaSource = …, which I checked and kept. Every removal in this PR I verified by reading the upstream source, not by trusting the script.

Validation

build:types, prettier:check, validate:types, build:example and validate:example all pass locally.

@JumpLink
JumpLink force-pushed the fix/gnome-51-api-drift branch from 3777bff to 755b6ff Compare August 29, 2026 06:55
@JumpLink
JumpLink force-pushed the fix/gnome-51-api-drift branch from 755b6ff to 42c3493 Compare August 29, 2026 07:02
@JumpLink JumpLink changed the title Sync declared API with GNOME Shell 51 Match the declarations to GNOME Shell 51 Aug 29, 2026
GNOME 51 moves event handling off actor vfuncs and onto Clutter actions,
gestures and key binding pools. The shell classes stopped overriding
`vfunc_*_event` and grew signal handlers instead. Those vfuncs still
exist on `Clutter.Actor`, so nothing fails to compile. The declarations
just stopped describing the shell.

Checked against gnome-shell at tag 51.beta, module by module, for every
declared name that changed between 50.4 and 51.beta:

  appDisplay    BaseAppView/AppDisplay._onScroll now takes the
                ScrollController signal arguments; _onKeyPressEvent is a
                binding pool closure
  boxpointer    _muteKeys is a KeyController, _muteInput a ClickGesture
  calendar      vfunc_scroll_event -> _onScroll
  dialog        vfunc_event -> KeyController
  layout        HotCorner.vfunc_leave_event is gone
  messageList   URLHighlighter motion/leave -> MotionController;
                Message.vfunc_key_press_event -> _closeIfAllowed
  messageTray   _onNotificationKeyRelease -> binding pool
  modalDialog   vfunc_captured_event is gone
  search        new exported SearchEntry with activate-new-instance
  slider        scroll/key vfuncs -> _onScroll, _moveLeft, _moveRight
  backlight     SliderItem forwards vfunc_navigate_focus
  volume        _handleScrollEvent -> _onScroll + _handleScroll
  switcherPopup key/scroll vfuncs -> _onKeyPress, _onModifierChange,
                _onScroll
  userWidget    new showAvatar/hideAvatar

Everything added here carries `@version 51`, including the handlers
whose arguments 51 reshaped.
Checking these modules against 51.beta turned up a second group. These
names are absent at 50.4 as well, so gnome-shell dropped them in an
earlier cycle and they describe an API no supported shell has.

  appFavorites  _onFavsChanged
  calendar      _dndSwitch, _dndButton and the DoNotDisturbSwitch class
                behind them (the switch moved to quick settings)
  layout        HotCorner._entered, _onCornerEntered, _onCornerLeft,
                _setupFallbackCornerIfNeeded, _pendingLoadBackground
  messageList   URLHighlighter button press/release vfuncs,
                NotificationMessage._getIcon/_onUpdated,
                MediaMessage._secondaryBin/_closeButton
  messageTray   _onNotificationShow
  popupMenu     _motionEvent, _touchDragging
  search        _onPan
  slider        button press/release and touch vfuncs, startDragging,
                _endDragging, _motionEvent, scroll
  switcherPopup vfunc_button_press_event

Slider gains `step(nSteps)` in the same pass. It replaced
`scroll(event)`, `status/volume` calls it, and it was never declared. It
predates 51, so it carries no `@version` tag.

Only modules that GNOME 51 touched are in scope here. The rest of the
package has more of this; the PR description lists it.
@JumpLink
JumpLink force-pushed the fix/gnome-51-api-drift branch from 42c3493 to 9cf89c9 Compare August 29, 2026 07:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant