WordPress.org

Make WordPress Core

Changeset 8925


Ignore:
Timestamp:
09/18/2008 06:14:46 AM (13 years ago)
Author:
ryan
Message:

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

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/wp-includes/media.php

    r8792 r8925  
    5454    }
    5555    elseif ( $size == 'large' ) {
    56         // 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
    57         // within the editor itself, and within the theme's content width if it's known.  the user can resize it in the editor
    58         // if they wish.
     56        // we're inserting a large size image into the editor.  if it's a really
     57        // big image we'll scale it down to fit reasonably within the editor
     58        // itself, and within the theme's content width if it's known.  the user
     59        // can resize it in the editor if they wish.
    5960        $max_width = intval(get_option('large_size_w'));
    6061        $max_height = intval(get_option('large_size_h'));
     
    110111 * resized one if it exists.
    111112 *
     113 * A plugin may use the 'image_downsize' filter to hook into and offer image
     114 * resizing services for images. The hook must return an array with the same
     115 * elements that are returned in the function. The first element being the URL
     116 * to the new image that was resized.
     117 *
    112118 * @since 2.5.0
    113119 * @uses apply_filters() Calls 'image_downsize' on $id and $size to provide
    114  *      resize services. Should return true if resizes.
     120 *      resize services.
    115121 *
    116122 * @param int $id Attachment ID for image.
     
    167173 * An <img src /> tag for an image attachment, scaling it down if requested.
    168174 *
    169  * {@internal Missing Long Description}}
     175 * The filter 'get_image_tag_class' allows for changing the class name for the
     176 * image without having to use regular expressions on the HTML content. The
     177 * parameters are: what WordPress will use for the class, the Attachment ID,
     178 * image align value, and the size the image should be.
     179 *
     180 * The second filter 'get_image_tag' has the HTML content, which can then be
     181 * further manipulated by a plugin to change all attribute values and even HTML
     182 * content.
    170183 *
    171184 * @since 2.5.0
     
    198211}
    199212
    200 // same as wp_shrink_dimensions, except the max parameters are optional.
    201 // if either width or height are empty, no constraint is applied on that dimension.
     213/**
     214 * Calculates the new dimentions for a downsampled image.
     215 *
     216 * Same as {@link wp_shrink_dimensions()}, except the max parameters are
     217 * optional. If either width or height are empty, no constraint is applied on
     218 * that dimension.
     219 *
     220 * @since 2.5.0
     221 *
     222 * @param int $current_width Current width of the image.
     223 * @param int $current_height Current height of the image.
     224 * @param int $max_width Optional. Maximum wanted width.
     225 * @param int $max_height Optional. Maximum wanted height.
     226 * @return array First item is the width, the second item is the height.
     227 */
    202228function wp_constrain_dimensions( $current_width, $current_height, $max_width=0, $max_height=0 ) {
    203229    if ( !$max_width and !$max_height )
     
    218244}
    219245
    220 // calculate dimensions and coordinates for a resized image that fits within a specified width and height
    221 // if $crop is true, the largest matching central portion of the image will be cropped out and resized to the required size
     246/**
     247 * Retrieve calculated resized dimensions for use in imagecopyresampled().
     248 *
     249 * Calculate dimensions and coordinates for a resized image that fits within a
     250 * specified width and height. If $crop is true, the largest matching central
     251 * portion of the image will be cropped out and resized to the required size.
     252 *
     253 * @since 2.5.0
     254 *
     255 * @param int $orig_w Original width.
     256 * @param int $orig_h Original height.
     257 * @param int $dest_w New width.
     258 * @param int $dest_h New height.
     259 * @param bool $crop Optional, default is false. Whether to crop image or resize.
     260 * @return bool|array False, on failure. Returned array matches parameters for imagecopyresampled() PHP function.
     261 */
    222262function image_resize_dimensions($orig_w, $orig_h, $dest_w, $dest_h, $crop=false) {
    223263
     
    272312 * Scale down an image to fit a particular size and save a new copy of the image.
    273313 *
    274  * @param unknown_type $file
    275  * @param unknown_type $max_w
    276  * @param unknown_type $max_h
    277  * @param unknown_type $crop
    278  * @param unknown_type $suffix
    279  * @param unknown_type $dest_path
    280  * @param unknown_type $jpeg_quality
    281  * @return unknown
     314 * The PNG transparency will be preserved using the function, as well as the
     315 * image type. If the file going in is PNG, then the resized image is going to
     316 * be PNG. The only supported image types are PNG, GIF, and JPEG.
     317 *
     318 * Some functionality requires API to exist, so some PHP version may lose out
     319 * support. This is not the fault of WordPress (where functionality is
     320 * downgraded, not actual defects), but of your PHP version.
     321 *
     322 * @since 2.5.0
     323 *
     324 * @param string $file Image file path.
     325 * @param int $max_w Maximum width to resize to.
     326 * @param int $max_h Maximum height to resize to.
     327 * @param bool $crop Optional. Whether to crop image or resize.
     328 * @param string $suffix Optional. File Suffix.
     329 * @param string $dest_path Optional. New image file path.
     330 * @param int $jpeg_quality Optional, default is 90. Image quality percentage.
     331 * @return mixed WP_Error on failure. String with new destination path. Array of dimensions from {@link image_resize_dimensions()}
    282332 */
    283333function image_resize( $file, $max_w, $max_h, $crop=false, $suffix=null, $dest_path=null, $jpeg_quality=90) {
     
    343393}
    344394
    345 // resize an image to make a thumbnail or intermediate size, and return metadata describing the new copy
    346 // returns false if no image was created
     395/**
     396 * Resize an image to make a thumbnail or intermediate size.
     397 *
     398 * The returned array has the file size, the image width, and image height. The
     399 * filter 'image_make_intermediate_size' can be used to hook in and change the
     400 * values of the returned array. The only parameter is the resized file path.
     401 *
     402 * @since 2.5.0
     403 *
     404 * @param string $file File path.
     405 * @param int $width Image width.
     406 * @param int $height Image height.
     407 * @param bool $crop Optional, default is false. Whether to crop image to specified height and width or resize.
     408 * @return bool|array False, if no image was created. Metadata array on success.
     409 */
    347410function image_make_intermediate_size($file, $width, $height, $crop=false) {
    348411    if ( $width || $height ) {
     
    360423}
    361424
     425/**
     426 * Retrieve the image's intermediate size (resized) path, width, and height.
     427 *
     428 * The $size parameter can be an array with the width and height respectively.
     429 * If the size matches the 'sizes' metadata array for width and height, then it
     430 * will be used. If there is no direct match, then the nearest image size larger
     431 * than the specified size will be used. If nothing is found, then the function
     432 * will break out and return false.
     433 *
     434 * The metadata 'sizes' is used for compatible sizes that can be used for the
     435 * parameter $size value.
     436 *
     437 * The url path will be given, when the $size parameter is a string.
     438 *
     439 * @since 2.5.0
     440 *
     441 * @param int $post_id Attachment ID for image.
     442 * @param array|string $size Optional, default is 'thumbnail'. Size of image, either array or string.
     443 * @return bool|array False on failure or array of file path, width, and height on success.
     444 */
    362445function image_get_intermediate_size($post_id, $size='thumbnail') {
    363446    if ( !is_array( $imagedata = wp_get_attachment_metadata( $post_id ) ) )
     
    403486}
    404487
    405 // get an image to represent an attachment - a mime icon for files, thumbnail or intermediate size for images
    406 // returns an array (url, width, height), or false if no image is available
     488/**
     489 * Retrieve an image to represent an attachment.
     490 *
     491 * A mime icon for files, thumbnail or intermediate size for images.
     492 *
     493 * @since 2.5.0
     494 *
     495 * @param int $attachment_id Image attachment ID.
     496 * @param string $size Optional, default is 'thumbnail'.
     497 * @param bool $icon Optional, default is false. Whether it is an icon.
     498 * @return bool|array Returns an array (url, width, height), or false, if no image is available.
     499 */
    407500function wp_get_attachment_image_src($attachment_id, $size='thumbnail', $icon = false) {
    408501
     
    421514}
    422515
    423 // as per wp_get_attachment_image_src, but returns an <img> tag
    424 function wp_get_attachment_image($attachment_id, $size='thumbnail', $icon = false) {
     516/**
     517 * Retrieve img HTML content for an image to represent an attachment.
     518 *
     519 * @see wp_get_attachment_image_src() Returns img HTML element based on array.
     520 * @since 2.5.0
     521 *
     522 * @param int $attachment_id Image attachment ID.
     523 * @param string $size Optional, default is 'thumbnail'.
     524 * @param bool $icon Optional, default is false. Whether it is an icon.
     525 * @return string HTML img element or empty string on failure.
     526 */
     527function wp_get_attachment_image($attachment_id, $size = 'thumbnail', $icon = false) {
    425528
    426529    $html = '';
     
    440543add_shortcode('caption', 'img_caption_shortcode');
    441544
     545/**
     546 * The Caption shortcode.
     547 *
     548 * Allows a plugin to replace the content that would otherwise be returned. The
     549 * filter is 'img_caption_shortcode' and passes an empty string, the attr
     550 * parameter and the content parameter values.
     551 *
     552 * The supported attributes for the shortcode are 'id', 'align', 'width', and
     553 * 'caption'.
     554 *
     555 * @since 2.6.0
     556 *
     557 * @param array $attr Attributes attributed to the shortcode.
     558 * @param string $content Optional. Shortcode content.
     559 * @return string
     560 */
    442561function img_caption_shortcode($attr, $content = null) {
    443562
     
    465584add_shortcode('gallery', 'gallery_shortcode');
    466585
     586/**
     587 * The Gallery shortcode.
     588 *
     589 * This implements the functionality of the Gallery Shortcode for displaying
     590 * WordPress images on a post.
     591 *
     592 * @since 2.5.0
     593 *
     594 * @param array $attr Attributes attributed to the shortcode.
     595 * @return string HTML content to display gallery.
     596 */
    467597function gallery_shortcode($attr) {
    468598    global $post;
     
    597727}
    598728
     729/**
     730 * Retrieve taxonomies attached to the attachment.
     731 *
     732 * @since 2.5.0
     733 *
     734 * @param int|array|object $attachment Attachment ID, Attachment data array, or Attachment data object.
     735 * @return array Empty array on failure. List of taxonomies on success.
     736 */
    599737function get_attachment_taxonomies($attachment) {
    600738    if ( is_int( $attachment ) )
Note: See TracChangeset for help on using the changeset viewer.