Corrected description of PrinterSettings.SupportsColor property

[Tanya-Solyanik]

Summary

• Corrected description of PrinterSettings.SupportsColor property.
• added a CS code snippet that demonstrates how to obtain a correct value using PInvoke

Things to finish:

• VB sample
• CPP sample
• differentiate between framework versions where this issue is fixed and the ones where it's not. It will be fixed in .NET Core 5.0 only. See issue PrinterSettings.SupportsColor should use DeviceCapabilities(DC_COLORDEVICE) instead of GetDeviceCaps(BITSPIXEL). runtime#34630

I'm looking for help with the third remaining checkbox. And I'm looking for guidance on how do we document APIs that just don't do what they were supposed to be doing. Thanks!

Fixes #4083

[carlossanlop]

So far it looks good to me.
You can view your changes here: https://review.docs.microsoft.com/en-us/dotnet/api/system.drawing.printing.printersettings.supportscolor?view=dotnet-plat-ext-3.1&branch=pr-en-us-4087
In case you don't yet know how I got that link:

• Click on "Details" in the OpenPublishing.Build leg of your CI
• Scroll down to the bottom of the report
• In the "Validated Files" table, click on the Preview URL, then navigate to the API you modified (PrinterSettings.SupportsColor).

[BillWagner]

@Tanya-Solyanik Will you come back to work on this, or should we close it?

[Tanya-Solyanik]

@BillWagner , I'll get back to it this week.

[RussKie]

@gewarren is there a preferred way of wording? I think in the last couple of PRs you worded it something like this:

Suggested change

	<summary>On .NET Frameworks 1.1 to 4.8, .NET Core framework versions 3.1 and 3.0, and on .NET Framework Extensions 2.1 to 3.1, gets a value indicating whether this printer uses multiple adjacent color bits for each pixel. This value does not guarantee if this printer supports color.<br/>
	On .NET 5, gets a value indicating whether this printer supports color printing.</summary>
	<summary>In all .NET Framework and .NET Core versions, and in .NET Framework Extensions 2.1 to 3.1 gets a value indicating whether this printer uses multiple adjacent color bits for each pixel. This value does not guarantee if this printer supports color.<br/>
	Starting .NET 5 gets a value indicating whether this printer supports color printing.</summary>

[gewarren]

@RussKie I left a suggestion for how I would work it. I usually using the "Starting in version x..." verbiage in the breaking change docs, but not so much in the API ref docs.

[gewarren]

Suggested change

	On Framework version below .NET 5, to determine if the printer supports color, P/Invoke [DeviceCapabilitiesW](https://docs.microsoft.com/en-us/windows/win32/api/wingdi/nf-wingdi-devicecapabilitiesw) function​ with `DC_COLORDEVICE` capability.<br/>
	On .NET versions prior to .NET 5, to determine if the printer supports color, use P/Invoke to invoke the [DeviceCapabilitiesW](/windows/win32/api/wingdi/nf-wingdi-devicecapabilitiesw) function​ with `DC_COLORDEVICE` capability.<br/>

[gewarren]

Suggested change

	On versions below .NET 5, <see langword="true" /> if this printer uses multiple adjacent color bits for each pixel; otherwise, <see langword="false" />.
	.NET Core 3.1 and earlier versions: <see langword="true" /> if this printer uses multiple adjacent color bits for each pixel; otherwise, <see langword="false" />.

[gewarren]

Suggested change

	On .NET 5 and above, <see langword="true" /> if this printer supports color; otherwise, <see langword="false" />.</value>
	.NET 5 and later versions: <see langword="true" /> if this printer supports color; otherwise, <see langword="false" />.</value>

[gewarren]

Suggested change

	<summary>On .NET Frameworks 1.1 to 4.8, .NET Core framework versions 3.1 and 3.0, and on .NET Framework Extensions 2.1 to 3.1, gets a value indicating whether this printer uses multiple adjacent color bits for each pixel. This value does not guarantee if this printer supports color.<br/>
	<summary>.NET 5.0 and later versions only: Gets a value that indicates whether this printer supports color printing.
	.NET Framework 1.1 to 4.8, .NET Core 3.1 and 3.0, and .NET Framework Extensions 2.1 - 3.1 only: Gets a value that indicates whether this printer uses multiple adjacent color bits for each pixel. This value does not guarantee if this printer supports color.<br/>

[gewarren]

@RussKie I left a suggestion for how I would work it. I usually using the "Starting in version x..." verbiage in the breaking change docs, but not so much in the API ref docs.

[carlossanlop]

@Tanya-Solyanik any chance you can take a look at the latest suggestions?

[carlossanlop]

@Tanya-Solyanik this has been stale for some time. Is it still on your radar?