After an evaluation, GNOME has moved from Bugzilla to GitLab. Learn more about GitLab.
No new issues can be reported in GNOME Bugzilla anymore.
To report an issue in a GNOME project, go to GNOME GitLab.
Do not go to GNOME Gitlab for: Bluefish, Doxygen, GnuCash, GStreamer, java-gnome, LDTP, NetworkManager, Tomboy.
Bug 778791 - Disable client side decorations (GTK_CSD) by default on Windows (win32)
Disable client side decorations (GTK_CSD) by default on Windows (win32)
Product: gtk+
Classification: Platform
Component: .General
Other Windows
: Normal normal
: ---
Assigned To: gtk-bugs
: 788291 (view as bug list)
Depends on:
Reported: 2017-02-16 20:11 UTC by Eduard Braun
Modified: 2018-05-02 18:07 UTC
See Also:
GNOME target: ---
GNOME version: ---

docs: gtk/running: Document the GTK_CSD env var (1.31 KB, patch)
2017-08-04 12:01 UTC, Daniel Boles
committed Details | Review
gtkwindow: Don't force enable CSD under Windows (985 bytes, patch)
2017-10-03 22:16 UTC, Christoph Reiter (lazka)
none Details | Review

Description Eduard Braun 2017-02-16 20:11:01 UTC
On Windows GTK3 windows look like aliens because they currently use client side decorations by default.

Even with the "win32" theme (which tries to emulate something Windows-7'ish but does not have transparent borders) it won't even blend in on Windows 7, let alone any other version of Windows.

Therefore I strongly suggest to disable GTK_CSD by deault on Windows which already makes applications using the Adwaita theme look more native than the "win32" theme does.
Comment 1 Eduard Braun 2017-02-16 20:17:10 UTC
See also for screenshots and additional information.

(I filed that first and only learned about the GTK_CSD environment variable there as it seems widely unknown/undocumented otherwise.
Comment 2 Eduard Braun 2017-02-18 13:00:17 UTC
I just found bug 759899 which was in fact about making CSD the default on Windows.

However I have to disagree with that decision:
The unwanted "mix of CSD and non-CSD windows" which was the reasoning to enable it by default is (in my opinion) still preferable to making every GTK app look like an alien consistently.

Unless CSD can be fixed to use native theming to draw borders and titlebars on Windows it's not a good default.
Comment 3 LRN 2017-02-18 13:37:08 UTC
CSD only affects window decorations. Even if you make CSD disabled by default, widgets will *still* use Adwaita, which is the default theme.

If it's just about looks, maybe writing (and maintaining) a more windowsly-looking theme will be a better solution?

There were attempts to leverage Windows Theming API to make a GTK theme that looked like Windows, but Windows theming went a different way - first was the Windows 7 glass border thingy that was *not* covered by Theming API, then Windows 10 changed it again (and again, you can't access that look via Theming API).

So right now the best way, IMO, to make GTK applications look windowsly is to just write a windowsly theme from scratch. For Windows 10 that is definitely doable, as it dropped the fancy decorations that Windows 7 had, and stopped using gradients everywhere.

Would you be willing to write and maintain such a theme?
Comment 4 Eduard Braun 2017-02-18 13:59:41 UTC
Sorry, but that's the typical (unhelpful) "If you don't like it do it yourself" answer.

You're certainly right that a proper native Windows theme supporting CSD would be the ideal case. But as you write yourself that's hard to do at best even if you don't intend to support all versions of Windows. I certainly don't have the skills to do it.

So, why let's not work with what we have to find a *workable* solution until somebody with the necessary skills has the time to create an *ideal* solution instead of sticking with a *bad* solution?
- With "GTK_CSD=0" the OS draws window decorations for us! As a result they'll always match perfectly (and also some other issues will be solved). One big issue done!
- With "gtk-theme-name=win32" we have a theme that offers at least something close to a native Windows look. People can easily use it to replace Adwaita where necessary. (It's not good enough to be the default, though, i.e. many labels are off, spinners have strange sizes, etc.). But all that can be relatively easy fixed in CSS (in contrast to window decorations!)

In combination we'd end up with a look and feel that is so close to native windows that it would be a fine solution for most GTK applications!

The few applications that actually require "GTK_CSD=1" can continue to do so (nothing will change for them!) until a point in the future where hopefully an ideal solution is found.
Comment 5 LRN 2017-02-18 14:24:24 UTC
I have exactly the same opinion, only on the opposite side.

Adwaita is well-done and is actually maintained, and unless someone makes Windows-specific theme, Adwaita is going to remain the *best* theme we have, so IMO we should keep using it by default.

It doesn't look very windowsly, sure, but between Microsoft changing Windows UI looks every two versions and proprietary software developers trying to show off by giving their applications "unique" themes and UI elements, Windows became kind of a zoo. So i've decided to work with what we have and just stick to Adwaita.

Windows 10 window decorations can be relatively easy implemented in CSS (in contrast to widgets, which always looked somewhat off, no matter how much i've fiddled with their theme; that said, that was back in Windows 7 days, maybe for 10 it'll be easier).
Comment 6 Alexander Shaduri 2017-06-15 13:25:27 UTC
Just my 2 cents:

Shipping a GTK+-based application under Windows, I'd like it to at least try to blend with native windows.
Right now this is achievable by using gtk-theme-name=win32.

However, the ugly win7-looking client-side decorations under Windows 10 look really weird. Especially when combined with GtkFileChooserNative, which has proper Windows 10 decorations.

Note that I do NOT want to use Adwaita, since it makes the UI look too alien under Windows. gtk-theme-name=win32 makes it close enough.

My application was recently ported from gtk2 to gtk3, so this is a release blocker for me, if you consider that the gtk2 version looks quite fine compared to this alien thing.

Please disable client-side windows by default.
Comment 7 Daniel Boles 2017-08-04 11:48:06 UTC
(In reply to LRN from comment #5)
> I have exactly the same opinion, only on the opposite side.
> [...]
> So i've decided to work with what we have and
> just stick to Adwaita.

Right. I seem to be one of the only people who _likes_ how GTK+ makes my program look identical across OSes! I see the other side about wanting the ability to blend with native toolkits, but... maybe it's just the fact that my application has a lot of custom CSS; I can't imagine having to support that across multiple different themes for different OSes, and I don't want to, so I force Adwaita:dark. Maybe I'm in the minority on that /shrug

> Windows 10 window decorations can be relatively easy implemented in CSS (in
> contrast to widgets, which always looked somewhat off, no matter how much
> i've fiddled with their theme; that said, that was back in Windows 7 days,
> maybe for 10 it'll be easier).

I was thinking about this the other day. Windows 10 will (if you believe MS) not change much in more fundamental areas like this, as nor will GTK+ 3 theming (finally!), so the time is right to start developing a Windows 10 style theme, and I think it could probably get very close indeed.

However, while I enjoy using GTK+ and CSS a lot, and am now using SASS in my own application, I'm not sure I like it enough to be the one who develops the theme. I'll just try my hardest not to idly start sketching out ideas some weekend, and end up falling completely down the rabbit hole. :S
Comment 8 Daniel Boles 2017-08-04 12:01:56 UTC
Created attachment 356939 [details] [review]
docs: gtk/running: Document the GTK_CSD env var

(In reply to Eduard Braun from comment #1)
> See also for
> screenshots and additional information.
> (I filed that first and only learned about the GTK_CSD environment variable
> there as it seems widely unknown/undocumented otherwise.

    docs: gtk/running: Document the GTK_CSD env var

    It was not documented before.
Comment 9 Eduard Braun 2017-08-06 15:13:17 UTC
Another argument for disabling client side decorations:
A lot of work was put recently into implementing GtkFileChooserNative.
Now that we finally have native file pickers (that look native!) we don't have a native looking applications anymore (with GTK_CSD=1)!

As a result we now even introduce inconsistencies inside one and the same applications, so the consistency arguments starts to crumble...
Comment 10 Eduard Braun 2017-08-06 15:17:54 UTC
While I still feel we should aim at providing a native look, I'm afraid this is currently blocked by bug 781153.

There's not much point in having a native look if it means performance goes down the drain :-/
Comment 11 Daniel Boles 2017-08-06 15:25:16 UTC
Review of attachment 356939 [details] [review]:

notes for when I'm not on a struggling netbook

::: docs/reference/gtk/running.sgml
@@ +522,3 @@
+    disables the default use of client-side decorations on GTK+ windows, thus
+    making the window manager responsible for drawing the decorations of
+    windows using the default titlebar that are opened by affected processes.

This should probably be "without a custom titlebar widget", and "by affected processes" is redundant in a discussion of environment variables, where it should be assumed that people get that idea.

@@ +526,3 @@
+  <para>
+    Windows whose titlebar is set to a GtkHeaderBar will be set to CSD, as they
+    disables the default use of client-side decorations on GTK+ windows, thus

This should refer to 'Windows with a custom titlebar widget' rather than HeaderBar specifically, as set_titlebar() takes a GtkWidget*, not a GtkHeaderBar*.
Comment 12 Eduard Braun 2017-08-06 16:11:23 UTC
Examples on how "GTK_CSD=1" causes a lot of trouble in practice and (IMHO) causes more issues than it solves:
- bug 785886
- bug 785887
- bug 785888
- bug 763013 (now closed, with "only" 1860 lines of code)

If I'm not mistaken all functionality that would be natively provided by the Window manager is broken by "GTK_CSD=1" and if we want to support something similar we have to duplicate it in custom code.

In my opinion this does sound like a very bad approach as a custom implementation will
a) always be lacking (see the open bugs for examples)
b) will (even in the ideal case still) still feel non-native:
   the functionality implemented by LRN, while appreciated,
   still looks completely different to the native implementation
c) is fragile by definition. It might introduce bugs and is likely
   to break at will in future versions of Windows.
   Incompatibilities between different versions are likely

Comment 13 Daniel Boles 2017-08-06 16:45:24 UTC
Comment on attachment 356939 [details] [review]
docs: gtk/running: Document the GTK_CSD env var

pushed with tweaks as
Comment 14 Eduard Braun 2017-08-06 16:48:33 UTC
Thanks for documenting this Daniel!

Another issue with CSD windows: bug 785892
Comment 15 LRN 2017-08-06 17:56:26 UTC
It might be possible to do CSD without completely dropping normal window decorations, by painting over them (and being creative with client-area indicators). However, that will take a lot of research and prototyping, and then, if that pays off, someone will have to apply that to GDK. That is not trivial.

Secondly, as you've noticed, the use of layered windows provides (unintended?) performance boost (or maybe non-layered-painting code is just slow by itself - it's difficult for me to tell). So, apart from figuring out non-client-area drawing, someone will have to ensure that everything is painted optimally.

Thirdly, the use of layered windows fixes the decorations/content drawing mismatch, which causes painting glitches when a window is moved and resized simultaneously (i.e. when dragging at its left, top, bottom-left, top-left or top-right edge). I've tried to do that without using layered windows, and failed. It might still be possible to do this by some other means, but these "other means" remain elusive so far. One possibility that i have not explored is to hijack the WM_WINDOWPOSCHANGING message, and just postpone any size changes until the new window contents are redrawn. Again, this requires research.
Comment 16 Emmanuele Bassi (:ebassi) 2017-09-28 12:52:33 UTC
*** Bug 788291 has been marked as a duplicate of this bug. ***
Comment 17 Christoph Reiter (lazka) 2017-10-03 22:16:48 UTC
Created attachment 360886 [details] [review]
gtkwindow: Don't force enable CSD under Windows
Comment 18 Luis Menina 2017-10-18 14:59:40 UTC
So, the patch from comment 16 disabling CSD by default has landed on MSYS2, which is the preferred way to get GTK.

What do we do now that the default shipping channel starts shipping non-blessed changes? This issue should get more feedback from GTK maintainers and have an "official" position from the project.

Either GTK apps should look the same across platforms (which has been the choice until now), or try to follow more closely the native UI. This includes CSD but also the default theme.

If the developers and/or users prefer consistency across platform, then an extra effort should be done on the documentation so that Windows developers that want a closest-to-native UI can easily find how to do it. This is free software, so MSYS2 developers are free to patch, but I don't like the idea of diverging from upstream. This should be sorted out by both communities.

However disabling by default CSD opens a can of worms with new bugs, from window sizing/positionning (bug 785892) to performance (bug 781153), so I think that for the moment this is not ready enough to become the default on MSYS, and should be reverted.

@ebassi: could we have some sort of official statement from the GTK maintainers so this stops popping up from time to time?
Comment 19 Emmanuele Bassi (:ebassi) 2017-10-18 15:27:22 UTC
(In reply to Luis Menina from comment #18)

> @ebassi: could we have some sort of official statement from the GTK
> maintainers so this stops popping up from time to time?

I'm not entirely sure why I'm being singled out, but as far as I'm concerned the official stance of the GTK project is what we encode in our git repository. If downstream distributors decide to ship a patched version of GTK it's entirely in their power to do so — after all, Linux distributors do this all the time. Of course, if a downstream distributor decides to patch GTK, they also get to pick up the pieces when something breaks, and upstream reserves the right to close bugs caused by downstream patches.
Comment 20 Luis Menina 2017-10-18 15:30:53 UTC
@ebassi: you were single out cause you werealready in the bug and usually make strong statements ;). But I'm on #gtk+ right now to try to sort things out too with other people.
Comment 21 Eduard Braun 2017-10-18 15:37:04 UTC
@Luis: The first bug you cited above is actually an argument for *disabling* CSD and IMHO CSD windows are the can of worms we should avoid, see issues linked above (especially comment 12).

The only issue with non-CSD windows I'm aware of is the performance issue, which we should aim at fixing either way.
Comment 22 Daniel Boles 2018-03-18 12:09:40 UTC
See the proposal in, which by my understanding would mean we'd always have to use CSD, but would also fix a number of the cited problems with CSD around the lack of AeroSnap.
Comment 23 GNOME Infrastructure Team 2018-05-02 18:07:03 UTC
-- GitLab Migration Automatic Message --

This bug has been migrated to GNOME's GitLab instance and has been closed from further activity.

You can subscribe and participate further through the new bug through this link to our GitLab instance: