## awn-overlay awn-overlay — Base object for overlays used with AwnOverlayable. |

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

    #include <libawn/libawn.h>

                        AwnOverlay;
    void                render                              (AwnOverlay *overlay,
                                                             GtkWidget *widget,
                                                             cairo_t *cr,
                                                             gint width,
                                                             gint height);
    enum                AwnOverlayAlign;
    AwnOverlay*         awn_overlay_new                     (void);
    void                awn_overlay_render                  (AwnOverlay *overlay,
                                                             GtkWidget *widget,
                                                             cairo_t *cr,
                                                             gint width,
                                                             gint height);
    void                awn_overlay_move_to                 (AwnOverlay *overlay,
                                                             cairo_t *cr,
                                                             gint icon_width,
                                                             gint icon_height,
                                                             gint overlay_width,
                                                             gint overlay_height,
                                                             AwnOverlayCoord *coord_req);
    gboolean            awn_overlay_get_apply_effects       (AwnOverlay *overlay);
    void                awn_overlay_set_apply_effects       (AwnOverlay *overlay,
                                                             gboolean value);
    gboolean            awn_overlay_get_use_source_op       (AwnOverlay *overlay);
    void                awn_overlay_set_use_source_op       (AwnOverlay *overlay,
                                                             gboolean value);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----AwnOverlay
                   +----AwnOverlayProgress
                   +----AwnOverlayPixbuf
                   +----AwnOverlayThemedIcon
                   +----AwnOverlayText
                   +----AwnOverlayThrobber

## Properties

      "active"                   gboolean              : Read / Write / Construct
      "align"                    gint                  : Read / Write / Construct
      "apply-effects"            gboolean              : Read / Write
      "gravity"                  GdkGravity            : Read / Write / Construct
      "use-source-op"            gboolean              : Read / Write
      "x-adj"                    gdouble               : Read / Write / Construct
      "x-override"               gdouble               : Read / Write / Construct
      "y-adj"                    gdouble               : Read / Write / Construct
      "y-override"               gdouble               : Read / Write / Construct

## Description

Base object for overlays used with AwnOverlayable. This object is only useful as a base class from which other classes are derived.

## Details

### AwnOverlay

    typedef struct _AwnOverlay AwnOverlay;

Base object for overlays used with AwnOverlayable. This object is only useful as a base class from which other classes are derived.

### render ()

    void                render                              (AwnOverlay *overlay,
                                                             GtkWidget *widget,
                                                             cairo_t *cr,
                                                             gint width,
                                                             gint height);

`overlay` : |
`widget` : |
`cr` : |
`width` : |
`height` : |

### enum AwnOverlayAlign

    typedef enum
    {
      AWN_OVERLAY_ALIGN_CENTRE,
      AWN_OVERLAY_ALIGN_LEFT,
      AWN_OVERLAY_ALIGN_RIGHT
    }AwnOverlayAlign;

An enum for horizontal alignment relative to the GdkGravity specified for an AwnOverlay. Possible values are `AWN_OVERLAY_ALIGN_CENTRE`, `AWN_OVERLAY_ALIGN_LEFT` and `AWN_OVERLAY_ALIGN_RIGHT`

`AWN_OVERLAY_ALIGN_CENTRE` | Centre alignment.
`AWN_OVERLAY_ALIGN_LEFT` | Left alignment.
`AWN_OVERLAY_ALIGN_RIGHT` | Right alignment.

### awn_overlay_new ()

    AwnOverlay*         awn_overlay_new                     (void);

Creates a new instance of AwnOverlay.

Returns : | an instance of AwnOverlay.

### awn_overlay_render ()

    void                awn_overlay_render                  (AwnOverlay *overlay,
                                                             GtkWidget *widget,
                                                             cairo_t *cr,
                                                             gint width,
                                                             gint height);

A virtual function invoked by AwnOverlaidIcon for each overlay it contains, on "expose". This should be implemented by subclasses of AwnOverlay.

`overlay` : | An pointer to an AwnOverlay (or subclass) object.
`widget` : | The GtkWidget that is being overlaid.
`cr` : | Pointer to cairo context ( cairo_t ) for the surface being overlaid.
`width` : | The width of the AwnThemedIcon as gint.
`height` : | The height of the AwnThemedIcon as gint.

### awn_overlay_move_to ()

    void                awn_overlay_move_to                 (AwnOverlay *overlay,
                                                             cairo_t *cr,
                                                             gint icon_width,
                                                             gint icon_height,
                                                             gint overlay_width,
                                                             gint overlay_height,
                                                             AwnOverlayCoord *coord_req);

A convenience function for subclasses of AwnOverlay. For most cases will provide correct placement of the overlay within the surface. Only of interest for those implementing AwnOverlay subclass.

`overlay` : | An pointer to an AwnOverlay (or subclass) object.
`cr` : | Pointer to Cairo context ( cairo_t) for the surface being overlaid. Poi
`icon_width` : | The width of the AwnIcon as gint.
`icon_height` : | The height of the AwnIcon as gint.
`overlay_width` : | The width of the AwnOverlay as gint.
`overlay_height` : | The height of the AwnOverlay as gint.
`coord_req` : | Address of a AwnOverlayCoord structure or NULL. The x,y coords will be returned in the structure if one is provided so they can be used a later time if needed.

### awn_overlay_get_apply_effects ()

    gboolean            awn_overlay_get_apply_effects       (AwnOverlay *overlay);

`overlay` : |
Returns : |

### awn_overlay_set_apply_effects ()

    void                awn_overlay_set_apply_effects       (AwnOverlay *overlay,
                                                             gboolean value);

`overlay` : |
`value` : |

### awn_overlay_get_use_source_op ()

    gboolean            awn_overlay_get_use_source_op       (AwnOverlay *overlay);

`overlay` : |
Returns : |

### awn_overlay_set_use_source_op ()

    void                awn_overlay_set_use_source_op       (AwnOverlay *overlay,
                                                             gboolean value);

`overlay` : |
`value` : |

## Property Details

### The `"active"` property

      "active"                   gboolean              : Read / Write / Construct

The active property controls if the render virtual method of AwnOverlayClass is invoked when `awn_overlay_render_overlay()` . If set to FALSE the overlay is not rendered. Subclass implementors should monitor this_effect property for changes if it is appropriate to disengage timers etc when set to FALSE.

Default value: TRUE

### The `"align"` property

      "align"                    gint                  : Read / Write / Construct

An AwnOverlayAlign property that controls horizontal alignment of the overlay relative to it's position as specified by the gravity property. Often used with AwnOverlayText overlays. Setting to AWN_OVERLAY_ALIGN_RIGHT or AWN_OVERLAY_ALIGN_LEFT will allow for a fixed right or left position for the overlay.

Allowed values: [0,2]

Default value: 0

### The `"apply-effects"` property

      "apply-effects"            gboolean              : Read / Write

The apply-effects property controls AwnEffects effects are applied to the overlay.

Default value: TRUE

### The `"gravity"` property

      "gravity"                  GdkGravity            : Read / Write / Construct

A property that controls placement of the overlay of type GdkGravity. GDK_GRAVITY_STATIC is NOT a valid value.

Default value: GDK_GRAVITY_CENTER

### The `"use-source-op"` property

      "use-source-op"            gboolean              : Read / Write

The use-source-op property controls if this overlay replaces graphics already painted beneath the overlay. (support for this has to be implemented by the subclasses)

Default value: FALSE

### The `"x-adj"` property

      "x-adj"                    gdouble               : Read / Write / Construct

An property of type gdouble that allows the adjustment of the horizontal position of the AwnOverlay. Range of -1.0...1.0. The amount of adjustment is this x-adj * width of the AwnIcon. A value of 0.0 indicates that gravity and align will solely determine the x position.

Allowed values: [-1,1]

Default value: 0

### The `"x-override"` property

      "x-override"               gdouble               : Read / Write / Construct

Overrides the x coordinates. In most cases if you're using this then you are probably doing something wrong.

Allowed values: [-10000,1000]

Default value: -10000

### The `"y-adj"` property

      "y-adj"                    gdouble               : Read / Write / Construct

An property of type gdouble that allows the adjustment of the vertical position of the AwnOverlay. Range of -1.0...1.0. The amount of adjustment is this y-adj * height of the AwnIcon. A value of 0.0 indicates that gravity and align will solely determine the y position.

Allowed values: [-1,1]

Default value: 0

### The `"y-override"` property

      "y-override"               gdouble               : Read / Write / Construct

Overrides the y coordinates. In most cases if you're using this then you are probably doing something wrong.

Allowed values: [-10000,1000]

Default value: -10000

## See Also

#AwnOverlayable, AwnEffects, AwnIcon, AwnOverlayText, AwnOverlayThemedIcon, AwnOverlayThrobber