Commit 18dd625f authored by Havoc Pennington's avatar Havoc Pennington Committed by Havoc Pennington

Documented a bunch of functions in here (gtk_widget_realize): Warn if you

2000-11-20  Havoc Pennington  <hp@redhat.com>

	* gtk/gtkwidget.c: Documented a bunch of functions in here
	(gtk_widget_realize): Warn if you try to realize
	a widget with no parent that isn't a toplevel
	(gtk_widget_intersect): return a gboolean
parent 6f7dd53b
2000-11-20 Havoc Pennington <hp@redhat.com>
* gtk/gtkwidget.c: Documented a bunch of functions in here
(gtk_widget_realize): Warn if you try to realize
a widget with no parent that isn't a toplevel
(gtk_widget_intersect): return a gboolean
2000-11-20 Havoc Pennington <hp@redhat.com>
* gtk/gtktextview.c, gtk/gtktextlayout.c, gtk/gtktextchild.c,
......
2000-11-20 Havoc Pennington <hp@redhat.com>
* gtk/gtkwidget.c: Documented a bunch of functions in here
(gtk_widget_realize): Warn if you try to realize
a widget with no parent that isn't a toplevel
(gtk_widget_intersect): return a gboolean
2000-11-20 Havoc Pennington <hp@redhat.com>
* gtk/gtktextview.c, gtk/gtktextlayout.c, gtk/gtktextchild.c,
......
2000-11-20 Havoc Pennington <hp@redhat.com>
* gtk/gtkwidget.c: Documented a bunch of functions in here
(gtk_widget_realize): Warn if you try to realize
a widget with no parent that isn't a toplevel
(gtk_widget_intersect): return a gboolean
2000-11-20 Havoc Pennington <hp@redhat.com>
* gtk/gtktextview.c, gtk/gtktextlayout.c, gtk/gtktextchild.c,
......
2000-11-20 Havoc Pennington <hp@redhat.com>
* gtk/gtkwidget.c: Documented a bunch of functions in here
(gtk_widget_realize): Warn if you try to realize
a widget with no parent that isn't a toplevel
(gtk_widget_intersect): return a gboolean
2000-11-20 Havoc Pennington <hp@redhat.com>
* gtk/gtktextview.c, gtk/gtktextlayout.c, gtk/gtktextchild.c,
......
2000-11-20 Havoc Pennington <hp@redhat.com>
* gtk/gtkwidget.c: Documented a bunch of functions in here
(gtk_widget_realize): Warn if you try to realize
a widget with no parent that isn't a toplevel
(gtk_widget_intersect): return a gboolean
2000-11-20 Havoc Pennington <hp@redhat.com>
* gtk/gtktextview.c, gtk/gtktextlayout.c, gtk/gtktextchild.c,
......
2000-11-20 Havoc Pennington <hp@redhat.com>
* gtk/gtkwidget.c: Documented a bunch of functions in here
(gtk_widget_realize): Warn if you try to realize
a widget with no parent that isn't a toplevel
(gtk_widget_intersect): return a gboolean
2000-11-20 Havoc Pennington <hp@redhat.com>
* gtk/gtktextview.c, gtk/gtktextlayout.c, gtk/gtktextchild.c,
......
2000-11-20 Havoc Pennington <hp@redhat.com>
* gtk/gtkwidget.c: Documented a bunch of functions in here
(gtk_widget_realize): Warn if you try to realize
a widget with no parent that isn't a toplevel
(gtk_widget_intersect): return a gboolean
2000-11-20 Havoc Pennington <hp@redhat.com>
* gtk/gtktextview.c, gtk/gtktextlayout.c, gtk/gtktextchild.c,
......
......@@ -172,6 +172,12 @@ void marshal_INT__POINTER_POINTER_INT_INT(GtkObject* object,
</para>
<!-- ##### ARG GtkTextTag:font_set ##### -->
<para>
</para>
<!-- ##### MACRO gtk_marshal_NONE__POINTER_UINT_ENUM ##### -->
<para>
......@@ -1012,6 +1018,12 @@ will be shown, or NULL to show all charsets.
@Returns:
<!-- ##### ARG GtkTextTag:offset_set ##### -->
<para>
</para>
<!-- ##### MACRO GTK_TYPE_NUM_BUILTINS ##### -->
<para>
No idea.
......@@ -1074,6 +1086,13 @@ This function is labeled private.
@object: the object whose signal handlers should be destroyed.
<!-- ##### ARG GtkTextTag:left_wrapped_line_margin ##### -->
<para>
Pixel width of the left margin of the text for lines after the first
line in a wrapped paragraph.
</para>
<!-- ##### FUNCTION gtk_text_iter_in_region ##### -->
<para>
......@@ -1544,6 +1563,13 @@ Causes the "changed" signal to be emitted.
@mark:
@Returns:
<!-- ##### ARG GtkTextTag:offset ##### -->
<para>
Pixels to offset the text horizontally or vertically, useful to
produce superscript and subscript.
</para>
<!-- ##### SIGNAL GtkEditable::insert-text ##### -->
<para>
This signal is emitted when text is inserted into
......@@ -2017,6 +2043,12 @@ GtkIMContextSimple
</para>
<!-- ##### ARG GtkTextTag:left_wrapped_line_margin_set ##### -->
<para>
</para>
<!-- ##### MACRO GTK_VALUE_C_CALLBACK ##### -->
<para>
Use to get the value of a GtkArg whose GtkType is GTK_TYPE_C_CALLBACK
......
......@@ -57,10 +57,9 @@ Describes a type of line wrapping.
@appearance:
@justify:
@direction:
@font_desc:
@font:
@left_margin:
@left_wrapped_line_margin:
@offset:
@indent:
@right_margin:
@pixels_above_lines:
@pixels_below_lines:
......@@ -125,10 +124,12 @@ Describes a type of line wrapping.
@fg_color:
@bg_stipple:
@fg_stipple:
@rise:
@underline:
@strikethrough:
@draw_bg:
@inside_selection:
@is_text:
<!-- ##### FUNCTION gtk_text_attributes_new ##### -->
<para>
......@@ -222,6 +223,41 @@ Font as a Pango font name, e.g. "Sans Italic 12"
Font as a #PangoFontDescription.
</para>
<!-- ##### ARG GtkTextTag:family ##### -->
<para>
</para>
<!-- ##### ARG GtkTextTag:style ##### -->
<para>
</para>
<!-- ##### ARG GtkTextTag:variant ##### -->
<para>
</para>
<!-- ##### ARG GtkTextTag:weight ##### -->
<para>
</para>
<!-- ##### ARG GtkTextTag:stretch ##### -->
<para>
</para>
<!-- ##### ARG GtkTextTag:size ##### -->
<para>
</para>
<!-- ##### ARG GtkTextTag:size_points ##### -->
<para>
</para>
<!-- ##### ARG GtkTextTag:foreground ##### -->
<para>
Foreground color as a string such as "red" or "#FFFFFF".
......@@ -255,16 +291,14 @@ you probably don't need it.
Pixel width of left margin of the text.
</para>
<!-- ##### ARG GtkTextTag:left_wrapped_line_margin ##### -->
<!-- ##### ARG GtkTextTag:indent ##### -->
<para>
Pixel width of the left margin of the text for lines after the first
line in a wrapped paragraph.
</para>
<!-- ##### ARG GtkTextTag:offset ##### -->
<!-- ##### ARG GtkTextTag:rise ##### -->
<para>
Pixels to offset the text horizontally or vertically, useful to
produce superscript and subscript.
</para>
<!-- ##### ARG GtkTextTag:pixels_above_lines ##### -->
......@@ -340,7 +374,32 @@ applies to the first character in a paragraph.
</para>
<!-- ##### ARG GtkTextTag:font_set ##### -->
<!-- ##### ARG GtkTextTag:family_set ##### -->
<para>
</para>
<!-- ##### ARG GtkTextTag:style_set ##### -->
<para>
</para>
<!-- ##### ARG GtkTextTag:variant_set ##### -->
<para>
</para>
<!-- ##### ARG GtkTextTag:weight_set ##### -->
<para>
</para>
<!-- ##### ARG GtkTextTag:stretch_set ##### -->
<para>
</para>
<!-- ##### ARG GtkTextTag:size_set ##### -->
<para>
</para>
......@@ -375,12 +434,12 @@ applies to the first character in a paragraph.
</para>
<!-- ##### ARG GtkTextTag:left_wrapped_line_margin_set ##### -->
<!-- ##### ARG GtkTextTag:indent_set ##### -->
<para>
</para>
<!-- ##### ARG GtkTextTag:offset_set ##### -->
<!-- ##### ARG GtkTextTag:rise_set ##### -->
<para>
</para>
......
......@@ -415,3 +415,28 @@ types related to the text widget and how they work together.
</para>
<!-- ##### ARG GtkTextView:justify ##### -->
<para>
</para>
<!-- ##### ARG GtkTextView:left_margin ##### -->
<para>
</para>
<!-- ##### ARG GtkTextView:right_margin ##### -->
<para>
</para>
<!-- ##### ARG GtkTextView:indent ##### -->
<para>
</para>
<!-- ##### ARG GtkTextView:tabs ##### -->
<para>
</para>
......@@ -1046,16 +1046,24 @@ gtk_widget_init (GtkWidget *widget)
gtk_widget_set_colormap (widget, colormap);
}
/*****************************************
* gtk_widget_new:
*
* arguments:
*
* results:
*****************************************/
/**
* gtk_widget_new:
* @type: type ID of the widget to create
* @first_arg_name: name of first property to set
* @Varargs: value of first property, followed by more properties, NULL-terminated
*
* This is a convenience function for creating a widget and setting
* its properties in one go. For example you might write:
* gtk_widget_new (GTK_TYPE_LABEL, "label", "Hello World", "xalign",
* 0.0, NULL) to create a left-aligned label. Equivalent to
* gtk_object_new(), but returns a widget so you don't have to
* cast the object yourself.
*
* Return value: a new #GtkWidget of type @widget_type
**/
GtkWidget*
gtk_widget_new (GtkType widget_type,
gtk_widget_new (GtkType type,
const gchar *first_arg_name,
...)
{
......@@ -1065,9 +1073,9 @@ gtk_widget_new (GtkType widget_type,
GSList *info_list = NULL;
gchar *error;
g_return_val_if_fail (gtk_type_is_a (widget_type, GTK_TYPE_WIDGET), NULL);
g_return_val_if_fail (gtk_type_is_a (type, GTK_TYPE_WIDGET), NULL);
object = gtk_type_new (widget_type);
object = gtk_type_new (type);
va_start (var_args, first_arg_name);
error = gtk_object_args_collect (GTK_OBJECT_TYPE (object),
......@@ -1104,14 +1112,19 @@ gtk_widget_new (GtkType widget_type,
return GTK_WIDGET (object);
}
/*****************************************
/**
* gtk_widget_newv:
*
* arguments:
*
* results:
*****************************************/
* @type: a #GtkType for the widget to create
* @nargs: number of args in @args
* @args: array of args specifying widget properties
*
* Same as gtk_widget_new(), but takes an array instead of using
* varargs. This version is only useful if you need to construct
* the args programmatically. Equivalent to gtk_object_newv(), but
* returns a #GtkWidget so you don't have to case the object yourself.
*
* Return value: a #GtkWidget
**/
GtkWidget*
gtk_widget_newv (GtkType type,
guint nargs,
......@@ -1122,14 +1135,13 @@ gtk_widget_newv (GtkType type,
return GTK_WIDGET (gtk_object_newv (type, nargs, args));
}
/*****************************************
/**
* gtk_widget_get:
*
* arguments:
*
* results:
*****************************************/
* @widget: a #GtkWidget
* @arg: single #GtkArg with the argument name filled in
*
* Queries the value of @arg, storing it in @arg.
**/
void
gtk_widget_get (GtkWidget *widget,
GtkArg *arg)
......@@ -1141,14 +1153,14 @@ gtk_widget_get (GtkWidget *widget,
gtk_object_getv (GTK_OBJECT (widget), 1, arg);
}
/*****************************************
/**
* gtk_widget_getv:
*
* arguments:
*
* results:
*****************************************/
* @widget: a #GtkWidget
* @nargs: number of args in @args
* @args: array of #GtkArg
*
* Like calling gtk_widget_get() on each arg in @args.
**/
void
gtk_widget_getv (GtkWidget *widget,
guint nargs,
......@@ -1160,14 +1172,15 @@ gtk_widget_getv (GtkWidget *widget,
gtk_object_getv (GTK_OBJECT (widget), nargs, args);
}
/*****************************************
/**
* gtk_widget_set:
*
* arguments:
*
* results:
*****************************************/
* @widget: a #GtkWidget
* @first_arg_name: name of first arg to set
* @Varargs: value of first arg, then more name-value pairs, and %NULL-terminated
*
* Like gtk_object_set() - there's no reason to use this instead of
* gtk_object_set().
**/
void
gtk_widget_set (GtkWidget *widget,
const gchar *first_arg_name,
......@@ -1214,14 +1227,20 @@ gtk_widget_set (GtkWidget *widget,
}
}
/*****************************************
/**
* gtk_widget_setv:
*
* arguments:
*
* results:
*****************************************/
* @widget: a #GtkWidget
* @nargs: args in @args
* @args: array of args to set on the widget
*
* Each arg in @args should have its name and value filled in. The
* corresponding properties will be set on the
* widget. gtk_object_set() is a more convenient version of this
* function, since it takes varargs in place of the array. You may
* need the array version to construct the list of args to set at
* runtime.
*
**/
void
gtk_widget_setv (GtkWidget *widget,
guint nargs,
......@@ -1247,6 +1266,14 @@ gtk_widget_queue_clear_child (GtkWidget *widget)
widget->allocation.height);
}
/**
* gtk_widget_unparent:
* @widget: a #GtkWidget
*
* INTERNAL FUNCTION, only for use in widget implementations.
* Should be called by implementations of the remove method
* on #GtkContainer, to dissociate a child from the container.
**/
void
gtk_widget_unparent (GtkWidget *widget)
{
......@@ -1376,14 +1403,26 @@ gtk_widget_unparent (GtkWidget *widget)
gtk_widget_unref (widget);
}
/*****************************************
/**
* gtk_widget_destroy:
* @widget: a #GtkWidget
*
* arguments:
*
* results:
*****************************************/
* Destroys a widget. Equivalent to gtk_object_destroy(), except that
* you don't have to cast the widget to #GtkObject. When a widget is
* destroyed, it will break any references it holds to other objects.
* If the widget is inside a container, the widget will be removed
* from the container. If the widget is a toplevel (derived from
* #GtkWindow), it will be removed from the list of toplevels, and the
* reference GTK+ holds to it will be removed. Removing a
* widget from its container or the list of toplevels results in the
* widget being finalized, unless you've added additional references
* to the widget with gtk_object_ref().
*
* In most cases, only toplevel widgets (windows) require explicit
* destruction, because when you destroy a toplevel its children will
* be destroyed as well.
*
**/
void
gtk_widget_destroy (GtkWidget *widget)
{
......@@ -1394,16 +1433,20 @@ gtk_widget_destroy (GtkWidget *widget)
gtk_object_destroy ((GtkObject*) widget);
}
/*****************************************
/**
* gtk_widget_destroyed:
* Utility function: sets widget_pointer
* to NULL when widget is destroyed.
*
* arguments:
*
* results:
*****************************************/
* @widget: a #GtkWidget
* @widget_pointer: address of a variable that contains @widget
*
* This function sets *@widget_pointer to NULL if @widget_pointer !=
* NULL. It's intended to be used as a callback connected to the
* "destroy" signal of a widget. You connect gtk_widget_destroyed()
* as a signal handler, and pass the address of your widget variable
* as user data. Then when the widget is destroyed, the variable will
* be set to NULL. Useful for example to avoid multiple copies
* of the same dialog.
*
**/
void
gtk_widget_destroyed (GtkWidget *widget,
GtkWidget **widget_pointer)
......@@ -1416,14 +1459,23 @@ gtk_widget_destroyed (GtkWidget *widget,
*widget_pointer = NULL;
}
/*****************************************
/**
* gtk_widget_show:
* @widget: a #GtkWidget
*
* Flags a widget to be displayed. Any widget that isn't shown will
* not appear on the screen. If you want to show all the widgets in a
* container, it's easier to call gtk_widget_show_all() on the
* container, instead of individually showing the widgets.
*
* arguments:
* Remember that you have to show the containers containing a widget,
* in addition to the widget itself, before it will appear onscreen.
*
* results:
*****************************************/
* When a toplevel container is shown, it is immediately realized and
* mapped; other shown widgets are realized and mapped when their
* toplevel container is realized and mapped.
*
**/
void
gtk_widget_show (GtkWidget *widget)
{
......@@ -1455,18 +1507,6 @@ gtk_widget_real_show (GtkWidget *widget)
}
}
/*************************************************************
* gtk_widget_show_now:
* Show a widget, and if it is an unmapped toplevel widget
* wait for the map_event before returning
*
* Warning: This routine will call the main loop recursively.
*
* arguments:
*
* results:
*************************************************************/
static void
gtk_widget_show_map_callback (GtkWidget *widget, GdkEvent *event, gint *flag)
{
......@@ -1474,6 +1514,16 @@ gtk_widget_show_map_callback (GtkWidget *widget, GdkEvent *event, gint *flag)
gtk_signal_disconnect_by_data (GTK_OBJECT (widget), flag);
}
/**
* gtk_widget_show_now:
* @widget: a #GtkWidget
*
* Shows a widget. If the widget is an unmapped toplevel widget
* (i.e. a #GtkWindow that has not yet been shown), enter the main
* loop and wait for the window to actually be mapped. Be careful;
* because the main loop is running, anything can happen during
* this function.
**/
void
gtk_widget_show_now (GtkWidget *widget)
{
......@@ -1499,14 +1549,13 @@ gtk_widget_show_now (GtkWidget *widget)
gtk_widget_show (widget);
}
/*****************************************
/**
* gtk_widget_hide:
*
* arguments:
*
* results:
*****************************************/
* @widget: a #GtkWidget
*
* Reverses the effects of gtk_widget_show(), causing the widget to be
* hidden (invisible to the user).
**/
void
gtk_widget_hide (GtkWidget *widget)
{
......@@ -1538,6 +1587,19 @@ gtk_widget_real_hide (GtkWidget *widget)
}
}
/**
* gtk_widget_hide_on_delete:
* @widget: a #GtkWidget
*
* Utility function; intended to be connected to the "delete_event"
* signal on a #GtkWindow. The function calls gtk_widget_hide() on its
* argument, then returns %TRUE. If connected to "delete_event",
* the result is that clicking the window manager close button for
* will hide but not destroy the window. By default, GTK+ destroys
* windows when "delete_event" is received.
*
* Return value: %TRUE
**/
gint
gtk_widget_hide_on_delete (GtkWidget *widget)
{
......@@ -1549,6 +1611,13 @@ gtk_widget_hide_on_delete (GtkWidget *widget)
return TRUE;
}
/**
* gtk_widget_show_all:
* @widget: a #GtkWidget
*
* Recursively shows a widget, and any child widgets (if the widget is
* a container).
**/
void
gtk_widget_show_all (GtkWidget *widget)
{
......@@ -1563,6 +1632,12 @@ gtk_widget_show_all (GtkWidget *widget)
class->show_all (widget);
}
/**
* gtk_widget_hide_all:
* @widget: a #GtkWidget
*
* Recursively hides a widget and any child widgets.
**/
void
gtk_widget_hide_all (GtkWidget *widget)
{
......@@ -1577,14 +1652,14 @@ gtk_widget_hide_all (GtkWidget *widget)
class->hide_all (widget);
}
/*****************************************
/**
* gtk_widget_map:
*
* arguments:
*
* results:
*****************************************/
* @widget: a #GtkWidget
*
* INTERNAL FUNCTION, only for use in widget implementations. Causes
* a widget to be mapped if it isn't already.
*
**/
void
gtk_widget_map (GtkWidget *widget)
{
......@@ -1603,14 +1678,14 @@ gtk_widget_map (GtkWidget *widget)
}
}
/*****************************************
/**
* gtk_widget_unmap:
* @widget: a #GtkWidget
*
* arguments:
*
* results:
*****************************************/
* INTERNAL FUNCTION, only for use in widget implementations. Causes
* a widget to be unmapped if it's currently mapped.
*
**/
void
gtk_widget_unmap (GtkWidget *widget)
{
......@@ -1625,14 +1700,30 @@ gtk_widget_unmap (GtkWidget *widget)
}
}
/*****************************************
/**
* gtk_widget_realize:
*
* arguments:
*
* results:
*****************************************/
* @widget: a #GtkWidget
*
* Creates the GDK (windowing system) resources associated with a
* widget. For example, widget->window will be created when a widget
* is realized. Normally realization happens implicitly; if you show
* a widget and all its parent containers, then the widget will be
* realized and mapped automatically.
*
* Realizing a widget requires all
* the widget's parent widgets to be realized; calling
* gtk_widget_realize() realizes the widget's parents in addition to
* @widget itself. If a widget is not yet inside a toplevel window
* when you realize it, bad things will happen.
*
* This function is primarily used in widget implementations, and
* isn't very useful otherwise. Many times when you think you might
* need it, a better approach is to connect to a signal that will be
* called after the widget is realized automatically, such as
* "expose_event". Or simply gtk_signal_connect_after() to the
* "realize" signal.
*
**/
void
gtk_widget_realize (GtkWidget *widget)
{
......@@ -1649,6 +1740,12 @@ gtk_widget_realize (GtkWidget *widget)
if (GTK_IS_CONTAINER (widget) && !GTK_WIDGET_NO_WINDOW (widget))
g_message ("gtk_widget_realize(%s)", gtk_type_name (GTK_WIDGET_TYPE (widget)));
*/
if (widget->parent == NULL &&
!GTK_WIDGET_TOPLEVEL (widget))
g_warning ("Calling gtk_widget_realize() on a widget that isn't "
"inside a toplevel window is not going to work very well. "
"Widgets must be inside a toplevel container before realizing them.");
if (widget->parent && !GTK_WIDGET_REALIZED (widget->parent))
gtk_widget_realize (widget->parent);
......@@ -1680,14 +1777,15 @@ gtk_widget_realize (GtkWidget *widget)
}
}
/*****************************************
/**
* gtk_widget_unrealize:
* @widget: a #GtkWidget
*