. : MapViewer Control : .
Version 2.0.0.0

     


 . : General Information
This control provides functionality similar to the well known UOMap.ocx ActiveX control. The main difference between UOMap and MapViewer is the type of control. MapViewer is a C# control, making it somewhat more reliable because you're sure your application is going to use exactly the version you used when programming.
 : .

 . : Using the control

I am not going to provide detailed information on the use of this control because if you're going to use it, you most likely know what you're doing already ;) You can use this control as any other control in a development environment as Visual Studio. Just add it to your project and drag it to your form.

Make sure that when you reference the control inside your project, the MapViewer.xml file is in the same folder as the dll. This will add the IntelliSense functionality which provides you with a short explanation of all the available classes, methods and properties.

 : .

 . : Draw Objects

You can add your own custom objects on the map surface by creating a class that implements the TheBox.MapViewer.DrawObjects.IMapDrawable interface which is composed of two methods:

  • bool IsVisible( Rectangle bounds, Maps map );
  • void Draw( Graphics g, MapViewInfo ViewInfo );

The IsVisible method determines if the object is visible for the current view of the map. the bounds parameter is a rectangle in map coordinates that specifies the map area visible on the control. map is an enumeration value specifying which map is currently displayd.

The Draw method implements the actual drawing and is called only when IsVisible returns true. The MapViewInfo class provides access to the logic governing the control surface and its mapping into map coordinates. It provides methods to convert points and distances from map coordinates to control coordinates and vice versa. Implementation of this method is strictly dependant on the type of object you're drawing. I might add some examples to the documentation if there's such a request.

The control includes a few basic objects you can already use. They are located in the TheBox.MapViewer.DrawObjects namespace and they are a rectangle, a circle and a cross. I might add more in future releases.

 : .

 . : Bug reports and support
All support for this program is provided through The Box website.
 : .

 . : Requirements

MapViewer is a .NET control, therefore it requires the .NET Framework redistributable (version 1.1) installed on the target system to operate.

Since version 2.0 MapViewer also requires the "Box Common Library" (BoxCL.dll) to be present in the MapViewer.dll folder (or in your application folder if you're re-using code). The BoxCL.dll library provides the MulManager class used to manage the location of UO files. If you don't want to use BoxCL.dll you'll have to write your own file location routines. The source of BoxCL.dll is not being released for now, but an XML file for Intellisense will be provided.

 : .

 . : Version History
1.0.0.0

August 16, 2003 - First release of the control. Functionalities implemented:

  • All the main functionality needed to display the map
  • Zooming
  • Draw Objects (rectangle, circle and cross included) with support for user created objects (must implement IMapDrawable)
 
1.0.1.0

September 18 , 2003

  • Fixed an issue with the ClientPath property. If set to null it will now read information from the registry. Make sure you ship your software with this property set to null to avoid the users having to set the mul path manually. null is considered as a default value meaning that the path will be retrieved from the registry.
  • ClientPath is now validated in order to ensure that it contains the required files. If the path is not valid, the previous value is not altered.
  • Exposed the Zoom property in the MapViewInfo object.

NOTE: If you're upgrading existing software from 1.0.0.0 to 1.0.1.0, you have to remove or set to null your existing ClientPath value.

 

 
2.0.0.0

May 13, 2004

This new version of the MapViewer control is the one bundled with Pandora's Box 2 and comes with several new features.

  • Navigation property: allows you to use built in map navigation specifying which mouse button should be considered as the input for map movement (MapNavigation enumeration).
  • WheelZoom property: allows you to use the mouse wheel to perform zooming in the map.
  • MulManager and static MulFileManager properties. This is the new system used to locate UO files. The MulManager class is located in the BoxCL.dll library (aka Box Common Library) which allows the MulManager class to be created and managed in your application and then assigned to either the MapViewer object or class from your code. BoxCL.dll is a required component of the MapViewer and it will not function properly without it. If you're using the MapViewer source code you must add a reference to BoxCL.dll to your project, or write a new file managment. The source of BoxCL.dll will not be released at this time.
  • [Unsupported] ExtractMap() function: this function saves a JPEG image of a map to disk. This function hasn't been tested so is provided without support. Use at your own risk.
  • [Unsupported] RotateView property: this property allows to see the map rotated by 45° making it similar to the radar map in the UO game window. Keep in mind that this mode required to load a much larger portion of the map therefore it may slow down the MapViewer performance. This feature can lead to unexpected results in certain cases (depending on the control size). If the result is not what you're expeting try changing your control width/height by 1 or 2 pixels.
  • ClientPath property removed: use MulManager.CustomFolder.
 : .





this document is based on the fade out web templated create by clouser 2002©
modified by Arya
.: this machine will not communicate :.