mgm/doc/docs.html

   1 <title>  xiph.org: MGM manual </title>
   2
   3 <STYLE>
   4 <!--
   5         BODY  {font-family: Verdana, Arial, Helvetica;
   6                font-size: 12pt;
   7                background-color: #ffffff}
   8 -->
   9 </STYLE>
  10
  11 <body bgcolor="#ffffff" link="#208b8b" vlink="#000080">
  12
  13 <p align=center><img src="mgm.gif"><br>
  14 <hr>
  15
  16 <p align=center>
  17 [ <a href="index.html">home</a> | <a href="faq.html">FAQ</a> | <a href="down.html">download</a> | <a href="trouble.html">troubleshooting</a> | <a href="docs.html">manual</a> | <a href="http://www.xiph.org/cvs.html">cvs</a> | <a href="mail.html">mailing lists</a> ]<p>
  18 <hr>
  19
  20 <h1>T.F.M. for Users</h1>
  21 <h2>caveat user</h2>
  22
  23 MGM is targetted at the power user that despises safety-interlocks.
  24 Out of the box, it Just Works.  If you want to fiddle around with
  25 things (and I <em>know</em> you want to fiddle around with things),
  26 MGM is designed to let you try pretty much anything you want to with
  27 the X resources. It gives you all the rope you need to shoot yourself
  28 in the foot in any number of creative ways.  It's fairly easy to make
  29 the code fall over by doing overly silly things, so be warned; MGM is
  30 generally not going to say 'no'.<p>
  31
  32 Thus, I don't want to hear any complaints about setting a negative
  33 window area and the darned thing trying to do it.  Bugs are a
  34 different matter, of course.  If you find a genuine case of "this
  35 should work, but it doesn't", fix it and submit a patch (or at least
  36 write <a href="mailto:mgm@xiph.org">mgm@xiph.org</a> about it). This
  37 documentation is also under source control.  Don't forget to patch
  38 bugs in the documentation.<p>
  39
  40 <h2>beginning</h2>
  41
  42 MGM is configured via X resources, like procmeter used to be.  As an
  43 example, my .Xresources entries for MGM look like this:
  44
  45 <pre>
  46 mgm*background:         #222222
  47 mgm*textpad:            0
  48 mgm.Forks.active:       false
  49 mgm.Swapstat.active:    false
  50 mgm.Pagestat.active:    false
  51 mgm.Context.active:     false
  52 mgm.Phoon*background:   black
  53 mgm.Phoon*foreground:   white
  54 mgm.Clock*background:   black
  55 mgm.Clock*foreground:   white
  56 mgm.geometry:           450x62+1+1
  57 </pre>
  58
  59 Resources can be set on the command line; for example, if given the following:
  60
  61 <pre>
  62 mgm -background DimGray
  63 </pre>
  64
  65 MGM parses the command line equivalent to <tt>mgm*background:
  66 DimGray</tt>.  Tk allows resource priority levels (a useful feature on
  67 which MGM relies).  Higher priorities take precedence over lower
  68 priorities (for details, see 'perldoc Tk::option'). Resources on the
  69 command line are given a resource priority of 80 (and thus generally
  70 take precedence over entries in .Xresources, which take precedence
  71 over built-in settings).<p>
  72
  73 <h2>resource naming</h2>
  74
  75 The MGM main window has a name of 'mgm' and a class of 'Mgm'. In the
  76 below examples, I use the window name to set resources. (Note that due
  77 to a Tk feature, specifically message passing between applications,
  78 all Tk MainWindows have a different name.  Thus, the first MGM started
  79 should be named 'mgm', the second 'mgm #2' and so on. However, Tk
  80 seems to have difficulty on some boxes and all but the first MGM end
  81 up being '#3'.)<p>
  82
  83 A number of resources are global to all of MGM.  Most resources,
  84 however, are set by module.  Module resources may be set for all
  85 modules of a given type (the module class is the same as the module
  86 name capitalized.  Most of the entries in my .Xresources file above
  87 are by-Class entries).  Modules may also be configured by instance;
  88 modules are numbered from 0 to n-1 (left-to-right or top-to-bottom).
  89 For example, to set a blue background for module number three, one
  90 should use:
  91
  92 <pre>
  93 mgm.3*background:   blue
  94 </pre>
  95
  96 Most modules use bargraphs; individual bars are also addressable as:
  97
  98 <pre>
  99 mgm*<em>Class</em>.bar.<em>number</em>
 100 </pre>
 101
 102 or
 103
 104 <pre>
 105 mgm.<em>number</em>.bar.<em>number</em>
 106 </pre>
 107
 108 <h2>resource lists</h2>
 109
 110 <h3>Global resources</h3>
 111
 112 The following resources are set once for the MGM main window and
 113 affect all of MGM. They should be set as
 114 "<tt>mgm.<em>resource</em></tt>".
 115
 116 <ul>
 117 <li><a href=r-bars.html>bars</a>
 118 <li><a href=r-geometry.html>geometry</a>
 119 <li><a href=r-lendemand.html>lendemand</a>
 120 <li><a href=r-stack.html>stack</a>
 121 <li><a href=r-widdemand.html>widdemand</a>
 122 </ul>
 123
 124 <h3>Instance resources</h3>
 125
 126 The following resources are common to all modules and may be set at
 127 the main window for all modules by using
 128 "<tt>mgm*<em>resource</em></tt>".  They may also be set for individual
 129 module classes or module instance.  A number of modules use Xresources
 130 beyond the list below; these resources are discussed in the
 131 documentation for the relevant module.
 132
 133 <ul>
 134 <li><a href=r-active.html>active</a>
 135 <li><a href=r-background.html>background</a>
 136 <li><a href=r-borderwidth.html>borderwidth</a>
 137 <li><a href=r-dimbackground.html>dimbackground</a>
 138 <li><a href=r-dimforeground.html>dimforeground</a>
 139 <li><a href=r-dimrelief.html>dimrelief</a>
 140 <li><a href=r-font.html>font</a>
 141 <li><a href=r-foreground.html>foreground</a>
 142 <li><a href=r-label.html>label</a>
 143 <li><a href=r-labelsize.html>labelsize</a>
 144 <li><a href=r-litbackground.html>litbackground</a>
 145 <li><a href=r-litforeground.html>litforeground</a>
 146 <li><a href=r-litrelief.html>litrelief</a>
 147 <li><a href=r-minx.html>minx</a>
 148 <li><a href=r-miny.html>miny</a>
 149 <li><a href=r-order.html>order</a>
 150 <li><a href=r-ratio.html>ratio</a>
 151 <li><a href=r-reconfig.html>reconfig</a>
 152 <li><a href=r-relief.html>relief</a>
 153 <li><a href=r-scale.html>scale</a>
 154 <li><a href=r-scalecolor.html>scalecolor</a>
 155 <li><a href=r-scalejustify.html>scalejustify</a>
 156 <li><a href=r-scalelenadj.html>scalelenadj</a>
 157 <li><a href=r-scalerefresh.html>scalerefresh</a>
 158 <li><a href=r-scalereturn.html>scalereturn</a>
 159 <li><a href=r-scalescroll.html>scalescroll</a>
 160 <li><a href=r-scalethresh.html>scalethresh</a>
 161 <li><a href=r-scalewidadj.html>scalewidadj</a>
 162 <li><a href=r-textpad.html>textpad</a>
 163 <li><a href=r-widgetpad.html>widgetpad</a>
 164
 165 </ul>
 166
 167 <h3>Module documentation</h3>
 168
 169 A number of modules implement extra features or resources.
 170 Documentation for each module currently distributed with MGM appears
 171 below.
 172
 173 <ul>
 174 <li><a href=m-battery.html>battery</a>
 175 <li><a href=m-biff.html>biff</a>
 176 <li><a href=m-clock.html>clock</a>
 177 <li><a href=m-context.html>context</a>
 178 <li><a href=m-cpustat.html>cpustat</a>
 179 <li><a href=m-diskstat.html>diskstat</a>
 180 <li><a href=m-diskuse.html>diskuse</a>
 181 <li><a href=m-forks.html>forks</a>
 182 <li><a href=m-hostlogo.html>hostlogo</a>
 183 <li><a href=m-loadav.html>loadav</a>
 184 <li><a href=m-memuse.html>memuse</a>
 185 <li><a href=m-netstat.html>netstat</a>
 186 <li><a href=m-pagestat.html>pagestat</a>
 187 <li><a href=m-phoon.html>phoon</a>
 188 <li><a href=m-spacer.html>spacer</a>
 189 <li><a href=m-swapstat.html>swapstat</a>
 190 </ul>
 191
 192 <h2>A very few examples</h2>
 193
 194 <h3>Vertical mode</h3>
 195
 196 command line:<br>
 197 <tt>mgm -bars horizontal -stack vertical</tt><p>
 198
 199 Xresources:
 200 <pre>
 201 mgm.bars:       horizontal
 202 mgm.stack:      vertical
 203 </pre>
 204
 205 <h3>Single battery graph with a picture</h3>
 206
 207 Xresources:
 208 <pre>
 209 mgm*active:                false
 210 mgm*Battery.active:        true
 211 mgm*Hostlogo.active:       true
 212 mgm*Hostlogo.label:
 213 mgm*Hostlogo.logopixmap:   ~/battery.xpm
 214 mgm.bars:                  horizontal
 215 </pre>
 216
 217 (of course, the picture actually has to exist)<p>
 218
 219 <h2>Todo</h2>
 220
 221 <h3>More modules</h3>
 222
 223 Other platforms still need the basic modules.  All platforms need more
 224 modules in general.<p>
 225
 226 <h3>Module subclassing</h3>
 227
 228 Most modules use the same hooks; they should be subclassed from a
 229 general graphing module supertype.<p>
 230
 231 <h3>Resources</h3>
 232
 233 Quite a few settings remain hardwired for no terribly good reason (eg,
 234 scale labels, fixed/autoranging graphs, etc).  They should be
 235 generalized to resource settings.<p>
 236
 237 <h3>Time graphs</h3>
 238
 239 Right now, MGM only does instantaneous graphing with bargraphs (what I
 240 happen to like).  It should have time graphing ala
 241 procmeter and xload as well (note that there's some trickiness here).<p>
 242
 243 <hr>
 244 <a href="http://www.xiph.org/">
 245 <img src="white-xifish.gif" align=left border=0>
 246 </a>
 247 <p>
 248 <font size=-2 color=#505050>
 249
 250 MGM will not get your whites whiter or your colors brighter.  It will,
 251 however, sit there and look spiffy while sucking down a major
 252 honking wad of RAM.<p>
 253
 254 MGM, Xiphophorus and their logos are trademarks (tm) of
 255 <a href="http://www.xiph.org/">Xiphophorus</a>.  These pages are
 256 copyright (C) 1994-1999 Xiphophorus. All rights reserved.<p>
 257
 258 </body>