From: Javier Jardón Date: Sat, 6 Nov 2010 16:57:23 +0000 (+0100) Subject: docs: Move documentation to inline comments: GtkCellRenderer X-Git-Url: http://pileus.org/git/?a=commitdiff_plain;h=322db81256abbf1ffe63ce740c99d1e72ec0087e;p=~andy%2Fgtk docs: Move documentation to inline comments: GtkCellRenderer --- diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore index 227f7d33d..2ad13ef89 100644 --- a/docs/reference/gtk/tmpl/.gitignore +++ b/docs/reference/gtk/tmpl/.gitignore @@ -8,6 +8,7 @@ gtkbuilder.sgml gtkbutton.sgml gtkcalendar.sgml gtkcelleditable.sgml +gtkcellrenderer.sgml gtkcolorbutton.sgml gtkcolorsel.sgml gtkcombobox.sgml diff --git a/docs/reference/gtk/tmpl/gtkcellrenderer.sgml b/docs/reference/gtk/tmpl/gtkcellrenderer.sgml deleted file mode 100644 index 39147e6a2..000000000 --- a/docs/reference/gtk/tmpl/gtkcellrenderer.sgml +++ /dev/null @@ -1,448 +0,0 @@ - -GtkCellRenderer - - -An object for rendering a single cell on a GdkDrawable - - - -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 #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, 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 -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 @activate or @start_editing virtual functions, -respectively. - - - - -#GtkCellRendererText,#GtkCellRendererPixbuf,#GtkCellRendererToggle - - - - - - - - - - -Tells how a cell is to be rendererd. - - -@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. - - - -Identifies how the user can interact with a particular cell. - - -@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. - - - - - - - - - - - - -@cellrenderer: the object which received the signal. - - - - - - -@cellrenderer: the object which received the signal. -@arg1: -@arg2: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@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: - - - - - - -@cell: -@widget: -@cell_area: -@x_offset: -@y_offset: -@width: -@height: - - - - - - - -@cell: -@cr: -@widget: -@background_area: -@cell_area: -@flags: - - - - - - - -@cell: -@event: -@widget: -@path: -@background_area: -@cell_area: -@flags: -@Returns: - - - - - - - -@cell: -@event: -@widget: -@path: -@background_area: -@cell_area: -@flags: -@Returns: - - - - - - - -@cell: -@canceled: - - - - - - - -@cell: -@width: -@height: - - - - - - - -@cell: -@width: -@height: - - - - - - - -@cell: -@Returns: - - - - - - - -@cell: -@visible: - - - - - - - -@cell: -@Returns: - - - - - - - -@cell: -@sensitive: - - - - - - - -@cell: -@xalign: -@yalign: - - - - - - - -@cell: -@xalign: -@yalign: - - - - - - - -@cell: -@xpad: -@ypad: - - - - - - - -@cell: -@xpad: -@ypad: - - - - - - - -@cell: -@widget: -@minimum_size: -@natural_size: - - - - - - - -@cell: -@widget: -@width: -@minimum_height: -@natural_height: - - - - - - - -@cell: -@widget: -@minimum_size: -@natural_size: - - - - - - - -@cell: -@widget: -@minimum_size: -@natural_size: - - - - - - - -@cell: -@widget: -@height: -@minimum_width: -@natural_width: - - - - - - - -@cell: -@Returns: - - - - - - - -@cell_view: -@path: -@avail_size: -@minimum_size: -@natural_size: - - - - - - - -@cell_view: -@path: -@minimum_size: -@natural_size: - - diff --git a/gtk/gtkcellrenderer.c b/gtk/gtkcellrenderer.c index da6c77ce9..4b9355738 100644 --- a/gtk/gtkcellrenderer.c +++ b/gtk/gtkcellrenderer.c @@ -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 #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, 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 + * 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. + */ + + #define DEBUG_CELL_SIZE_REQUEST 0 static void gtk_cell_renderer_init (GtkCellRenderer *cell); diff --git a/gtk/gtkcellrenderer.h b/gtk/gtkcellrenderer.h index 407d35730..25ffed30a 100644 --- a/gtk/gtkcellrenderer.h +++ b/gtk/gtkcellrenderer.h @@ -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,