WM(4) Window Manager ________ ABSTRACT This document describes the window manager being used in the Integral PC. User view, and program view are presented. This is revision 5.0; last changed 12-14-84 - 1 - WM(4) WM(4) 1. Overview Overview Overview Overview The window manager will allow multiple terminal emulators and multiple plotter emulators to exist at the same time. Each terminal and plotter has its own window on the screen. This makes it possible for the user to keep one programs I/O separate from another. The windows are allowed to be any size and may overlap. A typical window set would be a command window, and one or more application windows. Each window has its own menu which is under control of the program running within that window. There is also one system menu for global system use. The system menu is shared by all windows. A mouse will be supported, but is optional. A feature summary follows: * A given window's size, or position on the screen, may be changed at any time * The keyboard is attached to only one window at a time. * When a window receives output, it will be brought out in front of the other windows * A window can be told to 'hide' itself disappearing from the screen temporarily. * Positioning devices (mouse, etc) are supported 2. Why Have Windows Why Have Windows Why Have Windows Why Have Windows Windows exist to keep communication from becoming tangled. They do that by separating the different input and output character streams. On many machines a user must be aware of an "input mode" where he can not give a system command without pausing, or killing, his program. This is solved on the Integral PC by having the command interpreter and the application in two separate windows. It is especially important to reduce I/O ambiguity when there is more than one application program running at the same time. For example: if the user is using an editor and also needs frequent calculations from an RPN calculator program, he can simply communicate with the window of his choice as required. This method of communication with a "multi-tasking" operating system can be mastered even by a novice user so that he doesn't know that he is multi- tasking. - 2 - WM(4) WM(4) 3. User Model User Model User Model User Model The first part of the model is the desk and paper analogy. The screen can be considered a desk, with each window a paper on the desk. This is supported by the fact that windows can overlay each other without modifying each others information. The term "window" is also part of the model. A window supplies a view taken from a large two dimensional object. This object can be scrolled up, down, left, and right to change which part of the object is peeking through the window. For example: a spread sheet may only be seen 2 columns and 3 rows at a time. These six cells are a view of part of the spread sheet presented through the window. A small tab called the window "title" sticks up from the upper left edge of each window. The window title contains a unique window name. The window name in the title is the same as the last part of the path name for the window in the file system. This allows the user to communicate window names to a command interpreter. 3.1 Window Stacking Window Stacking Window Stacking Window Stacking Since windows are allowed to cover each other, some rules for uncovering need to be discussed. In general, whenever a window receives new information, either from a running program or from echoing a users input, that window will "show" itself. A window which is showing itself will be in front of the other windows. A window is also shown when it is selected by the mouse, when it comes out from "hideing" (off screen storage), or when it comes to the front via the "shuffle" command. Windows can also be told to hide. This is accomplished by using the "Hide" command in the system menu. When a window is hidden, the information part of the window is removed from the screen, while the title is placed at the lower left part of the screen. When there is more than one window hidden, there will be a title for each hidden window. If output occurs to a window in this state, the window will remain hidden. When the window is next shown (via the selector and the select key) the new information will be there. Shuffling a window to the front or back, or hiding it, does not change its place on the screen. Only its depth or visibility relative to the other windows is changed. This supports the paper/desk model by allowing specific papers to move to the top or bottom of a heap of papers on the desk. - 3 - WM(4) WM(4) 3.2 Active Window Active Window Active Window Active Window The keyboard is considered to be connected to only one window at a time. For example; when the user types, the letters will only show up in one window. This window is called the active window. The center of the menu contains the name of the active window. And, this name matches the name found in the window title of the active window. The user is in full control of which window is active. A window is made active by the user in the following ways: I. The mouse can be used to make a window active. Simply move the selector over any portion of the desired window and press the "Select" button. Note that the cursor keys can be made to act like a mouse. This is also the mechanism to retrieve a hiden window from the lower left of the screen. Simply select the title. II. If a window is brought to the top with the "shuffle" command, then it is made the active window. III. When an application is placed in a new window by PAM, it is made the active window. Note that in most cases the active window and the showing, or front, window are the same. The exceptions occur when a non-active non-front window is written to from some background task. If this window is not hiding as a title in the lower left then it will pop to the front of the other windows. This window does not become the active window unless the application wishes to get involved with this concept. 3.3 Cursors And The Selector Cursors And The Selector Cursors And The Selector Cursors And The Selector Each window has its own cursor. If a window is a terminal emulator (most windows) then the cursor will behave as a normal terminal cursor. If a window is a graphics window, then the cursor is associated with the plotter pen. Cursors are window based images that are not allowed to leave their windows. The selector is a small image that is free to roam over the entire screen. When the selector is between windows it will appear as a small diamond. When the selector is over the menu it will appear as a small arrow. Each window is allowed its own selector image so that as the selector travals across any portion of the window that image is in effect. The default image is a small arrow. The selector is usually controlled by a mouse, or other caravan loop device, but can be controlled by the cursor keys (by use of - 4 - WM(4) WM(4) the CTRL key). The selector is used with the "Select" key to select a place of interest on the screen. 3.4 Keyboard And Mouse Information Keyboard And Mouse Information Keyboard And Mouse Information Keyboard And Mouse Information The User Interface is designed around a required keyboard and an optional mouse. The following two techniques are used in order to allow the user interface to behave in a consistent manner with and without a mouse: I. The keyboard can simulate a mouse movement. In particular the cursor control keys can be made to control the selector instead. Simply use the CTRL key with the cursor keys. II. There are two keys on the keyboard ("Select", and "Menu") that duplicate the functionality of the two buttons on the mouse. 3.5 Menus In General Menus In General Menus In General Menus In General A menu is a list of items equivalent to the keylabels of the Series 80 machines and current HP terminals (2626 family). These items are listed horizontally at the bottom of the screen in an inverse video area. This area "floats" on top of any windows that extend into the bottom area of the screen. The existence of the menu will never modify information in any window even though the window is covered. The "Menu" key on the keyboard, and the right button on the mouse, will act as a toggle causing the menu to appear or disappear each time it is pressed. When the menu is displayed (via the "Menu" key or programatically) it will continue to be displayed until it is removed (again, via the "Menu" key or programatically). When a window is made active, the menu will show the items appropriate for that window. The soft keys can be used to access the menu items. However, it is also possible to access the items with the mouse and its "Select" key. Each window has its own menu called the user menu. This keeps menu items from different programs from interfering with each other. There is also a system menu for window manipulation commands that is shared by all windows. The "User" and "System" keys on the keyboard are used to select which menu type is active. Also, item 5 in the system menu is used to change to a window type specific menu. For example, the terminal 0 keys include items such as "Display Functns". The center area of the menu contains an identifier that tells the user which type of menu he is - 5 - WM(4) WM(4) looking at. The current identifiers are: "User", "System", "Alpha", and "Graphics". In all cases there will at most be one menu on the screen. And, if a menu exists, it will be associated with the active window. Also, for all cases, the mouse or the soft keys can be used for menu item selection. Finally, even if the menu is not being displayed, the soft keys can be used to select the items that the user knows are assigned there. 4. Command Description Command Description Command Description Command Description The user gives commands to the window manager in three ways: 1) utility programs (not described in this document), 2) the menu, and 3) hard keys. 4.1 System Menu System Menu System Menu System Menu The following sections describe the system menu commands in detail. 4.1.1 ____ This command removes the active window from the Hide screen without modifying the information it contains. Its banner will be placed in the lower left corner of the screen. To get this window back, move the selector to the banner and press the select key. 4.1.2 _______ This command inverts the color sense of the Invert* active window. Black on white will turn to white on black, and vice versa. The asterisk will come and go to indicate the current mode. 4.1.3 ____ This is an interactive command that will move Move the active window to a specified location without changing its size. When "Move" is invoked, the selector will change its image to that of a bracket in the shape of an upper left hand window corner (like an upside down "L"). This corner selector indicates the placement of the upper left hand corner of the window. The user can move the selector anywhere on the screen, and use the "Select" key to finish the command. The moved window will remain the active window. The move can be aborted at any time up to the final select by hitting any other key. That key will not only abort the move, but it will perform its usual function. 4.1.4 ______ This command is a toggle that tells the Pause* active window to perform no more output until the next pause command is given. The asterisk will come and go to indicate the current mode. When a window is paused, the internal buffers will fill up and then the process(s) will be put to - 6 - WM(4) WM(4) sleep. This is equivelent to CTRL-S and CTRL-Q in a standard unix tty driver. 4.1.5 _____ This command is used to toggle the save state Save* of the active window. The asterisk will come and go to indicate the current mode. When a window is not to be saved (no asterisk, and default mode) and no program is currently using the window (it is closed, but old output may still be present), then when the next window is created the former window will be destroyed. This command is used to retain old windows that have desirable information. 4.1.6 ____ This command is identical to the "Stop" hard Stop key. (See below.) It is included in the menu to facilitate system administration with a mouse. 4.1.7 _______ This is an interactive command that will Stretch change the size of a window while leaving its position unchanged. "Stretch" behaves like "Move" except that the corner selector looks like the lower right hand corner of a window (a backward "L"). The selected position becomes the lower right hand corner of the window, and the upper left hand corner (called the anchor) stays where it is. If the selected position is above or to the left of the anchor, then the window will be placed such that the selected position and the anchor form two corners diagonally opposed to each other. 4.1.8 __________________ These commands bring up the Alpha and Graphics window type specific menus. The active window type determines which one of "Alpha, "Graphics", or a future type will be indicated in the system menu. 4.2 Commands Assigned To Hard Keys Commands Assigned To Hard Keys Commands Assigned To Hard Keys Commands Assigned To Hard Keys Most of the keys on the keyboard are defined by the active window type. See the terminal emulator and plotter emulator ERS's. There are some keys on the keyboard whose functionality is defined by the window manager. Those keys are defined in the following sections. 4.2.1 ____ This key is found on the mouse and the Menu keyboard. Pressing this key will toggle the on/off nature of the menu. 4.2.2 _____ This key will cause a full screen dump to the Print internal printer. 4.2.3 ________________ This is known as a "shuffle". The Select (Shifted) farthest window back on the screen will come to the front and become the active window. This is the standard way to - 7 - WM(4) WM(4) switch between windows. 4.2.4 __________________ This key is found on the mouse Select (Unshifted) and the keyboard. When the selector is over a menu item, and "Select" is pressed, that item is invoked. When the selector is at the middle of the menu the menu is toggled between the system items and the user items. If the center indicator is showing "Alpha" or "Graphics", then the menu will change to system. When the selector is over any part of a window, then that window is placed on top of any windows which might be covering it, and it is made the active window. When a "Move" or "Stretch" is in effect (as indicated by the shape of the selector), the position on the screen will be used for placement or size information. 4.2.5 __________________ This command causes any invisible Select (with CTRL) window to show itself. Repetitive use will show windows in the reverse order that they were made invisible. (last invisible, first shown). An invisible window is one which is not on the screen at all. It is not merely hidden (title only format) or covered by other windows. This type of window is only created programatically. 4.2.6 ________________ This key will destroy the active Stop (Unshifted) window if it is not being used (not open). Otherwise, SIGQUIT will be sent to the process group, and the window will be destroyed when/if the final close occurs. 4.2.7 ______________ This key will destroy the active Stop (Shifted) window if it is not being used (not open). Otherwise, SIGKILL will be sent to the process group, and the window will be destroyed when/if the final close occurs. 4.2.8 ______ If the menu is not currently displayed, then System an implied "Menu" key hit will occur, and the system menu items will be placed into the menu. If the menu is already displayed, this key will toggle the menu items between the system set and the user set. 4.2.9 ____ This command causes the user menu items for the User currently active window to be placed into the menu. If the menu is not currently displayed, then an implied "Menu" key hit will also occur. 5. Software Interface To The Window Manager Software Interface To The Window Manager Software Interface To The Window Manager Software Interface To The Window Manager Normally, no knowledge of the window manager is required of any application. An application can communicate to the user as if it were using a standard terminal or plotter. The terminal 0 window has exactly the same protocols as the - 8 - WM(4) WM(4) standard TTY driver, right down to the baud rate data structures. This allows for easy software importation. It is only when an application wants to take advantage of some unique features of the window manager that explicit window manager communication must occur. This communication takes place through an additional set of IOCTL commands that are understood by any window or /dev/screen/wm (the window manager device node). 5.1 IOCTL Commands IOCTL Commands IOCTL Commands IOCTL Commands The following IOCTL commands are in addition to those available for a given window type (terminal, or plotter). In all cases the general calling format is: ioctl (fd, com, arg) "fd" is a standard file descriptor. "com" is an integer which specifies which command is to be invoked. "arg" can be a pointer used to pass parameter structures, or an actual parameter. Possible error conditions are listed for each command. However, other errors are possible since the general file system code controls access to any driver. Use to aquire the proper defines. 5.1.1 _______________________ This command will create a WMCREATE: Create Window new window. This new window will not be open as a device. However, a device node will be created for this purpose. Call "ioctl (fd, WMCREATE, arg)". "fd" can be associated with any window or with /dev/screen/wm. The "arg" parameter points to a structure with the following format: - 9 - WM(4) WM(4) struct windio { char w_path[40]; /* path name for node */ long w_minor; /* minor dev num */ short w_type; /* type of window */ short w_stat; /* window status */ short w_xloc; /* x coord. of window */ short w_yloc; /* y coord. of window */ short w_height; /* height of window */ short w_width; /* width of window */ short w_gen1; /* general purpose variable */ short w_gen2; /* general purpose variable */ short w_gen2; /* general purpose variable */ short w_gen4; /* general purpose variable */ } "w_path" is a path name that will be used to make the device node that is associated with the new window. Also the simple name at the end of the path will be used as the window name in the title. "w_path" is typically an absolute path name with '/dev/screen/' as the directory for the new window. "w_minor" is filled in by the window manager and passed back into the caller's structure. "w_type" specifies the type of window; 0 for a terminal, and 1 for a plotter. "w_stat" is a collection of bits defined as follows: - 10 - WM(4) WM(4) INVERT 000001 /* window has black background */ ACTIVE 000002 /* window is active (connected to to the keyboard). only one window will have this bit set */ AUTO_ACT 000004 /* window becomes active when the showing bit gets set. As soon as ACTIVE is set (for any reason) this bit is cleared */ FRONT 000010 /* window is the front most window. only one window will have this bit set. setting this bit with AUTO_ACT set will set ACTIVE */ AUTO_FRONT 000020 /* window will become frontmost on write if: CORK is cleared, and SHRUNK is cleared */ CORK 000040 /* window is paused. this equivelent to XOFF */ ON_SCREEN 000100 /* window is on the screen as oppossed to invisible off screen. clearing this bit will also clear ACTIVE and SHOWING */ NO_DESTROY 000200 /* the stop and shift-stop keys are ignored for this window. setting this bit will cause AUTO_DEST to be set. */ AUTO_DEST 000400 /* destroy window on last close */ IGNORE_KEY 001000 /* don't allow this window to become active and showing (front) just because some other window has been hidden or shuffled. this rule is relaxed if there is nothing but this kind of window on the screen */ NO_BANNER 002000 /* the window title will not be displayed when the window is not SHRUNK */ RECOVER 004000 /* destroy this window when a new window is created, if this window is closed. this is also toggled by the save key. an asterisk on the save key means that this bit is clear */ SHRUNK 010000 /* window is shrunk to banner only. */ KEY_SCAN 020000 /* when this bit is set for the active window, ALL keys on the keyboard, including window control keys are passed through to the read buffer as 2 byte codes. These codes are the same as described in the keyboard ERS (cntr-shift-reset is not passed - 11 - WM(4) WM(4) through) */ "w_xloc", "w_yloc", "w_height", and "w_width" are all in terms of screen dots. The origin of the screen (0,0) is the upper left corner. "w_gen1" through "w_gen4" are used in different ways for different window types. The terminal 0 window type uses w_gen1 to specify the number of lines in the terminal buffer, and w_gen2 to specify the number of columns. If 0 is specified for both, then a default of 48 lines by 80 columns will be used. For plotter windows the plotter bed size in dots is specified. The default is 512 dots wide by 255 dots high. The possible error conditions are as follows: EEXIST A file with the desired path name already exists (other codes are possible from the internal mknod call) EINVAL Bad w_type, or bad w_gen1 through w_gen4 ENOMEM Not enough system memory to create window ENOSPC Not enough table space in the window manager to create window 5.1.2 ____________________________ This command is used to WMGET: Get Window Parameters read the window parameters. Call "ioctl (fd, WMGET, arg)". "fd" can be associated with any window or with /dev/screen/wm. If fd is associated with /dev/screen/wm, then w_path is used to determine the target window. If w_path is null, then w_minor is used (see WMLIST and WMLLIST. "arg" must point to a windio structure (see the WMCREATE command). The possible error conditions are as follows: ENOENT No such window as w_path 5.1.3 ____________________________ This command is used to WMSET: Set Window Parameters change the window parameters. It is normal to perform a WMGET first. Call "ioctl (fd, WMSET, arg)". - 12 - WM(4) WM(4) "fd" can be associated with any window or with /dev/screen/wm. If fd is associated with /dev/screen/wm, then w_path is used to determine the target window. If w_path is null, then w_minor is used (see WMLIST and WMLLIST. "arg" must point to a windio structure (see the WMCREATE command). Also note that an attempt to change w_path through the /dev/screen/wm node will fail with ENOENT as the cause. Open the old path name and use that fd to change w_path. The possible error conditions are as follows: EEXIST A file with the desired path name already exists (other codes are posible from the internal mknod call) EINVAL Attempt to change w_type, w_minor, or w_gen1 through w_gen4 ENOENT No such window as w_path 5.1.4 ________________________________ This command is WMDESTROY: Set Window Parameters used to destroy a specific window. It will behave the same way as the shift-stop key, except that the target window is specified explicitly. Call "ioctl (fd, WMDESTROY, arg)". "fd" can be associated with any window or with /dev/screen/wm. "arg" must point to a windio structure (see the WMCREATE command). It is the "w_path" component of the structure that will determine which window to destroy. If w_path is null, then w_minor is used (see WMLIST and WMLLIST. Note that if the calling program is in the process group that the target window is controlling, SIGKILL will will be sent to the calling program. A program that wishes to destroy its own window should use WMGET and WMSET to set the AUTO_DEST bit. When the exit or final explicit close occurs, the window will be destroyed. The possible error conditions are as follows: ENOENT No such window as w_path 5.1.5 ________________________________ This command is WMGETMOUSE: Get Mouse Parameters used to get the current mouse position and button information. Call "ioctl (fd, WMGETMOUSE, arg)". - 13 - WM(4) WM(4) "fd" must be associated with the target window. (Each window has its own structure.) The "arg" parameter points to a structure with the following format: struct m_stat { double s_xloc; /* x coord. of sprite */ double s_yloc; /* y coord. of sprite */ unsigned short s_buttons; /* button status */ unsigned long s_mask; /* interrupt mask */ unsigned long s_event; /* event history */ } "s_xloc" and "s_yloc" contain the current sprite postion. "s_xloc" and "s_yloc" are relative to the window (not the screen). They are also in units appropriate for the window type. Terminals deal in character positions, and plotters deal in scaled values. The sprite hot spot determines which part of the sprite is actually at the coordinates (see WMGETSPRITE). "s_buttons" specifies the current state of the mouse buttons. The least significant bit is associated with the left most button. If a bit is set, then that button is down. "s_mask" is used to specify conditions to interrupt the user process with the SIGMOUSE signal. "s_mask" is a set of bits defined as follows: EVENT_B1_DOWN 00000001 /* button 1 pressed */ EVENT_B1_UP 00000002 /* button 1 released */ EVENT_B2_DOWN 00000004 /* button 2 pressed */ EVENT_B2_UP 00000010 /* button 2 released */ EVENT_B3_DOWN 00000020 /* button 3 pressed */ EVENT_B3_UP 00000040 /* button 3 released */ EVENT_B4_DOWN 00000100 /* button 4 pressed */ EVENT_B4_UP 00000200 /* button 4 released */ EVENT_B5_DOWN 00000400 /* button 5 pressed */ EVENT_B5_UP 00001000 /* button 5 released */ EVENT_B6_DOWN 00002000 /* button 6 pressed */ EVENT_B6_UP 00004000 /* button 6 released */ EVENT_B7_DOWN 00010000 /* button 7 pressed */ EVENT_B7_UP 00020000 /* button 7 released */ EVENT_B8_DOWN 00040000 /* button 8 pressed */ EVENT_B8_UP 00100000 /* button 8 released */ EVENT_SPRITE 00200000 /* sprite moved */ EVENT_MOVE 00400000 /* window moved */ EVENT_STRETCH 01000000 /* window stretched */ EVENT_ACTIVE 02000000 /* w_stat ACTIVE bit changed */ - 14 - WM(4) WM(4) The default "s_mask" setting is 0. Use WMSETMOUSE to modify "s_mask". "s_event" can be used to sense the events which have occured. The "s_event" bits are defined the same as the "s_mask" bits. "s_event" represents an intersection between "s_mask" and the events which have happened, but which have not yet been WMEVENTPOLLed or cleared by WMSETMOUSE. Individual "s_event" bits are cleared when the information about the event(s) is read by WMEVENTPOLL. Setting bits in "s_event" then doing a WMSETMOUSE will clear the corresponding bits. To clear all events do a WMGETMOUSE followed by a WMSETMOUSE. The possible error conditions are as follows: (none special for this command) 5.1.6 ________________________________ This command is WMSETMOUSE: Set Mouse Parameters used to set the current mouse position. It is also used to set up signal generation events. Setting up mask will allow the window manager to send the SIGMOUSE signal to the process group attached to this window. The receiving program still has to catch SIGMOUSE with the signal() function call. The default signal behavior is SIG_IGN (ignore signal). Call "ioctl (fd, WMSETMOUSE, arg)". "fd" must be associated with the target window. The "arg" parameter points to a structure of the type defined for WMGETMOUSE. Setting bits in "s_event" then doing a WMSETMOUSE will clear the corresponding bits. To clear all events do a WMGETMOUSE followed by a WMSETMOUSE. Note that only s_xloc, s_yloc, and s_mask are writable. The other parameters are ignored. The possible error conditions are as follows: EBUSY attempt to change sprite possition when not active Note that mask will still be read in and set up 5.1.7 __________________________________ This command is WMEVENTPOLL: Poll For Mouse Events used to get information about mouse events. Call "ioctl (fd, WMEVENTPOLL, arg)". "fd" must be associated with the target window. (Each window has its own structure.) The "arg" parameter points to a structure with the following format: - 15 - WM(4) WM(4) struct m_event { unsigned long e_event; /* desired event */ short e_count; /* number of times event has occured */ double e_x; /* sprite x last time event occured */ double e_y; /* sprite y last time event occured */ } "e_event" is defined in the same way as "s_event" in WMGETMOUSE, and WMSETMOUSE. In this case, however, it is an input parameter and an output parameter. If e_event is passed to WMEVENTPOLL as 0, then the last event that has occured will be selected. "e_event" will be passed back containing the appropriate value. (EVENT_SPRITE will not be considered an event in this case.) However, if "e_event" is passed in containing a bit set, then this is the event which will be polled. If more than one bit has been set, then the most significant (left most) will be used. For the bits associated with buttons, "e_count" is the number of times this event has occured since the last time the "e_x", and "e_y" values were read. "e_x" is the sprite x location at the time of the last event of this type. "e_y" is the sprite y location at the time of the last event of this type. "e_x", and "e_y" are in units appropriate for the particular window type. For bits not associated with buttons, e_count will be 0 or 1 depending on whether the event has happened, and e_x and e_y are set to the current sprite position. The possible error conditions are as follows: (none special for this command) 5.1.8 __________________________________ This command is WMGETSPRITE: Get Sprite Parameters used to get the current sprite pattern and hot spot. The pattern is a 16 dot by 16 dot bit pattern which is exclusive or'ed on to the screen. The hot spot is the dot that is used for movement and position reporting. When the sprite is over the window, the sprite will take on this shape. The default shape is a large arrow. The default hot spot is at 0,15 (the tip of the arrow). Call "ioctl (fd, WMGETSPRITE, arg)". "fd" must be associated with the target window. The "arg" parameter points to a structure defined as follows: - 16 - WM(4) WM(4) struct sprt_stat { char sprite[32]; /* sprite image */ short hot_x; /* hot spot x */ short hot_y; /* hot spot y */ } "sprite[]" holds the 32 byte sprite image. "sprite[0] is the upper left 8 bits. "sprite[1] is the upper right 8 bits. "hot_x", and "hot_y" define the hot spot of the sprite image. The hot spot is used to get and set sprite position. 0,0 is the upper left pixel. Note that the hot spot may be outside of the sprite (in fact it can be placed so that the sprite is clear across the screen inside some other window). The possible error conditions are as follows: (none special for this command) 5.1.9 __________________________________ This command is WMSETSPRITE: Set Sprite Parameters used to set the sprite pattern and hot spot. When the window is active and showing (front most), and the sprite is within the window boundary or title, then the sprite will take on this shape. Call "ioctl (fd, WMSETSPRITE, arg)". "fd" must be associated with the target window. The "arg" parameter points to a structure of the type defined for WMGETSPRITE. The possible error conditions are as follows: (none special for this command) 5.1.10 _________________________________________ This WMGETMSREL: Get Mouse Sprite Relationship command is used to get the current travel muliplier, to detect mouse existance, and number of buttons. Call "ioctl (fd, WMGETMSREL, arg)". "fd" can be associated with any window or with /dev/screen/wm. The "arg" parameter points to a structure defined as follows: - 17 - WM(4) WM(4) struct msrel_stat { int m_exist; /* mouse exists (number of buttons)*/ int m_xshift; /* horizontal multiplier for mouse movement */ int m_yshift; /* vertical multiplier for mouse movement */ } If the mouse exists, "m_exist" is set to the number of buttons. If the mouse does not exist, "m_exist" is set to -1. "m_xshift", and "m_yshift" are used to change the sensitivity and speed of the sprite. Small values speed up the movement, but makes it difficult to select a given spot due to coarseness. The raw mouse data is shifted right by these numbers. The possible error conditions are as follows: (none special for this command) 5.1.11 _________________________________________ This WMSETMSREL: Set Mouse Sprite Relationship command is used to set the mouse sprite relationships. Call "ioctl (fd, WMSETMSREL, arg)". "fd" can be associated with any window or with /dev/screen/wm. The "arg" parameter points to a structure of the type defined for WMGETMSREL. Note that "m_exist" will be ignored. The possible error conditions are as follows: (none special for this command) 5.1.12 ________ This command is used to lock all windows WMLOCK: so that the calling process can communicate with the screen hardware directly. Any other pid which attempts to modify the screen using the normal window manager ioctls or by communicating with their window(s) will be put to sleep untill the original process performs a WMUNLOCK. Call "ioctl (fd, WMLOCK, NULL)". "fd" can be associated with any window or with /dev/screen/wm. The "arg" parameter is not used. - 18 - WM(4) WM(4) The possible error conditions are as follows: (none special for this command) 5.1.13 __________ This command is used to turn the window WMUNLOCK: manager on after a WMLOCK has been in effect. Note that destroying or refreshing windows may be appropriate if the screen has been disturbed while WMLOCK was in effect. Call "ioctl (fd, WMUNLOCK, NULL)". "fd" can be associated with any window or with /dev/screen/wm. The "arg" parameter is not used. The possible error conditions are as follows: (none special for this command) 5.1.14 _________ This command will return a long list of WMLLIST: objects that the window manager is currently controlling. Call "ioctl (fd, WMLLIST, arg)". "fd" can be associated with any window or with /dev/screen/wm. The "arg" parameter points to a structure defined as follows: struct w_llist { int l_active; int l_lastactive; int l_bottom; char llist[256][2]; } The three integers in the structure are indices into the list array. They point to the currently active window, the window that was active before that, and the bottom most object that is on the screen. -1 is used to specify that there is no such window, or object. The rows in the list represent the individual objects. The zero'th row is the frontmost object. Higher indices specify objects farther back from the front. Ojects that are off the screen entirely (not just occluded, ON_SCREEN is clear) follow the bottommost object (llist[l_bottom]). The list is terminated with both bytes set to -1. Each row in the list array contains information about an object. The first byte is an - 19 - WM(4) WM(4) object number. This number can be used in the w_minor field of the WMGET, WMSET, and WMDESTROY commands. The second byte specifies the object type as follows: 0-64, window types 0, terminal 0 1, hpgl plotter >64, icons etc. (possible future) The possible error conditions are as follows: (none special for this command) 5.1.15 ________ This command returns a short list of WMLIST: objects controlled by the window manager. Call "ioctl (fd, WMLIST, arg)". "fd" can be associated with any window or with /dev/screen/wm. The "arg" parameter points to a structure defined as follows: struct w_list { char list[5][2]; } Each row of the list array above is interpreted the same as in the llist array of the WMLLIST command. However, the rows are not ordered from front to back. The ordering is as follows: row 0, active window row 1, last active window row 2, front object row 3, 2nd object row 4, bottom object which is on screen Note that any or all of the above rows may read as -1, -1 (no such object). The possible error conditions are as follows: (none special for this command) - 20 - WM(4) WM(4) 5.1.16 ________ This command is used to define the visual WMMENU: part of a windows menu. The keycodes read by a program are not redefinable via this command. Note that term0 windows have escape sequences to define images and definitions, while the graphics windows have neither. The normal use for this call is to set up menus for graphics windows, and for fast menu changes of term0 windows. Call "ioctl (fd, WMMENU, arg)". "fd" must be associated with the target window. The "arg" parameter points to a structure defined as follows: struct menu { char items[16][8]; /* menu labels */ unsigned char upper; /* shifted key flags */ } "items" contains an 8 character label for each of 16 menu positions. Position 0 is the lower part of item 1, position 1 is the lower part of item 2, etc. Position 8 is the upper part of item 1, etc. "upper" contains 8 bits, one for each softkey. The most significant bit is associated with the left most key. If a bit is clear, both the shited and unshifted key will generate the unshifted code. If a bit a set, there will be two different codes, and a horizontal dividing line will appear between the two items. A term0 windows concept of which keys have shifted items, should not be violated by indescriminate setting and clearing of the "upper" bits. The "upper" bits should always be in sync with any previously sent escape sequences. The possible error conditions are as follows: (none special for this command) 5.1.17 __________ This command is used to initialize the ALL_INIT: window manager. All internal variables will be reset. This command will also cause the keyboard driver and screen driver to be initialized. Any windows should be destroyed first. Call "ioctl (fd, ALL_INIT, NULL)". "fd" can be associated with any window or with /dev/screen/wm. The "arg" parameter is not used. - 21 - WM(4) WM(4) The possible error conditions are as follows: (none special for this command) 5.1.18 _____________ This command is used to aquire the ALL_VERSION: version of the window manager control module. Each window type has its own equivalent command. The version is interpreted as a five digit decimal number xxyzz where xx is the major product release level, y is the revision level, and zz is the soft (patch) revision level. Call "ioctl (fd, ALL_VERSION, arg)". "fd" can be associated with any window or with /dev/screen/wm. The "arg" parameter points to an integer. This integer location will receive the version code. The possible error conditions are as follows: (none special for this command) - 22 -