Chapter 17. Setting Widget Attributes

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

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

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

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

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

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.