
                              TWCW HELP FILE


DESCRIPTION

   Twcw is a X/Motif application that sends Morse code.  It uses the
   openMotif toolkit.  Previous versions used lessTif.

   The application consists of two programs, twcw and sendCW.  Start the 
   application by running twcw.  This creates the Motif interface and forks a
   child process that runs sendCW.  The child process, sendCW, does two things.
   It toggles the serial port's Request to Send (RTS) line, and generates the
   sidetone.  The two processes talk to each other using a message queue.  For
   more information on message queues and troubleshooting, see IPC COMMANDS
   below. 
 

HARDWARE INTERFACE

        WARNING   THIS INTERFACE MAY DAMAGE YOUR EQUIPMENT.  I AM NOT
                  RESPONSIBLE FOR ANY DAMAGE TO ANY OF YOUR EQUIPMENT.
 
   The transmitter is keyed by the RTS signal on the serial port.  A line in 
   the resource file, Twcw, allows you to specify which serial port will be
   keyed.  The default value is /dev/ttyS1.  See the comments in Twcw for more
   info.
   

FEATURES
 
   This section gives a brief description of the features of twcw.  For a more
   complete description see the sections mentioned below.

      Interface to Log Programs
         Twcw will try to get the call of the station you are working from
         log programs.  Currently this works with twlog and xlog.

      Send Macros
         Short text strings can be sent with a keystroke you define.  See
         the resource file, Twcw, for instructions on defining new macros.
         Two are automatically defined.  Shift Alt m (Me) can be modified in
         Twcw to send your call.  Shift Alt h (Him) will send the call of the
         station found in a log program.  Shift Alt o (Over) will send
         "his call de your call", or just "de your call" if it can't find
          his call from a log program.

      Twcw Resource File
         Like other X applications, the resource file, Twcw, is used to set
         interface properties.  In addition to the basic properties like the
         x-y location and colors, Twcw initializes the state of other resources,
         like the names of the text files.  See RESOURCE FILE section below for
         more information.

      Timing
         Code timing is generated via the real time clock device - /dev/rtc.

      Word Completion
         Only whole words are sent.  In other words, you must hit the Space
         or Enter key before a word can be sent.  Once started, the word will
         be sent completely.  See WORD COMPLETION below for more.

      Send Files
         You can create and send your own text files.  These can be used for
         CQ's, QSO's and contests.  When sending a file, the program looks for
         words that start with the * character.  When one of these *WORDS is
         found, a dialog window allows you to enter the words you want to send
         at that point in the file.  See the SENDING FILES section below for
         more.

      Pro Signs
         The pro signs, like sk and kn, are sent by typing Shift-Alt 1 through
         Shift-Alt 6.  See PRO SIGNS below for more information.
     
      WPM range
         The WPM range is from 8 to 50 WPM.  


GRAPHICAL INTERFACE

   The graphical interface consists of a Call label, a Menu Bar, the Text
   window, the Sending text field, a tone scale, the XMIT, SC and Rig toggle
   buttons, and the WPM text field.
   
   Call Label
      Your call will be displayed here by setting a property in the resource
      file, Twcw.  See RESOURCE FILES below, the README and Twcw for more
      information.

   Menu Bar
      The menu bar has the following buttons, which display drop down menus.

      File
         The menu displayed by this button allows you to terminate the program
         (QRT), and send files.  See SENDING FILES for more information on how
         to set these files,

      Controls
         The menu for this button gives you the following options.  All of the
         buttons in this pull down menu and the QRT (exit) button are also
         on a pop up menu via the right mouse button.  See ACCELERATOR KEYS
         below.

         Clear Copy
            Clears the Copy text window.

         Clear Sent
            Clears the Send text field.

         Clear All 
            Clears both the Copy and Sent fields and resets the program by
            delete all the text that is waiting to be sent.  

         Practice
            When this toggle button is enabled, twcw will send random 5
            letter groups.

      Help
         About
            This pops up a window that tells you about who did this.

         Help
            Displays this file.

   Copy Text window 
      As a character is sent by the program, it is displayed in this window.
      This window is not visible when in CWirc mode, since the text will be
      displayed in CWirc.

   Send Text window
      This is the window where you type the text you want to send.  If you send 
      a text file, its contents is displayed here too.

   WPM
      Set this field to the speed you want to send.  This will cause the speed
      to change when the next word is sent, even is you are typing ahead of
      the sending.

   Tone
      Use this scale to select a sidetone frequency. The SC button (see 
      below) must be ON before a sidetone will be heard.  You will hear the
      new tone when the next word is sent.

   Farnsworth
      This control will add addition time between characters and words.  The
      value displayed in the Farnsworth control is the actual speed that the
      text will be sent.  The individual characters will be send at the speed
      displayed in the WPM control.

   SC
      When this toggle button is set, the tones will be generated by the
      soundcard.  This button is disabled when in CWirc mode, since CWirc
      will produce the tones.

   Rig
      When this toggle button is set, program will key your rig using the
      serial device's Request To Send signal (RTS).

   Xmit
      The Xmit button allows text to be send and will have a red background
      when enabled. When Xmit if off, you can do type ahead - the text you
      type will not be send until you turn on Xmit.  If you turn it off
      while a word is being sent, that word will finish, and then sending
      will stop. 


RESOURCE FILE

   The resource file is named Twcw.  It has two columns per line.  The left 
   had column is a property name followed by a : character. The right hand
   column has the value you want to assign the property. 

   Any line starting with the ! character is a comment.  There are lots of 
   comments describing the first nine properties in the file.  These are the
   ones you will most likely want to change.

   A resource file is read when the program starts.  So when you change 
   something, you must stop and restart the program for the change to take
   effect.


TIMING
   
   Timing is generate using the real time clock device - /dev/rtc.
   
WORD COMPLETION

   Word completions means that when sendCW starts to send a word, there is no
   way to stop it.  A word is defined when you hit the Space or Enter key.  
   This means that you can not Backspace or Delete past a Space or Enter.  In
   fact, the GUI won't let you.  You can only enter text at the very end.  Just
   hit ! to send an error and retype the word.  If you want to know the messy
   details as to why, then read the next three paragraphs.
   
   Two process, twcw and sendCW are running and they talk to each other with
   a message queue.  twcw sends a word to sendCW every time you hit the SPACE
   or Enter key.  A copy of that word is now in the message queue and sendCW
   will transmit it when it gets around to it.  There are other words ahead of
   it in the queue if you are type fast.   

   GOOD NEWS

      Besides word messages, twcw sends control messages to sendCW, like start,
      stop, and change WPM.  The messages are process according to their type.
      When sendCW reads the queue, it first looks for any control messages in
      the queue and processes them.  If there are none, then it looks for the
      next word message and transmits it completely before checking the queue
      again, first for control messages and then words.  This is what prevents
      the WPM from changing in the middle of a word, yet allows the WPM to
      change even though there are words that were placed in the queue before
      the the WPM message.  Those words will be sent later at the new WPM.

   BAD NEWS

      The bad news is there is no way to change the word once it is on the
      queue.  You still see the word in the interface, but the queue has a copy
      that that you can't change.  This means you can backspace and edit all
      you want, but NOT after the Space or Enter key has been hit.  In fact,
      the GUI won't let you.  It will only let you enter text at the very end,
      and you can only Backspace or Delete to the last Space or Enter.  Trying
      to just makes it mad and beep at you.  Not really bad news.


PRO SIGNS

   The - key sends bt.  The error, ar, sk, kn, as, and bk characters are sent
   with the Shift-Alt 1 through Shift-Alt 6 keys.  In other words, they are
   sent by holding down the Shift and Alt keys and hitting 1 through 6.  The
   program catches these keys and actually displays ar, sk, etc. in lower case.

   I used a word processor to create a line with "err ar sk kn as bt".  By
   playing with the font size and spacing, I got a printout that lined up with
   the 1 through 6 keys.  Some clear plastic and you will have a overlay
   for the keyboard with the pro signs above their F keys.


SENDING FILES

   When sending a file, the program looks for words that start with the *
   character.  When one of these *WORDS is found, a dialog window allows you to
   enter the words you want to send at that point in the file.
   
   For example, if *RST is found in a text file, a dialog box with the label
   RST will pop up and you can enter as much text as you want.  When you have
   finished, hit the Enter key.  The dialog box will go away and the text will
   be put into the interface.   The rest of the file will then be sent or,
   until another *WORD is found.  There is a limit of 9 text files, but it is
   easy to reconfigure the program with different text files.  See LIMITS below.

   To send a file you must create it where twcw can find it, and tell twcw its
   name in the TWCW resource file.  First we will create the file.

   To create a file, it must first be in the .twcwDir directory in your home
   directory.  While you're there, view the QSO1 file that came twcw. It will
   show you a format you could use.  

   When you send a file like QSO1, the text in the file will be added to the
   Send window and sending will start if Xmit is on.  However, when a word
   starting with * is found, the program will prompt you for some text to
   replace this *word.  Any plain text will continue to be sent while you
   answer the prompt.  To answer the prompt in this case, a dialog pops up
   with the label TOD (time of day).  You type "ge ge" or "ga ga" and hit
   Enter. The text you entered will be added to the Send window and the rest
   of the file will be sent - unless there is another *word in which case
   you would be prompted again.  QSO1 would next prompt you for his RST.

   Case does not matter in these files, so I like to do all the text in lower
   case and the *WORDS in upper case.  *WORDS stand out better and since the
   program user WORDS for the dialog title, the dialog box looks better.
   
   Now that you have created file, you have to tell the program about it.  This
   is done in the resource file.  Twcw has a line like this:

        twcw.buttonNames:             ShortCQ,LongCQ,QSO1,QSO2,PARIS


   The right hand side is a comma separated list of you files.  They will
   appear in the File pull down menu in the order they appear here.  Make sure
   there are no spaces on the end of this line.  Restart twcw and check the
   FILE menu.  You should see your file name on a button.  I like to put them
   in some logical order - the first two for CQ's, then QSO files in the order
   they will be used, etc.

   
LIMITS

   There are a few "limits" you should know about.  First, you can only have 9
   files listed in the twcw.buttonNames property.  This is because Control 1
   through Control 9 are used as accelerator keys to send these files.  See
   ACCELERATOR KEYS  below.  This is not a big limit since you can have as
   many file you want in ./twcwDir. Just change the twcw.buttonNames resource 
   in Twcw to select files you need for a given contest or other situation.

   Another "limit" is the number of bytes that can be in the queue.  On my 
   system, the max size of the queue is 16384 bytes, so this should not be a 
   problem even when sending files.  To determine your system limits, see IPC
   COMMANDS below. 


ACCELERATOR KEYS

   As you start using this program, you will probably use the menus.  But, as
   you do, look for text on the right side of a button.  It will be something
   like Ctrl-T.  This means that pressing Control T does the same thing as 
   pushing the button.  Mice are nice, but the key stroke can be much faster.
   As mentioned above, the File pulldown menu, which lists the files you can
   send also has accelerator keys.  They are assigned Control 1 through
   Control 9.   
   
   There is also one more menu, a popup menu.  It is displayed by pressing the
   right mouse button.  Options on this menu are the same as the Edit menu plus
   the QRT button from the File menu.  These buttons also have the accelerator
   buttons mentioned above.


IPC COMMANDS
   
   Since this program uses IPC message queues, there are a few Unix commands
   that you may need to know.  First is the command "ipcs -lq".  This displays 
   information about Message Limits.  The "default max size of queue (bytes)"
   line of the output shows the "default max size of queue in bytes".  For me,
   it is over 16KB, which should be more than enough to send a file.
   
   The "ipcs -q" command displays detailed information about the message queues.
   If twcw is running, you should see something like this:

    ------ Message Queues --------
    msqid     owner     perms     used-bytes  messages    
    256       you       666       0           0
 
