rb-rating-helper

## rb-rating-helper rb-rating-helper — helper functions for displaying song ratings |

## Synopsis

                        RBRatingPixbufs;
    #define             RB_RATING_MAX_SCORE
    gboolean            rb_rating_render_stars              (GtkWidget *widget,
                                                             GdkWindow *window,
                                                             RBRatingPixbufs *pixbufs,
                                                             gulong x,
                                                             gulong y,
                                                             gulong x_offset,
                                                             gulong y_offset,
                                                             gdouble rating,
                                                             gboolean selected);
    double              rb_rating_get_rating_from_widget    (GtkWidget *widget,
                                                             gint widget_x,
                                                             gint widget_width,
                                                             double current_rating);
    RBRatingPixbufs *   rb_rating_pixbufs_new               (void);
    void                rb_rating_pixbufs_free              (RBRatingPixbufs *pixbufs);
    void                rb_rating_install_rating_property   (GObjectClass *klass,
                                                             gulong prop);

## Description

A few helper functions for dealing with ratings. These are shared between RBRating and RBCellRendererRating.

## Details

### RBRatingPixbufs

    typedef struct _RBRatingPixbufs RBRatingPixbufs;

### RB_RATING_MAX_SCORE

    #define RB_RATING_MAX_SCORE 5

### rb_rating_render_stars ()

    gboolean            rb_rating_render_stars              (GtkWidget *widget,
                                                             GdkWindow *window,
                                                             RBRatingPixbufs *pixbufs,
                                                             gulong x,
                                                             gulong y,
                                                             gulong x_offset,
                                                             gulong y_offset,
                                                             gdouble rating,
                                                             gboolean selected);

Renders a rating as a row of stars. floor(`rating`) large stars are drawn, followed by 5-floor(`rating`) small stars.

`widget` : | a GtkWidget to render on behalf of
`window` : | the GdkWindow being rendered to
`pixbufs` : | a RBRatingPixbufs structure
`x` : | source X coordinate within the rating pixbufs (usually 0)
`y` : | source Y coordinate within the rating pixbufs (usually 0)
`x_offset` : | destination X coordinate within the window
`y_offset` : | destination Y coordinate within the window
`rating` : | the rating to display (between 0.0 and 5.0)
`selected` : | TRUE if the widget is currently selected for input
Returns : | TRUE if the stars were drawn successfully

### rb_rating_get_rating_from_widget ()

    double              rb_rating_get_rating_from_widget    (GtkWidget *widget,
                                                             gint widget_x,
                                                             gint widget_width,
                                                             double current_rating);

Updates the rating for a widget after the user clicks on the rating. If the user clicks on the Nth star, the rating is set to N, unless the rating is already N, in which case the rating is set to N-1. This allows the user to set the rating to 0.

`widget` : | the GtkWidget displaying the rating
`widget_x` : | x component of the position to query
`widget_width` : | width of the widget
`current_rating` : | the current rating displayed in the widget
Returns : | the updated rating

### rb_rating_pixbufs_new ()

    RBRatingPixbufs *   rb_rating_pixbufs_new               (void);

Creates and returns a structure holding a set of pixbufs to use to display ratings.

Returns : | RBRatingPixbufs structure, or NULL if not all of the pixbufs could be loaded.

### rb_rating_pixbufs_free ()

    void                rb_rating_pixbufs_free              (RBRatingPixbufs *pixbufs);

Frees a set of rating pixbufs.

`pixbufs` : | RBRatingPixbufs instance

### rb_rating_install_rating_property ()

    void                rb_rating_install_rating_property   (GObjectClass *klass,
                                                             gulong prop);

Installs a 'rating' property in the specified class.

`klass` : | a GObjectClass to add the property to
`prop` : | property index to use