[Info] How to implement properties in custom TRichView items

[Sergey Tkachenko]

The question of Implementation of custom item types is not covered in TRichView manual
("item" is an object that can be inserted in TRichView document, such as picture, equation, etc.)

This topic contains some information about custom items.

Normally, an item occupies a rectangular area in document, and can be placed inline in text. Such items must be inherited from TRVRectItemInfo class (RVItem.pas).
If you want to extend an existing item type with additional properties, inherit your class from the proper item type. For example, from TRVLabelItemInfo (RVLabelItem.pas)

Each item must have a unique identifier. It is a negative integer number.
A list of used numbers is here: https://www.trichview.com/help/idh_const_rvsxxx.html
This identifier must be assigned to StyleNo property in constructor.
You must override the constructor Create(ARVData: TPersistent).
If you want custom painting, override Paint method. If you want custom printing, override Print method (there is also an option of drawing to bitmap, and then printing this bitmap)

[Sergey Tkachenko]

The best method to add additional properties to items is implementation of "extra integer properties" and "extra string properties".
With the proper implementation, these properties can be stored in RVF files. In an editor, you will be able to assign values to these properties as an editing operations (undoable by the users).
You can use the following methods for integer properties:

• TRichView.GetExtraItemIntPropertyEx
• TRichView.SetExtraItemIntPropertyEx
• TRichViewEdit.SetItemExtraIntPropertyExEd
• TRichViewEdit.GetCurrentItemExtraIntPropertyEx
• TRichViewEdit.SetCurrentItemExtraIntPropertyEx

For string properties:

• TRichView.GetExtraItemStrPropertyEx
• TRichView.SetExtraItemStrPropertyEx
• TRichViewEdit.SetItemExtraStrPropertyExEd
• TRichViewEdit.GetCurrentItemExtraStrPropertyEx
• TRichViewEdit.SetCurrentItemExtraStrPropertyEx

Of course, instead of these methods, you can get your item object (TRichView.GetItem, TRichViewEdit.GetCurrentItem), and then work with properties of your object directly. But direct assignment to these properties is not en editing operation (and cannot be undone by the user).

If you need Boolean, TColor or enum properties, you can use integer properties (by converting value to Integer)
If you need TStringList property, you can use string properties (by accessing StringList.Text)

[Sergey Tkachenko]

First, you need to choose integer identifiers for your properties.
Here is a list of used identifiers for integer properties:
https://www.trichview.com/help/idh_const_rveipcxxx.html
For string properties:
https://www.trichview.com/help/idh_const_rvespcxxx.html

These identifiers are not necessary globally unique. For example, value 200 is used for many identifiers.
But identifiers must be unique for the item type.
So, if you inherit your item from TRVLabelItemInfo, you cannot use value 200, because it is already used. You can start your property identifiers from 300.
I do not recommend starting your numbers immediately when numbers of the parent item type end. For example, TRVLabelItemInfo uses identifiers up to 206. It's a bad idea to use 207 for your item, because there is a chance that a new property will be added to TRVLabelItemInfo later, and it will use this identifier.

Next, you need to choose string identifiers for your properties. These identifiers will be used to store your properties in RVF file.

[Sergey Tkachenko]

For integer properties, override the following methods:
SetExtraIntPropertyEx, GetExtraIntPropertyEx, and optionally GetExtraIntPropertyReformat
For string properties, override the following methods:
SetExtraStrPropertyEx, GetExtraStrPropertyEx, and optionally GetExtraStrPropertyReformat
For any type of properties, override
SetExtraCustomProperty, GetRVFExtraPropertyCount, SaveRVFExtraProperties


GetExtraStrPropertyReformat and GetExtraStrPropertyReformat informs the editor what should be done when assigning this property as an editing operation.
Possible result values:
rvrfNone - nothing (the property does not affect visual appearance) - default for string properties
rvrfNormal - normal reformatting (the property may affect size of the item) - default for integer properties
rvrfFull - assignment to this property requires the complete reformatting of the whole document
rvrfRepaint - repainting (the property affect visual appearance of the item but not its size)
rvrfSRVRepaint - (in ScaleRichView) repainting of the full component
rvrfSRVReformat - (in ScaleRichView) reformatting of the full component

[Sergey Tkachenko]

As an example of implementation of custom properties, you can see the equation item (<TRichView Dir>\Math\Source\RVMathItem.pas)

It implements integer properties with identifiers:

Code: Select all

  rveipcFontSizeDouble = 200;
  rveipcTextColor = 201;
  rveipcDisplayInline = 202;

String properties with identifiers:

Code: Select all

  rvespcText = 200;
  rvespcFontName = 201;

For storing in RVF, it implements property names:

Code: Select all

const
  rveipcMath_First = rveipcFontSizeDouble;
  rveipcMath_Last  = rveipcDisplayInline;

  rvespcMath_First = rvespcText;
  rvespcMath_Last = rvespcFontName;

const
  IntPropertyNames: array [rveipcMath_First .. rveipcMath_Last] of PRVAnsiChar =
    ('fontsize_double', 'text_color', 'display_inline');

  StrPropertyNames: array [rvespcMath_First .. rvespcMath_Last] of PRVAnsiChar =
    ('text', 'fontname');

You can see implementation of the methods listed above your self in RVMathItem.pas