Contents

DH_TextArray

 Next
 

Function:

Provides storage and retrieval of text strings by a numeric index.

Inputs:

Input - A text string to be stored in the array.

Index - Selects a string using values from 0 to the Array Size - 1. Voltage  input is rounded to the nearest integer.

Write - Writes the Input string to the current index location, replacing any existing text, on change from TRUE to FALSE (mouse up). If Input pin is blank, the current index location becomes empty. The Write pin updates the array 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.

File Name - Names the text file used to store array 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).

Clear - Erases all strings on change from TRUE to FALSE (mouse up).  Deletes the module's backing file if in Immediate Save Mode.

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

Outputs:

Text Out (right and left) - The text string stored at the currently indexed position, or an empty string if the slot is empty.

Index - The integer value of the current index. (voltage)

Parameters:

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

Read/Write Mode:

  • Passive - the array 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 array in memory can be updated manually by using the Load pin.
     

  • Active Refresh - The array 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 input and output Index pins are regular SE voltage type connections. The File Name pin is a DSP text input with a file icon, which can be used with either a Text Entry, or the newer Patch Mem - Text sub-control. The rest of the pins are GUI types, so that the module can easily be integrated with other sub-controls.
     

  • The file is just a text file, so you can edit or create one in a text editor like Notepad, if that seems more convenient than loading each string into the module in SynthEdit.

    The format of the file follows two simple rules:

  1. Each array entry must be terminated by a semicolon (;)
  2. Strings may contain spaces, and may be spread over multiple lines; spaces and line breaks, including any leading or trailing spaces, will be stored as entered.

Note that this format is much less restrictive than that for DH_TextList. If a file is to be shared by both types of module, be sure to follow DH_TextList's rule that each item must be on a single line. Please see the help for DH_TextList for additional information about list formatting and restrictions.

  • 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_TextArray can update lists dynamically in Immediate Save mode. Other DH_TextArrays and DH_TextLists in Active Refresh Mode receive these updates, along with any changes made to the 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. 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 when the GUI is initialized, but the module will not respond to changes on the File Name pin unless the audio is running.

  • The file DH_Controls_demo2.se1 shows an example of this module being used in conjunction with other SynthEdit and DH sub-controls. (Look inside the DH_Output_Formatter preset.)
     

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


     

 Next