WordPress.org

Make WordPress Core

Changeset 8960


Ignore:
Timestamp:
09/23/08 04:03:28 (9 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.