FileHold viewers - Custom preset annotations

 

Annotation property descriptions

The table below describes the available options for the annotation properties.

ID	Name	Type	Description
borderWidth	Border width	Float	In viewer dialogs, this value is multiplied by 96, i.e. 0.2 is presented as 19.2. Predefined values: Extra thin – 0.01 Thin – 0.02 Normal – 0.04 Strong – 0.08 Very strong – 0.1
dashCap	Dash cap	Int	Applicable only when dash style is other than solid. Allowed values: 0 – flat 2 – round 3 – triangle More details here
dashStyle	Dash style	Int	Allowed values: 0 – solid 1 – dash 2 – dot 3 – dash dot 4 – dash dot dot More details here
startCap	Start cap	Int	Cap style used at the start of drawn line. Allowed values: 0 – flat 1 – square 2 – round 3 – triangle 16 – no anchor 17 – square anchor 18 – round anchor 19 – diamond anchor 20 – arrow anchor 240 – anchor mask More details here
endCap	End cap	Int	Cap style used at the end of drawn line. Allowed values are the same like for startCap property.
fillColor	Fill color	String	Hexadecimal color code, i.e. #FFFFFF
stroke	Stroke	Boolean	Determines whether a stoke should be visible or not. Allowed values: True False
strokeColor	Stroke color	String	Hexadecimal color code, i.e. #FFFFFF
fontName	Font name	String	Name of font to be used to render the text
fontSize	Font size	Int	Font size in pixels
fontStyle	Font style	Int	Allowed values: 0 – regular 1 – bold 2 – italic 4 – underline 8 – strikeout
foreColor	Text color	String	Hexadecimal color code, i.e. #FFFFFF
alignment	Horizontal alignment	Int	Allowed values: 0 – left 1 – center 2 – right
lineAlignment	Vertical alignment	Int	Allowed values: 0 – top 1 – middle 2 – bottom
text	Text	String	Text value to be displayed as annotation content.
autoSize	Auto size	Boolean	Determines whether annotation should be automatically resized to its contents or not. Allowed values: True False
squaredBox	Squared box	Boolean	Determines whether annotation should have the same width and height. Allowed values: True False
radiusFactor	Radius factor	Float	Determines (in %) how rounded should be drawn borders. 0 means 0% rounded borders, 1 means 100% rounded borders. Allowed float numbers in the range from 0 to 1.
measurementUnit	Measurement unit	Int	Determines a unit to be presented next to the calculated distance. Allowed values: 0 – pixel 1 – inch 2 – centimeter 3 – millimeter
scale	Scale	Float	Determines a scale of the ruler. Presented distance will be calculated with this formula: distance = inches * scale
arrowFilled	Arrow filled	Boolean	Determines whether arrow should be filled or not. Allowed values: True False
arrowHeight	Arrow height	Int	Determines height of the arrow in inches.
arrowWidth	Arrow width	Int	Determines width of the arrow in inches.
opacity	Opacity	Float	Determines (in %) an opacity (or blending level) of the annotation. 0 means full transparency, 1 means full opacity. Allowed float numbers in the range from 0 to 1.
rotation	Rotation	Int	Determines (in °) a rotation of the annotation. Allowed integers in the range from 0 to 360.

 

Managing annotation presets

Annotation presets are managed directly within the Microsoft SQL database. This section describes how to add, edit, and delete annotation presets. Each operation has its own stored procedure in the ch_librarymanager database.

Each operation in the database should be executed with an active transaction. Only data from successfully executed scripts is applied to the database. The example below describes how to execute a SQL query within a transaction.

BEGIN TRY
       BEGIN TRANSACTION
       -- <<< start of query to execute

       -- write here some query
    
       -- >>> end of query to execute
       COMMIT
END TRY
BEGIN CATCH
       IF @@TRANCOUNT > 0 ROLLBACK TRAN

       DECLARE @error NVARCHAR(4000) = ERROR_MESSAGE()
       RAISERROR( @error, 16, 1)
END CATCH

Stored Procedures

The following are the stored procedures for annotation presets and their allowed parameters.

ch_AddViewerAnnotationPreset

Add an entry to the ViewerAnnotationPresets table.

Param name	Type	Is output	Description
@annotationType	Integer	No	Annotation type ID
@name	String	No	Preset name, max 100 characters
@presetId	Integer	Yes	Returns ID of created preset

 

ch_SetViewerAnnotationPresetValue

Add or edit annotation preset value (modifies ViewerAnnotationPresetValues table).

Param name	Type	Is output	Description
@presetId	Integer	No	ID of annotation preset of which property should added or modified
@propertyId	String	No	Identified of the property which should be added or modified
@value	String	No	Value of the annotation property. Regardless of the property type, each value should be written as string
@visible	Boolean	No	Determines whether property should be displayed in UI dialog when adding an annotation preset to the document. If all properties in preset are set to be invisible, an UI dialog when adding annotation will NOT be displayed. Allowed values: 0 – hide (default value) 1 – show

 

ch_UpdateViewerAnnotationPreset

Update annotation preset name.

Param name	Type	Is output	Description
@presetId	Integer	No	ID of the annotation preset to be modified
@name	String	No	Preset name to be updated

 

ch_RemoveViewerAnnotationPreset

Remove annotation preset from the database.

Param name	Type	Is output	Description
@presetId	Integer	No	ID of the annotation preset to be removed

 

Adding annotation presets

In order to add annotation preset, the following two stored procedures need to be executed:

• ch_AddViewerAnnotationPreset – Execute only once.
• ch_SetViewerAnnotationPresetValue – Execute zero or many times - repeat for each property.

Note: Since all default values for each annotation type is stored in the system database, there is no need to duplicate properties with default values in the annotation presets. In another words, annotation presets should consist of only the properties of which values are different that default ones.

For example, adding a rubber stamp annotation preset called “Edited in” that consists of following values:

• border color: #00FF00
• text size: 16
• text color: #00FF00
• text: “FileHold”

BEGIN TRY
       BEGIN TRANSACTION
       -- <<< start of query to execute

       DECLARE @presetId INT
       EXEC ch_AddViewerAnnotationPreset 0, 'Edited in', @presetId OUTPUT

       EXEC ch_SetViewerAnnotationPresetValue @presetId, 'strokeColor', '#00FF00'
       EXEC ch_SetViewerAnnotationPresetValue @presetId, 'fontSize', '16'
       EXEC ch_SetViewerAnnotationPresetValue @presetId, 'foreColor', '#00FF00'
       EXEC ch_SetViewerAnnotationPresetValue @presetId, 'text', 'FileHold'

       -- >>> end of query to execute
       COMMIT
END TRY
BEGIN CATCH
       IF @@TRANCOUNT > 0 ROLLBACK TRAN

       DECLARE @error NVARCHAR(4000) = ERROR_MESSAGE()
       RAISERROR( @error, 16, 1)
END CATCH

The stamp would appear as:

Image

Modifying annotation presets

In order to modify annotation presets, the following two stored procedures need to executed:

• ch_UpdateViewerAnnotationPreset – zero or once
• ch_SetViewerAnnotationPresetValue – zero or many times - repeat for each property

For example, changing the name of the annotation preset from “Edited by” to “Edited at” and set following properties:

• dash style: dash
• fill color: #FFFFFF
• text: “[[sys|now|yyyy-MM-dd HH:mm:ss]]” . This dynamic field will be automatically replaced with the current date and time. For a list of available tags, see Assemble document tags.
• border width: solid (0.08 inch)

BEGIN TRY
       BEGIN TRANSACTION
       -- <<< start of query to execute

       DECLARE @presetId INT
       SELECT @presetId = PresetId FROM ViewerAnnotationPresets WHERE PresetName like 'Edited in'

       EXEC ch_UpdateViewerAnnotationPreset @presetId, 'Edited at'

       EXEC ch_SetViewerAnnotationPresetValue @presetId, 'borderWidth', '0.08'
       EXEC ch_SetViewerAnnotationPresetValue @presetId, 'dashStyle', '1'
       EXEC ch_SetViewerAnnotationPresetValue @presetId, 'fill', 'true'
       EXEC ch_SetViewerAnnotationPresetValue @presetId, 'fillColor', '#FFFFFF'
       EXEC ch_SetViewerAnnotationPresetValue @presetId, 'text', '[[sys|now|yyyy-MM-dd HH:mm:ss]]'

       -- >>> end of query to execute
       COMMIT
END TRY
BEGIN CATCH
       IF @@TRANCOUNT > 0 ROLLBACK TRAN

       DECLARE @error NVARCHAR(4000) = ERROR_MESSAGE()
       RAISERROR( @error, 16, 1)
END CATCH

The stamp would appear as:

Image

Removing annotation presets

To delete annotation preset, execute following stored procedure:

• ch_RemoveViewerAnnotationPreset

The example below shows how to delete annotation preset with name “Edited at”. All property values associated with this preset will be removed automatically.

BEGIN TRY
       BEGIN TRANSACTION
       -- <<< start of query to execute

       DECLARE @presetId INT
       SELECT @presetId = PresetId FROM ViewerAnnotationPresets WHERE PresetName like 'Edited at'

       EXEC ch_RemoveViewerAnnotationPreset @presetId

       -- >>> end of query to execute
       COMMIT
END TRY
BEGIN CATCH
       IF @@TRANCOUNT > 0 ROLLBACK TRAN

       DECLARE @error NVARCHAR(4000) = ERROR_MESSAGE()
       RAISERROR( @error, 16, 1)
END CATCH