golem
/
twentyGOLEM
9
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

phpdoc for media.php. Props jacobsantos. fixes #7658 

git-svn-id: http://svn.automattic.com/wordpress/trunk@8925 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
ryan 2008-09-18 06:14:46 +00:00
parent 31d4e0f6ab
commit d68fd16abf
1 changed files with 161 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

184
wp-includes/media.php
View File

@ -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 <img src /> 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 <img> 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);