What's use of "#process" callback in drupal form api?

Question

In drupal fapi there is an attribute "#process".what exactly does it?Why password field use it for field duplication instead of adding it with theming?
I want to use it for defining a new field type with hook_elements.

Edit:
here is my hook_elements:

function test_elemets() {  
    return array(
        'test_field' => array(  
            '#input' => TRUE,  
            '#process' => array('test_field_process'),
        )
    );
}

and process callback:

function test_field_process($element, $edit, &$form_state, $complete_form) {
    $element = array();    
    return $element;    
}

as you see in process function I used $element=array() to see what happens.But the form is shown as it was before.why?

Answer 1

Read the Forms API documentation on the '#process' form element property.

It is an array of callback functions, each of which will be called with the the element definition array passed to it. The callback function can then act on the element definition array to turn it into a different (usually more complex) definition, like e.g. duplicating a password field while attaching an equality checking JavaScript file, or turning one combined 'radios' definition into an according amount of specific single 'radio' definitions, etc.

You will want to use it if you want to offer a complex form element (e.g. a combination of multiple 'standard' elements combined, or one with automatic addition of standard JavaScript helpers), but still keep the simple, declarative approach of the Forms API. (Look Ma - only one '#type' = 'myCrazyFormElement' array, that expands 'automagically' to something way more complex ;)

Doing this via the theming layer might be possible, depending on the use case, but would require more code, every time you need it.

Answer 2

api.drupal.org documentation on #process says:

An array of functions that are called when an element is processed. Using this callback, modules can "register" further actions. For example the "radios" form type is expanded to multiple radio buttons using a processing function.

Processing differs from theming in keeping within the form API. You can't alter a form array in the theme layer (at least not in D6). Password specifically, adds form_expand_ahah to #process. You could probably kludge most of that into the theme layer, but not this line:

$element['#cache'] = TRUE;

Because caching happens before the theme layer, that couldn't be done in the theme layer. More generally, while some of what happens in #process could happen in the theme layer, it couldn't all happen there because forms are more than front-end display; they're also back-end processing.