--- name: "common" section: "3x" platform: "linux" package: "libafterimage-dev" version: "2.2.12-18" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/common" --- # common(3x) common functions used in other examples libAfterImage/tutorials/common.h ## NAME **common** - common functions used in other examples libAfterImage/tutorials/common.h ## SYNOPSIS Generic Xlib related functionality, common for all the tutorials. ## SEE ALSO libAfterImage, ASView, ASScale, ASTile, ASMerge, ASGrad, ASFlip, ASText libAfterImage/tutorials/\_XA\_WM\_DELETE\_WINDOW ## NAME\_XA\_WM\_DELETE\_WINDOW ## SYNOPSIS \_XA\_WM\_DELETE\_WINDOW - stores value of X Atom "WM\_DELETE\_WINDOW". ## DESCRIPTION In X all client's top level windows are managed by window manager. That includes moving, resizing, decorating, focusing and closing of windows. Interactions between window manager and client window are governed by ICCCM specification. All the parts of this specification are completely optional, but it is recommended that the following minimum set of hints be supplied for any client window: Window's title(WM\_NAME), iconified window title(WM\_ICON\_NAME), class hint (WM\_CLASS) and supported protocols (WM\_PROTOCOLS). It is recommended also that WM\_DELETE\_WINDOW protocol be supported, as otherwise there are no way to safely close client window, but to kill it. All of the above mentioned hints are identified by atoms that have standard preset values, except for WM\_DELETE\_WINDOW. As the result we need to obtain WM\_DELETE\_WINDOW atoms ID explicitly. We use \_XA\_WM\_DELETE\_WINDOW to store the ID of that atom, so it is accessible anywhere from our application. ## SOURCE Atom \_XA\_WM\_DELETE\_WINDOW = None; libAfterImage/tutorials/create\_top\_level\_window() ## NAMEcreate\_top\_level\_window() ## SYNOPSIS Window create\_top\_level\_window( ASVisual \*asv, Window root,\ int x, int y,\ unsigned int width,\ unsigned int height,\ unsigned int border\_width,\ unsigned long attr\_mask,\ XSetWindowAttributes \*attr,\ char \*app\_class ); ## INPUTS - asv \- pointer to valid preinitialized ASVisual structure. - root \- root window of the screen on which to create window. - x, y - desired position of the window - width, height - desired window size. - border\_width \- desired initial border width of the window (may not have any effect due to Window Manager intervention. - attr\_mask \- mask of the attributes that has to be set on the window - attr \- values of the attributes to be set. - app\_class \- title of the application to be used as its window Title and resources class. ## RETURN VALUE ID of the created window. ## DESCRIPTION create\_top\_level\_window() is autyomating process of creating top level application window. It creates window for specified ASVisual, and then sets up basic ICCCM hints for that window, such as WM\_NAME, WM\_ICON\_NAME, WM\_CLASS and WM\_PROTOCOLS. ## SOURCE Window create\_top\_level\_window( ASVisual \*asv, Window root, int x, int y,\ unsigned int width, unsigned int height,\ unsigned int border\_width, \ unsigned long attr\_mask,\ XSetWindowAttributes \*attr, \ const char \*app\_class, const char \*app\_name ) {\ Window w = None; #ifndef X\_DISPLAY\_MISSING\ char \*tmp ;\ XTextProperty name;\ XClassHint class1; w = create\_visual\_window(asv, root, x, y, width, height, border\_width, \ InputOutput, attr\_mask, attr ); tmp = (app\_name==NULL)?(char\*)get\_application\_name():(char\*)app\_name;\ XStringListToTextProperty (&tmp, 1, &name); class1.res\_name = tmp; /\* for future use \*/\ class1.res\_class = (char\*)app\_class;\ XSetWMProtocols (asv-\>dpy, w, &\_XA\_WM\_DELETE\_WINDOW, 1);\ XSetWMProperties (asv-\>dpy, w, &name, &name, NULL, 0, NULL, NULL, &class1);\ /\* final cleanup \*/\ XFree ((char \*) name.value); \#endif /\* X\_DISPLAY\_MISSING \*/\ return w; } libAfterImage/tutorials/set\_window\_background\_and\_free() ## NAMEset\_window\_background\_and\_free() ## SYNOPSIS Pixmap set\_window\_background\_and\_free( Window w, Pixmap p ); ## INPUTS - w \- ID of the window background of which we need to set. - p \- Pixmap to set background to. ## RETURN VALUE None on success. Pixmap ID of original Pixmap on failure. ## DESCRIPTION set\_window\_background\_and\_free() will set window's background to specified Pixmap, Then refresh window contents so that background is drawn by the server, flush all the requests to force it to be sent to server to be processed as fast as possible. ## NOTES After Window's background has been set to Pixmap - X server makes hidden copy of this Pixmap for later window refreshing. As the result original Pixmap is no longer needed and can be freed to conserve resources. ## SOURCE Pixmap set\_window\_background\_and\_free( Window w, Pixmap p ) { #ifndef X\_DISPLAY\_MISSING\ if( p != None && w != None )\ {\ Display \*dpy = get\_default\_asvisual()-\>dpy; if (dpy)\ {\ XSetWindowBackgroundPixmap( dpy, w, p );\ XClearWindow( dpy, w );\ XFlush( dpy );\ XFreePixmap( dpy, p );\ p = None ;\ }\ } #endif /\* X\_DISPLAY\_MISSING \*/\ return p ; } libAfterImage/tutorials/wait\_closedown() ## NAMEwait\_closedown() ## SYNOPSIS void wait\_closedown( Window w ); ## INPUTS - w \- ID of the window from which to wait for events. ## DESCRIPTION User action requesting window to be closed is generally received first by Window Manager. Window Manager is then handles it down to the window by sending it ClientMessage event with first 32 bit word of data set to the value of WM\_DELETE\_WINDOW Atom. Accordingly, all client has to do is wait for such event from X server and, when received, it should destroy its window and generally exit. ## NOTES It is recommended that XFlush() is issued right after XDestroyWindow() as Window Manager itself may attempt to do something with the window until it receives DestroyNotify event. ## SEE ALSO ICCCM, Window ## SOURCE void wait\_closedown( Window w ) { #ifndef X\_DISPLAY\_MISSING\ Display \*dpy = get\_default\_asvisual()-\>dpy; if(dpy)\ {\ if (w)\ {\ XSelectInput (dpy, w, ( StructureNotifyMask \| \ ButtonPressMask\|\ ButtonReleaseMask)); while(w != None)\ {\ XEvent event ; XNextEvent (dpy, &event);\ switch(event.type)\ {\ case ClientMessage:\ if ((event.xclient.format != 32) \|\|\ (event.xclient.data.l\[0\] != \_XA\_WM\_DELETE\_WINDOW))\ break ;\ case ButtonPress:\ XDestroyWindow( dpy, w );\ XFlush( dpy );\ w = None ;\ break ;\ }\ }\ }\ XCloseDisplay (dpy);\ } #endif }