JustUI/include/justui/jlabel.h

//---
// JustUI.jlabel: Simple one-line or multi-line text label without formatting
//---

#ifndef _J_JLABEL
#define _J_JLABEL

#include <justui/defs.h>
#include <justui/jwidget.h>
#include <justui/p/vec.h>

#include <gint/display.h>

/* jlabel_wrapmode: Text wrapping options */
typedef enum jwrapmode {
	/* Wrap only at \n characters */
	J_WRAP_NONE,
	/* Break only at spaces; if a word is longer than a full line, breaking in
	   that word is allowed */
	J_WRAP_WORD,
	/* Break only at spaces and tabs, even if a word is longer than a line */
	J_WRAP_WORD_ONLY,
	/* Break at any letter */
	J_WRAP_LETTER,

} __attribute__((packed)) jwrapmode;

/* jlabel: One-line or multi-line piece of text, without formatting.

   This widget is used for mundane text printing. All the text in the label is
   printed with a single font. The text can be aligned horizontally and
   vertically within the widget ("block alignment"), and the lines can also be
   aligned horizontally within the text block ("text alignment").

     +-------------+
     |    label    |    Text is centered within the widget (block centered).
     |      1      |    Lines are aligned by their center (text centered).
     +-------------+

     +-------------+
     |    label    |    Text is centered within the widget (block centered).
     |    2        |    Lines are aligned by their left side (text left).
     +-------------+

     +-------------+
     |label        |    Text is aligned left within the widget (block left).
     |  3          |    Lines are aligned by their center (text centered).
     +-------------+

   Lines are broken at '\n' characters. Depending on the word wrap settings,
   lines can also be broken whenever the edge of the widget is reached. Extra
   line spacing (even negative) can be specified.

   The natural size of the widget is always computed based on newline
   characters, since there is no way to wrap until a width has been assigned.
   If you want predictable results, use size constraints.

   The text color and font can also be set, using the same color values and
   fonts as <gint/display.h>. If the font is set to NULL, gint's default font
   is used. The background color for the whole widget is handled by jwidget. */
typedef struct {
	jwidget widget;

	/* Horizontal block alignment */
	jalign block_halign;
	/* Vertical block alignment */
	jalign block_valign;
	/* Text alignment */
	jalign text_align;
	/* Pixels of spacing between each line, in addition to font->height */
	int8_t line_spacing;

	/* Text to display */
	char const *text;
	/* List of line break offsets; indexes 2n and 2n+1 give the start and end
	   of line number n */
  DECLARE_VEC(uint16_t, breaks);

	/* Text wrapping mode */
	enum jwrapmode wrap_mode;
	/* Whether the text has been allocated by the label or supplied by user */
	int8_t owns_text;
	/* Block width (maximum length of a rendered line) */
	uint16_t block_width;

	/* Color and font of text; if NULL, gint's default font is used */
	int color;
	font_t const *font;

} jlabel;

/* jlabel_create(): Create a label with a fixed text

   Initially the label has the supplied string as text (which must outlive the
   widget). If you want dynamic text, you can provide an empty string and use
   jlabel_printf() later. */
jlabel *jlabel_create(char const *text, void *parent);

/* jlabel_set_text(): Set a fixed string
   This function sets the label text to a fixed string. This is the same as in
   jlabel_create(). The string is not copied, it must outlive the label. This
   is the most useful when the provided string is a literal. */
void jlabel_set_text(jlabel *l, char const *text);

/* jlabel_asprintf(): Generate and set a formatted string
   This function generates the label string with printf-formatting. The
   resulting string is created with malloc() and owned by the label; it is
   destroyed when the text is replaced of the label is destroyed. Because of
   how asprintf() works, the string is generated twice. Returns the number of
   characters printed. */
int jlabel_asprintf(jlabel *l, char const *format, ...);

/* jlabel_snprintf(): Generate and set a formatted string
   Similar to jlabel_asprintf(), but an upper bound on the length of the result
   string has to be provided. This avoids generating the string twice. Return
   the number of characters printed. */
int jlabel_snprintf(jlabel *l, size_t size, char const *format, ...);

/* jlabel_text(): Get the current string */
char const *jlabel_text(jlabel *l);

/* Set block and text alignment, individually */
void jlabel_set_block_alignment(jlabel *l, jalign horz, jalign vert);
void jlabel_set_text_alignment(jlabel *l, jalign align);
/* Set both horizontal alignments at the same time (most natural) */
void jlabel_set_alignment(jlabel *l, jalign horizontal_align);

/* Trivial properties */
void jlabel_set_line_spacing(jlabel *l, int line_spacing);
void jlabel_set_wrap_mode(jlabel *l, jwrapmode mode);
void jlabel_set_text_color(jlabel *l, int color);
void jlabel_set_font(jlabel *l, font_t const *font);

#endif /* _J_JLABEL */