  Xconvers User Guide
  Joop Stakenborg, pa4tu@amsat.org
  March 10, 2001
  ____________________________________________________________

  Table of Contents


  1. Introduction
     1.1 About xconvers
     1.2 The convers system

  2. Xconvers usage
     2.1 Main window
     2.2 Open dialog
     2.3 Close dialog
     2.4 Preferences dialog
     2.5 About dialog

  3. Xconvers project
     3.1 Glade tutorial
     3.2 Xconvers code layout
        3.2.1 callbacks.c
        3.2.2 color.c
        3.2.3 history.c
        3.2.4 interface.c
        3.2.5 main.c
        3.2.6 net.c
        3.2.7 preferences.c
        3.2.8 support.c
        3.2.9 types.h

  4. Credits and References


  ______________________________________________________________________

  11..  IInnttrroodduuccttiioonn

  Xconvers is a split screen convers client for amateur radio, written
  in C with the Gimp Toolkit (_G_T_K_+). Xconvers was developed with _g_l_a_d_e,
  a graphical user interface builder.  The xconvers homepage is at
  <http://xconvers.sourceforge.net>.


  11..11..  AAbboouutt xxccoonnvveerrss

  After connecting a convers server with xconvers, the top section of
  the main window will display the server response.  You can type your
  text in a one-line transmit window.  Xconvers features color support,
  the possibility to record the session into a file and history for the
  connect dialog and the transmit window.  The appearance of the main
  window can be changed by enabling or disabling the menu, scrollbar and
  statusbar and setting your own font and background for the received
  text.  Finally, it is possible to automatically login to a convers
  server, by entering a default name and channel in a settings dialog.


  Xconvers was originally written as a client to connect to the convers
  server shipped with wampes. The original motif version (still
  available as version 0.4.2) was written by Guido Vattrodt (DL3BZN) and
  maintained by me.  I wanted to enhance xconvers and give it a more
  modern look, so I decided to write a new version, programmed with
  GTK+.


  Please report any bugs you find in xconvers. I will try to fix them.
  If you need additional help with xconvers or if you have any
  suggestions, mail me. I sometimes hang around on channel 44 of the
  worldwide convers system.


  11..22..  TThhee ccoonnvveerrss ssyysstteemm

  The convers system is an IRC-like network which uses port 3600 to
  connect.  It is optimized for producing less traffic, because some of
  its servers are connected through the radio waves, where bandwidth is
  scarce. Convers is used primarily by ham-radio operators. Here is a
  list of servers which I have used in the past to check the behaviour
  if xconvers:


  Hostname                   Server  Version  Last Checked  Name
  -------------------------------------------------------------------
  pe1lxx.penguinpowered.com  htpp    1.22     Dec 10,2000   SHB_NL
  dxc.amprnet.org.br         htpp    1.22     Dec 10,2000
  radio-gw.cnuce.cnr.it      tnos    2.30     Dec 10,2000
  g0uje.ampr.org             htpp    1.22     Dec 10,2000
  irc.n1uro.ampr.org         htppu   1.3      Dec 10,2000
  qso.ka1rci.ampr.org        mfnos   1.28.4   Dec 10,2000
  hamgate.crb.org.br         htpp    1.22     Dec 10,2000
  blues.pspt.fi              htpp    1.22     Dec 10,2000   Kuopio_FI

  Please note: This list might be out of date and is not intended to be complete.



  You can join a convers server by typing _/_n_a_m_e _c_a_l_l_s_i_g_n _c_h_a_n_n_e_l_n_u_m_b_e_r
  after you are connected. The channelnumber is optional.  Type _/_h_e_l_p or
  _/_? to get an overview of the available commands after you are
  connected.


  22..  XXccoonnvveerrss uussaaggee



  22..11..  MMaaiinn wwiinnddooww

  The main xconvers window is divided into 4 parts: the menu, the
  receiving window, the one-line transmit window and the statusbar.

  <CENTER > <img src="images/xconvers-mainwindow.png" alt="[ main window
  screenshot ]" > </CENTER >

  <center >FFiigguurree 11.. XXccoonnvveerrss mmaaiinn wwiinnddooww </center >


  _M_e_n_u_s can be selected by using the mouse or the Alt-key. The program
  can be exited by clicking on the close button or selecting
  _F_i_l_e_(_A_l_t_+_F_)_-_>_E_x_i_t from the menu.  The _H_o_s_t_(_A_l_t_+_H_)_-_>_O_p_e_n menu entry
  will be automatically disabled when you are connected. At the same
  time _H_o_s_t_-_>_C_l_o_s_e is enabled.  You can use the _P_g_U_p_/_P_g_D_n keys to scroll
  the receive window. _S_e_t_t_i_n_g_s_(_A_l_t_+_S_)_-_>_P_r_e_f_e_r_e_n_c_e_s will show a dialog
  for xconvers settings and _H_e_l_p_(_A_l_t_+_P_)_-_>_A_b_o_u_t will activate the about
  dialog.


  The _r_e_c_e_i_v_e _w_i_n_d_o_w will use a different color for every new user with
  a maximum of 10 colors. Status messages (messages starting with ***)
  will be displayes in red, sent messages will be white and non-user
  messages will be somewhat greyish. Colors for user 1 to 10 will be in
  yellow, green, blue, magenta, orange, cyan, purple, DarkKhaki,
  DarkCyan or DeepPink.  Private message (messages send to you with the
  /msg comand) will be displayed in pink.


  The one-line _t_r_a_n_s_m_i_t _w_i_n_d_o_w remembers the last 10 lines you have
  typed. You can recall them by using the up- and down-arrow. These
  lines will be saved if you leave xconvers and reloaded the next time
  you start the program.


  The bottom _s_t_a_t_u_s _b_a_r will show the host you are connected to and will
  display any failures, like a hostname which can not be resolved  or a
  connection which is refused. When the statusbar is disabled, these
  messages will appear in the receive window prepended by an arrow
  (-->).


  22..22..  OOppeenn ddiiaalloogg

  A connection is opened by selecting _H_o_s_t_-_>_O_p_e_n.

  <CENTER > <img src="images/xconvers-connect.png" alt="[ open dialog
  screenshot ]" > </CENTER >

  <center >FFiigguurree 22.. TThhee ooppeenn ((ccoonnnneecctt)) ddiiaalloogg </center >


  This will show the open dialog, with 2 entries for hostname and port.
  The entries will be filled with the last connection you have made.
  The last 10 connections are available when you click on the down-
  arrow.  When nothing is entered and the entries are blank, the default
  values will be used and a connection to localhost, port 3600 will be
  tried.


  22..33..  CClloossee ddiiaalloogg

  The close dialog closes the socket which you have used to connect to
  the convers server.

  <CENTER > <img src="images/xconvers-disconnect.png" alt="[ close
  dialog screenshot ]" > </CENTER >

  <center >FFiigguurree 33.. CClloossee ((ddiissccoonnnneecctt)) ddiiaalloogg </center >

  Of course, you could close the connection by typing _/_q_u_i_t, but there
  is a possibility that the remote server has already closed the
  connection. Typing _/_q_u_i_t will let you wait forever for a server
  response.  There is one disadvantage when closing the socket: the
  convers server will think there is a link failure. So, if you are sure
  that you are connected, it is best to just use the _/_q_u_i_t command.


  22..44..  PPrreeffeerreenncceess ddiiaalloogg

  The preferences dialog, activated by selecting _S_e_t_t_i_n_g_s_-_>_P_r_e_f_e_r_e_n_c_e_s
  from the menu, can be used to change general settings and appearance
  of xconvers. The dialog consists of 2 pages, called _G_e_n_e_r_a_l and
  _D_i_s_p_l_a_y. Your preferences will be saved in _~_/_._x_c_o_n_v_e_r_s_/_p_r_e_f_e_r_e_n_c_e_s
  when you click OK and will be recalled the next time you start
  xconvers.

  <CENTER > <img src="images/xconvers-preferences.png" alt="[
  preferences dialog screenshot - general ]" > </CENTER >
  <center >FFiigguurree 44.. PPrreeffeerreenncceess ddiiaalloogg ((ggeenneerraall ppaaggee)) </center >


  The GGeenneerraall page has 2 checkbuttons, one for enabling logging to a
  file, the other one for enabling autlogin.  The log is saved in
  _~_/_._x_c_o_n_v_e_r_s_/_h_o_s_t_n_a_m_e_._l_o_g).  Please note that if you have 2 instances
  of xconvers running and are connected to the same host, both programs
  will log to the same file.  If you click on autologin, you can fill in
  a name and channel which will be used to automatically login to a
  convers server, by sending _/_n _n_a_m_e _c_h_a_n_n_e_l) the first time you
  connect.

  <CENTER > <img src="images/xconvers-preferences-display.png" alt="[
  preferences dialog screenshot - display ]" > </CENTER >

  <center >FFiigguurree 55.. PPrreeffeerreenncceess ddiiaalloogg ((ddiissppllaayy ppaaggee)) </center >


  The DDiissppllaayy page is used to change the appearance of xconvers.  Menu,
  scrollbar and statusbar of the mainwindow can be disabled, by clicking
  on one of the checkboxes. The background color of the main window can
  be changed by clicking on the colored button in the _c_o_l_o_r _f_r_a_m_e (this
  button will be black the first time you change the background). This
  will bring up a color selection dialog. Likewise, clicking on the
  button marked ...... in the _f_o_n_t _f_r_a_m_e will bring up a font selection
  dialog for changing the font of the main window.


  22..55..  AAbboouutt ddiiaalloogg

  The about dialog, displayed by selecting _H_e_l_p_-_>_A_b_o_u_t,

  <CENTER > <img src="images/xconvers-about.png" alt="[ about dialog
  screenshot ]" > </CENTER >

  <center >FFiigguurree 66.. TThhee aabboouutt ddiiaalloogg </center >


  will show a dialog with 3 different pages providing you with contact
  information, the xconvers logo, a short helpfile a copyright notice.


  33..  XXccoonnvveerrss pprroojjeecctt

  Xconvers is a free software project. One of the things I like about
  writing free software is the exchange of information between people.
  When writing xconvers, I can take a look at other code for examples,
  while other people can also benefit from the work I have done.


  Let me tell you something about the tools I have used to develop
  xconvers.  Maybe I can get you interested in free software development
  because  we need a lot more hams who want to write free software.


  33..11..  GGllaaddee ttuuttoorriiaall

  Glade is a user interface builder for GTK and Gnome. It allows you to
  build a program with a few mouseclicks. You can drag widgets (buttons,
  text, frames, whatever) to a worksheet. Next you have to define events
  which will interact with the user (for example: clicking on a button).
  Once you have saved your projects, your task will be to write code
  which will respond correctly when such an event occurs. In other
  words: you will have to write the callback function. Here is how the
  gtk version of glade looks like:

  <CENTER > <img src="images/tutor.jpg" alt="[ screenshot with glade ]"
  > </CENTER >

  <center >FFiigguurree 77.. GGllaaddee iinn aaccttiioonn </center >

  You can see 4 windows. The left one is called the _P_a_l_e_t_t_e dialog.  It
  contains all available GTK widgets which you can use. I have created
  the window in the center marked Tutor, by clicking on the left topmost
  icon, which looks like a little window.  The window on the right is
  the _P_r_o_p_e_r_t_i_e_s dialog. It is used to set the properties (appearance)
  of a widget and to add functions to widget events. As you can see, I
  have used the properties dialog to set the title of the window by
  changing the entry called Title. Finally, the small top window called
  Glade, is the main glade window.  It contains a list of windows and
  dialogs which you have created.  You use this window to save your
  project and build the source.


  We want the application to exit nicely if we click on the close button
  of the tutor window (the button marked X in most window managers).  In
  order to do this, we have to add a callback to the window's _d_e_s_t_r_o_y
  _e_v_e_n_t:

  <CENTER > <img src="images/tutor-properties.png" alt="[ glade
  properties screenshot ]" > </CENTER >

  <center >FFiigguurree 88.. TTuuttoorr pprrooppeerrttiieess </center >

  We do this by selecting the _S_i_g_n_a_l_s _p_a_g_e of the properties dialog.
  Click on the button marked ...... next to the Signal entry. You will see
  a list of signals which can be used to interact with the user. Select
  _d_e_s_t_r_o_y from the list under GtkObject signals (the last signal in the
  list).  Next, we need to fill in which function should handle this
  event.  Click on the down arrow next to the Handler entry and select
  _g_t_k___m_a_i_n___q_u_i_t.  You now have created the simplest program possible
  with GTK. It shows a window when it is started and exits if we click
  the close button.


  It is time to save our project. When you choose a project name, the
  name for the executable will be automatically filled in. The project
  will be saved as project.glade. This file describes your user
  interface in XML. Next, you should write the source code. This will
  create all the files which are necessary to build the executable. You
  should run the _a_u_t_o_g_e_n_._s_h script and then type _m_a_k_e. Your executable
  will be in the src directory. If you strip it, it will be as small as
  7 kB.


  This program does nothing sensible, but it can give you a bit of
  insight into the working of glade. Normally you will make a more
  complicated user-interface which generated dozens of signals. You will
  then modify callback.c in the src directory to handle the signal. The
  glade source code contains a user guide and a more complex example on
  how to use glade. On the glade web site you can find links to lots of
  source code developed with glade. Some of them include the XML .glade
  file, so you can load the user-interface in glade to see how it is
  build up.



  33..22..  XXccoonnvveerrss ccooddee llaayyoouutt

  Xconvers has evolved from just over 1000 lines of code in the
  0.5alpha1 version to 3000 lines of code in the current version.  In
  order to keep the code readable I had to organize the .c files into
  modules.  Here is a description of every .c file and the functions it
  contains.


  33..22..11..  ccaallllbbaacckkss..cc


       Contains callbacks generated by glade which connect to a
       widget signal.  Functions included handle selection of the
       menu, opening and closing of the main window and all the
       dialogs, keypresses in the main window, clicking on OK and
       Cancel buttons, toggling of checkbuttons and changing text
       entries.



  33..22..22..  ccoolloorr..cc


       All about colors: functions for looking up and displaying
       messages associated with a particular user in the right
       color. Also has a function which calculates the right color
       which is looked up in the xconvers preferences file.



  33..22..33..  hhiissttoorryy..cc


       Loads and saves the history of the the one-line transmit
       window and the comboboxes in the open dialog.



  33..22..44..  iinntteerrffaaccee..cc


       Generated by glade. Sets the properties for every window,
       dialog and widget and adds signals to a widget.



  33..22..55..  mmaaiinn..cc


       Glade generated. Does nothing much except initialize gtk and
       start the main loop.



  33..22..66..  nneett..cc


       Network functions. Lets you transmit and receive text,
       lookup a hostname and connect and disconnect.



  33..22..77..  pprreeffeerreenncceess..cc


       Functions that lookup and save settings to the xconvers
       preferences file.  Also checks if the .xconvers directory
       can be created.


  33..22..88..  ssuuppppoorrtt..cc


       Support function supplied by glade. Most functions are used
       internally by glade. Contains 1 public function called
       lookup_widget which is used to find the name of a widget in
       a dialog or window, in case you want to set properties at
       run time.



  33..22..99..  ttyyppeess..hh


       Defines a structure where all the xconvers settings are
       saved, so they are accessible at runtime.



  44..  CCrreeddiittss aanndd RReeffeerreenncceess

  Development of xconvers would not have been possible without the
  following:


  +o  The xconvers website, which is hosted at sourceforge
     <http://sourceforge.net>.  On the xconvers project page
     <http://sourceforge.net/projects/xconvers> you can find the latest
     news, download the latest version and access the CVS archive.

  +o  I found great help in joining the GTK-app-devel
     <http://mail.gnome.org/mailman/listinfo/gtk-app-devel-list> mailing
     list.  It is a list oriented toward developing applications with
     GTK+.

  +o  Two great books I have to mention: Linux Socket Programming by
     Example <http://www.mcp.com/detail.cfm?item=0789722410>, which
     helped me in getting a grip on sockets, and Teach Yourself GTK+
     Programming in 21 Days
     <http://www.mcp.com/detail.cfm?item=0672318296>, which teached me
     how to use GTK.

  +o  Thanks to Damon Chaplin for writing glade <http://glade.pn.org>, a
     user interface builder for GTK+.  A big thanks for the people who
     wrote the GIMP Toolkit <http://www.gtk.org>.

  +o  The xconvers documentation is written in LinuxDoc-DTD, using
     sgmltools <http://sourceforge.net/projects/sgmltools-lite>.

  +o  I have used scite <http:www.scintilla.org> as a coding editor.



