+.NH 2
+User Preference Subroutines
+.PP
+.IN "Keyboard" "Bell Volume"
+.IN "Keyboard" "Keyclick Volume"
+.IN "Mouse" "Programming"
+In this category are the user preference options of bell, keyclick,
+mouse behavior, etc.
+The default values for many of these functions are determined by
+.IN "File" "/etc/ttys"
+command line arguments to the X server, typically set in \fI/etc/ttys\fP.
+Not all implementations will actually be able to control all of these
+parameters.
+.FD
+.IN "Definitions" "XMouseControl"
+.IN "XMouseControl"
+.IN "Mouse" "Behavior"
+XMouseControl (acceleration, threshold)
+ int acceleration, threshold;
+.FN
+Defines how the mouse moves.
+The \fIacceleration\fP is a multiplier for movement.
+For example,
+specifying 3 means the cursor moves three times as fast as the mouse.
+Acceleration only takes effect if the mouse moves more than
+threshold pixels at once,
+and only applies to the amount beyond the \fIthreshold\fP.
+.FD
+.IN "Definitions" "XFeepControl"
+.IN "XFeepControl"
+XFeepControl (volume)
+ int volume; /* 0 to 7 */
+.FN
+Defines the base volume for \fIXFeep\fP request.
+The volume is in the range
+0 to 7, with 7 the loudest.
+.FD
+.IN "Definitions" "XFeep"
+.IN "XFeep"
+XFeep (volume)
+ int volume; /* -7 to 7 */
+.FN
+\fIXFeep\fP rings a bell on the display.
+The
+sound \fIvolume\fP is in the range -7 to 7
+and is added to the base \fIvolume\fP defined by \fIXFeepControl\fP.
+.FD
+.IN "Definitions" "XKeyClickControl"
+.IN "XKeyClickControl"
+XKeyClickControl (volume)
+ int volume; /* 0 to 8 */
+.FN
+\fIXKeyClick\fP controls the volume of the `click' that the keyboard makes
+when a key is pressed.
+0 is `off', 8 is the loudest \fIvolume\fP.
+.FD
+.IN "Keyboard" "Auto-Repeat"
+.IN "Definitions" "XAutoRepeatOn"
+.IN "Definitions" "XAutoRepeatOff"
+.IN "XAutoRepeatOn"
+.IN "XAutoRepeatOff"
+XAutoRepeatOn ()
+
+XAutoRepeatOff ()
+.FN
+\fIXAutoRepeatOn\fP turns the keyboard's auto-repeat on.
+\fIXAutoRepeatOff\fP turns the keyboard's auto-repeat off.
+.FD
+.IN "Keyboard" "Lock Key"
+.IN "Definitions" "XLockUpDown"
+.IN "XLockUpDown"
+.IN "Definitions" "XLockToggle"
+.IN "XLockToggle"
+XLockUpDown ()
+
+XLockToggle ()
+.FN
+Some people hate the behavior of the shift lock key.
+These subroutines change the mode of the Shift LOCK key on the keyboard.
+When the keyboard is in \fILockUpDown\fP mode,
+KeyPressed and KeyReleased events are sent as for any other key, and the
+ShiftLockMask sent in events gives the current state of the key.
+.IN "KeyPressed Events"
+In \fILockToggle\fP mode,
+\fIKeyPressed\fP and \fIKeyReleased\fP events are never sent
+for the Lock key,
+and the state of the \fIShiftLockMask\fP sent in events is toggled on every
+press of the LOCK key.
+.FD
+.IN "Screen Saver"
+.IN "Definitions" "XScreenSaver"
+.IN "XScreenSaver"
+XScreenSaver (savetimeout, patterntimeout, video)
+ int savetimeout, patterntimeout; /* in minutes */
+ int video;
+.FN
+If the server remains idle for the specified number of minutes,
+the server will blank the screen, usually with a pattern that changes at the
+specified rate.
+The screen state will typically be restored when the next request or input
+event occurs, unless the server was out of memory, in which case exposure
+events to all mapped windows are generated.
+If \fIvideo\fP is non-zero, the server will attempt to disable the video to
+implement the screen saver, rather than change to the background
+grey.
+.FD
+.IN "XGetDefault"
+.IN "Definitions" "XGetDefault"
+.IN "Default Options"
+char *XGetDefault(program, name)
+ char *program; /* usually name of program */
+ char *name;
+.FN
+The number of options that a program may need can be very large in the X
+environment.
+(Fonts of various sorts, colors of characters, mouse, background, text,
+cursor, etc.)
+If only command line options could be used to specify each of these,
+things quickly become unmanageable as your tastes in windows will often
+be drastically different from someone else's.
+.PP
+\fIXGetDefault\fP
+makes it easy to find out what the user wants for his favorite
+font, colors, etc.
+Its use is highly encouraged.
+.PP
+\fIXGetDefault\fP will return NULL if no option of the specified name exists for
+the program.
+Defaults are read out of a file called
+.IN "File" "$HOME/.Xdefaults"
+\fI~/.Xdefaults\fP in the user's home directory.
+See the X manual page
+for details of its format.
+.PP
+The strings returned by \fIXGetDefault\fP are owned by Xlib and should not
+be modified or freed by the client.
+.FD
+.IN "XParseGeometry"
+.IN "Definitions" "XParseGeometry"
+.IN "Window" "Initial Location"
+int XParseGeometry (string, x, y, width, height)
+ char *string;
+ int *x, *y, *width, *height; /* RETURN */
+.FN
+By convention,
+X applications use a standard string to indicate window size and placement.
+This subroutine makes it easy to conform to this standard.
+It is not normally used by user programs, which typically use
+.IN "XCreate"
+.IN "XCreateTerm"
+the \fIXCreate\fP or \fIXCreateTerm\fP subroutines to create the window.
+This subroutine is used to parse strings of form
+\fI=<width>x<height>{+-}<xoffset>{+-}<yoffset>\fP where
+width, height, xoffset and yoffset are returned in the \fIwidth\fP,
+\fIheight\fP, \fIx\fP and \fIy\fP arguments.
+It returns a bitmask that indicates which of the four values were
+actually found in the string, and whether the x and y values
+are negative (remember, -0 is not equal +0 in this system!).
+For each value found, the corresponding argument is updated;
+for each value not found, the argument is left unchanged.
+The bits are \fIXValue\fP, \fIYValue\fP, \fIWidthValue\fP, \fIHeightValue\fP,
+\fIXNegative\fP, \fIYNegative\fP, and are defined in \fI<X/Xlib.h>\fP.
+.IN "File" "<X/Xlib.h>
+They will be set whenever one of the values are defined or signs
+are set.
+.FD
+.IN "XGeometry"
+.IN "Definitions" "Geometry"
+.IN "Window" "Initial Location"
+.IN "Window" "Computing Placement"
+int XGeometry (position, default, bwidth, fwidth, fheight, xadd, yadd, x, y, width, height)
+ char *position, default; /* geometry specs */
+ int bwidth; /* border width */
+ int fwidth, fheight; /* size of units of width and height spec */
+ int xadd, yadd; /* any additional interior space */
+ int *x, *y, *width, *height; /* RETURN */
+.FN
+This routine does all the work required to determine the placement of
+a window using the current format to position windows.
+Given a fully qualified default geometry specification and a (possibly)
+incompletely specified geometry specification, it will return a bitmask
+value as defined above in the \fIXParseGeometry\fP call.
+It is not normally used by user programs, which typically use
+.IN "XCreate"
+.IN "XCreateTerm"
+the \fIXCreate\fP or \fIXCreateTerm\fP subroutines to create the window.
+The position the window should be placed will be returned in the
+x, y, width, and height arguments.
+If either the function returns the \fIXValue\fP or \fIYValue\fP flag,
+you should
+place the window at the requested position.
+The border width (\fIbwidth\fP),
+size of the increments \fIfwidth\fP and \fIfheight\fP
+(typically font width and height),
+and any additional interior space (\fIxadd\fP and \fIyadd\fP)
+are passed in to make it easy to compute the resulting size.
+.FD
+.IN "XReadBitmapFile"
+.IN "Definitions" "Bitmap file format"
+.IN "Definitions" "XReadBitmapFile"
+Status XReadBitmapFile (filename, width, height, data, x_hot, y_hot)
+ char *filename;
+ int *width, *height; /* RETURN; must be non-NULL */
+ short **data; /* RETURN */
+ int *x_hot, *y_hot; /* RETURN; may be NULL */
+.FN
+\fIXReadBitmapFile\fP reads a file produced by the
+.I bitmap(1)
+program. The format of that file is described in the man page for
+that program.
+.PP
+If the cannot be opened, \fIXReadBitmapFile\fP returns a Status of 0. If the
+file can be opened but is not syntactically valid, the procedure returns
+a negative Status. If the file is readable and valid, it returns a Status of 1.
+.PP
+\fIXReadBitmapFile\fP assigns the bitmap's \fIheight\fP and \fIwidth\fP,
+as read from the file,
+to the caller's variables
+\fIwidth\fP
+and
+\fIheight\fP.
+It then allocates an appropriate
+amount of storage, reads the bitmap data from the file, and assigns to the
+caller's variable
+.I data.
+The caller must free
+.I data
+when he is done with it.
+.PP
+If
+.I x_hot
+and
+.I y_hot
+are non-NULL, then \fIXReadBitmapFile\fP will set
+.I *x_hot
+and
+.I *y_hot
+to the value of the hot spot as defined in the file. If no hot spot is
+defined, \fIXReadBitmapFile\fP will set
+.I *x_hot
+and
+.I *y_hot
+to -1.
+
projects / unix-history / commitdiff