## BTheme

BTheme — theme support to visualize Blinkenlights

## Synopsis

    struct      BColor;
    struct      BRectangle;
    struct      BWindow;
    #define     B_WINDOW_VALUE_ALL
    struct      BOverlay;
    struct      BTheme;
    BTheme*     b_theme_new_from_file           (const gchar *filename,
                                                 gboolean lazy_load,
                                                 GError **error);
    BTheme*     b_theme_new_from_scratch        (const gchar *title,
                                                 const gchar *type,
                                                 gint rows,
                                                 gint columns,
                                                 gint channels,
                                                 gint maxval,
                                                 gint width,
                                                 gint height);
    gboolean    b_theme_load                    (BTheme *theme,
                                                 GError **error);
    void        b_theme_unload                  (BTheme *theme);
    struct      BThemesQuery;
    enum        BThemesQueryFlags;
    GList*      b_themes_query                  (const gchar *themepath,
                                                 BThemesQuery *query);
    gboolean    (*BThemesForeachFunc)           (BTheme *theme,
                                                 gpointer callback_data);
    void        b_themes_foreach                (const gchar *themepath,
                                                 BThemesForeachFunc callback,
                                                 gpointer callback_data);
    void        b_themes_foreach_theme          (const gchar *themepath,
                                                 GHFunc callback,
                                                 gpointer callback_data);
    BTheme*     b_themes_lookup_theme           (const gchar *name,
                                                 const gchar *themepath,
                                                 GError **error);

## Object Hierarchy

      GObject
       +----BObject
             +----BTheme

## Description

A BTheme object defines the dimensions, features and the look of a Blinkenlights installation. It allows to implement a graphical simulation. BLib comes with two widgets, BViewGtk and BViewDirectFB that hide the ugly details of BTheme.

## Details

### struct BColor

    struct BColor {

      guchar  a;
      guchar  r;
      guchar  g;
      guchar  b;
    };

The BColor struct is used to store a single color. The color channels have values in the range from 0 to 255.

guchar `a` | alpha channel value (opacity)
guchar `r` | red channel value
guchar `g` | green channel value
guchar `b` | blue channel value

### struct BRectangle

    struct BRectangle {

      gint    x;
      gint    y;
      gint    w;
      gint    h;
    };

The BRectangle struct is used to store a rectangle. The coordinates are pixel values. The x coordinate advances from left to right, the y coordinate from top to bottom.

gint `x` | horizontal offset from origin
gint `y` | vertical offset from origin
gint `w` | width
gint `h` | height

### struct BWindow

    struct BWindow {

      gint        value;
      gint        row;
      gint        column;
      gint        src_x;
      gint        src_y;
      BRectangle  rect;
    };

The BWindow struct defines a single overlay window used in a BTheme.

gint `value` | the value this window definition applies to
gint `row` | the row index
gint `column` | the column index
gint `src_x` | x coordinate in the upper left corner in the source image
gint `src_y` | y coordinate of the upper left corner in the source image
BRectangle `rect` | the destination rectangle

### B_WINDOW_VALUE_ALL

    #define B_WINDOW_VALUE_ALL 0

A special value used to indicate that the window definition is valid for all possible values.

### struct BOverlay

    struct BOverlay {

      gchar       *image;
      BColor       color;

      GList       *windows;
    };

The BOverlay struct defines a set of overlay windows used in a BTheme.

gchar *`image` | an optional image to blend over the background
BColor `color` | the color is only used when no `image` is specified
GList *`windows` | a GList of BWindow structs

### struct BTheme

    struct BTheme;

The BTheme object defines the dimensions and the look of a Blinkenlights installation.

### b_theme_new_from_file ()

    BTheme*     b_theme_new_from_file           (const gchar *filename,
                                                 gboolean lazy_load,
                                                 GError **error);

Tries to load a BTheme from the file pointed to by `filename`. If `lazy_load` is `TRUE`, only the header is loaded.

`filename` : | the name of the file to load the theme from
`lazy_load` : | whether to do lazy-loading
`error` : | location to store the error occuring, or `NULL` to ignore errors
Returns : | a newly allocated BTheme object or `NULL` if the load failed

### b_theme_new_from_scratch ()

    BTheme*     b_theme_new_from_scratch        (const gchar *title,
                                                 const gchar *type,
                                                 gint rows,
                                                 gint columns,
                                                 gint channels,
                                                 gint maxval,
                                                 gint width,
                                                 gint height);

Creates a new BTheme object from scratch. This may be useful if you want to quickly test a movie for a layout you don't have a theme for. You need to call b_theme_load() before you can use the new theme.

`title` : | a descriptive title
`type` : | the theme type or `NULL`
`rows` : | the number of rows of windows
`columns` : | the number of columns of windows
`channels` : | the number of channels per window (must be 1)
`maxval` : | the maximum value
`width` : | screen width in pixels
`height` : | screen height in pixels
Returns : | a newly allocated, lazy-loaded, BTheme object

### b_theme_load ()

    gboolean    b_theme_load                    (BTheme *theme,
                                                 GError **error);

Loads all data into the `theme`. You only need to call this if you lazy-loaded the theme or called b_theme_unload() before.

`theme` : | a BTheme object
`error` : | location to store the error occuring, or `NULL` to ignore errors
Returns : | `TRUE` on success, FALSE otherwise

### b_theme_unload ()

    void        b_theme_unload                  (BTheme *theme);

Frees all data of a BTheme except the meta information stored in the header.

`theme` : | a BTheme object

### struct BThemesQuery

    struct BThemesQuery {

      BThemesQueryFlags  flags;

      const gchar       *name;
      const gchar       *type;
      gint               rows;
      gint               columns;
      gint               width;
      gint               height;
    };

A structure that defines a query on the installed themes. Used by b_themes_query().

### enum BThemesQueryFlags

    typedef enum
    {
      B_THEMES_QUERY_NONE    = 0,
      B_THEMES_QUERY_NAME    = 1 << 0,
      B_THEMES_QUERY_TYPE    = 1 << 1,
      B_THEMES_QUERY_ROWS    = 1 << 2,
      B_THEMES_QUERY_COLUMNS = 1 << 3,
      B_THEMES_QUERY_WIDTH   = 1 << 4,
      B_THEMES_QUERY_HEIGHT  = 1 << 5
    } BThemesQueryFlags;

Flags that define which values of a BThemesQuery are valid.

### b_themes_query ()

    GList*      b_themes_query                  (const gchar *themepath,
                                                 BThemesQuery *query);

Looks for themes as defined by `query`. If `themepath` is not specified the default path is used. The default path can be overridden by setting the environment variable B_THEME_PATH.

Each theme that matches the `query` is lazy-loaded.

`themepath` : | a colon-separated list of directories to search or `NULL` to use the default path
`query` : | pointer to a BThemesQuery
Returns : | a GList of newly allocated, lazy-loaded BTheme objects or `NULL` if no matching theme was found

### BThemesForeachFunc ()

    gboolean    (*BThemesForeachFunc)           (BTheme *theme,
                                                 gpointer callback_data);

This function is called for each theme found by b_themes_foreach().

`theme` : |
`callback_data` : |
Returns : |

### b_themes_foreach ()

    void        b_themes_foreach                (const gchar *themepath,
                                                 BThemesForeachFunc callback,
                                                 gpointer callback_data);

This function iterates over all themes in the `themepath`, lazy-loads them, runs `callback` on the theme and unrefs it again. The iteration is stopped if a `callback` returns `FALSE`.

If `themepath` is not specified, the default path is used. The default path can be overridden by setting the environment variable B_THEME_PATH.

`themepath` : | a colon-separated list of directories to search or `NULL` to use the default path
`callback` : | a function to call for each theme
`callback_data` : | data to pass to the `callback`

### b_themes_foreach_theme ()

    void        b_themes_foreach_theme          (const gchar *themepath,
                                                 GHFunc callback,
                                                 gpointer callback_data);

### Warning

`b_themes_foreach_theme` is deprecated and should not be used in newly-written code.

Shouldn't be used in new code, use b_themes_foreach() instead.

`themepath` : |
`callback` : |
`callback_data` : |

### b_themes_lookup_theme ()

    BTheme*     b_themes_lookup_theme           (const gchar *name,
                                                 const gchar *themepath,
                                                 GError **error);

### Warning

`b_themes_lookup_theme` is deprecated and should not be used in newly-written code.

Shouldn't be used in new code, use b_themes_query() instead.

`name` : |
`themepath` : |
`error` : |
Returns : |

## See Also

BViewDirectFB, BViewGtk