From a2ad62af11dbff0880909b0039253f8ab29d9a52 Mon Sep 17 00:00:00 2001 From: Miguel de Icaza Date: Sat, 25 Nov 2000 05:05:40 +0000 Subject: Documented. 2000-11-25 Miguel de Icaza * e-cell.c: Documented. 2000-11-24 Miguel de Icaza * e-cell-toggle.c (etog_queue_redraw): Documented. * e-cell-text.c: Removed list of unused arguments. Add docs. * e-cell-checkbox.c (e_cell_checkbox_new): Add docs. * e-table-simple.c (e_table_simple_new): Add docs. svn path=/trunk/; revision=6665 --- widgets/table/e-cell-checkbox.c | 11 +++- widgets/table/e-cell-text.c | 55 +++++++++++-------- widgets/table/e-cell-toggle.c | 24 ++++++++ widgets/table/e-cell-tree.c | 2 +- widgets/table/e-cell.c | 118 +++++++++++++++++++++++++++++++++++++++- widgets/table/e-table-simple.c | 31 ++++++++++- 6 files changed, 212 insertions(+), 29 deletions(-) (limited to 'widgets/table') diff --git a/widgets/table/e-cell-checkbox.c b/widgets/table/e-cell-checkbox.c index 4d31b53784..cb0c66df94 100644 --- a/widgets/table/e-cell-checkbox.c +++ b/widgets/table/e-cell-checkbox.c @@ -4,7 +4,7 @@ * Author: * Miguel de Icaza (miguel@kernel.org) * - * (C) 1999 Helix Code, Inc + * (C) 1999, 2000 Helix Code, Inc */ #include #include @@ -33,6 +33,15 @@ e_cell_checkbox_class_init (GtkObjectClass *object_class) E_MAKE_TYPE(e_cell_checkbox, "ECellCheckbox", ECellCheckbox, e_cell_checkbox_class_init, NULL, PARENT_TYPE); +/** + * e_cell_checkbox_new: + * + * Creates a new ECell renderer that can be used to render check + * boxes. the data provided from the model is cast to an integer. + * zero is used for the off display, and non-zero for checked status. + * + * Returns: an ECell object that can be used to render checkboxes. + */ ECell * e_cell_checkbox_new (void) { diff --git a/widgets/table/e-cell-text.c b/widgets/table/e-cell-text.c index 0fe721f0ec..2a7eae1d70 100644 --- a/widgets/table/e-cell-text.c +++ b/widgets/table/e-cell-text.c @@ -4,8 +4,10 @@ * * Authors: Miguel de Icaza * Chris Lahey - * - * A majority of code taken from: + * + * (C) 1999, 2000 Helix Code, Inc. + * + * A lot of code taken from: * * Text item type for GnomeCanvas widget * @@ -58,27 +60,7 @@ struct line { /* Object argument IDs */ enum { ARG_0, - ARG_TEXT, /* UTF-8 */ - ARG_X, - ARG_Y, - ARG_FONT, - ARG_FONTSET, - ARG_FONT_GDK, - ARG_ANCHOR, - ARG_JUSTIFICATION, - ARG_CLIP_WIDTH, - ARG_CLIP_HEIGHT, - ARG_CLIP, - ARG_X_OFFSET, - ARG_Y_OFFSET, - ARG_FILL_COLOR, - ARG_FILL_COLOR_GDK, - ARG_FILL_COLOR_RGBA, - ARG_FILL_STIPPLE, - ARG_TEXT_WIDTH, - ARG_TEXT_HEIGHT, - ARG_USE_ELLIPSIS, - ARG_ELLIPSIS, + ARG_STRIKEOUT_COLUMN, ARG_BOLD_COLUMN, ARG_TEXT_FILTER, @@ -1610,6 +1592,30 @@ e_cell_text_init (ECellText *ect) E_MAKE_TYPE(e_cell_text, "ECellText", ECellText, e_cell_text_class_init, e_cell_text_init, PARENT_TYPE); +/** + * e_cell_text_new: + * @fontname: font to be used to render on the screen + * @justify: Justification of the string in the cell. + * + * Creates a new ECell renderer that can be used to render strings that + * that come from the model. The value returned from the model is + * interpreted as being a char *. + * + * The ECellText object support a large set of properties that can be + * configured through the Gtk argument system and allows the user to have + * a finer control of the way the string is displayed. The arguments supported + * allow the control of strikeout, bold, color and a text filter. + * + * The arguments "strikeout_column", "bold_column" and "color_column" set + * and return an integer that points to a column in the model that controls + * these settings. So controlling the way things are rendered is achieved + * by having special columns in the model that will be used to flag whether + * the text should be rendered with strikeout, or bolded. In the case of + * the "color_column" argument, the column in the model is expected to have + * a string that can be parsed by gdk_color_parse(). + * + * Returns: an ECell object that can be used to render strings. + */ ECell * e_cell_text_new (const char *fontname, GtkJustification justify) { @@ -2289,7 +2295,8 @@ _selection_received (GtkInvisible *invisible, } } -static void e_cell_text_view_supply_selection (CellEdit *edit, guint time, GdkAtom selection, char *data, gint length) +static void +e_cell_text_view_supply_selection (CellEdit *edit, guint time, GdkAtom selection, char *data, gint length) { gboolean successful; GtkWidget *invisible; diff --git a/widgets/table/e-cell-toggle.c b/widgets/table/e-cell-toggle.c index 0dd4fe8d20..9c5f7b391b 100644 --- a/widgets/table/e-cell-toggle.c +++ b/widgets/table/e-cell-toggle.c @@ -280,6 +280,16 @@ e_cell_toggle_class_init (GtkObjectClass *object_class) E_MAKE_TYPE(e_cell_toggle, "ECellToggle", ECellToggle, e_cell_toggle_class_init, NULL, PARENT_TYPE); +/** + * e_cell_toggle_construct: + * @etog: a fresh ECellToggle object + * @border: number of pixels used as a border + * @n_states: number of states the toggle will have + * @images: a collection of @n_states images, one for each state. + * + * Constructs the @etog object with the @border, @n_staes, and @images + * arguments. + */ void e_cell_toggle_construct (ECellToggle *etog, int border, int n_states, GdkPixbuf **images) { @@ -302,6 +312,20 @@ e_cell_toggle_construct (ECellToggle *etog, int border, int n_states, GdkPixbuf etog->height = max_height; } +/** + * e_cell_checkbox_new: + * @border: number of pixels used as a border + * @n_states: number of states the toggle will have + * @images: a collection of @n_states images, one for each state. + * + * Creates a new ECell renderer that can be used to render toggle + * buttons with the images specified in @images. The value returned + * by ETableModel::get_value is typecase into an integer and clamped + * to the [0..n_states) range. That will select the image rendered. + * + * Returns: an ECell object that can be used to render multi-state + * toggle cells. + */ ECell * e_cell_toggle_new (int border, int n_states, GdkPixbuf **images) { diff --git a/widgets/table/e-cell-tree.c b/widgets/table/e-cell-tree.c index a465d3b290..32ae9ca1f7 100644 --- a/widgets/table/e-cell-tree.c +++ b/widgets/table/e-cell-tree.c @@ -9,7 +9,7 @@ * the ECellText renderer. * * Copyright (C) 1998 The Free Software Foundation - * + * Copyright (C) 1999, 2000 Helix Code, Inc. */ #include diff --git a/widgets/table/e-cell.c b/widgets/table/e-cell.c index 8fe664f7e1..53aba7c625 100644 --- a/widgets/table/e-cell.c +++ b/widgets/table/e-cell.c @@ -124,7 +124,18 @@ e_cell_init (GtkObject *object) E_MAKE_TYPE(e_cell, "ECell", ECell, e_cell_class_init, e_cell_init, PARENT_TYPE); - +/** + * e_cell_event: + * @ecell_view: The ECellView where the event will be dispatched + * @event: The GdkEvent. + * @model_col: the column in the model + * @view_col: the column in the view + * @row: the row + * + * Dispatches the event @event to the @ecell_view for. + * + * Returns: processing state from the GdkEvent handling. + */ gint e_cell_event (ECellView *ecell_view, GdkEvent *event, int model_col, int view_col, int row) { @@ -132,6 +143,21 @@ e_cell_event (ECellView *ecell_view, GdkEvent *event, int model_col, int view_co ecell_view, event, model_col, view_col, row); } +/** + * e_cell_new_view: + * @ecell: the Ecell that will create the new view + * @table_model: the table model the ecell is bound to + * @e_table_item_view: An ETableItem object (the CanvasItem that reprensents the view of the table) + * + * ECell renderers new to be bound to a table_model and to the actual view + * during their life time to actually render the data. This method is invoked + * by the ETableItem canvas item to instatiate a new view of the ECell. + * + * This is invoked when the ETableModel is attached to the ETableItem (a CanvasItem + * that can render ETableModels in the screen). + * + * Returns: a new ECellView for this @ecell on the @table_model displayed on the @e_table_item_view. + */ ECellView * e_cell_new_view (ECell *ecell, ETableModel *table_model, void *e_table_item_view) { @@ -139,24 +165,65 @@ e_cell_new_view (ECell *ecell, ETableModel *table_model, void *e_table_item_view ecell, table_model, e_table_item_view); } +/** + * e_cell_realize: + * @ecell_view: The ECellView to be realized. + * + * This function is invoked to give a chance to the ECellView to allocate + * any resources it needs from Gdk, equivalent to the GtkWidget::realize + * signal. + */ void e_cell_realize (ECellView *ecell_view) { return E_CELL_CLASS (GTK_OBJECT (ecell_view->ecell)->klass)->realize (ecell_view); } +/** + * e_cell_kill_view: + * @ecell_view: view to be destroyed. + * + * This method it used to destroy a view of an ECell renderer + */ void e_cell_kill_view (ECellView *ecell_view) { E_CELL_CLASS (GTK_OBJECT (ecell_view->ecell)->klass)->kill_view (ecell_view); } +/** + * e_cell_unrealize: + * @ecell_view: The ECellView to be unrealized. + * + * This function is invoked to give a chance to the ECellView to + * release any resources it allocated during the realize method, + * equivalent to the GtkWidget::unrealize signal. + */ void e_cell_unrealize (ECellView *ecell_view) { E_CELL_CLASS (GTK_OBJECT (ecell_view->ecell)->klass)->unrealize (ecell_view); } +/** + * e_cell_draw: + * @ecell_view: the ECellView to redraw + * @drawable: draw desination + * @model_col: the column in the model being drawn. + * @view_col: the column in the view being drawn (what the model maps to). + * @row: the row being drawn + * @flags: rendering flags. + * @x1: boudary for the rendering + * @y1: boudary for the rendering + * @x2: boudary for the rendering + * @y2: boudary for the rendering + * + * This instructs the ECellView to render itself into the drawable. The + * region to be drawn in given by (x1,y1)-(x2,y2). + * + * The most important flags are %E_CELL_SELECTED and %E_CELL_FOCUSED, other + * flags include alignments and justifications. + */ void e_cell_draw (ECellView *ecell_view, GdkDrawable *drawable, int model_col, int view_col, int row, ECellFlags flags, int x1, int y1, int x2, int y2) @@ -165,6 +232,11 @@ e_cell_draw (ECellView *ecell_view, GdkDrawable *drawable, ecell_view, drawable, model_col, view_col, row, flags, x1, y1, x2, y2); } +/** + * e_cell_print: + * + * FIXME: + */ void e_cell_print (ECellView *ecell_view, GnomePrintContext *context, int model_col, int view_col, int row, @@ -174,6 +246,11 @@ e_cell_print (ECellView *ecell_view, GnomePrintContext *context, (ecell_view, context, model_col, view_col, row, width, height); } +/** + * e_cell_print: + * + * FIXME: + */ gdouble e_cell_print_height (ECellView *ecell_view, GnomePrintContext *context, int model_col, int view_col, int row, @@ -186,6 +263,16 @@ e_cell_print_height (ECellView *ecell_view, GnomePrintContext *context, return 0.0; } +/** + * e_cell_height: + * @ecell_view: the ECellView. + * @model_col: the column in the model + * @view_col: the column in the view. + * @row: the row to me measured + * + * Returns: the height of the cell at @model_col, @row rendered at + * @view_col, @row. + */ int e_cell_height (ECellView *ecell_view, int model_col, int view_col, int row) { @@ -193,6 +280,16 @@ e_cell_height (ECellView *ecell_view, int model_col, int view_col, int row) ecell_view, model_col, view_col, row); } +/** + * e_cell_enter_edit: + * @ecell_view: the ECellView that will enter editing + * @model_col: the column in the model + * @view_col: the column in the view + * @row: the row + * + * Notifies the ECellView that it is about to enter editing mode for + * @model_col, @row rendered at @view_col, @row. + */ void * e_cell_enter_edit (ECellView *ecell_view, int model_col, int view_col, int row) { @@ -200,6 +297,16 @@ e_cell_enter_edit (ECellView *ecell_view, int model_col, int view_col, int row) ecell_view, model_col, view_col, row); } +/** + * e_cell_leave_edit: + * @ecell_view: the ECellView that will leave editing + * @model_col: the column in the model + * @view_col: the column in the view + * @row: the row + * + * Notifies the ECellView that editing is finished at @model_col, @row + * rendered at @view_col, @row. + */ void e_cell_leave_edit (ECellView *ecell_view, int model_col, int view_col, int row, void *edit_context) { @@ -207,6 +314,15 @@ e_cell_leave_edit (ECellView *ecell_view, int model_col, int view_col, int row, ecell_view, model_col, view_col, row, edit_context); } +/** + * e_cell_max_width: + * @ecell_view: the ECellView that will leave editing + * @model_col: the column in the model + * @view_col: the column in the view. + * + * Returns: the maximum width for the ECellview at @model_col which + * is being rendered as @view_col + */ int e_cell_max_width (ECellView *ecell_view, int model_col, int view_col) { diff --git a/widgets/table/e-table-simple.c b/widgets/table/e-table-simple.c index 8c8ed87b70..2144091d17 100644 --- a/widgets/table/e-table-simple.c +++ b/widgets/table/e-table-simple.c @@ -7,7 +7,7 @@ * Author: * Miguel de Icaza (miguel@gnu.org) * - * (C) 1999 Helix Code, Inc. + * (C) 1999, 2000 Helix Code, Inc. */ #include @@ -209,6 +209,33 @@ e_table_simple_get_type (void) return type; } +/** + * e_table_simple_new: + * @col_count: + * @row_count: + * @value_at: + * @set_value_at: + * @is_cell_editable: + * @duplicate_value: + * @free_value: + * @initialize_value: + * @value_is_empty: + * @value_to_string: + * @data: closure pointer. + * + * This initializes a new ETableSimpleModel object. ETableSimpleModel is + * an implementaiton of the abstract class ETableModel. The ETableSimpleModel + * is designed to allow people to easily create ETableModels without having + * to create a new GtkType derived from ETableModel every time they need one. + * + * Instead, ETableSimpleModel uses a setup based in callback functions, every + * callback function signature mimics the signature of each ETableModel method + * and passes the extra @data pointer to each one of the method to provide them + * with any context they might want to use. + * + * Returns: An ETableSimpleModel object (which is also an ETableModel + * object). + */ ETableModel * e_table_simple_new (ETableSimpleColumnCountFn col_count, ETableSimpleRowCountFn row_count, @@ -239,4 +266,4 @@ e_table_simple_new (ETableSimpleColumnCountFn col_count, et->data = data; return (ETableModel *) et; -} + } -- cgit v1.2.3