Agar Logo

Agar 1.7 Manual

(Printable Version)
AG_TextElement(3)

SYNOPSIS 

#include <agar/core.h>

DESCRIPTION

The AG_TextElement (or AG_Text) structure provides a dynamically-allocated buffer for a text element, specified in one or more languages.

Agar GUI widgets such as AG_Textbox(3) or AG_Editable(3) may be bound to a AG_TextElement (in which case they make it possible to select the language from a contextual menu). It is also possible to define an AG_Variable(3) referencing an AG_TextElement. It is defined as: 
typedef struct ag_text {
	AG_Mutex lock;
	AG_TextEnt ent[AG_LANG_LAST]; /* Language entries */
	enum ag_language lang;        /* Selected language */
	AG_Size maxLen;               /* Maximum length (bytes) */
	Uint flags;
} AG_Text, AG_TextElement;

The lock mutex must be acquired prior to accessing any entry ent[]. The lang member is either AG_LANG_NONE or AG_LANG_xx, where xx is a ISO-639 language code. For convenience, the AG_LANG_* enums are also valid indices into public arrays agLanguageCodes[] (two-character codes) and agLanguageNames[] (full language names).

Per-language entries are described by the AG_TextEnt structure: 
typedef struct ag_text_ent {
	char *buf;       /* String buffer */
	AG_Size maxLen;  /* Length (allocated) */
	AG_Size len;     /* Length (chars) */
} AG_TextEnt;

INTERFACE ↑


AG_Text * AG_TextNew (AG_Size maxLen)

void AG_TextInit (AG_Text *T, AG_Size maxLen)

void AG_TextSetLimit (AG_Text *T, AG_Size maxLen)

void AG_TextDestroy (AG_Text *T)

void AG_TextClear (AG_Text *T)

void AG_TextSetLang (AG_Text *T, enum ag_language lang)

enum ag_language AG_TextGetLang (AG_Text *T)

void AG_TextSetLangISO (AG_Text *T, const char *lang_code)

const char* AG_TextGetLangISO (AG_Text *T)

void AG_TextSet (AG_Text *T, const char *fmt, ...)

void AG_TextSetS (AG_Text *T, const char *s)

void AG_TextSetEnt (AG_Text *T, enum ag_language lang, const char *fmt, ...)

void AG_TextSetEntS (AG_Text *T, enum ag_language lang, const char *fmt, ...)

AG_Text * AG_TextDup (AG_Text *T)

int AG_TextLoad (AG_Text *T, AG_DataSource *ds)

void AG_TextSave (AG_DataSource *ds, AG_Text *T)


The AG_TextNew() function allocates and initializes a new, empty AG_TextElement. AG_TextInit() initializes an existing AG_TextElement. The maxLen argument specifies a maximum string length in bytes, or 0 for no limit. AG_TextSetLimit() may be used to set the effective limit.

AG_TextDestroy() frees all resources allocated by a text element.

AG_TextClear() frees and reinitializes all entries of the element.

The functions AG_TextGetLang() and AG_TextSetLang() return or select the active language for a text element, specified as AG_LANG_NONE or AG_LANG_xx enum. The AG_TextGetLangISO() and AG_TextSetLangISO() variants accept a two-character ISO-639 code as argument.

The AG_TextSet() routine sets the text entry for the currently selected language. The AG_TextSetEnt() variant sets the text entry for the specified language.

The AG_TextDup() routine returns a newly-allocated copy of the specified text element.

The AG_TextLoad() function initializes the specified text element from AG_DataSource(3) data. AG_TextSave() saves the text element to the given data source.

EXAMPLES ↑

The following GUI code creates a text element and binds an AG_Textbox(3) widget to it: 
AG_Text *name;
AG_Textbox *tb;

name = AG_TextNew(32);
AG_TextSetEnt(name, AG_LANG_EN, "John");
AG_TextSetEnt(name, AG_LANG_FR, "Jean");
AG_TextSetEnt(name, AG_LANG_DE, "Johannes");

tb = AG_TextboxNewS(NULL, 0, "Name: ");
AG_TextboxBindText(tb, name);

SEE ALSO ↑

AG_Editable(3), AG_Intro(3), AG_Text(3), AG_Textbox(3), AG_Variable(3)

HISTORY ↑

The AG_TextElement interface first appeared in Agar 1.5.0

Csoft.net ElectronTubeStore