Module: Gtk::CellLayout

Defined in:
lib/gtk3/cell-layout.rb

Overview

An interface for packing cells

GtkCellLayout is an interface to be implemented by all objects which
want to provide a GtkTreeViewColumn like API for packing cells,
setting attributes and data funcs.

One of the notable features provided by implementations of
GtkCellLayout are attributes. Attributes let you set the properties
in flexible ways. They can just be set to constant values like regular
properties. But they can also be mapped to a column of the underlying
tree model with gtk_cell_layout_set_attributes(), which means that the value
of the attribute can change from cell to cell as they are rendered by
the cell renderer. Finally, it is possible to specify a function with
gtk_cell_layout_set_cell_data_func() that is called to determine the
value of the attribute for each cell that is rendered.

GtkCellLayouts as GtkBuildable

Implementations of GtkCellLayout which also implement the GtkBuildable
interface (GtkCellView, GtkIconView, GtkComboBox,
GtkEntryCompletion, GtkTreeViewColumn) accept GtkCellRenderer objects
as <child> elements in UI definitions. They support a custom <attributes>
element for their children, which can contain multiple <attribute>
elements. Each <attribute> element has a name attribute which specifies
a property of the cell renderer; the content of the element is the
attribute value.

This is an example of a UI definition fragment specifying attributes:

<object class="GtkCellView">
  <child>
    <object class="GtkCellRendererText"/>
    <attributes>
      <attribute name="text">0</attribute>
    </attributes>
  </child>
</object>

Furthermore for implementations of GtkCellLayout that use a GtkCellArea
to lay out cells (all GtkCellLayouts in GTK use a GtkCellArea)
cell properties can also be defined
in the format by specifying the custom <cell-packing> attribute which can
contain multiple <property> elements.

Here is a UI definition fragment specifying cell properties:

<object class="GtkTreeViewColumn">
  <child>
    <object class="GtkCellRendererText"/>
    <cell-packing>
      <property name="align">True</property>
      <property name="expand">False</property>
    </cell-packing>
  </child>
</object>

Subclassing GtkCellLayout implementations

When subclassing a widget that implements GtkCellLayout like
GtkIconView or GtkComboBox, there are some considerations related
to the fact that these widgets internally use a GtkCellArea.
The cell area is exposed as a construct-only property by these
widgets. This means that it is possible to e.g. do

GtkWIdget *combo =
  g_object_new (GTK_TYPE_COMBO_BOX, "cell-area", my_cell_area, NULL);

to use a custom cell area with a combo box. But construct properties
are only initialized after instance init()
functions have run, which means that using functions which rely on
the existence of the cell area in your subclass init() function will
cause the default cell area to be instantiated. In this case, a provided
construct property value will be ignored (with a warning, to alert
you to the problem).

static void
my_combo_box_init (MyComboBox *b)
{
  GtkCellRenderer *cell;

  cell = gtk_cell_renderer_pixbuf_new ();

  // The following call causes the default cell area for combo boxes,
  // a GtkCellAreaBox, to be instantiated
  gtk_cell_layout_pack_start (GTK_CELL_LAYOUT (b), cell, FALSE);
  ...
}

GtkWidget *
my_combo_box_new (GtkCellArea *area)
{
  // This call is going to cause a warning about area being ignored
  return g_object_new (MY_TYPE_COMBO_BOX, "cell-area", area, NULL);
}

If supporting alternative cell areas with your derived widget is
not important, then this does not have to concern you. If you want
to support alternative cell areas, you can do so by moving the
problematic calls out of init() and into a constructor()
for your class.

Instance Method Summary collapse

Instance Method Details

#add_attribute(cell, name, value) ⇒ nil

Parameters:

  • cell_layout (Gtk::CellLayout) —

    a GtkCellLayout

  • cell (Gtk::CellRenderer) —

    a GtkCellRenderer

  • attribute (String) —

    a property on the renderer

  • column (Integer) —

    the column position on the model to get the attribute from

Returns:

  • (nil) 


26
27
28
29
 
# File 'lib/gtk3/cell-layout.rb', line 26

def add_attribute(cell, name, value)
  name = name.to_s if name.is_a?(Symbol)
  add_attribute_raw(cell, name, value)
end

#add_attribute_raw ⇒ nil

Parameters:

  • cell_layout (Gtk::CellLayout) —

    a GtkCellLayout

  • cell (Gtk::CellRenderer) —

    a GtkCellRenderer

  • attribute (String) —

    a property on the renderer

  • column (Integer) —

    the column position on the model to get the attribute from

Returns:

  • (nil) 



# File 'lib/gtk3/cell-layout.rb', line 25

#area ⇒ Gtk::CellArea

Returns the underlying GtkCellArea which might be cell_layout
if called on a GtkCellArea or might be nil if no GtkCellArea
is used by cell_layout.

Returns:

#cells ⇒ GLib::List<Gtk::CellRenderer>

Returns the cell renderers which have been added to cell_layout.

Returns:

  • (GLib::List<Gtk::CellRenderer>) —

    a list of cell renderers. The list, but not the renderers has
    been newly allocated and should be freed with g_list_free()
    when no longer needed.

#clear(cell_layout) ⇒ nil

Parameters:

Returns:

  • (nil)

#clear_attributes(cell_layout, cell) ⇒ nil

Parameters:

Returns:

  • (nil)

#get_area(cell_layout) ⇒ Gtk::CellArea

Returns the cell area used by cell_layout.

Parameters:

Returns:

#get_cells(cell_layout) ⇒ GLib::List<Gtk::CellRenderer>

Returns a list of cell renderers. The list, but not the renderers has
been newly allocated and should be freed with g_list_free()
when no longer needed.

Parameters:

Returns:

  • (GLib::List<Gtk::CellRenderer>) —

    a list of cell renderers. The list, but not the renderers has
    been newly allocated and should be freed with g_list_free()
    when no longer needed.

#pack_end(cell_layout, cell, expand) ⇒ nil

Parameters:

  • cell_layout (Gtk::CellLayout) —

    a GtkCellLayout

  • cell (Gtk::CellRenderer) —

    a GtkCellRenderer

  • expand (Boolean) —

    true if cell is to be given extra space allocated to cell_layout

Returns:

  • (nil)

#pack_start(cell_layout, cell, expand) ⇒ nil

Parameters:

  • cell_layout (Gtk::CellLayout) —

    a GtkCellLayout

  • cell (Gtk::CellRenderer) —

    a GtkCellRenderer

  • expand (Boolean) —

    true if cell is to be given extra space allocated to cell_layout

Returns:

  • (nil)

#reorder(cell_layout, cell, position) ⇒ nil

Parameters:

  • cell_layout (Gtk::CellLayout) —

    a GtkCellLayout

  • cell (Gtk::CellRenderer) —

    a GtkCellRenderer to reorder

  • position (Integer) —

    new position to insert cell at

Returns:

  • (nil)

#set_attributes(cell, attributes) ⇒ nil

Sets the attributes in the parameter list as the attributes
of cell_layout.

See [methodGtk.CellLayout.add_attribute] for more details.

The attributes should be in attribute/column order, as in
gtk_cell_layout_add_attribute(). All existing attributes are
removed, and replaced with the new attributes.

Parameters:

  • cell (Gtk::CellRenderer) —

    a GtkCellRenderer

  • array (Array) —

    a nil-terminated list of attributes

Returns:

  • (nil) 


19
20
21
22
23
 
# File 'lib/gtk3/cell-layout.rb', line 19

def set_attributes(cell, attributes)
  attributes.each do |key, value|
    add_attribute(cell, key, value)
  end
end

#set_cell_data_func(cell_layout, cell, func, func_data, destroy) ⇒ nil

Parameters:

  • cell_layout (Gtk::CellLayout) —

    a GtkCellLayout

  • cell (Gtk::CellRenderer) —

    a GtkCellRenderer

  • func (Gtk::CellLayoutDataFunc) —

    the GtkCellLayoutDataFunc to use

  • func_data (GObject) —

    user data for func

  • destroy (GLib::DestroyNotify) —

    destroy notify for func_data

Returns:

  • (nil)