Skip to content

Corrected description of PrinterSettings.SupportsColor property #4087

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

Corrected description of PrinterSettings.SupportsColor property #4087

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 11 additions & 3 deletions ...sharp/VS_Snippets_Winforms/PaperSource and PaperSize Example with Resolution/CS/source.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@
using System.ComponentModel;
using System.Windows.Forms;
using System.Data;
using System.Runtime.InteropServices;

namespace WindowsApplication3
{
Expand Down Expand Up @@ -283,16 +284,23 @@ private void MyButtonPrint_Click(object sender, System.EventArgs e)
protected int currentPageNumber = 1;
// <Snippet6>

private void MyButtonPrint_OnClick(object sender, System.EventArgs e)
{
[DllImport("winspool.drv", SetLastError = true, CharSet = CharSet.Unicode, ExactSpelling = true)]
private static extern int DeviceCapabilitiesW(string pDevice, string pPort, short fwCapabilities, IntPtr pOutput, IntPtr pDevMode);
private const short DC_COLORDEVICE = 32;

private static bool GetColorDeviceCapability(string printerName) {
return DeviceCapabilitiesW(printerName, null, DC_COLORDEVICE, IntPtr.Zero, IntPtr.Zero) == 1;
}

private void MyButtonPrint_OnClick(object sender, System.EventArgs e) {

// Set the printer name and ensure it is valid. If not, provide a message to the user.
printDoc.PrinterSettings.PrinterName = "\\mynetworkprinter";

if (printDoc.PrinterSettings.IsValid) {

// If the printer supports printing in color, then override the printer's default behavior.
if (printDoc.PrinterSettings.SupportsColor) {
if (GetColorDeviceCapability("\\mynetworkprinter")) {

// Set the page default's to not print in color.
printDoc.DefaultPageSettings.Color = false;
Expand Down
11 changes: 7 additions & 4 deletions xml/System.Drawing.Printing/PrinterSettings.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1654,13 +1654,16 @@
<ReturnType>System.Boolean</ReturnType>
</ReturnValue>
<Docs>
<summary>Gets a value indicating whether this printer supports color printing.</summary>
<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/>
Copy link
Contributor

@gewarren gewarren Feb 4, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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/>

On .NET 5, gets a value indicating whether this printer supports color printing.</summary>
Comment on lines +1657 to +1658
Copy link
Contributor

@RussKie RussKie Feb 3, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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>

Copy link
Contributor

@gewarren gewarren Feb 4, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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.

<value>
<see langword="true" /> if this printer supports color; otherwise, <see langword="false" />.</value>
On versions below .NET 5, <see langword="true" /> if this printer uses multiple adjacent color bits for each pixel; otherwise, <see langword="false" />.
Copy link
Contributor

@gewarren gewarren Feb 4, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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" />.

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

@gewarren gewarren Feb 4, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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>

<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
## Remarks
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/>
Copy link
Contributor

@gewarren gewarren Feb 4, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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/>

To print using color, and if the printer supports it, set <xref:System.Drawing.Printing.PageSettings.Color%2A?displayProperty=nameWithType> to `true`.
Expand All @@ -1672,7 +1675,7 @@
[!code-cpp[PaperSource and PaperSize Example with Resolution#6](~/samples/snippets/cpp/VS_Snippets_Winforms/PaperSource and PaperSize Example with Resolution/CPP/source.cpp#6)]
[!code-csharp[PaperSource and PaperSize Example with Resolution#6](~/samples/snippets/csharp/VS_Snippets_Winforms/PaperSource and PaperSize Example with Resolution/CS/source.cs#6)]
[!code-vb[PaperSource and PaperSize Example with Resolution#6](~/samples/snippets/visualbasic/VS_Snippets_Winforms/PaperSource and PaperSize Example with Resolution/VB/source.vb#6)]
[!code-vb[PaperSource and PaperSize Example with Resolution#6](~/samples/snippets/visualbasic/VS_Snippets_Winforms/PaperSource and PaperSize Example with Resolution/VB/source.vb#6)]
]]></format>
</remarks>
Expand Down