WordPress.org
Get WordPress

Make WordPress Core

Changeset 8960


Ignore:
Timestamp:
09/23/2008 04:03:28 AM (17 years ago)
Author:
ryan
Message:

phpdoc for widgets.php. Props jacobsantos. fixes #7661

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/wp-includes/widgets.php

    r8950 r8960  
    3636
    3737/**
     38 * Stores the registered widget control (options).
    3839 *
    3940 * @global array $wp_registered_widget_controls
    … …  
    171172
    172173/**
    173  * {@internal Missing Short Description}}
    174  *
    175  * {@internal Missing Long Description}}
     174 * Register widget for sidebar with backwards compatibility.
     175 *
     176 * Allows $name to be an array that accepts either three elements to grab the
     177 * first element and the third for the name or just uses the first element of
     178 * the array for the name.
     179 *
     180 * Passes to {@link wp_register_sidebar_widget()} after argument list and
     181 * backwards compatibility is complete.
    176182 *
    177183 * @since 2.2.0
    178184 * @uses wp_register_sidebar_widget() Passes the compiled arguments.
    179185 *
    180  * @param string $name
    181  * @param callback $output_callback
    182  * @param string $classname
     186 * @param string|int $name Widget ID.
     187 * @param callback $output_callback Run when widget is called.
     188 * @param string $classname Classname widget option.
     189 * @param mixed $params,... Widget parameters.
    183190 */
    184191function register_sidebar_widget($name, $output_callback, $classname = '') {
    … …  
    204211
    205212/**
    206  * {@internal Missing Short Description}}
    207  *
    208  * {@internal Missing Long Description}}
    209  *
    210  * @since 2.2.0
    211  *
    212  * @uses $wp_registered_widgets {@internal Missing Description}}
    213  * @uses $wp_register_widget_defaults {@internal Missing Description}}
    214  *
    215  * @param int $id {@internal Missing Description}}
    216  * @param string $name {@internal Missing Description}}
    217  * @param callback $output_callback {@internal Missing Description}}
    218  * @param array|string $options {@internal Missing Description}}
    219  * @return null Will return if $output_callback is empty
     213 * Register widget for use in sidebars.
     214 *
     215 * The default widget option is 'classname' that can be override.
     216 *
     217 * The function can also be used to unregister widgets when $output_callback
     218 * parameter is an empty string.
     219 *
     220 * @since 2.2.0
     221 *
     222 * @uses $wp_registered_widgets Uses stored registered widgets.
     223 * @uses $wp_register_widget_defaults Retrieves widget defaults.
     224 *
     225 * @param int|string $id Widget ID.
     226 * @param string $name Widget display title.
     227 * @param callback $output_callback Run when widget is called.
     228 * @param array|string Optional. $options Widget Options.
     229 * @param mixed $params,... Widget parameters to add to widget.
     230 * @return null Will return if $output_callback is empty after removing widget.
    220231 */
    221232function wp_register_sidebar_widget($id, $name, $output_callback, $options = array()) {
    … …  
    244255
    245256/**
    246  * {@internal Missing Short Description}}
    247  *
    248  * {@internal Missing Long Description}}
     257 * Retrieve description for widget.
     258 *
     259 * When registering widgets, the options can also include 'description' that
     260 * describes the widget for display on the widget administration panel or
     261 * in the theme.
    249262 *
    250263 * @since 2.5.0
    251264 *
    252  * @param unknown_type $id
    253  * @return unknown
     265 * @param int|string $id Widget ID.
     266 * @return string Widget description, if available. Null on failure to retrieve description.
    254267 */
    255268function wp_widget_description( $id ) {
    … …  
    270283 * @since 2.2.0
    271284 *
    272  * @param int $id Same as wp_unregister_sidebar_widget()
     285 * @param int|string $id Widget ID.
    273286 */
    274287function unregister_sidebar_widget($id) {
    … …  
    277290
    278291/**
    279  * {@internal Missing Short Description}}
    280  *
    281  * {@internal Missing Long Description}}
    282  *
    283  * @since 2.2.0
    284  *
    285  * @param int $id {@internal Missing Description}}
     292 * Remove widget from sidebar.
     293 *
     294 * @since 2.2.0
     295 *
     296 * @param int|string $id Widget ID.
    286297 */
    287298function wp_unregister_sidebar_widget($id) {
    … …  
    291302
    292303/**
    293  * {@internal Missing Short Description}}
    294  *
    295  * {@internal Missing Long Description}}
    296  *
    297  * @since 2.2.0
    298  *
    299  * @param unknown_type $name {@internal Missing Description}}
    300  * @param unknown_type $control_callback {@internal Missing Description}}
    301  * @param unknown_type $width {@internal Missing Description}}
    302  * @param unknown_type $height {@internal Missing Description}}
     304 * Registers widget control callback for customizing options.
     305 *
     306 * Allows $name to be an array that accepts either three elements to grab the
     307 * first element and the third for the name or just uses the first element of
     308 * the array for the name.
     309 *
     310 * Passes to {@link wp_register_widget_control()} after the argument list has
     311 * been compiled.
     312 *
     313 * @since 2.2.0
     314 *
     315 * @param int|string $name Sidebar ID.
     316 * @param callback $control_callback Widget control callback to display and process form.
     317 * @param int $width Widget width.
     318 * @param int $height Widget height.
    303319 */
    304320function register_widget_control($name, $control_callback, $width = '', $height = '') {
    … …  
    325341}
    326342
    327 /* $options: height, width, id_base
    328  *   height: never used
    329  *   width:  width of fully expanded control form.  Try hard to use the default width.
    330  *   id_base: for multi-widgets (widgets which allow multiple instances such as the text widget), an id_base must be provided.
    331  *            the widget id will ennd up looking like {$id_base}-{$unique_number}
    332  */
    333 /**
    334  * {@internal Missing Short Description}}
    335  *
    336  * {@internal Missing Long Description}}
    337  *
    338  * @since 2.2.0
    339  *
    340  * @param int $id {@internal Missing Description}}
    341  * @param string $name {@internal Missing Description}}
    342  * @param callback $control_callback {@internal Missing Description}}
    343  * @param array|string $options {@internal Missing Description}}
     343/**
     344 * Registers widget control callback for customizing options.
     345 *
     346 * The options contains the 'height', 'width', and 'id_base' keys. The 'height'
     347 * option is never used. The 'width' option is the width of the fully expanded
     348 * control form, but try hard to use the default width. The 'id_base' is for
     349 * multi-widgets (widgets which allow multiple instances such as the text
     350 * widget), an id_base must be provided. The widget id will end up looking like
     351 * {$id_base}-{$unique_number}.
     352 *
     353 * @since 2.2.0
     354 *
     355 * @param int|string $id Sidebar ID.
     356 * @param string $name Sidebar display name.
     357 * @param callback $control_callback Run when sidebar is displayed.
     358 * @param array|string $options Optional. Widget options. See above long description.
     359 * @param mixed $params,... Optional. Additional parameters to add to widget.
    344360 */
    345361function wp_register_widget_control($id, $name, $control_callback, $options = array()) {
    … …  
    378394 * @see wp_unregister_widget_control()
    379395 *
    380  * @param int $id Widget ID.
     396 * @param int|string $id Widget ID.
    381397 */
    382398function unregister_widget_control($id) {
    … …  
    385401
    386402/**
    387  * {@internal Missing Short Description}}
    388  *
    389  * {@internal Missing Long Description}}
    390  *
    391  * @since 2.2.0
    392  * @uses wp_register_widget_control() {@internal Missing Description}}
    393  *
    394  * @param int $id {@internal Missing Description}}
     403 * Remove control callback for widget.
     404 *
     405 * @since 2.2.0
     406 * @uses wp_register_widget_control() Unregisters by using empty callback.
     407 *
     408 * @param int|string $id Widget ID.
    395409 */
    396410function wp_unregister_widget_control($id) {
    … …  
    399413
    400414/**
    401  * {@internal Missing Short Description}}
    402  *
    403  * {@internal Missing Long Description}}
    404  *
    405  * @since 2.2.0
    406  *
    407  * @param unknown_type $index
    408  * @return unknown
     415 * Display dynamic sidebar.
     416 *
     417 * By default it displays the default sidebar or 'sidebar-1'. The 'sidebar-1' is
     418 * not named by the theme, the actual name is '1', but 'sidebar-' is added to
     419 * the registered sidebars for the name. If you named your sidebar 'after-post',
     420 * then the parameter $index will still be 'after-post', but the lookup will be
     421 * for 'sidebar-after-post'.
     422 *
     423 * It is confusing for the $index parameter, but just know that it should just
     424 * work. When you register the sidebar in the theme, you will use the same name
     425 * for this function or "Pay no heed to the man behind the curtain." Just accept
     426 * it as an oddity of WordPress sidebar register and display.
     427 *
     428 * @since 2.2.0
     429 *
     430 * @param int|string $index Optional, default is 1. Name or ID of dynamic sidebar.
     431 * @return bool True, if widget sidebar was found and called. False if not found or not called.
    409432 */
    410433function dynamic_sidebar($index = 1) {
    … …  
    462485
    463486/**
    464  * {@internal Missing Short Description}}
    465  *
    466  * {@internal Missing Long Description}}
    467  *
    468  * @since 2.2.0
    469  *
    470  * @param unknown_type $callback
    471 /* @return mixed false if widget is not active or id of sidebar in which the widget is active
     487 * Whether widget is registered using callback with widget ID.
     488 *
     489 * Will only check if both parameters are used. Used to find which sidebar the
     490 * widget is located in, but requires that both the callback and the widget ID
     491 * be known.
     492 *
     493 * @since 2.2.0
     494 *
     495 * @param callback $callback Widget callback to check.
     496 * @param int $widget_id Optional, but needed for checking. Widget ID.
     497/* @return mixed false if widget is not active or id of sidebar in which the widget is active.
    472498 */
    473499function is_active_widget($callback, $widget_id = false) {
    … …  
    487513
    488514/**
    489  * {@internal Missing Short Description}}
    490  *
    491  * {@internal Missing Long Description}}
    492  *
    493  * @since 2.2.0
    494  *
    495  * @return unknown
     515 * Whether the dynamic sidebar is enabled and used by theme.
     516 *
     517 * @since 2.2.0
     518 *
     519 * @return bool True, if using widgets. False, if not using widgets.
    496520 */
    497521function is_dynamic_sidebar() {
    … …  
    511535
    512536/**
    513  * {@internal Missing Short Description}}
    514  *
    515  * {@internal Missing Long Description}}
     537 * Retrieve full list of sidebars and their widgets.
     538 *
     539 * Will upgrade sidebar widget list, if needed. Will also save updated list, if
     540 * needed.
    516541 *
    517542 * @since 2.2.0
    518543 * @access private
    519544 *
    520  * @param unknown_type $update
    521  * @return unknown
     545 * @param bool $update Optional, default is true. Whether to save upgrade of widget array list.
     546 * @return array Upgraded list of widgets to version 2 array format.
    522547 */
    523548function wp_get_sidebars_widgets($update = true) {
    … …  
    600625
    601626/**
    602  * {@internal Missing Short Description}}
    603  *
    604  * {@internal Missing Long Description}}
     627 * Set the sidebar widget option to update sidebars.
    605628 *
    606629 * @since 2.2.0
    607630 * @access private
    608  * @uses update_option()
    609  *
    610  * @param unknown_type $sidebars_widgets
     631 *
     632 * @param array $sidebars_widgets Sidebar widgets and their settings.
    611633 */
    612634function wp_set_sidebars_widgets( $sidebars_widgets ) {
    … …  
    615637
    616638/**
    617  * {@internal Missing Short Description}}
    618  *
    619  * {@internal Missing Long Description}}
     639 * Retrieve default registered sidebars list.
    620640 *
    621641 * @since 2.2.0
    622642 * @access private
    623643 *
    624  * @return unknown
     644 * @return array
    625645 */
    626646function wp_get_widget_defaults() {
Note: See TracChangeset for help on using the changeset viewer.