/*
 * Copyright (C) Birb Developers
 *
 * Birb is the legal property of its developers, whose names are too numerous
 * to list here. Please refer to the AUTHORS file distributed with this source
 * distribution
 *
 * 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/>.
 */

#if !defined(BIRB_GLOBAL_HEADER_INSIDE) && !defined(BIRB_COMPILATION)
# error "only <birb.h> may be included directly"
#endif

#ifndef BIRB_PANGO_FORMATTER_H
#define BIRB_PANGO_FORMATTER_H

#include <glib.h>
#include <glib-object.h>

#include <pango/pango.h>

#include "birbversion.h"

G_BEGIN_DECLS

#define BIRB_TYPE_PANGO_FORMATTER (birb_pango_formatter_get_type())

/**
 * BirbPangoFormatter:
 *
 * A helper class for writing out [type@Pango.AttrList] formatted strings.
 *
 * [method@PangoFormatter.format] will process a plain text string with a
 * [struct@Pango.AttrList] and call the appropriate virtual functions when
 * necessary.
 *
 * When formatting is started [vfunc@PangoFormatter.start] will always be
 * called.
 *
 * When an attribute is starting, [vfunc@PangoFormatter.attribute_start] will
 * be called to tell the formatter as such. Likewise,
 * [vfunc@PangoFormatter.attribute_end] will be called when the attribute is
 * ending.
 *
 * [vfunc@PangoFormatter.text] will be called for all text which will be
 * dispersed between calls turning attributes on and off.
 *
 * Finally once all text and attributes have been processed,
 * [vfunc@PangoFormatter.finish] will be called to get the resulting
 * formatted string.
 *
 * Here is a simple example of how this would work with a string like
 * `foo <b>bar</b> baz`.
 *
 * * [vfunc@PangoFormatter.start] is called
 * * [vfunc@PangoFormatter.text] is called with `"foo "` as the text parameter.
 * * [vfunc@PangoFormatter.attribute_start] is called with the
 *   [struct@Pango.Attribute] for the weight.
 * * [vfunc@PangoFormatter.text] is called with `"bar"` as the text parameter.
 * * [vfunc@PangoFormatter.attribute_end] is called with the
 *   [struct@Pango.Attribute] for the weight.
 * * [vfunc@PangoFormatter.text] is called with `" baz"` as the text parameter.
 * * [vfunc@PangoFormatter.finish] is called
 *
 * Since: 0.6
 */
BIRB_AVAILABLE_IN_0_6
G_DECLARE_DERIVABLE_TYPE(BirbPangoFormatter, birb_pango_formatter, BIRB,
                         PANGO_FORMATTER, GObject)

struct _BirbPangoFormatterClass {
	GObjectClass parent;

	/**
	 * BirbPangoFormatterClass::start:
	 *
	 * Called when [method@PangoFormatter.format] was called to initialize the
	 * formatter.
	 *
	 * Since: 0.6
	 */
	void (*start)(BirbPangoFormatter *formatter);

	/**
	 * BirbPangoFormatterClass::attribute_start:
	 * @attribute: the attribute
	 *
	 * Called when an attribute is being started.
	 *
	 * Since: 0.6
	 */
	void (*attribute_start)(BirbPangoFormatter *formatter, PangoAttribute *attribute);

	/**
	 * BirbPangoFormatterClass::attribute_end:
	 * @attribute: the attribute
	 *
	 * Called when an attribute is being finished.
	 *
	 * Since: 0.6
	 */
	void (*attribute_end)(BirbPangoFormatter *formatter, PangoAttribute *attribute);

	/**
	 * BirbPangoFormatterClass::text:
	 * @text: the text
	 *
	 * Called when there is text to insert.
	 *
	 * Since: 0.6
	 */
	void (*text)(BirbPangoFormatter *formatter, const char *text);

	/**
	 * BirbPangoFormatterClass::finish:
	 *
	 * Called when there is no more text or attributes to get the results of
	 * the formatting.
	 *
	 * Returns: (transfer full) (nullable): The formatted string.
	 *
	 * Since: 0.6
	 */
	char *(*finish)(BirbPangoFormatter *formatter);

	gpointer reserved[8];
};

/**
 * birb_pango_formatter_format:
 * @plain_text: the text to format
 * @attrs: the pango attr list
 *
 * Formats the given text with the given attributes.
 *
 * Returns: (transfer full): The formatted text.
 *
 * Since: 0.6
 */
BIRB_AVAILABLE_IN_0_6
char *birb_pango_formatter_format(BirbPangoFormatter *formatter, const char *plain_text, PangoAttrList *attrs);

G_END_DECLS

#endif /* BIRB_PANGO_FORMATTER_H */
