text: #===========================================================================
  #
  # StrConverter
  #
  #===========================================================================
  
  """StrConverter module containing class StrConverter."""
  
  #===========================================================================
  # Place all imports after here.
  #
  import matplotlib.units as units
  from matplotlib.cbook import iterable
  
  # Place all imports before here.
  #===========================================================================
  
  __all__ = [ 'StrConverter' ]
  
  #===========================================================================
  class StrConverter( units.ConversionInterface ):
     """: A matplotlib converter class.  Provides matplotlib conversion
          functionality for string data values.
  
     Valid units for string are:
     - 'indexed' : Values are indexed as they are specified for plotting.
     - 'sorted'  : Values are sorted alphanumerically.
     - 'inverted' : Values are inverted so that the first value is on top.
     - 'sorted-inverted' :  A combination of 'sorted' and 'inverted'
     """
  
     #------------------------------------------------------------------------
     @staticmethod
     def axisinfo( unit, axis ):
        """: Returns information on how to handle an axis that has string data.
  
        = INPUT VARIABLES
        - axis    The axis using this converter.
        - unit    The units to use for a axis with string data.
  
        = RETURN VALUE
        - Returns a matplotlib AxisInfo data structure that contains
          minor/major formatters, major/minor locators, and default
          label information.
        """
  
        return None
  
     #------------------------------------------------------------------------
     @staticmethod
     def convert( value, unit, axis ):
        """: Convert value using unit to a float.  If value is a sequence, return
        the converted sequence.
  
        = INPUT VARIABLES
        - axis    The axis using this converter.
        - value   The value or list of values that need to be converted.
        - unit    The units to use for a axis with Epoch data.
  
        = RETURN VALUE
        - Returns the value parameter converted to floats.
        """
  
        if ( units.ConversionInterface.is_numlike( value ) ):
           return value
  
        if ( value == [] ):
           return []
  
        # we delay loading to make matplotlib happy
        ax = axis.axes
        if axis is ax.get_xaxis():
           isXAxis = True
        else:
           isXAxis = False
  
        axis.get_major_ticks()
        ticks = axis.get_ticklocs()
        labels = axis.get_ticklabels()
  
        labels = [ l.get_text() for l in labels if l.get_text() ]
  
        if ( not labels ):
           ticks = [] 
           labels = []
  
  
        if ( not iterable( value ) ):
           value = [ value ]
  
        newValues = []
        for v in value:
           if ( (v not in labels) and (v not in newValues) ):
              newValues.append( v )
  
        for v in newValues:
           if ( labels ):
              labels.append( v )
           else:
              labels = [ v ]
  
        #DISABLED: This is disabled because matplotlib bar plots do not
        #DISABLED: recalculate the unit conversion of the data values
        #DISABLED: this is due to design and is not really a bug.
        #DISABLED: If this gets changed, then we can activate the following
        #DISABLED: block of code.  Note that this works for line plots.
        #DISABLED if ( unit ):
        #DISABLED    if ( unit.find( "sorted" ) > -1 ):
        #DISABLED       labels.sort()
        #DISABLED    if ( unit.find( "inverted" ) > -1 ):
        #DISABLED       labels = labels[ ::-1 ]
  
        # add padding (so they do not appear on the axes themselves)
        labels = [ '' ] + labels + [ '' ]
        ticks = range( len(labels) )
        ticks[0] = 0.5
        ticks[-1] = ticks[-1] - 0.5
  
        axis.set_ticks( ticks )
        axis.set_ticklabels( labels )
        # we have to do the following lines to make ax.autoscale_view work
        loc = axis.get_major_locator()
        loc.set_bounds( ticks[0], ticks[-1] )
  
        if ( isXAxis ):
           ax.set_xlim( ticks[0], ticks[-1] )
        else:
           ax.set_ylim( ticks[0], ticks[-1] )
  
        result = []
        for v in value:
           # If v is not in labels then something went wrong with adding new
           # labels to the list of old labels.
           errmsg  = "This is due to a logic error in the StrConverter class.  "
           errmsg += "Please report this error and its message in bugzilla."
           assert ( v in labels ), errmsg
           result.append( ticks[ labels.index(v) ] )
  
        ax.viewLim.ignore(-1)
        return result
  
     #------------------------------------------------------------------------
     @staticmethod
     def default_units( value, axis ):
        """: Return the default unit for value, or None.
  
        = INPUT VARIABLES
        - axis    The axis using this converter.
        - value   The value or list of values that need units.
  
        = RETURN VALUE
        - Returns the default units to use for value.
        Return the default unit for value, or None.
        """
  
        # The default behavior for string indexing.
        return "indexed"
  
  