* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
- * License along with this library; if not, write to the
- * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
- * Boston, MA 02111-1307, USA.
+ * License along with this library. If not, see <http://www.gnu.org/licenses/>.
*/
#include "config.h"
#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
}
/**
- * gdk_pango_layout_line_get_clip_region:
+ * gdk_pango_layout_line_get_clip_region: (skip)
* @line: a #PangoLayoutLine
* @x_origin: X pixel where you intend to draw the layout line with this clip
* @y_origin: baseline pixel where you intend to draw the layout line with this clip
- * @index_ranges: array of byte indexes into the layout, where even members of array are start indexes and odd elements are end indexes
+ * @index_ranges: (array): array of byte indexes into the layout,
+ * where even members of array are start indexes and odd elements
+ * are end indexes
* @n_ranges: number of ranges in @index_ranges, i.e. half the size of @index_ranges
*
* Obtains a clip region which contains the areas where the given
}
/**
- * gdk_pango_layout_get_clip_region:
+ * gdk_pango_layout_get_clip_region: (skip)
* @layout: a #PangoLayout
* @x_origin: X pixel where you intend to draw the layout with this clip
* @y_origin: Y pixel where you intend to draw the layout with this clip
* is more convenient if you want to keep a context around and track
* changes to the screen's font rendering settings.
*
- * Return value: a new #PangoContext for the default display
+ * Return value: (transfer full): a new #PangoContext for the default display
**/
PangoContext *
gdk_pango_context_get (void)
* is more convenient if you want to keep a context around and track
* changes to the screen's font rendering settings.
*
- * Return value: a new #PangoContext for @screen
+ * Return value: (transfer full): a new #PangoContext for @screen
*
* Since: 2.2
**/
PangoContext *context;
const cairo_font_options_t *options;
double dpi;
-
+
g_return_val_if_fail (GDK_IS_SCREEN (screen), NULL);
fontmap = pango_cairo_font_map_get_default ();
-
- context = pango_cairo_font_map_create_context (PANGO_CAIRO_FONT_MAP (fontmap));
+ context = pango_font_map_create_context (fontmap);
options = gdk_screen_get_font_options (screen);
pango_cairo_context_set_font_options (context, options);