ImageGear .NET
Client-Side API
| User Guide > How to Work with... > ASP.NET > Displaying Images using ASP.NET > Client-Side API |
The client-side API resides in three ASP.NET client-side controls: PageView Class, ThumbnailView Class, and ImGearThumbnailList Class. These controls rely on the framework that Microsoft introduced in ASP.NET 2.0.
The ImGearThumbnailList Class properties will acquire the current state of the associated server-side property SelectedPages.
 |
If you are binding documents to the ImGearThumbnailList control from the server side and setting specific properties on the server side then you should do this every time you load the pages containing the ImGearThumbnailList control. |
These controls are supported by a few enumerations and other classes and expose an easy, but powerful viewing API. Normally, you will want to develop as much of your viewer functionality as possible in JavaScript to avoid round-trips to the server. The client portion of ImageGear will automatically interact with the server portion using AJAX calls to support whatever viewing operations you have requested via the client API.
In addition to the viewing functionality, these controls expose a rich API for adding, editing, or deleting marks or annotations to your images. Marks can also be interactively added, edited, and deleted via a set of mouse tools and context menus.
If your application is based on ASP.NET postbacks, then the server-side PageView and ThumbnailView controls will automatically save your annotations. The ImGearThumbnailList control does not use postbacks for saving annotations; it uses services.
If your application does not utilize postbacks, and you wish to save your annotations when using either the PageView or ThumbnailView controls, use the saveArtPage methods to save the annotations. In the ImGearThumbnailList client control, use the saveArtData method. The ImGearThumbnailList.saveArtData method will save only pages where annotation changes are made including creation of new annotation objects.
The ImageGear ASP.NET PageView control provides the ability to customize the behavior of its context menu.
Using the public API available in the PageView control, you can show and hide the context menu (see showContextMenu and hideContextMenu for details). You can also catch and process an event when the user activates the context menu (see contextMenu event for details).
If your application requires customization of the existing context menu such as adding new menu items with the corresponding events, deleting existing items, changing the context menu item text, or changing the behavior of the context menu item, this can be achieved with the use of the context menu API provided by the JavaScript PageView control. This API includes setContextMenu, setContextMenuForTool, getDefaultContextMenu, and getContextMenu methods that could be used to customize the context menu of the PageView control.
See Context Menu Customization for more information.
For client-side errors, ImageGear uses the ASP.NET client-side trace facility (Sys.Debug.trace), as well as a global function, onImageGearItemLogged(), that you can create to receive notification of logged items. Refer to the PageView.debug Property for more information.
For more information about the client-side API, refer to the ImageGear.Web.UI Namespace Client API Library Reference.
A web application can track failures occurring during the opening of images. This can be done using the pageOpenFailed event. This event is fired whenever an image fails to open with an openImage call in the PageView or ThumbnailView client controls. The ImGearThumbnailList client control fires the pageAddFailed event when a page fails to load in the control.
The event argument ImageGear.Web.UI.ImGearPageOpenFailedEventArgs contains an error object of one of the following types:
The ImGearHttpException gives some information about an error occurring on the server when trying to open an image. In particular, if you are using a custom data provider, then you can use the ImGearHttpException object to pass information about an error occurring on the server in the parameter “customErrorCode”.
 |
The “statuscode” parameter for this object must be one of the standard HTTP error codes. Also, when you are using a custom provider, make sure that you never pass a statuscode of 200 when there is an error. The statuscode value of 200 means there was no error. |
All other error exceptions objects reflect errors occurring in the client side code.