1 /* GDK - The GIMP Drawing Kit
2 * Copyright (C) 2000 Red Hat, Inc.
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the License, or (at your option) any later version.
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with this library. If not, see <http://www.gnu.org/licenses/>.
22 #include "gdkscreen.h"
26 #include <pango/pangocairo.h>
30 * SECTION:pango_interaction
31 * @Short_description: Using Pango in GDK
32 * @Title: Pango Interaction
34 * Pango is the text layout system used by GDK and GTK+. The functions
35 * and types in this section are used to obtain clip regions for
36 * #PangoLayouts, and to get #PangoContexts that can be used with
39 * Creating a #PangoLayout object is the first step in rendering text,
40 * and requires getting a handle to a #PangoContext. For GTK+ programs,
41 * you'll usually want to use gtk_widget_get_pango_context(), or
42 * gtk_widget_create_pango_layout(), rather than using the lowlevel
43 * gdk_pango_context_get_for_screen(). Once you have a #PangoLayout, you
44 * can set the text and attributes of it with Pango functions like
45 * pango_layout_set_text() and get its size with pango_layout_get_size().
46 * (Note that Pango uses a fixed point system internally, so converting
47 * between Pango units and pixels using <link
48 * linkend="PANGO-SCALE-CAPS">PANGO_SCALE</link> or the PANGO_PIXELS() macro.)
50 * Rendering a Pango layout is done most simply with pango_cairo_show_layout();
51 * you can also draw pieces of the layout with pango_cairo_show_layout_line().
52 * <example id="rotated-example">
53 * <title>Draw transformed text with Pango and cairo</title>
54 * <!-- Note that this example is basically the same as
55 * demos/gtk-demo/rotated_text.c -->
59 * #define FONT "Sans Bold 18"
61 * PangoContext *context;
62 * PangoLayout *layout;
63 * PangoFontDescription *desc;
69 * /<!---->* Set up a transformation matrix so that the user space coordinates for
70 * * where we are drawing are [-RADIUS, RADIUS], [-RADIUS, RADIUS]
71 * * We first center, then change the scale *<!---->/
73 * width = gdk_window_get_width (window);
74 * height = gdk_window_get_height (window);
75 * radius = MIN (width, height) / 2.;
77 * cairo_translate (cr,
78 * radius + (width - 2 * radius) / 2,
79 * radius + (height - 2 * radius) / 2);
80 * cairo_scale (cr, radius / RADIUS, radius / RADIUS);
82 * /<!---->* Create a PangoLayout, set the font and text *<!---->/
83 * context = gdk_pango_context_get_for_screen (screen);
84 * layout = pango_layout_new (context);
85 * pango_layout_set_text (layout, "Text", -1);
86 * desc = pango_font_description_from_string (FONT);
87 * pango_layout_set_font_description (layout, desc);
88 * pango_font_description_free (desc);
90 * /<!---->* Draw the layout N_WORDS times in a circle *<!---->/
91 * for (i = 0; i < N_WORDS; i++)
93 * double red, green, blue;
94 * double angle = 2 * G_PI * i / n_words;
98 * /<!---->* Gradient from red at angle == 60 to blue at angle == 300 *<!---->/
99 * red = (1 + cos (angle - 60)) / 2;
103 * cairo_set_source_rgb (cr, red, green, blue);
104 * cairo_rotate (cr, angle);
106 * /<!---->* Inform Pango to re-layout the text with the new transformation matrix *<!---->/
107 * pango_cairo_update_layout (cr, layout);
109 * pango_layout_get_size (layout, &width, &height);
111 * cairo_move_to (cr, - width / 2 / PANGO_SCALE, - DEFAULT_TEXT_RADIUS);
112 * pango_cairo_show_layout (cr, layout);
114 * cairo_restore (cr);
117 * g_object_unref (layout);
118 * g_object_unref (context);
122 * <title>Output of <xref linkend="rotated-example"/></title>
123 * <graphic fileref="rotated-text.png" format="PNG"/>
127 /* Get a clip region to draw only part of a layout. index_ranges
128 * contains alternating range starts/stops. The region is the
129 * region which contains the given ranges, i.e. if you draw with the
130 * region as clip, only the given ranges are drawn.
132 static cairo_region_t*
133 layout_iter_get_line_clip_region (PangoLayoutIter *iter,
136 const gint *index_ranges,
139 PangoLayoutLine *line;
140 cairo_region_t *clip_region;
141 PangoRectangle logical_rect;
145 line = pango_layout_iter_get_line_readonly (iter);
147 clip_region = cairo_region_create ();
149 pango_layout_iter_get_line_extents (iter, NULL, &logical_rect);
150 baseline = pango_layout_iter_get_baseline (iter);
155 gint *pixel_ranges = NULL;
156 gint n_pixel_ranges = 0;
159 /* Note that get_x_ranges returns layout coordinates
161 if (index_ranges[i*2+1] >= line->start_index &&
162 index_ranges[i*2] < line->start_index + line->length)
163 pango_layout_line_get_x_ranges (line,
166 &pixel_ranges, &n_pixel_ranges);
168 for (j = 0; j < n_pixel_ranges; j++)
173 x_off = PANGO_PIXELS (pixel_ranges[2*j] - logical_rect.x);
174 y_off = PANGO_PIXELS (baseline - logical_rect.y);
176 rect.x = x_origin + x_off;
177 rect.y = y_origin - y_off;
178 rect.width = PANGO_PIXELS (pixel_ranges[2*j + 1] - logical_rect.x) - x_off;
179 rect.height = PANGO_PIXELS (baseline - logical_rect.y + logical_rect.height) - y_off;
181 cairo_region_union_rectangle (clip_region, &rect);
184 g_free (pixel_ranges);
191 * gdk_pango_layout_line_get_clip_region: (skip)
192 * @line: a #PangoLayoutLine
193 * @x_origin: X pixel where you intend to draw the layout line with this clip
194 * @y_origin: baseline pixel where you intend to draw the layout line with this clip
195 * @index_ranges: (array): array of byte indexes into the layout,
196 * where even members of array are start indexes and odd elements
198 * @n_ranges: number of ranges in @index_ranges, i.e. half the size of @index_ranges
200 * Obtains a clip region which contains the areas where the given
201 * ranges of text would be drawn. @x_origin and @y_origin are the top left
202 * position of the layout. @index_ranges
203 * should contain ranges of bytes in the layout's text. The clip
204 * region will include space to the left or right of the line (to the
205 * layout bounding box) if you have indexes above or below the indexes
206 * contained inside the line. This is to draw the selection all the way
207 * to the side of the layout. However, the clip region is in line coordinates,
208 * not layout coordinates.
210 * Note that the regions returned correspond to logical extents of the text
211 * ranges, not ink extents. So the drawn line may in fact touch areas out of
212 * the clip region. The clip region is mainly useful for highlightling parts
213 * of text, such as when text is selected.
215 * Return value: a clip region containing the given ranges
218 gdk_pango_layout_line_get_clip_region (PangoLayoutLine *line,
221 const gint *index_ranges,
224 cairo_region_t *clip_region;
225 PangoLayoutIter *iter;
227 g_return_val_if_fail (line != NULL, NULL);
228 g_return_val_if_fail (index_ranges != NULL, NULL);
230 iter = pango_layout_get_iter (line->layout);
231 while (pango_layout_iter_get_line_readonly (iter) != line)
232 pango_layout_iter_next_line (iter);
234 clip_region = layout_iter_get_line_clip_region(iter, x_origin, y_origin, index_ranges, n_ranges);
236 pango_layout_iter_free (iter);
242 * gdk_pango_layout_get_clip_region: (skip)
243 * @layout: a #PangoLayout
244 * @x_origin: X pixel where you intend to draw the layout with this clip
245 * @y_origin: Y pixel where you intend to draw the layout with this clip
246 * @index_ranges: array of byte indexes into the layout, where even members of array are start indexes and odd elements are end indexes
247 * @n_ranges: number of ranges in @index_ranges, i.e. half the size of @index_ranges
249 * Obtains a clip region which contains the areas where the given ranges
250 * of text would be drawn. @x_origin and @y_origin are the top left point
251 * to center the layout. @index_ranges should contain
252 * ranges of bytes in the layout's text.
254 * Note that the regions returned correspond to logical extents of the text
255 * ranges, not ink extents. So the drawn layout may in fact touch areas out of
256 * the clip region. The clip region is mainly useful for highlightling parts
257 * of text, such as when text is selected.
259 * Return value: a clip region containing the given ranges
262 gdk_pango_layout_get_clip_region (PangoLayout *layout,
265 const gint *index_ranges,
268 PangoLayoutIter *iter;
269 cairo_region_t *clip_region;
271 g_return_val_if_fail (PANGO_IS_LAYOUT (layout), NULL);
272 g_return_val_if_fail (index_ranges != NULL, NULL);
274 clip_region = cairo_region_create ();
276 iter = pango_layout_get_iter (layout);
280 PangoRectangle logical_rect;
281 cairo_region_t *line_region;
284 pango_layout_iter_get_line_extents (iter, NULL, &logical_rect);
285 baseline = pango_layout_iter_get_baseline (iter);
287 line_region = layout_iter_get_line_clip_region(iter,
288 x_origin + PANGO_PIXELS (logical_rect.x),
289 y_origin + PANGO_PIXELS (baseline),
293 cairo_region_union (clip_region, line_region);
294 cairo_region_destroy (line_region);
296 while (pango_layout_iter_next_line (iter));
298 pango_layout_iter_free (iter);
304 * gdk_pango_context_get:
306 * Creates a #PangoContext for the default GDK screen.
308 * The context must be freed when you're finished with it.
310 * When using GTK+, normally you should use gtk_widget_get_pango_context()
311 * instead of this function, to get the appropriate context for
312 * the widget you intend to render text onto.
314 * The newly created context will have the default font options (see
315 * #cairo_font_options_t) for the default screen; if these options
316 * change it will not be updated. Using gtk_widget_get_pango_context()
317 * is more convenient if you want to keep a context around and track
318 * changes to the screen's font rendering settings.
320 * Return value: (transfer full): a new #PangoContext for the default display
323 gdk_pango_context_get (void)
325 return gdk_pango_context_get_for_screen (gdk_screen_get_default ());
329 * gdk_pango_context_get_for_screen:
330 * @screen: the #GdkScreen for which the context is to be created.
332 * Creates a #PangoContext for @screen.
334 * The context must be freed when you're finished with it.
336 * When using GTK+, normally you should use gtk_widget_get_pango_context()
337 * instead of this function, to get the appropriate context for
338 * the widget you intend to render text onto.
340 * The newly created context will have the default font options
341 * (see #cairo_font_options_t) for the screen; if these options
342 * change it will not be updated. Using gtk_widget_get_pango_context()
343 * is more convenient if you want to keep a context around and track
344 * changes to the screen's font rendering settings.
346 * Return value: (transfer full): a new #PangoContext for @screen
351 gdk_pango_context_get_for_screen (GdkScreen *screen)
353 PangoFontMap *fontmap;
354 PangoContext *context;
355 const cairo_font_options_t *options;
358 g_return_val_if_fail (GDK_IS_SCREEN (screen), NULL);
360 fontmap = pango_cairo_font_map_get_default ();
361 context = pango_font_map_create_context (fontmap);
363 options = gdk_screen_get_font_options (screen);
364 pango_cairo_context_set_font_options (context, options);
366 dpi = gdk_screen_get_resolution (screen);
367 pango_cairo_context_set_resolution (context, dpi);