NSScreens and XRANDR

[sheffler]

PROBLEM: when libxrandr-dev is installed, HAVE_XRANDR is triggered which enables some code that modifies NSWindows to adjust their position when there is a screen change.

The computations seem to not work correctly. One thing I observed is that menus are repositioned partly offscreen because of some of the adjustments.

The problem seems to be in the value of

[NSScreen screens]

When libxrandr-dev is not installed, there is one NSScreen that corresponds to the entire DISPLAY of the Xserver. When libxrandr-dev is installed, one NSScreen per monitor will appear, but their sizes and offsets do not match the output of the shell command xrandr.

DISCUSSION: I believe there are some inconsistencies in the computing of NSScreens (which correspond to monitors) and the XDisplay (which can span the union of a couple of monitors.) The X11 XRANDR extension provides ways to get details about monitor configurations and GS has some support for watching for XRANDR events, but it seems to me that the way in which NSScreens are configured using XRANDR is incorrect.

When libxrandr-dev is installed, an XRANDR event is handled by
libs-back and libs-gui.

Chain of events:

  XGServerEvent.m
    if xEvent is a RANDR event, then
      XRRUpdateConfiguration() // to update the client's X config state
      [NSScreen resetScreens] // destroy existing list of screens
      [NSNotify NSApplicationDidChangeScreenParameters] // tell application 

  in NSWindow.:
    - applicationDidChangeScreenParameters
      - calls [NSScreen screens] which regenerates list

  in NSScreen.m
    - observe [NSScreen screens]
    - put this print statement
        NSLog(@"TOM: SCREENS:%@", screenArray)
      before last line of [NSScreen screens]

  in XGServerWindow.m
    put this print statement
      NSLog(@"TOM: BoundsForScrreen:%@ %@", screen, NSScreenFromRect(boundsRect)
    before last line of boundsForScreen:(int)screen

    NOTE: method screenList in XGServerWindow.m has HAVE_XRANDR code
    that is building an array called monitors[] that is examined
    by boundsForScreen:(int)screen.  So the problem is somewhere in
    that code, I believe.

With those print statements in, I see this traces below.

It seems that the :boundsForScreen:(int)screen method is not correctly accessing screen number N. It seems to be incorrect whether it is called as the result of an xrandr event, OR when it is the initial call in the applicaiton. (This seems to rule out Xevent race conditions in a running program due to the xrandr event updates).

$ openapp SystemPreferences
// initial size of screen is correct - builtin display only
2026-01-03 08:42:31.352 SystemPreferences[59609:59609] TOM: BoundsForScreen:0  {x = 0; y = 0; width = 1920; height = 1080}
2026-01-03 08:42:31.355 SystemPreferences[59609:59609] TOM: SCREENS:("<NSScreen: 0x55c620dc7e48> number: 0 frame: {x = 0; y = 0; width = 1920; height = 1080}")
// enable external 1920x1200 display.  Number of screens seems ok.  Sizes are not.
2026-01-03 08:42:58.937 SystemPreferences[59609:59609] TOM: BoundsForScreen:0  {x = 0; y = 0; width = 1920; height = 1080}
2026-01-03 08:42:58.937 SystemPreferences[59609:59609] TOM: BoundsForScreen:1  {x = 0; y = 0; width = 1920; height = 1080}
2026-01-03 08:42:58.937 SystemPreferences[59609:59609] TOM: SCREENS:("<NSScreen: 0x55c6211b96a8> number: 0 frame: {x = 0; y = 0; width = 1920; height = 1080}", "<NSScreen: 0x55c6213df828> number: 1 frame: {x = 0; y = 0; width = 1920; height = 1080}")
// disable external 1920x1200 display.  width is incorrect.
2026-01-03 08:43:18.582 SystemPreferences[59609:59609] TOM: BoundsForScreen:0  {x = 0; y = 0; width = 3840; height = 1200}
2026-01-03 08:43:18.582 SystemPreferences[59609:59609] TOM: SCREENS:("<NSScreen: 0x55c6213afe48> number: 0 frame: {x = 0; y = 0; width = 3840; height = 1200}")

Here is another test where I start with two monitors and then change them. The initial sizes of the monitors seems incorrect.

$ openapp SystemPreferences
// initial configuration is two screens.  The sizes are not right.
2026-01-03 08:48:33.733 SystemPreferences[59769:59769] TOM: BoundsForScreen:0  {x = 0; y = 0; width = 3840; height = 1200}
2026-01-03 08:48:33.735 SystemPreferences[59769:59769] TOM: BoundsForScreen:1  {x = 0; y = 0; width = 3840; height = 1200}
2026-01-03 08:48:33.735 SystemPreferences[59769:59769] TOM: SCREENS:("<NSScreen: 0x5597821dee28> number: 0 frame: {x = 0; y = 0; width = 3840; height = 1200}", "<NSScreen: 0x5597821f2fb8> number: 1 frame: {x = 0; y = 0; width = 3840; height = 1200}")
// disable one screen.  The remaining builtin display has the correct bounds
2026-01-03 08:48:46.743 SystemPreferences[59769:59769] TOM: BoundsForScreen:0  {x = 0; y = 0; width = 1920; height = 1080}
2026-01-03 08:48:46.744 SystemPreferences[59769:59769] TOM: SCREENS:("<NSScreen: 0x559782815f78> number: 0 frame: {x = 0; y = 0; width = 1920; height = 1080}")
// enable the external 1920x1200 display.  things are strange.
2026-01-03 08:49:12.119 SystemPreferences[59769:59769] TOM: BoundsForScreen:0  {x = 0; y = 0; width = 3840; height = 1200}
2026-01-03 08:49:12.119 SystemPreferences[59769:59769] TOM: BoundsForScreen:1  {x = 0; y = 0; width = 3840; height = 1200}
2026-01-03 08:49:12.120 SystemPreferences[59769:59769] TOM: SCREENS:("<NSScreen: 0x55978278b9b8> number: 0 frame: {x = 0; y = 0; width = 3840; height = 1200}", "<NSScreen: 0x5597827f1e58> number: 1 frame: {x = 0; y = 0; width = 3840; height = 1200}")
// disable the external display.  The remaining builtin display is correct
2026-01-03 08:49:24.248 SystemPreferences[59769:59769] TOM: BoundsForScreen:0  {x = 0; y = 0; width = 1920; height = 1080}
2026-01-03 08:49:24.248 SystemPreferences[59769:59769] TOM: SCREENS:("<NSScreen: 0x559782774f78> number: 0 frame: {x = 0; y = 0; width = 1920; height = 1080}")

If I revert to no Xrandr support by removing and rebuilding

$ sudo apt remove libxrandr-dev
 $ cd libs-back
 $ make
 $ sudo -E make install

and recompile libs-back, a simpler behavior is implemented. In this case there
is always just one "screen", and its size represents the size of the X11 "Display"
which is the union of the monitors areas. Using arandr to change the displays
has no effect on the running program.

// both monitors are enabled.  start the program
$ openapp SystemPreferences
2026-01-03 09:17:47.975 SystemPreferences[64810:64810] TOM: BoundsForScreen:0  {x = 0; y = 0; width = 3840; height = 1200}
2026-01-03 09:17:47.975 SystemPreferences[64810:64810] TOM: SCREENS:("<NSScreen: 0x5631f62b96c8> number: 0 frame: {x = 0; y = 0; width = 3840; height = 1200}")

// only one monitor is enabled.  start the program.
$ openapp SystemPreferences
2026-01-03 09:18:30.651 SystemPreferences[64883:64883] TOM: BoundsForScreen:0  {x = 0; y = 0; width = 1920; height = 1080}
2026-01-03 09:18:30.652 SystemPreferences[64883:64883] TOM: SCREENS:("<NSScreen: 0x55a419ee96c8> number: 0 frame: {x = 0; y = 0; width = 1920; height = 1080}")

The program arandr was used to alter the screen setup between these two configures.

[sheffler]

Also attached is a screenshot showing how the Menu in the top-left is shifted offscreen after a changing the size to two monitors and back to one. There is no easy way to grab the menu and reposition since its title bar is offscreen.

[sheffler]

@rfm - I investigated this some more and have some information to share regarding multiple monitors, screens and _NET_WORKAREA.

On my system, using xfwm4 as the window manager, the window manager defaults to providing 4 workspaces. This is reflected in the _NET_WORKAREA having four copies of the entire X display area.

If there is one 1920x1080 monitor the _NET_WORKAREA is
(0, 0, 1920, 1080), (0, 0, 1920, 1080), (0, 0, 1920, 1080), (0, 0, 1920, 1080),

When a second monitor of size 1920x1200 is added, the Xdisplay size is 3840x1200 and _NET_WORKAREA becomes
(0, 0, 3840, 1200), (0, 0, 3840, 1200), (0, 0, 3840, 1200), (0, 0, 3840, 1200),

Now, when HAVE_XRANDR is enabled, libs-back and libs-gui try to map each monitor to an NSScreen. in XGServerWIndow method screenList this line

    		  if ([workAreas count] > mi)

has the effect of mapping an NSScreen[1] to _NET_WORKAREA[1], which is the 2nd copy of the XDisplay of size (0,0,3840,1200) instead of the second monitor with offset and size (1920,0,1920,1200)

turning the line above into

                 if (false) 

fixes the NSScreen size issue when HAVE_XRANDR.

The other thing is the applicationDidChangeScreenParameters callback in NSWindow. There are some computations that translate or move the origin and size of each window when the screens change. I'm not sure all of this works correctly. The new window position does not always put menus in the right place. Also, I believe applying a new frame has the effect of destroying the cached bitmaps of icons and they simply dissappear. GWorkspace folder icons simply become blank after a screen change.

I've modified this method to simply return and while there are minor positioning things with menus, at least the icons in GWorkspace and SystemPreferences do not dissappear.

Hope this helps. I'm not an expert on X11 and this info is just what i've been observing.

- (void) applicationDidChangeScreenParameters: (NSNotification *)aNotif
{
  NSRect       oldScreenFrame = [_screen frame];
  int          screenNumber = [_screen screenNumber];
  NSRect       newScreenFrame;
  NSRect       newFrame;
  NSEnumerator *e;
  NSScreen     *scr;

  // We need to get new screen from renewed screen list because
  // [NSScreen mainScreen] returns NSScreen object of key window and that object
  // will never be released.
  e = [[NSScreen screens] objectEnumerator];
  while ((scr = [e nextObject]))
    {
      if ([scr screenNumber] == screenNumber)
        {
          ASSIGN(_screen, scr);
          break;
        }
    }

  return;  // JUST RETURN HERE

  // SKIP all of the following CODE
}

[sheffler]

More info: if I log the class of 'self' in the applicaitonDidChangeScreenParameters, I see the following classes

• NSIconWindow
• NSWindow
• NSMenuPanel (many)
• GSCacheW (many)

As an experiment, suspecting an issue with caching of bitmaps when a new frame is set on a GSCacheW, I suppressed it

   if ([[self className] isEqualToString:@"GSCacheW"]])
     {
         NSLog(@"ignoring %@", [self class]);
          return;
      }

and the icons in GWorkspace and SystemPreferences seem to survive when the NSScreen of the app is removed and the app moves to Screen0.

[sheffler]

FYI - here is what it looks like when the icons disappear (without the fix above). Procedure:

• add a second monitor
• drag GWorkspace there
• disable the second monitor

The icons in GWorkspace File Viewer are gone.

[rfm]

I added a small change to NSCachedImageRep.m in the gui library, to have the off-screen windows used for image caching ignore the screen changes (as far as I can see, the cached info in an off-screen window should be unaffected by a screen change).

I'm not an X11 expert by any means (I wrote some GNUstep X11 code 20 or 30 years ago, and have basically never used it since then), and I don't have two monitors to play with, but I've read up on this.

It seems that there's no good way to deal with avoiding window-manager reserved spaces on a multi-monitor system. That's because the _NET_WORKAREA property provided by the window manager does not provide information about available space on any particular monitor, only about the available space on the composite display made up of all the monitors. If there is only one monitor, it works, and if the base library doesn't have XRANDR (so sees the collection of monitors as a single monitor), it works.

I changed the code to be aware of this, and to not try to use work area information if the library knows about more than one monitor. That seems about the best we can do at the moment: where we know about multiple monitors we act as if the entire monitor is available to display on, and if we only know about one monitor then we display into the space that the window manager tells us is available.

As far as I can see the only way to fix this correctly for a multi monitor setup would be to add code to gnustep-back to duplicate the work that a window-manager does to calculate the usable area of each monitor using the monitor layout information from XRANDR (so you know where each monitor is within the composite display) and the _NET_WM_STRUT_PARTIAL (or _NET_WM_STRUT if _NET_WM_STRUT_PARTIAL is not set) information for each window (saying where that window has reserved space within the composite display). I can't realistically work on that, but if you could calculate the used parts of each monitor, you could then calculate the usable rectangle within that monitor, and use it to set the size of each NSScreen so that things could be correctly positioned within each monitor.

[rfm]

On further reading, I wonder if the issue is not more fundamental than that. Since modern window manager interaction seems to be based around virtual workspaces, perhaps the best solution is to change what we mean by an NSScreen. At the moment it tries to correspond to a physical monitor but it should perhaps correspond to a virtual workspace instead, at least from the point of view of understanding screen dimensions and where a window appears on a screen?

[rfm]

No, looking at the NSScreen API, it's clearly the physical monitor, which seems to mean that there's really no Cocoa equivalent of the X workspace :-(

[sheffler]

A followup:

• the change to NSCachedImageRep.m seems to fix the "disappearing icons" problem

I"ve ended up with some minimal changes that seem to be working pretty well with the set up I have. I wanted to be able to dock and use two monitors, and undock and set the built-in display only. The original problem was that when the 2nd monitor was removed, windows and menus would end up off-screen. I could grab the windows with the window-manager, but the menus would end up unreachable.

Attaching the two fixes that seem to help. First, an NSScreen (i think) should correspond to a monitor and its position in the X-display space. So on my system the two monitors end up
(0, 0, 1920, 1080) (1920, 0, 1920,1200)
when the second monitor is removed, there should be one NSScreen and windows should be moved back to that
(0, 0, 1920,1080)

(this is without any NET_WORKAREA space reservation for a menu bar, etc. So that capability might need work)

Attached are the two methods I changed.

• in XGServerEvent.m I eliminated the 2nd NSScreen getting the bounds 2nd work area (see the TOM: 2026-01-11 comment)
• in NSWindow.m, ensure that when applicationDidChangeScreenParameters, that every window finds a new valid NSScreen. Problem was, if the old NSScreen was the 2nd monitor (with frame (1920,0,1920,1200)) the menu wouldn't be given a new NSScreen with frame (0,0,1920,1080) and it would end up off screen and strangely offset. (see the TOM: comment)

Hope this helps someone else. I think it needs more testing.

/**** file: XGServerWindow.m ****/


/* This method assumes that we deal with one X11 screen - `defScreen`.
   Basically it means that we have DISPLAY variable set to `:0.0`.
   Where both digits have artbitrary values, but it defines once on
   every application run.
   AppKit and X11 use the same term "screen" with different meaning:
   AppKit Screen - single monitor/display device.
   X11 Screen - it's a plane where X Server can draw on.
   XRandR - Xorg extension that helps to manipulate monitor layout providing
   X11 Screen. 
   We map XRandR monitors (outputs) to NSScreen. */
- (NSArray *)screenList
{
  Window        root = [self xDisplayRootWindow];
  NSArray	*workAreas = _workAreas(dpy, root);
  xScreenSize = _screenSize(dpy, defScreen);

  monitorsCount = 0;
  if (monitors != NULL)
    {
      NSZoneFree([self zone], monitors);
      monitors = NULL;
    }
  
#ifdef HAVE_XRANDR
  XRRScreenResources *screen_res = XRRGetScreenResources(dpy, root);

  if (screen_res != NULL)
    {
      monitorsCount = screen_res->noutput;
      if (monitorsCount != 0)
        {
          int             i;
          int             mi;
          NSMutableArray *tmpScreens;
          RROutput        primary_output = XRRGetOutputPrimary(dpy, root);

          tmpScreens = [NSMutableArray arrayWithCapacity: monitorsCount];

          monitors = NSZoneMalloc([self zone],
	    monitorsCount * sizeof(MonitorDevice));

          for (i = 0, mi = 0; i < screen_res->noutput; i++)
            {
              XRROutputInfo *output_info;
              
              output_info = XRRGetOutputInfo(dpy,
		screen_res, screen_res->outputs[i]);
              if (output_info->crtc)
                {
                  XRRCrtcInfo *crtc_info;
                  
                  crtc_info = XRRGetCrtcInfo(dpy,
		    screen_res, output_info->crtc);

                  monitors[mi].screen_id = defScreen;
                  monitors[mi].depth = [self windowDepthForScreen: mi];
                  monitors[mi].resolution
		    = [self resolutionForScreen: defScreen];
		  // TOM: 2026-01-11 - an NSScreen corresponds
		  // to a monitor and its position in X-display space
		  // if ([workAreas count] > mi)
		  if (0)
		    {
		      monitors[mi].frame = 
			[[workAreas objectAtIndex: mi] rectValue];
		    }
		  else
		    {
		      /* Transform coordinates from Xlib (flipped)
		       * to OpenStep (unflipped). 
		       * Windows and screens should have the same
		       * coordinate system.
		       */
		      monitors[mi].frame =
			NSMakeRect(crtc_info->x,
			  xScreenSize.height - crtc_info->height - crtc_info->y,
			  crtc_info->width,
			  crtc_info->height);
		    }
                  /* Add monitor ID (index in monitors array).
                   * Put primary monitor ID at index 0 since
		   * NSScreen gets this as main screen if application
		   * has no key window.
		   */
                  if (screen_res->outputs[i] == primary_output)
                    {
                      [tmpScreens insertObject: [NSNumber numberWithInt: mi]
				       atIndex: 0];
                    }
                  else
                    {
                      [tmpScreens addObject: [NSNumber numberWithInt: mi]];
                    }
                  XRRFreeCrtcInfo(crtc_info);
                  mi++;
                }
              XRRFreeOutputInfo(output_info);
            }

          monitorsCount = mi;
          if (monitorsCount != 0)
            {
              XRRFreeScreenResources(screen_res);
              return [NSArray arrayWithArray: tmpScreens];
            }
          else
            {
              NSZoneFree([self zone], monitors);
              monitors = NULL;
            }
        }
      XRRFreeScreenResources(screen_res);
    }
#endif

  /* It is assumed that there is always only one screen per application. 
     We only need to know its number and it was saved in _initXContext as
     `defScreen`. */
  monitorsCount = 1;
  monitors = NSZoneMalloc([self zone], sizeof(MonitorDevice));
  monitors[0].screen_id = defScreen;
  monitors[0].depth = [self windowDepthForScreen: 0];
  monitors[0].resolution = [self resolutionForScreen: defScreen];
  monitors[0].frame = NSMakeRect(0, 0, xScreenSize.width, xScreenSize.height);

  if ([workAreas count] > 0)
    {
      monitors[0].frame = [[workAreas firstObject] rectValue];
    }
  return [NSArray arrayWithObject: [NSNumber numberWithInt: defScreen]];
}


/*** file: NSWindow.m ****/

- (void) applicationDidChangeScreenParameters: (NSNotification *)aNotif
{
  NSRect       oldScreenFrame = [_screen frame];
  int          screenNumber = [_screen screenNumber];
  NSRect       newScreenFrame;
  NSRect       newFrame;
  NSEnumerator *e;
  NSScreen     *scr;

  // We need to get new screen from renewed screen list because
  // [NSScreen mainScreen] returns NSScreen object of key window and that object
  // will never be released.
#if 0 // TOM: possible bug. when old screen is removed, needs to find a new one
  e = [[NSScreen screens] objectEnumerator];
  while ((scr = [e nextObject]))
    {
      if ([scr screenNumber] == screenNumber)
        {
          ASSIGN(_screen, scr);
          break;
        }
    }
#else
  NSScreen *found = nil;
  e = [[NSScreen screens] objectEnumerator];
  while ((scr = [e nextObject]))
    {
      if ([scr screenNumber] == screenNumber)
	{
	  found = scr;
	  break;
	}
    }
  if (found == nil)
    found = [[NSScreen screens] objectAtIndex:0];
  ASSIGN(_screen, found);    
#endif

  // Do not adjust frame for mini and appicon windows - it's a WM's job.
  if ([self isKindOfClass: [NSMiniWindow class]] || self == [NSApp iconWindow])
    {
      return;
    }

  newScreenFrame = [_screen frame];
  newFrame = _frame;
  // Screen Y origin change.
  newFrame.origin.y += newScreenFrame.origin.y - oldScreenFrame.origin.y;
  // Screen height change.
  newFrame.origin.y += newScreenFrame.size.height - oldScreenFrame.size.height;
  // Screen X origin change. Screen width change shouldn't affect our frame.
  newFrame.origin.x += newScreenFrame.origin.x - oldScreenFrame.origin.x;

  /* Call backend's `placewindow::` directly because our origin in OpenStep
     coordinates might be unchanged and `setFrame:display:` has check
     for it. */
  [self _applyFrame: newFrame];
  [self display];

  if (_autosaveName != nil)
    {
      [self saveFrameUsingName: _autosaveName];
    }
}