Merge branch 'master' of git.dolda2000.com:/srv/git/r/doldaconnect
[doldaconnect.git] / doc / gui-shell
1                           GUI shell details
2
3 The majority of Dolda Connect is made out of a number of ordinary Unix
4 programs;  for  example,  doldacond  follows the  normal  Unix  daemon
5 conventions, and  dolcon -- while not  a command-line program  -- is a
6 self-contained  GUI completely  separate from  the daemon.  While Unix
7 users  should  feel quite  at  home  with  these programs,  the  whole
8 convention of  using separate programs  may seem quite alien  to those
9 used  to  traditional Direct  Connect  clients,  such  as DC++,  where
10 everything is done by one, monolithic program.
11
12 In order to make life a bit easier for those people, Dolda Connect, as
13 of 1.0, comes with a number  of wrapper programs, which should be able
14 to  provide  the  illusion  of  Dolda Connect  being  one,  integrated
15 environment. For  those wishing  to hack on  them or those  just being
16 curious  about how everything  works together,  this file  attempts to
17 document the details of this so called `GUI shell'.
18
19 At its  core, Dolda  Connect consists of  two programs:  The doldacond
20 daemon, and the dolcon GUI. The  GUI shell adds three programs to wrap
21 them together:
22
23  * The `dolconf' GUI configuration program
24  * The `doldacond-shell' daemon wrapper
25  * The `dolcon-launch' magic do-what-I-mean program
26
27 The dolconf  program is simply a  program which provides a  GUI to the
28 user in  order to compose a  configuration file for  doldacond. It can
29 run  both  in  assistant  (that's  `wizard'  for  you  Windows  users)
30 super-simple  mode, or  on  a slightly  more  advanced ordinary  mode,
31 somewhat,   vaguely  reminiscent  of   the  configuration   dialog  in
32 DC++. When  it starts, it  checks to see if  the $HOME/.doldacond.conf
33 file exists. If  it does, it will automatically  start in its ordinary
34 mode, whereas if it does not, it will ask the user whether to start in
35 assistant or ordinary mode. It provides the `-a' and `-w' command-line
36 options  to   immediately,  regardlessly  of  the   existance  of  the
37 configuration   file,   enter  the   assistant   or  ordinary   modes,
38 respectively.
39
40 The doldacond-shell program  is a wrapper program for  the daemon. Its
41 main task  is providing visual feedback  (by means of  a window) while
42 the daemon  is starting and  scanning the shares,  and a tray  icon to
43 indicate that  the daemon  is currently running.   It also  provides a
44 simple way  to launch dolcon simply  by clicking the tray  icon. As an
45 extra  service, it  also monitors  all transfers  in progress  and, if
46 compiled  with  libnotify  support,  will pop  up  notifications  when
47 interesting things  happen to the  transfers. When it starts,  it will
48 check  the  $HOME/.doldacond.pid  file   for  the  PID  of  a  running
49 daemon. If a  daemon is already running as indicated  by that file, it
50 will not  attempt to  start a new  one. It  shuts down along  with the
51 daemon itself.
52
53 The dolcon-launch  program is a  little DWIM program  for facilitating
54 the creation  of a desktop  file (a program  menu entry). It  is quite
55 simple  --   if  $HOME/.doldacond.conf  does  not   exist,  it  starts
56 dolconf.  If it  does exist,  but  no daemon  can be  found (again  as
57 indicated  by $HOME/.doldacond.pid),  it  starts doldacond-shell,  and
58 otherwise it starts an instance of dolcon.
59
60 To facilitate  all this,  dolcon has been  gifted with a  `-l' command
61 line  option, which,  if present,  causes dolcon  to autoconnect  to a
62 local daemon  via a  Unix socket. That  way, $HOME/.dolconrc  need not
63 necessarily be  configured for  local operation for  the GUI  shell to
64 work.
65
66 In all, I believe these programs together should present the illusion
67 of an integrated Direct Connect client program.