doc/configuration

   1 About
   2 ======
   3 All files in wmiirc-lua are stored in ~/.wmii-3.5.  You can read a bit
   4 more about this in doc/dir-structure.  wmiirc-lua configuration is stored
   5 in wmiirc and is a lua script.
   6
   7
   8 Initialization
   9 ===============
  10 Being a lua script, wmiirc, begins with the following line to cause the
  11 system to run it under the lua VM.  This must be the first line.
  12
  13         #!/usr/bin/env lua
  14
  15 An alternative is to use specific path to the lua interperter, like so:
  16
  17         #!/usr/bin/lua5.1
  18
  19 The next part loads the 'wmii' library, which implements all the
  20 functionality.  However to find it, the interpreter has to be told where
  21 to look for it.
  22
  23         -- initialize wmii library
  24         package.path = package.path
  25                .. ";" .. os.getenv("HOME") .. "/.wmii-3.5/core/?.lua"
  26                .. ";" .. os.getenv("HOME") .. "/.wmii-3.5/plugins/?.lua"
  27         require "wmii"
  28
  29 The lines above sets a new package.path which will look for lua
  30 libraries in ~/.wmii-3.5/core/ and ~/.wmii-3.5/plugins/.
  31
  32 Loading the 'wmii' lua library does not cause any events to be handled
  33 yet.  To handle events you need to issue the wmii.run_event_loop() call,
  34 which should be done at the bottom of wmiirc as it never exits.
  35
  36         -- this function does not exit
  37         wmii.run_event_loop()
  38
  39 If you make modifications to wmiirc, you can reload the script by
  40 pressing Mod1-a (alt-a) and then selecting wmiirc from the list.
  41
  42 Configuring the window manager
  43 ===============================
  44 Now let's look how to configure wmiirc-lua; please note that any
  45 configuration must come after the require "wmii" line and before the
  46 wmii.run_event_loop() call.
  47
  48 Wmii, the window manager itself, stores some information about how it
  49 should look and behave.  These are usually accessed as shows below on
  50 the command line:
  51
  52         # wmiir read /ctl
  53         view 1
  54         focuscolors #FFFFAA #007700 #88FF88
  55         normcolors #888888 #222222 #333333
  56         font fixed
  57         grabmod Mod1
  58         border 1
  59
  60 All these variables can be set sing wmii.set_ctl command.  In your
  61 wmiirc, you can set each one individually:
  62
  63         wmii.set_ctl ("view", 1)
  64
  65 or set some or all at once using a table:
  66
  67         wmii.set_ctl ({
  68                 -- which tag should be shown at startup
  69                 view        = 1,
  70                 -- width of the border decorating the clients
  71                 border      = 1,
  72                 -- what font should wmii use
  73                 font        = 'fixed',
  74                 -- colours for selected items
  75                 focuscolors = '#FFFFAA #007700 #88FF88',
  76                 -- colours for everything else
  77                 normcolors  = '#888888 #222222 #333333',
  78                 -- used with mouse actions to control windows
  79                 grabmod     = ' Mod1'
  80         })
  81
  82 The comments above describe what each option does.
  83
  84 To read back the control values use:
  85
  86         all = wmii.get_ctl()
  87         print ("current view is ", all.view)
  88
  89 Or you can read one view at a time:
  90
  91         view = wmii.get_ctl('view')
  92
  93
  94 Setting wmiirc-lua system variables
  95 ====================================
  96 wmiirc-lua provides a configuration table to store variables which will
  97 control how it runs as well as how certain plugins operate.
  98
  99 You can set an individual value like this:
 100
 101         wmii.set_conf ("xterm", "urxvt")
 102
 103 Or set multiple values at once:
 104
 105         wmii.set_conf ({
 106                 xterm = 'x-terminal-emulator',
 107                 clock.format = '%c'
 108         })
 109
 110 Note that the latter sets configuration parameters in the clock plugin.
 111 It is a convention in wmiirc-lua to prefix plugin variables with the
 112 plugin name and a period.
 113
 114 To read back the configuration values use:
 115
 116         all = wmii.get_conf()
 117         one = wmii.get_conf('xterm')
 118
 119 Adding plugins
 120 ===============
 121 wmiirc-lua is extendible through plugin modules.  Some plugins are
 122 shipped with the package, others you can get from 3rd party sources.
 123 New plugins should be placed in ~/.wmii-3.5/plugins/ directory.
 124 See doc/plugin-api to learn more about writing plugins.
 125
 126 To load plugins into wmiirc, simply call the load_plugin function:
 127
 128         -- load some plugins
 129         wmii.load_plugin ("messages")
 130         wmii.load_plugin ("clock")
 131         wmii.load_plugin ("dstat_load")
 132         wmii.load_plugin ("browser")
 133
 134 As mentioned above plugins can have configuration options.  To set them
 135 at load time a table can be passed with those parameters defined.
 136
 137         wmii.load_plugin ("clock", {
 138                         update = 2
 139                 })
 140
 141 Note that doing the above is equivalent to:
 142
 143         wmii.set_conf ("clock.update", 2)
 144         wmii.load_plugin ("clock")
 145
 146 As with configuration, all plugins must be loaded before calling
 147 run_event_loop() function.
 148
 149
 150
 151 vim: set ts=8 et sw=8 tw=72