Appendix. Software. Overview... Data Types Used in the Starter Toolkit... Functions... Resources and Convenience Function of Paper Class Widgets...

Transcription

1 Appendix Software A.1. A.2. A.3. A.4. Overview... Data Types Used in the Starter Toolkit... Functions... Resources and Convenience Function of Paper Class Widgets

2 SOFTWARE 361 A.1. OVERVIEW The Starter toolkit was originally developed as an education tool to allow graduate and undergraduate students to write graphics or image-processing programs easily without being overwhelmed by X Window System complexity. It has been used for such a purpose since From the beginning the goal was not to provide a complete toolkit but to support only the most common operations used in graphics and image processing. It was assumed that if students needed to use parts of X not covered by the Starter toolkit, they could access them by writing Xlib or Xt code. The Starter toolkit offers hooks for such extensions, and the name starter was deliberately chosen to emphasize this feature of the toolkit. The need to support extensions was one reason that we did not use a toolkit such as Tk. Another reason for creating one more toolkit was our commitment to the C (or C++) language. In significant parts of our work, the graphics interface was used only during development and debugging, and the final code was stripped of all window-system-related parts. We eventually found that the Starter toolkit was useful not only for avoiding the complexity of the X Window System but also as a supplement when the major part of a program was in Xlib (as in the spy program in Listing 2.2). However such usage conflicts with the original intention. Initially names were kept as simple as possible, but once mixed with significant amounts of Xlib and Xt code, an identifying prefix was desirable. Another problem was that the original version support selection menus in terms of peer objects of a major toolkit, such as Motif (the particular toolkit was determined at compilation time). When the Starter toolkit was linked to a program that had its own ideas about selection menus, there were problems. This led to a stripped-down version of the toolkit with macros that redefine names by adding the prefix St_. Having two versions of a library (even if one is in essence a subset of the other) does not seem to be a good solution, but another centrifugal force becomes apparent at the same time. As PCs became increasingly popular in both the laboratory and the classroom it was necessary to provide tools to simplify programming in the Microsoft Windows environment. Kevin Hunter, who was the teaching assistant in the undergraduate graphics course, with the help of other students ported a large part of the Starter application toolkit to the win32 process inferface (API) for Windows 95 and Windows NT. Clearly the PC and X Starter toolkits must differ in how they hook with the main window system; thus the spell was broken, and we had to include functions that were different in each version. The version of the Starter toolkit included with the code in this book is minimal and of course includes all the hooks for X.

3 362 FUNDAMENTALS OF X PROGRAMMING A.2. DATA TYPES USED IN THE STARTER TOOLKIT St_event Type defined as typedef struct { int x, y; /* location of the cursor */ int kind; /* what kind of event occurred */ char key; /* what key was struck on the keyboard, if any */ long origin; /* where it comes from (widget) */ long time; /* time of the event in milliseconds */ } pevent; #define St_event pevent The possible values for kind are declared in the file Starter. h, which can be found in starter /include. A.3. FUNCTIONS This section documents Starter toolkit functions used in program examples in this text. St_arguments (int arc, char **arv) int St_back_color (char *cname) void St_clear_screen (int x, inty, intw, int H) void St_collect_text (St_event *p) Pass the arguments of the command line to the Intrinsics. Used when an application uses Starter toolkit functions to create its main window. Set the background color to the given name (e.g., red, orange, etc.); returns 0 if the color is successfully set, otherwise it returns -1.. If any argument is negative, the entire drawing window is erased; otherwise only a rectangle with upper left corner coordinates x, y and dimensions W and H is erased. Event handler for collecting strings of characters typed on the window; see also St_init_text (), St_set_string_use(), and St_get_string().

4 SOFTWARE 363 void St_draw_area (PaperWidget w) void St_draw window (void (*f) (), void (*g) (St_event*), intw, inth, char*s) void St fill_rectangle (int x, int y, int W, int H) int St for_color (char*cname) void St_get_default_args (Display **dpp, Window *wp, GC *gcp) void St_get_string (St_event *p) int St_init_text (int x, int y, int k). Copy the display pointer, window, and GC associated with w to the static variables of the module containing Starter toolkit drawing functions such as St_put_line () and St_fore_color(). Argument f is a pointer to a drawing function, as in vis_window ( ); g is the event handler, w and h are the width and height of the window, respectively; and s is the window label. Display a filled rectangle with upper left corner coordinates x, y and dimensions w and H. Set the foreground color to the given name (e.g., red, orange, etc.); returns 0 if the color is successfully set; otherwise it returns -1. Return the values of the first three arguments of Xlib functions needed to draw on windows created by the Starter toolkit. Event handler that, in response to a button press, places a prompt at the cursor location and then displays typed text there. It calls St_init_text ( ) and St_collect_text (). Initialize text collection when the event handler is collect_text ( ). Characters typed on the keyboard appear in the application window, starting at the location with coordinates x, y. If k is nonzero pressing the return key terminates text entry. Otherwise the user must press the escape key to terminate text entry; see also set_string_use ( ).

5 364 FUNDAMENTALS OF X PROGRAMMING int Stnake_color_cursor (unsigned char iconbits [ ], int hx, int hy, char *color, char *mask_color) void St_put_line (intx1, intyl, intx2, int y2) void St_put_text(char*text, putx, puty). void St_set_foregr (long c) void St_set_redraw (void (*f)() ) voidst set_string_use (void (*f) (char *) ) Cursor St_true_cursor (int c) Create a cursor icon using the array iconbits. Arguments hx and hy are coordinates of the cursor hot spot, the point whose coordinates are returned by the event handler. The upper left corner of the icon is 0, 0. The last two arguments must be character strings specifying colors of the cursor and its mask. Function returns an integer used to reference the cursor from the applications program. Function returns a negative index when not enough memory is left to create the structure. The mask is automatically created. Display a straight line segment joining a pair of points with coordinates x1, y1, and x2, y2, respectively. Display the string text so that it starts at x, and its baseline is at y; it returns the width of the displayed text in pixels. Warning: The string should not contain new line characters. Set the foreground color to the value c. Argument f is the name of a function that normally takes no arguments; it should be called whenever it is necessary to redraw a window. Advanced Use: In reality, the Intrinsics call f with the widget when an expose event occurrred as its argument. Applications that deal with multiple windows may find this feature useful. Used when the eventg handler is St_collect_text ( ). After the user terminates text entry, the function f is called with the entered text as its argument. Return the Cursor XID, given the return of the St_make_color_cursor () function.

6 SOFTWARE 365 void St_use_replace_mode() void St_use_xor_mode() void St_vis_window (void (*f)(), int w, int h) void St_xflush() Set the drawing mode to replacement. (The old value is replaced by the new.) Set the drawing mode to exclusive OR. (The value in the refresh memory is formed by the bitwise exclusive OR of the old and the new values.) Create a window with width w and height h or default values if arguments are unreasonable. When the window is ready, call f ( ) to create the display contents. The function f() is also called whenever the window must be redrawn in response to display changes; for example if the window is obscured by another, then becomes visible. Flush the graphics instructions to the server. Normally drawing instructions are buffered until there are events in the server queue. Calling this function causes immediate execution. A.4. RESOURCES AND CONVENIENCE FUNCTION OF PAPER CLASS WIDGETS Paper class widgets can be created by specifying paperwidgetclass. This class inherits all Core class resources, and it has the following additional resources (in alphabetical order): XtNfont (type XFontStruct *): Font to be used for text display; default is the default server font. XtNforeground (type Pixel) : : Foreground color; default is black. XtNredrawCallback (type XtCallbackList): Expose event callback; function pointer passed to St_vis_window ( ) or St_draw_ window as first argument is not this callback. Starter toolkit has an internal callback that does some preliminary work, then calls that function; default is NULL. XtNrigid (type Boolean): Used internally by the Starter toolkit to establish constraints that do not allow the user to resize the widget window; default is True.

7 366 FUNDAMENTALS OF X PROGRAMMING XtNuserCallback (type XtCallbackList): Callback in response to keyboard and mouse events. A pointer to a simplified event structure of type St_event is passed as call data. This is not the same as the function passed as second argument to St_draw_window. Starter toolkit has an internal callback that calls the function with the pointer as the only argument; default is NULL. XtNuserData (type XtPointer): Place to hang data; default is NULL. XtNvisual (type Visual *): Server visual; a read-only resource to be used with color map and raster image functions. In addition there are three convenience functions: GC paper_gc (Widget w): Return the read/write graphic context. GC pr_paper_gc (Widget w): Return the read-only graphic context. XtPointer *paper_hanger (Widget w): Return a pointer to the location used to store user data. Note: Before calling any of the drawing functions, the function St draw_area ( ) must be called.

8 REFERENCES [AS90] [JR94] [Ki95] [Kr96] [MvR96] [Ny92] [Ou94] [Pa96] [Pi83] [SG92] P. J. Asente and R. R. Swick, X Window System Toolkit. Digital Press/Butterworth Heinemann, Newton, MA, E. F. Johnson and K. Reichard, Advanced X Window Applications Programming M&T Books, MIS:Press, Inc., New York, P. E. Kimball, The X Toolkit Cookbook, Prentice Hall, Englewood Cliffs, NJ, M. J. Kirkland, OpenGL Programming for the X Window System. Addison-Wesley, Reading, MA, J. D. Murray and W. vanryper, Graphics File Formats, 2d ed. O Reilly, Sebastopol, CA, A. Nye (ed.). Xlib Reference Manual, vol. 2, 3d ed. O Reilly, Sebastopol. CA, J. K. Ousterhout, Tcl and the Tk Toolkit, Addison-Wesley, Reading, MA, T. Pavlidis, Interactive Computer Graphics in X PWS Publishing, Boston, Rob Pike, Graphics in Overlapping Bitmap Layers, ACM Transactions on Graphics 2, No. 2, 135 (April 1983). R. W. Scheifler and J. Gettys, X Window System, 3d ed. Digital Press, Burlington, MA,

9 Index Accelerators, 147 Action(s) Procedure(s), 97, 98, 103, 131, 199, 246 prototype for, 104 table, 104 Active window, 45 Animation, 119 Application class, 77 Application Programming Interface for Selections, 298 Application shell, 159 Applications class, 70 Arc drawing, 225 Argtype, 64 Asynchronous animation, 124 Athena toolkit, 7, 61, 71, 138 Atoms, 36, 39 Attributes, 34 Background color, 17, 217, 235 Backing store, 35 Backing up windows, 34 Base classes, 61 Bitmaps, 231 bit_gravity, 35 Blackboard widget, 335, BlackPixel, 17, 28 Blinking text, Blocking function, 31 Box widget (Athena), 152 Buffer between client and server, 31 Bulletin Board widget, 209 (Motif or OLIT), 156 Button, actions, invoked from keyboard, 147 creation, utility function, 145 Widgets, 143 ButtonPress, 41 ButtonRelease, 41 Call data, 325 Callback(s), 10, 97, 98, 100, 306, 308, 324 list, 10, 100, 101 prototype, 100 call_data, 100, 103 Cascade button, 188, 191 Changing event handlers, reasons for, 100 Circular arc drawing, 225, 226 Class record, , 317, 318, 324 Clearing a window area, 225 Client (application), 5, 27 machine name, 38 message, 283 ClientMessage, 47-49, Client data (in Xt), 203 client_data, 99, 100, Clip masks, 242 Clipboard selection, 284 Clipping widget, 184 Color, approximation, 252 economizing,

10 370 FUNDAMENTALS OF X PROGRAMMING Color (cont.) halftoning, 251 name database, 255 Colormap, 16, 187, creating new, 265 hardware, 251 of image, 267 logical, 16, 251 reason for complexity in X, Command line resource name abbreviations, 73 Command Widgets, 143 Communication between applications (clients), 29, 283 Communication between server and window manager, 46 Comparison of event handler versus translation table, 110 Compiling Xt programs, 10 Composite widget (class), 61, 335, 351 Compound widgets, 183 ConfigureNotify, 42 Constraint Widget Class, 61, 63, 175 of the Athena Toolkit, 177 of the Motif Toolkit, 180 of OLIT, 183 Constraints, widget member, 175 Container Widgets, 137, 138, 152 Content widget, 184 Control area widget (OL1T), 152 Control of keyboard, 41 Control of mouse, 41 Convenience functions (for window properties), 37 Core widget class, 61 resources, 67 Cursor(s), 231,234 font, 239 Cut-and-paste, 283 Debugging X programs, 20 Default colormap, 253 depth, 262 font of the server, 236 visual, 262 DefaultGC, 221 Def aultscreenof Display, 35 Def aultscreen, 30 Detail of event (in translation table), 109 Device versus graphics context, 8 Dialogue box(es), 42, 208, 210 Extended, 212 Widgets, 208 Digital clock, 124 Disabling a widget, 149, 155 DISPLAY (shell environment variable), 27 Display structure, 27 DoesBackingStore,35 Drag and Drop, 283, 300 Drawable(s), 217, 218 Drawing area widget, Motif, 167 OLIT, 167 Drawing widgets, 138, dup. 126 Elliptic arc drawing, 225, 226 Entering text, 128 Entry Form Application, 202 Event(s), 3, 31,97 dispatching, 32, 97 driven programs, 3, 31 expose. 33, 35, 41,313, 324 handler, 97, 98, 110, I 14, 1 16, 324 prototype, 98 queue, 3 I relationship with messages, 3 selection, 31,41 Exclusive OR (XOR), 17 with nonzero background, 223 Exclusive widget (OLIT), 156 execl, 126 Explicit grab, 41 Expose event(s), 33, 35,41,313, 324 Fallback (resources), 74, 75, 78 File and Pipe Input, 125 File descriptor, 125 Fill patterns, 227 Finding widgets by name, 150 Fixing window size, 160, 161 Focus, 129 Font(s), 231,235 information structure, 236 libraries, 239 names, 239 fields, 240 Foreground color, 17,217,235 fork, 126 Form Widget Athena, 177 Motif. 180 Frame buffer, 16 Gadgets, 148,210 GC: see Graphics Context Geometry requests, 151 resource, 73 get time, 124

11 INDEX 371 Graphical front end, 125, 126 Graphical user interfaces, 3 Graphics Context (GC), 5, 42, 217, 220, 225, 236, 306, 308, 326 Graphics Context Cache, 220, 225 GraphicsExpose, 42 Gravity, 35 GUIs: see Graphical user interfaces Handles, 18 Hints, 39 Hot spot (of cursor), 235 ICCCM: see Inter-Client Communication Conventions Manual lcon(s), 231 file format, 231 Iconified window, 231 Image Popups, 166 Selections, 294 specification for button widgets, 144 structure, X client side, 268 Implicit grab, 41 Input Focus, 129, 199 assigning to sub-windows, 199 Athena, OLIT, 129 keyboard, 41 Motif, 129 Input Hint, 39 Input modality (for popups), 164 Instance record, , 317, 318, 324 Inter-Client Communication, 61, 283 Conventions Manual (ICCCM), 7, 57, 284 Imerrupt-driven programming, 3 Intrinsics, 97, 122 Keyboard, 45, 128, 130, 131, 199 events, 129, 130 focus, 316 KeyPress, 41 KeyRelease, 41 keysym, 130 Label Widget Class, 141 Layout policy, 151 Limiting window resizing, 160, 161 Managed widgets/children, 68, 138 Mapped widgets, 138 Mapping of a string into an atom, 37 Marking Selections, 296 by blinking, 296 by reverse video, 296 Menu(s) accelerators, 131 bar, 188 example of visible, 152 transient, 188 Message box, 209, 210 Message driven programs, 3 Modal, input, 42 popup, 210 programs, 42 Modified event (in translation table), 109 Motif, 7, 36, 40, 61, 71, 129, 138, 147, 148 Primitive widget class, 335 Slider widget class, 335 MotionNotif y, 41 NoExpose, 42 Non-Rectangular Windows, 244 Non-blocking function, 31 Objects, 148 OLIT, 7, 40, 61,71, 138, 147, 148 Overlay, 258, with tiling pixmaps, 275 Override shell, 159 Paned widgets, 176 Paper class widget, 98, 169 Parsing the command line for resources, 71 Pipes, 125 Pixel planes, 258, 259 Pixmap, 218, 267, 270, 293 background for window, 227 of depth one, 228 Placing Text Labels in a Drawing, 205 Plane allocation, 272 Pointer, 54 Polygon Plotting, 227, 228 Popup, 205 Menu(s), 147, 148, 188 Athena, 189 Motif, 189 OLIT, 192 widget, 183 shell placement, 206 Widget(s), 64, 159, 164 windows with modal input, 42 Primary selection, 287 Private definition file, 308, 309, 311 Properties, 34, 36, 39 types, 37 Public definition file, 309, 310, 311, 317

12 372 FUNDAMENTALS OF X PROGRAMMING Pulldown menus, 147, 148, 188 Motif, 190 OLIT, 192 Quarks, 83 Radio box. 145, 156 Redrawing function, 35 Refresh memory, 16, 29, 45 Regions, 217, 241 operations on, 242 Registration with the Intrinsics, 97 Reparenting, 227 by window manager, 46 Reparenting obligations, 46 Resizing, 36 ofchild window through parent resizing, 177, 180 initiated by child widget, 176 Resource(s), 11, 67, 68, 305, 318, 324, 326 array, 81 command line arguments, 69 conversion, 80, 85, 255 definition, concept, 79 files, 69 priorities, 78 risks associated with, 69 table, 175 values, 64 through the Command Line, 71 RESOURCE_MANAGER property, 68, 78, 92 Root window, Row-Column widget (Motif), 152, 156 Rubber Band Drawing Program, Rubber Tile Widget Class (OLIT), 183 Screen, 17, 29 Scrollbar, 184, 187 Scrolled Windows, 184 Selection(s), 199,283 alternatives to, 296 of integer data, 291 loss, 285 with more than one type, 293 ownership, 285 type, 287, 290 send_event, 32 Sensitivity, 155 of cascade buttons, 193 Serial number of event, 32 Server, 5, 283, 27 backup, 36 Shape extension of X, 244 Shell (widget class), 61, 137, 138, 159 resources, 67 top level, 159 transient, 159 Simple widget. 137 Simplifying X, 13 Slider Widget class, Spring loaded popup, Spy program (for window properties), 40, 49 Starter Toolkit, 14,40,98,218 Straight line segment drawing, 225 String specification in Motif, 142 StructureNotifyMask, 42 Subclass, widget, 61 Superclass inheritence, 308 Syntax of Resource Lines, 75 Syntax of Translation Tables, 108 Text Entry, 130 field, 203, 204 Text height, estimation of, 238 Text Widgets, Athena, 200 Motif, 201 OLIT. 202 Text width, estimation of, 238 Timeouts, 122, 123 advantages of, Animation using, 122 prototype of function, 122 Timers. 122 Tk,6, 40 Toggle Widgets, 144 Toolkit, 6 Translation table. 98, 104, 105, 109, 110, , 115 Translations,11 Transparent windows, 227 Two way pipe, 126, 127 type, event union member, 31, 32 Unix, 126 Unmanaged children, 138 Unmapped widgets, 138 User data, 203, 327 User driven programs, 3 User Interface for Selections, 298 varargs routines, 65 Video look-up table, 16, 45, 251 visual type, 261 Visuals,

13 INDEX 373 WhitePixel, 28 Widget, 7, 12,32,61 class, 61 derivation, 61 hierarchy, 61, 62 enabling, 149, 155 forest, 161 geometry, 150 Instances, 62 Management, 67 Mapping, 67 Radio group (Athena), 156 Realization, 67 Sensitivity, 149 Spy, 139 Structure, Tree, 62, 139, 140, 161, 162 Wildcarding, 77 Difference between resource and Unix shell, 78 Window, 218 attributes, 29 creation, 30 gravity, 36 layout specification, 176 manager, 5, 30, 37,41, 44, 45, 46, 54, 61, 129, 130, 137, 159, 187,199,227,231,265,283 interaction with, 47 messages, 114 reparenting, 54 mapping, 30, 45 properties, 283, 29 resizing, effect of on subwindow layout, 176 type, 18 X versus Microsoft, 7 WM_CLIENT_MACHINE property, 38, 40 WM_DELETE_WINDOW property, 47 WM_NAME property, 36, 37, 40 WM_PROTOCOLS property, 40, 47 Work Procedures, animation using, 117 X protocol, 5, 46 X Toolkit (Xt), 6, 8, 36, 38, XAllocColor, , 261 XAllocColorCells, 258, 259, 261, 273 XAllocColors, 254, XAnyEvent, event union member, 31, 32 XChangeGC, 222 XChangeWindowAttributes, 34 XClearArea, 225 xclient, event union member, 48, 49 XCloseDisplay, 27 XColor structure, , 259 XCopyArea, 219, 270 XCopyGC, 221,222 XCopyPlane, 228,277 XCreateBitmapFromData, 232, 233, 234 XCreateColormap, 265 XCreateFontCursor, 239 XCreateGC, 220, 221,222 XCreate lmage, 269, 271 XCreatePixmapCursor, 234, 235 XCreatePixmap, 219 XCreateRegion, 242 XCreateSimpleWindow, XDef inecursor, 235, 239 XDrawArc, 225, 226 XDrawImageString, 238 XDrawLines, 227 XDrawline, 225 XDrawString, 238 XENVIRONMENT, 78 XEvent, xexpose, event union member, 33 XFillArc, 226 XFillPolygon, 230 XFlush, 30 XFreeGC, 221 XFreePixmap, 219, 235 XFree, 270 XGContextFromGC, 237 XGCValues, 220 XGetAtomName, 56 XGetGCValues, 223, 225 XGetVisualInfo, 263, 264 XGetWindowProperty, 92 XGetWMHints, 39 XGetWMName, 38 XGrabPointer, 55 XID, 18 selections, 293 xinit,46 XlnternAtom, 37, 115, 116, 287 Xlib, 5, 46 XListFonts, 240, 241 XListProperties, 56 XLoadQueryFont, 237, 240 XMatchVisualInfo, 264 XNextEvent, 31, 47 XOpenDisplay, 27 XParseColor, 255 XPointInRegion, 243 XPolygon Region, 241 XPut Image, 270 XQueryColors, 256, 259 XQueryFont, 237 XQueryPointer, 51, 54 XReadBitmapFile, 232, 233 XRecolorCursor, 239 XrmOptionDescRec,73

14 374 FUNDAMENTALS OF X PROGRAMMING XrmQuarkToString, 83 XrmStringToQuark, 83 XSelectlnput, 18, 31, 42 XSendEvent, 47 XSetFillStyle, 276 XSetFont, 237 XSetPlaneMask, 272, 273 XSetRegion, 242 XSetTile, 276 XSetWindowAttributes,34 XSetWMHints, 39 XSetWMName, 38 XSetWMProtocols, 47, 115, 116 XStoreColors, 254 XStoreColor, 254, 259, 261 XStorseColor, 265 XSublmage, 270 Xt: see X Toolkit XtAddCallback, 101 XtAddEventHandler, 99, 112 XtAddWorkProc, 117 XtAppAddActions, 104, 113 XtAppAddlnput, 125 XtAppAddTimeOut, 122, 124, 125 XtAppAddWorkProc, 119, 153 XtAppContext, 70 XtAppInitialize, 65, 70 XLAppMainLoop, 70, 97 XtAppNextEvent,97 XtConvertAndStore, 88 XtCreateManagedWidget, 64 XtDisownSelection, 299 XtDispatchEvent,97 XTextWidth, 238 XtGetConstraintResourceList, 90 XtGetResourceList, 89 XtGetSelectionValue, 285, 287, 289, 290, 293, 294 XtManageChild, 138 XtMapWidget, 139 XtNameToWidget,150, 164 XtNextEvent, 123 XtNumber, 104 XtOffsetOf, 81 XtOpenDisplay, 161 XtOwnSelection, , 293 XtParent, 139 XtPopdown, 164, 165 XtPopup, 164, 165 XtRealizeWidget,68, 138 XtRemoveAllCallbacks, 103 XtRemoveCallback, 103 XtRemoveEventHandler, 99 XtResourceList, 84 XtRosource, 81, 84 XtSetKeyboardFocus, 199 XtUnmapWidget,139 XtVaAppCreateShell, 161, 162 XtVaAppInitialize, 65, 72 XtVaCreateManagedWidget, 64 XtVaGetApplicationResources, 82, 84 XtVaGetValues,65 XtVaSetValues, 65 XtVaTypedArg, 66 XtWidgetToApplicationContext, 119 XUngrabPointer, 55