PrintCapabilities Class (System.Printing)

Switch View :
ScriptFree
.NET Framework Class Library
PrintCapabilities Class

Defines the capabilities of a printer.

Inheritance Hierarchy

System.Object
  System.Printing.PrintCapabilities

Namespace:  System.Printing
Assembly:  ReachFramework (in ReachFramework.dll)
Syntax

Visual Basic
Public NotInheritable Class PrintCapabilities
C#
public sealed class PrintCapabilities
Visual C++
public ref class PrintCapabilities sealed
F#
[<Sealed>]
type PrintCapabilities =  class end

The PrintCapabilities type exposes the following members.

Constructors

  Name Description
Public method PrintCapabilities Initializes a new instance of the PrintCapabilities class by using an XML stream (that contains a PrintCapabilities document) that specifies printer capabilities and complies with the XML Print Schema.
Top
Properties

  Name Description
Public property CollationCapability Gets a collection of values that identify the collation capabilities of a printer.
Public property DeviceFontSubstitutionCapability Gets a collection of values that identify whether and how a printer can substitute device-based fonts for computer-based fonts.
Public property DuplexingCapability Gets a collection of values that identify whether and how a printer can perform two-sided printing.
Public property InputBinCapability Gets a collection of values that indicate what input bin (paper tray) is used.
Public property MaxCopyCount Gets a value indicating the maximum number of copies that the device can print in a single print job.
Public property OrientedPageMediaHeight Gets a value indicating the height of the imageable area on a page, where height means the vertical dimension relative to the page's orientation.
Public property OrientedPageMediaWidth Gets a value indicating the width of the imageable area on a page, where width means the horizontal dimension relative to the page's orientation.
Public property OutputColorCapability Gets a collection of values that specify the ways in which a printer can print content with color and shades of gray.
Public property OutputQualityCapability Gets a collection of values that indicate the types of output quality the printer supports.
Public property PageBorderlessCapability Gets a collection of values that indicate whether the printer can print up to the edge of the media.
Public property PageImageableArea Gets an object that represents the area of a page that the printer can use.
Public property PageMediaSizeCapability Gets a collection of PageMediaSize objects that identify the paper and media sizes that a printer supports.
Public property PageMediaTypeCapability Gets a collection of values that identify what types of paper and other media a printer supports.
Public property PageOrderCapability Gets a collection of values that indicate whether a printer is capable of printing multiple-page documents from front-to-back, back-to-front, or both ways.
Public property PageOrientationCapability Gets a collection of values that identify what types of page orientation a printer supports.
Public property PageResolutionCapability Gets a collection of PageResolution objects that identify what levels of page resolution the printer supports.
Public property PageScalingFactorRange Gets the maximum and minimum percentages by which a printer can enlarge or reduce the print image on a page.
Public property PagesPerSheetCapability Gets a collection of integers, each identifying the number of pages that a user can choose to print on a single side of a sheet of paper.
Public property PagesPerSheetDirectionCapability Gets a collection of values that identify what patterns a printer supports for presenting multiple pages on a single side of a sheet of paper.
Public property PhotoPrintingIntentCapability Gets a collection of values that identify the quality options the printer supports for printing photographs.
Public property StaplingCapability Gets a collection of values that identify the types of automatic stapling that a printer supports.
Public property TrueTypeFontModeCapability Gets a collection of values that identify the methods that a printer supports for handling TrueType fonts.
Top
Methods

  Name Description
Public method Equals(Object) Determines whether the specified Object is equal to the current Object. (Inherited from Object.)
Protected method Finalize Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
Public method GetHashCode Serves as a hash function for a particular type. (Inherited from Object.)
Public method GetType Gets the Type of the current instance. (Inherited from Object.)
Protected method MemberwiseClone Creates a shallow copy of the current Object. (Inherited from Object.)
Public method ToString Returns a string that represents the current object. (Inherited from Object.)
Top
Remarks

A PrintCapabilities object is an easy-to-work-with representation of a certain type of XML document called a PrintCapabilities document. The latter is a snapshot of all of a printer's capabilities and their current settings. For example, if the printer supports color printing, then the document would have a <PageOutputColor … > element that sets out how color output will be handled. The element is, in turn, represented by the OutputColorCapability property of the PrintCapabilities object. If the printer does not support color, then there is no <PageOutputColor … > element in the document and the value of the OutputColorCapability property is null. The PrintCapabilities document must conform to the Print Schema.

The PrintCapabilities class enables your application to obtain a printer's capabilities without having to engage in any direct reading of XML Stream objects.

All of the most popular features of file and photo printers, for both home and business, are encapsulated by the PrintCapabilities class. But the Print Schema defines many more, less common, features and it can be extended to handle features of specialty printing devices. So, although the PrintTicket and PrintCapabilities classes cannot be inherited, you can extend the Print Schema to recognize print device features that are not accounted for in the PrintTicket or PrintCapabilities classes.

Note   When the PrintCapabilities object is created with the constructor that takes a PrintCapabilities document (as a Stream) parameter, that entire document is stored in a non-public field in the object, including the XML elements within it that express less common features that are not represented by any of the public properties of the PrintCapabilities class. In fact, if the driver that produced the PrintCapabilities document is using a private extension of the Print Schema, that privately defined markup is also stored as part of the non-public PrintCapabilities document.

Examples

The following example shows how to determine the capabilities of a specific printer and how to configure a print job to take advantage of them.

Visual Basic

' ---------------------- GetPrintTicketFromPrinter -----------------------
''' <summary>
'''   Returns a PrintTicket based on the current default printer.</summary>
''' <returns>
'''   A PrintTicket for the current local default printer.</returns>
Private Function GetPrintTicketFromPrinter() As PrintTicket
    Dim printQueue As PrintQueue = Nothing

    Dim localPrintServer As New LocalPrintServer()

    ' Retrieving collection of local printer on user machine
    Dim localPrinterCollection As PrintQueueCollection = localPrintServer.GetPrintQueues()

    Dim localPrinterEnumerator As System.Collections.IEnumerator = localPrinterCollection.GetEnumerator()

    If localPrinterEnumerator.MoveNext() Then
        ' Get PrintQueue from first available printer
        printQueue = CType(localPrinterEnumerator.Current, PrintQueue)
    Else
        ' No printer exist, return null PrintTicket
        Return Nothing
    End If

    ' Get default PrintTicket from printer
    Dim printTicket As PrintTicket = printQueue.DefaultPrintTicket

    Dim printCapabilites As PrintCapabilities = printQueue.GetPrintCapabilities()

    ' Modify PrintTicket
    If printCapabilites.CollationCapability.Contains(Collation.Collated) Then
        printTicket.Collation = Collation.Collated
    End If

    If printCapabilites.DuplexingCapability.Contains(Duplexing.TwoSidedLongEdge) Then
        printTicket.Duplexing = Duplexing.TwoSidedLongEdge
    End If

    If printCapabilites.StaplingCapability.Contains(Stapling.StapleDualLeft) Then
        printTicket.Stapling = Stapling.StapleDualLeft
    End If

    Return printTicket
End Function ' end:GetPrintTicketFromPrinter()


C#

// ---------------------- GetPrintTicketFromPrinter -----------------------
/// <summary>
///   Returns a PrintTicket based on the current default printer.</summary>
/// <returns>
///   A PrintTicket for the current local default printer.</returns>
private PrintTicket GetPrintTicketFromPrinter()
{
    PrintQueue printQueue = null;

    LocalPrintServer localPrintServer = new LocalPrintServer();

    // Retrieving collection of local printer on user machine
    PrintQueueCollection localPrinterCollection =
        localPrintServer.GetPrintQueues();

    System.Collections.IEnumerator localPrinterEnumerator =
        localPrinterCollection.GetEnumerator();

    if (localPrinterEnumerator.MoveNext())
    {
        // Get PrintQueue from first available printer
        printQueue = (PrintQueue)localPrinterEnumerator.Current;
    }
    else
    {
        // No printer exist, return null PrintTicket
        return null;
    }

    // Get default PrintTicket from printer
    PrintTicket printTicket = printQueue.DefaultPrintTicket;

    PrintCapabilities printCapabilites = printQueue.GetPrintCapabilities();

    // Modify PrintTicket
    if (printCapabilites.CollationCapability.Contains(Collation.Collated))
    {
        printTicket.Collation = Collation.Collated;
    }

    if ( printCapabilites.DuplexingCapability.Contains(
            Duplexing.TwoSidedLongEdge) )
    {
        printTicket.Duplexing = Duplexing.TwoSidedLongEdge;
    }

    if (printCapabilites.StaplingCapability.Contains(Stapling.StapleDualLeft))
    {
        printTicket.Stapling = Stapling.StapleDualLeft;
    }

    return printTicket;
}// end:GetPrintTicketFromPrinter()


Visual C++

// ---------------------- GetPrintTicketFromPrinter -----------------------
/// <summary>
///   Returns a PrintTicket based on the current default printer.</summary>
/// <returns>
///   A PrintTicket for the current local default printer.</returns>
PrintTicket^ GetPrintTicketFromPrinter () 
{
   PrintQueue^ printQueue = nullptr;

   LocalPrintServer^ localPrintServer = gcnew LocalPrintServer();

   // Retrieving collection of local printer on user machine
   PrintQueueCollection^ localPrinterCollection = localPrintServer->GetPrintQueues();

   System::Collections::IEnumerator^ localPrinterEnumerator = localPrinterCollection->GetEnumerator();

   if (localPrinterEnumerator->MoveNext())
   {
      // Get PrintQueue from first available printer
      printQueue = ((PrintQueue^)localPrinterEnumerator->Current);
   } else
   {
      return nullptr;
   }
   // Get default PrintTicket from printer
   PrintTicket^ printTicket = printQueue->DefaultPrintTicket;

   PrintCapabilities^ printCapabilites = printQueue->GetPrintCapabilities();

   // Modify PrintTicket
   if (printCapabilites->CollationCapability->Contains(Collation::Collated))
   {
      printTicket->Collation = Collation::Collated;
   }
   if (printCapabilites->DuplexingCapability->Contains(Duplexing::TwoSidedLongEdge))
   {
      printTicket->Duplexing = Duplexing::TwoSidedLongEdge;
   }
   if (printCapabilites->StaplingCapability->Contains(Stapling::StapleDualLeft))
   {
      printTicket->Stapling = Stapling::StapleDualLeft;
   }
   return printTicket;
};// end:GetPrintTicketFromPrinter()


Version Information

.NET Framework

Supported in: 4, 3.5, 3.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1
Platforms

Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.
Thread Safety

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.
See Also

Reference

Other Resources