人力资源-SilverLightViewer 开发人员指南.docx

SilverLightViewer
开发人员指南
丁 海
二〇一〇年八月
目录
简述 2
背景 2
术语和定义 2
GIS(地理信息系统) 2
GPS (全球卫星定位系统) 2
RIA (富因特网应用程序) 3
Flex 3
SilverLight 4
开发环境 4
必备知识 4
SilverLight Viewer开发框架 5
概述 5
系统框架图 6
开发人员指南 7
Widget Framework基础 7
系统配置文件 11
系统常用事件(AppEvent) 17
开发自己的Widget 25
使用外部参数 34
使用自定义图形光标 35
附录I：Widgets介绍 35
主控窗口(Viewer Controller Widget) 35
Header Controller 35
Classic Controller 36
图层切换(Map Switcher Widget) 38
鹰眼(Overview Map Widget) 39
书签(Bookmark Widget) 40
附录II：常见问题 41
使用跨域访问配置文件(clientaccesspolicy.xml) 41

简述
本文档用于帮助开发人员使用SilverLight Viewer框架，开发基于ArcGIS for Silverlight/WPF API 2.0 的RIA地图应用。
背景
ESRI发布了ArcGIS SilverLight API等快速Web开发包，受到了广大用户及开发商的关注。 但一直以来开发商和用户都只是使用在线的文档及零散的在线例子，开发商或用户准备使用ArcGIS SilverLight API进行开发的时候，总是感到无从下手。基于以上原因，本方案旨在为客户提供一个可扩展、移植的SilverLight API开发框架，并向用户展示ArcGIS SilverLight API的功能及魅力。
术语和定义
GIS(地理信息系统)
地理信息系统（Geographic Information System，简称 GIS）是建立在地球科学基础上的边缘科学，是以地理空间数据库为基础，在计算机软硬件的支持下，对空间相关资料进行采集、管理、操作、查询分析、模拟、显示和制图输出，并采用地理模型分析方法，适时提供多种空间和动态的地理信息，为地理研究和地理决策服务而建立起来的计算机技术系统。是融地理学、几何学、计算机科学及各类应用对象为一体的综合性高新技术。
GPS (全球卫星定位系统)
GPS是全球卫星定位系统(Global Positioning System，GPS)的英文缩写，GPS利用导航卫星进行测时和测距，以构成全球定位系统，能提供个人候的定位、授时、测速功能。
GPS是一种精密的卫星导航系统。该系统由24颗绕地球旋转的卫星组成，卫星连续不断地发送位置和时间信息。这些卫星均匀地分布在6个轨道上，每个轨道有4 颗卫星。地面GPS接收机可接收5到12颗卫星信号。为实现地面定位功能，GPS接收机至少需要接收4个卫星信号，其中3个信号用来计算GPS接收机的纬度、经度和海拔高度，第四个信号提供同步时间校准。
RIA (富因特网应用程序)
RIA是Rich Internet Application 的简称，也称富因特网应用程序，是由Macromedia（现Adobe）最先提示的概念，以示与传统Web应用程序相区别。
自从B/S架构迅速流行开来之后，我们就一直面临着这样一个问题：如何做到当初C/S那样的表示层精确控制以及良好的用户体验？当然，大量的利用DHTML以及 JavaScript我们可以实现接近C/S时代的表示层控制和展现，比如Bindows ，但是我们需要付出比C/S时代更多的人力物力才能做到接近于C/S客户端的表现方式，这不是我们想要的。在我们从当初狂热的B/S浪潮中逐渐冷静下来的时候，我们发现单纯的瘦客户端/胖服务器模式并非是一个万能的模式 - 世间能量终究是守恒的，有得必有失，我们在获得了B/S带来的种种好处之后，也同样失去了C/S带给我们的帮助，因此RIA(Rich Internet Applications)的出现就显得极其自然了。
RIA意味:
不同凡响的Web功能、更好的用户体验、更强大的用户界面、更好的交 互性、更先进的开发模型、更强大的多媒体功能、更好的数据管理、更好的 程序控制
目前RIA开发的技术主要有，Adobe Flex、Ajax、WPF、OpenLaszlo、Google Web Toolkit、Java SWT、XUL、JavaFX、Silverlight。
Flex
随着当今信息技术飞速发展和Internet带宽的增加，传统的文字＋图片的方式已经不能满足人们对Web内容的需要。随着Web 2.0的概念越来越深入人心，Flex技术作为RIA技术的领航者已经快速的发展到了第三个版本Flex 3.0。Flex技术是完全基于矢量图形技术的，这样使得用户能够获得更多的用户体验。只要浏览器可以播放Flash，就可以显示Flex的网站。由于FlashPlayer的高市场占有率，基于Flex的RIA技术已经逐渐成为Web 2.0开发的主要技术手段。Flex的定位是提供丰富Internet应用的企业级开发框架。轻便的开发模式和良好的服务端兼容性使得Flex已经成为主流的网站和电子商务的发展方向。
SilverLight
Silverlight是微软推出的一个跨平台跨操作系统的插件，使Web开发者能够在浏览器中建造丰富的媒体体验和RIA应用。可用于Windows平台上的IE和Firefox浏览器，以及Mac OS X平台上的Firefox和Safari浏览器。
Silverlight 是一种新的 Web 呈现技术，能在各种平台上运行。借助该技术，您将拥有内容丰富、视觉效果绚丽的交互式体验，而且，无论是在浏览器内、在多个设备上还是在桌面操作系统（如 Apple Macintosh）中，您都可以获得这种体验。支持创建3D模型、可以更轻松的现实视频播放和分享的播放器一类的东西，支持搜索引擎。
开发环境
Windows Xp/2003/2008/7
IIS
Microsoft Visual Studio 2010
Microsoft Expression Blend 4
SilverLight 4
Silverlight_4_Toolkit
SilverLight Tools for Visual Studio 2010
ArcGIS for Silverlight/WPF API 2.0
SilverLightViewer 1.0
必备知识
熟练使用Visual Studio开发SilverLight（C # 或VB）
熟悉ArcGIS for Silverlight/WPF API
SilverLight Viewer开发框架
概述
SilverLight Viewer开发框架帮助开发人员，快速的开发和部署基于ArcGIS for Silverlight/WPF API 2.0 的RIA地图应用。
SilverLight Viewer开发框架有以下特点：
1． 轻松配置，以满足客户业务需求和要求
2． 通过Widget来实现各种功能，提供许多核心的Widget如：图层管理、鹰眼等
3． 轻松扩展，可根据自己的业务需求，轻松的编写或下载widgets
4． Widgets采取按需下载管理模式，最小化服务器网络负载。
5． 类似于 ArcGIS Viewer for Flex

系统框架图

开发人员指南
Widget Framework基础
Widget是被封装在一起的一段或一组孤立的可执行代码，它实现了用户的一种或一组功能或业务逻辑（包括可视化的界面）。对于面向服务的应用，Widget甚至可以是一个服务(数据、业务流程等)。用户可以轻松的执行这个Widget。同时Widget也支持被共享和重用。

IBaseWidget接口(IBaseWidget.cs)
定义了Widget的一系列通用接口，会被WidgetManager调用。

public interface IBaseWidget
{
int ID { get; set; }
void setTitle(string value);
void setIcon(string value);
string config { get; set; }
ConfigData configData { get; set; }
void setState(string value);
Map map { get; set; }
void setPreload(string value);
void setXYPosition(double x, double y);
void setRelativePosition(double left, double right, double top, double bottom, string horizontal, string vertical);
Boolean isDragable { get; set; }
Boolean isResizeable { get; set; }
string proxyUrl { get; }
void run();
}

BaseWidget类(BaseWidget.xaml、BaseWidget.xaml.cs)
Widget的基础类，所有Widget都继承自这个基类。它实现了IBaseWidget接口和一些通用的方法。
一些通用的方法：
public void showInfoWindow(Dictionary<string, Object> infoData);
public void setMapAction(string action, string status, EventHandler<DrawEventArgs> callback);
public void setMapNavigation(String navMethod, String status);
public void showError(string errorMessage);

一些通用的事件：
public delegate void WidgetConfigEventHandler(object sender, AppEvent e);（配置文件加载事件代理）
public event WidgetConfigEventHandler WidgetConfigEvent; （配置文件加载事件）
public event WidgetConfigEventHandler WidgetConfigErrorEvent; （配置文件加载失败事件）

注：所有的Widget必须继承自这个类。
IWidgetPanel接口(IWidgetPanel.cs)
这个接口定义了Widget模板(通用的界面及行为)在BaseWidget 中被调用的接口。
public interface IWidgetPanel
{
int widgetId { get; set; }
string widgetTitle { get; set; }
string widgetIcon { get; set; }
void setState(string value);
Boolean isDragable { get; set; }
Boolean isResizeable { get; set; }
}

WidgetPanel类(WidgetPanel.xaml、WidgetPanel.xaml.cs)
一个Widget模板。提供了widget的基本的用户界面布局(面板、窗口、标题栏、图像按钮等)和行为 (最大化、最小化、关闭等).通过使用Widget模板，Widget开发人员可以花更多的他们对自己的核心业务需求的开发时间。
开发人员可以自定义自己的widget模板，一定要实现IWidgetPanel接口。

一些通用的方法：
public virtual void addTitlebarButton(String icon, String tip, MouseButtonEventHandler mouseLeftButtonDown);

一些通用的事件：
public event EventHandler WidgetMinimizedEvent;（最小化事件）
public event EventHandler WidgetMaximizedEvent; （最大化事件）
public event EventHandler WidgetClosedEvent; （关闭事件）

Widget 界面元素
titleBar
txtTitle
imgIcon

widgetPanel
Content

LayoutRoot

界面元素嵌套关系如下图：

WidgetBar
Widget 和 WidgetBar

Widget控制条
Widget

Widget ：接受WidgetContorl 管理。
WidgetBar ：不受WidgetContorl 管理。

系统配置文件
我们可以通过修改配置文件，轻松完成系统界面的定制。
全局配置文件(默认为config.xml)

<userinterface>标签段
定义用户的UI界面。包括title、subtitle、logo、stylesheet、等标签段。
<title>：SilverLight Viewer应用程序的标题。(HeaderController Widget的左上角显示标题)
<subtitle>：SilverLight Viewer应用程序的子标题。(HeaderController Widget的标题下方显示)
< logo >：SilverLight Viewer应用程序的Logo。(HeaderController Widget的左上角显示)
< stylesheet >：SilverLight Viewer应用程序的风格描述文件。
<widgetlayout>：Widget的布局方式。有下面几种布局方式：
horizontal：横向布局

vertical：纵向布局 （默认）

float：随意布局，widget 可拖动、调整大小
<map>标签段
定义Map相关的信息，<Map>标签段包括下面的一些属性：
initialExtent：安装时地图显示的区域（XMin YMin XMax YMax）
fullExtent：地图显示的最大区域（XMin YMin XMax YMax）
left：地图距离最左边的距离
right：地图距离最右边的距离
top：地图距离最上边的距离
bottom：地图距离最下边的距离
还包含下面的标签段：
<basemaps>：定义背景地图信息，包含mapservice标签段
<mapservice>：定义一个地图服务信息，包含下面的一些属性及值域
Label：地图服务的标题名
type：地图服务类型（tiled\dynamic\virtualearth\image）
visible：地图服务的可见性
token：token串
alpha：透明度
icon：地图服务的图标
style: 图层风格(Road、Aerial 、AerialWithLabels) (只适用于virtualearth)
值域：地图服务的访问地址
<operationallayers>：定义操作地图信息，包含layer标签段
<layer>：定义一个操作图层信息，包含下面的一些属性及值域
Label：图层的标题名
type：图层的类型（tiled\dynamic\feature）
visible：图层的可见性
token：token串
alpha：透明度
icon：图层的图标
值域：图层的访问地址
<widgets>标签段
定义Widgets的信息。包含多个<widget>标签段
<widget>：定义一个Widget的信息，包含下面的属性及值域
Label：Widget的标题名
icon：Widget的图标
type：Widget的类名（创建Widget时使用）
preload：启动应用系统时是否自动加载（true/false）
config：Widget的独有的配置文件。
resdict：Widget的独有的资源文件。
group： Widget的分组信息
x：Widget的X轴绝对位置
y：Widget的Y轴绝对位置
值域：Widget所在DLL或Xap包的名称（含路径）

<widgetbars>标签段
定义Widgetbars的信息。包含多个<bar>标签段
<bar>：定义一个Widgetbar的信息，包含下面的属性及值域
Label：Widgetbar的标题名
icon：Widgetbar的图标
type：Widgetbar的类名（创建Widget时使用）
config：Widgetbar的独有的配置文件。
resdict：Widgetbar的独有的资源文件。
left：Widgetbar相对于最左边的距离（没有设置时不参与计算）
right：Widgetbar相对于最右边的距离（没有设置时不参与计算）
top：Widgetbar相对于最上边的距离（没有设置时不参与计算）
bottom：Widgetbar相对于最下边的距离（没有设置时不参与计算）
horizontal：Widgetbar横向计算模式（left(默认)：自左向右, right：自右向左）
vertical：Widgetbar纵向计算模式（top(默认)：自上向下 , bottom：自下向上）
值域：Widget所在DLL或Xap包的名称（含路径）

Widget配置文件(*.xml)
Widget独有的配置文件，定义Widget需要的配置信息，配置文件格式及内容由Widget自己处理（开发人员在WidgetConfigEvent事件中处理）。
ConfigData类
public class ConfigData
{
public Dictionary<string, string> UI { get; set; }
public Dictionary<string, string> Map { get; set; }
public Dictionary<int, Dictionary<string, string>> Basemaps { get; set; }
public Dictionary<int, Dictionary<string, string>> OperationalLayers { get; set; }
public Dictionary<int, Dictionary<string, string>> Widgets { get; set; }
public Dictionary<string, Dictionary<string, string>> Controls { get; set; }
}

系统常用事件(AppEvent)
定义了一些列系统常用的事件，包含在AppEvent.cs文件中。使用监听和发起系统事件必须使用ViewerContainer全局类。
监听事件例子：
ViewerContainer.addEventListener(AppEvent.CONTAINER_INITIALIZED, new ViewerEventHandler(containerInitialized));
触发事件例子：
ViewerContainer.dispatchEvent(AppEvent.WIDGET_RUN, new AppEvent(ItemId));
APP_ERROR
应用程序出错事件，在应用程序出错时触发。
AppEvent类的data属性为字符串类型。

触发事件示例：
String data = “出错了！”;
ViewerContainer.dispatchEvent(AppEvent.APP_ERROR, new AppEvent(data));

CONFIG_LOADED
系统全局配置文件加载成功后，触发事件。
AppEvent类的data属性为ConfigData类型实例。

监听事件示例：
ViewerContainer.addEventListener(AppEvent.CONFIG_LOADED,
new ViewerEventHandler(ConfigLoaded));

private void ConfigLoaded(object sender, AppEvent e)
{
……
}
MAP_LOADED
地图控件加载成功时触发的事件。
AppEvent 类的data属性为ESRI.ArcGIS.Client.Map类型实例。

监听事件示例：
ViewerContainer.addEventListener(AppEvent.MAP_LOADED,
new ViewerEventHandler(MapLoaded));

private void MapLoaded(object sender, AppEvent e)
{
map = (Map)e.Data;
}
MAP_RESIZE
用于改变地图控件大小事件。
AppEvent 类的data属性为Dictionary<string, Double>类型实例，包含以下的元素：
"left" : 左边的空白距离
"right" : 右边的空白距离
"top" : 上边的空白距离
"bottom" : 下边的空白距离

触发事件示例：
Dictionary<string, Double> data = new Dictionary<string, Double>();
data.Add("left",0);
data.Add("right",0);
data.Add("top",0);
data.Add("bottom",0);
ViewerContainer.dispatchEvent(AppEvent.MAP_RESIZE, new AppEvent(data));
LAYER_LOADED
基础地图图层加载成功时触发的事件。
AppEvent 类的data属性为Null。

监听事件示例：
ViewerContainer.addEventListener(AppEvent.LAYER_LOADED,
new ViewerEventHandler(OnlayerLoaded));

private void OnlayerLoaded(object sender, AppEvent e)
{
……
}
MAP_LAYER_VISIBLE
设置地图图层是否显示的事件。
AppEvent 类的data属性为Dictionary<string, Object>类型实例，包含以下的元素：
"layer" : ESRI.ArcGIS.Client.layer类型
"visible" : 布尔类型(true/false)

触发事件示例：
Dictionary<string, Object> data = new Dictionary<string, Object>();
ESRI.ArcGIS.Client.Layer ly = getLayer("layer");
data.Add("layer", ly);
data.Add("visible",false);
ViewerContainer.dispatchEvent(AppEvent.MAP_LAYER_VISIBLE,
new ppEvent(data));
BASEMAP_SWITCH
切换基础地图图层显示的事件。
AppEvent 类的data属性为int类型的图层ID(layerID);

触发事件示例：
string label ="Streets Map";
Dictionary<int, Dictionary<string, string>> BaseMaps =
configData.Basemaps;
for (int i = 0; i < BaseMaps.Count(); i++)
{
if (label == BaseMaps[i]["label"])
{
ViewerContainer.dispatchEvent(AppEvent.BASEMAP_SWITCH,
new AppEvent(i));
break;
}
}
WIDGET_RUN
用于运行指定Widget的事件。
AppEvent 类的data属性为int类型的Widget标识;

触发事件示例：
ViewerContainer.dispatchEvent(AppEvent.WIDGET_RUN, new AppEvent(id));
WIDGET_BROADCAST
Widget的广播事件，所有Widget都默认收到该事件。
AppEvent 类的data属性为Dictionary<string, Object>类型实例，内容自定;

触发事件示例：
Dictionary<string, Object> data = new Dictionary<string, object>();
data["closewidget"] = 10;
ViewerContainer.dispatchEvent(AppEvent.WIDGET_BROADCAST,
new AppEvent(data));

处理事件示例（Widget）：
protected override void ProcessBroadcast(Dictionary<string, object> data)
{
……
}
SET_MAP_NAVIGATION
用于指定地图当前导航操作的事件，所有Widget可调用setMapNavigation(String navMethod, String status) 方法触发该事件。
AppEvent 类的data属性为Dictionary<string, Object>类型实例，包含以下的元素：
" tool " : 当前导航任务，主要包含：
pan 移动地图(Navigation.PAN)
zoomin 放大地图(Navigation.ZOOM_IN)
zoomout 缩小地图(Navigation.ZOOM_OUT)
zoomfull 全景地图(ViewerContainer.NAVIGATION_ZOOM_FULL)
zoomprevious 地图上一场景(ViewerContainer.NAVIGATION_ZOOM_PREVIOUS)
zoomnext 地图下一场景(ViewerContainer.NAVIGATION_ZOOM_NEXT)
" status " : 当前状态信息

触发事件示例：
setMapNavigation("pan", "移动");
SET_MAP_ACTION
用于获得地图画图操作的事件所有Widget可调用setMapAction(string action, string status, EventHandler<DrawEventArgs> callback) 方法触发该事件。
AppEvent 类的data属性为Dictionary<string, Object>类型实例，包含以下的元素：
" tool " : 当前画图方法，主要包含：
point 画点(DrawMode.Point)
rectangle 画矩形(DrawMode.Rectangle)
polyline 画线(DrawMode.Polyline)
polygon 画多边形(DrawMode.Polygon)
freehand 手画(DrawMode.Freehand)

" status " : 当前状态信息
" handler " : drawEnd事件句柄

触发事件示例：
setMapAction(value, status, drawEnd);
private void drawEnd(object sender,DrawEventArgs e)
{
……
}
DATA_PUBLISH
发布新的共享数据的事件，所有Widget可调用addSharedData(string key, List<object> list)方法触发该事件。
AppEvent 类的data属性为Dictionary<string, Object>类型实例，内容为：
数据标识1: 数据内容
……
数据标识n: 数据内容

触发事件示例：
Dictionary<string, Object> data = new Dictionary<string, object>();
data.Add(key, this);
ViewerContainer.dispatchEvent(AppEvent.DATA_PUBLISH, new AppEvent(data));
监听事件示例：
ViewerContainer.addEventListener(AppEvent.DATA_PUBLISH,
new ViewerEventHandler(datapublish));

private void datapublish (object sender, AppEvent e)
{
……
}
DATA_NEW_PUBLISHED
当新的数据被加到共享数据池时触发的事件。
AppEvent 类的data属性为Dictionary<string, Object>类型实例，内容为：
数据标识1: 数据内容
……
数据标识n: 数据内容

监听事件示例：
ViewerContainer.addEventListener(AppEvent.DATA_NEW_PUBLISHED,
new ViewerEventHandler(datanewpublish));

private void datanewpublish (object sender, AppEvent e)
{
……
}
DATA_FETCH_ALL
发出获得所有共享数据池中数据申请的事件，事件将会触发DATA_SENT事件，所有Widget可调用fetchSharedData()方法触发该事件。
AppEvent 类的data属性为null

触发事件示例：
this. fetchSharedData ();
DATA_FETCH
发出获得指定共享数据池中数据申请的事件，事件将会触发DATA_SENT事件。
AppEvent 类的data属性为Dictionary<string, Object>类型实例，内容为：
数据标识1: 数据内容
……
数据标识n: 数据内容

触发事件示例：
String key = “key1”;
ViewerContainer.dispatchEvent(AppEvent.DATA_FETCH, new AppEvent(key));
DATA_SENT
由共享数据池发出的响应数据查看申请(DATA_FETCH、DATA_FETCH_ALL)的事件。
AppEvent 类的data属性为Dictionary<string, Object>类型实例，内容为：
数据标识1: 数据内容
……
数据标识n: 数据内容

监听事件示例：
ViewerContainer.addEventListener(AppEvent.DATA_SEND,
new ViewerEventHandler(datasend));

private void datasend (object sender, AppEvent e)
{
……
}
SHOW_INFOWINDOW
显示信息窗口事件，所有Widget可调用showInfoWindow(Dictionary<string, Object>)方法触发该事件。
AppEvent 类的data属性为Dictionary<string, Object>类型实例，包含以下的元素：
" icon " : 信息的图标
" title " : 信息的标题内容
" link " : 信息的链接信息
" point " : 信息在图上显示的位置(ESRI.ArcGIS.Client.Geometry.MapPoint)
" geometry " : 信息对应的几何元素(ESRI.ArcGIS.Client.Geometry)

触发事件示例：