diff --git a/ChangeLog b/ChangeLog index 69fa7ea45b..2ddcb15f74 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +2004-07-15 Michael Natterer + + * app/core/gimpviewable.[ch]: corrected API docs and fixed + function parameter names to silent gtk-doc warnings. + 2004-07-15 Michael Natterer * app/app_procs.c (app_run): register a log handler for the diff --git a/app/core/gimpviewable.c b/app/core/gimpviewable.c index e8f0e81c96..91aa822249 100644 --- a/app/core/gimpviewable.c +++ b/app/core/gimpviewable.c @@ -139,11 +139,8 @@ gimp_viewable_get_type (void) static void gimp_viewable_class_init (GimpViewableClass *klass) { - GObjectClass *object_class; - GimpObjectClass *gimp_object_class; - - object_class = G_OBJECT_CLASS (klass); - gimp_object_class = GIMP_OBJECT_CLASS (klass); + GObjectClass *object_class = G_OBJECT_CLASS (klass); + GimpObjectClass *gimp_object_class = GIMP_OBJECT_CLASS (klass); parent_class = g_type_class_peek_parent (klass); @@ -408,7 +405,7 @@ gimp_viewable_serialize_property (GimpConfig *config, * * Causes any cached preview to be marked as invalid, so that a new * preview will be generated at the next attempt to display one. - */ + **/ void gimp_viewable_invalidate_preview (GimpViewable *viewable) { @@ -424,7 +421,7 @@ gimp_viewable_invalidate_preview (GimpViewable *viewable) * This function sends a signal that is handled at a lower level in the * object hierarchy, and provides a mechanism by which objects derived * from #GimpViewable can respond to size changes. - */ + **/ void gimp_viewable_size_changed (GimpViewable *viewable) { @@ -435,30 +432,32 @@ gimp_viewable_size_changed (GimpViewable *viewable) /** * gimp_viewable_calc_preview_size: - * @aspect_width: unscaled width of the preview for an item. + * @aspect_width: unscaled width of the preview for an item. * @aspect_height: unscaled height of the preview for an item. - * @width: maximum available width for scaled preview. - * @height: maximum available height for scaled preview. - * @dot_for_dot: if #TRUE, ignore any differences in axis resolution. - * @xresolution: resolution in the horizontal direction. - * @yresolution: resolution in the vertical direction. - * @return_width: place to return the calculated preview width. - * @return_height: place to return the calculated preview height. - * @scaling_up: returns #TRUE here if the calculated size change will cause - * the preview to grow. + * @width: maximum available width for scaled preview. + * @height: maximum available height for scaled preview. + * @dot_for_dot: if #TRUE, ignore any differences in axis resolution. + * @xresolution: resolution in the horizontal direction. + * @yresolution: resolution in the vertical direction. + * @return_width: place to return the calculated preview width. + * @return_height: place to return the calculated preview height. + * @scaling_up: returns #TRUE here if the calculated preview size + * is larger than the viewable itself. * - * A utility function, for calculating the dimensions of a preview based - * on the information specified in the arguments. The arguments @aspect_width and - * @aspect_height are the dimensions of the unscaled preview. The arguments - * @width and @height represent the maximum width and height that the scaled - * preview must fit into. The preview is scaled to be as large as possible - * without exceeding these constraints. + * A utility function, for calculating the dimensions of a preview + * based on the information specified in the arguments. The arguments + * @aspect_width and @aspect_height are the dimensions of the unscaled + * preview. The arguments @width and @height represent the maximum + * width and height that the scaled preview must fit into. The + * preview is scaled to be as large as possible without exceeding + * these constraints. * - * If @dot_for_dot is #TRUE, and @xresolution and @yresolution are different, - * then these results are corrected for the difference in resolution on the - * two axes, so that the requested aspect ratio applies to the appearance of - * the display rather than to pixel counts. - */ + * If @dot_for_dot is #TRUE, and @xresolution and @yresolution are + * different, then these results are corrected for the difference in + * resolution on the two axes, so that the requested aspect ratio + * applies to the appearance of the display rather than to pixel + * counts. + **/ void gimp_viewable_calc_preview_size (gint aspect_width, gint aspect_height, @@ -501,19 +500,19 @@ gimp_viewable_calc_preview_size (gint aspect_width, /** * gimp_viewable_get_preview_size: - * @viewable: the object for which to calculate the preview size. - * @size: requested size for preview. - * @popup: ? + * @viewable: the object for which to calculate the preview size. + * @size: requested size for preview. + * @popup: %TRUE if the preview is intended for a popup window. * @dot_for_dot: If #TRUE, ignore any differences in X and Y resolution. - * @width: place to return the calculated width. - * @height: place to return the calculated height. + * @width: return location for the the calculated width. + * @height: return location for the calculated height. * - * Retrieve the size of an object's preview. By default, this simply - * returns the value of the @size argument for both the @width and - * @height, but this can be overridden in objects derived from - * #GimpViewable. If either the width or height exceeds + * Retrieve the size of a viewable's preview. By default, this + * simply returns the value of the @size argument for both the @width + * and @height, but this can be overridden in objects derived from + * #GimpViewable. If either the width or height exceeds * #GIMP_VIEWABLE_MAX_PREVIEW_SIZE, they are silently truncated. - */ + **/ void gimp_viewable_get_preview_size (GimpViewable *viewable, gint size, @@ -541,18 +540,22 @@ gimp_viewable_get_preview_size (GimpViewable *viewable, /** * gimp_viewable_get_popup_size: - * @viewable: the object for which to calculate the popup size. - * @width: requested size for popup. - * @height: requested height for popup. - * @dot_for_dot: If #TRUE, ignore any differences in X and Y resolution. - * @popup_width: place to return the alloted width. - * @popup_height: place to return the alloted height. + * @viewable: the object for which to calculate the popup size. + * @width: the width of the preview from which the popup will be shown. + * @height: the height of the preview from which the popup will be shown. + * @dot_for_dot: If #TRUE, ignore any differences in X and Y resolution. + * @popup_width: return location for the calculated popup width. + * @popup_height: return location for the calculated popup height. * - * Calculate the size of an object's preview, for use in making a popup. - * The arguments @width and @height specify the maximum dimensions that - * will be returned, but they can be reduced if any of a variety of - * constraints is violated. - */ + * Calculate the size of a viewable's preview, for use in making a + * popup. The arguments @width and @height specify the size of the + * preview from which the popup will be shown. + * + * Returns: Whether the viewable wants a popup to be shown. Usually + * %TRUE if the passed preview size is smaller than the viewable + * size, and %FALSE if the viewable completely fits into the + * original preview. + **/ gboolean gimp_viewable_get_popup_size (GimpViewable *viewable, gint width, @@ -621,21 +624,22 @@ gimp_viewable_get_popup_size (GimpViewable *viewable, /** * gimp_viewable_get_preview: * @viewable: The viewable object to get a preview for. - * @width: desired width for the preview - * @height: desired height for the preview + * @width: desired width for the preview + * @height: desired height for the preview * * Gets a preview for a viewable object, by running through a variety - * of methods until it finds one that works. First, if an implementation - * exists of a "get_preview" method, it is tried, and the result is - * returned if it is not #NULL. Second, the function checks to see - * whether there is a cached preview with the correct dimensions; if - * so, it is returned. If neither of these works, then the function - * looks for an implementation of the "get_new_preview" method, and - * executes it, caching the result. If everything fails, #NULL is returned. + * of methods until it finds one that works. First, if an + * implementation exists of a "get_preview" method, it is tried, and + * the result is returned if it is not #NULL. Second, the function + * checks to see whether there is a cached preview with the correct + * dimensions; if so, it is returned. If neither of these works, then + * the function looks for an implementation of the "get_new_preview" + * method, and executes it, caching the result. If everything fails, + * #NULL is returned. * * Returns: A #TempBuf containg the preview image, or #NULL if none can - * be found or created. - */ + * be found or created. + **/ TempBuf * gimp_viewable_get_preview (GimpViewable *viewable, gint width, @@ -678,17 +682,18 @@ gimp_viewable_get_preview (GimpViewable *viewable, /** * gimp_viewable_get_new_preview: * @viewable: The viewable object to get a preview for. - * @width: desired width for the preview - * @height: desired height for the preview + * @width: desired width for the preview + * @height: desired height for the preview * - * Gets a new preview for a viewable object. Similar to gimp_viewable_get_preview(), - * except that it tries things in a different order, first looking for - * a "get_new_preview" method, and then if that fails for a "get_preview" - * method. This function does not look for a cached preview. + * Gets a new preview for a viewable object. Similar to + * gimp_viewable_get_preview(), except that it tries things in a + * different order, first looking for a "get_new_preview" method, and + * then if that fails for a "get_preview" method. This function does + * not look for a cached preview. * * Returns: A #TempBuf containg the preview image, or #NULL if none can - * be found or created. - */ + * be found or created. + **/ TempBuf * gimp_viewable_get_new_preview (GimpViewable *viewable, gint width, @@ -721,17 +726,17 @@ gimp_viewable_get_new_preview (GimpViewable *viewable, /** * gimp_viewable_get_dummy_preview: * @viewable: viewable object for which to get a dummy preview. - * @width: width of the preview. - * @height: height of the preview. - * @bpp: bytes per pixel for the preview, must be 3 or 4. + * @width: width of the preview. + * @height: height of the preview. + * @bpp: bytes per pixel for the preview, must be 3 or 4. * * Creates a dummy preview the fits into the specified dimensions, - * containing a default "question" symbol. This function is used - * to generate a preview in situations where layer previews have been + * containing a default "question" symbol. This function is used to + * generate a preview in situations where layer previews have been * disabled in the current Gimp configuration. * * Returns: a #TempBuf containing the preview image. - */ + **/ TempBuf * gimp_viewable_get_dummy_preview (GimpViewable *viewable, gint width, @@ -771,21 +776,22 @@ gimp_viewable_get_dummy_preview (GimpViewable *viewable, /** * gimp_viewable_get_pixbuf: * @viewable: The viewable object to get a pixbuf preview for. - * @width: desired width for the preview - * @height: desired height for the preview + * @width: desired width for the preview + * @height: desired height for the preview * * Gets a preview for a viewable object, by running through a variety - * of methods until it finds one that works. First, if an implementation - * exists of a "get_pixbuf" method, it is tried, and the result is - * returned if it is not #NULL. Second, the function checks to see - * whether there is a cached preview with the correct dimensions; if - * so, it is returned. If neither of these works, then the function - * looks for an implementation of the "get_new_pixbuf" method, and - * executes it, caching the result. If everything fails, #NULL is returned. + * of methods until it finds one that works. First, if an + * implementation exists of a "get_pixbuf" method, it is tried, and + * the result is returned if it is not #NULL. Second, the function + * checks to see whether there is a cached preview with the correct + * dimensions; if so, it is returned. If neither of these works, then + * the function looks for an implementation of the "get_new_pixbuf" + * method, and executes it, caching the result. If everything fails, + * #NULL is returned. * * Returns: A #GdkPixbuf containing the preview pixbuf, or #NULL if none can - * be found or created. - */ + * be found or created. + **/ GdkPixbuf * gimp_viewable_get_pixbuf (GimpViewable *viewable, gint width, @@ -828,17 +834,18 @@ gimp_viewable_get_pixbuf (GimpViewable *viewable, /** * gimp_viewable_get_new_pixbuf: * @viewable: The viewable object to get a new pixbuf preview for. - * @width: desired width for the pixbuf - * @height: desired height for the pixbuf + * @width: desired width for the pixbuf + * @height: desired height for the pixbuf * - * Gets a new preview for a viewable object. Similar to gimp_viewable_get_pixbuf(), - * except that it tries things in a different order, first looking for - * a "get_new_pixbuf" method, and then if that fails for a "get_pixbuf" - * method. This function does not look for a cached pixbuf. + * Gets a new preview for a viewable object. Similar to + * gimp_viewable_get_pixbuf(), except that it tries things in a + * different order, first looking for a "get_new_pixbuf" method, and + * then if that fails for a "get_pixbuf" method. This function does + * not look for a cached pixbuf. * * Returns: A #GdkPixbuf containing the preview, or #NULL if none can - * be created. - */ + * be created. + **/ GdkPixbuf * gimp_viewable_get_new_pixbuf (GimpViewable *viewable, gint width, @@ -871,19 +878,20 @@ gimp_viewable_get_new_pixbuf (GimpViewable *viewable, /** * gimp_viewable_get_dummy_pixbuf: * @viewable: the viewable object for which to create a dummy representation. - * @width: maximum permitted width for the pixbuf. - * @height: maximum permitted height for the pixbuf. - * @bpp: bytes per pixel for the pixbuf, must equal 3 or 4. + * @width: maximum permitted width for the pixbuf. + * @height: maximum permitted height for the pixbuf. + * @bpp: bytes per pixel for the pixbuf, must equal 3 or 4. * - * Creates a pixbuf containing a default "question" symbol, sized to fit - * into the specified dimensions. The depth of the pixbuf must be 3 or 4 - * because #GdkPixbuf does not support grayscale. This function is used - * to generate a preview in situations where previewing has been disabled - * in the current Gimp configuration. [Note: this function is currently - * unused except internally to #GimpViewable -- consider making it static?] + * Creates a pixbuf containing a default "question" symbol, sized to + * fit into the specified dimensions. The depth of the pixbuf must be + * 3 or 4 because #GdkPixbuf does not support grayscale. This + * function is used to generate a preview in situations where + * previewing has been disabled in the current Gimp configuration. + * [Note: this function is currently unused except internally to + * #GimpViewable -- consider making it static?] * * Returns: the created #GdkPixbuf. - */ + **/ GdkPixbuf * gimp_viewable_get_dummy_pixbuf (GimpViewable *viewable, gint width, @@ -930,15 +938,15 @@ gimp_viewable_get_dummy_pixbuf (GimpViewable *viewable, /** * gimp_viewable_get_description: * @viewable: viewable object for which to retrieve a description. - * @tooltip: place to put a pointer to the description string. + * @tooltip: return loaction for an optional tooltip string. * * Retrieves a string containing a description of the viewable object, - * By default, it simply returns the name of the object, but this - * can be overridden by object types that inherit from #GimpViewable. + * By default, it simply returns the name of the object, but this can + * be overridden by object types that inherit from #GimpViewable. * * Returns: a copy of the description string. This should be freed - * when it is no longer needed. - */ + * when it is no longer needed. + **/ gchar * gimp_viewable_get_description (GimpViewable *viewable, gchar **tooltip) @@ -957,8 +965,8 @@ gimp_viewable_get_description (GimpViewable *viewable, * constructing an iconic representation of the object. * * Returns: a pointer to the string containing the stock ID. The - * contents must not be altered or freed. - */ + * contents must not be altered or freed. + **/ const gchar * gimp_viewable_get_stock_id (GimpViewable *viewable) { @@ -975,11 +983,10 @@ gimp_viewable_get_stock_id (GimpViewable *viewable) * @viewable: viewable object to assign the specified stock ID. * @stock_id: string containing a stock identifier. * - * Seta the object's stock ID, for use in - * constructing iconic smbols of the object. The contents - * of @stock_id are copied, so it should be freed when you - * are done with it.. - */ + * Seta the object's stock ID, for use in constructing iconic smbols + * of the object. The contents of @stock_id are copied, so you can + * free it when you are done with it. + **/ void gimp_viewable_set_stock_id (GimpViewable *viewable, const gchar *stock_id) diff --git a/app/core/gimpviewable.h b/app/core/gimpviewable.h index 01b60a69d6..545e2da386 100644 --- a/app/core/gimpviewable.h +++ b/app/core/gimpviewable.h @@ -129,7 +129,7 @@ TempBuf * gimp_viewable_get_new_preview (GimpViewable *viewable, gint width, gint height); -TempBuf * gimp_viewable_get_dummy_preview (GimpViewable *vieable, +TempBuf * gimp_viewable_get_dummy_preview (GimpViewable *viewable, gint width, gint height, gint bpp);