Pileus Git - ~andy/gtk/blob - docs/reference/gtk/tmpl/gtkcellrenderer.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 GtkCellRenderer
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 An object for rendering a single cell on a #GdkDrawable
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 The #GtkCellRenderer is a base class of a set of objects used for
  10 rendering a cell to a #GdkDrawable.  These objects are used primarily by
  11 the #GtkTreeView widget, though they aren't tied to them in any
  12 specific way.  It is worth noting that #GtkCellRenderer is not a
  13 #GtkWidget and cannot be treated as such.
  14 </para>
  15
  16 <para>
  17 The primary use of a #GtkCellRenderer is for drawing a certain graphical
  18 elements on a #GdkDrawable.  Typically, one cell renderer is used to
  19 draw many cells on the screen.  To this extent, it isn't expected that a
  20 CellRenderer keep any permanent state around.  Instead, any state is set
  21 just prior to use using #GObject<!-- -->s property system.  Then, the
  22 cell is measured using gtk_cell_renderer_get_size().  Finally, the cell
  23 is rendered in the correct location using gtk_cell_renderer_render().
  24 </para>
  25
  26 <para>
  27 There are a number of rules that must be followed when writing a new
  28 #GtkCellRenderer.  First and formost, it's important that a certain set
  29 of properties will always yield a cell renderer of the same size,
  30 barring a #GtkStyle change.  The #GtkCellRenderer also has a number of
  31 generic properties that are expected to be honored by all children.
  32 </para>
  33
  34 <para>
  35 Beyond merely rendering a cell, cell renderers can optionally
  36 provide active user interface elements. A cell renderer can be
  37 <firstterm>activatable</firstterm> like #GtkCellRendererToggle,
  38 which toggles when it gets activated by a mouse click, or it can be
  39 <firstterm>editable</firstterm> like #GtkCellRendererText, which
  40 allows the user to edit the text using a #GtkEntry.
  41 To make a cell renderer activatable or editable, you have to
  42 implement the @activate or @start_editing virtual functions,
  43 respectively.
  44 </para>
  45
  46 <!-- ##### SECTION See_Also ##### -->
  47 <para>
  48 #GtkCellRendererText,#GtkCellRendererPixbuf,#GtkCellRendererToggle
  49 </para>
  50
  51 <!-- ##### ENUM GtkCellRendererState ##### -->
  52 <para>
  53 Tells how a cell is to be rendererd.
  54 </para>
  55
  56 @GTK_CELL_RENDERER_SELECTED: The cell is currently selected, and
  57 probably has a selection colored background to render to.
  58 @GTK_CELL_RENDERER_PRELIT: The mouse is hovering over the cell.
  59 @GTK_CELL_RENDERER_INSENSITIVE: The cell is drawn in an insensitive manner
  60 @GTK_CELL_RENDERER_SORTED: The cell is in a sorted row
  61 @GTK_CELL_RENDERER_FOCUSED:
  62
  63 <!-- ##### ENUM GtkCellRendererMode ##### -->
  64 <para>
  65 Identifies how the user can interact with a particular cell.
  66 </para>
  67
  68 @GTK_CELL_RENDERER_MODE_INERT: The cell is just for display
  69 and cannot be interacted with.  Note that this doesn't mean that eg. the
  70 row being drawn can't be selected -- just that a particular element of
  71 it cannot be individually modified.
  72 @GTK_CELL_RENDERER_MODE_ACTIVATABLE: The cell can be clicked.
  73 @GTK_CELL_RENDERER_MODE_EDITABLE: The cell can be edited or otherwise modified.
  74
  75 <!-- ##### STRUCT GtkCellRenderer ##### -->
  76 <para>
  77
  78 </para>
  79
  80
  81 <!-- ##### SIGNAL GtkCellRenderer::editing-canceled ##### -->
  82 <para>
  83
  84 </para>
  85
  86 @cellrenderer: the object which received the signal.
  87
  88 <!-- ##### SIGNAL GtkCellRenderer::editing-started ##### -->
  89 <para>
  90
  91 </para>
  92
  93 @cellrenderer: the object which received the signal.
  94 @arg1:
  95 @arg2:
  96
  97 <!-- ##### ARG GtkCellRenderer:cell-background ##### -->
  98 <para>
  99
 100 </para>
 101
 102 <!-- ##### ARG GtkCellRenderer:cell-background-gdk ##### -->
 103 <para>
 104
 105 </para>
 106
 107 <!-- ##### ARG GtkCellRenderer:cell-background-set ##### -->
 108 <para>
 109
 110 </para>
 111
 112 <!-- ##### ARG GtkCellRenderer:height ##### -->
 113 <para>
 114
 115 </para>
 116
 117 <!-- ##### ARG GtkCellRenderer:is-expanded ##### -->
 118 <para>
 119
 120 </para>
 121
 122 <!-- ##### ARG GtkCellRenderer:is-expander ##### -->
 123 <para>
 124
 125 </para>
 126
 127 <!-- ##### ARG GtkCellRenderer:mode ##### -->
 128 <para>
 129
 130 </para>
 131
 132 <!-- ##### ARG GtkCellRenderer:sensitive ##### -->
 133 <para>
 134
 135 </para>
 136
 137 <!-- ##### ARG GtkCellRenderer:visible ##### -->
 138 <para>
 139
 140 </para>
 141
 142 <!-- ##### ARG GtkCellRenderer:width ##### -->
 143 <para>
 144
 145 </para>
 146
 147 <!-- ##### ARG GtkCellRenderer:xalign ##### -->
 148 <para>
 149
 150 </para>
 151
 152 <!-- ##### ARG GtkCellRenderer:xpad ##### -->
 153 <para>
 154
 155 </para>
 156
 157 <!-- ##### ARG GtkCellRenderer:yalign ##### -->
 158 <para>
 159
 160 </para>
 161
 162 <!-- ##### ARG GtkCellRenderer:ypad ##### -->
 163 <para>
 164
 165 </para>
 166
 167 <!-- ##### FUNCTION gtk_cell_renderer_get_size ##### -->
 168 <para>
 169
 170 </para>
 171
 172 @cell:
 173 @widget:
 174 @cell_area:
 175 @x_offset:
 176 @y_offset:
 177 @width:
 178 @height:
 179
 180
 181 <!-- ##### FUNCTION gtk_cell_renderer_render ##### -->
 182 <para>
 183
 184 </para>
 185
 186 @cell:
 187 @window:
 188 @widget:
 189 @background_area:
 190 @cell_area:
 191 @expose_area:
 192 @flags:
 193
 194
 195 <!-- ##### FUNCTION gtk_cell_renderer_activate ##### -->
 196 <para>
 197
 198 </para>
 199
 200 @cell:
 201 @event:
 202 @widget:
 203 @path:
 204 @background_area:
 205 @cell_area:
 206 @flags:
 207 @Returns:
 208
 209
 210 <!-- ##### FUNCTION gtk_cell_renderer_start_editing ##### -->
 211 <para>
 212
 213 </para>
 214
 215 @cell:
 216 @event:
 217 @widget:
 218 @path:
 219 @background_area:
 220 @cell_area:
 221 @flags:
 222 @Returns:
 223
 224
 225 <!-- ##### FUNCTION gtk_cell_renderer_editing_canceled ##### -->
 226 <para>
 227
 228 </para>
 229
 230 @cell:
 231
 232
 233 <!-- ##### FUNCTION gtk_cell_renderer_stop_editing ##### -->
 234 <para>
 235
 236 </para>
 237
 238 @cell:
 239 @canceled:
 240
 241
 242 <!-- ##### FUNCTION gtk_cell_renderer_get_fixed_size ##### -->
 243 <para>
 244
 245 </para>
 246
 247 @cell:
 248 @width:
 249 @height:
 250
 251
 252 <!-- ##### FUNCTION gtk_cell_renderer_set_fixed_size ##### -->
 253 <para>
 254
 255 </para>
 256
 257 @cell:
 258 @width:
 259 @height:
 260
 261