path: root/libs/gtkmm2/pango/pangomm/layout.h

// -*- c++ -*-
// Generated by gtkmmproc -- DO NOT MODIFY!
#ifndef _PANGOMM_LAYOUT_H
#define _PANGOMM_LAYOUT_H

#include <glibmm.h>

/* $Id$ */

/* layout.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 Library General Public
 * License as published by the Free Software Foundation; either
 * version 2 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
 * Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library General Public
 * License along with this library; if not, write to the Free
 * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 */


#include <glibmm/object.h>
#include <glibmm/slisthandle.h>
#include <pangomm/font.h>
#include <pangomm/fontdescription.h>
#include <pangomm/context.h>
#include <pangomm/attrlist.h>
#include <pangomm/tabarray.h>
#include <pangomm/layoutline.h>
#include <pangomm/layoutiter.h>
#include <pango/pango-layout.h>


#ifndef DOXYGEN_SHOULD_SKIP_THIS
typedef struct _PangoLayout PangoLayout;
typedef struct _PangoLayoutClass PangoLayoutClass;
#endif /* DOXYGEN_SHOULD_SKIP_THIS */


namespace Pango
{ class Layout_Class; } // namespace Pango
namespace Pango
{


/** @addtogroup pangommEnums Enums and Flags */

/**
 * @ingroup pangommEnums
 */
enum Alignment
{
  ALIGN_LEFT,
  ALIGN_CENTER,
  ALIGN_RIGHT
};

} // namespace Pango


#ifndef DOXYGEN_SHOULD_SKIP_THIS
namespace Glib
{

template <>
class Value<Pango::Alignment> : public Glib::Value_Enum<Pango::Alignment>
{
public:
  static GType value_type() G_GNUC_CONST;
};

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


namespace Pango
{

/**
 * @ingroup pangommEnums
 */
enum WrapMode
{
  WRAP_WORD,
  WRAP_CHAR,
  WRAP_WORD_CHAR
};

} // namespace Pango


#ifndef DOXYGEN_SHOULD_SKIP_THIS
namespace Glib
{

template <>
class Value<Pango::WrapMode> : public Glib::Value_Enum<Pango::WrapMode>
{
public:
  static GType value_type() G_GNUC_CONST;
};

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


namespace Pango
{

/**
 * @ingroup pangommEnums
 */
enum EllipsizeMode
{
  ELLIPSIZE_NONE,
  ELLIPSIZE_START,
  ELLIPSIZE_MIDDLE,
  ELLIPSIZE_END
};

} // namespace Pango


#ifndef DOXYGEN_SHOULD_SKIP_THIS
namespace Glib
{

template <>
class Value<Pango::EllipsizeMode> : public Glib::Value_Enum<Pango::EllipsizeMode>
{
public:
  static GType value_type() G_GNUC_CONST;
};

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


namespace Pango
{


/** A Pango::Layout represents an entire paragraph of text.
 * It is initialized with a Pango::Context, UTF-8 string and set of attributes for that string.
 * Once that is done, the set of formatted lines can be extracted from the object,
 * the layout can be rendered, and conversion between logical character positions
 * within the layout's text, and the physical position of the resulting glyphs can be made.
 */

class Layout : public Glib::Object
{
  
#ifndef DOXYGEN_SHOULD_SKIP_THIS

public:
  typedef Layout CppObjectType;
  typedef Layout_Class CppClassType;
  typedef PangoLayout BaseObjectType;
  typedef PangoLayoutClass BaseClassType;

private:  friend class Layout_Class;
  static CppClassType layout_class_;

private:
  // noncopyable
  Layout(const Layout&);
  Layout& operator=(const Layout&);

protected:
  explicit Layout(const Glib::ConstructParams& construct_params);
  explicit Layout(PangoLayout* castitem);

#endif /* DOXYGEN_SHOULD_SKIP_THIS */

public:
  virtual ~Layout();

#ifndef DOXYGEN_SHOULD_SKIP_THIS
  static GType get_type()      G_GNUC_CONST;
  static GType get_base_type() G_GNUC_CONST;
#endif

  ///Provides access to the underlying C GObject.
  PangoLayout*       gobj()       { return reinterpret_cast<PangoLayout*>(gobject_); }

  ///Provides access to the underlying C GObject.
  const PangoLayout* gobj() const { return reinterpret_cast<PangoLayout*>(gobject_); }

  ///Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.
  PangoLayout* gobj_copy();

private:

  
protected:
  explicit Layout(const Glib::RefPtr<Context>& context);

public:
  
  static Glib::RefPtr<Layout> create(const Glib::RefPtr<Context>& context);


  /** Does a deep copy-by-value of the @a src  layout. The attribute list,
   * tab array, and text from the original layout are all copied by
   * value.
   * @return A new Pango::Layout identical to @a src .
   */
  Glib::RefPtr<Layout> copy();
  
  /** Retrieves the Pango::Context used for this layout.
   * @return The Pango::Context for the layout. This does not
   * have an additional refcount added, so if you want to keep
   * a copy of this around, you must reference it yourself.
   */
  Glib::RefPtr<Context> get_context() const;
  
  /** Sets the text attributes for a layout object.
   * @param attrs A Pango::AttrList.
   */
  void set_attributes(AttrList& attrs);
  
  /** Gets the attribute list for the layout, if any.
   * @return A Pango::AttrList.
   */
  AttrList get_attributes() const;

  /** Set the text of the layout.
   * @param text The text for the layout.
   */
  void set_text(const Glib::ustring& text);

  
  /** Gets the text in the layout. The returned text should not
   * be freed or modified.
   * @return The text in the @a layout .
   */
  Glib::ustring get_text() const;

  /** Sets the layout text and attribute list from marked-up text (see markup format).
   * Replaces the current text and attribute list.
   * @param markup Some marked-up text.
   */
  void set_markup(const Glib::ustring& markup);

  /** Sets the layout text and attribute list from marked-up text (see markup format).
   * Replaces the current text and attribute list.
   *
   * 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, and 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 Some marked-up text.
   * @param accel_marker Marker for accelerators in the text.
   * @param accel_char Return location for any located accelerators.
   */
  void set_markup(const Glib::ustring& markup, gunichar accel_marker, gunichar& accel_char);

  
  /** Set the default font description for the layout. If no font
   * description is set on the layout, the font description from
   * the layout's context is used.
   * @param desc The new pango font description.
   */
  void set_font_description(const FontDescription& desc);
  void unset_font_description();

  
  /** Sets the width to which the lines of the Pango::Layout should be wrapped.
   * @param width The desired width, or -1 to indicate that no wrapping should be
   * performed.
   */
  void set_width(int width);
  
  /** Gets the width to which the lines of the Pango::Layout should be wrapped.
   * @return The width.
   */
  int get_width() const;
  
  /** Sets the wrap mode; the wrap mode only has an effect if a width
   * is set on the layout with pango_layout_set_width(). To turn off wrapping,
   * set the width to -1.
   * @param wrap The wrap mode.
   */
  void set_wrap(WrapMode wrap);
  
  /** Gets the wrap mode for the layout.
   * @return Active wrap mode.
   */
  WrapMode get_wrap() const;
  
  /** Sets the width in pango units to indent each paragraph. A negative value
   * of @a indent  will produce a hanging indent. That is, the first line will
   * have the full width, and subsequent lines will be indented by the
   * absolute value of @a indent .
   * @param indent The amount by which to indentset.
   */
  void set_indent(int indent);
  
  /** Gets the paragraph indent width in pango units. A negative value
   * indicates a hanging indent.
   * @return The indent.
   */
  int get_indent() const;
  
  /** Sets the amount of spacing between the lines of the layout.
   * @param spacing The amount of spacing.
   */
  void set_spacing(int spacing);
  
  /** Gets the amount of spacing between the lines of the layout.
   * @return The spacing (in Pango::GlyphUnit).
   */
  int get_spacing() const;
  
  /** Sets whether or not each complete line should be stretched to
   * fill the entire width of the layout. This stretching is typically
   * done by adding whitespace, but for some scripts (such as Arabic),
   * the justification is done by extending the characters.
   * 
   * Note that as of Pango-1.4, this functionality is not yet implemented.
   * @param justify Whether the lines in the layout should be justified.
   */
  void set_justify(bool justify = true);
  
  /** Gets whether or not each complete line should be stretched to
   * fill the entire width of the layout.
   * @return The justify.
   */
  bool get_justify() const;

  
  /** Gets whether to calculate the bidirectional base direction
   * for the layout according to the contents of the layout.
   * See pango_layout_set_auto_dir().
   * @return If <tt>true</tt>, the bidirectional base direction
   * is computed from the layout's contents.
   */
  bool get_auto_dir() const;
  
  /** Sets whether to calculate the bidirectional base direction
   * for the layout according to the contents of the layout;
   * when this flag is on (the default), then paragraphs in
   *    @a layout  that begin with strong right-to-left characters
   * (Arabic and Hebrew principally), will have right-to-left
   * layout, paragraphs with letters from other scripts will
   * have left-to-right layout. Paragraphs with only neutral
   * characters get their direction from the surrounding paragraphs.
   * 
   * When <tt>false</tt>, the choice between left-to-right and
   * right-to-left layout is done by according to the base direction
   * of the layout's Pango::Context. (See pango_context_set_base_dir()).
   * 
   * When the auto-computed direction or a paragraph differs from the
   * base direction of the context, then the interpretation of
   * Pango::ALIGN_LEFT and Pango::ALIGN_RIGHT are swapped.
   * @param auto_dir If <tt>true</tt>, compute the bidirectional base direction
   * from the layout's contents.
   */
  void set_auto_dir(bool auto_dir = true);
  
  
  /** Sets the alignment for the layout (how partial lines are
   * positioned within the horizontal space available.)
   * @param alignment The new alignment.
   */
  void set_alignment(Alignment alignment);
  
  /** Sets the alignment for the layout (how partial lines are
   * positioned within the horizontal space available.)
   * @return The alignment value.
   */
  Alignment get_alignment() const;

  
  /** Sets the tabs to use for @a layout , overriding the default tabs
   * (by default, tabs are every 8 spaces). If @a tabs  is <tt>0</tt>, the default
   * tabs are reinstated. @a tabs  is copied into the layout; you must
   * free your copy of @a tabs  yourself.
   * @param tabs A Pango::TabArray.
   */
  void set_tabs(TabArray& tabs);
  
  /** Get the current Pango::TabArray used by this layout. If no
   * Pango::TabArray has been set, then the default tabs are in use
   * and an invalid instance is returned. Default tabs are every 8 spaces.
   * @return A copy of the tabs for this layout.
   */
  TabArray get_tabs() const;

  
  /** If @a setting  is <tt>true</tt>, do not treat newlines and similar characters
   * as paragraph separators; instead, keep all text in a single paragraph,
   * and display a glyph for paragraph separator characters. Used when
   * you want to allow editing of newlines on a single text line.
   * @param setting New setting.
   */
  void set_single_paragraph_mode(bool setting = true);
  
  /** Obtains the value set by pango_layout_set_single_paragraph_mode().
   * @return <tt>true</tt> if the layout does not break paragraphs at 
   * paragraph separator characters.
   */
  bool get_single_paragraph_mode() const;

  
  /** Sets the type of ellipsization being performed for @a layout .
   * Depending on the ellipsization mode @a ellipsize  text is
   * removed from the start, middle, or end of lines so they
   * fit within the width of layout set with pango_layout_set_width().
   * 
   * If the layout contains characters such as newlines that
   * force it to be layed out in multiple lines, then each line
   * is ellipsized separately.
   * 
   * Since: 1.6
   * @param ellipsize The new ellipsization mode for @a layout .
   */
  void set_ellipsize(EllipsizeMode ellipsize);
  
  /** Gets the type of ellipsization being performed for @a layout .
   * See pango_layout_set_ellipsize()
   * @return The current ellipsization mode for @a layout 
   * 
   * Since: 1.6.
   */
  EllipsizeMode get_ellipsize() const;

  
  /** Forces recomputation of any state in the Pango::Layout 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 context_changed();

  /** Retrieve an array of logical attributes for each character in the layout.
   * @return An array of logical attributes.
   */
  Glib::ArrayHandle<LogAttr> get_log_attrs() const;

  /** Convert from an index within the layout to the onscreen position corresponding to the grapheme at that index, which is represented as rectangle.
   * Note that @a x in the returned rectangle is always the leading edge of the grapheme
   * and @a x + @a width the trailing edge of the grapheme.
   * If the directionality of the grapheme is right-to-left, then @a width will be negative.
   * @param index Byte index within layout.
   * @return The position of the grapheme.
   */
  Rectangle index_to_pos(int index) const;

  
  /** Given an index within a layout, determines the positions that of the
   * strong and weak cursors if the insertion point is at that
   * index. The position of each cursor is stored as a zero-width
   * rectangle. The strong cursor location is the location where
   * characters of the directionality equal to the base direction of the
   * layout are inserted.  The weak cursor location is the location
   * where characters of the directionality opposite to the base
   * direction of the layout are inserted.
   * @param index The byte index of the cursor.
   * @param strong_pos Location to store the strong cursor position (may be <tt>0</tt>).
   * @param weak_pos Location to store the weak cursor position (may be <tt>0</tt>).
   */
  void get_cursor_pos(int index, Rectangle& strong_pos, Rectangle& weak_pos) const;

  /** Given an index within the layout, determine the positions that of the strong cursors if the insertion point is at that index.
   * @param index The byte index of the cursor.
   * @return The strong cursor position.
   */
  Rectangle get_cursor_strong_pos(int index) const;

  /** Given an index within the layout, determine the positions that of the weak cursors if the insertion point is at that index.
   * @param index The byte index of the cursor.
   * @return The weak cursor position.
   */
  Rectangle get_cursor_weak_pos(int index) const;

  
  /** Computes a new cursor position from an old position and
   * a count of positions to move visually. If @a count  is positive,
   * then the new strong cursor position will be one position
   * to the right of the old cursor position. If @a count  is position
   * then the new strong cursor position will be one position
   * to the left of the old cursor position. 
   * 
   * In the presence of bidirection text, the correspondence
   * between logical and visual order will depend on the direction
   * of the current run, and there may be jumps when the cursor
   * is moved off of the end of a run.
   * 
   * Motion here is in cursor positions, not in characters, so a
   * single call to pango_layout_move_cursor_visually() may move the
   * cursor over multiple characters when multiple characters combine
   * to form a single grapheme.
   * @param strong Whether the moving cursor is the strong cursor or the
   * weak cursor. The strong cursor is the cursor corresponding
   * to text insertion in the base direction for the layout.
   * @param old_index The byte index of the grapheme for the old index.
   * @param old_trailing If 0, the cursor was at the trailing edge of the 
   * grapheme indicated by @a old_index , if &gt; 0, the cursor
   * was at the leading edge.
   * @param direction Direction to move cursor. A negative
   * value indicates motion to the left.
   * @param new_index Location to store the new cursor byte index. A value of -1 
   * indicates that the cursor has been moved off the beginning
   * of the layout. A value of G_MAXINT indicates that
   * the cursor has been moved off the end of the layout.
   * @param new_trailing Number of characters to move forward from the location returned
   * for @a new_index  to get the position where the cursor should
   * be displayed. This allows distinguishing the position at
   * the beginning of one line from the position at the end
   * of the preceding line. @a new_index  is always on the line
   * where the cursor should be displayed.
   */
  void move_cursor_visually(bool strong,
     int old_index, int old_trailing, int direction,
     int& new_index, int& new_trailing) const;

  
  /** Converts from X and Y position within a layout to the byte 
   * index to the character at that logical position. If the
   * Y position is not inside the layout, the closest position is chosen
   * (the position will be clamped inside the layout). If the
   * X position is not within the layout, then the start or the
   * end of the line is chosen as  described for pango_layout_x_to_index().
   * If either the X or Y positions were not inside the layout, then the
   * function returns <tt>false</tt>; on an exact hit, it returns <tt>true</tt>.
   * @param x The X offset (in Pango::GlyphUnit)
   * from the left edge of the layout.
   * @param y The Y offset (in Pango::GlyphUnit)
   * from the top edge of the layout.
   * @param index Location to store calculated byte index.
   * @param trailing Location to store a integer indicating where
   * in the grapheme the user clicked. It will either
   * be zero, or the number of characters in the
   * grapheme. 0 represents the trailing edge of the grapheme.
   * @return <tt>true</tt> if the coordinates were inside text.
   */
  bool xy_to_index(int x, int y, int& index, int& trailing) const;

  
  /** Compute the logical and ink extents of @a layout . Logical extents
   * are usually what you want for positioning things. The extents
   * are given in layout coordinates; layout coordinates begin at the
   * top left corner of the layout.
   * @param ink_rect Rectangle used to store the extents of the layout as drawn.
   * @param logical_rect Rectangle used to store the logical extents of the layout.
   */
  void get_extents(Rectangle& ink_rect, Rectangle& logical_rect) const;

  /** Compute the ink extents of layout.
   * @return The extents of the layout as drawn.
   */
  Rectangle get_ink_extents() const;

  /** Compute the logical extents of layout.
   * @return The logical extents of the layout.
   */
  Rectangle get_logical_extents() const;

  
  /** Compute the logical and ink extents of @a layout  in device units.
   * See pango_layout_get_extents(); this function just calls
   * pango_layout_get_extents() and then converts the extents to
   * pixels using the Pango::SCALE factor.
   * @param ink_rect Rectangle used to store the extents of the layout as drawn.
   * @param logical_rect Rectangle used to store the logical extents of the
   * layout.
   */
  void get_pixel_extents(Rectangle& ink_rect, Rectangle& logical_rect) const;

  /** Compute the ink extents of the layout in device units.
   * @return The extents of the layout as drawn.
   */
  Rectangle get_pixel_ink_extents() const;

  /** Compute the logical extents of the layout in device units.
   * @return The logical extents of the layout.
   */
  Rectangle get_pixel_logical_extents() const;

  
  /** Determines the logical width and height of a Pango::Layout
   * in Pango units. (device units divided by Pango::SCALE). This
   * is simply a convenience function around pango_layout_get_extents().
   * @param width Location to store the logical width, or <tt>0</tt>.
   * @param height Location to store the logical height, or <tt>0</tt>.
   */
  void get_size(int& width, int& height) const;
  
  /** Determines the logical width and height of a Pango::Layout
   * in device units. (pango_layout_get_size() returns the width
   * and height in thousandths of a device unit.) This
   * is simply a convenience function around pango_layout_get_extents().
   * @param width Location to store the logical width, or <tt>0</tt>.
   * @param height Location to store the logical height, or <tt>0</tt>.
   */
  void get_pixel_size(int& width, int& height) const;

  
  /** Retrieves the count of lines for the @a layout .
   * @return The line count.
   */
  int get_line_count() const;
  
  
  /** Retrieves a particular line from a Pango::Layout.
   * @param line The index of a line, which must be between 0 and
   * <tt>pango_layout_get_line_count(layout) - 1</tt>, inclusive.
   * @return The requested Pango::LayoutLine, or <tt>0</tt> 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 Pango::Layout.
   */
  Glib::RefPtr<LayoutLine> get_line(int line);
  
  /** Retrieves a particular line from a Pango::Layout.
   * @param line The index of a line, which must be between 0 and
   * <tt>pango_layout_get_line_count(layout) - 1</tt>, inclusive.
   * @return The requested Pango::LayoutLine, or <tt>0</tt> 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 Pango::Layout.
   */
  Glib::RefPtr<const LayoutLine> get_line(int line) const;
  
  
  /** Returns the lines of the @a layout  as a list.
   * @return A G::SList containing the lines in the layout. This
   * points to internal data of the Pango::Layout and must be used with
   * care. It will become invalid on any change to the layout's
   * text or properties.
   */
  SListHandle_LayoutLine get_lines();
  
  /** Returns the lines of the @a layout  as a list.
   * @return A G::SList containing the lines in the layout. This
   * points to internal data of the Pango::Layout and must be used with
   * care. It will become invalid on any change to the layout's
   * text or properties.
   */
  SListHandle_ConstLayoutLine get_lines() const;
  
  /** Gets an iterator to iterate over the visual extents of the layout.
   * @param iter Location to store the iterator.
   */
  void get_iter(LayoutIter& iter);


public:

public:
  //C++ methods used to invoke GTK+ virtual functions:

protected:
  //GTK+ Virtual Functions (override these to change behaviour):

  //Default Signal Handlers::


};

} /* namespace Pango */


namespace Glib
{
  /** @relates Pango::Layout
   * @param object The C instance
   * @param take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref.
   * @result A C++ instance that wraps this C instance.
   */
  Glib::RefPtr<Pango::Layout> wrap(PangoLayout* object, bool take_copy = false);
}


#endif /* _PANGOMM_LAYOUT_H */