Commit 322db812 authored by Javier Jardón's avatar Javier Jardón Committed by Tristan Van Berkom

docs: Move documentation to inline comments: GtkCellRenderer

parent b1112cb8
......@@ -8,6 +8,7 @@ gtkbuilder.sgml
gtkbutton.sgml
gtkcalendar.sgml
gtkcelleditable.sgml
gtkcellrenderer.sgml
gtkcolorbutton.sgml
gtkcolorsel.sgml
gtkcombobox.sgml
......
<!-- ##### SECTION Title ##### -->
GtkCellRenderer
<!-- ##### SECTION Short_Description ##### -->
An object for rendering a single cell on a GdkDrawable
<!-- ##### SECTION Long_Description ##### -->
<para>
The #GtkCellRenderer is a base class of a set of objects used for
rendering a cell to a #GdkDrawable. 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.
</para>
<para>
The primary use of a #GtkCellRenderer is for drawing a certain graphical
elements on a #GdkDrawable. 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 #GObject<!-- -->s 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().
</para>
<para>
There are a number of rules that must be followed when writing a new
#GtkCellRenderer. First and formost, it's 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.
</para>
<para>
Beyond merely rendering a cell, cell renderers can optionally
provide active user interface elements. A cell renderer can be
<firstterm>activatable</firstterm> like #GtkCellRendererToggle,
which toggles when it gets activated by a mouse click, or it can be
<firstterm>editable</firstterm> 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 @activate or @start_editing virtual functions,
respectively.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
#GtkCellRendererText,#GtkCellRendererPixbuf,#GtkCellRendererToggle
</para>
<!-- ##### SECTION Stability_Level ##### -->
<!-- ##### SECTION Image ##### -->
<!-- ##### ENUM GtkCellRendererState ##### -->
<para>
Tells how a cell is to be rendererd.
</para>
@GTK_CELL_RENDERER_SELECTED: The cell is currently selected, and
probably has a selection colored background to render to.
@GTK_CELL_RENDERER_PRELIT: The mouse is hovering over the cell.
@GTK_CELL_RENDERER_INSENSITIVE: The cell is drawn in an insensitive manner
@GTK_CELL_RENDERER_SORTED: The cell is in a sorted row
@GTK_CELL_RENDERER_FOCUSED: The cell is in the focus row.
<!-- ##### ENUM GtkCellRendererMode ##### -->
<para>
Identifies how the user can interact with a particular cell.
</para>
@GTK_CELL_RENDERER_MODE_INERT: 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.
@GTK_CELL_RENDERER_MODE_ACTIVATABLE: The cell can be clicked.
@GTK_CELL_RENDERER_MODE_EDITABLE: The cell can be edited or otherwise modified.
<!-- ##### STRUCT GtkCellRenderer ##### -->
<para>
</para>
<!-- ##### SIGNAL GtkCellRenderer::editing-canceled ##### -->
<para>
</para>
@cellrenderer: the object which received the signal.
<!-- ##### SIGNAL GtkCellRenderer::editing-started ##### -->
<para>
</para>
@cellrenderer: the object which received the signal.
@arg1:
@arg2:
<!-- ##### ARG GtkCellRenderer:cell-background ##### -->
<para>
</para>
<!-- ##### ARG GtkCellRenderer:cell-background-gdk ##### -->
<para>
</para>
<!-- ##### ARG GtkCellRenderer:cell-background-set ##### -->
<para>
</para>
<!-- ##### ARG GtkCellRenderer:editing ##### -->
<para>
</para>
<!-- ##### ARG GtkCellRenderer:height ##### -->
<para>
</para>
<!-- ##### ARG GtkCellRenderer:is-expanded ##### -->
<para>
</para>
<!-- ##### ARG GtkCellRenderer:is-expander ##### -->
<para>
</para>
<!-- ##### ARG GtkCellRenderer:mode ##### -->
<para>
</para>
<!-- ##### ARG GtkCellRenderer:sensitive ##### -->
<para>
</para>
<!-- ##### ARG GtkCellRenderer:visible ##### -->
<para>
</para>
<!-- ##### ARG GtkCellRenderer:width ##### -->
<para>
</para>
<!-- ##### ARG GtkCellRenderer:xalign ##### -->
<para>
</para>
<!-- ##### ARG GtkCellRenderer:xpad ##### -->
<para>
</para>
<!-- ##### ARG GtkCellRenderer:yalign ##### -->
<para>
</para>
<!-- ##### ARG GtkCellRenderer:ypad ##### -->
<para>
</para>
<!-- ##### STRUCT GtkCellRendererClass ##### -->
<para>
</para>
@parent_class:
@get_request_mode:
@get_preferred_width:
@get_preferred_height_for_width:
@get_preferred_height:
@get_preferred_width_for_height:
@get_size:
@render:
@activate:
@start_editing:
@editing_canceled:
@editing_started:
@_gtk_reserved1:
@_gtk_reserved2:
<!-- ##### FUNCTION gtk_cell_renderer_get_size ##### -->
<para>
</para>
@cell:
@widget:
@cell_area:
@x_offset:
@y_offset:
@width:
@height:
<!-- ##### FUNCTION gtk_cell_renderer_render ##### -->
<para>
</para>
@cell:
@cr:
@widget:
@background_area:
@cell_area:
@flags:
<!-- ##### FUNCTION gtk_cell_renderer_activate ##### -->
<para>
</para>
@cell:
@event:
@widget:
@path:
@background_area:
@cell_area:
@flags:
@Returns:
<!-- ##### FUNCTION gtk_cell_renderer_start_editing ##### -->
<para>
</para>
@cell:
@event:
@widget:
@path:
@background_area:
@cell_area:
@flags:
@Returns:
<!-- ##### FUNCTION gtk_cell_renderer_stop_editing ##### -->
<para>
</para>
@cell:
@canceled:
<!-- ##### FUNCTION gtk_cell_renderer_get_fixed_size ##### -->
<para>
</para>
@cell:
@width:
@height:
<!-- ##### FUNCTION gtk_cell_renderer_set_fixed_size ##### -->
<para>
</para>
@cell:
@width:
@height:
<!-- ##### FUNCTION gtk_cell_renderer_get_visible ##### -->
<para>
</para>
@cell:
@Returns:
<!-- ##### FUNCTION gtk_cell_renderer_set_visible ##### -->
<para>
</para>
@cell:
@visible:
<!-- ##### FUNCTION gtk_cell_renderer_get_sensitive ##### -->
<para>
</para>
@cell:
@Returns:
<!-- ##### FUNCTION gtk_cell_renderer_set_sensitive ##### -->
<para>
</para>
@cell:
@sensitive:
<!-- ##### FUNCTION gtk_cell_renderer_get_alignment ##### -->
<para>
</para>
@cell:
@xalign:
@yalign:
<!-- ##### FUNCTION gtk_cell_renderer_set_alignment ##### -->
<para>
</para>
@cell:
@xalign:
@yalign:
<!-- ##### FUNCTION gtk_cell_renderer_get_padding ##### -->
<para>
</para>
@cell:
@xpad:
@ypad:
<!-- ##### FUNCTION gtk_cell_renderer_set_padding ##### -->
<para>
</para>
@cell:
@xpad:
@ypad:
<!-- ##### FUNCTION gtk_cell_renderer_get_preferred_height ##### -->
<para>
</para>
@cell:
@widget:
@minimum_size:
@natural_size:
<!-- ##### FUNCTION gtk_cell_renderer_get_preferred_height_for_width ##### -->
<para>
</para>
@cell:
@widget:
@width:
@minimum_height:
@natural_height:
<!-- ##### FUNCTION gtk_cell_renderer_get_preferred_size ##### -->
<para>
</para>
@cell:
@widget:
@minimum_size:
@natural_size:
<!-- ##### FUNCTION gtk_cell_renderer_get_preferred_width ##### -->
<para>
</para>
@cell:
@widget:
@minimum_size:
@natural_size:
<!-- ##### FUNCTION gtk_cell_renderer_get_preferred_width_for_height ##### -->
<para>
</para>
@cell:
@widget:
@height:
@minimum_width:
@natural_width:
<!-- ##### FUNCTION gtk_cell_renderer_get_request_mode ##### -->
<para>
</para>
@cell:
@Returns:
<!-- ##### FUNCTION gtk_cell_view_get_desired_height_for_width_of_row ##### -->
<para>
</para>
@cell_view:
@path:
@avail_size:
@minimum_size:
@natural_size:
<!-- ##### FUNCTION gtk_cell_view_get_desired_width_of_row ##### -->
<para>
</para>
@cell_view:
@path:
@minimum_size:
@natural_size:
......@@ -24,6 +24,45 @@
#include "gtkprivate.h"
#include "gtktreeprivate.h"
/**
* SECTION:gtkcellrenderer
* @Short_description: An object for rendering a single cell on a GdkDrawable
* @Title: GtkCellRenderer
* @See_also: #GtkCellRendererText, #GtkCellRendererPixbuf, #GtkCellRendererToggle
*
* The #GtkCellRenderer is a base class of a set of objects used for
* rendering a cell to a #GdkDrawable. 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 #GdkDrawable. 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 #GObject<!-- -->s 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, it's 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
* <firstterm>activatable</firstterm> like #GtkCellRendererToggle,
* which toggles when it gets activated by a mouse click, or it can be
* <firstterm>editable</firstterm> 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.
*/
#define DEBUG_CELL_SIZE_REQUEST 0
static void gtk_cell_renderer_init (GtkCellRenderer *cell);
......
......@@ -28,6 +28,18 @@
G_BEGIN_DECLS
/**
* GtkCellRendererState:
* @GTK_CELL_RENDERER_SELECTED: The cell is currently selected, and
* probably has a selection colored background to render to.
* @GTK_CELL_RENDERER_PRELIT: The mouse is hovering over the cell.
* @GTK_CELL_RENDERER_INSENSITIVE: The cell is drawn in an insensitive manner
* @GTK_CELL_RENDERER_SORTED: The cell is in a sorted row
* @GTK_CELL_RENDERER_FOCUSED: The cell is in the focus row.
*
* Tells how a cell is to be rendererd.
*/
typedef enum
{
GTK_CELL_RENDERER_SELECTED = 1 << 0,
......@@ -38,6 +50,17 @@ typedef enum
GTK_CELL_RENDERER_FOCUSED = 1 << 4
} GtkCellRendererState;
/**
* GtkCellRendererMode:
* @GTK_CELL_RENDERER_MODE_INERT: 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.
* @GTK_CELL_RENDERER_MODE_ACTIVATABLE: The cell can be clicked.
* @GTK_CELL_RENDERER_MODE_EDITABLE: The cell can be edited or otherwise modified.
*
* Identifies how the user can interact with a particular cell.
*/
typedef enum
{
GTK_CELL_RENDERER_MODE_INERT,
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment