Contents

DH_TextList

 Next
 

Function:

Allows a customized selection list to be built dynamically or loaded from a text file. The custom list can then be used to control selection from another list, using the List output, or even multiple lists, using the Index output and an Int splitter, as shown below.



 

Inputs:

Selection - Connects to a Dropdown List or other GUI selection sub-control.

Text IO - Input for entering text when building a list dynamically

Index - Selects a list item numerically

Write - Writes character string at Text IO to currently selected list item, replacing any existing text, on change from TRUE to FALSE. (mouse up). If Text IO pin is blank, the currently selected list position becomes blank. The Write pin updates the list in memory, but the file is not updated until a new file is selected or the module closes unless the Read/Write Mode is set to Immediate Save.

Clear List - Clears all items from the list on change from TRUE to FALSE. (mouse up). Deletes the file if in Immediate Save Mode. 

File Name - Names the text file used to store list data when the module is not running.  If 2 or more modules use the same filename, they will access the same file (see Read/Write Mode below).

Load - Reloads the list from the text file on change from TRUE to FALSE. (mouse up). Has no effect in Active Refresh mode, as the list is then being updated automatically on a periodic basis.

Outputs:

List  -  Connection to a list input (GUI type). Use a Patch Mem - List2 to connect to a DSP type list entry input.

Index -  Position in list of currently selected item, with first list item having an index of 0.

Parameters (right-click Properties):

List Size - Specifies the maximum number of items in a list. Use it to set the size of a list that is built dynamically using the Write pin. It has no effect when a list is loaded from a text file, because in that case the list is automatically sized to fit the number of items in the file.

Read/Write Mode:

  • Passive - The list is backed up to file on module close, and reloaded on module open to provide persistent storage. The Write pin updates the list in memory, but updates are not saved to file until a new file is selected or the module is closed.

    If the text file is being updated dynamically by another DH_TextArray or DH_TextList writing to the same file in Immediate Save mode, or by an external program, the list in memory can be updated manually by using the Load pin.
     

  • Active Refresh - The list is updated automatically on a specified time interval to pick up any changes made to the file by other DH_TextLists or  DH_TextArrays, or by an external program.
     

  • Immediate Save - The Write pin writes directly through to the file. Only one DH_TextList or DH_TextArray should be set to Immediate Save for a file, or results will be unpredictable.

Active Refresh Interval (ms) - Sets the time interval, in milliseconds, between updates in Active Refresh Mode.


Notes:

  • The file is just a text file, so you can edit or create one in a text editor like Notepad.

    The format of the file follows two simple rules:

  1. Each list item must be on a single line
  2. Each line must be terminated by a semicolon (;)

  • Currently, lists are limited to approximately 1000 characters. This is because queue deadlocks, which can freeze the computer, can occur when too many characters are sent to a list pin. Rather than risk freeze ups, the module enforces a limitation, and sends a message when it has to truncate a list. This in itself does not affect the original file. If you then use DH_TextList's Write pin to change a truncated list, however, the truncated list will be saved over the original file. This limitation on the number of characters will be increased or removed when changes in SynthEdit make it safe to do so.
     

  • You should use just a file name, without a path, for the File Name pin. Then, while you are working in SynthEdit, the module will look for and save its file in the SynthEdit directory. When you do a "save as VST", add the file using the Embedded Files tab, again without a path (if it's in your SynthEdit directory it should appear that way when you add it). When the VST is run, it will unload the file into the same folder that the VST creates for its .sep/.sem modules, and the module will find it there.
     

  • DH_TextList can update lists dynamically in Immediate Save mode. Other DH_TextLists and DH_TextArrays in Active Refresh Mode receive these updates, along with any changes made to the list file by external processes. Beginning with version 2.2,  Active Refresh runs when the GUI side of the plugin is otherwise idle, so the impact on resources is minimal.
     

  • Beginning with version 2.2, all file processing is done on the GUI side, eliminating the bottleneck that sometimes occurred in earlier versions of the module when long lists and/or many instances of the module were used in a project. The File Name pin has been kept as a DSP pin, however, to maintain pin compatibility with prior versions. If you specify a File Name in the right-click Properties, the file will be loaded and the list populated when the GUI is initialized, but the module will not respond to changes on the File Name pin unless the audio is running.

  • Your list items can include formatting characters for DH_PopupMenu to give your menu horizontal separators, non-selectable headings, and forced column breaks. The formatting characters all start with a > as the 1st character in the item:

>--- ; (one or more hyphens, followed by a semicolon to end the line) inserts a horizontal separator.

>~ (tilde) at the beginning of an item marks it as non-selectable for category headings and the like.

>| (vertical bar) at the beginning of an item forces a column break with a vertical bar separator.

>] (right square bracket) at the beginning of an item forces a column break without a vertical bar separator.

Other DH selection controls will ignore these formatting characters. You can use a DH_ListStandardizer to convert a list that contains formatting characters to a standard SE list for use with other modules.

  • An example of a momentary contact button that outputs a Boolean value suitable for use with the Write, Clear List and Load pins is included in the distribution .zip file as BoolButton.se1.
     

 

 Next