Rich Text

AddCitation

Description

Appends one or more source citations to the current contents of a RichText object. It takes an item pointer as its first parameter. If this is a link to a source record (that is, a source citation itself), it will add this source citation. If it is anything else, it will look for all source citations (items with tag SOUR) that are immediate children of this item, and (subject to the second parameter) add them as source citations. The second parameter, bExcludeEmbeddedCitations, is only applicable if the first parameter points to a rich text item. If it does, any source citations that are embedded in the rich text item will not be added, unless bExcludeEmbeddedCitations is set to false.

Rich text items can have both embedded and non-embedded source citations. User can add non-embedded source citations to a rich text item in exactly the same way that they can source citations to anything else - in the yellow Citation List pane of the Property Box. Embedded source citations can only be added in the Note Window.

When citations are added to the rich text, they are normally appended to the end of the existing rich text contents. The only exception is if the existing rich text ends with one or more spaces, tabs, carriage returns or line feed characters. In that case, the citation will be inserted just before these trailing characters.

The function returns the number of citations added.

Syntax

iCitations = rt:AddCitation(ptr, bExcludeEmbeddedCitations)

Parameters

ptr: item pointer: the source citation to add, or the 'owner' of the source citations to add (see description above).
bExcludeEmbedded: Optional. Defaults to true if not supplied, and is only applicable, in any case, if the first paramter, ptr, is a rich text item.

Return Value

iCitations: integer: the number of citations added.

Remarks

Example

pi = fhNewItemPtr()
 
... (set pi to point to appropriate item) ...
 
rt = fhNewRichText()
rt:AddText("An <u>important</u> point")
rt:AddCitation(pi)