.TH Fvwm n "Version 1.0" "Tcl Fvmw module interface" .SH NAME Fvwm \- Fvwm module interface for Tcl .SH SYNOPSIS package require \fBFvwm\fR .PP \fBfvwm::send\fR \fIcommand\fR ?\fIwindowid\fR? .PP \fBfvwm::bind \fIevent\fR ?\fIscript\fR? .PP \fBfvwm::getConfig \fIvarname\fR ?\fIglobPattern\fR? .PP \fBfvwm::getWindowList \fIvarname\fR .PP \fBfvwm::setMask \fIlist\fR .PP \fBfvwm::iconPath \fIname\fR ?\fIoption\fR? .SH DESCRIPTION \fBFvwm\fR package is a Tcl-only package which provides a way to build \fBfvwm\fR(1) modules on Tcl/Tk. Upon package initialization it checks if script is invoked as fvwm module and set ups pipes to communicate with \fBfvwm\fR. If script doesn't started as fvwm module, package initialization fails. Package provides procedures to set commands to fvwm and obtain information from it. It provides procedures to parse fvwm \fBWindowList\fR and \fBConfigInfo\fR messages and way to handle messages sended by fvwm just like Tk events. .PP Upon initialization \fBFvwm\fR package removes all fvwm-specific information from global \fBargv\fR variable and changes \fBargc\fR accordingly. This information can be accessed via package variables. .SH VARIABLES .TP 8 .B Context Contain information about context in which module is called. It can be one of following strings: .RS .PP \fBNO_CONTEXT\fR, \fBWINDOW\fR, \fBTITLE\fR, \fBICON\fR, \fBROOT\fR, \fBFRAME\fR, \fBSIDEBAR\fR, \fBLEFT1\fR - \fBLEFT5\fR, \fBRIGHT1\fR - \fBRIGHT5\fR .PP which corresponds with parts of window decorations, provided by fvwm .RE .TP 8 .B WindowId Integer (decimal) identifier of window, in whose context script was called .TP 8 .B configFile Name of \fBfvwm\fR configuration file (probably useless for fvwm 2.0, because configuration info could be requested from fvwm itself. .SH FUNCTIONS .TP 8 \fBsend\fR \fIcommand\fR ?\fIwindowId\fR? sends a command to fvwm. Command is a string exactly as it appears in \fB.fvwmrc\fR file. Command may be optionally followed by \fIwindow id\fR, in this case it can be applied to given window. .TP 8 \fBsetMask\fR \fIlist\fR Instructs \fBfvwm\fR to send only certain events to this script. List should contain list of event names (see EVENTS below) .TP 8 \fBbind\fR \fIevent\fR ?\fIscript\fR? binds a script with specific fvwm event (see EVENTS below) Script will be executed in global namespace appended by list of event arguments. If script is omitted, current script would be returned. Specifying empty string disables processing of given event. .TP 8 \fBgetConfig\fR \fIvarname\fR ?\fIglobPattern\fR? Requests configuration information from fvwm and stores it in the array \fIvarname\fR. Glob pattern allows to restrict configuration to lines matching pattern. .RS .PP Global configuration lines such as \fBPixmapPath\fR would be always returned, but module-specific lines (those which start from \fB`*'\fR), would be returned only if they (with `*' stripped off) match given pattern. First word in line (without `*') would be used as array index. If multiple lines have same first word, they would be concatenated into Tcl list. .PP Entries which are lists of directories (\fBIconPath\fR, \fBPixmapPath\fR) are converted to Tcl list too. .RE .TP 8 \fBgetWindowList\fR \fIvarname\fR Requests information about current desktop state and stores it in the given array variable. This array would have indices: .RS .TP 4 .B Desk Number of current desk .TP 4 .B Page list of four coordinates of current page .TP 4 .B Focus containing Id of toplevel window. .TP 4 .B DefaultIcon name of default icon (used for windows which have no icon defined) \fIwindowId\fB,frame\fR for each window there is list of following values: windowId of window frame, X of frame, Y of frame, width of frame, height of frame, height of title, border width, .TP 4 \fIwindowId\fB,desk\fR number of desktop, .TP 4 \fIwindowId\fB,flags\fR window flags field .TP 4 \fIwindowId\fB,base\fR Offset of window base coordinates from top-left frame corner .TP 4 \fIwindowId\fB,grid\fR resize width increment, resize height increment, .TP 4 \fIwindowId\fB,min\fR minimum width, minimum height. .TP 4 \fIwindowId\fB,max\fR maximum width, maximum height. .TP 4 \fIwindowId\fB,iconIds\fR icon label window id (or 0), icon pixmap window id (or 0), .TP 4 \fIwindowId\fB,gravity\fRwindow gravity, string, as defined in /usr/X11R6/include/X11/X.h .TP 4 \fIwindowId\fB,title\fR Title of window .TP 4 \fIwindowId\fB,iconName\fR Title of icon for this window .TP 4 \fIwindowId\fB,resource\fR Resource name for this window .TP 4 \fIwindowId\fB,class\fR Resource class for this window .TP 4 \fIwindowId\fB,icon\fR Name of xpm file which is used as icon for this window .TP 4 \fIwindowId\fB,miniIcon\fR Name of xpm file which is used as title icon (fvwm-95 only). .RE .TP 8 \fBiconPath\fR \fIfilename\fR ?\fIoption\fR? Searches for given filename in fvwm pixmap or icon path and returns full pathname of it if found. I don't like an idea to return Tcl image because there is two Tcl extension which can create Xpm images - Img and Tix and I don't know which you'll prefer. .RS .PP \fIoption\fR can be either \fB-pixmap\fR or \fB-icon\fR which would cause \fBPixmapPath\fR or \fBIconPath\fR to be searched. Defaults to \fBPixmapPath\fR. .SH EVENTS Fvwm events are described in file \fBdocs/modules.tex\fR in fvwm distribution. If you are seriously planning to develop fvwm module, you should read it anyway. Note that event names in tcl Fvwm package differs in capitalization from C constants, defined in fvwm's \fBmodule.h\fR. List of names is shown below. .PP When event handler is called it is appended by long list of arguments. First argument passed is always event name, thus allowing you to use same handlers for several event types. All other fields are all field from fvwm packet body, even they are appear completely useless. Refer to \fBmodules.tex\fR for description of this fields .PP For convinience we would note that if event is related to particular window, its ID is passed as first argument, and if event have text message associated with it, it is always fourth (don't counting event name). .PP There is one additional event type \fBDeadPipe\fR, which occurs if eof on pipe is encountered. This event have default handler, which exits from script. It can be redefined to perform applicaton cleanup. .PP Event of type \fBError\fR have default handler, which raises Tcl error with same message as original event. This error is raised from \fBafter idle\fR handler to avoid closing pipe, which is default Tcl behavoir in case of unhandled errors in fileevent scripts. .SH EVENT LIST .TP 4 .B FVWM 2.0.43 events NewPage NewDesk AddWindow RaiseWindow LowerWindow ConfigureWindow FocusChange DestroyWindow Iconify Deiconify WindowName IconName ResClass ResName End_WindowList IconLocation Map Error ConfigInfo End_ConfigInfo IconFile DefaultIcon String .TP 4 .B FVWM-95 only FunctionEnd MiniIcon ScrollRegion .TP 4 .B Dummy event, generated by package itself DeadPipe .SH ERROR REPORTING .SH SEE ALSO \fBfvwm(1)\fR, \fBdocs/modules.tex\fR in fvwm distribution .SH BUGS getWindowList doesn't properly handle pixel color values, returned by fvwm. Parsing event args should be better (may be keyed lists), especially for AddWindow and ConfigureWindow. There could be problems with wrong capitalization in fvwm config file, because \fBgetConfig\fR and \fBiconPath\fR work in case-sensitive manner, and fvwm seems to be case-insensitive. .SH AUTHOR Victor Wagner