Chapter 17. Setting Widget Attributes

This describes the methods used to operate on widgets (and objects). These can be used to set style, padding, size, etc.

The method:
 
widget.activate()

causes the widget to emit the "activate" signal.

The method:
 
widget.set_sensitive(sensitive)

sets the sensitivity of the widget (i.e. does it react to events). if sensitive is TRUE the widget will receive events; if FALSE the widget will not receive events. A widget that is insensitive is usually displayed "grayed out".

The method:
 
widget.set_uposition(x, y)

sets the location of the widget in its parent window using the x and y coordinates.

The method:
 
widget.set_usize(width, height)

sets the widget size to the given width and height.

17.1 Widget Flag Methods

The methods:
 
widget.set_flags(flags)
flags = widget.flags()

set and get the GtkObject and GtkWidget flags. flags can be any of the standard flags:
 
    DESTROYED
    FLOATING
    CONNECTED
    CONSTRUCTED
    TOPLEVEL
    NO_WINDOW
    REALIZED
    MAPPED
    VISIBLE
    SENSITIVE
    PARENT_SENSITIVE
    CAN_FOCUS
    HAS_FOCUS
    CAN_DEFAULT
    HAS_DEFAULT
    HAS_GRAB
    RC_STYLE
    COMPOSITE_CHILD
    NO_REPARENT
    APP_PAINTABLE
    RECEIVES_DEFAULT

The method:
 
widget.grab_focus()

allows a widget to grab the focus assuming that it has the CAN_FOCUS flag set.

17.2 Widget Display Methods

The methods:
 
widget.show()

widget.hide()
widget.realize()
widget.unrealize()
widget.map()
widget.unmap()

manage the display of the widget.

The show() method arrange to display the widget by using the realize() and map() methods.

The hide() method arranges to remove the widget from the display and also unmaps it using the unmap() method if necessary.
The realize() method arranges to allocate resources to the widget including its window.

The unrealize() method releases the widget window and other resources. Unrealizing a widget will also hide and unmap it.

The map() method arranges to allocate space on the display for the widget; this only applies to widgets that need to be handled by the window manager. Mapping a widget will also cause it to be realized if necessary.

The unmap() method removes a widget from the display and will also hide it if necessary.

17.3 Widget Accelerators

The following methods:
 
widget.add_accelerator(accel_signal, accel_group, accel_key, accel_mods, accel_flags)
widget.remove_accelerator(accel_group, accel_key, accel_mods)

add and remove accelerators from a GtkAcceleratorGroup that must be attached to the top level widget to handle the accelerators.

The accel_signal is a signal that is valid for the widget to emit.

The accel_key is a keyboard key to use as the accelerator.

The accel_mods are modifiers (defined in GDK.py) to add to the accel_key (e.g. Shift, Control, etc.):
 
SHIFT_MASK
LOCK_MASK
CONTROL_MASK
MOD1_MASK
MOD2_MASK
MOD3_MASK
MOD4_MASK
MOD5_MASK
BUTTON1_MASK
BUTTON2_MASK
BUTTON3_MASK
BUTTON4_MASK
BUTTON5_MASK
RELEASE_MASK

The accel_flags set options about how the accelerator information is displayed. Valid values are:
 
ACCEL_VISIBLE         # display the accelerator key in the widget display
ACCEL_SIGNAL_VISIBLE  # display the signal information in the widget display
ACCEL_LOCKED          # do not allow the accelerator display to change

An accelerator group is created by the function:
 
accel_group = GtkAcceleratorGroup()

The accel_group is attached to a top level widget with the following method:
 
accel_group.attach(window)

An example of adding an accelerator:
 
menu_item.add_accelerator("activate", accel_group,
                          ord('Q'), GDK.CONTROL_MASK, ACCEL_VISIBLE)

17.4 Widget Name Methods

The following widget methods set and get the name of a widget:
 
widget.set_name(name)

name = widget.get_name()

name is the string that will be associated with the widget. This is useful for specifying styles to be used with specific widgets within an application. The name of the widget can be used to narrow the application of the style as opposed to using the widget's class. See the chapter on using GTK's rc Files for more details.

17.5 Widget Styles

The following methods get and set the style associated with a widget:
 
widget.set_style(style)
                                           
style = widget.get_style()

The following functions:
 
style = get_default_style()
set_default_style(style)

set and get the default style. Any widgets created after the default style has been changed will be created with the new default style.

A style contains the graphics information needed by a widget to draw itself in its various states:
 
STATE_NORMAL        # The state during normal operation.
STATE_ACTIVE        # The widget is currently active, such as a button pushed
STATE_PRELIGHT      # The mouse pointer is over the widget.
STATE_SELECTED      # The widget is selected
STATE_INSENSITIVE   # The widget is disabled

A style contains the following attributes:
 
fg          # a list of 5 foreground colors - one for each state
bg          # a list of 5 background colors
light       # a list of 5 colors - created during set_style() method
dark        # a list of 5 colors - created during set_style() method
mid         # a list of 5 colors - created during set_style() method
text        # a list of 5 colors
base        # a list of 5 colors
black       # the black color
white       # the white color
font        # the default font
fg_gc       # a list of 5 graphics contexts - created during set_style() method
bg_gc       # a list of 5 graphics contexts - created during set_style() method
light_gc    # a list of 5 graphics contexts - created during set_style() method
dark_gc     # a list of 5 graphics contexts - created during set_style() method
mid_gc      # a list of 5 graphics contexts - created during set_style() method
text_gc     # a list of 5 graphics contexts - created during set_style() method
base_gc     # a list of 5 graphics contexts - created during set_style() method
black_gc    # a list of 5 graphics contexts - created during set_style() method
white_gc    # a list of 5 graphics contexts - created during set_style() method
bg_pixmap   # a list of 5 GdkPixmaps

Each attribute can be accessed directly similar to style.black and style.fg_gc[STATE_NORMAL].

An existing style can be copied for later modification by using the method:
 
new_style = style.copy()

which copies the style attributes except for the graphics context lists and the light, dark and mid color lists.

To change the style of a widget (e.g. to change the widget foreground color), the procedure is:
 
# copy the current widget style
style = widget.get_style().copy()
# change the style attributes
new_style.font = new_font
new_style.bg[STATE_NORMAL] = widget.get_colormap().alloc(65535, 0, 0)
# fill out the new style by attaching it to the widget
widget.set_style(new_style)

Setting the style will allocate the new_style colors and create the graphics contexts. Most widgets will automatically redraw themselves after the style is changed.

Not all style changes will affect the widget. For example, changing the Label widget background color will not change the label background color because the Label widget does not have its own GdkWIndow. The background of the label is dependent on the background color of the label's parent. The use of an EventBox to hold a Label will allow the Label background color to be set. See the EventBox section for an example.