Scinterm 5.5: How to access the initialized color pairs?

[rhaberkorn]

Beginning with Scinterm 5.5 you are initializing color pairs on demand. How are you supposed to make use of these pairs from the code that embeds Scinterm? Do you rely on including PlatCurses.h - effectively requiring C++ - or are you supposed to initialize new color pairs independently of Scinterm?

[rhaberkorn]

I also see another disadvantage with the current implementation of "true RGB": If you do really use arbitrary RGB values you could easily "hit" one of the special RGB values that map to the predefined curses colors. These are again palletized by the terminal emulator and usually will not correspond to their special Scinterm RGB values. Ie. using 0x0000FF will usually not give you that exact RGB value, which may be an issue if the value is calculated or a direct user input.

Perhaps full RGB support should be a configurable feauture. If enabled, you should always initialize all colors to their exact RGB values. If disabled, you could retain the old pre-5.5 algorithm for initializing the color pairs.

[orbitalquark]

Beginning with Scinterm 5.5 you are initializing color pairs on demand. How are you supposed to make use of these pairs from the code that embeds Scinterm? Do you rely on including PlatCurses.h - effectively requiring C++ - or are you supposed to initialize new color pairs independently of Scinterm?

That's a good point. Do you think there is any value in exposing Scinterm's color definitions to the embedding application? Otherwise, we could perhaps define an "offset" C API to have Scinterm start defining its colors at a particular color pair number, and the application can define and use any prior numbers for itself.

I also see another disadvantage with the current implementation of "true RGB": If you do really use arbitrary RGB values you could easily "hit" one of the special RGB values that map to the predefined curses colors. These are again palletized by the terminal emulator and usually will not correspond to their special Scinterm RGB values. Ie. using 0x0000FF will usually not give you that exact RGB value, which may be an issue if the value is calculated or a direct user input.

Maybe we need another API to "unset" the predefined curses colors, or at least ignore them if the user intends to use RGB.

[rhaberkorn]

It's sad that Scintilla discards the most significant byte from RGB values. Otherwise we could use it to cleanly separate the "true" RGB space from the "placeholder" color palette values. Alpha also cannot be set everywhere.

The only solution I see is exposing an API function to enable "true" RGB colors. If enabled all RGB values are used to initialize new colors. If disabled, you can only use the predefined placeholder values which will be mapped to the 16 color palette. In this case, you could also initialize the color pairs just like you did in v5.4. So yeah, by default true RGB values should be disabled and behavior should be largely v5.4 compatible (using only predefined colors).

[orbitalquark]

That's why I would strongly suggest to either optionally preserve the pre-v5.5 behavior with regards to color pair allocation or to expose Colors::get() and Colors::Pair() as C functions. If I had the latter, I could easily query the existing pairs and register new ones on demand.

I cannot expose those functions in C because ColourRGBA is a C++ construct. Should I declare an API that accepts ints in 0xBBGGRR notation and returns short color numbers/pairs? That doesn't feel right to me.

I also don't see the point in scintilla_set_color_offsets(). If I know that the range from 0 to the offset is sufficient for my own needs, I might assume that Scinterm will also be fine with the same range. So I can let it allocate beginning with 0 and allocate my own colors and pairs beginning at the offset. I.e. I would just init_pair() beginning with 128.

My thought was that users ought to know what colors they want to use ahead of time in their application. They set aside those colors/pairs and tell Scinterm what is available via this new function.

I don't think applications should rely on using colors Scinterm allocates. As you point out later, Scinterm could theoretically run out of colors. If I choose to "recycle" older colors (e.g. ring buffer-type of structure), then applications using Scinterm-allocated colors/pairs could experience unexpected changes.

I'm not sure how to proceed given all of this feedback.

[rhaberkorn]

I don't think applications should rely on using colors Scinterm allocates. As you point out later, Scinterm could theoretically run out of colors. If I choose to "recycle" older colors (e.g. ring buffer-type of structure), then applications using Scinterm-allocated colors/pairs could experience unexpected changes.

I'm not sure how to proceed given all of this feedback.

Well, I think that #32 should be pretty uncontroversial. Unrelated, but I also commented in #22 in how we could get underlined text via indicators.

You could leave scintilla_set_color_offsets() if you think there is a need (but I still don't see it). Forget about my proposal to expose Color::get() and Color::Pair().

But the RGB "true" vs "placeholder" values is a problem we definitely still need to tackle. I suggest to make this a settings, exposed via the C API and provide pre-allocate the 256 color pairs for the 16 builtin colors when "true" RGB mode is disabled. Let's say scintilla_set_rgb_mode().

Alternatively you might just want to omit the 16 predefined colors from the map, so you will never accidentally use one of the builtin colors but always only the actual RGB values. In this case, the function might be called for instance scintilla_use_builtin_colors().

[orbitalquark]

Okay, I will keep the scintilla_set_color_offsets() from the proposal, and think about an API for enabling/disabling true RGB mode.

[orbitalquark]

I've opened #34 with a new function scintilla_disable_color_palette(). I did some basic testing and it seems to work as expected, but I don't have as much experience developing terminal apps as you do, so perhaps you'd like to take a look before I commit it for good. We can also continue the discussion there if you think this thread is getting too long or off-topic.