st-texture-cache: Cinnamon St Reference Manual

## st-texture-cache st-texture-cache |

## Functions

StTextureCache * | st_texture_cache_get_default ()
ClutterActor * | st_texture_cache_load_sliced_image_file ()
ClutterActor * | st_texture_cache_load_sliced_image ()
ClutterActor * | st_texture_cache_load_from_pixbuf ()
ClutterActor * | st_texture_cache_load_from_raw ()
ClutterActor * | st_texture_cache_load_file_simple ()
StWidget * | st_texture_cache_bind_cairo_surface_property ()
ClutterActor * | st_texture_cache_load_gicon_with_scale ()
ClutterActor * | st_texture_cache_load_gicon ()
ClutterActor * | st_texture_cache_load_icon_name ()
ClutterActor * | st_texture_cache_load_file_async ()
ClutterActor * | st_texture_cache_load_uri_async ()
CoglTexture * | st_texture_cache_load_gfile_to_cogl_texture ()
CoglTexture * | st_texture_cache_load_file_to_cogl_texture ()
cairo_surface_t * | st_texture_cache_load_gfile_to_cairo_surface ()
cairo_surface_t * | st_texture_cache_load_file_to_cairo_surface ()
void | (*StTextureCacheLoadImageCallback) ()
guint | st_texture_cache_load_image_from_file_async ()
CoglTexture * | (*StTextureCacheLoader) ()
CoglTexture * | st_texture_cache_load ()
gboolean | st_texture_cache_rescan_icon_theme ()
GtkIconTheme * | st_texture_cache_get_icon_theme ()
gboolean | st_texture_cache_can_load_mime_type ()

## Signals

void | icon-theme-changed | Run Last
void | texture-file-changed | Run Last

## Types and Values

#define | ST_TYPE_TEXTURE_CACHE
struct | StTextureCache
enum | StTextureCachePolicy
| StTextureCachePrivate

## Object Hierarchy

        GEnum
        ╰── StTextureCachePolicy
        GObject
        ╰── StTextureCache

## Description

## Functions

### st_texture_cache_get_default ()

    StTextureCache *
    st_texture_cache_get_default (void);

#### Returns

The global texture cache.

[transfer none]

### st_texture_cache_load_sliced_image_file ()

    ClutterActor *
    st_texture_cache_load_sliced_image_file
                                   (StTextureCache *cache,
                                    GFile *file,
                                    gint grid_width,
                                    gint grid_height,
                                    gint paint_scale,
                                    gfloat resource_scale,
                                    GFunc load_callback,
                                    gpointer user_data);

This function reads a single image file which contains multiple images internally. The image file will be divided using `grid_width` and `grid_height` ; note that the dimensions of the image loaded from `path` should be a multiple of the specified grid dimensions.

#### Parameters

cache | A StTextureCache |
file | A GFile |
grid_width | Width in pixels |
grid_height | Height in pixels |
paint_scale | Scale factor of the display |
load_callback | Function called when the image is loaded, or `NULL`. | [scope async][nullable]
user_data | Data to pass to the load callback |

#### Returns

A new ClutterActor.

[transfer none]

### st_texture_cache_load_sliced_image ()

    ClutterActor *
    st_texture_cache_load_sliced_image (StTextureCache *cache,
                                        const gchar *path,
                                        gint grid_width,
                                        gint grid_height,
                                        GFunc load_callback,
                                        gpointer user_data);

This function reads a single image file which contains multiple images internally. The image file will be divided using `grid_width` and `grid_height` ; note that the dimensions of the image loaded from `path` should be a multiple of the specified grid dimensions.

#### Parameters

cache | A StTextureCache |
path | Path to a filename |
grid_width | Width in pixels |
grid_height | Height in pixels |
load_callback | Function called when the image is loaded, or `NULL`. | [scope async][allow-none]
user_data | Data to pass to the load callback |

#### Returns

A new ClutterActor.

[transfer none]

### st_texture_cache_load_from_pixbuf ()

    ClutterActor *
    st_texture_cache_load_from_pixbuf (GdkPixbuf *pixbuf,
                                       int size);

Converts a GdkPixbuf into a ClutterTexture.

#### Parameters

pixbuf | A GdkPixbuf |
size | int |

#### Returns

A new ClutterActor.

[transfer none]

### st_texture_cache_load_from_raw ()

    ClutterActor *
    st_texture_cache_load_from_raw (StTextureCache *cache,
                                    const guchar *data,
                                    gsize len,
                                    gboolean has_alpha,
                                    int width,
                                    int height,
                                    int rowstride,
                                    int size,
                                    GError **error);

Creates (or retrieves from cache) an icon based on raw pixel data.

#### Parameters

cache | a StTextureCache |
data | raw pixel data. | [array length=len]
len | the length of `data` |
has_alpha | whether `data` includes an alpha channel |
width | width in pixels of `data` |
height | width in pixels of `data` |
rowstride | rowstride of `data` |
size | size of icon to return |

#### Returns

a new ClutterActor displaying a pixbuf created from `data` and the other parameters.

[transfer none]

### st_texture_cache_load_file_simple ()

    ClutterActor *
    st_texture_cache_load_file_simple (StTextureCache *cache,
                                       const gchar *file_path);

Synchronously load an image into a texture. The texture will be cached indefinitely. On error, this function returns an empty texture and prints a warning.

#### Parameters

cache | A StTextureCache |
file_path | Filesystem path |

#### Returns

A new ClutterTexture.

[transfer none]

### st_texture_cache_bind_cairo_surface_property ()

    StWidget *
    st_texture_cache_bind_cairo_surface_property
                                   (StTextureCache *cache,
                                    GObject *object,
                                    const char *property_name,
                                    gint size);

Create a ClutterActor which tracks the cairo_surface_t value of a GObject property named by `property_name` . Unlike other methods in StTextureCache, the underlying CoglTexture is not shared by default with other invocations to this method.

If the source object is destroyed, the texture will continue to show the last value of the property.

#### Parameters

object | A GObject with a property `property_name` of type GdkPixbuf |
property_name | Name of a property |

#### Returns

A new StWidget.

[transfer none]

### st_texture_cache_load_gicon_with_scale ()

    ClutterActor *
    st_texture_cache_load_gicon_with_scale
                                   (StTextureCache *cache,
                                    StThemeNode *theme_node,
                                    GIcon *icon,
                                    gint size,
                                    gint paint_scale,
                                    gfloat resource_scale);

This method returns a new ClutterActor for a given GIcon. If the icon isn't loaded already, the texture will be filled asynchronously.

#### Parameters

cache | The texture cache instance |
theme_node | The StThemeNode to use for colors, or NULL if the icon must not be recolored. | [nullable]
icon | the GIcon to load |
size | Size of themed |
paint_scale | Scale factor of display |
resource_scale | Resource scale factor |

#### Returns

A new ClutterActor for the icon, or `NULL` if not found.

[transfer none]

### st_texture_cache_load_gicon ()

    ClutterActor *
    st_texture_cache_load_gicon (StTextureCache *cache,
                                 StThemeNode *theme_node,
                                 GIcon *icon,
                                 gint size);

This method returns a new ClutterActor for a given GIcon. If the icon isn't loaded already, the texture will be filled asynchronously.

#### Parameters

cache | The texture cache instance |
theme_node | The StThemeNode to use for colors, or NULL if the icon must not be recolored. | [allow-none]
icon | the GIcon to load |
size | Size of themed |

#### Returns

A new ClutterActor for the icon, or an empty ClutterActor if none was found.

[transfer none]

### st_texture_cache_load_icon_name ()

    ClutterActor *
    st_texture_cache_load_icon_name (StTextureCache *cache,
                                     StThemeNode *theme_node,
                                     const char *name,
                                     StIconType icon_type,
                                     gint size);

Load a themed icon into a texture. See the StIconType documentation for an explanation of how `icon_type` affects the returned icon. The colors used for symbolic icons are derived from `theme_node` .

#### Parameters

cache | The texture cache instance |
theme_node | a StThemeNode. | [allow-none]
name | Name of a themed icon |
icon_type | the type of icon to load |
size | Size of themed |

#### Returns

A new ClutterTexture for the icon.

[transfer none]

### st_texture_cache_load_file_async ()

    ClutterActor *
    st_texture_cache_load_file_async (StTextureCache *cache,
                                      GFile *file,
                                      int available_width,
                                      int available_height,
                                      int paint_scale,
                                      gfloat resource_scale);

Asynchronously load an image. Initially, the returned texture will have a natural size of zero. At some later point, either the image will be loaded successfully and at that point size will be negotiated, or upon an error, no image will be set.

#### Parameters

cache | The texture cache instance |
file | a GFile of the image file from which to create a pixbuf |
available_width | available width for the image, can be -1 if not limited |
available_height | available height for the image, can be -1 if not limited |
paint_scale | scale factor of the display |
resource_scale | Resource scale factor |

#### Returns

A new ClutterActor with no image loaded initially.

[transfer none]

### st_texture_cache_load_uri_async ()

    ClutterActor *
    st_texture_cache_load_uri_async (StTextureCache *cache,
                                     const gchar *uri,
                                     int available_width,
                                     int available_height);

Asynchronously load an image. Initially, the returned texture will have a natural size of zero. At some later point, either the image will be loaded successfully and at that point size will be negotiated, or upon an error, no image will be set.

#### Parameters

cache | The texture cache instance |
uri | uri of the image file from which to create a pixbuf |
available_width | available width for the image, can be -1 if not limited |
available_height | available height for the image, can be -1 if not limited |

#### Returns

A new ClutterActor with no image loaded initially.

[transfer none]

### st_texture_cache_load_gfile_to_cogl_texture ()

    CoglTexture *
    st_texture_cache_load_gfile_to_cogl_texture
                                   (StTextureCache *cache,
                                    GFile *file,
                                    gint paint_scale,
                                    gfloat resource_scale);

This function synchronously loads the given file path into a COGL texture. On error, a warning is emitted and `NULL` is returned.

[skip]

#### Parameters

cache | A StTextureCache |
file | A GFile in supported image format |
paint_scale | Scale factor of the display |
resource_scale | Resource scale factor |

#### Returns

a new CoglTexture.

[transfer full]

### st_texture_cache_load_file_to_cogl_texture ()

    CoglTexture *
    st_texture_cache_load_file_to_cogl_texture
                                   (StTextureCache *cache,
                                    const gchar *file_path);

This function synchronously loads the given file path into a COGL texture. On error, a warning is emitted and `NULL` is returned.

[skip]

#### Parameters

cache | A StTextureCache |
file_path | Path to a file in supported image format |

#### Returns

a new CoglTexture.

[transfer full]

### st_texture_cache_load_gfile_to_cairo_surface ()

    cairo_surface_t *
    st_texture_cache_load_gfile_to_cairo_surface
                                   (StTextureCache *cache,
                                    GFile *file,
                                    gint paint_scale,
                                    gfloat resource_scale);

This function synchronously loads the given file path into a cairo surface. On error, a warning is emitted and `NULL` is returned.

#### Parameters

cache | A StTextureCache |
file | A GFile in supported image format |
paint_scale | Scale factor of the display |
resource_scale | Resource scale factor |

#### Returns

a new cairo_surface_t.

[transfer full]

### st_texture_cache_load_file_to_cairo_surface ()

    cairo_surface_t *
    st_texture_cache_load_file_to_cairo_surface
                                   (StTextureCache *cache,
                                    const gchar *file_path);

This function synchronously loads the given file path into a cairo surface. On error, a warning is emitted and `NULL` is returned.

#### Parameters

cache | A StTextureCache |
file_path | Path to a file in supported image format |

#### Returns

a new cairo_surface_t.

[transfer full]

### StTextureCacheLoadImageCallback ()

    void
    (*StTextureCacheLoadImageCallback) (StTextureCache *cache,
                                        guint handle,
                                        ClutterActor *actor,
                                        gpointer user_data);

Callback from st_texture_cache_load_image_from_file_async. The handle should match the one returned by _load_image_from_file_async.

#### Parameters

cache | a StTextureCache |
handle | the handle returned to the caller in the original call. |
actor | the actor containing the loaded image |
user_data | Callback data |

### st_texture_cache_load_image_from_file_async ()

    guint
    st_texture_cache_load_image_from_file_async
                                   (StTextureCache *cache,
                                    const gchar *path,
                                    gint width,
                                    gint height,
                                    StTextureCacheLoadImageCallback callback,
                                    gpointer user_data);

This function loads an image file into a clutter actor asynchronously. This is mostly useful for situations where you want to load an image asynchronously, but don't want the actor back until it's fully loaded and sized (as opposed to load_uri_async, which provides no callback function, and leaves size negotiation to its own devices.)

The image's aspect ratio is always maintained and if both width and height are > 0 the image will never exceed these dimensions.

#### Parameters

cache | A StTextureCache |
path | Path to a filename |
width | Width in pixels (or -1 to leave unconstrained) |
height | Height in pixels (or -1 to leave unconstrained) |
callback | Function called when the image is loaded (required). | [scope async][not nullable]
user_data | Data to pass to the load callback. | [closure]

#### Returns

A handle that can be used to verify the actor issued in the callback is the expected one.

### StTextureCacheLoader ()

    CoglTexture *
    (*StTextureCacheLoader) (StTextureCache *cache,
                             const char *key,
                             void *data,
                             GError **error);

See `st_texture_cache_load()`. Implementations should return a texture handle for the given key, or set `error` .

[skip]

#### Parameters

cache | a StTextureCache |
key | Unique identifier for this texture |
data | Callback user data |
error | A GError |

### st_texture_cache_load ()

    CoglTexture *
    st_texture_cache_load (StTextureCache *cache,
                           const char *key,
                           StTextureCachePolicy policy,
                           StTextureCacheLoader load,
                           void *data,
                           GError **error);

Load an arbitrary texture, caching it. The string chosen for `key` should be of the form "type-prefix:type-uuid". For example, "url:file:///usr/share/icons/hicolor/48x48/apps/firefox.png", or "stock-icon:gtk-ok".

[skip]

#### Parameters

cache | A StTextureCache |
key | Arbitrary string used to refer to item |
policy | Caching policy |
load | Function to create the texture, if not already cached |
data | User data passed to `load` |
error | A GError |

#### Returns

A newly-referenced handle to the texture.

[transfer full]

### st_texture_cache_rescan_icon_theme ()

    gboolean
    st_texture_cache_rescan_icon_theme (StTextureCache *cache);

### st_texture_cache_get_icon_theme ()

    GtkIconTheme *
    st_texture_cache_get_icon_theme (StTextureCache *cache);

#### Returns

The texture cache's icon theme.

[transfer none]

### st_texture_cache_can_load_mime_type ()

    gboolean
    st_texture_cache_can_load_mime_type (StTextureCache *cache,
                                         const char *mime_type);

Compares `mime_type` with a list of types that we are capable of loading.

#### Parameters

cache | A StTextureCache |
mime_type | A MIME type string (like 'image/png') |

#### Returns

`TRUE` if the mime_type is valid.

## Types and Values

### ST_TYPE_TEXTURE_CACHE

    #define ST_TYPE_TEXTURE_CACHE                 (st_texture_cache_get_type ())

### struct StTextureCache

    struct StTextureCache;

### enum StTextureCachePolicy

#### Members

ST_TEXTURE_CACHE_POLICY_NONE |  |
ST_TEXTURE_CACHE_POLICY_FOREVER |  |

### StTextureCachePrivate

    typedef struct _StTextureCachePrivate StTextureCachePrivate;

## Signal Details

### The `“icon-theme-changed”` signal

    void
    user_function (StTextureCache *sttexturecache,
                   gpointer        user_data)

Flags: Run Last

### The `“texture-file-changed”` signal

    void
    user_function (StTextureCache *sttexturecache,
                   GFile          *arg1,
                   gpointer        user_data)

Flags: Run Last