huey: Internal maintenance specification

This class is a compound widget containing the list of standard color names. It responds to user clicks by calling its callback function with a Color instance. It also contains a translation table for converting its color names to color values. For an important discussion of the two methods of converting color names, see Section 13.4, “NamePicker.__setByName(): Try to convert a color name to a color”.

In GUI terms, it is a frame containing only a single widget, a ScrolledList. This widget is a compound widget from the author's widget library. It is a combination of a Tkinter Listbox widget with a vertical Scrollbar. For particulars of its call and implementation, see Section 4.1, “Imports”.

To populate this list with standard color names, there are two possible sources. On most Unix boxen, there is a file named rgb.txt that defines the names and values. Depending on the age of the install, it may be in one of these paths; the first one reflects the more recent practice:

/usr/share/X11
/usr/lib/X11

However, just so this program isn't useless in the absence of the file, this class contains an internal version of rgb.txt as a fallback measure.

Here is the class interface:

# - - - - -   c l a s s   P i c k L i s t

class PickList(Frame):
    """Compound widget for the color pick list.

      Exports:
        PickList ( parent, callback=None ):
          [ (parent is a Frame) and
            (callback is a function or None) ->
              parent  :=  parent with a new PickList widget added
                  but not gridded
              return that new widget ]

This method allows the caller to translate a color name to a Color instance; see Section 14.3, “PickList.lookupName(): Convert a color name to a color value”.

        .lookupName ( colorName ):
          [ colorName is a string ->
              if colorName matches a color in self's list,
              case-insensitive ->
                return the corresponding value as a Color instance
              else -> return None ]

      Contained widgets:
        .__scrolledList:
          [ a scrolledlist.ScrolledList containing self's color
            names ]

      Grid plan:  Only one widget

Here are the internal attributes. First, we keep a copy of the callback procedure.

      State/Invariants:
        .__callback:    [ as passed to the constructor ]

For internal data structures, we need to be able to look up colors both by name and by their position in the pick list. The lists .__colorList and .__nameList are by position: the nth element in self.__colorList is the color displayed in the nth line of the pick list, and the nth element of self.__nameList is the name of the color displayed in that line.

        .__colorList:
          [ a list of Color instances such that self.__colorList[i]
            is the value of the color displayed in the (i)th line
            of self.__scrolledList, as a Color instance ]
        .__nameList:
          [ a list of color names such that self.__nameList[i]
            is the name of the color displayed in the (i)th line
            of self.__scrolledList ]

The obvious data structure for looking up color names is a dictionary. To make the lookup case-insensitive, the keys of this dictionary are the color names, uppercased. Each value in the dictionary is a tuple (index, color, name), where:

        .__colorMap:
          [ a dictionary whose keys are the color names in self,
            uppercased, and each value is a tuple (index, color,
            name) where index orders the colors in their original
            source order, color is a Color instance, and name is
            the color name as a string ]
    """