<!DOCTYPE page
[<!ENTITY % balsa SYSTEM "balsa.entities">%balsa; ]>
<page xmlns="http://projectmallard.org/1.0/" type="topic"
id="win-composer">
  <info>
    <link type="guide" xref="index" />
  </info>
  <title>The Message Composer</title>
  <figure>
    <title>Message Composition Window</title>
    <media src="figures/newmsg-window.png" format="PNG" />
  </figure>
  <p>When the
  <gui>New Message</gui> or
  <gui>Reply</gui> or
  <gui>Forward</gui> action is selected, the message to be sent is
  brought up in the Message Composer. This window is where you can
  type the text of the message, attach files, and specify
  recipients. The window also provides an interface to spell check
  the message. Signing and encryption of messages using
  <app>GnuPG</app> or
  <app>PGP</app> are also supported, when &Balsa; is built with
  cryptographic support.</p>
  <p>When the message window first opens, you will see the several
  main sections:</p>
  <list>
    <item>
      <p>The menu bar</p>
    </item>
    <item>
      <p>Toolbar</p>
    </item>
    <item>
      <p>Mail headers</p>
    </item>
    <item>
      <p>The attachment box</p>
    </item>
    <item>
      <p>The message body</p>
    </item>
  </list>
  <p>These will each be covered in depth below:</p>
  <section id="win-composer-menu">
    <title>Menu Bar</title>
    <p>This contains all of the available commands for acting on
    the message, from selecting the headers to display to changing
    the character set of the message. Some of the menu items are
    not always available, depending on what state the message is
    currently in.</p>
    <terms>
      <item>
        <title>
          <gui>File</gui>
        </title>
        <p>The file menu contains commands for manipulating the
        message as a whole.</p>
        <list>
          <item>
            <p>
            <guiseq>
              <gui>File</gui>
              <gui>Include File…</gui>
            </guiseq> &mdash; Include a text file in the body of the
            message; only works for plain text files.</p>
          </item>
          <item>
            <p>
            <guiseq>
              <gui>File</gui>
              <gui>Attach File…</gui>
            </guiseq> &mdash; Attach any kind of file to the
            message.</p>
          </item>
          <item>
            <p>
            <guiseq>
              <gui>File</gui>
              <gui>Send</gui>
            </guiseq>
            <keyseq>
              <key>Ctrl</key>
              <key>Enter</key>
            </keyseq> &mdash; Send the message.</p>
          </item>
          <item>
            <p>
            <guiseq>
              <gui>File</gui>
              <gui>Queue</gui>
            </guiseq>
            <keyseq>
              <key>Ctrl</key>
              <key>Q</key>
            </keyseq> &mdash; Queue the message in the outbox for
            sending later.</p>
            <note>
              <p>A message is considered valid (ready for sending
              or queuing) if it contains at least one valid email
              address, and no invalid addresses, in the
              <gui>Recipients</gui> fields.</p>
            </note>
          </item>
          <item>
            <p>
            <guiseq>
              <gui>File</gui>
              <gui>Postpone</gui>
            </guiseq> &mdash; Save the message in the
            <code>Draftbox</code> for later revision and sending,
            and close the compose window. You will be unable to
            postpone a message that is not currently valid.</p>
          </item>
          <item>
            <p>
            <guiseq>
              <gui>File</gui>
              <gui>Save</gui>
            </guiseq>
            <keyseq>
              <key>Ctrl</key>
              <key>S</key>
            </keyseq> &mdash; Save the message in the
            <code>Draftbox</code> and continue editing.</p>
          </item>
          <item>
            <p>
            <guiseq>
              <gui>File</gui>
              <gui>Page Setup</gui>
            </guiseq> &mdash; Set print options such as paper size
            and print orientation.</p>
          </item>
          <item>
            <p>
            <guiseq>
              <gui>File</gui>
              <gui>Print…</gui>
            </guiseq>
            <keyseq>
              <key>Ctrl</key>
              <key>P</key>
            </keyseq> &mdash; Print a hard-copy of the current
            message.</p>
          </item>
          <item>
            <p>
            <guiseq>
              <gui>File</gui>
              <gui>Close</gui>
            </guiseq>
            <keyseq>
              <key>Ctrl</key>
              <key>W</key>
            </keyseq> &mdash; Close and discard the current
            message.</p>
          </item>
        </list>
      </item>
      <item>
        <title>
          <gui>Edit</gui>
        </title>
        <p>The Edit menu contains commands which are used to modify
        the body of the message.</p>
        <list>
          <item>
            <p>
            <guiseq>
              <gui>Edit</gui>
              <gui>Undo</gui>
            </guiseq>
            <keyseq>
              <key>Ctrl</key>
              <key>Z</key>
            </keyseq> &mdash; Undo the most recent editing
            action.</p>
          </item>
          <item>
            <p>
            <guiseq>
              <gui>Edit</gui>
              <gui>Redo</gui>
            </guiseq>
            <keyseq>
              <key>Shift</key>
              <key>Ctrl</key>
              <key>Z</key>
            </keyseq> &mdash; Redo an undone editing action.</p>
          </item>
          <item>
            <p>
            <guiseq>
              <gui>Edit</gui>
              <gui>Cut</gui>
            </guiseq>
            <keyseq>
              <key>Ctrl</key>
              <key>X</key>
            </keyseq> &mdash; Cut the selected text to the
            clipboard.</p>
          </item>
          <item>
            <p>
            <guiseq>
              <gui>Edit</gui>
              <gui>Copy</gui>
            </guiseq>
            <keyseq>
              <key>Ctrl</key>
              <key>C</key>
            </keyseq> &mdash; Copy the selected text to the
            clipboard.</p>
          </item>
          <item>
            <p>
            <guiseq>
              <gui>Edit</gui>
              <gui>Paste</gui>
            </guiseq>
            <keyseq>
              <key>Ctrl</key>
              <key>V</key>
            </keyseq> &mdash; Paste the contents of the clipboard to
            the current position of the cursor.</p>
          </item>
          <item>
            <p>
              <guiseq>
                <gui>Edit</gui>
                <gui>Select All</gui>
              </guiseq>
              <keyseq>
                <key>Ctrl</key>
                <key>A</key>
              </keyseq>
            </p>
          </item>
          <item>
            <p>
            <guiseq>
              <gui>Edit</gui>
              <gui>Wrap Body</gui>
            </guiseq>
            <keyseq>
              <key>Ctrl</key>
              <key>B</key>
            </keyseq> &mdash; Cause all the lines in the message to
            be wrapped to the specified outgoing mail wrap
            column.</p>
          </item>
          <item>
            <p>
            <guiseq>
              <gui>Edit</gui>
              <gui>Reflow Selected Text</gui>
            </guiseq>
            <keyseq>
              <key>Ctrl</key>
              <key>R</key>
            </keyseq> &mdash; Cause all selected lines to be wrapped
            to the specified outgoing mail wrap column.</p>
          </item>
          <item>
            <p>
            <guiseq>
              <gui>Edit</gui>
              <gui>Check Spelling</gui>
            </guiseq> &mdash; Start spell checking the current
            message.</p>
          </item>
        </list>
      </item>
      <item>
        <title>
          <gui>Show</gui>
        </title>
        <p>The Show menu is used to control which headers are
        displayed in the composer window for editing.</p>
        <list>
          <item>
            <p>
            <guiseq>
              <gui>Show</gui>
              <gui>Toolbar</gui>
            </guiseq> &mdash; Show or hide the toolbar.</p>
          </item>
          <item>
            <p>
            <guiseq>
              <gui>Show</gui>
              <gui>From</gui>
            </guiseq> &mdash; Display the
            <code>From</code> header.</p>
          </item>
          <item>
            <p>
            <guiseq>
              <gui>Show</gui>
              <gui>Recipients</gui>
            </guiseq> &mdash; Display the
            <code>To:</code> ,
            <code>Cc:</code> , and
            <code>Bcc:</code> addresses.</p>
          </item>
          <item>
            <p>
            <guiseq>
              <gui>Show</gui>
              <gui>Reply To</gui>
            </guiseq> &mdash; Display the
            <code>Reply-To</code> header.</p>
          </item>
          <item>
            <p>
            <guiseq>
              <gui>Show</gui>
              <gui>Fcc</gui>
            </guiseq> &mdash; Display the
            <code>Fcc</code> header; this is the folder to which
            your copy of the sent message will be saved. The
            default is your Sentbox.</p>
          </item>
        </list>
      </item>
      <item>
        <title>
          <gui>Language</gui>
        </title>
        <p>The Language menu allows you to set the language to use
        for composing and checking the spelling of the message.
        Only languages for which you have dictionaries installed
        are shown.</p>
      </item>
      <item>
        <title>
          <gui>Options</gui>
        </title>
        <list>
          <item>
            <p>
            <guiseq>
              <gui>Options</gui>
              <gui>Request Disposition Notification</gui>
            </guiseq> &mdash; If checked &Balsa; will include
            the
            <code>Disposition-Notification-To</code> header line
            with your
            <code>From</code> address. Please note that the handling
            of this request depends on the receiving mail program
            and that it is not guaranteed that this notification will
            be sent back.</p>
          </item>
          <item>
            <p>
            <guiseq>
              <gui>Options</gui>
              <gui>Format = Flowed</gui>
            </guiseq> &mdash; The “Flowed” format (RFC 3676) breaks
            the message text into paragraphs, which you type
            continuously using the
            <key>Enter</key> key only to mark the end of a
            paragraph, and “fixed” lines which you mark
            individually using the
            <key>Enter</key> key. This allows other mailers that
            recognize the format to display the text appropriately
            for the width of the recipient's screen, and to quote
            the text correctly when constructing a reply. The text
            is also displayed intelligibly by a non-flowed-aware
            mailer.</p>
            <note>
              <p>Using “Format=Flowed” is strongly recommended. It
              helps to avert the “embarrassing line wrap” that you
              see when quoted text is broken across lines and shown
              with the wrong level of quoting.</p>
            </note>
          </item>
          <item>
            <p>
            <guiseq>
              <gui>Options</gui>
              <gui>Send as plain text and HTML</gui>
            </guiseq> &mdash; &Balsa; can send and receive
            messages in right-to-left languages such as Arabic,
            Hebrew, and Persian, but some other agents such as
            mailing lists may mangle them when translating into
            HTML. If the “Send as plain text and HTML” option is
            selected, &Balsa; will generate a correct HTML
            message part that such agents will use instead.</p>
          </item>
          <item>
            <p>
            <guiseq>
              <gui>Options</gui>
              <gui>Sign message</gui>
            </guiseq> &mdash; Cryptographically sign the message.
            The recipients can check the signature to prove the
            sender's (=your) identity or to detect any tampering
            with the message.</p>
          </item>
          <item>
            <p>
            <guiseq>
              <gui>Options</gui>
              <gui>Encrypt message</gui>
            </guiseq> &mdash; Encrypt the message. Only the intended
            recipient(s) can decrypt and read the contents.</p>
          </item>
          <item>
            <p>The following options determine the protocol used
            for signing and/or encrypting the message. You should
            choose the appropriate protocol which all recipients
            can use.</p>
            <list>
              <item>
                <p>
                <guiseq>
                  <gui>Options</gui>
                  <gui>GnuPG uses MIME mode</gui>
                </guiseq> &mdash; Sign and/or encrypt the complete
                message, including all attachments, using the
                PGP/MIME mode (RFC 3156). Note that the message
                envelope (including the Subject) is not
                protected.</p>
              </item>
              <item>
                <p>
                <guiseq>
                  <gui>Options</gui>
                  <gui>GnuPG uses old OpenPGP mode</gui>
                </guiseq> &mdash; Sign and/or encrypt only the
                message text, but not attachments, using the
                OpenPGP mode (RFC 2440). If you want to add any
                attachments, sign and/or encrypt them manually
                before adding.</p>
              </item>
              <item>
                <p>
                <guiseq>
                  <gui>Options</gui>
                  <gui>S/MIME mode (GpgSM)</gui>
                </guiseq> &mdash; Sign and/or encrypt the complete
                message, including all attachments, using the
                S/MIME mode (RFC 2633). Note that the message
                envelope (including the Subject) is not
                protected.</p>
              </item>
            </list>
            <note>
              <p>Cryptographic signatures and encryption are
              available only when &Balsa; has been built with
              &GnuPG; support. For a detailed description of
              E-Mail cryptography, see the
              <link href="http://www.gnupg.org/documentation/manuals/gnupg/"
              type="http"> GnuPG Manual</link> and the
              <link href="https://www.gnupg.org/howtos/en/GPGMiniHowto.html">
              GnuPG HOWTO</link>.</p>
            </note>
          </item>
        </list>
      </item>
    </terms>
  </section>
  <section id="win-composer-toolbar">
    <title>Toolbar</title>
    <p>The toolbar contains buttons for the most commonly used
    functions when sending messages, including <gui>Send</gui>,
    <gui>Attach File…</gui>, and <gui>Save</gui>. As with the
    menu bar, some buttons are disabled if the message is not
    correctly setup to be sent.</p>
    <figure>
      <title>Toolbar</title>
      <media type="image"
      src="figures/newmsg-window-toolbar.png" />
    </figure>
    <terms>
      <item>
        <title>
          <gui>Send</gui>
        </title>
        <p>Send the current message. Only available if the message
        is legal to be sent (i.e. proper email addresses). This
        button may also be configured to queue the message in the
        outbox to be sent later (see the
        <link xref="preferences-outgoing">
        Preferences</link> dialog).</p>
      </item>
      <item>
        <title>
          <gui>Attach</gui>
        </title>
        <p>Open a dialog to attach a file to the current
        message.</p>
      </item>
      <item>
        <title>
          <gui>Postpone</gui>
        </title>
        <p>Postpone the message to the Draftbox for later revision
        and sending.</p>
      </item>
      <item>
        <title>
          <gui>Check Spelling</gui>
        </title>
        <p>Start a spell check on the current message. If
        &Balsa; is built with support for
        <app>GtkSpell</app> , your spelling is checked in place.
        Otherwise, &Balsa; can use either
        <app>ispell</app> or
        <app>aspell</app> to do the spell checking. Settings for
        this can be found in the
        <link xref="preferences-spelling">
        Preferences</link> dialog.</p>
      </item>
      <item>
        <title>
          <gui>Print</gui>
        </title>
        <p>Print out the draft of the message.</p>
      </item>
      <item>
        <title>
          <gui>Cancel</gui>
        </title>
        <p>Close the composition window without saving or sending
        the message within.</p>
      </item>
    </terms>
  </section>
  <section id="win-composer-headers">
    <title>Headers</title>
    <p>The headers area is where the information regarding where
    the message is being sent to and from, as well as comments and
    keywords can be entered. All of the available headers are not
    shown by default, but they can be turned on and off very
    quickly using the menu.</p>
    <terms>
      <item>
        <title>
          <gui>From</gui>
        </title>
        <p>
        <code>From</code> is used to indicate the origin of the
        message, &Balsa; automatically fills this in for you if
        you have entered your name and email address in the
        <link xref="identities">identities</link> window.</p>
      </item>
      <item>
        <title>
          <gui>To</gui>
        </title>
        <p>The
        <code>To</code> header is used to indicate the intended
        recipient of the message; &Balsa; automatically fills
        this in for you if you are replying to a message.</p>
      </item>
      <item>
        <title>
          <gui>Subject</gui>
        </title>
        <p>The
        <code>Subject</code> header is used to summarize the topic
        of the message.</p>
      </item>
      <item>
        <title>
          <gui>Cc</gui>
        </title>
        <p>The “Carbon Copy” header. A comma separated list of
        recipients other than the main recipient should go
        here.</p>
      </item>
      <item>
        <title>
          <gui>Bcc</gui>
        </title>
        <p>The
        <code>Bcc</code> , or “Blind Carbon Copy” header. Similar to
        the Cc header, except that email addresses placed in this
        header will not appear as recipients to readers of the
        message. Also known as a “silent” carbon copy.</p>
      </item>
      <item>
        <title>
          <gui>Fcc</gui>
        </title>
        <p>The
        <code>Fcc</code> header stands for “Folder Carbon Copy”, and
        it is used to specify any folders that you want the message
        copied to after being sent. It is presented as a drop-down
        combo box with a list of all available mailboxes, simply
        select the destination.</p>
      </item>
      <item>
        <title>
          <gui>Reply-To</gui>
        </title>
        <p>The
        <code>Reply-To</code> header is for specifying what email
        address you want any replies to go to.</p>
      </item>
    </terms>
    <section id="specify-addresses">
    <title>Specifying Addresses</title>
    <p>&Balsa; supports many different methods of selecting
    email addresses. All of the headers that can contain addresses
    have a small colored book to the left of them that will open up
    &Balsa;'s address book.</p>
    <p>However, &Balsa; will also attempt to guess what the
    headers should contain depending on what context the
    composition window is opened in, so it may not be necessary to
    fill them in most of the time.</p>
    <note>
      <p>Also, &Balsa; supports alias expansion. As you type a
      name, &Balsa; will guess the e-mail address from all the
      entries in the &GnomeCard; application. To enable this
      feature, read the section on
      <link xref="common-tasks#ct-alias-expansion">
      Alias Expansion</link>. In
      addition, the composition window supports drag-and-drop of
      addresses from the &GnomeCard; application.</p>
    </note> &gt;</section>
  </section>
  <section id="win-composer-attachments">
    <title>Attachments</title>
    <figure>
      <title>List of Attachments</title>
      <media type="image"
      src="figures/newmsg-window-attachments.png" />
    </figure>
    <p>Below the headers may be a large box displaying a list of
    attachments; this view can be toggled in the
    <gui>Show</gui> menu.</p>
    <p>When there are attachments displayed, it is possible to
    right-click on one of them to access an option menu.
    <gui>Inline</gui> and
    <gui>Attachment</gui> are mutually exclusive options that will
    display to the recipient either the attachment inline with the
    rest of the message, or separately as an attachment. Selecting
    <gui>Reference</gui> will send a MIME external part reference (a
    kind of link) in lieu of the actual file.
    <gui>Remove</gui> , and any available
    <gui>Open with</gui> options are also available.</p>
  </section>
  <section id="win-composer-body">
    <title>Message Body</title>
    <p>Finally, below the attachment list is the main area of the
    window where the text of the message is displayed. The text
    editing capabilities are very basic, but it supports cut, copy,
    and paste so it is possible to write a message in your favorite
    editor and simply paste it in.</p>
    <p>If the message is a reply or forward, the referenced message
    will be displayed in the body text widget, with the prefix
    specified in the
    <link xref="preferences-outgoing">Preferences</link> dialog.</p>
  </section>
  <section id="win-composer-spellcheck">
    <title>Spell Checker</title>
    <p>Once the spell check has been started, it will take a moment
    to load the text and spell checking module, and then it will
    automatically begin checking the message. If it finds any words
    that are incorrect, the word will be highlighted and a panel
    will be shown that offers a number of suggestions and available
    courses of action.</p>
    <figure>
      <title>Spell Checking Panel</title>
      <media type="image" src="figures/spell-check.png" />
    </figure>
    <p>As shown above, the panel consists of a list of two panes,
    one to the left containing a list of suggestions and an entry box,
    while the right contains several buttons to choose your action.
    The list on the left is re-generated for each incorrect word,
    with all the suggestions the spell check program comes up with.
    You can choose what program you want to use through loadable
    modules, selectable in the
    <link xref="preferences-spelling">Preferences</link> dialog. The
    entry box above the list is what will be used to replace the
    current word, and usually reflects the current selection in the
    list, but can be edited by hand if you wish to make manual
    changes.</p>
    <p>The buttons on the left control the actions to take for each
    incorrect word. The buttons include:</p>
    <terms>
      <item>
        <title>
          <gui>Change</gui>
        </title>
        <p>Change the incorrect word with the currently selected
        suggested word or the user's edited word.</p>
      </item>
      <item>
        <title>
          <gui>Change All</gui>
        </title>
        <p>Change all occurrences of the current incorrect word with
        the currently selected suggestion.</p>
      </item>
      <item>
        <title>
          <gui>Ignore</gui>
        </title>
        <p>Ignore the current incorrect word and continue to the
        next one.</p>
      </item>
      <item>
        <p>Ignore all occurrences of the current word, and continue
        to the next incorrect word.</p>
      </item>
      <item>
        <title>
          <gui>Learn</gui>
        </title>
        <p>Add the current incorrect word to your personal
        dictionary. This will cause it to be considered correct for
        all future spell checks.</p>
      </item>
      <item>
        <title>
          <gui>Done</gui>
        </title>
        <p>Stop the spell check at the current point, keeping all
        changes so far and returning to the normal message window
        interface.</p>
      </item>
      <item>
        <title>
          <gui>Cancel</gui>
        </title>
        <p>Stop the spell check at the current point, reverting all
        changes so far, including any words added to your personal
        dictionary.</p>
      </item>
    </terms>
  </section>
  <section id="addr-book-buttons">
    <title>Address Book</title>
    <p>When composing a message, clicking on any of the colored
    book icons next to a destination field (To, Cc, Bcc) will bring
    up the &Balsa; address book. It helps you to select
    recipients for your messages quickly and easily.</p>
    <figure>
      <title>Address Book Window</title>
      <media type="image" src="figures/address-book.png" />
    </figure>
    <p>The address book provides two panes, the one on the left
    consisting of all available addresses, while the one on the
    right contains the intended recipients of your message.
    Addresses are added to the recipient list by selecting them in
    the left pane and clicking the arrow button pointing to the
    right, or by simply double-clicking on the address. This will
    remove the address from the left pane, so they cannot be added
    more than once. If you decide that you no longer want to send
    the message to a particular address, simply select it in the
    right-hand pane and click the left-arrow button, or
    double-click it again, to move it back.</p>
    <p>If, while selecting people to send your message to, you
    decide to add someone new to the address book, it is a simple
    matter to click on the
    <gui>Run Editor</gui> button. This will bring up the
    &GnomeCard; application, allowing you to easily manipulate
    your contact list. After any changes have been made using the
    address book, they can be forced to show up in the left hand
    pane by clicking on the
    <gui>Re-Import</gui> button.</p>
  </section>
</page>
