|
|
|
GTK+ 3 Reference Manual | |
|---|---|---|---|---|
| Top | Description | ||||
#include <gtk/gtk.h> enum GtkCellRendererState; enum GtkCellRendererMode; struct GtkCellRenderer; struct 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. |
struct GtkCellRendererClass {
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);
};
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