manpagez: man pages & more
html files: pygtk
Home | html | info | man
): gtk.gdk.Color(red=0, green=0, blue=0, pixel=0)
def to_string()
Functions

    def gtk.gdk.color_parse(spec)
def gtk.gdk.color_from_hsv(hue, saturation, value)

Attributes

Note

Floating-point and HSV attributes are available in PyGTK 2.16 and above.

"pixel"Read-WriteThe pixel value of the color
"red"Read-WriteThe value of the red component of the color
"green"Read-WriteThe value of the green component of the color
"blue"Read-WriteThe value of the blue component of the color
"red_float"Read-WriteThe value of the red component of the color as a float in the range 0.0--1.0
"green_float"Read-WriteThe value of the green component of the color as a float in the range 0.0--1.0
"blue_float"Read-WriteThe value of the blue component of the color as a float in the range 0.0--1.0
"hue"ReadThe hue (in HSV colorspace) of the color as a float in the range 0.0--1.0
"saturation"ReadThe saturation (in HSV colorspace) of the color as a float in the range 0.0--1.0
"value"ReadThe value (in HSV colorspace) of the color as a float in the range 0.0--1.0

For details on how assignment to *_float attributes work, see constructor documentation.

Description

A gtk.gdk.Color contains the values of a color that may or may not be allocated. The red, green and blue attributes are specified by an unsigned integer in the range 0-65535. The pixel value is an index into the colormap that has allocated the gtk.gdk.Color. Typically a color is allocated by using the gdk.Colormap.alloc_color() method. Unallocated colors can be used to specify the color attributes of gtk.Style objects since these colors will be allocated when an attempt is made to use the gtk.Style object.

Starting with PyGTK 2.14 gtk.gdk.Color objects are properly comparable. By Python rules, colors (being mutable) are now unhashable. If you need to use them as dictionary keys, use string representation instead. You can convert string representation to gtk.gdk.Color objects using the constructor.

Also beginning with PyGTK 2.14 gtk.gdk.Color objects have custom support for str and repr Python functions. For any color it holds that:

  color == eval(repr(color))
    

PyGTK 2.16 introduces several ways of using floating-point numbers for creating gtk.gdk.Color objects or setting their individual components. In all cases it was decided to silently clamp input values to valid range, rather than being strict and e.g. raise an exception. The rationale is that floating-point arithmetics are imprecise, so you could end with a computed value slightly larger than maximum or a little smaller than minimum valid value. To simplify using new features, such "slightly off" values are just clamped without any warning.

Constructor

    gtk.gdk.Color(red=0, green=0, blue=0, pixel=0)
    gtk.gdk.Color(spec)

red :

The red color component in the range 0-65535

green :

The green color component in the range 0-65535

blue :

The blue color component in the range 0-65535

pixel :

The index of the color when allocated in its colormap

spec :

String containing color specification

Returns :

a new gtk.gdk.Color object

Note

Second form of the constructor is available in PyGTK 2.14 and above.

Note

red, green and blue can be floating-point numbers since PyGTK 2.16.

Creates a new gtk.gdk.Color object with the color component values specified by red, green and blue (all default to 0) and using the pixel value specified by pixel. The value of pixel will be overwritten when the color is allocated.

Second form of the constructor is analogous to gtk.gdk.color_parse.

Starting with PyGTK 2.16, red, green and blue parameters can also be floating-point numbers in the range 0.0--1.0. Either all specified values must be integers or floats -- mixing is not allowed as this would be too error-prone. Values outside the valid range 0.0--1.0 are clamped, so e.g. 3.14 is the same as 1.0.

Note that internally values are still stored as integers, so values of corresponding *_float attribute will not necessarily be the same as the value used as argument for the constructor. They will be as close as permitted by 16-bit color component storage used by GdkColor though.

All of the following expressions create a bright green color:

  gtk.gdk.Color(0, 65535, 0)
  gtk.gdk.Color(green=1.0)
  gtk.gdk.Color('#0f0')
    

Methods

gtk.gdk.Color.to_string

    def to_string()

Returns :

a string

Note

This method is available in PyGTK 2.12 and above.

The to_string() method returns a textual specification of color in the hexadecimal form #rrrrggggbbbb, where r, g and b are hex digits representing the red, green and blue components respectively.

Note

Starting with PyGTK 2.14 you can also use str(color) code. However, that can return a shorter (3, 6 or 12 hexadecimal digits) string if shorter version means the same for the constructor.

Functions

gtk.gdk.color_parse

    def gtk.gdk.color_parse(spec)

spec :

a string containing a color specification

Returns :

a gtk.gdk.Color object

The gtk.gdk.color_parse() method returns the gtk.gdk.Color specified by spec. The format of spec is a string containing the specification of the color either as a name (e.g. "navajowhite") as specified in the X11 rgb.txt file or as a hexadecimal string (e.g. "#FF0078"). The hexadecimal string must start with '#' and must contain 3 sets of hexadecimal digits of the same length (i.e. 1, 2 ,3 or 4 digits). For example the following specify the same color value: "#F0A", "#FF00AA", "#FFF000AAA" and "#FFFF0000AAAA". The gtk.gdk.Color is not allocated.

This function raise the ValueError (TypeError prior to PyGTK 2.4) exception if unable to parse the color specification

gtk.gdk.color_from_hsv

    def gtk.gdk.color_from_hsv(hue, saturation, value)

hue :

Hue of the desired color as a float in range 0.0--1.0

saturation :

Saturation of the desired color as a float in range 0.0--1.0

value :

Value of the desired color as a float in range 0.0--1.0

Returns :

a gtk.gdk.Color object

Note

This function is available in PyGTK 2.16 and above.

The gtk.gdk.color_from_hsv() method returns the gtk.gdk.Color specified by the HSV parameters. All three parameters are mandatory and should be floats from 0.0 to 1.0. The range requirement, however, is not strict, see below.

As hue goes from 0 to 1 color goes roughly as red → yellow → green → cyan → blue → magenta → red. Because of the "circular" nature, this parameter wraps around, so only fractional part matters. E.g. -4.2 or 1.8 are the same as 0.8. Saturation determines how intense a color is, with 0.0 meaning pure gray and 1.0 -- fully intense color. Value determines how light a color is, with 0.0 standing for fully black and 1.0 for completely white color. Both saturation and value are clamped to valid range (see rationale at the top of the page).

Note that internal storage is still integers, so values of corresponding hue, saturation and value attributes of the returned object will not necessarily be equal to the value used as argument for this functions. They will be as close as permitted by 16-bit color component storage used by GdkColor though.

For more details read about HSV colorspace.

© manpagez.com 2000-2017
Individual documents may contain additional copyright information.