/***********************************************************************/
//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.
PrintTask 控件能够让用户打印一个地图或者一个任务结果，并附带着图例、比例尺、版权信息和指北针。PrintTask控件能够让用户设置多个用于打印页面的属性。作为一个开发者，你可以控制打印选项对话框中出现什么内容以及打印页面中显示的内容。打印任务生成一个新的浏览器窗口，窗口里面显示打印预览的内容。然后用户可以使用本地或者网络上任何一个可以获取的打印机打印页面。
Assembly: ESRI.ArcGIS.ADF.Tasks.dll
Class: ESRI.ArcGIS.ADF.Tasks.PrintTask
Using the PrintTask control
使用打印任务控件
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.
向页面中添加支持控件
为了全面的利用PrintTask控件的优势，必须添加若干个提供支持作用的控件。创建一个web应用程，根据他们的使用向导添加一个MapResourceManager和一个Map控件。添加一个或者多个任务，比如：添加一个QueryAttributesTask到你想打印任务结果的页面。如果你添加了一个tasks，那么请记住一定要添加一个TaskResults控件，可以根据控件的添加信息进行添加。运行状态下，TaskResults控件将会显示task操作结果。如果你想要用户看到当选中结果后在地图上高亮显示的，还需要设置TaskResults控件的Map属性为我们在前面添加的控件。 如果需要，还可以添加一个TaskManager控件和一个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（内部的）.
Add a PrintTask control
可以选择性的添加一些其他的控件，比如内容表格空间（也就是ＴＯＣ控件），对于PrintTask控件显示一个图例来说，向页面中添加一个ＴＯＣ控件并不是必须的，因为PrintTask控件在内部生成她自己的图例。
添加一个ＴＯＣ控件到页面
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:
在ＶＳ中，在设计模式下显示页面的ｗｅｂ表格。选择Toolbox并展开ArcGIS Web 控件。 拖拽一个PrintTask控件到页面中。你的页面应该假设和下面的使用table后的布局以及安排。
Set the properties for the PrintTask
设置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箭头，单击这个箭头来显示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.
Task Results container（任务结果容器）:单击samrt tag menu 中的第一个item 来选择task results containers或者在属性窗口中单击TaskResultsContainers属性按钮。然后调出BuddyControl集合编辑框。单击Add按钮向集合中添加一个项。选中一个taskResults1，在右边的对话框，单击drop-down下拉列表，选择你在前面添加的taskResults控件。PrintTask 控件将会打印在这个结果容器中显示的内容 。 如果这个属性没有设置，那么在PrintTask对话中将不会出现这些结果。
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.
选择图例图层，如果你想从打印图例中删除一些地图图层，单击smart tag中的第二个项来选择被选中的图例图层。 在出现的表格中，展开地图资源，取消选中要从图层中隐藏的图例，单击【ok】按钮保存你的设置。
Set other properties for the PrintTask
设置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".
你想为你的应用程序定义的其他的属性包括：
Title:显示在web站点的中打印表格顶部。你可以从默认中改变这个属性，默认值是控件的ID。 选择一个标题，比如：print或者print map and data
ButtonText: text for the button that creates the print preview page. Default is "Create Print Page".
ButtonText(按钮文本):生成打印预览页面的按钮的文本。默认值是：“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.
LegendSettings(图例设置): 展开这个属性设置在图例中显示的列的数目，而不用管图例是进行压缩（如果没有压缩，显示所有的资源项的名称和图层的名称），图例显示的是否是默认的值，在对话框是否包含一个打印图例的选项（默认值为false）和是否隐藏图层。使用samrt tag 来编辑隐藏图层
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).
MapSettings: 展开属性来设置是否按照默认值打印地图，是否给用户一个打印地图的选项。
NorthArrowSettings（设置指北针）:展开属性设置默认打印的指北针以及设置是否给用户一个打印指北针的选项
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.
QualitySettings：这个设置将会影响打印的质量。 展开属性，设置地图默认的DPI属性。设置用户是否看到改变质量的选项，并且，当DisplayInDialog为true时候，一系列的Map 质量的设置项将会显示在用户对话框中。为了编辑QualityList，单击在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.
ResultsVisible：是否在website中的打印对话框包含一个可以打印的任务结果列表。如果存储打印任务TaskResultsContainer中含有一个或者多个任务并且你不想让用户从这些任务中打印结果，那么就设置属性为false。
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).
ScaleBarSettings：展开这个属性设置是否打印默认的比例工具，以及是否给用户一个打印scalebar的选项（选项显示在打印对话框里面）。
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).
TitleSettings：展开这个属性设置打印页面的标题，标题会一直使用，除非用户改变它。是否给用户一个浏览和改变标题的选项。
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（n.比例；部分，份儿；均衡，相称） 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.
WidthSettings：这些设置定义了打印地图的大小。 这个大小的设置是基于要求的宽度。地图高度会自动的和当前页面中的地图保持比例。展开这个属性设置默认的宽度，设置是否给用户改变当前宽度的选项。如果DisplayInDialog的值为true，将在打印对话框中显示宽度调节列表。为了编辑宽度列表，单击list后面的省略号按钮，在打开的对话框中编辑列表的值。每一个大小都会分配一个名称和一个以英尺或者厘米为单位的宽度值。
LayoutTemplateFile: path to the file that defines the inclusion（包含） and arrangement（n.[常 pl.]安排，准备工作；整理） 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
LayoutTemplateFile：定义打印页面中包含的元素以及他们的排版的文件的路径。创建一个自定义模板文件，你可以：指定标准打印页面元素的现实样式和位置，这些元素有：地图，图例，标题，任务结果框，版权标题，和版权文本，这些元素包括自定义元素：比如，公司的logo。
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.
展示动态信息：比如：时间邮戳和用户注册、登记信息。
操纵任务结果展示分析报告和生成先进的可视化图表等等..
使用JavaScript和ASP.NET来实现交互性、互动。
更多的消息，单击 workding with print task templates
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:
运行状态下调用 printTask
PrintTask对话框显示在设计视图模式下的设置的打印属性。 默认情况下，print 对话框类似于这个图片
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.
用户重新定义title,size等属性，选择任何一个results打印，单击【Create Print Page】按钮，这个打开一个新的浏览器窗口和tab，新的打印页面就展示在新的窗口中。用户就可能使用浏览器的打印功能来打印这个页面。
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:
当你向一个web应用程序中添加一个打印任务，task为页面的大小提供预先定义的值，以及print quality 和 指北针箭头。预定义的值为：
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，
如果你改变显示在地图上的指北针样式，不管是在管理器中或者是VS中创建应用程序，你都可以使用character的索引值来设置print task的指北针的样式索引值。
In the case of the page size and print quality, the text shown above 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.
对于：页面的大小和打印的质量，在打印对话框的上面将会出现应用程序最终用户想要打印的地图的文字。你可以在VS里面通过编辑print task里面相关属性改变这些值，比如：WidthSettings, QualitySettings, and NorthArrowSettings。尽管如此，你必须为你创建的每一个ｗｅｂ应用程序设置这些属性。
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.
Print Task使用一个配置文件来存储这些预定义的值，因此，如果你想使用你自己的值来取代这些预定义的值，你也可以在文本编辑器里面修改这些配置文件。任何新创建的应用程序就会使用这些新的预定义的值。
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:
配置文件存放在<install_location>/Dotnet and is called ESRI.ArcGIS.ADF.Tasks.dll.config（文件存放路径），为来改变显示的页面大小或者打印质量名称，你需哟啊添加新的属性调用名称。这些将会重载当前预定义的值，这些预定义的值都保存在一个用于本地化资源文件里面。
比如：这是一个和页面大小和名称一同的添加。
<Size ID="PrintTaskSize0" Name=擲mall 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.
当设置页面大小以及质量的时候，一定要记住ＧＩＳ Server 限制了她能够返回的图像最大的size的值。 比如ArcGISServer 地图服务,在默认情况下,限制图像的最大值为2048 x 2048 像素。这就意味着一个10平方英尺的地图加上200dpi的质量就是2000*2000像素。 如果打印任务地图的请求超过了GIS Server的限制，那么个别的services将不会输出。