pango-layout.c

Pango is a library for layout and rendering of text, with an emphasis on internationalization. Pang

{
  g_return_val_if_fail (layout != NULL, FALSE);

  pango_layout_check_lines (layout);

  return layout->is_ellipsized;
}

/**
 * pango_layout_set_text:
 * @layout: a #PangoLayout
 * @text: a valid UTF-8 string
 * @length: maximum length of @text, in bytes. -1 indicates that
 *          the string is nul-terminated and the length should be
 *          calculated.  The text will also be truncated on
 *          encountering a nul-termination even when @length is
 *          positive.
 *
 * Sets the text of the layout.
 *
 * Note that if you have used
 * pango_layout_set_markup() or pango_layout_set_markup_with_accel() on
 * @layout before, you may want to call pango_layout_set_attributes() to clear
 * the attributes set on the layout from the markup as this function does not
 * clear attributes.
 **/
void
pango_layout_set_text (PangoLayout *layout,
		       const char  *text,
		       int          length)
{
  char *old_text, *start, *end;

  g_return_if_fail (layout != NULL);
  g_return_if_fail (length == 0 || text != NULL);

  old_text = layout->text;

  if (length < 0)
    layout->text = g_strdup (text);
  else if (length > 0)
    /* This is not exactly what we want.  We don't need the padding...
     */
    layout->text = g_strndup (text, length);
  else
    layout->text = g_malloc0 (1);

  layout->length = strlen (layout->text);

  /* validate it, and replace invalid bytes with '?'
   */
  start = layout->text;
  for (;;) {
    gboolean valid;

    valid = g_utf8_validate (start, -1, (const char **)&end);

    if (!*end)
      break;

    /* Replace invalid bytes with -1.  The -1 will be converted to
     * ((gunichar) -1) by glib, and that in turn yields a glyph value of
     * ((PangoGlyph) -1) by PANGO_GET_UNKNOWN_GLYPH(-1),
     * and that's PANGO_GLYPH_INVALID_INPUT.
     */
    if (!valid)
      *end++ = -1;

    start = end;
  }

  if (start != layout->text)
    /* TODO: Write out the beginning excerpt of text? */
    g_warning ("Invalid UTF-8 string passed to pango_layout_set_text()");

  layout->n_chars = g_utf8_strlen (layout->text, -1);

  pango_layout_clear_lines (layout);

  g_free (old_text);
}

/**
 * pango_layout_get_text:
 * @layout: a #PangoLayout
 *
 * Gets the text in the layout. The returned text should not
 * be freed or modified.
 *
 * Return value: the text in the @layout.
 **/
G_CONST_RETURN char*
pango_layout_get_text (PangoLayout *layout)
{
  g_return_val_if_fail (PANGO_IS_LAYOUT (layout), NULL);

  return layout->text;
}

/**
 * pango_layout_set_markup:
 * @layout: a #PangoLayout
 * @markup: marked-up text
 * @length: length of marked-up text in bytes, or -1 if @markup is
 * nul-terminated
 *
 * Same as pango_layout_set_markup_with_accel(), but
 * the markup text isn't scanned for accelerators.
 *
 **/
void
pango_layout_set_markup (PangoLayout *layout,
			 const char  *markup,
			 int          length)
{
  pango_layout_set_markup_with_accel (layout, markup, length, 0, NULL);
}

/**
 * pango_layout_set_markup_with_accel:
 * @layout: a #PangoLayout
 * @markup: marked-up text
 * (see <link linkend="PangoMarkupFormat">markup format</link>)
 * @length: length of marked-up text in bytes, or -1 if @markup is
 * nul-terminated
 * @accel_marker: marker for accelerators in the text
 * @accel_char: return location for first located accelerator, or %NULL
 *
 * Sets the layout text and attribute list from marked-up text (see
 * <link linkend="PangoMarkupFormat">markup format</link>). Replaces
 * the current text and attribute list.
 *
 * If @accel_marker is nonzero, the given character will mark the
 * character following it as an accelerator. For example, @accel_marker
 * might be an ampersand or underscore. All characters marked
 * as an accelerator will receive a %PANGO_UNDERLINE_LOW attribute,
 * and the first character so marked will be returned in @accel_char.
 * Two @accel_marker characters following each other produce a single
 * literal @accel_marker character.
 **/
void
pango_layout_set_markup_with_accel (PangoLayout    *layout,
				    const char     *markup,
				    int             length,
				    gunichar        accel_marker,
				    gunichar       *accel_char)
{
  PangoAttrList *list = NULL;
  char *text = NULL;
  GError *error;

  g_return_if_fail (PANGO_IS_LAYOUT (layout));
  g_return_if_fail (markup != NULL);

  error = NULL;
  if (!pango_parse_markup (markup, length,
			   accel_marker,
			   &list, &text,
			   accel_char,
			   &error))
    {
      g_warning ("pango_layout_set_markup_with_accel: %s", error->message);
      g_error_free (error);
      return;
    }

  pango_layout_set_text (layout, text, -1);
  pango_layout_set_attributes (layout, list);
  pango_attr_list_unref (list);
  g_free (text);
}

/**
 * pango_layout_get_unknown_glyphs_count:
 * @layout: a #PangoLayout
 *
 * Counts the number unknown glyphs in @layout.  That is, zero if
 * glyphs for all characters in the layout text were found, or more
 * than zero otherwise.
 *
 * This function can be used to determine if there are any fonts
 * available to render all characters in a certain string, or when
 * used in combination with %PANGO_ATTR_FALLBACK, to check if a
 * certain font supports all the characters in the string.
 *
 * Return value: The number of unknown glyphs in @layout.
 *
 * Since: 1.16
 */
int
pango_layout_get_unknown_glyphs_count (PangoLayout *layout)
{
    PangoLayoutLine *line;
    PangoLayoutRun *run;
    GSList *lines_list;
    GSList *runs_list;
    int i, count = 0;

    g_return_val_if_fail (PANGO_IS_LAYOUT (layout), 0);

    pango_layout_check_lines (layout);

    if (layout->unknown_glyphs_count >= 0)
      return layout->unknown_glyphs_count;

    lines_list = layout->lines;
    while (lines_list)
      {
	line = lines_list->data;
	runs_list = line->runs;

	while (runs_list)
	  {
	    run = runs_list->data;

	    for (i = 0; i < run->glyphs->num_glyphs; i++)
	      {
		if (run->glyphs->glyphs[i].glyph & PANGO_GLYPH_UNKNOWN_FLAG)
		    count++;
	      }

	    runs_list = runs_list->next;
	  }
	lines_list = lines_list->next;
      }

    layout->unknown_glyphs_count = count;
    return count;
}

/**
 * pango_layout_context_changed:
 * @layout: a #PangoLayout
 *
 * Forces recomputation of any state in the #PangoLayout that
 * might depend on the layout's context. This function should
 * be called if you make changes to the context subsequent
 * to creating the layout.
 **/
void
pango_layout_context_changed (PangoLayout *layout)
{
  pango_layout_clear_lines (layout);
  layout->tab_width = -1;
}

/**
 * pango_layout_get_log_attrs:
 * @layout: a #PangoLayout
 * @attrs: location to store a pointer to an array of logical attributes
 *         This value must be freed with g_free().
 * @n_attrs: location to store the number of the attributes in the
 *           array. (The stored value will be one more than the total number
 *           of characters in the layout, since there need to be attributes
 *           corresponding to both the position before the first character
 *           and the position after the last character.)
 *
 * Retrieves an array of logical attributes for each character in
 * the @layout.
 **/
void
pango_layout_get_log_attrs (PangoLayout    *layout,
			    PangoLogAttr  **attrs,
			    gint           *n_attrs)
{
  g_return_if_fail (layout != NULL);

  pango_layout_check_lines (layout);

  if (attrs)
    {
      *attrs = g_new (PangoLogAttr, layout->n_chars + 1);
      memcpy (*attrs, layout->log_attrs, sizeof(PangoLogAttr) * (layout->n_chars + 1));
    }

  if (n_attrs)
    *n_attrs = layout->n_chars + 1;
}


/**
 * pango_layout_get_line_count:
 * @layout: #PangoLayout
 *
 * Retrieves the count of lines for the @layout.
 *
 * Return value: the line count.
 **/
int
pango_layout_get_line_count (PangoLayout   *layout)
{
  g_return_val_if_fail (layout != NULL, 0);

  pango_layout_check_lines (layout);
  return g_slist_length (layout->lines);
}

/**
 * pango_layout_get_lines:
 * @layout: a #PangoLayout
 *
 * Returns the lines of the @layout as a list.
 *
 * Use the faster pango_layout_get_lines_readonly() if you do not plan
 * to modify the contents of the lines (glyphs, glyph widths, etc.).
 *
 * Return value: a #GSList containing the lines in the layout. This
 * points to internal data of the #PangoLayout and must be used with
 * care. It will become invalid on any change to the layout's
 * text or properties.
 **/
GSList *
pango_layout_get_lines (PangoLayout *layout)
{
  pango_layout_check_lines (layout);

  if (layout->lines)
    {
      GSList *tmp_list = layout->lines;
      while (tmp_list)
	{
	  PangoLayoutLine *line = tmp_list->data;
	  tmp_list = tmp_list->next;

	  pango_layout_line_leaked (line);
	}
    }

  return layout->lines;
}

/**
 * pango_layout_get_lines_readonly:
 * @layout: a #PangoLayout
 *
 * Returns the lines of the @layout as a list.
 *
 * This is a faster alternative to pango_layout_get_lines(),
 * but the user is not expected
 * to modify the contents of the lines (glyphs, glyph widths, etc.).
 *
 * Return value: a #GSList containing the lines in the layout. This
 * points to internal data of the #PangoLayout and must be used with
 * care. It will become invalid on any change to the layout's
 * text or properties.  No changes should be made to the lines.
 *
 * Since: 1.16
 **/
GSList *
pango_layout_get_lines_readonly (PangoLayout *layout)
{
  pango_layout_check_lines (layout);

  return layout->lines;
}

/**
 * pango_layout_get_line:
 * @layout: a #PangoLayout
 * @line: the index of a line, which must be between 0 and
 *        <literal>pango_layout_get_line_count(layout) - 1</literal>, inclusive.
 *
 * Retrieves a particular line from a #PangoLayout.
 *
 * Use the faster pango_layout_get_line_readonly() if you do not plan
 * to modify the contents of the line (glyphs, glyph widths, etc.).
 *
 * Return value: the requested #PangoLayoutLine, or %NULL if the
 *               index is out of range. This layout line can
 *               be ref'ed and retained, but will become invalid
 *               if changes are made to the #PangoLayout.
 **/
PangoLayoutLine *
pango_layout_get_line (PangoLayout *layout,
		       int          line)
{
  GSList *list_item;
  g_return_val_if_fail (layout != NULL, NULL);
  g_return_val_if_fail (line >= 0, NULL);

  if (line < 0)
    return NULL;

  pango_layout_check_lines (layout);

  list_item = g_slist_nth (layout->lines, line);

  if (list_item)
    {
      PangoLayoutLine *line = list_item->data;

      pango_layout_line_leaked (line);
      return line;
    }

  return NULL;
}

/**
 * pango_layout_get_line_readonly:
 * @layout: a #PangoLayout
 * @line: the index of a line, which must be between 0 and
 *        <literal>pango_layout_get_line_count(layout) - 1</literal>, inclusive.
 *
 * Retrieves a particular line from a #PangoLayout.
 *
 * This is a faster alternative to pango_layout_get_line(),
 * but the user is not expected
 * to modify the contents of the line (glyphs, glyph widths, etc.).
 *
 * Return value: the requested #PangoLayoutLine, or %NULL if the
 *               index is out of range. This layout line can
 *               be ref'ed and retained, but will become invalid
 *               if changes are made to the #PangoLayout.
 *               No changes should be made to the line.
 *
 * Since: 1.16
 **/
PangoLayoutLine *
pango_layout_get_line_readonly (PangoLayout *layout,
				int          line)
{
  GSList *list_item;
  g_return_val_if_fail (layout != NULL, NULL);
  g_return_val_if_fail (line >= 0, NULL);

  if (line < 0)
    return NULL;

  pango_layout_check_lines (layout);

  list_item = g_slist_nth (layout->lines, line);

  if (list_item)
    {
      PangoLayoutLine *line = list_item->data;
      return line;
    }

  return NULL;
}

/**
 * pango_layout_line_index_to_x:
 * @line:     a #PangoLayoutLine
 * @index_:   byte offset of a grapheme within the layout
 * @trailing: an integer indicating the edge of the grapheme to retrieve
 *            the position of. If > 0, the trailing edge of the grapheme,
 *            if 0, the leading of the grapheme.
 * @x_pos: location to store the x_offset (in Pango unit)
 *
 * Converts an index within a line to a X position.
 *
 **/
void
pango_layout_line_index_to_x (PangoLayoutLine  *line,
			      int               index,
			      int               trailing,
			      int              *x_pos)
{
  PangoLayout *layout = line->layout;
  GSList *run_list = line->runs;
  int width = 0;

  while (run_list)
    {
      PangoLayoutRun *run = run_list->data;
      ItemProperties properties;

      pango_layout_get_item_properties (run->item, &properties);

      if (run->item->offset <= index && run->item->offset + run->item->length > index)
	{
	  int offset = g_utf8_pointer_to_offset (layout->text, layout->text + index);
	  if (trailing)
	    {
	      while (index < line->start_index + line->length &&
		     offset + 1 < layout->n_chars &&
		     !layout->log_attrs[offset + 1].is_cursor_position)
		{
		  offset++;
		  index = g_utf8_next_char (layout->text + index) - layout->text;
		}
	    }
	  else
	    {
	      while (index > line->start_index &&
		     !layout->log_attrs[offset].is_cursor_position)
		{
		  offset--;
		  index = g_utf8_prev_char (layout->text + index) - layout->text;
		}