[[TranslatedPages]]
[[TOC(sectionindex, heading=ARexx Function List, notitle, depth=1, Documentation/ARexxAPI/)]]
== MAILWRITE

 NAME::
     MailWrite -- Open a new Write window or activate one already opened. (V1.3)

 TEMPLATE::
     VAR/K,STEM/K,WINDOW/N,QUIET/S

 FUNCTION::
     Opens a Write window to compose a new mail or activates one already
     opened.

     Except when replying/forwarding/bouncing email where only one
     Write window is used, MAILWRITE is needed before trying to edit
     any part of a new message.

 INPUTS::
     `VAR/K`      - alternative variable to put the results into instead of RESULT  (V2.0)\\
     `STEM/K`     - base name used for the stem where the returned data will be stored  (V2.0)\\
     `WINDOW/N`   - change the command behavior to just activate an already opened Write window identified by the supplied parameter\\
     `QUIET/S`    - force the window to stay invisible  (V2.1)\\

 RETURNS::
     `VAR`          - info returned by the command\\
     `<STEM>WINDOW` - number of the created/activated window\\

     `RC` is set to 5 if `WINDOW` is used with a value referring to an
     inexistant window, or to 10 if the window cannot be opened, maybe
     because the limit of two Write windows has been reached.

 NOTES::
     Window slots are dinamically assigned as they are required until
     all of them are occupied, and remain in use until the relevant window
     is closed (an "invisible" Write window is also "open" within this
     context).  The optional `WINDOW` parameter sets the '''active''' Write window,
     upon which the [[WRITEATTACH]], [[WRITEBCC]], 
     [[WRITECC]], [[WRITEEDITOR]]
     [[WRITEFROM]], [[WRITELETTER]], 
     [[WRITEMAILTO]], [[WRITEOPTIONS]],
     [[WRITEQUEUE]], [[WRITEREPLYTO]], 
     [[WRITESEND]], [[WRITESUBJECT]], and
     [[WRITETO]] commands will act when called, though strictly speaking
     this is only necessary when at least two Write windows are opened
     at the same time - in that case, `MAILWRITE WINDOW x` should be
     called before using any of these commands to ensure they act on
     the window they are supposed to.

     Regardless, note that manually activating a Write window using the
     GUI does '''not''' magically make it the target of the above mentioned
     commands.

 EXAMPLE::
     {{{#!urbiscript
     /* Enable result codes */
     OPTIONS RESULTS

     /* Start a new mail */
     MAILWRITE STEM st.
     win1 = st.window

     /* Start yet another mail */
     MAILWRITE STEM st.
     win2 = st.window

     /* Edit the first Write window */
     MAILWRITE WINDOW win1
     WRITETO 'boss@example.com'
     'WRITESUBJECT "I don't think I can go to work today"'
     WRITELETTER 'work:excuses.txt'

     /* Edit the second Write window */
     MAILWRITE WINDOW win2
     WRITETO 'peggy@example.org'
     'WRITESUBJECT "Stuffed at work, I'll be late"'

     /* Put the first email in the Outgoing queue */
     MAILWRITE WINDOW win1
     WRITEQUEUE

     /* Start a new email using an invisible Write window */
     MAILWRITE STEM st. QUIET
     win3 = st.window
     WRITETO sales@example.com
     'WRITESUBJECT "Two with Mozzarella + lots of coke"'
     WRITELETTER 'dh5:priv/Snail_Linda.txt'

     /* Finish editing the second email and send it at once */
     MAILWRITE WINDOW win2
     WRITESEND

     /* Send the third email */
     MAILWRITE WINDOW win3
     WRITEOPTIONS DELETE   /* avoid leaving any traces */
     WRITESEND
     }}}

 BUGS::
     `MAILWRITE` would throw Enforcer hits if YAM was iconified and the
     external editor was configured to be launched immediately, or when
     the `QUIET` switch was used; this was fixed in V2.3.

 SEE ALSO::
     [[WRITEATTACH]], [[WRITEBCC]], 
     [[WRITECC]], [[WRITEEDITOR]]
     [[WRITEFROM]], [[WRITELETTER]], 
     [[WRITEMAILTO]], [[WRITEOPTIONS]],
     [[WRITEQUEUE]], [[WRITEREPLYTO]], 
     [[WRITESEND]], [[WRITESUBJECT]],
     [[WRITETO]]