XW-Mod-Util (xwmodutil.so)
= = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
Utility in the form of a dynamically linked, shared library that,
once attached to the initializing process,
can perform runtime actions or add new functionalities.
Examples include: maximize window, change application icon
or execute shell command.
Build Instructions
* Enter project directory, the "makefile" is located there.
* Use command: "make release" to build the library.
* On success, new file "xwmodutil.so" is created under "/bin" subdir.
* Thats it, copy the shared library to your directory or create symlink to it.
There is no system wide install step.
Configuration
Configuration must be done using the environment variable named
XWMODUTIL_CFG. All selectors and actions must be specified
as colon separated list.
SELECTORS
--------------
Selectors provide a way on how to search for the target window in the
initializing process. Just like actions, at least one must be
added to the configuration environment variable.
bOnFirstInput=1
Action is activated by first user input. Key press,
mouse button press or mouse move.
nSearchWndAfter=ms
Search for the target window by: (1) waiting specified amout of time,
then (2) checking if active window is from the current process.
Search is performed only one time. This is the crude way, if
the encountered active window does not belong to the current
process, no action is taken. Parameter is the timeout value
in milisecsonds (eg. 1000 is 1 second).
nUseMapFromTo=FROM,TO
Action is performed on every N-th call to the XMapWindow(),
while N >= FROM and N < TO.
Eg. use 'nUseMapFromTo=3,4' to perform the actions when
the process performs it's third call to the XMapWindow().
XMapWindow() is the X11 funtion from the Xlib. Programs use it
to make every window they create visible. Using this API funtion,
rather than one of create-window ones, seems to be more reliable.
WINDOW ACTIONS
------------------
Preferably, keep terminal window open to see what results
XWMODUTIL prints to the STDOUT to tweak it's configuration.
mx2
Maximize window.
mi2
Minimize window.
exec2=c
Execute a shell command once target window has been selected.
Thanks to text tags, shell command can receive window identifier
and do further processing. Also see note#2.
Tag list: @pid@, @wid@ and @dpy@.
uwp2
Update window pid property. The "_NET_WM_PID".
swi2=f
Set window icon.
Please note that image loading routine is very simple,
Though only one format is supported, it is full 32-bit
per pixel format with alpha channel translucentcy.
Only PAM images with RGBA pixel format are supported.
Value must specify valid path to the PAM image.
Example image size: 64x64.
Command example, using Ffmpeg, to convert to comaptible format:
$> ffmpeg -i ./a.png -an -f image2 -c:v pam -pix_fmt rgba ./a.pam
(See also note#2).
swg2=s
Set window geometry (same as '-geometry' switch from Gnome
environment (format: WxH+X+Y)).
Eg: "swg2=400x300+64+32"
On PROCESS init ACTIONS
----------------------------
Actions on XWMODUTIL initialization performed regardless
if any window has been selected.
pidfile=f
Create pid-file that holds current process ID and is automatically
deleted once process exits (see note#2).
szActiveIf=t
Optional condition that determines whenever XWMODUTIL should
switch into dormant state. By default XWMODUTIL is in active state.
A text that is to be matched on argv[0] of the current process.
Simple text matching only.
bClearPreload
If set, XWMODUTIL clears itself from the LD_PRELOAD env var.
Note: simple string matching, name of shared library cannot be changed.
This action is performed only if not switched into dormant state
(see 'szActiveIf').
note#2:
Percent-decoding where indicated. Encoding detection is by tail characters,
ie. decoding is done if the last 3 characters have been set to the
'%HH' sequence, eg. '%20'. The '%00' sequence can be used to make
that last character removed from the result.
Examples
# Setup two environment variables, LD_PRELOAD and XWMODUTIL_CFG.
# Once XWMODUTIL initializes itself, it changes window icon of
# the 'leafpad' to "icon_file_64x64.pam".
export LD_PRELOAD=/path/to/xwmodutil.so
export XWMODUTIL_CFG="bOnFirstInput:swi2=/path/to/icon_file_64x64.pam"
leafpad