rb-text-helpers: Rhythmbox Development Reference Manual

rb-text-helpers

rb-text-helpers — text direction (LTR/RTL) functions

Functions

gboolean	rb_text_direction_conflict ()
PangoDirection	rb_text_common_direction ()
char *	rb_text_cat ()

Description

Provides some helper functions for constructing strings that may include both left-to-right and right-to-left text.

Functions

rb_text_direction_conflict ()

gboolean
rb_text_direction_conflict (PangoDirection dir1,
                            PangoDirection dir2);

Direction conflict here means the two directions are defined (non-neutral) and they are different.

Parameters

dir1	direction A
dir2	direction B

Returns

TRUE if the two directions conflict.

rb_text_common_direction ()

PangoDirection
rb_text_common_direction (const char *first,
                          ...);

This functions checks the direction of all given strings and:

If all strings are direction neutral, returns PANGO_DIRECTION_NEUTRAL;
If all strings are either LTR or neutral, returns PANGO_DIRECTION_LTR;
If all strings are either RTL or neutral, returns PANGO_DIRECTION_RTL;
If at least one is RTL and one LTR, returns PANGO_DIRECTION_NEUTRAL.

Note: neutral (1) and mixed (4) are two very different situations, they share a return code here only because they're the same for our specific use.

Parameters

first	first string
...	rest of strings, terminated with `NULL`

Returns

common direction of all strings, as defined above.

rb_text_cat ()

char *
rb_text_cat (PangoDirection base_dir,
             ...);

This function concatenates strings to a single string, preserving each part's original direction (LTR or RTL) using unicode markup, as detailed here: http://unicode.org/reports/tr9/.

It is called like this:

s = rb_text_cat(base_dir, str1, format1, ..., strN, formatN, NULL)

Format is a printf format with exactly one %s. "%s" or "" will insert the string as is.

Any string that is empty ("") will be skipped, its format must still be passed.

A space is inserted between strings.

The algorithm:

Caller supplies the base direction of the result in base_dir.
Insert either LRM or RLM at the beginning of the string to set its base direction, according to base_dir.
Find the direction of each string using pango.
For strings that have the same direction as the base direction, just insert them in.
For strings that have the opposite direction than the base one, insert them surrounded with embedding codes RLE/LRE .. PDF.

Parameters

base_dir	direction of the result string.
...	pairs of strings (content, format) terminated with `NULL`.

Returns

a new string containing the result.