drupal----confused by the argument $form_state

Question

this is an example form the pro drupal book.

  function annotate_admin_settings() {

    $options = node_get_types('names');
      $form['annotate_node_types'] = array(

   '#type' => 'checkboxes',

    '#title' => t('Users may annotate these content types'),
    '#options' => $options,
    '#default_value' => variable_get('annotate_node_types', array('page')),
     '#description' => t('A text field will be available on these content types to
     make user-specific notes.'),
    );
    return system_settings_form($form);
   }

but form the drupal documentation, the builder of a form's style is like this.

function mymodule_myform($form_state) {

}

there is a parameter($form_state) in the funcion, when i should use this parameter.thank you.

Answer 1

If you're looking for the differences between $form and $form_state:

$form is an associative array containing the structure of the form. It is modified with calls such as hook_form_alter to add fields or do other stuff.

$form_state is a keyed array containing the current state of the form. The exact state depends on what stage in the node process that the form is in. Typically, it holds the values that will be processed upon form submission.

Answer 2

thosewhatnots is completely completely correct in their discussion of the difference between $form and $form_state. $form defines the form, $form_state carries information about the processed form.

So why do form building functions take $form_state as their first argument (along with any number of optional, user specified arguments)? To provide context and state information that may be necessary when a form is being built.

Form building functions should always return a form definition, but they may make decisions about the form definition based on information like the last button clicked, user submitted values, or other information. As mentioned by ceejayoz in a comment, a common use of $form_state in a builder function is to handle multi-step forms, where the state of the form ("step 1 + 2 complete, step 3 still to go) has an effect on the form that is displayed to the user.

In many common use cases, $form_state is completely ignored, and optional arguments are used to provide contextual information (for one of many examples, see the comment_form API documentation).