huey: Internal maintenance specification

The purpose of this method is to place a standard set of color names into self.__scrolledList and the internal data structures self.__colorMap, self.__colorMap and self.__colorList, that describe that same set of colors.

# - - -   P i c k L i s t . _ _ a d d C o l o r s

    def __addColors ( self ):
        """Populate the color set

          [ if a readable, valid self.COLOR_NAMES_FILE exists in
            one of the directories named in self.PATHS_LIST ->
              self.__scrolledList   :=  self.pickList with the color
                  names added from that file in the same order
              self.__colorMap   :=  as invariant from that file
              self.__colorList  :=  as invariant from that file
              self.__nameList   :=  as invariant from that file
            else ->
              self.__scrolledList   :=  self.pickList with the color
                  names added from the internal default list
              self.__colorMap   :=  as invariant from that list
              self.__colorList  :=  as invariant from that list
              self.__nameList   :=  as invariant from that file ]
        """

We will try to find the file first; see Section 14.6, “PickList.__findColorsFile(): Read the rgb.txt file”.

        #-- 1 --
        # [ if self.COLOR_NAMES_FILE names a readable, valid
        #   rgb.txt file in one of the directories named in
        #   self.PATHS_LIST ->
        #       self.__colorMap  :=  as invariant from that file
        #   else ->
        #       self.__colorMap  :=  an empty dictionary ]
        self.__findColorsFile()

If that didn't work, set up self.__colorList from self.DEFAULT_COLORS; see Section 14.10, “PickList.__useDefaultColors(): Set up a default color list”.

        #-- 2 --
        # [ if self.__colorMap is empty ->
        #     self.__colorMap  +:=  as invariant from self.DEFAULT_COLORS
        #   else -> I ]
        if  len(self.__colorMap) == 0:
            self.__useDefaultColors()

Because of historical differences in language and naming conventions, the color files usually have a large number of redundant colors. For example, in our local rgb.txt, colors “LightSlateGray”, “LightSlateGrey”, “light slate gray”, and “light slate grey” all refer to exactly the same color. So, to make it easier for the user to scroll through the list, we'll remove redundant colors from self.__colorMap; see Section 14.11, “PickList.__cleanColorMap(): Remove redundant colors”.

        #-- 3 --
        # [ self.__colorMap  :=  self.__colorMap with redundant colors
        #       removed ]
        self.__cleanColorMap()

Now that the color set is finalized, populate the ScrolledList widget and build the self.__nameList and self.__colorList lists. Because the values in self.__colorMap are tuples starting the original color index, sorting these values will put them back in their original order.

        #-- 4 --
        # [ valueList  :=  values from self.__colorMap, sorted ]
        valueList  =  self.__colorMap.values()
        valueList.sort()

        #-- 5 --
        # [ valueList is a list of tuples (index, color, name) ->
        #     self.__scrolledList  +:=  names from valueList in the
        #                               same order
        #     self.__colorList  +:=  colors from valueList in the
        #                           same order ]
        for index, color, name in valueList:
            self.__scrolledList.append ( name )
            self.__nameList.append ( name )
            self.__colorList.append ( color )