forked from AuroraMiddleware/gtk
Move documentation to inline comments: GtkImage
https://bugzilla.gnome.org/show_bug.cgi?id=597865
This commit is contained in:
Javier Jardón
parent
016fba99e7
commit
e62e7f76c9
@ -1,518 +0,0 @@
|
||||
<!-- ##### SECTION Title ##### -->
|
||||
GtkImage
|
||||
|
||||
<!-- ##### SECTION Short_Description ##### -->
|
||||
A widget displaying an image
|
||||
|
||||
<!-- ##### SECTION Long_Description ##### -->
|
||||
<para>
|
||||
The #GtkImage widget displays an image. Various kinds of object
|
||||
can be displayed as an image; most typically, you would load a
|
||||
#GdkPixbuf ("pixel buffer") from a file, and then display that.
|
||||
There's a convenience function to do this, gtk_image_new_from_file(),
|
||||
used as follows:
|
||||
<informalexample><programlisting>
|
||||
GtkWidget *image;
|
||||
image = gtk_image_new_from_file ("myfile.png");
|
||||
</programlisting></informalexample>
|
||||
If the file isn't loaded successfully, the image will contain a
|
||||
"broken image" icon similar to that used in many web browsers.
|
||||
If you want to handle errors in loading the file yourself,
|
||||
for example by displaying an error message, then load the image with
|
||||
gdk_pixbuf_new_from_file(), then create the #GtkImage with
|
||||
gtk_image_new_from_pixbuf().
|
||||
</para>
|
||||
<para>
|
||||
The image file may contain an animation, if so the #GtkImage will
|
||||
display an animation (#GdkPixbufAnimation) instead of a static image.
|
||||
</para>
|
||||
<para>
|
||||
#GtkImage is a subclass of #GtkMisc, which implies that you can
|
||||
align it (center, left, right) and add padding to it, using
|
||||
#GtkMisc methods.
|
||||
</para>
|
||||
<para>
|
||||
#GtkImage is a "no window" widget (has no #GdkWindow of its own),
|
||||
so by default does not receive events. If you want to receive events
|
||||
on the image, such as button clicks, place the image inside a
|
||||
#GtkEventBox, then connect to the event signals on the event box.
|
||||
<example>
|
||||
<title>Handling button press events on a
|
||||
<structname>GtkImage</structname>.</title>
|
||||
<programlisting>
|
||||
static gboolean
|
||||
button_press_callback (GtkWidget *event_box,
|
||||
GdkEventButton *event,
|
||||
gpointer data)
|
||||
{
|
||||
g_print ("Event box clicked at coordinates %f,%f\n",
|
||||
event->x, event->y);
|
||||
|
||||
/* Returning TRUE means we handled the event, so the signal
|
||||
* emission should be stopped (don't call any further
|
||||
* callbacks that may be connected). Return FALSE
|
||||
* to continue invoking callbacks.
|
||||
*/
|
||||
return TRUE;
|
||||
}
|
||||
|
||||
static GtkWidget*
|
||||
create_image (void)
|
||||
{
|
||||
GtkWidget *image;
|
||||
GtkWidget *event_box;
|
||||
|
||||
image = gtk_image_new_from_file ("myfile.png");
|
||||
|
||||
event_box = gtk_event_box_new (<!-- -->);
|
||||
|
||||
gtk_container_add (GTK_CONTAINER (event_box), image);
|
||||
|
||||
g_signal_connect (G_OBJECT (event_box),
|
||||
"button_press_event",
|
||||
G_CALLBACK (button_press_callback),
|
||||
image);
|
||||
|
||||
return image;
|
||||
}
|
||||
</programlisting>
|
||||
</example>
|
||||
</para>
|
||||
<para>
|
||||
When handling events on the event box, keep in mind that coordinates
|
||||
in the image may be different from event box coordinates due to
|
||||
the alignment and padding settings on the image (see #GtkMisc).
|
||||
The simplest way to solve this is to set the alignment to 0.0
|
||||
(left/top), and set the padding to zero. Then the origin of
|
||||
the image will be the same as the origin of the event box.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Sometimes an application will want to avoid depending on external data
|
||||
files, such as image files. GTK+ comes with a program to avoid this,
|
||||
called <application>gdk-pixbuf-csource</application>. This program
|
||||
allows you to convert an image into a C variable declaration, which
|
||||
can then be loaded into a #GdkPixbuf using
|
||||
gdk_pixbuf_new_from_inline().
|
||||
</para>
|
||||
|
||||
<!-- ##### SECTION See_Also ##### -->
|
||||
<para>
|
||||
#GdkPixbuf
|
||||
</para>
|
||||
|
||||
<!-- ##### SECTION Stability_Level ##### -->
|
||||
|
||||
|
||||
<!-- ##### STRUCT GtkImage ##### -->
|
||||
<para>
|
||||
This struct contain private data only and should be accessed by the functions
|
||||
below.
|
||||
</para>
|
||||
|
||||
|
||||
<!-- ##### ARG GtkImage:file ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
<!-- ##### ARG GtkImage:gicon ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
<!-- ##### ARG GtkImage:icon-name ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
<!-- ##### ARG GtkImage:icon-set ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
<!-- ##### ARG GtkImage:icon-size ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
<!-- ##### ARG GtkImage:image ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
<!-- ##### ARG GtkImage:mask ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
<!-- ##### ARG GtkImage:pixbuf ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
<!-- ##### ARG GtkImage:pixbuf-animation ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
<!-- ##### ARG GtkImage:pixel-size ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
<!-- ##### ARG GtkImage:pixmap ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
<!-- ##### ARG GtkImage:stock ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
<!-- ##### ARG GtkImage:storage-type ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
<!-- ##### ENUM GtkImageType ##### -->
|
||||
<para>
|
||||
Describes the image data representation used by a #GtkImage. If you
|
||||
want to get the image from the widget, you can only get the
|
||||
currently-stored representation. e.g. if the
|
||||
gtk_image_get_storage_type() returns #GTK_IMAGE_PIXBUF, then you can
|
||||
call gtk_image_get_pixbuf() but not gtk_image_get_stock(). For empty
|
||||
images, you can request any storage type (call any of the "get"
|
||||
functions), but they will all return %NULL values.
|
||||
</para>
|
||||
|
||||
@GTK_IMAGE_EMPTY: there is no image displayed by the widget
|
||||
@GTK_IMAGE_PIXMAP: the widget contains a #GdkPixmap
|
||||
@GTK_IMAGE_IMAGE: the widget contains a #GdkImage
|
||||
@GTK_IMAGE_PIXBUF: the widget contains a #GdkPixbuf
|
||||
@GTK_IMAGE_STOCK: the widget contains a stock icon name (see <xref linkend="gtk-Stock-Items"/>)
|
||||
@GTK_IMAGE_ICON_SET: the widget contains a #GtkIconSet
|
||||
@GTK_IMAGE_ANIMATION: the widget contains a #GdkPixbufAnimation
|
||||
@GTK_IMAGE_ICON_NAME: the widget contains a named icon.
|
||||
This image type was added in GTK+ 2.6
|
||||
@GTK_IMAGE_GICON: the widget contains a #GIcon.
|
||||
This image type was added in GTK+ 2.14
|
||||
|
||||
<!-- ##### FUNCTION gtk_image_get_icon_set ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@image:
|
||||
@icon_set:
|
||||
@size:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_image_get_image ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@image:
|
||||
@gdk_image:
|
||||
@mask:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_image_get_pixbuf ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@image:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_image_get_pixmap ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@image:
|
||||
@pixmap:
|
||||
@mask:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_image_get_stock ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@image:
|
||||
@stock_id:
|
||||
@size:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_image_get_animation ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@image:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_image_get_icon_name ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@image:
|
||||
@icon_name:
|
||||
@size:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_image_get_gicon ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@image:
|
||||
@gicon:
|
||||
@size:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_image_get_storage_type ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@image:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_image_new_from_file ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@filename:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_image_new_from_icon_set ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@icon_set:
|
||||
@size:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_image_new_from_image ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@image:
|
||||
@mask:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_image_new_from_pixbuf ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@pixbuf:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_image_new_from_pixmap ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@pixmap:
|
||||
@mask:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_image_new_from_stock ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@stock_id:
|
||||
@size:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_image_new_from_animation ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@animation:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_image_new_from_icon_name ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@icon_name:
|
||||
@size:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_image_new_from_gicon ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@icon:
|
||||
@size:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_image_set_from_file ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@image:
|
||||
@filename:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_image_set_from_icon_set ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@image:
|
||||
@icon_set:
|
||||
@size:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_image_set_from_image ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@image:
|
||||
@gdk_image:
|
||||
@mask:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_image_set_from_pixbuf ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@image:
|
||||
@pixbuf:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_image_set_from_pixmap ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@image:
|
||||
@pixmap:
|
||||
@mask:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_image_set_from_stock ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@image:
|
||||
@stock_id:
|
||||
@size:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_image_set_from_animation ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@image:
|
||||
@animation:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_image_set_from_icon_name ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@image:
|
||||
@icon_name:
|
||||
@size:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_image_set_from_gicon ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@image:
|
||||
@icon:
|
||||
@size:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_image_clear ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@image:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_image_new ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@Returns: the #GtkImage
|
||||
<!-- # Unused Parameters # -->
|
||||
@mask: a #GdkBitmap that indicates which parts of the image should be transparent.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_image_set ##### -->
|
||||
<para>
|
||||
Sets the #GtkImage.
|
||||
</para>
|
||||
|
||||
@image: a #GtkImage
|
||||
@val: a #GdkImage
|
||||
@mask: a #GdkBitmap that indicates which parts of the image should be transparent.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_image_get ##### -->
|
||||
<para>
|
||||
Gets the #GtkImage.
|
||||
</para>
|
||||
|
||||
@image: a #GtkImage
|
||||
@val: return location for a #GdkImage
|
||||
@mask: a #GdkBitmap that indicates which parts of the image should be transparent.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_image_set_pixel_size ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@image:
|
||||
@pixel_size:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_image_get_pixel_size ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@image:
|
||||
@Returns:
|
||||
|
||||
|
||||
110
gtk/gtkimage.c
110
gtk/gtkimage.c
@ -37,6 +37,96 @@
|
||||
#include "gtkprivate.h"
|
||||
#include "gtkalias.h"
|
||||
|
||||
/**
|
||||
* SECTION:gtkimage
|
||||
* @Short_description: A widget displaying an image
|
||||
* @Title: GtkImage
|
||||
* @See_also:#GdkPixbuf
|
||||
*
|
||||
* The #GtkImage widget displays an image. Various kinds of object
|
||||
* can be displayed as an image; most typically, you would load a
|
||||
* #GdkPixbuf ("pixel buffer") from a file, and then display that.
|
||||
* There's a convenience function to do this, gtk_image_new_from_file(),
|
||||
* used as follows:
|
||||
* <informalexample><programlisting>
|
||||
* GtkWidget *image;
|
||||
* image = gtk_image_new_from_file ("myfile.png");
|
||||
* </programlisting></informalexample>
|
||||
* If the file isn't loaded successfully, the image will contain a
|
||||
* "broken image" icon similar to that used in many web browsers.
|
||||
* If you want to handle errors in loading the file yourself,
|
||||
* for example by displaying an error message, then load the image with
|
||||
* gdk_pixbuf_new_from_file(), then create the #GtkImage with
|
||||
* gtk_image_new_from_pixbuf().
|
||||
*
|
||||
* The image file may contain an animation, if so the #GtkImage will
|
||||
* display an animation (#GdkPixbufAnimation) instead of a static image.
|
||||
*
|
||||
* #GtkImage is a subclass of #GtkMisc, which implies that you can
|
||||
* align it (center, left, right) and add padding to it, using
|
||||
* #GtkMisc methods.
|
||||
*
|
||||
* #GtkImage is a "no window" widget (has no #GdkWindow of its own),
|
||||
* so by default does not receive events. If you want to receive events
|
||||
* on the image, such as button clicks, place the image inside a
|
||||
* #GtkEventBox, then connect to the event signals on the event box.
|
||||
* <example>
|
||||
* <title>Handling button press events on a
|
||||
* <structname>GtkImage</structname>.</title>
|
||||
* <programlisting>
|
||||
* static gboolean
|
||||
* button_press_callback (GtkWidget *event_box,
|
||||
* GdkEventButton *event,
|
||||
* gpointer data)
|
||||
* {
|
||||
* g_print ("Event box clicked at coordinates %f,%f\n",
|
||||
* event->x, event->y);
|
||||
*
|
||||
* /<!---->* Returning TRUE means we handled the event, so the signal
|
||||
* * emission should be stopped (don't call any further
|
||||
* * callbacks that may be connected). Return FALSE
|
||||
* * to continue invoking callbacks.
|
||||
* *<!---->/
|
||||
* return TRUE;
|
||||
* }
|
||||
*
|
||||
* static GtkWidget*
|
||||
* create_image (void)
|
||||
* {
|
||||
* GtkWidget *image;
|
||||
* GtkWidget *event_box;
|
||||
*
|
||||
* image = gtk_image_new_from_file ("myfile.png");
|
||||
*
|
||||
* event_box = gtk_event_box_new (<!-- -->);
|
||||
*
|
||||
* gtk_container_add (GTK_CONTAINER (event_box), image);
|
||||
*
|
||||
* g_signal_connect (G_OBJECT (event_box),
|
||||
* "button_press_event",
|
||||
* G_CALLBACK (button_press_callback),
|
||||
* image);
|
||||
*
|
||||
* return image;
|
||||
* }
|
||||
* </programlisting>
|
||||
* </example>
|
||||
*
|
||||
* When handling events on the event box, keep in mind that coordinates
|
||||
* in the image may be different from event box coordinates due to
|
||||
* the alignment and padding settings on the image (see #GtkMisc).
|
||||
* The simplest way to solve this is to set the alignment to 0.0
|
||||
* (left/top), and set the padding to zero. Then the origin of
|
||||
* the image will be the same as the origin of the event box.
|
||||
*
|
||||
* Sometimes an application will want to avoid depending on external data
|
||||
* files, such as image files. GTK+ comes with a program to avoid this,
|
||||
* called <application>gdk-pixbuf-csource</application>. This program
|
||||
* allows you to convert an image into a C variable declaration, which
|
||||
* can then be loaded into a #GdkPixbuf using
|
||||
* gdk_pixbuf_new_from_inline().
|
||||
*/
|
||||
|
||||
typedef struct _GtkImagePrivate GtkImagePrivate;
|
||||
|
||||
struct _GtkImagePrivate
|
||||
@ -1431,6 +1521,16 @@ gtk_image_new (void)
|
||||
return g_object_new (GTK_TYPE_IMAGE, NULL);
|
||||
}
|
||||
|
||||
/**
|
||||
* gtk_image_set:
|
||||
* @image: a #GtkImage
|
||||
* @val: a #GdkImage
|
||||
* @mask: a #GdkBitmap that indicates which parts of the image should be transparent.
|
||||
*
|
||||
* Sets the #GtkImage.
|
||||
*
|
||||
* Deprecated: 2.0: Use gtk_image_set_from_image() instead.
|
||||
*/
|
||||
void
|
||||
gtk_image_set (GtkImage *image,
|
||||
GdkImage *val,
|
||||
@ -1441,6 +1541,16 @@ gtk_image_set (GtkImage *image,
|
||||
gtk_image_set_from_image (image, val, mask);
|
||||
}
|
||||
|
||||
/**
|
||||
* gtk_image_get:
|
||||
* @image: a #GtkImage
|
||||
* @val: return location for a #GdkImage
|
||||
* @mask: a #GdkBitmap that indicates which parts of the image should be transparent.
|
||||
*
|
||||
* Gets the #GtkImage.
|
||||
*
|
||||
* Deprecated: 2.0: Use gtk_image_get_image() instead.
|
||||
*/
|
||||
void
|
||||
gtk_image_get (GtkImage *image,
|
||||
GdkImage **val,
|
||||
|
||||
@ -104,6 +104,28 @@ struct _GtkImageGIconData
|
||||
guint theme_change_id;
|
||||
};
|
||||
|
||||
/**
|
||||
* GtkImageType:
|
||||
* @GTK_IMAGE_EMPTY: there is no image displayed by the widget
|
||||
* @GTK_IMAGE_PIXMAP: the widget contains a #GdkPixmap
|
||||
* @GTK_IMAGE_IMAGE: the widget contains a #GdkImage
|
||||
* @GTK_IMAGE_PIXBUF: the widget contains a #GdkPixbuf
|
||||
* @GTK_IMAGE_STOCK: the widget contains a stock icon name (see <xref linkend="gtk-Stock-Items"/>)
|
||||
* @GTK_IMAGE_ICON_SET: the widget contains a #GtkIconSet
|
||||
* @GTK_IMAGE_ANIMATION: the widget contains a #GdkPixbufAnimation
|
||||
* @GTK_IMAGE_ICON_NAME: the widget contains a named icon.
|
||||
* This image type was added in GTK+ 2.6
|
||||
* @GTK_IMAGE_GICON: the widget contains a #GIcon.
|
||||
* This image type was added in GTK+ 2.14
|
||||
*
|
||||
* Describes the image data representation used by a #GtkImage. If you
|
||||
* want to get the image from the widget, you can only get the
|
||||
* currently-stored representation. e.g. if the
|
||||
* gtk_image_get_storage_type() returns #GTK_IMAGE_PIXBUF, then you can
|
||||
* call gtk_image_get_pixbuf() but not gtk_image_get_stock(). For empty
|
||||
* images, you can request any storage type (call any of the "get"
|
||||
* functions), but they will all return %NULL values.
|
||||
*/
|
||||
typedef enum
|
||||
{
|
||||
GTK_IMAGE_EMPTY,
|
||||
@ -117,6 +139,12 @@ typedef enum
|
||||
GTK_IMAGE_GICON
|
||||
} GtkImageType;
|
||||
|
||||
/**
|
||||
* GtkImage:
|
||||
*
|
||||
* This struct contain private data only and should be accessed by the functions
|
||||
* below.
|
||||
*/
|
||||
struct _GtkImage
|
||||
{
|
||||
GtkMisc misc;
|
||||
|
||||
Loading…
Reference in New Issue
Block a user