Fvwm.3tcl

   1 .TH Fvwm n "Version 1.0" "Tcl Fvmw module interface"
   2 .SH NAME
   3 Fvwm \- Fvwm module interface for Tcl
   4
   5 .SH SYNOPSIS
   6 package require \fBFvwm\fR
   7 .PP
   8 \fBfvwm::send\fR \fIcommand\fR ?\fIwindowid\fR?
   9 .PP
  10 \fBfvwm::bind \fIevent\fR ?\fIscript\fR?
  11 .PP
  12 \fBfvwm::getConfig \fIvarname\fR ?\fIglobPattern\fR?
  13 .PP
  14 \fBfvwm::getWindowList \fIvarname\fR
  15 .PP
  16 \fBfvwm::setMask \fIlist\fR
  17 .PP
  18 \fBfvwm::iconPath \fIname\fR ?\fIoption\fR?
  19 .SH DESCRIPTION
  20
  21 \fBFvwm\fR package is a Tcl-only package which provides a way to build
  22 \fBfvwm\fR(1) modules on Tcl/Tk. Upon package initialization it checks
  23 if script is invoked as fvwm module and set ups pipes to communicate
  24 with \fBfvwm\fR. If script doesn't started as fvwm module, package
  25 initialization fails. Package provides procedures to set commands
  26 to fvwm and obtain information from it. It provides procedures
  27 to parse fvwm \fBWindowList\fR and \fBConfigInfo\fR messages and
  28 way to handle messages sended by fvwm just like Tk events.
  29 .PP
  30 Upon initialization \fBFvwm\fR package removes all fvwm-specific
  31 information from global \fBargv\fR variable and changes \fBargc\fR
  32 accordingly. This information can be accessed via package variables.
  33 .SH VARIABLES
  34 .TP 8
  35 .B Context
  36 Contain information about context in which module is called. It can
  37 be one of following strings:
  38 .RS
  39 .PP
  40 \fBNO_CONTEXT\fR, \fBWINDOW\fR, \fBTITLE\fR, \fBICON\fR, \fBROOT\fR,
  41 \fBFRAME\fR, \fBSIDEBAR\fR, \fBLEFT1\fR - \fBLEFT5\fR, \fBRIGHT1\fR -
  42 \fBRIGHT5\fR
  43 .PP
  44 which corresponds with parts of window decorations, provided by fvwm
  45 .RE
  46 .TP 8
  47 .B WindowId
  48 Integer (decimal) identifier of window, in whose context script was
  49 called
  50 .TP 8
  51 .B configFile
  52 Name of \fBfvwm\fR configuration file (probably useless for fvwm 2.0,
  53 because configuration info could be requested from fvwm itself.
  54
  55 .SH FUNCTIONS
  56 .TP 8
  57 \fBsend\fR \fIcommand\fR ?\fIwindowId\fR?
  58
  59 sends a command to fvwm. Command is a string exactly as it appears in
  60 \fB.fvwmrc\fR file. Command may be optionally followed by \fIwindow
  61 id\fR, in this case it can be applied to given window.
  62 .TP 8
  63 \fBsetMask\fR \fIlist\fR
  64 Instructs \fBfvwm\fR to send only certain events to this script.
  65 List should contain list of event names (see EVENTS below)
  66 .TP 8
  67 \fBbind\fR \fIevent\fR ?\fIscript\fR?
  68 binds a script with specific fvwm event (see EVENTS below)
  69 Script will be executed in global namespace
  70 appended by list of event arguments. If script is omitted,
  71 current script would be returned. Specifying empty string disables
  72 processing of given event.
  73 .TP 8
  74 \fBgetConfig\fR \fIvarname\fR ?\fIglobPattern\fR?
  75 Requests configuration information from fvwm and stores it
  76 in the array \fIvarname\fR. Glob pattern allows to restrict
  77 configuration to lines matching pattern.
  78 .RS
  79 .PP
  80 Global configuration lines such as \fBPixmapPath\fR would be always
  81 returned, but module-specific lines (those which start from \fB`*'\fR),
  82 would be returned only if they (with `*' stripped off) match given
  83 pattern. First word in line (without `*') would be used as array index.
  84 If multiple lines have same first word, they would be concatenated
  85 into Tcl list.
  86 .PP
  87 Entries which are lists of directories (\fBIconPath\fR,
  88 \fBPixmapPath\fR) are converted to Tcl list too.
  89 .RE
  90 .TP 8
  91 \fBgetWindowList\fR \fIvarname\fR
  92 Requests information about current desktop state and stores it
  93 in the given array variable. This array would have indices:
  94 .RS
  95 .TP 4
  96 .B Desk
  97 Number of current desk
  98 .TP 4
  99 .B Page
 100 list of four coordinates of current page
 101 .TP 4
 102 .B Focus
 103 containing Id of toplevel window.
 104 .TP 4
 105 .B DefaultIcon
 106 name of default icon (used for windows which have no icon defined)
 107 \fIwindowId\fB,frame\fR
 108 for each window there is list of following values: windowId of window
 109 frame, X of frame, Y of frame, width of frame, height of frame, height of title, border width,
 110 .TP 4
 111 \fIwindowId\fB,desk\fR
 112 number of desktop,
 113 .TP 4
 114 \fIwindowId\fB,flags\fR
 115 window flags field
 116 .TP 4
 117 \fIwindowId\fB,base\fR
 118 Offset of window base coordinates from top-left frame corner
 119 .TP 4
 120 \fIwindowId\fB,grid\fR
 121 resize width increment, resize height increment,
 122 .TP 4
 123 \fIwindowId\fB,min\fR
 124 minimum width, minimum height.
 125 .TP 4
 126 \fIwindowId\fB,max\fR
 127 maximum width, maximum height.
 128 .TP 4
 129 \fIwindowId\fB,iconIds\fR
 130 icon label window id (or 0), icon pixmap window id (or 0),
 131 .TP 4
 132 \fIwindowId\fB,gravity\fRwindow
 133 gravity, string, as defined in /usr/X11R6/include/X11/X.h
 134 .TP 4
 135 \fIwindowId\fB,title\fR
 136 Title of window
 137 .TP 4
 138 \fIwindowId\fB,iconName\fR
 139 Title of icon for this window
 140 .TP 4
 141 \fIwindowId\fB,resource\fR
 142 Resource name for this window
 143 .TP 4
 144 \fIwindowId\fB,class\fR
 145 Resource class for this window
 146 .TP 4
 147 \fIwindowId\fB,icon\fR
 148 Name of xpm file which is used as icon for this window
 149 .TP 4
 150 \fIwindowId\fB,miniIcon\fR
 151 Name of xpm file which is used as title icon (fvwm-95 only).
 152 .RE
 153 .TP 8
 154 \fBiconPath\fR \fIfilename\fR ?\fIoption\fR?
 155 Searches for given filename in fvwm pixmap or icon path and returns
 156 full pathname of it if found. I don't like an idea to return Tcl image
 157 because there is two Tcl extension which can create Xpm images - Img and
 158 Tix and I don't know which you'll prefer.
 159 .RS
 160 .PP
 161 \fIoption\fR can be either \fB-pixmap\fR or \fB-icon\fR which would
 162 cause \fBPixmapPath\fR or \fBIconPath\fR to be searched. Defaults to
 163 \fBPixmapPath\fR.
 164
 165 .SH EVENTS
 166
 167 Fvwm events are described in file \fBdocs/modules.tex\fR in fvwm
 168 distribution. If you are seriously planning to develop fvwm module,
 169 you should read it anyway. Note that event names in tcl Fvwm package
 170 differs in capitalization from C constants, defined in fvwm's
 171 \fBmodule.h\fR. List of names is shown below.
 172 .PP
 173 When event handler is called it is appended by long list of
 174 arguments. First argument passed is always event name, thus allowing
 175 you to use same handlers for several event types. All other fields
 176 are all field from fvwm packet body, even they are appear completely
 177 useless. Refer to \fBmodules.tex\fR for description of this fields
 178 .PP
 179 For convinience we would note that if event is related to particular
 180 window, its ID is passed as first argument, and if event have text
 181 message associated with it, it is always fourth (don't counting event
 182 name).
 183 .PP
 184 There is one additional event type \fBDeadPipe\fR, which occurs if
 185 eof on pipe is encountered. This event have default handler, which
 186 exits from script. It can be redefined to perform applicaton cleanup.
 187 .PP
 188 Event of type \fBError\fR have default handler, which raises Tcl error
 189 with same message as original event. This error is raised from
 190 \fBafter idle\fR handler to avoid closing pipe, which is default Tcl
 191 behavoir in case of unhandled errors in fileevent scripts.
 192
 193 .SH EVENT LIST
 194
 195 .TP 4
 196 .B FVWM 2.0.43 events
 197 NewPage
 198 NewDesk
 199 AddWindow
 200 RaiseWindow
 201 LowerWindow
 202 ConfigureWindow
 203 FocusChange
 204 DestroyWindow
 205 Iconify
 206 Deiconify
 207 WindowName
 208 IconName
 209 ResClass
 210 ResName
 211 End_WindowList
 212 IconLocation
 213 Map
 214 Error
 215 ConfigInfo
 216 End_ConfigInfo
 217 IconFile
 218 DefaultIcon
 219 String
 220
 221 .TP 4
 222 .B FVWM-95 only
 223 FunctionEnd
 224 MiniIcon
 225 ScrollRegion
 226 .TP 4
 227 .B Dummy event, generated by package itself
 228 DeadPipe
 229
 230 .SH ERROR REPORTING
 231
 232
 233 .SH SEE ALSO
 234 \fBfvwm(1)\fR, \fBdocs/modules.tex\fR in fvwm distribution
 235
 236 .SH BUGS
 237 getWindowList doesn't properly handle pixel color values, returned by
 238 fvwm. Parsing event args should be better (may be keyed lists),
 239 especially for AddWindow and ConfigureWindow. There could be
 240 problems with wrong capitalization in fvwm config file, because
 241 \fBgetConfig\fR and \fBiconPath\fR work in case-sensitive manner, and
 242 fvwm seems to be case-insensitive.
 243
 244 .SH AUTHOR
 245
 246 Victor Wagner <vitus@ice.ru>
 247
 248
 249
 250