-
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.
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.
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 |
|---|---|
| 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. |
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
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 |
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) |
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. |
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. |
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<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. |
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) |
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 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 |
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. |
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 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. |
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. |
This page is auto-generated. User edits will be lost when regenerated.