home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / as1455n6.zip / XFree86 / doc / AfterStep / src / modules_interface < prev    next >
Text File  |  1998-05-13  |  16KB  |  392 lines
  1. The AfterStep Module Interface by Hannu Rummukainen (hrummuka@cc.hut.fi)
  2. ************************************************************************
  3.  
  4.  
  5. This document is intended to serve as an introduction to the AfterStep
  6. module interface and its capabilities.  This is not meant to be a
  7. comprehensive reference guide; make anything involved and you are bound to
  8. be reading AfterStep sources anyway.  Some background knowledge on xlib and
  9. unix programming is assumed.
  10.  
  11. A module is basically a separate unix program that AfterStep starts and
  12. communicates with.  A module can be started during AfterStep initialization
  13. via the Module option, or at any time during the X session by the Module
  14. built-in.  A module can run indefinitely until AfterStep exits, or can
  15. perform a single task and exit.
  16.  
  17.  
  18. Module Invocation
  19. =================
  20.  
  21. A module should be an executable file located in one of the directories
  22. listed in the .steprc ModulePath option.  It is referenced in AfterStep
  23. commands by the name of the executable.
  24.  
  25. AfterStep gives a module 5 or 6 command line arguments (in addition to
  26. its path name in argv[0]), as follows:
  27.  
  28. argv[0]
  29.         The path and name used by AfterStep to start the module.
  30.  
  31. argv[1]
  32.         The file descriptor for the open pipe that the module must
  33.         write to in order to send commands and requests to AfterStep.
  34.         This is an integer formatted in decimal.
  35.  
  36. argv[2]
  37.         The file descriptor for the open pipe that the module must
  38.         read to in order to acquire any information sent by AfterStep.
  39.         This is an integer formatted in decimal.
  40.  
  41. argv[3]
  42.         Base file (paths) usually ~/GNUstep/Library/AfterStep/base
  43.  
  44. argv[4]
  45.         The Window ID of the application window that was focused when the
  46.         module was invoked.  The argument is zero if no window was focused,
  47.         or if the Module was started during AfterStep initialization.
  48.  
  49. argv[5]
  50.         The AfterStep context of the module invocation.  Briefly, when
  51.         the previous argument specifies a window, this argument tells
  52.         which part of the window (title bar, client area etc) was
  53.         concerned.
  54.  
  55.         The AfterStep contexts are defined in the include file
  56.         "appropriate path/afterstep/afterstep.h".
  57.  
  58.         This is an unsigned 32 bit integer formatted in hexadecimal.
  59.  
  60. argv[6] (optional, check argc to be sure)
  61.         Any command line arguments for the module, if such were supplied
  62.         in the Module command that invoked this module.  They are all sent
  63.         as a single null-terminated string.
  64.  
  65. The DISPLAY environment variable points to the display managed by
  66. the AfterStep instance that started the module.
  67.  
  68.  
  69. Sending commands to AfterStep
  70. =============================
  71.  
  72. The data sent to AfterStep consists of packets with a structure like this:
  73.  
  74. Window w;
  75.         Window ID for the window to be affected, or None.
  76.         The window ID can refer to an application window or to a decoration
  77.         window made by AfterStep, including the top-level frame window.
  78.  
  79. int size;
  80.         The length of the text string to follow in characters.
  81.         The size is limited to no more than 255 characters.
  82.  
  83. char text[size];
  84.         A text command formatted similarly to the function field in
  85.         the mouse and key bindings in .steprc.  See below for special
  86.         commands available in Modules.
  87.  
  88. int cont;
  89.         If this is nonzero, everything goes on as usual.
  90.         On the other hand, if the integer value is zero, AfterStep closes
  91.         the pipes to the module permanently.
  92.  
  93. The text commands are rather thoroughly documented on the AfterStep manual
  94. page.  However, there are a couple of additional commands that can only be
  95. issued by a module:
  96.  
  97. Set_Mask maskvalue
  98.         Set the input mask for the module, in order to specify what actions
  99.         AfterStep should inform the module about.  The input mask values are
  100.         defined in the include file "appropriate path/afterstep/module.h".
  101.  
  102. Send_WindowList
  103.         Get the AfterStep window list in its entirety.
  104.         See below for more information.
  105.  
  106. Unlock
  107.         Let AfterStep return to normal after it's been locked.
  108.  
  109. When AfterStep is about to exit, it closes down the communication pipes.
  110. Modules should detect this and respond with SIGCHLD when they are ready
  111. to let go.  However, in 30 seconds AfterStep exits anyway.
  112.  
  113. The locking facility is a kludge to allow animating of iconifying windows.
  114. A better alternative is on the way, and I do not recommend depending on
  115. the current implementation.  For now, when you set the input mask bit
  116. M_LOCKONSEND, AfterStep stops on its tracks when sending any packet to your
  117. module.  You have to acknowledge each and every packet by a Unlock command.
  118.  
  119. Reading information from AfterStep
  120. ==================================
  121.  
  122. AfterStep sends information to modules in small packets.  By default a
  123. module will get all types of packets, but it is recommended that you select
  124. (with the Set_Mask command) exactly the types of packets that you need.
  125.  
  126. Every packet sent to modules begins with a header:
  127.  
  128. unsigned long START_FLAG;
  129.         A special packet start flag defined in module.h
  130.  
  131. unsigned long packet_type;
  132.         A packet type identifier, equivalent to the input masks defined
  133.         in module.h
  134.  
  135. unsigned long packet_length;
  136.         The total length of the packet in unsigned longs, including
  137.         everything from the start flag to the last unsigned long.
  138.  
  139. The contents of the rest of the packet depend on the packet type.  Each type
  140. contains a constant amount of data items, as shown by the table below.  Of
  141. course, a future version might send more data so using the packet length
  142. field is a good idea.  Every data item is cast to unsigned long before
  143. sending, except for strings which are merely copied into place.
  144.  
  145. Of the common data items below: `app_win' is the window id of the real
  146. client application window, `frame' is the window id of the top-level frame
  147. window, which is an ancestor of the application window, and a child of the
  148. root window.  The corresponding ASWindow structure pointer is there as well,
  149. what it is good for I do not know.
  150.  
  151. ------------------------------------------------------------------------------
  152. packet type    #data    what the data items are for, in order and with
  153.                items    types to cast them back to, if necessary
  154.         a brief explanation
  155. ------------------------------------------------------------------------------
  156. M_ADD_WINDOW      0     -
  157.         A new window is being created.
  158.         Followed by M_WINDOW_NAME, M_ICON_NAME, M_RES_CLASS and M_RES_NAME.
  159.  
  160. M_DESTROY_WINDOW  3     Window app_win, Window frame, ASWindow* t
  161.         A window is destroyed.
  162.  
  163. M_FOCUS_CHANGE    3     Window app_win, Window frame, ASWindow* t
  164.                         or: 0, 0, 0
  165.         Contains the identity of the window that just got the focus.
  166.         If the window is not managed by AfterStep, all the data values
  167.         are sent as zero.
  168.  
  169. M_MAP             3     Window app_win, Window frame, ASWindow* t
  170.         A window is mapped.  This is not sent if the mapping is due to
  171.         deiconification.
  172.  
  173. M_RAISE_WINDOW    3     Window app_win, Window frame, ASWindow* t
  174.         A window is raised.  Note: these messages are not a reliable way
  175.         of tracking the window stacking order; should you want to do this,
  176.         do an occasional Send_WindowList or communicate directly with the
  177.         X server.
  178.  
  179. M_LOWER_WINDOW    3     Window app_win, Window frame, ASWindow* t
  180.         A window is lowered.
  181.  
  182. M_ICONIFY         7     Window app_win, Window frame, ASWindow* t,
  183.                         icon_x, icon_y, icon_width, icon_height
  184.         A window is iconified.
  185.         When this packet is sent as part of a window list, the four last
  186.         data items are zero in case the window is iconified but the icon is
  187.         unmapped.
  188.  
  189. M_DEICONIFY       3     Window app_win, Window frame, ASWindow* t,
  190.                         icon_x, icon_y, icon_width, icon_height
  191.         A window is deiconified.
  192.         The last four data items are zero if the deiconification was
  193.         initiated by the application itself.
  194.  
  195. M_ICON_LOCATION   7     Window app_win, Window frame, ASWindow* t,
  196.                         new_icon_x, new_icon_y, icon_width, icon_height
  197.         An icon was moved.
  198.  
  199. M_TOGGLE_PAGING   1     0 or 1
  200.         The TogglePage built-in is called; the data value is 1 if the
  201.         edge scrolling is enabled and 0 if it is disabled.
  202.  
  203. M_NEW_PAGE        3     new_x, new_y, desknumber
  204.         The virtual screen is scrolled.
  205.  
  206. M_NEW_DESK        1     new_desknumber
  207.         A change of desktop.
  208.  
  209. M_SHADE           3     Window app_win, Window frame, ASWindow* t
  210.         A window is shaded.
  211.  
  212. M_UNSHADE         3     Window app_win, Window frame, ASWindow* t
  213.         A window is unshaded.
  214.  
  215. M_NEW_BACKGROUND  1     0 or 1
  216.         User decided to use another pixmap for background and pager must
  217.         update its pixmaps.
  218.  
  219. M_END_WINDOWLIST  0
  220.         An end marker for the Send_WindowList packetfest.  See below.
  221.  
  222. M_CONFIGURE_WINDOW  24  Window app_win, Window frame, ASWindow* t,
  223.                         frame_x, frame_y, frame_width, frame_height,
  224.                         Desk, flags, title_height, boundary_width,
  225.                         hints.base_width, hints.base_height,
  226.                         hints.width_inc, hints.height_inc,
  227.                         hints.min_width, hints.min_height,
  228.                         hints.max_width, hints.max_height,
  229.                         0, icon_pixmap_w, hints.win_gravity,
  230.                         TextPixel, BlackPixel
  231.         Some properties or flags associated with a window were changed.
  232.         Except for the zero and the ASWindow pointer, the data items in
  233.         the packet are fields of the ASWindow structure (see afterstep.h).
  234.  
  235. M_WINDOW_NAME     3+s   Window app_win, Window frame, ASWindow* t,
  236.                         char[] window_name
  237.         The title of a window is set or changed.
  238.  
  239. M_ICON_NAME       3+s   Window app_win, Window frame, ASWindow* t,
  240.                         char[] icon_name
  241.         The icon name of a window is set or changed.
  242.  
  243. M_RES_CLASS       3+s   Window app_win, Window frame, ASWindow* t,
  244.                         char[] res_class
  245.         The class name of a window is set.
  246.  
  247. M_RES_NAME        3+s   Window app_win, Window frame, ASWindow* t,
  248.                         char[] res_name
  249.         The application name of a window is set.
  250. ------------------------------------------------------------------------------
  251.  
  252. There is no corresponding packet for the mask value M_LOCKONSEND.
  253.  
  254.  
  255. In response to a Send_WindowList request, AfterStep sends the following
  256. packets to the module that sent the request:
  257.   
  258.         M_TOGGLE_PAGING
  259.         M_NEW_DESK
  260.         M_NEW_PAGE
  261.         * for each window:
  262.                 M_CONFIGURE_WINDOW
  263.                 M_WINDOW_NAME
  264.                 M_ICON_NAME
  265.                 M_RES_CLASS
  266.                 M_RES_NAME
  267.                 * if the window is iconified,
  268.                         M_ICONIFY
  269.                   (see the M_ICONIFY description for a special note on this)
  270.         * to terminate the window list:
  271.         M_END_WINDOWLIST
  272.  
  273.  
  274. The AfterStep library
  275. =====================
  276.  
  277. There is a library of utility routines available in the lib directory of the
  278. source distribution.  Your module can take advantage of the library by
  279. including the include file aftersteplib.h and linking to libafterstep.a.
  280.  
  281. Here's a lowdown of the routines in the library:
  282.  
  283. void SendText(int *fd,char *message,unsigned long window);
  284. void SendInfo(int *fd, char *message, unsigned long window);
  285.         Send a command to AfterStep.  The fd argument is the file descriptor
  286.         of the module-to-AfterStep pipe, message is the text command to be
  287.         sent, and window is None or the window ID of the window to be
  288.         affected.  The continuation flag in the packet is set.
  289.  
  290.         Interestingly, the two functions are identical.
  291.  
  292. char *findIconFile(char *icon, char *pathlist, int type);
  293.         Search for a file with the specified name (the `icon' argument)
  294.         along the pathlist given.  If found, the complete path name of the
  295.         file is returned.
  296.         The type argument corresponds to the second argument of access(2).
  297.         Typical values are R_OK and X_OK for readability and executability.
  298.  
  299. int ReadASPacket(int fd, unsigned long *header, unsigned long **body);
  300.         Read a packet from AfterStep.  The fd is the file descriptor of
  301.         the AfterStep-to-module pipe, header should point to an array of
  302.         MAX_HEADER unsigned longs, and body is the address of a pointer
  303.         that will be filled with the address of the body of the packet.
  304.  
  305.         The caller is responsible for free()ing the packet body area.
  306.  
  307.         The routine returns a positive number if the read went fine,
  308.         zero if the packet was invalid and a negative value if something
  309.         is very wrong.
  310.  
  311.         You should provide a routine with a prototype like
  312.                 void DeadPipe(int nonsense);
  313.         that will be called by ReadASPacket when the pipe is no longer open.
  314.         Usually this indicates that AfterStep is exiting.
  315.  
  316. void sleep_a_little(int n);
  317.         Sleep for the specified amount of microseconds.
  318.  
  319. int GetFdWidth(void);
  320.         Get the maximum number of files a process can open.
  321.  
  322. char *safemalloc(int size);
  323.         This is a malloc() that is guaranteed to succeed.
  324.  
  325. int matchWildcards(char *pattern, char *string);
  326.         Returns a nonzero value if the string matches the pattern.
  327.         The characters '?' and '*' are wildcards with the usual meanings.
  328.  
  329. int mystrcasecmp(char *a, char *b);
  330. int mystrncasecmp(char *a, char *b, int n);
  331.         These provide the nonstandard but useful str[n]casecmp functions
  332.         for systems that do not have them.  Briefly, they are just like
  333.         the ANSI str[n]cmp functions but ignore case differences.
  334.  
  335. char *CatString3(char *a, char *b, char *c);
  336.         Concatenate 3 strings into a single 256 byte global buffer.
  337.  
  338. int mygethostname(char *client, int namelen);
  339.         Get the name of the host machine if it is available by some means.
  340.         The string buffer is provided by the caller.
  341.  
  342. int mygetostype(char *buf, int max);
  343.         Acquire a string indicating the OS type if such information is
  344.         available.  The string buffer is provided by the caller.
  345.  
  346. void CopyString(char **dest, char *source);
  347.         Allocate memory for a copy of the source string, save the address
  348.         of the allocate area to *dest, and copy the source string without
  349.         any leading or trailing whitespace to the allocated area.
  350.  
  351. Compatibility with Fvwm
  352. =======================
  353.  
  354. As AfterStep is derived from Fvwm 1.24, the module interface is very close
  355. to that of Fvwm.  In practice AfterStep and Fvwm-1 modules are often
  356. interchangeable; however problems do occur.  I don't know a lot about the
  357. Fvwm interface so this section is sketchy at best.
  358.  
  359. Fvwm does not support locking (M_LOCKONSEND) nor shading (M_SHADE,
  360. M_UNSHADE).
  361.  
  362. Fvwm does not send icon coordinates in M_DEICONIFY messages.
  363.  
  364. AfterStep does not support any of the Fvwm-2 extensions.
  365.  
  366. More?
  367.  
  368.  
  369. Further reading
  370. ===============
  371.  
  372. The AfterStep source code is the definitive resource.  The source is a mess,
  373. but in principle it is modular which makes it easier to begin reading and
  374. comprehending relevant sections of the code.  The module communication takes
  375. place in module.c.
  376.  
  377. Obviously existing modules are a good basis for experimentation.  See the
  378. official ftp site and your favourite search engine to find more modules.
  379.  
  380. If you are just beginning X programming and looking for more depth than is
  381. available in the man pages, see the comp.windows.x FAQ for literature
  382. references.  For the economically challenged, the X source distribution
  383. contains dozens of megabytes of documentation.
  384.  
  385.  
  386. Disclaimer
  387. ==========
  388.  
  389. The document contains probably several inaccuracies, mistakes and what not.
  390. All responsibility is hereby transferred to the readers of the document.
  391. Use it for good.
  392.