From 316109ea096e64b11aec6c47982b47ffd78e40c0 Mon Sep 17 00:00:00 2001 From: Kristian Rietveld Date: Thu, 2 Oct 2003 21:30:11 +0000 Subject: [PATCH] Added API doc comments. Thu Oct 2 23:28:02 2003 Kristian Rietveld * gtk/gtkcombobox.c: Added API doc comments. * gtk/gtkcomboboxentry.c: Ditto. --- ChangeLog | 6 +++ ChangeLog.pre-2-10 | 6 +++ ChangeLog.pre-2-4 | 6 +++ ChangeLog.pre-2-6 | 6 +++ ChangeLog.pre-2-8 | 6 +++ gtk/gtkcombobox.c | 112 +++++++++++++++++++++++++++++++++++++++++ gtk/gtkcomboboxentry.c | 27 ++++++++++ 7 files changed, 169 insertions(+) diff --git a/ChangeLog b/ChangeLog index cefcf44d5e..73b440bd66 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,9 @@ +Thu Oct 2 23:28:02 2003 Kristian Rietveld + + * gtk/gtkcombobox.c: Added API doc comments. + + * gtk/gtkcomboboxentry.c: Ditto. + 2003-10-02 Matthias Clasen * gtk/gtktoggleaction.c: Documentation tweaks. diff --git a/ChangeLog.pre-2-10 b/ChangeLog.pre-2-10 index cefcf44d5e..73b440bd66 100644 --- a/ChangeLog.pre-2-10 +++ b/ChangeLog.pre-2-10 @@ -1,3 +1,9 @@ +Thu Oct 2 23:28:02 2003 Kristian Rietveld + + * gtk/gtkcombobox.c: Added API doc comments. + + * gtk/gtkcomboboxentry.c: Ditto. + 2003-10-02 Matthias Clasen * gtk/gtktoggleaction.c: Documentation tweaks. diff --git a/ChangeLog.pre-2-4 b/ChangeLog.pre-2-4 index cefcf44d5e..73b440bd66 100644 --- a/ChangeLog.pre-2-4 +++ b/ChangeLog.pre-2-4 @@ -1,3 +1,9 @@ +Thu Oct 2 23:28:02 2003 Kristian Rietveld + + * gtk/gtkcombobox.c: Added API doc comments. + + * gtk/gtkcomboboxentry.c: Ditto. + 2003-10-02 Matthias Clasen * gtk/gtktoggleaction.c: Documentation tweaks. diff --git a/ChangeLog.pre-2-6 b/ChangeLog.pre-2-6 index cefcf44d5e..73b440bd66 100644 --- a/ChangeLog.pre-2-6 +++ b/ChangeLog.pre-2-6 @@ -1,3 +1,9 @@ +Thu Oct 2 23:28:02 2003 Kristian Rietveld + + * gtk/gtkcombobox.c: Added API doc comments. + + * gtk/gtkcomboboxentry.c: Ditto. + 2003-10-02 Matthias Clasen * gtk/gtktoggleaction.c: Documentation tweaks. diff --git a/ChangeLog.pre-2-8 b/ChangeLog.pre-2-8 index cefcf44d5e..73b440bd66 100644 --- a/ChangeLog.pre-2-8 +++ b/ChangeLog.pre-2-8 @@ -1,3 +1,9 @@ +Thu Oct 2 23:28:02 2003 Kristian Rietveld + + * gtk/gtkcombobox.c: Added API doc comments. + + * gtk/gtkcomboboxentry.c: Ditto. + 2003-10-02 Matthias Clasen * gtk/gtktoggleaction.c: Documentation tweaks. diff --git a/gtk/gtkcombobox.c b/gtk/gtkcombobox.c index d54da472be..cf95ee6772 100644 --- a/gtk/gtkcombobox.c +++ b/gtk/gtkcombobox.c @@ -2227,6 +2227,8 @@ gtk_combo_box_cell_layout_clear_attributes (GtkCellLayout *layout, * Creates a new #GtkComboBox with the model initialized to @model. * * Return value: A new #GtkComboBox. + * + * Since: 2.4 */ GtkWidget * gtk_combo_box_new (GtkTreeModel *model) @@ -2242,6 +2244,17 @@ gtk_combo_box_new (GtkTreeModel *model) return GTK_WIDGET (combo_box); } +/** + * gtk_combo_box_set_wrap_width: + * @combo_box: A #GtkComboBox. + * @width: Preferred number of columns. + * + * Sets the wrap width of @combo_box to be @width. The wrap width is basically + * the preferred number of columns when you want to the popup to be layed out + * in a table. + * + * Since: 2.4 + */ void gtk_combo_box_set_wrap_width (GtkComboBox *combo_box, gint width) @@ -2254,6 +2267,17 @@ gtk_combo_box_set_wrap_width (GtkComboBox *combo_box, gtk_combo_box_relayout (combo_box); } +/** + * gtk_combo_box_set_row_span_column: + * @combo_box: A #GtkComboBox. + * @row_span: A column in the model passed during construction. + * + * Sets the column with row span information for @combo_box to be @row_span. + * The row span column contains integers which indicate how many rows + * an item should span. + * + * Since: 2.4 + */ void gtk_combo_box_set_row_span_column (GtkComboBox *combo_box, gint row_span) @@ -2270,6 +2294,17 @@ gtk_combo_box_set_row_span_column (GtkComboBox *combo_box, gtk_combo_box_relayout (combo_box); } +/** + * gtk_combo_box_set_column_span_column: + * @combo_box: A #GtkComboBox. + * @column_span: A column in the model passed during construction. + * + * Sets the column with column span information for @combo_box to be + * @column_span. The column span column contains integers which indicate + * how many columns an item should span. + * + * Since: 2.4 + */ void gtk_combo_box_set_column_span_column (GtkComboBox *combo_box, gint column_span) @@ -2286,6 +2321,16 @@ gtk_combo_box_set_column_span_column (GtkComboBox *combo_box, gtk_combo_box_relayout (combo_box); } +/** + * gtk_combo_box_get_active: + * @combo_box: A #GtkComboBox. + * + * Returns the index of the currently active item. + * + * Return value: An integer which is the index of the currently active item. + * + * Since: 2.4 + */ gint gtk_combo_box_get_active (GtkComboBox *combo_box) { @@ -2294,6 +2339,15 @@ gtk_combo_box_get_active (GtkComboBox *combo_box) return combo_box->priv->active_item; } +/** + * gtk_combo_box_set_active: + * @combo_box: A #GtkComboBox. + * @index: An index in the model passed during construction. + * + * Sets the active item of @combo_box to be the item at @index. + * + * Since: 2.4 + */ void gtk_combo_box_set_active (GtkComboBox *combo_box, gint index) @@ -2347,6 +2401,16 @@ gtk_combo_box_set_active (GtkComboBox *combo_box, g_signal_emit_by_name (combo_box, "changed", NULL, NULL); } +/** + * gtk_combo_box_get_model + * @combo_box: A #GtkComboBox. + * + * Returns the #GtkTreeModel which is acting as data source for @combo_box. + * + * Return value: A #GtkTreeModel which was passed during construction. + * + * Since: 2.4 + */ GtkTreeModel * gtk_combo_box_get_model (GtkComboBox *combo_box) { @@ -2357,6 +2421,20 @@ gtk_combo_box_get_model (GtkComboBox *combo_box) /* convenience API for simple text combos */ + +/** + * gtk_combo_box_new_text: + * + * Convenience function which constructs a new text combo box, which is a + * #GtkComboBox just displaying strings. If you use this function to create + * a text combo box, you only want to manipulate it's data source with the + * following convenience functions: gtk_combo_box_append_text(), + * gtk_combo_box_insert_text() and gtk_combo_box_prepend_text(). + * + * Return value: A new text combo box. + * + * Since: 2.4 + */ GtkWidget * gtk_combo_box_new_text (void) { @@ -2377,6 +2455,17 @@ gtk_combo_box_new_text (void) return combo_box; } +/** + * gtk_combo_box_append_text: + * @combo_box: A #GtkComboBox constructed using gtk_combo_box_new_text(). + * @text: A string. + * + * Appends @string to the list of strings stored in @combo_box. Note that + * you can only use this function with combo boxes constructed with + * gtk_combo_box_new_text(). + * + * Since: 2.4 + */ void gtk_combo_box_append_text (GtkComboBox *combo_box, const gchar *text) @@ -2394,6 +2483,18 @@ gtk_combo_box_append_text (GtkComboBox *combo_box, gtk_list_store_set (store, &iter, 0, text, -1); } +/** + * gtk_combo_box_insert_text: + * @combo_box: A #GtkComboBox constructed using gtk_combo_box_new_text(). + * @position: An index to insert @text. + * @text: A string. + * + * Inserts @string at @position in the list of strings stored in @combo_box. + * Note that you can only use this function with combo boxes constructed + * with gtk_combo_box_new_text(). + * + * Since: 2.4 + */ void gtk_combo_box_insert_text (GtkComboBox *combo_box, gint position, @@ -2413,6 +2514,17 @@ gtk_combo_box_insert_text (GtkComboBox *combo_box, gtk_list_store_set (store, &iter, 0, text, -1); } +/** + * gtk_combo_box_prepend_text: + * @combo_box: A #GtkComboBox constructed with gtk_combo_box_new_text(). + * @text: A string. + * + * Prepends @string to the list of strings stored in @combo_box. Note that + * you can only use this function with combo boxes constructed with + * gtk_combo_box_new_text(). + * + * Since: 2.4 + */ void gtk_combo_box_prepend_text (GtkComboBox *combo_box, const gchar *text) diff --git a/gtk/gtkcomboboxentry.c b/gtk/gtkcomboboxentry.c index d2e907e6fa..1e08b1aaee 100644 --- a/gtk/gtkcomboboxentry.c +++ b/gtk/gtkcomboboxentry.c @@ -135,6 +135,22 @@ gtk_combo_box_entry_contents_changed (GtkEntry *entry, } /* public API */ + +/** + * gtk_combo_box_entry_new: + * @model: A #GtkTreeModel. + * @text_column: A column in @model to get the strings from. + * + * Creates a new #GtkComboBoxEntry which has a #GtkEntry as child and a list + * of strings as popup. You can get the #GtkEntry from a #GtkComboBoxEntry + * using GTK_ENTRY (GTK_BIN (combo_box_entry)->child). To add and remove + * strings from the list, just modify @model using it's data manipulation + * API. + * + * Return value: A new #GtkComboBoxEntry. + * + * Since: 2.4 + */ GtkWidget * gtk_combo_box_entry_new (GtkTreeModel *model, gint text_column) @@ -170,6 +186,17 @@ gtk_combo_box_entry_new (GtkTreeModel *model, return ret; } +/** + * gtk_combo_box_entry_get_text_column: + * @entry_box: A #GtkComboBoxEntry. + * + * Returns the column which @entry_box is using to get the strings from. + * This is the same column which got passed during construction. + * + * Return value: A column in the data source model of @entry_box. + * + * Since: 2.4 + */ gint gtk_combo_box_entry_get_text_column (GtkComboBoxEntry *entry_box) {