Developing Web Applications with the Web ADF - Web controls  

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:

    PrintTask control on page
  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.

    PrintTask smart tag
    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.

    QueryAttributesTask result container 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.
     
    PrintTask - select legend layers
  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:

    Print task at runtime

    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