From d68fd16abff80a51a6c8d91ecedc1d6508e7ffa3 Mon Sep 17 00:00:00 2001 From: ryan Date: Thu, 18 Sep 2008 06:14:46 +0000 Subject: [PATCH] phpdoc for media.php. Props jacobsantos. fixes #7658 git-svn-id: http://svn.automattic.com/wordpress/trunk@8925 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-includes/media.php | 184 ++++++++++++++++++++++++++++++++++++------ 1 file changed, 161 insertions(+), 23 deletions(-) diff --git a/wp-includes/media.php b/wp-includes/media.php index 6137e9b85..0ed7caf29 100644 --- a/wp-includes/media.php +++ b/wp-includes/media.php @@ -53,9 +53,10 @@ function image_constrain_size_for_editor($width, $height, $size = 'medium') { // if no width is set, default to the theme content width if available } elseif ( $size == 'large' ) { - // we're inserting a large size image into the editor. if it's a really big image we'll scale it down to fit reasonably - // within the editor itself, and within the theme's content width if it's known. the user can resize it in the editor - // if they wish. + // we're inserting a large size image into the editor. if it's a really + // big image we'll scale it down to fit reasonably within the editor + // itself, and within the theme's content width if it's known. the user + // can resize it in the editor if they wish. $max_width = intval(get_option('large_size_w')); $max_height = intval(get_option('large_size_h')); if ( intval($content_width) > 0 ) @@ -109,9 +110,14 @@ function image_hwstring($width, $height) { * function won't create a new resized copy, it will just return an already * resized one if it exists. * + * A plugin may use the 'image_downsize' filter to hook into and offer image + * resizing services for images. The hook must return an array with the same + * elements that are returned in the function. The first element being the URL + * to the new image that was resized. + * * @since 2.5.0 * @uses apply_filters() Calls 'image_downsize' on $id and $size to provide - * resize services. Should return true if resizes. + * resize services. * * @param int $id Attachment ID for image. * @param string $size Optional, default is 'medium'. Size of image, can be 'thumbnail'. @@ -166,7 +172,14 @@ function image_downsize($id, $size = 'medium') { /** * An tag for an image attachment, scaling it down if requested. * - * {@internal Missing Long Description}} + * The filter 'get_image_tag_class' allows for changing the class name for the + * image without having to use regular expressions on the HTML content. The + * parameters are: what WordPress will use for the class, the Attachment ID, + * image align value, and the size the image should be. + * + * The second filter 'get_image_tag' has the HTML content, which can then be + * further manipulated by a plugin to change all attribute values and even HTML + * content. * * @since 2.5.0 * @@ -197,8 +210,21 @@ function get_image_tag($id, $alt, $title, $align, $size='medium') { return $html; } -// same as wp_shrink_dimensions, except the max parameters are optional. -// if either width or height are empty, no constraint is applied on that dimension. +/** + * Calculates the new dimentions for a downsampled image. + * + * Same as {@link wp_shrink_dimensions()}, except the max parameters are + * optional. If either width or height are empty, no constraint is applied on + * that dimension. + * + * @since 2.5.0 + * + * @param int $current_width Current width of the image. + * @param int $current_height Current height of the image. + * @param int $max_width Optional. Maximum wanted width. + * @param int $max_height Optional. Maximum wanted height. + * @return array First item is the width, the second item is the height. + */ function wp_constrain_dimensions( $current_width, $current_height, $max_width=0, $max_height=0 ) { if ( !$max_width and !$max_height ) return array( $current_width, $current_height ); @@ -217,8 +243,22 @@ function wp_constrain_dimensions( $current_width, $current_height, $max_width=0, return array( intval($current_width * $ratio), intval($current_height * $ratio) ); } -// calculate dimensions and coordinates for a resized image that fits within a specified width and height -// if $crop is true, the largest matching central portion of the image will be cropped out and resized to the required size +/** + * Retrieve calculated resized dimensions for use in imagecopyresampled(). + * + * Calculate dimensions and coordinates for a resized image that fits within a + * specified width and height. If $crop is true, the largest matching central + * portion of the image will be cropped out and resized to the required size. + * + * @since 2.5.0 + * + * @param int $orig_w Original width. + * @param int $orig_h Original height. + * @param int $dest_w New width. + * @param int $dest_h New height. + * @param bool $crop Optional, default is false. Whether to crop image or resize. + * @return bool|array False, on failure. Returned array matches parameters for imagecopyresampled() PHP function. + */ function image_resize_dimensions($orig_w, $orig_h, $dest_w, $dest_h, $crop=false) { if ($orig_w <= 0 || $orig_h <= 0) @@ -271,14 +311,24 @@ function image_resize_dimensions($orig_w, $orig_h, $dest_w, $dest_h, $crop=false /** * Scale down an image to fit a particular size and save a new copy of the image. * - * @param unknown_type $file - * @param unknown_type $max_w - * @param unknown_type $max_h - * @param unknown_type $crop - * @param unknown_type $suffix - * @param unknown_type $dest_path - * @param unknown_type $jpeg_quality - * @return unknown + * The PNG transparency will be preserved using the function, as well as the + * image type. If the file going in is PNG, then the resized image is going to + * be PNG. The only supported image types are PNG, GIF, and JPEG. + * + * Some functionality requires API to exist, so some PHP version may lose out + * support. This is not the fault of WordPress (where functionality is + * downgraded, not actual defects), but of your PHP version. + * + * @since 2.5.0 + * + * @param string $file Image file path. + * @param int $max_w Maximum width to resize to. + * @param int $max_h Maximum height to resize to. + * @param bool $crop Optional. Whether to crop image or resize. + * @param string $suffix Optional. File Suffix. + * @param string $dest_path Optional. New image file path. + * @param int $jpeg_quality Optional, default is 90. Image quality percentage. + * @return mixed WP_Error on failure. String with new destination path. Array of dimensions from {@link image_resize_dimensions()} */ function image_resize( $file, $max_w, $max_h, $crop=false, $suffix=null, $dest_path=null, $jpeg_quality=90) { @@ -342,8 +392,21 @@ function image_resize( $file, $max_w, $max_h, $crop=false, $suffix=null, $dest_p return $destfilename; } -// resize an image to make a thumbnail or intermediate size, and return metadata describing the new copy -// returns false if no image was created +/** + * Resize an image to make a thumbnail or intermediate size. + * + * The returned array has the file size, the image width, and image height. The + * filter 'image_make_intermediate_size' can be used to hook in and change the + * values of the returned array. The only parameter is the resized file path. + * + * @since 2.5.0 + * + * @param string $file File path. + * @param int $width Image width. + * @param int $height Image height. + * @param bool $crop Optional, default is false. Whether to crop image to specified height and width or resize. + * @return bool|array False, if no image was created. Metadata array on success. + */ function image_make_intermediate_size($file, $width, $height, $crop=false) { if ( $width || $height ) { $resized_file = image_resize($file, $width, $height, $crop); @@ -359,6 +422,26 @@ function image_make_intermediate_size($file, $width, $height, $crop=false) { return false; } +/** + * Retrieve the image's intermediate size (resized) path, width, and height. + * + * The $size parameter can be an array with the width and height respectively. + * If the size matches the 'sizes' metadata array for width and height, then it + * will be used. If there is no direct match, then the nearest image size larger + * than the specified size will be used. If nothing is found, then the function + * will break out and return false. + * + * The metadata 'sizes' is used for compatible sizes that can be used for the + * parameter $size value. + * + * The url path will be given, when the $size parameter is a string. + * + * @since 2.5.0 + * + * @param int $post_id Attachment ID for image. + * @param array|string $size Optional, default is 'thumbnail'. Size of image, either array or string. + * @return bool|array False on failure or array of file path, width, and height on success. + */ function image_get_intermediate_size($post_id, $size='thumbnail') { if ( !is_array( $imagedata = wp_get_attachment_metadata( $post_id ) ) ) return false; @@ -402,8 +485,18 @@ function image_get_intermediate_size($post_id, $size='thumbnail') { return $data; } -// get an image to represent an attachment - a mime icon for files, thumbnail or intermediate size for images -// returns an array (url, width, height), or false if no image is available +/** + * Retrieve an image to represent an attachment. + * + * A mime icon for files, thumbnail or intermediate size for images. + * + * @since 2.5.0 + * + * @param int $attachment_id Image attachment ID. + * @param string $size Optional, default is 'thumbnail'. + * @param bool $icon Optional, default is false. Whether it is an icon. + * @return bool|array Returns an array (url, width, height), or false, if no image is available. + */ function wp_get_attachment_image_src($attachment_id, $size='thumbnail', $icon = false) { // get a thumbnail or intermediate image if there is one @@ -420,8 +513,18 @@ function wp_get_attachment_image_src($attachment_id, $size='thumbnail', $icon = return false; } -// as per wp_get_attachment_image_src, but returns an tag -function wp_get_attachment_image($attachment_id, $size='thumbnail', $icon = false) { +/** + * Retrieve img HTML content for an image to represent an attachment. + * + * @see wp_get_attachment_image_src() Returns img HTML element based on array. + * @since 2.5.0 + * + * @param int $attachment_id Image attachment ID. + * @param string $size Optional, default is 'thumbnail'. + * @param bool $icon Optional, default is false. Whether it is an icon. + * @return string HTML img element or empty string on failure. + */ +function wp_get_attachment_image($attachment_id, $size = 'thumbnail', $icon = false) { $html = ''; $image = wp_get_attachment_image_src($attachment_id, $size, $icon); @@ -439,6 +542,22 @@ function wp_get_attachment_image($attachment_id, $size='thumbnail', $icon = fals add_shortcode('wp_caption', 'img_caption_shortcode'); add_shortcode('caption', 'img_caption_shortcode'); +/** + * The Caption shortcode. + * + * Allows a plugin to replace the content that would otherwise be returned. The + * filter is 'img_caption_shortcode' and passes an empty string, the attr + * parameter and the content parameter values. + * + * The supported attributes for the shortcode are 'id', 'align', 'width', and + * 'caption'. + * + * @since 2.6.0 + * + * @param array $attr Attributes attributed to the shortcode. + * @param string $content Optional. Shortcode content. + * @return string + */ function img_caption_shortcode($attr, $content = null) { // Allow plugins/themes to override the default caption template. @@ -464,6 +583,17 @@ function img_caption_shortcode($attr, $content = null) { add_shortcode('gallery', 'gallery_shortcode'); +/** + * The Gallery shortcode. + * + * This implements the functionality of the Gallery Shortcode for displaying + * WordPress images on a post. + * + * @since 2.5.0 + * + * @param array $attr Attributes attributed to the shortcode. + * @return string HTML content to display gallery. + */ function gallery_shortcode($attr) { global $post; @@ -596,6 +726,14 @@ function adjacent_image_link($prev = true) { echo wp_get_attachment_link($attachments[$k]->ID, 'thumbnail', true); } +/** + * Retrieve taxonomies attached to the attachment. + * + * @since 2.5.0 + * + * @param int|array|object $attachment Attachment ID, Attachment data array, or Attachment data object. + * @return array Empty array on failure. List of taxonomies on success. + */ function get_attachment_taxonomies($attachment) { if ( is_int( $attachment ) ) $attachment = get_post($attachment);