-
Notifications
You must be signed in to change notification settings - Fork 4
IProject
A Paratext project
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.
ProjectDataChangedHandler ProjectDataChanged
Raised when a Project setting or other data is changed.
Action ProjectDeleted
Raised when the project is deleted
string ID
Gets the unique ID of the project
string ShortName
Gets the short name of the project
IVersification Versification
Gets the versification used by the project
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
ProjectType Type
Gets the type of project
IProject BaseProject
Gets the base project; or null, if not based on another project.
IKeyboard VernacularKeyboard
Gets the default vernacular keyboard. Can be null.
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<IBookInfo> AvailableBooks
Gets the books that are available in the project.
IReadOnlyList<IUserInfo> NonObserverUsers
Gets the users who have a non-Observer role on 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.
IReadOnlyList<IMarkerInfo> ScriptureMarkerInformation
Gets information about all the markers defined for Scripture books in this project.
IReadOnlyList<IMarkerInfo> FrontBackMarkerInformation
Gets information about all the markers defined for front and back matter in this project.
USFMVersion USFMVersion
The version of USFM used by the 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.
string NormalizeText(string text)
Normalizes the text according to the project settings (either Unicode composed or decomposed form).
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 |
|---|---|
| reference | The reference to format |
| nameType | What form of the book name to use. |
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 |
|---|---|
| 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. |
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. |
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 |
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 |
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 |
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 |
|---|---|
| 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) |
DateTime GetPluginDataModifiedTime(IPluginObject obj, string dataIdentifier)
Gets the date/time when the specified project-specific data was last modified.
| Parameter | Description |
|---|---|
| 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) |
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. |
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 |
|---|---|
| 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. |
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 |
|---|---|
| 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. |
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 |
|---|---|
| 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) |
IWriteLock RequestWriteLock(IPluginObject obj, Action< IWriteLock > releaseRequested, WriteLockScope lockScope)
Requests a write lock for the specified scope.
| Parameter | Description |
|---|---|
| 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. |
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. |
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. |
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 |
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 |
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. |
void DeletePluginData(IWriteLock writeLock, IPluginObject obj, string dataIdentifier)
Removes project-specific data. The plugin is responsible for checking {TBD} 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) |
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 |
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 |
IBiblicalTermRenderings GetBiblicalTermRenderings(IBiblicalTerm term, bool guessIfNotRendered)
Gets an object representing the vernacular renderings from the project for the requested term.
| Parameter | Description |
|---|---|
| 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. |
This page is auto-generated. User edits will be lost when regenerated.