README

   1 This is an in-development, future version of Tilda. There will be bugs.
   2
   3
   4 REQUIREMENTS
   5 ================================================================================
   6 GTK+ >= 2.8
   7 VTE (only 0.16.12 tested)
   8 DBus >= 1.0
   9 DBus-GLib (only 0.74 tested)
  10
  11
  12 BUILDING FROM SOURCE
  13 ================================================================================
  14 This version of Tilda is not autoconf'd yet, so it will not detect missing
  15 dependencies above. This is not a priority right now, sorry.
  16
  17 There is a (poorly) hand-written Makefile available with the sources. It works
  18 for me. Give it a try with: make
  19
  20
  21 RUNNING TILDA
  22 ================================================================================
  23 This version of Tilda has no configuration wizard, which means that you will
  24 have to configure it by hand. I'm concentrating on Tilda features first, rather
  25 than the wizard.
  26
  27 The configuration defaults are now stored in share-tilda.conf, rather than being
  28 hardcoded into the binary. They will be installed in /usr/share/tilda when the
  29 project is autoconf'd, but that is not yet the case. Please DO NOT modify this
  30 file. Override the defaults as specified below in CONFIGURING.
  31
  32 Tilda can be run by starting the executable tilda in its checkout directory. If
  33 you do not start it in the correct directory, it will not be able to load the
  34 configuration defaults.
  35
  36
  37 CONFIGURING
  38 ================================================================================
  39 Since this version of Tilda does not currently have a wizard, you must configure
  40 it by hand (or use the defaults).
  41
  42 The configuration file should be named tilda.conf and should reside in the same
  43 directory as this README file, otherwise it will not be found.
  44
  45 The configuration file is in standard key file format, which is the same used
  46 for freedesktop.org .desktop files, as well as many others. It resembles the
  47 Microsoft Windows INI file format. See the following for more details:
  48 http://library.gnome.org/devel/glib/stable/glib-Key-value-file-parser.html
  49
  50 The current tilda has some per-program settings, some per-window settings, and
  51 some per-terminal settings. The new configuration format allows you to override
  52 a setting for just a specific window or terminal, if you please. This is done
  53 using groups.
  54
  55 So, an example file which sets the default font for ALL terminals to
  56 "Courier 12", but overrides it to "Courier 18" just for the second terminal
  57 would be as follows:
  58
  59 [Global]
  60 font = Courier 12
  61
  62 [Window0/Terminal1]
  63 font = Courier 18
  64
  65 From this simple example, you can notice that the windows and terminals are
  66 numbered from 0. And that the font property (which is terminal-specific) can be
  67 overridden for any terminal you want.
  68
  69 Now for another example. This time we will set the global font to "Courier 12"
  70 as before, but change all of the fonts for window 1 to "Courier 18". This means
  71 that ALL terminals that are part of the second window will have a "Courier 18"
  72 font.
  73
  74 [Global]
  75 font = Courier 12
  76
  77 [Window1]
  78 font = Courier 18
  79
  80 From this example, you can see that terminal-specific settings can be part of a
  81 window setting-group, and they will override all of that window's terminals.
  82
  83 Note, however, that setting a window-specific setting in a terminal
  84 setting-group will have no effect. So the following:
  85
  86 [Global]
  87 height = 300
  88 width = 600
  89
  90 [Window0/Terminal0]
  91 height = 600
  92 width = 1200
  93
  94 Will not work. The height and width for all windows will be 300 and 600,
  95 respectively.
  96
  97 Also note that sections must have unique names. So having two [Window0] sections
  98 is meaningless. Look at the GKeyFile implementation for what will happen.
  99
 100
 101 DEFAULT KEY
 102 ================================================================================
 103 Until the wizard is in place, there is currently a hack in the source to start
 104 the keys at F3, and keep moving up. (The algorithm is window number + 3). When
 105 the wizard is working, it will prompt you, but the wizard is not done yet.
 106 Sorry.
 107
 108 You will want to override your key. Use the following in your tilda.conf file to
 109 get the old Tilda default behavior.
 110
 111 [Window0]
 112 key = F1
 113
 114 [Window1]
 115 key = F2
 116
 117 [Window2]
 118 key = F3
 119
 120 Et cetera, for as many windows as you want or need.
 121
 122
 123 NEW BEHAVIOR
 124 ================================================================================
 125 This version of Tilda is completely configurable over DBus. If you have a DBus
 126 browser, for example qdbusviewer (installed with Trolltech QT4), you can
 127 customize Tilda's behavior at runtime.
 128
 129 This version of Tilda is designed to be run single-instance, like a daemon. It
 130 now handles many Tilda windows. You can add them by running the AddWindow()
 131 method across DBus. This is easy to do with a DBus browser, or via dbus-send,
 132 which is installed with DBus.
 133
 134 To add a window with dbus-send, the following command will work:
 135 dbus-send --print-reply --dest=net.sourceforge.Tilda \
 136                         /net/sourceforge/Tilda \
 137                         net.sourceforge.Tilda.Controller.AddWindow
 138
 139 Likewise, to set the font property on Window0/Terminal0:
 140 dbus-send --print-reply --dest=net.sourceforge.Tilda \
 141                         /net/sourceforge/Tilda/Window0/Terminal0 \
 142                         org.freedesktop.DBus.Properties.Set \
 143                         string:'' \
 144                         string:'font' \
 145                         variant:string:'Courier 12'
 146
 147 Tilda will complain if you try to give it the wrong data types, etc. You cannot
 148 set enums over DBus. I'm working on it. Sorry.
 149
 150
 151 BUG REPORTS / FEATURE REQUESTS
 152 ================================================================================
 153 Please send them to tilda@irasnyder.com, but put [tilda-gobject] in the subject
 154 line.
 155
 156 Thank you!
 157
 158 # vim: set ft=txt tw=80 noet noai nocindent nosmartindent ts=4 sw=4 sts=4: