AsBranding: AppStream Library Reference Manual

## AsBranding

AsBranding — Description of branding for an AsComponent.

## Functions

const gchar * | as_color_kind_to_string ()
AsColorKind | as_color_kind_from_string ()
const gchar * | as_color_scheme_kind_to_string ()
AsColorSchemeKind | as_color_scheme_kind_from_string ()
AsBranding * | as_branding_new ()
void | as_branding_set_color ()
void | as_branding_remove_color ()
void | as_branding_color_iter_init ()
gboolean | as_branding_color_iter_next ()
const gchar * | as_branding_get_color ()

## Types and Values

#define | AS_TYPE_BRANDING
struct | AsBrandingClass
enum | AsColorKind
enum | AsColorSchemeKind
| AsBranding

## Includes

    #include <appstream.h>

## Description

This class provides information contained in an AppStream branding tag. See https://www.freedesktop.org/software/appstream/docs/chap-Metadata.htmltag-branding for more information.

See also: AsComponent

## Functions

### as_color_kind_to_string ()

    const gchar *
    as_color_kind_to_string (AsColorKind kind);

Converts the enumerated value to an text representation.

#### Parameters

kind | the `AsColorKind`. |

#### Returns

string version of `kind`

Since: 0.15.2

### as_color_kind_from_string ()

    AsColorKind
    as_color_kind_from_string (const gchar *str);

Converts the text representation to an enumerated value.

#### Parameters

str | the string. |

#### Returns

a AsColorKind or `AS_COLOR_KIND_UNKNOWN` for unknown.

Since: 0.15.2

### as_color_scheme_kind_to_string ()

    const gchar *
    as_color_scheme_kind_to_string (AsColorSchemeKind kind);

Converts the enumerated value to an text representation.

#### Parameters

kind | the `AsColorSchemeKind`. |

#### Returns

string version of `kind`

Since: 0.15.2

### as_color_scheme_kind_from_string ()

    AsColorSchemeKind
    as_color_scheme_kind_from_string (const gchar *str);

Converts the text representation to an enumerated value.

#### Parameters

str | the string. |

#### Returns

a AsColorKind or `AS_COLOR_SCHEME_KIND_UNKNOWN` for unknown.

Since: 0.15.2

### as_branding_new ()

    AsBranding *
    as_branding_new (void);

Creates a new AsBranding.

#### Returns

a AsBranding.

[transfer full]

Since: 0.10

### as_branding_set_color ()

    void
    as_branding_set_color (AsBranding *branding,
                           AsColorKind kind,
                           AsColorSchemeKind scheme_preference,
                           const gchar *colorcode);

Sets a new accent color. If a color of the given kind with the given scheme preference already exists, it will be overriden with the new color code.

#### Parameters

branding | an AsBranding instance. |
kind | the AsColorKind, e.g. `AS_COLOR_KIND_PRIMARY`. |
scheme_preference | Type of color scheme preferred for this color, e.g. `AS_COLOR_SCHEME_KIND_LIGHT` |
colorcode | a HTML color code. |

Since: 0.15.2

### as_branding_remove_color ()

    void
    as_branding_remove_color (AsBranding *branding,
                              AsColorKind kind,
                              AsColorSchemeKind scheme_preference);

Deletes a color that matches the given type and scheme preference.

#### Parameters

branding | an AsBranding instance. |
kind | the AsColorKind, e.g. `AS_COLOR_KIND_PRIMARY`. |
scheme_preference | Type of color scheme preferred for this color, e.g. `AS_COLOR_SCHEME_KIND_LIGHT` |

Since: 0.15.2

### as_branding_color_iter_init ()

    void
    as_branding_color_iter_init (AsBrandingColorIter *iter,
                                 AsBranding *branding);

Initializes a color iterator for the accent color list and associates it it with `branding` . The AsBrandingColorIter structure is typically allocated on the stack and does not need to be freed explicitly.

#### Parameters

iter | an uninitialized AsBrandingColorIter |
branding | an AsBranding |

### as_branding_color_iter_next ()

    gboolean
    as_branding_color_iter_next (AsBrandingColorIter *iter,
                                 AsColorKind *kind,
                                 AsColorSchemeKind *scheme_preference,
                                 const gchar **value);

Returns the current color entry and advances the iterator. Example:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    AsBrandingColorIter iter;
    AsColorKind ckind;
    AsColorSchemeKind scheme_preference;
    const gchar *color_value;

    as_branding_color_iter_init (&iter, branding);
    while (as_branding_color_iter_next (&iter, &ckind, &scheme_preference, &color_value)) {
        // do something with the color data
    }

#### Parameters

iter | an initialized AsBrandingColorIter |
kind | Destination of the returned color kind. | [out][optional][not nullable]
scheme_preference | Destination of the returned color's scheme preference. | [out][optional][not nullable]
value | Destination of the returned color code. | [out][optional][not nullable]

#### Returns

`FALSE` if the last entry has been reached.

### as_branding_get_color ()

    const gchar *
    as_branding_get_color (AsBranding *branding,
                           AsColorKind kind,
                           AsColorSchemeKind scheme_kind);

Retrieve a color of the given `kind` that matches `scheme_kind` . If a color has no scheme preference defined, it will be returned for either scheme type, unless a more suitable color was found.

#### Parameters

branding | an AsBranding instance. |
kind | the AsColorKind, e.g. `AS_COLOR_KIND_PRIMARY`. |
scheme_kind | Color scheme preference for the color, e.g. `AS_COLOR_SCHEME_KIND_LIGHT` |

#### Returns

The HTML color code of the found color, or `NULL` if no color was found.

[nullable]

Since: 0.15.2

## Types and Values

### AS_TYPE_BRANDING

    #define AS_TYPE_BRANDING (as_branding_get_type ())

### struct AsBrandingClass

    struct AsBrandingClass {
    	GObjectClass parent_class;
    };

### enum AsColorKind

A branding color type.

#### Members

AS_COLOR_KIND_UNKNOWN | Color type invalid or not known |
AS_COLOR_KIND_PRIMARY | Primary accent color |

### enum AsColorSchemeKind

A color scheme type.

#### Members

AS_COLOR_SCHEME_KIND_UNKNOWN | Color scheme invalid or not known |
AS_COLOR_SCHEME_KIND_LIGHT | A light color scheme |
AS_COLOR_SCHEME_KIND_DARK | A dark color scheme |

### AsBranding

    typedef struct _AsBranding AsBranding;