mirror of https://github.com/GNOME/gimp.git
corrected API docs and fixed function parameter names to silent gtk-doc
2004-07-15 Michael Natterer <mitch@gimp.org> * app/core/gimpviewable.[ch]: corrected API docs and fixed function parameter names to silent gtk-doc warnings.
This commit is contained in:
Michael Natterer
Michael Natterer
parent
4812d3165a
commit
c9d31f6e97
|
|
@ -1,3 +1,8 @@
|
|||
2004-07-15 Michael Natterer <mitch@gimp.org>
|
||||
|
||||
* app/core/gimpviewable.[ch]: corrected API docs and fixed
|
||||
function parameter names to silent gtk-doc warnings.
|
||||
|
||||
2004-07-15 Michael Natterer <mitch@gimp.org>
|
||||
|
||||
* app/app_procs.c (app_run): register a log handler for the
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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);
|
||||
|
|
|
|||
Loading…
Reference in New Issue