-
Notifications
You must be signed in to change notification settings - Fork 4
IProject
A non-resource Paratext project
ProjectDataChangedHandler ProjectDataChanged
Raised when a Project setting or other data is changed.
Action ProjectDeleted
Raised when the project is deleted
ScriptureDataChangedHandler ScriptureDataChanged
Raised when the Project's Scripture content is changed.
NOTE: The book number will be zero if the content of multiple books changed. The chapter number will be zero if the content of multiple chapters changed.
IReadOnlyList<IBookInfo> AvailableBooks
Gets the books that are available in the project.
IReadOnlyList<ILanguage> AvailableNotesLanguages
Gets all the languages available to be used when creating notes for this project.
NOTE: This includes any that are defined in the project plus any others defined (locally) in Paratext.
IProject BaseProject
Gets the base project; or null, if not based on another project.
IBiblicalTermList BiblicalTermList
Gets the list of biblical terms associated with this project.
NOTE: If enumerating the terms, caller should subscribe to ProjectDataChanged, so that if ProjectDataChangeType.DataBiblicalTerms changes, it does not continue enumerating them.
bool CanBeRegistered
Gets whether the project can be registered on the Paratext Registry
NOTE: IsRegistered
IReadOnlyList<IMarkerInfo> FrontBackMarkerInformation
Gets information about all the markers defined for front and back matter in this project. Each entry will be a IParagraphMarkerInfo, ICharacterMarkerInfo, or INoteMarkerInfo.
NOTE: IParagraphMarkerInfo, ICharacterMarkerInfo, INoteMarkerInfo
string ID
Gets the unique ID of the project
bool IsRegistered
Gets whether the project has been registered on the Paratext Registry
NOTE: This will always return false for projects that can not be registered.
CanBeRegistered
bool IsResource
Returns a boolean value determining if the read-only project is a resource
IProjectLanguage Language
Gets the language of the project.
string LanguageName
Gets the name of the language as associated with this project.
NOTE: This may or may not match one of the known names associated with the language identified by ILanguage.Id
string LongName
Gets the long name of the project
IReadOnlyList<IUserInfo> NonObserverUsers
Gets the users who have a non-Observer role on the project.
NormalizationType NormalizationType
The normalization form used by the project
IKeyboard NotesKeyboard
Gets the "notes" keyboard (i.e., the keyboard for the default language used to write project notes. Often a LWC). Can be null.
IReadOnlyList<IMarkerInfo> ScriptureMarkerInformation
Gets information about all the markers defined for Scripture books in this project. Each entry will be a IParagraphMarkerInfo, ICharacterMarkerInfo, or INoteMarkerInfo.
NOTE: IParagraphMarkerInfo, ICharacterMarkerInfo, INoteMarkerInfo
string ShortName
Gets the short name of the project
ProjectType Type
Gets the type of project
USFMVersion USFMVersion
The version of USFM used by the project
IKeyboard VernacularKeyboard
Gets the default vernacular keyboard. Can be null.
IVersification Versification
Gets the versification used by the project
IProjectNote AddNote(IWriteLock writeLock, IScriptureTextSelection anchor, IEnumerable< CommentParagraph > contentParagraphs, ILanguage language=null, IUserInfo assignedUser=null)
Adds a project note
NOTE: Plugins can create their own implementations of IScriptureTextSelection or use FindMatchingScriptureSelections to get selections to pass as the anchor for a new note.
| Parameter | Description |
|---|---|
| return value | The newly added note |
| writeLock | The write lock previously obtained by a call to RequestWriteLock(IPluginObject,Action<IWriteLock>,WriteLockScope) with a scope of WriteLockScope.ProjectNotes |
| anchor | A selection in the Scripture text representing the "anchor" location of the note. Note that the IScriptureTextSelection.SelectedText is expected to begin and end at a word break; Paratext will attempt to expand the selection if it is not. |
| contentParagraphs | One or more paragraphs of formatted text |
| language | The default language used in contentParagraphs (except where specified explicitly in a FormattedString). |
| assignedUser | User (if any) to whom the new note is to be assigned. |
| Exception | Condition |
|---|---|
| ParatextPluginException | Start and end reference are different, selected text includes a marker, content paragraphs collection is null or empty, or contains a null paragraph. |
bool CanEdit(IPluginObject obj, DataType dataType=DataType.PluginData)
Checks whether the current user can edit the specified type of data using the given plugin.
| Parameter | Description |
|---|---|
| obj | Any object owned by the plugin that can be used to uniquely identify the plugin |
| dataType | The type of data |
bool CanEdit(IPluginObject obj, int bookNum, int chapterNum=0)
Checks whether the current user can edit a specified book and chapter (optional) using the given plugin.
| Parameter | Description |
|---|---|
| obj | Any object owned by the plugin that can be used to uniquely identify the plugin |
| bookNum | book or 0 for all books |
| chapterNum | chapter or 0 for entire book/text |
bool CheckForRegistration()
Checks the Paratext Registry for a registration for the project, downloading the project's license if necessary.
NOTE: True if a registration was found on the Paratext RegistryOpenRegistrationPage
| Parameter | Description |
|---|---|
| return value | True if a registration was found on the Paratext Registry |
string ConvertToUSFMString(IReadOnlyList< IUSFMToken > tokens)
Gets the USFM equivalent of the specified tokens (with normalized whitespace and line breaks). Format of USFM will be in the version returned by USFMVersion.
| Parameter | Description |
|---|---|
| tokens | The USFM tokens, which must be one of the three standard derived types of IUSFMToken: IUSFMMarkerTokenIUSFMTextTokenIUSFMAttributeToken |
| Exception | Condition |
|---|---|
| ParatextPluginException | Plugin gave invalid data. |
void DeletePluginData(IWriteLock writeLock, IPluginObject obj, string dataIdentifier)
Removes project-specific data. The plugin is responsible for checking CanEdit(IPluginObject, DataType) to make sure the current user has permission to write data for the project.
NOTE: The caller is responsible for disposing the lock if so desired. Notifications will be sent only when the lock is disposed or when IWriteLock.SendNotifications is called.
| Parameter | Description |
|---|---|
| writeLock | The write lock previously obtained by a call to RequestWriteLock(IPluginObject,Action<IWriteLock>,string). |
| obj | Any object owned by the plugin that can be used to uniquely identify the plugin |
| dataIdentifier | string identifying the data (e.g. a filename) |
| Exception | Condition |
|---|---|
| ParatextPluginException | Plugin gave invalid data or the user does not have permission to write data for the project |
| IOException | If something went wrong accessing the file on disk |
IReadOnlyList<IScriptureTextSelection> FindMatchingScriptureSelections(IVerseRef reference, string selectedText, string verseUsfm=null, bool wholeWord=false, bool treatAsRegex=false)
Gets a selection for each occurrence of the specified text in the verse.
| Parameter | Description |
|---|---|
| return value | A list of 0 or more matching selections. (Will not be null.) |
| reference | The reference of the verse in which to search (and which will be used for any results returned) |
| selectedText | The text to search for. The match will be case insensitive unless treatAsRegex is true. |
| verseUsfm | Optional USFM representing the text of the verse (which may represent an edited form of the text that has not yet been saved). Typically, this would come from the parameter passed to IPluginAnnotationSource.GetAnnotations. |
| wholeWord | Flag indicating whether to consider only whole-word matches. |
| treatAsRegex | Flag indicating whether to treat selectedText as a regular expression. |
| Exception | Condition |
|---|---|
| ParatextPluginException | verseUsfm contains USFM for verse(s) that do not correspond to the verse of the given reference , reference is null or invalid, or selectedText is null or empty. |
IBiblicalTermRenderings GetBiblicalTermRenderings(IBiblicalTerm term, bool guessIfNotRendered)
Gets an object representing the vernacular renderings from the project for the requested term.
| Parameter | Description |
|---|---|
| return value | If there is no rendering for the specified term a renderings object will still be returned. |
| term | The term whose renderings are needed. |
| guessIfNotRendered | If true and there are no (guessed or approved) renderings Paratext will use the guessing logic to try to find some renderings. These guessed renderings will not be added to the ones Paratext persists. This might take a while. |
string GetFormattedReference(IVerseRef reference, BookNameType nameType)
Creates a string from the given verse reference formatted as specified in the project reference settings.
NOTE: If the requested name type has not been set, the next best name will be used.
| Parameter | Description |
|---|---|
| return value | The formatted reference, or null if either none of the book names for the book have been set or if the reference settings have not been defined. |
| reference | The reference to format |
| nameType | What form of the book name to use. |
IReadOnlyList<IProjectNote> GetNotes(int bookNum=0, int chapterNum=0, bool unresolvedOnly=true)
Gets project notes.
NOTE: This does not include conflict notes, spelling notes, consultant notes, term rendering notes, etc.
| Parameter | Description |
|---|---|
| bookNum | The book number. Zero to get the notes for the entire project. |
| chapterNum | The chapter number. Zero to get the notes for the whole book. |
| unresolvedOnly | True to only return notes that are unresolved. |
| Exception | Condition |
|---|---|
| ParatextPluginException | Invalid parameters |
TextReader GetPluginData(IPluginObject obj, string dataIdentifier)
Gets a text reader that the plugin can use to read project-specific data. The plugin is responsible for closing the reader.
| Parameter | Description |
|---|---|
| return value | The reader containing the data, or null if it did not exist |
| obj | Any object owned by the plugin that can be used to uniquely identify the plugin |
| dataIdentifier | string identifying the data (e.g. a filename) |
| Exception | Condition |
|---|---|
| ParatextPluginException | Plugin gave invalid data |
| IOException | If something went wrong accessing the file on disk |
DateTime GetPluginDataModifiedTime(IPluginObject obj, string dataIdentifier)
Gets the date/time when the specified project-specific data was last modified.
| Parameter | Description |
|---|---|
| return value | The date/time when the data was last modified |
| obj | Any object owned by the plugin that can be used to uniquely identify the plugin |
| dataIdentifier | string identifying the data (e.g. a filename) |
| Exception | Condition |
|---|---|
| ParatextPluginException | Plugin gave invalid data |
| IOException | If something went wrong accessing the file on disk |
IScriptureTextSelection GetScriptureSelectionForVerse(IVerseRef reference, string verseUsfm=null)
Gets a selection for the verse.
| Parameter | Description |
|---|---|
| reference | The reference of the verse |
| verseUsfm | Optional USFM representing the text of the verse (which may represent an edited form of the text that has not yet been saved). Typically, this would come from the parameter passed to IPluginAnnotationSource.GetAnnotations. |
| Exception | Condition |
|---|---|
| ParatextPluginException | verseUsfm contains USFM for verse(s) that do not correspond to the verse of the given reference or reference is null or invalid. |
string GetUSFM(int bookNum, int chapterNum=0)
Gets the "raw" USFM data (in the version specified by USFMVersion).
| Parameter | Description |
|---|---|
| bookNum | The book number |
| chapterNum | The chapter number. Zero to get the whole book |
string GetUSFM(int bookNum, int chapterNum, int verseNum)
Gets the "raw" USFM data of a single verse (in the version specified by USFMVersion).
| Parameter | Description |
|---|---|
| bookNum | The book number |
| chapterNum | The chapter number |
| verseNum | The verse number |
IEnumerable<IUSFMToken> GetUSFMTokens(int bookNum, int chapterNum=0)
Gets the USFM in a form that is easier to parse.
NOTE: Even if the project has its USFM data stored in an older version of USFM, the tokens returned will reflect the current internal version of USFM used by Paratext. (For example, information about figures will always be returned as attributes.)
| Parameter | Description |
|---|---|
| bookNum | The book number |
| chapterNum | The chapter number. Zero to get the whole book |
IEnumerable<IUSFMToken> GetUSFMTokens(int bookNum, int chapterNum, int verseNum)
Gets the USFM of a single verse in a form that is easier to parse.
NOTE: Even if the project has its USFM data stored in an older version of USFM, the tokens returned will reflect the current internal version of USFM used by Paratext. (For example, information about figures will always be returned as attributes.)
| Parameter | Description |
|---|---|
| bookNum | The book number |
| chapterNum | The chapter number |
| verseNum | The verse number |
string GetUSX(int bookNum, bool strict=false, USXVersion version=USXVersion.Latest)
Gets the data for the specified book as USX.
| Parameter | Description |
|---|---|
| bookNum | The book number |
| strict | Flag indicating whether to return only USX that passes strict schema validation. If the data is not in a condition to be able to produce compliant USX and this flag is set, a ParatextPluginException will be thrown. |
| version | Desired USX version |
| Exception | Condition |
|---|---|
| ParatextPluginException | The strict flag was set and the data is not in a condition to be able to produce valid USX. |
void MakeHistoryPoint(string message, bool force=false)
Creates a new project history point with the specified message.
| Parameter | Description |
|---|---|
| message | The message to display for the history point. |
| force | True to force the creation of the history point even if nothing has changed. |
string NormalizeText(string text)
Normalizes the text according to the project settings (either Unicode composed or decomposed form).
void OpenRegistrationPage()
Opens the user's web browser at the Paratext Registry page for the project. If the project is not yet registered, it will let the user register the project.
NOTE: For projects that can not be registered, this method does nothing.
IsRegistered, CanBeRegistered, CheckForRegistration
void PutPluginData(IWriteLock writeLock, IPluginObject obj, string dataIdentifier, Action< TextWriter > writeData)
Requests Paratext to obtain a text writer and call back to the plugin so it can use it to write project-specific data (will be Sent/Received). The plugin is responsible for checking CanEdit(IPluginObject, DataType) (for DataType.PluginData) to make sure the current user has permission to write data for the project.
NOTE: The caller is responsible for disposing the lock if so desired. Notifications will be sent only when the lock is disposed or when IWriteLock.SendNotifications is called.
| Parameter | Description |
|---|---|
| writeLock | The write lock previously obtained by a call to RequestWriteLock(IPluginObject,Action<IWriteLock>,string). |
| obj | Any object owned by the plugin that can be used to uniquely identify the plugin |
| dataIdentifier | string identifying the data (e.g. a filename) |
| writeData | A callback supplying a TextWriter that the plugin should use to write the data. |
| Exception | Condition |
|---|---|
| ParatextPluginException | Plugin gave invalid data, the lock does not cover the specified plugin data, or the user does not have permission to write data for the project |
| IOException | If something went wrong accessing the file on disk |
void PutUSFM(IWriteLock writeLock, string usfmData, int bookNum)
Requests Paratext to write (and overwrite if existing) data for a chapter or book represented by the given USFM data.
NOTE: The caller is responsible for disposing the lock if so desired. Notifications will be sent only when the lock is disposed or when IWriteLock.SendNotifications is called.
| Parameter | Description |
|---|---|
| writeLock | The write lock previously obtained by a call to RequestWriteLock(IPluginObject,Action<IWriteLock>,int,int) |
| usfmData | Data representing either a single chapter in the given book or the entire book. If replacing an entire book, the given data must have content for all existing chapters. If the data is in a USFM version later than the version returned by USFMVersion, some loss of data may occur. |
| bookNum | The book number |
| Exception | Condition |
|---|---|
| ParatextPluginException | Plugin gave invalid data, the lock does not cover the needed scope, or the user does not have permission to write the given project data. |
| IOException | If something went wrong accessing the file on disk |
void PutUSFMTokens(IWriteLock writeLock, IReadOnlyList< IUSFMToken > tokens, int bookNum)
Requests Paratext to write (and overwrite if existing) data for a chapter or book represented by the given USFM tokens.
NOTE: The caller is responsible for disposing the lock if so desired. Notifications will be sent only when the lock is disposed or when IWriteLock.SendNotifications is called.
| Parameter | Description |
|---|---|
| writeLock | The write lock previously obtained by a call to RequestWriteLock(IPluginObject,Action<IWriteLock>,int,int) |
| tokens | The USFM tokens representing either a single chapter in the given book or the entire book. If replacing an entire book, the given data must have content for all existing chapters. Each token must be one of the three standard derived types of IUSFMToken: IUSFMMarkerTokenIUSFMTextTokenIUSFMAttributeToken |
| bookNum | The book number |
| Exception | Condition |
|---|---|
| ParatextPluginException | Plugin gave invalid data, the lock does not cover the needed scope, or the user does not have permission to write the given project data. |
| IOException | If something went wrong accessing the file on disk |
void PutUSX(IWriteLock writeLock, string usxData, bool strict=false)
Requests Paratext to write (and overwrite if existing) data for the book represented by the given USX data.
NOTE: The caller is responsible for disposing the lock if so desired. Notifications will be sent only when the lock is disposed or when IWriteLock.SendNotifications is called.
| Parameter | Description |
|---|---|
| writeLock | The write lock previously obtained by a call to RequestWriteLock(IPluginObject,Action<IWriteLock>,int,int) |
| usxData | The data to put |
| strict | Flag indicating whether to accept only USX that passes strict schema validation. |
| Exception | Condition |
|---|---|
| ParatextPluginException | Plugin gave invalid data (ill-formed XML, version incompatible, etc.), the lock does not cover the entire book, or the user does not have permission to write the given book (all chapters). |
| IOException | If something went wrong accessing the file on disk |
IWriteLock RequestWriteLock(IPluginObject obj, Action< IWriteLock > releaseRequested, int bookNum, int chapterNum=0)
Requests a write lock for the specified scripture data.
NOTE: An appropriate lock should be obtained before calling PutUSFM, PutUSFMTokens, or PutUSX.
| Parameter | Description |
|---|---|
| return value | The requested lock or null if not available. |
| obj | Any object owned by the plugin that can be used to uniquely identify the plugin |
| releaseRequested | Delegate to call when some other task requests a lock that overlaps with the lock granted as a result of this request. Plugin should normally release the lock in response to this. |
| bookNum | The book number. Zero to lock the entire project text. |
| chapterNum | The chapter number. Zero to lock the whole book. |
| Exception | Condition |
|---|---|
| ParatextPluginException | Plugin gave invalid data |
IWriteLock RequestWriteLock(IPluginObject obj, Action< IWriteLock > releaseRequested, string pluginDataIdentifier=null)
Requests a write lock for the specified plugin data.
NOTE: An appropriate lock should be obtained before calling PutPluginData.
| Parameter | Description |
|---|---|
| return value | The requested lock or null if not available. |
| obj | Any object owned by the plugin that can be used to uniquely identify the plugin |
| releaseRequested | Delegate to call when some other task requests a lock that overlaps with the lock granted as a result of this request. Plugin should normally release the lock in response to this. |
| pluginDataIdentifier | string identifying the data (e.g. a filename) |
| Exception | Condition |
|---|---|
| ParatextPluginException | Plugin gave invalid data |
IWriteLock RequestWriteLock(IPluginObject obj, Action< IWriteLock > releaseRequested, WriteLockScope lockScope)
Requests a write lock for the specified scope.
| Parameter | Description |
|---|---|
| return value | The requested lock or null if not available. |
| obj | Any object owned by the plugin that can be used to uniquely identify the plugin |
| releaseRequested | Delegate to call when some other task requests a lock that overlaps with the lock granted as a result of this request. Plugin should normally release the lock in response to this. |
| lockScope | The scope of the lock. |
| Exception | Condition |
|---|---|
| ParatextPluginException | Plugin gave invalid data |
This page is auto-generated. User edits will be lost when regenerated.