<!doctype Linuxdoc system>

<article>

<title>AfterStep documentation
<author>Compiled by Guylhem Aznar <tt/guylhem@danmark.linux.eu.org/
<date>v1.4 ; February 1998

<abstract>
Copyright &copy; November 1997, Diego Zamboni &amp; Copyright &copy; February
1998 Guylhem Aznar.

Freely redistributable under the terms of LDP license, Version 2, January 1998.
</abstract>

<toc>

<sect>Introduction<p>

AfterStep is a continuation of the BowMan window manager which was
originally put together by Bo Yang.  BowMan was based on the fvwm window
manager, written by Robert Nation.  Fvwm was based on code from twm.  And
so on...  It was originally designed to emulate some of the look and feel
of the NEXTSTEP user interface, but has since taken steps towards
adding more useful, requested, and neat features especially in 1.4 version !
The changes which comprise AfterStep's personality were originally part of
bowman development, but due to a desire to move past simple emulation and into
a niche as its own valuable window manager, AfterStep designers decided to
change the project name and move on.

     Important features of AfterStep include:

1. Wharf: a free-floating application loader which can "Swallow" running
    programs and also can contain "Folders" of more applications.

2. Gradient filled TitleBars with 5 button : help/zap, action/tasks,
    iconize/maximise, shade/stick & close/destroy buttons

3. Gradient filled root window PopUp menus which can be configured to
   accomodate different tastes and styles of management

4. NEXTSTEP style icons which give a consistent look to the entire desktop

5. Pixmapped Pager with desktop pixmmaping

6. Easy to use look files, to share you desktop appearance with your friends

7. Start menu entries in a hierarchy of directories

8. WinList : a tasklist which can be horizontal or vertical

9. Many modules & asapps to give a good look to your X window station

     Initiation files will look very familiar to users of fvwm 1.24r since
it shares a good number of commands and owns the same syntax.
As those who know can attest, this can yield a tremendous amount of flexibility.

     AfterStep now also has its own mailing list devoted to discussion
of AfterStep code, features, help, and the future of the project. If you
would like to subscribe, simply send an email message to:

<tscreen><verb>
afterstep-request@eosys.com
or
afterstep-dev-request@eosys.com
</verb></tscreen>

  The body of the message should contain the word 'subscribe'.

  Well, if you like what you see, have a problem, or would like to join in
development, let me know.

  Have Fun!

<sect>New in 1.4 version<p>

Please read man page for more information !

1) New configuration mode


1-1) Directories

Now, everything goes to ~/GNUstep/Library/AfterStep or /usr/share/afterstep !

However, this last solution isn't recommanded because startmenu must therefore
be world writable !

New versions of asapps (ie the nice little programs included in apps/) will
also put their config. file here in a near future, like modules currently do.

1-2) AfterStep config. files & colordeph

If your colordepth is 8bpp, files ending by .8bpp will be used, the same for
16bpp & 32bpp : it allows you to have different configuration for color-rich
or color-poor X, different videocards, etc.

1-3) Config. files in this directory


1-3-A) Files you must *not* change

1-3-A1) "autoexec.(yourcolordepth)bpp" will launch several programs at startup;
however, your desktop configuration when you close AfterStep is saved in
~/GNUstep/Library/AfterStep/.windows (this file is called from autoexec)

1-3-A2) "base.(yourcolordepth)bpp" configures directories where AfterStep, its
modules & its pixmaps are

1-3-A3) "startmenu" is remade everytime you start/restart AfterStep : don't
edit it ! All changes will be lost !

1-3-A4) in "desktop" directory, you mustn't change files in desks/ hierarchy.


YOU SHOULDN'T NEED TO MODIFY THEESE FILES !!!


1-3-B) Files you can change

1-3-B1) "modulesname" configures modules (like Auto, Wharf, Pager, Audio) :
change it the way you like (except Pager background files)

1-3-B2) "start" directory : simply put here files to add to 'Start' menu, for
exemple, creating a file called 'My option' containing 'xedit' will create a
'My option' entry in 'Start' menu, which will lauch 'xedit' when clicked.

You can also createe subdirectories to create submenus !

All this is read when AfterStep is launch & a temporary "startmenu" file is
created, so don't edit it since all your changes will be lost !

1-3-B3) "desktop/backgrounds" directory : put there pictures you'd like to put
in the background, however XPM format is obligatory !

cp mypicture.xpm ~/GNUstep/Library/AfterStep/desktop/backgrounds

Then, restart AfterStep & open 'Start/Desktop/Background pictures' to change
screen background : your picture has been automatically added to Desktop menu.

Solid colors can also be put, just copy this example :
~/GNUstep/Library/AfterStep/desktop/backgrounds/black.xpm

1-3-B4) "desktop/buttons" directory : if you add your own window buttons here,
you will have to create a look file

1-3-B5) "desktop/icons" directory : if you add your own window icons here,
you will have to create a feel file

1-3-B6) "desktop/sounds" directory : if you add your own sounds here, you will
have to edit "modules" to configure Audio

1-3-B7) "desktop/feels/" & "desktop/looks" : see section below



2) New functions

Start menu is opened when you left click in the root window while right
clicking will open a list of all windows opened

2-1) look & feel files

"look" & "feel" files live in "desktop/looks" & "desktop/feels/"; they define
windows colors & reactions !

If you wish to create your own file, just refer to afterstep man page !

If you want to change AfterStep look without restart it, just select the look
of your choice in 'Start/Desktop/Looks/', in 2 seconds all windows will be
redrawn with that look & all modules will be restarted.

If you want to change AfterStep feel (ie the way it reacts), just do the same
with feel files !

NB : You can use diffent look & different feel files on different desktops,
however since this is very CPU hungry, it isn't defined by default !

Just edit configure.h & define DIFFERENTLOOKNFEELFOREACHDESKTOP !

NB2: But by default, you can use different pictures for each desktop, just
change them in 'Start/Desktop/Background picture', to add more options simply
put XPM pictures in "desktop/backgrounds" directory.

2-2) GetHelp

When you want to open a program manpage, just right click on left button !
Help program is defined in configure.h

2-3) Zap

When you want to change to next window with the less effort possible, just
type Alt-Tab or left click on left button !

2-4) Menu fonctions

To move a windows to another desktop (you can also drag in from the pager), to
resize it (...) just left click on second left button

2-5) Windows opened

To know which windows are opened, just right click on second left button.
You can also focus on a specific window clicking on it in this list !

2-6) Put in foreground / Put in background

Click on the titlebar to do this ; Alt-F11 will put current window on top af
all the others while Alt-F10 will put current window in the backgound of all
the others !

2-7) Iconify/Maximise

Iconifying a window is changing it to a little picture (with or without
background, edit configure.h to change this)

Left clicking/Right clicking on first right button will respectively do this !

2-8) Shade/Stick

Shading a window is hiding it behind its titlebar.
Sticking it is making the window follow you on any screen.

Left clicking/Right clicking on second right button will respectively do this !

2-9) Closing/Killing

Closing a window is ending a program normally.
Killing a window is closing a program which doesn't answer anylonger.

Left clicking/Right clicking on third right button will respectively do this !

2-10) Desktop saving

When you close AfterStep, all the windows still opened are saved in
~/GNUstep/Library/AfterStep/.windows, next time you start, AfterStep will
open them by himself !

Edit configure.h  & add NO_SAVEWINDOWS if you don't want that.

Module Save isn't doing the same : it writes desktop state in ~/.xinitrc
(default for each relauch), so for exemple :

* put "modules/Save/Save desktop into xinitrc" into
"~/GNUstep/Library/AfterStep/start/Modules/" & restart afterstep : this entry
is added into startmenu.

* open a clock, a biff, some programs you always want to have & run :
Modules/Save desktop into xinitrc

* close all this stuff FIRST, then afterstep & restart : it's back here !

* if you then reclose & restart AF, programs you've written in xinitrc will
also be written in ~/GNUstep/Library/AfterStep/.windows, therefore you should
ONLY USE afterstep default saving rather than Module Save's ugly one !


2-11) Start/Quit/Close this session

This will ask you wheter or not you want to close current session.

2-12) asapps

Many programs are included, like asclock, ascd ...

To run any, just click on 'Start/Application/StEP Applications'

NB : if you don't compile & install xiterm with XPM support, you won't be able
to run "X terminal (pixmap)" !

NB2: IF YOU WANT TO USE "pppchecker" TO CALL, DON'T FORGET TO CREATE ~/.ppprc ;
AN EXEMPLE IS INCLUDED IN applications/asppp/ppprc

NB3: If you're using bash & xiterm, try :

<tscreen><verb>
PS1='(\u@\h:\w)% \[\033]0;\w\007\]'

tcsh fans will use :

set prompt="%{\033]2;%n@%M:%/ - %l\007\033]1;%l@%m\007%}[%T] %B%m%b:%.02 %# "
</verb></tscreen>

And watch xiterm titlebar while you change directory ... very COOL !


<sect>History of AfterStep<p>

1.4.0: Final ! I'm very excited & I hope people will like this version

       Udated afterstep logo in Banner :^)

       Updated all documentation (takes loooots of time)

       Changed gnustep to GNUstep to go with the flow...

       Added a true TaskBar thanks to Ren'e Fichter

       Added autoconf support for afterstep, now xiterm depends on it

       Cleaned headers files & checked copyrights in C files

       Checked & updated manpages for afterstep & its modules

       Fixed Sticky bug (clicking on Pager unsticked it)

       Added autoraise to Focus (seems quite normal)

       Checked & modifyed icons included

       Added os-dependant.h

       Rewrote README in a clearer maneer for "copyright" explainations

pre1.4:

3:     Changed configuration files : desktops are now in ~/desks/deskN

2:     Changed modules & iconify code, many cleanups

1:     FINISHED NO_ICON_BACKGROUND !!! It was soooo hard to have transparent
       icons of the *right* size !
       Fixed little left corner bug new in pre0 (from Rob patch)

0:     Applyied many patches (cooltitle from Rob Malda, Animate patch from
       Frank Scheelen, etc.) : Title is 3 dimentional, Animate flips x&y axis

       Made possible to use different look & feel files for each desktop (when
       you click on the Pager towards another desktop, a QuickRestart is
       performed & new desktop specific files are read)

       Cleaned QuickRestart (crashed AfterAtep before)

       Commented Auto in autoexec since it unsticked Pager : ugly bug !

1.3:

55:    Added ascd, David Muse sent me a working version of asfsm (very nice !!)

       Changed save window code : now saving in
       ~/gnustep/library/AfterStep/.window

54:    New iconify code is now working (at least !!!)

53:    Just realised I hadn't written changes in this file for a long time !

       Somethings I can't therefore remember :)

       Added feel changing (like looks)

       Checked included icons ; worked on them & put the same for 8bpp & 16bpp
       with just reduced color, deleted many which had copyright problems, so
       please send me ORIGINAL icons, not some you've stolen from another OS !

       Started to split desktop : backgrounds now differ from a desktop to
       another (i.e. when you use ChangeBG) now working on differing look +feels
       for each desktop

       Included more looks & less backgrounds (get them from AS1.2 if you want)

       Fixed bugs in Pager for backgrounds

       All included apps are now GPL (mailed original authors)

51:    Ported many many Modules to AfterStep

       Added .8bpp & .16bpp files

       Modyfied Pager to support background change

       Added GetHelp, ChangeBackground & ChangeLook functions

       Changed keybindings

       Added ToFix file

       Fixed install-time bigs

1.2:   Put a brand new configuration mode with ~/.step director

       Name chosen for Afterstep/WindowMaker compatible programs : StEPprogs

       Added even more icons & pixmaps

       5 buttons are now by default

       Put some diffs in documentation/patches for people to play with :)

       Started SGML documentation

       Added applications dir, with Window Maker support for many (hope its
       dock will be available for Afterstep soon !)

1.1:   Added many icons

       Defined new goals

       Deleted M4 support

1.0:   Final

       -Updated version.h to 1.0! (finally!)

       -Standardized the cursor selection

       PRE7

       -Fixed AnimateTwist bug

       -Fixed windowlist hotkey bug 

       -Fixed problematic mousebindings

       -Fixed iconized bug

       -No longer eats up all cpu in a select loop if there are

        more FD than FD_SETSIZE

       PRE6

       -Fixed Solaris WharfAnimateMain crashing bug

       -Top pixel line of the titlebar now acts as it should

       -NoFocus really works correctly in ClickToFocus mode

       -Icons are now dynamically updated

       -Animate's usleep() has been replaced with libafterstep's 

        sleep_a_little() for portability

       -Wharf pixmaps no longer require a transparent pixel

       -Minor animate type cleanup

       -Replaced PI in Animate with AS_PI to ease the pain

       -Added new and final (?) afterstep manpage

       -Majorly updated FAQ

       -Included a guide to the module interface

       PRE5

       -Added a fix for menus with different fonts 

       -Changing geometry information now given in the center

       -Added Animate module and AfterStep lockability

       -Shaded windows should update visibility properly now

       -Worked around locking problems related to NumLock

       -RaiseLower now works as expected on maximized windows

       PRE4

       -Shade code modified and hopefully fixed

       -Added shade animation

       -Changed color allocation code for gradients so that the

        resource leak bug(?) is hopefully fixed (no more slowdowns)

       -Added Wharf Swallow-Exec 

       -Due to overwhelming demand, included penguin.xpm

       PRE3

       -Added ClickToRaise focus mode

       -Eliminated problem with iconified windows being
        deiconified on a different virtual desktop

       -Overlapping StaysOnTop windows no longer change the
        window order

       -Added flag to ClickToFocus to "catch" the raising
        mouse click

       -Changed order of ASWindow list to be top-down

       -CirculateUp and CirculateDown now work correctly

       -Updated manpage to reflect the recent changes

       -The window placement box now accurately represents the
        window it is placing

       -Installme now appends a before.`date +%H%M%S` to files
        that it replaces

       PRE2

       -Fixed Wharf multiple-column bug

       -Eliminated ClickAndHold option...PopDown menus now 
        behave intelligently and will decide which menu style
        was desired

       -Fully updated manpages

       -Readded Cursor selection for TitleBar buttons

       -Changed default Cursor for PopDown menus for a more uniform
        look

       -Shrunk file size of all regular icons by eliminating all
        references to xv

       -Removed the debugging information that was causing confusion

       -Installme no longer creates /backgrounds

       PRE1

       -Alfredo Kenji Kojima (kojima@inf.ufrgs.br) has joined the 
	AfterStep development team as a primary member ; added to Wharf : button
	pushing styles, configurable border drawing, change of icon creation
	code (Does not use shape extension anymore, each icon window now
	contains the whole background), OffiX drop support, animation, withdraw
	on button2 click, icon overlaying, sound bindings.

       -Added Icon Titles

       -Fixed WharfRows bug

       -Focused TitleBar text is rendered with gradients

       -Fixed handle drawing bug

       -Icons now have configurable backgrounds

       -Added configurable sound bindings for Wharf

       -OffiX compatible Drag and Drop has been added to Wharf

       -No longer limited to two TitleBar buttons

       -TitleBar button style is configurable

       -Wharf now has TextureTypes similar to the popdown menus'

       -Wharf Folders now can be animated

       -Miscellaneous additional Wharf enhancements and fixes

       -Installme should now handle minor username disasters

0.98a: BETA33

       -Added Sticky gradient patch

       -Shade crashes should be completely eliminated

       -Titlebars can now be textured with pixmaps

       -All manpages have been added

       -Included the updated afterstep FAQ

       -Installme has been modified 

       BETA32

       -Miscellaneous Wharf "fixes", allowing for single-buttoned

        Wharfs to function properly as Folders

       -Wharfs in row mode now properly display their Folders 

       BETA31

       -WharfGeometry now properly handles positve and negative 
        values of X

       -Eliminated gap between -0+0 Wharf Folder buttons and their 
        children 

       -Installme will now ask for display depth

       BETA30

       -Added "accident" proof texture/maxcolor parsing 

       -Improved gradient speed

       -Misc. gradient bugfixes

       -Eliminated the need to link with the math library

       -Fixed Shade crash on noname windows

       -Fixed Shade color-xterm crash bug (?)

       -Added new gradient types

       -Multicolumn Wharf fix

       -Included asclock release 10

       BETA29 

       -Children of Popup menus no longer are gapped if their
        parents have an even width

       -Installme script now sets permissions correctly 

       BETA28

       -Root PullDown menu's children are now aligned properly 

       -WharfGeometry -0+0 works like it should ... no gap

       -Reworked and improved the Installme script

       -Added more icons to the icons directory

       -Created a backgrounds directory for selected backgrounds

       -Improved, updated, and even commented the sample.steprc 

       BETA27

       -Gradient color specifications are now in standard RGB format

       -More gradient options: see README.gradient

       -Misc. code clean up, primarily for DEC operating systems

       BETA26

       -Unfocused windows now also have gradient TitleBars

       -Paging speed has been increased tremendously 

       -Updated sample.steprc - more comments to come soon

       BETA25

       -Wharf is now more resilient to pre-folder pushes

       -Updated Sun's header file location to match reality 

       BETA24a

       -Cosmetic change to remove the small pixel that is displayed
        on the top left corner of every menu box that is highlighted 

       BETA24

       -Added Titlebar gradient code

       -Fixed "no-window-title" bug

       BETA23a 

       -Minor cosmetic change to left side of PullDown Menu's TitleBar

       -PullDown Menu TitleBar no longer is highlighted on focus

       BETA23

       -Added Menu Gradient code...check README.gradient for help
        in using 

       -Made Wharf.beta the standard Wharf

       -No longer need to press a folder button first on Wharf

       -added StubbornPlacement code back in

       BETA22

       -Added beta code for Wharf Folders in directory modules/Wharf.beta

       -Readded Memory Leak fix that was added in BETA20 but absent in BETA21

       -Fixed Maximize bug introduced in the last version

       BETA21

       -Yet more work on the Restart bug -- Restart works from the menu item 
        but not Wharf on a test system where it had not previously been working

       -Icons automatically reposition themselves to take up the least space 
        when one is deiconified

       BETA20

       -More work on Restart bug

       -Hopefully stopped up a memory leak 

       -added CREDITS file

       BETA19

       -Hopefully fixed Restart bug (thanks to Dave Adkins) 

       BETA18

       -Restart code modified to hopefully fix linux problems

       -Miscellaneous code cleanup

       BETA17

       -Shade Restart bug is fixed

       -Maximize function no longer erases the bottom handles

       -asclock 7 defaults to English 

       BETA16 

       -Updated asclock 

       BETA15

       -Added the *correct* asclock ;^)

       BETA14

       -CirculateUp/Down has been revised to discriminate against
        windows without borders (ie, root windows and popups)

       -Added a TODO file

       -Added the Banner module by Robert Depenrock, although still 
        have no logo for it (hint,hint)

       -Updated asclock version to 6

       -Added icon set with reduced colors to the icons/8bit directory

       -Updated manpages and added a page for the Auto module

       BETA13pre5

       -Added the updated version of asclock to the hierarchy

       BETA13pre4

       -MaxSwallow Wharf option has now been added in order to fully 
        Swallow an app (such as asclock), while still allowing others
	to be 48x48

       BETA13pre3

       -replaced tkdate with asclock (author is Christian Beat), which 
        for now must be compiled individually

       -introduced minor kludge that makes Swallow-ed apps hold a 
        geometry of 57x55...this WILL be fixed soon

       BETA13pre2

       -Implemented a working(?) NoFocus steprc option that will, thus
        far, only work with SloppyFocus...why would you want it 
	otherwise, really?

       -Probably broke other things

       -Added some icons to the hierarchy

       BETA13pre1

       -Added experimental NoFocus steprc Style option in order to 
        designate that a window should not take a focus

       -Included mini-faq in the hierarchy

       BETA12

       -Added MenusHigh steprc option to allow for the root popdown menu
        to spawn child menus beginning at the same height as the parent

       -Added TkDate to the src directory

       -Some other fix I cannot remember

       PreBETA12

       -Added some sounds to the hierarchy 

       -Converted fvwm2's superior FvwmAuto module and added it
        to the modules hierarchy, while eliminating the older 
	AutoRaise code

       -HotKeys on root popdownmenu now work properly 

       -Fixed ClickToFocus problem 

       -Fixed Highlight problem on Wharf 

       -Users with 8bit displays should no longer have problems with
        Wharf so long as they select icons that don't overrun the 
        8bit colormap limitation

       -Miscellaneous Wharf fixes to newer problems   

       -Once again, icons must no longer be 48x48...however, they 
        should not exceed that size

       -Improved 3D look of Wharf's pushed buttons

       -Introduced the "feature" that XPM files utilized in Wharf
        must be exactly 48x48 and must contain at least one
        transparent pixel

       -Changed hightlight colors

       -Added Audio module 

       -minor popupmenu fix 

       -Changed the bowman name to AfterStep in order to represent the
        project's desire to establish the window manager not as one
        bound to emulation, but rather as one desiring new 
        features and functionality irregardless of what other products
        possess
        
0.93j: -Cosmetic popupmenu fix 

       -MAJORLY optimized Wharf button pushing 

       -Eliminated MWMFunctionHints, MWMDecorHints, and MWMHintOverride
        bowmanrc options

       -Eliminated GoodStuffFore and GoodStuffBack bowmanrc options 

       -Eliminated DoubleClick ability on Wharf due to its being
        obviated by "pushable" buttons...may later add a compile option
        to add DoubleClick support onto NoPush buttons

       -Added *WharfNoPush bowmanrc option which disables the "pushable"
        buttons on Wharf and provides a means for Wharf usage on 
        8bit displays

       -Swallowed Wharf buttons are no longer pushable

       -Created minor Installme script which should help some newbies

       -Added new icons to the icons directory 

       -Eliminated the 3 dots on the Wharf buttons for the time being 

       -Wharf now no longer takes a focus 

       -Added Pager module which is a modified version of FvwmPager 

       -Keyboard Shortcut root popup menu ClickAndStick fixes

       -More Wharf bug fixes 

       -Major root popup menu bug fix  

       -Cleaned up the button pixmap 

       -Made Wharf buttons three dimensionally "pushable" 

       -fixed highlight color problems around executed modules

       -added "OldMenus" bowmanrc option to allow for the old 
        "click-and-hold" style root popup menu

       -removed Lenience bowmanrc option

       -Changed iconbox cursor to the normal arrow (will soon be a 
        bowmanrc option)

       -Fixed 24bit colormap bug with Wharf

       -Added *WharfClick bowmanrc option which can be used to
        select how many (Single or Double) clicks will activate a 
        program from Wharf

0.93i: -further changed the default action of the root popup menu

       -fixed button highlight scheme on maximized and shaded windows

0.93h: -changed action of the root window's popup menu
            
0.93g: -added PutOnTop function

0.93f: -added Shade function

       -added TripleClick support

0.93e: -fixed hilight on left edge of Wharf icons

       -Wharf now responds only to double click

       -Fixed icon positioning

       -Distance between pop-up menu bars is reduced.

0.93d: -first beta release Sun Sep 24 1995

<sect>Frequently Asked Questions (FAQ)<p>

  Maintained by Diego Zamboni, to be SGMLlized soon

  Table of Contents:

  1.      General information

  1.1.    What is AfterStep?

  1.2.    What is its history?

  1.3.    What are its main features?

  1.4.    Is it compatible with fvwm-2?

  1.5.    Where can I get this FAQ?

  1.6.    Who contributes to this FAQ?

  1.7.    What are the AfterStep-related mailing lists?

  2.      Getting and installing AfterStep

  2.1.    Where do I get AfterStep?

  2.2.    Other important WWW pages

  2.3.    What is the latest version of AfterStep

  2.4.    I've compiled AfterStep for my system but every time I try to
  use it I receive the message: Cannot open display. What should I do?

  2.5.    How do I enable sound in AfterStep?

  2.6.    I grabbed TkStep and Tcl7.6 and tried to install TkStep, but
  it doesn't work

  2.7.    Why doesn't ASCP run on my system?

  2.8.    How can I install AfterStep without being root?

  3.      Icons, graphics and pixmaps

  3.1.    Icons staying put

  3.2.    Colormap issues

  3.3.    Icons disappear from Wharf. What's wrong?

  3.4.    How do I create an icon with a transparent pixel?

  3.5.    Why doesn't program `xyz' work in 16bpp?

  3.6.    Why doesn't xv do `xyz' in 16bpp?

  3.7.    Why don't icon names change when the application changes it?

  3.8.    Suddenly, some windows stay always on top. Why?

  3.9.    Can you add `xyz' to the Wharf?

  4.      Modules


  4.1.    How do I get multiple Wharfs/Pagers on the screen?

  4.2.    How can I get ASclock to properly appear in Wharf?

  4.3.    How do I configure asclock to use fewer colors?

  5.      General usage, features and bugs

  5.1.    Why does AfterStep get slower and slower until I restart it?

  5.2.    Click-to-focus dies

  5.3.    What is this `Shade' thing?

  5.4.    When I restart AfterStep, it kills X. What gives?

  5.5.    What is swallow-exec?

  5.6.    I upgraded to 1.0pre4 or later, and now the Wharf doesn't
  work. What happens?

  6.      Other AfterStep-related applications

  6.1.    What is this WindowMaker I keep hearing about in the list?

  6.2.    What is ASCP?

  6.3.    What is TkStep and why do I want it?

  7.      Other AfterStep-unrelated applications

  7.1.    I have a problem with program `xyz'

  7.2.    Why am I having `xyz' problem/how do I do `xyz' with a
  terminal window?
  ______________________________________________________________________

  1.  General information

  1.1.  What is AfterStep?

  AfterStep is a Window Manager for X that emulates the NEXTSTEP look
  and feel, which many adepts will tell you is not only the most
  visually pleasant interface, but also one of the most functional and
  intuitive out there.

  1.2.  What is its history?

  From the man page:


       AfterStep is a continuation of the BowMan window manager
       which was originally put together by Bo Yang.  BowMan was
       based on the fvwm window manager, written by Robert Nation.
       fvwm was based on code from twm.  And so on...  It is
       designed to emulate some of the look and feel of the
       NEXTSTEP user interface, while adding useful, requested, and
       neat features.  The changes which comprise AfterStep person-
       ality were originally part of BowMan development, but due to
       a desire to move past simple emulation and into a niche as
       its own valuable window manager, the current designers
       decided to change the project name and move on.  BowMan
       development may continue, but we will no longer be a part of
       it.


  1.3.  What are its main features?

  1. NEXTSTEP-alike title bar, title buttons, borders and corners.

  2. AfterStep's Wharf is a much worked-out version of GoodStuff. To
     avoid copyright complications it is not called a `dock.'

  3. NEXTSTEP style menus. However the menus are not controlled by
     applications, they are more of pop-up service lists on the root
     window.

  4. NEXTSTEP style icons. The default icons are consistent with those
     in the NEXTSTEP interface, but they are configurable.

  5. Pixmapped Pager with desktop pixmmaping

  6. Easy to use look files, to share you desktop appearance with your friends

  7. Start menu entries in a hierarchy of directories

  8. WinList : a tasklist which can be horizontal or vertical

  9. Many modules & asapps to give a good look to your X window station

  However, the flexibility of fvwm was not traded off.
  Initiation files recognizes most of the fvwm 1.24r commands. Virtual
  screens and the pager are still intact. fvwm modules should work just
  fine.

  1.4.  Is it compatible with fvwm-2?

  Compatibility with fvwm-2 & enlightenment *modules* is planned for version 2.0

  1.5.  Where can I get this FAQ?

  The latest version is available at:
  <tscreen><verb>
  http://www.cs.purdue.edu/homes/zamboni/afterstep/FAQ.html
  </verb></tscreen>

  1.6.  Who contributes to this FAQ?

  The initial version of the FAQ was written by Frank Fejes
  (frank@ssax.com) and Jonathan B. Leffert (j-leffert@uchicago.edu).
  Major additions were made by Kragen Sittler (kragen@tcsi.com). The FAQ
  is currently maintained by Diego Zamboni (zamboni@cs.purdue.edu). Most
  of the questions and answers have been provided by the people
  participating in the AfterStep mailing lists :
<tscreen><verb>
  http://www.eosys.com/mailing-list/AfterStep.html
</verb></tscreen>

  1.7.  What are the AfterStep-related mailing lists?

     AfterStep-Announce:

        This is a low volume (moderated) list for announcements of
        general interest to all AfterStep users (e.g. new releases). You
        may submit announcements to be moderated via afterstep-
        announce@eosys.com.

     AfterStep:
        The purpose of this list is to provide a forum in which users of
        the AfterStep X11 window manager can discuss issues related to
        to using AfterStep. Appropriate topics include, but are not
        limited to, the installation and configuration of AfterStep and
        related modules and applications.



     AfterStep-Digest:
        This list contains the same messages as the AfterStep mailing
        list. However, the messages are saved up (not transmitted
        individually) and sent out as a bundle. This decreases the
        number of separate messages received from the list, but makes it
        more difficult to reply to a specific message.


     AfterStep-Dev:
        This list is a forum to discuss ongoing development issues
        related to AfterStep. If you want to participate in the
        development of AfterStep, please join this forum.


     AfterStep-Dev-Digest:
        This list contains the same messages as the AfterStep-Dev
        mailing list. However, the messages are saved up (not
        transmitted individually) and sent out as a bundle. This
        decreases the number of separate messages received from the
        list, but makes it more difficult to reply to a specific
        message.


  For subscribing to any of these lists, send a message to
  (listname)-request@eosys.com containing:



       subscribe




  You can find more information, and archives of all the lists, at
  http://www.eosys.com/mailing-list/AfterStep.html, maintained by Ed
  Orcutt (edo@eosys.com), and from where these descriptions were taken.


  2.  Getting and installing AfterStep

  2.1.  Where do I get AfterStep?

  The main AfterStep resources in the net are:

     WWW Page:
        The official WWW page is at :
<tscreen><verb>
http://www.afterstep.org
</verb></tscreen>

Alas, it is way too old & haven't been updated since version 1.0 (hint/hint)

     FTP Site:
<tscreen><verb>
ftp://ftp.afterstep.org/pub/
</verb></tscreen>

     Upload directory:
<tscreen><verb>
ftp://ftp.afterstep.org/incoming/
</verb></tscreen> 

  You can get AfterStep from either the WWW page or the FTP site.

     Alfredo Kojima's Page: http://www.inf.ufrgs.br/~kojima/

     Matt Kramer's Page: http://defiant.gmi.edu/afterstep/

     Kiwi's Page: http://www.iis.ee.ethz.ch/~kiwi/AfterStep/

  On the above pages, you will find links to other interesting things
  that work nicely with AfterStep or WindowMaker such as TkStep, TkDesk,
  lib-neXtaw, and nifty icons that were adapted from NEXTSTEP.

  2.3.  What is the latest version of AfterStep

  The latest public version is 1.4.0, released on February 1998.

  2.4.  I've compiled AfterStep for my system but every time I try to
  use it I receive the message: Cannot open display. What should I do?

  AfterStep is an X window manager and cannot be run from the terminal.
  It must be run through X.  The easiest way to do that is to either
  create or edit your own  .xinitrc file (which contains a list of the
  programs you wish to load upon startup) and add the line exec
  afterstep to the end.  This last exec'd line is significant in that it
  says to shut down X when that program is terminated.  Now that you
  have that file, simply startup X in your customary manner, most likely
  startx or xinit.  Now you're off and running...good luck.

  2.5.  How do I enable sound in AfterStep?

  First, make sure you have compiled the Linux kernel with sound support
  and that the sound works ; try :

<tscreen><verb>
cat <some au file> > /dev/audio
</verb></tscreen>

  Then, edit ~/GNUstep/Library/AfterStep/audio file.
  You should see (if you don't add it) lines like this:



         *AudioPlayCmd /usr/bin/showaudio
         *AudioDir /usr/X11/lib/X11/afterstep/sounds
         *AudioDelay 1



  If these aren't there, add them.  Verify that the AudioPlayCmd is a
  valid program and that the sounds you want to play are in
  /usr/X11/lib/X11/afterstep/sounds (or set it to the appropriate
  directory).


  Below that section, you sould see many lines like this:



         #*Audio startup gong.au




  Simply remove the comment (#) from the beginning of the line and if
  you wish, set the startup event to some other au file.  The format is:


<tscreen><verb>
       Audio <event> <sound>
</verb></tscreen>



  Do that for the rest of the Audio events, and as one AfterStepper put
  it, you'll literally add new bells and whistles to AfterStep.

  2.6.  I grabbed TkStep and Tcl7.6 and tried to install TkStep, but it
  doesn't work 

  TkStep still doesn't work with Tcl7.6. Try Tcl 7.5 (see question ``''
  for information about TkStep).


  2.7.  Why doesn't ASCP run on my system?

  ASCP needs TkStep, a version of Tk implemented by Alfredo Kojima
  (kojima@inf.ufrgs.br) that gives Tk the NEXTSTEP look-and-feel, and
  implements a few new widgets, like font and color choosers. You can
  download it from http://www.inf.ufrgs.br/~kojima/tkstep.html &amp; see
  question ``'' for information about ASCP.

  A new version of ASCP which will not depent on TkStep but on something
  more standard is also planned.

  2.8.  How can I install AfterStep without being root?

  This is fairly easy. You will have to install all the files under your
  home directory. The usual recommendation is to use the same
  directories as suggested in the installation procedure, but replacing
   /usr/local by your home directory. For example, if you home directory
  is  /home/bla you would use directories like
   /home/blah/bin,  /home/blah/etc,  /home/blah/lib, etc.

  Compile AfterStep following the manual installation procedure until
  install step. Then, do the following (make sure to create the
  destination directories first if they don't exist. All the source
  paths are relative to the AfterStep source directory):


  1. Copy  afterstep/afterstep to  $HOME/bin/.

  2. Copy  modules/*/(binaries) to  $HOME/bin/.

  3. Copy  apps/*/(binaries) to  $HOME/bin/.

  4. Copy  GNUstep/ to  $HOME/.

  5. Edit  $HOME/GNUstep/Library/AfterStep/base.* to reflect the above paths in
  the lines starting with ModulePath and PixmapPath.

  9. Put  $HOME/bin in your path.

  You should be set. Feel free to modify this procedure according to
  your particular needs or the particular setup of your machine/account.

  3.  Icons, graphics and pixmaps

  3.1.  Icons staying put

  In old versions of AfterStep, an icon to be used in Wharf must contain
  at least one transparent pixel, otherwise the symptoms you've
  mentioned will be prevalent.  Simply add a transparent pixel and
  everything should work flawlessly (see question ``'' for instructions
  on how to do this).

  Newer versions of AfterStep fix this problem, allowing you to use
  icons without transparent pixels in the Wharf without problems. You
  should really upgrade to the latest version.

3.2.  Colormap issues

  When I run AfterStep some of the icons on the button bar don't show
  up. If I load them at the top they show up, but then the other ones
  don't. Also, when I use netscape, the colors get wacky. What's wrong?
 
  Odds are you are using a 256 color (8bit) display.  A quick
  explanation is that you can only have 256 colors on the screen at the
  same time, and the more colors you use in Wharf (the button bar), the
  less you can use for other applications and icons.  I would suggest
  upgrading your video hardware or using more conservative (less
  colorful) icons.  For netscape, an option is to run it with the
  netscape -install` command.  This will insure that netscape gets a
  good deal of the color that it wants. However, this will result in the
  colors flashing whenever you move the mouse in or out the Netscape
  window. You decide if you can live with that.

  You can find some help on configuring AfterStep for running on an
  8-bit display in http://www.infinet.com/~gnosis/as.html ; you can
  find a good collection of low-color icons (all of them together use
  only 21 colors) at http://www.iis.ee.ethz.ch/~kiwi/AfterStep/

  If you are using asclock, you can configure it to use much fewer
  colors. See question ``''.

  Moreover, AfterStep will use config. files ending by 8bpp or 8 bit displays.
  Just modify these files to use less colors.

  3.3.  Icons disappear from Wharf. What's wrong?

  You are most likely running out of colors. Either upgrade your
  hardware, switch to a higher color depth (i.e. 16 bpp or higher), or
  use icons that contain fewer colors. See question ``''.

  3.4.  How do I create an icon with a transparent pixel?

  Its beyond easy. An xpm is a simple text file. Therefore, the only
  image manipulation software you will need is vi. If you edit your xpm,
  you will become aware of the beauty and simplicity. At the bottom you
  will notice a character representation of your image. At the top there
  is a color listing corresponding to each pixel of the character
  representation.

  You have two options to create a transparent pixel:

     Change an existing pixel color to transparent:

        Simply find the pixel character(s) you wish to become
        transparent, then go back up top and find that character in the
        listing.  Change the color code (number beginning with a #) to
        None.  Save, and you're all tootin'.

     Create a new transparent pixel: 

        Edit the line near the top corresponding to the
        height/width/number of colors/chars per pixel.  Increment the
        number of colors (third value) by one.  Then in the list of
        pixels and color values add the line:


               "c None",




     Where `c' should be a character that is not being used by any other
     color. From there save and take off.

  If you're the slightest bit unsure, take a look at one of the xpm
  files in the AfterStep distribution's icons directory.

  The `correct' size for a Wharf icon is 48x48 pixels. However, if you
  use bigger icons, they will display correctly, up to 64x64, which is
  the default size for the Wharf buttons.

  3.5.  Why doesn't program `xyz' work in 16bpp?

  A lot of 8bpp programs don't work on displays without a PseudoColor
  visual available. A lot of PC X servers don't support PseudoColor
  visuals on displays running in TrueColor mode. You should buy an SGI.
  Or run two simultaneous X servers, if you're on Linux.

  3.6.  Why doesn't xv do `xyz' in 16bpp? 

  xv doesn't cope well with 16bpp in three ways. First, it can't grab
  pieces of the screen. Second, if you grab pieces of the screen with
  xwd and try to display them with xv, it doesn't work well. xwud works.
  Third, if you display a 24bpp picture, it doesn't bother to dither it
  down to 16bpp, resulting in bad pictures.

  3.7.  Why don't icon names change when the application changes it?

  Sorry guy, but icon names change since AfterStep 1.1 !

  3.8.  Suddenly, some windows stay always on top. Why?

  With the default, triple-clicking on a window titlebar
  toggles a window's always-on-top state.  Triple-click again to remove
  it. If you want to remove this feature, locate the lines in your
  feel file that look like this (there are several of them):



               PutOnTop        "TripleClick"




  and delete them. Or better yet, just comment them out, in case you
  later decide you need the feature again.


  3.9.  Can you add `xyz' to the Wharf?


  You know, it would be really nice if the Wharf supported text
  titles/cascading menus/tabs on the side/plug-in modules/swallowing
  running applications in folders/scrollbars on folders/starting
  applications only if they're not already running. Why doesn't someone
  do it?

  This is a holy war.  You will be crucified at dawn.  Unless you
  implement it yourself and post a patch.

  No, seriously, there has been a lot of discussion about these topics.

  Many people believED that AfterStep should be kept as close as possible
  to the original NEXTSTEP interface, why others thought it should be
  extended and be made as configurable as possible.

  Now WindowMaker is following the original NEXTSTEP interface, while
  AfsterStep is going its own way.

  So please tell exactly what you'd like to be implemented, or even better :
  do it yourself and send us a patch.

  Three "features" wishes will be grated to each user (just joking).

  4.  Modules

  4.1.  How do I get multiple Wharfs/Pagers on the screen?
                                      
  It's pretty easy. You just have to have the Wharf exist under several
  different names, and then configure each of them using its name. For
  example, if you make a link to  Wharf called  MyWharf (type man ln if
  you don't know how to make links), you would use lines like these in
  your ~/GNUstep/Library/AfterStep/wharf file :



       *MyWharfAnimate
       *MyWharf "label" Icon.xpm Exec "something" something




  Same for the Pager.

  Note: Apparently, due to the way the AfterStep configuration file
  parser works, links with names like  Wharf2 (i.e. the same original
  name with characters appended to it) will not work, the parser will
  think you are referring to the original module and will get confused.
  You have to give each link a distinctive name.

  4.2.  How can I get ASclock to properly appear in Wharf?

  First, you need AfterStep 0.98 beta 4 or later. These version have the
  MaxSwallow' option. Then, add a command such as this to the wharf file :



         *Wharf asclock nil MaxSwallow "asclock" asclock -12 -shape &




  You can omit the `-12' to be in 24 hour time.

  4.3.  How do I configure asclock to use fewer colors? 

  When installing, after executing configure, asclock configure should
  be lauched by default !
  Else, go to the  modules/asclock directory and do the following:


  1. Execute sh configure

  2. Several menus will appear, asking for the default language for
     dates (yes, you can change it!) and the number of colors used.
     There is one option to use 2-bit color, resulting in an asclock
     that uses only 4 colors, but still looks pretty good.

  3. Done. Now go and compile asclock as usual.




  5.  General usage, features and bugs

  5.1.  Why does AfterStep get slower and slower until I restart it?

  Apparently there was a bug in versions up to 1.0pre3 (probably a
  memory leak) that caused this behavior. We know that setting your
  TextureMaxColors to something small, like `16 16 16 16' or `32 32 32
  32', will stop this problem. It also seems to happen only with XFree86
  in 32-bpp mode (or 16? Please give me confirmation), and if you're in
  8-bpp or a different X server, it doesn't seem to cause a problem.

  This problem was solved in 1.0pre4, as far as we know. Upgrade!

  5.2.  Click-to-focus dies


  Sometimes, after I've been running AfterStep for a while in click-to-
  focus mode, I can't shift the focus from one window to another by
  clicking.  I have to iconify and deiconify the window to shift focus,
  or pick it from the popup list.

  This is a strange bug, that is (sometimes at least) caused by having
  the NumLock key activated. It is present up to 1.0pre4, so check your
  NumLock key.

  This problem is solved in 1.0pre5.

  5.3.  What is this `Shade' thing?

  Shade is a window function that is often seen on the Macintosh system.
  In theory, it makes a window disappear except for the title bar.  For
  example, an Xterm normally looks like this:



         |------------------------------|
         |             Xterm            |
         |------------------------------|
         |                              |
         |                              |
         |                              |
         |                              |
         |                              |
         |------------------------------|




  Shade is set by default to take effect when one double clicks on the
  title bar of the window.  When shade takes effect, the Xterm looks
  like this:



         |------------------------------|
         |             Xterm            |
         |------------------------------|

  This is nice for saving desktop space and for window management
  purposes.  Some prefer it to iconifying the windows.

  Up to 1.0pre3, Shade didn't work correctly, because it worked by
  resizing the window to a height of 0 pixels, which some applications
  didn't like.

  In 1.0pre4 and posterior versions, Shade works by making the
  application think that it is being iconified, so it works with all
  applications again. It has the problem, though, that shaded windows
  become `sticky' and appear in all the pages in the virtual desktop.

  5.4.  When I restart AfterStep, it kills X. What gives?

  This was a bug that occured in AfterStep betas. If you experience this
  bug, you are running an old release of AfterStep. Upgrade to v1.0pre4
  or later to fix this. This is, incidentally, something you should
  probably do anyway, considering the wealth of features your are
  missing.

  5.5.  What is swallow-exec?

  Is a feature introduced in the distribution in 1.0pre4 (it previously
  existed as a separate patch) that allows you to associate an action to
  an entry in the Wharf corresponding to a swallowed application. So for
  example you can have asmail in the Wharf, and have it configured so
  that when you click on it, it warps to your email reading window. If
  your email reader is exmh, the required lines would be:



       *Wharf "asmail" nil Swallow     "asmail" asmail &
       *Wharf "asmail" nil Warp        "-" exmh




  Note how both lines have the same label `asmail', which tells Wharf
  that those two go together. You can use any AfterStep function instead
  of `Warp'. For example, if you want the xload icon to fire a top
  window when clicked, you can have something like this:



       *Wharf "xload" nil Swallow      "xload" xload -geometry 48x48-1-1 &
       *Wharf "xload" nil Exec "Top" xterm +sb -T Top -n Top -e top &




  By the way, this feature is responsible for a strange bug. See
  question ``''.


  5.6.  I upgraded to 1.0pre4 or later, and now the Wharf doesn't work.
  What happens?  

  This is not a bug, it's a feature :-). No, really, this behavior was
  introduced due to the introduction of the `Swallow-exec' capability in
  1.0pre4. See question ``''.
  To fix it, do the following:


  1. In your  .steprc, locate the lines that start with


       *Wharf "" ...




  2. The  could be also nil, or any other label that is the same for all
     the Wharf entries. These repeated labels are the ones causing the
     trouble. You have to give each Wharf entry a unique label there,
     like `xload', `asmail', `Pager', etc.

  3. Restart and it should be fixed.



  6.1.  What is this WindowMaker I keep hearing about in the list?

  WindowMaker a new NeXT-like window manager that is being developed by
  Alfredo Kojima (kojima@inf.ufrgs.br) with the support of a lot of
  other people. It will support many OpenStep/GNUStep-ish features, and
  there is talk that it may be the `next-generation _asnl', and even the
  window manager of choice for GNUstep. You can download it from
  http://www.windowmaker.org

  However, be advised that WindowMaker is still in a very early stage of
  development, so don't plan on using it for real work for now unless
  you want to cope with a lot of unimplemented features. But it is
  advancing very fast, so you may also want to take a good look at it.

  6.2.  What is ASCP?

  ASCP stands for `AfterStep Control Panel', and is a program that
  allows you to configure AfterStep while imitating the NEXTSTEP control
  panel look and feel. It makes really easy to configure AfterStep
  without manually fiddling with the  .steprc file. You can download it
  from http://www.inf.ufrgs.br/~kojima/ascp.html ; be sure to backup
  your .steprc file before using it, because it still has some bugs and
  problems.

  WARNING: Due to changes introduced in AfterStep 1.0pre4 and posterior
  versions, the files written by ASCP cause AfterStep to behave very
  strangely, particularily the Wharf. So please don't use ASCP for
  configuring 1.0pre4 until this is fixed. If you accidentally did and
  you don't have a backup of your  .steprc, do the following to fix it:

  WARNING2: AfterStep doesn't use .steprc since version 1.2, so you will
  have to run it in 'compatibility' mode : afterstep -f yeoldsteprc

  1. In your  .steprc, locate the lines that start with


       *Wharf "" ...





  2. The empty double quotes are the ones causing the trouble. You have
     to give each Wharf entry a unique label there, inside the double
     quotes.

  3. Restart and it should be fixed.

  In case you are interested, this happens because 1.0pre4 introduced
  the `swallow-exec' capability in the standard distribution (see
  question ``''). This uses the labels to know which Wharf items have
  multiple meanings, so if all the labels are the same, Wharf
  superimposes all the icons on one.

  6.3.  What is TkStep and why do I want it?

  TkStep is a modified version of Tk that implements the NEXTSTEP look
  and feel. If you use wishstep instead of wish to run your
  applications, all your Tcl/Tk programs will suddenly have a renewed
  and great new look!

  You also want it because ASCP needs it. See question ``''.

  You can get it at http://www.inf.ufrgs.br/~kojima/tkstep.html ; you
  need to have Tcl7.5/Tk4.1 to run it. ASCP does not work with Tcl7.6
  yet.

  7.  Other AfterStep-unrelated applications


  7.1.  I have a problem with program `xyz'

  Please, please, don't post questions unrelated to AfterStep to the

  mailing lists. If you have a problem with some application not
  running, and you think AfterStep is the culprit, first try the
  following:


  1. Read the documentation (manual pages, etc.) for the program.

  2. Find out about its configuration parameters (not only command line,
     but also options in  .Xdefaults, config files, etc.).

  3. Ask other people who know about that specific program. Find a
     mailing list about that program and ask there.

  4. Try running the program under some other window manager. If it
     doesn't work there either, it is not an AfterStep problem.

  If you are very confident that it is an AfterStep problem, then send
  it to the mailing list, but try to give as much information as
  possible. Questions like `Why doesn't blig-graphics work on my
  system?' do not contain any useful information that may help others in
  diagnosing your problem. Some data you may have to include is:


  1. AfterStep version you are using.

  2. Operating system version, machine architecture.

  3. System configuration (color depth, memory, anything you think may
     help).

  4. Problematic program.

  5. Environment information (other programs running at the same time,
     etc.)

  6. A detailed description of the problem. What happens (error
     messages, etc.), how replicable it is, how to replicate it, etc.
     The more information you provide, the easier it will be for others
     to find a solution.

  7.2.  Why am I having `xyz' problem/how do I do `xyz' with a terminal
  window?

  Are you using plain vanilla xterm, color xterm, rxvt, rxvt-xpm,
  vanilla xterm with Xaw3d or Xaw-Xpm or neXtaw, dtterm, nxterm, hpterm,
  aixterm, xiterm, cmdtool, shelltool, or something else?

  See question ``''.

<sect>How to make a new module?<p>

  First, note that AfterStep in only compatible with Bowman &amp; Fvwm-1
  for now.

  AfterStep 2.0 will include module compatibility with at least Fvwm2
  &amp; Fvwm95, maybe with others window managers like enlightenment
  (tell us about the modules you'd like to be ported to AfterStep !).

The AfterStep Module Interface by Hannu Rummukainen (hrummuka@cc.hut.fi)

<tscreen><verb>
This document is intended to serve as an introduction to the AfterStep
module interface and its capabilities.  This is not meant to be a
comprehensive reference guide; make anything involved and you are bound to
be reading AfterStep sources anyway.  Some background knowledge on xlib and
unix programming is assumed.

A module is basically a separate unix program that AfterStep starts and
communicates with.  A module can be started during AfterStep initialization
via the Module option, or at any time during the X session by the Module
built-in.  A module can run indefinitely until AfterStep exits, or can
perform a single task and exit.


Module Invocation
=================

A module should be an executable file located in one of the directories
listed in the .steprc ModulePath option.  It is referenced in AfterStep
commands by the name of the executable.

AfterStep gives a module 5 or 6 command line arguments (in addition to
its path name in argv[0]), as follows:

argv[0]
	The path and name used by AfterStep to start the module.

argv[1]
	The file descriptor for the open pipe that the module must
	write to in order to send commands and requests to AfterStep.
	This is an integer formatted in decimal.

argv[2]
	The file descriptor for the open pipe that the module must
	read to in order to acquire any information sent by AfterStep.
	This is an integer formatted in decimal.

argv[3]
	THIS SHOULD NOT BE USED ANYMORE !
	It used to be te name of the AfterStep configuration file.
	Modules read their config. file in ~/GNUstep/Library/AfterStep/modname

argv[4]
	The Window ID of the application window that was focused when the
	module was invoked.  The argument is zero if no window was focused,
	or if the Module was started during AfterStep initialization.
	This is an unsigned 32 bit integer formatted in hexadecimal.

argv[5]
	The AfterStep context of the module invocation.  Briefly, when
	the previous argument specifies a window, this argument tells
	which part of the window (title bar, client area etc) was
	concerned.

	The AfterStep contexts are defined in the include file
	"appropriate path/afterstep/afterstep.h".

	This is an unsigned 32 bit integer formatted in hexadecimal.

argv[6]	(optional, check argc to be sure)
	Any command line arguments for the module, if such were supplied
	in the Module command that invoked this module.  They are all sent
	as a single null-terminated string.

The DISPLAY environment variable points to the display managed by
the AfterStep instance that started the module.


Sending commands to AfterStep
=============================

The data sent to AfterStep consists of packets with a structure like this:

Window w;
	Window ID for the window to be affected, or None.
	The window ID can refer to an application window or to a decoration
	window made by AfterStep, including the top-level frame window.

int size;
	The length of the text string to follow in characters.
	The size is limited to no more than 255 characters.

char text[size];
	A text command formatted similarly to the function field in
	the mouse and key bindings in .steprc.  See below for special
	commands available in Modules.

int cont;
	If this is nonzero, everything goes on as usual.
	On the other hand, if the integer value is zero, AfterStep closes
	the pipes to the module permanently.

The text commands are rather thoroughly documented on the AfterStep manual
page.  However, there are a couple of additional commands that can only be
issued by a module:

Set_Mask maskvalue
	Set the input mask for the module, in order to specify what actions
	AfterStep should inform the module about.  The input mask values are
	defined in the include file "appropriate path/afterstep/module.h".

Send_WindowList
	Get the AfterStep window list in its entirety.
	See below for more information.

Unlock
	Let AfterStep return to normal after it's been locked.

When AfterStep is about to exit, it closes down the communication pipes.
Modules should detect this and respond with SIGCHLD when they are ready
to let go.  However, in 30 seconds AfterStep exits anyway.

The locking facility is a kludge to allow animating of iconifying windows.
A better alternative is on the way, and I do not recommend depending on
the current implementation.  For now, when you set the input mask bit
M_LOCKONSEND, AfterStep stops on its tracks when sending any packet to your
module.  You have to acknowledge each and every packet by a Unlock command.


Reading information from AfterStep
==================================

AfterStep sends information to modules in small packets.  By default a
module will get all types of packets, but it is recommended that you select
(with the Set_Mask command) exactly the types of packets that you need.

Every packet sent to modules begins with a header:

unsigned long START_FLAG;
	A special packet start flag defined in module.h

unsigned long packet_type;
	A packet type identifier, equivalent to the input masks defined
	in module.h

unsigned long packet_length;
	The total length of the packet in unsigned longs, including
	everything from the start flag to the last unsigned long.

The contents of the rest of the packet depend on the packet type.  Each type
contains a constant amount of data items, as shown by the table below.  Of
course, a future version might send more data so using the packet length
field is a good idea.  Every data item is cast to unsigned long before
sending, except for strings which are merely copied into place.

Of the common data items below: `app_win' is the window id of the real
client application window, `frame' is the window id of the top-level frame
window, which is an ancestor of the application window, and a child of the
root window.  The corresponding ASWindow structure pointer is there as well,
what it is good for I do not know.

------------------------------------------------------------------------------
packet type    #data	what the data items are for, in order and with
	       items	types to cast them back to, if necessary
	a brief explanation
------------------------------------------------------------------------------
M_ADD_WINDOW	  0	-
	A new window is being created.
	Followed by M_WINDOW_NAME, M_ICON_NAME, M_RES_CLASS and M_RES_NAME.

M_DESTROY_WINDOW  3	Window app_win, Window frame, ASWindow* t
	A window is destroyed.

M_FOCUS_CHANGE	  3	Window app_win, Window frame, ASWindow* t
			or: 0, 0, 0
	Contains the identity of the window that just got the focus.
	If the window is not managed by AfterStep, all the data values
	are sent as zero.

M_MAP		  3	Window app_win, Window frame, ASWindow* t
	A window is mapped.  This is not sent if the mapping is due to
	deiconification.

M_RAISE_WINDOW	  3	Window app_win, Window frame, ASWindow* t
	A window is raised.  Note: these messages are not a reliable way
	of tracking the window stacking order; should you want to do this,
	do an occasional Send_WindowList or communicate directly with the
	X server.

M_LOWER_WINDOW	  3	Window app_win, Window frame, ASWindow* t
	A window is lowered.

M_ICONIFY	  7	Window app_win, Window frame, ASWindow* t,
			icon_x, icon_y, icon_width, icon_height
	A window is iconified.
	When this packet is sent as part of a window list, the four last
	data items are zero in case the window is iconified but the icon is
	unmapped.

M_DEICONIFY	  3	Window app_win, Window frame, ASWindow* t,
			icon_x, icon_y, icon_width, icon_height
	A window is deiconified.
	The last four data items are zero if the deiconification was
	initiated by the application itself.

M_ICON_LOCATION	  7	Window app_win, Window frame, ASWindow* t,
			new_icon_x, new_icon_y, icon_width, icon_height
	An icon was moved.

M_TOGGLE_PAGING	  1	0 or 1
	The TogglePage built-in is called; the data value is 1 if the
	edge scrolling is enabled and 0 if it is disabled.

M_NEW_PAGE	  3	new_x, new_y, desknumber
	The virtual screen is scrolled.

M_NEW_DESK	  1	new_desknumber
	A change of desktop.

M_SHADE		  3	Window app_win, Window frame, ASWindow* t
	A window is shaded.

M_UNSHADE	  3	Window app_win, Window frame, ASWindow* t
	A window is unshaded.

M_NEW_BACKGROUND  1	0 or 1
	User decided to use another pixmap for background and pager must
	update its pixmaps.

M_END_WINDOWLIST  0
	An end marker for the Send_WindowList packetfest.  See below.

M_CONFIGURE_WINDOW  24	Window app_win, Window frame, ASWindow* t,
			frame_x, frame_y, frame_width, frame_height,
			Desk, flags, title_height, boundary_width,
			hints.base_width, hints.base_height,
			hints.width_inc, hints.height_inc,
			hints.min_width, hints.min_height,
			hints.max_width, hints.max_height,
			0, icon_pixmap_w, hints.win_gravity,
			TextPixel, BlackPixel
	Some properties or flags associated with a window were changed.
	Except for the zero and the ASWindow pointer, the data items in
	the packet are fields of the ASWindow structure (see afterstep.h).

M_WINDOW_NAME	  3+s	Window app_win, Window frame, ASWindow* t,
			char[] window_name
	The title of a window is set or changed.

M_ICON_NAME	  3+s	Window app_win, Window frame, ASWindow* t,
			char[] icon_name
	The icon name of a window is set or changed.

M_RES_CLASS	  3+s	Window app_win, Window frame, ASWindow* t,
			char[] res_class
	The class name of a window is set.

M_RES_NAME	  3+s	Window app_win, Window frame, ASWindow* t,
			char[] res_name
	The application name of a window is set.
------------------------------------------------------------------------------

There is no corresponding packet for the mask value M_LOCKONSEND.


In response to a Send_WindowList request, AfterStep sends the following
packets to the module that sent the request:

	M_TOGGLE_PAGING
	M_NEW_DESK
	M_NEW_PAGE
	* for each window:
		M_CONFIGURE_WINDOW
		M_WINDOW_NAME
		M_ICON_NAME
		M_RES_CLASS
		M_RES_NAME
		* if the window is iconified,
			M_ICONIFY
		  (see the M_ICONIFY description for a special note on this)
	* to terminate the window list:
	M_END_WINDOWLIST


The AfterStep library
=====================

There is a library of utility routines available in the lib directory of the
source distribution.  Your module can take advantage of the library by
including the include file aftersteplib.h and linking to libafterstep.a.

Here's a lowdown of the routines in the library:

void SendText(int *fd,char *message,unsigned long window);
void SendInfo(int *fd, char *message, unsigned long window);
	Send a command to AfterStep.  The fd argument is the file descriptor
	of the module-to-AfterStep pipe, message is the text command to be
	sent, and window is None or the window ID of the window to be
	affected.  The continuation flag in the packet is set.

	Interestingly, the two functions are identical.

char *findIconFile(char *icon, char *pathlist, int type);
	Search for a file with the specified name (the `icon' argument)
	along the pathlist given.  If found, the complete path name of the
	file is returned.
	The type argument corresponds to the second argument of access(2).
	Typical values are R_OK and X_OK for readability and executability.

int ReadASPacket(int fd, unsigned long *header, unsigned long **body);
	Read a packet from AfterStep.  The fd is the file descriptor of
	the AfterStep-to-module pipe, header should point to an array of
	MAX_HEADER unsigned longs, and body is the address of a pointer
	that will be filled with the address of the body of the packet.

	The caller is responsible for free()ing the packet body area.

	The routine returns a positive number if the read went fine,
	zero if the packet was invalid and a negative value if something
	is very wrong.

	You should provide a routine with a prototype like
		void DeadPipe(int nonsense);
	that will be called by ReadASPacket when the pipe is no longer open.
	Usually this indicates that AfterStep is exiting.

void sleep_a_little(int n);
	Sleep for the specified amount of microseconds.

int GetFdWidth(void);
	Get the maximum number of files a process can open.

char *safemalloc(int size);
	This is a malloc() that is guaranteed to succeed.

int matchWildcards(char *pattern, char *string);
	Returns a nonzero value if the string matches the pattern.
	The characters '?' and '*' are wildcards with the usual meanings.

int mystrcasecmp(char *a, char *b);
int mystrncasecmp(char *a, char *b, int n);
	These provide the nonstandard but useful str[n]casecmp functions
	for systems that do not have them.  Briefly, they are just like
	the ANSI str[n]cmp functions but ignore case differences.

char *CatString3(char *a, char *b, char *c);
	Concatenate 3 strings into a single 256 byte global buffer.

int mygethostname(char *client, int namelen);
	Get the name of the host machine if it is available by some means.
	The string buffer is provided by the caller.

int mygetostype(char *buf, int max);
	Acquire a string indicating the OS type if such information is
	available.  The string buffer is provided by the caller.

void CopyString(char **dest, char *source);
	Allocate memory for a copy of the source string, save the address
	of the allocate area to *dest, and copy the source string without
	any leading or trailing whitespace to the allocated area.


Compatibility with Fvwm
=======================

As AfterStep is derived from Fvwm 1.24, the module interface is very close
to that of Fvwm.  In practice AfterStep and Fvwm-1 modules are often
interchangeable; however problems do occur.  I don't know a lot about the
Fvwm interface so this section is sketchy at best.

Fvwm does not support locking (M_LOCKONSEND) nor shading (M_SHADE,
M_UNSHADE).

Fvwm does not send icon coordinates in M_DEICONIFY messages.

AfterStep does not support any of the Fvwm-2 extensions.

More?


Further reading
===============

The AfterStep source code is the definitive resource.  The source is a mess,
but in principle it is modular which makes it easier to begin reading and
comprehending relevant sections of the code.  The module communication takes
place in module.c.

Obviously existing modules are a good basis for experimentation.  See the
official ftp site and your favourite search engine to find more modules.

If you are just beginning X programming and looking for more depth than is
available in the man pages, see the comp.windows.x FAQ for literature
references.  For the economically challenged, the X source distribution
contains dozens of megabytes of documentation.


Disclaimer
==========

The document contains probably several inaccuracies, mistakes and what not.
All responsibility is hereby transferred to the readers of the document.
Use it for good.
</verb></tscreen>

<sect>Included document about Freedom<p>

his section is a political message from the League for Programming
Freedom to the users of Window Maker.

We have included it here because the issue of interface copyright is
important to the GNU project and window managers !

Apple, Lotus, and now CDC have tried to create a new form of legal
monopoly: a copyright on a user interface.

An interface is a kind of language---a set of conventions for
communication between two entities, human or machine.  Until a few years
ago, the law seemed clear: interfaces were outside the domain of
copyright, so programmers could program freely and implement whatever
interface the users demanded.  Imitating de-facto standard interfaces,
sometimes with improvements, was standard practice in the computer
field.  These improvements, if accepted by the users, caught on and
became the norm; in this way, much progress took place.

Computer users, and most software developers, were happy with this state
of affairs.  However, large companies such as Apple and Lotus would
prefer a different system---one in which they can own interfaces and
thereby rid themselves of all serious competitors.  They hope that
interface copyright will give them, in effect, monopolies on major
classes of software.

Other large companies such as IBM and Digital also favor interface
monopolies, for the same reason: if languages become property, they
expect to own many de-facto standard languages.  But Apple and Lotus are
the ones who have actually sued.  Apple's lawsuit was defeated, for
reasons only partly related to the general issue of interface copyright.

Lotus won lawsuits against two small companies, which were thus put out
of business.  Then Lotus sued Borland; Lotus won in the trial court (no
surprise, since it was the same court that had ruled for Lotus twice
before), but the court of appeals ruled in favor of Borland, which was
assisted by a friend-of-the-court brief from the League for Programming
Freedom.

Lotus appealed the case to the Supreme Court, which heard the case but
was unable to reach a decision.  This failure means that the appeals
court decision stands, in one portion of the United States, and may
influence the other appeals courts, but it does not set a nationwide
precedent.  The battle is not over, and it is not limited to the United
States.

The battle is extending into other areas of software as well.  In 1995 a
company that produced a simulator for a CDC computer was shut down by a
copyright lawsuit, in which CDC charged that the simulator infringed the
copyright on the manuals for the computer.

If the monopolists get their way, they will hobble the software field:

<itemize>
<item>
Gratuitous incompatibilities will burden users.  Imagine if each car
manufacturer had to design a different way to start, stop, and steer a
car.

<item>
Users will be ``locked in'' to whichever interface they learn; then they
will be prisoners of one supplier, who will charge a monopolistic price.

<item>
Large companies have an unfair advantage wherever lawsuits become
commonplace.  Since they can afford to sue, they can intimidate smaller
developers with threats even when they don't really have a case.

<item>
Interface improvements will come slower, since incremental evolution
through creative partial imitation will no longer occur.
</itemize>

If interface monopolies are accepted, other large companies are waiting
to grab theirs:

<itemize>
<item>
Adobe is expected to claim a monopoly on the interfaces of various
popular application programs, if Lotus ultimately wins the case against
Borland.

<item>
Open Computing magazine reported a Microsoft vice president as threatening
to sue people who imitate the interface of Windows.
</itemize>

Users invest a great deal of time and money in learning to use computer
interfaces.  Far more, in fact, than software developers invest in
developing *and even implementing* the interfaces.  Whoever can own
an interface, has made its users into captives, and misappropriated
their investment.

To protect our freedom from monopolies like these, a group of
programmers and users have formed a grass-roots political organization,
the League for Programming Freedom.

The purpose of the League is to oppose monopolistic practices such as
interface copyright and software patents.  The League calls for a return
to the legal policies of the recent past, in which programmers could
program freely.  The League is not concerned with free software as an
issue, and is not affiliated with the Free Software Foundation.

The League's activities include publicizing the issues, as is being done
here, and filing friend-of-the-court briefs on behalf of defendants sued
by monopolists.

The League's membership rolls include Donald Knuth, the foremost
authority on algorithms, John McCarthy, inventor of Lisp, Marvin Minsky,
founder of the MIT Artificial Intelligence lab, Guy L.  Steele, Jr.,
author of well-known books on Lisp and C, as well as Richard Stallman,
the developer of GNU CC.  Please join and add your name to the list.
Membership dues in the League are $42 per year for programmers, managers
and professionals; $10.50 for students; $21 for others.

Activist members are especially important, but members who have no time
to give are also important.  Surveys at major ACM conferences have
indicated a vast majority of attendees agree with the League on both
issues (interface copyrights and software patents).  If just ten percent
of the programmers who agree with the League join the League, we will
probably triumph.

To join, or for more information, phone (617) 243-4091 or write to:

<tscreen><verb>
League for Programming Freedom
1 Kendall Square #143
P.O. Box 9171
Cambridge, MA 02139
</verb></tscreen>

You can also send electronic mail to lpf@@uunet.uu.net

In addition to joining the League, here are some suggestions from the
League for other things you can do to protect your freedom to write
programs:

<itemize>
<item>
Tell your friends and colleagues about this issue and how it threatens
to ruin the computer industry.

<item>
Mention that you are a League member in your .signature, and
mention the League's email address for inquiries.

<item>
Ask the companies you consider working for or working with to make
statements against software monopolies, and give preference to those
that do.

<item>
When employers ask you to sign contracts giving them copyright on your
work, insist on a clause saying they will not claim the copyright covers
imitating the interface.

<item>
When employers ask you to sign contracts giving them patent rights,
insist on clauses saying they can use these rights only defensively.
Don't rely on ``company policy,'' since that can change at any time;
don't rely on an individual executive's private word, since that person
may be replaced.  Get a commitment just as binding as the commitment
they get from you.

<item>
Write to Congress to explain the importance of these issues.
</itemize>

<tscreen><verb>
House Subcommittee on Intellectual Property
2137 Rayburn Bldg
Washington, DC 20515

Senate Subcommittee on Patents, Trademarks and Copyrights
United States Senate
Washington, DC 20510
</verb></tscreen>

(These committees have received lots of mail already; let's give them
even more.)


********************************************************************


If you want to have more free software a few years from now, it makes
sense for you to help encourage people to contribute funds for its
development.  The most effective approach known is to encourage
commercial redistributors to donate.

Users of free software systems can boost the pace of development by
encouraging for-a-fee distributors to donate part of their selling price
to free software developers---the Free Software Foundation, and others.

The way to convince distributors to do this is to demand it and expect
it from them.  So when you compare distributors, judge them partly by
how much they give to free software development.  Show distributors
they must compete to be the one who gives the most.

To make this approach work, you must insist on numbers that you can
compare, such as, ``We will donate ten dollars to the Frobnitz project
for each disk sold.''  Don't be satisfied with a vague promise, such as
``A portion of the profits are donated,'' since it doesn't give a basis
for comparison.

Even a precise fraction ``of the profits from this disk'' is not very
meaningful, since creative accounting and unrelated business decisions
can greatly alter what fraction of the sales price counts as profit.
If the price you pay is $50, ten percent of the profit is probably
less than a dollar; it might be a few cents, or nothing at all.

Some redistributors do development work themselves.  This is useful too;
but to keep everyone honest, you need to inquire how much they do, and
what kind.  Some kinds of development make much more long-term
difference than others.  For example, maintaining a separate version of
a program contributes very little; maintaining the standard version of a
program for the whole community contributes much.  Easy new ports
contribute little, since someone else would surely do them; difficult
ports such as adding a new CPU to the GNU C compiler contribute more;
major new features or packages contribute the most.

By establishing the idea that supporting further development is ``the
proper thing to do'' when distributing free software for a fee, we can
assure a steady flow of resources into making more free software.

<tscreen><verb>
Copyright (C) 1994 Free Software Foundation, Inc.
Verbatim copying and redistribution of this section is permitted
without royalty; alteration is not permitted.
</verb></tscreen>

<sect>Credits<p>

<tscreen><verb>
Most of current AfterStep was made by:

 Frank Fejes - ffejes@midway.uchicago.edu
 Alfredo Kenji Kojima - kojima@inf.ufrgs.br
 Dan Weeks - dan@mango.sfasu.edu

Alfredo, Dan & Frank have had a solid core of talented contributors: 

Mordechai Abzug
  - WindowList hotkey fix

Dave Adkins
  - Restart code changes
  - Memory leak stoppage (?)

Guylhem Aznar
  - AfterStep developpement since 1.0.2

Michael Beam
  - Ported FvwmForm

Erik Berry
  - Final manpage compilation

Rainer M. Canavan
  - Fixed Wharf's transparent pixel fetish
 
Rob Malda
  - Many patches & asapps

Emanuele Caratti
  - Dynamic icon title code

Beat Christen
  - asclock module
  - Wharf Folders code

Robert Depenbrock 
  - Banner work

Ren'e Fichter
  - TaskBar horizontal mode for WindowList

Amadeus Foudray
  - StubbornPlacement code
  - Unfocused gradient work
  - Pager speedup

Kaj Groner
  - Wharf Swallow Exec code
  - Twist iconification mode
  - Animate configuration file parsing
  - Animate manpage

Takanori Kubota
  - Color mapping fixed in Forms

Jonathan B. Leffert
  - AfterStep FAQ work
  - AfterStep FTP site maintainer

Yoshikazu Ooe
  - WharfAnimateMain fix

Ed Orcutt
  - Icon Background Gradients and Pixmap handling
  - Mailing list

Hannu Rummukainen
  - PopDown menu enhancement
  - Numerous focus mode enhancements
  - Many window circulation bug fixes
  - Multiple WindowList fixes and improvements
  - NumLock workaround
  - Shade fixes
  - Animate fixes
  - Wrote The AfterStep Module Interface Guide
  - Manpage updates
  - Much more

Manome Tomonori
  - AnimateTwist fix
  - Japanese FAQ

Jarkko Torppa
  - GetFdWidth fix

Diego Zamboni
  - Menu width fix
  - Final FAQ

drz (please somebody, give me the full name)
  - TitleBar Button enhancements

Yngwie J. Malmsteen
  - Tunes

-Thanks to all!-
</verb></tscreen>

</article>

