/* $Id: attrlist.hg,v 1.4 2005/11/22 15:00:17 murrayc Exp $ */

/* attrlist.h
 *
 * Copyright (C) 1998-1999 The gtkmm Development Team
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * 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., 675 Mass Ave, Cambridge, MA 02139, USA.
 */

#include <pangomm/attributes.h>
#include <pangomm/attriter.h>

_DEFS(pangomm,pango)

namespace Pango
{

/** A Pango::AttrList represents a list of attributes that apply to a section of text.
 * The attributes are, in general, allowed to overlap in an arbitrary fashion, however,
 * if the attributes are manipulated only through Pango::AttrList::change(), the overlap between properties will meet stricter criteria.
 *
 * Since the Pango::AttrList structure is stored as a linear list, it is not suitable for storing attributes for large amounts of text.
 * In general, you should not use a single Pango::AttrList for more than one paragraph of text.
 *
 * When obtaining an AttrList, you should check that it is valid. For instance, if(attrlist).
 */
class AttrList
{
  _CLASS_BOXEDTYPE(AttrList, PangoAttrList, pango_attr_list_new, pango_attr_list_copy, pango_attr_list_unref)
  _IGNORE(pango_attr_list_copy, pango_attr_list_ref, pango_attr_list_unref)
public:
  /** Constructs an attribute list by parsing a marked-up text (see markup format).
   * If @a accel_marker is nonzero, the given character will mark the character
   * following it as an accelerator. For example, the accel marker might be an
   * ampersand or underscore. All characters marked as an accelerator will receive
   * a Pango::UNDERLINE_LOW attribute.
   * Two @a accel_marker characters following each other
   * produce a single literal @a accel_marker character.
   *
   * @param markup_text Markup to parse (see markup format).
   * @param accel_marker Character that precedes an accelerator, or <tt>0</tt> for none.
   */
  explicit AttrList(const Glib::ustring& markup_text, gunichar accel_marker=0);

  /** Constructs an attribute list by parsing a marked-up text (see markup format).
   * @a text is set to the plaintext string.
   * If @a accel_marker is nonzero, the given character will mark the character 
   * following it as an accelerator. For example, the accel marker might be an 
   * ampersand or underscore. All characters marked as an accelerator will receive
   * a Pango::UNDERLINE_LOW attribute. The first character so marked will be 
   * returned in @a accel_char. Two @a accel_marker characters following each other 
   * produce a single literal @a accel_marker character.
   *
   * @param markup_text Markup to parse (see markup format).
   * @param accel_marker Character that precedes an accelerator, or <tt>0</tt> for none.
   * @param text Return location for text with tags stripped.
   * @param accel_char Return location for accelerator char.
   */
  AttrList(const Glib::ustring& markup_text, gunichar accel_marker, Glib::ustring& text, gunichar& accel_char);

  _DEPRECATE_IFDEF_START
  ///@deprecated Use the const version
  explicit operator bool();
  _DEPRECATE_IFDEF_END

  ///Tests whether the AttrList is valid.
  explicit operator bool() const;

  void insert(Attribute& attr);
  _IGNORE(pango_attr_list_insert) // hand code because we need to pass a copy of the attribute
  void insert_before(Attribute& attr);
  _IGNORE(pango_attr_list_insert_before) // hand code because we need to pass a copy of the attribute
  void change(Attribute& attr);
  _IGNORE(pango_attr_list_change) // hand code because we need to pass a copy of the attribute
  _WRAP_METHOD(void splice(AttrList& other, int pos, int len), pango_attr_list_splice)
  _WRAP_METHOD(AttrIter get_iter(), pango_attr_list_get_iterator)

  //TODO: Though it doesn't seem important:
  //PangoAttrList* pango_attr_list_filter (PangoAttrList* list, PangoAttrFilterFunc  func, gpointer             data)
};

} //namespace Pango