HdyCarousel: Handy Reference Manual

## HdyCarousel HdyCarousel — A paginated scrolling widget. |

## Functions

GtkWidget * | hdy_carousel_new ()
void | hdy_carousel_prepend ()
void | hdy_carousel_insert ()
void | hdy_carousel_reorder ()
void | hdy_carousel_scroll_to ()
void | hdy_carousel_scroll_to_full ()
guint | hdy_carousel_get_n_pages ()
gdouble | hdy_carousel_get_position ()
gboolean | hdy_carousel_get_interactive ()
void | hdy_carousel_set_interactive ()
guint | hdy_carousel_get_spacing ()
void | hdy_carousel_set_spacing ()
guint | hdy_carousel_get_animation_duration ()
void | hdy_carousel_set_animation_duration ()
gboolean | hdy_carousel_get_allow_mouse_drag ()
void | hdy_carousel_set_allow_mouse_drag ()
gboolean | hdy_carousel_get_allow_scroll_wheel ()
void | hdy_carousel_set_allow_scroll_wheel ()
gboolean | hdy_carousel_get_allow_long_swipes ()
void | hdy_carousel_set_allow_long_swipes ()
guint | hdy_carousel_get_reveal_duration ()
void | hdy_carousel_set_reveal_duration ()

## Properties

gboolean | allow-long-swipes | Read / Write
gboolean | allow-mouse-drag | Read / Write
gboolean | allow-scroll-wheel | Read / Write
guint | animation-duration | Read / Write
gboolean | interactive | Read / Write
guint | n-pages | Read
double | position | Read
guint | reveal-duration | Read / Write
guint | spacing | Read / Write

## Signals

void | page-changed | Run Last

## Types and Values

#define | HDY_TYPE_CAROUSEL
| HdyCarousel

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GtkWidget
                ╰── GtkContainer
                    ╰── GtkBin
                        ╰── GtkEventBox
                            ╰── HdyCarousel

## Implemented Interfaces

HdyCarousel implements AtkImplementorIface, GtkBuildable, GtkOrientable and HdySwipeable.

## Description

The HdyCarousel widget can be used to display a set of pages with swipe-based navigation between them.

### CSS nodes

HdyCarousel has a single CSS node with name carousel.

## Functions

### hdy_carousel_new ()

    GtkWidget *
    hdy_carousel_new (void);

Create a new HdyCarousel widget.

#### Returns

The newly created HdyCarousel widget

Since: 1.0

### hdy_carousel_prepend ()

    void
    hdy_carousel_prepend (HdyCarousel *self,
                          GtkWidget *child);

Prepends `child` to `self`

#### Parameters

self | a HdyCarousel |
child | a widget to add |

Since: 1.0

### hdy_carousel_insert ()

    void
    hdy_carousel_insert (HdyCarousel *self,
                         GtkWidget *child,
                         gint position);

Inserts `child` into `self` at position `position` .

If position is -1, or larger than the number of pages, `child` will be appended to the end.

#### Parameters

self | a HdyCarousel |
child | a widget to add |
position | the position to insert `child` in. |

Since: 1.0

### hdy_carousel_reorder ()

    void
    hdy_carousel_reorder (HdyCarousel *self,
                          GtkWidget *child,
                          gint position);

Moves `child` into position `position` .

If position is -1, or larger than the number of pages, `child` will be moved to the end.

#### Parameters

self | a HdyCarousel |
child | a widget to add |
position | the position to move `child` to. |

Since: 1.0

### hdy_carousel_scroll_to ()

    void
    hdy_carousel_scroll_to (HdyCarousel *self,
                            GtkWidget *widget);

Scrolls to `widget` position with an animation. “animation-duration” property can be used for controlling the duration.

#### Parameters

self | a HdyCarousel |
widget | a child of `self` |

Since: 1.0

### hdy_carousel_scroll_to_full ()

    void
    hdy_carousel_scroll_to_full (HdyCarousel *self,
                                 GtkWidget *widget,
                                 gint64 duration);

Scrolls to `widget` position with an animation.

#### Parameters

self | a HdyCarousel |
widget | a child of `self` |
duration | animation duration in milliseconds |

Since: 1.0

### hdy_carousel_get_n_pages ()

    guint
    hdy_carousel_get_n_pages (HdyCarousel *self);

Gets the number of pages in `self` .

#### Parameters

self | a HdyCarousel |

#### Returns

The number of pages in `self`

Since: 1.0

### hdy_carousel_get_position ()

    gdouble
    hdy_carousel_get_position (HdyCarousel *self);

Gets current scroll position in `self` . It's unitless, 1 matches 1 page.

#### Parameters

self | a HdyCarousel |

#### Returns

The scroll position

Since: 1.0

### hdy_carousel_get_interactive ()

    gboolean
    hdy_carousel_get_interactive (HdyCarousel *self);

Gets whether `self` can be navigated.

#### Parameters

self | a HdyCarousel |

#### Returns

`TRUE` if `self` can be swiped

Since: 1.0

### hdy_carousel_set_interactive ()

    void
    hdy_carousel_set_interactive (HdyCarousel *self,
                                  gboolean interactive);

Sets whether `self` can be navigated. This can be used to temporarily disable a HdyCarousel to only allow swiping in a certain state.

#### Parameters

self | a HdyCarousel |
interactive | whether `self` can be swiped. |

Since: 1.0

### hdy_carousel_get_spacing ()

    guint
    hdy_carousel_get_spacing (HdyCarousel *self);

Gets spacing between pages in pixels.

#### Parameters

self | a HdyCarousel |

#### Returns

Spacing between pages

Since: 1.0

### hdy_carousel_set_spacing ()

    void
    hdy_carousel_set_spacing (HdyCarousel *self,
                              guint spacing);

Sets spacing between pages in pixels.

#### Parameters

self | a HdyCarousel |
spacing | the new spacing value |

Since: 1.0

### hdy_carousel_get_animation_duration ()

    guint
    hdy_carousel_get_animation_duration (HdyCarousel *self);

Gets animation duration used by `hdy_carousel_scroll_to()`.

#### Parameters

self | a HdyCarousel |

#### Returns

Animation duration in milliseconds

Since: 1.0

### hdy_carousel_set_animation_duration ()

    void
    hdy_carousel_set_animation_duration (HdyCarousel *self,
                                         guint duration);

Sets animation duration used by `hdy_carousel_scroll_to()`.

#### Parameters

self | a HdyCarousel |
duration | animation duration in milliseconds |

Since: 1.0

### hdy_carousel_get_allow_mouse_drag ()

    gboolean
    hdy_carousel_get_allow_mouse_drag (HdyCarousel *self);

Sets whether `self` can be dragged with mouse pointer

#### Parameters

self | a HdyCarousel |

#### Returns

`TRUE` if `self` can be dragged with mouse

Since: 1.0

### hdy_carousel_set_allow_mouse_drag ()

    void
    hdy_carousel_set_allow_mouse_drag (HdyCarousel *self,
                                       gboolean allow_mouse_drag);

Sets whether `self` can be dragged with mouse pointer. If `allow_mouse_drag` is `FALSE`, dragging is only available on touch.

#### Parameters

self | a HdyCarousel |
allow_mouse_drag | whether `self` can be dragged with mouse pointer |

Since: 1.0

### hdy_carousel_get_allow_scroll_wheel ()

    gboolean
    hdy_carousel_get_allow_scroll_wheel (HdyCarousel *self);

Gets whether `self` will respond to scroll wheel events.

#### Parameters

self | a HdyCarousel |

#### Returns

`TRUE` if `self` will respond to scroll wheel events

Since: 1.4

### hdy_carousel_set_allow_scroll_wheel ()

    void
    hdy_carousel_set_allow_scroll_wheel (HdyCarousel *self,
                                         gboolean allow_scroll_wheel);

Sets whether `self` will respond to scroll wheel events. If the value is `FALSE`, wheel events will be ignored.

#### Parameters

self | a HdyCarousel |
allow_scroll_wheel | whether `self` will respond to scroll wheel events. |

Since: 1.4

### hdy_carousel_get_allow_long_swipes ()

    gboolean
    hdy_carousel_get_allow_long_swipes (HdyCarousel *self);

Whether to allow swiping for more than one page at a time. If the value is `FALSE`, each swipe can only move to the adjacent pages.

#### Parameters

self | a HdyCarousel |

#### Returns

`TRUE` if long swipes are allowed, `FALSE` otherwise

Since: 1.2

### hdy_carousel_set_allow_long_swipes ()

    void
    hdy_carousel_set_allow_long_swipes (HdyCarousel *self,
                                        gboolean allow_long_swipes);

Sets whether to allow swiping for more than one page at a time. If the value is `FALSE`, each swipe can only move to the adjacent pages.

#### Parameters

self | a HdyCarousel |
allow_long_swipes | whether to allow long swipes |

Since: 1.2

### hdy_carousel_get_reveal_duration ()

    guint
    hdy_carousel_get_reveal_duration (HdyCarousel *self);

Gets duration of the animation used when adding or removing pages in milliseconds.

#### Parameters

self | a HdyCarousel |

#### Returns

Page reveal duration

Since: 1.0

### hdy_carousel_set_reveal_duration ()

    void
    hdy_carousel_set_reveal_duration (HdyCarousel *self,
                                      guint reveal_duration);

Sets duration of the animation used when adding or removing pages in milliseconds.

#### Parameters

self | a HdyCarousel |
reveal_duration | the new reveal duration value |

Since: 1.0

## Types and Values

### HDY_TYPE_CAROUSEL

    #define HDY_TYPE_CAROUSEL (hdy_carousel_get_type())

### HdyCarousel

    typedef struct _HdyCarousel HdyCarousel;

## Property Details

### The `“allow-long-swipes”` property

      “allow-long-swipes”        gboolean

Whether to allow swiping for more than one page at a time. If the value is `FALSE`, each swipe can only move to the adjacent pages.

Owner: HdyCarousel

Flags: Read / Write

Default value: FALSE

Since: 1.2

### The `“allow-mouse-drag”` property

      “allow-mouse-drag”         gboolean

Sets whether the HdyCarousel can be dragged with mouse pointer. If the value is `FALSE`, dragging is only available on touch.

Owner: HdyCarousel

Flags: Read / Write

Default value: TRUE

Since: 1.0

### The `“allow-scroll-wheel”` property

      “allow-scroll-wheel”       gboolean

Whether the widget will respond to scroll wheel events. If the value is `FALSE`, wheel events will be ignored.

Owner: HdyCarousel

Flags: Read / Write

Default value: TRUE

Since: 1.4

### The `“animation-duration”` property

      “animation-duration”       guint

Animation duration in milliseconds, used by `hdy_carousel_scroll_to()`.

Owner: HdyCarousel

Flags: Read / Write

Default value: 250

Since: 1.0

### The `“interactive”` property

      “interactive”              gboolean

Whether the carousel can be navigated. This can be used to temporarily disable a HdyCarousel to only allow navigating it in a certain state.

Owner: HdyCarousel

Flags: Read / Write

Default value: TRUE

Since: 1.0

### The `“n-pages”` property

      “n-pages”                  guint

The number of pages in a HdyCarousel

Owner: HdyCarousel

Flags: Read

Default value: 0

Since: 1.0

### The `“position”` property

      “position”                 double

Current scrolling position, unitless. 1 matches 1 page. Use `hdy_carousel_scroll_to()` for changing it.

Owner: HdyCarousel

Flags: Read

Allowed values: >= 0

Default value: 0

Since: 1.0

### The `“reveal-duration”` property

      “reveal-duration”          guint

Page reveal duration in milliseconds.

Owner: HdyCarousel

Flags: Read / Write

Default value: 0

Since: 1.0

### The `“spacing”` property

      “spacing”                  guint

Spacing between pages in pixels.

Owner: HdyCarousel

Flags: Read / Write

Default value: 0

Since: 1.0

## Signal Details

### The `“page-changed”` signal

    void
    user_function (HdyCarousel *self,
                   guint        index,
                   gpointer     user_data)

This signal is emitted after a page has been changed. This can be used to implement "infinite scrolling" by connecting to this signal and amending the pages.

#### Parameters

self | The HdyCarousel instance |
index | Current page |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 1.0

## See Also

HdyCarouselIndicatorDots, HdyCarouselIndicatorLines