![]() |
![]() |
![]() |
GTK+ 3 Reference Manual | ![]() |
---|---|---|---|---|
Top | Description |
#include <gtk/gtk.h> enum GtkCellRendererState; enum GtkCellRendererMode; GtkCellRenderer; GtkCellRendererClass; void gtk_cell_renderer_get_aligned_area (GtkCellRenderer *cell
,GtkWidget *widget
,GtkCellRendererState flags
,const GdkRectangle *cell_area
,GdkRectangle *aligned_area
); void gtk_cell_renderer_get_size (GtkCellRenderer *cell
,GtkWidget *widget
,const GdkRectangle *cell_area
,gint *x_offset
,gint *y_offset
,gint *width
,gint *height
); void gtk_cell_renderer_render (GtkCellRenderer *cell
,cairo_t *cr
,GtkWidget *widget
,const GdkRectangle *background_area
,const GdkRectangle *cell_area
,GtkCellRendererState flags
); gboolean gtk_cell_renderer_activate (GtkCellRenderer *cell
,GdkEvent *event
,GtkWidget *widget
,const gchar *path
,const GdkRectangle *background_area
,const GdkRectangle *cell_area
,GtkCellRendererState flags
); GtkCellEditable * gtk_cell_renderer_start_editing (GtkCellRenderer *cell
,GdkEvent *event
,GtkWidget *widget
,const gchar *path
,const GdkRectangle *background_area
,const GdkRectangle *cell_area
,GtkCellRendererState flags
); void gtk_cell_renderer_stop_editing (GtkCellRenderer *cell
,gboolean canceled
); void gtk_cell_renderer_get_fixed_size (GtkCellRenderer *cell
,gint *width
,gint *height
); void gtk_cell_renderer_set_fixed_size (GtkCellRenderer *cell
,gint width
,gint height
); gboolean gtk_cell_renderer_get_visible (GtkCellRenderer *cell
); void gtk_cell_renderer_set_visible (GtkCellRenderer *cell
,gboolean visible
); gboolean gtk_cell_renderer_get_sensitive (GtkCellRenderer *cell
); void gtk_cell_renderer_set_sensitive (GtkCellRenderer *cell
,gboolean sensitive
); void gtk_cell_renderer_get_alignment (GtkCellRenderer *cell
,gfloat *xalign
,gfloat *yalign
); void gtk_cell_renderer_set_alignment (GtkCellRenderer *cell
,gfloat xalign
,gfloat yalign
); void gtk_cell_renderer_get_padding (GtkCellRenderer *cell
,gint *xpad
,gint *ypad
); void gtk_cell_renderer_set_padding (GtkCellRenderer *cell
,gint xpad
,gint ypad
); GtkStateFlags gtk_cell_renderer_get_state (GtkCellRenderer *cell
,GtkWidget *widget
,GtkCellRendererState cell_state
); gboolean gtk_cell_renderer_is_activatable (GtkCellRenderer *cell
); void gtk_cell_renderer_get_preferred_height (GtkCellRenderer *cell
,GtkWidget *widget
,gint *minimum_size
,gint *natural_size
); void gtk_cell_renderer_get_preferred_height_for_width (GtkCellRenderer *cell
,GtkWidget *widget
,gint width
,gint *minimum_height
,gint *natural_height
); void gtk_cell_renderer_get_preferred_size (GtkCellRenderer *cell
,GtkWidget *widget
,GtkRequisition *minimum_size
,GtkRequisition *natural_size
); void gtk_cell_renderer_get_preferred_width (GtkCellRenderer *cell
,GtkWidget *widget
,gint *minimum_size
,gint *natural_size
); void gtk_cell_renderer_get_preferred_width_for_height (GtkCellRenderer *cell
,GtkWidget *widget
,gint height
,gint *minimum_width
,gint *natural_width
); GtkSizeRequestMode gtk_cell_renderer_get_request_mode (GtkCellRenderer *cell
);
The GtkCellRenderer is a base class of a set of objects used for rendering a cell to a cairo_t. These objects are used primarily by the GtkTreeView widget, though they aren't tied to them in any specific way. It is worth noting that GtkCellRenderer is not a GtkWidget and cannot be treated as such.
The primary use of a GtkCellRenderer is for drawing a certain graphical
elements on a cairo_t. Typically, one cell renderer is used to
draw many cells on the screen. To this extent, it isn't expected that a
CellRenderer keep any permanent state around. Instead, any state is set
just prior to use using GObjects property system. Then, the
cell is measured using gtk_cell_renderer_get_size()
. Finally, the cell
is rendered in the correct location using gtk_cell_renderer_render()
.
There are a number of rules that must be followed when writing a new GtkCellRenderer. First and formost, its important that a certain set of properties will always yield a cell renderer of the same size, barring a GtkStyle change. The GtkCellRenderer also has a number of generic properties that are expected to be honored by all children.
Beyond merely rendering a cell, cell renderers can optionally provide active user interface elements. A cell renderer can be activatable like GtkCellRendererToggle, which toggles when it gets activated by a mouse click, or it can be editable like GtkCellRendererText, which allows the user to edit the text using a GtkEntry. To make a cell renderer activatable or editable, you have to implement the GtkCellRendererClass.activate or GtkCellRendererClass.start_editing virtual functions, respectively.
typedef enum { GTK_CELL_RENDERER_SELECTED = 1 << 0, GTK_CELL_RENDERER_PRELIT = 1 << 1, GTK_CELL_RENDERER_INSENSITIVE = 1 << 2, /* this flag means the cell is in the sort column/row */ GTK_CELL_RENDERER_SORTED = 1 << 3, GTK_CELL_RENDERER_FOCUSED = 1 << 4 } GtkCellRendererState;
Tells how a cell is to be rendererd.
The cell is currently selected, and probably has a selection colored background to render to. | |
The mouse is hovering over the cell. | |
The cell is drawn in an insensitive manner | |
The cell is in a sorted row | |
The cell is in the focus row. |
typedef enum { GTK_CELL_RENDERER_MODE_INERT, GTK_CELL_RENDERER_MODE_ACTIVATABLE, GTK_CELL_RENDERER_MODE_EDITABLE } GtkCellRendererMode;
Identifies how the user can interact with a particular cell.
The cell is just for display and cannot be interacted with. Note that this doesn't mean that eg. the row being drawn can't be selected -- just that a particular element of it cannot be individually modified. | |
The cell can be clicked. | |
The cell can be edited or otherwise modified. |
typedef struct { GInitiallyUnownedClass parent_class; /* vtable - not signals */ GtkSizeRequestMode (* get_request_mode) (GtkCellRenderer *cell); void (* get_preferred_width) (GtkCellRenderer *cell, GtkWidget *widget, gint *minimum_size, gint *natural_size); void (* get_preferred_height_for_width) (GtkCellRenderer *cell, GtkWidget *widget, gint width, gint *minimum_height, gint *natural_height); void (* get_preferred_height) (GtkCellRenderer *cell, GtkWidget *widget, gint *minimum_size, gint *natural_size); void (* get_preferred_width_for_height) (GtkCellRenderer *cell, GtkWidget *widget, gint height, gint *minimum_width, gint *natural_width); void (* get_aligned_area) (GtkCellRenderer *cell, GtkWidget *widget, GtkCellRendererState flags, const GdkRectangle *cell_area, GdkRectangle *aligned_area); void (* get_size) (GtkCellRenderer *cell, GtkWidget *widget, const GdkRectangle *cell_area, gint *x_offset, gint *y_offset, gint *width, gint *height); void (* render) (GtkCellRenderer *cell, cairo_t *cr, GtkWidget *widget, const GdkRectangle *background_area, const GdkRectangle *cell_area, GtkCellRendererState flags); gboolean (* activate) (GtkCellRenderer *cell, GdkEvent *event, GtkWidget *widget, const gchar *path, const GdkRectangle *background_area, const GdkRectangle *cell_area, GtkCellRendererState flags); GtkCellEditable * (* start_editing) (GtkCellRenderer *cell, GdkEvent *event, GtkWidget *widget, const gchar *path, const GdkRectangle *background_area, const GdkRectangle *cell_area, GtkCellRendererState flags); /* Signals */ void (* editing_canceled) (GtkCellRenderer *cell); void (* editing_started) (GtkCellRenderer *cell, GtkCellEditable *editable, const gchar *path); /* Padding for future expansion */ void (*_gtk_reserved1) (void); void (*_gtk_reserved2) (void); void (*_gtk_reserved3) (void); void (*_gtk_reserved4) (void); } GtkCellRendererClass;
void gtk_cell_renderer_get_aligned_area (GtkCellRenderer *cell
,GtkWidget *widget
,GtkCellRendererState flags
,const GdkRectangle *cell_area
,GdkRectangle *aligned_area
);
Gets the aligned area used by cell
inside cell_area
. Used for finding
the appropriate edit and focus rectangle.
|
a GtkCellRenderer instance |
|
the GtkWidget this cell will be rendering to |
|
render flags |
|
cell area which would be passed to gtk_cell_renderer_render()
|
|
the return location for the space inside cell_area
that would acually be used to render. [out]
|
Since 3.0
void gtk_cell_renderer_get_size (GtkCellRenderer *cell
,GtkWidget *widget
,const GdkRectangle *cell_area
,gint *x_offset
,gint *y_offset
,gint *width
,gint *height
);
gtk_cell_renderer_get_size
has been deprecated since version 3.0 and should not be used in newly-written code. Use gtk_cell_renderer_get_preferred_size()
instead.
Obtains the width and height needed to render the cell. Used by view
widgets to determine the appropriate size for the cell_area passed to
gtk_cell_renderer_render()
. If cell_area
is not NULL
, fills in the
x and y offsets (if set) of the cell relative to this location.
Please note that the values set in width
and height
, as well as those
in x_offset
and y_offset
are inclusive of the xpad and ypad properties.
|
a GtkCellRenderer |
|
the widget the renderer is rendering to |
|
The area a cell will be allocated, or NULL . [allow-none]
|
|
location to return x offset of cell relative to cell_area , or NULL . [out][allow-none]
|
|
location to return y offset of cell relative to cell_area , or NULL . [out][allow-none]
|
|
location to return width needed to render a cell, or NULL . [out][allow-none]
|
|
location to return height needed to render a cell, or NULL . [out][allow-none]
|
void gtk_cell_renderer_render (GtkCellRenderer *cell
,cairo_t *cr
,GtkWidget *widget
,const GdkRectangle *background_area
,const GdkRectangle *cell_area
,GtkCellRendererState flags
);
Invokes the virtual render function of the GtkCellRenderer. The three
passed-in rectangles are areas in cr
. Most renderers will draw within
cell_area
; the xalign, yalign, xpad, and ypad fields of the GtkCellRenderer
should be honored with respect to cell_area
. background_area
includes the
blank space around the cell, and also the area containing the tree expander;
so the background_area
rectangles for all cells tile to cover the entire
window
.
|
a GtkCellRenderer |
|
a cairo context to draw to |
|
the widget owning window
|
|
entire cell area (including tree expanders and maybe padding on the sides) |
|
area normally rendered by a cell renderer |
|
flags that affect rendering |
gboolean gtk_cell_renderer_activate (GtkCellRenderer *cell
,GdkEvent *event
,GtkWidget *widget
,const gchar *path
,const GdkRectangle *background_area
,const GdkRectangle *cell_area
,GtkCellRendererState flags
);
Passes an activate event to the cell renderer for possible processing. Some cell renderers may use events; for example, GtkCellRendererToggle toggles when it gets a mouse click.
|
a GtkCellRenderer |
|
a GdkEvent |
|
widget that received the event |
|
widget-dependent string representation of the event location; e.g. for GtkTreeView, a string representation of GtkTreePath |
|
background area as passed to gtk_cell_renderer_render()
|
|
cell area as passed to gtk_cell_renderer_render()
|
|
render flags |
Returns : |
TRUE if the event was consumed/handled
|
GtkCellEditable * gtk_cell_renderer_start_editing (GtkCellRenderer *cell
,GdkEvent *event
,GtkWidget *widget
,const gchar *path
,const GdkRectangle *background_area
,const GdkRectangle *cell_area
,GtkCellRendererState flags
);
Passes an activate event to the cell renderer for possible processing.
|
a GtkCellRenderer |
|
a GdkEvent |
|
widget that received the event |
|
widget-dependent string representation of the event location; e.g. for GtkTreeView, a string representation of GtkTreePath |
|
background area as passed to gtk_cell_renderer_render()
|
|
cell area as passed to gtk_cell_renderer_render()
|
|
render flags |
Returns : |
A new GtkCellEditable, or NULL . [transfer none]
|
void gtk_cell_renderer_stop_editing (GtkCellRenderer *cell
,gboolean canceled
);
Informs the cell renderer that the editing is stopped.
If canceled
is TRUE
, the cell renderer will emit the
"editing-canceled" signal.
This function should be called by cell renderer implementations in response to the "editing-done" signal of GtkCellEditable.
|
A GtkCellRenderer |
|
TRUE if the editing has been canceled
|
Since 2.6
void gtk_cell_renderer_get_fixed_size (GtkCellRenderer *cell
,gint *width
,gint *height
);
Fills in width
and height
with the appropriate size of cell
.
|
A GtkCellRenderer |
|
location to fill in with the fixed width of the cell, or NULL . [out][allow-none]
|
|
location to fill in with the fixed height of the cell, or NULL . [out][allow-none]
|
void gtk_cell_renderer_set_fixed_size (GtkCellRenderer *cell
,gint width
,gint height
);
Sets the renderer size to be explicit, independent of the properties set.
|
A GtkCellRenderer |
|
the width of the cell renderer, or -1 |
|
the height of the cell renderer, or -1 |
gboolean gtk_cell_renderer_get_visible (GtkCellRenderer *cell
);
Returns the cell renderer's visibility.
|
A GtkCellRenderer |
Returns : |
TRUE if the cell renderer is visible
|
Since 2.18
void gtk_cell_renderer_set_visible (GtkCellRenderer *cell
,gboolean visible
);
Sets the cell renderer's visibility.
|
A GtkCellRenderer |
|
the visibility of the cell |
Since 2.18
gboolean gtk_cell_renderer_get_sensitive (GtkCellRenderer *cell
);
Returns the cell renderer's sensitivity.
|
A GtkCellRenderer |
Returns : |
TRUE if the cell renderer is sensitive
|
Since 2.18
void gtk_cell_renderer_set_sensitive (GtkCellRenderer *cell
,gboolean sensitive
);
Sets the cell renderer's sensitivity.
|
A GtkCellRenderer |
|
the sensitivity of the cell |
Since 2.18
void gtk_cell_renderer_get_alignment (GtkCellRenderer *cell
,gfloat *xalign
,gfloat *yalign
);
Fills in xalign
and yalign
with the appropriate values of cell
.
|
A GtkCellRenderer |
|
location to fill in with the x alignment of the cell, or NULL . [out][allow-none]
|
|
location to fill in with the y alignment of the cell, or NULL . [out][allow-none]
|
Since 2.18
void gtk_cell_renderer_set_alignment (GtkCellRenderer *cell
,gfloat xalign
,gfloat yalign
);
Sets the renderer's alignment within its available space.
|
A GtkCellRenderer |
|
the x alignment of the cell renderer |
|
the y alignment of the cell renderer |
Since 2.18
void gtk_cell_renderer_get_padding (GtkCellRenderer *cell
,gint *xpad
,gint *ypad
);
Fills in xpad
and ypad
with the appropriate values of cell
.
|
A GtkCellRenderer |
|
location to fill in with the x padding of the cell, or NULL . [out][allow-none]
|
|
location to fill in with the y padding of the cell, or NULL . [out][allow-none]
|
Since 2.18
void gtk_cell_renderer_set_padding (GtkCellRenderer *cell
,gint xpad
,gint ypad
);
Sets the renderer's padding.
|
A GtkCellRenderer |
|
the x padding of the cell renderer |
|
the y padding of the cell renderer |
Since 2.18
GtkStateFlags gtk_cell_renderer_get_state (GtkCellRenderer *cell
,GtkWidget *widget
,GtkCellRendererState cell_state
);
Translates the cell renderer state to GtkStateFlags, based on the cell renderer and widget sensitivity, and the given GtkCellRendererState.
|
a GtkCellRenderer, or NULL
|
|
a GtkWidget, or NULL
|
|
cell renderer state |
Returns : |
the widget state flags applying to cell
|
Since 3.0
gboolean gtk_cell_renderer_is_activatable (GtkCellRenderer *cell
);
Checks whether the cell renderer can do something when activated.
|
A GtkCellRenderer |
Returns : |
TRUE if the cell renderer can do anything when activated
|
Since 3.0
void gtk_cell_renderer_get_preferred_height (GtkCellRenderer *cell
,GtkWidget *widget
,gint *minimum_size
,gint *natural_size
);
Retreives a renderer's natural size when rendered to widget
.
|
a GtkCellRenderer instance |
|
the GtkWidget this cell will be rendering to |
|
location to store the minimum size, or NULL . [out][allow-none]
|
|
location to store the natural size, or NULL . [out][allow-none]
|
Since 3.0
void gtk_cell_renderer_get_preferred_height_for_width (GtkCellRenderer *cell
,GtkWidget *widget
,gint width
,gint *minimum_height
,gint *natural_height
);
Retreives a cell renderers's minimum and natural height if it were rendered to
widget
with the specified width
.
|
a GtkCellRenderer instance |
|
the GtkWidget this cell will be rendering to |
|
the size which is available for allocation |
|
location for storing the minimum size, or NULL . [out][allow-none]
|
|
location for storing the preferred size, or NULL . [out][allow-none]
|
Since 3.0
void gtk_cell_renderer_get_preferred_size (GtkCellRenderer *cell
,GtkWidget *widget
,GtkRequisition *minimum_size
,GtkRequisition *natural_size
);
Retrieves the minimum and natural size of a cell taking into account the widget's preference for height-for-width management.
|
a GtkCellRenderer instance |
|
the GtkWidget this cell will be rendering to |
|
location for storing the minimum size, or NULL . [out][allow-none]
|
|
location for storing the natural size, or NULL . [out][allow-none]
|
Since 3.0
void gtk_cell_renderer_get_preferred_width (GtkCellRenderer *cell
,GtkWidget *widget
,gint *minimum_size
,gint *natural_size
);
Retreives a renderer's natural size when rendered to widget
.
|
a GtkCellRenderer instance |
|
the GtkWidget this cell will be rendering to |
|
location to store the minimum size, or NULL . [out][allow-none]
|
|
location to store the natural size, or NULL . [out][allow-none]
|
Since 3.0
void gtk_cell_renderer_get_preferred_width_for_height (GtkCellRenderer *cell
,GtkWidget *widget
,gint height
,gint *minimum_width
,gint *natural_width
);
Retreives a cell renderers's minimum and natural width if it were rendered to
widget
with the specified height
.
|
a GtkCellRenderer instance |
|
the GtkWidget this cell will be rendering to |
|
the size which is available for allocation |
|
location for storing the minimum size, or NULL . [out][allow-none]
|
|
location for storing the preferred size, or NULL . [out][allow-none]
|
Since 3.0
GtkSizeRequestMode gtk_cell_renderer_get_request_mode (GtkCellRenderer *cell
);
Gets whether the cell renderer prefers a height-for-width layout or a width-for-height layout.
|
a GtkCellRenderer instance |
Returns : |
The GtkSizeRequestMode preferred by this renderer. |
Since 3.0