Recolor

<recolor>
   <colorway name=”xxxx”>
      <threads>
         <thread color="32768" code="xx" brand="xx" description="xx" />
         <thread color="1554175" code="xx" brand="xx" description="xx" />
      </threads>
   </colorway> 
</recolor>

The recolor element is used to replace colorways in or add colorways to an existing design. Design colorway and stop sequence information can be retrieved via designInfo or designTrueview APIs. The colorway element is described in the Design Information section under ‘Colorway information’. Only the threads elements and name attribute work with recolor. The current attribute works with the AddColorway option.

Recolor element usage

The recolor element can be used by following APIs:

ReplaceColorway option

The ReplaceColorway attribute option uses the following syntax…

<recolor option="ReplaceColorway">

This option allows you to replace colors in an existing colorway. For example…

<design file="<Filename>.EMB">
  <recolor option="ReplaceColorway">
    <colorway bkg_color="13401855" current="true" name="Colorway 1" >
      <threads>
        <thread color="39168" code="1" brand="Default" description="Dark Green" />
        <thread color="16711680" code="2" brand="Default" description="Blue" />
      ...
      </threads>
    </colorway>
  </recolor>
</design>

Notes:

  • For backwards compatibility, the default option is always ‘ReplaceColorway’ if the attribute is missing from the statement.
  • Use recolor.colorway.name to specify the colorway to be replaced. If it is missing and the design only has one colorway, this will be replaced.

The colors in the colorway will be as provided in the threads list unless:

  • The color index which is used by the design is out of range of the provided thread list. The EWA will append colors from original design to the colorway by position until it reaches the last used color.
  • The provided thread list contains too many colors. Only first 128 colors will be used in any colorway.

AddColorway option

The AddColorway attribute option uses the following syntax…

<recolor option="AddColorway">

This option allows you to add colorways to an existing design. For example…

<design file="<Filename>.EMB">
  <recolor option="AddColorway">
    <colorway bkg_color="13401855" current="true"  name="Colorway 2">
      <threads>
        <thread color="39168" code="1" brand="Default" description="Dark Green" />
        <thread color="16711680" code="2" brand="Default" description="Blue" />
        ...
      </threads>
    </colorway>
  </recolor>
</design>

Notes:

  • The name of the colorway must be provided. If not, an ‘ERROR_INVALID_CWY_NAME’ exception is shown.
  • If a colorway with the specified name already exists, an ‘ERROR_DUPLICATE_CWY_NAME’ exception is shown.
  • If the ‘current’ flag is set to true, the newly added colorway set as current.

Action order

Recoloring is the first action to be undertaken on the API side. The action order is important in some circumstances. As we know, lettering object colors can be modified. If recolor is used at the same time, the action order will affect the color palette of the resulting design. For example…

  1. A design has color palette employing Colors 1 to 8.
  2. The editDesign API is used to change a lettering object to Color 9.
  3. At the same time, recolor provides a list of colors containing Color 9.

If recolor is performed first, the color palette will be modified accordingly and the new color added. The lettering object action is then performed. Color 9 is already in the palette and can be used.

If, on the other hand, the lettering object action is performed first, Color 9 is not yet in the palette so is appended. Then, if the recolor action is performed, it replaces the first 8 colors in the palette. The results will differ.