def edit_colors(
        self,
        color_value=((255, 0, 0),),
        color_format="rgb_tuple",
        alone_when_single=True,
    ):
        """Display dialog to edit/pick colors.

        Note that, during the editing session, the color
        value is treated as though the color_format and
        alone_when_single parameters are set to 'rgb_ints'
        and False, respectively, regardless of the values
        provided by the user.

        The values provided by the user for those parameters
        are relevant, though. Such actual values received
        are used when returning the value back at the end
        of the editing session, if the user doesn't cancel
        the editing session.

        Parameters
        ==========

        color_value (special value)

            if an special value, it must be an object
            representing one or multiple color values;

            it may be in different formats:

            1) a tuple of RGB(A) values (integers so that
               0 <= integer <= 255), representing a
               single color;
            2) a string representing a color in hex
               format using '#ffffff' or '#ffffffff'
               format, representing a single color;
            3) a tuple in which each item represents a
               color; such items must all be in the
               format specified in either the item 1)
               or item 2), never both.

        color_format (string)

            either 'rgb_tuple', if individual colors
            must use the representation described in
            the item (1) of the 'color_value' parameter
            explanation above or 'hex_string', if the
            format in item (2) must be used instead;

        alone_when_single (boolean)

            when True, instead of a tuple of colors, the
            color itself is used as the value when the
            color value represents a single color (that is,
            when True, if only one color is stored, it will
            be either a string or a tuple of integers
            representing a single color, instead of a tuple
            containing such color);

            for instance, for
            color_format='hex_string' and
            alone_when_single=True, say the value of the
            button is ['#ffffff', '#00ff00aa'], if you
            go and delete any color (for instance, the
            second one), instead of ['#ffffff'] as the
            value of the button, you'll end up with
            '#ffffff' (that is, the string itself).
        """
        ### set a edition session cancelation flag to False
        self.cancel_edition = False

        ### treat the color properly in order to obtain a
        ### tuple of full rgb colors

        ## convert color value to a tuple of rgb colors

        try:
            colors = custom_format_color(color_value, "rgb_tuple", False)

        ## XXX maybe show a dialog with the
        ## error message here? or just print on the
        ## screen? probably also log the error;
        ## ponder;

        ## if a value error is raised, though,
        ## it means  there's something wrong with
        ## the given value, so we return earlier
        except ValueError:
            return None

        ### set the full rgb colors into the colors panel
        self.colors_panel.set_colors(colors)

        ### loop
        self.loop()

        ### blit a semitransparent surface over the screen
        ### on the area occupied by self.rect to leave the
        ### area temporarily darkened in case it keeps
        ### showing even after leaving this color picker
        ### (in some cases the loop holder which called
        ### this method might not care to update the area
        ### of the screen previously occupied by this color
        ### picker, making it so it keeps appearing as if
        ### it was still active on the screen)
        self.unhighlight()

        ### define appropriate value to return according
        ### to the value of the "cancel edition flag"

        to_return = (
            ## if the "cancel edition flag" is turned on,
            ## the value is None
            None
            if self.cancel_edition
            ## otherwise, it is the edited color(s) from
            ## the colors panel, converted according to
            ## the settings given as the 'color_format'
            ## and 'alone_when_single' arguments
            else custom_format_color(
                self.colors_panel.get_colors(), color_format, alone_when_single
            )
        )

        ### finally, return the value after freeing up
        ### memory used by the colors panel

        self.colors_panel.free_up_memory()

        return to_return
Display dialog to edit/pick colors.

        Note that, during the editing session, the color
        value is treated as though the color_format and
        alone_when_single parameters are set to 'rgb_ints'
        and False, respectively, regardless of the values
        provided by the user.

        The values provided by the user for those parameters
        are relevant, though. Such actual values received
        are used when returning the value back at the end
        of the editing session, if the user doesn't cancel
        the editing session.

        Parameters
        ==========

        color_value (special value)

            if an special value, it must be an object
            representing one or multiple color values;

            it may be in different formats:

            1) a tuple of RGB(A) values (integers so that
               0 <= integer <= 255), representing a
               single color;
            2) a string representing a color in hex
               format using '#ffffff' or '#ffffffff'
               format, representing a single color;
            3) a tuple in which each item represents a
               color; such items must all be in the
               format specified in either the item 1)
               or item 2), never both.

        color_format (string)

            either 'rgb_tuple', if individual colors
            must use the representation described in
            the item (1) of the 'color_value' parameter
            explanation above or 'hex_string', if the
            format in item (2) must be used instead;

        alone_when_single (boolean)

            when True, instead of a tuple of colors, the
            color itself is used as the value when the
            color value represents a single color (that is,
            when True, if only one color is stored, it will
            be either a string or a tuple of integers
            representing a single color, instead of a tuple
            containing such color);

            for instance, for
            color_format='hex_string' and
            alone_when_single=True, say the value of the
            button is ['#ffffff', '#00ff00aa'], if you
            go and delete any color (for instance, the
            second one), instead of ['#ffffff'] as the
            value of the button, you'll end up with
            '#ffffff' (that is, the string itself).
        
nodezator/colorsman/editor/loopop.py