SoMFString(3IV)

NAME
     SoMFString (SoMString) - multiple-value field containing any number of
     strings

INHERITS FROM
     SoField > SoMField > SoMFString

SYNOPSIS
     #include <Inventor_c/fields/SoMFString.h>

     typedef SoMFString  SoMString

          Functions from class SoMFString:

                         SoMStringSetStrs(SoMString *this, int start, int num,
                              const char *strings[])
                         SoMStringSetStr(SoMString *this, const char *string)
     SoType              SoMStringGetClassTypeId()
     void                SoMStringGetTypeId(const SoMString *this)
     const SbString *    SoMStringGet(const SoMString *this, int i)
     const SbString *    SoMStringGetN(const SoMString *this, int start)
     int                 SoMStringFind(SoMString *this, const SbString *
                              targetValue, SbBool addIfNotFound = FALSE)
     void                SoMStringSetN(SoMString *this, int start, int num,
                              const SbString *newValues)
     void                SoMStringSet1(SoMString *this, int index, const
                              SbString * newValue)
     void                SoMStringSet(SoMString *this, const SbString *
                              newValue)
     int                 SoMStringIsEq(const SoMString *this, const SoMFString
                              *f)
     int                 SoMStringIsNEq(const SoMString *this, const
                              SoMFString *f)
     SbString *          SoMStringStartEdit(SoMString *this)
     void                SoMStringFinishEdit(SoMString *this)

          Functions from class SoMField:

     int                 SoMStringGetNum(const SoMString *this)
     void                SoMStringSetNum(SoMString *this, int num)
     void                SoMStringDel(SoMString *this, int start, int num =
                              -1)
     void                SoMStringInsertSpace(SoMString *this, int start, int
                              num)
     void                SoMStringGet1(SoMString *this, int index, SbString
                              *valueString)

          Functions from class SoField:

     void                SoMStringSetIgnored(SoMString *this, SbBool ignore)
     SbBool              SoMStringIsIgnored(const SoMString *this)

     SbBool              SoMStringIsDflt(const SoMString *this)
     SbBool              SoMStringIsOfType(const SoMString *this, SoType type)
     SbBool              SoMStringSetFromStr(SoMString *this, const char
                              *valueString)
     void                SoMStringGetIntoStr(SoMString *this, SbString
                              *valueString)
     void                SoMStringTouch(SoMString *this)
     SbBool              SoMStringConnFromField(SoMString *this, SoField
                              *fromField)
     SbBool              SoMStringConnFrom(SoMString *this, SoEngineOutput
                              *fromEngine)
     void                SoMStringDisconn(SoMString *this)
     SbBool              SoMStringIsConn(const SoMString *this)
     SbBool              SoMStringIsConnFromField(const SoMString *this)
     SbBool              SoMStringGetConnField(const SoMString *this, SoField
                              **writingField)
     SbBool              SoMStringIsConnFromEngine(const SoMString *this)
     SbBool              SoMStringGetConnEngine(const SoMString *this,
                              SoEngineOutput **engineOutput)
     void                SoMStringEnableConn(SoMString *this, SbBool flag)
     SbBool              SoMStringIsConnEnabled(const SoMString *this)
     int                 SoMStringGetForwardConn(const SoMString *this,
                              SoFieldList *list)
     SoFieldContainer *  SoMStringGetContainer(const SoMString *this)


DESCRIPTION
     A multiple-value field that contains any number of strings.

     SoMFStrings are written to file as one or more strings within double
     quotes. Any characters (including newlines) may appear within the quotes.
     To include a double quote character within the string, precede it with a
     backslash. For example:

          [ cowEnizer , "Scene Boy" , "He said, \"I did not!\"" ]



FUNCTIONS
                         SoMStringSetStrs(SoMString *this, int start, int num,
                              const char *strings[])
          Sets num values, starting at index start, to the strings in the
          given character arrays.

                         SoMStringSetStr(SoMString *this, const char *string)
          Deletes all values currently in this field and sets this field to
          contain only the given string.

     SoType              SoMStringGetClassTypeId()
     void                SoMStringGetTypeId(const SoMString *this)
          Returns the type for this class or a particular object of this
          class.
     const SbString *    SoMStringGet(const SoMString *this, int i)
          Returns the i'th value of the field. Indexing past the end of the
          field (passing in i greater than getNum()) will return garbage.

     const SbString *    SoMStringGetN(const SoMString *this, int start)
          Returns a pointer into the array of values in the field, starting at
          index start. The values are read-only; see the
          startEditing()/finishEditing() methods for a way of modifying values
          in-place.

     int                 SoMStringFind(SoMString *this, const SbString *
                              targetValue, SbBool addIfNotFound = FALSE)
          Finds the given value in the array and returns the index of that
          value in the array. If the value is not found, -1 is returned. If
          addIfNotFound is set, then targetValue will be added to the end of
          the array (but -1 is still returned).

     void                SoMStringSetN(SoMString *this, int start, int num,
                              const SbString *newValues)
          Sets num values starting at index start to the values in newValues.
          The array will be automatically be made larger to accomodate the new
          values, if necessary.

     void                SoMStringSet1(SoMString *this, int index, const
                              SbString * newValue)
          Sets the index'th value in the array to newValue. The array will be
          automatically expanded, if necessary.

     void                SoMStringSet(SoMString *this, const SbString *
                              newValue)
          Sets the first value in the array to newValue, and deletes the
          second and subsequent values.

     int                 SoMStringIsEq(const SoMString *this, const SoMFString
                              *f)
     int                 SoMStringIsNEq(const SoMString *this, const
                              SoMFString *f)
          Returns TRUE if all of the values of this field equal (do not equal)
          those of the given field. If the fields are different types FALSE
          will always be returned (even if one field is an SoMFFloat with one
          value of 1.0 and the other is an SoMFInt with a value of 1, for
          example).

     SbString *          SoMStringStartEdit(SoMString *this)
     void                SoMStringFinishEdit(SoMString *this)
          startEditing() returns a pointer to the internally-maintained array
          that can be modified. The values in the array may be changed, but
          values cannot be added or removed. It is illegal to call any other
          editing methods between StartEdit() and FinishEdit() (e.g. Set1(),
          Set(), etc).

          Fields, engines or sensors connected to this field and sensors are
          not notified that this field has changed until FinishEdit() is
          called. Calling FinishEdit() always sets the IsDflt. flag to FALSE
          and informs engines and sensors that the field changed, even if none
          of the values actually were changed.