== <string> ==

A string object represents a single-line or multi-line text value.

[[rpimage(zoo_string1.gif)]]
{{{
  <string id="title">
    <about>
      <label>Title</label>
      <description>This text will be used as the title for all plots.</description>
    </about>
    <default>untitled</default>
  </string>
}}}

[[BR]]
[[rpimage(zoo_string2.gif)]]
{{{
  <string id="indeck">
    <about>
      <label>Input</label>
      <description>This is the control file for the program.</description>
      <hints>EXAMPLE:  .print ac vm(11) mag(i(vcc))</hints>
    </about>
    <size>40x10</size>
    <default>Enter your SPICE commands
in this area.  Right-click
for a menu of editing options.</default>
  </string>
}}}
A string becomes a multi-line string by setting its {{{<size>}}} to {{{WxH}}}.  The width W and height H represent a good size for the text editor.  They do not limit the overall size of the text.

The {{{<hints>}}} parameter represents a hint for the user, shown below the editing area.

If binary data is loaded into a string element, it changes to show a binary data icon and information about the data type:

[[rpimage(zoo_string3.gif)]]

If you expect binary data for a particular string element, you can force the binary display mode by setting the string size to {{{binary}}} as follows:
{{{
  <string id="tarfile">
    <about>
      <label>Archive File</label>
      <description>Upload a gzipped tar file containing the input data</description>
    </about>
    <size>binary</size>
  </string>
}}}


If you specify a {{{<filetype>}}} in your xml the download button will create a file name that concatenates the widget's {{{<label>}}} and {{{<filetype>}}} to create the name of the downloaded file.

{{{
  <string id="tarfile">
    <about>
      <label>mydata</label>
      <description>Generated data .csv file</description>
    </about>
    <filetype>.csv</filetype>
    <current>street,city,zip
3221 HIGH ST,SACRAMENTO,95838
55 OMAHA CT,SACRAMENTO,95823</current>
  </string>
}}}

In this example, the output string's {{{<label>}}} is mydata and the {{{<filetype>}}} is ''.csv''. When the user downloads the data, it will be offered to be saved in a file named ''mydata.csv''.

Note that if your {{{<label>}}} was ''mydata.csv'' and you don't specify a {{{<filetype>}}} element in the xml, Rappture will look to see if the file is text or binary data. If the file is plain text data, Rappture will offer the name ''mydatacsv.txt'', removing the '''.''' in the original label and tacking on a ''.txt'' file extension. If the file is binary data, Rappture will offer the name ''mydatacsv.dat'', removing the '''.''' in the original label and tacking on a ''.dat'' file extension.


You can see working code in the [browser:trunk/examples/zoo zoo of examples] in the [browser:trunk/examples/zoo/string string example] directory, or on the hub in the directory /apps/rappture/examples/zoo/string.  There's also an example of [browser:trunk/examples/zoo/binary handling binary data].