/* $Id: text.hg,v 1.7 2005/01/05 18:21:30 murrayc Exp $ */

/* Copyright (C) 2002 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, see <https://www.gnu.org/licenses/>.
 */

_DEFS(atkmm,atk)

#include <atkmm/component.h> /* for Atk::CoordType */
#include <glibmm/slisthandle.h>
#include <atk/atktext.h>


namespace Atk
{

class ATKMM_API Attribute
{
  _CLASS_GENERIC(Attribute, AtkAttribute)

public:
  Attribute();
  Attribute(const Glib::ustring& name, const Glib::ustring& value);
  explicit Attribute(const AtkAttribute* gobject);
  ~Attribute();

  Attribute(const Attribute& other);
  Attribute& operator=(const Attribute& other);

  void swap(Attribute& other);

  _MEMBER_GET(name, name, Glib::ustring, const char*)
  _MEMBER_GET(value, value, Glib::ustring, const char*)

  /// Provides access to the underlying C GObject.
  AtkAttribute*       gobj()       { return &gobject_; }

  /// Provides access to the underlying C GObject.
  const AtkAttribute* gobj() const { return &gobject_; }

protected:
  AtkAttribute gobject_;
};

/** @relates Atk::Attribute */
inline void swap(Attribute& lhs, Attribute& rhs)
  { lhs.swap(rhs); }

struct AttributeTraits
{
  typedef Atk::Attribute      CppType;
  typedef const AtkAttribute* CType;
  typedef AtkAttribute*       CTypeNonConst;

  static CType to_c_type(CType item)          { return item; }
  static CType to_c_type(const CppType& item) { return item.gobj(); }
  static CppType to_cpp_type(CType item)      { return CppType(item); }
  static void release_c_type(CType item)      { g_free(const_cast<CTypeNonConst>(item)); }
};

typedef Glib::SListHandle<Attribute, AttributeTraits> AttributeSet;


_CC_INCLUDE(atk/atk-enum-types.h)
_WRAP_ENUM(BuiltinTextAttribute, AtkTextAttribute, decl_prefix ATKMM_API)

class ATKMM_API TextAttribute
{
private:
  int attribute_;

public:
  TextAttribute() : attribute_ (0) {}
  TextAttribute(BuiltinTextAttribute attribute) : attribute_ (attribute) {}

  // Behave like an ordinary enum.
  explicit TextAttribute(int attribute) : attribute_ (attribute) {}
  operator int() const { return attribute_; }

  static TextAttribute for_name(const Glib::ustring& name);
  static Glib::ustring get_name(TextAttribute attribute);
  static Glib::ustring get_value(TextAttribute attribute, int index);
};

} // namespace Atk

#ifndef DOXYGEN_SHOULD_SKIP_THIS
namespace Glib
{

template <>
class ATKMM_API Value<Atk::TextAttribute> : public Glib::Value_Enum<Atk::TextAttribute>
{
public:
  static GType value_type() G_GNUC_CONST;
};

} // namespace Glib
#endif /* DOXYGEN_SHOULD_SKIP_THIS */

namespace Atk
{

_WRAP_ENUM(TextBoundary, AtkTextBoundary, decl_prefix ATKMM_API)
_WRAP_ENUM(TextClipType, AtkTextClipType, decl_prefix ATKMM_API)
_WRAP_ENUM(TextGranularity, AtkTextGranularity, decl_prefix ATKMM_API)

/** The ATK interface implemented by components with text content.
 * This should be implemented by Atk::Objects on behalf of widgets that have text content which is either attributed
 * or otherwise non-trivial. Atk::Objects whose text content is simple, unattributed, and very brief may expose that
 * content via Atk::Object::get_name() instead; however if the text is editable, multi-line, typically longer than
 * three or four words, attributed, selectable, or if the object already uses the 'name' ATK property for other
 * information, this Text interface should be used to expose the text content. In the case of editable text content,
 * Atk::EditableText (a subtype of the Atk::Text interface) should be implemented instead.
 *
 * Atk::Text provides not only traversal facilities and change notification for text content, but also caret tracking
 * and glyph bounding box calculations. Note that the text strings are exposed as UTF-8, and are therefore potentially
 * multi-byte, and caret-to-byte offset mapping makes no assumptions about the character length; also bounding box
 * glyph-to-offset mapping may be complex for languages which use ligatures.
 */
class ATKMM_API Text : public Glib::Interface
{
  _CLASS_INTERFACE(Text, AtkText, ATK_TEXT, AtkTextIface, , , ATKMM_API)

public:
  _WRAP_METHOD(Glib::ustring get_text(int start_offset, int end_offset) const, atk_text_get_text)
  _WRAP_METHOD(gunichar get_character_at_offset(int offset) const, atk_text_get_character_at_offset)
  _WRAP_METHOD(Glib::ustring get_text_after_offset(int offset, TextBoundary boundary_type, int& start_offset, int& end_offset) const, atk_text_get_text_after_offset, deprecated "Use get_string_at_offset() instead.")
  _WRAP_METHOD(Glib::ustring get_text_at_offset(int offset, TextBoundary boundary_type, int& start_offset, int& end_offset) const, atk_text_get_text_at_offset, deprecated "Use get_string_at_offset() instead.")
  _WRAP_METHOD(Glib::ustring get_text_before_offset(int offset, TextBoundary boundary_type, int& start_offset, int& end_offset) const, atk_text_get_text_before_offset, deprecated "Use get_string_at_offset() instead.")

  _WRAP_METHOD(Glib::ustring get_string_at_offset(int offset, TextGranularity granularity, int& start_offset, int& end_offset), atk_text_get_string_at_offset)

  _WRAP_METHOD(int get_caret_offset() const, atk_text_get_caret_offset)
  _WRAP_METHOD(void get_character_extents(int offset, int& x, int& y, int& width, int& height, CoordType coords) const, atk_text_get_character_extents)
  _WRAP_METHOD(AttributeSet get_run_attributes(int offset, int& start_offset, int& end_offset) const, atk_text_get_run_attributes)
  _WRAP_METHOD(AttributeSet get_default_attributes() const, atk_text_get_default_attributes)
  _WRAP_METHOD(int get_character_count() const, atk_text_get_character_count)
  _WRAP_METHOD(int get_offset_at_point(int x, int y, CoordType coords) const, atk_text_get_offset_at_point)
  _WRAP_METHOD(int get_n_selections() const, atk_text_get_n_selections)
  _WRAP_METHOD(Glib::ustring get_selection(int selection_num, int& start_offset, int& end_offset) const, atk_text_get_selection)
  _WRAP_METHOD(bool add_selection(int start_offset, int end_offset), atk_text_add_selection)
  _WRAP_METHOD(bool remove_selection(int selection_num), atk_text_remove_selection)
  _WRAP_METHOD(bool set_selection(int selection_num, int start_offset, int end_offset), atk_text_set_selection)
  _WRAP_METHOD(bool set_caret_offset(int offset), atk_text_set_caret_offset)
  
  typedef AtkTextRectangle Rectangle;
    
  _WRAP_METHOD(void get_range_extents(int start_offset, int end_offset,
                                      CoordType coord_type,
                                      Rectangle& rect), atk_text_get_range_extents)
  _WRAP_METHOD(AtkTextRange** get_bounded_ranges(const Rectangle& rect, CoordType coord_type,
                                                 TextClipType x_clip_type, TextClipType y_clip_type), atk_text_get_bounded_ranges)
                                                           

  _WRAP_SIGNAL(void text_changed(int position, int length), "text_changed")
  _WRAP_SIGNAL(void text_caret_moved(int location), "text_caret_moved")
  _WRAP_SIGNAL(void text_selection_changed(), "text_selection_changed")
  _WRAP_SIGNAL(void text_attributes_changed(), "text_attributes_changed")

protected:
#m4 _CONVERSION(`Glib::ustring', `gchar*', `g_strdup(($3).c_str())')
#m4 _CONVERSION(`gchar*', `Glib::ustring', `Glib::convert_return_gchar_ptr_to_ustring($3)')
  _WRAP_VFUNC(Glib::ustring get_text(int start_offset, int end_offset) const, get_text)
  _WRAP_VFUNC(gunichar get_character_at_offset(int offset) const, get_character_at_offset)

  /** @deprecated This virtual function is deprecated and it should not be overridden.
   */
  _WRAP_VFUNC(Glib::ustring get_text_after_offset(int offset, TextBoundary boundary_type, int& start_offset, int& end_offset) const, get_text_after_offset)

  _WRAP_VFUNC(Glib::ustring get_text_at_offset(int offset, TextBoundary boundary_type, int& start_offset, int& end_offset) const, get_text_at_offset)

  /** @deprecated This virtual function is deprecated and it should not be overridden.
   */
  _WRAP_VFUNC(Glib::ustring get_text_before_offset(int offset, TextBoundary boundary_type, int& start_offset, int& end_offset) const, get_text_before_offset)

  _WRAP_VFUNC(int get_caret_offset() const, get_caret_offset)
  _WRAP_VFUNC(void get_character_extents(int offset, int& x, int& y, int& width, int& height, CoordType coords) const, get_character_extents)
  _WRAP_VFUNC(AtkAttributeSet* get_run_attributes(int offset, int& start_offset, int& end_offset) const, get_run_attributes)
  _WRAP_VFUNC(AtkAttributeSet* get_default_attributes() const, get_default_attributes)
  _WRAP_VFUNC(int get_character_count() const, get_character_count)
  _WRAP_VFUNC(int get_offset_at_point(int x, int y, CoordType coords) const, get_offset_at_point)
  _WRAP_VFUNC(int get_n_selections() const, get_n_selections)
  _WRAP_VFUNC(Glib::ustring get_selection(int selection_num, int& start_offset, int& end_offset) const, get_selection)
  _WRAP_VFUNC(bool add_selection(int start_offset, int end_offset), add_selection)
  _WRAP_VFUNC(bool remove_selection(int selection_num), remove_selection)
  _WRAP_VFUNC(bool set_selection(int selection_num, int start_offset, int end_offset), set_selection)
  _WRAP_VFUNC(bool set_caret_offset(int offset), set_caret_offset)
  
  //TODO: Add get_range_extents(), and get_bounded_ranges() vfuncs when we can break ABI.
};

} // namespace Atk
