Log In
Home
Support
Demos
Documentation
Blogs
Training
Webinars
[Expand]General Information
[Collapse]WinForms Controls
  Prerequisites
 [Expand]What's Installed
 [Expand]Build an Application
 [Collapse]Controls and Libraries
  [Expand]Forms and User Controls
  [Expand]Messages, Notifications and Dialogs
  [Expand]Editors and Simple Controls
  [Expand]Ribbon, Bars and Menu
  [Expand]Application UI Manager
  [Expand]Docking Library
  [Expand]Data Grid
  [Expand]Vertical Grid
  [Expand]Pivot Grid
  [Expand]Tree List
  [Expand]Chart Control
  [Expand]Diagrams
  [Expand]Gauges
  [Expand]Map Control
  [Expand]Scheduler
  [Expand]Spreadsheet
  [Expand]Rich Text Editor
  [Expand]Spell Checker
  [Expand]Form Layout Managers
  [Expand]Navigation Controls
  [Expand]Printing-Exporting
  [Expand]PDF Viewer
   Reporting
  [Collapse]Snap
   [Expand]Product Information
   [Expand]Getting Started
   [Collapse]Fundamental Concepts
    [Expand]Graphical User Interface
     Supported Formats
    [Collapse]Developer Guidelines
      Application Programming Interface
      Snap Commands
      Snap List and Document Template
      Snap Fields
      Snap Document Events
      Globalization (Units of Measurement)
    [Expand]Data Acquisition
    [Expand]Data Shaping
   [Expand]Examples
  [Expand]TreeMap Control
 [Expand]Common Features
  Get More Help
 [Expand]API Reference
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Document Server
[Expand]Reporting
[Expand]Report Server
[Expand]Dashboard
[Expand]eXpressApp Framework
[Expand]CodeRush
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation

Snap Document Events

This topic describes the hierarchy and structure of specialized events in Snap.

In addition to rich text related events inherited from the Document interface, SnapDocument provides many events that you can handle to implement custom document templates.

For a code example on using Snap-specific events, see How to use SnapDocument events to customize the default templates of Snap lists and columns.

With the exception of the SnapDocument.ConnectionError event that assists the data connection process, the following events occur when dropping data fields from the Data Explorer onto a document, allowing you to modify the structure and formatting of the resulting table. These events correspond to the following user scenarios.

Expanded Create a New List

The first group of events maintains the creation of a new list in a document.

  • SnapDocument.BeforeInsertSnList

    Handle this event to customize the order in which fields are added and their position in a document.

    The nesting level of fields in the resulting document list depends only on the data source structure.

    Specifying an empty field set creates no new fields in the document.

  • SnapDocument.PrepareSnList

    Based on the field set obtained, maintains the structure of a default list template (a regular table-like SnList). You can customize the resulting template using the Snap API.

    For example, you can add custom text, or access a list by traversing its fields, to apply a custom ListHeader/ListFooter/RowTemplate or add group/sort/filter criteria. (For a code example, refer to How to use SnapDocument events to customize the default templates of Snap lists and columns.)

    The changes made to the list template will be applied to the document after all other event handlers expire.

  • SnapDocument.AfterInsertSnList

    Fires after a new list has been added to a document. Maintains the document range of the added content.

    This event does not fire if a list was not added for any reason.

Expanded Add Columns to a List

The following image illustrates the creation of new columns in an existing list using the vertical hot zone.

The following three events maintain this scenario.

  • SnapDocument.BeforeInsertSnListColumns

    Maintains the creation of a new set of columns in a document, and provides the following arguments.

    1. BeforeInsertSnListColumnsEventArgs.Target - specifies the list to which the columns are added.

    2. BeforeInsertSnListColumnsEventArgs.TargetColumnIndex - specifies the position in which the columns are added.

    For a table that consists of N columns, this parameter will get the following values:

    - 0 when inserting new columns to the left;
    - 1 when inserting new columns between the first and second columns;
    - N when inserting new columns to the right.

    3. BeforeInsertSnListColumnsEventArgs.DataFields - specifies the fields to add. You can customize the set and/or order of the fields. Specifying null or an empty field set creates no new fields in the document.

  • SnapDocument.PrepareSnListColumns

    Fires as many times as there are new columns being added. The event arguments contain two default templates:

    - a column header template that only contains the field name;
    - a field template that contains the data records.

    Specifying null in this template creates no new column headers in the document. This can take place if no header is specified for the original table, or the specified header has an unacceptable structure.

  • SnapDocument.AfterInsertSnListColumns

    Fires after all columns have been successfully created, and returns a resulting list in its arguments.

    This is the last chance to customize the list before document generation (for example, to implement grouping, sorting and/or filtering).

    This event does not fire if the add operation was not completed for any reason.

Expanded Insert a Nested List

The following image illustrates the creation of a new list (nested into an existing list) using the horizontal hot zone.

The following three events maintain this scenario (listed in the order in which they are triggered).

Expanded Add Fields to a List

The following two events add fields to an existing list without using hot zones.

  • SnapDocument.BeforeInsertSnListRecordData

    Fires when adding fields to a list without using hot zones (this is only possible if the target list has been previously converted to paragraphs). This event provides the following arguments.

    1. BeforeInsertSnListColumnsEventArgs.Target - provides access to the list to which the fields are being added. Making changes to the list during this event is only safe when passing it with a null set of fields (see below).

    2. BeforeInsertSnListColumnsEventArgs.TargetColumnIndex - indicates the column index to which the fields are added. (If the target list was previously converted to paragraphs, the value is -1.)

    3. BeforeInsertSnListColumnsEventArgs.DataFields - specifies the fields to add. You can customize the set and/or order of the fields. Specifying null or an empty field set results in no fields being added.

  • SnapDocument.AfterInsertSnListRecordData

    Fires after new fields have successfully been added. In its arguments, indicates the document range to which the new content has been applied.

    This event does not fire if the add operation was not completed for any reason.

    During this event execution, the input focus belongs to the target list's record, and the specified changes have not yet been applied to the entire document template (and therefore, not applied to other records). For this reason, refreshing the field result of the list during this stage will result in losing all changes made to the record.

How would you rate this topic?​​​​​​​