<?xml version="1.0"?>
<!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 1.0.4//EN" "http://www.gnustep.org/gsdoc-1_0_4.dtd">
<gsdoc base="NSColorList" up="Gui">
  <head>
    <title>NSColorList</title>
    <author name="Scott Christley">
      <email address="scottc@net-community.com">
        scottc@net-community.com
      </email>
    </author>
    <author name="Nicola Pero">
      <email address="n.pero@mi.flashnet.it">
        n.pero@mi.flashnet.it
      </email>
    </author>
    <abstract>Manage named lists of NSColors.</abstract>
    <copy>1996, 2000 Free Software Foundation, Inc.</copy>
  </head>
  <body>
    <front><contents /></front>
    <chapter>
      <heading>
        Software documentation for the NSColorList class
      </heading>
      <class name="NSColorList" super="NSObject" ovadd="1.0.0">
        <declared>AppKit/NSColorList.h</declared>
        <conform>NSCoding</conform>
        <desc>
          <em>Description forthcoming.</em>
        </desc>
        <ivariable type="NSMutableDictionary*" name="_colorDictionary" validity="protected" ovadd="1.0.0">
          <desc>
            <em>Warning</em> the underscore at the start of the
            name of this instance variable indicates that, even
            though it is not technically <em>private</em>, it is
            intended for internal use within the package, and
            you should not use the variable in other code.
          </desc>
        </ivariable>
        <ivariable type="NSString*" name="_fullFileName" validity="protected" ovadd="1.0.0">
          <desc>
            <em>Warning</em> the underscore at the start of the
            name of this instance variable indicates that, even
            though it is not technically <em>private</em>, it is
            intended for internal use within the package, and
            you should not use the variable in other code.
          </desc>
        </ivariable>
        <ivariable type="BOOL" name="_is_editable" validity="protected" ovadd="1.0.0">
          <desc>
            <em>Warning</em> the underscore at the start of the
            name of this instance variable indicates that, even
            though it is not technically <em>private</em>, it is
            intended for internal use within the package, and
            you should not use the variable in other code.
          </desc>
        </ivariable>
        <ivariable type="NSString*" name="_name" validity="protected" ovadd="1.0.0">
          <desc>
            <em>Warning</em> the underscore at the start of the
            name of this instance variable indicates that, even
            though it is not technically <em>private</em>, it is
            intended for internal use within the package, and
            you should not use the variable in other code.
          </desc>
        </ivariable>
        <ivariable type="NSMutableArray*" name="_orderedColorKeys" validity="protected" ovadd="1.0.0">
          <desc>
            <em>Warning</em> the underscore at the start of the
            name of this instance variable indicates that, even
            though it is not technically <em>private</em>, it is
            intended for internal use within the package, and
            you should not use the variable in other code.
          </desc>
        </ivariable>
        <method type="NSArray*" factory="yes" ovadd="1.0.0">
          <sel>availableColorLists</sel>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
        </method>
        <method type="NSColorList*" factory="yes" ovadd="1.0.0">
          <sel>colorListNamed:</sel>
          <arg type="NSString*">name</arg>
          <desc>
            Returns the first color list (from the array of
            available lists) matching <var>name</var>.
          </desc>
        </method>
        <method type="NSArray*" ovadd="1.0.0">
          <sel>allKeys</sel>
          <desc>
            Returns an array containing all the keyus in the
            color list
          </desc>
        </method>
        <method type="NSColor*" ovadd="1.0.0">
          <sel>colorWithKey:</sel>
          <arg type="NSString*">key</arg>
          <desc>
            Returns the color for the specified <var>key</var>
            (if any).
          </desc>
        </method>
        <method type="void" ovadd="1.0.0">
          <sel>encodeWithCoder:</sel>
          <arg type="NSCoder*">aCoder</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
        </method>
        <method type="id" ovadd="1.0.0">
          <sel>initWithCoder:</sel>
          <arg type="NSCoder*">aDecoder</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
        </method>
        <method type="id" ovadd="1.0.0">
          <sel>initWithName:</sel>
          <arg type="NSString*">name</arg>
          <desc>
            Initializes a new, empty color list registered
            under given <var>name</var>.
          </desc>
        </method>
        <method type="id" ovadd="1.0.0">
          <sel>initWithName:</sel>
          <arg type="NSString*">name</arg>
          <sel>fromFile:</sel>
          <arg type="NSString*">path</arg>
          <desc>
            <p>
              Initializes a new color list registered under
              given <var>name</var>, taking contents from the
              file specified in <var>path</var>. (Path should
              include the filename with extension (usually
              ".clr"), and by convention <var>name</var>
              should be the same as filename <em>without</em>
              the extension.)
            </p>
            <p>
              The format of the file can be either an archive of an
              NSColorList or an ASCII format. ASCII files
              follow this format:
            </p>
            <p>
              first line = [#/colors] <br /> each subsequent line
              describes a color as [<strong>int</strong>
              float+ string] <br /> the first
              <strong>int</strong> describes the method (RGBA,
              etc.), the floats provide its arguments (e.g., r,
              g, b, alpha), and string is <var>name</var>.
            </p>
            <p>
              The <em>method</em> corresponds to one of the
              <ref type="class" id="NSColor">NSColor</ref>
                initializers. We are looking for
                documentation of the exact correspondence
                on OpenStep; for now the only supported method is
                "0", which is an RGBA format with the arguments in
                order R,G,B, A.
              </p>
          </desc>
        </method>
        <method type="void" ovadd="1.0.0">
          <sel>insertColor:</sel>
          <arg type="NSColor*">color</arg>
          <sel>key:</sel>
          <arg type="NSString*">key</arg>
          <sel>atIndex:</sel>
          <arg type="unsigned">location</arg>
          <desc>
            Inserts a <var>color</var> into the
            <var>color</var> list at the specified index. Removes
            any other <var>color</var> with the same name.
          </desc>
        </method>
        <method type="BOOL" ovadd="1.0.0">
          <sel>isEditable</sel>
          <desc>
            Returns a flag indicating whether the receiver is
            editable.
          </desc>
        </method>
        <method type="NSString*" ovadd="1.0.0">
          <sel>name</sel>
          <desc>
            Returns the name of the receiver.
          </desc>
        </method>
        <method type="void" ovadd="1.0.0">
          <sel>removeColorWithKey:</sel>
          <arg type="NSString*">key</arg>
          <desc>
            Removes the color for the specified <var>key</var>
            from the list.
          </desc>
        </method>
        <method type="void" ovadd="1.0.0">
          <sel>removeFile</sel>
          <desc>
            Removes the on-disk representation of the list.
          </desc>
        </method>
        <method type="void" ovadd="1.0.0">
          <sel>setColor:</sel>
          <arg type="NSColor*">aColor</arg>
          <sel>forKey:</sel>
          <arg type="NSString*">key</arg>
          <desc>
            Sets the color for this <var>key</var> and appends it
            to the color list.
          </desc>
        </method>
        <method type="BOOL" ovadd="1.0.0">
          <sel>writeToFile:</sel>
          <arg type="NSString*">path</arg>
          <desc>
            Writes the receiver to the specified <var>path</var>
            . <br /> If <var>path</var> is <code>nil</code>, writes
            to a file located in the current user's personal Colors
            directory whose name is that of the list with the
            extension 'clr' appended. <br /> If
            <var>path</var> is a directory, writes to a file in
            that directory whose name is that of the list with the
            extension 'clr' appended. <br /> Otherwise (
            <var>path</var> is neither <code>nil</code> nor a
            directory), writes to the <var>path</var>
            without appending the l.ist name. <br /> Returns
            <code>YES</code> on success, <code>NO</code> on
            failure. <br /> Writing with a <var>path</var> of
            <code>nil</code> will cause the receiver to be added
            to the
            <ref type="method" id="+availableColorLists">
              +availableColorLists
            </ref>
            if it is not already there.
          </desc>
        </method>
      </class>
    </chapter>
  </body>
</gsdoc>
