The Chapters statement provides a programmatic interface to the functionality found in the Chapter Editor.
The statement is valid in all execution modes but the returned action test state may be more meaningful when executing grouped. For all functions which return a value in the specified track variable, if a file does not have chapters or a specified chapter number is invalid, the track variable is set to empty.
When a chapter number is specified, the field may contain any of the escape sequences described in Escape Sequences. Note that chapter numbers start with 1. 0 is an invalid chapter number.
The following functions are available:
- Get the Number of Chapters
- The specified track variable will be set to the number of chapters or empty if there are none. An action test state of true implies all files in the current execution mode contained chapters.
- Test if any Chapter Names Are Modified
- The specified track variable will be set to 1 if any chapter names are modified. Otherwise the track variable will be set to empty. An action test state of true implies that at least one file had modifications to the chapter names.
- Test if a Chapter Name is Modified
- The specified track variable will be set to 1 if the name of the specified chapter has been modified. Otherwise the track variable will be set to empty. An action test state of true implies that at least one file had modifications to the name of the specified chapter.
- Get the Initial Name of a Chapter
- The specified track variable will be set to the initial name of the specified chapter. An action test state of false implies that at least one file did not have chapters or that the supplied chapter number was invalid. The initial name is the name currently stored in a file.
- Get the Changed Name of a Chapter
- The specified track variable will be set to the modified name of the specified chapter, if there is one. Otherwise the track variable will be set to empty. An action test state of true implies that at least one updated chapter name was returned. Note that testing for empty does not guarantee that the chapter name was not modified. A chapter name can be set to empty. Use the Test if a Chapter Name is Modified function if an exact changed determination is required.
- Get the Write Name of a Chapter
- The specified track variable will be set to the name of the specified chapter that will be written if the chapters are updated. An action test state of true implies that at least one returned chapter name was a modification.
- Get a List of Initial Chapter Names
- The specified track variable is set to a list of all initial chapter names. The list items are delimited by a newline character (\n). The test state will be false if any file did not have chapters.
- Get a List of Changed Chapter Names
- The specified track variable is set to a list of all modified chapter names. If a particulare chapter names has not been modified, the corresponding list item will be empty. List items are delimited by a newline character (\n). The test state will be false if any file did not have chapters. Note that testing an item for empty does not guarantee that the chapter name was not modified. A chapter name can be set to empty. Use the Test if a Chapter Name is Modified function if an exact changed determination is required.
- Get a List of Write Chapter Names
- The specified track variable is set to a list of all chapter names which will be written when the file is saved. List items are delimited by a newline character (\n). The test state will be false if any file did not have chapters.
- Set the Name of a Chapter
- The name of the specified chapter will be set to the contents of the specified track variable. An action test state of true implies that at least one chapter name was modified. If the Revert to initial value if empty option is set and the track variable is empty, the chapter name will be reset to its initial value.
- Set All Chapter Names from List
- The specified track variable must contain a list with items delimited by a newline (\n) character or the default list delimiter (\~). An entirely empty list is ignored. If there are more items in a list than there are chapters, they are ignored. There must be the same number of items in the list as there are chapters. For example if you are setting three chapter names the following will work:
Chapter 1\nChapter 2\nChapter 3
If a list item is completely empty and the Revert to initial value if empty option is set, the associated chapter name will be set to its initial value. If you are importing chapter names by reading a text file it is a good idea to have the correct number of chapter names in the text file. For example:
Chapter 1\nChapter 2\nChapter 3\n
contains four names. The last is empty. If there are only three chapters in the media file, the trailing \n is ignored.
The test state will be false if any file did not have chapters.
- Clear All Chapter Names
- All chapter names will be set to empty. The test state will be false if any file did not have chapters.
