docs: Move documentation to inline comments: gdkpango

This commit is contained in:
Javier Jardón 2010-11-15 16:50:21 +01:00
parent cc13047315
commit 9a8fcfa65a
3 changed files with 100 additions and 158 deletions

View File

@ -9,6 +9,7 @@ gdkscreen.sgml
gdktesting.sgml
general.sgml
keys.sgml
pango_interaction.sgml
pixbufs.sgml
regions.sgml
windows.sgml

View File

@ -1,158 +0,0 @@
<!-- ##### SECTION Title ##### -->
Pango Interaction
<!-- ##### SECTION Short_Description ##### -->
Using Pango in GDK
<!-- ##### SECTION Long_Description ##### -->
<para>
Pango is the text layout system used by GDK and GTK+. The functions
and types in this section are used to obtain clip regions for
#PangoLayouts, and to get #PangoContexts that can be used with
GDK.
</para>
<para>
Creating a #PangoLayout object is the first step in rendering text,
and requires getting a handle to a #PangoContext. For GTK+ programs,
you'll usually want to use gtk_widget_get_pango_context(), or
gtk_widget_create_pango_layout(), rather than using the lowlevel
gdk_pango_context_get_for_screen(). Once you have a #PangoLayout, you
can set the text and attributes of it with Pango functions like
pango_layout_set_text() and get its size with pango_layout_get_size().
(Note that Pango uses a fixed point system internally, so converting
between Pango units and pixels using <link
linkend="PANGO-SCALE-CAPS">PANGO_SCALE</link> or the PANGO_PIXELS() macro.)
</para>
<para>
Rendering a Pango layout is done most simply with pango_cairo_show_layout();
you can also draw pieces of the layout with pango_cairo_show_layout_line().
</para>
<example id="rotated-example">
<title>Draw transformed text with Pango and cairo</title>
<!-- Note that this example is basically the same as
demos/gtk-demo/rotated_text.c -->
<programlisting>
#define RADIUS 100
#define N_WORDS 10
#define FONT "Sans Bold 18"
PangoContext *context;
PangoLayout *layout;
PangoFontDescription *desc;
double radius;
int width, height;
int i;
/* Set up a transformation matrix so that the user space coordinates for
* where we are drawing are [-RADIUS, RADIUS], [-RADIUS, RADIUS]
* We first center, then change the scale */
width = gdk_window_get_width (window);
height = gdk_window_get_height (window);
radius = MIN (width, height) / 2.;
cairo_translate (cr,
radius + (width - 2 * radius) / 2,
radius + (height - 2 * radius) / 2);
cairo_scale (cr, radius / RADIUS, radius / RADIUS);
/* Create a PangoLayout, set the font and text */
context = gdk_pango_context_get_for_screen (screen);
layout = pango_layout_new (context);
pango_layout_set_text (layout, "Text", -1);
desc = pango_font_description_from_string (FONT);
pango_layout_set_font_description (layout, desc);
pango_font_description_free (desc);
/* Draw the layout N_WORDS times in a circle */
for (i = 0; i &lt; N_WORDS; i++)
{
double red, green, blue;
double angle = 2 * G_PI * i / n_words;
cairo_save (cr);
/* Gradient from red at angle == 60 to blue at angle == 300 */
red = (1 + cos (angle - 60)) / 2;
green = 0;
blue = 1 - red;
cairo_set_source_rgb (cr, red, green, blue);
cairo_rotate (cr, angle);
/* Inform Pango to re-layout the text with the new transformation matrix */
pango_cairo_update_layout (cr, layout);
pango_layout_get_size (layout, &amp;width, &amp;height);
cairo_move_to (cr, - width / 2 / PANGO_SCALE, - DEFAULT_TEXT_RADIUS);
pango_cairo_show_layout (cr, layout);
cairo_restore (cr);
}
g_object_unref (layout);
g_object_unref (context);
</programlisting>
</example>
<figure>
<title>Output of <xref linkend="rotated-example"/></title>
<graphic fileref="rotated-text.png" format="PNG"/>
</figure>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<!-- ##### SECTION Stability_Level ##### -->
<!-- ##### SECTION Image ##### -->
<!-- ##### FUNCTION gdk_pango_layout_get_clip_region ##### -->
<para>
</para>
@layout:
@x_origin:
@y_origin:
@index_ranges:
@n_ranges:
@Returns:
<!-- ##### FUNCTION gdk_pango_layout_line_get_clip_region ##### -->
<para>
</para>
@line:
@x_origin:
@y_origin:
@index_ranges:
@n_ranges:
@Returns:
<!-- ##### FUNCTION gdk_pango_context_get ##### -->
<para>
</para>
@void:
@Returns:
<!-- ##### FUNCTION gdk_pango_context_get_for_screen ##### -->
<para>
</para>
@screen:
@Returns:

View File

@ -27,6 +27,105 @@
#include <math.h>
#include <pango/pangocairo.h>
/**
* SECTION:pango_interaction
* @Short_description: Using Pango in GDK
* @Title: Pango Interaction
*
* Pango is the text layout system used by GDK and GTK+. The functions
* and types in this section are used to obtain clip regions for
* #PangoLayouts, and to get #PangoContexts that can be used with
* GDK.
*
* Creating a #PangoLayout object is the first step in rendering text,
* and requires getting a handle to a #PangoContext. For GTK+ programs,
* you'll usually want to use gtk_widget_get_pango_context(), or
* gtk_widget_create_pango_layout(), rather than using the lowlevel
* gdk_pango_context_get_for_screen(). Once you have a #PangoLayout, you
* can set the text and attributes of it with Pango functions like
* pango_layout_set_text() and get its size with pango_layout_get_size().
* (Note that Pango uses a fixed point system internally, so converting
* between Pango units and pixels using <link
* linkend="PANGO-SCALE-CAPS">PANGO_SCALE</link> or the PANGO_PIXELS() macro.)
*
* Rendering a Pango layout is done most simply with pango_cairo_show_layout();
* you can also draw pieces of the layout with pango_cairo_show_layout_line().
* <example id="rotated-example">
* <title>Draw transformed text with Pango and cairo</title>
* <!-- Note that this example is basically the same as
* demos/gtk-demo/rotated_text.c -->
* <programlisting>
* #define RADIUS 100
* #define N_WORDS 10
* #define FONT "Sans Bold 18"
*
* PangoContext *context;
* PangoLayout *layout;
* PangoFontDescription *desc;
*
* double radius;
* int width, height;
* int i;
*
* /<!---->* Set up a transformation matrix so that the user space coordinates for
* * where we are drawing are [-RADIUS, RADIUS], [-RADIUS, RADIUS]
* * We first center, then change the scale *<!---->/
*
* width = gdk_window_get_width (window);
* height = gdk_window_get_height (window);
* radius = MIN (width, height) / 2.;
*
* cairo_translate (cr,
* radius + (width - 2 * radius) / 2,
* radius + (height - 2 * radius) / 2);
* cairo_scale (cr, radius / RADIUS, radius / RADIUS);
*
* /<!---->* Create a PangoLayout, set the font and text *<!---->/
* context = gdk_pango_context_get_for_screen (screen);
* layout = pango_layout_new (context);
* pango_layout_set_text (layout, "Text", -1);
* desc = pango_font_description_from_string (FONT);
* pango_layout_set_font_description (layout, desc);
* pango_font_description_free (desc);
*
* /<!---->* Draw the layout N_WORDS times in a circle *<!---->/
* for (i = 0; i < N_WORDS; i++)
* {
* double red, green, blue;
* double angle = 2 * G_PI * i / n_words;
*
* cairo_save (cr);
*
* /<!---->* Gradient from red at angle == 60 to blue at angle == 300 *<!---->/
* red = (1 + cos (angle - 60)) / 2;
* green = 0;
* blue = 1 - red;
*
* cairo_set_source_rgb (cr, red, green, blue);
* cairo_rotate (cr, angle);
*
* /<!---->* Inform Pango to re-layout the text with the new transformation matrix *<!---->/
* pango_cairo_update_layout (cr, layout);
*
* pango_layout_get_size (layout, &width, &height);
*
* cairo_move_to (cr, - width / 2 / PANGO_SCALE, - DEFAULT_TEXT_RADIUS);
* pango_cairo_show_layout (cr, layout);
*
* cairo_restore (cr);
* }
*
* g_object_unref (layout);
* g_object_unref (context);
* </programlisting>
* </example>
* <figure>
* <title>Output of <xref linkend="rotated-example"/></title>
* <graphic fileref="rotated-text.png" format="PNG"/>
* </figure>
*/
/* Get a clip region to draw only part of a layout. index_ranges
* contains alternating range starts/stops. The region is the
* region which contains the given ranges, i.e. if you draw with the