PrintTask control

The PrintTask control enables users to print a map and task results, along with a legend, scalebar, copyright and north arrow. The task can allow the end user to set various properties for the print page. As a developer, you can control what options appear in the print options dialog and what is displayed on the print page. The print task generates a new browser window with the print page preview. The user then can print the page to any available printer locally or on the network.

Assembly: ESRI.ArcGIS.ADF.Tasks.dll
Class: ESRI.ArcGIS.ADF.Tasks.PrintTask

Using the PrintTask control

1. Add supporting controls to the page 
   
   In order to take full advantage of the PrintTask control, a number of supporting controls must be available.  Set up a Web application with MapResourceManager and Map controls using their discussion topics as a guide. Add one or more tasks, such as a QueryAttributesTask, to the page if you wish to be able to print the results of task(s). If you add tasks, remember to also add a TaskResults control using that control's discussion topics as a guide. At runtime, the TaskResults control will display the results of task operations. Also set the Map property of the TaskResults control to the Map control you added, if you want users to see results highlighted on the map when selected. If desired, also add a TaskManager and menu control to enable users to open tasks from the menu.
   
   Optionally add other controls, such as a table of contents (Toc) control. It is not necessary to add a Toc to the page in order to have the PrintTask display a legend, since the PrintTask generates its own legend internally.
2. Add a PrintTask control
   
   In Visual Studio, display the page's Web form in design mode. Select the Toolbox and expand the ArcGIS Web Controls tab. Drag and drop a PrintTask onto the page. Your page might resemble the following layout, arranged using a table:
   
   
   
3. Set the properties for the PrintTask
   
   In design mode, click the PrintTask, which will display the smart tag arrow in the upper right of the control. Click on this arrow to display the smart tag menu. This menu displays common properties that you can set, though others are available in the Properties window for the control.
   
   
   a. Task Results container: Click the first item in the smart tag menu to choose the Task Results container, or click the TaskResultsContainers property button in the Properties window. This brings up the BuddyControl collection editor. Click Add to add an item to the collection. With the TaskResults1 item selected, in the right side of the dialog, click the drop-down list and select the TaskResults control you added earlier. The PrintTask will print results that appear in this task results container. If this property is not set, results will not be available to print in the PrintTask dialog.
   
   
   
   b: Select Legend Layers: If you want to omit some map layers from the printed legend, click the second item in the smart tag menu to choose Select Legend Layers. In the form that opens, expand the map resource and uncheck the layer(s) to hide from the legend. Click OK to save the settings.
    
   
4. Set other properties for the PrintTask 
   
   Some of the properties you may wish to modify for your application include:
   
   • Title: displayed at the top of the print form in the website. You should change this from the default, which is the ID of the control. Choose a title such as "Print" or "Print the map and data".
   • ButtonText: text for the button that creates the print preview page. Default is "Create Print Page".
   • LegendSettings: expand this property to set the number of columns in the legend, whether the legend is condensed (if not condensed, prints all resource item names and group layer names), whether the legend prints by default (DefaultValue), whether an option to print the legend is included in the user dialog (false by default), and hidden layers, if any. Use the smart tag (see above - Select Legend Layers) to edit the hidden layers.
   • MapSettings: expand this property to set whether the map prints by default (DefaultValue), and whether the user will be given the option to print the map (DisplayInDialog).
   • NorthArrowSettings: expand this property to set whether the north arrow prints by default (DefaultValue), and whether the user will be given an option to print the north arrow (DisplayInDialog).
   • QualitySettings: these settings affect the quality of the map when printed. Expand this property to set the default DPI setting for the map (DefaultValue), whether the user will see an option to change the quality (DisplayInDialog), and the list of map quality settings that will be in the user dialog if DisplayInDialog is true. To edit the QualityList, click the "..." button next to the list.
   • ResultsVisible: whether the print dialog in the website includes a list of task results to print. Set this property to false if the TaskResultsContainer in which the PrintTask resides has one or more other tasks, but you do not want users to be able to print results from those tasks.
   • ScaleBarSettings: expand this property to set whether the scalebar prints by default (DefaultValue), and whether the user will be given an option to print the scalebar (DisplayInDialog).
   • TitleSettings: expand this property to set the title of the printed page that is used unless the user changes it (DefaultValue), and whether the user will be given an option to view and change the title (DisplayInDialog).
   • WidthSettings: these settings determine the size of the printed map. The size is set based on the desired width. The height of the map is automatically proportioned to the current map in the web page. Expand this property to set the default width (DefaultValue), whether the print dialog will include an option to change the width (DisplayInDialog), and the list of width settings that will display in the print dialog if DisplayInDialog is true. To edit the WidthList, click the "..." button next to the list and edit the values in the dialog that opens. Each size may be assigned a name and a width value in inches or centimeters.
   • LayoutTemplateFile: path to the file that defines the inclusion and arrangement of elements on the print page.  By creating a custom template file, you can:
     • Specify the appearance and placement of standard print page elements - map, legend, title, task results, copyright title, and copyright text
     • Include custom elements such as company logos
     • Display dynamic information such as time stamps and user login
     • Manipulate task results to perform analyses and create advanced visualizations (e.g. charts)
     • Use JavaScript and ASP.NET to enable interactivity
     For further information, refer to Working with print task templates.
     
      
5. Using the PrintTask at runtime
   
   The PrintTask dialog displays the options for printing based on the settings at design time. By default, the print dialog resembles this image:
   
   
   
   The user modifies settings for title, size, etc., chooses task results, if any, to print, and clicks the Create Print Page button. This opens a new browser window or tab, and the print page is displayed in the new window. The user may then use the browser's print functions to print the page.

Members

Properties 

  The following table provides a list of properties of interest.  For complete reference information, see the PrintTask control in the library reference section.

Property Name	Type	Description
ButtonText	String	The text which appears on the button to executes the task.
LegendSettings	LegendItemSettings	Settings for printing the legend in the print page.
MapSettings	ItemSettings	Settings for whether the map prints.
NorthArrowSettings	NorthArrowSettings	Settings for printing the north arrow on the print page.
QualitySettings	QualityItemSettings	Settings for the quality (DPI) of the map on the print page.
ResultsVisible	Boolean	Whether the list of task results displays in the print dialog, enabling the user to print task results.
ScaleBarSettings	ItemSettings	Settings for whether the scalebar displays on the print page.
TitleSettings	ItemSettings	Settings for the title on the print page.
WidthSettings	WidthItemSettings	Settings for the size (based on the width) of the map on the print page.
ActivityIndicatorImage	String	URL of the image to display while a task is executing.
ActivityIndicatorLocation	TaskActivityIndicatorLocation	The location of an animated image that is displayed while the task is executing.
NavigationPath	String	The path to the task as it would appear in a hierarchical data control buddied to the task's TaskManager.
Map	String	ID of the Map control that will be used as the source for the printed map.
MapCopyrightText	String	ID of the MapCopyrightText control to use for printing a copyright statement on the printed page.
TaskResultsContainers	BuddyControlCollection	The controls in which results from this task are displayed.
LayoutTemplateFile	String	The path to the file specifying the layout of the print page.

 

Discussion

• Setting the default page size, quality, and North arrow
  
  When you add a Print Task to your web application, the task provides predefined values for the page size, print quality and North arrow. The predefined values are:
  
  Page Size
  
  • Small: 3 inches x 3 inches
  • Medium: 5 inches x 5 inches
  • Large: 7 inches x 7 inches
  Print Quality
  • Draft: 96 pixels (dots) per inch (DPI) - suitable for screen display, but poorer quality when printed
  • Normal: 200 pixels (dots) per inch (DPI) - better quality when printed, though may appear less clear on screen in print preview page
  North Arrow
  • Font name: ESRI North
  • Font character: 176

  If you change the North arrow character displayed on the Map, either when creating the application in Manager, or in Visual Studio, then you can use the index character number to set the character number for the Print Task's north arrow.

  In the case of the page size and print quality, the text shown above (i.e., small, medium, large; draft, and normal) will display in the print dialog that appears when the end user of your application wants to print the map. You can change these values in Visual Studio by editing the appropriate properties on the Print Task: WidthSettings, QualitySettings, and NorthArrowSettings. However, you have to set these properties for every Web application you create.

  The Print Task uses a configuration file to store the predefined values. Thus, if you want to replace these values with your own values, you can do so by editing the configuration file in a text editor. Any newly created applications will then use the new predefined values.

  The configuration file is located in the folder <install_location>/Dotnet and is called ESRI.ArcGIS.ADF.Tasks.dll.config. To change the page size or print quality names that display (e.g., small, draft), you will need to add a new attribute called Name. This will override the current predefined value, which is stored in a resource file for localization purposes. For example, here is one entry for the page size with Name added:

  <Size ID="PrintTaskSize0" Name=”Small Map” SizeHeight="3.0" SizeWidth="3.0" Unit="Inches" />

  When setting the page size and quality, keep in mind that the GIS server imposes limits on the maximum image size it can return. For example, ArcGIS Server map services, by default, restrict the image size to a maximum of 2048 x 2048 pixels. This means that a 10 inch square map with a quality of 200 dpi is 2000 x 2000 pixels. If the print task map request exceeds the limits of the GIS server, the particular service will not print.