pango-1.0/pango/pango-glyph-item.h

0001 /* Pango
0002  * pango-glyph-item.h: Pair of PangoItem and a glyph string
0003  *
0004  * Copyright (C) 2002 Red Hat Software
0005  *
0006  * This library is free software; you can redistribute it and/or
0007  * modify it under the terms of the GNU Library General Public
0008  * License as published by the Free Software Foundation; either
0009  * version 2 of the License, or (at your option) any later version.
0010  *
0011  * This library is distributed in the hope that it will be useful,
0012  * but WITHOUT ANY WARRANTY; without even the implied warranty of
0013  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0014  * Library General Public License for more details.
0015  *
0016  * You should have received a copy of the GNU Library General Public
0017  * License along with this library; if not, write to the
0018  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
0019  * Boston, MA 02111-1307, USA.
0020  */
0021
0022 #ifndef __PANGO_GLYPH_ITEM_H__
0023 #define __PANGO_GLYPH_ITEM_H__
0024
0025 #include <pango/pango-attributes.h>
0026 #include <pango/pango-break.h>
0027 #include <pango/pango-item.h>
0028 #include <pango/pango-glyph.h>
0029
0030 G_BEGIN_DECLS
0031
0032 /**
0033  * PangoGlyphItem:
0034  * @item: corresponding `PangoItem`
0035  * @glyphs: corresponding `PangoGlyphString`
0036  * @y_offset: shift of the baseline, relative to the baseline
0037  *   of the containing line. Positive values shift upwards
0038  * @start_x_offset: horizontal displacement to apply before the
0039  *   glyph item. Positive values shift right
0040  * @end_x_offset: horizontal displacement to apply after th
0041  *   glyph item. Positive values shift right
0042  *
0043  * A `PangoGlyphItem` is a pair of a `PangoItem` and the glyphs
0044  * resulting from shaping the items text.
0045  *
0046  * As an example of the usage of `PangoGlyphItem`, the results
0047  * of shaping text with `PangoLayout` is a list of `PangoLayoutLine`,
0048  * each of which contains a list of `PangoGlyphItem`.
0049  */
0050 typedef struct _PangoGlyphItem PangoGlyphItem;
0051
0052 struct _PangoGlyphItem
0053 {
0054   PangoItem *item;
0055   PangoGlyphString *glyphs;
0056   int y_offset;
0057   int start_x_offset;
0058   int end_x_offset;
0059 };
0060
0061 #define PANGO_TYPE_GLYPH_ITEM (pango_glyph_item_get_type ())
0062
0063 PANGO_AVAILABLE_IN_ALL
0064 GType pango_glyph_item_get_type (void) G_GNUC_CONST;
0065
0066 PANGO_AVAILABLE_IN_1_2
0067 PangoGlyphItem *pango_glyph_item_split        (PangoGlyphItem *orig,
0068                            const char     *text,
0069                            int             split_index);
0070 PANGO_AVAILABLE_IN_1_20
0071 PangoGlyphItem *pango_glyph_item_copy         (PangoGlyphItem *orig);
0072 PANGO_AVAILABLE_IN_1_6
0073 void            pango_glyph_item_free         (PangoGlyphItem *glyph_item);
0074 PANGO_AVAILABLE_IN_1_2
0075 GSList *        pango_glyph_item_apply_attrs  (PangoGlyphItem *glyph_item,
0076                            const char     *text,
0077                            PangoAttrList  *list);
0078 PANGO_AVAILABLE_IN_1_6
0079 void            pango_glyph_item_letter_space (PangoGlyphItem *glyph_item,
0080                            const char     *text,
0081                            PangoLogAttr   *log_attrs,
0082                            int             letter_spacing);
0083 PANGO_AVAILABLE_IN_1_26
0084 void      pango_glyph_item_get_logical_widths (PangoGlyphItem *glyph_item,
0085                            const char     *text,
0086                            int            *logical_widths);
0087
0088
0089 /**
0090  * PangoGlyphItemIter:
0091  *
0092  * A `PangoGlyphItemIter` is an iterator over the clusters in a
0093  * `PangoGlyphItem`.
0094  *
0095  * The *forward direction* of the iterator is the logical direction of text.
0096  * That is, with increasing @start_index and @start_char values. If @glyph_item
0097  * is right-to-left (that is, if `glyph_item->item->analysis.level` is odd),
0098  * then @start_glyph decreases as the iterator moves forward.  Moreover,
0099  * in right-to-left cases, @start_glyph is greater than @end_glyph.
0100  *
0101  * An iterator should be initialized using either
0102  * pango_glyph_item_iter_init_start() or
0103  * pango_glyph_item_iter_init_end(), for forward and backward iteration
0104  * respectively, and walked over using any desired mixture of
0105  * pango_glyph_item_iter_next_cluster() and
0106  * pango_glyph_item_iter_prev_cluster().
0107  *
0108  * A common idiom for doing a forward iteration over the clusters is:
0109  *
0110  * ```
0111  * PangoGlyphItemIter cluster_iter;
0112  * gboolean have_cluster;
0113  *
0114  * for (have_cluster = pango_glyph_item_iter_init_start (&cluster_iter,
0115  *                                                       glyph_item, text);
0116  *      have_cluster;
0117  *      have_cluster = pango_glyph_item_iter_next_cluster (&cluster_iter))
0118  * {
0119  *   ...
0120  * }
0121  * ```
0122  *
0123  * Note that @text is the start of the text for layout, which is then
0124  * indexed by `glyph_item->item->offset` to get to the text of @glyph_item.
0125  * The @start_index and @end_index values can directly index into @text. The
0126  * @start_glyph, @end_glyph, @start_char, and @end_char values however are
0127  * zero-based for the @glyph_item.  For each cluster, the item pointed at by
0128  * the start variables is included in the cluster while the one pointed at by
0129  * end variables is not.
0130  *
0131  * None of the members of a `PangoGlyphItemIter` should be modified manually.
0132  *
0133  * Since: 1.22
0134  */
0135 typedef struct _PangoGlyphItemIter PangoGlyphItemIter;
0136
0137 struct _PangoGlyphItemIter
0138 {
0139   PangoGlyphItem *glyph_item;
0140   const gchar *text;
0141
0142   int start_glyph;
0143   int start_index;
0144   int start_char;
0145
0146   int end_glyph;
0147   int end_index;
0148   int end_char;
0149 };
0150
0151 #define PANGO_TYPE_GLYPH_ITEM_ITER (pango_glyph_item_iter_get_type ())
0152
0153 PANGO_AVAILABLE_IN_1_22
0154 GType               pango_glyph_item_iter_get_type (void) G_GNUC_CONST;
0155 PANGO_AVAILABLE_IN_1_22
0156 PangoGlyphItemIter *pango_glyph_item_iter_copy (PangoGlyphItemIter *orig);
0157 PANGO_AVAILABLE_IN_1_22
0158 void                pango_glyph_item_iter_free (PangoGlyphItemIter *iter);
0159
0160 PANGO_AVAILABLE_IN_1_22
0161 gboolean pango_glyph_item_iter_init_start   (PangoGlyphItemIter *iter,
0162                          PangoGlyphItem     *glyph_item,
0163                          const char         *text);
0164 PANGO_AVAILABLE_IN_1_22
0165 gboolean pango_glyph_item_iter_init_end     (PangoGlyphItemIter *iter,
0166                          PangoGlyphItem     *glyph_item,
0167                          const char         *text);
0168 PANGO_AVAILABLE_IN_1_22
0169 gboolean pango_glyph_item_iter_next_cluster (PangoGlyphItemIter *iter);
0170 PANGO_AVAILABLE_IN_1_22
0171 gboolean pango_glyph_item_iter_prev_cluster (PangoGlyphItemIter *iter);
0172
0173 G_END_DECLS
0174
0175 #endif /* __PANGO_GLYPH_ITEM_H__ */