Inconsistent behavior when drawing overlapping styled regions

[jwortmann]

This describes a bug discovered in #1585, when drawing multiple styled regions on top of each other, which is caused by a race condition. Sublime Text derives the order how overlapping regions are drawn (via the view.add_regions API method), from the time when the corresponding region key is created the first time in a particular view.

The following minimum example will illustrate this (for actual LSP examples see the screenshots/gif in #1585):

1. Create a new view with some text in it, and paste the following lines into the console:

>>> view.add_regions("filled", [sublime.Region(20, 30)], scope="region.bluish", flags=sublime.DRAW_NO_OUTLINE)
>>> view.add_regions("squiggly", [sublime.Region(10, 40)], scope="region.redish", flags=sublime.DRAW_NO_FILL|sublime.DRAW_NO_OUTLINE|sublime.DRAW_SQUIGGLY_UNDERLINE)

Here everything looks fine and the squiggly underline can be seen on top of the blue background.

2. Now create another new view with some text in it, and use the following commands instead:

>>> view.add_regions("squiggly", [sublime.Region(0, 0)], scope="region.redish", flags=sublime.DRAW_NO_FILL|sublime.DRAW_NO_OUTLINE|sublime.DRAW_SQUIGGLY_UNDERLINE)
>>> view.erase_regions("squiggly")
>>> view.add_regions("filled", [sublime.Region(20, 30)], scope="region.bluish", flags=sublime.DRAW_NO_OUTLINE)
>>> view.add_regions("squiggly", [sublime.Region(10, 40)], scope="region.redish", flags=sublime.DRAW_NO_FILL|sublime.DRAW_NO_OUTLINE|sublime.DRAW_SQUIGGLY_UNDERLINE)

Even thoug "squiggly" is drawn last here, it is now hidden underneath the "filled" region. This happens because the "squiggly" key has been created earlier in this view. It also shows that view.erase_regions will not reset the drawing order of region keys.

This causes inconsisten behavior when there are multiple overlapping region keys in a view, dependent on which of the keys was created first. The bug affects the document highlights when there are some diagnostic regions in a view, for example if diagnostics are reported before the the document highlights feature is used for the first time, the document highlights will always hide the diagnostics if they overlap. And it may also affect #1588 if a language server uses the same diagnostic severity for both diagnostics with tags and diagnostics without tags.

A solution I can think of would add the corresponding region keys for the regions which should always be drawn "on the bottom", whenever a new view gets created (perhaps together with the textDocument/didOpen notification?). A proper implementation regarding the behavior of the document highlights together with diagnostics should include the current user settings for "document_highlight_style" and "diagnostics_highlight_style":

• If document highlights are set to "fill" and (at the same time) diagnostics are not set to "fill", diagnostics should be drawn on the top (i.e. we need to create the document highlight regions key first)
• If document highlights are not set to "fill", or if diagnostics are set to "fill", the document highlight regions should probably be drawn on the top (create all diagnostic regions keys first)

For the diagnostic tag regions (to allow dimmed foreground via a custom color scheme rule) it should be quite simple, just ensure to always create their key(s) first, so that they don't hide the regular underline/squiggly/box for diagnostics. If the diagnostics style is set to "fill", the foreground dimming for the "unnecessary" or "deprecated" tags probably wouldn't be possible with this (I haven't tested).

Another thing to pay attention to is whether the diagnostic tag regions should be on top of the document highlight regions, or not (this would either allow dimmed foreground, or visible document highlights for a single token in a file, but not both at the same time).

[jwortmann]

This should be fixed now, with the correct drawing order being enforced by SessionView._initialize_region_keys().