From b567a3027bceabc0f1f42dd162268f06f15e8149 Mon Sep 17 00:00:00 2001 From: marha Date: Sun, 18 Oct 2009 12:07:02 +0000 Subject: Updated following packages: libX11-1.3.1 xtrans-1.2.5 --- libX11/specs/Makefile.am | 3 + libX11/specs/Makefile.in | 618 ++++ libX11/specs/XIM/Makefile.am | 33 + libX11/specs/XIM/Makefile.in | 554 +++ libX11/specs/XIM/xim.ms | 4279 ++++++++++++++++++++++ libX11/specs/i18n/Framework.ms | 1567 ++++++++ libX11/specs/i18n/LocaleDB.ms | 502 +++ libX11/specs/i18n/Makefile.am | 33 + libX11/specs/i18n/Makefile.in | 554 +++ libX11/specs/i18n/Trans.ms | 1148 ++++++ libX11/specs/libX11/AppA | 604 +++ libX11/specs/libX11/AppB | 101 + libX11/specs/libX11/AppC | 2230 ++++++++++++ libX11/specs/libX11/AppD | 1183 ++++++ libX11/specs/libX11/CH01 | 663 ++++ libX11/specs/libX11/CH02 | 2052 +++++++++++ libX11/specs/libX11/CH03 | 3121 ++++++++++++++++ libX11/specs/libX11/CH04 | 1595 ++++++++ libX11/specs/libX11/CH05 | 518 +++ libX11/specs/libX11/CH06 | 4773 ++++++++++++++++++++++++ libX11/specs/libX11/CH07 | 2357 ++++++++++++ libX11/specs/libX11/CH08 | 3468 ++++++++++++++++++ libX11/specs/libX11/CH09 | 1290 +++++++ libX11/specs/libX11/CH10 | 3886 ++++++++++++++++++++ libX11/specs/libX11/CH11 | 1664 +++++++++ libX11/specs/libX11/CH12 | 2680 ++++++++++++++ libX11/specs/libX11/CH13 | 7673 +++++++++++++++++++++++++++++++++++++++ libX11/specs/libX11/CH14 | 3590 ++++++++++++++++++ libX11/specs/libX11/CH15 | 1628 +++++++++ libX11/specs/libX11/CH16 | 2364 ++++++++++++ libX11/specs/libX11/Makefile.am | 62 + libX11/specs/libX11/Makefile.in | 580 +++ libX11/specs/libX11/abstract.t | 106 + libX11/specs/libX11/credits.t | 216 ++ libX11/specs/libX11/glossary | 1484 ++++++++ libX11/specs/libX11/libX11.ms | 24 + libX11/specs/libX11/postproc | 17 + libX11/specs/macros.t | 226 ++ libX11/specs/troffrules.in | 68 + 39 files changed, 59514 insertions(+) create mode 100644 libX11/specs/Makefile.am create mode 100644 libX11/specs/Makefile.in create mode 100644 libX11/specs/XIM/Makefile.am create mode 100644 libX11/specs/XIM/Makefile.in create mode 100644 libX11/specs/XIM/xim.ms create mode 100644 libX11/specs/i18n/Framework.ms create mode 100644 libX11/specs/i18n/LocaleDB.ms create mode 100644 libX11/specs/i18n/Makefile.am create mode 100644 libX11/specs/i18n/Makefile.in create mode 100644 libX11/specs/i18n/Trans.ms create mode 100644 libX11/specs/libX11/AppA create mode 100644 libX11/specs/libX11/AppB create mode 100644 libX11/specs/libX11/AppC create mode 100644 libX11/specs/libX11/AppD create mode 100644 libX11/specs/libX11/CH01 create mode 100644 libX11/specs/libX11/CH02 create mode 100644 libX11/specs/libX11/CH03 create mode 100644 libX11/specs/libX11/CH04 create mode 100644 libX11/specs/libX11/CH05 create mode 100644 libX11/specs/libX11/CH06 create mode 100644 libX11/specs/libX11/CH07 create mode 100644 libX11/specs/libX11/CH08 create mode 100644 libX11/specs/libX11/CH09 create mode 100644 libX11/specs/libX11/CH10 create mode 100644 libX11/specs/libX11/CH11 create mode 100644 libX11/specs/libX11/CH12 create mode 100644 libX11/specs/libX11/CH13 create mode 100644 libX11/specs/libX11/CH14 create mode 100644 libX11/specs/libX11/CH15 create mode 100644 libX11/specs/libX11/CH16 create mode 100644 libX11/specs/libX11/Makefile.am create mode 100644 libX11/specs/libX11/Makefile.in create mode 100644 libX11/specs/libX11/abstract.t create mode 100644 libX11/specs/libX11/credits.t create mode 100644 libX11/specs/libX11/glossary create mode 100644 libX11/specs/libX11/libX11.ms create mode 100644 libX11/specs/libX11/postproc create mode 100644 libX11/specs/macros.t create mode 100644 libX11/specs/troffrules.in (limited to 'libX11/specs') diff --git a/libX11/specs/Makefile.am b/libX11/specs/Makefile.am new file mode 100644 index 000000000..4a51cae70 --- /dev/null +++ b/libX11/specs/Makefile.am @@ -0,0 +1,3 @@ +SUBDIRS=libX11 i18n XIM + +EXTRA_DIST=troffrules.in macros.t diff --git a/libX11/specs/Makefile.in b/libX11/specs/Makefile.in new file mode 100644 index 000000000..1b38734f6 --- /dev/null +++ b/libX11/specs/Makefile.in @@ -0,0 +1,618 @@ +# Makefile.in generated by automake 1.11 from Makefile.am. +# @configure_input@ + +# Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, +# 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, +# Inc. +# This Makefile.in is free software; the Free Software Foundation +# gives unlimited permission to copy and/or distribute it, +# with or without modifications, as long as this notice is preserved. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY, to the extent permitted by law; without +# even the implied warranty of MERCHANTABILITY or FITNESS FOR A +# PARTICULAR PURPOSE. + +@SET_MAKE@ +VPATH = @srcdir@ +pkgdatadir = $(datadir)/@PACKAGE@ +pkgincludedir = $(includedir)/@PACKAGE@ +pkglibdir = $(libdir)/@PACKAGE@ +pkglibexecdir = $(libexecdir)/@PACKAGE@ +am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd +install_sh_DATA = $(install_sh) -c -m 644 +install_sh_PROGRAM = $(install_sh) -c +install_sh_SCRIPT = $(install_sh) -c +INSTALL_HEADER = $(INSTALL_DATA) +transform = $(program_transform_name) +NORMAL_INSTALL = : +PRE_INSTALL = : +POST_INSTALL = : +NORMAL_UNINSTALL = : +PRE_UNINSTALL = : +POST_UNINSTALL = : +build_triplet = @build@ +host_triplet = @host@ +subdir = specs +DIST_COMMON = $(srcdir)/Makefile.am $(srcdir)/Makefile.in +ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 +am__aclocal_m4_deps = $(top_srcdir)/acinclude.m4 \ + $(top_srcdir)/configure.ac +am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ + $(ACLOCAL_M4) +mkinstalldirs = $(install_sh) -d +CONFIG_HEADER = $(top_builddir)/src/config.h \ + $(top_builddir)/include/X11/XlibConf.h +CONFIG_CLEAN_FILES = +CONFIG_CLEAN_VPATH_FILES = +AM_V_GEN = $(am__v_GEN_$(V)) +am__v_GEN_ = $(am__v_GEN_$(AM_DEFAULT_VERBOSITY)) +am__v_GEN_0 = @echo " GEN " $@; +AM_V_at = $(am__v_at_$(V)) +am__v_at_ = $(am__v_at_$(AM_DEFAULT_VERBOSITY)) +am__v_at_0 = @ +SOURCES = +DIST_SOURCES = +RECURSIVE_TARGETS = all-recursive check-recursive dvi-recursive \ + html-recursive info-recursive install-data-recursive \ + install-dvi-recursive install-exec-recursive \ + install-html-recursive install-info-recursive \ + install-pdf-recursive install-ps-recursive install-recursive \ + installcheck-recursive installdirs-recursive pdf-recursive \ + ps-recursive uninstall-recursive +RECURSIVE_CLEAN_TARGETS = mostlyclean-recursive clean-recursive \ + distclean-recursive maintainer-clean-recursive +AM_RECURSIVE_TARGETS = $(RECURSIVE_TARGETS:-recursive=) \ + $(RECURSIVE_CLEAN_TARGETS:-recursive=) tags TAGS ctags CTAGS \ + distdir +ETAGS = etags +CTAGS = ctags +DIST_SUBDIRS = $(SUBDIRS) +DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) +am__relativize = \ + dir0=`pwd`; \ + sed_first='s,^\([^/]*\)/.*$$,\1,'; \ + sed_rest='s,^[^/]*/*,,'; \ + sed_last='s,^.*/\([^/]*\)$$,\1,'; \ + sed_butlast='s,/*[^/]*$$,,'; \ + while test -n "$$dir1"; do \ + first=`echo "$$dir1" | sed -e "$$sed_first"`; \ + if test "$$first" != "."; then \ + if test "$$first" = ".."; then \ + dir2=`echo "$$dir0" | sed -e "$$sed_last"`/"$$dir2"; \ + dir0=`echo "$$dir0" | sed -e "$$sed_butlast"`; \ + else \ + first2=`echo "$$dir2" | sed -e "$$sed_first"`; \ + if test "$$first2" = "$$first"; then \ + dir2=`echo "$$dir2" | sed -e "$$sed_rest"`; \ + else \ + dir2="../$$dir2"; \ + fi; \ + dir0="$$dir0"/"$$first"; \ + fi; \ + fi; \ + dir1=`echo "$$dir1" | sed -e "$$sed_rest"`; \ + done; \ + reldir="$$dir2" +ACLOCAL = @ACLOCAL@ +ADMIN_MAN_DIR = @ADMIN_MAN_DIR@ +ADMIN_MAN_SUFFIX = @ADMIN_MAN_SUFFIX@ +AMTAR = @AMTAR@ +AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@ +APP_MAN_DIR = @APP_MAN_DIR@ +APP_MAN_SUFFIX = @APP_MAN_SUFFIX@ +AR = @AR@ +AUTOCONF = @AUTOCONF@ +AUTOHEADER = @AUTOHEADER@ +AUTOMAKE = @AUTOMAKE@ +AWK = @AWK@ +BIGFONT_CFLAGS = @BIGFONT_CFLAGS@ +BIGFONT_LIBS = @BIGFONT_LIBS@ +CC = @CC@ +CCDEPMODE = @CCDEPMODE@ +CC_FOR_BUILD = @CC_FOR_BUILD@ +CFLAGS = @CFLAGS@ +CHANGELOG_CMD = @CHANGELOG_CMD@ +CPP = @CPP@ +CPPFLAGS = @CPPFLAGS@ +CWARNFLAGS = @CWARNFLAGS@ +CXX = @CXX@ +CXXCPP = @CXXCPP@ +CXXDEPMODE = @CXXDEPMODE@ +CXXFLAGS = @CXXFLAGS@ +CYGPATH_W = @CYGPATH_W@ +DEFS = @DEFS@ +DEPDIR = @DEPDIR@ +DOLT_BASH = @DOLT_BASH@ +DRIVER_MAN_DIR = @DRIVER_MAN_DIR@ +DRIVER_MAN_SUFFIX = @DRIVER_MAN_SUFFIX@ +DSYMUTIL = @DSYMUTIL@ +ECHO = @ECHO@ +ECHO_C = @ECHO_C@ +ECHO_N = @ECHO_N@ +ECHO_T = @ECHO_T@ +EGREP = @EGREP@ +EXEEXT = @EXEEXT@ +F77 = @F77@ +FFLAGS = @FFLAGS@ +FILE_MAN_DIR = @FILE_MAN_DIR@ +FILE_MAN_SUFFIX = @FILE_MAN_SUFFIX@ +GREP = @GREP@ +GROFF = @GROFF@ +I18N_MODULE_LIBS = @I18N_MODULE_LIBS@ +INSTALL = @INSTALL@ +INSTALL_DATA = @INSTALL_DATA@ +INSTALL_PROGRAM = @INSTALL_PROGRAM@ +INSTALL_SCRIPT = @INSTALL_SCRIPT@ +INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@ +KEYSYMDEF = @KEYSYMDEF@ +LAUNCHD = @LAUNCHD@ +LDFLAGS = @LDFLAGS@ +LIBOBJS = @LIBOBJS@ +LIBS = @LIBS@ +LIBTOOL = @LIBTOOL@ +LIB_MAN_DIR = @LIB_MAN_DIR@ +LIB_MAN_SUFFIX = @LIB_MAN_SUFFIX@ +LINT = @LINT@ +LINTLIB = @LINTLIB@ +LINT_FLAGS = @LINT_FLAGS@ +LN_S = @LN_S@ +LTCOMPILE = @LTCOMPILE@ +LTCXXCOMPILE = @LTCXXCOMPILE@ +LTLIBOBJS = @LTLIBOBJS@ +MAINT = @MAINT@ +MAKEINFO = @MAKEINFO@ +MALLOC_ZERO_CFLAGS = @MALLOC_ZERO_CFLAGS@ +MISC_MAN_DIR = @MISC_MAN_DIR@ +MISC_MAN_SUFFIX = @MISC_MAN_SUFFIX@ +MKDIR_P = @MKDIR_P@ +NMEDIT = @NMEDIT@ +OBJEXT = @OBJEXT@ +PACKAGE = @PACKAGE@ +PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@ +PACKAGE_NAME = @PACKAGE_NAME@ +PACKAGE_STRING = @PACKAGE_STRING@ +PACKAGE_TARNAME = @PACKAGE_TARNAME@ +PACKAGE_VERSION = @PACKAGE_VERSION@ +PATH_SEPARATOR = @PATH_SEPARATOR@ +PERL = @PERL@ +PKG_CONFIG = @PKG_CONFIG@ +PS2PDF = @PS2PDF@ +RANLIB = @RANLIB@ +RAWCPP = @RAWCPP@ +RAWCPPFLAGS = @RAWCPPFLAGS@ +SED = @SED@ +SET_MAKE = @SET_MAKE@ +SHELL = @SHELL@ +STRIP = @STRIP@ +VERSION = @VERSION@ +WCHAR32 = @WCHAR32@ +X11_CFLAGS = @X11_CFLAGS@ +X11_DATADIR = @X11_DATADIR@ +X11_EXTRA_DEPS = @X11_EXTRA_DEPS@ +X11_LIBDIR = @X11_LIBDIR@ +X11_LIBS = @X11_LIBS@ +X11_LOCALEDATADIR = @X11_LOCALEDATADIR@ +X11_LOCALEDIR = @X11_LOCALEDIR@ +X11_LOCALELIBDIR = @X11_LOCALELIBDIR@ +XDMCP_CFLAGS = @XDMCP_CFLAGS@ +XDMCP_LIBS = @XDMCP_LIBS@ +XERRORDB = @XERRORDB@ +XKBPROTO_CFLAGS = @XKBPROTO_CFLAGS@ +XKBPROTO_LIBS = @XKBPROTO_LIBS@ +XKBPROTO_REQUIRES = @XKBPROTO_REQUIRES@ +XKEYSYMDB = @XKEYSYMDB@ +XLOCALEDATADIR = @XLOCALEDATADIR@ +XLOCALEDIR = @XLOCALEDIR@ +XLOCALELIBDIR = @XLOCALELIBDIR@ +XMALLOC_ZERO_CFLAGS = @XMALLOC_ZERO_CFLAGS@ +XPROTO_CFLAGS = @XPROTO_CFLAGS@ +XPROTO_LIBS = @XPROTO_LIBS@ +XTHREADLIB = @XTHREADLIB@ +XTHREAD_CFLAGS = @XTHREAD_CFLAGS@ +XTMALLOC_ZERO_CFLAGS = @XTMALLOC_ZERO_CFLAGS@ +abs_builddir = @abs_builddir@ +abs_srcdir = @abs_srcdir@ +abs_top_builddir = @abs_top_builddir@ +abs_top_srcdir = @abs_top_srcdir@ +ac_ct_CC = @ac_ct_CC@ +ac_ct_CXX = @ac_ct_CXX@ +ac_ct_F77 = @ac_ct_F77@ +am__include = @am__include@ +am__leading_dot = @am__leading_dot@ +am__quote = @am__quote@ +am__tar = @am__tar@ +am__untar = @am__untar@ +bindir = @bindir@ +build = @build@ +build_alias = @build_alias@ +build_cpu = @build_cpu@ +build_os = @build_os@ +build_vendor = @build_vendor@ +builddir = @builddir@ +datadir = @datadir@ +datarootdir = @datarootdir@ +distcleancheck_listfiles = @distcleancheck_listfiles@ +docdir = @docdir@ +dvidir = @dvidir@ +exec_prefix = @exec_prefix@ +host = @host@ +host_alias = @host_alias@ +host_cpu = @host_cpu@ +host_os = @host_os@ +host_vendor = @host_vendor@ +htmldir = @htmldir@ +includedir = @includedir@ +infodir = @infodir@ +install_sh = @install_sh@ +libdir = @libdir@ +libexecdir = @libexecdir@ +localedir = @localedir@ +localstatedir = @localstatedir@ +mandir = @mandir@ +mkdir_p = @mkdir_p@ +oldincludedir = @oldincludedir@ +pdfdir = @pdfdir@ +prefix = @prefix@ +program_transform_name = @program_transform_name@ +psdir = @psdir@ +sbindir = @sbindir@ +sharedstatedir = @sharedstatedir@ +srcdir = @srcdir@ +sysconfdir = @sysconfdir@ +target_alias = @target_alias@ +top_build_prefix = @top_build_prefix@ +top_builddir = @top_builddir@ +top_srcdir = @top_srcdir@ +SUBDIRS = libX11 i18n XIM +EXTRA_DIST = troffrules.in macros.t +all: all-recursive + +.SUFFIXES: +$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(am__configure_deps) + @for dep in $?; do \ + case '$(am__configure_deps)' in \ + *$$dep*) \ + ( cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh ) \ + && { if test -f $@; then exit 0; else break; fi; }; \ + exit 1;; \ + esac; \ + done; \ + echo ' cd $(top_srcdir) && $(AUTOMAKE) --foreign specs/Makefile'; \ + $(am__cd) $(top_srcdir) && \ + $(AUTOMAKE) --foreign specs/Makefile +.PRECIOUS: Makefile +Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status + @case '$?' in \ + *config.status*) \ + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \ + *) \ + echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \ + cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \ + esac; + +$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh + +$(top_srcdir)/configure: @MAINTAINER_MODE_TRUE@ $(am__configure_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(ACLOCAL_M4): @MAINTAINER_MODE_TRUE@ $(am__aclocal_m4_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(am__aclocal_m4_deps): + +mostlyclean-libtool: + -rm -f *.lo + +clean-libtool: + -rm -rf .libs _libs + +# This directory's subdirectories are mostly independent; you can cd +# into them and run `make' without going through this Makefile. +# To change the values of `make' variables: instead of editing Makefiles, +# (1) if the variable is set in `config.status', edit `config.status' +# (which will cause the Makefiles to be regenerated when you run `make'); +# (2) otherwise, pass the desired values on the `make' command line. +$(RECURSIVE_TARGETS): + @failcom='exit 1'; \ + for f in x $$MAKEFLAGS; do \ + case $$f in \ + *=* | --[!k]*);; \ + *k*) failcom='fail=yes';; \ + esac; \ + done; \ + dot_seen=no; \ + target=`echo $@ | sed s/-recursive//`; \ + list='$(SUBDIRS)'; for subdir in $$list; do \ + echo "Making $$target in $$subdir"; \ + if test "$$subdir" = "."; then \ + dot_seen=yes; \ + local_target="$$target-am"; \ + else \ + local_target="$$target"; \ + fi; \ + ($(am__cd) $$subdir && $(MAKE) $(AM_MAKEFLAGS) $$local_target) \ + || eval $$failcom; \ + done; \ + if test "$$dot_seen" = "no"; then \ + $(MAKE) $(AM_MAKEFLAGS) "$$target-am" || exit 1; \ + fi; test -z "$$fail" + +$(RECURSIVE_CLEAN_TARGETS): + @failcom='exit 1'; \ + for f in x $$MAKEFLAGS; do \ + case $$f in \ + *=* | --[!k]*);; \ + *k*) failcom='fail=yes';; \ + esac; \ + done; \ + dot_seen=no; \ + case "$@" in \ + distclean-* | maintainer-clean-*) list='$(DIST_SUBDIRS)' ;; \ + *) list='$(SUBDIRS)' ;; \ + esac; \ + rev=''; for subdir in $$list; do \ + if test "$$subdir" = "."; then :; else \ + rev="$$subdir $$rev"; \ + fi; \ + done; \ + rev="$$rev ."; \ + target=`echo $@ | sed s/-recursive//`; \ + for subdir in $$rev; do \ + echo "Making $$target in $$subdir"; \ + if test "$$subdir" = "."; then \ + local_target="$$target-am"; \ + else \ + local_target="$$target"; \ + fi; \ + ($(am__cd) $$subdir && $(MAKE) $(AM_MAKEFLAGS) $$local_target) \ + || eval $$failcom; \ + done && test -z "$$fail" +tags-recursive: + list='$(SUBDIRS)'; for subdir in $$list; do \ + test "$$subdir" = . || ($(am__cd) $$subdir && $(MAKE) $(AM_MAKEFLAGS) tags); \ + done +ctags-recursive: + list='$(SUBDIRS)'; for subdir in $$list; do \ + test "$$subdir" = . || ($(am__cd) $$subdir && $(MAKE) $(AM_MAKEFLAGS) ctags); \ + done + +ID: $(HEADERS) $(SOURCES) $(LISP) $(TAGS_FILES) + list='$(SOURCES) $(HEADERS) $(LISP) $(TAGS_FILES)'; \ + unique=`for i in $$list; do \ + if test -f "$$i"; then echo $$i; else echo $(srcdir)/$$i; fi; \ + done | \ + $(AWK) '{ files[$$0] = 1; nonempty = 1; } \ + END { if (nonempty) { for (i in files) print i; }; }'`; \ + mkid -fID $$unique +tags: TAGS + +TAGS: tags-recursive $(HEADERS) $(SOURCES) $(TAGS_DEPENDENCIES) \ + $(TAGS_FILES) $(LISP) + set x; \ + here=`pwd`; \ + if ($(ETAGS) --etags-include --version) >/dev/null 2>&1; then \ + include_option=--etags-include; \ + empty_fix=.; \ + else \ + include_option=--include; \ + empty_fix=; \ + fi; \ + list='$(SUBDIRS)'; for subdir in $$list; do \ + if test "$$subdir" = .; then :; else \ + test ! -f $$subdir/TAGS || \ + set "$$@" "$$include_option=$$here/$$subdir/TAGS"; \ + fi; \ + done; \ + list='$(SOURCES) $(HEADERS) $(LISP) $(TAGS_FILES)'; \ + unique=`for i in $$list; do \ + if test -f "$$i"; then echo $$i; else echo $(srcdir)/$$i; fi; \ + done | \ + $(AWK) '{ files[$$0] = 1; nonempty = 1; } \ + END { if (nonempty) { for (i in files) print i; }; }'`; \ + shift; \ + if test -z "$(ETAGS_ARGS)$$*$$unique"; then :; else \ + test -n "$$unique" || unique=$$empty_fix; \ + if test $$# -gt 0; then \ + $(ETAGS) $(ETAGSFLAGS) $(AM_ETAGSFLAGS) $(ETAGS_ARGS) \ + "$$@" $$unique; \ + else \ + $(ETAGS) $(ETAGSFLAGS) $(AM_ETAGSFLAGS) $(ETAGS_ARGS) \ + $$unique; \ + fi; \ + fi +ctags: CTAGS +CTAGS: ctags-recursive $(HEADERS) $(SOURCES) $(TAGS_DEPENDENCIES) \ + $(TAGS_FILES) $(LISP) + list='$(SOURCES) $(HEADERS) $(LISP) $(TAGS_FILES)'; \ + unique=`for i in $$list; do \ + if test -f "$$i"; then echo $$i; else echo $(srcdir)/$$i; fi; \ + done | \ + $(AWK) '{ files[$$0] = 1; nonempty = 1; } \ + END { if (nonempty) { for (i in files) print i; }; }'`; \ + test -z "$(CTAGS_ARGS)$$unique" \ + || $(CTAGS) $(CTAGSFLAGS) $(AM_CTAGSFLAGS) $(CTAGS_ARGS) \ + $$unique + +GTAGS: + here=`$(am__cd) $(top_builddir) && pwd` \ + && $(am__cd) $(top_srcdir) \ + && gtags -i $(GTAGS_ARGS) "$$here" + +distclean-tags: + -rm -f TAGS ID GTAGS GRTAGS GSYMS GPATH tags + +distdir: $(DISTFILES) + @srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + list='$(DISTFILES)'; \ + dist_files=`for file in $$list; do echo $$file; done | \ + sed -e "s|^$$srcdirstrip/||;t" \ + -e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \ + case $$dist_files in \ + */*) $(MKDIR_P) `echo "$$dist_files" | \ + sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \ + sort -u` ;; \ + esac; \ + for file in $$dist_files; do \ + if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \ + if test -d $$d/$$file; then \ + dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \ + if test -d "$(distdir)/$$file"; then \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ + fi; \ + if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \ + cp -fpR $(srcdir)/$$file "$(distdir)$$dir" || exit 1; \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ + fi; \ + cp -fpR $$d/$$file "$(distdir)$$dir" || exit 1; \ + else \ + test -f "$(distdir)/$$file" \ + || cp -p $$d/$$file "$(distdir)/$$file" \ + || exit 1; \ + fi; \ + done + @list='$(DIST_SUBDIRS)'; for subdir in $$list; do \ + if test "$$subdir" = .; then :; else \ + test -d "$(distdir)/$$subdir" \ + || $(MKDIR_P) "$(distdir)/$$subdir" \ + || exit 1; \ + fi; \ + done + @list='$(DIST_SUBDIRS)'; for subdir in $$list; do \ + if test "$$subdir" = .; then :; else \ + dir1=$$subdir; dir2="$(distdir)/$$subdir"; \ + $(am__relativize); \ + new_distdir=$$reldir; \ + dir1=$$subdir; dir2="$(top_distdir)"; \ + $(am__relativize); \ + new_top_distdir=$$reldir; \ + echo " (cd $$subdir && $(MAKE) $(AM_MAKEFLAGS) top_distdir="$$new_top_distdir" distdir="$$new_distdir" \\"; \ + echo " am__remove_distdir=: am__skip_length_check=: am__skip_mode_fix=: distdir)"; \ + ($(am__cd) $$subdir && \ + $(MAKE) $(AM_MAKEFLAGS) \ + top_distdir="$$new_top_distdir" \ + distdir="$$new_distdir" \ + am__remove_distdir=: \ + am__skip_length_check=: \ + am__skip_mode_fix=: \ + distdir) \ + || exit 1; \ + fi; \ + done +check-am: all-am +check: check-recursive +all-am: Makefile +installdirs: installdirs-recursive +installdirs-am: +install: install-recursive +install-exec: install-exec-recursive +install-data: install-data-recursive +uninstall: uninstall-recursive + +install-am: all-am + @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am + +installcheck: installcheck-recursive +install-strip: + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + `test -z '$(STRIP)' || \ + echo "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'"` install +mostlyclean-generic: + +clean-generic: + +distclean-generic: + -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES) + -test . = "$(srcdir)" || test -z "$(CONFIG_CLEAN_VPATH_FILES)" || rm -f $(CONFIG_CLEAN_VPATH_FILES) + +maintainer-clean-generic: + @echo "This command is intended for maintainers to use" + @echo "it deletes files that may require special tools to rebuild." +clean: clean-recursive + +clean-am: clean-generic clean-libtool mostlyclean-am + +distclean: distclean-recursive + -rm -f Makefile +distclean-am: clean-am distclean-generic distclean-tags + +dvi: dvi-recursive + +dvi-am: + +html: html-recursive + +html-am: + +info: info-recursive + +info-am: + +install-data-am: + +install-dvi: install-dvi-recursive + +install-dvi-am: + +install-exec-am: + +install-html: install-html-recursive + +install-html-am: + +install-info: install-info-recursive + +install-info-am: + +install-man: + +install-pdf: install-pdf-recursive + +install-pdf-am: + +install-ps: install-ps-recursive + +install-ps-am: + +installcheck-am: + +maintainer-clean: maintainer-clean-recursive + -rm -f Makefile +maintainer-clean-am: distclean-am maintainer-clean-generic + +mostlyclean: mostlyclean-recursive + +mostlyclean-am: mostlyclean-generic mostlyclean-libtool + +pdf: pdf-recursive + +pdf-am: + +ps: ps-recursive + +ps-am: + +uninstall-am: + +.MAKE: $(RECURSIVE_CLEAN_TARGETS) $(RECURSIVE_TARGETS) ctags-recursive \ + install-am install-strip tags-recursive + +.PHONY: $(RECURSIVE_CLEAN_TARGETS) $(RECURSIVE_TARGETS) CTAGS GTAGS \ + all all-am check check-am clean clean-generic clean-libtool \ + ctags ctags-recursive distclean distclean-generic \ + distclean-libtool distclean-tags distdir dvi dvi-am html \ + html-am info info-am install install-am install-data \ + install-data-am install-dvi install-dvi-am install-exec \ + install-exec-am install-html install-html-am install-info \ + install-info-am install-man install-pdf install-pdf-am \ + install-ps install-ps-am install-strip installcheck \ + installcheck-am installdirs installdirs-am maintainer-clean \ + maintainer-clean-generic mostlyclean mostlyclean-generic \ + mostlyclean-libtool pdf pdf-am ps ps-am tags tags-recursive \ + uninstall uninstall-am + + +# Tell versions [3.59,3.63) of GNU make to not export all variables. +# Otherwise a system limit (for SysV at least) may be exceeded. +.NOEXPORT: diff --git a/libX11/specs/XIM/Makefile.am b/libX11/specs/XIM/Makefile.am new file mode 100644 index 000000000..c76a3f720 --- /dev/null +++ b/libX11/specs/XIM/Makefile.am @@ -0,0 +1,33 @@ +# +# Copyright 2009 Sun Microsystems, Inc. All rights reserved. +# +# Permission to use, copy, modify, distribute, and sell this software and its +# documentation for any purpose is hereby granted without fee, provided that +# the above copyright notice appear in all copies and that both that +# copyright notice and this permission notice appear in supporting +# documentation. +# +# The above copyright notice and this permission notice shall be included +# in all copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +# OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +# IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR +# OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +# ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +# OTHER DEALINGS IN THE SOFTWARE. +# +# Except as contained in this notice, the name of the copyright holders shall +# not be used in advertising or otherwise to promote the sale, use or +# other dealings in this Software without prior written authorization +# from the copyright holders. +# + +# Based on xc/doc/specs/XIM/Makefile from X11R6.9 + +doc_sources = xim.ms + +include $(top_srcdir)/specs/troffrules.in + + diff --git a/libX11/specs/XIM/Makefile.in b/libX11/specs/XIM/Makefile.in new file mode 100644 index 000000000..73392a119 --- /dev/null +++ b/libX11/specs/XIM/Makefile.in @@ -0,0 +1,554 @@ +# Makefile.in generated by automake 1.11 from Makefile.am. +# @configure_input@ + +# Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, +# 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, +# Inc. +# This Makefile.in is free software; the Free Software Foundation +# gives unlimited permission to copy and/or distribute it, +# with or without modifications, as long as this notice is preserved. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY, to the extent permitted by law; without +# even the implied warranty of MERCHANTABILITY or FITNESS FOR A +# PARTICULAR PURPOSE. + +@SET_MAKE@ + +# +# Copyright 2009 Sun Microsystems, Inc. All rights reserved. +# +# Permission to use, copy, modify, distribute, and sell this software and its +# documentation for any purpose is hereby granted without fee, provided that +# the above copyright notice appear in all copies and that both that +# copyright notice and this permission notice appear in supporting +# documentation. +# +# The above copyright notice and this permission notice shall be included +# in all copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +# OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +# IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR +# OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +# ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +# OTHER DEALINGS IN THE SOFTWARE. +# +# Except as contained in this notice, the name of the copyright holders shall +# not be used in advertising or otherwise to promote the sale, use or +# other dealings in this Software without prior written authorization +# from the copyright holders. +# + +# Based on xc/doc/specs/XIM/Makefile from X11R6.9 + +# +# Copyright 2009 Sun Microsystems, Inc. All rights reserved. +# +# Permission to use, copy, modify, distribute, and sell this software and its +# documentation for any purpose is hereby granted without fee, provided that +# the above copyright notice appear in all copies and that both that +# copyright notice and this permission notice appear in supporting +# documentation. +# +# The above copyright notice and this permission notice shall be included +# in all copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +# OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +# IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR +# OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +# ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +# OTHER DEALINGS IN THE SOFTWARE. +# +# Except as contained in this notice, the name of the copyright holders shall +# not be used in advertising or otherwise to promote the sale, use or +# other dealings in this Software without prior written authorization +# from the copyright holders. +# + +# Based on xc/doc/specs/*/Makefile from X11R6.9 + +VPATH = @srcdir@ +pkgdatadir = $(datadir)/@PACKAGE@ +pkgincludedir = $(includedir)/@PACKAGE@ +pkglibdir = $(libdir)/@PACKAGE@ +pkglibexecdir = $(libexecdir)/@PACKAGE@ +am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd +install_sh_DATA = $(install_sh) -c -m 644 +install_sh_PROGRAM = $(install_sh) -c +install_sh_SCRIPT = $(install_sh) -c +INSTALL_HEADER = $(INSTALL_DATA) +transform = $(program_transform_name) +NORMAL_INSTALL = : +PRE_INSTALL = : +POST_INSTALL = : +NORMAL_UNINSTALL = : +PRE_UNINSTALL = : +POST_UNINSTALL = : +build_triplet = @build@ +host_triplet = @host@ +DIST_COMMON = $(srcdir)/Makefile.am $(srcdir)/Makefile.in \ + $(top_srcdir)/specs/troffrules.in +subdir = specs/XIM +ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 +am__aclocal_m4_deps = $(top_srcdir)/acinclude.m4 \ + $(top_srcdir)/configure.ac +am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ + $(ACLOCAL_M4) +mkinstalldirs = $(install_sh) -d +CONFIG_HEADER = $(top_builddir)/src/config.h \ + $(top_builddir)/include/X11/XlibConf.h +CONFIG_CLEAN_FILES = +CONFIG_CLEAN_VPATH_FILES = +AM_V_GEN = $(am__v_GEN_$(V)) +am__v_GEN_ = $(am__v_GEN_$(AM_DEFAULT_VERBOSITY)) +am__v_GEN_0 = @echo " GEN " $@; +AM_V_at = $(am__v_at_$(V)) +am__v_at_ = $(am__v_at_$(AM_DEFAULT_VERBOSITY)) +am__v_at_0 = @ +SOURCES = +DIST_SOURCES = +am__vpath_adj_setup = srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; +am__vpath_adj = case $$p in \ + $(srcdir)/*) f=`echo "$$p" | sed "s|^$$srcdirstrip/||"`;; \ + *) f=$$p;; \ + esac; +am__strip_dir = f=`echo $$p | sed -e 's|^.*/||'`; +am__install_max = 40 +am__nobase_strip_setup = \ + srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*|]/\\\\&/g'` +am__nobase_strip = \ + for p in $$list; do echo "$$p"; done | sed -e "s|$$srcdirstrip/||" +am__nobase_list = $(am__nobase_strip_setup); \ + for p in $$list; do echo "$$p $$p"; done | \ + sed "s| $$srcdirstrip/| |;"' / .*\//!s/ .*/ ./; s,\( .*\)/[^/]*$$,\1,' | \ + $(AWK) 'BEGIN { files["."] = "" } { files[$$2] = files[$$2] " " $$1; \ + if (++n[$$2] == $(am__install_max)) \ + { print $$2, files[$$2]; n[$$2] = 0; files[$$2] = "" } } \ + END { for (dir in files) print dir, files[dir] }' +am__base_list = \ + sed '$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;s/\n/ /g' | \ + sed '$$!N;$$!N;$$!N;$$!N;s/\n/ /g' +am__installdirs = "$(DESTDIR)$(docdir)" +DATA = $(doc_DATA) +DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) +ACLOCAL = @ACLOCAL@ +ADMIN_MAN_DIR = @ADMIN_MAN_DIR@ +ADMIN_MAN_SUFFIX = @ADMIN_MAN_SUFFIX@ +AMTAR = @AMTAR@ +AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@ +APP_MAN_DIR = @APP_MAN_DIR@ +APP_MAN_SUFFIX = @APP_MAN_SUFFIX@ +AR = @AR@ +AUTOCONF = @AUTOCONF@ +AUTOHEADER = @AUTOHEADER@ +AUTOMAKE = @AUTOMAKE@ +AWK = @AWK@ +BIGFONT_CFLAGS = @BIGFONT_CFLAGS@ +BIGFONT_LIBS = @BIGFONT_LIBS@ +CC = @CC@ +CCDEPMODE = @CCDEPMODE@ +CC_FOR_BUILD = @CC_FOR_BUILD@ +CFLAGS = @CFLAGS@ +CHANGELOG_CMD = @CHANGELOG_CMD@ +CPP = @CPP@ +CPPFLAGS = @CPPFLAGS@ +CWARNFLAGS = @CWARNFLAGS@ +CXX = @CXX@ +CXXCPP = @CXXCPP@ +CXXDEPMODE = @CXXDEPMODE@ +CXXFLAGS = @CXXFLAGS@ +CYGPATH_W = @CYGPATH_W@ +DEFS = @DEFS@ +DEPDIR = @DEPDIR@ +DOLT_BASH = @DOLT_BASH@ +DRIVER_MAN_DIR = @DRIVER_MAN_DIR@ +DRIVER_MAN_SUFFIX = @DRIVER_MAN_SUFFIX@ +DSYMUTIL = @DSYMUTIL@ +ECHO = @ECHO@ +ECHO_C = @ECHO_C@ +ECHO_N = @ECHO_N@ +ECHO_T = @ECHO_T@ +EGREP = @EGREP@ +EXEEXT = @EXEEXT@ +F77 = @F77@ +FFLAGS = @FFLAGS@ +FILE_MAN_DIR = @FILE_MAN_DIR@ +FILE_MAN_SUFFIX = @FILE_MAN_SUFFIX@ +GREP = @GREP@ +GROFF = @GROFF@ +I18N_MODULE_LIBS = @I18N_MODULE_LIBS@ +INSTALL = @INSTALL@ +INSTALL_DATA = @INSTALL_DATA@ +INSTALL_PROGRAM = @INSTALL_PROGRAM@ +INSTALL_SCRIPT = @INSTALL_SCRIPT@ +INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@ +KEYSYMDEF = @KEYSYMDEF@ +LAUNCHD = @LAUNCHD@ +LDFLAGS = @LDFLAGS@ +LIBOBJS = @LIBOBJS@ +LIBS = @LIBS@ +LIBTOOL = @LIBTOOL@ +LIB_MAN_DIR = @LIB_MAN_DIR@ +LIB_MAN_SUFFIX = @LIB_MAN_SUFFIX@ +LINT = @LINT@ +LINTLIB = @LINTLIB@ +LINT_FLAGS = @LINT_FLAGS@ +LN_S = @LN_S@ +LTCOMPILE = @LTCOMPILE@ +LTCXXCOMPILE = @LTCXXCOMPILE@ +LTLIBOBJS = @LTLIBOBJS@ +MAINT = @MAINT@ +MAKEINFO = @MAKEINFO@ +MALLOC_ZERO_CFLAGS = @MALLOC_ZERO_CFLAGS@ +MISC_MAN_DIR = @MISC_MAN_DIR@ +MISC_MAN_SUFFIX = @MISC_MAN_SUFFIX@ +MKDIR_P = @MKDIR_P@ +NMEDIT = @NMEDIT@ +OBJEXT = @OBJEXT@ +PACKAGE = @PACKAGE@ +PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@ +PACKAGE_NAME = @PACKAGE_NAME@ +PACKAGE_STRING = @PACKAGE_STRING@ +PACKAGE_TARNAME = @PACKAGE_TARNAME@ +PACKAGE_VERSION = @PACKAGE_VERSION@ +PATH_SEPARATOR = @PATH_SEPARATOR@ +PERL = @PERL@ +PKG_CONFIG = @PKG_CONFIG@ +PS2PDF = @PS2PDF@ +RANLIB = @RANLIB@ +RAWCPP = @RAWCPP@ +RAWCPPFLAGS = @RAWCPPFLAGS@ +SED = @SED@ +SET_MAKE = @SET_MAKE@ +SHELL = @SHELL@ +STRIP = @STRIP@ +VERSION = @VERSION@ +WCHAR32 = @WCHAR32@ +X11_CFLAGS = @X11_CFLAGS@ +X11_DATADIR = @X11_DATADIR@ +X11_EXTRA_DEPS = @X11_EXTRA_DEPS@ +X11_LIBDIR = @X11_LIBDIR@ +X11_LIBS = @X11_LIBS@ +X11_LOCALEDATADIR = @X11_LOCALEDATADIR@ +X11_LOCALEDIR = @X11_LOCALEDIR@ +X11_LOCALELIBDIR = @X11_LOCALELIBDIR@ +XDMCP_CFLAGS = @XDMCP_CFLAGS@ +XDMCP_LIBS = @XDMCP_LIBS@ +XERRORDB = @XERRORDB@ +XKBPROTO_CFLAGS = @XKBPROTO_CFLAGS@ +XKBPROTO_LIBS = @XKBPROTO_LIBS@ +XKBPROTO_REQUIRES = @XKBPROTO_REQUIRES@ +XKEYSYMDB = @XKEYSYMDB@ +XLOCALEDATADIR = @XLOCALEDATADIR@ +XLOCALEDIR = @XLOCALEDIR@ +XLOCALELIBDIR = @XLOCALELIBDIR@ +XMALLOC_ZERO_CFLAGS = @XMALLOC_ZERO_CFLAGS@ +XPROTO_CFLAGS = @XPROTO_CFLAGS@ +XPROTO_LIBS = @XPROTO_LIBS@ +XTHREADLIB = @XTHREADLIB@ +XTHREAD_CFLAGS = @XTHREAD_CFLAGS@ +XTMALLOC_ZERO_CFLAGS = @XTMALLOC_ZERO_CFLAGS@ +abs_builddir = @abs_builddir@ +abs_srcdir = @abs_srcdir@ +abs_top_builddir = @abs_top_builddir@ +abs_top_srcdir = @abs_top_srcdir@ +ac_ct_CC = @ac_ct_CC@ +ac_ct_CXX = @ac_ct_CXX@ +ac_ct_F77 = @ac_ct_F77@ +am__include = @am__include@ +am__leading_dot = @am__leading_dot@ +am__quote = @am__quote@ +am__tar = @am__tar@ +am__untar = @am__untar@ +bindir = @bindir@ +build = @build@ +build_alias = @build_alias@ +build_cpu = @build_cpu@ +build_os = @build_os@ +build_vendor = @build_vendor@ +builddir = @builddir@ +datadir = @datadir@ +datarootdir = @datarootdir@ +distcleancheck_listfiles = @distcleancheck_listfiles@ +docdir = @docdir@ +dvidir = @dvidir@ +exec_prefix = @exec_prefix@ +host = @host@ +host_alias = @host_alias@ +host_cpu = @host_cpu@ +host_os = @host_os@ +host_vendor = @host_vendor@ +htmldir = @htmldir@ +includedir = @includedir@ +infodir = @infodir@ +install_sh = @install_sh@ +libdir = @libdir@ +libexecdir = @libexecdir@ +localedir = @localedir@ +localstatedir = @localstatedir@ +mandir = @mandir@ +mkdir_p = @mkdir_p@ +oldincludedir = @oldincludedir@ +pdfdir = @pdfdir@ +prefix = @prefix@ +program_transform_name = @program_transform_name@ +psdir = @psdir@ +sbindir = @sbindir@ +sharedstatedir = @sharedstatedir@ +srcdir = @srcdir@ +sysconfdir = @sysconfdir@ +target_alias = @target_alias@ +top_build_prefix = @top_build_prefix@ +top_builddir = @top_builddir@ +top_srcdir = @top_srcdir@ +doc_sources = xim.ms +EXTRA_DIST = $(doc_sources) +@HAVE_PS2PDF_FALSE@printable_format = .ps +@HAVE_PS2PDF_TRUE@printable_format = .pdf +@BUILD_SPECS_TRUE@doc_DATA = $(doc_sources:.ms=.txt) \ +@BUILD_SPECS_TRUE@ $(doc_sources:.ms=$(printable_format)) \ +@BUILD_SPECS_TRUE@ $(doc_sources:.ms=.html) + +@BUILD_SPECS_TRUE@CLEANFILES = $(doc_DATA) +@BUILD_SPECS_TRUE@MOSTLYCLEANFILES = index.* + +# Pass version string as a troff string for substitution +@BUILD_SPECS_TRUE@GROFF_DEFS = -dxV="$(PACKAGE_STRING)" + +# -e to run through eqn, -t to run through tbl +@BUILD_SPECS_TRUE@GROFF_FLAGS = -e -t -ms $(GROFF_DEFS) $(top_srcdir)/specs/macros.t +@BUILD_SPECS_TRUE@SUFFIXES = .ms .ps .txt .html .pdf +all: all-am + +.SUFFIXES: +.SUFFIXES: .ms .ps .txt .html .pdf +$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(top_srcdir)/specs/troffrules.in $(am__configure_deps) + @for dep in $?; do \ + case '$(am__configure_deps)' in \ + *$$dep*) \ + ( cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh ) \ + && { if test -f $@; then exit 0; else break; fi; }; \ + exit 1;; \ + esac; \ + done; \ + echo ' cd $(top_srcdir) && $(AUTOMAKE) --foreign specs/XIM/Makefile'; \ + $(am__cd) $(top_srcdir) && \ + $(AUTOMAKE) --foreign specs/XIM/Makefile +.PRECIOUS: Makefile +Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status + @case '$?' in \ + *config.status*) \ + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \ + *) \ + echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \ + cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \ + esac; + +$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh + +$(top_srcdir)/configure: @MAINTAINER_MODE_TRUE@ $(am__configure_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(ACLOCAL_M4): @MAINTAINER_MODE_TRUE@ $(am__aclocal_m4_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(am__aclocal_m4_deps): + +mostlyclean-libtool: + -rm -f *.lo + +clean-libtool: + -rm -rf .libs _libs +install-docDATA: $(doc_DATA) + @$(NORMAL_INSTALL) + test -z "$(docdir)" || $(MKDIR_P) "$(DESTDIR)$(docdir)" + @list='$(doc_DATA)'; test -n "$(docdir)" || list=; \ + for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + echo "$$d$$p"; \ + done | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(docdir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(docdir)" || exit $$?; \ + done + +uninstall-docDATA: + @$(NORMAL_UNINSTALL) + @list='$(doc_DATA)'; test -n "$(docdir)" || list=; \ + files=`for p in $$list; do echo $$p; done | sed -e 's|^.*/||'`; \ + test -n "$$files" || exit 0; \ + echo " ( cd '$(DESTDIR)$(docdir)' && rm -f" $$files ")"; \ + cd "$(DESTDIR)$(docdir)" && rm -f $$files +tags: TAGS +TAGS: + +ctags: CTAGS +CTAGS: + + +distdir: $(DISTFILES) + @srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + list='$(DISTFILES)'; \ + dist_files=`for file in $$list; do echo $$file; done | \ + sed -e "s|^$$srcdirstrip/||;t" \ + -e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \ + case $$dist_files in \ + */*) $(MKDIR_P) `echo "$$dist_files" | \ + sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \ + sort -u` ;; \ + esac; \ + for file in $$dist_files; do \ + if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \ + if test -d $$d/$$file; then \ + dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \ + if test -d "$(distdir)/$$file"; then \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ + fi; \ + if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \ + cp -fpR $(srcdir)/$$file "$(distdir)$$dir" || exit 1; \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ + fi; \ + cp -fpR $$d/$$file "$(distdir)$$dir" || exit 1; \ + else \ + test -f "$(distdir)/$$file" \ + || cp -p $$d/$$file "$(distdir)/$$file" \ + || exit 1; \ + fi; \ + done +check-am: all-am +check: check-am +all-am: Makefile $(DATA) +installdirs: + for dir in "$(DESTDIR)$(docdir)"; do \ + test -z "$$dir" || $(MKDIR_P) "$$dir"; \ + done +install: install-am +install-exec: install-exec-am +install-data: install-data-am +uninstall: uninstall-am + +install-am: all-am + @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am + +installcheck: installcheck-am +install-strip: + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + `test -z '$(STRIP)' || \ + echo "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'"` install +mostlyclean-generic: + -test -z "$(MOSTLYCLEANFILES)" || rm -f $(MOSTLYCLEANFILES) + +clean-generic: + -test -z "$(CLEANFILES)" || rm -f $(CLEANFILES) + +distclean-generic: + -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES) + -test . = "$(srcdir)" || test -z "$(CONFIG_CLEAN_VPATH_FILES)" || rm -f $(CONFIG_CLEAN_VPATH_FILES) + +maintainer-clean-generic: + @echo "This command is intended for maintainers to use" + @echo "it deletes files that may require special tools to rebuild." +clean: clean-am + +clean-am: clean-generic clean-libtool mostlyclean-am + +distclean: distclean-am + -rm -f Makefile +distclean-am: clean-am distclean-generic + +dvi: dvi-am + +dvi-am: + +html: html-am + +html-am: + +info: info-am + +info-am: + +install-data-am: install-docDATA + +install-dvi: install-dvi-am + +install-dvi-am: + +install-exec-am: + +install-html: install-html-am + +install-html-am: + +install-info: install-info-am + +install-info-am: + +install-man: + +install-pdf: install-pdf-am + +install-pdf-am: + +install-ps: install-ps-am + +install-ps-am: + +installcheck-am: + +maintainer-clean: maintainer-clean-am + -rm -f Makefile +maintainer-clean-am: distclean-am maintainer-clean-generic + +mostlyclean: mostlyclean-am + +mostlyclean-am: mostlyclean-generic mostlyclean-libtool + +pdf: pdf-am + +pdf-am: + +ps: ps-am + +ps-am: + +uninstall-am: uninstall-docDATA + +.MAKE: install-am install-strip + +.PHONY: all all-am check check-am clean clean-generic clean-libtool \ + distclean distclean-generic distclean-libtool distdir dvi \ + dvi-am html html-am info info-am install install-am \ + install-data install-data-am install-docDATA install-dvi \ + install-dvi-am install-exec install-exec-am install-html \ + install-html-am install-info install-info-am install-man \ + install-pdf install-pdf-am install-ps install-ps-am \ + install-strip installcheck installcheck-am installdirs \ + maintainer-clean maintainer-clean-generic mostlyclean \ + mostlyclean-generic mostlyclean-libtool pdf pdf-am ps ps-am \ + uninstall uninstall-am uninstall-docDATA + + +@BUILD_SPECS_TRUE@.ms.ps: +@BUILD_SPECS_TRUE@ -$(AM_V_GEN) $(GROFF) -Tps $(GROFF_FLAGS) $< 2> index.$@.raw > $@ +@BUILD_SPECS_TRUE@ @if grep '^[^1-9.]' index.$@.raw | grep -v warning; then exit 1; \ +@BUILD_SPECS_TRUE@ else test $$? -le 1; fi + +@BUILD_SPECS_TRUE@.ms.txt: +@BUILD_SPECS_TRUE@ $(AM_V_GEN) env GROFF_NO_SGR=TRUE $(GROFF) -Tutf8 $(GROFF_FLAGS) \ +@BUILD_SPECS_TRUE@ $< 2> index.$@.raw > $@ + +@BUILD_SPECS_TRUE@.ms.html: +@BUILD_SPECS_TRUE@ $(AM_V_GEN) $(GROFF) -Thtml $(GROFF_FLAGS) $< 2> index.$@.raw > $@ + +@BUILD_SPECS_TRUE@.ps.pdf: +@BUILD_SPECS_TRUE@ $(AM_V_GEN) $(PS2PDF) $< $@ + +# Tell versions [3.59,3.63) of GNU make to not export all variables. +# Otherwise a system limit (for SysV at least) may be exceeded. +.NOEXPORT: diff --git a/libX11/specs/XIM/xim.ms b/libX11/specs/XIM/xim.ms new file mode 100644 index 000000000..e41e9bcab --- /dev/null +++ b/libX11/specs/XIM/xim.ms @@ -0,0 +1,4279 @@ +.\" $Xorg: xim.ms,v 1.3 2000/08/17 19:42:21 cpqbld Exp $ +.\" To print this out, type tbl macros.t ThisFile | troff -ms +.\" $XFree86: xc/doc/specs/XIM/xim.ms,v 1.2 2000/12/14 17:48:58 dawes Exp $ +.EH '''' +.OH '''' +.EF '''' +.OF '''' +.ps 11 +.nr PS 11 +\& +.sp 8 +.TL +\s+3\fBThe Input Method Protocol\fP\s-3 +.sp +\fBVersion 1.0\fP +.sp +\fBX Consortium Standard\fP +.sp +\fBX Version 11, Release 7\fP +.sp +\fB\*(xV\fP +.sp 3 +.AU +Masahiko Narita +.AI +FUJITSU Limited. +.AU +Hideki Hiura +.AI +SunSoft, Inc. +.sp 3 +.AB +.LP +This specifies a protocol between IM library and IM (Input Method) +Server for internationalized text input, which is independent from +any specific language, any specific input method and the transport layer +used in communication between the IM library and the IM Server, and uses +a client-server model. +This protocol allows user to use his/her favorite input method for all +applications within the stand-alone distributed environment. +.AE +.ce 0 +.br +\& +.LP +.ps 11 +.nr PS 11 +.bp +\& +.ps 9 +.nr PS 9 +.sp 8 +.LP +.DS C +X Window System is a trademark of X Consortium, Inc. +.sp +Copyright \(co 1993, 1994 by X Consortium, Inc. +.DE +.sp 2 +.LP +Permission is hereby granted, free of charge, to any person obtaining +a copy of this software and associated documentation files (the +"Software"), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so, subject to +the following conditions: +.LP +The above copyright notice and this permission notice shall be included +in all copies or substantial portions of the Software. +.LP +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR +OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +OTHER DEALINGS IN THE SOFTWARE. +.LP +Except as contained in this notice, the name of the X Consortium shall +not be used in advertising or otherwise to promote the sale, use or +other dealings in this Software without prior written authorization +from the X Consortium. +.sp 3 +.DS C +Copyright \(co 1993, 1994 by FUJITSU LIMITED +.sp +Copyright \(co 1993, 1994 by Sun Microsystems, Inc. +.DE +.sp 2 +.LP +Permission to use, copy, modify, and distribute this documentation +for any purpose and without fee is hereby granted, provided +that the above copyright notice and this permission +notice appear in all copies. +Fujitsu and Sun Microsystems make no representations +about the suitability for any purpose of the information in this document. +This documentation is provided as is without express or implied warranty. +.ps 11 +.nr PS 11 +.bp 1 +.EH '\fBX Input Method Protocol\fP''\fB\*(xV\fP' +.OH '\fBX Input Method Protocol\fP''\fB\*(xV\fP' +.EF ''\fB % \fP'' +.OF ''\fB % \fP'' +.NH 1 +Introduction +.XS +\*(SN Introduction +.XE +.NH 2 +Scope +.XS +\*(SN Scope +.XE +.LP +The internationalization in the +X Window System +Version 11, Release 5 (X11R5) provides a common API which application +developers can use to create portable internationalized programs and to +adapt them to the requirements of different native languages, local customs, +and character string encodings (this is called ``localization''). +As one of its internationalization mechanisms X11R5 has defined a functional +interface for internationalized text input, called XIM (X Input Method). +.LP +When a client-server model is used with an IM (Input Method) implementation, +a protocol must be established between the client and the server. +However, the protocol used to interface Input Method Servers (IM Servers) +with the Input Method libraries (IM libraries) to which applications are +linked was not addressed in X11R5. +This led application developers to depend on vendor-specific input methods, +decreased the user's choice of available input methods, and made it more +difficult for developers to create portable applications. This paper describes +the Input Method Protocol developed for X11R6 to resolve the above problems +and to address the requirements of existing and future input methods. +.LP +The Input Method Protocol is independent from the transport layer used in +communication between the IM library and the IM Server. +Thus, the input method protocol can be built on any inter-process +communication mechanism, such as TCP/IP or the X protocol. +.LP +In addition, the protocol provides for future extensions such as differing +input model types. +.LP +.NH 2 +Background +.XS +\*(SN Background +.XE +.LP +Text input is much more simple for some languages than +others. English, for instance, uses an alphabet of a manageable size, +and input consists of pressing the corresponding key on a keyboard, +perhaps in combination with a shift key for capital letters or special +characters. +.LP +Some languages have larger alphabets, or modifiers such as accents, +which require the addition of special key combinations in order to enter +text. These input methods may require ``dead-keys'' or ``compose-keys'' +which, when followed by different combinations of key strokes, +generate different characters. +.LP +Text input for ideographic languages is much less simple. In these +languages, characters represent actual objects rather than phonetic +sounds used in pronouncing a word, and the number of characters +in these languages may continue to grow. In Japanese, for instance, most +text input methods involve entering characters in a phonetic alphabet, +after which the input method searches a dictionary for possible +ideographic equivalents (of which there may be many). The input method then +presents the candidate characters for the user to choose from. +.LP +In Japanese, either Kana (phonetic symbols) or Roman letters are +typed and then a region is selected for conversion to Kanji. Several +Kanji characters may have the same phonetic representation. If that +is the case with the string entered, a menu of characters is presented +and the user must choose the appropriate one. If no choice is necessary +or a preference has been established, the input method does the +substitution directly. +.LP +These complicated input methods must present state information (Status Area), +text entry and edit space (Preedit Area), and menu/choice presentations +(Auxiliary Area). Much of the protocol between the IM library and the IM +Server involves managing these IM areas. +Because of the size and complexity of these input methods, and because +of how widely they vary from one language or locale to another, they are +usually implemented as separate processes which can serve many client +processes on the same computer or network. +.LP +.NH 2 +Input Method Styles +.XS +\*(SN Input Method Styles +.XE +.LP +X11 internationalization support includes the following four types of +input method: +.RS +.IP "- on-the-spot:" 20 +The client application is directed by the IM Server to display all +pre-edit data at the site of text insertion. The client registers +callbacks invoked by the input method during pre-editing. +.IP "- off-the-spot:" 20 +The client application provides display windows for the pre-edit data +to the input method which displays into them directly. +.IP "- over-the-spot:" 20 +The input method displays pre-edit data in a window which it brings up +directly over the text insertion position. +.IP "- root-window:" 20 +The input method displays all pre-edit data in a separate area of the +screen in a window specific to the input method. +.RE +.LP +Client applications must choose from the available input methods +supported by the IM Server and provide the display areas and callbacks +required by the input method. +.LP +.NH 1 +Architecture +.XS +\*(SN Architecture +.XE +.NH 2 +Implementation Model +.XS +\*(SN Implementation Model +.XE +.LP +Within the X Window System environment, the following two typical +architectural models can be used as an input method's implementation +model. +.RS +.IP "- Client/Server model:" 20 +A separate process, the IM Server, processes input and handles preediting, +converting, and committing. The IM library within the application, acting +as client to the IM Server, simply receives the committed string from the +IM Server. +.IP "- Library model:" 20 +All input is handled by the IM library within the application. The +event process is closed within the IM library and a separate IM Server +process may not be required. +.RE +.LP +Most languages which need complex preediting, such as Asian languages, +are implemented using the Client/Server IM model. Other languages +which need only dead key or compose key processing, such as European +languages, are implemented using the Library model. +.LP +In this paper, we discuss mainly the Client/Server IM model and the +protocol used in communication between the IM library (client) and the IM +Server. +.LP +.NH 2 +Structure of IM +.XS +\*(SN Structure of IM +.XE +.LP +When the client connects or disconnects to the IM Server, an open or close +operation occurs between the client and the IM Server. +.LP +The IM can be specified at the time of XOpenIM() by setting the locale +of the client and a locale modifier. Since the IM remembers +the locale at the time of creation XOpenIM() can be called +multiple times (with the +setting for the locale and the locale modifier changed) to support +multiple languages. +.LP +In addition, the supported IM type can be obtained using XGetIMValues(). +.LP +The client usually holds multiple input (text) fields. Xlib provides a +value type called the ``Input Context'' (IC) to manage each individual +input field. An IC can be created by specifying XIM using XCreateIC(), +and it can be destroyed using XDestroyIC(). +.LP +The IC can specify the type of IM which is supported by XIM for each +input field, so each input field can handle a different type of IM. +.LP +Most importantly information such as the committed string sent from +the IM Server to the client, is exchanged based on each IC. +.LP +Since each IC corresponds to an input field, the focused input field +should be announced to the IM Server using XSetICFocus(). (XUnsetICFocus() +can also be used to change the focus.) +.LP +.NH 2 +Event Handling Model +.XS +\*(SN Event Handling Model +.XE +.LP +Existing input methods support either the FrontEnd method, the BackEnd method, +or both. This protocol specifically supports the BackEnd method as +the default method, but also supports the FrontEnd method as an optional +IM Server extension. +.LP +The difference between the FrontEnd and BackEnd methods is in how +events are delivered to the IM Server. (Fig. 1) +.LP +.NH 3 +BackEnd Method +.XS +\*(SN BackEnd Method +.XE +.LP +In the BackEnd method, client window input events are always delivered +to the IM library, which then passes them to the IM Server. Events are +handled serially in the order delivered, and therefore there is no +synchronization problem between the IM library and the IM Server. +.LP +Using this method, the IM library forwards all KeyPress and KeyRelease +events to the IM Server (as required by the Event Flow Control model +described in section 2.4. ``Event Flow Control''), and synchronizes +with the IM Server (as described in section 4.16. ``Filtering Events''). +.LP +.NH 3 +FrontEnd Method +.XS +\*(SN FrontEnd Method +.XE +.LP +In the FrontEnd method, client window input events are delivered by the +X server directly to both the IM Server and the IM library. Therefore this +method provides much better interactive performance while preediting +(particularly in cases such as when the IM Server is running locally on +the user's workstation and the client application is running on another +workstation over a relatively slow network). +.LP +However, the FrontEnd model may have synchronization problems between +the key events handled in the IM Server and other events handled in the +client, and these problems could possibly cause the loss or duplication +of key events. For this reason, the BackEnd method is the core method +supported, and the FrontEnd method is made available as an extension for +performance purposes. (Refer to Appendix A for more information.) +.LP +.LP +.bp +\^... 0.05 6.513 4.737 10.45 +\^... 0.000i 3.937i 4.687i 0.000i +.nr 00 \n(.u +.nf +.PS 3.937i 4.687i +.br +.ps +.ps 10 +\h'3.687i'\v'3.437i'\v'-.13m'\L'-0.500i\(br'\v'.13m' +.sp -1 +\h'3.712i'\v'3.037i'\D'l-0.025i -0.100i' +.sp -1 +\h'3.687i'\v'2.937i'\D'l-0.025i 0.100i' +.sp -1 +\h'2.187i'\v'1.938i'\v'-.13m'\L'-0.750i\(br'\v'.13m' +.sp -1 +\h'2.187i'\v'1.188i'\l'0.750i' +.sp -1 +\h'2.937i'\v'1.188i'\v'-.13m'\L'1.250i\(br'\v'.13m' +.sp -1 +\h'2.912i'\v'2.338i'\D'l0.025i 0.100i' +.sp -1 +\h'2.937i'\v'2.438i'\D'l0.025i -0.100i' +.sp -1 +\h'2.187i'\v'3.437i'\v'-.13m'\L'-1.499i\(br'\v'.13m' +.sp -1 +\h'2.212i'\v'2.038i'\D'l-0.025i -0.100i' +.sp -1 +\h'2.187i'\v'1.938i'\D'l-0.025i 0.100i' +.sp -1 +\h'1.938i'\v'3.437i'\l'1.999i' +.sp -1 +\h'3.937i'\v'3.437i'\v'-.13m'\L'0.500i\(br'\v'.13m' +.sp -1 +\h'3.937i'\v'3.937i'\l'-1.999i' +.sp -1 +\h'1.938i'\v'3.937i'\v'-.13m'\L'-0.500i\(br'\v'.13m' +.sp -1 +\h'2.562i'\v'2.438i'\l'2.125i' +.sp -1 +\h'4.687i'\v'2.438i'\v'-.13m'\L'0.499i\(br'\v'.13m' +.sp -1 +\h'4.687i'\v'2.937i'\l'-2.125i' +.sp -1 +\h'2.562i'\v'2.937i'\v'-.13m'\L'-0.499i\(br'\v'.13m' +.sp -1 +\h'2.562i'\v'1.438i'\l'1.313i' +.sp -1 +\h'3.875i'\v'1.438i'\v'-.13m'\L'0.437i\(br'\v'.13m' +.sp -1 +\h'3.875i'\v'1.875i'\l'-1.313i' +.sp -1 +\h'2.562i'\v'1.875i'\v'-.13m'\L'-0.437i\(br'\v'.13m' +.sp -1 +\h'1.938i'\v'0.438i'\l'1.999i' +.sp -1 +\h'3.937i'\v'0.438i'\v'-.13m'\L'1.500i\(br'\v'.13m' +.sp -1 +\h'3.937i'\v'1.938i'\l'-1.999i' +.sp -1 +\h'1.938i'\v'1.938i'\v'-.13m'\L'-1.500i\(br'\v'.13m' +.sp -1 +\D'l0.000i 0.000i' +.sp -1 +.ps +.ps 12 +\h'3.812i'\v'3.217i'\h'-0.0m'\v'0.2m'FrontEnd Method (Extension) +.sp -1 +\h'0.813i'\v'3.217i'\h'-0.0m'\v'0.2m'BackEnd Method (Core) +.sp -1 +\h'2.562i'\v'3.779i'\h'-0.0m'\v'0.2m'X Server +.sp -1 +\h'3.062i'\v'2.779i'\h'-0.0m'\v'0.2m'IM Server +.sp -1 +\h'3.062i'\v'1.717i'\h'-0.0m'\v'0.2m'Library +.sp -1 +\h'2.187i'\v'0.904i'\h'-0.0m'\v'0.2m'Application +.sp -1 +.ps +.ft +.sp 1+3.937i +.PE +.if \n(00 .fi +.ce +.sp +Fig.1 The Flow of Events +.LP +.NH 2 +Event Flow Control +.XS +\*(SN Event Flow Control +.XE +.LP +This protocol supports two event flow models for communication between the +IM library and the IM Server (Static and Dynamic). +.LP +Static Event Flow requires that input events always be sent to the IM +Server from the client. +.LP +Dynamic Event Flow, however, requires only that those input events which +need to be processed (converted) be sent to the IM Server from the client. +.LP +For instance, in the case of inputing a combination of ASCII characters +and Chinese characters, ASCII characters do not need to be processed in +the IM Server, so their key events do not have to be sent to the IM +Server. On the other hand, key events necessary for composing Chinese +characters must be sent to the IM Server. +.LP +Thus, by adopting the Dynamic Event Flow, the number of requests among the +X Server, the client, and the IM Server is significantly reduced, and the +number of context switches is also reduced, resulting in improved performance. +The IM Server can send +.PN XIM_REGISTER_TRIGGERKEYS +message in order to switch the event flow in the Dynamic Event Flow. +.LP +The protocol for this process is described in section 4.5. ``Event Flow +Control''. +.LP +.NH 1 +Default Preconnection Convention +.XS +\*(SN Default Preconnection Convention +.XE +.LP +IM Servers are strongly encouraged to register their symbolic +names as the ATOM names into the IM Server directory property, +.PN XIM_SERVERS, +on the root window of the screen_number 0. +This property can contain a list of ATOMs, and the each ATOM represents +each possible IM Server. +IM Server names are restricted to POSIX Portable Filename Character Set. +To discover if the IM Server is active, see if there is an owner for +the selection with that atom name. To learn the address of that IM Server, +convert the selection target +.PN TRANSPORT, +which will return a string form of the transport address(es). +To learn the supported locales of that IM Server, convert the selection target +.PN LOCALES, +which will return a set of names of the supported locales in the syntax +X/Open defines. +.LP +The basic semantics to determine the IM Server if there are +multiple ATOMs are found in +.PN XIM_SERVERS +property, is first fit if the IM Server name is not given as +a X modifier's category +.PN im. +.LP +The address information retrievable from the +.PN TRANSPORT +target is a transport-specific name. +The preregistered formats for transport-specific names are listed in Appendix B. +Additional transport-specific names may be registered with X Consortium. +.LP +For environments that lack X connections, or for IM Servers which +do not use the X Window System, the preconnection convention with IM Server +may be given outside the X Window system (e.g. using a Name Service). +.LP +.NH 1 +Protocol +.XS +\*(SN Protocol +.XE +.LP +The protocol described below uses the bi-directional +synchronous/asynchronous request/reply/error model and is specified +using the same conventions outlined in Section 2 of the core X Window +System protocol [1]: +.LP +.NH 2 +Basic Requests Packet Format +.XS +\*(SN Basic Requests Packet Format +.XE +.LP +This section describes the requests that may be exchanged between the client +and the IM Server. +.LP +The basic request packet header format is as follows. +.RS +.DS + major-opcode: CARD8 + minor-opcode: CARD8 + length: CARD16 +.DE +.RE +The MAJOR-OPCODE specifies which core request or extension package this +packet represents. If the MAJOR-OPCODE corresponds to a core request, +the MINOR-OPCODE contains 8 bits of request-specific data. +(If the MINOR-OPCODE is not used, it is 0.) +Otherwise, the MAJOR-OPCODE and the MINOR-OPCODE are specified by +.PN XIM_QUERY_EXTENSION +message. (Refer to 4.7. Query the supported extension protocol list.) +The LENGTH field specifies the number of 4 bytes elements following the +header. If no additional data is followed by the header, the LENGTH field +will be 0. +.LP +.NH 2 +Data Types +.XS +\*(SN Data Types +.XE +.LP +The following data types are used in the core X IM Server protocol: +.LP +.nf +.ta .2i .5i 2.0i +BITMASK16 + CARD16 +.sp +BITMASK32 + CARD32 +.sp +PADDING FORMAT + Where N is some expression, and Pad(N) is the number of bytes needed to round N up to a + multiple of four. + Pad(N) = (4 - (N mod 4)) mod 4 +.sp +LPCE + 1 A character from the4 X Portable Character Set in Latin Portable + Character Encoding +.bp +STRING + 2 n length of string in bytes + n LISTofLPCE string + p unused, p=Pad(2+n) +.sp +STR + 1 n length of name in bytes + n STRING8 name +.sp +XIMATTR + 2 CARD16 attribute ID (*1) + 2 CARD16 type of the value (*2) + 2 n length of im-attribute + n STRING8 im-attribute + p unused, p = Pad(2+n) +.sp +The im-attribute argument specifies XIM values such as XNQueryInputStyle. +.sp +XICATTR + 2 CARD16 attribute ID (*1) + 2 CARD16 type of the value (*2) + 2 n length of ic-attribute + n STRING8 ic-attribute + p unused, p = Pad(2+n) +.LP +.IP (*1) +XIMATTR and XICATTR are used during the setup stage and XIMATTRIBUTE and +XICATTRIBUTE are used after each attribute ID has been recognized by +the IM Server and the IM library. +.sp +.IP (*2) +The value types are defined as follows: +.TS H +tab(:); +l l l s s +l l l l l +l l l l l +l l l l l +l l l l l +l l l l l +l l l l l +l l l l l +l l l l l +l l l l l +l l l l l +l l l l l +l l l l l +l l l l l +l l l l l +l l l l l +l l l l l +l l l l l +l l l l l +l l l l l +l l l l l +l l l l l +l l l s s +l l l s s +l l l s s +l l l s s +l l l s s +l l l l l. +_ +.sp 6p +.B +values:data:format +.sp 6p +_ +.sp 6p +.TH +.R +#0:Separator of NestedList:----- (*3) +#1:byte data:CARD8 +#2:word data:CARD16 +#3:long data:CARD32 +#4:char data:STRING8 +#5:Window:CARD32 +#10:XIMStyles:2:n:number of XIMStyle list +::2::unused +::n:CARD32:XIMStyle list +#11:XRectangle:2:INT16:X +::2:INT16:Y +::2:CARD16:width +::2:CARD16:height +#12:XPoint:2:INT16:X +::2:INT16:Y +#13:XFontSet:2:n:length of Base font name +::n:STRING8:Base font name list +::p::unused, p = Pad(2+n) +#15:XIMHotKeyTriggers:4:n:T{ +number of XIMTRIGGERKEY list (*4) +T} +::n:XIMTRIGGERKEY:XIMHotkeyTrigger list +#16:XIMHotKeyState::XIMHOTKEYSTATE:T{ +HotKey processing state +T} +#17:XIMStringConversion:XIMSTRCONVTEXT +#18:XIMPreeditState:XIMPREEDITSTATE +#19:XIMResetState:XIMRESETSTATE +#x7fff:NestedList:----- +.sp 6p +_ +.TE +.LP +.IP (*3) +The IC value for the separator of NestedList is defined as follows, +.br + #define XNSeparatorofNestedList ``separatorofNestedList'' +.br +, which is registered in X Consortium and cannot be used for any +other purpose. +.sp +.IP (*4) +LISTofFOO +.RS +A Type name of the form LISTof FOO means a counted list of elements of +type FOO. +The size of the length field may vary (it is not necessarily the same +size as a FOO), and in some cases, it may be implicit. +.RE +.sp +.LP +.nf +.ta .2i .5i 2.0i +XIMTRIGGERKEY + 4 CARD32 keysym + 4 CARD32 modifier + 4 CARD32 modifier mask +.sp +ENCODINGINFO + 2 n length of encoding info + n STRING8 encoding info + p unused, p=Pad(2+n) +.sp +EXT + 1 CARD8 extension major-opcode + 1 CARD8 extension minor-opcode + 2 n length of extension name + n STRING8 extension name + p unused, p = Pad(n) +.sp +XIMATTRIBUTE + 2 CARD16 attribute ID + 2 n value length + n value + p unused, p = Pad(n) +.sp +XICATTRIBUTE + 2 CARD16 attribute ID + 2 n value length + n value + p unused, p = Pad(n) +.sp +.bp +.ta .2i .5i 3.0i +XIMSTRCONVTEXT + 2 CARD16 XIMStringConversionFeedback + #x0000001 XIMStringConversionLeftEdge + #x0000002 XIMStringConversionRightEdge + #x0000004 XIMStringConversionTopEdge + #x0000008 XIMStringConversionBottomEdge + #x0000010 XIMStringConversionConvealed + #x0000020 XIMStringConversionWrapped + 2 n byte length of the retrieved string + n STRING8 retrieved string + p unused, p = Pad(n) + 2 m byte length of feedback array + 2 unused + m LISTofXIMSTRCONVFEEDBACK feedback array(*1) +.IP (*1) +This field is reserved for future use. +.sp +.LP +.nf +.ta .2i .5i 2.0i +XIMFEEDBACK + 4 CARD32 XIMFeedback + #x000001 XIMReverse + #x000002 XIMUnderline + #x000004 XIMHighlight + #x000008 XIMPrimary + #x000010 XIMSecondary + #x000020 XIMTertiary + #x000040 XIMVisibleToForward + #x000080 XIMVisibleToBackward + #x000100 XIMVisibleCenter +.sp +XIMHOTKEYSTATE + 4 CARD32 XIMHotKeyState + #x0000001 XIMHotKeyStateON + #x0000002 XIMHotKeyStateOFF +.sp +XIMPREEDITSTATE + 4 CARD32 XIMPreeditState + #x0000001 XIMPreeditEnable + #x0000002 XIMPreeditDisable +.sp +XIMRESETSTATE + 4 CARD32 XIMResetState + #x0000001 XIMInitialState + #x0000002 XIMPreserveState +.LP +.NH 2 +Error Notification +.XS +\*(SN Error Notification +.XE +.LP +Both the IM Server and the IM library return +.PN XIM_ERROR +messages instead of the corresponding reply messages if any errors occur +during data processing. +.LP +At most one error is generated per request. If more than one error condition +is encountered in processing a request, the choice of which error is returned +is implementation-dependent. +.LP +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_ERROR (IM Server \(<-\(-> IM library) +.sp 6p +:2:CARD16:input-method-ID +:2:CARD16:input-context-ID +:2:BITMASK16:flag (*1) +::#0000:Both Input-Method-ID and Input-Context-ID are invalid +::#0001:Input-Method-ID is valid +::#0002:Input-Context-ID is valid +:2:CARD16:Error Code +::#1:BadAlloc +::#2:BadStyle +::#3:BadClientWindow +::#4:BadFocusWindow +::#5:BadArea +::#6:BadSpotLocation +::#7:BadColormap +::#8:BadAtom +::#9:BadPixel +::#10:BadPixmap +::#11:BadName +::#12:BadCursor +::#13:BadProtocol +::#14:BadForeground +::#15:BadBackground +::#16:LocaleNotSupported +::#999:BadSomething (*2) +:2:n:byte length of error detail. +:2:CARD16:type of error detail (*3) +:n:STRING8:error detail (*4) +:p::unused, p = Pad(n) +.TE +.LP +.IP (*1) +Before an IM is created, both Input-Method-ID and +Input-Context-ID are invalid. +Before an IC is created, only Input-Method-ID is valid. +After that, both of Input-Method-ID and Input-Context-ID are valid. +.IP (*2) +Unspecific error, for example ``language engine died'' +.IP (*3) +This field is reserved for future use. +.IP (*4) +Vendor defined detail error message +.RE +.LP +.NH 2 +Connection Establishment +.XS +\*(SN Connection Establishment +.XE +.LP +.PN XIM_CONNECT +message requests to establish a connection over a mutually-understood virtual +stream. +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_CONNECT (IM library \(-> IM Server) +.sp 6p +:1::byte order +::#x42 MSB first +::#x6c LSB first +:1::unused +:2:CARD16:client-major-protocol-version (*1) +:2:CARD16:client-minor-protocol-version (*1) +:2:CARD16:number of client-auth-protocol-names +:n:LISTofSTRING:client-auth-protocol-names +.TE +.LP +.IP (*1) +Specify the version of IM Protocol that the client supports. +.RE +.sp +.LP +A client must send +.PN XIM_CONNECT +message as the first message on the connection. +The list specifies the names of authentication protocols the sending +IM Server is willing to perform. +(If the client need not authenticate, the list may be omited.) +.LP +.PN XIM_AUTH_REQUIRED +message is used to send the authentication protocol name and protocol-specific +data. +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_AUTH_REQUIRED (IM library \(<-\(-> IM Server) +.sp 6p +:1:CARD8:auth-protocol-index +:3::unused +:2:n:length of authentication data +:2::unused +:n::data +:p::unused, p = Pad(n) +.TE +.RE +.LP +The auth-protocol is specified by an index into the list of names +given in the +.PN XIM_CONNECT +or +.PN XIM_AUTH_SETUP +message. Any protocol-specific data that might be required is also sent. +.LP +The IM library sends +.PN XIM_AUTH_REPLY +message as the reply to +.PN XIM_AUTH_REQUIRED +message, if the IM Server is authenticated. +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_AUTH_REPLY (IM library \(-> IM Server) +.sp 6p +:2:n:length of authentication data +:2::unused +:2:n:length of authentication data +:2::unused +:n::data +:p::unused, p = Pad(n) +.TE +.RE +.LP +The auth data is specific to the authentication protocol in use. +.LP +.PN XIM_AUTH_NEXT +message requests to send more auth data. +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_AUTH_NEXT (IM library \(<-\(-> IM Server) +.sp 6p +:2:n:length of authentication data +:2::unused +:n::data +:p::unused, p = Pad(n) +.TE +.RE +.LP +The auth data is specific to the authentication protocol in use. +.LP +The IM Server sends +.PN XIM_AUTH_SETUP +message to authenticate the client. +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_AUTH_SETUP (IM Server \(-> IM library) +.sp 6p +:2:CARD16:number of client-auth-protocol-names +:2::unused +:n:LISTofSTRING:server-auth-protocol-names +.TE +.RE +.LP +The list specifies the names of authentication protocols the +client is willing to perform. +.LP +.PN XIM_AUTH_NG +message requests to give up the connection. +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_AUTH_NG (IM library \(<-\(-> IM Server) +.TE +.RE +.LP +The IM Server sends +.PN XIM_CONNECT_REPLY +message as the reply to +.PN XIM_CONNECT +or +.PN XIM_AUTH_REQUIRED +message. +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_CONNECT_REPLY (IM Server \(-> IM library) +.sp 6p +:2:CARD16:server-major-protocol-version (*1) +:2:CARD16:server-minor-protocol-version (*1) +.TE +.LP +.IP (*1) +Specify the version of IM Protocol that the IM Server supports. +This document specifies major version one, minor version zero. +.RE +.sp +.LP +Here are the state diagrams for the client and the IM Server. +.sp +.B +State transitions for the client +.R +.RS +.LP +\fIinit_status\fP: +.RS +Use authorization function \(-> \fIclient_ask\fP +.br +Not use authorization function \(-> \fIclient_no_check\fP +.RE +.sp +.LP +\fIstart\fP: +.RS +Send +.PN XIM_CONNECT +.RS +If \fIclient_ask\fP \(-> \fIclient_wait1\fP +.br +If \fIclient_no_check\fP, client-auth-protocol-names may be omited \(-> \fIclient_wait2\fP +.RE +.RE +.sp +.LP +\fIclient_wait1\fP: +.RS +Receive +.PN XIM_AUTH_REQUIRED +\(-> \fIclient_check\fP +.br +Receive \(-> \fIclient_NG\fP +.RE +.sp +.LP +\fIclient_check\fP: +.RS +If no more auth needed, send +.PN XIM_AUTH_REPLY +\(-> \fIclient_wait2\fP +.br +If good auth data, send +.PN XIM_AUTH_NEXT +\(-> \fIclient_wait1\fP +.br +If bad auth data, send +.PN XIM_AUTH_NG +\(-> give up on this protocol +.RE +.sp +.LP +\fIclient_wait2\fP: +.RS +Receive +.PN XIM_CONNECT_REPLY +\(-> connect +.br +Receive +.PN XIM_AUTH_SETUP +\(-> \fIclient_more\fP +.br +Receive +.PN XIM_AUTH_NEXT +\(-> \fIclient_more\fP +.br +Receive +.PN XIM_AUTH_NG +\(-> give up on this protocol +.br +Receive \(-> \fIclient_NG\fP +.RE +.sp +.LP +\fIclient_more\fP: +.RS +Send +.PN XIM_AUTH_REQUIRED +\(-> \fIclient_wait2\fP +.RE +.sp +.LP +\fIclient_NG\fP: +.RS +Send +.PN XIM_AUTH_NG +\(-> give up on this protocol +.RE +.RE +.sp +.LP +.B +State transitions for the IM Server +.R +.RS +.LP +\fIinit-status\fP: +.RS +Use authorization function \(-> \fIserver_ask\fP +.br +Not use authorization function \(-> \fIserver_no_check\fP +.RE +.sp +.LP +\fIstart\fP: +.RS +Receive +.PN XIM_CONNECT +\(-> \fIstart2\fP +.br +Receive \(-> \fIserver_NG\fP +.RE +.sp +.LP +\fIstart2\fP: +.RS +If \fIclient_ask\fP, send +.PN XIM_AUTH_REQUIRED +\(-> \fIserver_wait1\fP +.br +If \fIclient_no_check\fP and \fIserver_ask\fP, send +.PN XIM_AUTH_SETUP +\(-> \fIserver_wait2\fP +.br +If \fIclient_no_check\fP and \fIserver_no_check\fP, send +.PN XIM_CONNECT_REPLY +\(-> connect +.RE +.sp +.LP +\fIserver_wait1\fP: +.RS +Receive +.PN XIM_AUTH_REPLY +\(-> \fIserver2\fP +.br +Receive +.PN XIM_AUTH_NEXT +\(-> \fIserver_more\fP +.br +Receive \(-> \fIserver_NG\fP +.RE +.sp +.LP +\fIserver_more\fP +.RS +Send +.PN XIM_AUTH_REQUIRED +\(-> \fIserver_wait1\fP +.RE +.sp +.LP +\fIserver2\fP +.RS +If \fIserver_ask\fP, send +.PN XIM_AUTH_SETUP +\(-> \fIserver_wait2\fP +.br +If \fIserver_no_check\fP, send +.PN XIM_CONNECT_REPLY +\(-> connect +.RE +.sp +.LP +\fIserver_wait2\fP +.RS +Receive +.PN XIM_AUTH_REQUIRED +\(-> \fIserver_check\fP +.br +Receive \(-> \fIserver_NG\fP +.RE +.sp +.LP +\fIserver_check\fP +.RS +If no more auth data, send +.PN XIM_CONNECT_REPLY +\(-> connect +.br +If bad auth data, send +.PN XIM_AUTH_NG +\(-> give up on this protocol +.br +If good auth data, send +.PN XIM_AUTH_NEXT +\(-> \fIserver_wait2\fP +.RE +.sp +.LP +\fIserver_NG\fP +.RS +Send +.PN XIM_AUTH_NG +\(-> give up on this protocol +.RE +.RE +.sp +.LP +.PN XIM_DISCONNECT +message requests to shutdown the connection over a mutually-understood +virtual stream. +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_DISCONNECT (IM library \(-> IM Server) +.TE +.RE +.LP +.PN XIM_DISCONNECT +is a synchronous request. The IM library should wait until it receives +either an +.PN XIM_DISCONNECT_REPLY +packet or an +.PN XIM_ERROR +packet. +.LP +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_DISCONNECT_REPLY (IM Server \(-> IM library) +.TE +.RE +.LP +.PN XIM_OPEN +requests to establish a logical connection between the IM library and the IM +Server. +.LP +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_OPEN (IM library \(-> IM Server) +.sp 6p +:n:STR:locale name +:p::unused, p = Pad(n) +.TE +.RE +.LP +.PN XIM_OPEN +is a synchronous request. The IM library should wait until receiving +either an +.PN XIM_OPEN_REPLY +packet or an +.PN XIM_ERROR +packet. +.LP +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_OPEN_REPLY (IM Server \(-> IM library) +.sp 6p +:2:CARD16:input-method-ID +:2:n:byte length of IM attributes supported +:n:LISTofXIMATTR:IM attributes supported +:2:m:byte length of IC attributes supported +:2:CARD16:unused +:m:LISTofXICATTR: IC attributes supported +.TE +.RE +.LP +.PN XIM_OPEN_REPLY +message returns all supported IM and IC attributes in LISTofXIMATTR and +LISTofXICATTR. These IM and IC attribute IDs are used to reduce the amount +of data which must be transferred via the network. In addition, this +indicates to the IM library what kinds of IM/IC attributes can be used +in this session, and what types of data will be exchanged. This allows +the IM Server provider and application writer to support IM system +enhancements with new IM/IC attributes, without modifying Xlib. +The IC value for the separator of NestedList must be included in the +LISTofXICATTR. +.LP +.PN XIM_CLOSE +message requests to shutdown the logical connection between the IM library +and the IM Server. +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_CLOSE (IM library \(-> IM Server) +.sp 6p +:2:CARD16:input-method-ID +:2::unused +.TE +.RE +.LP +.PN XIM_CLOSE +is a synchronous request. The IM library should wait until receiving +either an +.PN XIM_CLOSE_REPLY +packet or an +.PN XIM_ERROR +packet. +.LP +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_CLOSE_REPLY (IM Server \(-> IM library) +.sp 6p +:2:CARD16:input-method-ID +:2::unused +.TE +.RE +.LP +.NH 2 +Event Flow Control +.XS +\*(SN Event Flow Control +.XE +.LP +An IM Server must send +.PN XIM_SET_EVENT_MASK +message to the IM library in order for events to be forwarded to the IM +Server, since the IM library initially doesn't forward any events to the +IM Server. In the protocol, the IM Server will specify masks of X events +to be forwarded and which need to be synchronized by the IM library. +.LP +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_SET_EVENT_MASK (IM Server \(-> IM library) +.sp 6p +:2:CARD16:input-method-ID +:2:CARD16:input-context-ID +:4:EVENTMASK:forward-event-mask (*1) +:4:EVENTMASK:synchronous-event-mask (*2) +.TE +.LP +.IP (*1) +Specify all the events to be forwarded to the IM Server by the IM library. +.IP (*2) +Specify the events to be forwarded with synchronous flag on by the IM library. +.RE +.sp +.LP +.PN XIM_SET_EVENT_MASK +is an asynchronous request. The event masks are valid immediately after +they are set until changed by another +.PN XIM_SET_EVENT_MASK +message. If input-context-ID is set to zero, the default value of the +input-method-ID will be changed to the event masks specified in the request. +That value will be used for the IC's which have no individual values. +.LP +Using the Dynamic Event Flow model, an IM Server sends +.PN XIM_REGISTER_TRIGGERKEYS +message to the IM library before sending +.PN XIM_OPEN_REPLY +message. +Or the IM library may suppose that the IM Server uses the Static Event Flow +model. +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_REGISTER_TRIGGERKEYS (IM Server \(-> IM library) +.sp 6p +:2:CARD16:input-method-ID +:2::unused +:4:n:byte length of on-keys +:n:LISTofXIMTRIGGERKEY:on-keys list +:4:m:byte length of off-keys +:m:LISTofXIMTRIGGERKEY:off-keys list +.TE +.RE +.LP +.PN XIM_REGISTER_TRIGGERKEYS +is an asynchronous request. +The IM Server notifys the IM library of on-keys and off-keys lists with +this message. +.LP +The IM library notifys the IM Server with +.PN XIM_TRIGGER_NOTIFY +message that a key event matching either on-keys or off-keys has been occurred. +.LP +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_TRIGGER_NOTIFY (IM library \(-> IM Server) +.sp 6p +:2:CARD16:input-method-ID +:2:CARD16:input-context-ID +:4:CARD32:flag +::#0:on-keys list +::#1:off-keys list +:4:CARD32:index of keys list +:4:EVENTMASK:client-select-event-mask (*1) +.TE +.LP +.IP (*1) +Specify the events currently selected by the IM library with XSelectInput. +.RE +.sp +.LP +.PN XIM_TRIGGER_NOTIFY +is a synchronous request. The IM library should wait until receiving +either an +.PN XIM_TRIGGER_NOTIFY_REPLY +packet or an +.PN XIM_ERROR +packet. +.LP +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_TRIGGER_NOTIFY_REPLY (IM Server \(-> IM library) +.sp 6p +:2:CARD16:input-method-ID +:2:CARD16:input-context-ID +.TE +.RE +.LP +.NH 2 +Encoding Negotiation +.XS +\*(SN Encoding Negotiation +.XE +.LP +.PN XIM_ENCODING_NEGOTIATION +message requests to decide which encoding to be sent across the wire. +When the negotiation fails, the fallback default encoding is Portable +Character Encoding. +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_ENCODING_NEGOTIATION (IM library \(-> IM Server).sp 6p +:2:CARD16:input-method-ID +:2:n:byte length of encodings listed by name +:n:LISTofSTR:list of encodings supported in the IM library. +:p::unused, p = Pad(n) +:2:m:byte length of encodings listed by detailed data +:2::unused +:m:LISTofENCODINGINFO:list of encordings supported in the IM library +.TE +.RE +.LP +The IM Server must choose one encoding from the list sent by the IM library. +If index of the encording determined is -1 to indicate that the negotiation +is failed, the fallback default encoding is used. +The message must be issued after sending +.PN XIM_OPEN +message via XOpenIM(). +The name of encoding may be registered with X Consortium. +.LP +.PN XIM_ENCODING_NEGOTIATION +is a synchronous request. The IM library should wait until receiving +either an +.PN XIM_ENCODING_NEGOTIATION_REPLY +packet or an +.PN XIM_ERROR +packet. +.LP +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_ENCODING_NEGOTIATION_REPLY (IM Server \(-> IM library) +.sp 6p +:2:CARD16:input-method-ID +:2:CARD16:category of the encoding determined. +::#0:name +::#1:detailed data +:2:INT16:index of the encoding determinated. +:2::unused +.TE +.RE +.LP +.NH 2 +Query the supported extension protocol list +.XS +\*(SN Query the supported extension protocol list +.XE +.LP +.PN XIM_QUERY_EXTENSION +message requests to query the IM extensions supported by the IM Server to +which the client is being connected. +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_QUERY_EXTENSION (IM library \(-> IM Server) +.sp 6p +:2:CARD16:input-method-ID +:2:n:T{ +byte length of extensions supported by the IM library +T} +:n:LISTofSTR:extensions supported by the IM library +:p::unused, p = Pad(n) +.TE +.RE +.LP +An example of a supported extension is FrontEnd. +The message must be issued after sending +.PN XIM_OPEN +message via XOpenIM(). +.LP +If n is 0, the IM library queries the IM Server for all extensions. +.LP +If n is not 0, the IM library queries whether the IM Server supports the +contents specified in the list. +.LP +If a client uses an extension request without previously having issued a +.PN XIM_QUERY_EXTENSION +message for that extension, the IM Server responds with a +.PN BadProtocol +error. If the IM Server encounters a request with an unknown MAJOR-OPCODE +or MINOR-OPCODE, it responds with a +.PN BadProtocol +error. +.LP +.PN XIM_QUERY_EXTENSION +is a synchronous request. The IM library should wait until receiving +either an +.PN XIM_QUERY_EXTENSION_REPLY +packet or an +.PN XIM_ERROR +packet. +.LP +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_QUERY_EXTENSION_REPLY (IM Server \(-> IM library) +.sp 6p +:2:CARD16:input-method-ID +:2:n:T{ +byte length of extensions supported by both the IM library and the IM Server +T} +:n:LISTofEXT:T{ +list of extensions supported by both the IM library and the IM Server +T} +.TE +.RE +.LP +.PN XIM_QUERY_EXTENSION_REPLY +message returns the list of extensions supported by both the IM library and +the IM Server. If the list passed in +.PN XIM_QUERY_EXTENSION +message is NULL, the IM Server returns the full list of extensions supported +by the IM Server. If the list is not NULL, the IM Server returns the +extensions in the list that are supported by the IM Server. +.LP +A zero-length string is not a valid extension name. The IM library should +disregard any zero-length strings that are returned in the extension list. +The IM library does not use the requests which are not supported by the IM +Server. +.LP +.NH 2 +Setting IM Values +.XS +\*(SN Setting IM Values +.XE +.LP +.PN XIM_SET_IM_VALUES +requests to set attributes to the IM. +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_SET_IM_VALUES (IM library \(-> IM Server) +.sp 6p +:2:CARD16:input-method-ID +:2:n:byte length of im-attribute +:n:LISTofXIMATTRIBUTE:im-attributes +.TE +.RE +.LP +The im-attributes in +.PN XIM_SET_IM_VALUES +message are specified as a LISTofXIMATTRIBUTE, specifying the attributes +to be set. Attributes other than the ones returned by +.PN XIM_OPEN_REPLY +message should not be specified. +.LP +.PN XIM_SET_IM_VALUES +is a synchronous request. The IM library should wait until receiving +either an +.PN XIM_SET_IM_VALUES_REPLY +packet or an +.PN XIM_ERROR +packet, because it must receive the error attribute if +.PN XIM_ERROR +message is returned. +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_SET_IM_VALUES_REPLY (IM Server \(-> IM library) +.sp 6p +:2:CARD16:input-method-ID +:2::unused +.TE +.RE +.LP +.PN XIM_SET_IM_VALUES_REPLY +message returns the input-method-ID to distinguish replies from multiple IMs. +.LP +.NH 2 +Getting IM Values +.XS +\*(SN getting IM Values +.XE +.LP +.PN XIM_GET_IM_VALUES +requests to query IM values supported by the IM Server currently being +connected. +.LP +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_GET_IM_VALUES (IM library \(-> IM Server) +.sp 6p +:2:CARD16:input-method-ID +:2:n:byte length of im-attribute-id +:n:LISTofCARD16:im-attribute-id +:p::unused, p=Pad(n) +.TE +.RE +.LP +.PN XIM_GET_IM_VALUES +is a synchronous request. The IM library should wait until it receives +either an +.PN XIM_GET_IM_VALUES_REPLY +packet or an +.PN XIM_ERROR +packet. +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_GET_IM_VALUES_REPLY (IM Server \(-> IM library) +.sp 6p +:2:CARD16:input-method-ID +:2:n:byte length of im-attributes returned +:n:LISTofXIMATTRIBUTE:im-attributes returned +.TE +.RE +.LP +The IM Server returns IM values with +.PN XIM_GET_IM_VALUES_REPLY +message. The order of the returned im-attribute values corresponds directly +to that of the list passed with the +.PN XIM_GET_IM_VALUES +message. +.LP +.NH 2 +Creating an IC +.XS +\*(SN Creating an IC +.XE +.LP +.PN XIM_CREATE_IC +message requests to create an IC. +.LP +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_CREATE_IC (IM library \(-> IM Server) +.sp 6p +:2:CARD16:input-method-ID +:2:n:byte length of ic-attributes +:n:LISTofXICATTRIBUTE:ic-attributes +.TE +.RE +.LP +The input-context-id is specified by the IM Server to identify the client +(IC). (It is not specified by the client in +.PN XIM_CREATE_IC +message.), and it should not be set to zero. +.LP +.PN XIM_CREATE_IC +is a synchronous request which returns the input-context-ID. +The IM library should wait until it receives either an +.PN XIM_CREATE_IC_REPLY +packet or an +.PN XIM_ERROR +packet. +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_CREATE_IC_REPLY (IM Server \(-> IM library) +.sp 6p +:2:CARD16:input-method-ID +:2:CARD16:input-context-ID +.TE +.RE +.LP +.NH 2 +Destroying the IC +.XS +\*(SN Destroying the IC +.XE +.LP +.PN XIM_DESTROY_IC +message requests to destroy the IC. +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_DESTROY_IC (IM library \(-> IM Server) +.sp 6p +:2:CARD16:input-method-ID +:2:CARD16:input-context-ID +.TE +.RE +.LP +.PN XIM_DESTROY_IC +is a synchronous request. The IM library should not free its resources +until it receives an +.PN XIM_DESTROY_IC_REPLY +message because +.PN XIM_DESTROY_IC +message may result in Callback packets such as +.PN XIM_PREEDIT_DRAW +and +.PN XIM_PREEDIT_DONE. +.LP +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_DESTROY_IC_REPLY (IM Server \(-> IM library) +.sp 6p +:2:CARD16:input-method-ID +:2:CARD16:input-context-ID +.TE +.RE +.LP +.NH 2 +Setting IC Values +.XS +\*(SN Setting IC Values +.XE +.LP +.PN XIM_SET_IC_VALUES +messages requests to set attributes to the IC. +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_SET_IC_VALUES (IM library \(-> IM Server) +.sp 6p +:2:CARD16:input-method-ID +:2:CARD16:input-context-ID +:2:n:byte length of ic-attributes +:2::unused +:n:LISTofXICATTRIBUTE:ic-attributes +.TE +.RE +.LP +The ic-attributes in +.PN XIM_SET_IC_VALUES +message are specified as a LISTofXICATTRIBUTE, specifying the attributes +to be set. Attributes other than the ones returned by +.PN XIM_OPEN_REPLY +message should not be specified. +.LP +.PN XIM_SET_IC_VALUES +is a synchronous request. The IM library should wait until receiving +either an +.PN XIM_SET_IC_VALUES_REPLY +packet or an +.PN XIM_ERROR +packet, because it must receive the error attribute if +.PN XIM_ERROR +message is returned. +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_SET_IC_VALUES_REPLY (IM Server \(-> IM library) +.sp 6p +:2:CARD16:input-method-ID +:2:CARD16:input-context-ID +.TE +.RE +.LP +.NH 2 +Getting IC Values +.XS +\*(SN Getting IC Values +.XE +.LP +.PN XIM_GET_IC_VALUES +message requests to query IC values supported by the IM Server currently +being connected. +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_GET_IC_VALUES (IM library \(-> IM Server) +.sp 6p +:2:CARD16:input-method-ID +:2:CARD16:input-context-ID +:2:n:byte length of ic-attribute-id +:n:LISTofCARD16:ic-attribute-id +:p::unused, p=Pad(2+n) +.TE +.RE +.LP +In LISTofCARD16, the appearance of the ic-attribute-id for the separator +of NestedList shows the end of the heading nested list. +.LP +.PN XIM_GET_IC_VALUES +is a synchronous request and returns each attribute with its values to +show the correspondence. The IM library should wait until receiving +either an +.PN XIM_GET_IC_VALUES_REPLY +packet or an +.PN XIM_ERROR +packet. +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_GET_IC_VALUES_REPLY (IM Server \(-> IM library) +.sp 6p +:2:CARD16:input-method-ID +:2:CARD16:input-context-ID +:2:n:byte length of ic-attribute +:2::unused +:n:LISTofXICATTRIBUTE:ic-attribute +.TE +.RE +.LP +.NH 2 +Setting IC Focus +.XS +\*(SN Setting IC Focus +.XE +.LP +.PN XIM_SET_IC_FOCUS +message requests to set the focus to the IC. +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_SET_IC_FOCUS (IM library \(-> IM Server) +.sp 6p +:2:CARD16:input-method-ID +:2:CARD16:input-context-ID +.TE +.RE +.LP +.PN XIM_SET_IC_FOCUS +is an asynchronous request. +.LP +.NH 2 +Unsetting IC Focus +.XS +\*(SN Unsetting IC Focus +.XE +.LP +.PN XIM_UNSET_IC_FOCUS +message requests to unset the focus to the focused IC. +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_UNSET_IC_FOCUS (IM library \(-> IM Server) +.sp 6p +:2:CARD16:input-method-ID +:2:CARD16:input-context-ID +.TE +.RE +.LP +.PN XIM_UNSET_IC_FOCUS +is an asynchronous request. +.LP +.NH 2 +Filtering Events +.XS +\*(SN Filtering Events +.XE +.LP +Event filtering is mainly provided for BackEnd method to allow input method +to capture X events transparently to clients. +.LP +X Events are forwarded by +.PN XIM_FORWARD_EVENT +message. +This message can be operated both synchronously and asynchronously. +If the requester sets the synchronous flag, the receiver must send +.PN XIM_SYNC_REPLY +message back to the requester when all the data processing is done. +.sp +.B +Protocol flow of BackEnd model +.R +.LP +.LP +With BackEnd method, the protocol flow can be classified into two +methods in terms of synchronization, depending on the synchronous-eventmask +of +.PN XIM_SET_EVENT_MASK +message. One can be called on-demand-synchronous method and another +can be called as full-synchronous method. +.LP +In on-demand-synchronous method, the IM library always receives +.PN XIM_FORWARD_EVENT +or +.PN XIM_COMMIT +message as a synchronous request. Also, the IM Server needs to synchronously +process the correspondent reply from the IM library and the following +.PN XIM_FORWARD_EVENT +message sent from the IM library when any of the event causes the IM Server +to send +.PN XIM_FORWARD_EVENT +or +.PN XIM_COMMIT +message to the IM library, so that the input service is consistent. If the +IM library gets the control back from the application after receiving the +synchronous request, the IM library replies for the synchronous request before +processing any of the events. In this time, the IM Server blocks +.PN XIM_FORWARD_EVENT +message which is sent by the IM library, and handles it after receiving the +reply. However, the IM Server handles the other protocols at any time. +.LP +In full-synchronous method, the IM library always sends +.PN XIM_FORWARD_EVENT +message to the IM Server as a synchronous request. Therefore, the reply to it +from the IM Server will be put between the +.PN XIM_FORWARD_EVENT +message and its +.PN XIM_SYNC_REPLY +message. +In case of sending +.PN XIM_FORWARD_EVENT +or +.PN XIM_COMMIT +message, the IM Server should set the synchronous flag off. Because the +synchronization can be done by the following +.PN XIM_SYNC_REPLY +message. +.sp +.LP +.B +Sample Protocol flow chart 1 +.R +.LP +Following chart shows one of the simplest protocol flow which only +deals with keyevents for preediting operation. +.LP +.\"====================== event flow figure start ===================== +\^... 0.425 6.888 6.3 10.296 +\^... 0.000i 3.408i 5.875i 0.000i +.nr 00 \n(.u +.nf +.PS 3.408i 5.875i +.br +.ps 11 +\h'3.125i'\v'0.496i'\D'l1.625i 0.250i' +.sp -1 +\h'4.647i'\v'0.756i'\D'l0.103i -0.010i' +.sp -1 +\h'4.655i'\v'0.706i'\D'l0.095i 0.040i' +.sp -1 +\h'3.125i'\v'1.221i'\D'l1.687i 0.188i' +.sp -1 +\h'4.710i'\v'1.423i'\D'l0.102i -0.014i' +.sp -1 +\h'4.715i'\v'1.373i'\D'l0.097i 0.036i' +.sp -1 +\h'4.750i'\v'0.971i'\D'l-1.625i 0.438i' +.sp -1 +\h'3.215i'\v'1.359i'\D'l-0.090i 0.050i' +.sp -1 +\h'3.228i'\v'1.407i'\D'l-0.103i 0.002i' +.sp -1 +\h'2.000i'\v'0.409i'\D'l1.000i 0.062i' +.sp -1 +\h'2.899i'\v'0.490i'\D'l0.101i -0.019i' +.sp -1 +\h'2.902i'\v'0.440i'\D'l0.098i 0.031i' +.sp -1 +\h'2.000i'\v'1.034i'\D'l1.000i 0.125i' +.sp -1 +\h'2.898i'\v'1.171i'\D'l0.102i -0.012i' +.sp -1 +\h'2.904i'\v'1.122i'\D'l0.096i 0.037i' +.sp -1 +\h'3.000i'\v'1.409i'\D'l-1.000i 0.062i' +.sp -1 +\h'2.098i'\v'1.440i'\D'l-0.098i 0.031i' +.sp -1 +\h'2.101i'\v'1.490i'\D'l-0.101i -0.019i' +.sp -1 +\h'1.125i'\v'1.846i'\l'-0.500i' +.sp -1 +\h'0.725i'\v'1.821i'\D'l-0.100i 0.025i' +.sp -1 +\h'0.725i'\v'1.871i'\D'l-0.100i -0.025i' +.sp -1 +\h'0.688i'\v'0.159i'\l'0.437i' +.sp -1 +\h'1.025i'\v'0.184i'\D'l0.100i -0.025i' +.sp -1 +\h'1.025i'\v'0.134i'\D'l0.100i 0.025i' +.sp -1 +\h'0.688i'\v'0.846i'\l'0.437i' +.sp -1 +\h'1.025i'\v'0.871i'\D'l0.100i -0.025i' +.sp -1 +\h'1.025i'\v'0.821i'\D'l0.100i 0.025i' +.sp -1 +\h'5.562i'\v'1.409i'\l'0.313i' +.sp -1 +\h'5.875i'\v'1.409i'\v'-.13m'\L'1.937i\(br'\v'.13m' +.sp -1 +\h'5.875i'\v'3.346i'\D'l-0.250i 0.000i' +.sp -1 +\h'5.725i'\v'3.321i'\D'l-0.100i 0.025i' +.sp -1 +\h'5.725i'\v'3.371i'\D'l-0.100i -0.025i' +.sp -1 +\h'2.062i'\v'2.096i'\l'0.875i' +.sp -1 +\h'2.837i'\v'2.121i'\D'l0.100i -0.025i' +.sp -1 +\h'2.837i'\v'2.071i'\D'l0.100i 0.025i' +.sp -1 +\h'3.000i'\v'0.034i'\v'-.13m'\L'3.374i\(br'\v'.13m' +.sp -1 +\h'4.875i'\v'0.034i'\v'-.13m'\L'3.374i\(br'\v'.13m' +.sp -1 +\h'2.013i'\v'2.871i'\D'l0.937i 0.250i' +.sp -1 +\h'2.847i'\v'3.119i'\D'l0.103i 0.002i' +.sp -1 +\h'2.860i'\v'3.071i'\D'l0.090i 0.050i' +.sp -1 +\h'3.062i'\v'3.134i'\D'l1.688i 0.187i' +.sp -1 +\h'4.648i'\v'3.335i'\D'l0.102i -0.014i' +.sp -1 +\h'4.653i'\v'3.285i'\D'l0.097i 0.036i' +.sp -1 +\h'3.062i'\v'2.533i'\D'l1.750i 0.213i' +.sp -1 +\h'4.710i'\v'2.759i'\D'l0.102i -0.013i' +.sp -1 +\h'4.716i'\v'2.709i'\D'l0.096i 0.037i' +.sp -1 +\h'3.062i'\v'2.096i'\l'1.750i' +.sp -1 +\h'4.712i'\v'2.121i'\D'l0.100i -0.025i' +.sp -1 +\h'4.712i'\v'2.071i'\D'l0.100i 0.025i' +.sp -1 +\h'4.812i'\v'2.284i'\l'-1.750i' +.sp -1 +\h'3.162i'\v'2.259i'\D'l-0.100i 0.025i' +.sp -1 +\h'3.162i'\v'2.309i'\D'l-0.100i -0.025i' +.sp -1 +\h'1.250i'\v'0.193i'\h'-0.0m'\v'0.2m'\s10\fRXNextEvent\fP +.sp -1 +\h'1.250i'\v'0.381i'\h'-0.0m'\v'0.2m'\s10\fRXFilterEvent\fP +.sp -1 +\h'1.250i'\v'0.881i'\h'-0.0m'\v'0.2m'\s10\fRXNextEvent\fP +.sp -1 +\h'1.250i'\v'1.068i'\h'-0.0m'\v'0.2m'\s10\fRXFilterEvent\fP +.sp -1 +\h'1.250i'\v'1.506i'\h'-0.0m'\v'0.2m'\s10\fRXNextEvent\fP +.sp -1 +\h'1.250i'\v'1.881i'\h'-0.0m'\v'0.2m'\s10\fRXmbLookupString\fP +.sp -1 +\h'4.875i'\h'-0.0m'\v'0.2m'\s12\fRIM Server\fP +.sp -1 +\h'2.437i'\h'-0.0m'\v'0.2m'\s12\fRIM library\fP +.sp -1 +\h'1.250i'\v'1.693i'\h'-0.0m'\v'0.2m'\s10\fRXFilterEvent (returns False) \fP +.sp -1 +\v'2.168i'\h'-0.0m'\v'0.2m'\s10\fRthe focus\fP +.sp -1 +\h'1.250i'\h'-0.0m'\v'0.2m'\s12\fRXlib API\fP +.sp -1 +\v'2.006i'\h'-0.0m'\v'0.2m'\s10\fRApplication moves\fP +.sp -1 +\h'3.187i'\v'0.443i'\h'-0.0m'\v'0.2m'\s10\fRXIM_FORWARD_EVENT\fP +.sp -1 +\h'3.187i'\v'0.881i'\h'-0.0m'\v'0.2m'\s10\fRXIM_FORWARD_EVENT\fP +.sp -1 +\h'3.187i'\v'1.631i'\h'-0.0m'\v'0.2m'\s10\fRXIM_FORWARD_EVENT\fP +.sp -1 +\h'3.187i'\v'1.006i'\h'-0.0m'\v'0.2m'\s10\fRor XIM_COMMIT\fP +.sp -1 +\h'5.000i'\v'0.881i'\h'-0.0m'\v'0.2m'\s10\fRsynchronous \fP +.sp -1 +\h'5.000i'\v'1.006i'\h'-0.0m'\v'0.2m'\s10\fRrequest\fP +.sp -1 +\h'0.062i'\v'0.193i'\h'-0.0m'\v'0.2m'\s10\fRKey event\fP +.sp -1 +\h'0.062i'\v'0.881i'\h'-0.0m'\v'0.2m'\s10\fRKey event\fP +.sp -1 +\h'3.187i'\v'1.131i'\h'-0.0m'\v'0.2m'\s10\fR(synchronous) \fP +.sp -1 +\h'5.000i'\v'1.443i'\h'-0.0m'\v'0.2m'\s10\fRPending\fP +.sp -1 +\h'5.000i'\v'2.381i'\h'-0.0m'\v'0.2m'\s10\fRprocessed\fP +.sp -1 +\h'5.000i'\v'2.506i'\h'-0.0m'\v'0.2m'\s10\fR(The focused\fP +.sp -1 +\h'5.000i'\v'2.631i'\h'-0.0m'\v'0.2m'\s10\fRIC is changed) \fP +.sp -1 +\h'5.000i'\v'2.881i'\h'-0.0m'\v'0.2m'\s10\fRprocessed\fP +.sp -1 +\h'1.250i'\v'2.131i'\h'-0.0m'\v'0.2m'\s10\fRXSetICFocus\fP +.sp -1 +\h'3.125i'\v'2.881i'\h'-0.0m'\v'0.2m'\s10\fRXIM_SYNC_REPLY as a reply\fP +.sp -1 +\h'3.125i'\v'3.043i'\h'-0.0m'\v'0.2m'\s10\fRof the XIM_FORWARD_EVENT\fP +.sp -1 +\h'1.250i'\v'2.881i'\h'-0.0m'\v'0.2m'\s10\fRXNextEvent\fP +.sp -1 +\h'3.312i'\v'2.506i'\h'-0.0m'\v'0.2m'\s10\fRXIM_SET_IC_FOCUS\fP +.sp -1 +\h'3.312i'\v'2.006i'\h'-0.0m'\v'0.2m'\s10\fRXIM_SYNC\fP +.sp -1 +\h'3.312i'\v'2.193i'\h'-0.0m'\v'0.2m'\s10\fRXIM_SYNC_REPLY\fP +.sp -1 +\h'5.000i'\v'3.381i'\h'-0.0m'\v'0.2m'\s10\fRprocessed\fP +.sp -1 +.sp 1+3.408i +.PE +.if \n(00 .fi + +.\"====================== event flow figure end ======================= +.ce +.sp +Fig.2 Sample Protocol Flow +.sp +.LP +.B +Sample Protocol flow chart 2 +.R +.LP +Following chart shows one of the complex protocol flow, which deals +with multiple focus windows and button press event as well as keyevent, +and the focus is moved by the application triggered by both of keyevent +and button press event. +.LP +.bp +.\"====================== event2 flow figure start ===================== +\^... 0.425 5.575 6.3 10.296 +\^... 0.000i 4.721i 5.875i 0.000i +.nr 00 \n(.u +.nf +.PS 4.721i 5.875i +.br +.ps 11 +\h'3.125i'\v'0.496i'\D'l1.625i 0.163i' +.sp -1 +\h'4.648i'\v'0.674i'\D'l0.102i -0.015i' +.sp -1 +\h'4.653i'\v'0.624i'\D'l0.097i 0.035i' +.sp -1 +\h'2.000i'\v'0.409i'\D'l1.000i 0.062i' +.sp -1 +\h'2.899i'\v'0.490i'\D'l0.101i -0.019i' +.sp -1 +\h'2.902i'\v'0.440i'\D'l0.098i 0.031i' +.sp -1 +\h'0.688i'\v'0.159i'\l'0.437i' +.sp -1 +\h'1.025i'\v'0.184i'\D'l0.100i -0.025i' +.sp -1 +\h'1.025i'\v'0.134i'\D'l0.100i 0.025i' +.sp -1 +\h'1.250i'\v'0.193i'\h'-0.0m'\v'0.2m'\s10\fRXNextEvent\fP +.sp -1 +\h'1.250i'\v'0.381i'\h'-0.0m'\v'0.2m'\s10\fRXFilterEvent\fP +.sp -1 +\h'3.187i'\v'0.443i'\h'-0.0m'\v'0.2m'\s10\fRXIM_FORWARD_EVENT\fP +.sp -1 +\h'0.062i'\v'0.193i'\h'-0.0m'\v'0.2m'\s10\fRKey event\fP +.sp -1 +\h'3.125i'\v'1.221i'\D'l1.687i 0.125i' +.sp -1 +\h'4.710i'\v'1.364i'\D'l0.102i -0.018i' +.sp -1 +\h'4.714i'\v'1.314i'\D'l0.098i 0.032i' +.sp -1 +\h'4.750i'\v'0.971i'\D'l-1.625i 0.750i' +.sp -1 +\h'3.205i'\v'1.656i'\D'l-0.080i 0.065i' +.sp -1 +\h'3.226i'\v'1.702i'\D'l-0.101i 0.019i' +.sp -1 +\h'2.000i'\v'1.034i'\D'l1.000i 0.125i' +.sp -1 +\h'2.898i'\v'1.171i'\D'l0.102i -0.012i' +.sp -1 +\h'2.904i'\v'1.122i'\D'l0.096i 0.037i' +.sp -1 +\h'0.688i'\v'0.846i'\l'0.437i' +.sp -1 +\h'1.025i'\v'0.871i'\D'l0.100i -0.025i' +.sp -1 +\h'1.025i'\v'0.821i'\D'l0.100i 0.025i' +.sp -1 +\h'3.000i'\v'0.034i'\v'-.13m'\L'4.687i\(br'\v'.13m' +.sp -1 +\h'0.750i'\v'1.346i'\l'0.313i' +.sp -1 +\h'0.963i'\v'1.371i'\D'l0.100i -0.025i' +.sp -1 +\h'0.963i'\v'1.321i'\D'l0.100i 0.025i' +.sp -1 +\h'3.125i'\v'1.509i'\D'l1.687i 0.125i' +.sp -1 +\h'4.710i'\v'1.652i'\D'l0.102i -0.018i' +.sp -1 +\h'4.714i'\v'1.602i'\D'l0.098i 0.032i' +.sp -1 +\h'4.812i'\v'1.721i'\D'l-1.687i 0.188i' +.sp -1 +\h'3.222i'\v'1.873i'\D'l-0.097i 0.036i' +.sp -1 +\h'3.227i'\v'1.923i'\D'l-0.102i -0.014i' +.sp -1 +\h'2.937i'\v'1.971i'\D'l-0.937i 0.188i' +.sp -1 +\h'2.093i'\v'2.115i'\D'l-0.093i 0.044i' +.sp -1 +\h'2.103i'\v'2.164i'\D'l-0.103i -0.005i' +.sp -1 +\h'1.125i'\v'2.533i'\l'-0.500i' +.sp -1 +\h'0.725i'\v'2.508i'\D'l-0.100i 0.025i' +.sp -1 +\h'0.725i'\v'2.558i'\D'l-0.100i -0.025i' +.sp -1 +\h'5.562i'\v'1.346i'\l'0.313i' +.sp -1 +\h'5.875i'\v'1.346i'\v'-.13m'\L'2.687i\(br'\v'.13m' +.sp -1 +\h'5.875i'\v'4.033i'\D'l-0.250i 0.000i' +.sp -1 +\h'5.725i'\v'4.008i'\D'l-0.100i 0.025i' +.sp -1 +\h'5.725i'\v'4.058i'\D'l-0.100i -0.025i' +.sp -1 +\h'2.013i'\v'3.559i'\D'l0.937i 0.250i' +.sp -1 +\h'2.847i'\v'3.807i'\D'l0.103i 0.002i' +.sp -1 +\h'2.860i'\v'3.759i'\D'l0.090i 0.050i' +.sp -1 +\h'3.062i'\v'3.821i'\D'l1.688i 0.188i' +.sp -1 +\h'4.648i'\v'4.023i'\D'l0.102i -0.014i' +.sp -1 +\h'4.653i'\v'3.973i'\D'l0.097i 0.036i' +.sp -1 +\h'2.000i'\v'1.358i'\D'l1.000i 0.126i' +.sp -1 +\h'2.898i'\v'1.496i'\D'l0.102i -0.012i' +.sp -1 +\h'2.904i'\v'1.447i'\D'l0.096i 0.037i' +.sp -1 +\h'3.062i'\v'2.159i'\D'l-0.250i 0.000i' +.sp -1 +\h'2.812i'\v'2.159i'\v'-.13m'\L'1.812i\(br'\v'.13m' +.sp -1 +\h'2.812i'\v'3.971i'\D'l0.125i 0.125i' +.sp -1 +\h'2.849i'\v'4.043i'\D'l0.088i 0.053i' +.sp -1 +\h'2.884i'\v'4.008i'\D'l0.053i 0.088i' +.sp -1 +\h'2.062i'\v'2.783i'\l'0.875i' +.sp -1 +\h'2.837i'\v'2.808i'\D'l0.100i -0.025i' +.sp -1 +\h'2.837i'\v'2.758i'\D'l0.100i 0.025i' +.sp -1 +\h'2.062i'\v'3.783i'\D'l0.813i 0.438i' +.sp -1 +\h'2.775i'\v'4.196i'\D'l0.100i 0.025i' +.sp -1 +\h'2.799i'\v'4.152i'\D'l0.076i 0.069i' +.sp -1 +\h'0.625i'\v'3.533i'\l'0.438i' +.sp -1 +\h'0.963i'\v'3.558i'\D'l0.100i -0.025i' +.sp -1 +\h'0.963i'\v'3.508i'\D'l0.100i 0.025i' +.sp -1 +\h'3.062i'\v'4.346i'\D'l1.625i 0.163i' +.sp -1 +\h'4.585i'\v'4.524i'\D'l0.102i -0.015i' +.sp -1 +\h'4.590i'\v'4.474i'\D'l0.097i 0.035i' +.sp -1 +\h'4.875i'\v'0.034i'\v'-.13m'\L'4.687i\(br'\v'.13m' +.sp -1 +\h'3.062i'\v'4.146i'\D'l1.688i 0.187i' +.sp -1 +\h'4.648i'\v'4.347i'\D'l0.102i -0.014i' +.sp -1 +\h'4.653i'\v'4.297i'\D'l0.097i 0.036i' +.sp -1 +\h'3.062i'\v'2.871i'\D'l1.750i 0.212i' +.sp -1 +\h'4.710i'\v'3.096i'\D'l0.102i -0.013i' +.sp -1 +\h'4.716i'\v'3.046i'\D'l0.096i 0.037i' +.sp -1 +\h'1.250i'\v'0.881i'\h'-0.0m'\v'0.2m'\s10\fRXNextEvent\fP +.sp -1 +\h'1.250i'\v'1.068i'\h'-0.0m'\v'0.2m'\s10\fRXFilterEvent\fP +.sp -1 +\h'4.875i'\h'-0.0m'\v'0.2m'\s12\fRIM Server\fP +.sp -1 +\h'2.437i'\h'-0.0m'\v'0.2m'\s12\fRIM library\fP +.sp -1 +\h'1.250i'\h'-0.0m'\v'0.2m'\s12\fRXlib API\fP +.sp -1 +\h'3.187i'\v'0.881i'\h'-0.0m'\v'0.2m'\s10\fRXIM_FORWARD_EVENT\fP +.sp -1 +\h'5.000i'\v'0.881i'\h'-0.0m'\v'0.2m'\s10\fRsynchronous \fP +.sp -1 +\h'5.000i'\v'1.006i'\h'-0.0m'\v'0.2m'\s10\fRrequest\fP +.sp -1 +\h'0.062i'\v'0.881i'\h'-0.0m'\v'0.2m'\s10\fRKey event\fP +.sp -1 +\h'3.187i'\v'1.131i'\h'-0.0m'\v'0.2m'\s10\fR(synchronous) \fP +.sp -1 +\h'0.062i'\v'1.256i'\h'-0.0m'\v'0.2m'\s10\fRButton press causes\fP +.sp -1 +\h'0.062i'\v'1.381i'\h'-0.0m'\v'0.2m'\s10\fRfocus change\fP +.sp -1 +\h'1.250i'\v'1.381i'\h'-0.0m'\v'0.2m'\s10\fRXSetICFocus\fP +.sp -1 +\h'3.250i'\v'1.006i'\h'-0.0m'\v'0.2m'\s10\fRor XIM_COMMIT\fP +.sp -1 +\h'3.187i'\v'1.443i'\h'-0.0m'\v'0.2m'\s10\fRXIM_FORWARD_EVENT\fP +.sp -1 +\h'3.687i'\v'1.693i'\h'-0.0m'\v'0.2m'\s10\fRXIM_SYNC\fP +.sp -1 +\h'3.375i'\v'2.006i'\h'-0.0m'\v'0.2m'\s10\fRXIM_SYNC_REPLY\fP +.sp -1 +\h'1.250i'\v'2.193i'\h'-0.0m'\v'0.2m'\s10\fRXNextEvent\fP +.sp -1 +\h'1.250i'\v'2.568i'\h'-0.0m'\v'0.2m'\s10\fRXmbLookupString\fP +.sp -1 +\h'1.250i'\v'2.381i'\h'-0.0m'\v'0.2m'\s10\fRXFilterEvent (returns False) \fP +.sp -1 +\v'2.856i'\h'-0.0m'\v'0.2m'\s10\fRthe focus\fP +.sp -1 +\v'2.693i'\h'-0.0m'\v'0.2m'\s10\fRApplication moves\fP +.sp -1 +\h'5.000i'\v'3.068i'\h'-0.0m'\v'0.2m'\s10\fRprocessed\fP +.sp -1 +\h'5.000i'\v'3.193i'\h'-0.0m'\v'0.2m'\s10\fR(The focused\fP +.sp -1 +\h'5.000i'\v'3.318i'\h'-0.0m'\v'0.2m'\s10\fRIC is changed) \fP +.sp -1 +\h'5.000i'\v'3.568i'\h'-0.0m'\v'0.2m'\s10\fRprocessed\fP +.sp -1 +\h'3.125i'\v'3.568i'\h'-0.0m'\v'0.2m'\s10\fRXIM_SYNC_REPLY as a reply\fP +.sp -1 +\h'3.125i'\v'3.731i'\h'-0.0m'\v'0.2m'\s10\fRof the XIM_FORWARD_EVENT\fP +.sp -1 +\h'1.250i'\v'3.568i'\h'-0.0m'\v'0.2m'\s10\fRXNextEvent\fP +.sp -1 +\h'5.000i'\v'4.068i'\h'-0.0m'\v'0.2m'\s10\fRprocessed\fP +.sp -1 +\h'5.000i'\v'1.381i'\h'-0.0m'\v'0.2m'\s10\fRPending\fP +.sp -1 +\h'5.000i'\v'4.256i'\h'-0.0m'\v'0.2m'\s10\fRprocessed\fP +.sp -1 +\h'1.250i'\v'2.818i'\h'-0.0m'\v'0.2m'\s10\fRXSetICFocus\fP +.sp -1 +\h'3.125i'\v'2.443i'\h'-0.0m'\v'0.2m'\s10\fRis started by XIM_COMMIT\fP +.sp -1 +\h'3.125i'\v'2.193i'\h'-0.0m'\v'0.2m'\s10\fRXIM_SET_IC_FOCUS is\fP +.sp -1 +\h'3.125i'\v'2.318i'\h'-0.0m'\v'0.2m'\s10\fRpend because another sync cycle\fP +.sp -1 +\h'2.062i'\v'1.693i'\h'-0.0m'\v'0.2m'\s10\fRsync cycle is done\fP +.sp -1 +\h'2.062i'\v'1.568i'\h'-0.0m'\v'0.2m'\s10\fRPending until\fP +.sp -1 +\v'3.568i'\h'-0.0m'\v'0.2m'\s10\fRKey event\fP +.sp -1 +\h'1.250i'\v'3.756i'\h'-0.0m'\v'0.2m'\s10\fRXFilterEvent\fP +.sp -1 +\h'3.125i'\v'4.631i'\h'-0.0m'\v'0.2m'\s10\fRXIM_FORWARD_EVENT\fP +.sp -1 +\h'3.375i'\v'4.131i'\h'-0.0m'\v'0.2m'\s10\fRXIM_SET_IC_FOCUS\fP +.sp -1 +\h'3.250i'\v'2.818i'\h'-0.0m'\v'0.2m'\s10\fRXIM_SET_IC_FOCUS\fP +.sp -1 +.sp 1+4.721i +.PE +.if \n(00 .fi + +.\"====================== event2 flow figure end ======================= +.ce +.sp +Fig.3 Sample Protocol Flow chart +.LP +.LP +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_FORWARD_EVENT (IM library \(<-\(-> IM Server) +.sp 6p +:2:CARD16:input-method-ID +:2:CARD16:input-context-ID +:2:BITMASK16:flag +::#0001:synchronous +::#0002:request filtering (*1) +::#0004:request lookupstring (*2) +:2:CARD16:serial number +::XEVENT:X event +.TE +.LP +.IP (*1) +Indicate the receiver should filter events and possible preedit may be invoked. +.IP (*2) +Indicate the receiver should only do lookup string. The IM Server is expected +to just do a conversion of the key event to the best candidate. This bit may +affect the state of the preedit state (e.g. compose of dead key sequences). +.RE +.LP +XEVENT format is same as the X Protocol event format(xEvent). +As the value of xEvent's sequenceNumber is the bottom of 16 bit of XEvent's +xany.serial, the top of 16 bit is sent by serial number(INT16). +.LP +.PN XIM_FORWARD_EVENT +message is used for forwarding the events from the IM library to the IM Server +in order for IM to be able to filter the event. On the other hand, this +message is also used for forwarding the events from the IM Server to the IM +library if the event forwarded from the IM library is not filtered. +The IM Server, which receives +.PN XIM_FORWARD_EVENT +message without synchronous bit, should set synchronous bit. +If both ``request event filtering'' and ``request lookupstring'' flag are +set, then both filtering and lookup should be done for the same event. +.LP +.NH 2 +Synchronizing with the IM Server +.XS +\*(SN Synchronizing with the IM Server +.XE +.LP +.PN XIM_SYNC +message requests to synchronize the IM library and the IM Server. +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_SYNC (IM library \(<-\(-> IM Server) +.sp 6p +:2:CARD16:input-method-ID +:2:CARD16:input-context-ID +.TE +.RE +.LP +This synchronization can be started either on the IM library side or on the +IM Server side. The side which receives +.PN XIM_SYNC +message should process all XIM requests before replying. The input-context-ID +is necessary to distinguish the IC with which the IM library and the IM +Server are synchronized. +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_SYNC_REPLY (IM Server \(<-\(-> IM library) +.sp 6p +:2:CARD16:input-method-ID +:2:CARD16:input-context-ID +.TE +.RE +.LP +The side which receives +.PN XIM_FORWARD_EVENT, +.PN XIM_COMMIT +or any other message with synchronous bit, should process all XIM request +before replying, and send +.PN XIM_SYNC_REPLY +message as the reply to the previous message. +.LP +.NH 2 +Sending a committed string +.XS +\*(SN Sending a committed string +.XE +.LP +When the IM Server commits a string, the IM Server sends either the committed +string or list of KeySym, or both, by +.PN XIM_COMMIT +message. +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_COMMIT (IM Server \(-> IM library) +.sp 6p +:2:CARD16:input-method-ID +:2:CARD16:input-context-ID +:2:BITMASK16:flag +::#0001:synchronous +::#0002:XLookupChars +::#0004:XLookupKeySym +::#0006: XLookupBoth = XLookupChars | XLookupKeySym +.TE +.LP +If flag is XLookupKeySym, the arguments continue as follows: +.TS +tab(:); +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +:2::unused +:4:KEYSYM:KeySym +.TE +.LP +If flag is XLookupChars, the arguments continue as follows: +.TS +tab(:); +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +:2:m:byte length of committed string +:m:LISTofBYTE:committed string +:p::unused, p = Pad(m) +.TE +.LP +If flag is XLookupBoth, the arguments continue as follows: +.TS +tab(:); +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +:2::unused +:4:KEYSYM:KeySym +:2:n:byte length of committed string +:n:LISTofBYTE:committed string +:p::unused, p = Pad(2+n) +.TE +.RE +.LP +The IM Server which receives +.PN XIM_COMMIT +message without synchronous bit should set synchronous bit. +.LP +.NH 2 +Reset IC +.XS +\*(SN Reset IC +.XE +.LP +.PN XIM_RESET_IC +message requests to reset the status of IC in the IM Server. +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_RESET_IC (IM library \(-> IM Server) +.sp 6p +:2:CARD16:input-method-ID +:2:CARD16:input-context-ID +.TE +.RE +.LP +.PN XIM_RESET_IC +is a synchronous request. The IM library should wait until receiving either an +.PN XIM_RESET_IC_REPLY +packet or an +.PN XIM_ERROR +packet. +.LP +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_RESET_IC_REPLY (IM Server \(-> IM library) +.sp 6p +:2:CARD16:input-method-ID +:2:CARD16:input-context-ID +:2:n:byte length of preedit string +:n:LISTofBYTE:preedit string +:p::unused, p = Pad(2+n) +.TE +.RE +.LP +.PN XIM_RESET_IC_REPLY +message returns the input-context-ID to distinguish replies from multiple ICs. +.LP +.\"============================== Callbacks =============================== +.NH 2 +Callbacks +.XS +\*(SN Callbacks +.XE +.LP +If XIMStyle has XIMPreeditArea or XIMStatusArea set, XIMGeometryCallback +may be used, and if XIMPreeditCallback and/or XIMStatusCallback are set, +corresponding callbacks may be used. +.LP +Any callback request may be sent from an IM Server to an IM client +asynchronously in response to any request previously sent by the IM client +to the IM Server. +.LP +When an IM Server needs to send a callback request synchronously with +the request previously sent by an IM client, the IM Server sends it +before replying to the previous request. +.LP +.NH 3 +Negotiating geometry +.XS +\*(SN Negotiating geometry +.XE +.LP +The IM Server sends +.PN XIM_GEOMETRY +message to start geometry negotiation, if XIMStyle has XIMPreeditArea or +XIMStatusArea set. +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_GEOMETRY (IM Server \(-> IM library) +.sp 6p +:2:CARD16:input-method-ID +:2:CARD16:input-context-ID +.TE +.RE +.LP +There is always a single Focus Window, even if some input fields have only +one IC. +.LP +.NH 3 +Converting a string +.XS +\*(SN Converting a string +.XE +.LP +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_STR_CONVERSION (IM Server \(-> IM library) +.sp 6p +:2:CARD16:input-method-ID +:2:CARD16:input-context-ID +:2:CARD16:XIMStringConversionPosition +:2::unused +:4:CARD32:XIMCaretDirection +::#0:XIMForwardChar +::#1:XIMBackwardChar +::#2:XIMForwardWord +::#3:XIMBackwardWord +::#4:XIMCaretUp +::#5:XIMCaretDown +::#6:XIMNextLine +::#7:XIMCPreviousLine +::#8:XIMLineStart +::#9:XIMLineEnd +::#10:XIMAbsolutePosition +::#11:XIMDontChange +:2:CARD16:factor +:2:CARD16:XIMStringConversionOperation +::#0001:XIMStringConversionSubstitution +::#0002:XIMStringConversionRetrieval +:2:INT16:T{ +byte length to multiply the XIMStringConversionType +T} +.TE +.RE +.sp +.LP +.PN XIM_STR_CONVERSION +message may be used to start the string conversion from the IM +Server. +.LP +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_STR_CONVERSION_REPLY (IM library \(-> IM Server) +.sp 6p +:2:CARD16:input-method-ID +:2:CARD16:input-context-ID +:4:CARD32:XIMStringConversionFeedback +::XIMSTRCONVTEXT:XIMStringConversionText +.sp +.TE +.RE +.LP +.PN XIM_STR_CONVERSION_REPLY +message returns the string to be converted and the feedback information array. +.LP +.NH 3 +Preedit Callbacks +.XS +\*(SN Preedit Callbacks +.XE +.LP +The IM Server sends +.PN XIM_PREEDIT_START +message to call the XIMPreeditStartCallback function. +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_PREEDIT_START (IM Server \(-> IM library) +.sp 6p +:2:CARD16:input-method-ID +:2:CARD16:input-context-ID +.TE +.RE +.LP +The reply to this message must be sent synchronously. The reply forwards +the return value from the callback function to the IM Server. +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_PREEDIT_START_REPLY (IM library \(-> IM Server) +.sp 6p +:2:CARD16:input-method-ID +:2:CARD16:input-context-ID +:4:INT32:return value +.TE +.RE +.LP +.PN XIM_PREEDIT_START_REPLY +message returns the input-context-ID to distinguish replies from multiple +IC's. The return value contains the return value of the function +XIMPreeditStartCallback. +.LP +The IM Server sends +.PN XIM_PREEDIT_DRAW +message to call the XIMPreeditDrawCallback function. +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_PREEDIT_DRAW (IM Server \(-> IM library) +.sp 6p +:2:CARD16:input-method-ID +:2:CARD16:input-context-ID +:4:INT32:caret +:4:INT32:chg_first +:4:INT32:chg_length +:4:BITMASK32:status +::#x0000001:no string +::#x0000002:no feedback +:2:n:length of preedit string +:n:STRING8:preedit string +:p::unused, p = Pad(2+n) +:2:m:byte length of feedback array +:2::unused +:m:LISTofXIMFEEDBACK:feedback array +.TE +.RE +.LP +The fields ``caret'', ``chg_first'' and ``chg_length'' correspond to the +fields of XIMPreeditDrawCallbackStruct. +When the ``no string'' bit of the status field is set, the text field of +XIMPreeditDrawCallbackStruct is NULL. +When the ``no feedback'' bit of the status field is set, the text feedback +field of XIMPreeditDrawCallbackStruct is NULL. +When the above bits are not set, ``preedit string'' contains the preedit +string to be displayed, and the feedback array contains feedback information. +.LP +The IM Server sends +.PN XIM_PREEDIT_CARET +message to call the PreeditCaretCallback function. +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_PREEDIT_CARET (IM Server \(-> IM library) +.sp 6p +:2:CARD16:input-method-ID +:2:CARD16:input-context-ID +:4:INT32:position +:4:CARD32:direction +::#0:XIMForwardChar +::#1:XIMBackwardChar +::#2:XIMForwardWord +::#3:XIMBackwardWord +::#4:XIMCaretUp +::#5:XIMCaretDown +::#6:XIMNextLine +::#7:XIMCPreviousLine +::#8:XIMLineStart +::#9:XIMLineEnd +::#10:XIMAbsolutePosition +::#11:XIMDontChange +:4:CARD32:style +::#0:XIMInvisible +::#1:XIMCPrimary +::#2:XIMSecondary +.TE +.RE +.LP +Each entry corresponds to a field of XIMPreeditCaretCallbackStruct. +Since this callback sets the caret position, its reply must be sent +synchronously. +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_PREEDIT_CARET_REPLY (IM library \(-> IM Server) +.sp 6p +:2:CARD16:input-method-ID +:2:CARD16:input-context-ID +:4:CARD32:position +.TE +.RE +.LP +The position is the value returned by the callback function after it +has been called. +.LP +The IM Server sends +.PN XIM_PREEDIT_DONE +message to call the XIMPreeditDoneCallback function. +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_PREEDIT_DONE (IM Server \(-> IM library) +.sp 6p +:2:CARD16:input-method-ID +:2:CARD16:input-context-ID +.TE +.RE +.LP +.NH 3 +Preedit state notify +.XS +\*(SN Preedit state notify +.XE +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_PREEDITSTATE (IM Server \(-> IM Library) +.sp 6p +:2:CARD16:input-method-ID +:2:CARD16:input-context-ID +:4:BITMASK32:XIMPreeditState +::#x0000000:XIMPreeditUnknown +::#x0000001:XIMPreeditEnable +::#x0000002:XIMPreeditDisable +.TE +.sp +.TE +.RE +.LP +.PN XIM_PREEDITSTATE +message is used to call the XIMPreeditStateNotifyCallback function. +.LP +.NH 3 +Status Callbacks +.XS +\*(SN Status Callbacks +.XE +.LP +The IM Server sends +.PN XIM_STATUS_START +message to call the XIMStatusStartCallback function. +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_STATUS_START (IM Server \(-> IM library) +.sp 6p +:2:CARD16:input-method-ID +:2:CARD16:input-context-ID +.TE +.RE +.LP +The IM Server sends +.PN XIM_STATUS_DRAW +message to call the XIMStatusDrawCallback function. +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_STATUS_DRAW (IM Server \(-> IM library) +.sp 6p +:2:CARD16:input-method-ID +:2:CARD16:input-context-ID +:4:CARD32:type +::#0:XIMTextType +::#1:XIMBitmapType +.TE +.LP +If type is XIMTextType, the arguments continue as follows. +.TS +tab(:); +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +:4:BITMASK32:status +::#x0000001:no string +::#x0000002:no feedback +:2:n:length of status string +:n:STRING8:status string +:p::unused, p = Pad(2+n) +:2:m:byte length of feedback array +:2::unused +:m:LISTofXIMFEEDBACK:feedback array +.TE +.LP +If type is XIMBitmapType, the arguments continue as follows. +.TS +tab(:); +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +:4:PIXMAP:pixmap data +.TE +.RE +.LP +The field ``type'' corresponds to the field in XIMStatusDrawCallbackStruct. +.LP +The IM Server sends +.PN XIM_STATUS_DONE +message to call the XIMStatusDoneCallback function. +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_STATUS_DONE (IM Server \(-> IM library) +.sp 6p +:2:CARD16:input-method-ID +:2:CARD16:input-context-ID +.TE +.RE +.LP +.bp +.NH 1 +Acknowledgements +.XS +\*(SN Acknowledgements +.XE +.LP +This document represents the culmination of several years of debate and +experiments done under the auspices of the MIT X Consortium i18n working +group. Although this was a group effort, the author remains responsible +for any errors or omissions. +.LP +We would like to thank to all members of this group. +And we would like to make special thanks to the following people +(in alphabetical order) for their participation in the IM Protocol +design, +Hector Chan, Takashi Fujiwara, Yoshio Horiuchi, Makoto Inada, +Hiromu Inukai, Mickael Kung, Seiji Kuwari, Franky Ling, Hiroyuki Machida, +Hiroyuki Miyamoto, Frank Rojas, Bob Scheifler, Makiko Shimamura, +Shoji Sugiyama, Hidetoshi Tajima, Masaki Takeuchi, Makoto Wakamatsu, +Masaki Wakao, Nobuyuki Tanaka, Shigeru Yamada, Katsuhisa Yano, Jinsoo Yoon. +.LP +.NH 1 +References +.XS +\*(SN References +.XE +.LP +All of the following documents are X Consortium standards available from MIT: +.LP +[1] Scheifler, Robert W., \fI``X Window System Protocol Version 11''\fP +.LP +[2] Scheifler, Robert W. etc., \fI``Xlib \- C Language X Interface''\fP +.LP +.bp +.XS +Appendix A \- Common Extensions +.XE +.ce 10 +.sp 5 +\s+2\fBAppendix A\fP\s-2 +.sp +\s+1\fBCommon Extensions\fP\s-1 +.ce 0 +.sp +.LP +Extension opcodes and packet names (e.g. +.PN XIM_EXT_SET_EVENT_MASK +) for additional extensions may be registered with X Consortium. +The following is a commonly well-known extended packet. +.LP +.LP +.IP \fB(1) +Extension to manipulate the event handling\fP +.LP +.PN XIM_EXT_SET_EVENT_MASK +message specifies the set of event masks that the IM library should manipulate. +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_EXT_SET_EVENT_MASK (IM Server \(-> IM library) +.sp 6p +:2:CARD16:input-method-ID +:2:CARD16:input-context-ID +:4:EVENTMASK:filter-event-mask (*1) +:4:EVENTMASK:intercept-event-mask (*2) +:4:EVENTMASK:select-event-mask (*3) +:4:EVENTMASK:forward-event-mask (*4) +:4:EVENTMASK:synchronous-event-mask (*5) +.TE +.IP (*1) +Specify the events to be neglected by the IM library via XFilterEvent. +.IP (*2) +Specify the events to be deselected by the IM library with XSelectInput. +.IP (*3) +Specify the events to be selected by the IM library with XSelectInput. +.IP (*4) +Specify all the events to be forwarded to the IM Server by the IM library. +.IP (*5) +Specify the events to be forwarded with synchronous flag on by the IM library. +.RE +.LP +The IM library must reply +.PN XIM_SYNC_REPLY +message to the IM Server. This request is valid after the ic is created. +.LP +.sp +.IP \fB(2) +Extension for improvement of performance\fR +.LP +The following requests may be used for improvement of performance. +.LP +.PN XIM_EXT_FORWARD_KEYEVENT +message may be used instead of +.PN XIM_FORWARD_EVENT +message. +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_EXT_FORWARD_KEYEVENT (IM Server \(<-\(-> IM library) +.sp 6p +:2:CARD16:input-method-ID +:2:CARD16:input-context-ID +:2:BITMASK16:flag +::#0001:synchronous +:2:CARD16:sequence number +:1:BYTE:xEvent.u.u.type +:1:BYTE:keycode +:2:CARD16:state +:4:CARD32:time +:4:CARD32:window +.TE +.RE +.LP +.bp +.PN XIM_EXT_MOVE +message may be used to change the spot location instead of +.PN +XIM_SET_IC_VALUES +message. +It is effective only if the client specified XIMPreeditPosition. +.RS +.TS +tab(:); +lfB s s s +lw(.25i) lw(.25i) lw(1.75i) lw(3.5i). +XIM_EXT_MOVE (IM library \(-> IM Server) +.sp 6p +:2:CARD16:input-method-ID +:2:CARD16:input-context-ID +:2:INT16:X +:2:INT16:Y +.TE +.RE +.LP +.PN XIM_EXT_MOVE +message is a asynchronous request. +.LP +.bp +.XS +Appendix B \- The list of transport specific IM Server names registered +.XE +.ce 10 +.sp 5 +\s+2\fBAppendix B\fP\s-2 +.sp +\s+1\fBThe list of transport specific IM Server address format registered\fP\s-1 +.ce 0 +.sp +.LP +The following format represents the ATOM contained in +.PN XIM_SERVERS +property and the string returned from the request converting +selection target LOCALES and TRANSPORT. +.DS + ``{@\^\fIcategory\fP\^=[\^\fIvalue\fP,...]}...'' +.DE +.LP +The following categories are currently registered. +.RS +.TS +tab(;); +l l. +\fBserver\fP;: IM Server name (used for XIM_SERVERS) +\fBlocale\fP;: XPG4 locale name (LOCALES) +\fBtransport\fP;: transport-specific name (TRANSPORT) +.TE +.RE +.LP +The preregistered formats for transport-specific names are as follows: +.RS +.LP +\fBTCP/IP Names\fP +.LP +.RS +The following syntax should be used for system internal domain names: +.DS +<\fIlocal name\fP> ::= ``local/''<\fIhostname\fP>``:''<\fIpathname\fP> +.DE +.LP +Where <\fIpathname\fP> is a path name of socket address. +.LP +IM Server's name should be set to <\fIpathname\fP> to run multiple IM Server +at the same time +.LP +The following syntax should be used for Internet domain names: +.DS +<\fITCP name\fP> ::= ``tcp/''<\fIhostname\fP>``:''<\fIipportnumber\fP> +.DE +where <\fIhostname\fP> is either symbolic (such as expo.lcs.mit.edu) or +numeric decimal (such as 18.30.0.212). The <\fIipportnumber\fP> is the +port on which the IM Server is listening for connections. +For example: +.DS +tcp/expo.lcs.mit.edu:8012 +tcp/18.30.0.212:7890 +.DE +.RE +.LP +\fBDECnet Names\fP +.LP +.RS +The following syntax should be used for DECnet names: +.DS +<\fIDECnet name\fP> ::= ``decnet/''<\fInodename\fP>``::IMSERVER$''<\fIobjname\fP> +.DE +where <\fInodename\fP> is either symbolic (such as SRVNOD) or the numeric +decimal form of the DECnet address (such as 44.70). The <\fIobjname\fP> +is normal, case-insensitive DECnet object name. For example: +.DS +DECNET/SRVNOD::IMSERVER$DEFAULT +decnet/44.70::IMSERVER$other +.DE +.RE +.LP +\fBX Names\fP +.LP +.RS +The following syntax should be used for X names: +.DS +<\fIX name\fP> ::= ``X/'' +.DE +.RE +.RE +.LP +If a given category has multiple values, the value is evaluated in order of +setting. +.bp +.XS +Appendix C \- Protocol number +.XE +.ce 10 +.sp 5 +\s+2\fBAppendix C\fP\s-2 +.sp +\s+1\fBProtocol number\fP\s-1 +.ce 0 +.sp +.LP +\fBMajor Protocol number\fP +.TS +center, tab(:); +lw(9c) l. +XIM_CONNECT:#001 +XIM_CONNECT_REPLY:#002 +XIM_DISCONNECT:#003 +XIM_DISCONNECT_REPLY:#004 + +XIM_AUTH_REQUIRED:#010 +XIM_AUTH_REPLY:#011 +XIM_AUTH_NEXT:#012 +XIM_AUTH_SETUP:#013 +XIM_AUTH_NG:#014 + +XIM_ERROR:#020 + +XIM_OPEN:#030 +XIM_OPEN_REPLY:#031 +XIM_CLOSE:#032 +XIM_CLOSE_REPLY:#033 +XIM_REGISTER_TRIGGERKEYS:#034 +XIM_TRIGGER_NOTIFY:#035 +XIM_TRIGGER_NOTIFY_REPLY:#036 +XIM_SET_EVENT_MASK:#037 +XIM_ENCODING_NEGOTIATION:#038 +XIM_ENCODING_NEGOTIATION_REPLY:#039 +XIM_QUERY_EXTENSION:#040 +XIM_QUERY_EXTENSION_REPLY:#041 +XIM_SET_IM_VALUES:#042 +XIM_SET_IM_VALUES_REPLY:#043 +XIM_GET_IM_VALUES:#044 +XIM_GET_IM_VALUES_REPLY:#045 + +XIM_CREATE_IC:#050 +XIM_CREATE_IC_REPLY:#051 +XIM_DESTROY_IC:#052 +XIM_DESTROY_IC_REPLY:#053 +XIM_SET_IC_VALUES:#054 +XIM_SET_IC_VALUES_REPLY:#055 +XIM_GET_IC_VALUES:#056 +XIM_GET_IC_VALUES_REPLY:#057 +XIM_SET_IC_FOCUS:#058 +XIM_UNSET_IC_FOCUS:#059 +XIM_FORWARD_EVENT:#060 +XIM_SYNC:#061 +XIM_SYNC_REPLY:#062 +XIM_COMMIT:#063 +XIM_RESET_IC:#064 +XIM_RESET_IC_REPLY:#065 + +XIM_GEOMETRY:#070 +XIM_STR_CONVERSION:#071 +XIM_STR_CONVERSION_REPLY:#072 +XIM_PREEDIT_START:#073 +XIM_PREEDIT_START_REPLY:#074 +XIM_PREEDIT_DRAW:#075 +XIM_PREEDIT_CARET:#076 +XIM_PREEDIT_CARET_REPLY:#077 +XIM_PREEDIT_DONE:#078 +XIM_STATUS_START:#079 +XIM_STATUS_DRAW:#080 +XIM_STATUS_DONE:#081 +XIM_PREEDITSTATE:#082 +.TE +.sp +(*) The IM Server's extension protocol number should be more than #128. +.bp +.XS +Appendix D \- Implementation Tips +.XE +.ce 10 +.sp 5 +\s+2\fBAppendix D\fP\s-2 +.sp +\s+1\fBImplementation Tips\fP\s-1 +.ce 0 +.sp +.LP +.B +.IP \fB(1) +FrontEnd Method\fP +.LP +FrontEnd method is recognized as a performance acceleration by the +trade off of the variety of the reliability. +.LP +In order to use the FrontEnd method, the IM library must query the IM +Server to see if the FrontEnd extension is available. The query is +made by using the +.PN XIM_QUERY_EXTENSION +message. The IM Server may send +.PN XIM_EXT_SET_EVENT_MASK +message with intercept-event-mask, forward-event-mask, and +synchronous-event-mask values set after replying +.PN XIM_QUERY_EXTENSION_REPLY +message. +.LP +FrontEnd method can be implemented in a couple of ways depending on +how the IM Server utilize +.PN XIM_EXT_SET_EVENT_MASK +message. +.LP +One approach is to update both of the input mask and the filter-event-mask +depending on the preeidting state. The sample protocol sequence using the +static event flow is as follows: +.LP +.\"=================================================================== +.sp +\^... 1.675 6.888 6.237 10.296 +\^... 0.000i 3.408i 4.562i 0.000i +.nr 00 \n(.u +.nf +.PS 3.408i 4.562i +.br +.ps 11 +\h'3.750i'\v'0.034i'\v'-.13m'\L'3.374i\(br'\v'.13m' +.sp -1 +\h'3.912i'\v'1.384i'\D'l-0.100i 0.025i' +.sp -1 +\h'3.912i'\v'1.434i'\D'l-0.100i -0.025i' +.sp -1 +\h'3.812i'\v'1.409i'\l'0.750i' +.sp -1 +\h'3.750i'\h'-0.0m'\v'0.2m'\s12\fRIM Server\fP +.sp -1 +\h'3.812i'\v'0.818i'\h'-0.0m'\v'0.2m'\s10\fRevent mask is changed\fP +.sp -1 +\h'3.812i'\v'1.006i'\h'-0.0m'\v'0.2m'\s10\fRto select the event\fP +.sp -1 +\h'3.875i'\v'2.381i'\h'-0.0m'\v'0.2m'\s10\fRevent mask is changed\fP +.sp -1 +\h'3.875i'\v'2.568i'\h'-0.0m'\v'0.2m'\s10\fRto deselect the event\fP +.sp -1 +\h'3.875i'\v'1.631i'\h'-0.0m'\v'0.2m'\s10\fRX events directly come\fP +.sp -1 +\h'3.875i'\v'1.756i'\h'-0.0m'\v'0.2m'\s10\fRto the IM Server.\fP +.sp -1 +\h'3.875i'\v'2.006i'\h'-0.0m'\v'0.2m'\s10\fRwhen preediting is turning off\fP +.sp -1 +\h'0.625i'\v'0.284i'\l'0.875i' +.sp -1 +\h'1.400i'\v'0.309i'\D'l0.100i -0.025i' +.sp -1 +\h'1.400i'\v'0.259i'\D'l0.100i 0.025i' +.sp -1 +\h'1.750i'\v'0.346i'\l'1.687i' +.sp -1 +\h'3.337i'\v'0.371i'\D'l0.100i -0.025i' +.sp -1 +\h'3.337i'\v'0.321i'\D'l0.100i 0.025i' +.sp -1 +\h'1.850i'\v'2.134i'\D'l-0.100i 0.025i' +.sp -1 +\h'1.850i'\v'2.184i'\D'l-0.100i -0.025i' +.sp -1 +\h'1.750i'\v'2.159i'\l'1.687i' +.sp -1 +\h'1.562i'\v'0.034i'\v'-.13m'\L'3.374i\(br'\v'.13m' +.sp -1 +\h'1.850i'\v'0.446i'\D'l-0.100i 0.025i' +.sp -1 +\h'1.850i'\v'0.496i'\D'l-0.100i -0.025i' +.sp -1 +\h'1.750i'\v'0.471i'\l'1.687i' +.sp -1 +\h'1.687i'\v'0.631i'\h'-0.0m'\v'0.2m'\s10\fRXIM_EXT_SET_EVENT_MASK\fP +.sp -1 +\h'1.875i'\v'0.818i'\h'-0.0m'\v'0.2m'\s10\fRintercept-event-mask is set\fP +.sp -1 +\h'1.687i'\v'2.318i'\h'-0.0m'\v'0.2m'\s10\fRXIM_EXT_SET_EVENT_MASK\fP +.sp -1 +\h'1.875i'\v'2.443i'\h'-0.0m'\v'0.2m'\s10\fRselect-event-mask is set\fP +.sp -1 +\h'0.937i'\h'-0.0m'\v'0.2m'\s12\fRIM library\fP +.sp -1 +\v'0.193i'\h'-0.0m'\v'0.2m'\s10\fRKeys in the on-key-list\fP +.sp -1 +\h'0.250i'\v'2.318i'\h'-0.0m'\v'0.2m'\s10\fRevent mask is changed\fP +.sp -1 +\h'0.250i'\v'2.506i'\h'-0.0m'\v'0.2m'\s10\fRto select the event\fP +.sp -1 +\h'0.250i'\v'1.006i'\h'-0.0m'\v'0.2m'\s10\fRto deselect the event\fP +.sp -1 +\h'0.250i'\v'0.818i'\h'-0.0m'\v'0.2m'\s10\fRevent mask is changed\fP +.sp -1 +\h'1.812i'\v'0.256i'\h'-0.0m'\v'0.2m'\s10\fRXIM_FORWARD_EVENT\fP +.sp -1 +.sp 1+3.408i +.PE +.if \n(00 .fi +.sp +.\"=================================================================== +.LP +To pursuit a maximum performance regardless of the preediting mode, +the IM Server may use the dynamic event flow with the following +sample protocol sequence. +.bp +.LP +.\"=================================================================== +\^... 1.675 6.888 6.237 10.296 +\^... 0.000i 3.408i 4.562i 0.000i +.nr 00 \n(.u +.nf +.PS 3.408i 4.562i +.br +.ps 11 +\h'3.750i'\v'0.034i'\v'-.13m'\L'3.374i\(br'\v'.13m' +.sp -1 +\h'3.912i'\v'1.384i'\D'l-0.100i 0.025i' +.sp -1 +\h'3.912i'\v'1.434i'\D'l-0.100i -0.025i' +.sp -1 +\h'3.812i'\v'1.409i'\l'0.750i' +.sp -1 +\h'3.750i'\h'-0.0m'\v'0.2m'\s12\fRIM Server\fP +.sp -1 +\h'3.812i'\v'0.818i'\h'-0.0m'\v'0.2m'\s10\fRevent mask is changed\fP +.sp -1 +\h'3.812i'\v'1.006i'\h'-0.0m'\v'0.2m'\s10\fRto select the event\fP +.sp -1 +\h'3.875i'\v'2.381i'\h'-0.0m'\v'0.2m'\s10\fRevent mask is changed\fP +.sp -1 +\h'3.875i'\v'2.568i'\h'-0.0m'\v'0.2m'\s10\fRto deselect the event\fP +.sp -1 +\h'3.875i'\v'1.631i'\h'-0.0m'\v'0.2m'\s10\fRX events directly come\fP +.sp -1 +\h'3.875i'\v'1.756i'\h'-0.0m'\v'0.2m'\s10\fRto the IM Server.\fP +.sp -1 +\h'3.875i'\v'2.006i'\h'-0.0m'\v'0.2m'\s10\fRwhen preediting is turning off\fP +.sp -1 +\h'0.625i'\v'0.284i'\l'0.875i' +.sp -1 +\h'1.400i'\v'0.309i'\D'l0.100i -0.025i' +.sp -1 +\h'1.400i'\v'0.259i'\D'l0.100i 0.025i' +.sp -1 +\h'1.750i'\v'0.346i'\l'1.687i' +.sp -1 +\h'3.337i'\v'0.371i'\D'l0.100i -0.025i' +.sp -1 +\h'3.337i'\v'0.321i'\D'l0.100i 0.025i' +.sp -1 +\h'1.850i'\v'1.196i'\D'l-0.100i 0.025i' +.sp -1 +\h'1.850i'\v'1.246i'\D'l-0.100i -0.025i' +.sp -1 +\h'1.750i'\v'1.221i'\l'1.687i' +.sp -1 +\h'1.850i'\v'2.134i'\D'l-0.100i 0.025i' +.sp -1 +\h'1.850i'\v'2.184i'\D'l-0.100i -0.025i' +.sp -1 +\h'1.750i'\v'2.159i'\l'1.687i' +.sp -1 +\h'1.562i'\v'0.034i'\v'-.13m'\L'3.374i\(br'\v'.13m' +.sp -1 +\h'1.850i'\v'0.446i'\D'l-0.100i 0.025i' +.sp -1 +\h'1.850i'\v'0.496i'\D'l-0.100i -0.025i' +.sp -1 +\h'1.750i'\v'0.471i'\l'1.687i' +.sp -1 +\h'1.812i'\v'0.256i'\h'-0.0m'\v'0.2m'\s10\fRXIM_TRIGGER_NOTIFY\fP +.sp -1 +\h'1.687i'\v'1.068i'\h'-0.0m'\v'0.2m'\s10\fRXIM_TRIGGER_NOTIFY_REPLY\fP +.sp -1 +\h'1.687i'\v'0.631i'\h'-0.0m'\v'0.2m'\s10\fRXIM_EXT_SET_EVENT_MASK\fP +.sp -1 +\h'1.875i'\v'0.818i'\h'-0.0m'\v'0.2m'\s10\fRintercept-event-mask is set\fP +.sp -1 +\h'1.687i'\v'2.318i'\h'-0.0m'\v'0.2m'\s10\fRXIM_EXT_SET_EVENT_MASK\fP +.sp -1 +\h'1.875i'\v'2.443i'\h'-0.0m'\v'0.2m'\s10\fRselect-event-mask is set\fP +.sp -1 +\h'0.937i'\h'-0.0m'\v'0.2m'\s12\fRIM library\fP +.sp -1 +\v'0.193i'\h'-0.0m'\v'0.2m'\s10\fRKeys in the on-key-list\fP +.sp -1 +\h'0.250i'\v'2.318i'\h'-0.0m'\v'0.2m'\s10\fRevent mask is changed\fP +.sp -1 +\h'0.250i'\v'2.506i'\h'-0.0m'\v'0.2m'\s10\fRto select the event\fP +.sp -1 +\h'0.250i'\v'1.006i'\h'-0.0m'\v'0.2m'\s10\fRto deselect the event\fP +.sp -1 +\h'0.250i'\v'0.818i'\h'-0.0m'\v'0.2m'\s10\fRevent mask is changed\fP +.sp -1 +.sp 1+3.408i +.PE +.if \n(00 .fi +.\"=================================================================== +.LP +This method can reduce the XIM protocol traffic dramatically +by updating intercept-event-mask and select-event-mask accordingly. +The tradeoff of this performance improvement is that the key +events may be lost or disordered in some particular situation, such as +when the user types the keyboard in following sequence really fast: +.sp 6p +.RS +``some strings''``another string'' +.RE +.sp 6p +Since this method requires the input mask updates to the both the IM Server +and Xlib when turning on and off the preediting, and there is a time lag +till the requests take effect when two client issues the input mask updates +simultaneously. +.LP +Another approach of the FrontEnd method is to update the filter-event-mask +depending on the preediting state and not to update the input mask. +The IM Server must register both of the preediting on key list and off key +list by +.PN XIM_REGISTER_TRIGGERKEYS +message. +In this method, Both the IM Server and the IM client select the same +events on the same client's window, so that the events are delivered +to both of the IM Server and the client. The preediting on and off +states are expressed by whether the key events are filtered or not. +The sample protocol sequence are as follows: +.LP +.bp +<> +.LP +.\"==================================================================== +.sp +\^... 1.488 7.325 6.487 10.358 +\^... 0.000i 3.033i 4.999i 0.000i +.nr 00 \n(.u +.nf +.PS 3.033i 4.999i +.br +.ps 11 +\h'4.099i'\v'0.383i'\D'l-0.100i 0.025i' +.sp -1 +\h'4.099i'\v'0.433i'\D'l-0.100i -0.025i' +.sp -1 +\h'3.999i'\v'0.408i'\l'1.000i' +.sp -1 +\h'4.099i'\v'1.696i'\D'l-0.100i 0.025i' +.sp -1 +\h'4.099i'\v'1.746i'\D'l-0.100i -0.025i' +.sp -1 +\h'3.999i'\v'1.721i'\l'1.000i' +.sp -1 +\h'3.937i'\v'0.096i'\v'-.13m'\L'2.937i\(br'\v'.13m' +.sp -1 +\h'3.937i'\v'0.062i'\h'-0.0m'\v'0.2m'\s12\fRIM Server\fP +.sp -1 +\h'4.062i'\v'0.755i'\h'-0.0m'\v'0.2m'\s10\fRthe specified events\fP +.sp -1 +\h'4.062i'\v'0.943i'\h'-0.0m'\v'0.2m'\s10\fRare being processed\fP +.sp -1 +\h'4.062i'\v'2.255i'\h'-0.0m'\v'0.2m'\s10\fRthe specified events\fP +.sp -1 +\h'4.062i'\v'2.443i'\h'-0.0m'\v'0.2m'\s10\fRare being discarded\fP +.sp -1 +\h'4.249i'\v'1.568i'\h'-0.0m'\v'0.2m'\s10\fRKeys in the off-key-list\fP +.sp -1 +\h'4.187i'\v'0.318i'\h'-0.0m'\v'0.2m'\s10\fRKeys in the on-key-list\fP +.sp -1 +\h'0.812i'\v'0.346i'\l'0.875i' +.sp -1 +\h'1.587i'\v'0.371i'\D'l0.100i -0.025i' +.sp -1 +\h'1.587i'\v'0.321i'\D'l0.100i 0.025i' +.sp -1 +\h'1.937i'\v'0.408i'\l'1.687i' +.sp -1 +\h'3.524i'\v'0.433i'\D'l0.100i -0.025i' +.sp -1 +\h'3.524i'\v'0.383i'\D'l0.100i 0.025i' +.sp -1 +\h'1.749i'\v'0.096i'\v'-.13m'\L'2.937i\(br'\v'.13m' +.sp -1 +\h'2.037i'\v'0.508i'\D'l-0.100i 0.025i' +.sp -1 +\h'2.037i'\v'0.558i'\D'l-0.100i -0.025i' +.sp -1 +\h'1.937i'\v'0.533i'\l'1.687i' +.sp -1 +\h'0.812i'\v'1.721i'\l'0.875i' +.sp -1 +\h'1.587i'\v'1.746i'\D'l0.100i -0.025i' +.sp -1 +\h'1.587i'\v'1.696i'\D'l0.100i 0.025i' +.sp -1 +\h'2.099i'\v'1.758i'\D'l-0.100i 0.025i' +.sp -1 +\h'2.099i'\v'1.808i'\D'l-0.100i -0.025i' +.sp -1 +\h'1.999i'\v'1.783i'\l'1.688i' +.sp -1 +\h'1.874i'\v'0.693i'\h'-0.0m'\v'0.2m'\s10\fRXIM_EXT_SET_EVENT_MASK\fP +.sp -1 +\v'0.255i'\h'-0.0m'\v'0.2m'\s10\fRKeys in the on-key-list\fP +.sp -1 +\h'2.062i'\v'0.880i'\h'-0.0m'\v'0.2m'\s10\fRfilter-event-mask is set\fP +.sp -1 +\h'0.624i'\v'0.755i'\h'-0.0m'\v'0.2m'\s10\fRthe specified events\fP +.sp -1 +\h'0.624i'\v'0.943i'\h'-0.0m'\v'0.2m'\s10\fRare being filtered\fP +.sp -1 +\h'1.937i'\v'1.943i'\h'-0.0m'\v'0.2m'\s10\fRXIM_EXT_SET_EVENT_MASK\fP +.sp -1 +\h'2.124i'\v'2.068i'\h'-0.0m'\v'0.2m'\s10\fRfilter-event-mask is set\fP +.sp -1 +\h'0.062i'\v'1.568i'\h'-0.0m'\v'0.2m'\s10\fRKeys in the off-key-list\fP +.sp -1 +\h'1.062i'\h'-0.0m'\v'0.2m'\s12\fRIM library\fP +.sp -1 +\h'0.624i'\v'2.255i'\h'-0.0m'\v'0.2m'\s10\fRthe specified events\fP +.sp -1 +\h'0.624i'\v'2.443i'\h'-0.0m'\v'0.2m'\s10\fRare being processed\fP +.sp -1 +\h'1.999i'\v'0.318i'\h'-0.0m'\v'0.2m'\s10\fRXIM_FORWARD_EVENT\fP +.sp -1 +.sp 1+3.033i +.PE +.if \n(00 .fi +.\"==================================================================== +.LP +<> +.LP +.\"==================================================================== +\^... 1.488 7.325 6.487 10.358 +\^... 0.000i 3.033i 4.999i 0.000i +.nr 00 \n(.u +.nf +.PS 3.033i 4.999i +.br +.ps 11 +\h'4.099i'\v'0.383i'\D'l-0.100i 0.025i' +.sp -1 +\h'4.099i'\v'0.433i'\D'l-0.100i -0.025i' +.sp -1 +\h'3.999i'\v'0.408i'\l'1.000i' +.sp -1 +\h'4.099i'\v'1.696i'\D'l-0.100i 0.025i' +.sp -1 +\h'4.099i'\v'1.746i'\D'l-0.100i -0.025i' +.sp -1 +\h'3.999i'\v'1.721i'\l'1.000i' +.sp -1 +\h'3.937i'\v'0.096i'\v'-.13m'\L'2.937i\(br'\v'.13m' +.sp -1 +\h'3.937i'\v'0.062i'\h'-0.0m'\v'0.2m'\s12\fRIM Server\fP +.sp -1 +\h'4.062i'\v'0.755i'\h'-0.0m'\v'0.2m'\s10\fRthe specified events\fP +.sp -1 +\h'4.062i'\v'0.943i'\h'-0.0m'\v'0.2m'\s10\fRare being processed\fP +.sp -1 +\h'4.062i'\v'2.255i'\h'-0.0m'\v'0.2m'\s10\fRthe specified events\fP +.sp -1 +\h'4.062i'\v'2.443i'\h'-0.0m'\v'0.2m'\s10\fRare being discarded\fP +.sp -1 +\h'4.249i'\v'1.568i'\h'-0.0m'\v'0.2m'\s10\fRKeys in the off-key-list\fP +.sp -1 +\h'4.187i'\v'0.318i'\h'-0.0m'\v'0.2m'\s10\fRKeys in the on-key-list\fP +.sp -1 +\h'0.812i'\v'0.346i'\l'0.875i' +.sp -1 +\h'1.587i'\v'0.371i'\D'l0.100i -0.025i' +.sp -1 +\h'1.587i'\v'0.321i'\D'l0.100i 0.025i' +.sp -1 +\h'1.937i'\v'0.408i'\l'1.687i' +.sp -1 +\h'3.524i'\v'0.433i'\D'l0.100i -0.025i' +.sp -1 +\h'3.524i'\v'0.383i'\D'l0.100i 0.025i' +.sp -1 +\h'2.037i'\v'1.258i'\D'l-0.100i 0.025i' +.sp -1 +\h'2.037i'\v'1.308i'\D'l-0.100i -0.025i' +.sp -1 +\h'1.937i'\v'1.283i'\l'1.687i' +.sp -1 +\h'1.749i'\v'0.096i'\v'-.13m'\L'2.937i\(br'\v'.13m' +.sp -1 +\h'2.037i'\v'0.508i'\D'l-0.100i 0.025i' +.sp -1 +\h'2.037i'\v'0.558i'\D'l-0.100i -0.025i' +.sp -1 +\h'1.937i'\v'0.533i'\l'1.687i' +.sp -1 +\h'0.812i'\v'1.721i'\l'0.875i' +.sp -1 +\h'1.587i'\v'1.746i'\D'l0.100i -0.025i' +.sp -1 +\h'1.587i'\v'1.696i'\D'l0.100i 0.025i' +.sp -1 +\h'2.099i'\v'1.758i'\D'l-0.100i 0.025i' +.sp -1 +\h'2.099i'\v'1.808i'\D'l-0.100i -0.025i' +.sp -1 +\h'1.999i'\v'1.783i'\l'1.688i' +.sp -1 +\h'1.999i'\v'0.318i'\h'-0.0m'\v'0.2m'\s10\fRXIM_TRIGGER_NOTIFY\fP +.sp -1 +\h'1.874i'\v'1.130i'\h'-0.0m'\v'0.2m'\s10\fRXIM_TRIGGER_NOTIFY_REPLY\fP +.sp -1 +\h'1.874i'\v'0.693i'\h'-0.0m'\v'0.2m'\s10\fRXIM_EXT_SET_EVENT_MASK\fP +.sp -1 +\v'0.255i'\h'-0.0m'\v'0.2m'\s10\fRKeys in the on-key-list\fP +.sp -1 +\h'2.062i'\v'0.880i'\h'-0.0m'\v'0.2m'\s10\fRfilter-event-mask is set\fP +.sp -1 +\h'0.624i'\v'0.755i'\h'-0.0m'\v'0.2m'\s10\fRthe specified events\fP +.sp -1 +\h'0.624i'\v'0.943i'\h'-0.0m'\v'0.2m'\s10\fRare being filtered\fP +.sp -1 +\h'1.937i'\v'1.943i'\h'-0.0m'\v'0.2m'\s10\fRXIM_EXT_SET_EVENT_MASK\fP +.sp -1 +\h'2.124i'\v'2.068i'\h'-0.0m'\v'0.2m'\s10\fRfilter-event-mask is set\fP +.sp -1 +\h'0.062i'\v'1.568i'\h'-0.0m'\v'0.2m'\s10\fRKeys in the off-key-list\fP +.sp -1 +\h'1.062i'\h'-0.0m'\v'0.2m'\s12\fRIM library\fP +.sp -1 +\h'0.624i'\v'2.255i'\h'-0.0m'\v'0.2m'\s10\fRthe specified events\fP +.sp -1 +\h'0.624i'\v'2.443i'\h'-0.0m'\v'0.2m'\s10\fRare being processed\fP +.sp -1 +.sp 1+3.033i +.PE +.if \n(00 .fi + +.\"==================================================================== +.LP +This method does not have the problem of the time lag when going across +the preediting on and off mode, however, the amount of the performance +acceleration is not as good as the method described above. +.LP +In general, the FrontEnd method requires some synchronization to some +of the X protocols, such as the ChangeWindowAttribute protocol for the +event mask change or the GrabKey protocol, since it relies on the X's +principal event dispatching mechanism. Any X protocol bindings do not +consider the synchronization might cause some mis-synchronization +between the IM clients and the IM Server. +.LP +.bp +.IP \fB(2) +Transport Layer\fP +.LP +The Xlib XIM implementation is layered into three functions, a protocol +layer, an interface layer and a transport layer. The purpose of this +layering is to make the protocol independent of transport implementation. +Each function of these layers are: +.RS 3 +.IP "\fIThe protocol layer\fP" +.br +implements overall function of XIM and calls the interface layer +functions when it needs to communicate to IM Server. +.IP "\fIThe interface layer\fP" +.br +separates the implementation of the transport layer from the protocol +layer, in other words, it provides implementation independent hook for +the transport layer functions. +.IP "\fIThe transport layer\fP" +.br +handles actual data communication with IM Server. It is done by a set +of several functions named transporters. +.RE +.LP +The interface layer and the transport layer make various communication +channels usable such as X Protocol, TCP/IP, DECnet or STREAM. +The following is a sample implementation for the transporter using +the X connection. +Refer to "xtrans" for the transporter using Socket Transport. +.LP +At the beginning of the X Transport connection for the XIM transport +mechanism, two different windows must be created either in an Xlib XIM +or in an IM Server, with which the Xlib and the IM Server exchange the +XIM transports by using the ClientMessage events and Window Properties. +In the following, the window created by the Xlib is referred as the +"client communication window", and on the other hand, the window created +by the IM Server is referred as the "IMS communication window". +.LP +.B +Connection +.LP +.RS +In order to establish a connection, a communication window is created. +A ClientMessage in the following event's format is sent to the owner +window of XIM_SERVER selection, which the IM Server has created. +.LP +Refer to "The Input Method Protocol" for the XIM_SERVER atom. +.LP +.ce +Table D-1; The ClientMessage sent to the IMS window. +.TS H +tab(:); +l s|l +l l|l. +_ +.sp 6p +.B +Structure Member:Contents +.sp 6p +_ +.sp 6p +.TH +.R +int:type:ClientMessage +u_long:serial:Set by the X Window System +Bool:send_event:Set by the X Window System +Display:*display:The display to which connects +Window:window:IMS Window ID +Atom:message_type:XInternAtom(display, ``_XIM_XCONNECT'', False) +int:format:32 +long:data.l[0]:client communication window ID +long:data.l[1]:client-major-transport-version (*1) +long:data.l[2]:client-major-transport-version (*1) +.sp 6p +_ +.TE +.LP +In order to establish the connection (to notify the IM Server communication +window), the IM Server sends a ClientMessage in the following event's +format to the client communication window. +.LP +.bp +.ce +Table D-2; The ClientMessage sent by IM Server. +.TS H +tab(:); +l s | l +l l | l. +_ +.sp 6p +.B +Structure Member:Contents +.sp 6p +_ +.sp 6p +.TH +.R +int:type:ClientMessage +u_long:serial:Set by the X Window System +Bool:send_event:Set by the X Window System +Display:*display:The display to which connects +Window:window:client communication window ID +Atom:message_type:XInternAtom(display, ``_XIM_XCONNECT'', False) +int:format:32 +long:data.l[0]:IMS communication window ID +long:data.l[1]:server-major-transport-version (*1) +long:data.l[2]:server-minor-transport-version (*1) +long:data.l[3]:dividing size between ClientMessage and Property (*2) +.sp 6p +_ +.TE +.LP +.IP (*1) +major/minor-transport-version +.RS +The read/write method is decided by the combination of +major/minor-transport-version, as follows: +.LP +.ce +Table D-3; The read/write method and the major/minor-transport-version +.TS +center, tab(:); +| c s | l | +| c | c | l |. +_ +.sp 6p +.B +Transport-version:read/write +.sp 6p +_ +.sp 6p +major:minor: +.sp 6p +_ +.sp 6p +.R +0:0:only-CM & Property-with-CM +:1:only-CM & multi-CM +:2:only-CM & multi-CM & Property-with-CM +.sp 6p +_ +.sp 6p +1:0:PropertyNotify +.sp 6p +_ +.sp 6p +2:0:only-CM & PropertyNotify +:1:only-CM & multi-CM & PropertyNotify +.sp 6p +_ +.TE +.LP +.RS +.TS +center, tab(;); +l n l. +only-CM;:;data is sent via a ClientMessage +multi-CM;:;data is sent via multiple ClientMessages +Property-with-CM;:;T{ +data is written in Property, and its Atom is send via ClientMessage +T} +PropertyNotify;:;T{ +data is written in Property, and its Atom is send via PropertyNotify +T} +.TE +.RE +.LP +The method to decide major/minor-transport-version is as follows: +.LP +.IP (1) +The client sends 0 as major/minor-transport-version to the IM Server. +The client must support all methods in Table D-3. +The client may send another number as major/minor-transport-version to +use other method than the above in the future. +.IP (2) +The IM Server sends its major/minor-transport-version number to +the client. The client sends data using the method specified by the +IM Server. +.IP (3) +If major/minor-transport-version number is not available, it is regarded +as 0. +.RE +.LP +.IP (*2) +dividing size between ClientMessage and Property +.RS +If data is sent via both of multi-CM and Property, specify the dividing +size between ClientMessage and Property. The data, which is smaller than +this size, is sent via multi-CM (or only-CM), and the data, which is +lager than this size, is sent via Property. +.RE +.RE +.LP +.sp +.LP +.B +read/write +.LP +.RS +The data is transferred via either ClientMessage or Window Property in +the X Window System. +.LP +.B +Format for the data from the Client to the IM Server +.LP +.RS +.B +ClientMessage +.LP +If data is sent via ClientMessage event, the format is as follows: +.LP +.ce +Table D-4; The ClientMessage event's format (first or middle) +.TS +tab(;); +l s | l +l l | l. +_ +.sp 6p +.B +Structure Member;Contents +.sp 6p +_ +.sp 6p +.R +int;type;ClientMessage +u_long;serial;Set by the X Window System +Bool;send_event;Set by the X Window System +Display;*display;The display to which connects +Window;window;IMS communication window ID +Atom;message_type;XInternAtom(display, ``_XIM_MOREDATA'', False) +int;format;8 +char;data.b[20];(read/write DATA : 20 byte) +.sp 6p +_ +.TE +.LP +.ce +Table D-5; The ClientMessage event's format (only or last) +.TS H +tab(;); +l s | l +l l | l. +_ +.sp 6p +.B +Structure Member;Contents +.sp 6p +_ +.sp 6p +.TH +.R +int;type;ClientMessage +u_long;serial;Set by the X Window System +Bool;send_event;Set by the X Window System +Display;*display;The display to which connects +Window;window;IMS communication window ID +Atom;message_type;XInternAtom(display, ``_XIM_PROTOCOL'', False) +int;format;8 +char;data.b[20];(read/write DATA : MAX 20 byte) (*1) +.sp 6p +_ +.TE +.IP (*1) +If the data is smaller than 20 byte, all data other than available data +must be 0. +.RE +.LP +.RS +.B +Property +.LP +In the case of large data, data will be sent via the Window Property +for the efficiency. There are the following two methods to notify +Property, and transport-version is decided which method is used. +.LP +.IP (1) +The XChangeProperty function is used to store data in the client +communication window, and Atom of the stored data is notified to the +IM Server via ClientMessage event. +.IP (2) +The XChangeProperty function is used to store data in the client +communication window, and Atom of the stored data is notified to the +IM Server via PropertyNotify event. +.LP +The arguments of the XChangeProperty are as follows: +.LP +.bp +.ce +Table D-6; The XChangeProperty event's format +.TS H +tab(:); +l s | l +l l | l. +_ +.sp 6p +.B +Argument:Contents +.sp 6p +_ +.sp 6p +.TH +.R +Display:*display:The display to which connects +Window:window:IMS communication window ID +Atom:property:read/write property Atom (*1) +Atom:type:XA_STRING +int:format:8 +int:mode:PropModeAppend +u_char:*data:read/write DATA +int:nelements:length of DATA +.sp 6p +_ +.TE +.LP +.IP (*1) +The read/write property ATOM allocates the following strings by +\fBXInternAtom\fP. +.RS +``_clientXXX'' +.RE +.LP +The client changes the property with the mode of PropModeAppend and +the IM Server will read it with the delete mode i.e. (delete = True). +.LP +If Atom is notified via ClientMessage event, the format of the ClientMessage +is as follows: +.LP +.ce +Table D-7; The ClientMessage event's format to send Atom of property +.TS H +tab(:); +l s | l +l l | l. +_ +.sp 6p +.B +Structure Member:Contents +.sp 6p +_ +.sp 6p +.TH +.R +int:type:ClientMessage +u_long:serial:Set by the X Window System +Bool:send_event:Set by the X Window System +Display:*display:The display to which connects +Window:window:IMS communication window ID +Atom:message_type:XInternAtom(display, ``_XIM_PROTOCOL'', False) +int:format:32 +long:data.l[0]:length of read/write property Atom +long:data.l[1]:read/write property Atom +.sp 6p +_ +.TE +.RE +.LP +.B +Format for the data from the IM Server to the Client +.LP +.RS +.B +ClientMessage +.LP +The format of the ClientMessage is as follows: +.LP +.ce +Table D-8; The ClientMessage event's format (first or middle) +.TS H +tab(;); +l s | l +l l | l. +_ +.sp 6p +.B +Structure Member;Contents +.sp 6p +_ +.sp 6p +.TH +.R +int;type;ClientMessage +u_long;serial;Set by the X Window System +Bool;send_event ;Set by the X Window System +Display;*display;The display to which connects +Window;window;client communication window ID +Atom;message_type;XInternAtom(display, ``_XIM_MOREDATA'', False) +int;format;8 +char;data.b[20];(read/write DATA : 20 byte) +.sp 6p +_ +.TE +.LP +.bp +.ce +Table D-9; The ClientMessage event's format (only or last) +.TS +tab(;); +l s | l +l l | l. +_ +.sp 6p +.B +Structure Member;Contents +.sp 6p +_ +.sp 6p +.R +int;type;ClientMessage +u_long;serial;Set by the X Window System +Bool;send_event ;Set by the X Window System +Display;*display;The display to which connects +Window;window;client communication window ID +Atom;message_type;XInternAtom(display, ``_XIM_PROTOCOL'', False) +int;format;8 +char;data.b[20];(read/write DATA : MAX 20 byte) (*1) +.sp 6p +_ +.TE +.LP +.IP (*1) +If the data size is smaller than 20 bytes, all data other than available +data must be 0. +.LP +.B +Property +.LP +In the case of large data, data will be sent via the Window Property +for the efficiency. There are the following two methods to notify +Property, and transport-version is decided which method is used. +.LP +.IP (1) +The XChangeProperty function is used to store data in the IMS +communication window, and Atom of the property is sent via the +ClientMessage event. +.IP (2) +The XChangeProperty function is used to store data in the IMS +communication window, and Atom of the property is sent via +PropertyNotify event. +.LP +The arguments of the XChangeProperty are as follows: +.LP +.ce +Table D-10; The XChangeProperty event's format +.TS H +tab(:); +l s | l +l l | l. +_ +.sp 6p +.B +Argument:Contents +.sp 6p +_ +.sp 6p +.TH +.R +Display:*display:The display which to connects +Window:window:client communication window ID +Atom:property:read/write property Atom (*1) +Atom:type:XA_STRING +int:format:8 +int:mode:PropModeAppend +u_char:*data:read/write DATA +int:nelements:length of DATA +.sp 6p +_ +.TE +.LP +.IP (*1) +The read/write property ATOM allocates some strings, which are not +allocated by the client, by \fBXInternAtom\fP. +.LP +The IM Server changes the property with the mode of PropModeAppend and +the client reads it with the delete mode, i.e. (delete = True). +.LP +If Atom is notified via ClientMessage event, the format of the ClientMessage +is as follows: +.LP +.bp +.ce +Table D-11; The ClientMessage event's format to send Atom of property +.TS H +tab(:); +l s | l +l l | l. +_ +.sp 6p +.B +Structure Member:Contents +.sp 6p +_ +.sp 6p +.TH +.R +int:type:ClientMessage +u_long:serial:Set by the X Window System +Bool:send_event:Set by the X Window System +Display:*display:The display to which connects +Window:window:client communication window ID +Atom:message_type:XInternAtom(display, ``_XIM_PROTOCOL'', False) +int:format:32 +long:data.l[0]:length of read/write property ATOM +long:data.l[1]:read/write property ATOM +.sp 6p +_ +.TE +.RE +.RE +.LP +.B +Closing Connection +.RS +.LP +If the client disconnect with the IM Server, shutdown function should +free the communication window properties and etc.. +.RE +.LP +.bp +.EH '''' +.OH '''' +.EF '''' +.OF '''' +.TC + diff --git a/libX11/specs/i18n/Framework.ms b/libX11/specs/i18n/Framework.ms new file mode 100644 index 000000000..20ff3c7b3 --- /dev/null +++ b/libX11/specs/i18n/Framework.ms @@ -0,0 +1,1567 @@ +.\" $Xorg: Framework.ms,v 1.3 2000/08/17 19:42:49 cpqbld Exp $ +.\" $XdotOrg: xc/doc/specs/i18n/Framework.ms,v 1.2 2004/04/23 18:42:19 eich Exp $ +.\" To print this out, type tbl macros.t ThisFile | troff -ms +.\" $XFree86: xc/doc/specs/i18n/Framework.ms,v 1.4 2001/01/17 16:57:45 dawes Exp $ +.EH '''' +.OH '''' +.EF '''' +.OF '''' +.ps 11 +.nr PS 11 +\& +.TL +\s+3\fBX11R6 Sample Implementation Frame Work\fP\s-3 +.sp 2 +.AU +Katsuhisa Yano +.AI +TOSHIBA Corporation +.AU +Yoshio Horiuchi +.AI +IBM Japan +.LP +.bp +.br +\& +.sp 15 +.ps 9 +.nr PS 9 +.LP +Copyright \(co 1994 by TOSHIBA Corporation +.br +Copyright \(co 1994 by IBM Corporation +.LP +Permission to use, copy, modify, and distribute this documentation +for any purpose and without fee is hereby granted, provided +that the above copyright notice and this permission notice appear +in all copies. +TOSHIBA Corporation and IBM Corporation make no representations about +the suitability for any purpose of the information in this document. +This documentation is provided as is without express or implied warranty. +.sp 5 +Copyright \(co 1994 X Consortium +.LP +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the ``Software''), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: +.LP +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. +.LP +THE SOFTWARE IS PROVIDED ``AS IS'', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN +AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN +CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +.LP +Except as contained in this notice, the name of the X Consortium shall not be +used in advertising or otherwise to promote the sale, use or other dealings +in this Software without prior written authorization from the X Consortium. +.sp 3 +\fIX Window System\fP is a trademark of The Open Group. +.ps 11 +.nr PS 11 +.bp 1 +.EH '\fBSample Implementation Frame Work\fP''\fB\*(xV\fP' +.OH '\fBSample Implementation Frame Work\fP''\fB\*(xV\fP' +.EF ''\fB % \fP'' +.OF ''\fB % \fP'' +.NH 1 +Preface +.XS \*(SN Preface +.XE +.LP +This document proposes to define the structures, methods and their +signatures that are expected to be common to all locale dependent +functions within the Xlib sample implementation. The following +illustration (Fig.1) is proposed to outline the separating of +the components within the sample implementation. +.LP +.\" figure start +.in +1c +\^... 0.237 5.796 5.24 10.14 +\^... 0.000i 4.344i 5.003i 0.000i +.nr 00 \n(.u +.nf +.PS 4.344i 5.003i +.br +.ps 11 +\h'1.753i'\v'2.130i'\v'-.13m'\L'-1.000i\(br'\v'.13m' +.sp -1 +\h'1.753i'\v'1.130i'\l'1.500i' +.sp -1 +\h'3.253i'\v'1.130i'\v'-.13m'\L'1.000i\(br'\v'.13m' +.sp -1 +\h'3.253i'\v'2.130i'\l'-1.500i' +.sp -1 +\h'1.751i'\v'1.628i'\l'1.499i' +.sp -1 +\h'2.500i'\v'1.128i'\v'-.13m'\L'0.500i\(br'\v'.13m' +.sp -1 +\h'1.875i'\v'1.344i'\h'-0.0m'\v'0.2m'\s12\fRInput\fP +.sp -1 +\h'1.875i'\v'1.532i'\h'-0.0m'\v'0.2m'\s12\fRMethod\fP +.sp -1 +\h'2.625i'\v'1.344i'\h'-0.0m'\v'0.2m'\s12\fROutput\fP +.sp -1 +\h'2.625i'\v'1.532i'\h'-0.0m'\v'0.2m'\s12\fRMethod\fP +.sp -1 +\h'1.938i'\v'1.844i'\h'-0.0m'\v'0.2m'\s12\fR\fP +.sp -1 +\h'2.000i'\v'2.032i'\h'-0.0m'\v'0.2m'\s12\fRX Locale Object\fP +.sp -1 +\h'3.503i'\v'1.630i'\v'-.13m'\L'-0.500i\(br'\v'.13m' +.sp -1 +\h'3.503i'\v'1.130i'\l'1.500i' +.sp -1 +\h'5.003i'\v'1.130i'\v'-.13m'\L'0.500i\(br'\v'.13m' +.sp -1 +\h'5.003i'\v'1.630i'\l'-1.500i' +.sp -1 +\h'3.625i'\v'1.344i'\h'-0.0m'\v'0.2m'\s12\fRC Library\fP +.sp -1 +\h'4.250i'\v'1.532i'\h'-0.0m'\v'0.2m'\s12\fRANSI impl.\fP +.sp -1 +\h'0.003i'\v'1.630i'\v'-.13m'\L'-0.500i\(br'\v'.13m' +.sp -1 +\h'0.003i'\v'1.130i'\l'1.500i' +.sp -1 +\h'1.503i'\v'1.130i'\v'-.13m'\L'0.500i\(br'\v'.13m' +.sp -1 +\h'1.503i'\v'1.630i'\l'-1.500i' +.sp -1 +\h'0.125i'\v'1.344i'\h'-0.0m'\v'0.2m'\s12\fRLocale Library\fP +.sp -1 +\h'0.438i'\v'1.507i'\h'-0.0m'\v'0.2m'\s12\fRnon-AnSI impl.\fP +.sp -1 +\h'3.500i'\v'0.782i'\h'-0.0m'\v'0.2m'\s12\fR<< ANSI/MSE API >>\fP +.sp -1 +\h'4.250i'\v'0.969i'\h'-0.0m'\v'0.2m'\h'-\w'\s12\fR(X Contrib)\fP'u/2u'\s12\fR(X Contrib)\fP\h'-\w'\s12\fR(X Contrib)\fP'u/2u' +.sp -1 +\h'0.125i'\v'3.094i'\h'-0.0m'\v'0.2m'\s12\fRXLC_XLOCALE\fP +.sp -1 +\h'0.125i'\v'3.282i'\h'-0.0m'\v'0.2m'\s12\fR- MB_CUR_MAX\fP +.sp -1 +\h'0.125i'\v'3.444i'\h'-0.0m'\v'0.2m'\s12\fR- codeset info\fP +.sp -1 +\h'0.125i'\v'3.607i'\h'-0.0m'\v'0.2m'\s12\fRo char/charset\fP +.sp -1 +\h'0.125i'\v'3.769i'\h'-0.0m'\v'0.2m'\s12\fRo conv/charset\fP +.sp -1 +\h'0.003i'\v'3.880i'\v'-.13m'\L'-1.000i\(br'\v'.13m' +.sp -1 +\h'0.003i'\v'2.880i'\l'1.500i' +.sp -1 +\h'1.503i'\v'2.880i'\v'-.13m'\L'1.000i\(br'\v'.13m' +.sp -1 +\h'1.503i'\v'3.880i'\l'-1.500i' +.sp -1 +\h'1.875i'\v'3.094i'\h'-0.0m'\v'0.2m'\s12\fRXLC_FONTSET\fP +.sp -1 +\h'1.875i'\v'3.282i'\h'-0.0m'\v'0.2m'\s12\fR- fonset info\fP +.sp -1 +\h'1.875i'\v'3.444i'\h'-0.0m'\v'0.2m'\s12\fR- charset info\fP +.sp -1 +\h'1.875i'\v'3.607i'\h'-0.0m'\v'0.2m'\s12\fR- font/charset\fP +.sp -1 +\h'1.875i'\v'3.769i'\h'-0.0m'\v'0.2m'\s12\fR- XLFD, GL/GR\fP +.sp -1 +\h'1.753i'\v'3.880i'\v'-.13m'\L'-1.000i\(br'\v'.13m' +.sp -1 +\h'1.753i'\v'2.880i'\l'1.500i' +.sp -1 +\h'3.253i'\v'2.880i'\v'-.13m'\L'1.000i\(br'\v'.13m' +.sp -1 +\h'3.253i'\v'3.880i'\l'-1.500i' +.sp -1 +\h'3.625i'\v'3.444i'\h'-0.0m'\v'0.2m'\s12\fR- codeset info\fP +.sp -1 +\h'3.625i'\v'3.607i'\h'-0.0m'\v'0.2m'\s12\fRo char/charset\fP +.sp -1 +\h'3.625i'\v'3.769i'\h'-0.0m'\v'0.2m'\s12\fRo conv/charset\fP +.sp -1 +\h'3.625i'\v'3.282i'\h'-0.0m'\v'0.2m'\s12\fR- MB_CUR_MAX\fP +.sp -1 +\h'3.625i'\v'3.094i'\h'-0.0m'\v'0.2m'\s12\fRlocaledef DB\fP +.sp -1 +\h'3.503i'\v'3.880i'\v'-.13m'\L'-1.000i\(br'\v'.13m' +.sp -1 +\h'3.503i'\v'2.880i'\l'1.500i' +.sp -1 +\h'5.003i'\v'2.880i'\v'-.13m'\L'1.000i\(br'\v'.13m' +.sp -1 +\h'5.003i'\v'3.880i'\l'-1.500i' +.sp -1 +\h'0.753i'\v'0.250i'\D'l0.000i -0.250i' +.sp -1 +\h'0.753i'\l'3.500i' +.sp -1 +\h'4.253i'\D'l0.000i 0.250i' +.sp -1 +\h'4.253i'\v'0.250i'\l'-3.500i' +.sp -1 +\h'2.500i'\v'0.157i'\h'-0.0m'\v'0.2m'\h'-\w'\s12\fRApplication\fP'u/2u'\s12\fRApplication\fP\h'-\w'\s12\fRApplication\fP'u/2u' +.sp -1 +\v'0.782i'\h'-0.0m'\v'0.2m'\s12\fR<< ANSI/MSE API >>\fP +.sp -1 +\h'0.751i'\v'0.969i'\h'-0.0m'\v'0.2m'\h'-\w'\s12\fR(X Contrib)\fP'u/2u'\s12\fR(X Contrib)\fP\h'-\w'\s12\fR(X Contrib)\fP'u/2u' +.sp -1 +\h'2.500i'\v'2.128i'\v'-.13m'\L'0.749i\(br'\v'.13m' +.sp -1 +\h'2.475i'\v'2.777i'\D'l0.025i 0.100i' +.sp -1 +\h'2.525i'\v'2.777i'\D'l-0.025i 0.100i' +.sp -1 +\h'2.500i'\v'2.315i'\D'l-0.250i 0.187i' +.sp -1 +\h'2.250i'\v'2.502i'\l'-1.124i' +.sp -1 +\h'1.126i'\v'2.502i'\v'-.13m'\L'0.375i\(br'\v'.13m' +.sp -1 +\h'1.101i'\v'2.777i'\D'l0.025i 0.100i' +.sp -1 +\h'1.151i'\v'2.777i'\D'l-0.025i 0.100i' +.sp -1 +\h'2.500i'\v'2.315i'\D'l0.250i 0.187i' +.sp -1 +\h'2.750i'\v'2.502i'\l'1.125i' +.sp -1 +\h'3.875i'\v'2.502i'\v'-.13m'\L'0.375i\(br'\v'.13m' +.sp -1 +\h'3.850i'\v'2.777i'\D'l0.025i 0.100i' +.sp -1 +\h'3.900i'\v'2.777i'\D'l-0.025i 0.100i' +.sp -1 +\h'0.376i'\v'1.628i'\v'-.13m'\L'1.249i\(br'\v'.13m' +.sp -1 +\h'0.351i'\v'2.777i'\D'l0.025i 0.100i' +.sp -1 +\h'0.401i'\v'2.777i'\D'l-0.025i 0.100i' +.sp -1 +\h'4.625i'\v'1.628i'\v'-.13m'\L'1.249i\(br'\v'.13m' +.sp -1 +\h'4.600i'\v'2.777i'\D'l0.025i 0.100i' +.sp -1 +\h'4.650i'\v'2.777i'\D'l-0.025i 0.100i' +.sp -1 +\h'2.125i'\v'0.253i'\v'-.13m'\L'0.375i\(br'\v'.13m' +.sp -1 +\h'2.100i'\v'0.528i'\D'l0.025i 0.100i' +.sp -1 +\h'2.150i'\v'0.528i'\D'l-0.025i 0.100i' +.sp -1 +\h'2.875i'\v'0.253i'\v'-.13m'\L'0.375i\(br'\v'.13m' +.sp -1 +\h'2.850i'\v'0.528i'\D'l0.025i 0.100i' +.sp -1 +\h'2.900i'\v'0.528i'\D'l-0.025i 0.100i' +.sp -1 +\h'1.126i'\v'0.253i'\v'-.13m'\L'0.375i\(br'\v'.13m' +.sp -1 +\h'1.101i'\v'0.528i'\D'l0.025i 0.100i' +.sp -1 +\h'1.151i'\v'0.528i'\D'l-0.025i 0.100i' +.sp -1 +\h'3.875i'\v'0.253i'\v'-.13m'\L'0.375i\(br'\v'.13m' +.sp -1 +\h'3.850i'\v'0.528i'\D'l0.025i 0.100i' +.sp -1 +\h'3.900i'\v'0.528i'\D'l-0.025i 0.100i' +.sp -1 +\v'4.002i'\D'l0.125i 0.125i' +.sp -1 +\h'0.125i'\v'4.127i'\l'3.000i' +.sp -1 +\h'3.125i'\v'4.127i'\D'l0.125i -0.125i' +.sp -1 +\h'3.500i'\v'4.002i'\D'l0.125i 0.125i' +.sp -1 +\h'3.625i'\v'4.127i'\l'1.250i' +.sp -1 +\h'4.875i'\v'4.127i'\D'l0.125i -0.125i' +.sp -1 +\h'1.626i'\v'4.344i'\h'-0.0m'\v'0.2m'\h'-\w'\s12\fRXLocale Source (X Core)\fP'u/2u'\s12\fRXLocale Source (X Core)\fP\h'-\w'\s12\fRXLocale Source (X Core)\fP'u/2u' +.sp -1 +\h'4.250i'\v'4.344i'\h'-0.0m'\v'0.2m'\h'-\w'\s12\fRSystem LOcale Source\fP'u/2u'\s12\fRSystem LOcale Source\fP\h'-\w'\s12\fRSystem LOcale Source\fP'u/2u' +.sp -1 +\h'2.500i'\v'0.782i'\h'-0.0m'\v'0.2m'\h'-\w'\s12\fRXLib API\fP'u/2u'\s12\fRXLib API\fP\h'-\w'\s12\fRXLib API\fP'u/2u' +.sp -1 +\h'2.500i'\v'0.969i'\h'-0.0m'\v'0.2m'\h'-\w'\s12\fR(X Core)\fP'u/2u'\s12\fR(X Core)\fP\h'-\w'\s12\fR(X Core)\fP'u/2u' +.sp -1 +\h'1.751i'\v'0.782i'\h'-0.0m'\v'0.2m'\s12\fR<<\fP +.sp -1 +\h'3.063i'\v'0.782i'\h'-0.0m'\v'0.2m'\s12\fR>>\fP +.sp -1 +.sp 1+4.344i +.in -1c +.PE +.if \n(00 .fi +.\" figure end +.LP +.ce +.sp 6p +Fig.1 : Frame Work of Locale Service API Proposal +.LP +Generally speaking, the internationalized portion of Xlib (Locale +Dependent X, LDX) consists of three objects; +locale (LC) , input method (IM) and output method (OM). +The LC provides a set of information that depends on user's language +environment. The IM manages text inputing, and the OM manages text +drawing. Both IM and OM highly depend on LC data. +.LP +In X11R5, there are two sample implementations, Ximp and Xsi, for +Xlib internationalization. But in both implementations, IM and OM +actually refer the private extension of LC. It breaks coexistence +of these two sample implementations. For example, if a user creates +a new OM for special purpose as a part of Ximp, it will not work with +Xsi. +.LP +As a solution of this problem, we propose to define the standard +APIs between these three objects, and define the structure that are +common to these objects. +.LP +.NH 1 +Objective +.XS \*(SN Objective +.XE +.LP +.IP \(bu +Explain the current X11R6 sample implementation +.IP \(bu +Document the common set of locale dependent interfaces +.IP \(bu +Provide more flexible pluggable layer +.LP +.NH 1 +Locale Object Binding Functions +.XS \*(SN Locale Object Binding Functions +.XE +.LP +This chapter describes functions related locale object binding for +implementing the pluggable layer. +.LP +A locale loader is an entry point for locale object, which +instantiates XLCd object and binds locale methods with specified +locale name. The behavior of loader is implementation dependent. +And, what kind of loaders are available is also implementation +dependent. +.LP +The loader is called in +.PN _XOpenLC, +but caller of +.PN _XOpenLC +does not need to care about its inside. For example, if the loader is +implemented with dynamic load functions, and the dynamic module is +expected to be unloaded when the corresponding XLCd is freed, +close methods of XLCdMethods should handle unloading. +.LP +.sp +\fBInitializing a locale loader list\fP +.LP +.FD 0 +void _XlcInitLoader() +.FN +The +.PN _XlcInitLoader +function initializes the locale loader list with vendor specific +manner. Each loader is registered with calling +.PN _XlcAddLoader. +The number of loaders and their order in the loader list is +implementation dependent. +.sp +.LP +\fBAdd a loader\fP +.LP +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef XLCd (*XLCdLoadProc)(\fIname\fP); + char \fI*name\fP; + +typedef int XlcPosition; +.De +.TS +lw(.5i) lw(2i) lw(2i). +T{ +#define +T} T{ +XlcHead +T} T{ + 0 +T} +T{ +#define +T} T{ +XlcTail +T} T{ +-1 +T} +.TE +.LP +.FD 0 +Bool _XlcAddLoader(\fIproc, position\fP) +.br + XLCdLoadProc \fIproc\fP; +.br + XlcPosition \fIposition\fP; +.FN +.LP +The +.PN _XlcAddLoader +function registers the specified locale loader ``\fIproc\fP'' to the +internal loader list. The position specifies that the loader +``\fIproc\fP'' should be placed in the top of the loader list(XlcHead) +or last(XlcTail). +.LP +The object loader is called from the top of the loader list in order, +when calling time. +.sp +.LP +\fBRemove a loader\fP +.LP +.FD 0 +void _XlcRemoveLoader(\fIproc\fP) +.br + XLCdLoadProc \fIproc\fP; +.FN +.LP +The +.PN _XlcRemoveLoader +function removes the locale loader specified by ``\fIproc\fP'' from the +loader list. +.LP +Current implementation provides following locale loaders; +.DS +.PN _XlcDefaultLoader +.PN _XlcGenericLoader +.PN _XlcEucLoader +.PN _XlcSjisLoader +.PN _XlcUtfLoader +.PN _XaixOsDynamicLoad +.DE +.LP +.NH 1 +Locale Method Interface +.XS \*(SN Locale Method Interface +.XE +.LP +This chapter describes the locale method API, which is a set of +accessible functions from both IM and OM parts. +The locale method API provides the functionalities; obtaining locale +dependent information, handling charset, converting text, etc. +.LP +As a result of using these APIs instead of accessing vender private +extension of the locale object, we can keep locale, IM and OM +independently each other. +.LP +.NH 1 +Locale Method Functions +.XS \*(SN Locale Method Functions +.XE +.LP +\fBOpen a Locale Method\fP +.LP +.FD 0 +XLCd _XOpenLC(\fIname\fP) +.br + char \fI*name\fP; +.FN +.LP +The +.PN _XOpenLC +function opens a locale method which corresponds to the +specified locale name. +.PN _XOpenLC +calls a locale object loader, which is registered via +.PN _XlcAddLoader into the internal loader list. If the called loader +is valid and successfully opens a locale, +.PN _XOpenLC +returns the XLCd. If the loader is invalid or failed to open a locale, +.PN _XOpenLC +calls the next loader. If all registered loaders cannot open a locale, +.PN _XOpenLC +returns NULL. +.LP +.FD 0 +XLCd _XlcCurrentLC() +.FN +.LP +The +.PN _XlcCurrentLC +function returns an XLCd that are bound to current locale. +.sp +.LP +\fBClose a Locale Method\fP +.LP +.FD 0 +void _XCloseLC(\fIlcd\fP) +.br + XLCd \fIlcd\fP; +.FN +.LP +The +.PN _XCloseLC +function close a locale method the specified lcd. +.sp +.LP +\fBObtain Locale Method values\fP +.LP +.FD 0 +char * _XGetLCValues(\fIlcd\fP, ...) +.br + XLCd \fIlcd\fP; +.FN +.LP +The +.PN _XGetLCValues +function returns NULL if no error occurred; otherwise, it returns the +name of the first argument that could not be obtained. +The following values are defined as standard arguments. Other values +are implementation dependent. +.LP +.TS H +tab(:); +l l l. +_ +.sp 6p +.B +Name:Type:Description +.sp 6p +_ +.sp 6p +.TH +.R +XlcNCodeset:char*:codeset part of locale name +XlcNDefaultString:char*:XDefaultString() +XlcNEncodingName:char*:encoding name +XlcNLanguage:char*:language part of locale name +XlcNMbCurMax:int:ANSI C MB_CUR_MAX +XlcNStateDependentEncoding:Bool:is state-dependent encoding or not +XlcNTerritory:char*:territory part of locale name +.sp 6p +_ +.TE +.LP +.NH 1 +Charset functions +.XS \*(SN +Charset functions +.XE +.LP +The XlcCharSet is an identifier which represents a subset of characters +(character set) in the locale object. +.LP +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef enum { + XlcUnknown, XlcC0, XlcGL, XlcC1, XlcGR, XlcGLGR, XlcOther +} XlcSide; + +typedef struct _XlcCharSetRec *XlcCharSet; + +typedef struct { + char *name; + XPointer value; +} XlcArg, *XlcArgList; + +typedef char* (*XlcGetCSValuesProc)(\fIcharset\fP, \fIargs\fP, \fInum_args\fP); + XlcCharSet \fIcharset\fP; + XlcArgList \fIargs\fP; + int \fInum_args\fP; + +typedef struct _XlcCharSetRec { + char *name; + XrmQuark xrm_name; + char *encoding_name; + XrmQuark xrm_encoding_name; + XlcSide side; + int char_size; + int set_size; + char *ct_sequence; + XlcGetCSValuesProc get_values; +} XlcCharSetRec; +.De +.sp +.LP +\fBGet an XlcCharSet\fP +.LP +.FD 0 +XlcCharSet _XlcGetCharSet(\fIname\fP) +.br + char \fI*name\fP; +.FN +.LP +The +.PN _XlcGetCharSet +function gets an XlcCharSet which corresponds to the charset name +specified by ``\fIname\fP''. +.PN _XlcGetCharSet +returns NULL, if no XlcCharSet bound to specified ``\fIname\fP''. +.LP +The following character sets are pre-registered. +.LP +.TS H +tab(@); +l l. +_ +.sp 6p +.B +Name@Description +.sp 6p +_ +.sp 6p +.TH +.R +ISO8859-1:GL@7-bit ASCII graphics (ANSI X3.4-1968), +@Left half of ISO 8859 sets +JISX0201.1976-0:GL@Left half of JIS X0201-1976 (reaffirmed 1984), +@8-Bit Alphanumeric-Katakana Code +.sp +ISO8859-1:GR@Right half of ISO 8859-1, Latin alphabet No. 1 +ISO8859-2:GR@Right half of ISO 8859-2, Latin alphabet No. 2 +ISO8859-3:GR@Right half of ISO 8859-3, Latin alphabet No. 3 +ISO8859-4:GR@Right half of ISO 8859-4, Latin alphabet No. 4 +ISO8859-7:GR@Right half of ISO 8859-7, Latin/Greek alphabet +ISO8859-6:GR@Right half of ISO 8859-6, Latin/Arabic alphabet +ISO8859-8:GR@Right half of ISO 8859-8, Latin/Hebrew alphabet +ISO8859-5:GR@Right half of ISO 8859-5, Latin/Cyrillic alphabet +ISO8859-9:GR@Right half of ISO 8859-9, Latin alphabet No. 5 +JISX0201.1976-0:GR@Right half of JIS X0201-1976 (reaffirmed 1984), +@8-Bit Alphanumeric-Katakana Code +.sp +GB2312.1980-0:GL@GB2312-1980, China (PRC) Hanzi defined as GL +GB2312.1980-0:GR@GB2312-1980, China (PRC) Hanzi defined as GR +JISX0208.1983-0:GL@JIS X0208-1983, Japanese Graphic Character Set +@defined as GL +JISX0208.1983-0:GR@JIS X0208-1983, Japanese Graphic Character Set +@defined as GR +KSC5601.1987-0:GL@KS C5601-1987, Korean Graphic Character Set +@defined as GL +KSC5601.1987-0:GR@KS C5601-1987, Korean Graphic Character Set +@defined as GR +JISX0212.1990-0:GL@JIS X0212-1990, Japanese Graphic Character Set +@defined as GL +JISX0212.1990-0:GR@JIS X0212-1990, Japanese Graphic Character Set +@defined as GR +.\" CNS11643.1986-0:GL +.\" CNS11643.1986-1:GL +.\" TIS620-0:GR +.sp 6p +_ +.TE +.LP +.sp +\fBAdd an XlcCharSet\fP +.LP +.FD 0 +Bool _XlcAddCharSet(\fIcharset\fP) + XlcCharSet \fIcharset\fP; +.FN +.LP +The +.PN _XlcAddCharSet +function registers XlcCharSet specified by ``\fIcharset\fP''. +.LP +.sp +\fBObtain Character Set values\fP +.LP +.FD 0 +char * _XlcGetCSValues(\fIcharset\fP, ...) +.br + XlcCharSet \fIcharset\fP; +.FN +.LP +The +.PN _XlcGetCSValues +function returns NULL if no error occurred; +otherwise, it returns the name of the first argument that could not +be obtained. The following values are defined as standard arguments. +Other values are implementation dependent. +.LP +.TS H +tab(:); +l l l. +_ +.sp 6p +.B +Name:Type:Description +.sp 6p +_ +.sp 6p +.TH +.R +XlcNName:char*:charset name +XlcNEncodingName:char*:XLFD CharSet Registry and Encoding +XlcNSide:XlcSide:charset side (GL, GR, ...) +XlcNCharSize:int:number of octets per character +XlcNSetSize:int:number of character sets +XlcNControlSequence:char*:control sequence of Compound Text +.sp 6p +_ +.TE +.LP +.NH 1 +Converter Functions +.XS \*(SN Converter Functions +.XE +.LP +We provide a set of the common converter APIs, that are independent +from both of source and destination text type. +.LP +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef struct _XlcConvRec *XlcConv; + +typedef void (*XlcCloseConverterProc)(\fIconv\fP); + XlcConv \fIconv\fP; + +typedef int (*XlcConvertProc)(\fIconv\fP, \fIfrom\fP, \fIfrom_left\fP, \fIto\fP, \fIto_left\fP, \fIargs\fP, \fInum_args\fP); + XlcConv \fIconv\fP; + XPointer \fI*from\fP; + int \fI*from_left\fP; + XPointer \fI*to\fP; + int \fI*to_left\fP; + XPointer \fI*args\fP; + int \fInum_args\fP; + +typedef void (*XlcResetConverterProc)(\fIconv\fP); + XlcConv \fIconv\fP; + +typedef struct _XlcConvMethodsRec { + XlcCloseConverterProc close; + XlcConvertProc convert; + XlcResetConverterProc reset; +} XlcConvMethodsRec, *XlcConvMethods; + +typedef struct _XlcConvRec { + XlcConvMethods methods; + XPointer state; +} XlcConvRec; +.De +.LP +.sp +\fBOpen a converter\fP +.LP +.FD 0 +XlcConv _XlcOpenConverter(\fIfrom_lcd\fP, \fIfrom_type\fP, \fIto_lcd\fP, \fIto_type\fP) +.br + XLCd \fIfrom_lcd\fP; +.br + char \fI*from_type\fP; +.br + XLCd \fIto_lcd\fP; +.br + char \fI*to_type\fP; +.FN +.LP +.PN _XlcOpenConverter +function opens the converter which converts a text from specified +``\fIfrom_type\fP'' to specified ``\fIto_type\fP'' encoding. If the +function cannot find proper converter or cannot open a corresponding +converter, it returns NULL. Otherwise, it returns the conversion +descriptor. +.LP +The following types are pre-defined. Other types are implementation +dependent. +.LP +.TS H +tab(:); +l l l l. +_ +.sp 6p +.B +Name:Type:Description:Arguments +.sp 6p +_ +.sp 6p +.TH +.R +XlcNMultiByte:char *:multibyte:- +XlcNWideChar:wchar_t *:wide character:- +XlcNCompoundText:char *:COMPOUND_TEXT:- +XlcNString:char *:STRING:- +XlcNCharSet:char *:per charset:XlcCharSet +XlcNChar:char *:per character:XlcCharSet +.sp 6p +_ +.TE +.LP +.sp +\fBClose a converter\fP +.LP +.FD 0 +void _XlcCloseConverter(\fIconv\fP) +.br + XlcConv \fIconv\fP; +.FN +.LP +The +.PN _XlcCloseConverter +function closes the specified converter ``\fIconv\fP''. +.LP +.sp +\fBCode conversion\fP +.LP +.FD 0 +int _XlcConvert(\fIconv\fP, \fIfrom\fP, \fIfrom_left\fP, \fIto\fP, \fIto_left\fP, \fIargs\fP, \fInum_args\fP) +.br + XlcConv \fIconv\fP; +.br + XPointer \fI*from\fP; +.br + int \fI*from_left\fP; +.br + XPointer \fI*to\fP; +.br + int \fI*to_left\fP; +.br + XPointer \fI*args\fP; +.br + int \fInum_args\fP; +.FN +.LP +The +.PN _XlcConvert +function converts a sequence of characters from one type, in the array +specified by ``\fIfrom\fP'', into a sequence of corresponding characters +in another type, in the array specified by ``\fIto\fP''. The types are +those specified in the +.PN _XlcOpenConverter() +call that returned the conversion descriptor, ``\fIconv\fP''. +The arguments ``\fIfrom\fP'', ``\fIfrom_left\fP'', ``\fIto\fP'' and +``\fIto_left\fP'' have the same specification of XPG4 iconv function. +.LP +For state-dependent encodings, the conversion descriptor ``\fIconv\fP'' +is placed into its initial shift state by a call for which ``\fIfrom\fP'' +is a NULL pointer, or for which ``\fIfrom\fP'' points to a null pointer. +.LP +The following 2 converters prepared by locale returns appropriate +charset (XlcCharSet) in an area pointed by args[0]. +.LP +.TS +tab(:); +l l l. +_ +.sp 6p +.B +From:To:Description +.sp 6p +_ +.sp 6p +.R +XlcNMultiByte:XlcNCharSet:Segmentation (Decomposing) +XlcNWideChar:XlcNCharSet:Segmentation (Decomposing) +.sp 6p +_ +.TE +.LP +The conversion, from XlcNMultiByte/XlcNWideChar to XlcNCharSet, +extracts a segment which has same charset encoding characters. +More than one segment cannot be converted in a call. +.LP +.sp +\fBReset a converter\fP +.LP +.FD 0 +void _XlcResetConverter(\fIconv\fP) +.br + XlcConv \fIconv\fP; +.FN +.LP +The +.PN _XlcResetConverter +function reset the specified converter ``\fIconv\fP''. +.LP +.sp +\fBRegister a converter\fP +.LP +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef XlcConv (*XlcOpenConverterProc)(\fIfrom_lcd\fP, \fIfrom_type\fP, \fIto_lcd\fP, \fIto_type\fP); + XLCd \fIfrom_lcd\fP; + char \fI*from_type\fP; + XLCd \fIto_lcd\fP; + char \fI*to_type\fP; +.De +.LP +.FD 0 +Bool _XlcSetConverter(\fIfrom_lcd\fP, \fIfrom\fP, \fIto_lcd\fP, \fIto\fP, \fIconverter\fP) +.br + XLCd \fIfrom_lcd\fP; +.br + char \fI*from\fP; +.br + XLCd \fIto_lcd\fP; +.br + char \fI*to\fP; +.br + XlcOpenConverterProc \fIconverter\fP; +.FN +.LP +The \fBXlcSetConverter\fP function registers a converter which convert +from ``\fIfrom_type\fP'' to ``\fIto_type\fP'' into the converter list +(in the specified XLCd). +.LP +.NH 1 +X Locale Database functions +.XS \*(SN X Locale Database functions +.XE +.LP +X Locale Database contains the subset of user's environment that +depends on language. The following APIs are provided for accessing +X Locale Database and other locale relative files. +.LP +For more detail about X Locale Database, please refer +X Locale Database Definition document. +.LP +.sp +\fBGet a resource from database\fP +.LP +.FD 0 +void _XlcGetResource(\fIlcd\fP, \fIcategory\fP, \fIclass\fP, \fIvalue\fP, \fIcount\fP) +.br + XLCd \fIlcd\fP; +.br + char \fI*category\fP; +.br + char \fI*class\fP; +.br + char \fI***value\fP; +.br + int \fI*count\fP; +.FN +.LP +The +.PN _XlcGetResource +function obtains a locale dependent data which is associated with the +locale of specified ``\fIlcd\fP''. +The locale data is provided by system locale or by X Locale Database +file, and what kind of data is available is implementation dependent. +.LP +The specified ``\fIcategory\fP'' and ``\fIclass\fP'' are used for +finding out the objective locale data. +.LP +The returned value is returned in value argument in string list form, +and the returned count shows the number of strings in the value. +.LP +The returned value is owned by locale method, and should not be modified +or freed by caller. +.LP +.sp +\fBGet a locale relative file name\fP +.LP +.FD 0 +char * _XlcFileName(\fIlcd\fP, \fIcategory\fP) +.br + XLCd \fIlcd\fP; +.br + char \fI*category\fP; +.FN +.LP +The +.PN _XlcFileName +functions returns a file name which is bound to the specified ``\fIlcd\fP'' +and ``\fIcategory\fP'', as a null-terminated string. If no file name can +be found, or there is no readable file for the found file name, +.PN _XlcFileName +returns NULL. The returned file name should be freed by caller. +.LP +The rule for searching a file name is implementation dependent. +In current implementation, +.PN _XlcFileName +uses ``{category}.dir'' file as mapping table, which has pairs of +strings, a full locale name and a corresponding file name. +.LP +.NH 1 +Utility Functions +.XS \*(SN Utility Functions +.XE +.LP +\fBCompare Latin-1 strings\fP +.LP +.FD 0 +int _XlcCompareISOLatin1(\fIstr1\fP, \fIstr2\fP) +.br + char \fI*str1\fP, \fI*str2\fP; +.FN +.FD 0 +int _XlcNCompareISOLatin1(\fIstr1\fP, \fIstr2\fP, \fIlen\fP) +.br + char \fI*str1\fP, \fI*str2\fP; +.br + int \fIlen\fP; +.FN +.LP +The +.PN _XlcCompareIsoLatin1 +function to compares two ISO-8859-1 strings. Bytes representing ASCII lower +case letters are converted to upper case before making the comparison. +The value returned is an integer less than, equal to, or greater than +zero, depending on whether ``\fIstr1\fP'' is lexicographicly less than, +equal to, or greater than ``\fIstr2\fP''. +.LP +The +.PN _XlcNCompareIsoLatin1 +function is identical to +.PN _XlcCompareISOLatin1, +except that at most ``\fIlen\fP'' bytes are compared. +.LP +.sp +\fBResource Utility\fP +.LP +.FD 0 +int XlcNumber(\fIarray\fP) + ArrayType \fIarray\fP; +.FN +.LP +Similar to XtNumber. +.LP +.FD 0 +void _XlcCopyFromArg(\fIsrc\fP, \fIdst\fP, \fIsize\fP) +.br + char \fI*src\fP; +.br + char \fI*dst\fP; +.br + int \fIsize\fP; +.FN +.FD 0 +void _XlcCopyToArg(\fIsrc\fP, \fIdst\fP, \fIsize\fP) +.br + char \fI*src\fP; +.br + char \fI**dst\fP; +.br + int \fIsize\fP; +.FN +.LP +Similar to +.PN _XtCopyFromArg +and +.PN _XtCopyToArg. +.LP +.FD 0 +void _XlcCountVaList(\fIvar\fP, \fIcount_ret\fP) +.br + va_list \fIvar\fP; +.br + int \fI*count_ret\fP; +.FN +.LP +Similar to +.PN _XtCountVaList. +.LP +.FD 0 +void _XlcVaToArgList(\fIvar\fP, \fIcount\fP, \fIargs_ret\fP) +.br + va_list \fIvar\fP; +.br + int \fIcount\fP; +.br + XlcArgList \fI*args_ret\fP; +.FN +.LP +Similar to +.PN _XtVaToArgList. +.LP +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef struct _XlcResource { + char *name; + XrmQuark xrm_name; + int size; + int offset; + unsigned long mask; +} XlcResource, *XlcResourceList; +.De +.LP +.TS +lw(.5i) lw(2i) lw(2i). +T{ +#define +T} T{ +XlcCreateMask +T} T{ +(1L<<0) +T} +T{ +#define +T} T{ +XlcDefaultMask +T} T{ +(1L<<1) +T} +T{ +#define +T} T{ +XlcGetMask +T} T{ +(1L<<2) +T} +T{ +#define +T} T{ +XlcSetMask +T} T{ +(1L<<3) +T} +T{ +#define +T} T{ +XlcIgnoreMask +T} T{ +(1L<<4) +T} +.TE +.LP +.FD 0 +void _XlcCompileResourceList(\fIresources\fP, \fInum_resources\fP) +.br + XlcResourceList \fIresources\fP; +.br + int \fInum_resources\fP; +.FN +.LP +Similar to +.PN _XtCompileResourceList. +.LP +.FD 0 +char * _XlcGetValues(\fIbase\fP, \fIresources\fP, \fInum_resources\fP, \fIargs\fP, \fInum_args\fP, \fImask\fP) +.br + XPointer \fIbase\fP; +.br + XlcResourceList \fIresources\fP; +.br + int \fInum_resources\fP; +.br + XlcArgList \fIargs\fP; +.br + int \fInum_args\fP; +.br + unsigned long \fImask\fP; +.FN +.LP +Similar to XtGetSubvalues. +.LP +.FD 0 +char * _XlcSetValues(\fIbase\fP, \fIresources\fP, \fInum_resources\fP, \fIargs\fP, \fInum_args\fP, \fImask\fP) +.br + XPointer \fIbase\fP; +.br + XlcResourceList \fIresources\fP; +.br + int \fInum_resources\fP; +.br + XlcArgList \fIargs\fP; +.br + int \fInum_args\fP; +.br + unsigned long \fImask\fP; +.FN +.LP +Similar to XtSetSubvalues. +.LP +.sp +\fBANSI C Compatible Functions\fP +.LP +The following are ANSI C/MSE Compatible Functions for non-ANSI C environment. +.LP +.FD 0 +int _Xmblen(\fIstr\fP, \fIlen\fP) +.br + char \fI*str\fP; +.br + int \fIlen\fP; +.FN +.LP +The +.PN _Xmblen +function returns the number of characters pointed to by ``\fIstr\fP''. +Only ``\fIlen\fP'' bytes in ``\fIstr\fP'' are used in determining the +character count returned. ``\fIStr\fP'' may point at characters from +any valid codeset in the current locale. +.LP +The call +.PN _Xmblen +is equivalent to +.RS +_Xmbtowc(_Xmbtowc((\fIwchar_t*\fP)NULL, \fIstr\fP, \fIlen\fP)) +.RE +.LP +.FD 0 +int _Xmbtowc(\fIwstr\fP, \fIstr\fP, \fIlen\fP) +.br + wchar_t \fI*wstr\fP; +.br + char \fI*str\fP; +.br + int \fIlen\fP; +.FN +.LP +The +.PN _Xmbtowc +function converts the character(s) pointed to by ``\fIstr\fP'' +to their wide character representation(s) pointed to by ``\fIwstr\fP''. +``\fILen\fP'' is the number of bytes in ``\fIstr\fP'' to be converted. +The return value is the number of characters converted. +.LP +The call +.PN _Xmbtowc +is equivalent to +.RS +_Xlcmbtowc((XLCd)NULL, \fIwstr\fP, \fIstr\fP, \fIlen\fP) +.RE +.LP +.FD 0 +int _Xlcmbtowc(\fIlcd\fP, \fIwstr\fP, \fIstr\fP, \fIlen\fP) +.br + XLCd \fIlcd\fP; +.br + wchar_t \fI*wstr\fP; +.br + char \fI*str\fP; +.br + int \fIlen\fP; +.FN +.LP +The +.PN _Xlcmbtowc +function is identical to +.PN _Xmbtowc, +except that it requires the ``\fIlcd\fP'' argument. If ``\fIlcd\fP'' +is (XLCd) NULL, +.PN _Xlcmbtowc, +calls +.PN _XlcCurrentLC +to determine the current locale. +.LP +.FD 0 +int _Xwctomb(\fIstr\fP, \fIwc\fP) +.br + char \fI*str\fP; +.br + wchar_t \fIwc\fP; +.FN +.LP +The +.PN _Xwctomb +function converts a single wide character pointed to by ``\fIwc\fP'' to +its multibyte representation pointed to by ``\fIstr\fP''. +On success, the return value is 1. +.LP +The call +.PN _Xwctomb +is equivalent to +.RS +_Xlcwctomb((XLCd)NULL, \fIstr\fP, \fIwstr\fP) +.RE +.LP +.FD 0 +int _Xlcwctomb(\fIlcd\fP, \fIstr\fP, \fIwc\fP) +.br + XLCd \fIlcd\fP; +.br + char \fI*str\fP; +.br + wchar_t \fIwc\fP; +.FN +.LP +The +.PN _Xlcwctomb +function is identical to _Xwctomb, except that it requires the +``\fIlcd\fP'' argument. If ``\fIlcd\fP'' is (XLCd) NULL, +.PN _Xlcwctomb, +calls +.PN _XlcCurrentLC +to determine the current locale. +.LP +.FD 0 +int _Xmbstowcs(\fIwstr\fP, \fIstr\fP, \fIlen\fP) +.br + wchar_t \fI*wstr\fP; +.br + char \fI*str\fP; +.br + int \fIlen\fP; +.FN +.LP +The +.PN _Xmbstowcs +function converts the NULL-terminated string pointed to by ``\fIstr\fP'' +to its wide character string representation pointed to by ``\fIwstr\fP''. +``\fILen\fP'' is the number of characters in ``\fIstr\fP'' to be converted. +.LP +The call +.PN _Xmbstowcs +is equivalent to +.RS +_Xlcmbstowcs((XLCd)NULL, \fIwstr\fP, \fIstr\fP, \fIlen\fP) +.RE +.LP +.FD 0 +int _Xlcmbstowcs(\fIlcd\fP, \fIwstr\fP, \fIstr\fP, \fIlen\fP) +.br + XLCd \fIlcd\fP; +.br + wchar_t \fI*wstr\fP; +.br + char \fI*str\fP; +.br + int \fIlen\fP; +.FN +.LP +The +.PN _Xlcmbstowcs +function is identical to _Xmbstowcs, except that it requires the +``\fIlcd\fP'' argument. If ``\fIlcd\fP'' is (XLCd) NULL, +.PN _Xlcmbstowcs, +calls +.PN _XlcCurrentLC +to determine the current locale. +.LP +.FD 0 +int _Xwcstombs(\fIstr\fP, \fIwstr\fP, \fIlen\fP) +.br + char \fI*str\fP; +.br + wchar_t \fI*wstr\fP; +.br + int \fIlen\fP; +.FN +.LP +The +.PN _Xwcstombs +function converts the (wchar_t) NULL terminated wide character string +pointed to by ``\fIwstr\fP'' to the NULL terminated multibyte string +pointed to by ``\fIstr\fP''. +.LP +The call +.PN _Xwcstombs +is equivalent to +.RS +_Xlcwcstombs((XLCd)NULL, \fIstr\fP, \fIwstr\fP, \fIlen\fP) +.RE +.LP +.FD 0 +int _Xlcwcstombs(\fIlcd\fP, \fIstr\fP, \fIwstr\fP, \fIlen\fP) +.br + XLCd \fIlcd\fP; +.br + char \fI*str\fP; +.br + wchar_t \fI*wstr\fP; +.br + int \fIlen\fP; +.FN +.LP +The +.PN _Xlcwcstombs +function is identical to _Xwcstombs, except that it requires the +``\fIlcd\fP'' argument. If ``\fIlcd\fP'' is (XLCd) NULL, +.PN _Xlcwcstombs, +calls +.PN _XlcCurrentLC +to determine the current locale. +.LP +.FD 0 +int _Xwcslen(\fIwstr\fP) +.br + wchar_t \fI*wstr\fP; +.FN +.LP +The +.PN _Xwcslen +function returns the count of wide characters in the (wchar_t) NULL +terminated wide character string pointed to by ``\fIwstr\fP''. +.LP +.FD 0 +wchar_t * _Xwcscpy(\fIwstr1\fP, \fIwstr2\fP) +.br + wchar_t \fI*wstr1\fP, \fI*wstr2\fP; +.FN +.FD 0 +wchar_t * _Xwcsncpy(\fIwstr1\fP, \fIwstr2\fP, \fIlen\fP) +.br + wchar_t \fI*wstr1\fP, \fI*wstr2\fP; +.br + int \fIlen\fP; +.FN +.LP +The +.PN _Xwcscpy +function copies the (wchar_t) NULL terminated wide character string +pointed to by ``\fIwstr2\fP'' to the object pointed at by ``\fIwstr1\fP''. +``\fIWstr1\fP'' is (wchar_t) NULL terminated. The return value is a +pointer to ``\fIwstr1\fP''. +.LP +The +.PN _Xwcsncpy +function is identical to +.PN _Xwcscpy, +except that it copies ``\fIlen\fP'' wide characters from the object +pointed to by ``\fIwstr2\fP'' to the object pointed to ``\fIwstr1\fP''. +.LP +.FD 0 +int _Xwcscmp(\fIwstr1\fP, \fIwstr2\fP) +.br + wchar_t \fI*wstr1\fP, \fI*wstr2\fP; +.FN +.FD 0 +int _Xwcsncmp(\fIwstr1\fP, \fIwstr2\fP, \fIlen\fP) +.br + wchar_t \fI*wstr1\fP, \fI*wstr2\fP; +.br + int \fIlen\fP; +.FN +.LP +The +.PN _Xwcscmp +function compares two (wchar_t) NULL terminated wide character strings. +The value returned is an integer less than, equal to, or greater than zero, +depending on whether ``\fIwstr1\fP'' is lexicographicly less then, equal to, +or greater than ``\fIstr2\fP''. +.LP +The +.PN _Xwcsncmp +function is identical to +.PN _XlcCompareISOLatin1, +except that at most ``\fIlen\fP'' wide characters are compared. +.sp +.\" -------------------------------------------------------------------- +.\" .LP +.\" \fBLocale Method Internal Functions\fP +.\" .LP +.\" .FD 0 +.\" XlcCharSet _XlcCreateDefaultCharSet(\fIname\fP, \fIct_sequence\fP) +.\" .br +.\" char \fI*name\fP; +.\" .br +.\" char \fI*ct_sequence\fP; +.\" .FN +.\" .FD 0 +.\" Bool _XlcParseCharSet(\fIcharset\fP) +.\" .br +.\" XlcCharSet \fIcharset\fP; +.\" .FN +.\" .FD 0 +.\" void _XlcGetLocaleDataBase(\fIlcd\fP, \fIcategory\fP, \fIname\fP, \fIvalue\fP, \fIcount\fP) +.\" .br +.\" XLCd \fIlcd\fP; +.\" .br +.\" char \fI*category\fP; +.\" .br +.\" char \fI*name\fP; +.\" .br +.\" char \fI***value\fP; +.\" .br +.\" int \fI*count\fP; +.\" .FN +.\" .FD 0 +.\" void _XlcDestroyLocaleDataBase(\fIlcd\fP) +.\" .br +.\" XLCd \fIlcd\fP; +.\" .FN +.\" .FD 0 +.\" XPointer _XlcCreateLocaleDataBase(\fIlcd\fP) +.\" .br +.\" XLCd \fIlcd\fP; +.\" .FN +.\" .LP +.\" .sp +.\" \fBObtain an locale database path\fP +.\" .LP +.\" .FD 0 +.\" int _XlcResolveI18NPath(\fIdir\fP) +.\" .br +.\" char \fI*dir\fP; +.\" .FN +.\" .LP +.\" The +.\" .PN _XlcResolveI18NPath +.\" function returns path name list that is related to X Locale Database. +.\" The obtained path is stored into the array which is pointed by +.\" specified ``\fIdir\fP''. The path consists of directory paths which +.\" are separated with colon. +.\" If the environment variable XLOCALEDIR is specified, the path +.\" contains its contents. +.\" .LP +.\" The default path of X Locale Database is implementation dependent. +.\" In current implementation, it's determined in build time. +.\" .LP +.\" .PN _XlcResolveI18NPath +.\" does not check overflow of the array to which the ``\fIdir\fP'' +.\" parameter points. Caller should provide enough buffer to store this +.\" string. +.\" .LP +.\" .sp +.\" \fBObtain a full locale name\fP +.\" .LP +.\" .FD 0 +.\" int _XlcResolveLocaleName(\fIlc_name\fP, \fIfull_name\fP, \fIlanguage\fP, \fIterritory\fP, \fIcodeset\fP) +.\" .br +.\" char \fI*lc_name\fP; +.\" .br +.\" char \fI*full_name\fP; +.\" .br +.\" char \fI*language\fP; +.\" .br +.\" char \fI*territory\fP; +.\" .br +.\" char \fI*codeset\fP; +.\" .FN +.\" .LP +.\" The +.\" .PN _XlcResolveLocaleName +.\" function returns a full locale name. +.\" The obtained full locale name is stored into the array which is +.\" pointed by specified ``\fIfull_name\fP''. +.\" The language, territory and codeset part of the full locale name +.\" are copied to the return arguments, ``\fIlanguage\fP'', +.\" ``\fIterritory\fP'' and ``\fIcodeset\fP'', respectively. +.\" NULL can be specified for these arguments. +.\" .LP +.\" The rule for mapping from locale name to full locale name is +.\" implementation dependent. +.\" .LP +.\" .PN _XlcResolveLocaleName +.\" does not check overflow of the array to which +.\" ``\fIfull_name\fP'', ``\fIlanguage\fP'', ``\fIterritory\fP'' and +.\" ``\fIcodeset\fP'' parameter point. +.\" Caller should provide enough buffer to store those string. +.\" .LP +.\" In current implementation, +.\" .PN _XlcResolveLocaleName +.\" uses locale.alias file as mapping table, which has pairs of strings, +.\" a locale name and a full locale name. +.\" .LP +.\" .FD 0 +.\" int _XlcResolveDBName(\fIlc_name\fP, \fIfile_name\fP) +.\" .br +.\" char \fI*lc_name\fP; +.\" .br +.\" char \fI*file_name\fP; +.\" .FN +.\" .FD 0 +.\" XLCd _XlcCreateLC(\fIname\fP, \fImethods\fP) +.\" .br +.\" char \fI*name\fP; +.\" .br +.\" XLCdMethods \fImethods\fP; +.\" .FN +.\" .FD 0 +.\" void _XlcDestroyLC(\fIlcd\fP) +.\" .br +.\" XLCd \fIlcd\fP; +.\" .FN +.\" .LP +.\" + diff --git a/libX11/specs/i18n/LocaleDB.ms b/libX11/specs/i18n/LocaleDB.ms new file mode 100644 index 000000000..5ba792297 --- /dev/null +++ b/libX11/specs/i18n/LocaleDB.ms @@ -0,0 +1,502 @@ +.\" $Xorg: LocaleDB.ms,v 1.3 2000/08/17 19:42:49 cpqbld Exp $ +.\" $XdotOrg: xc/doc/specs/i18n/LocaleDB.ms,v 1.2 2004/04/23 18:42:19 eich Exp $ +.\" To print this out, type tbl macros.t ThisFile | troff -ms +.EH '''' +.OH '''' +.EF '''' +.OF '''' +.ps 11 +.nr PS 11 +\& +.TL +\s+3\fBX Locale Database Definition\fP\s-3 +.sp 2 +.AU +Yoshio Horiuchi +.AI +IBM Japan +.LP +.bp +.br +\& +.ps 9 +.nr PS 9 +.sp 2 +.LP +Copyright \(co IBM Corporation 1994 +.LP +All Rights Reserved +.LP +License to use, copy, modify, and distribute this software and its +documentation for any purpose and without fee is hereby granted, +provided that the above copyright notice appear in all copies and that +both that copyright notice and this permission notice appear in +supporting documentation, and that the name of IBM not be +used in advertising or publicity pertaining to distribution of the +software without specific, written prior permission. +.LP +IBM DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING +ALL IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS, AND +NONINFRINGEMENT OF THIRD PARTY RIGHTS, IN NO EVENT SHALL +IBM BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR +ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, +WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, +ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS +SOFTWARE. +.sp 5 +Copyright \(co 1994 X Consortium +.LP +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the ``Software''), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: +.LP +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. +.LP +THE SOFTWARE IS PROVIDED ``AS IS'', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN +AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN +CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +.LP +Except as contained in this notice, the name of the X Consortium shall not be +used in advertising or otherwise to promote the sale, use or other dealings +in this Software without prior written authorization from the X Consortium. +.sp 3 +\fIX Window System\fP is a trademark of The Open Group. +.LP +.bp 1 +.ps 11 +.nr PS 11 +.EH '\fBX Locale Database Definition\fP''\fB\*(xV\fP' +.OH '\fBX Locale Database Definition\fP''\fB\*(xV\fP' +.EF ''\fB % \fP'' +.OF ''\fB % \fP'' +.NH 1 +General +.XS +\*(SN General +.XE +.LP +An X Locale Database contains the subset of a user's environment that +depends on language, in X Window System. It is made up from one or more +categories. Each category consists of some classes and sub-classes. +.LP +It is provided as a plain ASCII text file, so a user can change its +contents easily. It allows a user to customize the behavior of +internationalized portion of Xlib without changing Xlib itself. +.LP +This document describes; +.RS +.IP +Database Format Definition +.IP +Contents of Database in sample implementation +.RE +.LP +Since it is hard to define the set of required information for all +platforms, only the flexible database format is defined. +The available entries in database are implementation dependent. +.LP +.NH 1 +Database Format Definition +.XS +\*(SN Database Format Definition +.XE +.LP +The X Locale Database contains one or more category definitions. +This section describes the format of each category definition. +.LP +The category definition consists of one or more class definitions. +Each class definition has a pair of class name and class value, or +has several subclasses which are enclosed by the left brace ({) and +the right brace (}). +.LP +Comments can be placed by using the number sign character (#). +Putting the number sign character on the top of the line indicates +that the entire line is comment. Also, putting any whitespace character +followed by the number sign character indicates that a part of the line +(from the number sign to the end of the line) is comment. +A line can be continued by placing backslash (\\) character as the +last character on the line; this continuation character will be +discarded from the input. Comment lines cannot be continued on +a subsequent line using an escaped new line character. +.LP +X Locale Database only accepts XPCS, the X Portable Character Set. +The reserved symbols are; the quotation mark("), the number sign (#), +the semicolon(;), the backslash(\\), the left brace({) and +the right brace(}). +.LP +The format of category definition is; +.RS +.TS +tab(@); +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l r l +l r l +l l l. +CategoryDefinition@::=@CategoryHeader CategorySpec CategoryTrailer +CategoryHeader@::=@CategoryName NL +CategorySpec@::=@{ ClassSpec } +CategoryTrailer@::=@"END" Delimiter CategoryName NL +CategoryName@::=@String +ClassSpec@::=@ClassName Delimiter ClassValue NL +ClassName@::=@String +ClassValue@::=@ValueList | "{" NL { ClassSpec } "}" +ValueList@::=@Value | Value ";" ValueList +Value@::=@ValuePiece | ValuePiece Value +ValuePiece@::=@String | QuotedString | NumericString +String@::=@Char { Char } +QuotedString@::=@""" QuotedChar { QuotedChar } """ +NumericString@::=@"\\\\o" OctDigit { OctDigit } +@|@"\\\\d" DecDigit { DecDigit } +@|@"\\\\x" HexDigit { HexDigit } +Char@::=@ +QuotedChar@::=@ +OctDigit@::=@ +DecDigit@::=@ +HexDigit@::=@ +Delimiter@::=@ Space { Space } +Space@::=@ | +NL@::=@ +.TE +.RE +.LP +Elements separated by vertical bar (|) are alternatives. Curly +braces ({...}) indicate zero or more repetitions of the enclosed +elements. Square brackets ([...]) indicate that the enclosed element +is optional. Quotes ("...") are used around literal characters. +.LP +The backslash, which is not the top character of the NumericString, is +recognized as an escape character, so that the next one character is +treated as a literal character. For example, the two-character +sequence, ``\\"''(the backslash followed by the quotation mark) is +recognized and replaced with a quotation mark character. +Any whitespace character, that is not the Delimiter, unquoted and +unescaped, is ignored. +.LP +.NH 1 +Contents of Database +.XS +\*(SN Contents of Database +.XE +.LP +The available categories and classes depend on implementation, because +different platform will require different information set. +For example, some platform have system locale but some platform don't. +Furthermore, there might be a difference in functionality even if the +platform has system locale. +.LP +In current sample implementation, categories listed below are available. +.RS +.TS +tab(:); +l l. +XLC_FONTSET:XFontSet relative information +XLC_XLOCALE:Character classification and conversion information +.TE +.RE +.LP +.NH 1 +XLC_FONTSET Category +.XS +\*(SN XLC_FONTSET Category +.XE +.LP +The XLC_FONTSET category defines the XFontSet relative information. +It contains the CHARSET_REGISTRY-CHARSET_ENCODING name and character +mapping side (GL, GR, etc), and is used in Output Method (OM). +.RS +.TS H +tab(:); +lw(1.5i) l l. +_ +.sp 6p +.B +class:super class:description +.sp 6p +_ +.sp 6p +.TH +.R +fsN::Nth fontset (N=0,1,2, ...) +.sp +charset:fsN:list of encoding name +font:fsN:list of font encoding name +.sp 6p +_ +.TE +.RE +.LP +.IP "fsN" +.br +Includes an encoding information for Nth charset, where N is +the index number (0,1,2,...). If there are 4 charsets available +in current locale, 4 fontsets, fs0, fs1, fs2 and fs3, should be +defined. +This class has two subclasses, `charset' and `font'. +.IP "charset" +Specifies an encoding information to be used internally in Xlib +for this fontset. The format of value is; +.RS +.TS +tab(;); +l l l. +EncodingInfo;::=;EncodingName [ ":" EncodingSide ] +EncodingName;::=;CHARSET_REGISTRY-CHARSET_ENCODING +EncodingSide;::=;"GL" | "GR" +.TE +.RE +For detail definition of CHARSET_REGISTRY-CHARSET_ENCODING, refer +"X Logical Font Descriptions" document. +.IP +example: +.br + ISO8859-1:GL +.IP "font" +.br +Specifies a list of encoding information which is used for searching +appropriate font for this fontset. The left most entry has highest +priority. +.LP +.NH 1 +XLC_XLOCALE Category +.XS +\*(SN XLC_XLOCALE Category +.XE +.LP +The XLC_XLOCALE category defines character classification, conversion +and other character attributes. +.RS +.TS H +tab(:); +lw(1.5i) l l. +_ +.sp 6p +.B +class:super class:description +.sp 6p +_ +.sp 6p +.TH +.R +encoding_name::codeset name +mb_cur_max::MB_CUR_MAX +state_depend_encoding::state dependent or not +wc_encoding_mask::for parsing wc string +wc_shift_bits::for conversion between wc and mb +csN::Nth charset (N=0,1,2,...) +.sp +side:csN:mapping side (GL, etc) +length:csN:length of a character +mb_encoding:csN:for parsing mb string +wc_encoding:csN:for parsing wc string +ct_encoding:csN:list of encoding name for ct +.sp 6p +_ +.TE +.RE +.LP +.IP "encoding_name" +Specifies a codeset name of current locale. +.IP "mb_cur_max" +Specifies a maximum allowable number of bytes in a multi-byte character. +It is corresponding to MB_CUR_MAX of "ISO/IEC 9899:1990 C Language Standard". +.IP "state_depend_encoding" +Indicates a current locale is state dependent. The value should be +specified "True" or "False". +.IP "wc_encoding_mask" +Specifies a bit-mask for parsing wide-char string. Each wide character is +applied bit-and operation with this bit-mask, then is classified into +the unique charset, by using `wc_encoding'. +.IP "wc_shift_bits" +Specifies a number of bit to be shifted for converting from a multi-byte +character to a wide character, and vice-versa. +.IP "csN" +.br +Includes a character set information for Nth charset, where N is the +index number (0,1,2,...). If there are 4 charsets available in current +locale, cs0, cs1, cs2 and cs3 should be defined. This class has five +subclasses, `side', `length', `mb_encoding' `wc_encoding' and `ct_encoding'. +.IP "side" +.br +Specifies a mapping side of this charset. The format of this value is; +.RS +.TS +tab(@); +l l l. +Side@::=@EncodingSide [``:Default''] +.TE +.RE +The suffix ":Default" can be specified. It indicates that a character +belongs to the specified side is mapped to this charset in initial state. +.IP "length" +.br +Specifies a number of bytes of a multi-byte character of this charset. +It should not contain the length of any single-shift sequence. +.IP "mb_encoding" +Specifies a list of shift sequence for parsing multi-byte string. +The format of this value is; +.RS +.TS +tab(@); +l l l +l r l +l l l +l l l +l l l +l l l +c l s +c l s. +MBEncoding@::=@ShiftType ShiftSequence +@|@ShiftType ShiftSequence ";" MBEncoding +ShiftType@::=@"" | "" | "" +ShiftSequence@::=@SequenceValue | SequenceValue ShiftSequence +SequenceValue@::=@NumericString +.sp +shift types: +@Indicates single shift sequence +@Indicates locking shift left sequence +@Indicates locking shift right sequence +.TE +.RE +example: +.br + \\x1b \\x28 \\x4a; \\x1b \\x28 \\x42 +.LP +.IP "wc_encoding" +Specifies an integer value for parsing wide-char string. +It is used to determine the charset for each wide character, after +applying bit-and operation using `wc_encoding_mask'. +This value should be unique in all csN classes. +.IP "ct_encoding" +Specifies a list of encoding information that can be used for Compound +Text. +.LP +.NH 1 +Sample of X Locale Database +.XS +\*(SN Sample of X Locale Database +.XE +.LP +The following is sample X Locale Database file. +.LP +.sp +.RS +.nf +# $Xorg: LocaleDB.ms,v 1.3 2000/08/17 19:42:49 cpqbld Exp $ +# XLocale Database Sample for ja_JP.euc +# + +# +# XLC_FONTSET category +# +XLC_FONTSET +# fs0 class (7 bit ASCII) +fs0 { + charset ISO8859-1:GL + font ISO8859-1:GL; JISX0201.1976-0:GL +} +# fs1 class (Kanji) +fs1 { + charset JISX0208.1983-0:GL + font JISX0208.1983-0:GL +} +# fs2 class (Half Kana) +fs2 { + charset JISX0201.1976-0:GR + font JISX0201.1976-0:GR +} +# fs3 class (User Defined Character) +# fs3 { +# charset JISX0212.1990-0:GL +# font JISX0212.1990-0:GL +# } +END XLC_FONTSET + +# +# XLC_XLOCALE category +# +XLC_XLOCALE + +encoding_name ja.euc +mb_cur_max 3 +state_depend_encoding False + +wc_encoding_mask \\x00008080 +wc_shift_bits 8 + +# cs0 class +cs0 { + side GL:Default + length 1 + wc_encoding \\x00000000 + ct_encoding ISO8859-1:GL; JISX0201.1976-0:GL +} +# cs1 class +cs1 { + side GR:Default + length 2 + + wc_encoding \\x00008080 + + ct_encoding JISX0208.1983-0:GL; JISX0208.1983-0:GR;\\ + JISX0208.1983-1:GL; JISX0208.1983-1:GR +} + +# cs2 class +cs2 { + side GR + length 1 + mb_encoding \\x8e + + wc_encoding \\x00000080 + + ct_encoding JISX0201.1976-0:GR +} + +# cs3 class +# cs3 { +# side GL +# length 2 +# mb_encoding \\x8f +# #if HasWChar32 +# wc_encoding \\x20000000 +# #else +# wc_encoding \\x00008000 +# #endif +# ct_encoding JISX0212.1990-0:GL; JISX0212.1990-0:GR +# } + +END XLC_XLOCALE +.fi +.RE +.LP +.NH 1 +Reference +.XS +\*(SN Reference +.XE +.LP +.XP +[1] \fIISO/IEC 9899:1990 C Language Standard\fP +.XP +[2] \fIX Logical Font Descriptions\fP +.LP diff --git a/libX11/specs/i18n/Makefile.am b/libX11/specs/i18n/Makefile.am new file mode 100644 index 000000000..dff852d11 --- /dev/null +++ b/libX11/specs/i18n/Makefile.am @@ -0,0 +1,33 @@ +# +# Copyright 2009 Sun Microsystems, Inc. All rights reserved. +# +# Permission to use, copy, modify, distribute, and sell this software and its +# documentation for any purpose is hereby granted without fee, provided that +# the above copyright notice appear in all copies and that both that +# copyright notice and this permission notice appear in supporting +# documentation. +# +# The above copyright notice and this permission notice shall be included +# in all copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +# OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +# IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR +# OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +# ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +# OTHER DEALINGS IN THE SOFTWARE. +# +# Except as contained in this notice, the name of the copyright holders shall +# not be used in advertising or otherwise to promote the sale, use or +# other dealings in this Software without prior written authorization +# from the copyright holders. +# + +# Based on xc/doc/specs/i18n/Makefile from X11R6.9 + +doc_sources = Framework.ms LocaleDB.ms Trans.ms + +include $(top_srcdir)/specs/troffrules.in + + diff --git a/libX11/specs/i18n/Makefile.in b/libX11/specs/i18n/Makefile.in new file mode 100644 index 000000000..defb1686d --- /dev/null +++ b/libX11/specs/i18n/Makefile.in @@ -0,0 +1,554 @@ +# Makefile.in generated by automake 1.11 from Makefile.am. +# @configure_input@ + +# Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, +# 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, +# Inc. +# This Makefile.in is free software; the Free Software Foundation +# gives unlimited permission to copy and/or distribute it, +# with or without modifications, as long as this notice is preserved. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY, to the extent permitted by law; without +# even the implied warranty of MERCHANTABILITY or FITNESS FOR A +# PARTICULAR PURPOSE. + +@SET_MAKE@ + +# +# Copyright 2009 Sun Microsystems, Inc. All rights reserved. +# +# Permission to use, copy, modify, distribute, and sell this software and its +# documentation for any purpose is hereby granted without fee, provided that +# the above copyright notice appear in all copies and that both that +# copyright notice and this permission notice appear in supporting +# documentation. +# +# The above copyright notice and this permission notice shall be included +# in all copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +# OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +# IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR +# OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +# ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +# OTHER DEALINGS IN THE SOFTWARE. +# +# Except as contained in this notice, the name of the copyright holders shall +# not be used in advertising or otherwise to promote the sale, use or +# other dealings in this Software without prior written authorization +# from the copyright holders. +# + +# Based on xc/doc/specs/i18n/Makefile from X11R6.9 + +# +# Copyright 2009 Sun Microsystems, Inc. All rights reserved. +# +# Permission to use, copy, modify, distribute, and sell this software and its +# documentation for any purpose is hereby granted without fee, provided that +# the above copyright notice appear in all copies and that both that +# copyright notice and this permission notice appear in supporting +# documentation. +# +# The above copyright notice and this permission notice shall be included +# in all copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +# OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +# IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR +# OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +# ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +# OTHER DEALINGS IN THE SOFTWARE. +# +# Except as contained in this notice, the name of the copyright holders shall +# not be used in advertising or otherwise to promote the sale, use or +# other dealings in this Software without prior written authorization +# from the copyright holders. +# + +# Based on xc/doc/specs/*/Makefile from X11R6.9 + +VPATH = @srcdir@ +pkgdatadir = $(datadir)/@PACKAGE@ +pkgincludedir = $(includedir)/@PACKAGE@ +pkglibdir = $(libdir)/@PACKAGE@ +pkglibexecdir = $(libexecdir)/@PACKAGE@ +am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd +install_sh_DATA = $(install_sh) -c -m 644 +install_sh_PROGRAM = $(install_sh) -c +install_sh_SCRIPT = $(install_sh) -c +INSTALL_HEADER = $(INSTALL_DATA) +transform = $(program_transform_name) +NORMAL_INSTALL = : +PRE_INSTALL = : +POST_INSTALL = : +NORMAL_UNINSTALL = : +PRE_UNINSTALL = : +POST_UNINSTALL = : +build_triplet = @build@ +host_triplet = @host@ +DIST_COMMON = $(srcdir)/Makefile.am $(srcdir)/Makefile.in \ + $(top_srcdir)/specs/troffrules.in +subdir = specs/i18n +ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 +am__aclocal_m4_deps = $(top_srcdir)/acinclude.m4 \ + $(top_srcdir)/configure.ac +am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ + $(ACLOCAL_M4) +mkinstalldirs = $(install_sh) -d +CONFIG_HEADER = $(top_builddir)/src/config.h \ + $(top_builddir)/include/X11/XlibConf.h +CONFIG_CLEAN_FILES = +CONFIG_CLEAN_VPATH_FILES = +AM_V_GEN = $(am__v_GEN_$(V)) +am__v_GEN_ = $(am__v_GEN_$(AM_DEFAULT_VERBOSITY)) +am__v_GEN_0 = @echo " GEN " $@; +AM_V_at = $(am__v_at_$(V)) +am__v_at_ = $(am__v_at_$(AM_DEFAULT_VERBOSITY)) +am__v_at_0 = @ +SOURCES = +DIST_SOURCES = +am__vpath_adj_setup = srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; +am__vpath_adj = case $$p in \ + $(srcdir)/*) f=`echo "$$p" | sed "s|^$$srcdirstrip/||"`;; \ + *) f=$$p;; \ + esac; +am__strip_dir = f=`echo $$p | sed -e 's|^.*/||'`; +am__install_max = 40 +am__nobase_strip_setup = \ + srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*|]/\\\\&/g'` +am__nobase_strip = \ + for p in $$list; do echo "$$p"; done | sed -e "s|$$srcdirstrip/||" +am__nobase_list = $(am__nobase_strip_setup); \ + for p in $$list; do echo "$$p $$p"; done | \ + sed "s| $$srcdirstrip/| |;"' / .*\//!s/ .*/ ./; s,\( .*\)/[^/]*$$,\1,' | \ + $(AWK) 'BEGIN { files["."] = "" } { files[$$2] = files[$$2] " " $$1; \ + if (++n[$$2] == $(am__install_max)) \ + { print $$2, files[$$2]; n[$$2] = 0; files[$$2] = "" } } \ + END { for (dir in files) print dir, files[dir] }' +am__base_list = \ + sed '$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;s/\n/ /g' | \ + sed '$$!N;$$!N;$$!N;$$!N;s/\n/ /g' +am__installdirs = "$(DESTDIR)$(docdir)" +DATA = $(doc_DATA) +DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) +ACLOCAL = @ACLOCAL@ +ADMIN_MAN_DIR = @ADMIN_MAN_DIR@ +ADMIN_MAN_SUFFIX = @ADMIN_MAN_SUFFIX@ +AMTAR = @AMTAR@ +AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@ +APP_MAN_DIR = @APP_MAN_DIR@ +APP_MAN_SUFFIX = @APP_MAN_SUFFIX@ +AR = @AR@ +AUTOCONF = @AUTOCONF@ +AUTOHEADER = @AUTOHEADER@ +AUTOMAKE = @AUTOMAKE@ +AWK = @AWK@ +BIGFONT_CFLAGS = @BIGFONT_CFLAGS@ +BIGFONT_LIBS = @BIGFONT_LIBS@ +CC = @CC@ +CCDEPMODE = @CCDEPMODE@ +CC_FOR_BUILD = @CC_FOR_BUILD@ +CFLAGS = @CFLAGS@ +CHANGELOG_CMD = @CHANGELOG_CMD@ +CPP = @CPP@ +CPPFLAGS = @CPPFLAGS@ +CWARNFLAGS = @CWARNFLAGS@ +CXX = @CXX@ +CXXCPP = @CXXCPP@ +CXXDEPMODE = @CXXDEPMODE@ +CXXFLAGS = @CXXFLAGS@ +CYGPATH_W = @CYGPATH_W@ +DEFS = @DEFS@ +DEPDIR = @DEPDIR@ +DOLT_BASH = @DOLT_BASH@ +DRIVER_MAN_DIR = @DRIVER_MAN_DIR@ +DRIVER_MAN_SUFFIX = @DRIVER_MAN_SUFFIX@ +DSYMUTIL = @DSYMUTIL@ +ECHO = @ECHO@ +ECHO_C = @ECHO_C@ +ECHO_N = @ECHO_N@ +ECHO_T = @ECHO_T@ +EGREP = @EGREP@ +EXEEXT = @EXEEXT@ +F77 = @F77@ +FFLAGS = @FFLAGS@ +FILE_MAN_DIR = @FILE_MAN_DIR@ +FILE_MAN_SUFFIX = @FILE_MAN_SUFFIX@ +GREP = @GREP@ +GROFF = @GROFF@ +I18N_MODULE_LIBS = @I18N_MODULE_LIBS@ +INSTALL = @INSTALL@ +INSTALL_DATA = @INSTALL_DATA@ +INSTALL_PROGRAM = @INSTALL_PROGRAM@ +INSTALL_SCRIPT = @INSTALL_SCRIPT@ +INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@ +KEYSYMDEF = @KEYSYMDEF@ +LAUNCHD = @LAUNCHD@ +LDFLAGS = @LDFLAGS@ +LIBOBJS = @LIBOBJS@ +LIBS = @LIBS@ +LIBTOOL = @LIBTOOL@ +LIB_MAN_DIR = @LIB_MAN_DIR@ +LIB_MAN_SUFFIX = @LIB_MAN_SUFFIX@ +LINT = @LINT@ +LINTLIB = @LINTLIB@ +LINT_FLAGS = @LINT_FLAGS@ +LN_S = @LN_S@ +LTCOMPILE = @LTCOMPILE@ +LTCXXCOMPILE = @LTCXXCOMPILE@ +LTLIBOBJS = @LTLIBOBJS@ +MAINT = @MAINT@ +MAKEINFO = @MAKEINFO@ +MALLOC_ZERO_CFLAGS = @MALLOC_ZERO_CFLAGS@ +MISC_MAN_DIR = @MISC_MAN_DIR@ +MISC_MAN_SUFFIX = @MISC_MAN_SUFFIX@ +MKDIR_P = @MKDIR_P@ +NMEDIT = @NMEDIT@ +OBJEXT = @OBJEXT@ +PACKAGE = @PACKAGE@ +PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@ +PACKAGE_NAME = @PACKAGE_NAME@ +PACKAGE_STRING = @PACKAGE_STRING@ +PACKAGE_TARNAME = @PACKAGE_TARNAME@ +PACKAGE_VERSION = @PACKAGE_VERSION@ +PATH_SEPARATOR = @PATH_SEPARATOR@ +PERL = @PERL@ +PKG_CONFIG = @PKG_CONFIG@ +PS2PDF = @PS2PDF@ +RANLIB = @RANLIB@ +RAWCPP = @RAWCPP@ +RAWCPPFLAGS = @RAWCPPFLAGS@ +SED = @SED@ +SET_MAKE = @SET_MAKE@ +SHELL = @SHELL@ +STRIP = @STRIP@ +VERSION = @VERSION@ +WCHAR32 = @WCHAR32@ +X11_CFLAGS = @X11_CFLAGS@ +X11_DATADIR = @X11_DATADIR@ +X11_EXTRA_DEPS = @X11_EXTRA_DEPS@ +X11_LIBDIR = @X11_LIBDIR@ +X11_LIBS = @X11_LIBS@ +X11_LOCALEDATADIR = @X11_LOCALEDATADIR@ +X11_LOCALEDIR = @X11_LOCALEDIR@ +X11_LOCALELIBDIR = @X11_LOCALELIBDIR@ +XDMCP_CFLAGS = @XDMCP_CFLAGS@ +XDMCP_LIBS = @XDMCP_LIBS@ +XERRORDB = @XERRORDB@ +XKBPROTO_CFLAGS = @XKBPROTO_CFLAGS@ +XKBPROTO_LIBS = @XKBPROTO_LIBS@ +XKBPROTO_REQUIRES = @XKBPROTO_REQUIRES@ +XKEYSYMDB = @XKEYSYMDB@ +XLOCALEDATADIR = @XLOCALEDATADIR@ +XLOCALEDIR = @XLOCALEDIR@ +XLOCALELIBDIR = @XLOCALELIBDIR@ +XMALLOC_ZERO_CFLAGS = @XMALLOC_ZERO_CFLAGS@ +XPROTO_CFLAGS = @XPROTO_CFLAGS@ +XPROTO_LIBS = @XPROTO_LIBS@ +XTHREADLIB = @XTHREADLIB@ +XTHREAD_CFLAGS = @XTHREAD_CFLAGS@ +XTMALLOC_ZERO_CFLAGS = @XTMALLOC_ZERO_CFLAGS@ +abs_builddir = @abs_builddir@ +abs_srcdir = @abs_srcdir@ +abs_top_builddir = @abs_top_builddir@ +abs_top_srcdir = @abs_top_srcdir@ +ac_ct_CC = @ac_ct_CC@ +ac_ct_CXX = @ac_ct_CXX@ +ac_ct_F77 = @ac_ct_F77@ +am__include = @am__include@ +am__leading_dot = @am__leading_dot@ +am__quote = @am__quote@ +am__tar = @am__tar@ +am__untar = @am__untar@ +bindir = @bindir@ +build = @build@ +build_alias = @build_alias@ +build_cpu = @build_cpu@ +build_os = @build_os@ +build_vendor = @build_vendor@ +builddir = @builddir@ +datadir = @datadir@ +datarootdir = @datarootdir@ +distcleancheck_listfiles = @distcleancheck_listfiles@ +docdir = @docdir@ +dvidir = @dvidir@ +exec_prefix = @exec_prefix@ +host = @host@ +host_alias = @host_alias@ +host_cpu = @host_cpu@ +host_os = @host_os@ +host_vendor = @host_vendor@ +htmldir = @htmldir@ +includedir = @includedir@ +infodir = @infodir@ +install_sh = @install_sh@ +libdir = @libdir@ +libexecdir = @libexecdir@ +localedir = @localedir@ +localstatedir = @localstatedir@ +mandir = @mandir@ +mkdir_p = @mkdir_p@ +oldincludedir = @oldincludedir@ +pdfdir = @pdfdir@ +prefix = @prefix@ +program_transform_name = @program_transform_name@ +psdir = @psdir@ +sbindir = @sbindir@ +sharedstatedir = @sharedstatedir@ +srcdir = @srcdir@ +sysconfdir = @sysconfdir@ +target_alias = @target_alias@ +top_build_prefix = @top_build_prefix@ +top_builddir = @top_builddir@ +top_srcdir = @top_srcdir@ +doc_sources = Framework.ms LocaleDB.ms Trans.ms +EXTRA_DIST = $(doc_sources) +@HAVE_PS2PDF_FALSE@printable_format = .ps +@HAVE_PS2PDF_TRUE@printable_format = .pdf +@BUILD_SPECS_TRUE@doc_DATA = $(doc_sources:.ms=.txt) \ +@BUILD_SPECS_TRUE@ $(doc_sources:.ms=$(printable_format)) \ +@BUILD_SPECS_TRUE@ $(doc_sources:.ms=.html) + +@BUILD_SPECS_TRUE@CLEANFILES = $(doc_DATA) +@BUILD_SPECS_TRUE@MOSTLYCLEANFILES = index.* + +# Pass version string as a troff string for substitution +@BUILD_SPECS_TRUE@GROFF_DEFS = -dxV="$(PACKAGE_STRING)" + +# -e to run through eqn, -t to run through tbl +@BUILD_SPECS_TRUE@GROFF_FLAGS = -e -t -ms $(GROFF_DEFS) $(top_srcdir)/specs/macros.t +@BUILD_SPECS_TRUE@SUFFIXES = .ms .ps .txt .html .pdf +all: all-am + +.SUFFIXES: +.SUFFIXES: .ms .ps .txt .html .pdf +$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(top_srcdir)/specs/troffrules.in $(am__configure_deps) + @for dep in $?; do \ + case '$(am__configure_deps)' in \ + *$$dep*) \ + ( cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh ) \ + && { if test -f $@; then exit 0; else break; fi; }; \ + exit 1;; \ + esac; \ + done; \ + echo ' cd $(top_srcdir) && $(AUTOMAKE) --foreign specs/i18n/Makefile'; \ + $(am__cd) $(top_srcdir) && \ + $(AUTOMAKE) --foreign specs/i18n/Makefile +.PRECIOUS: Makefile +Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status + @case '$?' in \ + *config.status*) \ + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \ + *) \ + echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \ + cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \ + esac; + +$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh + +$(top_srcdir)/configure: @MAINTAINER_MODE_TRUE@ $(am__configure_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(ACLOCAL_M4): @MAINTAINER_MODE_TRUE@ $(am__aclocal_m4_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(am__aclocal_m4_deps): + +mostlyclean-libtool: + -rm -f *.lo + +clean-libtool: + -rm -rf .libs _libs +install-docDATA: $(doc_DATA) + @$(NORMAL_INSTALL) + test -z "$(docdir)" || $(MKDIR_P) "$(DESTDIR)$(docdir)" + @list='$(doc_DATA)'; test -n "$(docdir)" || list=; \ + for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + echo "$$d$$p"; \ + done | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(docdir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(docdir)" || exit $$?; \ + done + +uninstall-docDATA: + @$(NORMAL_UNINSTALL) + @list='$(doc_DATA)'; test -n "$(docdir)" || list=; \ + files=`for p in $$list; do echo $$p; done | sed -e 's|^.*/||'`; \ + test -n "$$files" || exit 0; \ + echo " ( cd '$(DESTDIR)$(docdir)' && rm -f" $$files ")"; \ + cd "$(DESTDIR)$(docdir)" && rm -f $$files +tags: TAGS +TAGS: + +ctags: CTAGS +CTAGS: + + +distdir: $(DISTFILES) + @srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + list='$(DISTFILES)'; \ + dist_files=`for file in $$list; do echo $$file; done | \ + sed -e "s|^$$srcdirstrip/||;t" \ + -e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \ + case $$dist_files in \ + */*) $(MKDIR_P) `echo "$$dist_files" | \ + sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \ + sort -u` ;; \ + esac; \ + for file in $$dist_files; do \ + if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \ + if test -d $$d/$$file; then \ + dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \ + if test -d "$(distdir)/$$file"; then \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ + fi; \ + if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \ + cp -fpR $(srcdir)/$$file "$(distdir)$$dir" || exit 1; \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ + fi; \ + cp -fpR $$d/$$file "$(distdir)$$dir" || exit 1; \ + else \ + test -f "$(distdir)/$$file" \ + || cp -p $$d/$$file "$(distdir)/$$file" \ + || exit 1; \ + fi; \ + done +check-am: all-am +check: check-am +all-am: Makefile $(DATA) +installdirs: + for dir in "$(DESTDIR)$(docdir)"; do \ + test -z "$$dir" || $(MKDIR_P) "$$dir"; \ + done +install: install-am +install-exec: install-exec-am +install-data: install-data-am +uninstall: uninstall-am + +install-am: all-am + @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am + +installcheck: installcheck-am +install-strip: + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + `test -z '$(STRIP)' || \ + echo "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'"` install +mostlyclean-generic: + -test -z "$(MOSTLYCLEANFILES)" || rm -f $(MOSTLYCLEANFILES) + +clean-generic: + -test -z "$(CLEANFILES)" || rm -f $(CLEANFILES) + +distclean-generic: + -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES) + -test . = "$(srcdir)" || test -z "$(CONFIG_CLEAN_VPATH_FILES)" || rm -f $(CONFIG_CLEAN_VPATH_FILES) + +maintainer-clean-generic: + @echo "This command is intended for maintainers to use" + @echo "it deletes files that may require special tools to rebuild." +clean: clean-am + +clean-am: clean-generic clean-libtool mostlyclean-am + +distclean: distclean-am + -rm -f Makefile +distclean-am: clean-am distclean-generic + +dvi: dvi-am + +dvi-am: + +html: html-am + +html-am: + +info: info-am + +info-am: + +install-data-am: install-docDATA + +install-dvi: install-dvi-am + +install-dvi-am: + +install-exec-am: + +install-html: install-html-am + +install-html-am: + +install-info: install-info-am + +install-info-am: + +install-man: + +install-pdf: install-pdf-am + +install-pdf-am: + +install-ps: install-ps-am + +install-ps-am: + +installcheck-am: + +maintainer-clean: maintainer-clean-am + -rm -f Makefile +maintainer-clean-am: distclean-am maintainer-clean-generic + +mostlyclean: mostlyclean-am + +mostlyclean-am: mostlyclean-generic mostlyclean-libtool + +pdf: pdf-am + +pdf-am: + +ps: ps-am + +ps-am: + +uninstall-am: uninstall-docDATA + +.MAKE: install-am install-strip + +.PHONY: all all-am check check-am clean clean-generic clean-libtool \ + distclean distclean-generic distclean-libtool distdir dvi \ + dvi-am html html-am info info-am install install-am \ + install-data install-data-am install-docDATA install-dvi \ + install-dvi-am install-exec install-exec-am install-html \ + install-html-am install-info install-info-am install-man \ + install-pdf install-pdf-am install-ps install-ps-am \ + install-strip installcheck installcheck-am installdirs \ + maintainer-clean maintainer-clean-generic mostlyclean \ + mostlyclean-generic mostlyclean-libtool pdf pdf-am ps ps-am \ + uninstall uninstall-am uninstall-docDATA + + +@BUILD_SPECS_TRUE@.ms.ps: +@BUILD_SPECS_TRUE@ -$(AM_V_GEN) $(GROFF) -Tps $(GROFF_FLAGS) $< 2> index.$@.raw > $@ +@BUILD_SPECS_TRUE@ @if grep '^[^1-9.]' index.$@.raw | grep -v warning; then exit 1; \ +@BUILD_SPECS_TRUE@ else test $$? -le 1; fi + +@BUILD_SPECS_TRUE@.ms.txt: +@BUILD_SPECS_TRUE@ $(AM_V_GEN) env GROFF_NO_SGR=TRUE $(GROFF) -Tutf8 $(GROFF_FLAGS) \ +@BUILD_SPECS_TRUE@ $< 2> index.$@.raw > $@ + +@BUILD_SPECS_TRUE@.ms.html: +@BUILD_SPECS_TRUE@ $(AM_V_GEN) $(GROFF) -Thtml $(GROFF_FLAGS) $< 2> index.$@.raw > $@ + +@BUILD_SPECS_TRUE@.ps.pdf: +@BUILD_SPECS_TRUE@ $(AM_V_GEN) $(PS2PDF) $< $@ + +# Tell versions [3.59,3.63) of GNU make to not export all variables. +# Otherwise a system limit (for SysV at least) may be exceeded. +.NOEXPORT: diff --git a/libX11/specs/i18n/Trans.ms b/libX11/specs/i18n/Trans.ms new file mode 100644 index 000000000..19c053949 --- /dev/null +++ b/libX11/specs/i18n/Trans.ms @@ -0,0 +1,1148 @@ +.\" $Xorg: Trans.ms,v 1.3 2000/08/17 19:42:49 cpqbld Exp $ +.\" $XdotOrg: xc/doc/specs/i18n/Trans.ms,v 1.2 2004/04/23 18:42:19 eich Exp $ +.\" To print this out, type tbl macros.t This File | troff -ms +.EH '''' +.OH '''' +.EF '''' +.OF '''' +.ps 11 +.nr PS 11 +.\" .nr PD 1v +.\" .nr DD 1v +\& +.sp 8 +.TL +\s+3\fBThe XIM Transport Specification\s-3\fP +.sp +.sp +\fBRevision 0.1\fP +.sp +\fBX Version 11, Release 7\fP +.sp +\fB\*(xV\fP +.sp 3 +.AU +Takashi Fujiwara +.AI +FUJITSU LIMITED +.sp 3 +.AB +.LP +This specification describes the transport layer interfaces between +Xlib and IM Server, which makes various channels usable such as X +protocol or, TCP/IP, DECnet and etc. +.AE +.ce 0 +.br +.LP +.bp +\& +.ps 9 +.nr PS 9 +.sp 8 +.LP +Copyright \(co 1994 by FUJITSU LIMITED +.LP +Permission to use, copy, modify, and distribute this documentation +for any purpose and without fee is hereby granted, provided +that the above copyright notice and this permission +notice appear in all copies. +Fujitsu makes no representations about the suitability +for any purpose of the information in this document. +This documentation is provided as is without express or implied warranty. +.sp 5 +Copyright \(co 1994 X Consortium +.LP +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the ``Software''), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: +.LP +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. +.LP +THE SOFTWARE IS PROVIDED ``AS IS'', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN +AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN +CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +.LP +Except as contained in this notice, the name of the X Consortium shall not be +used in advertising or otherwise to promote the sale, use or other dealings +in this Software without prior written authorization from the X Consortium. +.sp 3 +\fIX Window System\fP is a trademark of The Open Group. +.ps 11 +.nr PS 11 +.bp 1 +.EH '\fBXIM Transport Specification\fP''\fB\*(xV\fP' +.OH '\fBXIM Transport Specification\fP''\fB\*(xV\fP' +.EF ''\fB % \fP'' +.OF ''\fB % \fP'' +.NH 1 +Introduction +.XS +\*(SN Introduction +.XE +.LP +The Xlib XIM implementation is layered into three functions, a protocol +layer, an interface layer and a transport layer. The purpose of this +layering is to make the protocol independent of transport implementation. +Each function of these layers are: +.RS 3 +.IP "\fIThe protocol layer\fP" +.br +implements overall function of XIM and calls the interface layer +functions when it needs to communicate to IM Server. +.IP "\fIThe interface layer\fP" +.br +separates the implementation of the transport layer from the protocol +layer, in other words, it provides implementation independent hook for +the transport layer functions. +.IP "\fIThe transport layer\fP" +.br +handles actual data communication with IM Server. It is done by a set +of several functions named transporters. +.RE +.LP +This specification describes the interface layer and the transport +layer, which makes various communication channels usable such as +X protocol or, TCP/IP, DECnet, STREAM, etc., and provides +the information needed for adding another new transport layer. +In addition, sample implementations for the transporter using the +X connection is described in section 4. +.NH 1 +Initialization +.XS +\*(SN Initialization +.XE +.NH 2 +Registering structure to initialize +.XS +\*(SN Registering structure to initialize +.XE +.LP +The structure typed as TransportSW contains the list of the transport +layer the specific implementations supports. +.LP +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef struct { +.br + char *transport_name; +.br + Bool (*config); +} TransportSW; +.De +.LP +.IP "\fItransport_name\fP" 15 +name of transport(*1) +.FS +(*1) Refer to "The Input Method Protocol: Appendix B" +.FE +.IP "\fIconfig\fP" 15 +initial configuration function +.LP +A sample entry for the Xlib supporting transporters is shown below: +.LP +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +TransportSW _XimTransportRec[] = { +.sp 3p +/* char \fI*: +\ * transport_name\fP, Bool \fI(*config)()\fP +\ */ + ``X'', _XimXConf, + ``tcp'', _XimTransConf, + ``local'', _XimTransConf, + ``decnet'', _XimTransConf, + ``streams'', _XimTransConf, + (char *)NULL, (Bool (*)())NULL, +}; +.De +.LP +.NH 2 +Initialization function +.XS +\*(SN Initialization function +.XE +.LP +The following function will be called once when Xlib configures the +transporter functions. +.sp 6p +.FD 0 +Bool (*config)(\fIim\fP, \fItransport_data\fP) +.br + XIM \fIim\fP; +.br + char \fI*transport_data\fP; +.br +.FN +.IP \fIim\fP 1i +Specifies XIM structure address. +.IP \fItransport_data\fP 1i +Specifies the data specific to the transporter, in IM Server address. (*1) +.FS +(*1) Refer to "The Input Method Protocol: Appendix B" +.FE +.sp 6p +.LP +This function must setup the transporter function pointers. +.LP +The actual \fIconfig\fP function will be chosen by IM Server at the +pre-connection time, matching by the \fItransport_name\fP specified +in the \fB_XimTransportRec\fP array; The specific members of XimProto +structure listed below must be initialized so that point they +appropriate transporter functions. +.LP +If the specified transporter has been configured successfully, this +function returns True. There is no Alternative Entry for config +function itself. +.LP +The structure XimProto contains the following function pointers: +.DS +.TA .5i 2.5i +.ta .5i 2.5i +Bool (*connect)(); /* Open connection */ +Bool (*shutdown)(); /* Close connection */ +Bool (*write)(); /* Write data */ +Bool (*read)(); /* Read data */ +Bool (*flush)(); /* Flush data buffer */ +Bool (*register_dispatcher)(); /* Register asynchronous data handler */ +Bool (*call_dispatcher)(); /* Call dispatcher */ +.DE +These functions are called when Xlib needs to communicate the +IM Server. These functions must process the appropriate procedure +described below. +.LP +.NH 1 +The interface/transport layer functions +.XS +\*(SN The interface/transport layer functions +.XE +.LP +Following functions are used for the transport interface. +.LP +.ce +Table 3-1; The Transport Layer Functions. +.SM +.TS +tab(:) center box; +cw(4c) | cw(4c) | c +c | c | c +l | l | c. +.B +Alternative Entry:XimProto member:Section +(Interface Layer):(Transport Layer):\^ += +.R +\fB_XimConnect\fP:connect:3.1 +_ +\fB_XimShutdown\fP:shutdown:3.2 +_ +\fB_XimWrite\fP:write:3.3 +_ +\fB_XimRead\fP:read:3.4 +_ +\fB_XimFlush\fP:flush:3.5 +_ +\fB_XimRegisterDispatcher\fP:register_dispatcher:3.6 +_ +\fB_XimCallDispatcher\fP:call_dispatcher:3.7 +.TE +.NL +.LP +The Protocol layer calls the above functions using the Alternative +Entry in the left column. The transport implementation defines +XimProto member function in the right column. The Alternative Entry is +provided so as to make easier to implement the Protocol Layer. +.LP +.NH 2 +Opening connection +.XS +\*(SN Opening connection +.XE +.LP +When \fBXOpenIM\fP is called, the following function is called to connect +with the IM Server. +.sp 6p +.FD 0 +Bool (*connect)(\fIim\fP) +.br + XIM \fIim\fP; +.FN +.IP \fIim\fP 1i +Specifies XIM structure address. +.sp 6p +.LP +This function must establishes the connection to the IM Server. If the +connection is established successfully, this function returns True. +The Alternative Entry for this function is: +.sp 6p +.FD 0 +Bool _XimConnect(\fIim\fP) +.br + XIM \fIim\fP; +.FN +.IP \fIim\fP 1i +Specifies XIM structure address. +.LP +.NH 2 +Closing connection +.XS +\*(SN Closing connection +.XE +.LP +When \fBXCloseIM\fP is called, the following function is called to +disconnect the connection with the IM Server. The Alternative Entry +for this function is: +.sp 6p +.FD 0 +Bool (*shutdown)(\fIim\fP) +.br + XIM \fIim\fP; +.FN +.IP \fIim\fP 1i +Specifies XIM structure address. +.sp 6p +.LP +This function must close connection with the IM Server. If the +connection is closed successfully, this function returns True. The +Alternative Entry for this function is: +.sp 6p +.FD 0 +Bool _XimShutdown(\fIim\fP) +.br + XIM \fIim\fP; +.FN +.IP \fIim\fP +Specifies XIM structure address. +.LP +.NH 2 +Writing data +.XS +\*(SN Writing data +.XE +.LP +The following function is called, when Xlib needs to write data to the +IM Server. +.sp 6p +.FD 0 +Bool (*write)(\fIim\fP, \fIlen\fP, \fIdata\fP) +.br + XIM \fIim\fP; +.br + INT16 \fIlen\fP; +.br + XPointer \fIdata\fP; +.FN +.IP \fIim\fP 1i +Specifies XIM structure address. +.IP \fIlen\fP 1i +Specifies the length of writing data. +.IP \fIdata\fP 1i +Specifies the writing data. +.sp 6p +.LP +This function writes the \fIdata\fP to the IM Server, regardless +of the contents. The number of bytes is passed to \fIlen\fP. The +writing data is passed to \fIdata\fP. If data is sent successfully, +the function returns True. Refer to "The Input Method Protocol" for +the contents of the writing data. The Alternative Entry for this +function is: +.sp 6p +.FD 0 +Bool _XimWrite(\fIim\fP, \fIlen\fP, \fIdata\fP) +.br + XIM \fIim\fP; +.br + INT16 \fIlen\fP; +.br + XPointer \fIdata\fP; +.FN +.IP \fIim\fP 1i +Specifies XIM structure address. +.IP \fIlen\fP 1i +Specifies the length of writing data. +.IP \fIdata\fP 1i +Specifies the writing data. +.LP +.NH 2 +Reading data +.XS +\*(SN Reading data +.XE +.LP +The following function is called when Xlib waits for response from IM +server synchronously. +.sp 6p +.FD 0 +Bool (*read)(\fIim\fP, \fIread_buf\fP, \fIbuf_len\fP, \fIret_len\fP) +.br + XIM \fIim\fP; +.br + XPointer \fIread_buf\fP; +.br + int \fIbuf_len\fP; +.br + int \fI*ret_len\fP; +.FN +.IP \fIim\fP 1i +Specifies XIM structure address. +.IP \fIread_buf\fP 1i +Specifies the buffer to store data. +.IP \fIbuf_len\fP 1i +Specifies the size of the \fIbuffer\fP +.IP \fIret_len\fP +Specifies the length of stored data. +.sp 6p +.LP +This function stores the read data in \fIread_buf\fP, which size is +specified as \fIbuf_len\fP. The size of data is set to \fIret_len\fP. +This function return True, if the data is read normally or reading +data is completed. +.LP +The Alternative Entry for this function is: +.sp 6p +.FD 0 +Bool _XimRead(\fIim\fP, \fIret_len\fP, \fIbuf\fP, \fIbuf_len\fP, \fIpredicate\fP, \fIpredicate_arg\fP) +.br + XIM \fIim\fP; +.br + INT16 \fI*ret_len\fP; +.br + XPointer \fIbuf\fP; +.br + int \fIbuf_len\fP; +.br + Bool \fI(*predicate)()\fP; +.br + XPointer \fIpredicate_arg\fP; +.FN +.IP \fIim\fP 1i +Specifies XIM structure address. +.IP \fIret_len\fP 1i +Specifies the size of the \fIdata\fP buffer. +.IP \fIbuf\fP 1i +Specifies the buffer to store data. +.IP \fIbuf_len\fP 1i +Specifies the length of \fIbuffer\fP. +.IP \fIpredicate\fP 1i +Specifies the predicate for the XIM data. +.IP \fIpredicate_arg\fP 1i +Specifies the predicate specific data. +.sp 6p +.LP +The predicate procedure indicates whether the \fIdata\fP is for the +XIM or not. \fIlen\fP +This function stores the read data in \fIbuf\fP, which size is specified +as \fIbuf_len\fP. The size of data is set to \fIret_len\fP. +If \fIpreedicate()\fP returns True, this function returns True. +If not, it calls the registered callback function. +.LP +The procedure and its arguments are: +.LP +.sp 6p +.FD 0 +Bool (*predicate)(\fIim\fP, \fIlen\fP, \fIdata\fP, \fIpredicate_arg\fP) +.br + XIM \fIim\fP; +.br + INT16 \fIlen\fP; +.br + XPointer \fIdata\fP; +.br + XPointer \fIpredicate_arg\fP; +.FN +.IP \fIim\fP 1i +Specifies XIM structure address. +.IP \fIlen\fP 1i +Specifies the size of the \fIdata\fP buffer. +.IP \fIdata\fP 1i +Specifies the buffer to store data. +.IP \fIpredicate_arg\fP 1i +Specifies the predicate specific data. +.LP +.NH 2 +Flushing buffer +.XS +\*(SN Flushing buffer +.XE +.LP +The following function is called when Xlib needs to flush the data. +.sp 6p +.FD 0 +void (*flush)(\fIim\fP) +.br + XIM \fIim\fP; +.FN +.IP \fIim\fP 1i +Specifies XIM structure address. +.sp 6p +.LP +This function must flush the data stored in internal buffer on the +transport layer. If data transfer is completed, the function returns +True. The Alternative Entry for this function is: +.sp 6p +.FD 0 +void _XimFlush(\fIim\fP) +.br + XIM \fIim\fP; +.FN +.IP \fIim\fP 1i +Specifies XIM structure address. +.LP +.NH 2 +Registering asynchronous data handler +.XS +\*(SN Registering asynchronous data handler +.XE +.LP +Xlib needs to handle asynchronous response from IM Server. This is +because some of the XIM data occur asynchronously to X events. +.LP +Those data will be handled in the \fIFilter\fP, and the \fIFilter\fP +will call asynchronous data handler in the protocol layer. Then it +calls dispatchers in the transport layer. The dispatchers are +implemented by the protocol layer. This function must store the +information and prepare for later call of the dispatchers using +\fB_XimCallDispatcher\fP. +.LP +When multiple dispatchers are registered, they will be called +sequentially in order of registration, on arrival of asynchronous +data. The register_dispatcher is declared as following: +.sp 6p +.FD 0 +Bool (*register_dispatcher)(\fIim\fP, \fIdispatcher\fP, \fIcall_data\fP) +.br + XIM \fIim\fP; +.br + Bool \fI(*dispatcher)()\fP; +.br + XPointer \fIcall_data\fP; +.FN +.IP \fIim\fP 1i +Specifies XIM structure address. +.IP \fIdispatcher\fP 1i +Specifies the dispatcher function to register. +.IP \fIcall_data\fP 1i +Specifies a parameter for the \fIdispatcher\fP. +.LP +The dispatcher is a function of the following type: +.sp 6p +.FD 0 +Bool (*dispatcher)(\fIim\fP, \fIlen\fP, \fIdata\fP, \fIcall_data\fP) +.br + XIM \fIim\fP; +.br + INT16 \fIlen\fP; +.br + XPointer \fIdata\fP; +.br + XPointer \fIcall_data\fP; +.FN +.IP \fIim\fP 1i +Specifies XIM structure address. +.IP \fIlen\fP 1i +Specifies the size of the \fIdata\fP buffer. +.IP \fIdata\fP 1i +Specifies the buffer to store data. +.IP \fIcall_data\fP 1i +Specifies a parameter passed to the register_dispatcher. +.sp 6p +.LP +The dispatcher is provided by the protocol layer. They are called once +for every asynchronous data, in order of registration. If the data is +used, it must return True. otherwise, it must return False. +.LP +If the dispatcher function returns True, the Transport Layer assume +that the data has been processed by the upper layer. The Alternative +Entry for this function is: +.sp 6p +.FD 0 +Bool _XimRegisterDispatcher(\fIim\fP, \fIdispatcher\fP, \fIcall_data\fP) +.br + XIM \fIim\fP; +.br + Bool \fI(*dispatcher)()\fP; +.br + XPointer \fIcall_data\fP; +.FN +.IP \fIim\fP 1i +Specifies XIM structure address. +.IP \fIdispatcher\fP 1i +Specifies the dispatcher function to register. +.IP \fIcall_data\fP 1i +Specifies a parameter for the \fIdispatcher\fP. +.LP +.NH 2 +Calling dispatcher +.XS +\*(SN Calling dispatcher +.XE +.LP +The following function is used to call the registered dispatcher +function, when the asynchronous response from IM Server has arrived. +.sp 6p +.FD 0 +Bool (*call_dispatcher)(\fIim\fP, \fIlen\fP, \fIdata\fP) +.br + XIM \fIim\fP; +.br + INT16 \fIlen\fP; +.br + XPointer \fIdata\fP; +.FN +.IP \fIim\fP 1i +Specifies XIM structure address. +.IP \fIlen\fP 1i +Specifies the size of \fIdata\fP buffer. +.IP \fIdata\fP 1i +Specifies the buffer to store data. +.LP +The call_dispatcher must call the dispatcher function, in order of +their registration. \fIlen\fP and \fIdata\fP are the data passed to +register_dispatcher. +.LP +The return values are checked at each invocation, and if it finds +True, it immediately return with true for its return value. +.LP +It is depend on the upper layer whether the read data is XIM +Protocol packet unit or not. +The Alternative Entry for this function is: +.sp 6p +.FD 0 +Bool _XimCallDispatcher(\fIim\fP, \fIlen\fP, \fIdata\fP) +.br + XIM \fIim\fP; +.br + INT16 \fIlen\fP; +.br + XPointer \fIcall_data\fP; +.FN +.LP +.bp +.NH 1 +Sample implementations for the Transport Layer +.XS +\*(SN Sample implementations for the Transport Layer +.XE +.LP +Sample implementations for the transporter using the X connection is +described here. +.LP +.NH 2 +X Transport +.XS +\*(SN X Transport +.XE +.LP +At the beginning of the X Transport connection for the XIM transport +mechanism, two different windows must be created either in an Xlib XIM +or in an IM Server, with which the Xlib and the IM Server exchange the +XIM transports by using the ClientMessage events and Window Properties. +In the following, the window created by the Xlib is referred as the +"client communication window", and on the other hand, the window created +by the IM Server is referred as the "IMS communication window". +.LP +.NH 3 +Connection +.XS +\*(SN X Connection +.XE +.LP +In order to establish a connection, a communication window is created. +A ClientMessage in the following event's format is sent to the owner +window of XIM_SERVER selection, which the IM Server has created. +.LP +Refer to "The Input Method Protocol" for the XIM_SERVER atom. +.LP +.ce +Table 4-1; The ClientMessage sent to the IMS window. +.TS H +tab(:); +l s|l +l l|l. +_ +.sp 6p +.B +Structure Member:Contents +.sp 6p +_ +.sp 6p +.TH +.R +int:type:ClientMessage +u_long:serial:Set by the X Window System +Bool:send_event:Set by the X Window System +Display:*display:The display to which connects +Window:window:IMS Window ID +Atom:message_type:XInternAtom(display, ``_XIM_XCONNECT'', False) +int:format:32 +long:data.l[0]:client communication window ID +long:data.l[1]:client-major-transport-version (*1) +long:data.l[2]:client-major-transport-version (*1) +.sp 6p +_ +.TE +.LP +In order to establish the connection (to notify the IM Server communication +window), the IM Server sends a ClientMessage in the following event's +format to the client communication window. +.LP +.ce +Table 4-2; The ClientMessage sent by IM Server. +.TS H +tab(:); +l s | l +l l | l. +_ +.sp 6p +.B +Structure Member:Contents +.sp 6p +_ +.sp 6p +.TH +.R +int:type:ClientMessage +u_long:serial:Set by the X Window System +Bool:send_event:Set by the X Window System +Display:*display:The display to which connects +Window:window:client communication window ID +Atom:message_type:XInternAtom(display, ``_XIM_XCONNECT'', False) +int:format:32 +long:data.l[0]:IMS communication window ID +long:data.l[1]:server-major-transport-version (*1) +long:data.l[2]:server-minor-transport-version (*1) +long:data.l[3]:dividing size between ClientMessage and Property (*2) +.sp 6p +_ +.TE +.LP +.IP (*1) +major/minor-transport-version +.RS +The read/write method is decided by the combination of +major/minor-transport-version, as follows: +.LP +.ce +Table 4-3; The read/write method and the major/minor-transport-version +.TS +center, tab(:); +| c s | l | +| c | c | l |. +_ +.sp 6p +.B +Transport-version:read/write +.sp 6p +_ +.sp 6p +major:minor: +.sp 6p +_ +.sp 6p +.R +0:0:only-CM & Property-with-CM +:1:only-CM & multi-CM +:2:only-CM & multi-CM & Property-with-CM +.sp 6p +_ +.sp 6p +1:0:PropertyNotify +.sp 6p +_ +.sp 6p +2:0:only-CM & PropertyNotify +:1:only-CM & multi-CM & PropertyNotify +.sp 6p +_ +.TE +.LP +.RS +.TS +center, tab(;); +l n l. +only-CM;:;data is sent via a ClientMessage +multi-CM;:;data is sent via multiple ClientMessages +Property-with-CM;:;T{ +data is written in Property, and its Atom is send via ClientMessage +T} +PropertyNotify;:;T{ +data is written in Property, and its Atom is send via PropertyNotify +T} +.TE +.RE +.LP +The method to decide major/minor-transport-version is as follows: +.LP +.IP (1) +The client sends 0 as major/minor-transport-version to the IM Server. +The client must support all methods in Table 4-3. +The client may send another number as major/minor-transport-version to +use other method than the above in the future. +.IP (2) +The IM Server sends its major/minor-transport-version number to +the client. The client sends data using the method specified by the +IM Server. +.IP (3) +If major/minor-transport-version number is not available, it is regarded +as 0. +.RE +.LP +.IP (*2) +dividing size between ClientMessage and Property +.RS +If data is sent via both of multi-CM and Property, specify the dividing +size between ClientMessage and Property. The data, which is smaller than +this size, is sent via multi-CM (or only-CM), and the data, which is +lager than this size, is sent via Property. +.RE +.LP +.NH 3 +read/write +.XS +\*(SN read/write +.XE +.LP +The data is transferred via either ClientMessage or Window Property in +the X Window System. +.LP +.NH 4 +Format for the data from the Client to the IM Server +.XS +\*(SN Format for the data from the Client to the IM Server +.XE +.LP +.B +ClientMessage +.LP +.RS +If data is sent via ClientMessage event, the format is as follows: +.LP +.ce +Table 4-4; The ClientMessage event's format (first or middle) +.TS H +tab(;); +l s | l +l l | l. +_ +.sp 6p +.B +Structure Member;Contents +.sp 6p +_ +.sp 6p +.TH +.R +int;type;ClientMessage +u_long;serial;Set by the X Window System +Bool;send_event;Set by the X Window System +Display;*display;The display to which connects +Window;window;IMS communication window ID +Atom;message_type;XInternAtom(display, ``_XIM_MOREDATA'', False) +int;format;8 +char;data.b[20];(read/write DATA : 20 byte) +.sp 6p +_ +.TE +.LP +.ce +Table 4-5; The ClientMessage event's format (only or last) +.TS H +tab(;); +l s | l +l l | l. +_ +.sp 6p +.B +Structure Member;Contents +.sp 6p +_ +.sp 6p +.TH +.R +int;type;ClientMessage +u_long;serial;Set by the X Window System +Bool;send_event;Set by the X Window System +Display;*display;The display to which connects +Window;window;IMS communication window ID +Atom;message_type;XInternAtom(display, ``_XIM_PROTOCOL'', False) +int;format;8 +char;data.b[20];(read/write DATA : MAX 20 byte) (*1) +.sp 6p +_ +.TE +.IP (*1) +If the data is smaller than 20 byte, all data other than available data +must be 0. +.RE +.LP +.B +Property +.LP +.RS +In the case of large data, data will be sent via the Window Property +for the efficiency. There are the following two methods to notify +Property, and transport-version is decided which method is used. +.LP +.IP (1) +The XChangeProperty function is used to store data in the client +communication window, and Atom of the stored data is notified to the +IM Server via ClientMessage event. +.IP (2) +The XChangeProperty function is used to store data in the client +communication window, and Atom of the stored data is notified to the +IM Server via PropertyNotify event. +.LP +The arguments of the XChangeProperty are as follows: +.LP +.ce +Table 4-6; The XChangeProperty event's format +.TS H +tab(:); +l s | l +l l | l. +_ +.sp 6p +.B +Argument:Contents +.sp 6p +_ +.sp 6p +.TH +.R +Display:*display:The display to which connects +Window:window:IMS communication window ID +Atom:property:read/write property Atom (*1) +Atom:type:XA_STRING +int:format:8 +int:mode:PropModeAppend +u_char:*data:read/write DATA +int:nelements:length of DATA +.sp 6p +_ +.TE +.LP +.IP (*1) +The read/write property ATOM allocates the following strings by +\fBXInternAtom\fP. +.RS +``_clientXXX'' +.RE +.LP +The client changes the property with the mode of PropModeAppend and +the IM Server will read it with the delete mode i.e. (delete = True). +.LP +If Atom is notified via ClientMessage event, the format of the ClientMessage +is as follows: +.LP +.ce +Table 4-7; The ClientMessage event's format to send Atom of property +.TS H +tab(:); +l s | l +l l | l. +_ +.sp 6p +.B +Structure Member:Contents +.sp 6p +_ +.sp 6p +.TH +.R +int:type:ClientMessage +u_long:serial:Set by the X Window System +Bool:send_event:Set by the X Window System +Display:*display:The display to which connects +Window:window:IMS communication window ID +Atom:message_type:XInternAtom(display, ``_XIM_PROTOCOL'', False) +int:format:32 +long:data.l[0]:length of read/write property Atom +long:data.l[1]:read/write property Atom +.sp 6p +_ +.TE +.RE +.LP +.NH 4 +Format for the data from the IM Server to the Client +.XS +\*(SN Format for the data from the Client to the Client +.XE +.LP +.B +ClientMessage +.LP +.RS +The format of the ClientMessage is as follows: +.LP +.ce +Table 4-8; The ClientMessage event's format (first or middle) +.TS H +tab(;); +l s | l +l l | l. +_ +.sp 6p +.B +Structure Member;Contents +.sp 6p +_ +.sp 6p +.TH +.R +int;type;ClientMessage +u_long;serial;Set by the X Window System +Bool;send_event ;Set by the X Window System +Display;*display;The display to which connects +Window;window;client communication window ID +Atom;message_type;XInternAtom(display, ``_XIM_MOREDATA'', False) +int;format;8 +char;data.b[20];(read/write DATA : 20 byte) +.sp 6p +_ +.TE +.LP +.ce +Table 4-9; The ClientMessage event's format (only or last) +.TS H +tab(;); +l s | l +l l | l. +_ +.sp 6p +.B +Structure Member;Contents +.sp 6p +_ +.sp 6p +.TH +.R +int;type;ClientMessage +u_long;serial;Set by the X Window System +Bool;send_event ;Set by the X Window System +Display;*display;The display to which connects +Window;window;client communication window ID +Atom;message_type;XInternAtom(display, ``_XIM_PROTOCOL'', False) +int;format;8 +char;data.b[20];(read/write DATA : MAX 20 byte) (*1) +.sp 6p +_ +.TE +.LP +.IP (*1) +If the data size is smaller than 20 bytes, all data other than available +data must be 0. +.RE +.LP +.B +Property +.LP +.RS +In the case of large data, data will be sent via the Window Property +for the efficiency. There are the following two methods to notify +Property, and transport-version is decided which method is used. +.LP +.IP (1) +The XChangeProperty function is used to store data in the IMS +communication window, and Atom of the property is sent via the +ClientMessage event. +.IP (2) +The XChangeProperty function is used to store data in the IMS +communication window, and Atom of the property is sent via +PropertyNotify event. +.LP +The arguments of the XChangeProperty are as follows: +.LP +.ce +Table 4-10; The XChangeProperty event's format +.TS H +tab(:); +l s | l +l l | l. +_ +.sp 6p +.B +Argument:Contents +.sp 6p +_ +.sp 6p +.TH +.R +Display:*display:The display which to connects +Window:window:client communication window ID +Atom:property:read/write property Atom (*1) +Atom:type:XA_STRING +int:format:8 +int:mode:PropModeAppend +u_char:*data:read/write DATA +int:nelements:length of DATA +.sp 6p +_ +.TE +.LP +.IP (*1) +The read/write property ATOM allocates some strings, which are not +allocated by the client, by \fBXInternAtom\fP. +.LP +The IM Server changes the property with the mode of PropModeAppend and +the client reads it with the delete mode, i.e. (delete = True). +.LP +If Atom is notified via ClientMessage event, the format of the ClientMessage +is as follows: +.LP +.ce +Table 4-11; The ClientMessage event's format to send Atom of property +.TS H +tab(:); +l s | l +l l | l. +_ +.sp 6p +.B +Structure Member:Contents +.sp 6p +_ +.sp 6p +.TH +.R +int:type:ClientMessage +u_long:serial:Set by the X Window System +Bool:send_event:Set by the X Window System +Display:*display:The display to which connects +Window:window:client communication window ID +Atom:message_type:XInternAtom(display, ``_XIM_PROTOCOL'', False) +int:format:32 +long:data.l[0]:length of read/write property ATOM +long:data.l[1]:read/write property ATOM +.sp 6p +_ +.TE +.RE +.LP +.NH 3 +Closing Connection +.XS +\*(SN Closing Connection +.XE +.LP +If the client disconnect with the IM Server, shutdown function should +free the communication window properties and etc.. +.LP +.NH 1 +References +.XS +\*(SN References +.XE +.LP +[1] Masahiko Narita and Hideki Hiura, \fI``The Input Method Protocol''\fP +.LP + diff --git a/libX11/specs/libX11/AppA b/libX11/specs/libX11/AppA new file mode 100644 index 000000000..26a1ba32f --- /dev/null +++ b/libX11/specs/libX11/AppA @@ -0,0 +1,604 @@ +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be included +.\" in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR +.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +.\" OTHER DEALINGS IN THE SOFTWARE. +.\" +.\" Except as contained in this notice, the name of the X Consortium shall +.\" not be used in advertising or otherwise to promote the sale, use or +.\" other dealings in this Software without prior written authorization +.\" from the X Consortium. +.\" +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by +.\" Digital Equipment Corporation +.\" +.\" Portions Copyright \(co 1990, 1991 by +.\" Tektronix, Inc. +.\" +.\" Permission to use, copy, modify and distribute this documentation for +.\" any purpose and without fee is hereby granted, provided that the above +.\" copyright notice appears in all copies and that both that copyright notice +.\" and this permission notice appear in all copies, and that the names of +.\" Digital and Tektronix not be used in in advertising or publicity pertaining +.\" to this documentation without specific, written prior permission. +.\" Digital and Tektronix makes no representations about the suitability +.\" of this documentation for any purpose. +.\" It is provided ``as is'' without express or implied warranty. +.\" +\& +.sp 1 +.ce 3 +\s+1\fBAppendix A\fP\s-1 + +\s+1\fBXlib Functions and Protocol Requests\fP\s-1 +.sp 2 +.na +.LP +.XS +Appendix A: Xlib Functions and Protocol Requests +.XE +This appendix provides two tables that relate to Xlib functions +and the X protocol. +The following table lists each Xlib function (in alphabetical order) +and the corresponding protocol request that it generates. +.LP +.TS H +lw(2.5i) lw(2.5i). +_ +.sp 6p +.B +Xlib Function Protocol Request +.sp 6p +_ +.sp 6p +.TH +.R +XActivateScreenSaver ForceScreenSaver +XAddHost ChangeHosts +XAddHosts ChangeHosts +XAddToSaveSet ChangeSaveSet +XAllocColor AllocColor +XAllocColorCells AllocColorCells +XAllocColorPlanes AllocColorPlanes +XAllocNamedColor AllocNamedColor +XAllowEvents AllowEvents +XAutoRepeatOff ChangeKeyboardControl +XAutoRepeatOn ChangeKeyboardControl +XBell Bell +XChangeActivePointerGrab ChangeActivePointerGrab +XChangeGC ChangeGC +XChangeKeyboardControl ChangeKeyboardControl +XChangeKeyboardMapping ChangeKeyboardMapping +XChangePointerControl ChangePointerControl +XChangeProperty ChangeProperty +XChangeSaveSet ChangeSaveSet +XChangeWindowAttributes ChangeWindowAttributes +XCirculateSubwindows CirculateWindow +XCirculateSubwindowsDown CirculateWindow +XCirculateSubwindowsUp CirculateWindow +XClearArea ClearArea +XClearWindow ClearArea +XConfigureWindow ConfigureWindow +XConvertSelection ConvertSelection +XCopyArea CopyArea +XCopyColormapAndFree CopyColormapAndFree +XCopyGC CopyGC +XCopyPlane CopyPlane +XCreateBitmapFromData CreateGC + CreatePixmap + FreeGC + PutImage +XCreateColormap CreateColormap +XCreateFontCursor CreateGlyphCursor +XCreateGC CreateGC +XCreateGlyphCursor CreateGlyphCursor +XCreatePixmap CreatePixmap +XCreatePixmapCursor CreateCursor +XCreatePixmapFromData CreateGC + CreatePixmap + FreeGC + PutImage +XCreateSimpleWindow CreateWindow +XCreateWindow CreateWindow +XDefineCursor ChangeWindowAttributes +XDeleteProperty DeleteProperty +XDestroySubwindows DestroySubwindows +XDestroyWindow DestroyWindow +XDisableAccessControl SetAccessControl +XDrawArc PolyArc +XDrawArcs PolyArc +XDrawImageString ImageText8 +XDrawImageString16 ImageText16 +XDrawLine PolySegment +XDrawLines PolyLine +XDrawPoint PolyPoint +XDrawPoints PolyPoint +XDrawRectangle PolyRectangle +XDrawRectangles PolyRectangle +XDrawSegments PolySegment +XDrawString PolyText8 +XDrawString16 PolyText16 +XDrawText PolyText8 +XDrawText16 PolyText16 +XEnableAccessControl SetAccessControl +XFetchBytes GetProperty +XFetchName GetProperty +XFillArc PolyFillArc +XFillArcs PolyFillArc +XFillPolygon FillPoly +XFillRectangle PolyFillRectangle +XFillRectangles PolyFillRectangle +XForceScreenSaver ForceScreenSaver +XFreeColormap FreeColormap +XFreeColors FreeColors +XFreeCursor FreeCursor +XFreeFont CloseFont +XFreeGC FreeGC +XFreePixmap FreePixmap +XGetAtomName GetAtomName +XGetClassHint GetProperty +XGetFontPath GetFontPath +XGetGeometry GetGeometry +XGetIconName GetProperty +XGetIconSizes GetProperty +XGetImage GetImage +XGetInputFocus GetInputFocus +XGetKeyboardControl GetKeyboardControl +XGetKeyboardMapping GetKeyboardMapping +XGetModifierMapping GetModifierMapping +XGetMotionEvents GetMotionEvents +XGetNormalHints GetProperty +XGetPointerControl GetPointerControl +XGetPointerMapping GetPointerMapping +XGetRGBColormaps GetProperty +XGetScreenSaver GetScreenSaver +XGetSelectionOwner GetSelectionOwner +XGetSizeHints GetProperty +XGetTextProperty GetProperty +XGetTransientForHint GetProperty +XGetWMClientMachine GetProperty +XGetWMColormapWindows GetProperty + InternAtom +XGetWMHints GetProperty +XGetWMIconName GetProperty +XGetWMName GetProperty +XGetWMNormalHints GetProperty +XGetWMProtocols GetProperty + InternAtom +XGetWMSizeHints GetProperty +XGetWindowAttributes GetWindowAttributes + GetGeometry +XGetWindowProperty GetProperty +XGetZoomHints GetProperty +XGrabButton GrabButton +XGrabKey GrabKey +XGrabKeyboard GrabKeyboard +XGrabPointer GrabPointer +XGrabServer GrabServer +XIconifyWindow InternAtom + SendEvent +XInitExtension QueryExtension +XInstallColormap InstallColormap +XInternAtom InternAtom +XKillClient KillClient +XListExtensions ListExtensions +XListFonts ListFonts +XListFontsWithInfo ListFontsWithInfo +XListHosts ListHosts +XListInstalledColormaps ListInstalledColormaps +XListProperties ListProperties +XLoadFont OpenFont +XLoadQueryFont OpenFont + QueryFont +XLookupColor LookupColor +XLowerWindow ConfigureWindow +XMapRaised ConfigureWindow + MapWindow +XMapSubwindows MapSubwindows +XMapWindow MapWindow +XMoveResizeWindow ConfigureWindow +XMoveWindow ConfigureWindow +XNoOp NoOperation +XOpenDisplay CreateGC +XParseColor LookupColor +XPutImage PutImage +XQueryBestCursor QueryBestSize +XQueryBestSize QueryBestSize +XQueryBestStipple QueryBestSize +XQueryBestTile QueryBestSize +XQueryColor QueryColors +XQueryColors QueryColors +XQueryExtension QueryExtension +XQueryFont QueryFont +XQueryKeymap QueryKeymap +XQueryPointer QueryPointer +XQueryTextExtents QueryTextExtents +XQueryTextExtents16 QueryTextExtents +XQueryTree QueryTree +XRaiseWindow ConfigureWindow +XReadBitmapFile CreateGC + CreatePixmap + FreeGC + PutImage +XRecolorCursor RecolorCursor +XReconfigureWMWindow ConfigureWindow + SendEvent +XRemoveFromSaveSet ChangeSaveSet +XRemoveHost ChangeHosts +XRemoveHosts ChangeHosts +XReparentWindow ReparentWindow +XResetScreenSaver ForceScreenSaver +XResizeWindow ConfigureWindow +XRestackWindows ConfigureWindow +XRotateBuffers RotateProperties +XRotateWindowProperties RotateProperties +XSelectInput ChangeWindowAttributes +XSendEvent SendEvent +XSetAccessControl SetAccessControl +XSetArcMode ChangeGC +XSetBackground ChangeGC +XSetClassHint ChangeProperty +XSetClipMask ChangeGC +XSetClipOrigin ChangeGC +XSetClipRectangles SetClipRectangles +XSetCloseDownMode SetCloseDownMode +XSetCommand ChangeProperty +XSetDashes SetDashes +XSetFillRule ChangeGC +XSetFillStyle ChangeGC +XSetFont ChangeGC +XSetFontPath SetFontPath +XSetForeground ChangeGC +XSetFunction ChangeGC +XSetGraphicsExposures ChangeGC +XSetIconName ChangeProperty +XSetIconSizes ChangeProperty +XSetInputFocus SetInputFocus +XSetLineAttributes ChangeGC +XSetModifierMapping SetModifierMapping +XSetNormalHints ChangeProperty +XSetPlaneMask ChangeGC +XSetPointerMapping SetPointerMapping +XSetRGBColormaps ChangeProperty +XSetScreenSaver SetScreenSaver +XSetSelectionOwner SetSelectionOwner +XSetSizeHints ChangeProperty +XSetStandardProperties ChangeProperty +XSetState ChangeGC +XSetStipple ChangeGC +XSetSubwindowMode ChangeGC +XSetTextProperty ChangeProperty +XSetTile ChangeGC +XSetTransientForHint ChangeProperty +XSetTSOrigin ChangeGC +XSetWMClientMachine ChangeProperty +XSetWMColormapWindows ChangeProperty + InternAtom +XSetWMHints ChangeProperty +XSetWMIconName ChangeProperty +XSetWMName ChangeProperty +XSetWMNormalHints ChangeProperty +XSetWMProperties ChangeProperty +XSetWMProtocols ChangeProperty + InternAtom +XSetWMSizeHints ChangeProperty +XSetWindowBackground ChangeWindowAttributes +XSetWindowBackgroundPixmap ChangeWindowAttributes +XSetWindowBorder ChangeWindowAttributes +XSetWindowBorderPixmap ChangeWindowAttributes +XSetWindowBorderWidth ConfigureWindow +XSetWindowColormap ChangeWindowAttributes +XSetZoomHints ChangeProperty +XStoreBuffer ChangeProperty +XStoreBytes ChangeProperty +XStoreColor StoreColors +XStoreColors StoreColors +XStoreName ChangeProperty +XStoreNamedColor StoreNamedColor +XSync GetInputFocus +XSynchronize GetInputFocus +XTranslateCoordinates TranslateCoordinates +XUndefineCursor ChangeWindowAttributes +XUngrabButton UngrabButton +XUngrabKey UngrabKey +XUngrabKeyboard UngrabKeyboard +XUngrabPointer UngrabPointer +XUngrabServer UngrabServer +XUninstallColormap UninstallColormap +XUnloadFont CloseFont +XUnmapSubwindows UnmapSubwindows +XUnmapWindow UnmapWindow +XWarpPointer WarpPointer +XWithdrawWindow SendEvent + UnmapWindow +.TE +.bp +.LP +The following table lists each X protocol request (in alphabetical +order) and the Xlib functions that reference it. +.TS H +lw(2.5i) lw(2.5i). +_ +.sp 6p +.B +Protocol Request Xlib Function +.sp 6p +_ +.sp 6p +.TH +.R +AllocColor XAllocColor +AllocColorCells XAllocColorCells +AllocColorPlanes XAllocColorPlanes +AllocNamedColor XAllocNamedColor +AllowEvents XAllowEvents +Bell XBell +ChangeActivePointerGrab XChangeActivePointerGrab +ChangeGC XChangeGC + XSetArcMode + XSetBackground + XSetClipMask + XSetClipOrigin + XSetFillRule + XSetFillStyle + XSetFont + XSetForeground + XSetFunction + XSetGraphicsExposures + XSetLineAttributes + XSetPlaneMask + XSetState + XSetStipple + XSetSubwindowMode + XSetTile + XSetTSOrigin +ChangeHosts XAddHost + XAddHosts + XRemoveHost + XRemoveHosts +ChangeKeyboardControl XAutoRepeatOff + XAutoRepeatOn + XChangeKeyboardControl +ChangeKeyboardMapping XChangeKeyboardMapping +ChangePointerControl XChangePointerControl +ChangeProperty XChangeProperty + XSetClassHint + XSetCommand + XSetIconName + XSetIconSizes + XSetNormalHints + XSetRGBColormaps + XSetSizeHints + XSetStandardProperties + XSetTextProperty + XSetTransientForHint + XSetWMClientMachine + XSetWMColormapWindows + XSetWMHints + XSetWMIconName + XSetWMName + XSetWMNormalHints + XSetWMProperties + XSetWMProtocols + XSetWMSizeHints + XSetZoomHints + XStoreBuffer + XStoreBytes + XStoreName +ChangeSaveSet XAddToSaveSet + XChangeSaveSet + XRemoveFromSaveSet +ChangeWindowAttributes XChangeWindowAttributes + XDefineCursor + XSelectInput + XSetWindowBackground + XSetWindowBackgroundPixmap + XSetWindowBorder + XSetWindowBorderPixmap + XSetWindowColormap + XUndefineCursor +CirculateWindow XCirculateSubwindowsDown + XCirculateSubwindowsUp + XCirculateSubwindows +ClearArea XClearArea + XClearWindow +CloseFont XFreeFont + XUnloadFont +ConfigureWindow XConfigureWindow + XLowerWindow + XMapRaised + XMoveResizeWindow + XMoveWindow + XRaiseWindow + XReconfigureWMWindow + XResizeWindow + XRestackWindows + XSetWindowBorderWidth +ConvertSelection XConvertSelection +CopyArea XCopyArea +CopyColormapAndFree XCopyColormapAndFree +CopyGC XCopyGC +CopyPlane XCopyPlane +CreateColormap XCreateColormap +CreateCursor XCreatePixmapCursor +CreateGC XCreateGC + XCreateBitmapFromData + XCreatePixmapFromData + XOpenDisplay + XReadBitmapFile +CreateGlyphCursor XCreateFontCursor + XCreateGlyphCursor +CreatePixmap XCreatePixmap + XCreateBitmapFromData + XCreatePixmapFromData + XReadBitmapFile +CreateWindow XCreateSimpleWindow + XCreateWindow +DeleteProperty XDeleteProperty +DestroySubwindows XDestroySubwindows +DestroyWindow XDestroyWindow +FillPoly XFillPolygon +ForceScreenSaver XActivateScreenSaver + XForceScreenSaver + XResetScreenSaver +FreeColormap XFreeColormap +FreeColors XFreeColors +FreeCursor XFreeCursor +FreeGC XFreeGC + XCreateBitmapFromData + XCreatePixmapFromData + XReadBitmapFile +FreePixmap XFreePixmap +GetAtomName XGetAtomName +GetFontPath XGetFontPath +GetGeometry XGetGeometry + XGetWindowAttributes +GetImage XGetImage +GetInputFocus XGetInputFocus + XSync + XSynchronize +GetKeyboardControl XGetKeyboardControl +GetKeyboardMapping XGetKeyboardMapping +GetModifierMapping XGetModifierMapping +GetMotionEvents XGetMotionEvents +GetPointerControl XGetPointerControl +GetPointerMapping XGetPointerMapping +GetProperty XFetchBytes + XFetchName + XGetClassHint + XGetIconName + XGetIconSizes + XGetNormalHints + XGetRGBColormaps + XGetSizeHints + XGetTextProperty + XGetTransientForHint + XGetWMClientMachine + XGetWMColormapWindows + XGetWMHints + XGetWMIconName + XGetWMName + XGetWMNormalHints + XGetWMProtocols + XGetWMSizeHints + XGetWindowProperty + XGetZoomHints +GetSelectionOwner XGetSelectionOwner +GetWindowAttributes XGetWindowAttributes +GrabButton XGrabButton +GrabKey XGrabKey +GrabKeyboard XGrabKeyboard +GrabPointer XGrabPointer +GrabServer XGrabServer +ImageText8 XDrawImageString +ImageText16 XDrawImageString16 +InstallColormap XInstallColormap +InternAtom XGetWMColormapWindows + XGetWMProtocols + XIconifyWindow + XInternAtom + XSetWMColormapWindows + XSetWMProtocols +KillClient XKillClient +ListExtensions XListExtensions +ListFonts XListFonts +ListFontsWithInfo XListFontsWithInfo +ListHosts XListHosts +ListInstalledColormaps XListInstalledColormaps +ListProperties XListProperties +LookupColor XLookupColor + XParseColor +MapSubwindows XMapSubwindows +MapWindow XMapRaised + XMapWindow +NoOperation XNoOp +OpenFont XLoadFont + XLoadQueryFont +PolyArc XDrawArc + XDrawArcs +PolyFillArc XFillArc + XFillArcs +PolyFillRectangle XFillRectangle + XFillRectangles +PolyLine XDrawLines +PolyPoint XDrawPoint + XDrawPoints +PolyRectangle XDrawRectangle + XDrawRectangles +PolySegment XDrawLine + XDrawSegments +PolyText8 XDrawString + XDrawText +PolyText16 XDrawString16 + XDrawText16 +PutImage XPutImage + XCreateBitmapFromData + XCreatePixmapFromData + XReadBitmapFile +QueryBestSize XQueryBestCursor + XQueryBestSize + XQueryBestStipple + XQueryBestTile +QueryColors XQueryColor + XQueryColors +QueryExtension XInitExtension + XQueryExtension +QueryFont XLoadQueryFont + XQueryFont +QueryKeymap XQueryKeymap +QueryPointer XQueryPointer +QueryTextExtents XQueryTextExtents + XQueryTextExtents16 +QueryTree XQueryTree +RecolorCursor XRecolorCursor +ReparentWindow XReparentWindow +RotateProperties XRotateBuffers + XRotateWindowProperties +SendEvent XIconifyWindow + XReconfigureWMWindow + XSendEvent + XWithdrawWindow +SetAccessControl XDisableAccessControl + XEnableAccessControl + XSetAccessControl +SetClipRectangles XSetClipRectangles +SetCloseDownMode XSetCloseDownMode +SetDashes XSetDashes +SetFontPath XSetFontPath +SetInputFocus XSetInputFocus +SetModifierMapping XSetModifierMapping +SetPointerMapping XSetPointerMapping +SetScreenSaver XGetScreenSaver + XSetScreenSaver +SetSelectionOwner XSetSelectionOwner +StoreColors XStoreColor + XStoreColors +StoreNamedColor XStoreNamedColor +TranslateCoordinates XTranslateCoordinates +UngrabButton XUngrabButton +UngrabKey XUngrabKey +UngrabKeyboard XUngrabKeyboard +UngrabPointer XUngrabPointer +UngrabServer XUngrabServer +UninstallColormap XUninstallColormap +UnmapSubwindows XUnmapSubWindows +UnmapWindow XUnmapWindow + XWithdrawWindow +WarpPointer XWarpPointer +.TE +.bp diff --git a/libX11/specs/libX11/AppB b/libX11/specs/libX11/AppB new file mode 100644 index 000000000..2e57ede86 --- /dev/null +++ b/libX11/specs/libX11/AppB @@ -0,0 +1,101 @@ +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be included +.\" in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR +.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +.\" OTHER DEALINGS IN THE SOFTWARE. +.\" +.\" Except as contained in this notice, the name of the X Consortium shall +.\" not be used in advertising or otherwise to promote the sale, use or +.\" other dealings in this Software without prior written authorization +.\" from the X Consortium. +.\" +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by +.\" Digital Equipment Corporation +.\" +.\" Portions Copyright \(co 1990, 1991 by +.\" Tektronix, Inc. +.\" +.\" Permission to use, copy, modify and distribute this documentation for +.\" any purpose and without fee is hereby granted, provided that the above +.\" copyright notice appears in all copies and that both that copyright notice +.\" and this permission notice appear in all copies, and that the names of +.\" Digital and Tektronix not be used in in advertising or publicity pertaining +.\" to this documentation without specific, written prior permission. +.\" Digital and Tektronix makes no representations about the suitability +.\" of this documentation for any purpose. +.\" It is provided ``as is'' without express or implied warranty. +.\" +\& +.sp 1 +.ce 3 +\s+1\fBAppendix B\fP\s-1 + +\s+1\fBX Font Cursors\fP\s-1 +.sp 2 +.na +.LP +.XS +Appendix B: X Font Cursors +.XE +The following are the available cursors that can be used with +.PN XCreateFontCursor . +.LP +.Ds 0 +.TA 3i +.ta 3i +#define XC_X_cursor 0 #define XC_ll_angle 76 +#define XC_arrow 2 #define XC_lr_angle 78 +#define XC_based_arrow_down 4 #define XC_man 80 +#define XC_based_arrow_up 6 #define XC_middlebutton 82 +#define XC_boat 8 #define XC_mouse 84 +#define XC_bogosity 10 #define XC_pencil 86 +#define XC_bottom_left_corner 12 #define XC_pirate 88 +#define XC_bottom_right_corner 14 #define XC_plus 90 +#define XC_bottom_side 16 #define XC_question_arrow 92 +#define XC_bottom_tee 18 #define XC_right_ptr 94 +#define XC_box_spiral 20 #define XC_right_side 96 +#define XC_center_ptr 22 #define XC_right_tee 98 +#define XC_circle 24 #define XC_rightbutton 100 +#define XC_clock 26 #define XC_rtl_logo 102 +#define XC_coffee_mug 28 #define XC_sailboat 104 +#define XC_cross 30 #define XC_sb_down_arrow 106 +#define XC_cross_reverse 32 #define XC_sb_h_double_arrow 108 +#define XC_crosshair 34 #define XC_sb_left_arrow 110 +#define XC_diamond_cross 36 #define XC_sb_right_arrow 112 +#define XC_dot 38 #define XC_sb_up_arrow 114 +#define XC_dot_box_mask 40 #define XC_sb_v_double_arrow 116 +#define XC_double_arrow 42 #define XC_shuttle 118 +#define XC_draft_large 44 #define XC_sizing 120 +#define XC_draft_small 46 #define XC_spider 122 +#define XC_draped_box 48 #define XC_spraycan 124 +#define XC_exchange 50 #define XC_star 126 +#define XC_fleur 52 #define XC_target 128 +#define XC_gobbler 54 #define XC_tcross 130 +#define XC_gumby 56 #define XC_top_left_arrow 132 +#define XC_hand1 58 #define XC_top_left_corner 134 +#define XC_hand2 60 #define XC_top_right_corner 136 +#define XC_heart 62 #define XC_top_side 138 +#define XC_icon 64 #define XC_top_tee 140 +#define XC_iron_cross 66 #define XC_trek 142 +#define XC_left_ptr 68 #define XC_ul_angle 144 +#define XC_left_side 70 #define XC_umbrella 146 +#define XC_left_tee 72 #define XC_ur_angle 148 +#define XC_leftbutton 74 #define XC_watch 150 + #define XC_xterm 152 +.De +.bp diff --git a/libX11/specs/libX11/AppC b/libX11/specs/libX11/AppC new file mode 100644 index 000000000..43261ba83 --- /dev/null +++ b/libX11/specs/libX11/AppC @@ -0,0 +1,2230 @@ +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be included +.\" in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR +.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +.\" OTHER DEALINGS IN THE SOFTWARE. +.\" +.\" Except as contained in this notice, the name of the X Consortium shall +.\" not be used in advertising or otherwise to promote the sale, use or +.\" other dealings in this Software without prior written authorization +.\" from the X Consortium. +.\" +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by +.\" Digital Equipment Corporation +.\" +.\" Portions Copyright \(co 1990, 1991 by +.\" Tektronix, Inc. +.\" +.\" Permission to use, copy, modify and distribute this documentation for +.\" any purpose and without fee is hereby granted, provided that the above +.\" copyright notice appears in all copies and that both that copyright notice +.\" and this permission notice appear in all copies, and that the names of +.\" Digital and Tektronix not be used in in advertising or publicity pertaining +.\" to this documentation without specific, written prior permission. +.\" Digital and Tektronix makes no representations about the suitability +.\" of this documentation for any purpose. +.\" It is provided ``as is'' without express or implied warranty. +.\" +\& +.sp 1 +.ce 3 +\s+1\fBAppendix C\fP\s-1 + +\s+1\fBExtensions\fP\s-1 +.sp 2 +.na +.LP +.XS +Appendix C: Extensions +.XE +Because X can evolve by extensions to the core protocol, +it is important that extensions not be perceived as second-class citizens. +At some point, +your favorite extensions may be adopted as additional parts of the +X Standard. +.LP +Therefore, there should be little to distinguish the use of an extension from +that of the core protocol. +To avoid having to initialize extensions explicitly in application programs, +it is also important that extensions perform lazy evaluations, +automatically initializing themselves when called for the first time. +.LP +This appendix describes techniques for writing extensions to Xlib that will +run at essentially the same performance as the core protocol requests. +.NT +It is expected that a given extension to X consists of multiple +requests. +Defining 10 new features as 10 separate extensions is a bad practice. +Rather, they should be packaged into a single extension +and should use minor opcodes to distinguish the requests. +.NE +.LP +The symbols and macros used for writing stubs to Xlib are listed in +.hN X11/Xlibint.h . +.SH +Basic Protocol Support Routines +.LP +The basic protocol requests for extensions are +.PN XQueryExtension +and +.PN XListExtensions . +.IN "XQueryExtension" "" "@DEF@" +.sM +.FD 0 +Bool XQueryExtension(\^\fIdisplay\fP, \fIname\fP, \fImajor_opcode_return\fP, \ +\fIfirst_event_return\fP, \fIfirst_error_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + char *\fIname;\fP\^ +.br + int *\fImajor_opcode_return\fP\^; +.br + int *\fIfirst_event_return\fP\^; +.br + int *\fIfirst_error_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIname\fP 1i +Specifies the extension name. +.IP \fImajor_opcode_return\fP 1i +Returns the major opcode. +.IP \fIfirst_event_return\fP 1i +Returns the first event code, if any. +.IP \fIfirst_error_return\fP 1i +Returns the first error code, if any. +.LP +.eM +The +.PN XQueryExtension +function determines if the named extension is present. +If the extension is not present, +.PN XQueryExtension +returns +.PN False ; +otherwise, it returns +.PN True . +If the extension is present, +.PN XQueryExtension +returns the major opcode for the extension to major_opcode_return; +otherwise, +it returns zero. +Any minor opcode and the request formats are specific to the +extension. +If the extension involves additional event types, +.PN XQueryExtension +returns the base event type code to first_event_return; +otherwise, +it returns zero. +The format of the events is specific to the extension. +If the extension involves additional error codes, +.PN XQueryExtension +returns the base error code to first_error_return; +otherwise, +it returns zero. +The format of additional data in the errors is specific to the extension. +.LP +If the extension name is not in the Host Portable Character Encoding +the result is implementation-dependent. +Uppercase and lowercase matter; +the strings ``thing'', ``Thing'', and ``thinG'' +are all considered different names. +.IN "XListExtensions" "" "@DEF@" +.sM +.FD 0 +char **XListExtensions(\^\fIdisplay\fP, \fInextensions_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int *\fInextensions_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fInextensions_return\fP 1i +Returns the number of extensions listed. +.LP +.eM +The +.PN XListExtensions +function returns a list of all extensions supported by the server. +If the data returned by the server is in the Latin Portable Character Encoding, +then the returned strings are in the Host Portable Character Encoding. +Otherwise, the result is implementation-dependent. +.IN "XFreeExtensionList" "" "@DEF@" +.sM +.FD 0 +XFreeExtensionList(\^\fIlist\fP\^) +.br + char **\fIlist\fP\^; +.FN +.IP \fIlist\fP 1i +Specifies the list of extension names. +.LP +.eM +The +.PN XFreeExtensionList +function frees the memory allocated by +.PN XListExtensions . +.SH +Hooking into Xlib +.LP +These functions allow you to hook into the library. +They are not normally used by application programmers but are used +by people who need to extend the core X protocol and +the X library interface. +The functions, which generate protocol requests for X, are typically +called stubs. +.LP +In extensions, stubs first should check to see if they have initialized +themselves on a connection. +If they have not, they then should call +.PN XInitExtension +to attempt to initialize themselves on the connection. +.LP +If the extension needs to be informed of GC/font allocation or +deallocation or if the extension defines new event types, +the functions described here allow the extension to be +called when these events occur. +.LP +The +.PN XExtCodes +structure returns the information from +.PN XInitExtension +and is defined in +.hN X11/Xlib.h : +.LP +.IN "XExtCodes" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct _XExtCodes { /* public to extension, cannot be changed */ + int extension; /* extension number */ + int major_opcode; /* major op-code assigned by server */ + int first_event; /* first event number for the extension */ + int first_error; /* first error number for the extension */ +} XExtCodes; +.De +.LP +.eM +.IN "XInitExtension" "" "@DEF@" +.sM +.FD 0 +XExtCodes *XInitExtension(\^\fIdisplay\fP, \fIname\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + char *\fIname\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIname\fP 1i +Specifies the extension name. +.LP +.eM +The +.PN XInitExtension +function determines if the named extension exists. +Then, it allocates storage for maintaining the +information about the extension on the connection, +chains this onto the extension list for the connection, +and returns the information the stub implementor will need to access +the extension. +If the extension does not exist, +.PN XInitExtension +returns NULL. +.LP +If the extension name is not in the Host Portable Character Encoding, +the result is implementation-dependent. +Uppercase and lowercase matter; +the strings ``thing'', ``Thing'', and ``thinG'' +are all considered different names. +.LP +The extension number in the +.PN XExtCodes +structure is +needed in the other calls that follow. +This extension number is unique only to a single connection. +.LP +.IN "XAddExtension" "" "@DEF@" +.sM +.FD 0 +XExtCodes *XAddExtension\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +For local Xlib extensions, the +.PN XAddExtension +function allocates the +.PN XExtCodes +structure, bumps the extension number count, +and chains the extension onto the extension list. +(This permits extensions to Xlib without requiring server extensions.) +.SH +Hooks into the Library +.LP +These functions allow you to define procedures that are to be +called when various circumstances occur. +The procedures include the creation of a new GC for a connection, +the copying of a GC, the freeing of a GC, the creating and freeing of fonts, +the conversion of events defined by extensions to and from wire +format, and the handling of errors. +.LP +All of these functions return the previous procedure defined for this +extension. +.IN "XESetCloseDisplay" "" "@DEF@" +.sM +.FD 0 +int (*XESetCloseDisplay(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIextension\fP\^; +.br + int (\^*\fIproc\fP\^)(\^); +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIextension\fP 1i +Specifies the extension number. +.IP \fIproc\fP 1i +Specifies the procedure to call when the display is closed. +.LP +.eM +The +.PN XESetCloseDisplay +function defines a procedure to be called whenever +.PN XCloseDisplay +is called. +It returns any previously defined procedure, usually NULL. +.LP +When +.PN XCloseDisplay +is called, +your procedure is called +with these arguments: +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +.R +(*\fIproc\fP\^)(\^\fIdisplay\fP, \fIcodes\fP\^) + Display *\fIdisplay\fP\^; + XExtCodes *\fIcodes\fP\^; +.De +.LP +.eM +.IN "XESetCreateGC" "" "@DEF@" +.sM +.FD 0 +int (*XESetCreateGC(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIextension\fP\^; +.br + int (\^*\fIproc\fP\^)(\^); +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIextension\fP 1i +Specifies the extension number. +.IP \fIproc\fP 1i +Specifies the procedure to call when a GC is closed. +.LP +.eM +The +.PN XESetCreateGC +function defines a procedure to be called whenever +a new GC is created. +It returns any previously defined procedure, usually NULL. +.LP +When a GC is created, +your procedure is called with these arguments: +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +.R +(*\fIproc\fP\^)(\^\fIdisplay\fP, \fIgc\fP, \fIcodes\fP\^) + Display *\fIdisplay\fP\^; + GC \fIgc\fP\^; + XExtCodes *\fIcodes\fP\^; +.De +.LP +.eM +.IN "XESetCopyGC" "" "@DEF@" +.sM +.FD 0 +int (*XESetCopyGC(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIextension\fP\^; +.br + int (\^*\fIproc\fP\^)(\^); +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIextension\fP 1i +Specifies the extension number. +.IP \fIproc\fP 1i +Specifies the procedure to call when GC components are copied. +.LP +.eM +The +.PN XESetCopyGC +function defines a procedure to be called whenever +a GC is copied. +It returns any previously defined procedure, usually NULL. +.LP +When a GC is copied, +your procedure is called with these arguments: +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +.R +(*\fIproc\fP\^)(\^\fIdisplay\fP, \fIgc\fP, \fIcodes\fP\^) + Display *\fIdisplay\fP\^; + GC \fIgc\fP\^; + XExtCodes *\fIcodes\fP\^; +.De +.LP +.eM +.IN "XESetFreeGC" "" "@DEF@" +.sM +.FD 0 +int (*XESetFreeGC(\^\fIdisplay\fP, \fIextension\fP, \fIproc)\fP\^)(\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIextension\fP\^; +.br + int (\^*\fIproc\fP\^)(\^); +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIextension\fP 1i +Specifies the extension number. +.IP \fIproc\fP 1i +Specifies the procedure to call when a GC is freed. +.LP +.eM +The +.PN XESetFreeGC +function defines a procedure to be called whenever +a GC is freed. +It returns any previously defined procedure, usually NULL. +.LP +When a GC is freed, +your procedure is called with these arguments: +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +.R +(*\fIproc\fP\^)(\^\fIdisplay\fP, \fIgc\fP, \fIcodes\fP\^) + Display *\fIdisplay\fP\^; + GC \fIgc\fP\^; + XExtCodes *\fIcodes\fP\^; +.De +.LP +.eM +.IN "XESetCreateFont" "" "@DEF@" +.sM +.FD 0 +int (*XESetCreateFont(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP))(\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIextension\fP\^; +.br + int (\^*\fIproc\fP\^)(\^); +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIextension\fP 1i +Specifies the extension number. +.IP \fIproc\fP 1i +Specifies the procedure to call when a font is created. +.LP +.eM +The +.PN XESetCreateFont +function defines a procedure to be called whenever +.PN XLoadQueryFont +and +.PN XQueryFont +are called. +It returns any previously defined procedure, usually NULL. +.LP +When +.PN XLoadQueryFont +or +.PN XQueryFont +is called, +your procedure is called with these arguments: +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +.R +(*\fIproc\fP\^)(\^\fIdisplay\fP, \fIfs\fP, \fIcodes\fP\^) + Display *\fIdisplay\fP\^; + XFontStruct *\fIfs\fP\^; + XExtCodes *\fIcodes\fP\^; +.De +.LP +.eM +.IN "XESetFreeFont" "" "@DEF@" +.sM +.FD 0 +int (*XESetFreeFont(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIextension\fP\^; +.br + int (\^*\fIproc\fP)(\^); +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIextension\fP 1i +Specifies the extension number. +.IP \fIproc\fP 1i +Specifies the procedure to call when a font is freed. +.LP +.eM +The +.PN XESetFreeFont +function defines a procedure to be called whenever +.PN XFreeFont +is called. +It returns any previously defined procedure, usually NULL. +.LP +When +.PN XFreeFont +is called, your procedure is called with these arguments: +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +.R +(*\fIproc\fP\^)(\^\fIdisplay\fP, \fIfs\fP, \fIcodes\fP\^) + Display *\fIdisplay\fP\^; + XFontStruct *\fIfs\fP\^; + XExtCodes *\fIcodes\fP\^; +.De +.LP +.eM +The +.PN XESetWireToEvent +and +.PN XESetEventToWire +functions allow you to define new events to the library. +An +.PN XEvent +structure always has a type code (type +.PN int ) +as the first component. +This uniquely identifies what kind of event it is. +The second component is always the serial number (type +.PN unsigned +.PN long ) +of the last request processed by the server. +The third component is always a Boolean (type +.PN Bool ) +indicating whether the event came from a +.PN SendEvent +protocol request. +The fourth component is always a pointer to the display +the event was read from. +The fifth component is always a resource ID of one kind or another, +usually a window, carefully selected to be useful to toolkit dispatchers. +The fifth component should always exist, even if +the event does not have a natural destination; +if there is no value +from the protocol to put in this component, initialize it to zero. +.NT +There is an implementation limit such that your host event +structure size cannot be bigger than the size of the +.PN XEvent +union of structures. +There also is no way to guarantee that more than 24 elements or 96 characters +in the structure will be fully portable between machines. +.NE +.IN "XESetWireToEvent" "" "@DEF@" +.sM +.FD 0 +int (*XESetWireToEvent(\^\fIdisplay\fP, \fIevent_number\fP, \fIproc\fP\^))(\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIevent_number\fP\^; +.br + Status (\^*\fIproc\fP\^)(\^); +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIevent_number\fP 1i +Specifies the event code. +.IP \fIproc\fP 1i +Specifies the procedure to call when converting an event. +.LP +.eM +The +.PN XESetWireToEvent +function defines a procedure to be called when an event +needs to be converted from wire format +.Pn ( xEvent ) +to host format +.Pn ( XEvent ). +The event number defines which protocol event number to install a +conversion procedure for. +.PN XESetWireToEvent +returns any previously defined procedure. +.NT +You can replace a core event conversion function with one +of your own, although this is not encouraged. +It would, however, allow you to intercept a core event +and modify it before being placed in the queue or otherwise examined. +.NE +When Xlib needs to convert an event from wire format to host +format, your procedure is called with these arguments: +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +.R +Status (*\fIproc\fP\^)(\^\fIdisplay\fP, \fIre\fP, \fIevent\fP\^) + Display *\fIdisplay\fP\^; + XEvent *\fIre\fP\^; + xEvent *\fIevent\fP\^; +.De +.LP +.eM +Your procedure must return status to indicate if the conversion succeeded. +The re argument is a pointer to where the host format event should be stored, +and the event argument is the 32-byte wire event structure. +In the +.PN XEvent +structure you are creating, +you must fill in the five required members of the event structure. +You should fill in the type member with the type specified for the +.PN xEvent +structure. +You should copy all other members from the +.PN xEvent +structure (wire format) to the +.PN XEvent +structure (host format). +Your conversion procedure should return +.PN True +if the event should be placed in the queue or +.PN False +if it should not be placed in the queue. +.LP +To initialize the serial number component of the event, call +.PN _XSetLastRequestRead +with the event and use the return value. +.LP +.IN "_XSetLastRequestRead" "" "@DEF@" +.sM +.FD 0 +unsigned long _XSetLastRequestRead(\^\fIdisplay\fP, \fIrep\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + xGenericReply *\fIrep\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIrep\fP 1i +Specifies the wire event structure. +.LP +.eM +The +.PN _XSetLastRequestRead +function computes and returns a complete serial number from the partial +serial number in the event. +.sp +.LP +.IN "XESetEventToWire" "" "@DEF@" +.sM +.FD 0 +Status (*XESetEventToWire(\^\fIdisplay\fP, \fIevent_number\fP, \fIproc\fP\^))(\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIevent_number\fP\^; +.br + int (\^*\fIproc\fP\^)(\^); +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIevent_number\fP 1i +Specifies the event code. +.IP \fIproc\fP 1i +Specifies the procedure to call when converting an event. +.LP +.eM +The +.PN XESetEventToWire +function defines a procedure to be called when an event +needs to be converted from host format +.Pn ( XEvent ) +to wire format +.Pn ( xEvent ) +form. +The event number defines which protocol event number to install a +conversion procedure for. +.PN XESetEventToWire +returns any previously defined procedure. +It returns zero if the conversion fails or nonzero otherwise. +.NT +You can replace a core event conversion function with one +of your own, although this is not encouraged. +It would, however, allow you to intercept a core event +and modify it before being sent to another client. +.NE +When Xlib needs to convert an event from host format to wire format, +your procedure is called with these arguments: +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +.R +(*\fIproc\fP\^)(\^\fIdisplay\fP, \fIre\fP, \fIevent\fP\^) + Display *\fIdisplay\fP\^; + XEvent *\fIre\fP\^; + xEvent *\fIevent\fP\^; +.De +.LP +.eM +The re argument is a pointer to the host format event, +and the event argument is a pointer to where the 32-byte wire event +structure should be stored. +You should fill in the type with the type from the +.PN XEvent +structure. +All other members then should be copied from the host format to the +.PN xEvent +structure. +.IN "XESetWireToError" "" "@DEF@" +.sM +.FD 0 +Bool (*XESetWireToError(\^\fIdisplay\fP, \fIerror_number\fP, \fIproc\fP\^)(\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIerror_number\fP\^; +.br + Bool (\^*\fIproc\fP\^)(\^); +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIerror_number\fP 1i +Specifies the error code. +.IP \fIproc\fP 1i +Specifies the procedure to call when an error is received. +.LP +.eM +The +.PN XESetWireToError +function defines a procedure to be called when an extension +error needs to be converted from wire format to host format. +The error number defines which protocol error code to install +the conversion procedure for. +.PN XESetWireToError +returns any previously defined procedure. +.LP +Use this function for extension errors that contain additional error values +beyond those in a core X error, when multiple wire errors must be combined +into a single Xlib error, or when it is necessary to intercept an +X error before it is otherwise examined. +.LP +When Xlib needs to convert an error from wire format to host format, +the procedure is called with these arguments: +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +.R +Bool (*\fIproc\fP\^)(\^\fIdisplay\fP, \fIhe\fP, \fIwe\fP\^) + Display *\fIdisplay\fP\^; + XErrorEvent *\fIhe\fP\^; + xError *\fIwe\fP\^; +.De +.LP +.eM +The he argument is a pointer to where the host format error should be stored. +The structure pointed at by he is guaranteed to be as large as an +.PN XEvent +structure and so can be cast to a type larger than an +.PN XErrorEvent +to store additional values. +If the error is to be completely ignored by Xlib +(for example, several protocol error structures will be combined into +one Xlib error), +then the function should return +.PN False ; +otherwise, it should return +.PN True . +.IN "XESetError" "" "@DEF@" +.sM +.FD 0 +int (*XESetError(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIextension\fP\^; +.br + int (\^*\fIproc\fP\^)(\^); +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIextension\fP 1i +Specifies the extension number. +.IP \fIproc\fP 1i +Specifies the procedure to call when an error is received. +.LP +.eM +Inside Xlib, there are times that you may want to suppress the +calling of the external error handling when an error occurs. +This allows status to be returned on a call at the cost of the call +being synchronous (though most such functions are query operations, in any +case, and are typically programmed to be synchronous). +.LP +When Xlib detects a protocol error in +.PN _XReply , +it calls your procedure with these arguments: +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +.R +int (*\fIproc\fP\^)(\fIdisplay\fP, \fIerr\fP, \fIcodes\fP, \fIret_code\fP\^) + Display *\fIdisplay\fP\^; + xError *\fIerr\fP\^; + XExtCodes *\fIcodes\fP\^; + int *\fIret_code\fP\^; +.De +.LP +.eM +The err argument is a pointer to the 32-byte wire format error. +The codes argument is a pointer to the extension codes structure. +The ret_code argument is the return code you may want +.PN _XReply +returned to. +.LP +If your procedure returns a zero value, +the error is not suppressed, and +the client's error handler is called. +(For further information, see section 11.8.2.) +If your procedure returns nonzero, +the error is suppressed, and +.PN _XReply +returns the value of ret_code. +.IN "XESetErrorString" "" "@DEF@" +.sM +.FD 0 +char *(*XESetErrorString(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIextension\fP\^; +.br + char *(\^*\fIproc\fP\^)(\^); +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIextension\fP 1i +Specifies the extension number. +.IP \fIproc\fP 1i +Specifies the procedure to call to obtain an error string. +.LP +.eM +The +.PN XGetErrorText +function returns a string to the user for an error. +.PN XESetErrorString +allows you to define a procedure to be called that +should return a pointer to the error message. +The following is an example. +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +.R +(*\fIproc\fP\^)(\^\fIdisplay\fP, \fIcode\fP, \fIcodes\fP, \fIbuffer\fP, \fInbytes\fP\^) + Display *\fIdisplay\fP\^; + int \fIcode\fP\^; + XExtCodes *\fIcodes\fP\^; + char *\fIbuffer\fP\^; + int \fInbytes\fP\^; +.De +.LP +.eM +Your procedure is called with the error code for every error detected. +You should copy nbytes of a null-terminated string containing the +error message into buffer. +.IN "XESetPrintErrorValues" "" "@DEF@" +.sM +.FD 0 +void (*XESetPrintErrorValues(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIextension\fP\^; +.br + void (\^*\fIproc\fP\^)(\^); +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIextension\fP 1i +Specifies the extension number. +.IP \fIproc\fP 1i +Specifies the procedure to call when an error is printed. +.LP +.eM +The +.PN XESetPrintErrorValues +function defines a procedure to be called when an extension +error is printed, to print the error values. +Use this function for extension errors that contain additional error values +beyond those in a core X error. +It returns any previously defined procedure. +.LP +When Xlib needs to print an error, +the procedure is called with these arguments: +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +.R +void (*\fIproc\fP\^)(\^\fIdisplay\fP, \fIev\fP, \fIfp\fP\^) + Display *\fIdisplay\fP\^; + XErrorEvent *\fIev\fP\^; + void *\fIfp\fP\^; +.De +.LP +.eM +The structure pointed at by ev is guaranteed to be as large as an +.PN XEvent +structure and so can be cast to a type larger than an +.PN XErrorEvent +to obtain additional values set by using +.PN XESetWireToError . +The underlying type of the fp argument is system dependent; +on a POSIX-compliant system, fp should be cast to type FILE*. +.IN "XESetFlushGC" "" "@DEF@" +.sM +.FD 0 +int (*XESetFlushGC(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIextension\fP\^; +.br + int *(\^*\fIproc\fP\^)(\^); +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIextension\fP 1i +Specifies the extension number. +.IP \fIproc\fP 1i +Specifies the procedure to call when a GC is flushed. +.LP +.eM +The procedure set by the +.PN XESetFlushGC +function has the same interface as the procedure set by the +.PN XESetCopyGC +function, but is called when a GC cache needs to be updated in the server. +.IN "XESetBeforeFlush" "" "@DEF@" +.sM +.FD 0 +int (*XESetBeforeFlush(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIextension\fP\^; +.br + int *(\^*\fIproc\fP\^)(\^); +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIextension\fP 1i +Specifies the extension number. +.IP \fIproc\fP 1i +Specifies the procedure to call when a buffer is flushed. +.LP +.eM +The +.PN XESetBeforeFlush +function defines a procedure to be called when data is about to be +sent to the server. When data is about to be sent, your procedure is +called one or more times with these arguments: +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +.R +void (*\fIproc\fP\^)(\^\fIdisplay\fP, \fIcodes\fP, \fIdata\fP, \fIlen\fP\^) + Display *\fIdisplay\fP\^; + XExtCodes *\fIcodes\fP\^; + char *\fIdata\fP\^; + long \fIlen\fP\^; +.De +.LP +.eM +The data argument specifies a portion of the outgoing data buffer, +and its length in bytes is specified by the len argument. +Your procedure must not alter the contents of the data and must not +do additional protocol requests to the same display. +.SH +Hooks onto Xlib Data Structures +.LP +Various Xlib data structures have provisions for extension procedures +to chain extension supplied data onto a list. +These structures are +.PN GC , +.PN Visual , +.PN Screen , +.PN ScreenFormat , +.PN Display , +and +.PN XFontStruct . +Because the list pointer is always the first member in the structure, +a single set of procedures can be used to manipulate the data +on these lists. +.LP +The following structure is used in the functions in this section +and is defined in +.hN X11/Xlib.h : +.LP +.IN "XExtData" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct _XExtData { + int number; /* number returned by XInitExtension */ + struct _XExtData *next; /* next item on list of data for structure */ + int (*free_private)(); /* if defined, called to free private */ + XPointer private_data; /* data private to this extension. */ +} XExtData; +.De +.LP +.eM +When any of the data structures listed above are freed, +the list is walked, and the structure's free procedure (if any) is called. +If free is NULL, +then the library frees both the data pointed to by the private_data member +and the structure itself. +.LP +.sM +.Ds 0 +.TA .5i +.ta .5i +union { Display *display; + GC gc; + Visual *visual; + Screen *screen; + ScreenFormat *pixmap_format; + XFontStruct *font } XEDataObject; +.De +.LP +.eM +.IN "XEHeadOfExtensionList" "" "@DEF@" +.sM +.FD 0 +XExtData **XEHeadOfExtensionList(\^\fIobject\fP\^) + XEDataObject \fIobject\fP\^; +.FN +.IP \fIobject\fP 1i +Specifies the object. +.LP +.eM +The +.PN XEHeadOfExtensionList +function returns a pointer to the list of extension structures attached +to the specified object. +In concert with +.PN XAddToExtensionList , +.PN XEHeadOfExtensionList +allows an extension to attach arbitrary data to any of the structures +of types contained in +.PN XEDataObject . +.LP +.IN "XAddToExtensionList" "" "@DEF@" +.sM +.FD 0 +XAddToExtensionList(\^\fIstructure\fP, \fIext_data\fP\^) +.br + XExtData **\fIstructure\fP\^; +.br + XExtData *\fIext_data\fP\^; +.FN +.IP \fIstructure\fP 1i +Specifies the extension list. +.IP \fIext_data\fP 1i +Specifies the extension data structure to add. +.LP +.eM +The structure argument is a pointer to one of the data structures +enumerated above. +You must initialize ext_data->number with the extension number +before calling this function. +.IN "XFindOnExtensionList" "" "@DEF@" +.sM +.FD 0 +XExtData *XFindOnExtensionList(\^\fIstructure\fP, \fInumber\fP\^) +.br + struct _XExtData **\fIstructure\fP\^; +.br + int \fInumber\fP\^; +.FN +.IP \fIstructure\fP 1i +Specifies the extension list. +.IP \fInumber\fP 1i +Specifies the extension number from +.PN XInitExtension . +.LP +.eM +The +.PN XFindOnExtensionList +function returns the first extension data structure +for the extension numbered number. +It is expected that an extension will add at most one extension +data structure to any single data structure's extension data list. +There is no way to find additional structures. +.LP +The +.PN XAllocID +macro, which allocates and returns a resource ID, is defined in +.hN X11/Xlib.h . +.IN "XAllocID" "" "@DEF@" +.sM +.FD 0 +XAllocID\^(\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +This macro is a call through the +.PN Display +structure to an internal resource ID allocator. +It returns a resource ID that you can use when creating new resources. +.LP +The +.PN XAllocIDs +macro allocates and returns an array of resource ID. +.IN "XAllocIDs" "" "@DEF@" +.sM +.FD 0 +XAllocIDs\^(\fIdisplay\fP, \fIids_return\fP, \fIcount\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XID *\fIids_return\fP\^; +.br + int \fIcount\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIids_return\fP 1i +Returns the resource IDs. +.IP \fIrep\fP 1i +Specifies the number of resource IDs requested. +.LP +.eM +This macro is a call through the +.PN Display +structure to an internal resource ID allocator. +It returns resource IDs to the array supplied by the caller. +To correctly handle automatic reuse of resource IDs, you must call +.PN XAllocIDs +when requesting multiple resource IDs. This call might generate +protocol requests. +.SH +GC Caching +.LP +GCs are cached by the library to allow merging of independent change +requests to the same GC into single protocol requests. +This is typically called a write-back cache. +Any extension procedure whose behavior depends on the contents of a GC +must flush the GC cache to make sure the server has up-to-date contents +in its GC. +.LP +The +.PN FlushGC +macro checks the dirty bits in the library's GC structure and calls +.PN _XFlushGCCache +if any elements have changed. +The +.PN FlushGC +macro is defined as follows: +.IN "FlushGC" "" "@DEF@" +.sM +.FD 0 +FlushGC\^(\^\fIdisplay\fP\^, \fIgc\fP\^) +.br + Display *\^\fIdisplay\fP\^; +.br + GC \fIgc\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgc\fP 1i +Specifies the GC. +.LP +.eM +Note that if you extend the GC to add additional resource ID components, +you should ensure that the library stub sends the change request immediately. +This is because a client can free a resource immediately after +using it, so if you only stored the value in the cache without +forcing a protocol request, the resource might be destroyed before being +set into the GC. +You can use the +.PN _XFlushGCCache +procedure +to force the cache to be flushed. +The +.PN _XFlushGCCache +procedure +is defined as follows: +.IN "_XFlushGCCache" "" "@DEF@" +.sM +.FD 0 +_XFlushGCCache\^(\^\fIdisplay\fP\^, \fIgc\fP\^) +.br + Display *\^\fIdisplay\fP\^; +.br + GC \fIgc\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgc\fP 1i +Specifies the GC. +.LP +.eM +.SH +Graphics Batching +.LP +If you extend X to add more poly graphics primitives, you may be able to +take advantage of facilities in the library to allow back-to-back +single calls to be transformed into poly requests. +This may dramatically improve performance of programs that are not +written using poly requests. +A pointer to an +.PN xReq , +called last_req in the display structure, is the last request being processed. +By checking that the last request +type, drawable, gc, and other options are the same as the new one +and that there is enough space left in the buffer, you may be able +to just extend the previous graphics request by extending the length +field of the request and appending the data to the buffer. +This can improve performance by five times or more in naive programs. +For example, here is the source for the +.PN XDrawPoint +stub. +(Writing extension stubs is discussed in the next section.) +.IP +.sM +.nf + +#include + +/* precompute the maximum size of batching request allowed */ + +static int size = sizeof(xPolyPointReq) + EPERBATCH * sizeof(xPoint); + +XDrawPoint(dpy, d, gc, x, y) + register Display *dpy; + Drawable d; + GC gc; + int x, y; /* INT16 */ +{ + xPoint *point; + LockDisplay(dpy); + FlushGC(dpy, gc); + { + register xPolyPointReq *req = (xPolyPointReq *) dpy->last_req; + /* if same as previous request, with same drawable, batch requests */ + if ( + (req->reqType == X_PolyPoint) + && (req->drawable == d) + && (req->gc == gc->gid) + && (req->coordMode == CoordModeOrigin) + && ((dpy->bufptr + sizeof (xPoint)) <= dpy->bufmax) + && (((char *)dpy->bufptr - (char *)req) < size) ) { + point = (xPoint *) dpy->bufptr; + req->length += sizeof (xPoint) >> 2; + dpy->bufptr += sizeof (xPoint); + } + + else { + GetReqExtra(PolyPoint, 4, req); /* 1 point = 4 bytes */ + req->drawable = d; + req->gc = gc->gid; + req->coordMode = CoordModeOrigin; + point = (xPoint *) (req + 1); + } + point->x = x; + point->y = y; + } + UnlockDisplay(dpy); + SyncHandle(); +} +.fi +.LP +.eM +To keep clients from generating very long requests that may monopolize the +server, +there is a symbol defined in +.hN X11/Xlibint.h +of EPERBATCH on the number of requests batched. +Most of the performance benefit occurs in the first few merged requests. +Note that +.PN FlushGC +is called \fIbefore\fP picking up the value of last_req, +because it may modify this field. +.SH +Writing Extension Stubs +.LP +All X requests always contain the length of the request, +expressed as a 16-bit quantity of 32 bits. +This means that a single request can be no more than 256K bytes in +length. +Some servers may not support single requests of such a length. +The value of dpy->max_request_size contains the maximum length as +defined by the server implementation. +For further information, +see ``X Window System Protocol.'' +.SH +Requests, Replies, and Xproto.h +.LP +The +.hN X11/Xproto.h +file contains three sets of definitions that +are of interest to the stub implementor: +request names, request structures, and reply structures. +.LP +You need to generate a file equivalent to +.hN X11/Xproto.h +for your extension and need to include it in your stub procedure. +Each stub procedure also must include +.hN X11/Xlibint.h . +.LP +The identifiers are deliberately chosen in such a way that, if the +request is called X_DoSomething, then its request structure is +xDoSomethingReq, and its reply is xDoSomethingReply. +The GetReq family of macros, defined in +.hN X11/Xlibint.h , +takes advantage of this naming scheme. +.LP +For each X request, +there is a definition in +.hN X11/Xproto.h +that looks similar to this: +.LP +.Ds +.R +#define X_DoSomething 42 +.De +In your extension header file, +this will be a minor opcode, +instead of a major opcode. +.SH +Request Format +.LP +Every request contains an 8-bit major opcode and a 16-bit length field +expressed in units of 4 bytes. +Every request consists of 4 bytes of header +(containing the major opcode, the length field, and a data byte) followed by +zero or more additional bytes of data. +The length field defines the total length of the request, including the header. +The length field in a request must equal the minimum length required to contain +the request. +If the specified length is smaller or larger than the required length, +the server should generate a +.PN BadLength +error. +Unused bytes in a request are not required to be zero. +Extensions should be designed in such a way that long protocol requests +can be split up into smaller requests, +if it is possible to exceed the maximum request size of the server. +The protocol guarantees the maximum request size to be no smaller than +4096 units (16384 bytes). +.LP +Major opcodes 128 through 255 are reserved for extensions. +Extensions are intended to contain multiple requests, +so extension requests typically have an additional minor opcode encoded +in the second data byte in the request header, +but the placement and interpretation of this minor opcode as well as all +other fields in extension requests are not defined by the core protocol. +Every request is implicitly assigned a sequence number (starting with one) +used in replies, errors, and events. +.LP +To help but not cure portability problems to certain machines, the +.PN B16 +and +.PN B32 +macros have been defined so that they can become bitfield specifications +on some machines. +For example, on a Cray, +these should be used for all 16-bit and 32-bit quantities, as discussed below. +.LP +Most protocol requests have a corresponding structure typedef in +.hN X11/Xproto.h , +which looks like: +.LP +.IN "xDoSomethingReq" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct _DoSomethingReq { + CARD8 reqType; /* X_DoSomething */ + CARD8 someDatum; /* used differently in different requests */ + CARD16 length B16; /* total # of bytes in request, divided by 4 */ + ... + /* request-specific data */ + ... +} xDoSomethingReq; +.De +.LP +.eM +If a core protocol request has a single 32-bit argument, +you need not declare a request structure in your extension header file. +Instead, such requests use the +.PN xResourceReq +structure in +.hN X11/Xproto.h . +This structure is used for any request whose single argument is a +.PN Window , +.PN Pixmap , +.PN Drawable , +.PN GContext , +.PN Font , +.PN Cursor , +.PN Colormap , +.PN Atom , +or +.PN VisualID . +.LP +.IN "xResourceReq" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct _ResourceReq { + CARD8 reqType; /* the request type, e.g. X_DoSomething */ + BYTE pad; /* not used */ + CARD16 length B16; /* 2 (= total # of bytes in request, divided by 4) */ + CARD32 id B32; /* the Window, Drawable, Font, GContext, etc. */ +} xResourceReq; +.De +.LP +.eM +If convenient, +you can do something similar in your extension header file. +.LP +In both of these structures, +the reqType field identifies the type of the request (for example, +X_MapWindow or X_CreatePixmap). +The length field tells how long the request is +in units of 4-byte longwords. +This length includes both the request structure itself and any +variable-length data, such as strings or lists, that follow the +request structure. +Request structures come in different sizes, +but all requests are padded to be multiples of four bytes long. +.LP +A few protocol requests take no arguments at all. +Instead, they use the +.PN xReq +structure in +.hN X11/Xproto.h , +which contains only a reqType and a length (and a pad byte). +.LP +If the protocol request requires a reply, +then +.hN X11/Xproto.h +also contains a reply structure typedef: +.LP +.IN "xDoSomethingReply" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct _DoSomethingReply { + BYTE type; /* always X_Reply */ + BYTE someDatum; /* used differently in different requests */ + CARD16 sequenceNumber B16; /* # of requests sent so far */ + CARD32 length B32; /* # of additional bytes, divided by 4 */ + ... + /* request-specific data */ + ... +} xDoSomethingReply; +.De +.LP +.eM +Most of these reply structures are 32 bytes long. +If there are not that many reply values, +then they contain a sufficient number of pad fields +to bring them up to 32 bytes. +The length field is the total number of bytes in the request minus 32, +divided by 4. +This length will be nonzero only if: +.IP \(bu 5 +The reply structure is followed by variable-length data, +such as a list or string. +.IP \(bu 5 +The reply structure is longer than 32 bytes. +.LP +Only +.PN GetWindowAttributes , +.PN QueryFont , +.PN QueryKeymap , +and +.PN GetKeyboardControl +have reply structures longer than 32 bytes in the core protocol. +.LP +A few protocol requests return replies that contain no data. +.hN X11/Xproto.h +does not define reply structures for these. +Instead, they use the +.PN xGenericReply +structure, which contains only a type, length, +and sequence number (and sufficient padding to make it 32 bytes long). +.SH +Starting to Write a Stub Procedure +.LP +An Xlib stub procedure should start like this: +.LP +.Ds +.R +#include " + +XDoSomething (arguments, ... ) +/* argument declarations */ +{ + +register XDoSomethingReq *req; +\^... +.De +If the protocol request has a reply, +then the variable declarations should include the reply structure for the request. +The following is an example: +.LP +.Ds +.R +xDoSomethingReply rep; +.De +.SH +Locking Data Structures +.LP +To lock the display structure for systems that +want to support multithreaded access to a single display connection, +each stub will need to lock its critical section. +Generally, this section is the point from just before the appropriate GetReq +call until all arguments to the call have been stored into the buffer. +The precise instructions needed for this locking depend upon the machine +architecture. +Two calls, which are generally implemented as macros, have been provided. +.IN "LockDisplay" "" "@DEF@" +.sM +.FD 0 +LockDisplay(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.LP +.IN "UnlockDisplay" "" "@DEF@" +.FD 0 +UnlockDisplay(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +.SH +Sending the Protocol Request and Arguments +.LP +After the variable declarations, +a stub procedure should call one of four macros defined in +.hN X11/Xlibint.h : +.PN GetReq , +.PN GetReqExtra , +.PN GetResReq , +or +.PN GetEmptyReq . +All of these macros take, as their first argument, +the name of the protocol request as declared in +.hN X11/Xproto.h +except with X_ removed. +Each one declares a +.PN Display +structure pointer, +called dpy, and a pointer to a request structure, called req, +which is of the appropriate type. +The macro then appends the request structure to the output buffer, +fills in its type and length field, and sets req to point to it. +.LP +If the protocol request has no arguments (for instance, X_GrabServer), +then use +.PN GetEmptyReq . +.LP +.Ds +.R +GetEmptyReq (DoSomething, req); +.De +If the protocol request has a single 32-bit argument (such as a +.PN Pixmap , +.PN Window , +.PN Drawable , +.PN Atom , +and so on), +then use +.PN GetResReq . +The second argument to the macro is the 32-bit object. +.PN X_MapWindow +is a good example. +.LP +.Ds +.R +GetResReq (DoSomething, rid, req); +.De +The rid argument is the +.PN Pixmap , +.PN Window , +or other resource ID. +.LP +If the protocol request takes any other argument list, +then call +.PN GetReq . +After the +.PN GetReq , +you need to set all the other fields in the request structure, +usually from arguments to the stub procedure. +.LP +.Ds +.R +GetReq (DoSomething, req); +/* fill in arguments here */ +req->arg1 = arg1; +req->arg2 = arg2; +\^... +.De +A few stub procedures (such as +.PN XCreateGC +and +.PN XCreatePixmap ) +return a resource ID to the caller but pass a resource ID as an argument +to the protocol request. +Such procedures use the macro +.PN XAllocID +to allocate a resource ID from the range of IDs +that were assigned to this client when it opened the connection. +.LP +.Ds +.R +rid = req->rid = XAllocID(); +\^... +return (rid); +.De +Finally, some stub procedures transmit a fixed amount of variable-length +data after the request. +Typically, these procedures (such as +.PN XMoveWindow +and +.PN XSetBackground ) +are special cases of more general functions like +.PN XMoveResizeWindow +and +.PN XChangeGC . +These procedures use +.PN GetReqExtra , +which is the same as +.PN GetReq +except that it takes an additional argument (the number of +extra bytes to allocate in the output buffer after the request structure). +This number should always be a multiple of four. +.SH +Variable Length Arguments +.LP +Some protocol requests take additional variable-length data that +follow the +.PN xDoSomethingReq +structure. +The format of this data varies from request to request. +Some requests require a sequence of 8-bit bytes, +others a sequence of 16-bit or 32-bit entities, +and still others a sequence of structures. +.LP +It is necessary to add the length of any variable-length data to the +length field of the request structure. +That length field is in units of 32-bit longwords. +If the data is a string or other sequence of 8-bit bytes, +then you must round the length up and shift it before adding: +.LP +.Ds +.R +req->length += (nbytes+3)>>2; +.De +To transmit variable-length data, use the +.PN Data +macros. +If the data fits into the output buffer, +then this macro copies it to the buffer. +If it does not fit, however, +the +.PN Data +macro calls +.PN _XSend , +which transmits first the contents of the buffer and then your data. +The +.PN Data +macros take three arguments: +the display, a pointer to the beginning of the data, +and the number of bytes to be sent. +.sM +.FD 0 +Data(\^\fIdisplay\fP, (char *) \fIdata\fP, \fInbytes\fP\^); +.sp +Data16(\^\fIdisplay\fP, (short *) \fIdata\fP, \fInbytes\fP\^); +.sp +Data32(\^\fIdisplay\fP, (long *) \fIdata\fP, \fInbytes\fP\^); +.FN +.LP +.eM +.PN Data , +.PN Data16 , +and +.PN Data32 +are macros that may use their last argument +more than once, so that argument should be a variable rather than +an expression such as ``nitems*sizeof(item)''. +You should do that kind of computation in a separate statement before calling +them. +Use the appropriate macro when sending byte, short, or long data. +.LP +If the protocol request requires a reply, +then call the procedure +.PN _XSend +instead of the +.PN Data +macro. +.PN _XSend +takes the same arguments, but because it sends your data immediately instead of +copying it into the output buffer (which would later be flushed +anyway by the following call on +.PN _XReply ), +it is faster. +.SH +Replies +.LP +If the protocol request has a reply, +then call +.PN _XReply +after you have finished dealing with +all the fixed-length and variable-length arguments. +.PN _XReply +flushes the output buffer and waits for an +.PN xReply +packet to arrive. +If any events arrive in the meantime, +.PN _XReply +places them in the queue for later use. +.IN "_XReply" "" "@DEF@" +.sM +.FD 0 +Status _XReply(\^\fIdisplay\fP, \fIrep\fP, \fIextra\fP, \fIdiscard\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + xReply *\fIrep\fP\^; +.br + int \fIextra\fP\^; +.br + Bool \fIdiscard\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIrep\fP 1i +Specifies the reply structure. +.IP \fIextra\fP 1i +Specifies the number of 32-bit words expected after the replay. +.IP \fIdiscard\fP 1i +Specifies if any data beyond that specified in the extra argument +should be discarded. +.LP +.eM +The +.PN _XReply +function waits for a reply packet and copies its contents into the +specified rep. +.PN _XReply +handles error and event packets that occur before the reply is received. +.PN _XReply +takes four arguments: +.IP \(bu 5 +A +.PN Display +* structure +.IP \(bu 5 +A pointer to a reply structure (which must be cast to an +.PN xReply +*) +.IP \(bu 5 +The number of additional 32-bit words (beyond +.Pn sizeof( xReply ) += 32 bytes) +in the reply structure +.IP \(bu 5 +A Boolean that indicates whether +.PN _XReply +is to discard any additional bytes +beyond those it was told to read +.LP +Because most reply structures are 32 bytes long, +the third argument is usually 0. +The only core protocol exceptions are the replies to +.PN GetWindowAttributes , +.PN QueryFont , +.PN QueryKeymap , +and +.PN GetKeyboardControl , +which have longer replies. +.LP +The last argument should be +.PN False +if the reply structure is followed +by additional variable-length data (such as a list or string). +It should be +.PN True +if there is not any variable-length data. +.NT +This last argument is provided for upward-compatibility reasons +to allow a client to communicate properly with a hypothetical later +version of the server that sends more data than the client expected. +For example, some later version of +.PN GetWindowAttributes +might use a +larger, but compatible, +.PN xGetWindowAttributesReply +that contains additional attribute data at the end. +.NE +.PN _XReply +returns +.PN True +if it received a reply successfully or +.PN False +if it received any sort of error. +.LP +For a request with a reply that is not followed by variable-length +data, you write something like: +.LP +.Ds +.R +_XReply(display, (xReply *)&rep, 0, True); +*ret1 = rep.ret1; +*ret2 = rep.ret2; +*ret3 = rep.ret3; +\^... +UnlockDisplay(dpy); +SyncHandle(); +return (rep.ret4); +} +.De +If there is variable-length data after the reply, +change the +.PN True +to +.PN False , +and use the appropriate +.PN _XRead +function to read the variable-length data. +.LP +.sM +.FD 0 +_XRead(\^\fIdisplay\fP, \fIdata_return\fP, \fInbytes\fP\^) + Display *\fIdisplay\fP\^; + char *\fIdata_return\fP\^; + long \fInbytes\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIdata_return\fP 1i +Specifies the buffer. +.IP \fInbytes\fP 1i +Specifies the number of bytes required. +.LP +.eM +The +.PN _XRead +function reads the specified number of bytes into data_return. +.LP +.sM +.FD 0 +_XRead16(\^\fIdisplay\fP, \fIdata_return\fP, \fInbytes\fP\^) + Display *\fIdisplay\fP\^; + short *\fIdata_return\fP\^; + long \fInbytes\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIdata_return\fP 1i +Specifies the buffer. +.IP \fInbytes\fP 1i +Specifies the number of bytes required. +.LP +.eM +The +.PN _XRead16 +function reads the specified number of bytes, +unpacking them as 16-bit quantities, +into the specified array as shorts. +.LP +.sM +.FD 0 +_XRead32(\^\fIdisplay\fP, \fIdata_return\fP, \fInbytes\fP\^) + Display *\fIdisplay\fP\^; + long *\fIdata_return\fP\^; + long \fInbytes\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIdata_return\fP 1i +Specifies the buffer. +.IP \fInbytes\fP 1i +Specifies the number of bytes required. +.LP +.eM +The +.PN _XRead32 +function reads the specified number of bytes, +unpacking them as 32-bit quantities, +into the specified array as longs. +.LP +.sM +.FD 0 +_XRead16Pad(\^\fIdisplay\fP, \fIdata_return\fP, \fInbytes\fP\^) + Display *\fIdisplay\fP\^; + short *\fIdata_return\fP\^; + long \fInbytes\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIdata_return\fP 1i +Specifies the buffer. +.IP \fInbytes\fP 1i +Specifies the number of bytes required. +.LP +.eM +The +.PN _XRead16Pad +function reads the specified number of bytes, +unpacking them as 16-bit quantities, +into the specified array as shorts. +If the number of bytes is not a multiple of four, +.PN _XRead16Pad +reads and discards up to two additional pad bytes. +.LP +.sM +.FD 0 +_XReadPad(\^\fIdisplay\fP, \fIdata_return\fP, \fInbytes\fP\^) + Display *\fIdisplay\fP\^; + char *\fIdata_return\fP\^; + long \fInbytes\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIdata_return\fP 1i +Specifies the buffer. +.IP \fInbytes\fP 1i +Specifies the number of bytes required. +.LP +.eM +The +.PN _XReadPad +function reads the specified number of bytes into data_return. +If the number of bytes is not a multiple of four, +.PN _XReadPad +reads and discards up to three additional pad bytes. +.LP +Each protocol request is a little different. +For further information, +see the Xlib sources for examples. +.SH +Synchronous Calling +.LP +Each procedure should have a call, just before returning to the user, +to a macro called +.PN SyncHandle . +If synchronous mode is enabled (see +.PN XSynchronize ), +the request is sent immediately. +The library, however, waits until any error the procedure could generate +at the server has been handled. +.SH +Allocating and Deallocating Memory +.LP +To support the possible reentry of these procedures, +you must observe several conventions when allocating and deallocating memory, +most often done when returning data to the user from the window +system of a size the caller could not know in advance +(for example, a list of fonts or a list of extensions). +The standard C library functions on many systems +are not protected against signals or other multithreaded uses. +The following analogies to standard I/O library functions +have been defined: +.TS +l l. +T{ +.PN Xmalloc () +T} T{ +Replaces +.PN malloc () +T} +T{ +.PN XFree () +T} T{ +Replaces +.PN free () +T} +T{ +.PN Xcalloc () +T} T{ +Replaces +.PN calloc () +T} +.TE +.LP +These should be used in place of any calls you would make to the normal +C library functions. +.LP +If you need a single scratch buffer inside a critical section +(for example, to pack and unpack data to and from the wire protocol), +the general memory allocators may be too expensive to use +(particularly in output functions, which are performance critical). +The following function returns a scratch buffer for use within a +critical section: +.IN "_XAllocScratch" "" "@DEF@" +.sM +.FD 0 +char *_XAllocScratch(\^\fIdisplay\fP, \fInbytes\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + unsigned long \fInbytes\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fInbytes\fP 1i +Specifies the number of bytes required. +.LP +.eM +This storage must only be used inside of a critical section of your +stub. The returned pointer cannot be assumed valid after any call +that might permit another thread to execute inside Xlib. For example, +the pointer cannot be assumed valid after any use of the +.PN GetReq +or +.PN Data +families of macros, +after any use of +.PN _XReply , +or after any use of the +.PN _XSend +or +.PN _XRead +families of functions. +.LP +.sp +The following function returns a scratch buffer for use across +critical sections: +.IN "_XAllocTemp" "" "@DEF@" +.sM +.FD 0 +char *_XAllocTemp(\^\fIdisplay\fP, \fInbytes\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + unsigned long \fInbytes\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fInbytes\fP 1i +Specifies the number of bytes required. +.LP +.eM +This storage can be used across calls that might permit another thread to +execute inside Xlib. The storage must be explicitly returned to Xlib. +The following function returns the storage: +.IN "_XFreeTemp" "" "@DEF@" +.sM +.FD 0 +void _XFreeTemp(\^\fIdisplay\fP, \fIbuf\fP, \fInbytes\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + char *\fIbuf\fP\^; +.br + unsigned long \fInbytes\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIbuf\fP 1i +Specifies the buffer to return. +.IP \fInbytes\fP 1i +Specifies the size of the buffer. +.LP +.eM +You must pass back the same pointer and size that were returned by +.PN _XAllocTemp . +.SH +Portability Considerations +.LP +Many machine architectures, +including many of the more recent RISC architectures, +do not correctly access data at unaligned locations; +their compilers pad out structures to preserve this characteristic. +Many other machines capable of unaligned references pad inside of structures +as well to preserve alignment, because accessing aligned data is +usually much faster. +Because the library and the server use structures to access data at +arbitrary points in a byte stream, +all data in request and reply packets \fImust\fP be naturally aligned; +that is, 16-bit data starts on 16-bit boundaries in the request +and 32-bit data on 32-bit boundaries. +All requests \fImust\fP be a multiple of 32 bits in length to preserve +the natural alignment in the data stream. +You must pad structures out to 32-bit boundaries. +Pad information does not have to be zeroed unless you want to +preserve such fields for future use in your protocol requests. +Floating point varies radically between machines and should be +avoided completely if at all possible. +.LP +This code may run on machines with 16-bit ints. +So, if any integer argument, variable, or return value either can take +only nonnegative values or is declared as a +.PN CARD16 +in the protocol, be sure to declare it as +.PN unsigned +.PN int +and not as +.PN int . +(This, of course, does not apply to Booleans or enumerations.) +.LP +Similarly, +if any integer argument or return value is declared +.PN CARD32 +in the protocol, +declare it as an +.PN unsigned +.PN long +and not as +.PN int +or +.PN long . +This also goes for any internal variables that may +take on values larger than the maximum 16-bit +.PN unsigned +.PN int . +.LP +The library currently assumes that a +.PN char +is 8 bits, a +.PN short +is 16 bits, an +.PN int +is 16 or 32 bits, and a +.PN long +is 32 bits. +The +.PN PackData +macro is a half-hearted attempt to deal with the possibility of 32 bit shorts. +However, much more work is needed to make this work properly. +.SH +Deriving the Correct Extension Opcode +.LP +The remaining problem a writer of an extension stub procedure faces that +the core protocol does not face is to map from the call to the proper +major and minor opcodes. +While there are a number of strategies, +the simplest and fastest is outlined below. +.IP 1. 5 +Declare an array of pointers, _NFILE long (this is normally found +in +.hN stdio.h +and is the number of file descriptors supported on the system) +of type +.PN XExtCodes . +Make sure these are all initialized to NULL. +.IP 2. 5 +When your stub is entered, your initialization test is just to use +the display pointer passed in to access the file descriptor and an index +into the array. +If the entry is NULL, then this is the first time you +are entering the procedure for this display. +Call your initialization procedure and pass to it the display pointer. +.IP 3. 5 +Once in your initialization procedure, call +.PN XInitExtension ; +if it succeeds, store the pointer returned into this array. +Make sure to establish a close display handler to allow you to zero the entry. +Do whatever other initialization your extension requires. +(For example, install event handlers and so on.) +Your initialization procedure would normally return a pointer to the +.PN XExtCodes +structure for this extension, which is what would normally +be found in your array of pointers. +.IP 4. 5 +After returning from your initialization procedure, +the stub can now continue normally, because it has its major opcode safely +in its hand in the +.PN XExtCodes +structure. +.bp diff --git a/libX11/specs/libX11/AppD b/libX11/specs/libX11/AppD new file mode 100644 index 000000000..f96e06175 --- /dev/null +++ b/libX11/specs/libX11/AppD @@ -0,0 +1,1183 @@ +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be included +.\" in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR +.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +.\" OTHER DEALINGS IN THE SOFTWARE. +.\" +.\" Except as contained in this notice, the name of the X Consortium shall +.\" not be used in advertising or otherwise to promote the sale, use or +.\" other dealings in this Software without prior written authorization +.\" from the X Consortium. +.\" +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by +.\" Digital Equipment Corporation +.\" +.\" Portions Copyright \(co 1990, 1991 by +.\" Tektronix, Inc. +.\" +.\" Permission to use, copy, modify and distribute this documentation for +.\" any purpose and without fee is hereby granted, provided that the above +.\" copyright notice appears in all copies and that both that copyright notice +.\" and this permission notice appear in all copies, and that the names of +.\" Digital and Tektronix not be used in in advertising or publicity pertaining +.\" to this documentation without specific, written prior permission. +.\" Digital and Tektronix makes no representations about the suitability +.\" of this documentation for any purpose. +.\" It is provided ``as is'' without express or implied warranty. +.\" +\& +.sp 1 +.ce 3 +\s+1\fBAppendix D\fP\s-1 + +\s+1\fBCompatibility Functions\fP\s-1 +.sp 2 +.na +.LP +.XS +Appendix D: Compatibility Functions +.XE +.LP +The X Version 11 and X Version 10 functions discussed in this appendix +are obsolete, have been superseded by newer X Version 11 functions, +and are maintained for compatibility reasons only. +.SH +X Version 11 Compatibility Functions +.LP +You can use the X Version 11 compatibility functions to: +.IP \(bu 5 +Set standard properties +.IP \(bu 5 +Set and get window sizing hints +.IP \(bu 5 +Set and get an +.PN XStandardColormap +structure +.IP \(bu 5 +Parse window geometry +.IP \(bu 5 +Get X environment defaults +.SH +Setting Standard Properties +.LP +To specify a minimum set of properties describing the simplest application, +use +.PN XSetStandardProperties . +This function has been superseded by +.PN XSetWMProperties +and sets all or portions of the +WM_NAME, WM_ICON_NAME, WM_HINTS, WM_COMMAND, +and WM_NORMAL_HINTS properties. +.IN "XSetStandardProperties" "" "@DEF@" +.sM +.FD 0 +XSetStandardProperties\^(\^\fIdisplay\fP, \fIw\fP, \fIwindow_name\fP, \fIicon_name\fP, \fIicon_pixmap\fP, \fIargv\fP, \fIargc\fP, \fIhints\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + char *\fIwindow_name\fP\^; +.br + char *\fIicon_name\fP\^; +.br + Pixmap \fIicon_pixmap\fP\^; +.br + char **\fIargv\fP\^; +.br + int \fIargc\fP\^; +.br + XSizeHints *\fIhints\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIwindow_name\fP 1i +Specifies the window name, +which should be a null-terminated string. +.IP \fIicon_name\fP 1i +Specifies the icon name, +which should be a null-terminated string. +.IP \fIicon_pixmap\fP 1i +Specifies the bitmap that is to be used for the icon or +.PN None . +.IP \fIargv\fP 1i +Specifies the application's argument list. +.IP \fIargc\fP 1i +Specifies the number of arguments. +.IP \fIhints\fP 1i +Specifies a pointer to the size hints for the window in its normal state. +.LP +.eM +The +.PN XSetStandardProperties +function provides a means by which simple applications set the +most essential properties with a single call. +.PN XSetStandardProperties +should be used to give a window manager some information about +your program's preferences. +It should not be used by applications that need +to communicate more information than is possible with +.PN XSetStandardProperties . +(Typically, argv is the argv array of your main program.) +If the strings are not in the Host Portable Character Encoding, +the result is implementation-dependent. +.LP +.PN XSetStandardProperties +can generate +.PN BadAlloc +and +.PN BadWindow +errors. +.SH +Setting and Getting Window Sizing Hints +.LP +Xlib provides functions that you can use to set or get window sizing hints. +The functions discussed in this section use the flags and the +.PN XSizeHints +structure, as defined in the +.hN X11/Xutil.h +header file and use the WM_NORMAL_HINTS property. +.LP +.sp +To set the size hints for a given window in its normal state, use +.PN XSetNormalHints . +This function has been superseded by +.PN XSetWMNormalHints . +.IN "XSetNormalHints" "" "@DEF@" +.sM +.FD 0 +XSetNormalHints\^(\^\fIdisplay\fP, \fIw\fP, \fIhints\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + XSizeHints *\fIhints\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIhints\fP 1i +Specifies a pointer to the size hints for the window in its normal state. +.LP +.eM +The +.PN XSetNormalHints +function sets the size hints structure for the specified window. +Applications use +.PN XSetNormalHints +to inform the window manager of the size +or position desirable for that window. +In addition, +an application that wants to move or resize itself should call +.PN XSetNormalHints +and specify its new desired location and size +as well as making direct Xlib calls to move or resize. +This is because window managers may ignore redirected +configure requests, but they pay attention to property changes. +.LP +To set size hints, +an application not only must assign values to the appropriate members +in the hints structure but also must set the flags member of the structure +to indicate which information is present and where it came from. +A call to +.PN XSetNormalHints +is meaningless, unless the flags member is set to indicate which members of +the structure have been assigned values. +.LP +.PN XSetNormalHints +can generate +.PN BadAlloc +and +.PN BadWindow +errors. +.LP +.sp +To return the size hints for a window in its normal state, use +.PN XGetNormalHints . +This function has been superseded by +.PN XGetWMNormalHints . +.IN "XGetNormalHints" "" "@DEF@" +.sM +.FD 0 +Status XGetNormalHints\^(\^\fIdisplay\fP, \fIw\fP, \fIhints_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + XSizeHints *\fIhints_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIhints_return\fP 1i +Returns the size hints for the window in its normal state. +.LP +.eM +The +.PN XGetNormalHints +function returns the size hints for a window in its normal state. +It returns a nonzero status if it succeeds or zero if +the application specified no normal size hints for this window. +.LP +.PN XGetNormalHints +can generate a +.PN BadWindow +error. +.LP +.sp +The next two functions set and read the WM_ZOOM_HINTS property. +.LP +To set the zoom hints for a window, use +.PN XSetZoomHints . +This function is no longer supported by the +\fIInter-Client Communication Conventions Manual\fP. +.IN "XSetZoomHints" "" "@DEF@" +.sM +.FD 0 +XSetZoomHints\^(\^\fIdisplay\fP, \fIw\fP, \fIzhints\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + XSizeHints *\fIzhints\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIzhints\fP 1i +Specifies a pointer to the zoom hints. +.LP +.eM +Many window managers think of windows in one of three states: +iconic, normal, or zoomed. +The +.PN XSetZoomHints +function provides the window manager with information for the window in the +zoomed state. +.LP +.PN XSetZoomHints +can generate +.PN BadAlloc +and +.PN BadWindow +errors. +.LP +.sp +To read the zoom hints for a window, use +.PN XGetZoomHints . +This function is no longer supported by the +\fIInter-Client Communication Conventions Manual\fP. +.IN "XGetZoomHints" "" "@DEF@" +.sM +.FD 0 +Status XGetZoomHints\^(\^\fIdisplay\fP, \fIw\fP, \fIzhints_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + XSizeHints *\fIzhints_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIzhints_return\fP 1i +Returns the zoom hints. +.LP +.eM +The +.PN XGetZoomHints +function returns the size hints for a window in its zoomed state. +It returns a nonzero status if it succeeds or zero if +the application specified no zoom size hints for this window. +.LP +.PN XGetZoomHints +can generate a +.PN BadWindow +error. +.LP +.sp +To set the value of any property of type WM_SIZE_HINTS, use +.PN XSetSizeHints . +This function has been superseded by +.PN XSetWMSizeHints . +.IN "XSetSizeHints" "" "@DEF@" +.sM +.FD 0 +XSetSizeHints\^(\^\fIdisplay\fP, \fIw\fP, \fIhints\fP, \fIproperty\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + XSizeHints *\fIhints\fP\^; +.br + Atom \fIproperty\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIhints\fP 1i +Specifies a pointer to the size hints. +.IP \fIproperty\fP 1i +Specifies the property name. +.LP +.eM +The +.PN XSetSizeHints +function sets the +.PN XSizeHints +structure for the named property and the specified window. +This is used by +.PN XSetNormalHints +and +.PN XSetZoomHints +and can be used to set the value of any property of type WM_SIZE_HINTS. +Thus, it may be useful if other properties of that type get defined. +.LP +.PN XSetSizeHints +can generate +.PN BadAlloc , +.PN BadAtom , +and +.PN BadWindow +errors. +.LP +.sp +To read the value of any property of type WM_SIZE_HINTS, use +.PN XGetSizeHints . +This function has been superseded by +.PN XGetWMSizeHints . +.IN "XGetSizeHints" "" "@DEF@" +.sM +.FD 0 +Status XGetSizeHints\^(\^\fIdisplay\fP, \fIw\fP, \fIhints_return\fP, \fIproperty\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + XSizeHints *\fIhints_return\fP\^; +.br + Atom \fIproperty\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIhints_return\fP 1i +Returns the size hints. +.IP \fIproperty\fP 1i +Specifies the property name. +.LP +.eM +The +.PN XGetSizeHints +function returns the +.PN XSizeHints +structure for the named property and the specified window. +This is used by +.PN XGetNormalHints +and +.PN XGetZoomHints . +It also can be used to retrieve the value of any property of type +WM_SIZE_HINTS. +Thus, it may be useful if other properties of that type get defined. +.PN XGetSizeHints +returns a nonzero status if a size hint was defined +or zero otherwise. +.LP +.PN XGetSizeHints +can generate +.PN BadAtom +and +.PN BadWindow +errors. +.SH +Getting and Setting an XStandardColormap Structure +.LP +To get the +.PN XStandardColormap +structure associated with one of the described atoms, use +.PN XGetStandardColormap . +This function has been superseded by +.PN XGetRGBColormap . +.IN "XGetStandardColormap" "" "@DEF@" +.sM +.FD 0 +Status XGetStandardColormap(\^\fIdisplay\fP, \fIw\fP, \fIcolormap_return\fP, \fIproperty\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + XStandardColormap *\fIcolormap_return\fP\^; +.br + Atom \fIproperty\fP\^; /* RGB_BEST_MAP, etc. */ +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIcolormap_return\fP 1i +Returns the colormap associated with the specified atom. +.IP \fIproperty\fP 1i +Specifies the property name. +.LP +.eM +The +.PN XGetStandardColormap +function returns the colormap definition associated with the atom supplied +as the property argument. +.PN XGetStandardColormap +returns a nonzero status if successful and zero otherwise. +For example, +to fetch the standard +.PN GrayScale +colormap for a display, +you use +.PN XGetStandardColormap +with the following syntax: +.LP +.sM +.Ds 0 +.TA .5i 1.5i +.ta .5i 1.5i +XGetStandardColormap(dpy, DefaultRootWindow(dpy), &cmap, XA_RGB_GRAY_MAP); +.De +.LP +.eM +See section 14.3 for the semantics of standard colormaps. +.LP +.PN XGetStandardColormap +can generate +.PN BadAtom +and +.PN BadWindow +errors. +.LP +.sp +To set a standard colormap, use +.PN XSetStandardColormap . +This function has been superseded by +.PN XSetRGBColormap . +.IN "XSetStandardColormap" "" "@DEF@" +.sM +.FD 0 +XSetStandardColormap(\^\fIdisplay\fP, \fIw\fP, \fIcolormap\fP, \fIproperty\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + XStandardColormap *\fIcolormap\fP\^; +.br + Atom \fIproperty\fP\^; /* RGB_BEST_MAP, etc. */ +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIcolormap\fP 1i +Specifies the colormap. +.IP \fIproperty\fP 1i +Specifies the property name. +.LP +.eM +The +.PN XSetStandardColormap +function usually is only used by window or session managers. +.LP +.PN XSetStandardColormap +can generate +.PN BadAlloc , +.PN BadAtom , +.PN BadDrawable , +and +.PN BadWindow +errors. +.SH +Parsing Window Geometry +.LP +To parse window geometry given a user-specified position +and a default position, use +.PN XGeometry . +This function has been superseded by +.PN XWMGeometry . +.IN "Window" "determining location" +.IN "XGeometry" "" "@DEF@" +.sM +.FD 0 +int XGeometry\^(\^\fIdisplay\fP, \fIscreen\fP, \fIposition\fP\^, \fIdefault_position\fP\^, \fIbwidth\fP\^, \fIfwidth\fP\^, \fIfheight\fP\^, \fIxadder\fP\^, +.br + \fIyadder\fP\^, \fIx_return\fP\^, \fIy_return\fP\^, \fIwidth_return\fP\^, \fIheight_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIscreen\fP\^; +.br + char *\fIposition\fP\^, *\fIdefault_position\fP\^; +.br + unsigned int \fIbwidth\fP\^; +.br + unsigned int \fIfwidth\fP\^, \fIfheight\fP\^; +.br + int \fIxadder\fP\^, \fIyadder\fP\^; +.br + int *\fIx_return\fP\^, *\fIy_return\fP\^; +.br + int *\fIwidth_return\fP\^, *\fIheight_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIscreen\fP 1i +Specifies the screen. +.IP \fIposition\fP 1i +.br +.ns +.IP \fIdefault_position\fP 1i +Specify the geometry specifications. +.IP \fIbwidth\fP 1i +Specifies the border width. +.IP \fIfheight\fP 1i +.br +.ns +.IP \fIfwidth\fP 1i +Specify the font height and width in pixels (increment size). +.IP \fIxadder\fP 1i +.br +.ns +.IP \fIyadder\fP 1i +Specify additional interior padding needed in the window. +.IP \fIx_return\fP 1i +.br +.ns +.IP \fIy_return\fP 1i +Return the x and y offsets. +.IP \fIwidth_return\fP 1i +.br +.ns +.IP \fIheight_return\fP 1i +Return the width and height determined. +.LP +.eM +You pass in the border width (bwidth), +size of the increments fwidth and fheight +(typically font width and height), +and any additional interior space (xadder and yadder) +to make it easy to compute the resulting size. +The +.PN XGeometry +function returns the position the window should be placed given a position and +a default position. +.PN XGeometry +determines the placement of +a window using a geometry specification as specified by +.PN XParseGeometry +and the additional information about the window. +Given a fully qualified default geometry specification and +an incomplete geometry specification, +.PN XParseGeometry +returns a bitmask value as defined above in the +.PN XParseGeometry +call, +by using the position argument. +.LP +The returned width and height will be the width and height specified +by default_position as overridden by any user-specified position. +They are not affected by fwidth, fheight, xadder, or yadder. +The x and y coordinates are computed by using the border width, +the screen width and height, padding as specified by xadder and yadder, +and the fheight and fwidth times the width and height from the +geometry specifications. +.SH +Getting the X Environment Defaults +.LP +The +.PN XGetDefault +function provides a primitive interface to the resource manager facilities +discussed in chapter 15. +It is only useful in very simple applications. +.LP +.sp +.IN "XGetDefault" "" "@DEF@" +.sM +.FD 0 +char *XGetDefault\^(\^\fIdisplay\fP, \fIprogram\fP\^, \fIoption\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + char *\fIprogram\fP\^; +.br + char *\fIoption\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIprogram\fP 1i +Specifies the program name for the Xlib defaults (usually argv[0] +of the main program). +.IP \fIoption\fP 1i +Specifies the option name. +.LP +.eM +The +.PN XGetDefault +function returns the value of the resource \fIprog\fP.\fIoption\fP, +where \fIprog\fP is the program argument with the directory prefix removed +and \fIoption\fP must be a single component. +Note that multilevel resources cannot be used with +.PN XGetDefault . +The class "Program.Name" is always used for the resource lookup. +If the specified option name does not exist for this program, +.PN XGetDefault +returns NULL. +The strings returned by +.PN XGetDefault +are owned by Xlib and should not be modified or freed by the client. +.LP +If a database has been set with +.PN XrmSetDatabase , +that database is used for the lookup. +Otherwise, a database is created +and is set in the display (as if by calling +.PN XrmSetDatabase ). +The database is created in the current locale. +To create a database, +.PN XGetDefault +uses resources from the RESOURCE_MANAGER property on the root +window of screen zero. +If no such property exists, +a resource file in the user's home directory is used. +On a POSIX-conformant system, +this file is +.PN "$HOME/.Xdefaults" . +.IN "Files" "$HOME/.Xdefaults" +After loading these defaults, +.PN XGetDefault +merges additional defaults specified by the XENVIRONMENT +environment variable. +If XENVIRONMENT is defined, +it contains a full path name for the additional resource file. +If XENVIRONMENT is not defined, +.PN XGetDefault +looks for +.PN "$HOME/.Xdefaults-\fIname\fP" , +where \fIname\fP specifies the name of the machine on which the application +is running. +.SH +X Version 10 Compatibility Functions +.LP +You can use the X Version 10 compatibility functions to: +.IP \(bu 5 +Draw and fill polygons and curves +.IP \(bu 5 +Associate user data with a value +.SH +Drawing and Filling Polygons and Curves +.LP +Xlib provides functions that you can use to draw or fill +arbitrary polygons or curves. +These functions are provided mainly for compatibility with X Version 10 +and have no server support. +That is, they call other Xlib functions, not the server directly. +Thus, if you just have straight lines to draw, using +.PN XDrawLines +.IN "XDrawLines" +or +.PN XDrawSegments +.IN "XDrawSegments" +is much faster. +.LP +The functions discussed here provide all the functionality of the +X Version 10 functions +.PN XDraw , +.IN "X10 compatibility" "XDraw" +.PN XDrawFilled , +.IN "X10 compatibility" "XDrawFilled" +.PN XDrawPatterned , +.IN "X10 compatibility" "XDrawPatterned" +.PN XDrawDashed , +.IN "X10 compatibility" "XDrawDashed" +and +.PN XDrawTiled . +.IN "X10 compatibility" "XDrawTiled" +They are as compatible as possible given X Version 11's new line-drawing +functions. +One thing to note, however, is that +.PN VertexDrawLastPoint +is no longer supported. +Also, the error status returned is the opposite of what it was under +X Version 10 (this is the X Version 11 standard error status). +.PN XAppendVertex +and +.PN XClearVertexFlag +from X Version 10 also are not supported. +.LP +Just how the graphics context you use is set up actually +determines whether you get dashes or not, and so on. +Lines are properly joined if they connect and include +the closing of a closed figure (see +.PN XDrawLines ). +The functions discussed here fail (return zero) only if they run out of memory +or are passed a +.PN Vertex +list that has a +.PN Vertex +with +.PN VertexStartClosed +set that is not followed by a +.PN Vertex +with +.PN VertexEndClosed +set. +.LP +.sp +To achieve the effects of the X Version 10 +.PN XDraw , +.IN "X10 compatibility" "XDraw" +.PN XDrawDashed , +.IN "X10 compatibility" "XDrawDashed" +and +.PN XDrawPatterned , +.IN "X10 compatibility" "XDrawPatterned" +use +.PN XDraw . +.IN "XDraw" "" "@DEF@" +.sM +.FD 0 +#include + +Status XDraw(\^\fIdisplay\fP, \fId\fP, \fIgc\fP, \fIvlist\fP, \fIvcount\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fId\fP\^; +.br + GC \fIgc\fP\^; +.br + Vertex *\fIvlist\fP\^; +.br + int \fIvcount\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fId\fP 1i +Specifies the drawable. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fIvlist\fP 1i +Specifies a pointer to the list of vertices that indicate what to draw. +.IP \fIvcount\fP 1i +Specifies how many vertices are in vlist. +.LP +.eM +The +.PN XDraw +function draws an arbitrary polygon or curve. +The figure drawn is defined by the specified list of vertices (vlist). +The points are connected by lines as specified in the flags in the +vertex structure. +.LP +Each Vertex, as defined in +.hN X11/X10.h , +is a structure with the following members: +.LP +.IN "Vertex" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 1.5i +.ta .5i 1.5i +typedef struct _Vertex { + short x,y; + unsigned short flags; +} Vertex; +.De +.LP +.eM +The x and y members are the coordinates of the vertex +that are relative to either the upper left inside corner of the drawable +(if +.PN VertexRelative +is zero) or the previous vertex (if +.PN VertexRelative +is one). +.LP +The flags, as defined in +.hN X11/X10.h , +are as follows: +.IN "VertexRelative" "" "@DEF@" +.IN "VertexDontDraw" "" "@DEF@" +.IN "VertexCurved" "" "@DEF@" +.IN "VertexStartClosed" "" "@DEF@" +.IN "VertexEndClosed" "" "@DEF@" +.sM +.TS +l l l. +T{ +.PN VertexRelative +T} T{ +0x0001 +T} T{ +/* else absolute */ +T} +T{ +.PN VertexDontDraw +T} T{ +0x0002 +T} T{ +/* else draw */ +T} +T{ +.PN VertexCurved +T} T{ +0x0004 +T} T{ +/* else straight */ +T} +T{ +.PN VertexStartClosed +T} T{ +0x0008 +T} T{ +/* else not */ +T} +T{ +.PN VertexEndClosed +T} T{ +0x0010 +T} T{ +/* else not */ +T} +.TE +.LP +.eM +.IP \(bu 5 +If +.PN VertexRelative +is not set, +the coordinates are absolute (that is, relative to the drawable's origin). +The first vertex must be an absolute vertex. +.IP \(bu 5 +If +.PN VertexDontDraw +is one, +no line or curve is drawn from the previous vertex to this one. +This is analogous to picking up the pen and moving to another place +before drawing another line. +.IP \(bu 5 +If +.PN VertexCurved +is one, +a spline algorithm is used to draw a smooth curve from the previous vertex +through this one to the next vertex. +Otherwise, a straight line is drawn from the previous vertex to this one. +It makes sense to set +.PN VertexCurved +to one only if a previous and next vertex are both defined +(either explicitly in the array or through the definition of a closed +curve). +.IP \(bu 5 +It is permissible for +.PN VertexDontDraw +bits and +.PN VertexCurved +bits both to be one. +This is useful if you want to define the previous point for the smooth curve +but do not want an actual curve drawing to start until this point. +.IP \(bu 5 +If +.PN VertexStartClosed +is one, +then this point marks the beginning of a closed curve. +This vertex must be followed later in the array by another vertex +whose effective coordinates are identical +and that has a +.PN VertexEndClosed +bit of one. +The points in between form a cycle to determine predecessor +and successor vertices for the spline algorithm. +.LP +This function uses these GC components: +function, plane-mask, line-width, line-style, cap-style, join-style, +fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and +clip-mask. +It also uses these GC mode-dependent components: +foreground, background, tile, stipple, +tile-stipple-x-origin, tile-stipple-y-origin, dash-offset, and dash-list. +.LP +.sp +To achieve the effects of the X Version 10 +.PN XDrawTiled +.IN "X10 compatibility" "XDrawTiled" +and +.PN XDrawFilled , +.IN "X10 compatibility" "XDrawFilled" +use +.PN XDrawFilled . +.IN "XDrawFilled" "" "@DEF@" +.sM +.FD 0 +#include + +Status XDrawFilled(\^\fIdisplay\fP, \fId\fP, \fIgc\fP, \fIvlist\fP, \fIvcount\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fId\fP\^; +.br + GC \fIgc\fP\^; +.br + Vertex *\fIvlist\fP\^; +.br + int \fIvcount\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fId\fP 1i +Specifies the drawable. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fIvlist\fP 1i +Specifies a pointer to the list of vertices that indicate what to draw. +.IP \fIvcount\fP 1i +Specifies how many vertices are in vlist. +.LP +.eM +The +.PN XDrawFilled +function draws arbitrary polygons or curves and then fills them. +.LP +This function uses these GC components: +function, plane-mask, line-width, line-style, cap-style, join-style, +fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and +clip-mask. +It also uses these GC mode-dependent components: +foreground, background, tile, stipple, +tile-stipple-x-origin, tile-stipple-y-origin, +dash-offset, dash-list, fill-style, and fill-rule. +.SH +Associating User Data with a Value +.LP +These functions have been superseded by the context management functions +(see section 16.10). +It is often necessary to associate arbitrary information with resource IDs. +Xlib provides the +.PN XAssocTable +functions that you can use to make such an association. +.IN "Hash Lookup" +.IN "Window" "IDs" +.IN "Resource IDs" +Application programs often need to be able to easily refer to +their own data structures when an event arrives. +The +.PN XAssocTable +system provides users of the X library with a method +for associating their own data structures with X resources +.Pn ( Pixmaps , +.PN Fonts , +.PN Windows , +and so on). +.LP +An +.PN XAssocTable +can be used to type X resources. +For example, the user +may want to have three or four types of windows, +each with different properties. +This can be accomplished by associating each X window ID +with a pointer to a window property data structure defined by the +user. +A generic type has been defined in the X library for resource IDs. +It is called an XID. +.LP +There are a few guidelines that should be observed when using an +.PN XAssocTable : +.IP \(bu 5 +All XIDs are relative to the specified display. +.IP \(bu 5 +Because of the hashing scheme used by the association mechanism, +the following rules for determining the size of a +.PN XAssocTable +should be followed. +Associations will be made and looked up more +efficiently if the table size (number of buckets in the hashing +system) is a power of two and if there are not more than 8 XIDs per +bucket. +.LP +.sp +To return a pointer to a new +.PN XAssocTable , +use +.PN XCreateAssocTable . +.IN "XCreateAssocTable" "" "@DEF@" +.sM +.FD 0 +XAssocTable *XCreateAssocTable\^(\^\fIsize\fP\^) +.br + int \fIsize\fP\^; +.FN +.IP \fIsize\fP 1i +Specifies the number of buckets in the hash system of +.PN XAssocTable . +.LP +.eM +The size argument specifies the number of buckets in the +hash system of +.PN XAssocTable . +For reasons of efficiency the number of buckets +should be a power of two. +Some size suggestions might be: use 32 buckets per 100 objects, +and a reasonable maximum number of objects per buckets is 8. +If an error allocating memory for the +.PN XAssocTable +occurs, +a NULL pointer is returned. +.LP +.sp +To create an entry in a given +.PN XAssocTable , +use +.PN XMakeAssoc . +.IN "XMakeAssoc" "" "@DEF@" +.sM +.FD 0 +XMakeAssoc\^(\^\fIdisplay\fP, \fItable\fP\^, \fIx_id\fP\^, \fIdata\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XAssocTable *\fItable\fP\^; +.br + XID \fIx_id\fP\^; +.br + char *\fIdata\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fItable\fP 1i +Specifies the assoc table. +.IP \fIx_id\fP 1i +Specifies the X resource ID. +.IP \fIdata\fP 1i +Specifies the data to be associated with the X resource ID. +.LP +.eM +The +.PN XMakeAssoc +function inserts data into an +.PN XAssocTable +keyed on an XID. +Data is inserted into the table only once. +Redundant inserts are ignored. +The queue in each association bucket is sorted from the lowest XID to +the highest XID. +.LP +.sp +To obtain data from a given +.PN XAssocTable , +use +.PN XLookUpAssoc . +.IN "XLookUpAssoc" "" "@DEF@" +.sM +.FD 0 +char *XLookUpAssoc\^(\^\fIdisplay\fP, \fItable\fP\^, \fIx_id\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XAssocTable *\fItable\fP\^; +.br + XID \fIx_id\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fItable\fP 1i +Specifies the assoc table. +.IP \fIx_id\fP 1i +Specifies the X resource ID. +.LP +.eM +The +.PN XLookUpAssoc +function retrieves the data stored in an +.PN XAssocTable +by its XID. +If an appropriately matching XID can be found in the table, +.PN XLookUpAssoc +returns the data associated with it. +If the x_id cannot be found in the table, +it returns NULL. +.LP +.sp +To delete an entry from a given +.PN XAssocTable , +use +.PN XDeleteAssoc . +.IN "XDeleteAssoc" "" "@DEF@" +.sM +.FD 0 +XDeleteAssoc\^(\^\fIdisplay\fP, \fItable\fP\^, \fIx_id\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XAssocTable *\fItable\fP\^; +.br + XID \fIx_id\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fItable\fP 1i +Specifies the assoc table. +.IP \fIx_id\fP 1i +Specifies the X resource ID. +.LP +.eM +The +.PN XDeleteAssoc +function deletes an association in an +.PN XAssocTable +keyed on its XID. +Redundant deletes (and deletes of nonexistent XIDs) are ignored. +Deleting associations in no way impairs the performance of an +.PN XAssocTable . +.LP +.sp +To free the memory associated with a given +.PN XAssocTable , +use +.PN XDestroyAssocTable . +.IN "XDestroyAssocTable" "" "@DEF@" +.sM +.FD 0 +XDestroyAssocTable\^(\^\fItable\fP\^) +.br + XAssocTable *\fItable\fP\^; +.FN +.IP \fItable\fP 1i +Specifies the assoc table. +.LP +.eM +.bp diff --git a/libX11/specs/libX11/CH01 b/libX11/specs/libX11/CH01 new file mode 100644 index 000000000..765e4b5fb --- /dev/null +++ b/libX11/specs/libX11/CH01 @@ -0,0 +1,663 @@ +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be included +.\" in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR +.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +.\" OTHER DEALINGS IN THE SOFTWARE. +.\" +.\" Except as contained in this notice, the name of the X Consortium shall +.\" not be used in advertising or otherwise to promote the sale, use or +.\" other dealings in this Software without prior written authorization +.\" from the X Consortium. +.\" +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by +.\" Digital Equipment Corporation +.\" +.\" Portions Copyright \(co 1990, 1991 by +.\" Tektronix, Inc. +.\" +.\" Permission to use, copy, modify and distribute this documentation for +.\" any purpose and without fee is hereby granted, provided that the above +.\" copyright notice appears in all copies and that both that copyright notice +.\" and this permission notice appear in all copies, and that the names of +.\" Digital and Tektronix not be used in in advertising or publicity pertaining +.\" to this documentation without specific, written prior permission. +.\" Digital and Tektronix makes no representations about the suitability +.\" of this documentation for any purpose. +.\" It is provided ``as is'' without express or implied warranty. +.\" +.EH '\fBXlib \- C Library\fP''\fB\*(xV\fP' +.OH '\fBXlib \- C Library\fP''\fB\*(xV\fP' +.EF ''\fB % \fP'' +.OF ''\fB % \fP'' +.hw WM_NORMAL_HINTS +\& +.sp 1 +.ce 3 +\s+1\fBChapter 1\fP\s-1 + +\s+1\fBIntroduction to Xlib\fP\s-1 +.sp 2 +.if \n(GS .nr nh*hl 1 +.nr H1 1 +.nr H2 0 +.nr H3 0 +.nr H4 0 +.nr H5 0 +.na +.LP +.XS +Chapter 1: Introduction to Xlib +.XE +The X Window System is a network-transparent window system +that was designed at MIT. +X display servers run on computers with either monochrome or color +bitmap display hardware. +The server distributes user input to and accepts output requests from various +client programs located either on the same machine or elsewhere in +the network. +Xlib is a C subroutine library that application programs (clients) +use to interface with the window system by means of a stream connection. +Although a client usually runs on the same machine as the X server +it is talking to, this need not be the case. +.LP +\fIXlib \- C Language X Interface\fP is a reference guide to the low-level +C language interface to the X Window System protocol. +It is neither a tutorial nor a user's guide to programming the X Window System. +Rather, it provides a detailed description of each function in the library +as well as a discussion of the related background information. +\fIXlib \- C Language X Interface\fP assumes a basic understanding of a graphics +window system and of the C programming language. +Other higher-level abstractions +(for example, those provided by the toolkits for X) +are built on top of the Xlib library. +For further information about these higher-level libraries, +see the appropriate toolkit documentation. +The \fIX Window System Protocol\fP provides the definitive word on the +behavior of X. +Although additional information appears here, +the protocol document is the ruling document. +.LP +To provide an introduction to X programming, +this chapter discusses: +.IP \(bu 5 +Overview of the X Window System +.IP \(bu 5 +Errors +.IP \(bu 5 +Standard header files +.IP \(bu 5 +Generic values and types +.IP \(bu 5 +Naming and argument conventions within Xlib +.IP \(bu 5 +Programming considerations +.IP \(bu 5 +Character sets and encodings +.IP \(bu 5 +Formatting conventions +.NH 2 +Overview of the X Window System +.XS +\*(SN Overview of the X Window System +.XE +.LP +Some of the terms used in this book are unique to X, +and other terms that are common to other window systems +have different meanings in X. +You may find it helpful to refer to the glossary, +which is located at the end of the book. +.LP +The X Window System supports one or more screens containing +overlapping windows or subwindows. +A screen is a physical monitor and hardware +that can be color, grayscale, or monochrome. +There can be multiple screens for each display or workstation. +A single X server can provide display services for any number of screens. +A set of screens for a single user with one keyboard and one pointer +(usually a mouse) is called a display. +.LP +.IN "Screen" +All the windows in an X server are arranged in strict hierarchies. +At the top of each hierarchy is a root window, +which covers each of the display screens. +Each root window is partially or completely covered by child windows. +All windows, except for root windows, have parents. +There is usually at least one window for each application program. +.IN "Child window" +.IN "Parent Window" +Child windows may in turn have their own children. +In this way, +an application program can create an arbitrarily deep tree +on each screen. +X provides graphics, text, and raster operations for windows. +.LP +A child window can be larger than its parent. +That is, part or all of +the child window can extend beyond the boundaries of the parent, +but all output to a window is clipped by its parent. +.IN "Stacking order" +If several children of a window have overlapping locations, +one of the children is considered to be on top of or raised over the +others, thus obscuring them. +Output to areas covered by other windows is suppressed by the window +system unless the window has backing store. +If a window is obscured by a second window, +the second window obscures only those ancestors of the second window +that are also ancestors of the first window. +.LP +.IN "Window" "" "@DEF@" +A window has a border zero or more pixels in width, which can +be any pattern (pixmap) or solid color you like. +A window usually but not always has a background pattern, +which will be repainted by the window system when uncovered. +Child windows obscure their parents, +and graphic operations in the parent window usually +are clipped by the children. +.LP +Each window and pixmap has its own coordinate system. +The coordinate system has the X axis horizontal and the Y axis vertical +with the origin [0, 0] at the upper-left corner. +Coordinates are integral, +in terms of pixels, +and coincide with pixel centers. +For a window, +the origin is inside the border at the inside, upper-left corner. +.LP +X does not guarantee to preserve the contents of windows. +When part or all of a window is hidden and then brought back onto the screen, +its contents may be lost. +The server then sends the client program an +.PN Expose +event to notify it that part or all of the window needs to be repainted. +Programs must be prepared to regenerate the contents of windows on demand. +.LP +.IN "Pixmap" +.IN "Drawable" +.IN "Tile" +.IN "Bitmap" +X also provides off-screen storage of graphics objects, +called pixmaps. +Single plane (depth 1) pixmaps are sometimes referred to as bitmaps. +Pixmaps can be used in most graphics functions interchangeably with +windows and are used in various graphics operations to define patterns or tiles. +Windows and pixmaps together are referred to as drawables. +.LP +Most of the functions in Xlib just add requests to an output buffer. +These requests later execute asynchronously on the X server. +Functions that return values of information stored in +the server do not return (that is, they block) +until an explicit reply is received or an error occurs. +You can provide an error handler, +which will be called when the error is reported. +.LP +.IN "XSync" +If a client does not want a request to execute asynchronously, +it can follow the request with a call to +.PN XSync , +which blocks until all previously buffered +asynchronous events have been sent and acted on. +As an important side effect, +the output buffer in Xlib is always flushed by a call to any function +that returns a value from the server or waits for input. +.LP +.IN "Resource IDs" +.IN "Resource IDs" "Window" +.IN "Resource IDs" "Font" +.IN "Resource IDs" "Pixmap" +.IN "Resource IDs" "Cursor" +.IN "Resource IDs" "GContext" +Many Xlib functions will return an integer resource ID, +which allows you to refer to objects stored on the X server. +These can be of type +.PN Window , +.PN Font , +.PN Pixmap , +.PN Colormap , +.PN Cursor , +and +.PN GContext , +as defined in the file +.hN X11/X.h . +These resources are created by requests and are destroyed +(or freed) by requests or when connections are closed. +Most of these resources are potentially sharable between +applications, and in fact, windows are manipulated explicitly by +window manager programs. +Fonts and cursors are shared automatically across multiple screens. +Fonts are loaded and unloaded as needed and are shared by multiple clients. +Fonts are often cached in the server. +Xlib provides no support for sharing graphics contexts between applications. +.LP +.IN "Event" +Client programs are informed of events. +Events may either be side effects of a request (for example, restacking windows +generates +.PN Expose +events) or completely asynchronous (for example, from the keyboard). +A client program asks to be informed of events. +Because other applications can send events to your application, +programs must be prepared to handle (or ignore) events of all types. +.LP +Input events (for example, a key pressed or the pointer moved) +arrive asynchronously from the server and are queued until they are +requested by an explicit call (for example, +.PN XNextEvent +or +.PN XWindowEvent ). +In addition, some library +functions (for example, +.PN XRaiseWindow ) +generate +.PN Expose +and +.PN ConfigureRequest +events. +These events also arrive asynchronously, but the client may +.IN "XSync" +wish to explicitly wait for them by calling +.PN XSync +after calling a function that can cause the server to generate events. +.NH 2 +Errors +.XS +\*(SN Errors +.XE +.LP +Some functions return +.PN Status , +an integer error indication. +If the function fails, it returns a zero. +If the function returns a status of zero, +it has not updated the return arguments. +.IN "Status" +Because C does not provide multiple return values, +many functions must return their results by writing into client-passed storage. +.IN "Error" "handling" +By default, errors are handled either by a standard library function +or by one that you provide. +Functions that return pointers to strings return NULL pointers if +the string does not exist. +.LP +The X server reports protocol errors at the time that it detects them. +If more than one error could be generated for a given request, +the server can report any of them. +.LP +Because Xlib usually does not transmit requests to the server immediately +(that is, it buffers them), errors can be reported much later than they +actually occur. +For debugging purposes, however, +Xlib provides a mechanism for forcing synchronous behavior +(see section 11.8.1). +When synchronization is enabled, +errors are reported as they are generated. +.LP +When Xlib detects an error, +it calls an error handler, +which your program can provide. +If you do not provide an error handler, +the error is printed, and your program terminates. +.NH 2 +Standard Header Files +.XS +\*(SN Standard Header Files +.XE +.LP +The following include files are part of the Xlib standard: +.IP \(bu 5 +.hN X11/Xlib.h +.IP +This is the main header file for Xlib. +The majority of all Xlib symbols are declared by including this file. +This file also contains the preprocessor symbol +.PN XlibSpecificationRelease . +.IN "XlibSpecificationRelease" "" "@DEF@" +This symbol is defined to have the 6 in this release of the standard. +(Release 5 of Xlib was the first release to have this symbol.) +.IP \(bu 5 +.hN X11/X.h +.IP +This file declares types and constants for the X protocol that are +to be used by applications. +It is included automatically from +.hN X11/Xlib.h , +so application code should never need to reference this file directly. +.IP \(bu 5 +.hN X11/Xcms.h +.IP +This file contains symbols for much of the color management facilities +described in chapter 6. +All functions, types, and symbols with the prefix ``Xcms'', +plus the Color Conversion Contexts macros, are declared in this file. +.hN X11/Xlib.h +must be included before including this file. +.IP \(bu 5 +.hN X11/Xutil.h +.IP +This file declares various functions, types, and symbols used for +inter-client communication and application utility functions, +which are described in chapters 14 and 16. +.hN X11/Xlib.h +must be included before including this file. +.IP \(bu 5 +.hN X11/Xresource.h +.IP +This file declares all functions, types, and symbols for the +resource manager facilities, which are described in chapter 15. +.hN X11/Xlib.h +must be included before including this file. +.IP \(bu 5 +.hN X11/Xatom.h +.IP +This file declares all predefined atoms, +which are symbols with the prefix ``XA_''. +.IP \(bu 5 +.hN X11/cursorfont.h +.IP +This file declares the cursor symbols for the standard cursor font, +which are listed in appendix B. +All cursor symbols have the prefix ``XC_''. +.IP \(bu 5 +.hN X11/keysymdef.h +.IP +This file declares all standard KeySym values, +which are symbols with the prefix ``XK_''. +The KeySyms are arranged in groups, and a preprocessor symbol controls +inclusion of each group. The preprocessor symbol must be defined +prior to inclusion of the file to obtain the associated values. +The preprocessor symbols are XK_MISCELLANY, XK_XKB_KEYS, XK_3270, +XK_LATIN1, XK_LATIN2, +XK_LATIN3, XK_LATIN4, XK_KATAKANA, XK_ARABIC, XK_CYRILLIC, XK_GREEK, +XK_TECHNICAL, XK_SPECIAL, XK_PUBLISHING, XK_APL, XK_HEBREW, +XK_THAI, and XK_KOREAN. +.IP \(bu 5 +.hN X11/keysym.h +.IP +This file defines the preprocessor symbols +XK_MISCELLANY, XK_XKB_KEYS, XK_LATIN1, XK_LATIN2, XK_LATIN3, +XK_LATIN4, and XK_GREEK +and then includes +.hN X11/keysymdef.h . +.IP \(bu 5 +.hN X11/Xlibint.h +.IP +This file declares all the functions, types, and symbols used for +extensions, which are described in appendix C. +This file automatically includes +.hN X11/Xlib.h . +.IP \(bu 5 +.hN X11/Xproto.h +.IP +This file declares types and symbols for the basic X protocol, +for use in implementing extensions. +It is included automatically from +.hN X11/Xlibint.h , +so application and extension code should never need to +reference this file directly. +.IP \(bu 5 +.hN X11/Xprotostr.h +.IP +This file declares types and symbols for the basic X protocol, +for use in implementing extensions. +It is included automatically from +.hN X11/Xproto.h , +so application and extension code should never need to +reference this file directly. +.IP \(bu 5 +.hN X11/X10.h +.IP +This file declares all the functions, types, and symbols used for the +X10 compatibility functions, which are described in appendix D. +.NH 2 +Generic Values and Types +.XS +\*(SN Generic Values and Types +.XE +.LP +The following symbols are defined by Xlib and used throughout the manual: +.IN "Bool" "" "@DEF@" +.IN "True" "" "@DEF@" +.IN "False" "" "@DEF@" +.IP \(bu 5 +Xlib defines the type +.PN Bool +and the Boolean values +.PN True +and +.PN False . +.IN "None" "" "@DEF@" +.IP \(bu 5 +.PN None +is the universal null resource ID or atom. +.IN "XID" "" "@DEF@" +.IP \(bu 5 +The type +.PN XID +is used for generic resource IDs. +.IN "XPointer" "" "@DEF@" +.IP \(bu 5 +The type +.PN XPointer +is defined to be char\^* and is used as a generic opaque pointer to data. +.NH 2 +Naming and Argument Conventions within Xlib +.XS +\*(SN Naming and Argument Conventions within Xlib +.XE +.LP +Xlib follows a number of conventions for the naming and syntax of the functions. +Given that you remember what information the function requires, +these conventions are intended to make the syntax of the functions more +predictable. +.LP +The major naming conventions are: +.IP \(bu 5 +To differentiate the X symbols from the other symbols, +the library uses mixed case for external symbols. +It leaves lowercase for variables and all uppercase for user macros, +as per existing convention. +.IP \(bu 5 +All Xlib functions begin with a capital X. +.IP \(bu 5 +The beginnings of all function names and symbols are capitalized. +.IP \(bu 5 +All user-visible data structures begin with a capital X. +More generally, +anything that a user might dereference begins with a capital X. +.IP \(bu 5 +Macros and other symbols do not begin with a capital X. +To distinguish them from all user symbols, +each word in the macro is capitalized. +.IP \(bu 5 +All elements of or variables in a data structure are in lowercase. +Compound words, where needed, are constructed with underscores (\^_\^). +.IP \(bu 5 +The display argument, where used, is always first in the argument list. +.IP \(bu 5 +All resource objects, where used, occur at the beginning of the argument list +immediately after the display argument. +.IP \(bu 5 +When a graphics context is present together with +another type of resource (most commonly, a drawable), the +graphics context occurs in the argument list after the other +resource. +Drawables outrank all other resources. +.IP \(bu 5 +Source arguments always precede the destination arguments in the argument list. +.IP \(bu 5 +The x argument always precedes the y argument in the argument list. +.IP \(bu 5 +The width argument always precedes the height argument in the argument list. +.IP \(bu 5 +Where the x, y, width, and height arguments are used together, +the x and y arguments always precede the width and height arguments. +.IP \(bu 5 +Where a mask is accompanied with a structure, +the mask always precedes the pointer to the structure in the argument list. +.NH 2 +Programming Considerations +.XS +\*(SN Programming Considerations +.XE +.LP +The major programming considerations are: +.IP \(bu 5 +Coordinates and sizes in X are actually 16-bit quantities. +This decision was made to minimize the bandwidth required for a +given level of performance. +Coordinates usually are declared as an +.PN int +in the interface. +Values larger than 16 bits are truncated silently. +Sizes (width and height) are declared as unsigned quantities. +.IP \(bu 5 +Keyboards are the greatest variable between different +manufacturers' workstations. +If you want your program to be portable, +you should be particularly conservative here. +.IP \(bu 5 +Many display systems have limited amounts of off-screen memory. +If you can, you should minimize use of pixmaps and backing +store. +.IP \(bu 5 +The user should have control of his screen real estate. +Therefore, you should write your applications to react to window management +rather than presume control of the entire screen. +What you do inside of your top-level window, however, +is up to your application. +For further information, +see chapter 14 +and the \fIInter-Client Communication Conventions Manual\fP. +.NH 2 +Character Sets and Encodings +.XS +\*(SN Character Sets and Encodings +.XE +.LP +Some of the Xlib functions make reference to specific character sets +and character encodings. +The following are the most common: +.IP \(bu 5 +X Portable Character Set +.IP +A basic set of 97 characters, +which are assumed to exist in all locales supported by Xlib. +This set contains the following characters: +.IP +.Ds 0 +.EQ +delim DD +.EN +a..z A..Z 0..9 +!"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~ +, , and +.EQ +delim %% +.EN +.De +.IP +This set is the left/lower half +of the graphic character set of ISO8859-1 plus space, tab, and newline. +It is also the set of graphic characters in 7-bit ASCII plus the same +three control characters. +The actual encoding of these characters on the host is system dependent. +.IP \(bu 5 +Host Portable Character Encoding +.IP +The encoding of the X Portable Character Set on the host. +The encoding itself is not defined by this standard, +but the encoding must be the same in all locales supported by Xlib on the host. +If a string is said to be in the Host Portable Character Encoding, +then it only contains characters from the X Portable Character Set, +in the host encoding. +.IP \(bu 5 +Latin-1 +.IP +The coded character set defined by the ISO8859-1 standard. +.IP \(bu 5 +Latin Portable Character Encoding +.IP +The encoding of the X Portable Character Set using the Latin-1 codepoints +plus ASCII control characters. +If a string is said to be in the Latin Portable Character Encoding, +then it only contains characters from the X Portable Character Set, +not all of Latin-1. +.IP \(bu 5 +STRING Encoding +.IP +Latin-1, plus tab and newline. +.IP \(bu 5 +POSIX Portable Filename Character Set +.IP +The set of 65 characters, +which can be used in naming files on a POSIX-compliant host, +that are correctly processed in all locales. +The set is: +.IP +.Ds 0 +a..z A..Z 0..9 ._- +.De +.NH 2 +Formatting Conventions +.XS +\*(SN Formatting Conventions +.XE +.LP +\fIXlib \- C Language X Interface\fP uses the following conventions: +.IP \(bu 5 +Global symbols are printed in +.PN this +.PN special +.PN font . +These can be either function names, +symbols defined in include files, or structure names. +When declared and defined, +function arguments are printed in \fIitalics\fP. +In the explanatory text that follows, +they usually are printed in regular type. +.IP \(bu 5 +Each function is introduced by a general discussion that +distinguishes it from other functions. +The function declaration itself follows, +and each argument is specifically explained. +Although ANSI C function prototype syntax is not used, +Xlib header files normally declare functions using function prototypes +in ANSI C environments. +General discussion of the function, if any is required, +follows the arguments. +Where applicable, +the last paragraph of the explanation lists the possible +Xlib error codes that the function can generate. +For a complete discussion of the Xlib error codes, +see section 11.8.2. +.IP \(bu 5 +To eliminate any ambiguity between those arguments that you pass and those that +a function returns to you, +the explanations for all arguments that you pass start with the word +\fIspecifies\fP or, in the case of multiple arguments, the word \fIspecify\^\fP. +The explanations for all arguments that are returned to you start with the +word \fIreturns\fP or, in the case of multiple arguments, the word \fIreturn\^\fP. +The explanations for all arguments that you can pass and are returned start +with the words \fIspecifies and returns\^\fP. +.IP \(bu 5 +Any pointer to a structure that is used to return a value is designated as +such by the \fI_return\fP suffix as part of its name. +All other pointers passed to these functions are +used for reading only. +A few arguments use pointers to structures that are used for +both input and output and are indicated by using the \fI_in_out\fP suffix. +.bp diff --git a/libX11/specs/libX11/CH02 b/libX11/specs/libX11/CH02 new file mode 100644 index 000000000..61554b898 --- /dev/null +++ b/libX11/specs/libX11/CH02 @@ -0,0 +1,2052 @@ +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996, 2000 The Open Group +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be included +.\" in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR +.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +.\" OTHER DEALINGS IN THE SOFTWARE. +.\" +.\" Except as contained in this notice, the name of The Open Group shall +.\" not be used in advertising or otherwise to promote the sale, use or +.\" other dealings in this Software without prior written authorization +.\" from The Open Group. +.\" +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by +.\" Digital Equipment Corporation +.\" +.\" Portions Copyright \(co 1990, 1991 by +.\" Tektronix, Inc. +.\" +.\" Permission to use, copy, modify and distribute this documentation for +.\" any purpose and without fee is hereby granted, provided that the above +.\" copyright notice appears in all copies and that both that copyright notice +.\" and this permission notice appear in all copies, and that the names of +.\" Digital and Tektronix not be used in in advertising or publicity pertaining +.\" to this documentation without specific, written prior permission. +.\" Digital and Tektronix makes no representations about the suitability +.\" of this documentation for any purpose. +.\" It is provided ``as is'' without express or implied warranty. +.\" +.\" $XFree86$ +\& +.sp 1 +.ce 3 +\s+1\fBChapter 2\fP\s-1 + +\s+1\fBDisplay Functions\fP\s-1 +.sp 2 +.nr H1 2 +.nr H2 0 +.nr H3 0 +.nr H4 0 +.nr H5 0 +.na +.LP +.XS +Chapter 2: Display Functions +.XE +Before your program can use a display, you must establish a connection +to the X server. +Once you have established a connection, +you then can use the Xlib macros and functions discussed in this chapter +to return information about the display. +This chapter discusses how to: +.IP \(bu 5 +Open (connect to) the display +.IP \(bu 5 +Obtain information about the display, image formats, or screens +.IP \(bu 5 +Generate a +.PN NoOperation +protocol request +.IP \(bu 5 +Free client-created data +.IP \(bu 5 +Close (disconnect from) a display +.IP \(bu 5 +Use X Server connection close operations +.IP \(bu 5 +Use Xlib with threads +.IP \(bu 5 +Use internal connections +.NH 2 +Opening the Display +.XS +\*(SN Opening the Display +.XE +.LP +To open a connection to the X server that controls a display, use +.PN XOpenDisplay . +.IN "XOpenDisplay" "" "@DEF@" +.LP +.sM +.FD 0 +Display *XOpenDisplay\^(\^\fIdisplay_name\fP\^) +.br + char *\fIdisplay_name\fP\^; +.FN +.IP \fIdisplay_name\fP 1i +Specifies the hardware display name, which determines the display +and communications domain to be used. +On a POSIX-conformant system, if the display_name is NULL, +it defaults to the value of the DISPLAY environment variable. +.IN "Environment" "DISPLAY" +.LP +.eM +The encoding and interpretation of the display name are +implementation-dependent. +Strings in the Host Portable Character Encoding are supported; +support for other characters is implementation-dependent. +On POSIX-conformant systems, +the display name or DISPLAY environment variable can be a string in the format: +.LP +.sM +.Ds 0 +.TA 1i +.ta 1i + \fIprotocol\fP\^/\^\fIhostname\fP\^:\^\fInumber\fP\^.\^\fIscreen_number\fP +.De +.IP \fIprotocol\fP 1i +Specifies a protocol family or an alias for a protocol family. Supported +protocol families are implementation dependent. The protocol entry is +optional. If protocol is not specified, the / separating protocol and +hostname must also not be specified. +.IP \fIhostname\fP 1i +Specifies the name of the host machine on which the display is physically +attached. +You follow the hostname with either a single colon (:) or a double colon (::). +.IP \fInumber\fP 1i +Specifies the number of the display server on that host machine. +You may optionally follow this display number with a period (.). +A single CPU can have more than one display. +Multiple displays are usually numbered starting with zero. +.IN "Screen" +.IP \fIscreen_number\fP 1i +Specifies the screen to be used on that server. +Multiple screens can be controlled by a single X server. +The screen_number sets an internal variable that can be accessed by +using the +.PN DefaultScreen +macro or the +.PN XDefaultScreen +function if you are using languages other than C (see section 2.2.1). +.LP +.eM +For example, the following would specify screen 1 of display 0 on the +machine named ``dual-headed'': +.LP +.Ds +dual-headed:0.1 +.De +.LP +The +.PN XOpenDisplay +function returns a +.PN Display +structure that serves as the +connection to the X server and that contains all the information +about that X server. +.PN XOpenDisplay +connects your application to the X server through TCP +or DECnet communications protocols, +or through some local inter-process communication protocol. +.IN "Protocol" "TCP" +.IN "Protocol" "DECnet" +If the protocol is specified as "tcp", "inet", or "inet6", or +if no protocol is specified and the hostname is a host machine name and a single colon (:) +separates the hostname and display number, +.PN XOpenDisplay +connects using TCP streams. (If the protocol is specified as "inet", TCP over +IPv4 is used. If the protocol is specified as "inet6", TCP over IPv6 is used. +Otherwise, the implementation determines which IP version is used.) +If the hostname and protocol are both not specified, +Xlib uses whatever it believes is the fastest transport. +If the hostname is a host machine name and a double colon (::) +separates the hostname and display number, +.PN XOpenDisplay +connects using DECnet. +A single X server can support any or all of these transport mechanisms +simultaneously. +A particular Xlib implementation can support many more of these transport +mechanisms. +.LP +.IN "Display" +If successful, +.PN XOpenDisplay +returns a pointer to a +.PN Display +structure, +which is defined in +.hN X11/Xlib.h . +If +.PN XOpenDisplay +does not succeed, it returns NULL. +After a successful call to +.PN XOpenDisplay , +all of the screens in the display can be used by the client. +The screen number specified in the display_name argument is returned +by the +.PN DefaultScreen +macro (or the +.PN XDefaultScreen +function). +You can access elements of the +.PN Display +and +.PN Screen +structures only by using the information macros or functions. +For information about using macros and functions to obtain information from +the +.PN Display +structure, +see section 2.2.1. +.LP +X servers may implement various types of access control mechanisms +(see section 9.8). +.NH 2 +Obtaining Information about the Display, Image Formats, or Screens +.XS +\*(SN Obtaining Information about the Display, Image Formats, or Screens +.XE +.LP +The Xlib library provides a number of useful macros +and corresponding functions that return data from the +.PN Display +structure. +The macros are used for C programming, +and their corresponding function equivalents are for other language bindings. +This section discusses the: +.IP \(bu 5 +Display macros +.IP \(bu 5 +Image format functions and macros +.IP \(bu 5 +Screen information macros +.LP +.IN "Display" "data structure" +All other members of the +.PN Display +structure (that is, those for which no macros are defined) are private to Xlib +and must not be used. +Applications must never directly modify or inspect these private members of the +.PN Display +structure. +.NT Note +The +.PN XDisplayWidth , +.PN XDisplayHeight , +.PN XDisplayCells , +.PN XDisplayPlanes , +.PN XDisplayWidthMM , +and +.PN XDisplayHeightMM +functions in the next sections are misnamed. +These functions really should be named Screen\fIwhatever\fP +and XScreen\fIwhatever\fP, not Display\fIwhatever\fP or XDisplay\fIwhatever\fP. +Our apologies for the resulting confusion. +.NE +.NH 3 +Display Macros +.XS +\*(SN Display Macros +.XE +.LP +Applications should not directly modify any part of the +.PN Display +and +.PN Screen +structures. +The members should be considered read-only, +although they may change as the result of other operations on the display. +.LP +The following lists the C language macros, +their corresponding function equivalents that are for other language bindings, +and what data both can return. +.LP +.sp +.sM +.FD 0 +AllPlanes +.sp +unsigned long XAllPlanes(\^) +.FN +.LP +.eM +.IN "AllPlanes" "" "@DEF@" +.IN "XAllPlanes" "" "@DEF@" +Both return a value with all bits set to 1 suitable for use in a plane argument to +a procedure. +.LP +.sp +Both +.PN BlackPixel +and +.PN WhitePixel +can be used in implementing a monochrome application. +These pixel values are for permanently allocated entries in the default +colormap. +The actual RGB (red, green, and blue) values are settable on some screens +and, in any case, may not actually be black or white. +The names are intended to convey the expected relative intensity of the colors. +.sM +.FD 0 +BlackPixel\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) +.sp +unsigned long XBlackPixel\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIscreen_number\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIscreen_number\fP 1i +Specifies the appropriate screen number on the host server. +.LP +.eM +.IN "BlackPixel" "" "@DEF@" +.IN "XBlackPixel" "" "@DEF@" +Both return the black pixel value for the specified screen. +.LP +.sp +.sM +.FD 0 +WhitePixel\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) +.sp +unsigned long XWhitePixel\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIscreen_number\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIscreen_number\fP 1i +Specifies the appropriate screen number on the host server. +.LP +.eM +.IN "WhitePixel" "" "@DEF@" +.IN "XWhitePixel" "" "@DEF@" +Both return the white pixel value for the specified screen. +.LP +.sp +.sM +.FD 0 +ConnectionNumber\^(\^\fIdisplay\fP\^) +.sp +int XConnectionNumber\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +.IN "ConnectionNumber" "" "@DEF@" +.IN "XConnectionNumber" "" "@DEF@" +Both return a connection number for the specified display. +On a POSIX-conformant system, +this is the file descriptor of the connection. +.LP +.sp +.sM +.FD 0 +DefaultColormap\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) +.sp +Colormap XDefaultColormap\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIscreen_number\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIscreen_number\fP 1i +Specifies the appropriate screen number on the host server. +.LP +.eM +.IN "DefaultColormap" "" "@DEF@" +.IN "XDefaultColormap" "" "@DEF@" +Both return the default colormap ID for allocation on the specified screen. +Most routine allocations of color should be made out of this colormap. +.LP +.sp +.sM +.FD 0 +DefaultDepth\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) +.sp +int XDefaultDepth\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIscreen_number\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIscreen_number\fP 1i +Specifies the appropriate screen number on the host server. +.LP +.eM +.IN "DefaultDepth" "" "@DEF@" +.IN "XDefaultDepth" "" "@DEF@" +Both return the depth (number of planes) of the default root window for the +specified screen. +Other depths may also be supported on this screen (see +.PN XMatchVisualInfo ). +.LP +.sp +.IN "XListDepths" "" "@DEF@" +To determine the number of depths that are available on a given screen, use +.PN XListDepths . +.sM +.FD 0 +int *XListDepths\^(\^\fIdisplay\fP, \fIscreen_number\fP, \fIcount_return\fP\^) +.br + Display *\fIdisplay\fP; +.br + int \fIscreen_number\fP; +.br + int *\fIcount_return\fP; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIscreen_number\fP 1i +Specifies the appropriate screen number on the host server. +.ds Cn depths +.IP \fIcount_return\fP 1i +Returns the number of \*(Cn. +.LP +.eM +The +.PN XListDepths +function returns the array of depths +that are available on the specified screen. +If the specified screen_number is valid and sufficient memory for the array +can be allocated, +.PN XListDepths +sets count_return to the number of available depths. +Otherwise, it does not set count_return and returns NULL. +To release the memory allocated for the array of depths, use +.PN XFree . +.LP +.sp +.sM +.FD 0 +DefaultGC\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) +.sp +GC XDefaultGC\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIscreen_number\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIscreen_number\fP 1i +Specifies the appropriate screen number on the host server. +.LP +.eM +.IN "DefaultGC" "" "@DEF@" +.IN "XDefaultGC" "" "@DEF@" +Both return the default graphics context for the root window of the +specified screen. +This GC is created for the convenience of simple applications +and contains the default GC components with the foreground and +background pixel values initialized to the black and white +pixels for the screen, respectively. +You can modify its contents freely because it is not used in any Xlib +function. +This GC should never be freed. +.LP +.sp +.sM +.FD 0 +DefaultRootWindow\^(\^\fIdisplay\fP\^) +.sp +Window XDefaultRootWindow\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +.IN "DefaultRootWindow" "" "@DEF@" +.IN "XDefaultRootWindow" "" "@DEF@" +Both return the root window for the default screen. +.LP +.sp +.sM +.FD 0 +DefaultScreenOfDisplay\^(\^\fIdisplay\fP\^) +.sp +Screen *XDefaultScreenOfDisplay\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +.IN "DefaultScreenOfDisplay" "" "@DEF@" +.IN "XDefaultScreenOfDisplay" "" "@DEF@" +Both return a pointer to the default screen. +.LP +.sp +.sM +.FD 0 +ScreenOfDisplay\^(\^\fIdisplay\fP, \fIscreen_number\fP\^) +.sp +Screen *XScreenOfDisplay\^(\^\fIdisplay\fP, \fIscreen_number\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIscreen_number\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIscreen_number\fP 1i +Specifies the appropriate screen number on the host server. +.LP +.eM +.IN "ScreenOfDisplay" "" "@DEF@" +.IN "XScreenOfDisplay" "" "@DEF@" +Both return a pointer to the indicated screen. +.LP +.sp +.sM +.FD 0 +DefaultScreen\^(\^\fIdisplay\fP\^) +.sp +int XDefaultScreen\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +.IN "DefaultScreen" "" "@DEF@" +.IN "XDefaultScreen" "" "@DEF@" +Both return the default screen number referenced by the +.PN XOpenDisplay +function. +This macro or function should be used to retrieve the screen number +in applications that will use only a single screen. +.LP +.sp +.sM +.FD 0 +DefaultVisual\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) +.sp +Visual *XDefaultVisual\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIscreen_number\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIscreen_number\fP 1i +Specifies the appropriate screen number on the host server. +.LP +.eM +.IN "DefaultVisual" "" "@DEF@" +.IN "XDefaultVisual" "" "@DEF@" +Both return the default visual type for the specified screen. +For further information about visual types, +see section 3.1. +.LP +.sp +.sM +.FD 0 +DisplayCells\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) +.sp +int XDisplayCells\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIscreen_number\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIscreen_number\fP 1i +Specifies the appropriate screen number on the host server. +.LP +.eM +.IN "DisplayCells" "" "@DEF@" +.IN "XDisplayCells" "" "@DEF@" +Both return the number of entries in the default colormap. +.LP +.sp +.sM +.FD 0 +DisplayPlanes\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) +.sp +int XDisplayPlanes\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIscreen_number\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIscreen_number\fP 1i +Specifies the appropriate screen number on the host server. +.LP +.eM +.IN "DisplayPlanes" "" "@DEF@" +.IN "XDisplayPlanes" "" "@DEF@" +Both return the depth of the root window of the specified screen. +For an explanation of depth, +see the glossary. +.LP +.sp +.sM +.FD 0 +DisplayString\^(\^\fIdisplay\fP\^) +.sp +char *XDisplayString\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +.IN "DisplayString" "" "@DEF@" +.IN "XDisplayString" "" "@DEF@" +Both return the string that was passed to +.PN XOpenDisplay +when the current display was opened. +On POSIX-conformant systems, +if the passed string was NULL, these return the value of +the DISPLAY environment variable when the current display was opened. +.IN "POSIX System Call" "fork" +These are useful to applications that invoke the +.PN fork +system call and want to open a new connection to the same display from the +child process as well as for printing error messages. +.LP +.sp +.sM +.FD 0 +long XExtendedMaxRequestSize(\^\fIdisplay\fP\^) + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +.IN "XExtendedMaxRequestSize" "" "@DEF@" +The +.PN XExtendedMaxRequestSize +function returns zero if the specified display does not support an +extended-length protocol encoding; otherwise, +it returns the maximum request size (in 4-byte units) supported +by the server using the extended-length encoding. +The Xlib functions +.PN XDrawLines , +.PN XDrawArcs , +.PN XFillPolygon , +.PN XChangeProperty , +.PN XSetClipRectangles , +and +.PN XSetRegion +will use the extended-length encoding as necessary, if supported +by the server. Use of the extended-length encoding in other Xlib +functions (for example, +.PN XDrawPoints , +.PN XDrawRectangles , +.PN XDrawSegments , +.PN XFillArcs , +.PN XFillRectangles , +.PN XPutImage ) +is permitted but not required; an Xlib implementation may choose to +split the data across multiple smaller requests instead. +.LP +.sp +.sM +.FD 0 +long XMaxRequestSize(\^\fIdisplay\fP\^) + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +.IN "XMaxRequestSize" "" "@DEF@" +The +.PN XMaxRequestSize +function returns the maximum request size (in 4-byte units) supported +by the server without using an extended-length protocol encoding. +Single protocol requests to the server can be no larger than this size +unless an extended-length protocol encoding is supported by the server. +The protocol guarantees the size to be no smaller than 4096 units +(16384 bytes). +Xlib automatically breaks data up into multiple protocol requests +as necessary for the following functions: +.PN XDrawPoints , +.PN XDrawRectangles , +.PN XDrawSegments , +.PN XFillArcs , +.PN XFillRectangles , +and +.PN XPutImage . +.LP +.sp +.sM +.FD 0 +LastKnownRequestProcessed\^(\^\fIdisplay\fP\^) +.sp +unsigned long XLastKnownRequestProcessed\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +.IN "LastKnownRequestProcessed" "" "@DEF@" +.IN "XLastKnownRequestProcessed" "" "@DEF@" +Both extract the full serial number of the last request known by Xlib +to have been processed by the X server. +Xlib automatically sets this number when replies, events, and errors +are received. +.LP +.sp +.sM +.FD 0 +NextRequest\^(\^\fIdisplay\fP\^) +.sp +unsigned long XNextRequest\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +.IN "NextRequest" "" "@DEF@" +.IN "XNextRequest" "" "@DEF@" +Both extract the full serial number that is to be used for the next +request. +Serial numbers are maintained separately for each display connection. +.LP +.sp +.sM +.FD 0 +ProtocolVersion\^(\^\fIdisplay\fP\^) +.sp +int XProtocolVersion\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +.IN "ProtocolVersion" "" "@DEF@" +.IN "XProtocolVersion" "" "@DEF@" +Both return the major version number (11) of the X protocol associated with +the connected display. +.LP +.sp +.sM +.FD 0 +ProtocolRevision\^(\^\fIdisplay\fP\^) +.sp +int XProtocolRevision\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +.IN "ProtocolRevision" "" "@DEF@" +.IN "XProtocolRevision" "" "@DEF@" +Both return the minor protocol revision number of the X server. +.LP +.sp +.sM +.FD 0 +QLength\^(\^\fIdisplay\fP\^) +.sp +int XQLength\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +.IN "QLength" "" "@DEF@" +.IN "XQLength" "" "@DEF@" +Both return the length of the event queue for the connected display. +Note that there may be more events that have not been read into +the queue yet (see +.PN XEventsQueued ). +.LP +.sp +.sM +.FD 0 +RootWindow\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) +.sp +Window XRootWindow\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIscreen_number\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIscreen_number\fP 1i +Specifies the appropriate screen number on the host server. +.LP +.eM +.IN "Window" "RootWindow" +.IN "RootWindow" "" "@DEF@" +.IN "Window" "XRootWindow" +.IN "XRootWindow" "" "@DEF@" +Both return the root window. +These are useful with functions that need a drawable of a particular screen +and for creating top-level windows. +.LP +.sp +.sM +.FD 0 +ScreenCount\^(\^\fIdisplay\fP\^) +.sp +int XScreenCount\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +.IN "ScreenCount" "" "@DEF@" +.IN "XScreenCount" "" "@DEF@" +Both return the number of available screens. +.LP +.sp +.sM +.FD 0 +ServerVendor\^(\^\fIdisplay\fP\^) +.sp +char *XServerVendor\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +.IN "ServerVendor" "" "@DEF@" +.IN "XServerVendor" "" "@DEF@" +Both return a pointer to a null-terminated string that provides +some identification of the owner of the X server implementation. +If the data returned by the server is in the Latin Portable Character Encoding, +then the string is in the Host Portable Character Encoding. +Otherwise, the contents of the string are implementation-dependent. +.LP +.sp +.sM +.FD 0 +VendorRelease\^(\^\fIdisplay\fP\^) +.sp +int XVendorRelease\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +.IN "VendorRelease" "" "@DEF@" +.IN "XVendorRelease" "" "@DEF@" +Both return a number related to a vendor's release of the X server. +.NH 3 +Image Format Functions and Macros +.XS +\*(SN Image Format Functions and Macros +.XE +.LP +Applications are required to present data to the X server +in a format that the server demands. +To help simplify applications, +most of the work required to convert the data is provided by Xlib +(see sections 8.7 and 16.8). +.LP +The +.PN XPixmapFormatValues +structure provides an interface to the pixmap format information +that is returned at the time of a connection setup. +It contains: +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + int depth; + int bits_per_pixel; + int scanline_pad; +} XPixmapFormatValues; +.De +.LP +.eM +.sp +To obtain the pixmap format information for a given display, use +.PN XListPixmapFormats . +.IN "XListPixmapFormats" "" "@DEF@" +.sM +.FD 0 +XPixmapFormatValues *XListPixmapFormats\^(\^\fIdisplay\fP, \fIcount_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int *\fIcount_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.ds Cn pixmap formats that are supported by the display +.IP \fIcount_return\fP 1i +Returns the number of \*(Cn. +.LP +.eM +The +.PN XListPixmapFormats +function returns an array of +.PN XPixmapFormatValues +structures that describe the types of Z format images supported +by the specified display. +If insufficient memory is available, +.PN XListPixmapFormats +returns NULL. +To free the allocated storage for the +.PN XPixmapFormatValues +structures, use +.PN XFree . +.LP +The following lists the C language macros, +their corresponding function equivalents that are for other language bindings, +and what data they both return for the specified server and screen. +These are often used by toolkits as well as by simple applications. +.LP +.sp +.sM +.FD 0 +ImageByteOrder\^(\^\fIdisplay\fP\^) +.sp +int XImageByteOrder\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +.IN "ImageByteOrder" "" "@DEF@" +.IN "XImageByteOrder" "" "@DEF@" +Both specify the required byte order for images for each scanline unit in +XY format (bitmap) or for each pixel value in +Z format. +The macro or function can return either +.PN LSBFirst +or +.PN MSBFirst . +.LP +.sp +.sM +.FD 0 +BitmapUnit\^(\^\fIdisplay\fP\^) +.sp +int XBitmapUnit\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +.IN "BitmapUnit" "" "@DEF@" +.IN "XBitmapUnit" "" "@DEF@" +Both return the size of a bitmap's scanline unit in bits. +The scanline is calculated in multiples of this value. +.LP +.sp +.sM +.FD 0 +BitmapBitOrder\^(\^\fIdisplay\fP\^) +.sp +int XBitmapBitOrder\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +.IN "BitmapBitOrder" "" "@DEF@" +.IN "XBitmapBitOrder" "" "@DEF@" +Within each bitmap unit, the left-most bit in the bitmap as displayed +on the screen is either the least significant or most significant bit in the +unit. +This macro or function can return +.PN LSBFirst +or +.PN MSBFirst . +.LP +.sp +.sM +.FD 0 +BitmapPad\^(\^\fIdisplay\fP\^) +.sp +int XBitmapPad\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +.IN "BitmapPad" "" "@DEF@" +.IN "XBitmapPad" "" "@DEF@" +Each scanline must be padded to a multiple of bits returned +by this macro or function. +.LP +.sp +.sM +.FD 0 +DisplayHeight\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) +.sp +int XDisplayHeight\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIscreen_number\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIscreen_number\fP 1i +Specifies the appropriate screen number on the host server. +.LP +.eM +.IN "DisplayHeight" "" "@DEF@" +.IN "XDisplayHeight" "" "@DEF@" +Both return an integer that describes the height of the screen +in pixels. +.LP +.sp +.sM +.FD 0 +DisplayHeightMM\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) +.sp +int XDisplayHeightMM\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIscreen_number\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIscreen_number\fP 1i +Specifies the appropriate screen number on the host server. +.LP +.eM +.IN "DisplayHeightMM" "" "@DEF@" +.IN "XDisplayHeightMM" "" "@DEF@" +Both return the height of the specified screen in millimeters. +.LP +.sp +.sM +.FD 0 +DisplayWidth\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) +.sp +int XDisplayWidth\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIscreen_number\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIscreen_number\fP 1i +Specifies the appropriate screen number on the host server. +.LP +.eM +.IN "DisplayWidth" "" "@DEF@" +.IN "XDisplayWidth" "" "@DEF@" +Both return the width of the screen in pixels. +.LP +.sp +.sM +.FD 0 +DisplayWidthMM\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) +.sp +int XDisplayWidthMM\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIscreen_number\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIscreen_number\fP 1i +Specifies the appropriate screen number on the host server. +.LP +.eM +.IN "DisplayWidthMM" "" "@DEF@" +.IN "XDisplayWidthMM" "" "@DEF@" +Both return the width of the specified screen in millimeters. +.NH 3 +Screen Information Macros +.XS +\*(SN Screen Information Macros +.XE +.LP +The following lists the C language macros, +their corresponding function equivalents that are for other language bindings, +and what data they both can return. +These macros or functions all take a pointer to the appropriate screen +structure. +.LP +.sp +.sM +.FD 0 +BlackPixelOfScreen\^(\^\fIscreen\fP\^) +.sp +unsigned long XBlackPixelOfScreen\^(\^\fIscreen\fP\^) +.br + Screen *\fIscreen\fP\^; +.FN +.IP \fIscreen\fP 1i +Specifies the appropriate +.PN Screen +structure. +.LP +.eM +.IN "BlackPixelOfScreen" "" "@DEF@" +.IN "XBlackPixelOfScreen" "" "@DEF@" +Both return the black pixel value of the specified screen. +.LP +.sp +.sM +.FD 0 +WhitePixelOfScreen\^(\^\fIscreen\fP\^) +.sp +unsigned long XWhitePixelOfScreen\^(\^\fIscreen\fP\^) +.br + Screen *\fIscreen\fP\^; +.FN +.IP \fIscreen\fP 1i +Specifies the appropriate +.PN Screen +structure. +.LP +.eM +.IN "WhitePixelOfScreen" "" "@DEF@" +.IN "XWhitePixelOfScreen" "" "@DEF@" +Both return the white pixel value of the specified screen. +.LP +.sp +.sM +.FD 0 +CellsOfScreen\^(\^\fIscreen\fP\^) +.sp +int XCellsOfScreen\^(\^\fIscreen\fP\^) +.br + Screen *\fIscreen\fP\^; +.FN +.IP \fIscreen\fP 1i +Specifies the appropriate +.PN Screen +structure. +.LP +.eM +.IN "CellsOfScreen" "" "@DEF@" +.IN "XCellsOfScreen" "" "@DEF@" +Both return the number of colormap cells in the default colormap +of the specified screen. +.LP +.sp +.sM +.FD 0 +DefaultColormapOfScreen\^(\^\fIscreen\fP\^) +.sp +Colormap XDefaultColormapOfScreen\^(\^\fIscreen\fP\^) +.br + Screen *\fIscreen\fP\^; +.FN +.IP \fIscreen\fP 1i +Specifies the appropriate +.PN Screen +structure. +.LP +.eM +.IN "DefaultColormapOfScreen" "" "@DEF@" +.IN "XDefaultColormapOfScreen" "" "@DEF@" +Both return the default colormap of the specified screen. +.LP +.sp +.sM +.FD 0 +DefaultDepthOfScreen\^(\^\fIscreen\fP\^) +.sp +int XDefaultDepthOfScreen\^(\^\fIscreen\fP\^) +.br + Screen *\fIscreen\fP\^; +.FN +.IP \fIscreen\fP 1i +Specifies the appropriate +.PN Screen +structure. +.LP +.eM +.IN "DefaultDepthOfScreen" "" "@DEF@" +.IN "XDefaultDepthOfScreen" "" "@DEF@" +Both return the depth of the root window. +.LP +.sp +.sM +.FD 0 +DefaultGCOfScreen\^(\^\fIscreen\fP\^) +.sp +GC XDefaultGCOfScreen\^(\^\fIscreen\fP\^) +.br + Screen *\fIscreen\fP\^; +.FN +.IP \fIscreen\fP 1i +Specifies the appropriate +.PN Screen +structure. +.LP +.eM +.IN "DefaultGCOfScreen" "" "@DEF@" +.IN "XDefaultGCOfScreen" "" "@DEF@" +Both return a default graphics context (GC) of the specified screen, +which has the same depth as the root window of the screen. +The GC must never be freed. +.LP +.sp +.sM +.FD 0 +DefaultVisualOfScreen\^(\^\fIscreen\fP\^) +.sp +Visual *XDefaultVisualOfScreen\^(\^\fIscreen\fP\^) +.br + Screen *\fIscreen\fP\^; +.FN +.IP \fIscreen\fP 1i +Specifies the appropriate +.PN Screen +structure. +.LP +.eM +.IN "DefaultVisualOfScreen" "" "@DEF@" +.IN "XDefaultVisualOfScreen" "" "@DEF@" +Both return the default visual of the specified screen. +For information on visual types, +see section 3.1. +.LP +.sp +.sM +.FD 0 +DoesBackingStore\^(\^\fIscreen\fP\^) +.sp +int XDoesBackingStore\^(\^\fIscreen\fP\^) +.br + Screen *\fIscreen\fP\^; +.FN +.IP \fIscreen\fP 1i +Specifies the appropriate +.PN Screen +structure. +.LP +.eM +.IN "DoesBackingStore" "" "@DEF@" +.IN "XDoesBackingStore" "" "@DEF@" +Both return a value indicating whether the screen supports backing +stores. +The value returned can be one of +.PN WhenMapped , +.PN NotUseful , +or +.PN Always +(see section 3.2.4). +.LP +.sp +.sM +.FD 0 +DoesSaveUnders\^(\^\fIscreen\fP\^) +.sp +Bool XDoesSaveUnders\^(\^\fIscreen\fP\^) +.br + Screen *\fIscreen\fP\^; +.FN +.IP \fIscreen\fP 1i +Specifies the appropriate +.PN Screen +structure. +.LP +.eM +.IN "DoesSaveUnders" "" "@DEF@" +.IN "XDoesSaveUnders" "" "@DEF@" +Both return a Boolean value indicating whether the +screen supports save unders. +If +.PN True , +the screen supports save unders. +If +.PN False , +the screen does not support save unders (see section 3.2.5). +.LP +.sp +.sM +.FD 0 +DisplayOfScreen\^(\^\fIscreen\fP\^) +.sp +Display *XDisplayOfScreen\^(\^\fIscreen\fP\^) +.br + Screen *\fIscreen\fP\^; +.FN +.IP \fIscreen\fP 1i +Specifies the appropriate +.PN Screen +structure. +.LP +.eM +.IN "DisplayOfScreen" "" "@DEF@" +.IN "XDisplayOfScreen" "" "@DEF@" +Both return the display of the specified screen. +.LP +.sp +.sM +.IN "XScreenNumberOfScreen" "" "@DEF@" +.FD 0 +int XScreenNumberOfScreen\^(\^\fIscreen\fP\^) +.br + Screen *\fIscreen\fP\^; +.FN +.IP \fIscreen\fP 1i +Specifies the appropriate +.PN Screen +structure. +.LP +.eM +The +.PN XScreenNumberOfScreen +function returns the screen index number of the specified screen. +.LP +.sp +.sM +.FD 0 +EventMaskOfScreen\^(\^\fIscreen\fP\^) +.sp +long XEventMaskOfScreen\^(\^\fIscreen\fP\^) +.br + Screen *\fIscreen\fP\^; +.FN +.IP \fIscreen\fP 1i +Specifies the appropriate +.PN Screen +structure. +.LP +.eM +.IN "EventMaskOfScreen" "" "@DEF@" +.IN "XEventMaskOfScreen" "" "@DEF@" +Both return the event mask of the root window for the specified screen +at connection setup time. +.LP +.sp +.sM +.FD 0 +WidthOfScreen\^(\^\fIscreen\fP\^) +.sp +int XWidthOfScreen\^(\^\fIscreen\fP\^) +.br + Screen *\fIscreen\fP\^; +.FN +.IP \fIscreen\fP 1i +Specifies the appropriate +.PN Screen +structure. +.LP +.eM +.IN "WidthOfScreen" "" "@DEF@" +.IN "XWidthOfScreen" "" "@DEF@" +Both return the width of the specified screen in pixels. +.LP +.sp +.sM +.FD 0 +HeightOfScreen\^(\^\fIscreen\fP\^) +.sp +int XHeightOfScreen\^(\^\fIscreen\fP\^) +.br + Screen *\fIscreen\fP\^; +.FN +.IP \fIscreen\fP 1i +Specifies the appropriate +.PN Screen +structure. +.LP +.eM +.IN "HeightOfScreen" "" "@DEF@" +.IN "XHeightOfScreen" "" "@DEF@" +Both return the height of the specified screen in pixels. +.LP +.sp +.sM +.FD 0 +WidthMMOfScreen\^(\^\fIscreen\fP\^) +.sp +int XWidthMMOfScreen\^(\^\fIscreen\fP\^) +.br + Screen *\fIscreen\fP\^; +.FN +.IP \fIscreen\fP 1i +Specifies the appropriate +.PN Screen +structure. +.LP +.eM +.IN "WidthMMOfScreen" "" "@DEF@" +.IN "XWidthMMOfScreen" "" "@DEF@" +Both return the width of the specified screen in millimeters. +.LP +.sp +.sM +.FD 0 +HeightMMOfScreen\^(\^\fIscreen\fP\^) +.sp +int XHeightMMOfScreen\^(\^\fIscreen\fP\^) +.br + Screen *\fIscreen\fP\^; +.FN +.IP \fIscreen\fP 1i +Specifies the appropriate +.PN Screen +structure. +.LP +.eM +.IN "HeightMMOfScreen" "" "@DEF@" +.IN "XHeightMMOfScreen" "" "@DEF@" +Both return the height of the specified screen in millimeters. +.LP +.sp +.sM +.FD 0 +MaxCmapsOfScreen\^(\^\fIscreen\fP\^) +.sp +int XMaxCmapsOfScreen\^(\^\fIscreen\fP\^) +.br + Screen *\fIscreen\fP\^; +.FN +.IP \fIscreen\fP 1i +Specifies the appropriate +.PN Screen +structure. +.LP +.eM +.IN "MaxCmapsOfScreen" "" "@DEF@" +.IN "XMaxCmapsOfScreen" "" "@DEF@" +Both return the maximum number of installed colormaps supported +by the specified screen (see section 9.3). +.LP +.sp +.sM +.FD 0 +MinCmapsOfScreen\^(\^\fIscreen\fP\^) +.sp +int XMinCmapsOfScreen\^(\^\fIscreen\fP\^) +.br + Screen *\fIscreen\fP\^; +.FN +.IP \fIscreen\fP 1i +Specifies the appropriate +.PN Screen +structure. +.LP +.eM +.IN "MinCmapsOfScreen" "" "@DEF@" +.IN "XMinCmapsOfScreen" "" "@DEF@" +Both return the minimum number of installed colormaps supported +by the specified screen (see section 9.3). +.LP +.sp +.sM +.FD 0 +PlanesOfScreen\^(\^\fIscreen\fP\^) +.sp +int XPlanesOfScreen\^(\^\fIscreen\fP\^) +.br + Screen *\fIscreen\fP\^; +.FN +.IP \fIscreen\fP 1i +Specifies the appropriate +.PN Screen +structure. +.LP +.eM +.IN "PlanesOfScreen" "" "@DEF@" +.IN "XPlanesOfScreen" "" "@DEF@" +Both return the depth of the root window. +.LP +.sp +.sM +.FD 0 +RootWindowOfScreen\^(\^\fIscreen\fP\^) +.sp +Window XRootWindowOfScreen\^(\^\fIscreen\fP\^) +.br + Screen *\fIscreen\fP\^; +.FN +.IP \fIscreen\fP 1i +Specifies the appropriate +.PN Screen +structure. +.LP +.eM +.IN "RootWindowOfScreen" "" "@DEF@" +.IN "XRootWindowOfScreen" "" "@DEF@" +Both return the root window of the specified screen. +.NH 2 +Generating a NoOperation Protocol Request +.XS +\*(SN Generating a NoOperation Protocol Request +.XE +.LP +To execute a +.PN NoOperation +protocol request, use +.PN XNoOp . +.IN "XNoOp" "" "@DEF@" +.sM +.FD 0 +XNoOp\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +The +.PN XNoOp +function sends a +.PN NoOperation +protocol request to the X server, +thereby exercising the connection. +.NH 2 +Freeing Client-Created Data +.XS +\*(SN Freeing Client-Created Data +.XE +.LP +To free in-memory data that was created by an Xlib function, use +.PN XFree . +.IN "XFree" "" "@DEF@" +.sM +.FD 0 +XFree\^(\^\fIdata\fP\^) +.br + void *\fIdata\fP\^; +.FN +.IP \fIdata\fP 1i +Specifies the data that is to be freed. +.LP +.eM +The +.PN XFree +function is a general-purpose Xlib routine that frees the specified data. +You must use it to free any objects that were allocated by Xlib, +unless an alternate function is explicitly specified for the object. +A NULL pointer cannot be passed to this function. +.NH 2 +Closing the Display +.XS +\*(SN Closing the Display +.XE +.LP +To close a display or disconnect from the X server, use +.PN XCloseDisplay . +.IN "XCloseDisplay" "" "@DEF@" +.LP +.sM +.FD 0 +XCloseDisplay\^(\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +The +.PN XCloseDisplay +function closes the connection to the X server for the display specified in the +.PN Display +structure and destroys all windows, resource IDs +.Pn ( Window , +.PN Font , +.PN Pixmap , +.PN Colormap , +.PN Cursor , +and +.PN GContext ), +or other resources that the client has created +on this display, unless the close-down mode of the resource has been changed +(see +.PN XSetCloseDownMode ). +Therefore, these windows, resource IDs, and other resources should never be +referenced again or an error will be generated. +Before exiting, you should call +.PN XCloseDisplay +explicitly so that any pending errors are reported as +.PN XCloseDisplay +performs a final +.PN XSync +operation. +.IN "Resource IDs" +.IN "XCloseDisplay" +.LP +.PN XCloseDisplay +can generate a +.PN BadGC +error. +.sp +.LP +Xlib provides a function to permit the resources owned by a client +to survive after the client's connection is closed. +To change a client's close-down mode, use +.PN XSetCloseDownMode . +.IN "XSetCloseDownMode" "" "@DEF@" +.sM +.FD 0 +XSetCloseDownMode\^(\^\fIdisplay\fP, \fIclose_mode\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIclose_mode\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIclose_mode\fP 1i +Specifies the client close-down mode. +You can pass +.PN DestroyAll , +.PN RetainPermanent , +or +.PN RetainTemporary . +.LP +.eM +The +.PN XSetCloseDownMode +defines what will happen to the client's resources at connection close. +A connection starts in +.PN DestroyAll +mode. +For information on what happens to the client's resources when the +close_mode argument is +.PN RetainPermanent +or +.PN RetainTemporary , +see section 2.6. +.LP +.PN XSetCloseDownMode +can generate a +.PN BadValue +error. +.NH 2 +Using X Server Connection Close Operations +.XS +\*(SN Using X Server Connection Close Operations +.XE +.LP +When the X server's connection to a client is closed +either by an explicit call to +.PN XCloseDisplay +or by a process that exits, the X server performs the following +automatic operations: +.IP \(bu 5 +It disowns all selections owned by the client +(see +.PN XSetSelectionOwner ). +.IP \(bu 5 +It performs an +.PN XUngrabPointer +and +.PN XUngrabKeyboard +if the client has actively grabbed the pointer +or the keyboard. +.IP \(bu 5 +It performs an +.PN XUngrabServer +if the client has grabbed the server. +.IP \(bu 5 +It releases all passive grabs made by the client. +.IP \(bu 5 +It marks all resources (including colormap entries) allocated +by the client either as permanent or temporary, +depending on whether the close-down mode is +.PN RetainPermanent +or +.PN RetainTemporary . +However, this does not prevent other client applications from explicitly +destroying the resources (see +.PN XSetCloseDownMode ). +.LP +When the close-down mode is +.PN DestroyAll , +the X server destroys all of a client's resources as follows: +.IP \(bu 5 +It examines each window in the client's save-set to determine if it is an inferior +(subwindow) of a window created by the client. +(The save-set is a list of other clients' windows +that are referred to as save-set windows.) +If so, the X server reparents the save-set window to the closest ancestor so +that the save-set window is not an inferior of a window created by the client. +The reparenting leaves unchanged the absolute coordinates (with respect to +the root window) of the upper-left outer corner of the save-set +window. +.IP \(bu 5 +It performs a +.PN MapWindow +request on the save-set window if the save-set window is unmapped. +The X server does this even if the save-set window was not an inferior of +a window created by the client. +.IP \(bu 5 +It destroys all windows created by the client. +.IP \(bu 5 +It performs the appropriate free request on each nonwindow resource created by +the client in the server (for example, +.PN Font , +.PN Pixmap , +.PN Cursor , +.PN Colormap , +and +.PN GContext ). +.IP \(bu 5 +It frees all colors and colormap entries allocated by a client application. +.LP +Additional processing occurs when the last connection to the X server closes. +An X server goes through a cycle of having no connections and having some +connections. +When the last connection to the X server closes as a result of a connection +closing with the close_mode of +.PN DestroyAll , +the X server does the following: +.IP \(bu 5 +It resets its state as if it had just been +started. +The X server begins by destroying all lingering resources from +clients that have terminated in +.PN RetainPermanent +or +.PN RetainTemporary +mode. +.IP \(bu 5 +It deletes all but the predefined atom identifiers. +.IP \(bu 5 +It deletes all properties on all root windows (see section 4.3). +.IP \(bu 5 +It resets all device maps and attributes +(for example, key click, bell volume, and acceleration) +as well as the access control list. +.IP \(bu 5 +It restores the standard root tiles and cursors. +.IP \(bu 5 +It restores the default font path. +.IP \(bu 5 +It restores the input focus to state +.PN PointerRoot . +.LP +However, the X server does not reset if you close a connection with a close-down +mode set to +.PN RetainPermanent +or +.PN RetainTemporary . +.NH 2 +Using Xlib with Threads +.XS +\*(SN Using Xlib with Threads +.XE +.LP +On systems that have threads, support may be provided to permit +multiple threads to use Xlib concurrently. +.LP +.sp +To initialize support for concurrent threads, use +.PN XInitThreads . +.IN "XInitThreads" "" "@DEF@" +.sM +.FD 0 +Status XInitThreads\^(\|); +.FN +.LP +.eM +The +.PN XInitThreads +function initializes Xlib support for concurrent threads. +This function must be the first Xlib function a +multi-threaded program calls, and it must complete +before any other Xlib call is made. +This function returns a nonzero status if initialization was +successful; otherwise, it returns zero. +On systems that do not support threads, this function always returns zero. +.LP +It is only necessary to call this function if multiple threads +might use Xlib concurrently. If all calls to Xlib functions +are protected by some other access mechanism (for example, +a mutual exclusion lock in a toolkit or through explicit client +programming), Xlib thread initialization is not required. +It is recommended that single-threaded programs not call this function. + +.LP +.sp +To lock a display across several Xlib calls, use +.PN XLockDisplay . +.IN "XLockDisplay" "" "@DEF@" +.sM +.FD 0 +void XLockDisplay\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +The +.PN XLockDisplay +function locks out all other threads from using the specified display. +Other threads attempting to use the display will block until +the display is unlocked by this thread. +Nested calls to +.PN XLockDisplay +work correctly; the display will not actually be unlocked until +.PN XUnlockDisplay +has been called the same number of times as +.PN XLockDisplay . +This function has no effect unless Xlib was successfully initialized +for threads using +.PN XInitThreads . +.LP +.sp +To unlock a display, use +.PN XUnlockDisplay . +.IN "XUnlockDisplay" "" "@DEF@" +.sM +.FD 0 +void XUnlockDisplay\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +The +.PN XUnlockDisplay +function allows other threads to use the specified display again. +Any threads that have blocked on the display are allowed to continue. +Nested locking works correctly; if +.PN XLockDisplay +has been called multiple times by a thread, then +.PN XUnlockDisplay +must be called an equal number of times before the display is +actually unlocked. +This function has no effect unless Xlib was successfully initialized +for threads using +.PN XInitThreads . +.NH 2 +Using Internal Connections +.XS +\*(SN Using Internal Connections +.XE +.LP +In addition to the connection to the X server, an Xlib implementation +may require connections to other kinds of servers (for example, to +input method servers as described in chapter 13). Toolkits and clients +that use multiple displays, or that use displays in combination with +other inputs, need to obtain these additional connections to correctly +block until input is available and need to process that input +when it is available. Simple clients that use a single display and +block for input in an Xlib event function do not need to use these +facilities. +.LP +To track internal connections for a display, use +.PN XAddConnectionWatch . +.LP +.IN "XWatchProc" "" "@DEF@" +.IN "XAddConnectionWatch" "" "@DEF@" +.sM +.FD 0 +typedef void (*XConnectionWatchProc)\^(\^\fIdisplay\fP, \fIclient_data\fP, \fIfd\fP, \fIopening\fP, \fIwatch_data\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XPointer \fIclient_data\fP\^; +.br + int \fIfd\fP\^; +.br + Bool \fIopening\fP\^; +.br + XPointer *\fIwatch_data\fP\^; +.sp +Status XAddConnectionWatch\^(\^\fIdisplay\fP, \fIprocedure\fP\^, \fIclient_data\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XWatchProc \fIprocedure\fP\^; +.br + XPointer \fIclient_data\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIprocedure\fP 1i +Specifies the procedure to be called. +.IP \fIclient_data\fP 1i +Specifies the additional client data. +.LP +.eM +The +.PN XAddConnectionWatch +function registers a procedure to be called each time Xlib opens or closes an +internal connection for the specified display. The procedure is passed the +display, the specified client_data, the file descriptor for the connection, +a Boolean indicating whether the connection is being opened or closed, and a +pointer to a location for private watch data. If opening is +.PN True , +the procedure can store a pointer to private data in the location pointed +to by watch_data; +when the procedure is later called for this same connection and opening is +.PN False , +the location pointed to by watch_data will hold this same private data pointer. +.LP +This function can be called at any time after a display is opened. +If internal connections already exist, the registered procedure will +immediately be called for each of them, before +.PN XAddConnectionWatch +returns. +.PN XAddConnectionWatch +returns a nonzero status if the procedure is successfully registered; +otherwise, it returns zero. +.LP +The registered procedure should not call any Xlib functions. +If the procedure directly or indirectly causes the state of internal +connections or watch procedures to change, the result is not defined. +If Xlib has been initialized for threads, the procedure is called with +the display locked and the result of a call by the procedure to any +Xlib function that locks the display is not defined unless the executing +thread has externally locked the display using +.PN XLockDisplay . +.LP +.sp +To stop tracking internal connections for a display, use +.PN XRemoveConnectionWatch . +.IN "XRemoveConnectionWatch" "" "@DEF@" +.sM +.FD 0 +Status XRemoveConnectionWatch\^(\^\fIdisplay\fP, \fIprocedure\fP\^, \fIclient_data\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XWatchProc \fIprocedure\fP\^; +.br + XPointer \fIclient_data\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIprocedure\fP 1i +Specifies the procedure to be called. +.IP \fIclient_data\fP 1i +Specifies the additional client data. +.LP +.eM +The +.PN XRemoveConnectionWatch +function removes a previously registered connection watch procedure. +The client_data must match the client_data used when the procedure +was initially registered. + +.LP +.sp +To process input on an internal connection, use +.PN XProcessInternalConnection . +.IN "XProcessInternalConnection" "" "@DEF@" +.sM +.FD 0 +void XProcessInternalConnection\^(\^\fIdisplay\fP, \fIfd\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIfd\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIfd\fP 1i +Specifies the file descriptor. +.LP +.eM +The +.PN XProcessInternalConnection +function processes input available on an internal connection. +This function should be called for an internal connection only +after an operating system facility (for example, +.PN select +or +.PN poll ) +has indicated that input is available; otherwise, +the effect is not defined. +.LP +.sp +To obtain all of the current internal connections for a display, use +.PN XInternalConnectionNumbers . +.IN "XInternalConnectionNumbers" "" "@DEF@" +.sM +.FD 0 +Status XInternalConnectionNumbers\^(\^\fIdisplay\fP, \fIfd_return\fP\^, \fIcount_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int **\fIfd_return\fP\^; +.br + int *\fIcount_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIfd_return\fP 1i +Returns the file descriptors. +.ds Cn file descriptors +.IP \fIcount_return\fP 1i +Returns the number of \*(Cn. +.LP +.eM +The +.PN XInternalConnectionNumbers +function returns a list of the file descriptors for all internal +connections currently open for the specified display. +When the allocated list is no longer needed, +free it by using +.PN XFree . +This functions returns a nonzero status if the list is successfully allocated; +otherwise, it returns zero. +.LP +.bp diff --git a/libX11/specs/libX11/CH03 b/libX11/specs/libX11/CH03 new file mode 100644 index 000000000..f7eb2d4c0 --- /dev/null +++ b/libX11/specs/libX11/CH03 @@ -0,0 +1,3121 @@ +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be included +.\" in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR +.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +.\" OTHER DEALINGS IN THE SOFTWARE. +.\" +.\" Except as contained in this notice, the name of the X Consortium shall +.\" not be used in advertising or otherwise to promote the sale, use or +.\" other dealings in this Software without prior written authorization +.\" from the X Consortium. +.\" +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by +.\" Digital Equipment Corporation +.\" +.\" Portions Copyright \(co 1990, 1991 by +.\" Tektronix, Inc. +.\" +.\" Permission to use, copy, modify and distribute this documentation for +.\" any purpose and without fee is hereby granted, provided that the above +.\" copyright notice appears in all copies and that both that copyright notice +.\" and this permission notice appear in all copies, and that the names of +.\" Digital and Tektronix not be used in in advertising or publicity pertaining +.\" to this documentation without specific, written prior permission. +.\" Digital and Tektronix makes no representations about the suitability +.\" of this documentation for any purpose. +.\" It is provided ``as is'' without express or implied warranty. +.\" +\& +.sp 1 +.ce 3 +\s+1\fBChapter 3\fP\s-1 + +\s+1\fBWindow Functions\fP\s-1 +.sp 2 +.nr H1 3 +.nr H2 0 +.nr H3 0 +.nr H4 0 +.nr H5 0 +.na +.LP +.XS +Chapter 3: Window Functions +.XE +In the X Window System, +a window is a rectangular area on the screen that lets you +view graphic output. +Client applications +can display overlapping and nested windows on one or more +screens that are driven by X servers on one or more machines. +Clients who want to create windows must first +connect their program to the X server +by calling +.PN XOpenDisplay . +This chapter begins with a discussion of +visual types and window attributes. +The chapter continues with a discussion of the Xlib functions you can use to: +.IP \(bu 5 +Create windows +.IP \(bu 5 +Destroy windows +.IP \(bu 5 +Map windows +.IP \(bu 5 +Unmap windows +.IP \(bu 5 +Configure windows +.IP \(bu 5 +Change window stacking order +.IP \(bu 5 +Change window attributes +.LP +This chapter also identifies the window actions that may generate events. +.LP +Note that it is vital that your application conform to the +established conventions for communicating with window managers +for it to work well with the various window managers in use (see section 14.1). +Toolkits generally adhere to these conventions for you, +relieving you of the burden. +Toolkits also often supersede many functions in this chapter +with versions of their own. +For more information, +refer to the documentation for the toolkit that you are using. +.NH 2 +Visual Types +.XS +\*(SN Visual Types +.XE +.LP +.IN "Visual Type" "" "@DEF@" +On some display hardware, +it may be possible to deal with color resources in more than one way. +For example, you may be able to deal with a screen of either 12-bit depth +with arbitrary mapping of pixel to color (pseudo-color) or 24-bit depth +with 8 bits of the pixel dedicated to each of red, green, and blue. +These different ways of dealing with the visual aspects of the screen +are called visuals. +For each screen of the display, there may be a list of valid visual types +supported at different depths of the screen. +Because default windows and visual types are defined for each screen, +most simple applications need not deal with this complexity. +Xlib provides macros and functions that return the default root window, +the default depth of the default root window, and the default visual type +(see sections 2.2.1 and 16.7). +.LP +Xlib uses an opaque +.PN Visual +.IN "Visual" "" "@DEF@" +structure that contains information about the possible color mapping. +The visual utility functions (see section 16.7) use an +.PN XVisualInfo +structure to return this information to an application. +The members of this structure pertinent to this discussion are class, red_mask, +green_mask, blue_mask, bits_per_rgb, and colormap_size. +The class member specifies one of the possible visual classes of the screen +and can be +.IN "Visual Classes" "StaticGray" +.IN "Visual Classes" "StaticColor" +.IN "Visual Classes" "TrueColor" +.IN "Visual Classes" "StaticColor" +.IN "Visual Classes" "GrayScale" +.IN "Visual Classes" "PseudoColor" +.PN StaticGray , +.PN StaticColor , +.PN TrueColor , +.PN GrayScale , +.PN PseudoColor , +or +.PN DirectColor . +.LP +The following concepts may serve to make the explanation of +visual types clearer. +The screen can be color or grayscale, +can have a colormap that is writable or read-only, +and can also have a colormap whose indices are decomposed into separate +RGB pieces, provided one is not on a grayscale screen. +This leads to the following diagram: +.LP +.DS +.TS +center; + c c s c s + c c c c c +| c | c | c | c | c |. + Color Gray-scale + R/O R/W R/O R/W +_ +Undecomposed Static Pseudo Static Gray +Colormap Color Color Gray Scale +_ +.T& +| c | c | c |. +Decomposed True Direct +Colormap Color Color +_ _ _ +.TE +.DE +.LP +Conceptually, +as each pixel is read out of video memory for display on the screen, +it goes through a look-up stage by indexing into a colormap. +Colormaps can be manipulated arbitrarily on some hardware, +in limited ways on other hardware, and not at all on other hardware. +The visual types affect the colormap and +the RGB values in the following ways: +.LP +.IP \(bu 5 +For +.PN PseudoColor , +a pixel value indexes a colormap to produce +independent RGB values, and the RGB values can be changed dynamically. +.IP \(bu 5 +.PN GrayScale +is treated the same way as +.PN PseudoColor +except that the primary that drives the screen is undefined. +Thus, the client should always store the +same value for red, green, and blue in the colormaps. +.IP \(bu 5 +For +.PN DirectColor , +a pixel value is decomposed into separate RGB subfields, and each +subfield separately indexes the colormap for the corresponding value. +The RGB values can be changed dynamically. +.IP \(bu 5 +.PN TrueColor +is treated the same way as +.PN DirectColor +except that the colormap has predefined, read-only RGB values. +These RGB values are server dependent but provide linear or near-linear +ramps in each primary. +.IP \(bu 5 +.PN StaticColor +is treated the same way as +.PN PseudoColor +except that the colormap has predefined, +read-only, server-dependent RGB values. +.IP \(bu 5 +.PN StaticGray +is treated the same way as +.PN StaticColor +except that the RGB values are equal for any single pixel +value, thus resulting in shades of gray. +.PN StaticGray +with a two-entry +colormap can be thought of as monochrome. +.LP +The red_mask, green_mask, and blue_mask members are only defined for +.PN DirectColor +and +.PN TrueColor . +Each has one contiguous set of bits with no +intersections. +The bits_per_rgb member specifies the log base 2 of the +number of distinct color values (individually) of red, green, and blue. +Actual RGB values are unsigned 16-bit numbers. +The colormap_size member defines the number of available colormap entries +in a newly created colormap. +For +.PN DirectColor +and +.PN TrueColor , +this is the size of an individual pixel subfield. +.sp +.LP +To obtain the visual ID from a +.PN Visual , +use +.PN XVisualIDFromVisual . +.IN "XVisualIDFromVisual" "" "@DEF@" +.sM +.FD 0 +VisualID XVisualIDFromVisual\^(\^\fIvisual\fP\^) +.br + Visual *\^\fIvisual\fP\^; +.FN +.IP \fIvisual\fP 1i +Specifies the visual type. +.LP +.eM +The +.PN XVisualIDFromVisual +function returns the visual ID for the specified visual type. +.NH 2 +Window Attributes +.XS +\*(SN Window Attributes +.XE +.LP +.IN "Window" +.IN "Window" "attributes" +All +.PN InputOutput +windows have a border width of zero or more pixels, an optional background, +an event suppression mask (which suppresses propagation of events from +children), and a property list (see section 4.3). +The window border and background can be a solid color or a pattern, called +a tile. +All windows except the root have a parent and are clipped by their parent. +If a window is stacked on top of another window, it obscures that other +window for the purpose of input. +If a window has a background (almost all do), it obscures the other +window for purposes of output. +Attempts to output to the obscured area do nothing, +and no input events (for example, pointer motion) are generated for the +obscured area. +.LP +Windows also have associated property lists (see section 4.3). +.LP +Both +.PN InputOutput +and +.PN InputOnly +windows have the following common attributes, +which are the only attributes of an +.PN InputOnly +window: +.IP \(bu 5 +win-gravity +.IP \(bu 5 +event-mask +.IP \(bu 5 +do-not-propagate-mask +.IP \(bu 5 +override-redirect +.IP \(bu 5 +cursor +.LP +If you specify any other attributes for an +.PN InputOnly +window, +a +.PN BadMatch +error results. +.LP +.PN InputOnly +windows are used for controlling input events in situations where +.PN InputOutput +windows are unnecessary. +.PN InputOnly +windows are invisible; can only be used to control such things as +cursors, input event generation, and grabbing; +and cannot be used in any graphics requests. +Note that +.PN InputOnly +windows cannot have +.PN InputOutput +windows as inferiors. +.LP +Windows have borders of a programmable width and pattern +as well as a background pattern or tile. +.IN "Tile" "pixmaps" +Pixel values can be used for solid colors. +.IN "Resource IDs" "freeing" +.IN "Freeing" "resources" +The background and border pixmaps can be destroyed immediately after +creating the window if no further explicit references to them +are to be made. +.IN "Tile" "mode" +The pattern can either be relative to the parent +or absolute. +If +.PN ParentRelative , +the parent's background is used. +.LP +When windows are first created, +they are not visible (not mapped) on the screen. +Any output to a window that is not visible on the screen +and that does not have backing store will be discarded. +.IN "Window" "mapping" +An application may wish to create a window long before it is +mapped to the screen. +When a window is eventually mapped to the screen +(using +.PN XMapWindow ), +.IN "XMapWindow" +the X server generates an +.PN Expose +event for the window if backing store has not been maintained. +.LP +A window manager can override your choice of size, +border width, and position for a top-level window. +Your program must be prepared to use the actual size and position +of the top window. +It is not acceptable for a client application to resize itself +unless in direct response to a human command to do so. +Instead, either your program should use the space given to it, +or if the space is too small for any useful work, your program +might ask the user to resize the window. +The border of your top-level window is considered fair game +for window managers. +.LP +To set an attribute of a window, +set the appropriate member of the +.PN XSetWindowAttributes +structure and OR in the corresponding value bitmask in your subsequent calls to +.PN XCreateWindow +and +.PN XChangeWindowAttributes , +or use one of the other convenience functions that set the appropriate +attribute. +The symbols for the value mask bits and the +.PN XSetWindowAttributes +structure are: +.sM +.LP +/* Window attribute value mask bits */ +.TS +lw(.5i) lw(2.5i) lw(.8i). +T{ +#define +T} T{ +.PN CWBackPixmap +T} T{ +(1L<<0) +T} +T{ +#define +T} T{ +.PN CWBackPixel +T} T{ +(1L<<1) +T} +T{ +#define +T} T{ +.PN CWBorderPixmap +T} T{ +(1L<<2) +T} +T{ +#define +T} T{ +.PN CWBorderPixel +T} T{ +(1L<<3) +T} +T{ +#define +T} T{ +.PN CWBitGravity +T} T{ +(1L<<4) +T} +T{ +#define +T} T{ +.PN CWWinGravity +T} T{ +(1L<<5) +T} +T{ +#define +T} T{ +.PN CWBackingStore +T} T{ +(1L<<6) +T} +T{ +#define +T} T{ +.PN CWBackingPlanes +T} T{ +(1L<<7) +T} +T{ +#define +T} T{ +.PN CWBackingPixel +T} T{ +(1L<<8) +T} +T{ +#define +T} T{ +.PN CWOverrideRedirect +T} T{ +(1L<<9) +T} +T{ +#define +T} T{ +.PN CWSaveUnder +T} T{ +(1L<<10) +T} +T{ +#define +T} T{ +.PN CWEventMask +T} T{ +(1L<<11) +T} +T{ +#define +T} T{ +.PN CWDontPropagate +T} T{ +(1L<<12) +T} +T{ +#define +T} T{ +.PN CWColormap +T} T{ +(1L<<13) +T} +T{ +#define +T} T{ +.PN CWCursor +T} T{ +(1L<<14) +T} +.TE +.IN "XSetWindowAttributes" "" "@DEF@" +.Ds 0 +.TA .5i 3i +.ta .5i 3i +/* Values */ + +typedef struct { + Pixmap background_pixmap; /* background, None, or ParentRelative */ + unsigned long background_pixel; /* background pixel */ + Pixmap border_pixmap; /* border of the window or CopyFromParent */ + unsigned long border_pixel; /* border pixel value */ + int bit_gravity; /* one of bit gravity values */ + int win_gravity; /* one of the window gravity values */ + int backing_store; /* NotUseful, WhenMapped, Always */ + unsigned long backing_planes; /* planes to be preserved if possible */ + unsigned long backing_pixel; /* value to use in restoring planes */ + Bool save_under; /* should bits under be saved? (popups) */ + long event_mask; /* set of events that should be saved */ + long do_not_propagate_mask; /* set of events that should not propagate */ + Bool override_redirect; /* boolean value for override_redirect */ + Colormap colormap; /* color map to be associated with window */ + Cursor cursor; /* cursor to be displayed (or None) */ +} XSetWindowAttributes; +.De +.LP +.eM +The following lists the defaults for each window attribute and indicates +whether the attribute is applicable to +.PN InputOutput +and +.PN InputOnly +windows: +.TS H +l l l l +lw(1.4i) lw(1.3i) cw(.9i) cw(.8i). +_ +.sp 6p +T{ +.B Attribute +T} T{ +.B Default +T} T{ +.PN InputOutput +T} T{ +.PN InputOnly +T} +.sp 6p +_ +.sp 6p +.TH +.R +T{ +background-pixmap +T} T{ +.PN None +T} T{ +Yes +T} T{ +No +T} +background-pixel Undefined Yes No +T{ +border-pixmap +T} T{ +.PN CopyFromParent +T} T{ +Yes +T} T{ +No +T} +border-pixel Undefined Yes No +T{ +bit-gravity +T} T{ +.PN ForgetGravity +T} T{ +Yes +T} T{ +No +T} +T{ +win-gravity +T} T{ +.PN NorthWestGravity +T} T{ +Yes +T} T{ +Yes +T} +T{ +backing-store +T} T{ +.PN NotUseful +T} T{ +Yes +T} T{ +No +T} +backing-planes All ones Yes No +backing-pixel zero Yes No +T{ +save-under +T} T{ +.PN False +T} T{ +Yes +T} T{ +No +T} +event-mask empty set Yes Yes +do-not-propagate-mask empty set Yes Yes +T{ +override-redirect +T} T{ +.PN False +T} T{ +Yes +T} T{ +Yes +T} +T{ +colormap +T} T{ +.PN CopyFromParent +T} T{ +Yes +T} T{ +No +T} +T{ +cursor +T} T{ +.PN None +T} T{ +Yes +T} T{ +Yes +T} +_ +.TE +.NH 3 +Background Attribute +.XS +\*(SN Background Attribute +.XE +.LP +Only +.PN InputOutput +windows can have a background. +You can set the background of an +.PN InputOutput +window by using a pixel or a pixmap. +.LP +The background-pixmap attribute of a window specifies the pixmap to be used for +a window's background. +This pixmap can be of any size, although some sizes may be faster than others. +The background-pixel attribute of a window specifies a pixel value used to paint +a window's background in a single color. +.LP +You can set the background-pixmap to a pixmap, +.PN None +(default), or +.PN ParentRelative . +You can set the background-pixel of a window to any pixel value (no default). +If you specify a background-pixel, +it overrides either the default background-pixmap +or any value you may have set in the background-pixmap. +A pixmap of an undefined size that is filled with the background-pixel is used +for the background. +Range checking is not performed on the background pixel; +it simply is truncated to the appropriate number of bits. +.LP +If you set the background-pixmap, +it overrides the default. +The background-pixmap and the window must have the same depth, +or a +.PN BadMatch +error results. +If you set background-pixmap to +.PN None , +the window has no defined background. +If you set the background-pixmap to +.PN ParentRelative : +.IP \(bu 5 +The parent window's background-pixmap is used. +The child window, however, must have the same depth as +its parent, +or a +.PN BadMatch +error results. +.IP \(bu 5 +If the parent window has a background-pixmap of +.PN None , +the window also has a background-pixmap of +.PN None . +.IP \(bu 5 +A copy of the parent window's background-pixmap is not made. +The parent's background-pixmap is examined each time the child window's +background-pixmap is required. +.IP \(bu 5 +The background tile origin always aligns with the parent window's +background tile origin. +If the background-pixmap is not +.PN ParentRelative , +the background tile origin is the child window's origin. +.LP +Setting a new background, whether by setting background-pixmap or +background-pixel, overrides any previous background. +The background-pixmap can be freed immediately if no further explicit reference +is made to it (the X server will keep a copy to use when needed). +If you later draw into the pixmap used for the background, +what happens is undefined because the +X implementation is free to make a copy of the pixmap or +to use the same pixmap. +.LP +When no valid contents are available for regions of a window +and either the regions are visible or the server is maintaining backing store, +the server automatically tiles the regions with the window's background +unless the window has a background of +.PN None . +If the background is +.PN None , +the previous screen contents from other windows of the same depth as the window +are simply left in place as long as the contents come from the parent of the +window or an inferior of the parent. +Otherwise, the initial contents of the exposed regions are undefined. +.PN Expose +events are then generated for the regions, even if the background-pixmap +is +.PN None +(see section 10.9). +.NH 3 +Border Attribute +.XS +\*(SN Border Attribute +.XE +.LP +Only +.PN InputOutput +windows can have a border. +You can set the border of an +.PN InputOutput +window by using a pixel or a pixmap. +.LP +The border-pixmap attribute of a window specifies the pixmap to be used +for a window's border. +The border-pixel attribute of a window specifies a pixmap of undefined size +filled with that pixel be used for a window's border. +Range checking is not performed on the background pixel; +it simply is truncated to the appropriate number of bits. +The border tile origin is always the same as the background tile origin. +.LP +You can also set the border-pixmap to a pixmap of any size (some may be faster +than others) or to +.PN CopyFromParent +(default). +You can set the border-pixel to any pixel value (no default). +.LP +If you set a border-pixmap, +it overrides the default. +The border-pixmap and the window must have the same depth, +or a +.PN BadMatch +error results. +If you set the border-pixmap to +.PN CopyFromParent , +the parent window's border-pixmap is copied. +Subsequent changes to the parent window's border attribute do not affect +the child window. +However, the child window must have the same depth as the parent window, +or a +.PN BadMatch +error results. +.LP +The border-pixmap can be freed immediately if no further explicit reference +is made to it. +If you later draw into the pixmap used for the border, +what happens is undefined because the +X implementation is free either to make a copy of the pixmap or +to use the same pixmap. +If you specify a border-pixel, +it overrides either the default border-pixmap +or any value you may have set in the border-pixmap. +All pixels in the window's border will be set to the border-pixel. +Setting a new border, whether by setting border-pixel or by setting +border-pixmap, overrides any previous border. +.LP +Output to a window is always clipped to the inside of the window. +Therefore, graphics operations never affect the window border. +.NH 3 +Gravity Attributes +.XS +\*(SN Gravity Attributes +.XE +.LP +The bit gravity of a window defines which region of the window should be +retained when an +.PN InputOutput +window is resized. +The default value for the bit-gravity attribute is +.PN ForgetGravity . +The window gravity of a window allows you to define how the +.PN InputOutput +or +.PN InputOnly +window should be repositioned if its parent is resized. +The default value for the win-gravity attribute is +.PN NorthWestGravity . +.LP +If the inside width or height of a window is not changed +and if the window is moved or its border is changed, +then the contents of the window are not lost but move with the window. +Changing the inside width or height of the window causes its contents to be +moved or lost (depending on the bit-gravity of the window) and causes +children to be reconfigured (depending on their win-gravity). +For a +change of width and height, the (x, y) pairs are defined: +.LP +.TS +l l +l l. +_ +.sp 6p +.B +Gravity Direction Coordinates +.sp 6p +_ +.sp 6p +.R +T{ +.PN NorthWestGravity +T} T{ +(0, 0) +T} +T{ +.PN NorthGravity +T} T{ +(Width/2, 0) +T} +T{ +.PN NorthEastGravity +T} T{ +(Width, 0) +T} +T{ +.PN WestGravity +T} T{ +(0, Height/2) +T} +T{ +.PN CenterGravity +T} T{ +(Width/2, Height/2) +T} +T{ +.PN EastGravity +T} T{ +(Width, Height/2) +T} +T{ +.PN SouthWestGravity +T} T{ +(0, Height) +T} +T{ +.PN SouthGravity +T} T{ +(Width/2, Height) +T} +T{ +.PN SouthEastGravity +T} T{ +(Width, Height) +T} +.sp 6p +_ +.TE +.LP +When a window with one of these bit-gravity values is resized, +the corresponding pair +defines the change in position of each pixel in the window. +When a window with one of these win-gravities has its parent window resized, +the corresponding pair defines the change in position of the window +within the parent. +When a window is so repositioned, a +.PN GravityNotify +event is generated (see section 10.10.5). +.LP +A bit-gravity of +.PN StaticGravity +indicates that the contents or origin should not move relative to the +origin of the root window. +If the change in size of the window is coupled with a change in position (x, y), +then for bit-gravity the change in position of each pixel is (\-x, \-y), and for +win-gravity the change in position of a child when its parent is so resized is +(\-x, \-y). +Note that +.PN StaticGravity +still only takes effect when the width or height of the window is changed, +not when the window is moved. +.LP +A bit-gravity of +.PN ForgetGravity +indicates that the window's contents are always discarded after a size change, +even if a backing store or save under has been requested. +The window is tiled with its background +and zero or more +.PN Expose +events are generated. +If no background is defined, the existing screen contents are not +altered. +Some X servers may also ignore the specified bit-gravity and +always generate +.PN Expose +events. +.LP +The contents and borders of inferiors are not affected by their parent's +bit-gravity. +A server is permitted to ignore the specified bit-gravity and use +.PN Forget +instead. +.LP +A win-gravity of +.PN UnmapGravity +is like +.PN NorthWestGravity +(the window is not moved), +except the child is also +unmapped when the parent is resized, +and an +.PN UnmapNotify +event is +generated. +.NH 3 +Backing Store Attribute +.XS +\*(SN Backing Store Attribute +.XE +.LP +Some implementations of the X server may choose to maintain the contents of +.PN InputOutput +windows. +If the X server maintains the contents of a window, +the off-screen saved pixels +are known as backing store. +The backing store advises the X server on what to do +with the contents of a window. +The backing-store attribute can be set to +.PN NotUseful +(default), +.PN WhenMapped , +or +.PN Always . +.LP +A backing-store attribute of +.PN NotUseful +advises the X server that +maintaining contents is unnecessary, +although some X implementations may +still choose to maintain contents and, therefore, not generate +.PN Expose +events. +A backing-store attribute of +.PN WhenMapped +advises the X server that maintaining contents of +obscured regions when the window is mapped would be beneficial. +In this case, +the server may generate an +.PN Expose +event when the window is created. +A backing-store attribute of +.PN Always +advises the X server that maintaining contents even when +the window is unmapped would be beneficial. +Even if the window is larger than its parent, +this is a request to the X server to maintain complete contents, +not just the region within the parent window boundaries. +While the X server maintains the window's contents, +.PN Expose +events normally are not generated, +but the X server may stop maintaining +contents at any time. +.LP +When the contents of obscured regions of a window are being maintained, +regions obscured by noninferior windows are included in the destination +of graphics requests (and source, when the window is the source). +However, regions obscured by inferior windows are not included. +.NH 3 +Save Under Flag +.XS +\*(SN Save Under Flag +.XE +.IN "Save Unders" +.LP +Some server implementations may preserve contents of +.PN InputOutput +windows under other +.PN InputOutput +windows. +This is not the same as preserving the contents of a window for you. +You may get better visual +appeal if transient windows (for example, pop-up menus) request that the system +preserve the screen contents under them, +so the temporarily obscured applications do not have to repaint. +.LP +You can set the save-under flag to +.PN True +or +.PN False +(default). +If save-under is +.PN True , +the X server is advised that, when this window is mapped, +saving the contents of windows it obscures would be beneficial. +.NH 3 +Backing Planes and Backing Pixel Attributes +.XS +\*(SN Backing Planes and Backing Pixel Attributes +.XE +.LP +You can set backing planes to indicate (with bits set to 1) +which bit planes of an +.PN InputOutput +window hold dynamic data that must be preserved in backing store +and during save unders. +The default value for the backing-planes attribute is all bits set to 1. +You can set backing pixel to specify what bits to use in planes not +covered by backing planes. +The default value for the backing-pixel attribute is all bits set to 0. +The X server is free to save only the specified bit planes in the backing store +or the save under and is free to regenerate the remaining planes with +the specified pixel value. +Any extraneous bits in these values (that is, those bits beyond +the specified depth of the window) may be simply ignored. +If you request backing store or save unders, +you should use these members to minimize the amount of off-screen memory +required to store your window. +.NH 3 +Event Mask and Do Not Propagate Mask Attributes +.XS +\*(SN Event Mask and Do Not Propagate Mask Attributes +.XE +.LP +The event mask defines which events the client is interested in for this +.PN InputOutput +or +.PN InputOnly +window (or, for some event types, inferiors of this window). +The event mask is the bitwise inclusive OR of zero or more of the +valid event mask bits. +You can specify that no maskable events are reported by setting +.PN NoEventMask +(default). +.LP +The do-not-propagate-mask attribute +defines which events should not be propagated to +ancestor windows when no client has the event type selected in this +.PN InputOutput +or +.PN InputOnly +window. +The do-not-propagate-mask is the bitwise inclusive OR of zero or more +of the following masks: +.PN KeyPress , +.PN KeyRelease , +.PN ButtonPress , +.PN ButtonRelease , +.PN PointerMotion , +.PN Button1Motion , +.PN Button2Motion , +.PN Button3Motion , +.PN Button4Motion , +.PN Button5Motion , +and +.PN ButtonMotion . +You can specify that all events are propagated by setting +.PN NoEventMask +(default). +.NH 3 +Override Redirect Flag +.XS +\*(SN Override Redirect Flag +.XE +.LP +To control window placement or to add decoration, +a window manager often needs to intercept (redirect) any map or configure +request. +Pop-up windows, however, often need to be mapped without a window manager +getting in the way. +To control whether an +.PN InputOutput +or +.PN InputOnly +window is to ignore these structure control facilities, +use the override-redirect flag. +.LP +The override-redirect flag specifies whether map and configure requests +on this window should override a +.PN SubstructureRedirectMask +on the parent. +You can set the override-redirect flag to +.PN True +or +.PN False +(default). +Window managers use this information to avoid tampering with pop-up windows +(see also chapter 14). +.NH 3 +Colormap Attribute +.XS +\*(SN Colormap Attribute +.XE +.LP +The colormap attribute specifies which colormap best reflects the true +colors of the +.PN InputOutput +window. +The colormap must have the same visual type as the window, +or a +.PN BadMatch +error results. +X servers capable of supporting multiple +hardware colormaps can use this information, +and window managers can use it for calls to +.PN XInstallColormap . +You can set the colormap attribute to a colormap or to +.PN CopyFromParent +(default). +.LP +If you set the colormap to +.PN CopyFromParent , +the parent window's colormap is copied and used by its child. +However, the child window must have the same visual type as the parent, +or a +.PN BadMatch +error results. +The parent window must not have a colormap of +.PN None , +or a +.PN BadMatch +error results. +The colormap is copied by sharing the colormap object between the child +and parent, not by making a complete copy of the colormap contents. +Subsequent changes to the parent window's colormap attribute do +not affect the child window. +.NH 3 +Cursor Attribute +.XS +\*(SN Cursor Attribute +.XE +.LP +The cursor attribute specifies which cursor is to be used when the pointer is +in the +.PN InputOutput +or +.PN InputOnly +window. +You can set the cursor to a cursor or +.PN None +(default). +.LP +If you set the cursor to +.PN None , +the parent's cursor is used when the +pointer is in the +.PN InputOutput +or +.PN InputOnly +window, and any change in the parent's cursor will cause an +immediate change in the displayed cursor. +By calling +.PN XFreeCursor , +the cursor can be freed immediately as long as no further explicit reference +to it is made. +.NH 2 +Creating Windows +.XS +\*(SN Creating Windows +.XE +.LP +Xlib provides basic ways for creating windows, +and toolkits often supply higher-level functions specifically for +creating and placing top-level windows, +which are discussed in the appropriate toolkit documentation. +If you do not use a toolkit, however, +you must provide some standard information or hints for the window +manager by using the Xlib inter-client communication functions +(see chapter 14). +.LP +If you use Xlib to create your own top-level windows +(direct children of the root window), +you must observe the following rules so that all applications interact +reasonably across the different styles of window management: +.IP \(bu 5 +You must never fight with the window manager for the size or +placement of your top-level window. +.IP \(bu 5 +You must be able to deal with whatever size window you get, +even if this means that your application just prints a message +like ``Please make me bigger'' in its window. +.IP \(bu 5 +You should only attempt to resize or move top-level windows in +direct response to a user request. +If a request to change the size of a top-level window fails, +you must be prepared to live with what you get. +You are free to resize or move the children of top-level +windows as necessary. +(Toolkits often have facilities for automatic relayout.) +.IP \(bu 5 +If you do not use a toolkit that automatically sets standard window properties, +you should set these properties for top-level windows before mapping them. +.LP +For further information, +see chapter 14 and the \fIInter-Client Communication Conventions Manual\fP. +.LP +.PN XCreateWindow +is the more general function that allows you to set specific window attributes +when you create a window. +.PN XCreateSimpleWindow +creates a window that inherits its attributes from its parent window. +.LP +.IN "Window" "InputOnly" +The X server acts as if +.PN InputOnly +windows do not exist for +the purposes of graphics requests, exposure processing, and +.PN VisibilityNotify +events. +An +.PN InputOnly +window cannot be used as a +drawable (that is, as a source or destination for graphics requests). +.PN InputOnly +and +.PN InputOutput +windows act identically in other respects (properties, +grabs, input control, and so on). +Extension packages can define other classes of windows. +.LP +To create an unmapped window and set its window attributes, use +.PN XCreateWindow . +.IN "XCreateWindow" "" "@DEF@" +.sM +.FD 0 +Window XCreateWindow\^(\^\fIdisplay\fP, \fIparent\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIborder_width\fP\^, \fIdepth\fP\^, +.br + \fIclass\fP\^, \fIvisual\fP\^, \fIvaluemask\fP\^, \fIattributes\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIparent\fP\^; +.br + int \fIx\fP\^, \fIy\fP\^; +.br + unsigned int \fIwidth\fP\^, \fIheight\fP\^; +.br + unsigned int \fIborder_width\fP\^; +.br + int \fIdepth\fP\^; +.br + unsigned int \fIclass\fP\^; +.br + Visual *\fIvisual\fP\^; +.br + unsigned long \fIvaluemask\fP\^; +.br + XSetWindowAttributes *\fIattributes\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIparent\fP 1i +Specifies the parent window. +.ds Xy , which are the top-left outside corner of the created window's \ +borders and are relative to the inside of the parent window's borders +.IP \fIx\fP 1i +.br +.ns +.IP \fIy\fP 1i +Specify the x and y coordinates\*(Xy. +.ds Wh , which are the created window's inside dimensions \ +and do not include the created window's borders +.IP \fIwidth\fP 1i +.br +.ns +.IP \fIheight\fP 1i +Specify the width and height\*(Wh. +The dimensions must be nonzero, +or a +.PN BadValue +error results. +.IP \fIborder_width\fP 1i +Specifies the width of the created window's border in pixels. +.IP \fIdepth\fP 1i +Specifies the window's depth. +A depth of +.PN CopyFromParent +means the depth is taken from the parent. +.IP \fIclass\fP 1i +Specifies the created window's class. +You can pass +.PN InputOutput , +.PN InputOnly , +or +.PN CopyFromParent . +A class of +.PN CopyFromParent +means the class +is taken from the parent. +.IP \fIvisual\fP 1i +Specifies the visual type. +A visual of +.PN CopyFromParent +means the visual type is taken from the +parent. +.IP \fIvaluemask\fP 1i +Specifies which window attributes are defined in the attributes +argument. +This mask is the bitwise inclusive OR of the valid attribute mask bits. +If valuemask is zero, +the attributes are ignored and are not referenced. +.IP \fIattributes\fP 1i +Specifies the structure from which the values (as specified by the value mask) +are to be taken. +The value mask should have the appropriate bits +set to indicate which attributes have been set in the structure. +.LP +.eM +The +.PN XCreateWindow +function creates an unmapped subwindow for a specified parent window, +returns the window ID of the created window, +and causes the X server to generate a +.PN CreateNotify +event. +The created window is placed on top in the stacking order +with respect to siblings. +.LP +The coordinate system has the X axis horizontal and the Y axis vertical +with the origin [0, 0] at the upper-left corner. +Coordinates are integral, +in terms of pixels, +and coincide with pixel centers. +Each window and pixmap has its own coordinate system. +For a window, +the origin is inside the border at the inside, upper-left corner. +.LP +The border_width for an +.PN InputOnly +window must be zero, or a +.PN BadMatch +error results. +For class +.PN InputOutput , +the visual type and depth must be a combination supported for the screen, +or a +.PN BadMatch +error results. +The depth need not be the same as the parent, +but the parent must not be a window of class +.PN InputOnly , +or a +.PN BadMatch +error results. +For an +.PN InputOnly +window, +the depth must be zero, and the visual must be one supported by the screen. +If either condition is not met, +a +.PN BadMatch +error results. +The parent window, however, may have any depth and class. +If you specify any invalid window attribute for a window, a +.PN BadMatch +error results. +.LP +The created window is not yet displayed (mapped) on the user's display. +To display the window, call +.PN XMapWindow . +The new window initially uses the same cursor as +its parent. +A new cursor can be defined for the new window by calling +.PN XDefineCursor . +.IN "Cursor" "Initial State" +.IN "XDefineCursor" +The window will not be visible on the screen unless it and all of its +ancestors are mapped and it is not obscured by any of its ancestors. +.LP +.PN XCreateWindow +can generate +.PN BadAlloc , +.PN BadColor , +.PN BadCursor , +.PN BadMatch , +.PN BadPixmap , +.PN BadValue , +and +.PN BadWindow +errors. +.LP +.sp +To create an unmapped +.PN InputOutput +subwindow of a given parent window, use +.PN XCreateSimpleWindow . +.IN "XCreateSimpleWindow" "" "@DEF@" +.sM +.FD 0 +Window XCreateSimpleWindow\^(\^\fIdisplay\fP, \fIparent\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIborder_width\fP\^, +.br + \fIborder\fP\^, \fIbackground\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIparent\fP\^; +.br + int \fIx\fP\^, \fIy\fP\^; +.br + unsigned int \fIwidth\fP\^, \fIheight\fP\^; +.br + unsigned int \fIborder_width\fP\^; +.br + unsigned long \fIborder\fP\^; +.br + unsigned long \fIbackground\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIparent\fP 1i +Specifies the parent window. +.ds Xy , which are the top-left outside corner of the new window's borders \ +and are relative to the inside of the parent window's borders +.IP \fIx\fP 1i +.br +.ns +.IP \fIy\fP 1i +Specify the x and y coordinates\*(Xy. +.ds Wh , which are the created window's inside dimensions \ +and do not include the created window's borders +.IP \fIwidth\fP 1i +.br +.ns +.IP \fIheight\fP 1i +Specify the width and height\*(Wh. +The dimensions must be nonzero, +or a +.PN BadValue +error results. +.IP \fIborder_width\fP 1i +Specifies the width of the created window's border in pixels. +.IP \fIborder\fP 1i +Specifies the border pixel value of the window. +.IP \fIbackground\fP 1i +Specifies the background pixel value of the window. + +.LP +.eM +The +.PN XCreateSimpleWindow +function creates an unmapped +.PN InputOutput +subwindow for a specified parent window, returns the +window ID of the created window, and causes the X server to generate a +.PN CreateNotify +event. +The created window is placed on top in the stacking order with respect to +siblings. +Any part of the window that extends outside its parent window is clipped. +The border_width for an +.PN InputOnly +window must be zero, or a +.PN BadMatch +error results. +.PN XCreateSimpleWindow +inherits its depth, class, and visual from its parent. +All other window attributes, except background and border, +have their default values. +.LP +.PN XCreateSimpleWindow +can generate +.PN BadAlloc , +.PN BadMatch , +.PN BadValue , +and +.PN BadWindow +errors. +.NH 2 +Destroying Windows +.XS +\*(SN Destroying Windows +.XE +.LP +Xlib provides functions that you can use to destroy a window or destroy all +subwindows of a window. +.LP +.sp +To destroy a window and all of its subwindows, use +.PN XDestroyWindow . +.IN "XDestroyWindow" "" "@DEF@" +.sM +.FD 0 +XDestroyWindow\^(\^\fIdisplay\fP, \fIw\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.LP +.eM +The +.PN XDestroyWindow +function destroys the specified window as well as all of its subwindows and causes +the X server to generate a +.PN DestroyNotify +event for each window. +The window should never be referenced again. +If the window specified by the w argument is mapped, +it is unmapped automatically. +The ordering of the +.PN DestroyNotify +events is such that for any given window being destroyed, +.PN DestroyNotify +is generated on any inferiors of the window before being generated on +the window itself. +The ordering among siblings and across subhierarchies is not otherwise +constrained. +If the window you specified is a root window, no windows are destroyed. +Destroying a mapped window will generate +.PN Expose +events on other windows that were obscured by the window being destroyed. +.LP +.PN XDestroyWindow +can generate a +.PN BadWindow +error. +.LP +.sp +To destroy all subwindows of a specified window, use +.PN XDestroySubwindows . +.IN "XDestroySubwindows" "" "@DEF@" +.sM +.FD 0 +XDestroySubwindows\^(\^\fIdisplay\fP, \fIw\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.LP +.eM +The +.PN XDestroySubwindows +function destroys all inferior windows of the specified window, +in bottom-to-top stacking order. +It causes the X server to generate a +.PN DestroyNotify +event for each window. +If any mapped +subwindows were actually destroyed, +.PN XDestroySubwindows +causes the X server to generate +.PN Expose +events on the specified window. +This is much more efficient than deleting many windows +one at a time because much of the work need be performed only once for all +of the windows, rather than for each window. +The subwindows should never be referenced again. +.LP +.PN XDestroySubwindows +can generate a +.PN BadWindow +error. +.NH 2 +Mapping Windows +.XS +\*(SN Mapping Windows +.XE +.LP +A window is considered mapped if an +.PN XMapWindow +call has been made on it. +It may not be visible on the screen for one of the following reasons: +.IP \(bu 5 +It is obscured by another opaque window. +.IP \(bu 5 +One of its ancestors is not mapped. +.IP \(bu 5 +It is entirely clipped by an ancestor. +.LP +.PN Expose +events are generated for the window when part or all of +it becomes visible on the screen. +A client receives the +.PN Expose +events only if it has asked for them. +Windows retain their position in the stacking order when they are unmapped. +.LP +A window manager may want to control the placement of subwindows. +If +.PN SubstructureRedirectMask +has been selected by a window manager +on a parent window (usually a root window), +a map request initiated by other clients on a child window is not performed, +and the window manager is sent a +.PN MapRequest +event. +However, if the override-redirect flag on the child had been set to +.PN True +(usually only on pop-up menus), +the map request is performed. +.LP +A tiling window manager might decide to reposition and resize other clients' +windows and then decide to map the window to its final location. +A window manager that wants to provide decoration might +reparent the child into a frame first. +For further information, +see sections 3.2.8 and 10.10. +Only a single client at a time can select for +.PN SubstructureRedirectMask . +.LP +Similarly, a single client can select for +.PN ResizeRedirectMask +on a parent window. +Then, any attempt to resize the window by another client is suppressed, and +the client receives a +.PN ResizeRequest +event. +.LP +.sp +To map a given window, use +.PN XMapWindow . +.IN "XMapWindow" "" "@DEF@" +.sM +.FD 0 +XMapWindow\^(\^\fIdisplay\fP, \fIw\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.LP +.eM +The +.PN XMapWindow +function +maps the window and all of its +subwindows that have had map requests. +Mapping a window that has an unmapped ancestor does not display the +window but marks it as eligible for display when the ancestor becomes +mapped. +Such a window is called unviewable. +When all its ancestors are mapped, +the window becomes viewable +and will be visible on the screen if it is not obscured by another window. +This function has no effect if the window is already mapped. +.LP +If the override-redirect of the window is +.PN False +and if some other client has selected +.PN SubstructureRedirectMask +on the parent window, then the X server generates a +.PN MapRequest +event, and the +.PN XMapWindow +function does not map the window. +Otherwise, the window is mapped, and the X server generates a +.PN MapNotify +event. +.LP +If the window becomes viewable and no earlier contents for it are remembered, +the X server tiles the window with its background. +If the window's background is undefined, +the existing screen contents are not +altered, and the X server generates zero or more +.PN Expose +events. +If backing-store was maintained while the window was unmapped, no +.PN Expose +events +are generated. +If backing-store will now be maintained, +a full-window exposure is always generated. +Otherwise, only visible regions may be reported. +Similar tiling and exposure take place for any newly viewable inferiors. +.LP +.IN "XMapWindow" +If the window is an +.PN InputOutput +window, +.PN XMapWindow +generates +.PN Expose +events on each +.PN InputOutput +window that it causes to be displayed. +If the client maps and paints the window +and if the client begins processing events, +the window is painted twice. +To avoid this, +first ask for +.PN Expose +events and then map the window, +so the client processes input events as usual. +The event list will include +.PN Expose +for each +window that has appeared on the screen. +The client's normal response to +an +.PN Expose +event should be to repaint the window. +This method usually leads to simpler programs and to proper interaction +with window managers. +.LP +.PN XMapWindow +can generate a +.PN BadWindow +error. +.LP +.sp +To map and raise a window, use +.PN XMapRaised . +.IN "XMapRaised" "" "@DEF@" +.sM +.FD 0 +XMapRaised\^(\^\fIdisplay\fP, \fIw\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.LP +.eM +The +.PN XMapRaised +function +essentially is similar to +.PN XMapWindow +in that it maps the window and all of its +subwindows that have had map requests. +However, it also raises the specified window to the top of the stack. +For additional information, +see +.PN XMapWindow . +.LP +.PN XMapRaised +can generate multiple +.PN BadWindow +errors. +.LP +.sp +To map all subwindows for a specified window, use +.PN XMapSubwindows . +.IN "XMapSubwindows" "" "@DEF@" +.sM +.FD 0 +XMapSubwindows\^(\^\fIdisplay\fP, \fIw\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.LP +.eM +The +.PN XMapSubwindows +.IN "XMapSubwindows" +function maps all subwindows for a specified window in top-to-bottom stacking +order. +The X server generates +.PN Expose +events on each newly displayed window. +This may be much more efficient than mapping many windows +one at a time because the server needs to perform much of the work +only once, for all of the windows, rather than for each window. +.LP +.PN XMapSubwindows +can generate a +.PN BadWindow +error. +.NH 2 +Unmapping Windows +.XS +\*(SN Unmapping Windows +.XE +.LP +Xlib provides functions that you can use to unmap a window or all subwindows. +.LP +.sp +To unmap a window, use +.PN XUnmapWindow . +.IN "XUnmapWindow" "" "@DEF@" +.sM +.FD 0 +XUnmapWindow\^(\^\fIdisplay\fP, \fIw\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.LP +.eM +The +.PN XUnmapWindow +function unmaps the specified window and causes the X server to generate an +.PN UnmapNotify +.IN "UnmapNotify Event" +.IN "XUnmapWindow" +event. +If the specified window is already unmapped, +.PN XUnmapWindow +has no effect. +Normal exposure processing on formerly obscured windows is performed. +Any child window will no longer be visible until another map call is +made on the parent. +In other words, the subwindows are still mapped but are not visible +until the parent is mapped. +Unmapping a window will generate +.PN Expose +events on windows that were formerly obscured by it. +.LP +.PN XUnmapWindow +can generate a +.PN BadWindow +error. +.LP +.sp +To unmap all subwindows for a specified window, use +.PN XUnmapSubwindows . +.IN "XUnmapSubwindows" "" "@DEF@" +.sM +.FD 0 +XUnmapSubwindows\^(\^\fIdisplay\fP, \fIw\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.LP +.eM +The +.PN XUnmapSubwindows +function unmaps all subwindows for the specified window in bottom-to-top +stacking order. +It causes the X server to generate an +.PN UnmapNotify +event on each subwindow and +.PN Expose +events on formerly obscured windows. +.IN "UnmapNotify Event" +Using this function is much more efficient than unmapping multiple windows +one at a time because the server needs to perform much of the work +only once, for all of the windows, rather than for each window. +.LP +.PN XUnmapSubwindows +can generate a +.PN BadWindow +error. +.NH 2 +Configuring Windows +.XS +\*(SN Configuring Windows +.XE +.LP +.LP +Xlib provides functions that you can use to +move a window, resize a window, move and resize a window, or +change a window's border width. +To change one of these parameters, +set the appropriate member of the +.PN XWindowChanges +structure and OR in the corresponding value mask in subsequent calls to +.PN XConfigureWindow . +The symbols for the value mask bits and the +.PN XWindowChanges +structure are: +.sM +.LP +/* Configure window value mask bits */ +.TS +lw(.5i) lw(2.5i) lw(.8i). +T{ +#define +T} T{ +.PN CWX +T} T{ +(1<<0) +T} +T{ +#define +T} T{ +.PN CWY +T} T{ +(1<<1) +T} +T{ +#define +T} T{ +.PN CWWidth +T} T{ +(1<<2) +T} +T{ +#define +T} T{ +.PN CWHeight +T} T{ +(1<<3) +T} +T{ +#define +T} T{ +.PN CWBorderWidth +T} T{ +(1<<4) +T} +T{ +#define +T} T{ +.PN CWSibling +T} T{ +(1<<5) +T} +T{ +#define +T} T{ +.PN CWStackMode +T} T{ +(1<<6) +T} +.TE +.IN "XWindowChanges" "" "@DEF@" +.Ds 0 +.TA .5i 3i +.ta .5i 3i +/* Values */ + +typedef struct { + int x, y; + int width, height; + int border_width; + Window sibling; + int stack_mode; +} XWindowChanges; +.De +.LP +.eM +The x and y members are used to set the window's x and y coordinates, +which are relative to the parent's origin +and indicate the position of the upper-left outer corner of the window. +The width and height members are used to set the inside size of the window, +not including the border, and must be nonzero, or a +.PN BadValue +error results. +Attempts to configure a root window have no effect. +.LP +The border_width member is used to set the width of the border in pixels. +Note that setting just the border width leaves the outer-left corner of the window +in a fixed position but moves the absolute position of the window's origin. +If you attempt to set the border-width attribute of an +.PN InputOnly +window nonzero, a +.PN BadMatch +error results. +.LP +The sibling member is used to set the sibling window for stacking operations. +The stack_mode member is used to set how the window is to be restacked +and can be set to +.PN Above , +.PN Below , +.PN TopIf , +.PN BottomIf , +or +.PN Opposite . +.LP +If the override-redirect flag of the window is +.PN False +and if some other client has selected +.PN SubstructureRedirectMask +on the parent, the X server generates a +.PN ConfigureRequest +event, and no further processing is performed. +Otherwise, +if some other client has selected +.PN ResizeRedirectMask +on the window and the inside +width or height of the window is being changed, +a +.PN ResizeRequest +event is generated, and the current inside width and height are +used instead. +Note that the override-redirect flag of the window has no effect +on +.PN ResizeRedirectMask +and that +.PN SubstructureRedirectMask +on the parent has precedence over +.PN ResizeRedirectMask +on the window. +.LP +When the geometry of the window is changed as specified, +the window is restacked among siblings, and a +.PN ConfigureNotify +event is generated if the state of the window actually changes. +.PN GravityNotify +events are generated after +.PN ConfigureNotify +events. +If the inside width or height of the window has actually changed, +children of the window are affected as specified. +.LP +If a window's size actually changes, +the window's subwindows move according to their window gravity. +Depending on the window's bit gravity, +the contents of the window also may be moved (see section 3.2.3). +.LP +If regions of the window were obscured but now are not, +exposure processing is performed on these formerly obscured windows, +including the window itself and its inferiors. +As a result of increasing the width or height, +exposure processing is also performed on any new regions of the window +and any regions where window contents are lost. +.LP +The restack check (specifically, the computation for +.PN BottomIf , +.PN TopIf , +and +.PN Opposite ) +is performed with respect to the window's final size and position (as +controlled by the other arguments of the request), not its initial position. +If a sibling is specified without a stack_mode, +a +.PN BadMatch +error results. +.LP +If a sibling and a stack_mode are specified, +the window is restacked as follows: +.TS +lw(1i) lw(5i). +T{ +.PN Above +T} T{ +The window is placed just above the sibling. +T} +.sp 6p +T{ +.PN Below +T} T{ +The window is placed just below the sibling. +T} +.sp 6p +T{ +.PN TopIf +T} T{ +If the sibling occludes the window, the window is placed +at the top of the stack. +T} +.sp 6p +T{ +.PN BottomIf +T} T{ +If the window occludes the sibling, the window is +placed at the bottom of the stack. +T} +.sp 6p +T{ +.PN Opposite +T} T{ +If the sibling occludes the window, the window +is placed at the top of the stack. +If the window occludes the sibling, +the window is placed at the bottom of the stack. +T} +.TE +.LP +If a stack_mode is specified but no sibling is specified, +the window is restacked as follows: +.TS +lw(1i) lw(5i). +T{ +.PN Above +T} T{ +The window is placed at the top of the stack. +T} +.sp 6p +T{ +.PN Below +T} T{ +The window is placed at the bottom of the stack. +T} +.sp 6p +T{ +.PN TopIf +T} T{ +If any sibling occludes the window, the window is placed at +the top of the stack. +T} +.sp 6p +T{ +.PN BottomIf +T} T{ +If the window occludes any sibling, the window is placed at +the bottom of the stack. +T} +.sp 6p +T{ +.PN Opposite +T} T{ +If any sibling occludes the window, the window +is placed at the top of the stack. +If the window occludes any sibling, +the window is placed at the bottom of the stack. +T} +.TE +.LP +Attempts to configure a root window have no effect. +.LP +.sp +To configure a window's size, location, stacking, or border, use +.PN XConfigureWindow . +.IN "XConfigureWindow" "" "@DEF@" +.sM +.FD 0 +XConfigureWindow\^(\^\fIdisplay\fP, \fIw\fP\^, \fIvalue_mask\fP\^, \fIvalues\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + unsigned int \fIvalue_mask\fP\^; +.br + XWindowChanges *\fIvalues\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.ds Wi to be reconfigured +.IP \fIw\fP 1i +Specifies the window \*(Wi. +.IP \fIvalue_mask\fP 1i +Specifies which values are to be set using information in +the values structure. +This mask is the bitwise inclusive OR of the valid configure window values bits. +.IP \fIvalues\fP 1i +Specifies the +.PN XWindowChanges +structure. +.LP +.eM +The +.PN XConfigureWindow +function uses the values specified in the +.PN XWindowChanges +structure to reconfigure a window's size, position, border, and stacking order. +Values not specified are taken from the existing geometry of the window. +.LP +If a sibling is specified without a stack_mode or if the window +is not actually a sibling, +a +.PN BadMatch +error results. +Note that the computations for +.PN BottomIf , +.PN TopIf , +and +.PN Opposite +are performed with respect to the window's final geometry (as controlled by the +other arguments passed to +.PN XConfigureWindow ), +not its initial geometry. +Any backing store contents of the window, its +inferiors, and other newly visible windows are either discarded or +changed to reflect the current screen contents +(depending on the implementation). +.LP +.PN XConfigureWindow +can generate +.PN BadMatch , +.PN BadValue , +and +.PN BadWindow +errors. +.LP +.sp +To move a window without changing its size, use +.PN XMoveWindow . +.IN "XMoveWindow" "" "@DEF@" +.sM +.FD 0 +XMoveWindow\^(\^\fIdisplay\fP, \fIw\fP\^, \fIx\fP\^, \fIy\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + int \fIx\fP\^, \fIy\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.ds Wi to be moved +.IP \fIw\fP 1i +Specifies the window \*(Wi. +.ds Xy , which define the new location of the top-left pixel \ +of the window's border or the window itself if it has no border +.IP \fIx\fP 1i +.br +.ns +.IP \fIy\fP 1i +Specify the x and y coordinates\*(Xy. +.LP +.eM +The +.PN XMoveWindow +function moves the specified window to the specified x and y coordinates, +but it does not change the window's size, raise the window, or +change the mapping state of the window. +Moving a mapped window may or may not lose the window's contents +depending on if the window is obscured by nonchildren +and if no backing store exists. +If the contents of the window are lost, +the X server generates +.PN Expose +events. +Moving a mapped window generates +.PN Expose +events on any formerly obscured windows. +.LP +If the override-redirect flag of the window is +.PN False +and some +other client has selected +.PN SubstructureRedirectMask +on the parent, the X server generates a +.PN ConfigureRequest +event, and no further processing is +performed. +Otherwise, the window is moved. +.LP +.PN XMoveWindow +can generate a +.PN BadWindow +error. +.LP +.sp +To change a window's size without changing the upper-left coordinate, use +.PN XResizeWindow . +.IN "XResizeWindow" "" "@DEF@" +.sM +.FD 0 +XResizeWindow\^(\^\fIdisplay\fP, \fIw\fP\^, \fIwidth\fP\^, \fIheight\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + unsigned int \fIwidth\fP\^, \fIheight\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.ds Wh , which are the interior dimensions of the window \ +after the call completes +.IP \fIwidth\fP 1i +.br +.ns +.IP \fIheight\fP 1i +Specify the width and height\*(Wh. +.LP +.eM +The +.PN XResizeWindow +function changes the inside dimensions of the specified window, not including +its borders. +This function does not change the window's upper-left coordinate or +the origin and does not restack the window. +Changing the size of a mapped window may lose its contents and generate +.PN Expose +events. +If a mapped window is made smaller, +changing its size generates +.PN Expose +events on windows that the mapped window formerly obscured. +.LP +If the override-redirect flag of the window is +.PN False +and some +other client has selected +.PN SubstructureRedirectMask +on the parent, the X server generates a +.PN ConfigureRequest +event, and no further processing is performed. +If either width or height is zero, +a +.PN BadValue +error results. +.LP +.PN XResizeWindow +can generate +.PN BadValue +and +.PN BadWindow +errors. +.LP +.sp +To change the size and location of a window, use +.PN XMoveResizeWindow . +.IN "XMoveResizeWindow" "" "@DEF@" +.sM +.FD 0 +XMoveResizeWindow\^(\^\fIdisplay\fP, \fIw\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + int \fIx\fP\^, \fIy\fP\^; +.br + unsigned int \fIwidth\fP\^, \fIheight\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.ds Wi to be reconfigured +.IP \fIw\fP 1i +Specifies the window \*(Wi. +.ds Xy , which define the new position of the window relative to its parent +.IP \fIx\fP 1i +.br +.ns +.IP \fIy\fP 1i +Specify the x and y coordinates\*(Xy. +.ds Wh , which define the interior size of the window +.IP \fIwidth\fP 1i +.br +.ns +.IP \fIheight\fP 1i +Specify the width and height\*(Wh. +.LP +.eM +The +.PN XMoveResizeWindow +function changes the size and location of the specified window +without raising it. +Moving and resizing a mapped window may generate an +.PN Expose +event on the window. +Depending on the new size and location parameters, +moving and resizing a window may generate +.PN Expose +events on windows that the window formerly obscured. +.LP +If the override-redirect flag of the window is +.PN False +and some +other client has selected +.PN SubstructureRedirectMask +on the parent, the X server generates a +.PN ConfigureRequest +event, and no further processing is performed. +Otherwise, the window size and location are changed. +.LP +.PN XMoveResizeWindow +can generate +.PN BadValue +and +.PN BadWindow +errors. +.LP +.sp +To change the border width of a given window, use +.PN XSetWindowBorderWidth . +.IN "XSetWindowBorderWidth" "" "@DEF@" +.sM +.FD 0 +XSetWindowBorderWidth\^(\^\fIdisplay\fP, \fIw\fP, \fIwidth\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + unsigned int \fIwidth\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIwidth\fP 1i +Specifies the width of the window border. +.LP +.eM +The +.PN XSetWindowBorderWidth +function sets the specified window's border width to the specified width. +.LP +.PN XSetWindowBorderWidth +can generate a +.PN BadWindow +error. +.NH 2 +Changing Window Stacking Order +.XS +\*(SN Changing Window Stacking Order +.XE +.LP +.LP +Xlib provides functions that you can use to raise, lower, circulate, +or restack windows. +.LP +.sp +To raise a window so that no sibling window obscures it, use +.PN XRaiseWindow . +.IN "XRaiseWindow" "" "@DEF@" +.sM +.FD 0 +XRaiseWindow\^(\^\fIdisplay\fP, \fIw\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.LP +.eM +The +.PN XRaiseWindow +function +raises the specified window to the top of the stack so that no sibling window +obscures it. +If the windows are regarded as overlapping sheets of paper stacked +on a desk, +then raising a window is analogous to moving the sheet to the top of +the stack but leaving its x and y location on the desk constant. +Raising a mapped window may generate +.PN Expose +events for the window and any mapped subwindows that were formerly obscured. +.LP +If the override-redirect attribute of the window is +.PN False +and some +other client has selected +.PN SubstructureRedirectMask +on the parent, the X server generates a +.PN ConfigureRequest +event, and no processing is performed. +Otherwise, the window is raised. +.LP +.PN XRaiseWindow +can generate a +.PN BadWindow +error. +.LP +.sp +To lower a window so that it does not obscure any sibling windows, use +.PN XLowerWindow . +.IN "XLowerWindow" "" "@DEF@" +.sM +.FD 0 +XLowerWindow\^(\^\fIdisplay\fP, \fIw\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.LP +.eM +The +.PN XLowerWindow +function lowers the specified window to the bottom of the stack +so that it does not obscure any sibling +windows. +If the windows are regarded as overlapping sheets of paper +stacked on a desk, then lowering a window is analogous to moving the +sheet to the bottom of the stack but leaving its x and y location on +the desk constant. +Lowering a mapped window will generate +.PN Expose +events on any windows it formerly obscured. +.LP +If the override-redirect attribute of the window is +.PN False +and some +other client has selected +.PN SubstructureRedirectMask +on the parent, the X server generates a +.PN ConfigureRequest +event, and no processing is performed. +Otherwise, the window is lowered to the bottom of the +stack. +.LP +.PN XLowerWindow +can generate a +.PN BadWindow +error. +.LP +.sp +To circulate a subwindow up or down, use +.PN XCirculateSubwindows . +.IN "XCirculateSubwindows" "" "@DEF@" +.sM +.FD 0 +XCirculateSubwindows\^(\^\fIdisplay\fP, \fIw\fP\^, \fIdirection\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + int \fIdirection\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIdirection\fP 1i +Specifies the direction (up or down) that you want to circulate +the window. +You can pass +.PN RaiseLowest +or +.PN LowerHighest . +.LP +.eM +The +.PN XCirculateSubwindows +function circulates children of the specified window in the specified +direction. +If you specify +.PN RaiseLowest , +.PN XCirculateSubwindows +raises the lowest mapped child (if any) that is occluded +by another child to the top of the stack. +If you specify +.PN LowerHighest , +.PN XCirculateSubwindows +lowers the highest mapped child (if any) that occludes another child +to the bottom of the stack. +Exposure processing is then performed on formerly obscured windows. +If some other client has selected +.PN SubstructureRedirectMask +on the window, the X server generates a +.PN CirculateRequest +event, and no further processing is performed. +If a child is actually restacked, +the X server generates a +.PN CirculateNotify +event. +.LP +.PN XCirculateSubwindows +can generate +.PN BadValue +and +.PN BadWindow +errors. +.LP +.sp +To raise the lowest mapped child of a window that is partially or completely +occluded by another child, use +.PN XCirculateSubwindowsUp . +.IN "XCirculateSubwindowsUp" "" "@DEF@" +.sM +.FD 0 +XCirculateSubwindowsUp\^(\^\fIdisplay\fP, \fIw\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.LP +.eM +The +.PN XCirculateSubwindowsUp +function raises the lowest mapped child of the specified window that +is partially +or completely +occluded by another child. +Completely unobscured children are not affected. +This is a convenience function equivalent to +.PN XCirculateSubwindows +with +.PN RaiseLowest +specified. +.LP +.PN XCirculateSubwindowsUp +can generate a +.PN BadWindow +error. +.LP +.sp +To lower the highest mapped child of a window that partially or +completely occludes another child, use +.PN XCirculateSubwindowsDown . +.IN "XCirculateSubwindowsDown" "" "@DEF@" +.sM +.FD 0 +XCirculateSubwindowsDown\^(\^\fIdisplay\fP, \fIw\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.LP +.eM +The +.PN XCirculateSubwindowsDown +function lowers the highest mapped child of the specified window that partially +or completely occludes another child. +Completely unobscured children are not affected. +This is a convenience function equivalent to +.PN XCirculateSubwindows +with +.PN LowerHighest +specified. +.LP +.PN XCirculateSubwindowsDown +can generate a +.PN BadWindow +error. +.LP +.sp +To restack a set of windows from top to bottom, use +.PN XRestackWindows . +.IN "XRestackWindows" "" "@DEF@" +.sM +.FD 0 +XRestackWindows\^(\^\fIdisplay\fP, \fIwindows\fP\^, \^\fInwindows\fP\^); +.br + Display *\fIdisplay\fP\^; +.br + Window \fIwindows\fP\^[]; +.br + int \fInwindows\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIwindows\fP 1i +Specifies an array containing the windows to be restacked. +.IP \fInwindows\fP 1i +Specifies the number of windows to be restacked. +.LP +.eM +The +.PN XRestackWindows +function restacks the windows in the order specified, +from top to bottom. +The stacking order of the first window in the windows array is unaffected, +but the other windows in the array are stacked underneath the first window, +in the order of the array. +The stacking order of the other windows is not affected. +For each window in the window array that is not a child of the specified window, +a +.PN BadMatch +error results. +.LP +If the override-redirect attribute of a window is +.PN False +and some +other client has selected +.PN SubstructureRedirectMask +on the parent, the X server generates +.PN ConfigureRequest +events for each window whose override-redirect flag is not set, +and no further processing is performed. +Otherwise, the windows will be restacked in top-to-bottom order. +.LP +.PN XRestackWindows +can generate a +.PN BadWindow +error. +.NH 2 +Changing Window Attributes +.XS +\*(SN Changing Window Attributes +.XE +.LP +.LP +Xlib provides functions that you can use to set window attributes. +.PN XChangeWindowAttributes +is the more general function that allows you to set one or more window +attributes provided by the +.PN XSetWindowAttributes +structure. +The other functions described in this section allow you to set one specific +window attribute, such as a window's background. +.LP +.sp +To change one or more attributes for a given window, use +.PN XChangeWindowAttributes . +.IN "XChangeWindowAttributes" "" "@DEF@" +.sM +.FD 0 +XChangeWindowAttributes\^(\^\fIdisplay\fP, \fIw\fP\^, \fIvaluemask\fP\^, \fIattributes\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + unsigned long \fIvaluemask\fP\^; +.br + XSetWindowAttributes *\fIattributes\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIvaluemask\fP 1i +Specifies which window attributes are defined in the attributes +argument. +This mask is the bitwise inclusive OR of the valid attribute mask bits. +If valuemask is zero, +the attributes are ignored and are not referenced. +The values and restrictions are +the same as for +.PN XCreateWindow . +.IP +.IP \fIattributes\fP 1i +Specifies the structure from which the values (as specified by the value mask) +are to be taken. +The value mask should have the appropriate bits +set to indicate which attributes have been set in the structure +(see section 3.2). +.LP +.eM +Depending on the valuemask, +the +.PN XChangeWindowAttributes +function uses the window attributes in the +.PN XSetWindowAttributes +structure to change the specified window attributes. +Changing the background does not cause the window contents to be +changed. +To repaint the window and its background, use +.PN XClearWindow . +Setting the border or changing the background such that the +border tile origin changes causes the border to be repainted. +Changing the background of a root window to +.PN None +or +.PN ParentRelative +restores the default background pixmap. +Changing the border of a root window to +.PN CopyFromParent +restores the default border pixmap. +Changing the win-gravity does not affect the current position of the +window. +Changing the backing-store of an obscured window to +.PN WhenMapped +or +.PN Always , +or changing the backing-planes, backing-pixel, or +save-under of a mapped window may have no immediate effect. +Changing the colormap of a window (that is, defining a new map, not +changing the contents of the existing map) generates a +.PN ColormapNotify +event. +Changing the colormap of a visible window may have no +immediate effect on the screen because the map may not be installed +(see +.PN XInstallColormap ). +Changing the cursor of a root window to +.PN None +restores the default +cursor. +Whenever possible, you are encouraged to share colormaps. +.LP +Multiple clients can select input on the same window. +Their event masks are maintained separately. +When an event is generated, +it is reported to all interested clients. +However, only one client at a time can select for +.PN SubstructureRedirectMask , +.PN ResizeRedirectMask , +and +.PN ButtonPressMask . +If a client attempts to select any of these event masks +and some other client has already selected one, +a +.PN BadAccess +error results. +There is only one do-not-propagate-mask for a window, +not one per client. +.LP +.PN XChangeWindowAttributes +can generate +.PN BadAccess , +.PN BadColor , +.PN BadCursor , +.PN BadMatch , +.PN BadPixmap , +.PN BadValue , +and +.PN BadWindow +errors. +.LP +.sp +To set the background of a window to a given pixel, use +.PN XSetWindowBackground . +.IN "XSetWindowBackground" "" "@DEF@" +.sM +.FD 0 +XSetWindowBackground\^(\^\fIdisplay\fP, \fIw\fP\^, \fIbackground_pixel\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + unsigned long \fIbackground_pixel\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIbackground_pixel\fP 1i +Specifies the pixel that is to be used for the background. +.LP +.eM +The +.PN XSetWindowBackground +function sets the background of the window to the specified pixel value. +Changing the background does not cause the window contents to be changed. +.PN XSetWindowBackground +uses a pixmap of undefined size filled with the pixel value you passed. +If you try to change the background of an +.PN InputOnly +window, a +.PN BadMatch +error results. +.LP +.PN XSetWindowBackground +can generate +.PN BadMatch +and +.PN BadWindow +errors. +.LP +.sp +.LP +To set the background of a window to a given pixmap, use +.PN XSetWindowBackgroundPixmap . +.IN "Window" "background" +.IN "XSetWindowBackgroundPixmap" "" "@DEF@" +.sM +.FD 0 +XSetWindowBackgroundPixmap\^(\^\fIdisplay\fP, \fIw\fP\^, \fIbackground_pixmap\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + Pixmap \fIbackground_pixmap\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIbackground_pixmap\fP 1i +Specifies the background pixmap, +.PN ParentRelative , +or +.PN None . +.LP +.eM +.IN "Resource IDs" "freeing" +.IN "Freeing" "resources" +The +.PN XSetWindowBackgroundPixmap +function sets the background pixmap of the window to the specified pixmap. +The background pixmap can immediately be freed if no further explicit +references to it are to be made. +If +.PN ParentRelative +is specified, +the background pixmap of the window's parent is used, +or on the root window, the default background is restored. +If you try to change the background of an +.PN InputOnly +window, a +.PN BadMatch +error results. +If the background is set to +.PN None , +the window has no defined background. +.LP +.PN XSetWindowBackgroundPixmap +can generate +.PN BadMatch , +.PN BadPixmap , +and +.PN BadWindow +errors. +.NT Note +.PN XSetWindowBackground +and +.PN XSetWindowBackgroundPixmap +do not change the current contents of the window. +.NE +.LP +.sp +To change and repaint a window's border to a given pixel, use +.PN XSetWindowBorder . +.IN "XSetWindowBorder" "" "@DEF@" +.sM +.FD 0 +XSetWindowBorder\^(\^\fIdisplay\fP, \fIw\fP\^, \fIborder_pixel\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + unsigned long \fIborder_pixel\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIborder_pixel\fP 1i +Specifies the entry in the colormap. +.LP +.eM +The +.PN XSetWindowBorder +function sets the border of the window to the pixel value you specify. +If you attempt to perform this on an +.PN InputOnly +window, a +.PN BadMatch +error results. +.LP +.PN XSetWindowBorder +can generate +.PN BadMatch +and +.PN BadWindow +errors. +.LP +.sp +To change and repaint the border tile of a given window, use +.PN XSetWindowBorderPixmap . +.IN "XSetWindowBorderPixmap" "" "@DEF@" +.sM +.FD 0 +XSetWindowBorderPixmap\^(\^\fIdisplay\fP, \fIw\fP\^, \fIborder_pixmap\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + Pixmap \fIborder_pixmap\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIborder_pixmap\fP 1i +Specifies the border pixmap or +.PN CopyFromParent . +.LP +.eM +The +.PN XSetWindowBorderPixmap +function sets the border pixmap of the window to the pixmap you specify. +The border pixmap can be freed immediately if no further explicit +references to it are to be made. +If you specify +.PN CopyFromParent , +a copy of the parent window's border pixmap is used. +If you attempt to perform this on an +.PN InputOnly +window, a +.PN BadMatch +error results. +.IN "Resource IDs" "freeing" +.IN "Freeing" "resources" +.LP +.PN XSetWindowBorderPixmap +can generate +.PN BadMatch , +.PN BadPixmap , +and +.PN BadWindow +errors. +.LP +.sp +To set the colormap of a given window, use +.PN XSetWindowColormap . +.IN "XSetWindowColormap" "" "@DEF@" +.sM +.FD 0 +XSetWindowColormap\^(\^\fIdisplay\fP, \fIw\fP\^, \fIcolormap\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + Colormap \fIcolormap\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIcolormap\fP 1i +Specifies the colormap. +.LP +.eM +The +.PN XSetWindowColormap +function sets the specified colormap of the specified window. +The colormap must have the same visual type as the window, +or a +.PN BadMatch +error results. +.LP +.PN XSetWindowColormap +can generate +.PN BadColor , +.PN BadMatch , +and +.PN BadWindow +errors. +.LP +.sp +To define which cursor will be used in a window, use +.PN XDefineCursor . +.IN "Window" "defining the cursor" +.IN "XDefineCursor" "" "@DEF@" +.sM +.FD 0 +XDefineCursor\^(\^\fIdisplay\fP, \fIw\fP\^, \fIcursor\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + Cursor \fIcursor\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIcursor\fP 1i +Specifies the cursor that is to be displayed or +.PN None . +.LP +.eM +If a cursor is set, it will be used when the pointer is in the window. +If the cursor is +.PN None , +it is equivalent to +.PN XUndefineCursor . +.LP +.PN XDefineCursor +can generate +.PN BadCursor +and +.PN BadWindow +errors. +.LP +.sp +To undefine the cursor in a given window, use +.PN XUndefineCursor . +.IN "Window" "undefining the cursor" +.IN "XUndefineCursor" "" "@DEF@" +.sM +.FD 0 +XUndefineCursor\^(\^\fIdisplay\fP, \fIw\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.LP +.eM +The +.PN XUndefineCursor +function undoes the effect of a previous +.PN XDefineCursor +for this window. +When the pointer is in the window, +the parent's cursor will now be used. +On the root window, +the default cursor is restored. +.LP +.PN XUndefineCursor +can generate a +.PN BadWindow +error. +.bp diff --git a/libX11/specs/libX11/CH04 b/libX11/specs/libX11/CH04 new file mode 100644 index 000000000..b964198c2 --- /dev/null +++ b/libX11/specs/libX11/CH04 @@ -0,0 +1,1595 @@ +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be included +.\" in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR +.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +.\" OTHER DEALINGS IN THE SOFTWARE. +.\" +.\" Except as contained in this notice, the name of the X Consortium shall +.\" not be used in advertising or otherwise to promote the sale, use or +.\" other dealings in this Software without prior written authorization +.\" from the X Consortium. +.\" +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by +.\" Digital Equipment Corporation +.\" +.\" Portions Copyright \(co 1990, 1991 by +.\" Tektronix, Inc. +.\" +.\" Permission to use, copy, modify and distribute this documentation for +.\" any purpose and without fee is hereby granted, provided that the above +.\" copyright notice appears in all copies and that both that copyright notice +.\" and this permission notice appear in all copies, and that the names of +.\" Digital and Tektronix not be used in in advertising or publicity pertaining +.\" to this documentation without specific, written prior permission. +.\" Digital and Tektronix makes no representations about the suitability +.\" of this documentation for any purpose. +.\" It is provided ``as is'' without express or implied warranty. +.\" +\& +.sp 1 +.ce 3 +\s+1\fBChapter 4\fP\s-1 + +\s+1\fBWindow Information Functions\fP\s-1 +.sp 2 +.nr H1 4 +.nr H2 0 +.nr H3 0 +.nr H4 0 +.nr H5 0 +.na +.LP +.XS +Chapter 4: Window Information Functions +.XE +After you connect the display to the X server and create a window, +you can use the Xlib window information functions to: +.IP \(bu 5 +Obtain information about a window +.IP \(bu 5 +Translate screen coordinates +.IP \(bu 5 +Manipulate property lists +.IP \(bu 5 +Obtain and change window properties +.IP \(bu 5 +Manipulate selections +.NH 2 +Obtaining Window Information +.XS +\*(SN Obtaining Window Information +.XE +.LP +Xlib provides functions that you can use to obtain information about +the window tree, the window's current attributes, +the window's current geometry, or the current pointer coordinates. +Because they are most frequently used by window managers, +these functions all return a status to indicate whether the window still +exists. +.LP +.sp +To obtain the parent, a list of children, and number of children for +a given window, use +.PN XQueryTree . +.IN "Child Window" +.IN "Parent Window" +.IN "XQueryTree" "" "@DEF@" +.sM +.FD 0 +Status XQueryTree\^(\^\fIdisplay\fP, \fIw\fP\^, \fIroot_return\fP\^, \fIparent_return\fP\^, \fIchildren_return\fP\^, \fInchildren_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + Window *\fIroot_return\fP\^; +.br + Window *\fIparent_return\fP\^; +.br + Window **\fIchildren_return\fP\^; +.br + unsigned int *\fInchildren_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.ds Wi whose list of children, root, parent, and number of children \ +you want to obtain +.IP \fIw\fP 1i +Specifies the window \*(Wi. +.IP \fIroot_return\fP 1i +Returns the root window. +.IP \fIparent_return\fP 1i +Returns the parent window. +.IP \fIchildren_return\fP 1i +Returns the list of children. +.IP \fInchildren_return\fP 1i +Returns the number of children. +.LP +.eM +The +.PN XQueryTree +function returns the root ID, the parent window ID, +a pointer to the list of children windows +(NULL when there are no children), +and the number of children in the list for the specified window. +The children are listed in current stacking order, from bottom-most +(first) to top-most (last). +.PN XQueryTree +returns zero if it fails and nonzero if it succeeds. +To free a non-NULL children list when it is no longer needed, use +.PN XFree . +.LP +.PN XQueryTree +can generate a +.PN BadWindow +error. +.LP +.sp +To obtain the current attributes of a given window, use +.PN XGetWindowAttributes . +.IN "XGetWindowAttributes" "" "@DEF@" +.sM +.FD 0 +Status XGetWindowAttributes\^(\^\fIdisplay\fP, \fIw\fP\^, \fIwindow_attributes_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + XWindowAttributes *\fIwindow_attributes_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.ds Wi whose current attributes you want to obtain +.IP \fIw\fP 1i +Specifies the window \*(Wi. +.IP \fIwindow_attributes_return\fP 1i +Returns the specified window's attributes in the +.PN XWindowAttributes +structure. +.LP +.eM +The +.PN XGetWindowAttributes +function returns the current attributes for the specified window to an +.PN XWindowAttributes +structure. +.LP +.IN "XWindowAttributes" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + int x, y; /* location of window */ + int width, height; /* width and height of window */ + int border_width; /* border width of window */ + int depth; /* depth of window */ + Visual *visual; /* the associated visual structure */ + Window root; /* root of screen containing window */ + int class; /* InputOutput, InputOnly*/ + int bit_gravity; /* one of the bit gravity values */ + int win_gravity; /* one of the window gravity values */ + int backing_store; /* NotUseful, WhenMapped, Always */ + unsigned long backing_planes; /* planes to be preserved if possible */ + unsigned long backing_pixel; /* value to be used when restoring planes */ + Bool save_under; /* boolean, should bits under be saved? */ + Colormap colormap; /* color map to be associated with window */ + Bool map_installed; /* boolean, is color map currently installed*/ + int map_state; /* IsUnmapped, IsUnviewable, IsViewable */ + long all_event_masks; /* set of events all people have interest in*/ + long your_event_mask; /* my event mask */ + long do_not_propagate_mask; /* set of events that should not propagate */ + Bool override_redirect; /* boolean value for override-redirect */ + Screen *screen; /* back pointer to correct screen */ +} XWindowAttributes; +.De +.LP +.eM +The x and y members are set to the upper-left outer +corner relative to the parent window's origin. +The width and height members are set to the inside size of the window, +not including the border. +The border_width member is set to the window's border width in pixels. +The depth member is set to the depth of the window +(that is, bits per pixel for the object). +The visual member is a pointer to the screen's associated +.PN Visual +structure. +The root member is set to the root window of the screen containing the window. +The class member is set to the window's class and can be either +.PN InputOutput +or +.PN InputOnly . +.LP +The bit_gravity member is set to the window's bit gravity +and can be one of the following: +.LP +.TS +lw(1.5i) lw(1.5i). +T{ +.PN ForgetGravity +T} T{ +.PN EastGravity +T} +T{ +.PN NorthWestGravity +T} T{ +.PN SouthWestGravity +T} +T{ +.PN NorthGravity +T} T{ +.PN SouthGravity +T} +T{ +.PN NorthEastGravity +T} T{ +.PN SouthEastGravity +T} +T{ +.PN WestGravity +T} T{ +.PN StaticGravity +T} +.PN CenterGravity +.TE +.LP +The win_gravity member is set to the window's window gravity +and can be one of the following: +.LP +.TS +lw(1.5i) lw(1.5i). +T{ +.PN UnmapGravity +T} T{ +.PN EastGravity +T} +T{ +.PN NorthWestGravity +T} T{ +.PN SouthWestGravity +T} +T{ +.PN NorthGravity +T} T{ +.PN SouthGravity +T} +T{ +.PN NorthEastGravity +T} T{ +.PN SouthEastGravity +T} +T{ +.PN WestGravity +T} T{ +.PN StaticGravity +T} +.PN CenterGravity +.TE +.LP +For additional information on gravity, +see section 3.2.3. +.LP +The backing_store member is set to indicate how the X server should maintain +the contents of a window +and can be +.PN WhenMapped , +.PN Always , +or +.PN NotUseful . +The backing_planes member is set to indicate (with bits set to 1) which bit +planes of the window hold dynamic data that must be preserved in backing_stores +and during save_unders. +The backing_pixel member is set to indicate what values to use +for planes not set in backing_planes. +.LP +The save_under member is set to +.PN True +or +.PN False . +The colormap member is set to the colormap for the specified window and can be +a colormap ID or +.PN None . +The map_installed member is set to indicate whether the colormap is +currently installed and can be +.PN True +or +.PN False . +The map_state member is set to indicate the state of the window and can be +.PN IsUnmapped , +.PN IsUnviewable , +or +.PN IsViewable . +.PN IsUnviewable +is used if the window is mapped but some ancestor is unmapped. +.LP +The all_event_masks member is set to the bitwise inclusive OR of all event +masks selected on the window by all clients. +The your_event_mask member is set to the bitwise inclusive OR of all event +masks selected by the querying client. +The do_not_propagate_mask member is set to the bitwise inclusive OR of the +set of events that should not propagate. +.LP +The override_redirect member is set to indicate whether this window overrides +structure control facilities and can be +.PN True +or +.PN False . +Window manager clients should ignore the window if this member is +.PN True . +.LP +The screen member is set to a screen pointer that gives you a back pointer +to the correct screen. +This makes it easier to obtain the screen information without +having to loop over the root window fields to see which field matches. +.LP +.PN XGetWindowAttributes +can generate +.PN BadDrawable +and +.PN BadWindow +errors. +.LP +.sp +To obtain the current geometry of a given drawable, use +.PN XGetGeometry . +.IN "XGetGeometry" "" "@DEF@" +.sM +.FD 0 +Status XGetGeometry\^(\^\fIdisplay\fP, \fId\fP\^, \^\fIroot_return\fP\^, \fIx_return\fP\^, \fIy_return\fP\^, \fIwidth_return\fP\^, +.br + \fIheight_return\fP\^, \fIborder_width_return\fP\^, \fIdepth_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fId\fP\^; +.br + Window *\fIroot_return\fP\^; +.br + int *\fIx_return\fP\^, *\fIy_return\fP\^; +.br + unsigned int *\fIwidth_return\fP\^, *\fIheight_return\fP\^; +.br + unsigned int *\fIborder_width_return\fP\^; +.br + unsigned int *\fIdepth_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.ds Dr , which can be a window or a pixmap +.IP \fId\fP 1i +Specifies the drawable\*(Dr. +.IP \fIroot_return\fP 1i +Returns the root window. +.IP \fIx_return\fP 1i +.br +.ns +.IP \fIy_return\fP 1i +Return the x and y coordinates that define the location of the drawable. +For a window, +these coordinates specify the upper-left outer corner relative to +its parent's origin. +For pixmaps, these coordinates are always zero. +.IP \fIwidth_return\fP 1i +.br +.ns +.IP \fIheight_return\fP 1i +Return the drawable's dimensions (width and height). +For a window, +these dimensions specify the inside size, not including the border. +.IP \fIborder_width_return\fP 1i +Returns the border width in pixels. +If the drawable is a pixmap, it returns zero. +.IP \fIdepth_return\fP 1i +Returns the depth of the drawable (bits per pixel for the object). +.LP +.eM +The +.PN XGetGeometry +function returns the root window and the current geometry of the drawable. +The geometry of the drawable includes the x and y coordinates, width and height, +border width, and depth. +These are described in the argument list. +It is legal to pass to this function a window whose class is +.PN InputOnly . +.LP +.PN XGetGeometry +can generate a +.PN BadDrawable +error. +.NH 2 +Translating Screen Coordinates +.XS +\*(SN Translating Screen Coordinates +.XE +.LP +Applications sometimes +need to perform a coordinate transformation from the coordinate +space of one window to another window or need to determine which +window the pointing device is in. +.PN XTranslateCoordinates +and +.PN XQueryPointer +fulfill these needs (and avoid any race conditions) by +asking the X server to perform these operations. +.LP +.sp +To translate a coordinate in one window to the coordinate +space of another window, use +.PN XTranslateCoordinates . +.IN "XTranslateCoordinates" "" "@DEF@" +.sM +.FD 0 +Bool XTranslateCoordinates\^(\^\fIdisplay\fP, \fIsrc_w\fP\^, \fIdest_w\fP\^, \fIsrc_x\fP\^, \fIsrc_y\fP\^, \fIdest_x_return\fP\^, +.br + \fIdest_y_return\fP\^, \fIchild_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIsrc_w\fP\^, \fIdest_w\fP\^; +.br + int \fIsrc_x\fP\^, \fIsrc_y\fP\^; +.br + int *\fIdest_x_return\fP\^, *\fIdest_y_return\fP\^; +.br + Window *\fIchild_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIsrc_w\fP 1i +Specifies the source window. +.IP \fIdest_w\fP 1i +Specifies the destination window. +.IP \fIsrc_x\fP 1i +.br +.ns +.IP \fIsrc_y\fP 1i +Specify the x and y coordinates within the source window. +.IP \fIdest_x_return\fP 1i +.br +.ns +.IP \fIdest_y_return\fP 1i +Return the x and y coordinates within the destination window. +.IP \fIchild_return\fP 1i +Returns the child if the coordinates are contained in a mapped child of the +destination window. +.LP +.eM +If +.PN XTranslateCoordinates +returns +.PN True , +it takes the src_x and src_y coordinates relative +to the source window's origin and returns these coordinates to +dest_x_return and dest_y_return +relative to the destination window's origin. +If +.PN XTranslateCoordinates +returns +.PN False , +src_w and dest_w are on different screens, +and dest_x_return and dest_y_return are zero. +If the coordinates are contained in a mapped child of dest_w, +that child is returned to child_return. +Otherwise, child_return is set to +.PN None . +.LP +.PN XTranslateCoordinates +can generate a +.PN BadWindow +error. +.LP +.sp +To obtain the screen coordinates of the pointer +or to determine the pointer coordinates relative to a specified window, use +.PN XQueryPointer . +.IN "XQueryPointer" "" "@DEF@" +.sM +.FD 0 +Bool XQueryPointer\^(\^\fIdisplay\fP, \fIw\fP\^, \fIroot_return\fP\^, \fIchild_return\fP\^, \fIroot_x_return\fP\^, \fIroot_y_return\fP\^, +.br + \fIwin_x_return\fP\^, \fIwin_y_return\fP\^, \fImask_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + Window *\fIroot_return\fP\^, *\fIchild_return\fP\^; +.br + int *\fIroot_x_return\fP\^, *\fIroot_y_return\fP\^; +.br + int *\fIwin_x_return\fP\^, *\fIwin_y_return\fP\^; +.br + unsigned int *\fImask_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.ds Ro that the pointer is in +.IP \fIroot_return\fP 1i +Returns the root window \*(Ro. +.IP \fIchild_return\fP 1i +Returns the child window that the pointer is located in, if any. +.IP \fIroot_x_return\fP 1i +.br +.ns +.IP \fIroot_y_return\fP 1i +Return the pointer coordinates relative to the root window's origin. +.IP \fIwin_x_return\fP 1i +.br +.ns +.IP \fIwin_y_return\fP 1i +Return the pointer coordinates relative to the specified window. +.IP \fImask_return\fP 1i +Returns the current state of the modifier keys and pointer buttons. +.LP +.eM +The +.PN XQueryPointer +function returns the root window the pointer is logically on and the pointer +coordinates relative to the root window's origin. +If +.PN XQueryPointer +returns +.PN False , +the pointer is not on the same screen as the specified window, and +.PN XQueryPointer +returns +.PN None +to child_return and zero to win_x_return and win_y_return. +If +.PN XQueryPointer +returns +.PN True , +the pointer coordinates returned to win_x_return and win_y_return +are relative to the origin of the specified window. +In this case, +.PN XQueryPointer +returns the child that contains the pointer, if any, +or else +.PN None +to child_return. +.LP +.PN XQueryPointer +returns the current logical state of the keyboard buttons +and the modifier keys in mask_return. +It sets mask_return to the bitwise inclusive OR of one or more +of the button or modifier key bitmasks to match +the current state of the mouse buttons and the modifier keys. +.LP +Note that the logical state of a device (as seen through Xlib) +may lag the physical state if device event processing is frozen +(see section 12.1). +.LP +.PN XQueryPointer +can generate a +.PN BadWindow +error. +.NH 2 +Properties and Atoms +.XS +\*(SN Properties and Atoms +.XE +.LP +A property is a collection of named, typed data. +The window system has a set of predefined properties +.IN "Atom" "predefined" +(for example, the name of a window, size hints, and so on), and users can +define any other arbitrary information and associate it with windows. +Each property has a name, +which is an ISO Latin-1 string. +For each named property, +a unique identifier (atom) is associated with it. +A property also has a type, for example, string or integer. +These types are also indicated using atoms, so arbitrary new +types can be defined. +Data of only one type may be associated with a single +property name. +Clients can store and retrieve properties associated with windows. +For efficiency reasons, +an atom is used rather than a character string. +.PN XInternAtom +can be used to obtain the atom for property names. +.IN "Atom" +.LP +A property is also stored in one of several possible formats. +The X server can store the information as 8-bit quantities, 16-bit +quantities, or 32-bit quantities. +This permits the X server to present the data in the byte order that the +client expects. +.NT Note +If you define further properties of complex type, +you must encode and decode them yourself. +These functions must be carefully written if they are to be portable. +For further information about how to write a library extension, +see appendix C. +.NE +The type of a property is defined by an atom, which allows for +arbitrary extension in this type scheme. +.IN "Atom" +.LP +Certain property names are +predefined in the server for commonly used functions. +The atoms for these properties are defined in +.hN X11/Xatom.h . +To avoid name clashes with user symbols, the +.PN #define +name for each atom has the XA_ prefix. +For an explanation of the functions that let you get and set +much of the information stored in these predefined properties, +see chapter 14. +.LP +The core protocol imposes no semantics on these property names, +but semantics are specified in other X Consortium standards, +such as the \fIInter-Client Communication Conventions Manual\fP +and the \fIX Logical Font Description Conventions\fP. +.LP +You can use properties to communicate other information between +applications. +The functions described in this section let you define new properties +and get the unique atom IDs in your applications. +.LP +Although any particular atom can have some client interpretation +within each of the name spaces, +atoms occur in five distinct name spaces within the protocol: +.IP \(bu 5 +Selections +.IP \(bu 5 +Property names +.IP \(bu 5 +Property types +.IP \(bu 5 +Font properties +.IP \(bu 5 +Type of a +.PN ClientMessage +event (none are built into the X server) +.LP +.LP +The built-in selection property names are: +.LP +.Ds 0 +.TA .5i 1.5i 3i +.ta .5i 1.5i 3i +.R +PRIMARY +SECONDARY +.De +.LP +The built-in property names are: +.TS +lw(2i) lw(2i). +.sp 6p +CUT_BUFFER0 RESOURCE_MANAGER +CUT_BUFFER1 WM_CLASS +CUT_BUFFER2 WM_CLIENT_MACHINE +CUT_BUFFER3 WM_COLORMAP_WINDOWS +CUT_BUFFER4 WM_COMMAND +CUT_BUFFER5 WM_HINTS +CUT_BUFFER6 WM_ICON_NAME +CUT_BUFFER7 WM_ICON_SIZE +RGB_BEST_MAP WM_NAME +RGB_BLUE_MAP WM_NORMAL_HINTS +RGB_DEFAULT_MAP WM_PROTOCOLS +RGB_GRAY_MAP WM_STATE +RGB_GREEN_MAP WM_TRANSIENT_FOR +RGB_RED_MAP WM_ZOOM_HINTS +.sp 6p +.TE +.LP +The built-in property types are: +.LP +.TS +lw(2i) lw(2i). +.sp 6p +ARC POINT +ATOM RGB_COLOR_MAP +BITMAP RECTANGLE +CARDINAL STRING +COLORMAP VISUALID +CURSOR WINDOW +DRAWABLE WM_HINTS +FONT WM_SIZE_HINTS +INTEGER +PIXMAP +.sp 6p +.TE +.LP +The built-in font property names are: +.TS +lw(2i) lw(2i). +.sp 6p +MIN_SPACE STRIKEOUT_DESCENT +NORM_SPACE STRIKEOUT_ASCENT +MAX_SPACE ITALIC_ANGLE +END_SPACE X_HEIGHT +SUPERSCRIPT_X QUAD_WIDTH +SUPERSCRIPT_Y WEIGHT +SUBSCRIPT_X POINT_SIZE +SUBSCRIPT_Y RESOLUTION +UNDERLINE_POSITION COPYRIGHT +UNDERLINE_THICKNESS NOTICE +FONT_NAME FAMILY_NAME +FULL_NAME CAP_HEIGHT +.sp 6p +.TE +.LP +For further information about font properties, +see section 8.5. +.LP +.sp +To return an atom for a given name, use +.PN XInternAtom . +.IN "Atom" "interning" +.IN "XInternAtom" "" "@DEF@" +.sM +.FD 0 +Atom XInternAtom\^(\^\fIdisplay\fP, \fIatom_name\fP\^, \fIonly_if_exists\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + char *\fIatom_name\fP\^; +.br + Bool \fIonly_if_exists\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIatom_name\fP 1i +Specifies the name associated with the atom you want returned. +.IP \fIonly_if_exists\fP 1i +Specifies a Boolean value that indicates whether the atom must be created. +.LP +.eM +The +.PN XInternAtom +function returns the atom identifier associated with the specified atom_name +string. +If only_if_exists is +.PN False , +the atom is created if it does not exist. +Therefore, +.PN XInternAtom +can return +.PN None . +If the atom name is not in the Host Portable Character Encoding, +the result is implementation-dependent. +Uppercase and lowercase matter; +the strings ``thing'', ``Thing'', and ``thinG'' +all designate different atoms. +The atom will remain defined even after the client's connection closes. +It will become undefined only when the last connection to +the X server closes. +.LP +.PN XInternAtom +can generate +.PN BadAlloc +and +.PN BadValue +errors. +.LP +.sp +To return atoms for an array of names, use +.PN XInternAtoms . +.IN "Atom" "interning" +.IN "XInternAtoms" "" "@DEF@" +.sM +.FD 0 +Status XInternAtoms\^(\^\fIdisplay\fP, \fInames\fP\^, \fIcount\fP\^, \fIonly_if_exists\fP, \fIatoms_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + char **\fInames\fP\^; +.br + int \fIcount\fP\^; +.br + Bool \fIonly_if_exists\fP\^; +.br + Atom *\fIatoms_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fInames\fP 1i +Specifies the array of atom names. +.ds Cn atom names in the array +.IP \fIcount\fP 1i +Specifies the number of \*(Cn. +.IP \fIonly_if_exists\fP 1i +Specifies a Boolean value that indicates whether the atom must be created. +.IP \fIatoms_return\fP 1i +Returns the atoms. +.LP +.eM +The +.PN XInternAtoms +function returns the atom identifiers associated with the specified names. +The atoms are stored in the atoms_return array supplied by the caller. +Calling this function is equivalent to calling +.PN XInternAtom +for each of the names in turn with the specified value of only_if_exists, +but this function minimizes the number of round-trip protocol exchanges +between the client and the X server. +.LP +This function returns a nonzero status if atoms are returned for +all of the names; +otherwise, it returns zero. +.LP +.PN XInternAtoms +can generate +.PN BadAlloc +and +.PN BadValue +errors. +.LP +.sp +To return a name for a given atom identifier, use +.PN XGetAtomName . +.IN "Atom" "getting name" +.IN "XGetAtomName" "" "@DEF@" +.sM +.FD 0 +char *XGetAtomName\^(\^\fIdisplay\fP, \fIatom\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Atom \fIatom\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIatom\fP 1i +Specifies the atom for the property name you want returned. +.LP +.eM +The +.PN XGetAtomName +function returns the name associated with the specified atom. +If the data returned by the server is in the Latin Portable Character Encoding, +then the returned string is in the Host Portable Character Encoding. +Otherwise, the result is implementation-dependent. +To free the resulting string, +call +.PN XFree . +.LP +.PN XGetAtomName +can generate a +.PN BadAtom +error. +.LP +.sp +To return the names for an array of atom identifiers, use +.PN XGetAtomNames . +.IN "Atom" "getting name" +.IN "XGetAtomNames" "" "@DEF@" +.sM +.FD 0 +Status XGetAtomNames\^(\^\fIdisplay\fP, \fIatoms\fP, \fIcount\fP\^, \fInames_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Atom *\fIatoms\fP\^; +.br + int \fIcount\fP\^; +.br + char **\fInames_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIatoms\fP 1i +Specifies the array of atoms. +.ds Cn atoms in the array +.IP \fIcount\fP 1i +Specifies the number of \*(Cn. +.IP \fInames_return\fP 1i +Returns the atom names. +.LP +.eM +The +.PN XGetAtomNames +function returns the names associated with the specified atoms. +The names are stored in the names_return array supplied by the caller. +Calling this function is equivalent to calling +.PN XGetAtomName +for each of the atoms in turn, +but this function minimizes the number of round-trip protocol exchanges +between the client and the X server. +.LP +This function returns a nonzero status if names are returned for +all of the atoms; +otherwise, it returns zero. +.LP +.PN XGetAtomNames +can generate a +.PN BadAtom +error. +.NH 2 +Obtaining and Changing Window Properties +.XS +\*(SN Obtaining and Changing Window Properties +.XE +.LP +You can attach a property list to every window. +Each property has a name, a type, and a value (see section 4.3). +The value is an array of 8-bit, 16-bit, or 32-bit quantities, +whose interpretation is left to the clients. The type +.PN char +is used to represent 8-bit quantities, the type +.PN short +is used to represent 16-bit quantities, and the type +.PN long +is used to represent 32-bit quantities. +.LP +Xlib provides functions that you can use to obtain, +change, update, or interchange window properties. +In addition, Xlib provides other utility functions for inter-client +communication (see chapter 14). +.LP +.sp +To obtain the type, format, and value of a property of a given window, use +.PN XGetWindowProperty . +.IN "Property" "getting" +.LP +.IN "XGetWindowProperty" "" "@DEF@" +.sM +.FD 0 +int XGetWindowProperty\^(\^\fIdisplay\fP, \fIw\fP\^, \fIproperty\fP\^, \fIlong_offset\fP\^, \fIlong_length\fP\^, \fIdelete\fP\^, \fIreq_type\fP\^, +.br + \fIactual_type_return\fP\^, \fIactual_format_return\fP\^, \fInitems_return\fP\^, \fIbytes_after_return\fP\^, +.br + \fIprop_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + Atom \fIproperty\fP\^; +.br + long \fIlong_offset\fP\^, \fIlong_length\fP\^; +.br + Bool \fIdelete\fP\^; +.br + Atom \fIreq_type\fP\^; +.br + Atom *\fIactual_type_return\fP\^; +.br + int *\fIactual_format_return\fP\^; +.br + unsigned long *\fInitems_return\fP\^; +.br + unsigned long *\fIbytes_after_return\fP\^; +.br + unsigned char **\fIprop_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.ds Wi whose property you want to obtain +.IP \fIw\fP 1i +Specifies the window \*(Wi. +.IP \fIproperty\fP 1i +Specifies the property name. +.IP \fIlong_offset\fP 1i +Specifies the offset in the specified property (in 32-bit quantities) +where the data is to be retrieved. +.IP \fIlong_length\fP 1i +Specifies the length in 32-bit multiples of the data to be retrieved. +.IP \fIdelete\fP 1i +Specifies a Boolean value that determines whether the property is deleted. +.IP \fIreq_type\fP 1i +Specifies the atom identifier associated with the property type or +.PN AnyPropertyType . +.IP \fIactual_type_return\fP 1i +Returns the atom identifier that defines the actual type of the property. +.IP \fIactual_format_return\fP 1i +Returns the actual format of the property. +.IP \fInitems_return\fP 1i +Returns the actual number of 8-bit, 16-bit, or 32-bit items +stored in the prop_return data. +.IP \fIbytes_after_return\fP 1i +Returns the number of bytes remaining to be read in the property if +a partial read was performed. +.IP \fIprop_return\fP 1i +Returns the data in the specified format. +.LP +.eM +The +.PN XGetWindowProperty +function returns the actual type of the property; the actual format of the property; +the number of 8-bit, 16-bit, or 32-bit items transferred; the number of bytes remaining +to be read in the property; and a pointer to the data actually returned. +.PN XGetWindowProperty +sets the return arguments as follows: +.IP \(bu 5 +If the specified property does not exist for the specified window, +.PN XGetWindowProperty +returns +.PN None +to actual_type_return and the value zero to +actual_format_return and bytes_after_return. +The nitems_return argument is empty. +In this case, the delete argument is ignored. +.IP \(bu 5 +If the specified property exists +but its type does not match the specified type, +.PN XGetWindowProperty +returns the actual property type to actual_type_return, +the actual property format (never zero) to actual_format_return, +and the property length in bytes +(even if the actual_format_return is 16 or 32) +to bytes_after_return. +It also ignores the delete argument. +The nitems_return argument is empty. +.IP \(bu 5 +If the specified property exists and either you assign +.PN AnyPropertyType +to the req_type argument or the specified type matches the actual property type, +.PN XGetWindowProperty +returns the actual property type to actual_type_return and the actual +property format (never zero) to actual_format_return. +It also returns a value to bytes_after_return and nitems_return, by +defining the following +values: +.IP +.nf + N = actual length of the stored property in bytes + (even if the format is 16 or 32) + I = 4 * long_offset + T = N - I + L = MINIMUM(T, 4 * long_length) + A = N - (I + L) +.fi +.IP +The returned value starts at byte index I in the property (indexing +from zero), and its length in bytes is L. +If the value for long_offset causes L to be negative, +a +.PN BadValue +error results. +The value of bytes_after_return is A, +giving the number of trailing unread bytes in the stored property. +.LP +If the returned format is 8, the returned data is represented as a +.PN char +array. +If the returned format is 16, the returned data is represented as a +.PN short +array and should be cast to that type to obtain the elements. +If the returned format is 32, the returned data is represented as a +.PN long +array and should be cast to that type to obtain the elements. +.LP +.PN XGetWindowProperty +always allocates one extra byte in prop_return +(even if the property is zero length) +and sets it to zero so that simple properties consisting of characters +do not have to be copied into yet another string before use. +.LP +If delete is +.PN True +and bytes_after_return is zero, +.PN XGetWindowProperty +deletes the property +from the window and generates a +.PN PropertyNotify +event on the window. +.LP +The function returns +.PN Success +if it executes successfully. +To free the resulting data, +use +.PN XFree . +.LP +.PN XGetWindowProperty +can generate +.PN BadAtom , +.PN BadValue , +and +.PN BadWindow +errors. +.LP +.sp +To obtain a given window's property list, use +.PN XListProperties . +.IN "Property" "listing" +.IN "XListProperties" "" "@DEF@" +.sM +.FD 0 +Atom *XListProperties\^(\^\fIdisplay\fP, \fIw\fP\^, \fInum_prop_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + int *\fInum_prop_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.ds Wi whose property list you want to obtain +.IP \fIw\fP 1i +Specifies the window \*(Wi. +.IP \fInum_prop_return\fP 1i +Returns the length of the properties array. +.LP +.eM +The +.PN XListProperties +function returns a pointer to an array of atom properties that are defined for +the specified window or returns NULL if no properties were found. +To free the memory allocated by this function, use +.PN XFree . +.LP +.PN XListProperties +can generate a +.PN BadWindow +error. +.LP +.sp +To change a property of a given window, use +.PN XChangeProperty . +.IN "Property" "changing" +.IN "Property" "appending" +.IN "Property" "prepending" +.IN "Property" "replacing" +.IN "Property" "format" +.IN "Property" "type" +.IN "XChangeProperty" "" "@DEF@" +.sM +.FD 0 +XChangeProperty\^(\^\fIdisplay\fP, \fIw\fP\^, \fIproperty\fP\^, \fItype\fP\^, \fIformat\fP\^, \fImode\fP\^, \fIdata\fP\^, \fInelements\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + Atom \fIproperty\fP\^, \fItype\fP\^; +.br + int \fIformat\fP\^; +.br + int \fImode\fP\^; +.br + unsigned char *\fIdata\fP\^; +.br + int \fInelements\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.ds Wi whose property you want to change +.IP \fIw\fP 1i +Specifies the window \*(Wi. +.IP \fIproperty\fP 1i +Specifies the property name. +.IP \fItype\fP 1i +Specifies the type of the property. +The X server does not interpret the type but simply +passes it back to an application that later calls +.PN XGetWindowProperty . +.IP \fIformat\fP 1i +Specifies whether the data should be viewed as a list +of 8-bit, 16-bit, or 32-bit quantities. +Possible values are 8, 16, and 32. +This information allows the X server to correctly perform +byte-swap operations as necessary. +If the format is 16-bit or 32-bit, +you must explicitly cast your data pointer to an (unsigned char *) in the call +to +.PN XChangeProperty . +.\" Changed name of this file to prop_mode.a on 1/13/87 +.IP \fImode\fP 1i +Specifies the mode of the operation. +You can pass +.PN PropModeReplace , +.PN PropModePrepend , +or +.PN PropModeAppend . +.IP \fIdata\fP 1i +Specifies the property data. +.IP \fInelements\fP 1i +Specifies the number of elements of the specified data format. +.LP +.eM +The +.PN XChangeProperty +function alters the property for the specified window and +causes the X server to generate a +.PN PropertyNotify +event on that window. +.PN XChangeProperty +performs the following: +.IP \(bu 5 +If mode is +.PN PropModeReplace , +.PN XChangeProperty +discards the previous property value and stores the new data. +.IP \(bu 5 +If mode is +.PN PropModePrepend +or +.PN PropModeAppend , +.PN XChangeProperty +inserts the specified data before the beginning of the existing data +or onto the end of the existing data, respectively. +The type and format must match the existing property value, +or a +.PN BadMatch +error results. +If the property is undefined, +it is treated as defined with the correct type and +format with zero-length data. +.LP +If the specified format is 8, the property data must be a +.PN char +array. +If the specified format is 16, the property data must be a +.PN short +array. +If the specified format is 32, the property data must be a +.PN long +array. +.LP +The lifetime of a property is not tied to the storing client. +Properties remain until explicitly deleted, until the window is destroyed, +or until the server resets. +For a discussion of what happens when the connection to the X server is closed, +see section 2.6. +The maximum size of a property is server dependent and can vary dynamically +depending on the amount of memory the server has available. +(If there is insufficient space, a +.PN BadAlloc +error results.) +.LP +.PN XChangeProperty +can generate +.PN BadAlloc , +.PN BadAtom , +.PN BadMatch , +.PN BadValue , +and +.PN BadWindow +errors. +.LP +.sp +To rotate a window's property list, use +.PN XRotateWindowProperties . +.LP +.IN "XRotateWindowProperties" "" "@DEF@" +.sM +.FD 0 +XRotateWindowProperties\^(\^\fIdisplay\fP, \fIw\fP, \fIproperties\fP, \fInum_prop\fP, \fInpositions\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + Atom \fIproperties\fP\^[]\^; +.br + int \fInum_prop\fP\^; +.br + int \fInpositions\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIproperties\fP 1i +Specifies the array of properties that are to be rotated. +.IP \fInum_prop\fP 1i +Specifies the length of the properties array. +.IP \fInpositions\fP 1i +Specifies the rotation amount. +.LP +.eM +The +.PN XRotateWindowProperties +function allows you to rotate properties on a window and causes +the X server to generate +.PN PropertyNotify +events. +If the property names in the properties array are viewed as being numbered +starting from zero and if there are num_prop property names in the list, +then the value associated with property name I becomes the value associated +with property name (I + npositions) mod N for all I from zero to N \- 1. +The effect is to rotate the states by npositions places around the virtual ring +of property names (right for positive npositions, +left for negative npositions). +If npositions mod N is nonzero, +the X server generates a +.PN PropertyNotify +event for each property in the order that they are listed in the array. +If an atom occurs more than once in the list or no property with that +name is defined for the window, +a +.PN BadMatch +error results. +If a +.PN BadAtom +or +.PN BadMatch +error results, +no properties are changed. +.LP +.PN XRotateWindowProperties +can generate +.PN BadAtom , +.PN BadMatch , +and +.PN BadWindow +errors. +.LP +.sp +To delete a property on a given window, use +.PN XDeleteProperty . +.IN "Property" "deleting" +.IN "XDeleteProperty" "" "@DEF@" +.sM +.FD 0 +XDeleteProperty\^(\^\fIdisplay\fP, \fIw\fP\^, \fIproperty\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + Atom \fIproperty\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.ds Wi whose property you want to delete +.IP \fIw\fP 1i +Specifies the window \*(Wi. +.IP \fIproperty\fP 1i +Specifies the property name. +.LP +.eM +The +.PN XDeleteProperty +function deletes the specified property only if the +property was defined on the specified window +and causes the X server to generate a +.PN PropertyNotify +event on the window unless the property does not exist. +.LP +.PN XDeleteProperty +can generate +.PN BadAtom +and +.PN BadWindow +errors. +.NH 2 +Selections +.XS +\*(SN Selections +.XE +.LP +.IN "Selection" +Selections are one method used by applications to exchange data. +By using the property mechanism, +applications can exchange data of arbitrary types and can negotiate +the type of the data. +A selection can be thought of as an indirect property with a dynamic type. +That is, rather than having the property stored in the X server, +the property is maintained by some client (the owner). +A selection is global in nature (considered to belong to the user +but be maintained by clients) rather than being private to a particular +window subhierarchy or a particular set of clients. +.LP +Xlib provides functions that you can use to set, get, or request conversion +of selections. +This allows applications to implement the notion of current selection, +which requires that notification be sent to applications when they no +longer own the selection. +Applications that support selection often highlight the current selection +and so must be informed when another application has +acquired the selection so that they can unhighlight the selection. +.LP +When a client asks for the contents of +a selection, it specifies a selection target type. +This target type +can be used to control the transmitted representation of the contents. +For example, if the selection is ``the last thing the user clicked on'' +and that is currently an image, then the target type might specify +whether the contents of the image should be sent in XY format or Z format. +.LP +The target type can also be used to control the class of +contents transmitted, for example, +asking for the ``looks'' (fonts, line +spacing, indentation, and so forth) of a paragraph selection, not the +text of the paragraph. +The target type can also be used for other +purposes. +The protocol does not constrain the semantics. +.LP +.sp +To set the selection owner, use +.PN XSetSelectionOwner . +.IN "Selection" "setting the owner" +.IN "XSetSelectionOwner" "" "@DEF@" +.sM +.FD 0 +XSetSelectionOwner\^(\^\fIdisplay\fP, \fIselection\fP\^, \fIowner\fP\^, \fItime\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Atom \fIselection\fP\^; +.br + Window \fIowner\fP\^; +.br + Time \fItime\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIselection\fP 1i +Specifies the selection atom. +.IP \fIowner\fP 1i +Specifies the owner of the specified selection atom. +You can pass a window or +.PN None . +.IP \fItime\fP 1i +Specifies the time. +You can pass either a timestamp or +.PN CurrentTime . +.LP +.eM +The +.PN XSetSelectionOwner +function changes the owner and last-change time for the specified selection +and has no effect if the specified time is earlier than the current +last-change time of the specified selection +or is later than the current X server time. +Otherwise, the last-change time is set to the specified time, +with +.PN CurrentTime +replaced by the current server time. +If the owner window is specified as +.PN None , +then the owner of the selection becomes +.PN None +(that is, no owner). +Otherwise, the owner of the selection becomes the client executing +the request. +.LP +If the new owner (whether a client or +.PN None ) +is not +the same as the current owner of the selection and the current +owner is not +.PN None , +the current owner is sent a +.PN SelectionClear +event. +If the client that is the owner of a selection is later +terminated (that is, its connection is closed) +or if the owner window it has specified in the request is later +destroyed, +the owner of the selection automatically +reverts to +.PN None , +but the last-change time is not affected. +The selection atom is uninterpreted by the X server. +.PN XGetSelectionOwner +returns the owner window, which is reported in +.PN SelectionRequest +and +.PN SelectionClear +events. +Selections are global to the X server. +.LP +.PN XSetSelectionOwner +can generate +.PN BadAtom +and +.PN BadWindow +errors. +.LP +.sp +To return the selection owner, use +.PN XGetSelectionOwner . +.IN "Selection" "getting the owner" +.IN "XGetSelectionOwner" "" "@DEF@" +.sM +.FD 0 +Window XGetSelectionOwner\^(\^\fIdisplay\fP, \fIselection\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Atom \fIselection\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.ds Se whose owner you want returned +.IP \fIselection\fP 1i +Specifies the selection atom \*(Se. +.LP +.eM +The +.PN XGetSelectionOwner +function +returns the window ID associated with the window that currently owns the +specified selection. +If no selection was specified, the function returns the constant +.PN None . +If +.PN None +is returned, +there is no owner for the selection. +.LP +.PN XGetSelectionOwner +can generate a +.PN BadAtom +error. +.LP +.sp +To request conversion of a selection, use +.PN XConvertSelection . +.IN "Selection" "converting" +.IN "XConvertSelection" "" "@DEF@" +.sM +.FD 0 +XConvertSelection\^(\^\fIdisplay\fP, \fIselection\fP\^, \fItarget\fP\^, \fIproperty\fP\^, \fIrequestor\fP\^, \fItime\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Atom \fIselection\fP\^, \fItarget\fP\^; +.br + Atom \fIproperty\fP\^; +.br + Window \fIrequestor\fP\^; +.br + Time \fItime\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIselection\fP 1i +Specifies the selection atom. +.IP \fItarget\fP 1i +Specifies the target atom. +.IP \fIproperty\fP 1i +Specifies the property name. +You also can pass +.PN None . +.IP \fIrequestor\fP 1i +Specifies the requestor. +.IP \fItime\fP 1i +Specifies the time. +You can pass either a timestamp or +.PN CurrentTime . +.LP +.eM +.PN XConvertSelection +requests that the specified selection be converted to the specified target +type: +.IP \(bu 5 +If the specified selection has an owner, the X server sends a +.PN SelectionRequest +event to that owner. +.IP \(bu 5 +If no owner for the specified +selection exists, the X server generates a +.PN SelectionNotify +event to the +requestor with property +.PN None . +.LP +The arguments are passed on unchanged in either of the events. +There are two predefined selection atoms: PRIMARY and SECONDARY. +.LP +.PN XConvertSelection +can generate +.PN BadAtom +and +.PN BadWindow +errors. +.bp diff --git a/libX11/specs/libX11/CH05 b/libX11/specs/libX11/CH05 new file mode 100644 index 000000000..6ea218378 --- /dev/null +++ b/libX11/specs/libX11/CH05 @@ -0,0 +1,518 @@ +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be included +.\" in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR +.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +.\" OTHER DEALINGS IN THE SOFTWARE. +.\" +.\" Except as contained in this notice, the name of the X Consortium shall +.\" not be used in advertising or otherwise to promote the sale, use or +.\" other dealings in this Software without prior written authorization +.\" from the X Consortium. +.\" +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by +.\" Digital Equipment Corporation +.\" +.\" Portions Copyright \(co 1990, 1991 by +.\" Tektronix, Inc. +.\" +.\" Permission to use, copy, modify and distribute this documentation for +.\" any purpose and without fee is hereby granted, provided that the above +.\" copyright notice appears in all copies and that both that copyright notice +.\" and this permission notice appear in all copies, and that the names of +.\" Digital and Tektronix not be used in in advertising or publicity pertaining +.\" to this documentation without specific, written prior permission. +.\" Digital and Tektronix makes no representations about the suitability +.\" of this documentation for any purpose. +.\" It is provided ``as is'' without express or implied warranty. +.\" +\& +.sp 1 +.ce 3 +\s+1\fBChapter 5\fP\s-1 + +\s+1\fBPixmap and Cursor Functions\fP\s-1 +.sp 2 +.nr H1 5 +.nr H2 0 +.nr H3 0 +.nr H4 0 +.nr H5 0 +.na +.LP +.XS +Chapter 5: Pixmap and Cursor Functions +.XE +Once you have connected to an X server, +you can use the Xlib functions to: +.IP \(bu 5 +Create and free pixmaps +.IP \(bu 5 +Create, recolor, and free cursors +.NH 2 +Creating and Freeing Pixmaps +.XS +\*(SN Creating and Freeing Pixmaps +.XE +.LP +Pixmaps can only be used on the screen on which they were created. +Pixmaps are off-screen resources that are used for various operations, +such as defining cursors as tiling patterns +or as the source for certain raster operations. +Most graphics requests can operate either on a window or on a pixmap. +A bitmap is a single bit-plane pixmap. +.LP +.sp +To create a pixmap of a given size, use +.PN XCreatePixmap . +.IN "XCreatePixmap" "" "@DEF@" +.sM +.FD 0 +Pixmap XCreatePixmap\^(\^\fIdisplay\fP, \fId\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIdepth\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fId\fP\^; +.br + unsigned int \fIwidth\fP\^, \fIheight\fP\^; +.br + unsigned int \fIdepth\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fId\fP 1i +Specifies which screen the pixmap is created on. +.ds Wh , which define the dimensions of the pixmap +.IP \fIwidth\fP 1i +.br +.ns +.IP \fIheight\fP 1i +Specify the width and height\*(Wh. +.IP \fIdepth\fP 1i +Specifies the depth of the pixmap. +.LP +.eM +The +.PN XCreatePixmap +function creates a pixmap of the width, height, and depth you specified +and returns a pixmap ID that identifies it. +It is valid to pass an +.PN InputOnly +window to the drawable argument. +The width and height arguments must be nonzero, +or a +.PN BadValue +error results. +The depth argument must be one of the depths supported by the screen +of the specified drawable, +or a +.PN BadValue +error results. +.LP +The server uses the specified drawable to determine on which screen +to create the pixmap. +The pixmap can be used only on this screen +and only with other drawables of the same depth (see +.PN XCopyPlane +for an exception to this rule). +The initial contents of the pixmap are undefined. +.LP +.PN XCreatePixmap +can generate +.PN BadAlloc , +.PN BadDrawable , +and +.PN BadValue +errors. +.LP +.sp +To free all storage associated with a specified pixmap, use +.PN XFreePixmap . +.IN "XFreePixmap" "" "@DEF@" +.sM +.FD 0 +XFreePixmap\^(\^\fIdisplay\fP, \fIpixmap\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Pixmap \fIpixmap\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIpixmap\fP 1i +Specifies the pixmap. +.LP +.eM +The +.PN XFreePixmap +function first deletes the association between the pixmap ID and the pixmap. +Then, the X server frees the pixmap storage when there are no references to it. +The pixmap should never be referenced again. +.LP +.PN XFreePixmap +can generate a +.PN BadPixmap +error. +.NH 2 +Creating, Recoloring, and Freeing Cursors +.XS +\*(SN Creating, Recoloring, and Freeing Cursors +.XE +.LP +Each window can have a different cursor defined for it. +Whenever the pointer is in a visible window, +it is set to the cursor defined for that window. +If no cursor was defined for that window, +the cursor is the one defined for the parent window. +.LP +From X's perspective, +a cursor consists of a cursor source, mask, colors, and a hotspot. +The mask pixmap determines the shape of the cursor and must be a depth +of one. +The source pixmap must have a depth of one, +and the colors determine the colors of the source. +The hotspot defines the point on the cursor that is reported +when a pointer event occurs. +There may be limitations imposed by the hardware on +cursors as to size and whether a mask is implemented. +.IN "XQueryBestCursor" +.PN XQueryBestCursor +can be used to find out what sizes are possible. +There is a standard font for creating cursors, but +Xlib provides functions that you can use to create cursors +from an arbitrary font or from bitmaps. +.LP +.sp +To create a cursor from the standard cursor font, use +.PN XCreateFontCursor . +.IN "XCreateFontCursor" "" "@DEF@" +.sM +.FD 0 +#include +.sp 6p +Cursor XCreateFontCursor\^(\^\fIdisplay\fP, \fIshape\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + unsigned int \fIshape\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIshape\fP 1i +Specifies the shape of the cursor. +.LP +.eM +X provides a set of standard cursor shapes in a special font named +cursor. +Applications are encouraged to use this interface for their cursors +because the font can be customized for the individual display type. +The shape argument specifies which glyph of the standard fonts +to use. +.LP +The hotspot comes from the information stored in the cursor font. +The initial colors of a cursor are a black foreground and a white +background (see +.PN XRecolorCursor ). +For further information about cursor shapes, +see appendix B. +.LP +.PN XCreateFontCursor +can generate +.PN BadAlloc +and +.PN BadValue +errors. +.LP +.sp +To create a cursor from font glyphs, use +.PN XCreateGlyphCursor . +.IN "XCreateGlyphCursor" "" "@DEF@" +.sM +.FD 0 +Cursor XCreateGlyphCursor\^(\^\fIdisplay\fP, \fIsource_font\fP\^, \fImask_font\fP\^, \fIsource_char\fP\^, \fImask_char\fP\^, +.br + \fIforeground_color\fP\^, \fIbackground_color\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Font \fIsource_font\fP\^, \fImask_font\fP\^; +.br + unsigned int \fIsource_char\fP\^, \fImask_char\fP\^; +.br + XColor *\fIforeground_color\fP\^; +.br + XColor *\fIbackground_color\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIsource_font\fP 1i +Specifies the font for the source glyph. +.IP \fImask_font\fP 1i +Specifies the font for the mask glyph or +.PN None . +.IP \fIsource_char\fP 1i +Specifies the character glyph for the source. +.IP \fImask_char\fP 1i +Specifies the glyph character for the mask. +.IP \fIforeground_color\fP 1i +Specifies the RGB values for the foreground of the source. +.IP \fIbackground_color\fP 1i +Specifies the RGB values for the background of the source. +.LP +.eM +The +.PN XCreateGlyphCursor +function is similar to +.PN XCreatePixmapCursor +except that the source and mask bitmaps are obtained from the specified +font glyphs. +The source_char must be a defined glyph in source_font, +or a +.PN BadValue +error results. +If mask_font is given, +mask_char must be a defined glyph in mask_font, +or a +.PN BadValue +error results. +The mask_font and character are optional. +The origins of the source_char and mask_char (if defined) glyphs are +positioned coincidently and define the hotspot. +The source_char and mask_char need not have the same bounding box metrics, +and there is no restriction on the placement of the hotspot relative to the bounding +boxes. +If no mask_char is given, all pixels of the source are displayed. +You can free the fonts immediately by calling +.PN XFreeFont +if no further explicit references to them are to be made. +.LP +For 2-byte matrix fonts, +the 16-bit value should be formed with the byte1 +member in the most significant byte and the byte2 member in the +least significant byte. +.LP +.PN XCreateGlyphCursor +can generate +.PN BadAlloc , +.PN BadFont , +and +.PN BadValue +errors. +.LP +.sp +To create a cursor from two bitmaps, +use +.PN XCreatePixmapCursor . +.IN "XCreatePixmapCursor" "" "@DEF@" +.sM +.FD 0 +Cursor XCreatePixmapCursor\^(\^\fIdisplay\fP, \fIsource\fP\^, \fImask\fP\^, \fIforeground_color\fP\^, \fIbackground_color\fP\^, \fIx\fP\^, \fIy\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Pixmap \fIsource\fP\^; +.br + Pixmap \fImask\fP\^; +.br + XColor *\fIforeground_color\fP\^; +.br + XColor *\fIbackground_color\fP\^; +.br + unsigned int \fIx\fP\^, \fIy\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIsource\fP 1i +Specifies the shape of the source cursor. +.\" *** JIM: NEED TO CHECK THIS. *** +.IP \fImask\fP 1i +Specifies the cursor's source bits to be displayed or +.PN None . +.IP \fIforeground_color\fP 1i +Specifies the RGB values for the foreground of the source. +.IP \fIbackground_color\fP 1i +Specifies the RGB values for the background of the source. +.ds Xy , which indicate the hotspot relative to the source's origin +.IP \fIx\fP 1i +.br +.ns +.IP \fIy\fP 1i +Specify the x and y coordinates\*(Xy. +.LP +.eM +The +.PN XCreatePixmapCursor +function creates a cursor and returns the cursor ID associated with it. +The foreground and background RGB values must be specified using +foreground_color and background_color, +even if the X server only has a +.PN StaticGray +or +.PN GrayScale +screen. +The foreground color is used for the pixels set to 1 in the +source, and the background color is used for the pixels set to 0. +Both source and mask, if specified, must have depth one (or a +.PN BadMatch +error results) but can have any root. +The mask argument defines the shape of the cursor. +The pixels set to 1 in the mask define which source pixels are displayed, +and the pixels set to 0 define which pixels are ignored. +If no mask is given, +all pixels of the source are displayed. +The mask, if present, must be the same size as the pixmap defined by the +source argument, or a +.PN BadMatch +error results. +The hotspot must be a point within the source, +or a +.PN BadMatch +error results. +.LP +The components of the cursor can be transformed arbitrarily to meet +display limitations. +The pixmaps can be freed immediately if no further explicit references +to them are to be made. +Subsequent drawing in the source or mask pixmap has an undefined effect on the +cursor. +The X server might or might not make a copy of the pixmap. +.LP +.PN XCreatePixmapCursor +can generate +.PN BadAlloc +and +.PN BadPixmap +errors. +.LP +.sp +To determine useful cursor sizes, use +.PN XQueryBestCursor . +.IN "XQueryBestCursor" "" "@DEF@" +.sM +.FD 0 +Status XQueryBestCursor\^(\^\fIdisplay\fP, \fId\fP, \fIwidth\fP\^, \fIheight\fP\^, \fIwidth_return\fP\^, \fIheight_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fId\fP\^; +.br + unsigned int \fIwidth\fP\^, \fIheight\fP\^; +.br + unsigned int *\fIwidth_return\fP\^, *\fIheight_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.ds Dr , which indicates the screen +.IP \fId\fP 1i +Specifies the drawable\*(Dr. +.ds Wh \ of the cursor that you want the size information for +.IP \fIwidth\fP 1i +.br +.ns +.IP \fIheight\fP 1i +Specify the width and height\*(Wh. +.IP \fIwidth_return\fP 1i +.br +.ns +.IP \fIheight_return\fP 1i +Return the best width and height that is closest to the specified width +and height. +.LP +.eM +Some displays allow larger cursors than other displays. +The +.PN XQueryBestCursor +function provides a way to find out what size cursors are actually +possible on the display. +.IN "Cursor" "limitations" +It returns the largest size that can be displayed. +Applications should be prepared to use smaller cursors on displays that +cannot support large ones. +.LP +.PN XQueryBestCursor +can generate a +.PN BadDrawable +error. +.LP +.sp +To change the color of a given cursor, use +.PN XRecolorCursor . +.IN "XRecolorCursor" "" "@DEF@" +.sM +.FD 0 +XRecolorCursor\^(\^\fIdisplay\fP, \fIcursor\fP\^, \fIforeground_color\fP\^, \fIbackground_color\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Cursor \fIcursor\fP\^; +.br + XColor *\fIforeground_color\fP\^, *\fIbackground_color\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIcursor\fP 1i +Specifies the cursor. +.IP \fIforeground_color\fP 1i +Specifies the RGB values for the foreground of the source. +.IP \fIbackground_color\fP 1i +Specifies the RGB values for the background of the source. +.LP +.eM +The +.PN XRecolorCursor +function changes the color of the specified cursor, and +if the cursor is being displayed on a screen, +the change is visible immediately. +The pixel members of the +.PN XColor +structures are ignored; only the RGB values are used. +.LP +.PN XRecolorCursor +can generate a +.PN BadCursor +error. +.LP +.sp +To free (destroy) a given cursor, use +.PN XFreeCursor . +.IN "XFreeCursor" "" "@DEF@" +.sM +.FD 0 +XFreeCursor\^(\^\fIdisplay\fP, \fIcursor\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Cursor \fIcursor\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIcursor\fP 1i +Specifies the cursor. +.LP +.eM +The +.PN XFreeCursor +function deletes the association between the cursor resource ID +and the specified cursor. +The cursor storage is freed when no other resource references it. +The specified cursor ID should not be referred to again. +.LP +.PN XFreeCursor +can generate a +.PN BadCursor +error. +.bp diff --git a/libX11/specs/libX11/CH06 b/libX11/specs/libX11/CH06 new file mode 100644 index 000000000..44824d324 --- /dev/null +++ b/libX11/specs/libX11/CH06 @@ -0,0 +1,4773 @@ +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be included +.\" in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR +.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +.\" OTHER DEALINGS IN THE SOFTWARE. +.\" +.\" Except as contained in this notice, the name of the X Consortium shall +.\" not be used in advertising or otherwise to promote the sale, use or +.\" other dealings in this Software without prior written authorization +.\" from the X Consortium. +.\" +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by +.\" Digital Equipment Corporation +.\" +.\" Portions Copyright \(co 1990, 1991 by +.\" Tektronix, Inc. +.\" +.\" Permission to use, copy, modify and distribute this documentation for +.\" any purpose and without fee is hereby granted, provided that the above +.\" copyright notice appears in all copies and that both that copyright notice +.\" and this permission notice appear in all copies, and that the names of +.\" Digital and Tektronix not be used in in advertising or publicity pertaining +.\" to this documentation without specific, written prior permission. +.\" Digital and Tektronix makes no representations about the suitability +.\" of this documentation for any purpose. +.\" It is provided ``as is'' without express or implied warranty. +.\" +\& +.sp 1 +.ce 3 +\s+1\fBChapter 6\fP\s-1 + +\s+1\fBColor Management Functions\fP\s-1 +.sp 2 +.nr H1 6 +.nr H2 0 +.nr H3 0 +.nr H4 0 +.nr H5 0 +.na +.LP +.XS +Chapter 6: Color Management Functions +.XE +Each X window always has an associated colormap that +provides a level of indirection between pixel values and colors displayed +on the screen. +Xlib provides functions that you can use to manipulate a colormap. +The X protocol defines colors using values in the RGB color space. +The RGB color space is device dependent; +rendering an RGB value on differing output devices typically results +in different colors. +Xlib also provides a means for clients to specify color using +device-independent color spaces for consistent results across devices. +Xlib supports device-independent color spaces derivable from the CIE XYZ +color space. +This includes the CIE XYZ, xyY, L*u*v*, and L*a*b* color spaces as well as +the TekHVC color space. +.LP +This chapter discusses how to: +.IP \(bu 5 +Create, copy, and destroy a colormap +.IP \(bu 5 +Specify colors by name or value +.IP \(bu 5 +Allocate, modify, and free color cells +.IP \(bu 5 +Read entries in a colormap +.IP \(bu 5 +Convert between color spaces +.IP \(bu 5 +Control aspects of color conversion +.IP \(bu 5 +Query the color gamut of a screen +.IP \(bu 5 +Add new color spaces +.LP +All functions, types, and symbols in this chapter with the prefix ``Xcms'' +are defined in +.hN X11/Xcms.h . +The remaining functions and types are defined in +.hN X11/Xlib.h . +.LP +Functions in this chapter manipulate the representation of color on the +screen. +For each possible value that a pixel can take in a window, +there is a color cell in the colormap. +For example, +if a window is 4 bits deep, pixel values 0 through 15 are defined. +A colormap is a collection of color cells. +A color cell consists of a triple of red, green, and blue (RGB) values. +The hardware imposes limits on the number of significant +bits in these values. +As each pixel is read out of display memory, the pixel +is looked up in a colormap. +The RGB value of the cell determines what color is displayed on the screen. +On a grayscale display with a black-and-white monitor, +the values are combined to determine the brightness on the screen. +.LP +Typically, an application allocates color cells or sets of color cells +to obtain the desired colors. +The client can allocate read-only cells. +In which case, +the pixel values for these colors can be shared among multiple applications, +and the RGB value of the cell cannot be changed. +If the client allocates read/write cells, +they are exclusively owned by the client, +and the color associated with the pixel value can be changed at will. +Cells must be allocated (and, if read/write, initialized with an RGB value) +by a client to obtain desired colors. +The use of pixel value for an +unallocated cell results in an undefined color. +.LP +Because colormaps are associated with windows, X supports displays +with multiple colormaps and, indeed, different types of colormaps. +If there are insufficient colormap resources in the display, +some windows will display in their true colors, and others +will display with incorrect colors. +A window manager usually controls which windows are displayed +in their true colors if more than one colormap is required for +the color resources the applications are using. +At any time, there is a set of installed colormaps for a screen. +Windows using one of the installed colormaps display with true colors, and +windows using other colormaps generally display with incorrect colors. +You can control the set of installed colormaps by using +.PN XInstallColormap +and +.PN XUninstallColormap . +.LP +Colormaps are local to a particular screen. +Screens always have a default colormap, +and programs typically allocate cells out of this colormap. +Generally, you should not write applications that monopolize +color resources. +Although some hardware supports multiple colormaps installed at one time, +many of the hardware displays +built today support only a single installed colormap, so the primitives +are written to encourage sharing of colormap entries between applications. +.LP +The +.PN DefaultColormap +macro returns the default colormap. +The +.PN DefaultVisual +macro +returns the default visual type for the specified screen. +.IN "Color map" +Possible visual types are +.PN StaticGray , +.PN GrayScale , +.PN StaticColor , +.PN PseudoColor , +.PN TrueColor , +or +.PN DirectColor +(see section 3.1). +.NH 2 +Color Structures +.XS +\*(SN Color Structures +.XE +.LP +Functions that operate only on RGB color space values use an +.PN XColor +structure, which contains: +.LP +.IN "XColor" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef struct { + unsigned long pixel; /* pixel value */ + unsigned short red, green, blue; /* rgb values */ + char flags; /* DoRed, DoGreen, DoBlue */ + char pad; +} XColor; +.De +.LP +.eM +The red, green, and blue values are always in the range 0 to 65535 +inclusive, independent of the number of bits actually used in the +display hardware. +The server scales these values down to the range used by the hardware. +Black is represented by (0,0,0), +and white is represented by (65535,65535,65535). +.IN "Color" +In some functions, +the flags member controls which of the red, green, and blue members is used +and can be the inclusive OR of zero or more of +.PN DoRed , +.PN DoGreen , +and +.PN DoBlue . +.LP +.sp +Functions that operate on all color space values use an +.PN XcmsColor +structure. +This structure contains a union of substructures, +each supporting color specification encoding for a particular color space. +Like the +.PN XColor +structure, the +.PN XcmsColor +structure contains pixel +and color specification information (the spec member in the +.PN XcmsColor +structure). +.IN "XcmsColor" "" "@DEF@" +.sM +.LP +.Ds 0 +.TA .5i 1i 2.5i +.ta .5i 1i 2.5i +typedef unsigned long XcmsColorFormat; /* Color Specification Format */ + +typedef struct { + union { + XcmsRGB RGB; + XcmsRGBi RGBi; + XcmsCIEXYZ CIEXYZ; + XcmsCIEuvY CIEuvY; + XcmsCIExyY CIExyY; + XcmsCIELab CIELab; + XcmsCIELuv CIELuv; + XcmsTekHVC TekHVC; + XcmsPad Pad; + } spec; + unsigned long pixel; + XcmsColorFormat format; +} XcmsColor; /* Xcms Color Structure */ +.De +.LP +.eM +Because the color specification can be encoded for the various color spaces, +encoding for the spec member is identified by the format member, +which is of type +.PN XcmsColorFormat . +The following macros define standard formats. +.sM +.TS +lw(.5i) lw(1.6i) lw(1.4i) lw(1.5i). +T{ +#define +T} T{ +.PN XcmsUndefinedFormat +T} T{ +0x00000000 +T} +T{ +#define +T} T{ +.PN XcmsCIEXYZFormat +T} T{ +0x00000001 +T} T{ +/* CIE XYZ */ +T} +T{ +#define +T} T{ +.PN XcmsCIEuvYFormat +T} T{ +0x00000002 +T} T{ +/* CIE u'v'Y */ +T} +T{ +#define +T} T{ +.PN XcmsCIExyYFormat +T} T{ +0x00000003 +T} T{ +/* CIE xyY */ +T} +T{ +#define +T} T{ +.PN XcmsCIELabFormat +T} T{ +0x00000004 +T} T{ +/* CIE L*a*b* */ +T} +T{ +#define +T} T{ +.PN XcmsCIELuvFormat +T} T{ +0x00000005 +T} T{ +/* CIE L*u*v* */ +T} +T{ +#define +T} T{ +.PN XcmsTekHVCFormat +T} T{ +0x00000006 +T} T{ +/* TekHVC */ +T} +T{ +#define +T} T{ +.PN XcmsRGBFormat +T} T{ +0x80000000 +T} T{ +/* RGB Device */ +T} +T{ +#define +T} T{ +.PN XcmsRGBiFormat +T} T{ +0x80000001 +T} T{ +/* RGB Intensity */ +T} +.TE +.LP +.eM +Formats for device-independent color spaces are +distinguishable from those for device-dependent spaces by the 32nd bit. +If this bit is set, +it indicates that the color specification is in a device-dependent form; +otherwise, it is in a device-independent form. +If the 31st bit is set, +this indicates that the color space has been added to Xlib at run time +(see section 6.12.4). +The format value for a color space added at run time may be different each +time the program is executed. +If references to such a color space must be made outside the client +(for example, storing a color specification in a file), +then reference should be made by color space string prefix +(see +.PN XcmsFormatOfPrefix +and +.PN XcmsPrefixOfFormat ). +.LP +Data types that describe the color specification encoding for the various +color spaces are defined as follows: +.sM +.IN "XcmsRGB" "" "@DEF@" +.LP +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef double XcmsFloat; + +typedef struct { + unsigned short red; /* 0x0000 to 0xffff */ + unsigned short green; /* 0x0000 to 0xffff */ + unsigned short blue; /* 0x0000 to 0xffff */ +} XcmsRGB; /* RGB Device */ +.De +.IN "XcmsRGBi" "" "@DEF@" +.LP +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef struct { + XcmsFloat red; /* 0.0 to 1.0 */ + XcmsFloat green; /* 0.0 to 1.0 */ + XcmsFloat blue; /* 0.0 to 1.0 */ +} XcmsRGBi; /* RGB Intensity */ +.De +.IN "XcmsCIEXYZ" "" "@DEF@" +.LP +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef struct { + XcmsFloat X; + XcmsFloat Y; /* 0.0 to 1.0 */ + XcmsFloat Z; +} XcmsCIEXYZ; /* CIE XYZ */ +.De +.IN "XcmsCIEuvY" "" "@DEF@" +.LP +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef struct { + XcmsFloat u_prime; /* 0.0 to ~0.6 */ + XcmsFloat v_prime; /* 0.0 to ~0.6 */ + XcmsFloat Y; /* 0.0 to 1.0 */ +} XcmsCIEuvY; /* CIE u'v'Y */ +.De +.IN "XcmsCIExyY" "" "@DEF@" +.LP +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef struct { + XcmsFloat x; /* 0.0 to ~.75 */ + XcmsFloat y; /* 0.0 to ~.85 */ + XcmsFloat Y; /* 0.0 to 1.0 */ +} XcmsCIExyY; /* CIE xyY */ +.De +.IN "XcmsCIELab" "" "@DEF@" +.LP +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef struct { + XcmsFloat L_star; /* 0.0 to 100.0 */ + XcmsFloat a_star; + XcmsFloat b_star; +} XcmsCIELab; /* CIE L*a*b* */ +.De +.IN "XcmsCIELuv" "" "@DEF@" +.LP +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef struct { + XcmsFloat L_star; /* 0.0 to 100.0 */ + XcmsFloat u_star; + XcmsFloat v_star; +} XcmsCIELuv; /* CIE L*u*v* */ +.De +.IN "XcmsTekHVC" "" "@DEF@" +.LP +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef struct { + XcmsFloat H; /* 0.0 to 360.0 */ + XcmsFloat V; /* 0.0 to 100.0 */ + XcmsFloat C; /* 0.0 to 100.0 */ +} XcmsTekHVC; /* TekHVC */ +.De +.IN "XcmsPad" "" "@DEF@" +.LP +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef struct { + XcmsFloat pad0; + XcmsFloat pad1; + XcmsFloat pad2; + XcmsFloat pad3; +} XcmsPad; /* four doubles */ +.De +.LP +.eM +The device-dependent formats provided allow color specification in: +.IP \(bu 5 +RGB Intensity +.Pn ( XcmsRGBi ) +.IP +Red, green, and blue linear intensity values, +floating-point values from 0.0 to 1.0, +where 1.0 indicates full intensity, 0.5 half intensity, and so on. +.IP \(bu 5 +RGB Device +.Pn ( XcmsRGB ) +.IP +Red, green, and blue values appropriate for the specified output device. +.PN XcmsRGB +values are of type unsigned short, +scaled from 0 to 65535 inclusive, +and are interchangeable with the red, green, and blue values in an +.PN XColor +structure. +.LP +It is important to note that RGB Intensity values are not gamma corrected +values. +In contrast, +RGB Device values generated as a result of converting color specifications +are always gamma corrected, and +RGB Device values acquired as a result of querying a colormap +or passed in by the client are assumed by Xlib to be gamma corrected. +The term \fIRGB value\fP in this manual always refers to an RGB Device value. +.NH 2 +Color Strings +.XS +\*(SN Color Strings +.XE +.LP +Xlib provides a mechanism for using string names for colors. +A color string may either contain an abstract color name +or a numerical color specification. +Color strings are case-insensitive. +.LP +Color strings are used in the following functions: +.IP \(bu 5 +.PN XAllocNamedColor +.IP \(bu 5 +.PN XcmsAllocNamedColor +.IP \(bu 5 +.PN XLookupColor +.IP \(bu 5 +.PN XcmsLookupColor +.IP \(bu 5 +.PN XParseColor +.IP \(bu 5 +.PN XStoreNamedColor +.LP +Xlib supports the use of abstract color names, for example, red or blue. +A value for this abstract name is obtained by searching one or more color +name databases. +Xlib first searches zero or more client-side databases; +the number, location, and content of these databases is +implementation-dependent and might depend on the current locale. +If the name is not found, Xlib then looks for the color in the +X server's database. +If the color name is not in the Host Portable Character Encoding, +the result is implementation-dependent. +.LP +A numerical color specification +consists of a color space name and a set of values in the following syntax: +.LP +.sM +.Ds 0 +\fI\fP:\fI/.../\fP +.De +.LP +.eM +The following are examples of valid color strings. +.LP +.Ds 0 +"CIEXYZ:0.3227/0.28133/0.2493" +"RGBi:1.0/0.0/0.0" +"rgb:00/ff/00" +"CIELuv:50.0/0.0/0.0" +.De +The syntax and semantics of numerical specifications are given +for each standard color space in the following sections. +.NH 3 +RGB Device String Specification +.XS +\*(SN RGB Device String Specification +.XE +.LP +An RGB Device specification is identified by +the prefix ``rgb:'' and conforms to the following syntax: +.LP +.\" Start marker code here +.Ds 0 +rgb:\fI//\fP + + \fI\fP, \fI\fP, \fI\fP := \fIh\fP | \fIhh\fP | \fIhhh\fP | \fIhhhh\fP + \fIh\fP := single hexadecimal digits (case insignificant) +.De +.\" End marker code here +.LP +Note that \fIh\fP indicates the value scaled in 4 bits, +\fIhh\fP the value scaled in 8 bits, +\fIhhh\fP the value scaled in 12 bits, +and \fIhhhh\fP the value scaled in 16 bits, respectively. +.LP +Typical examples are the strings ``rgb:ea/75/52'' and ``rgb:ccc/320/320'', +but mixed numbers of hexadecimal digit strings +(``rgb:ff/a5/0'' and ``rgb:ccc/32/0'') +are also allowed. +.LP +For backward compatibility, an older syntax for RGB Device is +supported, but its continued use is not encouraged. +The syntax is an initial sharp sign character followed by +a numeric specification, in one of the following formats: +.LP +.\" Start marker code here +.Ds 0 +.TA 2i +.ta 2i +#RGB (4 bits each) +#RRGGBB (8 bits each) +#RRRGGGBBB (12 bits each) +#RRRRGGGGBBBB (16 bits each) +.De +.\" End marker code here +.LP +The R, G, and B represent single hexadecimal digits. +When fewer than 16 bits each are specified, +they represent the most significant bits of the value +(unlike the ``rgb:'' syntax, in which values are scaled). +For example, the string ``#3a7'' is the same as ``#3000a0007000''. +.NH 3 +RGB Intensity String Specification +.XS +\*(SN RGB Intensity String Specification +.XE +.LP +An RGB intensity specification is identified +by the prefix ``rgbi:'' and conforms to the following syntax: +.LP +.\" Start marker code here +.Ds 0 +rgbi:\fI//\fP +.De +.\" End marker code here +.LP +Note that red, green, and blue are floating-point values +between 0.0 and 1.0, inclusive. +The input format for these values is an optional sign, +a string of numbers possibly containing a decimal point, +and an optional exponent field containing an E or e +followed by a possibly signed integer string. +.NH 3 +Device-Independent String Specifications +.XS +\*(SN Device-Independent String Specifications +.XE +.LP +The standard device-independent string specifications have +the following syntax: +.LP +.\" Start marker code here +.Ds 0 +CIEXYZ:\fI//\fP +CIEuvY:\fI//\fP +CIExyY:\fI//\fP +CIELab:\fI//\fP +CIELuv:\fI//\fP +TekHVC:\fI//\fP +.De +.\" End marker code here +.LP +All of the values (C, H, V, X, Y, Z, a, b, u, v, y, x) are +floating-point values. +The syntax for these values is an optional plus or minus sign, +a string of digits possibly containing a decimal point, +and an optional exponent field consisting of an ``E'' or ``e'' +followed by an optional plus or minus followed by a string of digits. +.NH 2 +Color Conversion Contexts and Gamut Mapping +.XS +\*(SN Color Conversion Contexts and Gamut Mapping +.XE +.LP +When Xlib converts device-independent color specifications +into device-dependent specifications and vice versa, +it uses knowledge about the color limitations of the screen hardware. +This information, typically called the device profile, +.IN "Device profile" +is available in a Color Conversion Context (CCC). +.IN "Color Conversion Context" +.IN "CCC" +.LP +Because a specified color may be outside the color gamut of the target screen +and the white point associated with the color specification may differ +from the white point inherent to the screen, +Xlib applies gamut mapping when it encounters certain conditions: +.IN "White point" +.IP \(bu 5 +Gamut compression occurs when conversion of device-independent +color specifications to device-dependent color specifications +results in a color out of the target screen's gamut. +.IP \(bu 5 +White adjustment occurs when the inherent white point of the screen +differs from the white point assumed by the client. +.LP +Gamut handling methods are stored as callbacks in the CCC, +which in turn are used by the color space conversion routines. +Client data is also stored in the CCC for each callback. +The CCC also contains the white point the client assumes to be +associated with color specifications (that is, the Client White Point). +.IN "Client White Point" +.IN "Gamut compression" +.IN "Gamut handling" +.IN "White point adjustment" +The client can specify the gamut handling callbacks and client data +as well as the Client White Point. +Xlib does not preclude the X client from performing other +forms of gamut handling (for example, gamut expansion); +however, Xlib does not provide direct support for gamut handling +other than white adjustment and gamut compression. +.LP +Associated with each colormap is an initial CCC transparently generated by +Xlib. +.IN "Color Conversion Context" "creation" +Therefore, +when you specify a colormap as an argument to an Xlib function, +you are indirectly specifying a CCC. +.IN "CCC" "of colormap" +.IN "Color Conversion Context" "of colormap" +There is a default CCC associated with each screen. +Newly created CCCs inherit attributes from the default CCC, +so the default CCC attributes can be modified to affect new CCCs. +.IN "CCC" "default" +.IN "Color Conversion Context" "default" +.LP +Xcms functions in which gamut mapping can occur return +.PN Status +and have specific status values defined for them, +as follows: +.IP \(bu 5 +.PN XcmsFailure +indicates that the function failed. +.IP \(bu 5 +.PN XcmsSuccess +indicates that the function succeeded. +In addition, +if the function performed any color conversion, +the colors did not need to be compressed. +.IP \(bu 5 +.PN XcmsSuccessWithCompression +indicates the function performed color conversion +and at least one of the colors needed to be compressed. +The gamut compression method is determined by the gamut compression +procedure in the CCC that is specified directly as a function argument +or in the CCC indirectly specified by means of the colormap argument. +.NH 2 +Creating, Copying, and Destroying Colormaps +.XS +\*(SN Creating, Copying, and Destroying Colormaps +.XE +.LP +To create a colormap for a screen, use +.PN XCreateColormap . +.IN "XCreateColormap" "" "@DEF@" +.sM +.FD 0 +Colormap XCreateColormap\^(\^\fIdisplay\fP, \fIw\fP\^, \fIvisual\fP\^, \fIalloc\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + Visual *\fIvisual\fP\^; +.br + int \fIalloc\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.ds Wi on whose screen you want to create a colormap +.IP \fIw\fP 1i +Specifies the window \*(Wi. +.IP \fIvisual\fP 1i +Specifies a visual type supported on the screen. +If the visual type is not one supported by the screen, +a +.PN BadMatch +error results. +.IP \fIalloc\fP 1i +Specifies the colormap entries to be allocated. +You can pass +.PN AllocNone +or +.PN AllocAll . +.LP +.eM +The +.PN XCreateColormap +function creates a colormap of the specified visual type for the screen +on which the specified window resides and returns the colormap ID +associated with it. +Note that the specified window is only used to determine the screen. +.LP +The initial values of the colormap entries are undefined for the +visual classes +.PN GrayScale , +.PN PseudoColor , +and +.PN DirectColor . +For +.PN StaticGray , +.PN StaticColor , +and +.PN TrueColor , +the entries have defined values, +but those values are specific to the visual and are not defined by X. +For +.PN StaticGray , +.PN StaticColor , +and +.PN TrueColor , +alloc must be +.PN AllocNone , +or a +.PN BadMatch +error results. +For the other visual classes, +if alloc is +.PN AllocNone , +the colormap initially has no allocated entries, +and clients can allocate them. +For information about the visual types, +see section 3.1. +.LP +If alloc is +.PN AllocAll , +the entire colormap is allocated writable. +The initial values of all allocated entries are undefined. +For +.PN GrayScale +and +.PN PseudoColor , +the effect is as if an +.PN XAllocColorCells +call returned all pixel values from zero to N \- 1, +where N is the colormap entries value in the specified visual. +For +.PN DirectColor , +the effect is as if an +.PN XAllocColorPlanes +call returned a pixel value of zero and red_mask, green_mask, +and blue_mask values containing the same bits as the corresponding +masks in the specified visual. +However, in all cases, +none of these entries can be freed by using +.PN XFreeColors . +.LP +.PN XCreateColormap +can generate +.PN BadAlloc , +.PN BadMatch , +.PN BadValue , +and +.PN BadWindow +errors. +.LP +.sp +To create a new colormap when the allocation out of a previously +shared colormap has failed because of resource exhaustion, use +.PN XCopyColormapAndFree . +.IN "XCopyColormapAndFree" "" "@DEF@" +.sM +.FD 0 +Colormap XCopyColormapAndFree\^(\^\fIdisplay\fP, \fIcolormap\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Colormap \fIcolormap\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIcolormap\fP 1i +Specifies the colormap. +.LP +.eM +The +.PN XCopyColormapAndFree +function creates a colormap of the same visual type and for the same screen +as the specified colormap and returns the new colormap ID. +It also moves all of the client's existing allocation from the specified +colormap to the new colormap with their color values intact +and their read-only or writable characteristics intact and frees those entries +in the specified colormap. +Color values in other entries in the new colormap are undefined. +If the specified colormap was created by the client with alloc set to +.PN AllocAll , +the new colormap is also created with +.PN AllocAll , +all color values for all entries are copied from the specified colormap, +and then all entries in the specified colormap are freed. +If the specified colormap was not created by the client with +.PN AllocAll , +the allocations to be moved are all those pixels and planes +that have been allocated by the client using +.PN XAllocColor , +.PN XAllocNamedColor , +.PN XAllocColorCells , +or +.PN XAllocColorPlanes +and that have not been freed since they were allocated. +.LP +.PN XCopyColormapAndFree +can generate +.PN BadAlloc +and +.PN BadColor +errors. +.LP +.sp +To destroy a colormap, use +.PN XFreeColormap . +.IN "XFreeColormap" "" "@DEF@" +.sM +.FD 0 +XFreeColormap\^(\^\fIdisplay\fP, \fIcolormap\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Colormap \fIcolormap\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.ds Cm that you want to destroy +.IP \fIcolormap\fP 1i +Specifies the colormap \*(Cm. +.LP +.eM +The +.PN XFreeColormap +function deletes the association between the colormap resource ID +and the colormap and frees the colormap storage. +However, this function has no effect on the default colormap for a screen. +If the specified colormap is an installed map for a screen, +it is uninstalled (see +.PN XUninstallColormap ). +If the specified colormap is defined as the colormap for a window (by +.PN XCreateWindow , +.PN XSetWindowColormap , +or +.PN XChangeWindowAttributes ), +.PN XFreeColormap +changes the colormap associated with the window to +.PN None +and generates a +.PN ColormapNotify +event. +X does not define the colors displayed for a window with a colormap of +.PN None . +.LP +.PN XFreeColormap +can generate a +.PN BadColor +error. +.NH 2 +Mapping Color Names to Values +.XS +\*(SN Mapping Color Names to Values +.XE +.LP +.sp +To map a color name to an RGB value, use +.PN XLookupColor . +.IN "Color" "naming" +.IN "XLookupColor" "" "@DEF@" +.sM +.FD 0 +Status XLookupColor\^(\^\fIdisplay\fP, \fIcolormap\fP, \fIcolor_name\fP, \ +\fIexact_def_return\fP\^, \fIscreen_def_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Colormap \fIcolormap\fP\^; +.br + char *\fIcolor_name\fP\^; +.br + XColor *\fIexact_def_return\fP\^, *\fIscreen_def_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIcolormap\fP 1i +Specifies the colormap. +.IP \fIcolor_name\fP 1i +Specifies the color name string (for example, red) whose color +definition structure you want returned. +.IP \fIexact_def_return\fP 1i +Returns the exact RGB values. +.IP \fIscreen_def_return\fP 1i +Returns the closest RGB values provided by the hardware. +.LP +.eM +The +.PN XLookupColor +function looks up the string name of a color with respect to the screen +associated with the specified colormap. +It returns both the exact color values and +the closest values provided by the screen +with respect to the visual type of the specified colormap. +If the color name is not in the Host Portable Character Encoding, +the result is implementation-dependent. +Use of uppercase or lowercase does not matter. +.PN XLookupColor +returns nonzero if the name is resolved; +otherwise, it returns zero. +.LP +.PN XLookupColor +can generate a +.PN BadColor +error. +.LP +.sp +To map a color name to the exact RGB value, use +.PN XParseColor . +.IN "Color" "naming" +.IN "XParseColor" "" "@DEF@" +.sM +.FD 0 +Status XParseColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \^\fIspec\fP\^, \fIexact_def_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Colormap \fIcolormap\fP\^; +.br + char *\fIspec\fP\^; +.br + XColor *\fIexact_def_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIcolormap\fP 1i +Specifies the colormap. +.IP \fIspec\fP 1i +Specifies the color name string; +case is ignored. +.IP \fIexact_def_return\fP 1i +Returns the exact color value for later use and sets the +.PN DoRed , +.PN DoGreen , +and +.PN DoBlue +flags. +.LP +.eM +The +.PN XParseColor +function looks up the string name of a color with respect to the screen +associated with the specified colormap. +It returns the exact color value. +If the color name is not in the Host Portable Character Encoding, +the result is implementation-dependent. +Use of uppercase or lowercase does not matter. +.PN XParseColor +returns nonzero if the name is resolved; +otherwise, it returns zero. +.LP +.PN XParseColor +can generate a +.PN BadColor +error. +.LP +.sp +To map a color name to a value in an arbitrary color space, use +.PN XcmsLookupColor . +.IN "Color" "naming" +.IN "XcmsLookupColor" "" "@DEF@" +.sM +.FD 0 +Status XcmsLookupColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcolor_string\fP\^, \fIcolor_exact_return\fP\^, \fIcolor_screen_return\fP\^, +.br + \fIresult_format\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Colormap \fIcolormap\fP\^; +.br + char *\fIcolor_string\fP\^; +.br + XcmsColor *\fIcolor_exact_return\fP\^, *\fIcolor_screen_return\fP\^; +.br + XcmsColorFormat \fIresult_format\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIcolormap\fP 1i +Specifies the colormap. +.ds St +.IP \fIcolor_string\fP 1i +Specifies the color string\*(St. +.IP \fIcolor_exact_return\fP 1i +Returns the color specification parsed from the color string +or parsed from the corresponding string found in a color-name database. +.IP \fIcolor_screen_return\fP 1i +Returns the color that can be reproduced on the screen. +.IP \fIresult_format\fP 1i +Specifies the color format for the returned color +specifications (color_screen_return and color_exact_return arguments). +If the format is +.PN XcmsUndefinedFormat +and the color string contains a +numerical color specification, +the specification is returned in the format used in that numerical +color specification. +If the format is +.PN XcmsUndefinedFormat +and the color string contains a color name, +the specification is returned in the format used +to store the color in the database. +.LP +.eM +The +.PN XcmsLookupColor +function looks up the string name of a color with respect to the screen +associated with the specified colormap. +It returns both the exact color values and +the closest values provided by the screen +with respect to the visual type of the specified colormap. +The values are returned in the format specified by result_format. +If the color name is not in the Host Portable Character Encoding, +the result is implementation-dependent. +Use of uppercase or lowercase does not matter. +.PN XcmsLookupColor +returns +.PN XcmsSuccess +or +.PN XcmsSuccessWithCompression +if the name is resolved; otherwise, it returns +.PN XcmsFailure . +If +.PN XcmsSuccessWithCompression +is returned, the color specification returned in +color_screen_return is the result of gamut compression. +.NH 2 +Allocating and Freeing Color Cells +.XS +\*(SN Allocating and Freeing Color Cells +.XE +.LP +There are two ways of allocating color cells: +explicitly as read-only entries, one pixel value at a time, +or read/write, +where you can allocate a number of color cells and planes simultaneously. +.IN "Read-only colormap cells" +A read-only cell has its RGB value set by the server. +.IN "Read/write colormap cells" +Read/write cells do not have defined colors initially; +functions described in the next section must be used to store values into them. +Although it is possible for any client to store values into a read/write +cell allocated by another client, +read/write cells normally should be considered private to the client +that allocated them. +.LP +Read-only colormap cells are shared among clients. +The server counts each allocation and freeing of the cell by clients. +When the last client frees a shared cell, the cell is finally deallocated. +If a single client allocates the same read-only cell multiple +times, the server counts each such allocation, not just the first one. +.LP +.sp +To allocate a read-only color cell with an RGB value, use +.PN XAllocColor . +.IN "Allocation" "read-only colormap cells" +.IN "Read-only colormap cells" "allocating" +.IN "Color" "allocation" +.IN "XAllocColor" "" "@DEF@" +.sM +.FD 0 +Status XAllocColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIscreen_in_out\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Colormap \fIcolormap\fP\^; +.br + XColor *\fIscreen_in_out\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIcolormap\fP 1i +Specifies the colormap. +.IP \fIscreen_in_out\fP 1i +Specifies and returns the values actually used in the colormap. +.LP +.eM +The +.PN XAllocColor +function allocates a read-only colormap entry corresponding to the closest +RGB value supported by the hardware. +.PN XAllocColor +returns the pixel value of the color closest to the specified +RGB elements supported by the hardware +and returns the RGB value actually used. +The corresponding colormap cell is read-only. +In addition, +.PN XAllocColor +returns nonzero if it succeeded or zero if it failed. +.IN "Color map" +.IN "Color" "allocation" +.IN "Allocation" "colormap" +.IN "read-only colormap cells" +Multiple clients that request the same effective RGB value can be assigned +the same read-only entry, thus allowing entries to be shared. +When the last client deallocates a shared cell, it is deallocated. +.PN XAllocColor +does not use or affect the flags in the +.PN XColor +structure. +.LP +.PN XAllocColor +can generate a +.PN BadColor +error. +.EQ +delim %% +.EN +.LP +.sp +To allocate a read-only color cell with a color in arbitrary format, use +.PN XcmsAllocColor . +.IN "Allocation" "read-only colormap cells" +.IN "Read-only colormap cells" "allocating" +.IN "Color" "allocation" +.IN "XcmsAllocColor" "" "@DEF@" +.sM +.FD 0 +Status XcmsAllocColor\^(\^\fIdisplay\fP\^, \fIcolormap\fP\^, \fIcolor_in_out\fP\^, \fIresult_format\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Colormap \fIcolormap\fP\^; +.br + XcmsColor *\fIcolor_in_out\fP\^; +.br + XcmsColorFormat \fIresult_format\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIcolormap\fP 1i +Specifies the colormap. +.IP \fIcolor_in_out\fP 1i +Specifies the color to allocate and returns the pixel and color +that is actually used in the colormap. +.IP \fIresult_format\fP 1i +Specifies the color format for the returned color specification. +.LP +.eM +The +.PN XcmsAllocColor +function is similar to +.PN XAllocColor +except the color can be specified in any format. +The +.PN XcmsAllocColor +function ultimately calls +.PN XAllocColor +to allocate a read-only color cell (colormap entry) with the specified color. +.PN XcmsAllocColor +first converts the color specified +to an RGB value and then passes this to +.PN XAllocColor . +.PN XcmsAllocColor +returns the pixel value of the color cell and the color specification +actually allocated. +This returned color specification is the result of converting the RGB value +returned by +.PN XAllocColor +into the format specified with the result_format argument. +If there is no interest in a returned color specification, +unnecessary computation can be bypassed if result_format is set to +.PN XcmsRGBFormat . +The corresponding colormap cell is read-only. +If this routine returns +.PN XcmsFailure , +the color_in_out color specification is left unchanged. +.LP +.PN XcmsAllocColor +can generate a +.PN BadColor +error. +.LP +.sp +To allocate a read-only color cell using a color name and return the closest +color supported by the hardware in RGB format, use +.PN XAllocNamedColor . +.IN "Allocation" "read-only colormap cells" +.IN "Read-only colormap cells" "allocating" +.IN "Color" "naming" +.IN "Color" "allocation" +.IN "XAllocNamedColor" "" "@DEF@" +.sM +.FD 0 +Status XAllocNamedColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \ +\fIcolor_name\fP\^, \fIscreen_def_return\fP\^, \fIexact_def_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Colormap \fIcolormap\fP\^; +.br + char *\fIcolor_name\fP\^; +.br + XColor *\fIscreen_def_return\fP\^, *\fIexact_def_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIcolormap\fP 1i +Specifies the colormap. +.IP \fIcolor_name\fP 1i +Specifies the color name string (for example, red) whose color +definition structure you want returned. +.IP \fIscreen_def_return\fP 1i +Returns the closest RGB values provided by the hardware. +.IP \fIexact_def_return\fP 1i +Returns the exact RGB values. +.LP +.eM +The +.PN XAllocNamedColor +function looks up the named color with respect to the screen that is +associated with the specified colormap. +It returns both the exact database definition and +the closest color supported by the screen. +The allocated color cell is read-only. +The pixel value is returned in screen_def_return. +If the color name is not in the Host Portable Character Encoding, +the result is implementation-dependent. +Use of uppercase or lowercase does not matter. +If screen_def_return and exact_def_return +point to the same structure, the pixel field will be set correctly, +but the color values are undefined. +.PN XAllocNamedColor +returns nonzero if a cell is allocated; +otherwise, it returns zero. +.LP +.PN XAllocNamedColor +can generate a +.PN BadColor +error. +.LP +.sp +To allocate a read-only color cell using a color name and return the closest +color supported by the hardware in an arbitrary format, use +.PN XcmsAllocNamedColor . +.IN "Allocation" "read-only colormap cells" +.IN "Read-only colormap cells" "allocating" +.IN "Color" "naming" +.IN "Color" "allocation" +.IN "XcmsAllocNamedColor" "" "@DEF@" +.sM +.FD 0 +Status XcmsAllocNamedColor\^(\^\fIdisplay\fP\^, \fIcolormap\fP\^, \fIcolor_string\fP\^, \fIcolor_screen_return\fP\^, \fIcolor_exact_return\fP\^, +.br + \fIresult_format\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Colormap \fIcolormap\fP\^; +.br + char *\fIcolor_string\fP\^; +.br + XcmsColor *\fIcolor_screen_return\fP\^; +.br + XcmsColor *\fIcolor_exact_return\fP\^; +.br + XcmsColorFormat \fIresult_format\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIcolormap\fP 1i +Specifies the colormap. +.ds St \ whose color definition structure is to be returned +.IP \fIcolor_string\fP 1i +Specifies the color string\*(St. +.IP \fIcolor_screen_return\fP 1i +Returns the pixel value of the color cell and color specification +that actually is stored for that cell. +.IP \fIcolor_exact_return\fP 1i +Returns the color specification parsed from the color string +or parsed from the corresponding string found in a color-name database. +.IP \fIresult_format\fP 1i +Specifies the color format for the returned color +specifications (color_screen_return and color_exact_return arguments). +If the format is +.PN XcmsUndefinedFormat +and the color string contains a +numerical color specification, +the specification is returned in the format used in that numerical +color specification. +If the format is +.PN XcmsUndefinedFormat +and the color string contains a color name, +the specification is returned in the format used +to store the color in the database. +.LP +.eM +The +.PN XcmsAllocNamedColor +function is similar to +.PN XAllocNamedColor +except that the color returned can be in any format specified. +This function +ultimately calls +.PN XAllocColor +to allocate a read-only color cell with +the color specified by a color string. +The color string is parsed into an +.PN XcmsColor +structure (see +.PN XcmsLookupColor ), +converted +to an RGB value, and finally passed to +.PN XAllocColor . +If the color name is not in the Host Portable Character Encoding, +the result is implementation-dependent. +Use of uppercase or lowercase does not matter. +.LP +This function returns both the color specification as a result +of parsing (exact specification) and the actual color specification +stored (screen specification). +This screen specification is the result of converting the RGB value +returned by +.PN XAllocColor +into the format specified in result_format. +If there is no interest in a returned color specification, +unnecessary computation can be bypassed if result_format is set to +.PN XcmsRGBFormat . +If color_screen_return and color_exact_return +point to the same structure, the pixel field will be set correctly, +but the color values are undefined. +.LP +.PN XcmsAllocNamedColor +can generate a +.PN BadColor +error. +.LP +.sp +To allocate read/write color cell and color plane combinations for a +.PN PseudoColor +model, use +.PN XAllocColorCells . +.IN "Read/write colormap cells" "allocating" +.IN "Allocation" "read/write colormap cells" +.IN "Color" "allocation" +.IN "XAllocColorCells" "" "@DEF@" +.sM +.FD 0 +Status XAllocColorCells\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcontig\fP\^, \ +\fIplane_masks_return\fP\^, \fInplanes\fP\^, +.br + \fIpixels_return\fP\^, \fInpixels\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Colormap \fIcolormap\fP\^; +.br + Bool \fIcontig\fP\^; +.br + unsigned long \fIplane_masks_return\fP[\^]\^; +.br + unsigned int \fInplanes\fP\^; +.br + unsigned long \fIpixels_return\fP[\^]\^; +.br + unsigned int \fInpixels\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIcolormap\fP 1i +Specifies the colormap. +.IP \fIcontig\fP 1i +Specifies a Boolean value that indicates whether the planes must be contiguous. +.IP \fIplane_mask_return\fP 1i +Returns an array of plane masks. +.\" *** JIM: NEED MORE INFO FOR THIS. *** +.IP \fInplanes\fP 1i +Specifies the number of plane masks that are to be returned in the plane masks +array. +.IP \fIpixels_return\fP 1i +Returns an array of pixel values. +.IP \fInpixels\fP 1i +Specifies the number of pixel values that are to be returned in the +pixels_return array. +.LP +.eM +.EQ +delim %% +.EN +The +.PN XAllocColorCells +function allocates read/write color cells. +The number of colors must be positive and the number of planes nonnegative, +or a +.PN BadValue +error results. +If ncolors and nplanes are requested, +then ncolors pixels +and nplane plane masks are returned. +No mask will have any bits set to 1 in common with +any other mask or with any of the pixels. +By ORing together each pixel with zero or more masks, +ncolors * %2 sup nplanes% distinct pixels can be produced. +All of these are +allocated writable by the request. +For +.PN GrayScale +or +.PN PseudoColor , +each mask has exactly one bit set to 1. +For +.PN DirectColor , +each has exactly three bits set to 1. +If contig is +.PN True +and if all masks are ORed +together, a single contiguous set of bits set to 1 will be formed for +.PN GrayScale +or +.PN PseudoColor +and three contiguous sets of bits set to 1 (one within each +pixel subfield) for +.PN DirectColor . +The RGB values of the allocated +entries are undefined. +.PN XAllocColorCells +returns nonzero if it succeeded or zero if it failed. +.LP +.PN XAllocColorCells +can generate +.PN BadColor +and +.PN BadValue +errors. +.LP +.sp +To allocate read/write color resources for a +.PN DirectColor +model, use +.PN XAllocColorPlanes . +.IN "Read/write colormap planes" "allocating" +.IN "Allocation" "read/write colormap planes" +.IN "Color" "allocation" +.IN "XAllocColorPlanes" "" "@DEF@" +.sM +.FD 0 +Status XAllocColorPlanes\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcontig\fP\^, \fIpixels_return\fP\^, \fIncolors\fP\^, \fInreds\fP\^, \fIngreens\fP\^, +.br + \fInblues\fP\^, \fIrmask_return\fP\^, \fIgmask_return\fP\^, \fIbmask_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Colormap \fIcolormap\fP\^; +.br + Bool \fIcontig\fP\^; +.br + unsigned long \fIpixels_return\fP[\^]\^; +.br + int \fIncolors\fP\^; +.br + int \fInreds\fP\^, \fIngreens\fP\^, \fInblues\fP\^; +.br + unsigned long *\fIrmask_return\fP\^, *\fIgmask_return\fP\^, *\fIbmask_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIcolormap\fP 1i +Specifies the colormap. +.IP \fIcontig\fP 1i +Specifies a Boolean value that indicates whether the planes must be contiguous. +.IP \fIpixels_return\fP 1i +Returns an array of pixel values. +.PN XAllocColorPlanes +returns the pixel values in this array. +.IP \fIncolors\fP 1i +Specifies the number of pixel values that are to be returned in the +pixels_return array. +.IP \fInreds\fP 1i +.br +.ns +.IP \fIngreens\fP 1i +.br +.ns +.IP \fInblues\fP 1i +.br +.ns +Specify the number of red, green, and blue planes. +The value you pass must be nonnegative. +.IP \fIrmask_return\fP 1i +.br +.ns +.IP \fIgmask_return\fP 1i +.br +.ns +.IP \fIbmask_return\fP 1i +Return bit masks for the red, green, and blue planes. +.LP +.eM +.EQ +delim %% +.EN +The specified ncolors must be positive; +and nreds, ngreens, and nblues must be nonnegative, +or a +.PN BadValue +error results. +If ncolors colors, nreds reds, ngreens greens, and nblues blues are requested, +ncolors pixels are returned; and the masks have nreds, ngreens, and +nblues bits set to 1, respectively. +If contig is +.PN True , +each mask will have +a contiguous set of bits set to 1. +No mask will have any bits set to 1 in common with +any other mask or with any of the pixels. +For +.PN DirectColor , +each mask +will lie within the corresponding pixel subfield. +By ORing together +subsets of masks with each pixel value, +ncolors * %2 sup (nreds+ngreens+nblues)% distinct pixel values can be produced. +All of these are allocated by the request. +However, in the +colormap, there are only ncolors * %2 sup nreds% independent red entries, +ncolors * %2 sup ngreens% independent green entries, +and ncolors * %2 sup nblues% independent blue entries. +This is true even for +.PN PseudoColor . +When the colormap entry of a pixel +value is changed (using +.PN XStoreColors , +.PN XStoreColor , +or +.PN XStoreNamedColor ), +the pixel is decomposed according to the masks, +and the corresponding independent entries are updated. +.PN XAllocColorPlanes +returns nonzero if it succeeded or zero if it failed. +.LP +.PN XAllocColorPlanes +can generate +.PN BadColor +and +.PN BadValue +errors. +.LP +.sp +.IN "Freeing" "colors" +To free colormap cells, use +.PN XFreeColors . +.IN "XFreeColors" "" "@DEF@" +.IN "Color" "deallocation" +.sM +.FD 0 +XFreeColors\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIpixels\fP\^, \fInpixels\fP\^, \fIplanes\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Colormap \fIcolormap\fP\^; +.br + unsigned long \fIpixels\fP\^[\^]; +.br + int \fInpixels\fP\^; +.br + unsigned long \fIplanes\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIcolormap\fP 1i +Specifies the colormap. +.ds Pi that map to the cells in the specified colormap +.IP \fIpixels\fP 1i +Specifies an array of pixel values \*(Pi. +.IP \fInpixels\fP 1i +Specifies the number of pixels. +.IP \fIplanes\fP 1i +Specifies the planes you want to free. +.LP +.eM +The +.PN XFreeColors +function frees the cells represented by pixels whose values are in the +pixels array. +The planes argument should not have any bits set to 1 in common with any of the +pixels. +The set of all pixels is produced by ORing together subsets of +the planes argument with the pixels. +The request frees all of these pixels that +were allocated by the client (using +.IN XAllocColor +.IN XAllocNamedColor +.IN XAllocColorCells +.IN XAllocColorPlanes +.PN XAllocColor , +.PN XAllocNamedColor , +.PN XAllocColorCells , +and +.PN XAllocColorPlanes ). +Note that freeing an +individual pixel obtained from +.PN XAllocColorPlanes +may not actually allow +it to be reused until all of its related pixels are also freed. +Similarly, +a read-only entry is not actually freed until it has been freed by all clients, +and if a client allocates the same read-only entry multiple times, +it must free the entry that many times before the entry is actually freed. +.LP +All specified pixels that are allocated by the client in the colormap are +freed, even if one or more pixels produce an error. +If a specified pixel is not a valid index into the colormap, a +.PN BadValue +error results. +If a specified pixel is not allocated by the +client (that is, is unallocated or is only allocated by another client) +or if the colormap was created with all entries writable (by passing +.PN AllocAll +to +.PN XCreateColormap ), +a +.PN BadAccess +error results. +If more than one pixel is in error, +the one that gets reported is arbitrary. +.LP +.PN XFreeColors +can generate +.PN BadAccess , +.PN BadColor , +and +.PN BadValue +errors. +.NH 2 +Modifying and Querying Colormap Cells +.XS +\*(SN Modifying and Querying Colormap Cells +.XE +.LP +.sp +To store an RGB value in a single colormap cell, use +.PN XStoreColor . +.IN "Color" "storing" +.IN "XStoreColor" "" "@DEF@" +.sM +.FD 0 +XStoreColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcolor\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Colormap \fIcolormap\fP\^; +.br + XColor *\fIcolor\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIcolormap\fP 1i +Specifies the colormap. +.IP \fIcolor\fP 1i +Specifies the pixel and RGB values. +.LP +.eM +The +.PN XStoreColor +function changes the colormap entry of the pixel value specified in the +pixel member of the +.PN XColor +structure. +You specified this value in the +pixel member of the +.PN XColor +structure. +This pixel value must be a read/write cell and a valid index into the colormap. +If a specified pixel is not a valid index into the colormap, +a +.PN BadValue +error results. +.PN XStoreColor +also changes the red, green, and/or blue color components. +You specify which color components are to be changed by setting +.PN DoRed , +.PN DoGreen , +and/or +.PN DoBlue +in the flags member of the +.PN XColor +structure. +If the colormap is an installed map for its screen, +the changes are visible immediately. +.LP +.PN XStoreColor +can generate +.PN BadAccess , +.PN BadColor , +and +.PN BadValue +errors. +.LP +.sp +To store multiple RGB values in multiple colormap cells, use +.PN XStoreColors . +.IN "Color" "storing" +.IN "XStoreColors" "" "@DEF@" +.sM +.FD 0 +XStoreColors\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcolor\fP\^, \fIncolors\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Colormap \fIcolormap\fP\^; +.br + XColor \fIcolor\fP\^[\^]\^; +.br + int \fIncolors\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIcolormap\fP 1i +Specifies the colormap. +.IP \fIcolor\fP 1i +Specifies an array of color definition structures to be stored. +.IP \fIncolors\fP 1i +.\"Specifies the number of color definition structures. +Specifies the number of +.PN XColor +structures in the color definition array. +.LP +.eM +The +.PN XStoreColors +function changes the colormap entries of the pixel values +specified in the pixel members of the +.PN XColor +structures. +You specify which color components are to be changed by setting +.PN DoRed , +.PN DoGreen , +and/or +.PN DoBlue +in the flags member of the +.PN XColor +structures. +If the colormap is an installed map for its screen, the +changes are visible immediately. +.PN XStoreColors +changes the specified pixels if they are allocated writable in the colormap +by any client, even if one or more pixels generates an error. +If a specified pixel is not a valid index into the colormap, a +.PN BadValue +error results. +If a specified pixel either is unallocated or is allocated read-only, a +.PN BadAccess +error results. +If more than one pixel is in error, +the one that gets reported is arbitrary. +.LP +.PN XStoreColors +can generate +.PN BadAccess , +.PN BadColor , +and +.PN BadValue +errors. +.LP +.sp +To store a color of arbitrary format in a single colormap cell, use +.PN XcmsStoreColor . +.IN "Color" "storing" +.IN "XcmsStoreColor" "" "@DEF@" +.sM +.FD 0 +Status XcmsStoreColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcolor\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Colormap \fIcolormap\fP\^; +.br + XcmsColor *\fIcolor\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIcolormap\fP 1i +Specifies the colormap. +.IP \fIcolor\fP 1i +Specifies the color cell and the color to store. +Values specified in this +.PN XcmsColor +structure remain unchanged on return. +.LP +.eM +The +.PN XcmsStoreColor +function converts the color specified in the +.PN XcmsColor +structure into RGB values. +It then uses this RGB specification in an +.PN XColor +structure, whose three flags +.Pn ( DoRed , +.PN DoGreen , +and +.PN DoBlue ) +are set, in a call to +.PN XStoreColor +to change the color cell specified by the pixel member of the +.PN XcmsColor +structure. +This pixel value must be a valid index for the specified colormap, +and the color cell specified by the pixel value must be a read/write cell. +If the pixel value is not a valid index, a +.PN BadValue +error results. +If the color cell is unallocated or is allocated read-only, a +.PN BadAccess +error results. +If the colormap is an installed map for its screen, +the changes are visible immediately. +.LP +Note that +.PN XStoreColor +has no return value; therefore, an +.PN XcmsSuccess +return value from this function indicates that the conversion +to RGB succeeded and the call to +.PN XStoreColor +was made. +To obtain the actual color stored, use +.PN XcmsQueryColor . +Because of the screen's hardware limitations or gamut compression, +the color stored in the colormap may not be identical +to the color specified. +.LP +.PN XcmsStoreColor +can generate +.PN BadAccess , +.PN BadColor , +and +.PN BadValue +errors. +.LP +.sp +To store multiple colors of arbitrary format in multiple colormap cells, use +.PN XcmsStoreColors . +.IN "Color" "storing" +.IN "XcmsStoreColors" "" "@DEF@" +.sM +.FD 0 +Status XcmsStoreColors\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcolors\fP\^, \fIncolors\fP\^, \fIcompression_flags_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Colormap \fIcolormap\fP\^; +.br + XcmsColor \fIcolors\fP\^[\^]\^; +.br + int \fIncolors\fP\^; +.br + Bool \fIcompression_flags_return\fP\^[\^]\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIcolormap\fP 1i +Specifies the colormap. +.IP \fIcolors\fP 1i +Specifies the color specification array of +.PN XcmsColor +structures, each specifying a color cell and the color to store in that +cell. +Values specified in the array remain unchanged upon return. +.IP \fIncolors\fP 1i +Specifies the number of +.PN XcmsColor +structures in the color-specification array. +.IP \fIcompression_flags_return\fP 1i +Returns an array of Boolean values indicating compression status. +If a non-NULL pointer is supplied, +each element of the array is set to +.PN True +if the corresponding color was compressed and +.PN False +otherwise. +Pass NULL if the compression status is not useful. +.LP +.eM +The +.PN XcmsStoreColors +function converts the colors specified in the array of +.PN XcmsColor +structures into RGB values and then uses these RGB specifications in +.PN XColor +structures, whose three flags +.Pn ( DoRed , +.PN DoGreen , +and +.PN DoBlue ) +are set, in a call to +.PN XStoreColors +to change the color cells specified by the pixel member of the corresponding +.PN XcmsColor +structure. +Each pixel value must be a valid index for the specified colormap, +and the color cell specified by each pixel value must be a read/write cell. +If a pixel value is not a valid index, a +.PN BadValue +error results. +If a color cell is unallocated or is allocated read-only, a +.PN BadAccess +error results. +If more than one pixel is in error, +the one that gets reported is arbitrary. +If the colormap is an installed map for its screen, +the changes are visible immediately. +.LP +Note that +.PN XStoreColors +has no return value; therefore, an +.PN XcmsSuccess +return value from this function indicates that conversions +to RGB succeeded and the call to +.PN XStoreColors +was made. +To obtain the actual colors stored, use +.PN XcmsQueryColors . +Because of the screen's hardware limitations or gamut compression, +the colors stored in the colormap may not be identical +to the colors specified. +.LP +.PN XcmsStoreColors +can generate +.PN BadAccess , +.PN BadColor , +and +.PN BadValue +errors. +.LP +.sp +To store a color specified by name in a single colormap cell, use +.PN XStoreNamedColor . +.IN "Color" "storing" +.IN "Color" "naming" +.IN "XStoreNamedColor" "" "@DEF@" +.sM +.FD 0 +XStoreNamedColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcolor\fP\^, \fIpixel\fP\^, \fIflags\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Colormap \fIcolormap\fP\^; +.br + char *\^\fIcolor\fP\^; +.br + unsigned long \fIpixel\fP\^; +.br + int \fIflags\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIcolormap\fP 1i +Specifies the colormap. +.IP \fIcolor\fP 1i +Specifies the color name string (for example, red). +.IP \fIpixel\fP 1i +Specifies the entry in the colormap. +.IP \fIflags\fP 1i +Specifies which red, green, and blue components are set. +.LP +.eM +The +.PN XStoreNamedColor +function looks up the named color with respect to the screen associated with +the colormap and stores the result in the specified colormap. +The pixel argument determines the entry in the colormap. +The flags argument determines which of the red, green, and blue components +are set. +You can set this member to the +bitwise inclusive OR of the bits +.PN DoRed , +.PN DoGreen , +and +.PN DoBlue . +If the color name is not in the Host Portable Character Encoding, +the result is implementation-dependent. +Use of uppercase or lowercase does not matter. +If the specified pixel is not a valid index into the colormap, a +.PN BadValue +error results. +If the specified pixel either is unallocated or is allocated read-only, a +.PN BadAccess +error results. +.LP +.PN XStoreNamedColor +can generate +.PN BadAccess , +.PN BadColor , +.PN BadName , +and +.PN BadValue +errors. +.LP +The +.PN XQueryColor +and +.PN XQueryColors +functions take pixel values in the pixel member of +.PN XColor +structures and store in the structures the RGB values for those +pixels from the specified colormap. +The values returned for an unallocated entry are undefined. +These functions also set the flags member in the +.PN XColor +structure to all three colors. +If a pixel is not a valid index into the specified colormap, a +.PN BadValue +error results. +If more than one pixel is in error, +the one that gets reported is arbitrary. +.LP +.sp +To query the RGB value of a single colormap cell, use +.PN XQueryColor . +.IN "Color" "querying" +.IN "XQueryColor" "" "@DEF@" +.sM +.FD 0 +XQueryColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIdef_in_out\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Colormap \fIcolormap\fP\^; +.br + XColor *\fIdef_in_out\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIcolormap\fP 1i +Specifies the colormap. +.IP \fIdef_in_out\fP 1i +Specifies and returns the RGB values for the pixel specified in the structure. +.LP +.eM +The +.PN XQueryColor +function returns the current RGB value for the pixel in the +.PN XColor +structure and sets the +.PN DoRed , +.PN DoGreen , +and +.PN DoBlue +flags. +.LP +.PN XQueryColor +can generate +.PN BadColor +and +.PN BadValue +errors. +.LP +.sp +To query the RGB values of multiple colormap cells, use +.PN XQueryColors . +.IN "Color" "querying" +.IN "XQueryColors" "" "@DEF@" +.sM +.FD 0 +XQueryColors\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIdefs_in_out\fP\^, \fIncolors\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Colormap \fIcolormap\fP\^; +.br + XColor \fIdefs_in_out\fP[\^]\^; +.br + int \fIncolors\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIcolormap\fP 1i +Specifies the colormap. +.IP \fIdefs_in_out\fP 1i +Specifies and returns an array of color definition structures for the pixel +specified in the structure. +.IP \fIncolors\fP 1i +.\"Specifies the number of color definition structures. +Specifies the number of +.PN XColor +structures in the color definition array. +.LP +.eM +The +.PN XQueryColors +function returns the RGB value for each pixel in each +.PN XColor +structure and sets the +.PN DoRed , +.PN DoGreen , +and +.PN DoBlue +flags in each structure. + +.LP +.PN XQueryColors +can generate +.PN BadColor +and +.PN BadValue +errors. +.sp +.LP +To query the color of a single colormap cell in an arbitrary format, use +.PN XcmsQueryColor . +.IN "Color" "querying" +.IN "XcmsQueryColor" "" "@DEF@" +.sM +.FD 0 +Status XcmsQueryColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcolor_in_out\fP\^, \fIresult_format\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Colormap \fIcolormap\fP\^; +.br + XcmsColor *\fIcolor_in_out\fP\^; +.br + XcmsColorFormat \fIresult_format\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIcolormap\fP 1i +Specifies the colormap. +.IP \fIcolor_in_out\fP 1i +Specifies the pixel member that indicates the color cell to query. +The color specification stored for the color cell is returned in this +.PN XcmsColor +structure. +.IP \fIresult_format\fP 1i +Specifies the color format for the returned color specification. +.LP +.eM +The +.PN XcmsQueryColor +function obtains the RGB value +for the pixel value in the pixel member of the specified +.PN XcmsColor +structure and then +converts the value to the target format as +specified by the result_format argument. +If the pixel is not a valid index in the specified colormap, a +.PN BadValue +error results. +.LP +.PN XcmsQueryColor +can generate +.PN BadColor +and +.PN BadValue +errors. +.sp +.LP +To query the color of multiple colormap cells in an arbitrary format, use +.PN XcmsQueryColors . +.IN "Color" "querying" +.IN "XcmsQueryColors" "" "@DEF@" +.sM +.FD 0 +Status XcmsQueryColors\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcolors_in_out\fP\^, \fIncolors\fP\^, \fIresult_format\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Colormap \fIcolormap\fP\^; +.br + XcmsColor \fIcolors_in_out\fP\^[\^]\^; +.br + unsigned int \fIncolors\fP\^; +.br + XcmsColorFormat \fIresult_format\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIcolormap\fP 1i +Specifies the colormap. +.IP \fIcolors_in_out\fP 1i +Specifies an array of +.PN XcmsColor +structures, each pixel member indicating the color cell to query. +The color specifications for the color cells are returned in these structures. +.IP \fIncolors\fP 1i +Specifies the number of +.PN XcmsColor +structures in the color-specification array. +.IP \fIresult_format\fP 1i +Specifies the color format for the returned color specification. +.LP +.eM +The +.PN XcmsQueryColors +function obtains the RGB values +for pixel values in the pixel members of +.PN XcmsColor +structures and then +converts the values to the target format as +specified by the result_format argument. +If a pixel is not a valid index into the specified colormap, a +.PN BadValue +error results. +If more than one pixel is in error, +the one that gets reported is arbitrary. +.LP +.PN XcmsQueryColors +can generate +.PN BadColor +and +.PN BadValue +errors. +.NH 2 +Color Conversion Context Functions +.XS +\*(SN Color Conversion Context Functions +.XE +.LP +This section describes functions to create, modify, +and query Color Conversion Contexts (CCCs). +.LP +Associated with each colormap is an initial CCC transparently generated by +Xlib. +.IN "Color Conversion Context" "creation" +Therefore, when you specify a colormap as an argument to a function, +you are indirectly specifying a CCC. +.IN "CCC" "of colormap" +.IN "Color Conversion Context" "of colormap" +The CCC attributes that can be modified by the X client are: +.IP \(bu 5 +Client White Point +.IP \(bu 5 +Gamut compression procedure and client data +.IP \(bu 5 +White point adjustment procedure and client data +.LP +The initial values for these attributes are implementation specific. +The CCC attributes for subsequently created CCCs can be defined +by changing the CCC attributes of the default CCC. +.IN "CCC" "default" +.IN "Color Conversion Context" "default" +There is a default CCC associated with each screen. +.NH 3 +Getting and Setting the Color Conversion Context of a Colormap +.XS +\*(SN Getting and Setting the Color Conversion Context of a Colormap +.XE +.LP +.sp +To obtain the CCC associated with a colormap, use +.PN XcmsCCCOfColormap . +.IN "XcmsCCCOfColormap" "" "@DEF@" +.IN "Colormap" "CCC of" +.IN "CCC" "of colormap" +.IN "Color Conversion Context" "of colormap" +.sM +.FD 0 +XcmsCCC XcmsCCCOfColormap\^(\^\fIdisplay\fP, \fIcolormap\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Colormap \fIcolormap\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIcolormap\fP 1i +Specifies the colormap. +.LP +.eM +The +.PN XcmsCCCOfColormap +function returns the CCC associated with the specified colormap. +Once obtained, +the CCC attributes can be queried or modified. +Unless the CCC associated with the specified colormap is changed with +.PN XcmsSetCCCOfColormap , +this CCC is used when the specified colormap is used as an argument +to color functions. +.sp +.LP +To change the CCC associated with a colormap, use +.PN XcmsSetCCCOfColormap . +.IN "XcmsSetCCCOfColormap" "" "@DEF@" +.IN "Colormap" "CCC of" +.IN "CCC" "of colormap" +.IN "Color Conversion Context" "of colormap" +.sM +.FD 0 +XcmsCCC XcmsSetCCCOfColormap\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIccc\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Colormap \fIcolormap\fP\^; +.br + XcmsCCC \fIccc\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIcolormap\fP 1i +Specifies the colormap. +.IP \fIccc\fP 1i +Specifies the CCC. +.LP +.eM +The +.PN XcmsSetCCCOfColormap +function changes the CCC associated with the specified colormap. +It returns the CCC previously associated with the colormap. +If they are not used again in the application, +CCCs should be freed by calling +.PN XcmsFreeCCC . +Several colormaps may share the same CCC without restriction; this +includes the CCCs generated by Xlib with each colormap. Xlib, however, +creates a new CCC with each new colormap. +.NH 3 +Obtaining the Default Color Conversion Context +.XS +\*(SN Obtaining the Default Color Conversion Context +.XE +.LP +You can change the default CCC attributes for subsequently created CCCs +by changing the CCC attributes of the default CCC. +.IN "CCC" "default" +.IN "Color Conversion Context" "default" +A default CCC is associated with each screen. +.sp +.LP +To obtain the default CCC for a screen, use +.PN XcmsDefaultCCC . +.IN "XcmsDefaultCCC" "" "@DEF@" +.IN "Color Conversion Context" "default" +.IN "CCC" "default" +.sM +.FD 0 +XcmsCCC XcmsDefaultCCC\^(\^\fIdisplay\fP, \fIscreen_number\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIscreen_number\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIscreen_number\fP 1i +Specifies the appropriate screen number on the host server. +.LP +.eM +The +.PN XcmsDefaultCCC +function returns the default CCC for the specified screen. +Its visual is the default visual of the screen. +Its initial gamut compression and white point +adjustment procedures as well as the associated client data are implementation +specific. +.NH 3 +Color Conversion Context Macros +.XS +\*(SN Color Conversion Context Macros +.XE +.LP +Applications should not directly modify any part of the +.PN XcmsCCC . +The following lists the C language macros, their corresponding function +equivalents for other language bindings, and what data they both +can return. +.sp +.LP +.IN "DisplayOfCCC" "" "@DEF@" +.IN "XcmsDisplayOfCCC" "" "@DEF@" +.sM +.FD 0 +DisplayOfCCC\^(\^\fIccc\fP\^) +.br + XcmsCCC \fIccc\fP\^; +.sp +Display *XcmsDisplayOfCCC\^(\^\fIccc\fP\^) +.br + XcmsCCC \fIccc\fP\^; +.FN +.IP \fIccc\fP 1i +Specifies the CCC. +.LP +.eM +Both return the display associated with the specified CCC. +.LP +.sp +.IN "VisualOfCCC" "" "@DEF@" +.IN "XcmsVisualOfCCC" "" "@DEF@" +.sM +.FD 0 +VisualOfCCC\^(\^\fIccc\fP\^) +.br + XcmsCCC \fIccc\fP\^; +.sp +Visual *XcmsVisualOfCCC\^(\^\fIccc\fP\^) +.br + XcmsCCC \fIccc\fP\^; +.FN +.IP \fIccc\fP 1i +Specifies the CCC. +.LP +.eM +Both return the visual associated with the specified CCC. +.sp +.LP +.IN "ScreenNumberOfCCC" "" "@DEF@" +.IN "XcmsScreenNumberOfCCC" "" "@DEF@" +.sM +.FD 0 +ScreenNumberOfCCC\^(\^\fIccc\fP\^) +.br + XcmsCCC \fIccc\fP\^; +.sp +int XcmsScreenNumberOfCCC\^(\^\fIccc\fP\^) +.br + XcmsCCC \fIccc\fP\^; +.FN +.IP \fIccc\fP 1i +Specifies the CCC. +.LP +.eM +Both return the number of the screen associated with the specified CCC. +.sp +.LP +.IN "ScreenWhitePointOfCCC" "" "@DEF@" +.IN "XcmsScreenWhitePointOfCCC" "" "@DEF@" +.sM +.FD 0 +ScreenWhitePointOfCCC\^(\^\fIccc\fP\^) +.br + XcmsCCC \fIccc\fP\^; +.sp +XcmsColor *XcmsScreenWhitePointOfCCC\^(\^\fIccc\fP\^) +.br + XcmsCCC \fIccc\fP\^; +.FN +.IP \fIccc\fP 1i +Specifies the CCC. +.LP +.eM +Both return the white point of the screen associated with the specified CCC. +.sp +.LP +.IN "ClientWhitePointOfCCC" "" "@DEF@" +.IN "XcmsClientWhitePointOfCCC" "" "@DEF@" +.sM +.FD 0 +ClientWhitePointOfCCC\^(\^\fIccc\fP\^) +.br + XcmsCCC \fIccc\fP\^; +.sp +XcmsColor *XcmsClientWhitePointOfCCC\^(\^\fIccc\fP\^) +.br + XcmsCCC \fIccc\fP\^; +.FN +.IP \fIccc\fP 1i +Specifies the CCC. +.LP +.eM +Both return the Client White Point of the specified CCC. +.NH 3 +Modifying Attributes of a Color Conversion Context +.XS +\*(SN Modifying Attributes of a Color Conversion Context +.XE +.LP +To set the Client White Point in the CCC, use +.PN XcmsSetWhitePoint . +.IN "XcmsSetWhitePoint" "" "@DEF@" +.IN "Client White Point" "of Color Conversion Context" +.sM +.FD 0 +Status XcmsSetWhitePoint\^(\^\fIccc\fP\^, \fIcolor\fP\^) +.br + XcmsCCC \fIccc\fP\^; +.br + XcmsColor *\fIcolor\fP\^; +.FN +.IP \fIccc\fP 1i +Specifies the CCC. +.ds Co new Client White Point +.IP \fIcolor\fP 1i +Specifies the \*(Co. +.LP +.eM +The +.PN XcmsSetWhitePoint +function changes the Client White Point in the specified CCC. +Note that the pixel member is ignored +and that the color specification is left unchanged upon return. +The format for the new white point must be +.PN XcmsCIEXYZFormat , +.PN XcmsCIEuvYFormat , +.PN XcmsCIExyYFormat , +or +.PN XcmsUndefinedFormat . +If the color argument is NULL, this function sets the format component of the +Client White Point specification to +.PN XcmsUndefinedFormat , +indicating that the Client White Point is assumed to be the same as the +Screen White Point. +.LP +This function returns nonzero status +if the format for the new white point is valid; +otherwise, it returns zero. + +.sp +.LP +To set the gamut compression procedure and corresponding client data +in a specified CCC, use +.PN XcmsSetCompressionProc . +.IN "XcmsSetCompressionProc" "" "@DEF@" +.IN "Gamut compression" "setting in Color Conversion Context" +.IN "Gamut compression" "procedure" +.IN "Gamut compression" "client data" +.sM +.FD 0 +XcmsCompressionProc XcmsSetCompressionProc\^(\^\fIccc\fP\^, \fIcompression_proc\fP\^, \fIclient_data\fP\^) +.br + XcmsCCC \fIccc\fP\^; +.br + XcmsCompressionProc \fIcompression_proc\fP\^; +.br + XPointer \fIclient_data\fP\^; +.FN +.IP \fIccc\fP 1i +Specifies the CCC. +.IP \fIcompression_proc\fP 1i +Specifies the gamut compression procedure that is to be applied +when a color lies outside the screen's color gamut. +If NULL is specified and a function using this CCC must convert +a color specification to a device-dependent format and encounters a color +that lies outside the screen's color gamut, +that function will return +.PN XcmsFailure . +.ds Cd the gamut compression procedure +.IP \fIclient_data\fP 1i +Specifies client data for \*(Cd or NULL. +.LP +.eM +The +.PN XcmsSetCompressionProc +function first sets the gamut compression procedure and client data +in the specified CCC with the newly specified procedure and client data +and then returns the old procedure. +.sp +.LP +To set the white point adjustment procedure and corresponding client data +in a specified CCC, use +.PN XcmsSetWhiteAdjustProc . +.IN "XcmsSetWhiteAdjustProc" "" "@DEF@" +.IN "White point adjustment" "setting in Color Conversion Context" +.IN "White point adjustment" "procedure" +.IN "White point adjustment" "client data" +.FD 0 +.sM +XcmsWhiteAdjustProc XcmsSetWhiteAdjustProc\^(\^\fIccc\fP\^, \fIwhite_adjust_proc\fP\^, \fIclient_data\fP\^) +.br + XcmsCCC \fIccc\fP\^; +.br + XcmsWhiteAdjustProc \fIwhite_adjust_proc\fP\^; +.br + XPointer \fIclient_data\fP\^; +.FN +.IP \fIccc\fP 1i +Specifies the CCC. +.IP \fIwhite_adjust_proc\fP 1i +Specifies the white point adjustment procedure. +.ds Cd the white point adjustment procedure +.IP \fIclient_data\fP 1i +Specifies client data for \*(Cd or NULL. +.LP +.eM +The +.PN XcmsSetWhiteAdjustProc +function first sets the white point adjustment procedure and client data +in the specified CCC with the newly specified procedure and client data +and then returns the old procedure. +.NH 3 +Creating and Freeing a Color Conversion Context +.XS +\*(SN Creating and Freeing a Color Conversion Context +.XE +.LP +You can explicitly create a CCC within your application by calling +.PN XcmsCreateCCC . +These created CCCs can then be used by those functions that explicitly +call for a CCC argument. +Old CCCs that will not be used by the application should be freed using +.PN XcmsFreeCCC . +.sp +.LP +To create a CCC, use +.PN XcmsCreateCCC . +.IN "XcmsCreateCCC" "" "@DEF@" +.IN "Color Conversion Context" "creation" +.IN "CCC" "creation" +.sM +.FD 0 +XcmsCCC XcmsCreateCCC\^(\^\fIdisplay\fP, \fIscreen_number\fP\^, \fIvisual\fP\^, \fIclient_white_point\fP\^, \fIcompression_proc\fP\^, +.br + \fIcompression_client_data\fP\^, \fIwhite_adjust_proc\fP\^, \fIwhite_adjust_client_data\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIscreen_number\fP\^; +.br + Visual *\fIvisual\fP\^; +.br + XcmsColor *\fIclient_white_point\fP\^; +.br + XcmsCompressionProc \fIcompression_proc\fP\^; +.br + XPointer \fIcompression_client_data\fP\^; +.br + XcmsWhiteAdjustProc \fIwhite_adjust_proc\fP\^; +.br + XPointer \fIwhite_adjust_client_data\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIscreen_number\fP 1i +Specifies the appropriate screen number on the host server. +.IP \fIvisual\fP 1i +Specifies the visual type. +.IP \fIclient_white_point\fP 1i +Specifies the Client White Point. +If NULL is specified, +the Client White Point is to be assumed to be the same as the +Screen White Point. +Note that the pixel member is ignored. +.IP \fIcompression_proc\fP 1i +Specifies the gamut compression procedure that is to be applied +when a color lies outside the screen's color gamut. +If NULL is specified and a function using this CCC must convert +a color specification to a device-dependent format and encounters a color +that lies outside the screen's color gamut, +that function will return +.PN XcmsFailure . +.IP \fIcompression_client_data\fP 1i +Specifies client data for use by the gamut compression procedure or NULL. +.IP \fIwhite_adjust_proc\fP 1i +Specifies the white adjustment procedure that is to be applied +when the Client White Point differs from the Screen White Point. +NULL indicates that no white point adjustment is desired. +.IP \fIwhite_adjust_client_data\fP 1i +Specifies client data for use with the white point adjustment procedure or NULL. +.LP +.eM +The +.PN XcmsCreateCCC +function creates a CCC for the specified display, screen, and visual. +.LP +.sp +To free a CCC, use +.PN XcmsFreeCCC . +.IN "XcmsFreeCCC" "" "@DEF@" +.IN "Color Conversion Context" "freeing" +.IN "CCC" "freeing" +.sM +.FD 0 +void XcmsFreeCCC\^(\^\fIccc\fP\^) +.br + XcmsCCC \fIccc\fP\^; +.FN +.IP \fIccc\fP 1i +Specifies the CCC. +.LP +.eM +The +.PN XcmsFreeCCC +function frees the memory used for the specified CCC. +Note that default CCCs and those currently associated with colormaps +are ignored. +.NH 2 +Converting between Color Spaces +.XS +\*(SN Converting between Color Spaces +.XE +.LP +.sp +To convert an array of color specifications in arbitrary color formats +to a single destination format, use +.PN XcmsConvertColors . +.IN "Color conversion" +.IN "Color" "conversion" +.IN "XcmsConvertColors" "" "@DEF@" +.sM +.FD 0 +Status XcmsConvertColors\^(\^\fIccc\fP\^, \fIcolors_in_out\fP\^, \fIncolors\fP\^, \fItarget_format\fP\^, \fIcompression_flags_return\fP\^) +.br + XcmsCCC \fIccc\fP\^; +.br + XcmsColor \fIcolors_in_out\fP\^[\^]\^; +.br + unsigned int \fIncolors\fP\^; +.br + XcmsColorFormat \fItarget_format\fP\^; +.br + Bool \fIcompression_flags_return\fP\^[\^]\^; +.FN +.IP \fIccc\fP 1i +Specifies the CCC. +If conversion is between device-independent color spaces only +(for example, TekHVC to CIELuv), +the CCC is necessary only to specify the Client White Point. +.IP \fIcolors_in_out\fP 1i +Specifies an array of color specifications. +Pixel members are ignored and remain unchanged upon return. +.IP \fIncolors\fP 1i +Specifies the number of +.PN XcmsColor +structures in the color-specification array. +.IP \fItarget_format\fP 1i +Specifies the target color specification format. +.IP \fIcompression_flags_return\fP 1i +Returns an array of Boolean values indicating compression status. +If a non-NULL pointer is supplied, +each element of the array is set to +.PN True +if the corresponding color was compressed and +.PN False +otherwise. +Pass NULL if the compression status is not useful. +.LP +.eM +The +.PN XcmsConvertColors +function converts the color specifications in the specified array of +.PN XcmsColor +structures from their current format to a single target format, +using the specified CCC. +When the return value is +.PN XcmsFailure , +the contents of the color specification array are left unchanged. +.LP +The array may contain a mixture of color specification formats +(for example, 3 CIE XYZ, 2 CIE Luv, and so on). +When the array contains both device-independent and +device-dependent color specifications and the target_format argument specifies +a device-dependent format (for example, +.PN XcmsRGBiFormat , +.PN XcmsRGBFormat ), +all specifications are converted to CIE XYZ format and then to the target +device-dependent format. +.NH 2 +Callback Functions +.XS +\*(SN Callback Functions +.XE +.LP +This section describes the gamut compression and white point +adjustment callbacks. +.LP +The gamut compression procedure specified in the CCC +is called when an attempt to convert a color specification from +.PN XcmsCIEXYZ +to a device-dependent format (typically +.PN XcmsRGBi ) +results in a color that lies outside the screen's color gamut. +If the gamut compression procedure requires client data, this data is passed +via the gamut compression client data in the CCC. +.LP +During color specification conversion between device-independent +and device-dependent color spaces, +if a white point adjustment procedure is specified in the CCC, +it is triggered when the Client White Point and Screen White Point differ. +If required, the client data is obtained from the CCC. +.NH 3 +Prototype Gamut Compression Procedure +.XS +\*(SN Prototype Gamut Compression Procedure +.XE +.LP +The gamut compression callback interface must adhere to the +following: +.IN "XcmsCompressionProc" "" "@DEF@" +.sM +.FD 0 +typedef Status (*\^XcmsCompressionProc\^)\^(\^\fIccc\fP\^, \fIcolors_in_out\fP\^, \fIncolors\fP\^, \fIindex\fP\^, \fIcompression_flags_return\fP\^) +.br + XcmsCCC \fIccc\fP\^; +.br + XcmsColor \fIcolors_in_out[]\fP\^; +.br + unsigned int \fIncolors\fP\^; +.br + unsigned int \fIindex\fP\^; +.br + Bool \fIcompression_flags_return[]\fP\^; +.FN +.IP \fIccc\fP 1i +Specifies the CCC. +.IP \fIcolors_in_out\fP 1i +Specifies an array of color specifications. +Pixel members should be ignored and must remain unchanged upon return. +.IP \fIncolors\fP 1i +Specifies the number of +.PN XcmsColor +structures in the color-specification array. +.IP \fIindex\fP 1i +Specifies the index into the array of +.PN XcmsColor +structures for the encountered color specification that lies outside the +screen's color gamut. +Valid values are 0 (for the first element) to ncolors \- 1. +.IP \fIcompression_flags_return\fP 1i +Returns an array of Boolean values for indicating compression status. +If a non-NULL pointer is supplied +and a color at a given index is compressed, then +.PN True +should be stored at the corresponding index in this array; +otherwise, the array should not be modified. +.LP +.eM +When implementing a gamut compression procedure, consider the following +rules and assumptions: +.IP \(bu 5 +The gamut compression procedure can attempt to compress one or multiple +specifications at a time. +.IP \(bu 5 +When called, elements 0 to index \- 1 in the color specification +array can be assumed to fall within the screen's color gamut. +In addition, these color specifications are already in some device-dependent +format (typically +.PN XcmsRGBi ). +If any modifications are made to these color specifications, +they must be in their initial device-dependent format upon return. +.IP \(bu 5 +When called, the element in the color specification array specified +by the index argument contains the color specification outside the +screen's color gamut encountered by the calling routine. +In addition, this color specification can be assumed to be in +.PN XcmsCIEXYZ . +Upon return, this color specification must be in +.PN XcmsCIEXYZ . +.IP \(bu 5 +When called, elements from index to ncolors \- 1 +in the color specification array may or may not fall within the +screen's color gamut. +In addition, these color specifications can be assumed to be in +.PN XcmsCIEXYZ . +If any modifications are made to these color specifications, +they must be in +.PN XcmsCIEXYZ +upon return. +.IP \(bu 5 +The color specifications passed to the gamut compression procedure +have already been adjusted to the Screen White Point. +This means that at this point the color specification's white point +is the Screen White Point. +.IP \(bu 5 +If the gamut compression procedure uses a device-independent color space not +initially accessible for use in the color management system, use +.PN XcmsAddColorSpace +to ensure that it is added. +.NH 3 +Supplied Gamut Compression Procedures +.XS +\*(SN Supplied Gamut Compression Procedures +.XE +.LP +The following equations are useful in describing gamut compression +functions: +.EQ +delim %% +.EN +.LP +.Ds 0 +%CIELab~Psychometric~Chroma ~=~ sqrt(a_star sup 2 ~+~ b_star sup 2 )% + +%CIELab~Psychometric~Hue ~=~ tan sup -1 left [ b_star over a_star right ]% + +%CIELuv~Psychometric~Chroma ~=~ sqrt(u_star sup 2 ~+~ v_star sup 2 )% + +%CIELuv~Psychometric~Hue ~=~ tan sup -1 left [ v_star over u_star right ]% +.De +.LP +The gamut compression callback procedures provided by Xlib are as follows: +.IP \(bu 5 +.PN XcmsCIELabClipL +.IP +This brings the encountered out-of-gamut color specification into the +screen's color gamut by reducing or increasing CIE metric lightness (L*) +in the CIE L*a*b* color space until the color is within the gamut. +If the Psychometric Chroma of the color specification +is beyond maximum for the Psychometric Hue Angle, +then while maintaining the same Psychometric Hue Angle, +the color will be clipped to the CIE L*a*b* coordinates of maximum +Psychometric Chroma. +See +.PN XcmsCIELabQueryMaxC . +No client data is necessary. +.IP \(bu 5 +.PN XcmsCIELabClipab +.IP +This brings the encountered out-of-gamut color specification into the +screen's color gamut by reducing Psychometric Chroma, +while maintaining Psychometric Hue Angle, +until the color is within the gamut. +No client data is necessary. +.IP \(bu 5 +.PN XcmsCIELabClipLab +.IP +This brings the encountered out-of-gamut color specification into the +screen's color gamut by replacing it with CIE L*a*b* coordinates +that fall within the color gamut while maintaining the original +Psychometric Hue +Angle and whose vector to the original coordinates is the shortest attainable. +No client data is necessary. +.IP \(bu 5 +.PN XcmsCIELuvClipL +.IP +This brings the encountered out-of-gamut color specification into the +screen's color gamut by reducing or increasing CIE metric lightness (L*) +in the CIE L*u*v* color space until the color is within the gamut. +If the Psychometric Chroma of the color specification +is beyond maximum for the Psychometric Hue Angle, +then, while maintaining the same Psychometric Hue Angle, +the color will be clipped to the CIE L*u*v* coordinates of maximum +Psychometric Chroma. +See +.PN XcmsCIELuvQueryMaxC . +No client data is necessary. +.IP \(bu 5 +.PN XcmsCIELuvClipuv +.IP +This brings the encountered out-of-gamut color specification into the +screen's color gamut by reducing +Psychometric Chroma, while maintaining Psychometric Hue Angle, +until the color is within the gamut. +No client data is necessary. +.IP \(bu 5 +.PN XcmsCIELuvClipLuv +.IP +This brings the encountered out-of-gamut color specification into the +screen's color gamut by replacing it with CIE L*u*v* coordinates +that fall within the color gamut while maintaining the original +Psychometric Hue +Angle and whose vector to the original coordinates is the shortest attainable. +No client data is necessary. +.IP \(bu 5 +.PN XcmsTekHVCClipV +.IP +This brings the encountered out-of-gamut color specification into the +screen's color gamut by reducing or increasing the Value dimension +in the TekHVC color space until the color is within the gamut. +If Chroma of the color specification is beyond maximum for the particular Hue, +then, while maintaining the same Hue, +the color will be clipped to the Value and Chroma coordinates +that represent maximum Chroma for that particular Hue. +No client data is necessary. +.IP \(bu 5 +.PN XcmsTekHVCClipC +.IP +This brings the encountered out-of-gamut color specification into the +screen's color gamut by reducing the Chroma dimension +in the TekHVC color space until the color is within the gamut. +No client data is necessary. +.IP \(bu 5 +.PN XcmsTekHVCClipVC +.IP +This brings the encountered out-of-gamut color specification into the +screen's color gamut by replacing it with TekHVC coordinates +that fall within the color gamut while maintaining the original Hue +and whose vector to the original coordinates is the shortest attainable. +No client data is necessary. +.NH 3 +Prototype White Point Adjustment Procedure +.XS +\*(SN Prototype White Point Adjustment Procedure +.XE +.LP +The white point adjustment procedure interface must adhere to the following: +.IN "XcmsWhiteAdjustProc" "" "@DEF@" +.sM +.FD 0 +typedef Status (*\^XcmsWhiteAdjustProc\^)\^(\^\fIccc\fP\^, \fIinitial_white_point\fP\^, \fItarget_white_point\fP\^, \fItarget_format\fP\^, +.br + \fIcolors_in_out\fP\^, \fIncolors\fP\^, \fIcompression_flags_return\fP\^) +.br + XcmsCCC \fIccc\fP\^; +.br + XcmsColor *\fIinitial_white_point\fP\^; +.br + XcmsColor *\fItarget_white_point\fP\^; +.br + XcmsColorFormat \fItarget_format\fP\^; +.br + XcmsColor \fIcolors_in_out[]\fP\^; +.br + unsigned int \fIncolors\fP\^; +.br + Bool \fIcompression_flags_return[]\fP\^; +.FN +.IP \fIccc\fP 1i +Specifies the CCC. +.IP \fIinitial_white_point\fP 1i +Specifies the initial white point. +.IP \fItarget_white_point\fP 1i +Specifies the target white point. +.IP \fItarget_format\fP 1i +Specifies the target color specification format. +.IP \fIcolors_in_out\fP 1i +Specifies an array of color specifications. +Pixel members should be ignored and must remain unchanged upon return. +.IP \fIncolors\fP 1i +Specifies the number of +.PN XcmsColor +structures in the color-specification array. +.IP \fIcompression_flags_return\fP 1i +Returns an array of Boolean values for indicating compression status. +If a non-NULL pointer is supplied +and a color at a given index is compressed, then +.PN True +should be stored at the corresponding index in this array; +otherwise, the array should not be modified. +.LP +.eM +.NH 3 +Supplied White Point Adjustment Procedures +.XS +\*(SN Supplied White Point Adjustment Procedures +.XE +.LP +White point adjustment procedures provided by Xlib are as follows: +.IP \(bu 5 +.PN XcmsCIELabWhiteShiftColors +.IP +This uses the CIE L*a*b* color space for adjusting the chromatic character +of colors to compensate for the chromatic differences between the source +and destination white points. +This procedure simply converts the color specifications to +.PN XcmsCIELab +using the source white point and then converts to the target specification +format using the destination's white point. +No client data is necessary. +.IP \(bu 5 +.PN XcmsCIELuvWhiteShiftColors +.IP +This uses the CIE L*u*v* color space for adjusting the chromatic character +of colors to compensate for the chromatic differences between the source +and destination white points. +This procedure simply converts the color specifications to +.PN XcmsCIELuv +using the source white point and then converts to the target specification +format using the destination's white point. +No client data is necessary. +.IP \(bu 5 +.PN XcmsTekHVCWhiteShiftColors +.IP +This uses the TekHVC color space for adjusting the chromatic character +of colors to compensate for the chromatic differences between the source +and destination white points. +This procedure simply converts the color specifications to +.PN XcmsTekHVC +using the source white point and then converts to the target specification +format using the destination's white point. +An advantage of this procedure over those previously described +is an attempt to minimize hue shift. +No client data is necessary. +.LP +From an implementation point of view, +these white point adjustment procedures convert the color specifications +to a device-independent but white-point-dependent color space +(for example, CIE L*u*v*, CIE L*a*b*, TekHVC) using one white point +and then converting those specifications to the target color space +using another white point. +In other words, +the specification goes in the color space with one white point +but comes out with another white point, +resulting in a chromatic shift based on the chromatic displacement +between the initial white point and target white point. +The CIE color spaces that are assumed to be white-point-independent +are CIE u'v'Y, CIE XYZ, and CIE xyY. +When developing a custom white point adjustment procedure that uses a +device-independent color space not initially accessible for use in the +color management system, use +.PN XcmsAddColorSpace +to ensure that it is added. +.LP +As an example, +if the CCC specifies a white point adjustment procedure +and if the Client White Point and Screen White Point differ, the +.PN XcmsAllocColor +function will use the white point adjustment +procedure twice: +.IP \(bu 5 +Once to convert to +.PN XcmsRGB +.IP \(bu 5 +A second time to convert from +.PN XcmsRGB +.LP +For example, assume the specification is in +.PN XcmsCIEuvY +and the adjustment procedure is +.PN XcmsCIELuvWhiteShiftColors . +During conversion to +.PN XcmsRGB , +the call to +.PN XcmsAllocColor +results in the following series of color specification conversions: +.\" Do these need to be font coded? +.IP \(bu 5 +From +.PN XcmsCIEuvY +to +.PN XcmsCIELuv +using the Client White Point +.IP \(bu 5 +From +.PN XcmsCIELuv +to +.PN XcmsCIEuvY +using the Screen White Point +.IP \(bu 5 +From +.PN XcmsCIEuvY +to +.PN XcmsCIEXYZ +(CIE u'v'Y and XYZ are white-point-independent color spaces) +.IP \(bu 5 +From +.PN XcmsCIEXYZ +to +.PN XcmsRGBi +.IP \(bu 5 +From +.PN XcmsRGBi +to +.PN XcmsRGB +.LP +The resulting RGB specification is passed to +.PN XAllocColor , +and the RGB +specification returned by +.PN XAllocColor +is converted back to +.PN XcmsCIEuvY +by reversing the color conversion sequence. +.NH 2 +Gamut Querying Functions +.XS +\*(SN Gamut Querying Functions +.XE +.LP +This section describes the gamut querying functions that Xlib provides. +These functions allow the client to query the boundary +of the screen's color gamut in terms of the CIE L*a*b*, CIE L*u*v*, +and TekHVC color spaces. +.IN "Gamut querying" +Functions are also provided that allow you to query +the color specification of: +.IP \(bu 5 +White (full-intensity red, green, and blue) +.IP \(bu 5 +Red (full-intensity red while green and blue are zero) +.IP \(bu 5 +Green (full-intensity green while red and blue are zero) +.IP \(bu 5 +Blue (full-intensity blue while red and green are zero) +.IP \(bu 5 +Black (zero-intensity red, green, and blue) +.LP +The white point associated with color specifications passed to +and returned from these gamut querying +functions is assumed to be the Screen White Point. +.IN "Screen White Point" +This is a reasonable assumption, +because the client is trying to query the screen's color gamut. +.LP +The following naming convention is used for the Max and Min functions: +.LP +.Ds 0 +Xcms\fI\fPQueryMax\fI\fP + +Xcms\fI\fPQueryMin\fI\fP +.De +.LP +The consists of a letter or letters +that identify the dimensions of the color space +that are not fixed. +For example, +.PN XcmsTekHVCQueryMaxC +is given a fixed Hue and Value for which maximum Chroma is found. +.NH 3 +Red, Green, and Blue Queries +.XS +\*(SN Red, Green, and Blue Queries +.XE +.LP +To obtain the color specification for black +(zero-intensity red, green, and blue), use +.PN XcmsQueryBlack . +.IN "XcmsQueryBlack" "" "@DEF@" +.sM +.FD 0 +Status XcmsQueryBlack\^(\^\fIccc\fP\^, \fItarget_format\fP\^, \fIcolor_return\fP\^) +.br + XcmsCCC \fIccc\fP\^; +.br + XcmsColorFormat \fItarget_format\fP\^; +.br + XcmsColor *\fIcolor_return\fP\^; +.FN +.IP \fIccc\fP 1i +Specifies the CCC. +The CCC's Client White Point and white point adjustment procedures +are ignored. +.IP \fItarget_format\fP 1i +Specifies the target color specification format. +.ds Cs zero-intensity red, green, and blue +.IP \fIcolor_return\fP 1i +Returns the color specification in the specified target format +for \*(Cs. +The white point associated with the returned +color specification is the Screen White Point. +The value returned in the pixel member is undefined. +.LP +.eM +The +.PN XcmsQueryBlack +function returns the color specification in the specified target format +for zero-intensity red, green, and blue. +.sp +.LP +To obtain the color specification for blue +(full-intensity blue while red and green are zero), use +.PN XcmsQueryBlue . +.IN "XcmsQueryBlue" "" "@DEF@" +.sM +.FD 0 +Status XcmsQueryBlue\^(\^\fIccc\fP\^, \fItarget_format\fP\^, \fIcolor_return\fP\^) +.br + XcmsCCC \fIccc\fP\^; +.br + XcmsColorFormat \fItarget_format\fP\^; +.br + XcmsColor *\fIcolor_return\fP\^; +.FN +.IP \fIccc\fP 1i +Specifies the CCC. +The CCC's Client White Point and white point adjustment procedures +are ignored. +.IP \fItarget_format\fP 1i +Specifies the target color specification format. +.ds Cs full-intensity blue while red and green are zero +.IP \fIcolor_return\fP 1i +Returns the color specification in the specified target format +for \*(Cs. +The white point associated with the returned +color specification is the Screen White Point. +The value returned in the pixel member is undefined. +.LP +.eM +The +.PN XcmsQueryBlue +function returns the color specification in the specified target format +for full-intensity blue while red and green are zero. +.sp +.LP +To obtain the color specification for green +(full-intensity green while red and blue are zero), use +.PN XcmsQueryGreen . +.IN "XcmsQueryGreen" "" "@DEF@" +.sM +.FD 0 +Status XcmsQueryGreen\^(\^\fIccc\fP\^, \fItarget_format\fP\^, \fIcolor_return\fP\^) +.br + XcmsCCC \fIccc\fP\^; +.br + XcmsColorFormat \fItarget_format\fP\^; +.br + XcmsColor *\fIcolor_return\fP\^; +.FN +.IP \fIccc\fP 1i +Specifies the CCC. +The CCC's Client White Point and white point adjustment procedures +are ignored. +.IP \fItarget_format\fP 1i +Specifies the target color specification format. +.ds Cs full-intensity green while red and blue are zero +.IP \fIcolor_return\fP 1i +Returns the color specification in the specified target format +for \*(Cs. +The white point associated with the returned +color specification is the Screen White Point. +The value returned in the pixel member is undefined. +.LP +.eM +The +.PN XcmsQueryGreen +function returns the color specification in the specified target format +for full-intensity green while red and blue are zero. +.sp +.LP +To obtain the color specification for red +(full-intensity red while green and blue are zero), use +.PN XcmsQueryRed . +.IN "XcmsQueryRed" "" "@DEF@" +.sM +.FD 0 +Status XcmsQueryRed\^(\^\fIccc\fP\^, \fItarget_format\fP\^, \fIcolor_return\fP\^) +.br + XcmsCCC \fIccc\fP\^; +.br + XcmsColorFormat \fItarget_format\fP\^; +.br + XcmsColor *\fIcolor_return\fP\^; +.FN +.IP \fIccc\fP 1i +Specifies the CCC. +The CCC's Client White Point and white point adjustment procedures +are ignored. +.IP \fItarget_format\fP 1i +Specifies the target color specification format. +.ds Cs full-intensity red while green and blue are zero +.IP \fIcolor_return\fP 1i +Returns the color specification in the specified target format +for \*(Cs. +The white point associated with the returned +color specification is the Screen White Point. +The value returned in the pixel member is undefined. +.LP +.eM +The +.PN XcmsQueryRed +function returns the color specification in the specified target format +for full-intensity red while green and blue are zero. +.LP +.sp +To obtain the color specification for white +(full-intensity red, green, and blue), use +.PN XcmsQueryWhite . +.IN "XcmsQueryWhite" "" "@DEF@" +.sM +.FD 0 +Status XcmsQueryWhite\^(\^\fIccc\fP\^, \fItarget_format\fP\^, \fIcolor_return\fP\^) +.br + XcmsCCC \fIccc\fP\^; +.br + XcmsColorFormat \fItarget_format\fP\^; +.br + XcmsColor *\fIcolor_return\fP\^; +.FN +.IP \fIccc\fP 1i +Specifies the CCC. +The CCC's Client White Point and white point adjustment procedures +are ignored. +.IP \fItarget_format\fP 1i +Specifies the target color specification format. +.ds Cs full-intensity red, green, and blue +.IP \fIcolor_return\fP 1i +Returns the color specification in the specified target format +for \*(Cs. +The white point associated with the returned +color specification is the Screen White Point. +The value returned in the pixel member is undefined. +.LP +.eM +The +.PN XcmsQueryWhite +function returns the color specification in the specified target format +for full-intensity red, green, and blue. +.NH 3 +CIELab Queries +.XS +\*(SN CIELab Queries +.XE +.LP +The following equations are useful in describing the CIELab query functions: +.EQ +delim %% +.EN +.LP +.IN "Psychometric Hue Angle" +.IN "CIE metric lightness" +.IN "Psychometric Chroma" +.IN "Psychometric Chroma" "maximum" +.Ds 0 +%CIELab~Psychometric~Chroma ~=~ sqrt(a_star sup 2 ~+~ b_star sup 2 )% + +%CIELab~Psychometric~Hue ~=~ tan sup -1 left [ b_star over a_star right ]% +.De +.sp +To obtain the CIE L*a*b* coordinates of maximum Psychometric Chroma +for a given Psychometric Hue Angle and CIE metric lightness (L*), use +.PN XcmsCIELabQueryMaxC . +.IN "XcmsCIELabQueryMaxC" "" "@DEF@" +.sM +.FD 0 +Status XcmsCIELabQueryMaxC\^(\^\fIccc\fP\^, \fIhue_angle\fP\^, \fIL_star\fP\^, \fIcolor_return\fP\^) +.br + XcmsCCC \fIccc\fP\^; +.br + XcmsFloat \fIhue_angle\fP\^; +.br + XcmsFloat \fIL_star\fP\^; +.br + XcmsColor *\fIcolor_return\fP\^; +.FN +.IP \fIccc\fP 1i +Specifies the CCC. +The CCC's Client White Point and white point adjustment procedures +are ignored. +.ds Ha maximum chroma +.IP \fIhue_angle\fP 1i +Specifies the hue angle (in degrees) at which to find \*(Ha. +.ds Ls maximum chroma +.IP \fIL_star\fP 1i +Specifies the lightness (L*) at which to find \*(Ls. +.ds Lc maximum chroma +.ds lC hue angle and lightness +.IP \fIcolor_return\fP 1i +Returns the CIE L*a*b* coordinates of \*(Lc +displayable by the screen for the given \*(lC. +The white point associated with the returned +color specification is the Screen White Point. +The value returned in the pixel member is undefined. +.LP +.eM +The +.PN XcmsCIELabQueryMaxC +function, given a hue angle and lightness, +finds the point of maximum chroma displayable by the screen. +It returns this point in CIE L*a*b* coordinates. +.LP +.sp +To obtain the CIE L*a*b* coordinates of maximum CIE metric lightness (L*) +for a given Psychometric Hue Angle and Psychometric Chroma, use +.PN XcmsCIELabQueryMaxL . +.IN "Psychometric Hue Angle" +.IN "CIE metric lightness" +.IN "CIE metric lightness" "maximum" +.IN "XcmsCIELabQueryMaxL" "" "@DEF@" +.sM +.FD 0 +Status XcmsCIELabQueryMaxL\^(\^\fIccc\fP\^, \fIhue_angle\fP\^, \fIchroma\fP\^, \fIcolor_return\fP\^) +.br + XcmsCCC \fIccc\fP\^; +.br + XcmsFloat \fIhue_angle\fP\^; +.br + XcmsFloat \fIchroma\fP\^; +.br + XcmsColor *\fIcolor_return\fP\^; +.FN +.IP \fIccc\fP 1i +Specifies the CCC. +The CCC's Client White Point and white point adjustment procedures +are ignored. +.ds Ha maximum lightness +.IP \fIhue_angle\fP 1i +Specifies the hue angle (in degrees) at which to find \*(Ha. +.ds Ch maximum lightness +.IP \fIchroma\fP 1i +Specifies the chroma at which to find \*(Ch. +.ds Lc maximum lightness +.ds lC hue angle and chroma +.IP \fIcolor_return\fP 1i +Returns the CIE L*a*b* coordinates of \*(Lc +displayable by the screen for the given \*(lC. +The white point associated with the returned +color specification is the Screen White Point. +The value returned in the pixel member is undefined. +.LP +.eM +The +.PN XcmsCIELabQueryMaxL +function, given a hue angle and chroma, +finds the point in CIE L*a*b* color space of maximum +lightness (L*) displayable by the screen. +It returns this point in CIE L*a*b* coordinates. +An +.PN XcmsFailure +return value usually indicates that the given chroma +is beyond maximum for the given hue angle. +.sp +.LP +To obtain the CIE L*a*b* coordinates of maximum Psychometric Chroma +for a given Psychometric Hue Angle, use +.PN XcmsCIELabQueryMaxLC . +.IN "Psychometric Hue Angle" +.IN "Psychometric Chroma" +.IN "CIE metric lightness" +.IN "Psychometric Chroma" "maximum" +.IN "CIE metric lightness" "maximum" +.IN "XcmsCIELabQueryMaxLC" "" "@DEF@" +.sM +.FD 0 +Status XcmsCIELabQueryMaxLC\^(\^\fIccc\fP\^, \fIhue_angle\fP\^, \fIcolor_return\fP\^) +.br + XcmsCCC \fIccc\fP\^; +.br + XcmsFloat \fIhue_angle\fP\^; +.br + XcmsColor *\fIcolor_return\fP\^; +.FN +.IP \fIccc\fP 1i +Specifies the CCC. +The CCC's Client White Point and white point adjustment procedures +are ignored. +.ds Ha maximum chroma +.IP \fIhue_angle\fP 1i +Specifies the hue angle (in degrees) at which to find \*(Ha. +.ds Lc maximum chroma +.ds lC hue angle +.IP \fIcolor_return\fP 1i +Returns the CIE L*a*b* coordinates of \*(Lc +displayable by the screen for the given \*(lC. +The white point associated with the returned +color specification is the Screen White Point. +The value returned in the pixel member is undefined. +.LP +.eM +The +.PN XcmsCIELabQueryMaxLC +function, given a hue angle, +finds the point of maximum chroma displayable by the screen. +It returns this point in CIE L*a*b* coordinates. +.sp +.LP +To obtain the CIE L*a*b* coordinates of minimum CIE metric lightness (L*) +for a given Psychometric Hue Angle and Psychometric Chroma, use +.PN XcmsCIELabQueryMinL . +.IN "Psychometric Hue Angle" +.IN "CIE metric lightness" +.IN "CIE metric lightness" "minimum" +.IN "XcmsCIELabQueryMinL" "" "@DEF@" +.sM +.FD 0 +Status XcmsCIELabQueryMinL\^(\^\fIccc\fP\^, \fIhue_angle\fP\^, \fIchroma\fP\^, \fIcolor_return\fP\^) +.br + XcmsCCC \fIccc\fP\^; +.br + XcmsFloat \fIhue_angle\fP\^; +.br + XcmsFloat \fIchroma\fP\^; +.br + XcmsColor *\fIcolor_return\fP\^; +.FN +.IP \fIccc\fP 1i +Specifies the CCC. +The CCC's Client White Point and white point adjustment procedures +are ignored. +.ds Ha minimum lightness +.IP \fIhue_angle\fP 1i +Specifies the hue angle (in degrees) at which to find \*(Ha. +.ds Ch minimum lightness +.IP \fIchroma\fP 1i +Specifies the chroma at which to find \*(Ch. +.ds Lc minimum lightness +.ds lC hue angle and chroma +.IP \fIcolor_return\fP 1i +Returns the CIE L*a*b* coordinates of \*(Lc +displayable by the screen for the given \*(lC. +The white point associated with the returned +color specification is the Screen White Point. +The value returned in the pixel member is undefined. +.LP +.eM +The +.PN XcmsCIELabQueryMinL +function, given a hue angle and chroma, +finds the point of minimum lightness (L*) displayable by the screen. +It returns this point in CIE L*a*b* coordinates. +An +.PN XcmsFailure +return value usually indicates that the given chroma +is beyond maximum for the given hue angle. +.NH 3 +CIELuv Queries +.XS +\*(SN CIELuv Queries +.XE +.LP +The following equations are useful in describing the CIELuv query functions: +.EQ +delim %% +.EN +.LP +.IN "Psychometric Hue Angle" +.IN "CIE metric lightness" +.IN "Psychometric Chroma" +.IN "Psychometric Chroma" "maximum" +.Ds 0 +%CIELuv~Psychometric~Chroma ~=~ sqrt(u_star sup 2 ~+~ v_star sup 2 )% + +%CIELuv~Psychometric~Hue ~=~ tan sup -1 left [ v_star over u_star right ]% +.De +.sp +.LP +To obtain the CIE L*u*v* coordinates of maximum Psychometric Chroma +for a given Psychometric Hue Angle and CIE metric lightness (L*), use +.PN XcmsCIELuvQueryMaxC . +.IN "XcmsCIELuvQueryMaxC" "" "@DEF@" +.sM +.FD 0 +Status XcmsCIELuvQueryMaxC\^(\^\fIccc\fP\^, \fIhue_angle\fP\^, \fIL_star\fP\^, \fIcolor_return\fP\^) +.br + XcmsCCC \fIccc\fP\^; +.br + XcmsFloat \fIhue_angle\fP\^; +.br + XcmsFloat \fIL_star\fP\^; +.br + XcmsColor *\fIcolor_return\fP\^; +.FN +.IP \fIccc\fP 1i +Specifies the CCC. +The CCC's Client White Point and white point adjustment procedures +are ignored. +.ds Ha maximum chroma +.IP \fIhue_angle\fP 1i +Specifies the hue angle (in degrees) at which to find \*(Ha. +.ds Ls maximum chroma +.IP \fIL_star\fP 1i +Specifies the lightness (L*) at which to find \*(Ls. +.ds Lc maximum chroma +.ds lC hue angle and lightness +.IP \fIcolor_return\fP 1i +Returns the CIE L*u*v* coordinates of \*(Lc +displayable by the screen for the given \*(lC. +The white point associated with the returned +color specification is the Screen White Point. +The value returned in the pixel member is undefined. +.LP +.eM +The +.PN XcmsCIELuvQueryMaxC +function, given a hue angle and lightness, +finds the point of maximum chroma displayable by the screen. +It returns this point in CIE L*u*v* coordinates. +.sp +.LP +To obtain the CIE L*u*v* coordinates of maximum CIE metric lightness (L*) +for a given Psychometric Hue Angle and Psychometric Chroma, use +.PN XcmsCIELuvQueryMaxL . +.IN "Psychometric Hue Angle" +.IN "CIE metric lightness" +.IN "CIE metric lightness" "maximum" +.IN "XcmsCIELuvQueryMaxL" "" "@DEF@" +.sM +.FD 0 +Status XcmsCIELuvQueryMaxL\^(\^\fIccc\fP\^, \fIhue_angle\fP\^, \fIchroma\fP\^, \fIcolor_return\fP\^) +.br + XcmsCCC \fIccc\fP\^; +.br + XcmsFloat \fIhue_angle\fP\^; +.br + XcmsFloat \fIchroma\fP\^; +.br + XcmsColor *\fIcolor_return\fP\^; +.FN +.IP \fIccc\fP 1i +Specifies the CCC. +The CCC's Client White Point and white point adjustment procedures +are ignored. +.ds Ha maximum lightness +.IP \fIhue_angle\fP 1i +Specifies the hue angle (in degrees) at which to find \*(Ha. +.ds Ls maximum lightness +.IP \fIL_star\fP 1i +Specifies the lightness (L*) at which to find \*(Ls. +.ds Lc maximum lightness +.ds lC hue angle and chroma +.IP \fIcolor_return\fP 1i +Returns the CIE L*u*v* coordinates of \*(Lc +displayable by the screen for the given \*(lC. +The white point associated with the returned +color specification is the Screen White Point. +The value returned in the pixel member is undefined. +.LP +.eM +The +.PN XcmsCIELuvQueryMaxL +function, given a hue angle and chroma, +finds the point in CIE L*u*v* color space of maximum +lightness (L*) displayable by the screen. +It returns this point in CIE L*u*v* coordinates. +An +.PN XcmsFailure +return value usually indicates that the given chroma +is beyond maximum for the given hue angle. +.sp +.LP +To obtain the CIE L*u*v* coordinates of maximum Psychometric Chroma +for a given Psychometric Hue Angle, use +.PN XcmsCIELuvQueryMaxLC . +.IN "Psychometric Hue Angle" +.IN "Psychometric Chroma" +.IN "CIE metric lightness" +.IN "Psychometric Chroma" "maximum" +.IN "CIE metric lightness" "maximum" +.IN "XcmsCIELuvQueryMaxLC" "" "@DEF@" +.sM +.FD 0 +Status XcmsCIELuvQueryMaxLC\^(\^\fIccc\fP\^, \fIhue_angle\fP\^, \fIcolor_return\fP\^) +.br + XcmsCCC \fIccc\fP\^; +.br + XcmsFloat \fIhue_angle\fP\^; +.br + XcmsColor *\fIcolor_return\fP\^; +.FN +.IP \fIccc\fP 1i +Specifies the CCC. +The CCC's Client White Point and white point adjustment procedures +are ignored. +.ds Ha maximum chroma +.IP \fIhue_angle\fP 1i +Specifies the hue angle (in degrees) at which to find \*(Ha. +.ds Lc maximum chroma +.ds lC hue angle +.IP \fIcolor_return\fP 1i +Returns the CIE L*u*v* coordinates of \*(Lc +displayable by the screen for the given \*(lC. +The white point associated with the returned +color specification is the Screen White Point. +The value returned in the pixel member is undefined. +.LP +.eM +The +.PN XcmsCIELuvQueryMaxLC +function, given a hue angle, +finds the point of maximum chroma displayable by the screen. +It returns this point in CIE L*u*v* coordinates. +.sp +.LP +To obtain the CIE L*u*v* coordinates of minimum CIE metric lightness (L*) +for a given Psychometric Hue Angle and Psychometric Chroma, use +.PN XcmsCIELuvQueryMinL . +.IN "Psychometric Hue Angle" +.IN "CIE metric lightness" +.IN "CIE metric lightness" "minimum" +.IN "XcmsCIELuvQueryMinL" "" "@DEF@" +.sM +.FD 0 +Status XcmsCIELuvQueryMinL\^(\^\fIccc\fP\^, \fIhue_angle\fP\^, \fIchroma\fP\^, \fIcolor_return\fP\^) +.br + XcmsCCC \fIccc\fP\^; +.br + XcmsFloat \fIhue_angle\fP\^; +.br + XcmsFloat \fIchroma\fP\^; +.br + XcmsColor *\fIcolor_return\fP\^; +.FN +.IP \fIccc\fP 1i +Specifies the CCC. +The CCC's Client White Point and white point adjustment procedures +are ignored. +.ds Ha minimum lightness +.IP \fIhue_angle\fP 1i +Specifies the hue angle (in degrees) at which to find \*(Ha. +.ds Ch minimum lightness +.IP \fIchroma\fP 1i +Specifies the chroma at which to find \*(Ch. +.ds Lc minimum lightness +.ds lC hue angle and chroma +.IP \fIcolor_return\fP 1i +Returns the CIE L*u*v* coordinates of \*(Lc +displayable by the screen for the given \*(lC. +The white point associated with the returned +color specification is the Screen White Point. +The value returned in the pixel member is undefined. +.LP +.eM +The +.PN XcmsCIELuvQueryMinL +function, given a hue angle and chroma, +finds the point of minimum lightness (L*) displayable by the screen. +It returns this point in CIE L*u*v* coordinates. +An +.PN XcmsFailure +return value usually indicates that the given chroma +is beyond maximum for the given hue angle. +.NH 3 +TekHVC Queries +.XS +\*(SN TekHVC Queries +.XE +.LP +To obtain the maximum Chroma for a given Hue and Value, use +.PN XcmsTekHVCQueryMaxC . +.IN "Chroma" +.IN "Chroma" "maximum" +.IN "XcmsTekHVCQueryMaxC" "" "@DEF@" +.sM +.FD 0 +Status XcmsTekHVCQueryMaxC\^(\^\fIccc\fP\^, \fIhue\fP\^, \fIvalue\fP\^, \fIcolor_return\fP\^) +.br + XcmsCCC \fIccc\fP\^; +.br + XcmsFloat \fIhue\fP\^; +.br + XcmsFloat \fIvalue\fP\^; +.br + XcmsColor *\fIcolor_return\fP\^; +.FN +.IP \fIccc\fP 1i +Specifies the CCC. +The CCC's Client White Point and white point adjustment procedures +are ignored. +.ds Hu in which to find the maximum Chroma +.IP \fIhue\fP 1i +Specifies the Hue \*(Hu. +.ds Va maximum Chroma +.IP \fIvalue\fP 1i +Specifies the Value in which to find the \*(Va. +.ds Lc maximum Chroma along with the actual Hue and Value +.ds lC maximum Chroma +.IP \fIcolor_return\fP 1i +Returns the \*(Lc at which the \*(lC was found. +The white point associated with the returned +color specification is the Screen White Point. +The value returned in the pixel member is undefined. +.LP +.eM +The +.PN XcmsTekHVCQueryMaxC +function, given a Hue and Value, +determines the maximum Chroma in TekHVC color space +displayable by the screen. +It returns the maximum Chroma along with the actual Hue +and Value at which the maximum Chroma was found. +.sp +.LP +To obtain the maximum Value for a given Hue and Chroma, use +.PN XcmsTekHVCQueryMaxV . +.IN "Value" +.IN "Value" "maximum" +.IN "XcmsTekHVCQueryMaxV" "" "@DEF@" +.sM +.FD 0 +Status XcmsTekHVCQueryMaxV\^(\^\fIccc\fP\^, \fIhue\fP\^, \fIchroma\fP\^, \fIcolor_return\fP\^) +.br + XcmsCCC \fIccc\fP\^; +.br + XcmsFloat \fIhue\fP\^; +.br + XcmsFloat \fIchroma\fP\^; +.br + XcmsColor *\fIcolor_return\fP\^; +.FN +.IP \fIccc\fP 1i +Specifies the CCC. +The CCC's Client White Point and white point adjustment procedures +are ignored. +.ds Hu in which to find the maximum Value +.IP \fIhue\fP 1i +Specifies the Hue \*(Hu. +.ds Ch maximum Value +.IP \fIchroma\fP 1i +Specifies the chroma at which to find \*(Ch. +.ds Lc maximum Value along with the Hue and Chroma +.ds lC maximum Value +.IP \fIcolor_return\fP 1i +Returns the \*(Lc at which the \*(lC was found. +The white point associated with the returned +color specification is the Screen White Point. +The value returned in the pixel member is undefined. +.LP +.eM +The +.PN XcmsTekHVCQueryMaxV +function, given a Hue and Chroma, +determines the maximum Value in TekHVC color space +displayable by the screen. +It returns the maximum Value and the actual Hue and Chroma +at which the maximum Value was found. +.sp +.LP +To obtain the maximum Chroma and Value at which it is reached +for a specified Hue, use +.PN XcmsTekHVCQueryMaxVC . +.IN "Chroma" +.IN "Value" +.IN "Chroma" "maximum" +.IN "Value" "maximum" +.IN "XcmsTekHVCQueryMaxVC" "" "@DEF@" +.sM +.FD 0 +Status XcmsTekHVCQueryMaxVC\^(\^\fIccc\fP\^, \fIhue\fP\^, \fIcolor_return\fP\^) +.br + XcmsCCC \fIccc\fP\^; +.br + XcmsFloat \fIhue\fP\^; +.br + XcmsColor *\fIcolor_return\fP\^; +.FN +.IP \fIccc\fP 1i +Specifies the CCC. +The CCC's Client White Point and white point adjustment procedures +are ignored. +.ds Hu in which to find the maximum Chroma +.IP \fIhue\fP 1i +Specifies the Hue \*(Hu. +.ds Lc color specification in \ +XcmsTekHVC for the maximum Chroma, the Value at which \ +that maximum Chroma is reached, and the actual Hue +.ds lC maximum Chroma +.IP \fIcolor_return\fP 1i +Returns the \*(Lc at which the \*(lC was found. +The white point associated with the returned +color specification is the Screen White Point. +The value returned in the pixel member is undefined. +.LP +.eM +The +.PN XcmsTekHVCQueryMaxVC +function, given a Hue, +determines the maximum Chroma in TekHVC color space displayable by the screen +and the Value at which that maximum Chroma is reached. +It returns the maximum Chroma, +the Value at which that maximum Chroma is reached, +and the actual Hue for which the maximum Chroma was found. +.sp +.LP +To obtain a specified number of TekHVC specifications such that they +contain maximum Values for a specified Hue and the +Chroma at which the maximum Values are reached, use +.PN XcmsTekHVCQueryMaxVSamples . +.IN "Chroma" +.IN "Value" +.IN "Chroma" "maximum" +.IN "Value" "maximum" +.IN "XcmsTekHVCQueryMaxVSamples" "" "@DEF@" +.sM +.FD 0 +Status XcmsTekHVCQueryMaxVSamples\^(\^\fIccc\fP\^, \fIhue\fP\^, \fIcolors_return\fP\^, \fInsamples\fP\^) +.br + XcmsCCC \fIccc\fP\^; +.br + XcmsFloat \fIhue\fP\^; +.br + XcmsColor \fIcolors_return[]\fP\^; +.br + unsigned int \fInsamples\fP\^; +.FN +.IP \fIccc\fP 1i +Specifies the CCC. +The CCC's Client White Point and white point adjustment procedures +are ignored. +.ds Hu for maximum Chroma/Value samples +.IP \fIhue\fP 1i +Specifies the Hue \*(Hu. +.IP \fInsamples\fP 1i +Specifies the number of samples. +.IP \fIcolors_return\fP 1i +Returns nsamples of color specifications in XcmsTekHVC +such that the Chroma is the maximum attainable for the Value and Hue. +The white point associated with the returned +color specification is the Screen White Point. +The value returned in the pixel member is undefined. +.LP +.eM +The +.PN XcmsTekHVCQueryMaxVSamples +returns nsamples of maximum Value, the Chroma at which that maximum Value +is reached, and the actual Hue for which the maximum Chroma was found. +These sample points may then be used to plot the maximum Value/Chroma +boundary of the screen's color gamut for the specified Hue in TekHVC color +space. +.sp +.LP +To obtain the minimum Value for a given Hue and Chroma, use +.PN XcmsTekHVCQueryMinV . +.IN "Value" +.IN "Value" "minimum" +.IN "XcmsTekHVCQueryMinV" "" "@DEF@" +.sM +.FD 0 +Status XcmsTekHVCQueryMinV\^(\^\fIccc\fP\^, \fIhue\fP\^, \fIchroma\fP\^, \fIcolor_return\fP\^) +.br + XcmsCCC \fIccc\fP\^; +.br + XcmsFloat \fIhue\fP\^; +.br + XcmsFloat \fIchroma\fP\^; +.br + XcmsColor *\fIcolor_return\fP\^; +.FN +.IP \fIccc\fP 1i +Specifies the CCC. +The CCC's Client White Point and white point adjustment procedures +are ignored. +.ds Hu in which to find the minimum Value +.IP \fIhue\fP 1i +Specifies the Hue \*(Hu. +.ds Va minimum Value +.IP \fIvalue\fP 1i +Specifies the Value in which to find the \*(Va. +.ds Lc minimum Value and the actual Hue and Chroma +.ds lC minimum Value +.IP \fIcolor_return\fP 1i +Returns the \*(Lc at which the \*(lC was found. +The white point associated with the returned +color specification is the Screen White Point. +The value returned in the pixel member is undefined. +.LP +.eM +The +.PN XcmsTekHVCQueryMinV +function, given a Hue and Chroma, +determines the minimum Value in TekHVC color space displayable by the screen. +It returns the minimum Value and the actual Hue and Chroma at which +the minimum Value was found. +.NH 2 +Color Management Extensions +.XS +\*(SN Color Management Extensions +.XE +.LP +The Xlib color management facilities can be extended in two ways: +.IP \(bu 5 +Device-Independent Color Spaces +.IP +Device-independent color spaces that are derivable to CIE XYZ +space can be added using the +.PN XcmsAddColorSpace +function. +.IP \(bu 5 +Color Characterization Function Set +.IP +A Color Characterization Function Set consists of +device-dependent color spaces and their functions that +convert between these color spaces and the CIE XYZ +color space, bundled together for a specific class of output devices. +A function set can be added using the +.PN XcmsAddFunctionSet +function. +.NH 3 +Color Spaces +.XS +\*(SN Color Spaces +.XE +.LP +The CIE XYZ color space serves as the hub for all +conversions between device-independent and device-dependent color spaces. +Therefore, the knowledge to convert an +.PN XcmsColor +structure to and from CIE XYZ format is associated with each color space. +For example, conversion from CIE L*u*v* to RGB requires the knowledge +to convert from CIE L*u*v* to CIE XYZ and from CIE XYZ to RGB. +This knowledge is stored as an array of functions that, +when applied in series, will convert the +.PN XcmsColor +structure to or from CIE XYZ format. +This color specification conversion mechanism facilitates +the addition of color spaces. +.LP +Of course, when converting between only device-independent color spaces +or only device-dependent color spaces, +shortcuts are taken whenever possible. +For example, conversion from TekHVC to CIE L*u*v* is performed +by intermediate conversion to CIE u*v*Y and then to CIE L*u*v*, +thus bypassing conversion between CIE u*v*Y and CIE XYZ. +.NH 3 +Adding Device-Independent Color Spaces +.XS +\*(SN Adding Device-Independent Color Spaces +.XE +.LP +To add a device-independent color space, use +.PN XcmsAddColorSpace . +.IN "XcmsAddColorSpace" "" "@DEF@" +.sM +.FD 0 +Status XcmsAddColorSpace\^(\^\fIcolor_space\fP\^) +.br + XcmsColorSpace *\fIcolor_space\fP\^; +.FN +.IP \fIcolor_space\fP 1i +Specifies the device-independent color space to add. +.LP +.eM +The +.PN XcmsAddColorSpace +function makes a device-independent color space (actually an +.PN XcmsColorSpace +structure) accessible by the color management system. +Because format values for unregistered color spaces are assigned at run time, +they should be treated as private to the client. +If references to an unregistered color space must be made +outside the client (for example, storing color specifications +in a file using the unregistered color space), +then reference should be made by color space prefix +(see +.PN XcmsFormatOfPrefix +and +.PN XcmsPrefixOfFormat ). +.LP +If the +.PN XcmsColorSpace +structure is already accessible in the color management system, +.PN XcmsAddColorSpace +returns +.PN XcmsSuccess . +.LP +Note that added +.PN XcmsColorSpaces +must be retained for reference by Xlib. +.NH 3 +Querying Color Space Format and Prefix +.XS +\*(SN Querying Color Space Format and Prefix +.XE +.LP +To obtain the format associated with the color space +associated with a specified color string prefix, use +.PN XcmsFormatOfPrefix . +.IN "XcmsFormatOfPrefix" "" "@DEF@" +.sM +.FD 0 +XcmsColorFormat XcmsFormatOfPrefix\^(\^\fIprefix\fP\^) +.br + char *\fIprefix\fP\^; +.FN +.IP \fIprefix\fP 1i +Specifies the string that contains the color space prefix. +.LP +.eM +The +.PN XcmsFormatOfPrefix +function returns the format for the specified color space prefix +(for example, the string ``CIEXYZ''). +The prefix is case-insensitive. +If the color space is not accessible in the color management system, +.PN XcmsFormatOfPrefix +returns +.PN XcmsUndefinedFormat . +.LP +.sp +To obtain the color string prefix associated with the color space +specified by a color format, use +.PN XcmsPrefixOfFormat . +.IN "XcmsPrefixOfFormat" "" "@DEF@" +.sM +.FD 0 +char *XcmsPrefixOfFormat\^(\^\fIformat\fP\^) +.br + XcmsColorFormat \fIformat\fP\^; +.FN +.IP \fIformat\fP 1i +Specifies the color specification format. +.LP +.eM +The +.PN XcmsPrefixOfFormat +function returns the string prefix associated with the color specification +encoding specified by the format argument. +Otherwise, if no encoding is found, it returns NULL. +The returned string must be treated as read-only. +.NH 3 +Creating Additional Color Spaces +.XS +\*(SN Creating Additional Color Spaces +.XE +.LP +Color space specific information necessary +for color space conversion and color string parsing is stored in an +.PN XcmsColorSpace +structure. +Therefore, a new structure containing this information is required +for each additional color space. +In the case of device-independent color spaces, +a handle to this new structure (that is, by means of a global variable) +is usually made accessible to the client program for use with the +.PN XcmsAddColorSpace +function. +.LP +If a new +.PN XcmsColorSpace +structure specifies a color space not registered with the X Consortium, +they should be treated as private to the client +because format values for unregistered color spaces are assigned at run time. +If references to an unregistered color space must be made outside the +client (for example, storing color specifications in a file using the +unregistered color space), then reference should be made by color space prefix +(see +.PN XcmsFormatOfPrefix +and +.PN XcmsPrefixOfFormat ). +.sM +.LP +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef (*XcmsConversionProc)(); +typedef XcmsConversionProc *XcmsFuncListPtr; + /* A NULL terminated list of function pointers*/ + +typedef struct _XcmsColorSpace { + char *prefix; + XcmsColorFormat format; + XcmsParseStringProc parseString; + XcmsFuncListPtr to_CIEXYZ; + XcmsFuncListPtr from_CIEXYZ; + int inverse_flag; +} XcmsColorSpace; +.De +.LP +.eM +The prefix member specifies the prefix that indicates a color string +is in this color space's string format. +For example, the strings ``ciexyz'' or ``CIEXYZ'' for CIE XYZ, +and ``rgb'' or ``RGB'' for RGB. +The prefix is case insensitive. +The format member specifies the color specification format. +Formats for unregistered color spaces are assigned at run time. +The parseString member contains a pointer to the function +that can parse a color string into an +.PN XcmsColor +structure. +This function returns an integer (int): nonzero if it succeeded +and zero otherwise. +The to_CIEXYZ and from_CIEXYZ members contain pointers, +each to a NULL terminated list of function pointers. +When the list of functions is executed in series, +it will convert the color specified in an +.PN XcmsColor +structure from/to the current color space format to/from the CIE XYZ format. +Each function returns an integer (int): nonzero if it succeeded +and zero otherwise. +The white point to be associated with the colors is specified +explicitly, even though white points can be found in the CCC. +The inverse_flag member, if nonzero, specifies that for each function listed +in to_CIEXYZ, +its inverse function can be found in from_CIEXYZ such that: +.LP +.Ds 0 +Given: n = number of functions in each list + +for each i, such that 0 <= i < n + from_CIEXYZ[n - i - 1] is the inverse of to_CIEXYZ[i]. +.De +.LP +This allows Xlib to use the shortest conversion path, +thus bypassing CIE XYZ if possible (for example, TekHVC to CIE L*u*v*). +.NH 3 +Parse String Callback +.XS +\*(SN Parse String Callback +.XE +.LP +The callback in the +.PN XcmsColorSpace +structure for parsing a color string for the particular color space must +adhere to the following software interface specification: +.IN "XcmsParseStringProc" "" "@DEF@" +.sM +.FD 0 +typedef int (*XcmsParseStringProc)\^(\^\fIcolor_string\fP, \fIcolor_return\fP\^) +.br + char *\fIcolor_string\fP\^; +.br + XcmsColor *\fIcolor_return\fP\^; +.FN +.IP \fIcolor_string\fP 1i +Specifies the color string to parse. +.IP \fIcolor_return\fP 1i +Returns the color specification in the color space's format. +.LP +.eM +.NH 3 +Color Specification Conversion Callback +.XS +\*(SN Color Specification Conversion Callback +.XE +.LP +Callback functions in the +.PN XcmsColorSpace +structure for converting a color specification between device-independent +spaces must adhere to the +following software interface specification: +.sM +.FD 0 +Status ConversionProc\^(\^\fIccc\fP, \fIwhite_point\fP, \fIcolors_in_out\fP, \fIncolors\fP\^) +.br + XcmsCCC \fIccc\fP\^; +.br + XcmsColor *\fIwhite_point\fP\^; +.br + XcmsColor *\fIcolors_in_out\fP\^; +.br + unsigned int \fIncolors\fP\^; +.FN +.IP \fIccc\fP 1i +Specifies the CCC. +.IP \fIwhite_point\fP 1i +Specifies the white point associated with color specifications. +The pixel member should be ignored, +and the entire structure remain unchanged upon return. +.IP \fIcolors_in_out\fP 1i +Specifies an array of color specifications. +Pixel members should be ignored and must remain unchanged upon return. +.IP \fIncolors\fP 1i +Specifies the number of +.PN XcmsColor +structures in the color-specification array. +.LP +.eM +.sp +Callback functions in the +.PN XcmsColorSpace +structure for converting a color specification to or from a device-dependent +space must adhere to the +following software interface specification: +.sM +.FD 0 +Status ConversionProc\^(\^\fIccc\fP, \fIcolors_in_out\fP, \fIncolors\fP, \fIcompression_flags_return\fP\^) +.br + XcmsCCC \fIccc\fP\^; +.br + XcmsColor *\fIcolors_in_out\fP\^; +.br + unsigned int \fIncolors\fP\^; +.br + Bool \fIcompression_flags_return\fP\^[\^]\^; +.FN +.IP \fIccc\fP 1i +Specifies the CCC. +.IP \fIcolors_in_out\fP 1i +Specifies an array of color specifications. +Pixel members should be ignored and must remain unchanged upon return. +.IP \fIncolors\fP 1i +Specifies the number of +.PN XcmsColor +structures in the color-specification array. +.IP \fIcompression_flags_return\fP 1i +Returns an array of Boolean values for indicating compression status. +If a non-NULL pointer is supplied +and a color at a given index is compressed, then +.PN True +should be stored at the corresponding index in this array; +otherwise, the array should not be modified. +.LP +.eM +Conversion functions are available globally for use by other color +spaces. +The conversion functions provided by Xlib are: +.TS H +lw(1.8i) lw(1.8i) lw(1.8i). +_ +.sp 6p +.B +Function Converts from Converts to +.sp 6p +_ +.sp 6p +.TH +.R +T{ +.PN XcmsCIELabToCIEXYZ +T} T{ +.PN XcmsCIELabFormat +T} T{ +.PN XcmsCIEXYZFormat +T} +T{ +.PN XcmsCIELuvToCIEuvY +T} T{ +.PN XcmsCIELuvFormat +T} T{ +.PN XcmsCIEuvYFormat +T} +T{ +.PN XcmsCIEXYZToCIELab +T} T{ +.PN XcmsCIEXYZFormat +T} T{ +.PN XcmsCIELabFormat +T} +T{ +.PN XcmsCIEXYZToCIEuvY +T} T{ +.PN XcmsCIEXYZFormat +T} T{ +.PN XcmsCIEuvYFormat +T} +T{ +.PN XcmsCIEXYZToCIExyY +T} T{ +.PN XcmsCIEXYZFormat +T} T{ +.PN XcmsCIExyYFormat +T} +T{ +.PN XcmsCIEXYZToRGBi +T} T{ +.PN XcmsCIEXYZFormat +T} T{ +.PN XcmsRGBiFormat +T} +T{ +.PN XcmsCIEuvYToCIELuv +T} T{ +.PN XcmsCIEuvYFormat +T} T{ +.PN XcmsCIELabFormat +T} +T{ +.PN XcmsCIEuvYToCIEXYZ +T} T{ +.PN XcmsCIEuvYFormat +T} T{ +.PN XcmsCIEXYZFormat +T} +T{ +.PN XcmsCIEuvYToTekHVC +T} T{ +.PN XcmsCIEuvYFormat +T} T{ +.PN XcmsTekHVCFormat +T} +T{ +.PN XcmsCIExyYToCIEXYZ +T} T{ +.PN XcmsCIExyYFormat +T} T{ +.PN XcmsCIEXYZFormat +T} +T{ +.PN XcmsRGBToRGBi +T} T{ +.PN XcmsRGBFormat +T} T{ +.PN XcmsRGBiFormat +T} +T{ +.PN XcmsRGBiToCIEXYZ +T} T{ +.PN XcmsRGBiFormat +T} T{ +.PN XcmsCIEXYZFormat +T} +T{ +.PN XcmsRGBiToRGB +T} T{ +.PN XcmsRGBiFormat +T} T{ +.PN XcmsRGBFormat +T} +T{ +.PN XcmsTekHVCToCIEuvY +T} T{ +.PN XcmsTekHVCFormat +T} T{ +.PN XcmsCIEuvYFormat +T} +.sp 6p +_ +.TE +.NH 3 +Function Sets +.XS +\*(SN Function Sets +.XE +.IN "Function set" +.IN "Function set" "LINEAR_RGB" +.LP +Functions to convert between device-dependent color spaces +and CIE XYZ may differ for different classes of output devices +(for example, color versus gray monitors). +Therefore, the notion of a Color Characterization Function Set +has been developed. +A function set consists of device-dependent color spaces +and the functions that convert color specifications +between these device-dependent color spaces and the CIE XYZ color space +appropriate for a particular class of output devices. +The function set also contains a function that reads +color characterization data off root window properties. +It is this characterization data that will differ between devices within +a class of output devices. +.IN "Device Color Characterization" +For details about how color characterization data is +stored in root window properties, +see the section on Device Color Characterization in the +\fIInter-Client Communication Conventions Manual\fP. +The LINEAR_RGB function set is provided by Xlib +and will support most color monitors. +Function sets may require data that differs +from those needed for the LINEAR_RGB function set. +In that case, +its corresponding data may be stored on different root window properties. +.NH 3 +Adding Function Sets +.XS +\*(SN Adding Function Sets +.XE +.LP +To add a function set, use +.PN XcmsAddFunctionSet . +.IN "XcmsAddFunctionSet" "" "@DEF@" +.sM +.FD 0 +Status XcmsAddFunctionSet\^(\^\fIfunction_set\fP\^) +.br + XcmsFunctionSet *\fIfunction_set\fP\^; +.FN +.IP \fIfunction_set\fP 1i +Specifies the function set to add. +.LP +.eM +The +.PN XcmsAddFunctionSet +function adds a function set to the color management system. +If the function set uses device-dependent +.PN XcmsColorSpace +structures not accessible in the color management system, +.PN XcmsAddFunctionSet +adds them. +If an added +.PN XcmsColorSpace +structure is for a device-dependent color space not registered +with the X Consortium, +they should be treated as private to the client +because format values for unregistered color spaces are assigned at run time. +If references to an unregistered color space must be made outside the +client (for example, storing color specifications in a file +using the unregistered color space), +then reference should be made by color space prefix +(see +.PN XcmsFormatOfPrefix +and +.PN XcmsPrefixOfFormat ). +.LP +Additional function sets should be added before any calls to other +Xlib routines are made. +If not, the +.PN XcmsPerScrnInfo +member of a previously created +.PN XcmsCCC +does not have the opportunity to initialize +with the added function set. +.NH 3 +Creating Additional Function Sets +.XS +\*(SN Creating Additional Function Sets +.XE +.LP +The creation of additional function sets should be +required only when an output device does not conform to existing +function sets or when additional device-dependent color spaces are necessary. +A function set consists primarily of a collection of device-dependent +.PN XcmsColorSpace +structures and a means to read and store a +screen's color characterization data. +This data is stored in an +.PN XcmsFunctionSet +structure. +A handle to this structure (that is, by means of global variable) +is usually made accessible to the client program for use with +.PN XcmsAddFunctionSet . +.LP +If a function set uses new device-dependent +.PN XcmsColorSpace +structures, +they will be transparently processed into the color management system. +Function sets can share an +.PN XcmsColorSpace +structure for a device-dependent color space. +In addition, multiple +.PN XcmsColorSpace +structures are allowed for a device-dependent color space; +however, a function set can reference only one of them. +These +.PN XcmsColorSpace +structures will differ in the functions to convert to and from CIE XYZ, +thus tailored for the specific function set. +.sM +.LP +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef struct _XcmsFunctionSet { + XcmsColorSpace **DDColorSpaces; + XcmsScreenInitProc screenInitProc; + XcmsScreenFreeProc screenFreeProc; +} XcmsFunctionSet; +.De +.LP +.eM +The DDColorSpaces member is a pointer to a NULL terminated list +of pointers to +.PN XcmsColorSpace +structures for the device-dependent color spaces that are supported +by the function set. +The screenInitProc member is set to the callback procedure (see the following +interface specification) that initializes the +.PN XcmsPerScrnInfo +structure for a particular screen. +.LP +The screen initialization callback must adhere to the following software +interface specification: +.IN "XcmsScreenInitProc" "" "@DEF@" +.sM +.FD 0 +typedef Status (*XcmsScreenInitProc)\^(\^\fIdisplay\fP, \fIscreen_number\fP, \fIscreen_info\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIscreen_number\fP\^; +.br + XcmsPerScrnInfo *\fIscreen_info\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIscreen_number\fP 1i +Specifies the appropriate screen number on the host server. +.IP \fIscreen_info\fP 1i +Specifies the +.PN XcmsPerScrnInfo +structure, which contains the per screen information. +.LP +.eM +The screen initialization callback in the +.PN XcmsFunctionSet +structure fetches the color characterization data (device profile) for +the specified screen, +typically off properties on the +screen's root window. +It then initializes the specified +.PN XcmsPerScrnInfo +structure. +.IN "Device profile" +.IN "Color Characterization Data" +If successful, the procedure fills in the +.PN XcmsPerScrnInfo +structure as follows: +.IP \(bu 5 +It sets the screenData member to the address +of the created device profile data structure +(contents known only by the function set). +.IP \(bu 5 +It next sets the screenWhitePoint member. +.IP \(bu 5 +It next sets the functionSet member to the address of the +.PN XcmsFunctionSet +structure. +.IP \(bu 5 +It then sets the state member to +.PN XcmsInitSuccess +and finally returns +.PN XcmsSuccess . +.LP +If unsuccessful, the procedure sets the state member to +.PN XcmsInitFailure +and returns +.PN XcmsFailure . +.LP +The +.PN XcmsPerScrnInfo +structure contains: +.sM +.LP +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef struct _XcmsPerScrnInfo { + XcmsColor screenWhitePoint; + XPointer functionSet; + XPointer screenData; + unsigned char state; + char pad[3]; +} XcmsPerScrnInfo; +.De +.LP +.eM +The screenWhitePoint member specifies the white point inherent to +the screen. +The functionSet member specifies the appropriate function set. +The screenData member specifies the device profile. +The state member is set to one of the following: +.IP \(bu 5 +.PN XcmsInitNone +indicates initialization has not been previously attempted. +.IP \(bu 5 +.PN XcmsInitFailure +indicates initialization has been previously attempted but failed. +.IP \(bu 5 +.PN XcmsInitSuccess +indicates initialization has been previously attempted and succeeded. +.LP +The screen free callback must adhere to the following software +interface specification: +.IN "XcmsScreenFreeProc" "" "@DEF@" +.sM +.FD 0 +typedef void (*XcmsScreenFreeProc)\^(\^\fIscreenData\fP\^) +.br + XPointer \fIscreenData\fP\^; +.FN +.IP \fIscreenData\fP 1i +Specifies the data to be freed. +.LP +.eM +This function is called to free the screenData stored in an +.PN XcmsPerScrnInfo +structure. +.bp diff --git a/libX11/specs/libX11/CH07 b/libX11/specs/libX11/CH07 new file mode 100644 index 000000000..d6f672289 --- /dev/null +++ b/libX11/specs/libX11/CH07 @@ -0,0 +1,2357 @@ +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be included +.\" in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR +.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +.\" OTHER DEALINGS IN THE SOFTWARE. +.\" +.\" Except as contained in this notice, the name of the X Consortium shall +.\" not be used in advertising or otherwise to promote the sale, use or +.\" other dealings in this Software without prior written authorization +.\" from the X Consortium. +.\" +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by +.\" Digital Equipment Corporation +.\" +.\" Portions Copyright \(co 1990, 1991 by +.\" Tektronix, Inc. +.\" +.\" Permission to use, copy, modify and distribute this documentation for +.\" any purpose and without fee is hereby granted, provided that the above +.\" copyright notice appears in all copies and that both that copyright notice +.\" and this permission notice appear in all copies, and that the names of +.\" Digital and Tektronix not be used in in advertising or publicity pertaining +.\" to this documentation without specific, written prior permission. +.\" Digital and Tektronix makes no representations about the suitability +.\" of this documentation for any purpose. +.\" It is provided ``as is'' without express or implied warranty. +.\" +\& +.sp 1 +.ce 3 +\s+1\fBChapter 7\fP\s-1 + +\s+1\fBGraphics Context Functions\fP\s-1 +.sp 2 +.nr H1 7 +.nr H2 0 +.nr H3 0 +.nr H4 0 +.nr H5 0 +.na +.LP +.XS +Chapter 7: Graphics Context Functions +.XE +A number of resources are used when performing graphics operations in X. +Most information about performing graphics (for example, foreground +color, background color, line style, and so on) is stored in +resources called graphics contexts (GCs). +.IN "Graphics context" +Most graphics operations (see chapter 8) take a +GC as an argument. +Although in theory the X protocol permits sharing of GCs between applications, +it is expected that applications will use their own +GCs when performing operations. +Sharing of GCs is highly discouraged because the library may cache GC state. +.LP +Graphics operations can be performed to either windows or pixmaps, +which collectively are called drawables. +.IN "Root" +Each drawable exists on a single screen. +A GC is created for a specific screen and drawable depth +and can only be used with drawables of matching +screen and depth. +.LP +This chapter discusses how to: +.IP \(bu 5 +Manipulate graphics context/state +.IP \(bu 5 +Use graphics context convenience functions +.NH 2 +Manipulating Graphics Context/State +.XS +\*(SN Manipulating Graphics Context/State +.XE +.LP +Most attributes of graphics operations are stored in GCs. +These include line width, line style, plane mask, foreground, background, +tile, stipple, clipping region, end style, join style, and so on. +Graphics operations (for example, drawing lines) use these values +to determine the actual drawing operation. +Extensions to X may add additional components to GCs. +The contents of a GC are private to Xlib. +.LP +Xlib implements a write-back cache for all elements of a GC that are not +resource IDs to allow Xlib to implement the transparent coalescing of changes +to GCs. +For example, +a call to +.PN XSetForeground +of a GC followed by a call to +.PN XSetLineAttributes +results in only a single-change GC protocol request to the server. +GCs are neither expected nor encouraged to be shared between client +applications, so this write-back caching should present no problems. +Applications cannot share GCs without external synchronization. +Therefore, +sharing GCs between applications is highly discouraged. +.LP +To set an attribute of a GC, +set the appropriate member of the +.PN XGCValues +structure and OR in the corresponding value bitmask in your subsequent calls to +.PN XCreateGC . +The symbols for the value mask bits and the +.PN XGCValues +structure are: +.sM +.LP +/* GC attribute value mask bits */ +.TS +lw(.5i) lw(2.5i) lw(.75i). +#define\ + T{ +.PN GCFunction +T} T{ +(1L<<0) +T} +#define\ + T{ +.PN GCPlaneMask +T} T{ +(1L<<1) +T} +#define\ + T{ +.PN GCForeground +T} T{ +(1L<<2) +T} +#define\ + T{ +.PN GCBackground +T} T{ +(1L<<3) +T} +#define\ + T{ +.PN GCLineWidth +T} T{ +(1L<<4) +T} +#define\ + T{ +.PN GCLineStyle +T} T{ +(1L<<5) +T} +#define\ + T{ +.PN GCCapStyle +T} T{ +(1L<<6) +T} +#define\ + T{ +.PN GCJoinStyle +T} T{ +(1L<<7) +T} +#define\ + T{ +.PN GCFillStyle +T} T{ +(1L<<8) +T} +#define\ + T{ +.PN GCFillRule +T} T{ +(1L<<9) +T} +#define\ + T{ +.PN GCTile +T} T{ +(1L<<10) +T} +#define\ + T{ +.PN GCStipple +T} T{ +(1L<<11) +T} +#define\ + T{ +.PN GCTileStipXOrigin +T} T{ +(1L<<12) +T} +#define\ + T{ +.PN GCTileStipYOrigin +T} T{ +(1L<<13) +T} +#define\ + T{ +.PN GCFont +T} T{ +(1L<<14) +T} +#define\ + T{ +.PN GCSubwindowMode +T} T{ +(1L<<15) +T} +#define\ + T{ +.PN GCGraphicsExposures +T} T{ +(1L<<16) +T} +#define\ + T{ +.PN GCClipXOrigin +T} T{ +(1L<<17) +T} +#define\ + T{ +.PN GCClipYOrigin +T} T{ +(1L<<18) +T} +#define\ + T{ +.PN GCClipMask +T} T{ +(1L<<19) +T} +#define\ + T{ +.PN GCDashOffset +T} T{ +(1L<<20) +T} +#define\ + T{ +.PN GCDashList +T} T{ +(1L<<21) +T} +#define\ + T{ +.PN GCArcMode +T} T{ +(1L<<22) +T} +.TE +.IN "XGCValues" "" "@DEF@" +.Ds 0 +.TA .5i 3i +.ta .5i 3i +/* Values */ + +typedef struct { + int function; /* logical operation */ + unsigned long plane_mask; /* plane mask */ + unsigned long foreground; /* foreground pixel */ + unsigned long background; /* background pixel */ + int line_width; /* line width (in pixels) */ + int line_style; /* LineSolid, LineOnOffDash, LineDoubleDash */ + int cap_style; /* CapNotLast, CapButt, CapRound, CapProjecting */ + int join_style; /* JoinMiter, JoinRound, JoinBevel */ + int fill_style; /* FillSolid, FillTiled, FillStippled FillOpaqueStippled*/ + int fill_rule; /* EvenOddRule, WindingRule */ + int arc_mode; /* ArcChord, ArcPieSlice */ + Pixmap tile; /* tile pixmap for tiling operations */ + Pixmap stipple; /* stipple 1 plane pixmap for stippling */ + int ts_x_origin; /* offset for tile or stipple operations */ + int ts_y_origin; + Font font; /* default text font for text operations */ + int subwindow_mode; /* ClipByChildren, IncludeInferiors */ + Bool graphics_exposures; /* boolean, should exposures be generated */ + int clip_x_origin; /* origin for clipping */ + int clip_y_origin; + Pixmap clip_mask; /* bitmap clipping; other calls for rects */ + int dash_offset; /* patterned/dashed line information */ + char dashes; +} XGCValues; +.De +.LP +.eM +The default GC values are: +.TS H +l l. +_ +.sp 6p +.B +Component Default +.sp 6p +_ +.sp 6p +.TH +.R +T{ +function +T} T{ +.PN GXcopy +T} +plane_mask All ones +foreground 0 +background 1 +line_width 0 +T{ +line_style +T} T{ +.PN LineSolid +T} +T{ +cap_style +T} T{ +.PN CapButt +T} +T{ +join_style +T} T{ +.PN JoinMiter +T} +T{ +fill_style +T} T{ +.PN FillSolid +T} +T{ +fill_rule +T} T{ +.PN EvenOddRule +T} +T{ +arc_mode +T} T{ +.PN ArcPieSlice +T} +tile Pixmap of unspecified size filled with foreground pixel + (that is, client specified pixel if any, else 0) + (subsequent changes to foreground do not affect this pixmap) +stipple Pixmap of unspecified size filled with ones +ts_x_origin 0 +ts_y_origin 0 +font +T{ +subwindow_mode +T} T{ +.PN ClipByChildren +T} +T{ +graphics_exposures +T} T{ +.PN True +T} +clip_x_origin 0 +clip_y_origin 0 +T{ +clip_mask +T} T{ +.PN None +T} +dash_offset 0 +dashes 4 (that is, the list [4, 4]) +.sp 6p +_ +.TE +.LP +Note that foreground and background are not set to any values likely +to be useful in a window. +.LP +.IN "Display Functions" "" "@DEF@" +.IN "Source" "" "@DEF@" +.IN "Destination" "" "@DEF@" +The function attributes of a GC are used when you update a section of +a drawable (the destination) with bits from somewhere else (the source). +The function in a GC defines how the new destination bits are to be +computed from the source bits and the old destination bits. +.PN GXcopy +is typically the most useful because it will work on a color display, +but special applications may use other functions, +particularly in concert with particular planes of a color display. +The 16 GC functions, defined in +.hN X11/X.h , +are: +.\" are listed in Table 5-1 along with the +.\"the associated hexadecimal code +.\" and operation. +.\".CP T 1 +.\"Display Functions +.TS H +lw(1.5i) cw(.5i) lw(2i). +_ +.sp 6p +.B +Function Name Value Operation +.sp 6p +_ +.sp 6p +.TH +T{ +.PN GXclear +T} T{ +0x0 +T} T{ +0 +T} +T{ +.PN GXand +T} T{ +0x1 +T} T{ +src AND dst +T} +T{ +.PN GXandReverse +T} T{ +0x2 +T} T{ +src AND NOT dst +T} +T{ +.PN GXcopy +T} T{ +0x3 +T} T{ +src +T} +T{ +.PN GXandInverted +T} T{ +0x4 +T} T{ +(NOT src) AND dst +T} +T{ +.PN GXnoop +T} T{ +0x5 +T} T{ +dst +T} +T{ +.PN GXxor +T} T{ +0x6 +T} T{ +src XOR dst +T} +T{ +.PN GXor +T} T{ +0x7 +T} T{ +src OR dst +T} +T{ +.PN GXnor +T} T{ +0x8 +T} T{ +(NOT src) AND (NOT dst) +T} +T{ +.PN GXequiv +T} T{ +0x9 +T} T{ +(NOT src) XOR dst +T} +T{ +.PN GXinvert +T} T{ +0xa +T} T{ +NOT dst +T} +T{ +.PN GXorReverse +T} T{ +0xb +T} T{ +src OR (NOT dst) +T} +T{ +.PN GXcopyInverted +T} T{ +0xc +T} T{ +NOT src +T} +T{ +.PN GXorInverted +T} T{ +0xd +T} T{ +(NOT src) OR dst +T} +T{ +.PN GXnand +T} T{ +0xe +T} T{ +(NOT src) OR (NOT dst) +T} +T{ +.PN GXset +T} T{ +0xf +T} T{ +1 +T} +.sp 6p +_ +.TE +.LP +Many graphics operations depend on either pixel values or planes in a GC. +.IN "Pixel value" +The planes attribute is of type long, and it specifies which planes of the +destination are to be modified, one bit per plane. +.IN "Plane" "mask" +A monochrome display has only one plane and +will be the least significant bit of the word. +As planes are added to the display hardware, they will occupy more +significant bits in the plane mask. +.LP +In graphics operations, given a source and destination pixel, +the result is computed bitwise on corresponding bits of the pixels. +That is, a Boolean operation is performed in each bit plane. +The plane_mask restricts the operation to a subset of planes. +A macro constant +.PN AllPlanes +can be used to refer to all planes of the screen simultaneously. +The result is computed by the following: +.LP +.Ds +((src FUNC dst) AND plane-mask) OR (dst AND (NOT plane-mask)) +.De +.LP +Range checking is not performed on the values for foreground, +background, or plane_mask. +They are simply truncated to the appropriate +number of bits. +The line-width is measured in pixels and either can be greater than or equal to +one (wide line) or can be the special value zero (thin line). +.LP +Wide lines are drawn centered on the path described by the graphics request. +Unless otherwise specified by the join-style or cap-style, +the bounding box of a wide line with endpoints [x1, y1], [x2, y2] and +width w is a rectangle with vertices at the following real coordinates: +.LP +.Ds +.TA .5i 2.5i +.ta .5i 2.5i +[x1-(w*sn/2), y1+(w*cs/2)], [x1+(w*sn/2), y1-(w*cs/2)], +[x2-(w*sn/2), y2+(w*cs/2)], [x2+(w*sn/2), y2-(w*cs/2)] +.De +.LP +Here sn is the sine of the angle of the line, +and cs is the cosine of the angle of the line. +A pixel is part of the line and so is drawn +if the center of the pixel is fully inside the bounding box +(which is viewed as having infinitely thin edges). +If the center of the pixel is exactly on the bounding box, +it is part of the line if and only if the interior is immediately to its right +(x increasing direction). +Pixels with centers on a horizontal edge are a special case and are part of +the line if and only if the interior or the boundary is immediately below +(y increasing direction) and the interior or the boundary is immediately +to the right (x increasing direction). +.LP +Thin lines (zero line-width) are one-pixel-wide lines drawn using an +unspecified, device-dependent algorithm. +There are only two constraints on this algorithm. +.IP 1. 5 +If a line is drawn unclipped from [x1,y1] to [x2,y2] and +if another line is drawn unclipped from [x1+dx,y1+dy] to [x2+dx,y2+dy], +a point [x,y] is touched by drawing the first line +if and only if the point [x+dx,y+dy] is touched by drawing the second line. +.IP 2. 5 +The effective set of points comprising a line cannot be affected by clipping. +That is, a point is touched in a clipped line if and only if the point +lies inside the clipping region and the point would be touched +by the line when drawn unclipped. +.LP +A wide line drawn from [x1,y1] to [x2,y2] always draws the same pixels +as a wide line drawn from [x2,y2] to [x1,y1], not counting cap-style +and join-style. +It is recommended that this property be true for thin lines, +but this is not required. +A line-width of zero may differ from a line-width of one in which pixels are +drawn. +This permits the use of many manufacturers' line drawing hardware, +which may run many times faster than the more precisely specified +wide lines. +.LP +In general, +drawing a thin line will be faster than drawing a wide line of width one. +However, because of their different drawing algorithms, +thin lines may not mix well aesthetically with wide lines. +If it is desirable to obtain precise and uniform results across all displays, +a client should always use a line-width of one rather than a line-width of zero. +.LP +The line-style defines which sections of a line are drawn: +.TS +lw(1.3i) lw(4.5i). +T{ +.PN LineSolid +T} T{ +The full path of the line is drawn. +T} +.sp 6p +T{ +.PN LineDoubleDash +T} T{ +The full path of the line is drawn, +but the even dashes are filled differently +from the odd dashes (see fill-style) with +.PN CapButt +style used where even and odd dashes meet. +T} +.sp 6p +T{ +.PN LineOnOffDash +T} T{ +Only the even dashes are drawn, +and cap-style applies to +all internal ends of the individual dashes, +except +.PN CapNotLast +is treated as +.PN CapButt . +T} +.TE +.LP +The cap-style defines how the endpoints of a path are drawn: +.IN "Graphics context" "path" +.TS +lw(1.3i) lw(4.5i). +T{ +.PN CapNotLast +T} T{ +This is equivalent to +.PN CapButt +except that for a line-width of zero the final endpoint is not drawn. +T} +.sp 6p +T{ +.PN CapButt +T} T{ +The line is square at the endpoint (perpendicular to the slope of the line) +with no projection beyond. +T} +.sp 6p +T{ +.PN CapRound +T} T{ +The line has a circular arc with the diameter equal to the line-width, +centered on the endpoint. +(This is equivalent to +.PN CapButt +for line-width of zero). +T} +.sp 6p +T{ +.PN CapProjecting +T} T{ +The line is square at the end, but the path continues beyond the endpoint +for a distance equal to half the line-width. +(This is equivalent to +.PN CapButt +for line-width of zero). +T} +.TE +.LP +The join-style defines how corners are drawn for wide lines: +.TS +lw(1.3i) lw(4.5i). +T{ +.PN JoinMiter +T} T{ +The outer edges of two lines extend to meet at an angle. +However, if the angle is less than 11 degrees, +then a +.PN JoinBevel +join-style is used instead. +T} +.sp 6p +T{ +.PN JoinRound +T} T{ +The corner is a circular arc with the diameter equal to the line-width, +centered on the joinpoint. +T} +.sp 6p +T{ +.PN JoinBevel +T} T{ +The corner has +.PN CapButt +endpoint styles with the triangular notch filled. +T} +.TE +.LP +For a line with coincident endpoints (x1=x2, y1=y2), +when the cap-style is applied to both endpoints, +the semantics depends on the line-width and the cap-style: +.TS +lw(1.3i) lw(.5i) lw(4i). +T{ +.PN CapNotLast +T} T{ +thin +T} T{ +The results are device dependent, +but the desired effect is that nothing is drawn. +T} +.sp 6p +T{ +.PN CapButt +T} T{ +thin +T} T{ +The results are device dependent, +but the desired effect is that a single pixel is drawn. +T} +.sp 6p +T{ +.PN CapRound +T} T{ +thin +T} T{ +The results are the same as for +.PN CapButt /thin. +T} +.sp 6p +T{ +.PN CapProjecting +T} T{ +thin +T} T{ +The results are the same as for +.PN CapButt /thin. +T} +.sp 6p +T{ +.PN CapButt +T} T{ +wide +T} T{ +Nothing is drawn. +T} +.sp 6p +T{ +.PN CapRound +T} T{ +wide +T} T{ +The closed path is a circle, centered at the endpoint, and +with the diameter equal to the line-width. +T} +.sp 6p +T{ +.PN CapProjecting +T} T{ +wide +T} T{ +The closed path is a square, aligned with the coordinate axes, centered at the +endpoint, and with the sides equal to the line-width. +T} +.TE +.LP +For a line with coincident endpoints (x1=x2, y1=y2), +when the join-style is applied at one or both endpoints, +the effect is as if the line was removed from the overall path. +However, if the total path consists of or is reduced to a single point joined +with itself, the effect is the same as when the cap-style is applied at both +endpoints. +.LP +The tile/stipple represents an infinite two-dimensional plane, +with the tile/stipple replicated in all dimensions. +When that plane is superimposed on the drawable +for use in a graphics operation, the upper-left corner +of some instance of the tile/stipple is at the coordinates within +the drawable specified by the tile/stipple origin. +The tile/stipple and clip origins are interpreted relative to the +origin of whatever destination drawable is specified in a graphics +request. +The tile pixmap must have the same root and depth as the GC, +or a +.PN BadMatch +error results. +The stipple pixmap must have depth one and must have the same root as the +GC, or a +.PN BadMatch +error results. +For stipple operations where the fill-style is +.PN FillStippled +but not +.PN FillOpaqueStippled , +the stipple pattern is tiled in a +single plane and acts as an additional clip mask to be ANDed with the clip-mask. +Although some sizes may be faster to use than others, +any size pixmap can be used for tiling or stippling. +.LP +The fill-style defines the contents of the source for line, text, and +fill requests. +For all text and fill requests (for example, +.PN XDrawText , +.PN XDrawText16 , +.PN XFillRectangle , +.PN XFillPolygon , +and +.PN XFillArc ); +for line requests +with line-style +.PN LineSolid +(for example, +.PN XDrawLine , +.PN XDrawSegments , +.PN XDrawRectangle , +.PN XDrawArc ); +and for the even dashes for line requests with line-style +.PN LineOnOffDash +or +.PN LineDoubleDash , +the following apply: +.TS +lw(1.8i) lw(4i). +T{ +.PN FillSolid +T} T{ +Foreground +T} +.sp 6p +T{ +.PN FillTiled +T} T{ +Tile +T} +.sp 6p +T{ +.PN FillOpaqueStippled +T} T{ +A tile with the same width and height as stipple, +but with background everywhere stipple has a zero +and with foreground everywhere stipple has a one +T} +.sp 6p +T{ +.PN FillStippled +T} T{ +Foreground masked by stipple +T} +.TE +.LP +When drawing lines with line-style +.PN LineDoubleDash , +the odd dashes are controlled by the fill-style in the following manner: +.TS +lw(1.8i) lw(4i). +T{ +.PN FillSolid +T} T{ +Background +T} +.sp 6p +T{ +.PN FillTiled +T} T{ +Same as for even dashes +T} +.sp 6p +T{ +.PN FillOpaqueStippled +T} T{ +Same as for even dashes +T} +.sp 6p +T{ +.PN FillStippled +T} T{ +Background masked by stipple +T} +.TE +.LP +Storing a pixmap in a GC might or might not result in a copy +being made. +If the pixmap is later used as the destination for a graphics request, +the change might or might not be reflected in the GC. +If the pixmap is used simultaneously in a graphics request both as +a destination and as a tile or stipple, +the results are undefined. +.LP +For optimum performance, +you should draw as much as possible with the same GC +(without changing its components). +The costs of changing GC components relative to using different GCs +depend on the display hardware and the server implementation. +It is quite likely that some amount of GC information will be +cached in display hardware and that such hardware can only cache a small number +of GCs. +.LP +The dashes value is actually a simplified form of the +more general patterns that can be set with +.PN XSetDashes . +Specifying a +value of N is equivalent to specifying the two-element list [N, N] in +.PN XSetDashes . +The value must be nonzero, +or a +.PN BadValue +error results. +.LP +The clip-mask restricts writes to the destination drawable. +If the clip-mask is set to a pixmap, +it must have depth one and have the same root as the GC, +or a +.PN BadMatch +error results. +If clip-mask is set to +.PN None , +the pixels are always drawn regardless of the clip origin. +The clip-mask also can be set by calling the +.PN XSetClipRectangles +or +.PN XSetRegion +functions. +Only pixels where the clip-mask has a bit set to 1 are drawn. +Pixels are not drawn outside the area covered by the clip-mask +or where the clip-mask has a bit set to 0. +The clip-mask affects all graphics requests. +The clip-mask does not clip sources. +The clip-mask origin is interpreted relative to the origin of whatever +destination drawable is specified in a graphics request. +.LP +You can set the subwindow-mode to +.PN ClipByChildren +or +.PN IncludeInferiors . +For +.PN ClipByChildren , +both source and destination windows are +additionally clipped by all viewable +.PN InputOutput +children. +For +.PN IncludeInferiors , +neither source nor destination window is clipped by inferiors. +This will result in including subwindow contents in the source +and drawing through subwindow boundaries of the destination. +The use of +.PN IncludeInferiors +on a window of one depth with mapped +inferiors of differing depth is not illegal, but the semantics are +undefined by the core protocol. +.LP +The fill-rule defines what pixels are inside (drawn) for +paths given in +.PN XFillPolygon +requests and can be set to +.PN EvenOddRule +or +.PN WindingRule . +For +.PN EvenOddRule , +a point is inside if +an infinite ray with the point as origin crosses the path an odd number +of times. +For +.PN WindingRule , +a point is inside if an infinite ray with the +point as origin crosses an unequal number of clockwise and +counterclockwise directed path segments. +A clockwise directed path segment is one that crosses the ray from left to +right as observed from the point. +A counterclockwise segment is one that crosses the ray from right to left +as observed from the point. +The case where a directed line segment is coincident with the ray is +uninteresting because you can simply choose a different ray that is not +coincident with a segment. +.LP +For both +.PN EvenOddRule +and +.PN WindingRule , +a point is infinitely small, +and the path is an infinitely thin line. +A pixel is inside if the center point of the pixel is inside +and the center point is not on the boundary. +If the center point is on the boundary, +the pixel is inside if and only if the polygon interior is immediately to +its right (x increasing direction). +Pixels with centers on a horizontal edge are a special case +and are inside if and only if the polygon interior is immediately below +(y increasing direction). +.LP +The arc-mode controls filling in the +.PN XFillArcs +function and can be set to +.PN ArcPieSlice +or +.PN ArcChord . +For +.PN ArcPieSlice , +the arcs are pie-slice filled. +For +.PN ArcChord , +the arcs are chord filled. +.LP +The graphics-exposure flag controls +.PN GraphicsExpose +event generation +for +.PN XCopyArea +and +.PN XCopyPlane +requests (and any similar requests defined by extensions). +.LP +.sp +To create a new GC that is usable on a given screen with a +depth of drawable, use +.PN XCreateGC . +.IN "Graphics context" "initializing" +.IN "XCreateGC" "" "@DEF@" +.sM +.FD 0 +GC XCreateGC\^(\^\fIdisplay\fP, \fId\fP\^, \fIvaluemask\fP\^, \fIvalues\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fId\fP\^; +.br + unsigned long \fIvaluemask\fP\^; +.br + XGCValues *\^\fIvalues\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fId\fP 1i +Specifies the drawable. +.ds Vm set using the information in the specified values structure +.IP \fIvaluemask\fP 1i +Specifies which components in the GC are to be \*(Vm. +This argument is the bitwise inclusive OR of zero or more of the valid +GC component mask bits. +.IP \fIvalues\fP 1i +Specifies any values as specified by the valuemask. +.LP +.eM +The +.PN XCreateGC +function creates a graphics context and returns a GC. +The GC can be used with any destination drawable having the same root +and depth as the specified drawable. +Use with other drawables results in a +.PN BadMatch +error. +.LP +.PN XCreateGC +can generate +.PN BadAlloc , +.PN BadDrawable , +.PN BadFont , +.PN BadMatch , +.PN BadPixmap , +and +.PN BadValue +errors. +.LP +.sp +To copy components from a source GC to a destination GC, use +.PN XCopyGC . +.IN "XCopyGC" "" "@DEF@" +.sM +.FD 0 +XCopyGC\^(\^\fIdisplay\fP, \fIsrc\fP\^, \fIvaluemask\fP\^, \fIdest\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + GC \fIsrc\fP\^, \fIdest\fP\^; +.br + unsigned long \fIvaluemask\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIsrc\fP 1i +Specifies the components of the source GC. +.ds Vm copied to the destination GC +.IP \fIvaluemask\fP 1i +Specifies which components in the GC are to be \*(Vm. +This argument is the bitwise inclusive OR of zero or more of the valid +GC component mask bits. +.IP \fIdest\fP 1i +Specifies the destination GC. +.LP +.eM +The +.PN XCopyGC +function copies the specified components from the source GC +to the destination GC. +The source and destination GCs must have the same root and depth, +or a +.PN BadMatch +error results. +The valuemask specifies which component to copy, as for +.PN XCreateGC . +.LP +.PN XCopyGC +can generate +.PN BadAlloc , +.PN BadGC , +and +.PN BadMatch +errors. +.LP +.sp +To change the components in a given GC, use +.PN XChangeGC . +.IN "XChangeGC" "" "@DEF@" +.sM +.FD 0 +XChangeGC\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIvaluemask\fP\^, \fIvalues\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + GC \fIgc\fP\^; +.br + unsigned long \fIvaluemask\fP\^; +.br + XGCValues *\^\fIvalues\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgc\fP 1i +Specifies the GC. +.ds Vm changed using information in the specified values structure +.IP \fIvaluemask\fP 1i +Specifies which components in the GC are to be \*(Vm. +This argument is the bitwise inclusive OR of zero or more of the valid +GC component mask bits. +.IP \fIvalues\fP 1i +Specifies any values as specified by the valuemask. +.LP +.eM +The +.PN XChangeGC +function changes the components specified by valuemask for +the specified GC. +The values argument contains the values to be set. +The values and restrictions are the same as for +.PN XCreateGC . +Changing the clip-mask overrides any previous +.PN XSetClipRectangles +request on the context. +Changing the dash-offset or dash-list +overrides any previous +.PN XSetDashes +request on the context. +The order in which components are verified and altered is server dependent. +If an error is generated, a subset of the components may have been altered. +.LP +.PN XChangeGC +can generate +.PN BadAlloc , +.PN BadFont , +.PN BadGC , +.PN BadMatch , +.PN BadPixmap , +and +.PN BadValue +errors. +.LP +.sp +To obtain components of a given GC, use +.PN XGetGCValues . +.IN "XGetGCValues" "" "@DEF@" +.sM +.FD 0 +Status XGetGCValues\^(\^\fIdisplay\fP, \fIgc\fP, \fIvaluemask\fP, \ +\fIvalues_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + GC \fIgc\fP\^; +.br + unsigned long \fIvaluemask\fP\^; +.br + XGCValues *\fIvalues_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgc\fP 1i +Specifies the GC. +.ds Vm returned in the values_return argument +.IP \fIvaluemask\fP 1i +Specifies which components in the GC are to be \*(Vm. +This argument is the bitwise inclusive OR of zero or more of the valid +GC component mask bits. +.IP \fIvalues_return\fP 1i +Returns the GC values in the specified +.PN XGCValues +structure. +.LP +.eM +The +.PN XGetGCValues +function returns the components specified by valuemask for the specified GC. +If the valuemask contains a valid set of GC mask bits +.Pn ( GCFunction , +.PN GCPlaneMask , +.PN GCForeground , +.PN GCBackground , +.PN GCLineWidth , +.PN GCLineStyle , +.PN GCCapStyle , +.PN GCJoinStyle , +.PN GCFillStyle , +.PN GCFillRule , +.PN GCTile , +.PN GCStipple , +.PN GCTileStipXOrigin , +.PN GCTileStipYOrigin , +.PN GCFont , +.PN GCSubwindowMode , +.PN GCGraphicsExposures , +.PN GCClipXOrigin , +.PN GCCLipYOrigin , +.PN GCDashOffset , +or +.PN GCArcMode ) +and no error occurs, +.PN XGetGCValues +sets the requested components in values_return and returns a nonzero status. +Otherwise, it returns a zero status. +Note that the clip-mask and dash-list (represented by the +.PN GCClipMask +and +.PN GCDashList +bits, respectively, in the valuemask) +cannot be requested. +Also note that an invalid resource ID (with one or more of the three +most significant bits set to 1) will be returned for +.PN GCFont , +.PN GCTile , +and +.PN GCStipple +if the component has never been explicitly set by the client. +.LP +.sp +To free a given GC, use +.PN XFreeGC . +.IN "XFreeGC" "" "@DEF@" +.sM +.FD 0 +XFreeGC\^(\^\fIdisplay\fP, \fIgc\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + GC \fIgc\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgc\fP 1i +Specifies the GC. +.LP +.eM +The +.PN XFreeGC +function destroys the specified GC as well as all the associated storage. +.LP +.PN XFreeGC +can generate a +.PN BadGC +error. +.LP +.sp +To obtain the +.PN GContext +resource ID for a given GC, use +.PN XGContextFromGC . +.IN "XGContextFromGC" "" "@DEF@" +.sM +.FD 0 +GContext XGContextFromGC\^(\^\fIgc\fP\^) +.br + GC \fIgc\fP\^; +.FN +.ds Gc for which you want the resource ID +.IP \fIgc\fP 1i +Specifies the GC \*(Gc. +.LP +.eM +.sp +Xlib usually defers sending changes to the components of a GC to the server +until a graphics function is actually called with that GC. +This permits batching of component changes into a single server request. +In some circumstances, however, it may be necessary for the client +to explicitly force sending the changes to the server. +An example might be when a protocol extension uses the GC indirectly, +in such a way that the extension interface cannot know what GC will be used. +To force sending GC component changes, use +.PN XFlushGC . +.IN "XFlushGC" "" "@DEF@" +.sM +.FD 0 +void XFlushGC\^(\^\fIdisplay\fP, \fIgc\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + GC \fIgc\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgc\fP 1i +Specifies the GC. +.LP +.eM +.NH 2 +Using Graphics Context Convenience Routines +.XS +\*(SN Using Graphics Context Convenience Routines +.XE +.LP +This section discusses how to set the: +.IP \(bu 5 +Foreground, background, plane mask, or function components +.IP \(bu 5 +Line attributes and dashes components +.IP \(bu 5 +Fill style and fill rule components +.IP \(bu 5 +Fill tile and stipple components +.IP \(bu 5 +Font component +.IP \(bu 5 +Clip region component +.IP \(bu 5 +Arc mode, subwindow mode, and graphics exposure components +.NH 3 +Setting the Foreground, Background, Function, or Plane Mask +.XS +\*(SN Setting the Foreground, Background, Function, or Plane Mask +.XE +.LP +To set the foreground, background, plane mask, and function components +for a given GC, use +.PN XSetState . +.IN "XSetState" "" "@DEF@" +.sM +.FD 0 +XSetState\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIforeground\fP\^, \fIbackground\fP\^, \fIfunction\fP\^, \fIplane_mask\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + GC \fIgc\fP\^; +.br + unsigned long \fIforeground\fP\^, \fIbackground\fP\^; +.br + int \fIfunction\fP\^; +.br + unsigned long \fIplane_mask\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fIforeground\fP 1i +Specifies the foreground you want to set for the specified GC. +.IP \fIbackground\fP 1i +Specifies the background you want to set for the specified GC. +.IP \fIfunction\fP 1i +Specifies the function you want to set for the specified GC. +.IP \fIplane_mask\fP 1i +Specifies the plane mask. +.\" *** JIM: NEED MORE INFO FOR THIS. *** +.LP +.eM +.PN XSetState +can generate +.PN BadAlloc , +.PN BadGC , +and +.PN BadValue +errors. +.LP +.sp +To set the foreground of a given GC, use +.PN XSetForeground . +.IN "XSetForeground" "" "@DEF@" +.sM +.FD 0 +XSetForeground\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIforeground\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + GC \fIgc\fP\^; +.br + unsigned long \fIforeground\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fIforeground\fP 1i +Specifies the foreground you want to set for the specified GC. +.LP +.eM +.PN XSetForeground +can generate +.PN BadAlloc +and +.PN BadGC +errors. +.LP +.sp +To set the background of a given GC, use +.PN XSetBackground . +.IN "XSetBackground" "" "@DEF@" +.sM +.FD 0 +XSetBackground\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIbackground\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + GC \fIgc\fP\^; +.br + unsigned long \fIbackground\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fIbackground\fP 1i +Specifies the background you want to set for the specified GC. +.LP +.eM +.PN XSetBackground +can generate +.PN BadAlloc +and +.PN BadGC +errors. +.LP +.sp +To set the display function in a given GC, use +.PN XSetFunction . +.IN "XSetFunction" "" "@DEF@" +.sM +.FD 0 +XSetFunction\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIfunction\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + GC \fIgc\fP\^; +.br + int \fIfunction\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fIfunction\fP 1i +Specifies the function you want to set for the specified GC. +.LP +.eM +.PN XSetFunction +can generate +.PN BadAlloc , +.PN BadGC , +and +.PN BadValue +errors. +.LP +.sp +To set the plane mask of a given GC, use +.PN XSetPlaneMask . +.IN "XSetPlaneMask" "" "@DEF@" +.sM +.FD 0 +XSetPlaneMask\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIplane_mask\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + GC \fIgc\fP\^; +.br + unsigned long \fIplane_mask\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fIplane_mask\fP 1i +Specifies the plane mask. +.\" *** JIM: NEED MORE INFO FOR THIS. *** +.LP +.eM +.PN XSetPlaneMask +can generate +.PN BadAlloc +and +.PN BadGC +errors. +.NH 3 +Setting the Line Attributes and Dashes +.XS +\*(SN Setting the Line Attributes and Dashes +.XE +.LP +To set the line drawing components of a given GC, use +.PN XSetLineAttributes . +.IN "XSetLineAttributes" "" "@DEF@" +.sM +.FD 0 +XSetLineAttributes\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIline_width\fP\^, \fIline_style\fP\^, \fIcap_style\fP\^, \fIjoin_style\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + GC \fIgc\fP\^; +.br + unsigned int \fIline_width\fP\^; +.br + int \fIline_style\fP\^; +.br + int \fIcap_style\fP\^; +.br + int \fIjoin_style\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fIline_width\fP 1i +Specifies the line-width you want to set for the specified GC. +.IP \fIline_style\fP 1i +Specifies the line-style you want to set for the specified GC. +You can pass +.PN LineSolid , +.PN LineOnOffDash , +or +.PN LineDoubleDash . +.IP \fIcap_style\fP 1i +Specifies the line-style and cap-style you want to set for the specified GC. +You can pass +.PN CapNotLast , +.PN CapButt , +.PN CapRound , +or +.PN CapProjecting . +.IP \fIjoin_style\fP 1i +Specifies the line join-style you want to set for the specified GC. +You can pass +.PN JoinMiter , +.PN JoinRound , +or +.PN JoinBevel . +.LP +.eM +.PN XSetLineAttributes +can generate +.PN BadAlloc , +.PN BadGC , +and +.PN BadValue +errors. +.LP +.sp +To set the dash-offset and dash-list for dashed line styles of a given GC, use +.PN XSetDashes . +.IN "XSetDashes" "" "@DEF@" +.sM +.FD 0 +XSetDashes\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIdash_offset\fP\^, \fIdash_list\fP\^, \fIn\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + GC \fIgc\fP\^; +.br + int \fIdash_offset\fP\^; +.br + char \fIdash_list\fP[]\^; +.br + int \fIn\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fIdash_offset\fP 1i +Specifies the phase of the pattern for the dashed line-style you want to set +for the specified GC. +.IP \fIdash_list\fP 1i +Specifies the dash-list for the dashed line-style +you want to set for the specified GC. +.IP \fIn\fP 1i +Specifies the number of elements in dash_list. +.LP +.eM +The +.PN XSetDashes +function sets the dash-offset and dash-list attributes for dashed line styles +in the specified GC. +There must be at least one element in the specified dash_list, +or a +.PN BadValue +error results. +The initial and alternating elements (second, fourth, and so on) +of the dash_list are the even dashes, and +the others are the odd dashes. +Each element specifies a dash length in pixels. +All of the elements must be nonzero, +or a +.PN BadValue +error results. +Specifying an odd-length list is equivalent to specifying the same list +concatenated with itself to produce an even-length list. +.LP +The dash-offset defines the phase of the pattern, +specifying how many pixels into the dash-list the pattern +should actually begin in any single graphics request. +Dashing is continuous through path elements combined with a join-style +but is reset to the dash-offset between each sequence of joined lines. +.LP +The unit of measure for dashes is the same for the ordinary coordinate system. +Ideally, a dash length is measured along the slope of the line, but implementations +are only required to match this ideal for horizontal and vertical lines. +Failing the ideal semantics, it is suggested that the length be measured along the +major axis of the line. +The major axis is defined as the x axis for lines drawn at an angle of between +\-45 and +45 degrees or between 135 and 225 degrees from the x axis. +For all other lines, the major axis is the y axis. +.LP +.PN XSetDashes +can generate +.PN BadAlloc , +.PN BadGC , +and +.PN BadValue +errors. +.NH 3 +Setting the Fill Style and Fill Rule +.XS +\*(SN Setting the Fill Style and Fill Rule +.XE +.LP +To set the fill-style of a given GC, use +.PN XSetFillStyle . +.IN "XSetFillStyle" "" "@DEF@" +.sM +.FD 0 +XSetFillStyle\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIfill_style\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + GC \fIgc\fP\^; +.br + int \fIfill_style\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fIfill_style\fP 1i +Specifies the fill-style you want to set for the specified GC. +You can pass +.PN FillSolid , +.PN FillTiled , +.PN FillStippled , +or +.PN FillOpaqueStippled . +.LP +.eM +.PN XSetFillStyle +can generate +.PN BadAlloc , +.PN BadGC , +and +.PN BadValue +errors. +.LP +.sp +To set the fill-rule of a given GC, use +.PN XSetFillRule . +.IN "XSetFillRule" "" "@DEF@" +.sM +.FD 0 +XSetFillRule\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIfill_rule\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + GC \fIgc\fP\^; +.br + int \fIfill_rule\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fIfill_rule\fP 1i +Specifies the fill-rule you want to set for the specified GC. +You can pass +.PN EvenOddRule +or +.PN WindingRule . +.LP +.eM +.PN XSetFillRule +can generate +.PN BadAlloc , +.PN BadGC , +and +.PN BadValue +errors. +.NH 3 +Setting the Fill Tile and Stipple +.XS +\*(SN Setting the Fill Tile and Stipple +.XE +.LP +Some displays have hardware support for tiling or +stippling with patterns of specific sizes. +Tiling and stippling operations that restrict themselves to those specific +sizes run much faster than such operations with arbitrary size patterns. +Xlib provides functions that you can use to determine the best size, +tile, or stipple for the display +as well as to set the tile or stipple shape and the tile or stipple origin. +.LP +.sp +To obtain the best size of a tile, stipple, or cursor, use +.PN XQueryBestSize . +.IN "XQueryBestSize" "" "@DEF@" +.sM +.FD 0 +Status XQueryBestSize\^(\^\fIdisplay\fP, \fIclass\fP, \fIwhich_screen\fP, \fIwidth\fP, \fIheight\fP, \fIwidth_return\fP, \fIheight_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIclass\fP\^; +.br + Drawable \fIwhich_screen\fP\^; +.br + unsigned int \fIwidth\fP, \fIheight\fP\^; +.br + unsigned int *\fIwidth_return\fP, *\fIheight_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIclass\fP 1i +Specifies the class that you are interested in. +You can pass +.PN TileShape , +.PN CursorShape , +or +.PN StippleShape . +.IP \fIwhich_screen\fP 1i +Specifies any drawable on the screen. +.IP \fIwidth\fP 1i +.br +.ns +.IP \fIheight\fP 1i +Specify the width and height. +.IP \fIwidth_return\fP 1i +.br +.ns +.IP \fIheight_return\fP 1i +Return the width and height of the object best supported +by the display hardware. +.LP +.eM +The +.PN XQueryBestSize +function returns the best or closest size to the specified size. +For +.PN CursorShape , +this is the largest size that can be fully displayed on the screen specified by +which_screen. +For +.PN TileShape , +this is the size that can be tiled fastest. +For +.PN StippleShape , +this is the size that can be stippled fastest. +For +.PN CursorShape , +the drawable indicates the desired screen. +For +.PN TileShape +and +.PN StippleShape , +the drawable indicates the screen and possibly the window class and depth. +An +.PN InputOnly +window cannot be used as the drawable for +.PN TileShape +or +.PN StippleShape , +or a +.PN BadMatch +error results. +.LP +.PN XQueryBestSize +can generate +.PN BadDrawable , +.PN BadMatch , +and +.PN BadValue +errors. +.LP +.sp +To obtain the best fill tile shape, use +.PN XQueryBestTile . +.IN "XQueryBestTile" "" "@DEF@" +.sM +.FD 0 +Status XQueryBestTile\^(\^\fIdisplay\fP, \fIwhich_screen\fP, \fIwidth\fP, \fIheight\fP, \fIwidth_return\fP, \fIheight_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fIwhich_screen\fP\^; +.br + unsigned int \fIwidth\fP, \fIheight\fP\^; +.br + unsigned int *\fIwidth_return\fP, *\fIheight_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIwhich_screen\fP 1i +Specifies any drawable on the screen. +.IP \fIwidth\fP 1i +.br +.ns +.IP \fIheight\fP 1i +Specify the width and height. +.IP \fIwidth_return\fP 1i +.br +.ns +.IP \fIheight_return\fP 1i +Return the width and height of the object best supported +by the display hardware. +.LP +.eM +The +.PN XQueryBestTile +function returns the best or closest size, that is, the size that can be +tiled fastest on the screen specified by which_screen. +The drawable indicates the screen and possibly the window class and depth. +If an +.PN InputOnly +window is used as the drawable, a +.PN BadMatch +error results. +.LP +.PN XQueryBestTile +can generate +.PN BadDrawable +and +.PN BadMatch +errors. +.LP +.sp +To obtain the best stipple shape, use +.PN XQueryBestStipple . +.IN "XQueryBestStipple" "" "@DEF@" +.sM +.FD 0 +Status XQueryBestStipple\^(\^\fIdisplay\fP, \fIwhich_screen\fP, \fIwidth\fP, \fIheight\fP, \fIwidth_return\fP, \fIheight_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fIwhich_screen\fP\^; +.br + unsigned int \fIwidth\fP, \fIheight\fP\^; +.br + unsigned int *\fIwidth_return\fP, *\fIheight_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIwhich_screen\fP 1i +Specifies any drawable on the screen. +.IP \fIwidth\fP 1i +.br +.ns +.IP \fIheight\fP 1i +Specify the width and height. +.IP \fIwidth_return\fP 1i +.br +.ns +.IP \fIheight_return\fP 1i +Return the width and height of the object best supported +by the display hardware. +.LP +.eM +The +.PN XQueryBestStipple +function returns the best or closest size, that is, the size that can be +stippled fastest on the screen specified by which_screen. +The drawable indicates the screen and possibly the window class and depth. +If an +.PN InputOnly +window is used as the drawable, a +.PN BadMatch +error results. +.LP +.PN XQueryBestStipple +can generate +.PN BadDrawable +and +.PN BadMatch +errors. +.LP +.sp +To set the fill tile of a given GC, use +.PN XSetTile . +.IN "XSetTile" "" "@DEF@" +.sM +.FD 0 +XSetTile\^(\^\fIdisplay\fP, \fIgc\fP\^, \fItile\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + GC \fIgc\fP\^; +.br + Pixmap \fItile\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fItile\fP 1i +Specifies the fill tile you want to set for the specified GC. +.LP +.eM +The tile and GC must have the same depth, +or a +.PN BadMatch +error results. +.LP +.PN XSetTile +can generate +.PN BadAlloc , +.PN BadGC , +.PN BadMatch , +and +.PN BadPixmap +errors. +.LP +.sp +To set the stipple of a given GC, use +.PN XSetStipple . +.IN "XSetStipple" "" "@DEF@" +.sM +.FD 0 +XSetStipple\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIstipple\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + GC \fIgc\fP\^; +.br + Pixmap \fIstipple\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fIstipple\fP 1i +Specifies the stipple you want to set for the specified GC. +.LP +.eM +The stipple must have a depth of one, +or a +.PN BadMatch +error results. +.LP +.PN XSetStipple +can generate +.PN BadAlloc , +.PN BadGC , +.PN BadMatch , +and +.PN BadPixmap +errors. +.LP +.sp +To set the tile or stipple origin of a given GC, use +.PN XSetTSOrigin . +.IN "XSetTSOrigin" "" "@DEF@" +.sM +.FD 0 +XSetTSOrigin\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIts_x_origin\fP\^, \fIts_y_origin\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + GC \fIgc\fP\^; +.br + int \fIts_x_origin\fP\^, \fIts_y_origin\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fIts_x_origin\fP 1i +.br +.ns +.IP \fIts_y_origin\fP 1i +Specify the x and y coordinates of the tile and stipple origin. +.LP +.eM +When graphics requests call for tiling or stippling, +the parent's origin will be interpreted relative to whatever destination +drawable is specified in the graphics request. +.LP +.PN XSetTSOrigin +can generate +.PN BadAlloc +and +.PN BadGC +errors. +.NH 3 +Setting the Current Font +.XS +\*(SN Setting the Current Font +.XE +.LP +To set the current font of a given GC, use +.PN XSetFont . +.IN "XSetFont" "" "@DEF@" +.sM +.FD 0 +XSetFont\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIfont\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + GC \fIgc\fP\^; +.br + Font \fIfont\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fIfont\fP 1i +Specifies the font. +.LP +.eM +.PN XSetFont +can generate +.PN BadAlloc , +.PN BadFont , +and +.PN BadGC +errors. +.NH 3 +Setting the Clip Region +.XS +\*(SN Setting the Clip Region +.XE +.LP +Xlib provides functions that you can use to set the clip-origin +and the clip-mask or set the clip-mask to a list of rectangles. +.LP +.sp +To set the clip-origin of a given GC, use +.PN XSetClipOrigin . +.IN "XSetClipOrigin" "" "@DEF@" +.sM +.FD 0 +XSetClipOrigin\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIclip_x_origin\fP\^, \fIclip_y_origin\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + GC \fIgc\fP\^; +.br + int \fIclip_x_origin\fP\^, \fIclip_y_origin\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fIclip_x_origin\fP 1i +.br +.ns +.IP \fIclip_y_origin\fP 1i +Specify the x and y coordinates of the clip-mask origin. +.LP +.eM +The clip-mask origin is interpreted relative to the origin of whatever +destination drawable is specified in the graphics request. +.LP +.PN XSetClipOrigin +can generate +.PN BadAlloc +and +.PN BadGC +errors. +.LP +.sp +To set the clip-mask of a given GC to the specified pixmap, use +.PN XSetClipMask . +.IN "XSetClipMask" "" "@DEF@" +.sM +.FD 0 +XSetClipMask\^(\^\fIdisplay\fP, \fIgc\fP, \fIpixmap\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + GC \fIgc\fP\^; +.br + Pixmap \fIpixmap\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fIpixmap\fP 1i +Specifies the pixmap or +.PN None . +.LP +.eM +If the clip-mask is set to +.PN None , +the pixels are always drawn (regardless of the clip-origin). +.LP +.PN XSetClipMask +can generate +.PN BadAlloc , +.PN BadGC , +.PN BadMatch , +and +.PN BadPixmap +errors. +.LP +.sp +To set the clip-mask of a given GC to the specified list of rectangles, use +.PN XSetClipRectangles . +.IN "XSetClipRectangles" "" "@DEF@" +.sM +.FD 0 +XSetClipRectangles\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIclip_x_origin\fP\^, \fIclip_y_origin\fP\^, \fIrectangles\fP\^, \fIn\fP\^, \fIordering\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + GC \fIgc\fP\^; +.br + int \fIclip_x_origin\fP\^, \fIclip_y_origin\fP\^; +.br + XRectangle \fIrectangles\fP[]\^; +.br + int \fIn\fP\^; +.br + int \fIordering\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fIclip_x_origin\fP 1i +.br +.ns +.IP \fIclip_y_origin\fP 1i +Specify the x and y coordinates of the clip-mask origin. +.IP \fIrectangles\fP 1i +Specifies an array of rectangles that define the clip-mask. +.IP \fIn\fP 1i +Specifies the number of rectangles. +.IP \fIordering\fP 1i +Specifies the ordering relations on the rectangles. +You can pass +.PN Unsorted , +.PN YSorted , +.PN YXSorted , +or +.PN YXBanded . +.LP +.eM +The +.PN XSetClipRectangles +function changes the clip-mask in the specified GC +to the specified list of rectangles and sets the clip origin. +The output is clipped to remain contained within the +rectangles. +The clip-origin is interpreted relative to the origin of +whatever destination drawable is specified in a graphics request. +The rectangle coordinates are interpreted relative to the clip-origin. +The rectangles should be nonintersecting, or the graphics results will be +undefined. +Note that the list of rectangles can be empty, +which effectively disables output. +This is the opposite of passing +.PN None +as the clip-mask in +.PN XCreateGC , +.PN XChangeGC , +and +.PN XSetClipMask . +.LP +If known by the client, ordering relations on the rectangles can be +specified with the ordering argument. +This may provide faster operation +by the server. +If an incorrect ordering is specified, the X server may generate a +.PN BadMatch +error, but it is not required to do so. +If no error is generated, the graphics +results are undefined. +.PN Unsorted +means the rectangles are in arbitrary order. +.PN YSorted +means that the rectangles are nondecreasing in their Y origin. +.PN YXSorted +additionally constrains +.PN YSorted +order in that all +rectangles with an equal Y origin are nondecreasing in their X +origin. +.PN YXBanded +additionally constrains +.PN YXSorted +by requiring that, +for every possible Y scanline, all rectangles that include that +scanline have an identical Y origins and Y extents. +.LP +.PN XSetClipRectangles +can generate +.PN BadAlloc , +.PN BadGC , +.PN BadMatch , +and +.PN BadValue +errors. +.LP +Xlib provides a set of basic functions for performing +region arithmetic. +For information about these functions, +see section 16.5. +.NH 3 +Setting the Arc Mode, Subwindow Mode, and Graphics Exposure +.XS +\*(SN Setting the Arc Mode, Subwindow Mode, and Graphics Exposure +.XE +.LP +To set the arc mode of a given GC, use +.PN XSetArcMode . +.IN "XSetArcMode" "" "@DEF@" +.sM +.FD 0 +XSetArcMode\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIarc_mode\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + GC \fIgc\fP\^; +.br + int \fIarc_mode\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fIarc_mode\fP 1i +Specifies the arc mode. +You can pass +.PN ArcChord +or +.PN ArcPieSlice . +.LP +.eM +.PN XSetArcMode +can generate +.PN BadAlloc , +.PN BadGC , +and +.PN BadValue +errors. +.LP +.sp +To set the subwindow mode of a given GC, use +.PN XSetSubwindowMode . +.IN "XSetSubwindowMode" "" "@DEF@" +.sM +.FD 0 +XSetSubwindowMode\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIsubwindow_mode\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + GC \fIgc\fP\^; +.br + int \fIsubwindow_mode\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fIsubwindow_mode\fP 1i +Specifies the subwindow mode. +You can pass +.PN ClipByChildren +or +.PN IncludeInferiors . +.LP +.eM +.PN XSetSubwindowMode +can generate +.PN BadAlloc , +.PN BadGC , +and +.PN BadValue +errors. +.LP +.sp +To set the graphics-exposures flag of a given GC, use +.PN XSetGraphicsExposures . +.IN "XSetGraphicsExposures" "" "@DEF@" +.sM +.FD 0 +XSetGraphicsExposures\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIgraphics_exposures\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + GC \fIgc\fP\^; +.br + Bool \fIgraphics_exposures\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fIgraphics_exposures\fP 1i +Specifies a Boolean value that indicates whether you want +.PN GraphicsExpose +and +.PN NoExpose +events to be reported when calling +.PN XCopyArea +and +.PN XCopyPlane +with this GC. +.LP +.eM +.PN XSetGraphicsExposures +can generate +.PN BadAlloc , +.PN BadGC , +and +.PN BadValue +errors. +.bp diff --git a/libX11/specs/libX11/CH08 b/libX11/specs/libX11/CH08 new file mode 100644 index 000000000..3d2161fb2 --- /dev/null +++ b/libX11/specs/libX11/CH08 @@ -0,0 +1,3468 @@ +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be included +.\" in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR +.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +.\" OTHER DEALINGS IN THE SOFTWARE. +.\" +.\" Except as contained in this notice, the name of the X Consortium shall +.\" not be used in advertising or otherwise to promote the sale, use or +.\" other dealings in this Software without prior written authorization +.\" from the X Consortium. +.\" +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by +.\" Digital Equipment Corporation +.\" +.\" Portions Copyright \(co 1990, 1991 by +.\" Tektronix, Inc. +.\" +.\" Permission to use, copy, modify and distribute this documentation for +.\" any purpose and without fee is hereby granted, provided that the above +.\" copyright notice appears in all copies and that both that copyright notice +.\" and this permission notice appear in all copies, and that the names of +.\" Digital and Tektronix not be used in in advertising or publicity pertaining +.\" to this documentation without specific, written prior permission. +.\" Digital and Tektronix makes no representations about the suitability +.\" of this documentation for any purpose. +.\" It is provided ``as is'' without express or implied warranty. +.\" +\& +.sp 1 +.ce 3 +\s+1\fBChapter 8\fP\s-1 + +\s+1\fBGraphics Functions\fP\s-1 +.sp 2 +.nr H1 8 +.nr H2 0 +.nr H3 0 +.nr H4 0 +.nr H5 0 +.na +.LP +.XS +Chapter 8: Graphics Functions +.XE +Once you have established a connection to a display, +you can use the Xlib graphics functions to: +.IP \(bu 5 +Clear and copy areas +.IP \(bu 5 +Draw points, lines, rectangles, and arcs +.IP \(bu 5 +Fill areas +.IP \(bu 5 +Manipulate fonts +.IP \(bu 5 +Draw text +.IP \(bu 5 +Transfer images between clients and the server +.LP +If the same drawable and GC is used for each call, +Xlib batches back-to-back calls to +.PN XDrawPoint , +.PN XDrawLine , +.PN XDrawRectangle , +.PN XFillArc , +and +.PN XFillRectangle . +Note that this reduces the total number of requests sent to the server. +.NH 2 +Clearing Areas +.XS +\*(SN Clearing Areas +.XE +.LP +Xlib provides functions that you can use to clear an area or the entire window. +Because pixmaps do not have defined backgrounds, +they cannot be filled by using the functions described in this section. +Instead, to accomplish an analogous operation on a pixmap, +you should use +.PN XFillRectangle , +which sets the pixmap to a known value. +.LP +.sp +To clear a rectangular area of a given window, use +.PN XClearArea . +.IN "Areas" "clearing" +.IN "Clearing" "areas" +.IN "XClearArea" "" "@DEF@" +.sM +.FD 0 +XClearArea\^(\^\fIdisplay\fP, \fIw\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIexposures\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + int \fIx\fP\^, \fIy\fP\^; +.br + unsigned int \fIwidth\fP\^, \fIheight\fP\^; +.br + Bool \fIexposures\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.ds Xy , which are relative to the origin of the window \ +and specify the upper-left corner of the rectangle +.IP \fIx\fP 1i +.br +.ns +.IP \fIy\fP 1i +Specify the x and y coordinates\*(Xy. +.ds Wh , which are the dimensions of the rectangle +.IP \fIwidth\fP 1i +.br +.ns +.IP \fIheight\fP 1i +Specify the width and height\*(Wh. +.IP \fIexposures\fP 1i +Specifies a Boolean value that indicates if +.PN Expose +events are to be generated. +.LP +.eM +The +.PN XClearArea +function paints a rectangular area in the specified window according to the +specified dimensions with the window's background pixel or pixmap. +The subwindow-mode effectively is +.PN ClipByChildren . +If width is zero, it +is replaced with the current width of the window minus x. +If height is +zero, it is replaced with the current height of the window minus y. +If the window has a defined background tile, +the rectangle clipped by any children is filled with this tile. +If the window has +background +.PN None , +the contents of the window are not changed. +In either +case, if exposures is +.PN True , +one or more +.PN Expose +events are generated for regions of the rectangle that are either visible or are +being retained in a backing store. +If you specify a window whose class is +.PN InputOnly , +a +.PN BadMatch +error results. +.LP +.PN XClearArea +can generate +.PN BadMatch , +.PN BadValue , +and +.PN BadWindow +errors. +.LP +.sp +To clear the entire area in a given window, use +.PN XClearWindow . +.IN "Window" "clearing" +.IN "Clearing" "windows" +.IN "XClearWindow" "" "@DEF@" +.sM +.FD 0 +XClearWindow\^(\^\fIdisplay\fP, \fIw\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.LP +.eM +The +.PN XClearWindow +function clears the entire area in the specified window and is +equivalent to +.PN XClearArea +(display, w, 0, 0, 0, 0, +.PN False ). +If the window has a defined background tile, the rectangle is tiled with a +plane-mask of all ones and +.PN GXcopy +function. +If the window has +background +.PN None , +the contents of the window are not changed. +If you specify a window whose class is +.PN InputOnly , +a +.PN BadMatch +error results. +.LP +.PN XClearWindow +can generate +.PN BadMatch +and +.PN BadWindow +errors. +.NH 2 +Copying Areas +.XS +\*(SN Copying Areas +.XE +.LP +Xlib provides functions that you can use to copy an area or a bit plane. +.LP +.sp +To copy an area between drawables of the same +root and depth, use +.PN XCopyArea . +.IN "Areas" "copying" +.IN "Copying" "areas" +.IN "XCopyArea" "" "@DEF@" +.sM +.FD 0 +XCopyArea\^(\^\fIdisplay\fP, \fIsrc\fP\^, \fIdest\fP\^, \fIgc\fP\^, \fIsrc_x\fP\^, \fIsrc_y\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIdest_x\fP\^, \fIdest_y\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fIsrc\fP\^, \fIdest\fP\^; +.br + GC \fIgc\fP\^; +.br + int \fIsrc_x\fP\^, \fIsrc_y\fP\^; +.br + unsigned int \fIwidth\fP\^, \fIheight\fP\^; +.br + int \fIdest_x\fP\^, \fIdest_y\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIsrc\fP 1i +.br +.ns +.IP \fIdest\fP 1i +Specify the source and destination rectangles to be combined. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fIsrc_x\fP 1i +.br +.ns +.IP \fIsrc_y\fP 1i +Specify the x and y coordinates, +which are relative to the origin of the source rectangle +and specify its upper-left corner. +.ds Wh , which are the dimensions of both the source \ +and destination rectangles +.IP \fIwidth\fP 1i +.br +.ns +.IP \fIheight\fP 1i +Specify the width and height\*(Wh. +.ds Dx , which are relative to the origin of the destination rectangle \ +and specify its upper-left corner +.IP \fIdest_x\fP 1i +.br +.ns +.IP \fIdest_y\fP 1i +Specify the x and y coordinates\*(Dx. +.LP +.eM +The +.PN XCopyArea +function combines the specified rectangle of src with the specified rectangle +of dest. +The drawables must have the same root and depth, +or a +.PN BadMatch +error results. +.LP +If regions of the source rectangle are obscured and have not been +retained in backing store +or if regions outside the boundaries of the source drawable are specified, +those regions are not copied. +Instead, the +following occurs on all corresponding destination regions that are either +visible or are retained in backing store. +If the destination is a window with a background other than +.PN None , +corresponding regions +of the destination are tiled with that background +(with plane-mask of all ones and +.PN GXcopy +function). +Regardless of tiling or whether the destination is a window or a pixmap, +if graphics-exposures is +.PN True , +then +.PN GraphicsExpose +events for all corresponding destination regions are generated. +If graphics-exposures is +.PN True +but no +.PN GraphicsExpose +events are generated, a +.PN NoExpose +event is generated. +Note that by default graphics-exposures is +.PN True +in new GCs. +.LP +This function uses these GC components: function, plane-mask, +subwindow-mode, graphics-exposures, clip-x-origin, +clip-y-origin, and clip-mask. +.LP +.PN XCopyArea +can generate +.PN BadDrawable , +.PN BadGC , +and +.PN BadMatch +errors. +.sp +.LP +To copy a single bit plane of a given drawable, use +.PN XCopyPlane . +.IN "Plane" "copying" +.IN "Copying" "planes" +.IN "XCopyPlane" "" "@DEF@" +.sM +.FD 0 +XCopyPlane\^(\^\fIdisplay\fP, \fIsrc\fP\^, \fIdest\fP\^, \fIgc\fP\^, \fIsrc_x\fP\^, \fIsrc_y\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIdest_x\fP\^, \fIdest_y\fP\^, \fIplane\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fIsrc\fP\^, \fIdest\fP\^; +.br + GC \fIgc\fP\^; +.br + int \fIsrc_x\fP\^, \fIsrc_y\fP\^; +.br + unsigned int \fIwidth\fP\^, \fIheight\fP\^; +.br + int \fIdest_x\fP\^, \fIdest_y\fP\^; +.br + unsigned long \fIplane\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIsrc\fP 1i +.br +.ns +.IP \fIdest\fP 1i +Specify the source and destination rectangles to be combined. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fIsrc_x\fP 1i +.br +.ns +.IP \fIsrc_y\fP 1i +Specify the x and y coordinates, +which are relative to the origin of the source rectangle +and specify its upper-left corner. +.ds Wh , which are the dimensions of both the source and destination rectangles +.IP \fIwidth\fP 1i +.br +.ns +.IP \fIheight\fP 1i +Specify the width and height\*(Wh. +.ds Dx , which are relative to the origin of the destination rectangle \ +and specify its upper-left corner +.IP \fIdest_x\fP 1i +.br +.ns +.IP \fIdest_y\fP 1i +Specify the x and y coordinates\*(Dx. +.IP \fIplane\fP 1i +Specifies the bit plane. +You must set exactly one bit to 1. +.LP +.eM +The +.PN XCopyPlane +function uses a single bit plane of the specified source rectangle +combined with the specified GC to modify the specified rectangle of dest. +The drawables must have the same root but need not have the same depth. +If the drawables do not have the same root, a +.PN BadMatch +error results. +If plane does not have exactly one bit set to 1 and the value of plane +is not less than %2 sup n%, where \fIn\fP is the depth of src, a +.PN BadValue +error results. +.LP +Effectively, +.PN XCopyPlane +forms a pixmap of the same depth as the rectangle of dest and with a +size specified by the source region. +It uses the foreground/background pixels in the GC (foreground +everywhere the bit plane in src contains a bit set to 1, +background everywhere the bit plane in src contains a bit set to 0) +and the equivalent of a +.PN CopyArea +protocol request is performed with all the same exposure semantics. +This can also be thought of as using the specified region of the source +bit plane as a stipple with a fill-style of +.PN FillOpaqueStippled +for filling a rectangular area of the destination. +.LP +This function uses these GC components: function, plane-mask, foreground, +background, subwindow-mode, graphics-exposures, clip-x-origin, clip-y-origin, +and clip-mask. +.LP +.PN XCopyPlane +can generate +.PN BadDrawable , +.PN BadGC , +.PN BadMatch , +and +.PN BadValue +errors. +.NH 2 +Drawing Points, Lines, Rectangles, and Arcs +.XS +\*(SN Drawing Points, Lines, Rectangles, and Arcs +.XE +.LP +Xlib provides functions that you can use to draw: +.IP \(bu 5 +A single point or multiple points +.IP \(bu 5 +A single line or multiple lines +.IP \(bu 5 +A single rectangle or multiple rectangles +.IP \(bu 5 +A single arc or multiple arcs +.LP +Some of the functions described in the following sections +use these structures: +.LP +.IN "XSegment" "" "@DEF@" +.sM +.Ds 0 +.TA .5i +.ta .5i +typedef struct { + short x1, y1, x2, y2; +} XSegment; +.De +.LP +.eM +.IN "XPoint" "" "@DEF@" +.sM +.Ds 0 +.TA .5i +.ta .5i +typedef struct { + short x, y; +} XPoint; +.De +.LP +.eM +.IN "XRectangle" "" "@DEF@" +.sM +.Ds 0 +.TA .5i +.ta .5i +typedef struct { + short x, y; + unsigned short width, height; +} XRectangle; +.De +.LP +.eM +.IN "XArc" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + short x, y; + unsigned short width, height; + short angle1, angle2; /* Degrees * 64 */ +} XArc; +.De +.LP +.eM +All x and y members are signed integers. +The width and height members are 16-bit unsigned integers. +You should be careful not to generate coordinates and sizes +out of the 16-bit ranges, because the protocol only has 16-bit fields +for these values. +.NH 3 +Drawing Single and Multiple Points +.XS +\*(SN Drawing Single and Multiple Points +.XE +.LP +.IN "Points" "drawing" +.IN "Drawing" "points" +.IN "XDrawPoints" +.IN "XDrawPoint" +.LP +To draw a single point in a given drawable, use +.PN XDrawPoint . +.IN "XDrawPoint" "" "@DEF@" +.sM +.FD 0 +XDrawPoint\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fId\fP\^; +.br + GC \fIgc\fP\^; +.br + int \fIx\fP\^, \fIy\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fId\fP 1i +Specifies the drawable. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fIx\fP 1i +.br +.ns +.IP \fIy\fP 1i +Specify the x and y coordinates where you want the point drawn. +.LP +.eM +.sp +To draw multiple points in a given drawable, use +.PN XDrawPoints . +.IN "XDrawPoints" "" "@DEF@" +.sM +.FD 0 +XDrawPoints\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIpoints\fP\^, \fInpoints\fP\^, \fImode\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fId\fP\^; +.br + GC \fIgc\fP\^; +.br + XPoint *\fIpoints\fP\^; +.br + int \fInpoints\fP\^; +.br + int \fImode\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fId\fP 1i +Specifies the drawable. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fIpoints\fP 1i +Specifies an array of points. +.IP \fInpoints\fP 1i +Specifies the number of points in the array. +.IP \fImode\fP 1i +Specifies the coordinate mode. +You can pass +.PN CoordModeOrigin +or +.PN CoordModePrevious . +.LP +.eM +The +.PN XDrawPoint +function uses the foreground pixel and function components of the +GC to draw a single point into the specified drawable; +.PN XDrawPoints +draws multiple points this way. +.PN CoordModeOrigin +treats all coordinates as relative to the origin, +and +.PN CoordModePrevious +treats all coordinates after the first as relative to the previous point. +.PN XDrawPoints +draws the points in the order listed in the array. +.LP +Both functions use these GC components: function, plane-mask, +foreground, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. +.LP +.PN XDrawPoint +can generate +.PN BadDrawable , +.PN BadGC , +and +.PN BadMatch +errors. +.PN XDrawPoints +can generate +.PN BadDrawable , +.PN BadGC , +.PN BadMatch , +and +.PN BadValue +errors. +.NH 3 +Drawing Single and Multiple Lines +.XS +\*(SN Drawing Single and Multiple Lines +.XE +.LP +.IN "Lines" "drawing" +.IN "Drawing" "lines" +.IN "XDrawLine" +.IN "XDrawLines" +.IN "Polygons" "drawing" +.IN "Drawing" "polygons" +.IN "XDrawSegments" +.LP +To draw a single line between two points in a given drawable, use +.PN XDrawLine . +.IN "XDrawLine" "" "@DEF@" +.sM +.FD 0 +XDrawLine\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx1\fP\^, \fIy1\fP\^, \fIx2\fP\^, \fIy2\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fId\fP\^; +.br + GC \fIgc\fP\^; +.br + int \fIx1\fP\^, \fIy1\fP\^, \fIx2\fP\^, \fIy2\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fId\fP 1i +Specifies the drawable. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fIx1\fP 1i +.br +.ns +.IP \fIy1\fP 1i +.br +.ns +.IP \fIx2\fP 1i +.br +.ns +.IP \fIy2\fP 1i +Specify the points (x1, y1) and (x2, y2) to be connected. +.LP +.eM +.sp +To draw multiple lines in a given drawable, use +.PN XDrawLines . +.IN "XDrawLines" "" "@DEF@" +.sM +.FD 0 +XDrawLines\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIpoints\fP\^, \fInpoints\fP\^, \fImode\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fId\fP\^; +.br + GC \fIgc\fP\^; +.br + XPoint *\fIpoints\fP\^; +.br + int \fInpoints\fP\^; +.br + int \fImode\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fId\fP 1i +Specifies the drawable. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fIpoints\fP 1i +Specifies an array of points. +.IP \fInpoints\fP 1i +Specifies the number of points in the array. +.IP \fImode\fP 1i +Specifies the coordinate mode. +You can pass +.PN CoordModeOrigin +or +.PN CoordModePrevious . +.LP +.eM +.sp +To draw multiple, unconnected lines in a given drawable, +use +.PN XDrawSegments . +.IN "XDrawSegments" "" "@DEF@" +.sM +.FD 0 +XDrawSegments\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIsegments\fP\^, \fInsegments\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fId\fP\^; +.br + GC \fIgc\fP\^; +.br + XSegment *\fIsegments\fP\^; +.br + int \fInsegments\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fId\fP 1i +Specifies the drawable. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fIsegments\fP 1i +Specifies an array of segments. +.IP \fInsegments\fP 1i +Specifies the number of segments in the array. +.LP +.eM +The +.PN XDrawLine +function uses the components of the specified GC to +draw a line between the specified set of points (x1, y1) and (x2, y2). +It does not perform joining at coincident endpoints. +For any given line, +.PN XDrawLine +does not draw a pixel more than once. +If lines intersect, the intersecting pixels are drawn multiple times. +.LP +The +.PN XDrawLines +function uses the components of the specified GC to draw +npoints\-1 lines between each pair of points (point[i], point[i+1]) +in the array of +.PN XPoint +structures. +It draws the lines in the order listed in the array. +The lines join correctly at all intermediate points, and if the first and last +points coincide, the first and last lines also join correctly. +For any given line, +.PN XDrawLines +does not draw a pixel more than once. +If thin (zero line-width) lines intersect, +the intersecting pixels are drawn multiple times. +If wide lines intersect, the intersecting pixels are drawn only once, as though +the entire +.PN PolyLine +protocol request were a single, filled shape. +.PN CoordModeOrigin +treats all coordinates as relative to the origin, +and +.PN CoordModePrevious +treats all coordinates after the first as relative to the previous point. +.LP +The +.PN XDrawSegments +function draws multiple, unconnected lines. +For each segment, +.PN XDrawSegments +draws a +line between (x1, y1) and (x2, y2). +It draws the lines in the order listed in the array of +.PN XSegment +structures and does not perform joining at coincident endpoints. +For any given line, +.PN XDrawSegments +does not draw a pixel more than once. +If lines intersect, the intersecting pixels are drawn multiple times. +.LP +All three functions use these GC components: +function, plane-mask, line-width, +line-style, cap-style, fill-style, subwindow-mode, +clip-x-origin, clip-y-origin, and clip-mask. +The +.PN XDrawLines +function also uses the join-style GC component. +All three functions also use these GC mode-dependent components: +foreground, background, tile, stipple, tile-stipple-x-origin, +tile-stipple-y-origin, dash-offset, and dash-list. +.LP +.PN XDrawLine , +.PN XDrawLines , +and +.PN XDrawSegments +can generate +.PN BadDrawable , +.PN BadGC , +and +.PN BadMatch +errors. +.PN XDrawLines +also can generate +.PN BadValue +errors. +.NH 3 +Drawing Single and Multiple Rectangles +.XS +\*(SN Drawing Single and Multiple Rectangles +.XE +.LP +.IN "Rectangles" "drawing" +.IN "Drawing" "rectangles" +.IN "XDrawRectangle" +.IN "XDrawRectangles" +.LP +To draw the outline of a single rectangle in a given drawable, use +.PN XDrawRectangle . +.IN "XDrawRectangle" "" "@DEF@" +.sM +.FD 0 +XDrawRectangle\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fId\fP\^; +.br + GC \fIgc\fP\^; +.br + int \fIx\fP\^, \fIy\fP\^; +.br + unsigned int \fIwidth\fP\^, \fIheight\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fId\fP 1i +Specifies the drawable. +.IP \fIgc\fP 1i +Specifies the GC. +.ds Xy , which specify the upper-left corner of the rectangle +.IP \fIx\fP 1i +.br +.ns +.IP \fIy\fP 1i +Specify the x and y coordinates\*(Xy. +.ds Wh , which specify the dimensions of the rectangle +.IP \fIwidth\fP 1i +.br +.ns +.IP \fIheight\fP 1i +Specify the width and height\*(Wh. +.LP +.eM +.sp +To draw the outline of multiple rectangles +in a given drawable, use +.PN XDrawRectangles . +.IN "XDrawRectangles" "" "@DEF@" +.sM +.FD 0 +XDrawRectangles\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIrectangles\fP\^, \fInrectangles\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fId\fP\^; +.br + GC \fIgc\fP\^; +.br + XRectangle \fIrectangles\fP\^[\^]\^; +.br + int \fInrectangles\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fId\fP 1i +Specifies the drawable. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fIrectangles\fP 1i +Specifies an array of rectangles. +.IP \fInrectangles\fP 1i +Specifies the number of rectangles in the array. +.LP +.eM +The +.PN XDrawRectangle +and +.PN XDrawRectangles +functions draw the outlines of the specified rectangle or rectangles as +if a five-point +.PN PolyLine +protocol request were specified for each rectangle: +.IP +[x,y] [x+width,y] [x+width,y+height] [x,y+height] [x,y] +.LP +For the specified rectangle or rectangles, +these functions do not draw a pixel more than once. +.PN XDrawRectangles +draws the rectangles in the order listed in the array. +If rectangles intersect, +the intersecting pixels are drawn multiple times. +.LP +Both functions use these GC components: +function, plane-mask, line-width, +line-style, cap-style, join-style, fill-style, +subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. +They also use these GC mode-dependent components: +foreground, background, tile, stipple, tile-stipple-x-origin, +tile-stipple-y-origin, dash-offset, and dash-list. +.LP +.PN XDrawRectangle +and +.PN XDrawRectangles +can generate +.PN BadDrawable , +.PN BadGC , +and +.PN BadMatch +errors. +.NH 3 +Drawing Single and Multiple Arcs +.XS +\*(SN Drawing Single and Multiple Arcs +.XE +.LP +.IN "Drawing" "arcs" +.IN "XDrawArc" +.IN "Arcs" "drawing" +.IN "XDrawArcs" +.LP +.sp +To draw a single arc in a given drawable, use +.PN XDrawArc . +.IN "XDrawArc" "" "@DEF@" +.sM +.FD 0 +XDrawArc\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIangle1\fP\^, \fIangle2\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fId\fP\^; +.br + GC \fIgc\fP\^; +.br + int \fIx\fP\^, \fIy\fP\^; +.br + unsigned int \fIwidth\fP\^, \fIheight\fP\^; +.br + int \fIangle1\fP\^, \fIangle2\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fId\fP 1i +Specifies the drawable. +.IP \fIgc\fP 1i +Specifies the GC. +.ds Xy , which are relative to the origin of the drawable \ +and specify the upper-left corner of the bounding rectangle +.IP \fIx\fP 1i +.br +.ns +.IP \fIy\fP 1i +Specify the x and y coordinates\*(Xy. +.ds Wh , which are the major and minor axes of the arc +.IP \fIwidth\fP 1i +.br +.ns +.IP \fIheight\fP 1i +Specify the width and height\*(Wh. +.IP \fIangle1\fP 1i +Specifies the start of the arc relative to the three-o'clock position +from the center, in units of degrees * 64. +.IP \fIangle2\fP 1i +Specifies the path and extent of the arc relative to the start of the +arc, in units of degrees * 64. +.LP +.eM +.sp +To draw multiple arcs in a given drawable, use +.PN XDrawArcs . +.IN "XDrawArcs" "" "@DEF@" +.sM +.FD 0 +XDrawArcs\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIarcs\fP\^, \fInarcs\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fId\fP\^; +.br + GC \fIgc\fP\^; +.br + XArc *\fIarcs\fP\^; +.br + int \fInarcs\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fId\fP 1i +Specifies the drawable. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fIarcs\fP 1i +Specifies an array of arcs. +.IP \fInarcs\fP 1i +Specifies the number of arcs in the array. +.LP +.eM +.EQ +delim %% +.EN +.PN XDrawArc +draws a single circular or elliptical arc, and +.PN XDrawArcs +draws multiple circular or elliptical arcs. +Each arc is specified by a rectangle and two angles. +The center of the circle or ellipse is the center of the +rectangle, and the major and minor axes are specified by the width and height. +Positive angles indicate counterclockwise motion, +and negative angles indicate clockwise motion. +If the magnitude of angle2 is greater than 360 degrees, +.PN XDrawArc +or +.PN XDrawArcs +truncates it to 360 degrees. +.LP +For an arc specified as %[ ~x, ~y, ~width , ~height, ~angle1, ~angle2 ]%, +the origin of the major and minor axes is at +% [ x +^ {width over 2} , ~y +^ {height over 2} ]%, +and the infinitely thin path describing the entire circle or ellipse +intersects the horizontal axis at % [ x, ~y +^ {height over 2} ]% and +% [ x +^ width , ~y +^ { height over 2 }] % +and intersects the vertical axis at % [ x +^ { width over 2 } , ~y ]% and +% [ x +^ { width over 2 }, ~y +^ height ]%. +These coordinates can be fractional +and so are not truncated to discrete coordinates. +The path should be defined by the ideal mathematical path. +For a wide line with line-width lw, +the bounding outlines for filling are given +by the two infinitely thin paths consisting of all points whose perpendicular +distance from the path of the circle/ellipse is equal to lw/2 +(which may be a fractional value). +The cap-style and join-style are applied the same as for a line +corresponding to the tangent of the circle/ellipse at the endpoint. +.LP +For an arc specified as % [ ~x, ~y, ~width, ~height, ~angle1, ~angle2 ]%, +the angles must be specified +in the effectively skewed coordinate system of the ellipse (for a +circle, the angles and coordinate systems are identical). The +relationship between these angles and angles expressed in the normal +coordinate system of the screen (as measured with a protractor) is as +follows: +.LP +.Ds +% roman "skewed-angle" ~ = ~ atan left ( tan ( roman "normal-angle" ) + * width over height right ) +^ adjust% +.De +.LP +The skewed-angle and normal-angle are expressed in radians (rather +than in degrees scaled by 64) in the range % [ 0 , ~2 pi ]% and where atan +returns a value in the range % [ - pi over 2 , ~pi over 2 ] % +and adjust is: +.LP +.Ds +.TA 1i 2i +.ta 1i 2i +%0% for normal-angle in the range % [ 0 , ~pi over 2 ]% +%pi% for normal-angle in the range % [ pi over 2 , ~{3 pi} over 2 ]% +%2 pi% for normal-angle in the range % [ {3 pi} over 2 , ~2 pi ]% +.De +.LP +For any given arc, +.PN XDrawArc +and +.PN XDrawArcs +do not draw a pixel more than once. +If two arcs join correctly and if the line-width is greater than zero +and the arcs intersect, +.PN XDrawArc +and +.PN XDrawArcs +do not draw a pixel more than once. +Otherwise, +the intersecting pixels of intersecting arcs are drawn multiple times. +Specifying an arc with one endpoint and a clockwise extent draws the same pixels +as specifying the other endpoint and an equivalent counterclockwise extent, +except as it affects joins. +.LP +If the last point in one arc coincides with the first point in the following +arc, the two arcs will join correctly. +If the first point in the first arc coincides with the last point in the last +arc, the two arcs will join correctly. +By specifying one axis to be zero, a horizontal or vertical line can be +drawn. +Angles are computed based solely on the coordinate system and ignore the +aspect ratio. +.LP +Both functions use these GC components: +function, plane-mask, line-width, line-style, cap-style, join-style, +fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. +They also use these GC mode-dependent components: +foreground, background, tile, stipple, tile-stipple-x-origin, +tile-stipple-y-origin, dash-offset, and dash-list. +.LP +.PN XDrawArc +and +.PN XDrawArcs +can generate +.PN BadDrawable , +.PN BadGC , +and +.PN BadMatch +errors. +.NH 2 +Filling Areas +.XS +\*(SN Filling Areas +.XE +.LP +Xlib provides functions that you can use to fill: +.IP \(bu 5 +A single rectangle or multiple rectangles +.IP \(bu 5 +A single polygon +.IP \(bu 5 +A single arc or multiple arcs +.NH 3 +Filling Single and Multiple Rectangles +.XS +\*(SN Filling Single and Multiple Rectangles +.XE +.LP +.IN "Filling" "rectangles" +.IN "XFillRectangle" +.IN "Rectangle" "filling" +.IN "XFillRectangles" +.LP +.sp +To fill a single rectangular area in a given drawable, use +.PN XFillRectangle . +.IN "XFillRectangle" "" "@DEF@" +.sM +.FD 0 +XFillRectangle\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fId\fP\^; +.br + GC \fIgc\fP\^; +.br + int \fIx\fP\^, \fIy\fP\^; +.br + unsigned int \fIwidth\fP\^, \fIheight\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fId\fP 1i +Specifies the drawable. +.IP \fIgc\fP 1i +Specifies the GC. +.ds Xy , which are relative to the origin of the drawable \ +and specify the upper-left corner of the rectangle +.IP \fIx\fP 1i +.br +.ns +.IP \fIy\fP 1i +Specify the x and y coordinates\*(Xy. +.ds Wh , which are the dimensions of the rectangle to be filled +.IP \fIwidth\fP 1i +.br +.ns +.IP \fIheight\fP 1i +Specify the width and height\*(Wh. +.LP +.eM +.sp +To fill multiple rectangular areas in a given drawable, use +.PN XFillRectangles . +.IN "XFillRectangles" "" "@DEF@" +.sM +.FD 0 +XFillRectangles\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIrectangles\fP\^, \fInrectangles\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fId\fP\^; +.br + GC \fIgc\fP\^; +.br + XRectangle *\fIrectangles\fP\^; +.br + int \fInrectangles\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fId\fP 1i +Specifies the drawable. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fIrectangles\fP 1i +Specifies an array of rectangles. +.IP \fInrectangles\fP 1i +Specifies the number of rectangles in the array. +.LP +.eM +The +.PN XFillRectangle +and +.PN XFillRectangles +functions fill the specified rectangle or rectangles +as if a four-point +.PN FillPolygon +protocol request were specified for each rectangle: +.LP +.Ds +[x,y] [x+width,y] [x+width,y+height] [x,y+height] +.De +.LP +Each function uses the x and y coordinates, +width and height dimensions, and GC you specify. +.LP +.PN XFillRectangles +fills the rectangles in the order listed in the array. +For any given rectangle, +.PN XFillRectangle +and +.PN XFillRectangles +do not draw a pixel more than once. +If rectangles intersect, the intersecting pixels are +drawn multiple times. +.LP +Both functions use these GC components: +function, plane-mask, fill-style, subwindow-mode, +clip-x-origin, clip-y-origin, and clip-mask. +They also use these GC mode-dependent components: +foreground, background, tile, stipple, tile-stipple-x-origin, +and tile-stipple-y-origin. +.LP +.PN XFillRectangle +and +.PN XFillRectangles +can generate +.PN BadDrawable , +.PN BadGC , +and +.PN BadMatch +errors. +.NH 3 +Filling a Single Polygon +.XS +\*(SN Filling a Single Polygon +.XE +.LP +.sp +To fill a polygon area in a given drawable, use +.PN XFillPolygon . +.IN "Polygons" "filling" +.IN "Filling" "polygon" +.IN "XFillPolygon" "" "@DEF@" +.sM +.FD 0 +XFillPolygon\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIpoints\fP\^, \fInpoints\fP\^, \fIshape\fP\^, \fImode\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fId\fP\^; +.br + GC \fIgc\fP\^; +.br + XPoint *\fIpoints\fP\^; +.br + int \fInpoints\fP\^; +.br + int \fIshape\fP\^; +.br + int \fImode\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fId\fP 1i +Specifies the drawable. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fIpoints\fP 1i +Specifies an array of points. +.IP \fInpoints\fP 1i +Specifies the number of points in the array. +.IP \fIshape\fP 1i +Specifies a shape that helps the server to improve performance. +You can pass +.PN Complex , +.PN Convex , +or +.PN Nonconvex . +.IP \fImode\fP 1i +Specifies the coordinate mode. +You can pass +.PN CoordModeOrigin +or +.PN CoordModePrevious . +.LP +.eM +.PN XFillPolygon +fills the region closed by the specified path. +The path is closed +automatically if the last point in the list does not coincide with the +first point. +.PN XFillPolygon +does not draw a pixel of the region more than once. +.PN CoordModeOrigin +treats all coordinates as relative to the origin, +and +.PN CoordModePrevious +treats all coordinates after the first as relative to the previous point. +.LP +Depending on the specified shape, the following occurs: +.IP \(bu 5 +If shape is +.PN Complex , +the path may self-intersect. +Note that contiguous coincident points in the path are not treated +as self-intersection. +.IP \(bu 5 +If shape is +.PN Convex , +for every pair of points inside the polygon, +the line segment connecting them does not intersect the path. +If known by the client, +specifying +.PN Convex +can improve performance. +If you specify +.PN Convex +for a path that is not convex, +the graphics results are undefined. +.IP \(bu 5 +If shape is +.PN Nonconvex , +the path does not self-intersect, but the shape is not +wholly convex. +If known by the client, +specifying +.PN Nonconvex +instead of +.PN Complex +may improve performance. +If you specify +.PN Nonconvex +for a self-intersecting path, the graphics results are undefined. +.LP +The fill-rule of the GC controls the filling behavior of +self-intersecting polygons. +.LP +This function uses these GC components: +function, plane-mask, fill-style, fill-rule, subwindow-mode, clip-x-origin, +clip-y-origin, and clip-mask. +It also uses these GC mode-dependent components: +foreground, background, tile, stipple, tile-stipple-x-origin, +and tile-stipple-y-origin. +.LP +.PN XFillPolygon +can generate +.PN BadDrawable , +.PN BadGC , +.PN BadMatch , +and +.PN BadValue +errors. +.NH 3 +Filling Single and Multiple Arcs +.XS +\*(SN Filling Single and Multiple Arcs +.XE +.LP +.IN "XFillArc" +.IN "Arcs" "filling" +.IN "Filling" "arcs" +To fill a single arc in a given drawable, use +.PN XFillArc . +.IN "XFillArc" "" "@DEF@" +.sM +.FD 0 +XFillArc\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIangle1\fP\^, \fIangle2\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fId\fP\^; +.br + GC \fIgc\fP\^; +.br + int \fIx\fP\^, \fIy\fP\^; +.br + unsigned int \fIwidth\fP\^, \fIheight\fP\^; +.br + int \fIangle1\fP\^, \fIangle2\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fId\fP 1i +Specifies the drawable. +.IP \fIgc\fP 1i +Specifies the GC. +.ds Xy , which are relative to the origin of the drawable \ +and specify the upper-left corner of the bounding rectangle +.IP \fIx\fP 1i +.br +.ns +.IP \fIy\fP 1i +Specify the x and y coordinates\*(Xy. +.ds Wh , which are the major and minor axes of the arc +.IP \fIwidth\fP 1i +.br +.ns +.IP \fIheight\fP 1i +Specify the width and height\*(Wh. +.IP \fIangle1\fP 1i +Specifies the start of the arc relative to the three-o'clock position +from the center, in units of degrees * 64. +.IP \fIangle2\fP 1i +Specifies the path and extent of the arc relative to the start of the +arc, in units of degrees * 64. +.LP +.eM +.sp +To fill multiple arcs in a given drawable, use +.PN XFillArcs . +.IN "XFillArcs" "" "@DEF@" +.sM +.FD 0 +XFillArcs\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIarcs\fP\^, \fInarcs\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fId\fP\^; +.br + GC \fIgc\fP\^; +.br + XArc *\fIarcs\fP\^; +.br + int \fInarcs\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fId\fP 1i +Specifies the drawable. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fIarcs\fP 1i +Specifies an array of arcs. +.IP \fInarcs\fP 1i +Specifies the number of arcs in the array. +.LP +.eM +For each arc, +.PN XFillArc +or +.PN XFillArcs +fills the region closed by the infinitely thin path +described by the specified arc and, depending on the +arc-mode specified in the GC, one or two line segments. +For +.PN ArcChord , +the single line segment joining the endpoints of the arc is used. +For +.PN ArcPieSlice , +the two line segments joining the endpoints of the arc with the center +point are used. +.PN XFillArcs +fills the arcs in the order listed in the array. +For any given arc, +.PN XFillArc +and +.PN XFillArcs +do not draw a pixel more than once. +If regions intersect, +the intersecting pixels are drawn multiple times. +.LP +Both functions use these GC components: +function, plane-mask, fill-style, arc-mode, subwindow-mode, clip-x-origin, +clip-y-origin, and clip-mask. +They also use these GC mode-dependent components: +foreground, background, tile, stipple, tile-stipple-x-origin, +and tile-stipple-y-origin. +.LP +.PN XFillArc +and +.PN XFillArcs +can generate +.PN BadDrawable , +.PN BadGC , +and +.PN BadMatch +errors. +.NH 2 +Font Metrics +.XS +\*(SN Font Metrics +.XE +.LP +.IN "Font" +A font is a graphical description of a set of characters that are used to +increase efficiency whenever a set of small, similar sized patterns are +repeatedly used. +.LP +This section discusses how to: +.IP \(bu 5 +Load and free fonts +.IP \(bu 5 +Obtain and free font names +.IP \(bu 5 +Compute character string sizes +.IP \(bu 5 +Compute logical extents +.IP \(bu 5 +Query character string sizes +.LP +The X server loads fonts whenever a program requests a new font. +The server can cache fonts for quick lookup. +Fonts are global across all screens in a server. +Several levels are possible when dealing with fonts. +Most applications simply use +.PN XLoadQueryFont +to load a font and query the font metrics. +.LP +Characters in fonts are regarded as masks. +Except for image text requests, +the only pixels modified are those in which bits are set to 1 in the character. +This means that it makes sense to draw text using stipples or tiles +(for example, many menus gray-out unusable entries). +.LP +.sM +The +.PN XFontStruct +structure contains all of the information for the font +and consists of the font-specific information as well as +a pointer to an array of +.PN XCharStruct +structures for the +characters contained in the font. +The +.PN XFontStruct , +.PN XFontProp , +and +.PN XCharStruct +structures contain: +.LP +.IN "XCharStruct" "" "@DEF@" +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + short lbearing; /* origin to left edge of raster */ + short rbearing; /* origin to right edge of raster */ + short width; /* advance to next char's origin */ + short ascent; /* baseline to top edge of raster */ + short descent; /* baseline to bottom edge of raster */ + unsigned short attributes; /* per char flags (not predefined) */ +} XCharStruct; +.De +.LP +.IN "XFontProp" "" "@DEF@" +.Ds 0 +.TA .5i 1i 3i +.ta .5i 1i 3i +typedef struct { + Atom name; + unsigned long card32; +} XFontProp; +.De +.LP +.IN "XChar2b" "" "@DEF@" +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { /* normal 16 bit characters are two bytes */ + unsigned char byte1; + unsigned char byte2; +} XChar2b; +.De +.LP +.IN "XFontStruct" "" "@DEF@" +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + XExtData *ext_data; /* hook for extension to hang data */ + Font fid; /* Font id for this font */ + unsigned direction; /* hint about the direction font is painted */ + unsigned min_char_or_byte2; /* first character */ + unsigned max_char_or_byte2; /* last character */ + unsigned min_byte1; /* first row that exists */ + unsigned max_byte1; /* last row that exists */ + Bool all_chars_exist; /* flag if all characters have nonzero size */ + unsigned default_char; /* char to print for undefined character */ + int n_properties; /* how many properties there are */ + XFontProp *properties; /* pointer to array of additional properties */ + XCharStruct min_bounds; /* minimum bounds over all existing char */ + XCharStruct max_bounds; /* maximum bounds over all existing char */ + XCharStruct *per_char; /* first_char to last_char information */ + int ascent; /* logical extent above baseline for spacing */ + int descent; /* logical descent below baseline for spacing */ +} XFontStruct; +.De +.LP +.eM +X supports single byte/character, two bytes/character matrix, +and 16-bit character text operations. +Note that any of these forms can be used with a font, but a +single byte/character text request can only specify a single byte +(that is, the first row of a 2-byte font). +You should view 2-byte fonts as a two-dimensional matrix of defined +characters: byte1 specifies the range of defined rows and +byte2 defines the range of defined columns of the font. +Single byte/character fonts have one row defined, and the byte2 range +specified in the structure defines a range of characters. +.LP +The bounding box of a character is defined by the +.PN XCharStruct +of that character. +When characters are absent from a font, +the default_char is used. +When fonts have all characters of the same size, +only the information in the +.PN XFontStruct +min and max bounds are used. +.LP +The members of the +.PN XFontStruct +have the following semantics: +.IP \(bu 5 +The direction member can be either +.PN FontLeftToRight +or +.PN FontRightToLeft . +It is just a hint as to whether most +.PN XCharStruct +elements +have a positive +.Pn ( FontLeftToRight ) +or a negative +.Pn ( FontRightToLeft ) +character width +metric. +The core protocol defines no support for vertical text. +.IP \(bu 5 +If the min_byte1 and max_byte1 members are both zero, min_char_or_byte2 +specifies the linear character index corresponding to the first element +of the per_char array, and max_char_or_byte2 specifies the linear character +index of the last element. +.IP +If either min_byte1 or max_byte1 are nonzero, both +min_char_or_byte2 and max_char_or_byte2 are less than 256, +and the 2-byte character index values corresponding to the +per_char array element N (counting from 0) are: +.IP +.nf + byte1 = N/D + min_byte1 +.br + byte2 = N\\D + min_char_or_byte2 +.IP +.fi +where: +.IP +.nf + D = max_char_or_byte2 \- min_char_or_byte2 + 1 + / = integer division + \\ = integer modulus +.fi +.IP \(bu 5 +If the per_char pointer is NULL, +all glyphs between the first and last character indexes +inclusive have the same information, +as given by both min_bounds and max_bounds. +.IP \(bu 5 +If all_chars_exist is +.PN True , +all characters in the per_char array have nonzero bounding boxes. +.IP \(bu 5 +The default_char member specifies the character that will be used when an +undefined or nonexistent character is printed. +The default_char is a 16-bit character (not a 2-byte character). +For a font using 2-byte matrix format, +the default_char has byte1 in the most-significant byte +and byte2 in the least significant byte. +If the default_char itself specifies an undefined or nonexistent character, +no printing is performed for an undefined or nonexistent character. +.IP \(bu 5 +The min_bounds and max_bounds members contain the most extreme values of +each individual +.PN XCharStruct +component over all elements of this array +(and ignore nonexistent characters). +The bounding box of the font (the smallest +rectangle enclosing the shape obtained by superimposing all of the +characters at the same origin [x,y]) has its upper-left coordinate at: +.Ds + [x + min_bounds.lbearing, y \- max_bounds.ascent] +.De +.IP +Its width is: +.Ds + max_bounds.rbearing \- min_bounds.lbearing +.De +.IP +Its height is: +.Ds + max_bounds.ascent + max_bounds.descent +.De +.IP \(bu 5 +The ascent member is the logical extent of the font above the baseline that is +used for determining line spacing. +Specific characters may extend beyond +this. +.IP \(bu 5 +The descent member is the logical extent of the font at or below the +baseline that is used for determining line spacing. +Specific characters may extend beyond this. +.IP \(bu 5 +If the baseline is at Y-coordinate y, +the logical extent of the font is inclusive between the Y-coordinate +values (y \- font.ascent) and (y + font.descent \- 1). +Typically, +the minimum interline spacing between rows of text is given +by ascent + descent. +.LP +For a character origin at [x,y], +the bounding box of a character (that is, +the smallest rectangle that encloses the character's shape) +described in terms of +.PN XCharStruct +components is a rectangle with its upper-left corner at: +.LP +.Ds +[x + lbearing, y \- ascent] +.De +.LP +Its width is: +.LP +.Ds +rbearing \- lbearing +.De +.LP +Its height is: +.LP +.Ds +ascent + descent +.De +.LP +The origin for the next character is defined to be: +.LP +.Ds +[x + width, y] +.De +.LP +The lbearing member defines the extent of the left edge of the character ink +from the origin. +The rbearing member defines the extent of the right edge of the character ink +from the origin. +The ascent member defines the extent of the top edge of the character ink +from the origin. +The descent member defines the extent of the bottom edge of the character ink +from the origin. +The width member defines the logical width of the character. +.LP +Note that the baseline (the y position of the character origin) +is logically viewed as being the scanline just below nondescending characters. +When descent is zero, +only pixels with Y-coordinates less than y are drawn, +and the origin is logically viewed as being coincident with the left edge of +a nonkerned character. +When lbearing is zero, +no pixels with X-coordinate less than x are drawn. +Any of the +.PN XCharStruct +metric members could be negative. +If the width is negative, +the next character will be placed to the left of the current origin. +.LP +The X protocol does not define the interpretation of the attributes member +in the +.PN XCharStruct +structure. +A nonexistent character is represented with all members of its +.PN XCharStruct +set to zero. +.LP +A font is not guaranteed to have any properties. +The interpretation of the property value (for example, long or unsigned long) +must be derived from \fIa priori\fP knowledge of the property. +A basic set of font properties is specified in the X Consortium standard +\fIX Logical Font Description Conventions\fP. +.NH 3 +Loading and Freeing Fonts +.XS +\*(SN Loading and Freeing Fonts +.XE +.LP +Xlib provides functions that you can use to load fonts, get font information, +unload fonts, and free font information. +.IN "Fonts" "getting information" +.IN "Fonts" "unloading" +.IN "Fonts" "freeing font information" +A few font functions use a +.PN GContext +resource ID or a font ID interchangeably. +.LP +.sp +To load a given font, use +.PN XLoadFont . +.IN "XLoadFont" "" "@DEF@" +.sM +.FD 0 +Font XLoadFont\^(\^\fIdisplay\fP, \fIname\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + char *\fIname\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIname\fP 1i +Specifies the name of the font, +which is a null-terminated string. +.LP +.eM +The +.PN XLoadFont +function loads the specified font and returns its associated font ID. +If the font name is not in the Host Portable Character Encoding, +the result is implementation-dependent. +Use of uppercase or lowercase does not matter. +When the characters ``?'' and ``*'' are used in a font name, a +pattern match is performed and any matching font is used. +In the pattern, +the ``?'' character will match any single character, +and the ``*'' character will match any number of characters. +A structured format for font names is specified in the X Consortium standard +\fIX Logical Font Description Conventions\fP. +If +.PN XLoadFont +was unsuccessful at loading the specified font, +a +.PN BadName +error results. +Fonts are not associated with a particular screen +and can be stored as a component +of any GC. +When the font is no longer needed, call +.PN XUnloadFont . +.LP +.PN XLoadFont +can generate +.PN BadAlloc +and +.PN BadName +errors. +.LP +.sp +To return information about an available font, use +.PN XQueryFont . +.IN "XQueryFont" "" "@DEF@" +.sM +.FD 0 +XFontStruct *XQueryFont\^(\^\fIdisplay\fP, \fIfont_ID\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XID \fIfont_ID\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIfont_ID\fP 1i +Specifies the font ID or the +.PN GContext +ID. +.LP +.eM +The +.PN XQueryFont +function returns a pointer to the +.PN XFontStruct +structure, which contains information associated with the font. +You can query a font or the font stored in a GC. +The font ID stored in the +.PN XFontStruct +structure will be the +.PN GContext +ID, and you need to be careful when using this ID in other functions +(see +.PN XGContextFromGC ). +If the font does not exist, +.PN XQueryFont +returns NULL. +To free this data, use +.PN XFreeFontInfo . +.LP +.sp +To perform a +.PN XLoadFont +and +.PN XQueryFont +in a single operation, use +.PN XLoadQueryFont . +.IN "XLoadQueryFont" "" "@DEF@" +.sM +.FD 0 +XFontStruct *XLoadQueryFont\^(\^\fIdisplay\fP, \fIname\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + char *\fIname\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIname\fP 1i +Specifies the name of the font, +which is a null-terminated string. +.LP +.eM +The +.PN XLoadQueryFont +function provides the most common way for accessing a font. +.PN XLoadQueryFont +both opens (loads) the specified font and returns a pointer to the +appropriate +.PN XFontStruct +structure. +If the font name is not in the Host Portable Character Encoding, +the result is implementation-dependent. +If the font does not exist, +.PN XLoadQueryFont +returns NULL. +.LP +.PN XLoadQueryFont +can generate a +.PN BadAlloc +error. +.LP +.sp +To unload the font and free the storage used by the font structure +that was allocated by +.PN XQueryFont +or +.PN XLoadQueryFont , +use +.PN XFreeFont . +.IN "XFreeFont" "" "@DEF@" +.sM +.FD 0 +XFreeFont\^(\^\fIdisplay\fP, \fIfont_struct\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XFontStruct *\fIfont_struct\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIfont_struct\fP 1i +Specifies the storage associated with the font. +.LP +.eM +The +.PN XFreeFont +function deletes the association between the font resource ID and the specified +font and frees the +.PN XFontStruct +structure. +The font itself will be freed when no other resource references it. +The data and the font should not be referenced again. +.LP +.PN XFreeFont +can generate a +.PN BadFont +error. +.LP +.sp +To return a given font property, use +.PN XGetFontProperty . +.IN "XGetFontProperty" "" "@DEF@" +.sM +.FD 0 +Bool XGetFontProperty\^(\^\fIfont_struct\fP\^, \^\fIatom\fP\^, \^\fIvalue_return\fP\^) +.br + XFontStruct *\fIfont_struct\fP\^; +.br + Atom \fIatom\fP\^; +.br + unsigned long *\fIvalue_return\fP\^; +.FN +.IP \fIfont_struct\fP 1i +Specifies the storage associated with the font. +.IP \fIatom\fP 1i +Specifies the atom for the property name you want returned. +.IP \fIvalue_return\fP 1i +Returns the value of the font property. +.LP +.eM +Given the atom for that property, +the +.PN XGetFontProperty +function returns the value of the specified font property. +.PN XGetFontProperty +also returns +.PN False +if the property was not defined or +.PN True +if it was defined. +A set of predefined atoms exists for font properties, +which can be found in +.hN X11/Xatom.h . +This set contains the standard properties associated with +a font. +Although it is not guaranteed, +it is likely that the predefined font properties will be present. +.LP +.sp +To unload a font that was loaded by +.PN XLoadFont , +use +.PN XUnloadFont . +.IN "XUnloadFont" "" "@DEF@" +.sM +.FD 0 +XUnloadFont\^(\^\fIdisplay\fP, \fIfont\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Font \fIfont\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIfont\fP 1i +Specifies the font. +.LP +.eM +The +.PN XUnloadFont +function deletes the association between the font resource ID and the specified font. +The font itself will be freed when no other resource references it. +The font should not be referenced again. +.LP +.PN XUnloadFont +can generate a +.PN BadFont +error. +.NH 3 +Obtaining and Freeing Font Names and Information +.XS +\*(SN Obtaining and Freeing Font Names and Information +.XE +.LP +You obtain font names and information by matching a wildcard specification +when querying a font type for a list of available sizes and so on. +.LP +.sp +To return a list of the available font names, use +.PN XListFonts . +.IN "XListFonts" "" "@DEF@" +.sM +.FD 0 +char **XListFonts\^(\^\fIdisplay\fP, \fIpattern\fP\^, \fImaxnames\fP, \fIactual_count_return\fP\^) +.br + Display *\^\fIdisplay\fP\^; +.br + char *\^\fIpattern\fP\^; +.br + int \fImaxnames\fP\^; +.br + int *\^\fIactual_count_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIpattern\fP 1i +Specifies the null-terminated pattern string that can contain wildcard +characters. +.IP \fImaxnames\fP 1i +Specifies the maximum number of names to be returned. +.IP \fIactual_count_return\fP 1i +Returns the actual number of font names. +.LP +.eM +The +.PN XListFonts +function returns an array of available font names +(as controlled by the font search path; see +.PN XSetFontPath ) +that match the string you passed to the pattern argument. +The pattern string can contain any characters, +but each asterisk (*) is a wildcard for any number of characters, +and each question mark (?) is a wildcard for a single character. +If the pattern string is not in the Host Portable Character Encoding, +the result is implementation-dependent. +Use of uppercase or lowercase does not matter. +Each returned string is null-terminated. +If the data returned by the server is in the Latin Portable Character Encoding, +then the returned strings are in the Host Portable Character Encoding. +Otherwise, the result is implementation-dependent. +If there are no matching font names, +.PN XListFonts +returns NULL. +The client should call +.PN XFreeFontNames +when finished with the result to free the memory. +.LP +.sp +To free a font name array, use +.PN XFreeFontNames . +.IN "XFreeFontNames" "" "@DEF@" +.sM +.FD 0 +XFreeFontNames\^(\^\fIlist\fP\^) +.br + char *\fIlist\fP\^[\^]\^; +.FN +.IP \fIlist\fP 1i +Specifies the array of strings you want to free. +.LP +.eM +The +.PN XFreeFontNames +function frees the array and strings returned by +.PN XListFonts +or +.PN XListFontsWithInfo . +.LP +.sp +To obtain the names and information about available fonts, use +.PN XListFontsWithInfo . +.IN "XListFontsWithInfo" "" "@DEF@" +.sM +.FD 0 +char **XListFontsWithInfo\^(\^\fIdisplay\fP, \fIpattern\fP, \fImaxnames\fP, \fIcount_return\fP, \fIinfo_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + char *\fIpattern\fP\^; +.br + int \fImaxnames\fP\^; +.br + int *\fIcount_return\fP\^; +.br + XFontStruct **\fIinfo_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIpattern\fP 1i +Specifies the null-terminated pattern string that can contain wildcard +characters. +.IP \fImaxnames\fP 1i +Specifies the maximum number of names to be returned. +.IP \fIcount_return\fP 1i +Returns the actual number of matched font names. +.IP \fIinfo_return\fP 1i +Returns the font information. +.LP +.eM +The +.PN XListFontsWithInfo +function returns a list of font names that match the specified pattern and their +associated font information. +The list of names is limited to size specified by maxnames. +The information returned for each font is identical to what +.PN XLoadQueryFont +would return except that the per-character metrics are not returned. +The pattern string can contain any characters, +but each asterisk (*) is a wildcard for any number of characters, +and each question mark (?) is a wildcard for a single character. +If the pattern string is not in the Host Portable Character Encoding, +the result is implementation-dependent. +Use of uppercase or lowercase does not matter. +Each returned string is null-terminated. +If the data returned by the server is in the Latin Portable Character Encoding, +then the returned strings are in the Host Portable Character Encoding. +Otherwise, the result is implementation-dependent. +If there are no matching font names, +.PN XListFontsWithInfo +returns NULL. +.LP +To free only the allocated name array, +the client should call +.PN XFreeFontNames . +To free both the name array and the font information array +or to free just the font information array, +the client should call +.PN XFreeFontInfo . +.LP +.sp +To free font structures and font names, use +.PN XFreeFontInfo . +.IN "XFreeFontInfo" "" "@DEF@" +.sM +.FD 0 +XFreeFontInfo(\^\fInames\fP, \fIfree_info\fP, \fIactual_count\fP\^) +.br + char **\fInames\fP\^; +.br + XFontStruct *\fIfree_info\fP; +.br + int \fIactual_count\fP\^; +.FN +.IP \fInames\fP 1i +Specifies the list of font names. + +.IP \fIfree_info\fP 1i +Specifies the font information. + +.IP \fIactual_count\fP 1i +Specifies the actual number of font names. + +.LP +.eM +The +.PN XFreeFontInfo +function frees a font structure or an array of font structures +and optionally an array of font names. +If NULL is passed for names, no font names are freed. +If a font structure for an open font (returned by +.PN XLoadQueryFont ) +is passed, the structure is freed, +but the font is not closed; use +.PN XUnloadFont +to close the font. +.NH 3 +Computing Character String Sizes +.XS +\*(SN Computing Character String Sizes +.XE +.LP +Xlib provides functions that you can use to compute the width, +the logical extents, +and the server information about 8-bit and 2-byte text strings. +.IN "XTextWidth" +.IN "XTextWidth16" +The width is computed by adding the character widths of all the characters. +It does not matter if the font is an 8-bit or 2-byte font. +These functions return the sum of the character metrics in pixels. +.LP +.sp +To determine the width of an 8-bit character string, use +.PN XTextWidth . +.IN "XTextWidth" "" "@DEF@" +.sM +.FD 0 +int XTextWidth\^(\^\fIfont_struct\fP\^, \fIstring\fP, \fIcount\fP\^) +.br + XFontStruct *\fIfont_struct\fP\^; +.br + char *\fIstring\fP\^; +.br + int \fIcount\fP\^; +.FN +.IP \fIfont_struct\fP 1i +Specifies the font used for the width computation. +.IP \fIstring\fP 1i +Specifies the character string. +.IP \fIcount\fP 1i +Specifies the character count in the specified string. +.LP +.eM +.sp +To determine the width of a 2-byte character string, use +.PN XTextWidth16 . +.IN "XTextWidth16" "" "@DEF@" +.sM +.FD 0 +int XTextWidth16\^(\^\fIfont_struct\fP\^, \fIstring\fP, \fIcount\fP\^) +.br + XFontStruct *\fIfont_struct\fP\^; +.br + XChar2b *\fIstring\fP\^; +.br + int \fIcount\fP\^; +.FN +.IP \fIfont_struct\fP 1i +Specifies the font used for the width computation. +.IP \fIstring\fP 1i +Specifies the character string. +.IP \fIcount\fP 1i +Specifies the character count in the specified string. +.LP +.eM +.NH 3 +Computing Logical Extents +.XS +\*(SN Computing Logical Extents +.XE +.LP +To compute the bounding box of an 8-bit character string in a given font, use +.PN XTextExtents . +.IN "XTextExtents" "" "@DEF@" +.sM +.FD 0 +XTextExtents\^(\^\fIfont_struct\fP\^, \fIstring\fP\^, \fInchars\fP\^, \ +\fIdirection_return\fP, \fIfont_ascent_return\fP, +.br + \fIfont_descent_return\fP, \fIoverall_return\fP\^) +.br + XFontStruct *\fIfont_struct\fP\^; +.br + char *\fIstring\fP\^; +.br + int \fInchars\fP\^; +.br + int *\fIdirection_return\fP\^; +.br + int *\fIfont_ascent_return\fP, *\fIfont_descent_return\fP\^; +.br + XCharStruct *\fIoverall_return\fP\^; + +.FN +.IP \fIfont_struct\fP 1i +Specifies the +.PN XFontStruct +structure. +.IP \fIstring\fP 1i +Specifies the character string. +.IP \fInchars\fP 1i +Specifies the number of characters in the character string. +.IP \fIdirection_return\fP 1i +Returns the value of the direction hint +.Pn ( FontLeftToRight +or +.PN FontRightToLeft ). +.IP \fIfont_ascent_return\fP 1i +Returns the font ascent. +.IP \fIfont_descent_return\fP 1i +Returns the font descent. +.IP \fIoverall_return\fP 1i +Returns the overall size in the specified +.PN XCharStruct +structure. +.LP +.eM +.sp +To compute the bounding box of a 2-byte character string in a given font, use +.PN XTextExtents16 . +.IN "XTextExtents16" "" "@DEF@" +.sM +.FD 0 +XTextExtents16\^(\^\fIfont_struct\fP\^, \fIstring\fP\^, \fInchars\fP\^, \ +\fIdirection_return\fP, \fIfont_ascent_return\fP, +.br + \fIfont_descent_return\fP, \fIoverall_return\fP\^) +.br + XFontStruct *\fIfont_struct\fP\^; +.br + XChar2b *\fIstring\fP\^; +.br + int \fInchars\fP\^; +.br + int *\fIdirection_return\fP\^; +.br + int *\fIfont_ascent_return\fP, *\fIfont_descent_return\fP\^; +.br + XCharStruct *\fIoverall_return\fP\^; + +.FN +.IP \fIfont_struct\fP 1i +Specifies the +.PN XFontStruct +structure. +.IP \fIstring\fP 1i +Specifies the character string. +.IP \fInchars\fP 1i +Specifies the number of characters in the character string. +.IP \fIdirection_return\fP 1i +Returns the value of the direction hint +.Pn ( FontLeftToRight +or +.PN FontRightToLeft ). +.IP \fIfont_ascent_return\fP 1i +Returns the font ascent. +.IP \fIfont_descent_return\fP 1i +Returns the font descent. +.IP \fIoverall_return\fP 1i +Returns the overall size in the specified +.PN XCharStruct +structure. +.LP +.eM +The +.PN XTextExtents +and +.PN XTextExtents16 +functions +perform the size computation locally and, thereby, +avoid the round-trip overhead of +.PN XQueryTextExtents +and +.PN XQueryTextExtents16 . +Both functions return an +.PN XCharStruct +structure, whose members are set to the values as follows. +.LP +The ascent member is set to the maximum of the ascent metrics of all +characters in the string. +The descent member is set to the maximum of the descent metrics. +The width member is set to the sum of the character-width metrics of all +characters in the string. +For each character in the string, +let W be the sum of the character-width metrics of all characters preceding +it in the string. +Let L be the left-side-bearing metric of the character plus W. +Let R be the right-side-bearing metric of the character plus W. +The lbearing member is set to the minimum L of all characters in the string. +The rbearing member is set to the maximum R. +.LP +For fonts defined with linear indexing rather than 2-byte matrix indexing, +each +.PN XChar2b +structure is interpreted as a 16-bit number with byte1 as the +most significant byte. +If the font has no defined default character, +undefined characters in the string are taken to have all zero metrics. +.NH 3 +Querying Character String Sizes +.XS +\*(SN Querying Character String Sizes +.XE +.LP +To query the server for the bounding box of an 8-bit character string in a +given font, use +.PN XQueryTextExtents . +.IN "XQueryTextExtents" "" "@DEF@" +.sM +.FD 0 +XQueryTextExtents\^(\^\fIdisplay\fP, \fIfont_ID\fP, \fIstring\fP, \ +\fInchars\fP, \fIdirection_return\fP, \fIfont_ascent_return\fP, +.br + \fIfont_descent_return\fP, \fIoverall_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XID \fIfont_ID\fP\^; +.br + char *\fIstring\fP\^; +.br + int \fInchars\fP\^; +.br + int *\fIdirection_return\fP\^; +.br + int *\fIfont_ascent_return\fP, *\fIfont_descent_return\fP\^; +.br + XCharStruct *\fIoverall_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIfont_ID\fP 1i +Specifies either the font ID or the +.PN GContext +ID that contains the font. +.IP \fIstring\fP 1i +Specifies the character string. +.IP \fInchars\fP 1i +Specifies the number of characters in the character string. +.IP \fIdirection_return\fP 1i +Returns the value of the direction hint +.Pn ( FontLeftToRight +or +.PN FontRightToLeft ). +.IP \fIfont_ascent_return\fP 1i +Returns the font ascent. +.IP \fIfont_descent_return\fP 1i +Returns the font descent. +.IP \fIoverall_return\fP 1i +Returns the overall size in the specified +.PN XCharStruct +structure. +.LP +.eM +.sp +To query the server for the bounding box of a 2-byte character string +in a given font, use +.PN XQueryTextExtents16 . +.IN "XQueryTextExtents16" "" "@DEF@" +.sM +.FD 0 +XQueryTextExtents16\^(\^\fIdisplay\fP, \fIfont_ID\fP, \fIstring\fP, \ +\fInchars\fP, \fIdirection_return\fP, \fIfont_ascent_return\fP, +.br + \fIfont_descent_return\fP, \fIoverall_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XID \fIfont_ID\fP\^; +.br + XChar2b *\fIstring\fP\^; +.br + int \fInchars\fP\^; +.br + int *\fIdirection_return\fP\^; +.br + int *\fIfont_ascent_return\fP, *\fIfont_descent_return\fP\^; +.br + XCharStruct *\fIoverall_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIfont_ID\fP 1i +Specifies either the font ID or the +.PN GContext +ID that contains the font. +.IP \fIstring\fP 1i +Specifies the character string. +.IP \fInchars\fP 1i +Specifies the number of characters in the character string. +.IP \fIdirection_return\fP 1i +Returns the value of the direction hint +.Pn ( FontLeftToRight +or +.PN FontRightToLeft ). +.IP \fIfont_ascent_return\fP 1i +Returns the font ascent. +.IP \fIfont_descent_return\fP 1i +Returns the font descent. +.IP \fIoverall_return\fP 1i +Returns the overall size in the specified +.PN XCharStruct +structure. +.LP +.eM +The +.PN XQueryTextExtents +and +.PN XQueryTextExtents16 +functions return the bounding box of the specified 8-bit and 16-bit +character string in the specified font or the font contained in the +specified GC. +These functions query the X server and, therefore, suffer the round-trip +overhead that is avoided by +.PN XTextExtents +and +.PN XTextExtents16 . +Both functions return a +.PN XCharStruct +structure, whose members are set to the values as follows. +.LP +The ascent member is set to the maximum of the ascent metrics +of all characters in the string. +The descent member is set to the maximum of the descent metrics. +The width member is set to the sum of the character-width metrics +of all characters in the string. +For each character in the string, +let W be the sum of the character-width metrics of all characters preceding +it in the string. +Let L be the left-side-bearing metric of the character plus W. +Let R be the right-side-bearing metric of the character plus W. +The lbearing member is set to the minimum L of all characters in the string. +The rbearing member is set to the maximum R. +.LP +For fonts defined with linear indexing rather than 2-byte matrix indexing, +each +.PN XChar2b +structure is interpreted as a 16-bit number with byte1 as the +most significant byte. +If the font has no defined default character, +undefined characters in the string are taken to have all zero metrics. +.LP +Characters with all zero metrics are ignored. +If the font has no defined default_char, +the undefined characters in the string are also ignored. +.LP +.PN XQueryTextExtents +and +.PN XQueryTextExtents16 +can generate +.PN BadFont +and +.PN BadGC +errors. +.NH 2 +Drawing Text +.XS +\*(SN Drawing Text +.XE +.LP +This section discusses how to draw: +.IP \(bu 5 +Complex text +.IP \(bu 5 +Text characters +.IP \(bu 5 +Image text characters +.LP +The fundamental text functions +.PN XDrawText +and +.PN XDrawText16 +use the following structures: +.LP +.IN "XTextItem" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + char *chars; /* pointer to string */ + int nchars; /* number of characters */ + int delta; /* delta between strings */ + Font font; /* Font to print it in, None don't change */ +} XTextItem; +.De +.LP +.IN "XTextItem16" "" "@DEF@" +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + XChar2b *chars; /* pointer to two-byte characters */ + int nchars; /* number of characters */ + int delta; /* delta between strings */ + Font font; /* font to print it in, None don't change */ +} XTextItem16; +.De +.LP +.eM +If the font member is not +.PN None , +the font is changed before printing and also is stored in the GC. +If an error was generated during text drawing, +the previous items may have been drawn. +The baseline of the characters are drawn starting at the x and y +coordinates that you pass in the text drawing functions. +.LP +For example, consider the background rectangle drawn by +.PN XDrawImageString . +If you want the upper-left corner of the background rectangle +to be at pixel coordinate (x,y), pass the (x,y + ascent) +as the baseline origin coordinates to the text functions. +The ascent is the font ascent, as given in the +.PN XFontStruct +structure. +If you want the lower-left corner of the background rectangle +to be at pixel coordinate (x,y), pass the (x,y \- descent + 1) +as the baseline origin coordinates to the text functions. +The descent is the font descent, as given in the +.PN XFontStruct +structure. +.NH 3 +Drawing Complex Text +.XS +\*(SN Drawing Complex Text +.XE +.LP +.IN "Text" "drawing" +.IN "Drawing" "text items" +.LP +To draw 8-bit characters in a given drawable, use +.PN XDrawText . +.IN "XDrawText" "" "@DEF@" +.sM +.FD 0 +XDrawText\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIitems\fP\^, \fInitems\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fId\fP\^; +.br + GC \fIgc\fP\^; +.br + int \fIx\fP\^, \fIy\fP\^; +.br + XTextItem *\fIitems\fP\^; +.br + int \fInitems\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fId\fP 1i +Specifies the drawable. +.IP \fIgc\fP 1i +Specifies the GC. +.ds Xy , which are relative to the origin of the specified drawable \ +and define the origin of the first character +.IP \fIx\fP 1i +.br +.ns +.IP \fIy\fP 1i +Specify the x and y coordinates\*(Xy. +.IP \fIitems\fP 1i +Specifies an array of text items. +.IP \fInitems\fP 1i +Specifies the number of text items in the array. +.LP +.eM +.sp +To draw 2-byte characters in a given drawable, use +.PN XDrawText16 . +.IN "XDrawText16" "" "@DEF@" +.sM +.FD 0 +XDrawText16\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIitems\fP\^, \fInitems\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fId\fP\^; +.br + GC \fIgc\fP\^; +.br + int \fIx\fP\^, \fIy\fP\^; +.br + XTextItem16 *\fIitems\fP\^; +.br + int \fInitems\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fId\fP 1i +Specifies the drawable. +.IP \fIgc\fP 1i +Specifies the GC. +.ds Xy , which are relative to the origin of the specified drawable \ +and define the origin of the first character +.IP \fIx\fP 1i +.br +.ns +.IP \fIy\fP 1i +Specify the x and y coordinates\*(Xy. +.IP \fIitems\fP 1i +Specifies an array of text items. +.IP \fInitems\fP 1i +Specifies the number of text items in the array. +.LP +.eM +The +.PN XDrawText16 +function is similar to +.PN XDrawText +except that it uses 2-byte or 16-bit characters. +Both functions allow complex spacing and font shifts between counted strings. +.LP +Each text item is processed in turn. +A font member other than +.PN None +in an item causes the font to be stored in the GC +and used for subsequent text. +A text element delta specifies an additional change +in the position along the x axis before the string is drawn. +The delta is always added to the character origin +and is not dependent on any characteristics of the font. +Each character image, as defined by the font in the GC, is treated as an +additional mask for a fill operation on the drawable. +The drawable is modified only where the font character has a bit set to 1. +If a text item generates a +.PN BadFont +error, the previous text items may have been drawn. +.LP +For fonts defined with linear indexing rather than 2-byte matrix indexing, +each +.PN XChar2b +structure is interpreted as a 16-bit number with byte1 as the +most significant byte. +.LP +Both functions use these GC components: +function, plane-mask, fill-style, font, subwindow-mode, +clip-x-origin, clip-y-origin, and clip-mask. +They also use these GC mode-dependent components: +foreground, background, tile, stipple, tile-stipple-x-origin, +and tile-stipple-y-origin. +.LP +.PN XDrawText +and +.PN XDrawText16 +can generate +.PN BadDrawable , +.PN BadFont , +.PN BadGC , +and +.PN BadMatch +errors. +.NH 3 +Drawing Text Characters +.XS +\*(SN Drawing Text Characters +.XE +.LP +.IN "Strings" "drawing" +.IN "Drawing" "strings" +To draw 8-bit characters in a given drawable, use +.PN XDrawString . +.IN "XDrawString" "" "@DEF@" +.sM +.FD 0 +XDrawString\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fIlength\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fId\fP\^; +.br + GC \fIgc\fP\^; +.br + int \fIx\fP\^, \fIy\fP\^; +.br + char *\fIstring\fP\^; +.br + int \fIlength\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fId\fP 1i +Specifies the drawable. +.IP \fIgc\fP 1i +Specifies the GC. +.ds Xy , which are relative to the origin of the specified drawable \ +and define the origin of the first character +.IP \fIx\fP 1i +.br +.ns +.IP \fIy\fP 1i +Specify the x and y coordinates\*(Xy. +.IP \fIstring\fP 1i +Specifies the character string. +.IP \fIlength\fP 1i +Specifies the number of characters in the string argument. +.LP +.eM +.sp +To draw 2-byte characters in a given drawable, use +.PN XDrawString16 . +.IN "XDrawString16" "" "@DEF@" +.sM +.FD 0 +XDrawString16\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fIlength\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fId\fP\^; +.br + GC \fIgc\fP\^; +.br + int \fIx\fP\^, \fIy\fP\^; +.br + XChar2b *\fIstring\fP\^; +.br + int \fIlength\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fId\fP 1i +Specifies the drawable. +.IP \fIgc\fP 1i +Specifies the GC. +.ds Xy , which are relative to the origin of the specified drawable \ +and define the origin of the first character +.IP \fIx\fP 1i +.br +.ns +.IP \fIy\fP 1i +Specify the x and y coordinates\*(Xy. +.IP \fIstring\fP 1i +Specifies the character string. +.IP \fIlength\fP 1i +Specifies the number of characters in the string argument. +.LP +.eM +Each character image, as defined by the font in the GC, is treated as an +additional mask for a fill operation on the drawable. +The drawable is modified only where the font character has a bit set to 1. +For fonts defined with 2-byte matrix indexing +and used with +.PN XDrawString16 , +each byte is used as a byte2 with a byte1 of zero. +.LP +Both functions use these GC components: +function, plane-mask, fill-style, font, subwindow-mode, clip-x-origin, +clip-y-origin, and clip-mask. +They also use these GC mode-dependent components: +foreground, background, tile, stipple, tile-stipple-x-origin, +and tile-stipple-y-origin. +.LP +.PN XDrawString +and +.PN XDrawString16 +can generate +.PN BadDrawable , +.PN BadGC , +and +.PN BadMatch +errors. +.NH 3 +Drawing Image Text Characters +.XS +\*(SN Drawing Image Text Characters +.XE +.LP +.IN "Image text" "drawing" +.IN "Drawing" "image text" +Some applications, in particular terminal emulators, need to +print image text in which both the foreground and background bits of +each character are painted. +This prevents annoying flicker on many displays. +.IN "XDrawImageString" +.IN "XDrawImageString16" +.LP +.sp +To draw 8-bit image text characters in a given drawable, use +.PN XDrawImageString . +.IN "XDrawImageString" "" "@DEF@" +.sM +.FD 0 +XDrawImageString\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fIlength\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fId\fP\^; +.br + GC \fIgc\fP\^; +.br + int \fIx\fP\^, \fIy\fP\^; +.br + char *\fIstring\fP\^; +.br + int \fIlength\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fId\fP 1i +Specifies the drawable. +.IP \fIgc\fP 1i +Specifies the GC. +.ds Xy , which are relative to the origin of the specified drawable \ +and define the origin of the first character +.IP \fIx\fP 1i +.br +.ns +.IP \fIy\fP 1i +Specify the x and y coordinates\*(Xy. +.IP \fIstring\fP 1i +Specifies the character string. +.IP \fIlength\fP 1i +Specifies the number of characters in the string argument. +.LP +.eM +.sp +To draw 2-byte image text characters in a given drawable, use +.PN XDrawImageString16 . +.IN "XDrawImageString16" "" "@DEF@" +.sM +.FD 0 +XDrawImageString16\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fIlength\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fId\fP\^; +.br + GC \fIgc\fP\^; +.br + int \fIx\fP\^, \fIy\fP\^; +.br + XChar2b *\fIstring\fP\^; +.br + int \fIlength\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fId\fP 1i +Specifies the drawable. +.IP \fIgc\fP 1i +Specifies the GC. +.ds Xy , which are relative to the origin of the specified drawable \ +and define the origin of the first character +.IP \fIx\fP 1i +.br +.ns +.IP \fIy\fP 1i +Specify the x and y coordinates\*(Xy. +.IP \fIstring\fP 1i +Specifies the character string. +.IP \fIlength\fP 1i +Specifies the number of characters in the string argument. +.LP +.eM +The +.PN XDrawImageString16 +function is similar to +.PN XDrawImageString +except that it uses 2-byte or 16-bit characters. +Both functions also use both the foreground and background pixels +of the GC in the destination. +.LP +The effect is first to fill a +destination rectangle with the background pixel defined in the GC and then +to paint the text with the foreground pixel. +The upper-left corner of the filled rectangle is at: +.LP +.Ds +[x, y \- font-ascent] +.De +.LP +The width is: +.LP +.Ds +overall-width +.De +.LP +The height is: +.LP +.Ds +font-ascent + font-descent +.De +.LP +The overall-width, font-ascent, and font-descent +are as would be returned by +.PN XQueryTextExtents +using gc and string. +The function and fill-style defined in the GC are ignored for these functions. +The effective function is +.PN GXcopy , +and the effective fill-style is +.PN FillSolid . +.LP +For fonts defined with 2-byte matrix indexing +and used with +.PN XDrawImageString , +each byte is used as a byte2 with a byte1 of zero. +.LP +Both functions use these GC components: +plane-mask, foreground, background, font, subwindow-mode, clip-x-origin, +clip-y-origin, and clip-mask. +.LP +.PN XDrawImageString +and +.PN XDrawImageString16 +can generate +.PN BadDrawable , +.PN BadGC , +and +.PN BadMatch +errors. +.LP +.NH 2 +Transferring Images between Client and Server +.XS +\*(SN Transferring Images between Client and Server +.XE +.LP +Xlib provides functions that you can use to transfer images between a client +and the server. +Because the server may require diverse data formats, +Xlib provides an image object that fully describes the data in memory +and that provides for basic operations on that data. +You should reference the data +through the image object rather than referencing the data directly. +However, some implementations of the Xlib library may efficiently deal with +frequently used data formats by replacing +functions in the procedure vector with special case functions. +Supported operations include destroying the image, getting a pixel, +storing a pixel, extracting a subimage of an image, and adding a constant +to an image (see section 16.8). +.LP +All the image manipulation functions discussed in this section make use of +the +.PN XImage +structure, +which describes an image as it exists in the client's memory. +.LP +.IN "XImage" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 1i 3i +.ta .5i 1i 3i +typedef struct _XImage { + int width, height; /* size of image */ + int xoffset; /* number of pixels offset in X direction */ + int format; /* XYBitmap, XYPixmap, ZPixmap */ + char *data; /* pointer to image data */ + int byte_order; /* data byte order, LSBFirst, MSBFirst */ + int bitmap_unit; /* quant. of scanline 8, 16, 32 */ + int bitmap_bit_order; /* LSBFirst, MSBFirst */ + int bitmap_pad; /* 8, 16, 32 either XY or ZPixmap */ + int depth; /* depth of image */ + int bytes_per_line; /* accelerator to next scanline */ + int bits_per_pixel; /* bits per pixel (ZPixmap) */ + unsigned long red_mask; /* bits in z arrangement */ + unsigned long green_mask; + unsigned long blue_mask; + XPointer obdata; /* hook for the object routines to hang on */ + struct funcs { /* image manipulation routines */ + struct _XImage *(*create_image)(); + int (*destroy_image)(); + unsigned long (*get_pixel)(); + int (*put_pixel)(); + struct _XImage *(*sub_image)(); + int (*add_pixel)(); + } f; +} XImage; +.De +.LP +.eM +.sp +To initialize the image manipulation routines of an image structure, use +.PN XInitImage . +.IN "XInitImage" "" "@DEF@" +.sM +.FD 0 +Status XInitImage\^(\^\fIimage\fP\^) +.br + XImage *\fIimage\fP\^; +.FN +.IP \fIximage\fP 1i +Specifies the image. +.LP +.eM +The +.PN XInitImage +function initializes the internal image manipulation routines of an +image structure, based on the values of the various structure members. +All fields other than the manipulation routines must already be initialized. +If the bytes_per_line member is zero, +.PN XInitImage +will assume the image data is contiguous in memory and set the +bytes_per_line member to an appropriate value based on the other +members; otherwise, the value of bytes_per_line is not changed. +All of the manipulation routines are initialized to functions +that other Xlib image manipulation functions need to operate on the +type of image specified by the rest of the structure. +.LP +This function must be called for any image constructed by the client +before passing it to any other Xlib function. +Image structures created or returned by Xlib do not need to be +initialized in this fashion. +.LP +This function returns a nonzero status if initialization of the +structure is successful. It returns zero if it detected some error +or inconsistency in the structure, in which case the image is not changed. +.LP +.sp +To combine an image with a rectangle of a drawable on the display, +use +.PN XPutImage . +.IN "XPutImage" "" "@DEF@" +.sM +.FD 0 +XPutImage\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIimage\fP\^, \fIsrc_x\fP, \fIsrc_y\fP, \fIdest_x\fP\^, \fIdest_y\fP\^, \fIwidth\fP\^, \fIheight\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fId\fP\^; +.br + GC \fIgc\fP\^; +.br + XImage *\fIimage\fP\^; +.br + int \fIsrc_x\fP\^, \fIsrc_y\fP\^; +.br + int \fIdest_x\fP\^, \fIdest_y\fP\^; +.br + unsigned int \fIwidth\fP\^, \fIheight\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fId\fP 1i +Specifies the drawable. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fIimage\fP 1i +Specifies the image you want combined with the rectangle. +.IP \fIsrc_x\fP 1i +Specifies the offset in X from the left edge of the image defined +by the +.PN XImage +structure. +.IP \fIsrc_y\fP 1i +Specifies the offset in Y from the top edge of the image defined +by the +.PN XImage +structure. +.ds Dx , which are relative to the origin of the drawable \ +and are the coordinates of the subimage +.IP \fIdest_x\fP 1i +.br +.ns +.IP \fIdest_y\fP 1i +Specify the x and y coordinates\*(Dx. +.ds Wh \ of the subimage, which define the dimensions of the rectangle +.IP \fIwidth\fP 1i +.br +.ns +.IP \fIheight\fP 1i +Specify the width and height\*(Wh. +.LP +.eM +The +.PN XPutImage +function +combines an image with a rectangle of the specified drawable. +The section of the image defined by the src_x, src_y, width, and height +arguments is drawn on the specified part of the drawable. +If +.PN XYBitmap +format is used, the depth of the image must be one, +or a +.PN BadMatch +error results. +The foreground pixel in the GC defines the source for the one bits in the image, +and the background pixel defines the source for the zero bits. +For +.PN XYPixmap +and +.PN ZPixmap , +the depth of the image must match the depth of the drawable, +or a +.PN BadMatch +error results. +.LP +If the characteristics of the image (for example, byte_order and bitmap_unit) +differ from what the server requires, +.PN XPutImage +automatically makes the appropriate +conversions. +.LP +This function uses these GC components: +function, plane-mask, subwindow-mode, clip-x-origin, clip-y-origin, +and clip-mask. +It also uses these GC mode-dependent components: +foreground and background. +.LP +.PN XPutImage +can generate +.PN BadDrawable , +.PN BadGC , +.PN BadMatch , +and +.PN BadValue +errors. +.LP +.sp +To return the contents of a rectangle in a given drawable on the display, +use +.PN XGetImage . +This function specifically supports rudimentary screen dumps. +.IN "XGetImage" "" "@DEF@" +.sM +.FD 0 +XImage *XGetImage\^(\^\fIdisplay\fP, \fId\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIplane_mask\fP, \fIformat\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fId\fP\^; +.br + int \fIx\fP\^, \fIy\fP\^; +.br + unsigned int \fIwidth\fP\^, \fIheight\fP\^; +.br + unsigned long \fIplane_mask\fP\^; +.br + int \fIformat\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fId\fP 1i +Specifies the drawable. +.ds Xy , which are relative to the origin of the drawable \ +and define the upper-left corner of the rectangle +.IP \fIx\fP 1i +.br +.ns +.IP \fIy\fP 1i +Specify the x and y coordinates\*(Xy. +.ds Wh \ of the subimage, which define the dimensions of the rectangle +.IP \fIwidth\fP 1i +.br +.ns +.IP \fIheight\fP 1i +Specify the width and height\*(Wh. +.IP \fIplane_mask\fP 1i +Specifies the plane mask. +.\" *** JIM: NEED MORE INFO FOR THIS. *** +.IP \fIformat\fP 1i +Specifies the format for the image. +You can pass +.PN XYPixmap +or +.PN ZPixmap . +.LP +.eM +The +.PN XGetImage +function returns a pointer to an +.PN XImage +structure. +This structure provides you with the contents of the specified rectangle of +the drawable in the format you specify. +If the format argument is +.PN XYPixmap , +the image contains only the bit planes you passed to the plane_mask argument. +If the plane_mask argument only requests a subset of the planes of the +display, the depth of the returned image will be the number of planes +requested. +If the format argument is +.PN ZPixmap , +.PN XGetImage +returns as zero the bits in all planes not +specified in the plane_mask argument. +The function performs no range checking on the values in plane_mask and ignores +extraneous bits. +.LP +.PN XGetImage +returns the depth of the image to the depth member of the +.PN XImage +structure. +The depth of the image is as specified when the drawable was created, +except when getting a subset of the planes in +.PN XYPixmap +format, when the depth is given by the number of bits set to 1 in plane_mask. +.LP +If the drawable is a pixmap, +the given rectangle must be wholly contained within the pixmap, +or a +.PN BadMatch +error results. +If the drawable is a window, +the window must be viewable, +and it must be the case that if there were no inferiors or overlapping windows, +the specified rectangle of the window would be fully visible on the screen +and wholly contained within the outside edges of the window, +or a +.PN BadMatch +error results. +Note that the borders of the window can be included and read with +this request. +If the window has backing-store, the backing-store contents are +returned for regions of the window that are obscured by noninferior +windows. +If the window does not have backing-store, +the returned contents of such obscured regions are undefined. +The returned contents of visible regions of inferiors +of a different depth than the specified window's depth are also undefined. +The pointer cursor image is not included in the returned contents. +If a problem occurs, +.PN XGetImage +returns NULL. +.LP +.PN XGetImage +can generate +.PN BadDrawable , +.PN BadMatch , +and +.PN BadValue +errors. +.sp +.LP +To copy the contents of a rectangle on the display +to a location within a preexisting image structure, use +.PN XGetSubImage . +.IN "XGetSubImage" "" "@DEF@" +.sM +.FD 0 +XImage *XGetSubImage\^(\^\fIdisplay\fP, \fId\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIplane_mask\fP, \fIformat\fP\^, \fIdest_image\fP\^, \fIdest_x\fP\^, +.br + \fIdest_y\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fId\fP\^; +.br + int \fIx\fP\^, \fIy\fP\^; +.br + unsigned int \fIwidth\fP\^, \fIheight\fP\^; +.br + unsigned long \fIplane_mask\fP\^; +.br + int \fIformat\fP\^; +.br + XImage *\fIdest_image\fP\^; +.br + int \fIdest_x\fP\^, \fIdest_y\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fId\fP 1i +Specifies the drawable. +.ds Xy , which are relative to the origin of the drawable \ +and define the upper-left corner of the rectangle +.IP \fIx\fP 1i +.br +.ns +.IP \fIy\fP 1i +Specify the x and y coordinates\*(Xy. +.ds Wh \ of the subimage, which define the dimensions of the rectangle +.IP \fIwidth\fP 1i +.br +.ns +.IP \fIheight\fP 1i +Specify the width and height\*(Wh. +.IP \fIplane_mask\fP 1i +Specifies the plane mask. +.\" *** JIM: NEED MORE INFO FOR THIS. *** +.IP \fIformat\fP 1i +Specifies the format for the image. +You can pass +.PN XYPixmap +or +.PN ZPixmap . +.IP \fIdest_image\fP 1i +Specifies the destination image. +.ds Dx , which are relative to the origin of the destination rectangle, \ +specify its upper-left corner, and determine where the subimage \ +is placed in the destination image +.IP \fIdest_x\fP 1i +.br +.ns +.IP \fIdest_y\fP 1i +Specify the x and y coordinates\*(Dx. +.LP +.eM +The +.PN XGetSubImage +function updates dest_image with the specified subimage in the same manner as +.PN XGetImage . +If the format argument is +.PN XYPixmap , +the image contains only the bit planes you passed to the plane_mask argument. +If the format argument is +.PN ZPixmap , +.PN XGetSubImage +returns as zero the bits in all planes not +specified in the plane_mask argument. +The function performs no range checking on the values in plane_mask and ignores +extraneous bits. +As a convenience, +.PN XGetSubImage +returns a pointer to the same +.PN XImage +structure specified by dest_image. +.LP +The depth of the destination +.PN XImage +structure must be the same as that of the drawable. +If the specified subimage does not fit at the specified location +on the destination image, the right and bottom edges are clipped. +If the drawable is a pixmap, +the given rectangle must be wholly contained within the pixmap, +or a +.PN BadMatch +error results. +If the drawable is a window, +the window must be viewable, +and it must be the case that if there were no inferiors or overlapping windows, +the specified rectangle of the window would be fully visible on the screen +and wholly contained within the outside edges of the window, +or a +.PN BadMatch +error results. +If the window has backing-store, +then the backing-store contents are returned for regions of the window +that are obscured by noninferior windows. +If the window does not have backing-store, +the returned contents of such obscured regions are undefined. +The returned contents of visible regions of inferiors +of a different depth than the specified window's depth are also undefined. +If a problem occurs, +.PN XGetSubImage +returns NULL. +.LP +.PN XGetSubImage +can generate +.PN BadDrawable , +.PN BadGC , +.PN BadMatch , +and +.PN BadValue +errors. +.bp diff --git a/libX11/specs/libX11/CH09 b/libX11/specs/libX11/CH09 new file mode 100644 index 000000000..2b79d3880 --- /dev/null +++ b/libX11/specs/libX11/CH09 @@ -0,0 +1,1290 @@ +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996, 2002 The Open Group +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be included +.\" in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR +.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +.\" OTHER DEALINGS IN THE SOFTWARE. +.\" +.\" Except as contained in this notice, the name of The Open Group shall +.\" not be used in advertising or otherwise to promote the sale, use or +.\" other dealings in this Software without prior written authorization +.\" from The Open Group. +.\" +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by +.\" Digital Equipment Corporation +.\" +.\" Portions Copyright \(co 1990, 1991 by +.\" Tektronix, Inc. +.\" +.\" Permission to use, copy, modify and distribute this documentation for +.\" any purpose and without fee is hereby granted, provided that the above +.\" copyright notice appears in all copies and that both that copyright notice +.\" and this permission notice appear in all copies, and that the names of +.\" Digital and Tektronix not be used in in advertising or publicity pertaining +.\" to this documentation without specific, written prior permission. +.\" Digital and Tektronix makes no representations about the suitability +.\" of this documentation for any purpose. +.\" It is provided ``as is'' without express or implied warranty. +.\" +\& +.sp 1 +.ce 3 +\s+1\fBChapter 9\fP\s-1 + +\s+1\fBWindow and Session Manager Functions\fP\s-1 +.sp 2 +.nr H1 9 +.nr H2 0 +.nr H3 0 +.nr H4 0 +.nr H5 0 +.na +.LP +.XS +Chapter 9: Window and Session Manager Functions +.XE +Although it is difficult to categorize functions as exclusively +for an application, a window manager, or a session manager, +the functions in this chapter are most often used by window managers +and session managers. +It is not expected that these functions will be used by most +application programs. +Xlib provides management functions to: +.IP \(bu 5 +Change the parent of a window +.IP \(bu 5 +Control the lifetime of a window +.IP \(bu 5 +Manage installed colormaps +.IP \(bu 5 +Set and retrieve the font search path +.IP \(bu 5 +Grab the server +.IP \(bu 5 +Kill a client +.IP \(bu 5 +Control the screen saver +.IP \(bu 5 +Control host access +.NH 2 +Changing the Parent of a Window +.XS +\*(SN Changing the Parent of a Window +.XE +.LP +To change a window's parent to another window on the same screen, use +.PN XReparentWindow . +There is no way to move a window between screens. +.IN "XReparentWindow" "" "@DEF@" +.sM +.FD 0 +XReparentWindow\^(\^\fIdisplay\fP, \fIw\fP\^, \fIparent\fP\^, \fIx\fP\^, \fIy\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + Window \fIparent\fP\^; +.br + int \fIx\fP\^, \fIy\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIparent\fP 1i +Specifies the parent window. +.ds Xy \ of the position in the new parent window +.IP \fIx\fP 1i +.br +.ns +.IP \fIy\fP 1i +Specify the x and y coordinates\*(Xy. +.LP +.eM +If the specified window is mapped, +.PN XReparentWindow +automatically performs an +.PN UnmapWindow +request on it, removes it from its current position in the hierarchy, +and inserts it as the child of the specified parent. +The window is placed in the stacking order on top with respect to +sibling windows. +.LP +After reparenting the specified window, +.PN XReparentWindow +causes the X server to generate a +.PN ReparentNotify +event. +The override_redirect member returned in this event is +set to the window's corresponding attribute. +Window manager clients usually should ignore this window if this member +is set to +.PN True . +Finally, if the specified window was originally mapped, +the X server automatically performs a +.PN MapWindow +request on it. +.LP +The X server performs normal exposure processing on formerly obscured +windows. +The X server might not generate +.PN Expose +events for regions from the initial +.PN UnmapWindow +request that are immediately obscured by the final +.PN MapWindow +request. +A +.PN BadMatch +error results if: +.IP \(bu 5 +The new parent window is not on the same screen as +the old parent window. +.IP \(bu 5 +The new parent window is the specified window or an inferior of the +specified window. +.IP \(bu 5 +The new parent is +.PN InputOnly , +and the window is not. +.IP \(bu 5 +The specified window has a +.PN ParentRelative +background, and the new parent window is not the same depth as the +specified window. +.LP +.PN XReparentWindow +can generate +.PN BadMatch +and +.PN BadWindow +errors. +.NH 2 +Controlling the Lifetime of a Window +.XS +\*(SN Controlling the Lifetime of a Window +.XE +.LP +The save-set of a client is a list of other clients' windows that, +if they are inferiors of one of the client's windows at connection close, +should not be destroyed and should be remapped if they are unmapped. +For further information about close-connection processing, +see section 2.6. +To allow an application's window to survive when a window manager that +has reparented a window fails, +Xlib provides the save-set functions that you can +use to control the longevity of subwindows +that are normally destroyed when the parent is destroyed. +For example, a window manager that wants to add decoration +to a window by adding a frame might reparent an application's +window. +When the frame is destroyed, +the application's window should not be destroyed +but be returned to its previous place in the window hierarchy. +.LP +The X server automatically removes windows from the save-set +when they are destroyed. +.LP +.sp +To add or remove a window from the client's save-set, use +.PN XChangeSaveSet . +.IN "XChangeSaveSet" "" "@DEF@" +.sM +.FD 0 +XChangeSaveSet\^(\^\fIdisplay\fP, \fIw\fP\^, \fIchange_mode\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + int \fIchange_mode\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.ds Wi that you want to add to or delete from the client's save-set +.IP \fIw\fP 1i +Specifies the window \*(Wi. +.IP \fIchange_mode\fP 1i +Specifies the mode. +You can pass +.PN SetModeInsert +or +.PN SetModeDelete . +.LP +.eM +Depending on the specified mode, +.PN XChangeSaveSet +either inserts or deletes the specified window from the client's save-set. +The specified window must have been created by some other client, +or a +.PN BadMatch +error results. +.LP +.PN XChangeSaveSet +can generate +.PN BadMatch , +.PN BadValue , +and +.PN BadWindow +errors. +.LP +.sp +To add a window to the client's save-set, use +.PN XAddToSaveSet . +.IN "XAddToSaveSet" "" "@DEF@" +.sM +.FD 0 +XAddToSaveSet\^(\^\fIdisplay\fP, \fIw\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.ds Wi that you want to add to the client's save-set +.IP \fIw\fP 1i +Specifies the window \*(Wi. +.LP +.eM +The +.PN XAddToSaveSet +function adds the specified window to the client's save-set. +The specified window must have been created by some other client, +or a +.PN BadMatch +error results. +.LP +.PN XAddToSaveSet +can generate +.PN BadMatch +and +.PN BadWindow +errors. +.LP +.sp +To remove a window from the client's save-set, use +.PN XRemoveFromSaveSet . +.IN "XRemoveFromSaveSet" "" "@DEF@" +.sM +.FD 0 +XRemoveFromSaveSet\^(\^\fIdisplay\fP, \fIw\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.ds Wi that you want to delete from the client's save-set +.IP \fIw\fP 1i +Specifies the window \*(Wi. +.LP +.eM +The +.PN XRemoveFromSaveSet +function removes the specified window from the client's save-set. +The specified window must have been created by some other client, +or a +.PN BadMatch +error results. +.LP +.PN XRemoveFromSaveSet +can generate +.PN BadMatch +and +.PN BadWindow +errors. +.NH 2 +Managing Installed Colormaps +.XS +\*(SN Managing Installed Colormaps +.XE +.LP +The X server maintains a list of installed colormaps. +Windows using these colormaps are guaranteed to display with +correct colors; windows using other colormaps may or may not display +with correct colors. +Xlib provides functions that you can use to install a colormap, +uninstall a colormap, and obtain a list of installed colormaps. +.LP +At any time, +there is a subset of the installed maps that is viewed as an ordered list +and is called the required list. +The length of the required list is at most M, +where M is the minimum number of installed colormaps specified for the screen +in the connection setup. +The required list is maintained as follows. +When a colormap is specified to +.PN XInstallColormap , +it is added to the head of the list; +the list is truncated at the tail, if necessary, to keep its length to +at most M. +When a colormap is specified to +.PN XUninstallColormap +and it is in the required list, +it is removed from the list. +A colormap is not added to the required list when it is implicitly installed +by the X server, +and the X server cannot implicitly uninstall a colormap that is in the +required list. +.LP +.sp +To install a colormap, use +.PN XInstallColormap . +.IN "XInstallColormap" "" "@DEF@" +.sM +.FD 0 +XInstallColormap\^(\^\fIdisplay\fP, \fIcolormap\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Colormap \fIcolormap\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIcolormap\fP 1i +Specifies the colormap. +.LP +.eM +The +.PN XInstallColormap +function installs the specified colormap for its associated screen. +All windows associated with this colormap immediately display with +true colors. +You associated the windows with this colormap when you created them by calling +.PN XCreateWindow , +.PN XCreateSimpleWindow , +.PN XChangeWindowAttributes , +or +.PN XSetWindowColormap . +.LP +If the specified colormap is not already an installed colormap, +the X server generates a +.PN ColormapNotify +event on each window that has that colormap. +In addition, for every other colormap that is installed as +a result of a call to +.PN XInstallColormap , +the X server generates a +.PN ColormapNotify +event on each window that has that colormap. +.LP +.PN XInstallColormap +can generate a +.PN BadColor +error. +.LP +.sp +To uninstall a colormap, use +.PN XUninstallColormap . +.IN "XUninstallColormap" "" "@DEF@" +.sM +.FD 0 +XUninstallColormap\^(\^\fIdisplay\fP, \fIcolormap\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Colormap \fIcolormap\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIcolormap\fP 1i +Specifies the colormap. +.LP +.eM +The +.PN XUninstallColormap +function removes the specified colormap from the required +list for its screen. +As a result, +the specified colormap might be uninstalled, +and the X server might implicitly install or uninstall additional colormaps. +Which colormaps get installed or uninstalled is server dependent +except that the required list must remain installed. +.LP +If the specified colormap becomes uninstalled, +the X server generates a +.PN ColormapNotify +event on each window that has that colormap. +In addition, for every other colormap that is installed or uninstalled as a +result of a call to +.PN XUninstallColormap , +the X server generates a +.PN ColormapNotify +event on each window that has that colormap. +.LP +.PN XUninstallColormap +can generate a +.PN BadColor +error. +.LP +.sp +To obtain a list of the currently installed colormaps for a given screen, use +.PN XListInstalledColormaps . +.IN "XListInstalledColormaps" "" "@DEF@" +.sM +.FD 0 +Colormap *XListInstalledColormaps\^(\^\fIdisplay\fP, \fIw\fP, \fInum_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + int *\fInum_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.ds Wi that determines the screen +.IP \fIw\fP 1i +Specifies the window \*(Wi. +.IP \fInum_return\fP 1i +Returns the number of currently installed colormaps. +.LP +.eM +The +.PN XListInstalledColormaps +function returns a list of the currently installed colormaps for the screen +of the specified window. +The order of the colormaps in the list is not significant +and is no explicit indication of the required list. +When the allocated list is no longer needed, +free it by using +.PN XFree . +.LP +.PN XListInstalledColormaps +can generate a +.PN BadWindow +error. +.NH 2 +Setting and Retrieving the Font Search Path +.XS +\*(SN Setting and Retrieving the Font Search Path +.XE +.LP +The set of fonts available from a server depends on a font +search path. Xlib provides functions to set and retrieve the +search path for a server. +.LP +.sp +To set the font search path, use +.PN XSetFontPath . +.IN "XSetFontPath" "" "@DEF@" +.sM +.FD 0 +XSetFontPath\^(\^\fIdisplay\fP, \fIdirectories\fP\^, \fIndirs\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + char **\fIdirectories\fP\^; +.br + int \fIndirs\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIdirectories\fP 1i +Specifies the directory path used to look for a font. +Setting the path to the empty list restores the default path defined +for the X server. +.IP \fIndirs\fP 1i +Specifies the number of directories in the path. +.LP +.eM +The +.PN XSetFontPath +function defines the directory search path for font lookup. +There is only one search path per X server, not one per client. +The encoding and interpretation of the strings are implementation-dependent, +but typically they specify directories or font servers to be searched +in the order listed. +An X server is permitted to cache font information internally; +for example, it might cache an entire font from a file and not +check on subsequent opens of that font to see if the underlying +font file has changed. +However, +when the font path is changed, +the X server is guaranteed to flush all cached information about fonts +for which there currently are no explicit resource IDs allocated. +The meaning of an error from this request is implementation-dependent. +.LP +.PN XSetFontPath +can generate a +.PN BadValue +error. +.LP +.sp +To get the current font search path, use +.PN XGetFontPath . +.IN "XGetFontPath" "" "@DEF@" +.sM +.FD 0 +char **XGetFontPath\^(\^\fIdisplay\fP, \fInpaths_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int *\fInpaths_return\fP\^; + +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fInpaths_return\fP 1i +Returns the number of strings in the font path array. +.LP +.eM +The +.PN XGetFontPath +function allocates and returns an array of strings containing the search path. +The contents of these strings are implementation-dependent +and are not intended to be interpreted by client applications. +When it is no longer needed, +the data in the font path should be freed by using +.PN XFreeFontPath . +.LP +.sp +To free data returned by +.PN XGetFontPath , +use +.PN XFreeFontPath . +.IN "XFreeFontPath" "" "@DEF@" +.sM +.FD 0 +XFreeFontPath\^(\^\fIlist\fP\^) +.br + char **\fIlist\fP\^; + +.FN +.IP \fIlist\fP 1i +Specifies the array of strings you want to free. +.LP +.eM +The +.PN XFreeFontPath +function +frees the data allocated by +.PN XGetFontPath . +.NH 2 +Grabbing the Server +.XS +\*(SN Grabbing the Server +.XE +.LP +Xlib provides functions that you can use to grab and ungrab the server. +These functions can be used to control processing of output on other +connections by the window system server. +While the server is grabbed, +no processing of requests or close downs on any other connection will occur. +A client closing its connection automatically ungrabs the server. +.IN "Menus" +.IN "Window" "managers" +Although grabbing the server is highly discouraged, it is sometimes necessary. +.LP +.sp +To grab the server, use +.PN XGrabServer . +.IN "Server" "grabbing" +.IN "Grabbing" "server" +.IN "XGrabServer" "" "@DEF@" +.sM +.FD 0 +XGrabServer\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +The +.PN XGrabServer +function disables processing of requests and close downs on all other +connections than the one this request arrived on. +You should not grab the X server any more than is absolutely necessary. +.LP +.sp +To ungrab the server, use +.PN XUngrabServer . +.IN "XUngrabServer" "" "@DEF@" +.sM +.FD 0 +XUngrabServer\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +The +.PN XUngrabServer +function restarts processing of requests and close downs on other connections. +You should avoid grabbing the X server as much as possible. +.NH 2 +Killing Clients +.XS +\*(SN Killing Clients +.XE +.LP +Xlib provides a function to cause the connection to +a client to be closed and its resources to be destroyed. +To destroy a client, use +.PN XKillClient . +.IN "XKillClient" "" "@DEF@" +.sM +.FD 0 +XKillClient\^(\^\fIdisplay\fP, \fIresource\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XID \fIresource\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIresource\fP 1i +Specifies any resource associated with the client that you want to destroy or +.PN AllTemporary . +.LP +.eM +The +.PN XKillClient +function +forces a close down of the client +that created the resource +if a valid resource is specified. +If the client has already terminated in +either +.PN RetainPermanent +or +.PN RetainTemporary +mode, all of the client's +resources are destroyed. +If +.PN AllTemporary +is specified, the resources of all clients that have terminated in +.PN RetainTemporary +are destroyed (see section 2.5). +This permits implementation of window manager facilities that aid debugging. +A client can set its close-down mode to +.PN RetainTemporary . +If the client then crashes, +its windows would not be destroyed. +The programmer can then inspect the application's window tree +and use the window manager to destroy the zombie windows. +.LP +.PN XKillClient +can generate a +.PN BadValue +error. +.NH 2 +Controlling the Screen Saver +.XS +\*(SN Controlling the Screen Saver +.XE +.LP +Xlib provides functions that you can use to set or reset the mode +of the screen saver, to force or activate the screen saver, +or to obtain the current screen saver values. +.LP +.sp +To set the screen saver mode, use +.PN XSetScreenSaver . +.IN "XSetScreenSaver" "" "@DEF@" +.sM +.FD 0 +XSetScreenSaver\^(\^\fIdisplay\fP, \fItimeout\fP\^, \fIinterval\fP\^, \fIprefer_blanking\fP\^, \fIallow_exposures\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fItimeout\fP\^, \fIinterval\fP\^; +.br + int \fIprefer_blanking\fP\^; +.br + int \fIallow_exposures\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fItimeout\fP 1i +Specifies the timeout, in seconds, until the screen saver turns on. +.IP \fIinterval\fP 1i +Specifies the interval, in seconds, between screen saver alterations. +.IP \fIprefer_blanking\fP 1i +Specifies how to enable screen blanking. +You can pass +.PN DontPreferBlanking , +.PN PreferBlanking , +or +.PN DefaultBlanking . +.IP \fIallow_exposures\fP 1i +Specifies the screen save control values. +You can pass +.PN DontAllowExposures , +.PN AllowExposures , +or +.PN DefaultExposures . +.LP +.eM +Timeout and interval are specified in seconds. +A timeout of 0 disables the screen saver +(but an activated screen saver is not deactivated), +and a timeout of \-1 restores the default. +Other negative values generate a +.PN BadValue +error. +If the timeout value is nonzero, +.PN XSetScreenSaver +enables the screen saver. +An interval of 0 disables the random-pattern motion. +If no input from devices (keyboard, mouse, and so on) is generated +for the specified number of timeout seconds once the screen saver is enabled, +the screen saver is activated. +.LP +For each screen, +if blanking is preferred and the hardware supports video blanking, +the screen simply goes blank. +Otherwise, if either exposures are allowed or the screen can be regenerated +without sending +.PN Expose +events to clients, +the screen is tiled with the root window background tile randomly +re-origined each interval seconds. +Otherwise, the screens' state do not change, +and the screen saver is not activated. +The screen saver is deactivated, +and all screen states are restored at the next +keyboard or pointer input or at the next call to +.PN XForceScreenSaver +with mode +.PN ScreenSaverReset . +.LP +If the server-dependent screen saver method supports periodic change, +the interval argument serves as a hint about how long the change period +should be, and zero hints that no periodic change should be made. +Examples of ways to change the screen include scrambling the colormap +periodically, moving an icon image around the screen periodically, or tiling +the screen with the root window background tile, randomly re-origined +periodically. +.LP +.PN XSetScreenSaver +can generate a +.PN BadValue +error. +.LP +.sp +To force the screen saver on or off, use +.PN XForceScreenSaver . +.IN "XForceScreenSaver" "" "@DEF@" +.sM +.FD 0 +XForceScreenSaver\^(\^\fIdisplay\fP\^, \fImode\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fImode\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fImode\fP 1i +Specifies the mode that is to be applied. +You can pass +.PN ScreenSaverActive +or +.PN ScreenSaverReset . +.LP +.eM +If the specified mode is +.PN ScreenSaverActive +and the screen saver currently is deactivated, +.PN XForceScreenSaver +activates the screen saver even if the screen saver had been disabled +with a timeout of zero. +If the specified mode is +.PN ScreenSaverReset +and the screen saver currently is enabled, +.PN XForceScreenSaver +deactivates the screen saver if it was activated, +and the activation timer is reset to its initial state +(as if device input had been received). +.LP +.PN XForceScreenSaver +can generate a +.PN BadValue +error. +.LP +.sp +To activate the screen saver, use +.PN XActivateScreenSaver . +.IN "XActivateScreenSaver" "" "@DEF@" +.sM +.FD 0 +XActivateScreenSaver\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +.sp +To reset the screen saver, use +.PN XResetScreenSaver . +.IN "XResetScreenSaver" "" "@DEF@" +.sM +.FD 0 +XResetScreenSaver\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +.sp +To get the current screen saver values, use +.PN XGetScreenSaver . +.IN "XGetScreenSaver" "" "@DEF@" +.sM +.FD 0 +XGetScreenSaver\^(\^\fIdisplay\fP, \fItimeout_return\fP\^, \fIinterval_return\fP\^, \fIprefer_blanking_return\fP\^, +.br + \fIallow_exposures_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int *\fItimeout_return\fP\^, *\fIinterval_return\fP\^; +.br + int *\fIprefer_blanking_return\fP\^; +.br + int *\fIallow_exposures_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fItimeout_return\fP 1i +Returns the timeout, in seconds, until the screen saver turns on. +.IP \fIinterval_return\fP 1i +Returns the interval between screen saver invocations. +.IP \fIprefer_blanking_return\fP 1i +Returns the current screen blanking preference +.Pn ( DontPreferBlanking , +.PN PreferBlanking , +or +.PN DefaultBlanking ). +.IP \fIallow_exposures_return\fP 1i +Returns the current screen save control value +.Pn ( DontAllowExposures , +.PN AllowExposures , +or +.PN DefaultExposures ). +.LP +.eM +.NH 2 +Controlling Host Access +.XS +\*(SN Controlling Host Access +.XE +.LP +This section discusses how to: +.IP \(bu 5 +Add, get, or remove hosts from the access control list +.IP \(bu 5 +Change, enable, or disable access +.LP +.IN "Access control list" +.IN "Authentication" +X does not provide any protection on a per-window basis. +If you find out the resource ID of a resource, you can manipulate it. +To provide some minimal level of protection, however, +connections are permitted only from machines you trust. +This is adequate on single-user workstations but obviously +breaks down on timesharing machines. +Although provisions exist in the X protocol for proper connection +authentication, the lack of a standard authentication server +leaves host-level access control as the only common mechanism. +.LP +.IN "Default Protection" +The initial set of hosts allowed to open connections typically consists of: +.IP \(bu 5 +The host the window system is running on. +.IP \(bu 5 +On POSIX-conformant systems, each host listed in the +.PN /etc/X?.hosts +file. +The ? indicates the number of the +display. +.IN "Files" "/etc/X?.hosts" +This file should consist of host names separated by newlines. +DECnet nodes must terminate in :: to distinguish them from Internet hosts. +.LP +If a host is not in the access control list when the access control +mechanism is enabled and if the host attempts to establish a connection, +the server refuses the connection. +To change the access list, +the client must reside on the same host as the server and/or must +have been granted permission in the initial authorization at connection +setup. +.LP +Servers also can implement other access control policies in addition to +or in place of this host access facility. +For further information about other access control implementations, +see ``X Window System Protocol.'' +.NH 3 +Adding, Getting, or Removing Hosts +.XS +\*(SN Adding, Getting, or Removing Hosts +.XE +.LP +Xlib provides functions that you can use to add, get, or remove hosts +from the access control list. +All the host access control functions use the +.PN XHostAddress +structure, which contains: +.LP +.IN "XHostAddress" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + int family; /* for example FamilyInternet */ + int length; /* length of address, in bytes */ + char *address; /* pointer to where to find the address */ +} XHostAddress; +.De +.LP +.eM +The family member specifies which protocol address family to use +(for example, TCP/IP or DECnet) and can be +.PN FamilyInternet , +.PN FamilyInternet6 , +.PN FamilyServerInterpreted , +.PN FamilyDECnet , +or +.PN FamilyChaos . +The length member specifies the length of the address in bytes. +The address member specifies a pointer to the address. +.LP +For TCP/IP, the address should be in network byte order. +For IP version 4 addresses, the family should be FamilyInternet +and the length should be 4 bytes. For IP version 6 addresses, the +family should be FamilyInternet6 and the length should be 16 bytes. +.LP +For the DECnet family, +the server performs no automatic swapping on the address bytes. +A Phase IV address is 2 bytes long. +The first byte contains the least significant 8 bits of the node number. +The second byte contains the most significant 2 bits of the +node number in the least significant 2 bits of the byte +and the area in the most significant 6 bits of the byte. +.LP +For the ServerInterpreted family, the length is ignored and the address +member is a pointer to a +.PN XServerInterpretedAddress +structure, which contains: +.LP +.IN "XServerInterpretedAddress" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + int typelength; /* length of type string, in bytes */ + int valuelength;/* length of value string, in bytes */ + char *type; /* pointer to where to find the type string */ + char *value; /* pointer to where to find the address */ +} XServerInterpretedAddress; +.De +.LP +.eM +The type and value members point to strings representing the type and value of +the server interpreted entry. These strings may not be NULL-terminated so care +should be used when accessing them. The typelength and valuelength members +specify the length in byte of the type and value strings. +.LP +.sp +To add a single host, use +.PN XAddHost . +.IN "XAddHost" "" "@DEF@" +.sM +.FD 0 +XAddHost\^(\^\fIdisplay\fP, \fIhost\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XHostAddress *\fIhost\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.ds Ho added +.IP \fIhost\fP 1i +Specifies the host that is to be \*(Ho. +.LP +.eM +The +.PN XAddHost +function adds the specified host to the access control list for that display. +The server must be on the same host as the client issuing the command, or a +.PN BadAccess +error results. +.LP +.PN XAddHost +can generate +.PN BadAccess +and +.PN BadValue +errors. +.LP +.sp +To add multiple hosts at one time, use +.PN XAddHosts . +.IN "XAddHosts" "" "@DEF@" +.sM +.FD 0 +XAddHosts\^(\^\fIdisplay\fP, \fIhosts\fP, \fInum_hosts\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XHostAddress *\fIhosts\fP\^; +.br + int \fInum_hosts\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.ds Ho added +.IP \fIhosts\fP 1i +Specifies each host that is to be \*(Ho. +.IP \fInum_hosts\fP 1i +Specifies the number of hosts. +.LP +.eM +The +.PN XAddHosts +function adds each specified host to the access control list for that display. +The server must be on the same host as the client issuing the command, or a +.PN BadAccess +error results. +.LP +.PN XAddHosts +can generate +.PN BadAccess +and +.PN BadValue +errors. +.LP +.sp +To obtain a host list, use +.PN XListHosts . +.IN "XListHosts" "" "@DEF@" +.sM +.FD 0 +XHostAddress *XListHosts\^(\^\fIdisplay\fP, \fInhosts_return\fP, \fIstate_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int *\fInhosts_return\fP\^; +.br + Bool *\fIstate_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fInhosts_return\fP 1i +Returns the number of hosts currently in the access control list. +.IP \fIstate_return\fP 1i +Returns the state of the access control. +.LP +.eM +The +.PN XListHosts +function returns the current access control list as well as whether the use +of the list at connection setup was enabled or disabled. +.PN XListHosts +allows a program to find out what machines can make connections. +It also returns a pointer to a list of host structures that +were allocated by the function. +When no longer needed, +this memory should be freed by calling +.PN XFree . +.LP +.sp +To remove a single host, use +.PN XRemoveHost . +.IN "XRemoveHost" "" "@DEF@" +.sM +.FD 0 +XRemoveHost\^(\^\fIdisplay\fP, \fIhost\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XHostAddress *\fIhost\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.ds Ho removed +.IP \fIhost\fP 1i +Specifies the host that is to be \*(Ho. +.LP +.eM +The +.PN XRemoveHost +function removes the specified host from the access control list +for that display. +The server must be on the same host as the client process, or a +.PN BadAccess +error results. +If you remove your machine from the access list, +you can no longer connect to that server, +and this operation cannot be reversed unless you reset the server. +.LP +.PN XRemoveHost +can generate +.PN BadAccess +and +.PN BadValue +errors. +.LP +.sp +To remove multiple hosts at one time, use +.PN XRemoveHosts . +.IN "XRemoveHosts" "" "@DEF@" +.sM +.FD 0 +XRemoveHosts\^(\^\fIdisplay\fP, \fIhosts\fP, \fInum_hosts\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XHostAddress *\fIhosts\fP\^; +.br + int \fInum_hosts\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.ds Ho removed +.IP \fIhosts\fP 1i +Specifies each host that is to be \*(Ho. +.IP \fInum_hosts\fP 1i +Specifies the number of hosts. +.LP +.eM +The +.PN XRemoveHosts +function removes each specified host from the access control list for that +display. +The X server must be on the same host as the client process, or a +.PN BadAccess +error results. +If you remove your machine from the access list, +you can no longer connect to that server, +and this operation cannot be reversed unless you reset the server. +.LP +.PN XRemoveHosts +can generate +.PN BadAccess +and +.PN BadValue +errors. +.NH 3 +Changing, Enabling, or Disabling Access Control +.XS +\*(SN Changing, Enabling, or Disabling Access Control +.XE +.LP +Xlib provides functions that you can use to enable, disable, +or change access control. +.LP +For these functions to execute successfully, +the client application must reside on the same host as the X server +and/or have been given permission in the initial authorization +at connection setup. +.LP +.sp +To change access control, use +.PN XSetAccessControl . +.IN "XSetAccessControl" "" "@DEF@" +.sM +.FD 0 +XSetAccessControl\^(\^\fIdisplay\fP, \fImode\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fImode\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fImode\fP 1i +Specifies the mode. +You can pass +.PN EnableAccess +or +.PN DisableAccess . +.LP +.eM +The +.PN XSetAccessControl +function either enables or disables the use of the access control list +at each connection setup. +.LP +.PN XSetAccessControl +can generate +.PN BadAccess +and +.PN BadValue +errors. +.LP +.sp +To enable access control, use +.PN XEnableAccessControl . +.IN "XEnableAccessControl" "" "@DEF@" +.sM +.FD 0 +XEnableAccessControl\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +The +.PN XEnableAccessControl +function enables the use of the access control list at each connection setup. +.LP +.PN XEnableAccessControl +can generate a +.PN BadAccess +error. +.LP +.sp +To disable access control, use +.PN XDisableAccessControl . +.IN "XDisableAccessControl" "" "@DEF@" +.sM +.FD 0 +XDisableAccessControl\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +The +.PN XDisableAccessControl +function disables the use of the access control list at each connection setup. +.LP +.PN XDisableAccessControl +can generate a +.PN BadAccess +error. +.bp diff --git a/libX11/specs/libX11/CH10 b/libX11/specs/libX11/CH10 new file mode 100644 index 000000000..76502fb9e --- /dev/null +++ b/libX11/specs/libX11/CH10 @@ -0,0 +1,3886 @@ +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be included +.\" in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR +.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +.\" OTHER DEALINGS IN THE SOFTWARE. +.\" +.\" Except as contained in this notice, the name of the X Consortium shall +.\" not be used in advertising or otherwise to promote the sale, use or +.\" other dealings in this Software without prior written authorization +.\" from the X Consortium. +.\" +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by +.\" Digital Equipment Corporation +.\" +.\" Portions Copyright \(co 1990, 1991 by +.\" Tektronix, Inc. +.\" +.\" Permission to use, copy, modify and distribute this documentation for +.\" any purpose and without fee is hereby granted, provided that the above +.\" copyright notice appears in all copies and that both that copyright notice +.\" and this permission notice appear in all copies, and that the names of +.\" Digital and Tektronix not be used in in advertising or publicity pertaining +.\" to this documentation without specific, written prior permission. +.\" Digital and Tektronix makes no representations about the suitability +.\" of this documentation for any purpose. +.\" It is provided ``as is'' without express or implied warranty. +.\" +\& +.sp 1 +.ce 3 +\s+1\fBChapter 10\fP\s-1 + +\s+1\fBEvents\fP\s-1 +.sp 2 +.nr H1 10 +.nr H2 0 +.nr H3 0 +.nr H4 0 +.nr H5 0 +.na +.LP +.XS +Chapter 10: Events +.XE +A client application communicates with the X server through the connection you +establish with the +.PN XOpenDisplay +.IN "XOpenDisplay" +function. +A client application sends requests to the X server over this connection. +.IN "Requests" "" "@DEF@" +These requests are made by the Xlib functions that are +called in the client application. +Many Xlib functions cause the X server to generate events, +and the user's typing or moving the pointer can generate events asynchronously. +The X server returns events to the client on the same connection. +.LP +This chapter discusses the following topics associated with events: +.IP \(bu 5 +Event types +.IP \(bu 5 +Event structures +.IP \(bu 5 +Event masks +.IP \(bu 5 +Event processing +.LP +Functions for handling events are dealt with in the next chapter. +.NH 2 +Event Types +.XS +\*(SN Event Types +.XE +.LP +.IN "Event" "types" +An event is data generated asynchronously by the X server as a result of some +device activity or as side effects of a request sent by an Xlib function. +.IN "Event" +Device-related events propagate from the source window to ancestor windows +until some client application has selected that event type +or until the event is explicitly discarded. +The X server generally sends an event to a client application +only if the client has specifically asked to be informed of that event type, +typically by setting the event-mask attribute of the window. +The mask can also be set when you create a window +or by changing the window's +event-mask. +You can also mask out events that would propagate to ancestor windows +by manipulating the +do-not-propagate mask of the window's attributes. +However, +.PN MappingNotify +events are always sent to all clients. +.IN "Input Control" +.IN "Output Control" +.LP +An event type describes a specific event generated by the X server. +For each event type, +a corresponding constant name is defined in +.hN X11/X.h , +which is used when referring to an event type. +.IN "Event" "categories" +The following table lists the event category +and its associated event type or types. +The processing associated with these events is discussed in section 10.5. +.LP +.\".CP T 1 +.\"Event Categories and Event Types +.LP +.TS H +lw(2.25i) lw(3.5i). +_ +.sp 6p +.B +Event Category Event Type +.sp 6p +_ +.sp 6p +.TH +.R +T{ +Keyboard events +T} T{ +.PN KeyPress , +.PN KeyRelease +T} +.sp 6p +T{ +Pointer events +T} T{ +.PN ButtonPress , +.PN ButtonRelease , +.PN MotionNotify +T} +.sp 6p +T{ +Window crossing events +T} T{ +.PN EnterNotify , +.PN LeaveNotify +T} +.sp 6p +T{ +Input focus events +T} T{ +.PN FocusIn , +.PN FocusOut +T} +.sp 6p +T{ +Keymap state notification event +T} T{ +.PN KeymapNotify +T} +.sp 6p +T{ +Exposure events +T} T{ +.PN Expose , +.PN GraphicsExpose , +.PN NoExpose +T} +.sp 6p +T{ +Structure control events +T} T{ +.PN CirculateRequest , +.PN ConfigureRequest , +.PN MapRequest , +.PN ResizeRequest +T} +.sp 6p +T{ +Window state notification events +T} T{ +.PN CirculateNotify , +.PN ConfigureNotify , +.PN CreateNotify , +.PN DestroyNotify , +.PN GravityNotify , +.PN MapNotify , +.PN MappingNotify , +.PN ReparentNotify , +.PN UnmapNotify , +.br +.PN VisibilityNotify +T} +.sp 6p +T{ +Colormap state notification event +T} T{ +.PN ColormapNotify +T} +.sp 6p +T{ +Client communication events +T} T{ +.PN ClientMessage , +.PN PropertyNotify , +.PN SelectionClear , +.PN SelectionNotify , +.PN SelectionRequest +T} +.sp 6p +_ +.TE +.\".LP +.\"Table 8-1 lists the event types and the Xlib functions that could cause +.\"the X server to generate that event type. +.\"The event types are listed alphabetically. +.\"Note that the error event is not listed in this table. +.\"For a list of the constants associated with an error event, see the Handling +.\"Errors section in this chapter. +.\".LP +.\".so eventtable +.NH 2 +Event Structures +.XS +\*(SN Event Structures +.XE +.LP +For each event type, +a corresponding structure is declared in +.hN X11/Xlib.h . +All the event structures have the following common members: +.LP +.IN "XAnyEvent" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + int type; + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window window; +} XAnyEvent; +.De +.LP +.eM +The type member is set to the event type constant name that uniquely identifies +it. +For example, when the X server reports a +.PN GraphicsExpose +event to a client application, it sends an +.PN XGraphicsExposeEvent +structure with the type member set to +.PN GraphicsExpose . +The display member is set to a pointer to the display the event was read on. +The send_event member is set to +.PN True +if the event came from a +.PN SendEvent +protocol request. +The serial member is set from the serial number reported in the protocol +but expanded from the 16-bit least-significant bits to a full 32-bit value. +The window member is set to the window that is most useful to toolkit +dispatchers. +.LP +The X server can send events at any time in the input stream. +Xlib stores any events received while waiting for a reply in an event queue +for later use. +Xlib also provides functions that allow you to check events +in the event queue (see section 11.3). +.LP +In addition to the individual structures declared for each event type, the +.PN XEvent +structure is a union of the individual structures declared for each event type. +Depending on the type, +you should access members of each event by using the +.PN XEvent +union. +.LP +.IN "XEvent" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef union _XEvent { + int type; /* must not be changed */ + XAnyEvent xany; + XKeyEvent xkey; + XButtonEvent xbutton; + XMotionEvent xmotion; + XCrossingEvent xcrossing; + XFocusChangeEvent xfocus; + XExposeEvent xexpose; + XGraphicsExposeEvent xgraphicsexpose; + XNoExposeEvent xnoexpose; + XVisibilityEvent xvisibility; + XCreateWindowEvent xcreatewindow; + XDestroyWindowEvent xdestroywindow; + XUnmapEvent xunmap; + XMapEvent xmap; + XMapRequestEvent xmaprequest; + XReparentEvent xreparent; + XConfigureEvent xconfigure; + XGravityEvent xgravity; + XResizeRequestEvent xresizerequest; + XConfigureRequestEvent xconfigurerequest; + XCirculateEvent xcirculate; + XCirculateRequestEvent xcirculaterequest; + XPropertyEvent xproperty; + XSelectionClearEvent xselectionclear; + XSelectionRequestEvent xselectionrequest; + XSelectionEvent xselection; + XColormapEvent xcolormap; + XClientMessageEvent xclient; + XMappingEvent xmapping; + XErrorEvent xerror; + XKeymapEvent xkeymap; + long pad[24]; +} XEvent; +.De +.LP +.eM +An +.PN XEvent +structure's first entry always is the type member, +which is set to the event type. +The second member always is the serial number of the protocol request +that generated the event. +The third member always is send_event, +which is a +.PN Bool +that indicates if the event was sent by a different client. +The fourth member always is a display, +which is the display that the event was read from. +Except for keymap events, +the fifth member always is a window, +which has been carefully selected to be useful to toolkit dispatchers. +To avoid breaking toolkits, +the order of these first five entries is not to change. +Most events also contain a time member, +which is the time at which an event occurred. +In addition, a pointer to the generic event must be cast before it +is used to access any other information in the structure. +.NH 2 +Event Masks +.XS +\*(SN Event Masks +.XE +.LP +.IN "Event mask" "" "@DEF@" +Clients select event reporting of most events relative to a window. +To do this, pass an event mask to an Xlib event-handling +function that takes an event_mask argument. +The bits of the event mask are defined in +.hN X11/X.h . +Each bit in the event mask maps to an event mask name, +which describes the event or events you want the X server to +return to a client application. +.LP +Unless the client has specifically asked for them, +most events are not reported to clients when they are generated. +Unless the client suppresses them by setting graphics-exposures in the GC to +.PN False , +.PN GraphicsExpose +and +.PN NoExpose +are reported by default as a result of +.PN XCopyPlane +and +.PN XCopyArea . +.PN SelectionClear , +.PN SelectionRequest , +.PN SelectionNotify , +or +.PN ClientMessage +cannot be masked. +Selection-related events are only sent to clients cooperating +with selections (see section 4.5). +When the keyboard or pointer mapping is changed, +.PN MappingNotify +is always sent to clients. +.LP +.\"Table 8-2 +The following table +lists the event mask constants you can pass to +the event_mask argument and +the circumstances in which you would want to specify the +event mask: +.LP +.\" .CP T 2 +.\"Event Mask Definitions +.TS H +lw(2i) lw(3.5i). +_ +.sp 6p +.B +Event Mask Circumstances +.sp 6p +_ +.sp 6p +.TH +.R +T{ +.PN NoEventMask +T} T{ +No events wanted +T} +T{ +.PN KeyPressMask +T} T{ +Keyboard down events wanted +T} +T{ +.PN KeyReleaseMask +T} T{ +Keyboard up events wanted +T} +T{ +.PN ButtonPressMask +T} T{ +Pointer button down events wanted +T} +T{ +.PN ButtonReleaseMask +T} T{ +Pointer button up events wanted +T} +T{ +.PN EnterWindowMask +T} T{ +Pointer window entry events wanted +T} +T{ +.PN LeaveWindowMask +T} T{ +Pointer window leave events wanted +T} +T{ +.PN PointerMotionMask +T} T{ +Pointer motion events wanted +T} +T{ +.PN PointerMotionHintMask +T} T{ +Pointer motion hints wanted +T} +T{ +.PN Button1MotionMask +T} T{ +Pointer motion while button 1 down +T} +T{ +.PN Button2MotionMask +T} T{ +Pointer motion while button 2 down +T} +T{ +.PN Button3MotionMask +T} T{ +Pointer motion while button 3 down +T} +T{ +.PN Button4MotionMask +T} T{ +Pointer motion while button 4 down +T} +T{ +.PN Button5MotionMask +T} T{ +Pointer motion while button 5 down +T} +T{ +.PN ButtonMotionMask +T} T{ +Pointer motion while any button down +T} +T{ +.PN KeymapStateMask +T} T{ +Keyboard state wanted at window entry and focus in +T} +T{ +.PN ExposureMask +T} T{ +Any exposure wanted +T} +T{ +.PN VisibilityChangeMask +T} T{ +Any change in visibility wanted +T} +T{ +.PN StructureNotifyMask +T} T{ +Any change in window structure wanted +T} +T{ +.PN ResizeRedirectMask +T} T{ +Redirect resize of this window +T} +T{ +.PN SubstructureNotifyMask +T} T{ +Substructure notification wanted +T} +T{ +.PN SubstructureRedirectMask +T} T{ +Redirect structure requests on children +T} +T{ +.PN FocusChangeMask +T} T{ +Any change in input focus wanted +T} +T{ +.PN PropertyChangeMask +T} T{ +Any change in property wanted +T} +T{ +.PN ColormapChangeMask +T} T{ +Any change in colormap wanted +T} +T{ +.PN OwnerGrabButtonMask +T} T{ +Automatic grabs should activate with owner_events set to +.PN True +T} +.sp 6p +_ +.TE +.LP +.NH 2 +Event Processing Overview +.XS +\*(SN Event Processing Overview +.XE +.LP +The event reported to a client application during event processing +depends on which event masks you provide as the event-mask attribute +for a window. +For some event masks, there is a one-to-one correspondence between +the event mask constant and the event type constant. +For example, if you pass the event mask +.PN ButtonPressMask , +the X server sends back only +.PN ButtonPress +events. +.IN "CurrentTime" +Most events contain a time member, +which is the time at which an event occurred. +.LP +In other cases, one event mask constant can map to several event type constants. +For example, if you pass the event mask +.PN SubstructureNotifyMask , +the X server can send back +.PN CirculateNotify , +.PN ConfigureNotify , +.PN CreateNotify , +.PN DestroyNotify , +.PN GravityNotify , +.PN MapNotify , +.PN ReparentNotify , +or +.PN UnmapNotify +events. +.LP +In another case, +two event masks can map to one event type. +For example, +if you pass either +.PN PointerMotionMask +or +.PN ButtonMotionMask , +the X server sends back +a +.PN MotionNotify +event. +.LP +The following table +lists the event mask, +its associated event type or types, +and the structure name associated with the event type. +Some of these structures actually are typedefs to a generic structure +that is shared between two event types. +Note that N.A. appears in columns for which the information is not applicable. +.LP +.ps 9 +.nr PS 9 +.TS H +lw(1.5i) lw(1i) lw(1.5i) lw(1.5i). +_ +.sp 6p +.B +Event Mask Event Type Structure Generic Structure +.sp 6p +_ +.sp 6p +.TH +.R +ButtonMotionMask MotionNotify XPointerMovedEvent XMotionEvent +Button1MotionMask +Button2MotionMask +Button3MotionMask +Button4MotionMask +Button5MotionMask +.sp 6p +ButtonPressMask ButtonPress XButtonPressedEvent XButtonEvent +.sp 6p +ButtonReleaseMask ButtonRelease XButtonReleasedEvent XButtonEvent +.sp 6p +ColormapChangeMask ColormapNotify XColormapEvent +.sp 6p +EnterWindowMask EnterNotify XEnterWindowEvent XCrossingEvent +.sp 6p +LeaveWindowMask LeaveNotify XLeaveWindowEvent XCrossingEvent +.sp 6p +ExposureMask Expose XExposeEvent +GCGraphicsExposures in GC GraphicsExpose XGraphicsExposeEvent + NoExpose XNoExposeEvent +.sp 6p +FocusChangeMask FocusIn XFocusInEvent XFocusChangeEvent + FocusOut XFocusOutEvent XFocusChangeEvent +.sp 6p +KeymapStateMask KeymapNotify XKeymapEvent +.sp 6p +KeyPressMask KeyPress XKeyPressedEvent XKeyEvent +KeyReleaseMask KeyRelease XKeyReleasedEvent XKeyEvent +.sp 6p +OwnerGrabButtonMask N.A. N.A. +.sp 6p +PointerMotionMask MotionNotify XPointerMovedEvent XMotionEvent +PointerMotionHintMask N.A. N.A. +.sp 6p +PropertyChangeMask PropertyNotify XPropertyEvent +.sp 6p +ResizeRedirectMask ResizeRequest XResizeRequestEvent +.sp 6p +StructureNotifyMask CirculateNotify XCirculateEvent + ConfigureNotify XConfigureEvent + DestroyNotify XDestroyWindowEvent + GravityNotify XGravityEvent + MapNotify XMapEvent + ReparentNotify XReparentEvent + UnmapNotify XUnmapEvent +.sp 6p +SubstructureNotifyMask CirculateNotify XCirculateEvent + ConfigureNotify XConfigureEvent + CreateNotify XCreateWindowEvent + DestroyNotify XDestroyWindowEvent + GravityNotify XGravityEvent + MapNotify XMapEvent + ReparentNotify XReparentEvent + UnmapNotify XUnmapEvent +.sp 6p +SubstructureRedirectMask CirculateRequest XCirculateRequestEvent + ConfigureRequest XConfigureRequestEvent + MapRequest XMapRequestEvent +.sp 6p +N.A. ClientMessage XClientMessageEvent +.sp 6p +N.A. MappingNotify XMappingEvent +.sp 6p +N.A. SelectionClear XSelectionClearEvent +.sp 6p +N.A. SelectionNotify XSelectionEvent +.sp 6p +N.A. SelectionRequest XSelectionRequestEvent +.sp 6p +VisibilityChangeMask VisibilityNotify XVisibilityEvent +.sp 6p +_ +.TE +.ps 11 +.nr PS 11 +.LP +The sections that follow describe the processing that occurs +when you select the different event masks. +The sections are organized according to these processing categories: +.IP \(bu 5 +Keyboard and pointer events +.IP \(bu 5 +Window crossing events +.IP \(bu 5 +Input focus events +.IP \(bu 5 +Keymap state notification events +.IP \(bu 5 +Exposure events +.IP \(bu 5 +Window state notification events +.IP \(bu 5 +Structure control events +.IP \(bu 5 +Colormap state notification events +.IP \(bu 5 +Client communication events +.NH 2 +Keyboard and Pointer Events +.XS +\*(SN Keyboard and Pointer Events +.XE +.LP +This section discusses: +.IP \(bu 5 +Pointer button events +.IP \(bu 5 +Keyboard and pointer events +.NH 3 +Pointer Button Events +.XS +\*(SN Pointer Button Events +.XE +.LP +The following describes the event processing that occurs when a pointer button +press is processed with the pointer in some window w and +when no active pointer grab is in progress. +.LP +The X server searches the ancestors of w from the root down, +looking for a passive grab to activate. +If no matching passive grab on the button exists, +the X server automatically starts an active grab for the client receiving +the event and sets the last-pointer-grab time to the current server time. +The effect is essentially equivalent to an +.PN XGrabButton +with these client passed arguments: +.TS H +lw(1.5i) lw(3.5i). +_ +.sp 6p +.B +Argument Value +.sp 6p +_ +.sp 6p +.TH +.R +T{ +\fIw\fP +T} T{ +The event window +T} +T{ +\fIevent_mask\fP +T} T{ +The client's selected pointer events on the event window +T} +T{ +\fIpointer_mode\fP +T} T{ +.PN GrabModeAsync +T} +T{ +\fIkeyboard_mode\fP +T} T{ +.PN GrabModeAsync +T} +T{ +\fIowner_events\fP +T} T{ +.PN True , +if the client has selected +.PN OwnerGrabButtonMask +on the event window, +otherwise +.PN False +T} +T{ +\fIconfine_to\fP +T} T{ +.PN None +T} +T{ +\fIcursor\fP +T} T{ +.PN None +T} +.sp 6p +_ +.TE +.LP +The active grab is automatically terminated when +the logical state of the pointer has all buttons released. +Clients can modify the active grab by calling +.PN XUngrabPointer +and +.PN XChangeActivePointerGrab . +.NH 3 +Keyboard and Pointer Events +.XS +\*(SN Keyboard and Pointer Events +.XE +.LP +.IN "Events" "ButtonPress" +.IN "Events" "ButtonRelease" +.IN "Events" "KeyPress" +.IN "Events" "KeyRelease" +.IN "Events" "MotionNotify" +This section discusses the processing that occurs for the +keyboard events +.PN KeyPress +and +.PN KeyRelease +and the pointer events +.PN ButtonPress , +.PN ButtonRelease , +and +.PN MotionNotify . +For information about the keyboard event-handling utilities, +see chapter 11. +.LP +.IN "KeyPress" "" "@DEF@" +.IN "KeyRelease" "" "@DEF@" +The X server reports +.PN KeyPress +or +.PN KeyRelease +events to clients wanting information about keys that logically change state. +Note that these events are generated for all keys, +even those mapped to modifier bits. +.IN "ButtonPress" "" "@DEF@" +.IN "ButtonRelease" "" "@DEF@" +The X server reports +.PN ButtonPress +or +.PN ButtonRelease +events to clients wanting information about buttons that logically change state. +.LP +.IN "MotionNotify" "" "@DEF@" +The X server reports +.PN MotionNotify +events to clients wanting information about when the pointer logically moves. +The X server generates this event whenever the pointer is moved +and the pointer motion begins and ends in the window. +The granularity of +.PN MotionNotify +events is not guaranteed, +but a client that selects this event type is guaranteed +to receive at least one event when the pointer moves and then rests. +.LP +The generation of the logical changes lags the physical changes +if device event processing is frozen. +.LP +To receive +.PN KeyPress , +.PN KeyRelease , +.PN ButtonPress , +and +.PN ButtonRelease +events, set +.PN KeyPressMask , +.PN KeyReleaseMask , +.PN ButtonPressMask , +and +.PN ButtonReleaseMask +bits in the event-mask attribute of the window. +.LP +To receive +.PN MotionNotify +events, set one or more of the following event +masks bits in the event-mask attribute of the window. +.IP \(bu 5 +.PN Button1MotionMask \ \- +.PN Button5MotionMask +.IP +The client application receives +.PN MotionNotify +events only when one or more of the specified buttons is pressed. +.IP \(bu 5 +.PN ButtonMotionMask +.IP +The client application receives +.PN MotionNotify +events only when at least one button is pressed. +.IP \(bu 5 +.PN PointerMotionMask +.IP +The client application receives +.PN MotionNotify +events independent of the state of +the pointer buttons. +.IP \(bu 5 +.PN PointerMotionHintMask +.IP +If +.PN PointerMotionHintMask +is selected in combination with one or more of the above masks, +the X server is free to send only one +.PN MotionNotify +event (with the is_hint member of the +.PN XPointerMovedEvent +structure set to +.PN NotifyHint ) +to the client for the event window, +until either the key or button state changes, +the pointer leaves the event window, or the client calls +.PN XQueryPointer +or +.PN XGetMotionEvents . +The server still may send +.PN MotionNotify +events without is_hint set to +.PN NotifyHint . +.LP +The source of the event is the viewable window that the pointer is in. +The window used by the X server to report these events depends on +the window's position in the window hierarchy +and whether any intervening window prohibits the generation of these events. +Starting with the source window, +the X server searches up the window hierarchy until it locates the first +window specified by a client as having an interest in these events. +If one of the intervening windows has its do-not-propagate-mask +set to prohibit generation of the event type, +the events of those types will be suppressed. +Clients can modify the actual window used for reporting by performing +active grabs and, in the case of keyboard events, by using the focus window. +.LP +The structures for these event types contain: +.LP +.IN "XButtonEvent" "" "@DEF@" +.IN "XButtonPressedEvent" "" "@DEF@" +.IN "XButtonReleasedEvent" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + int type; /* ButtonPress or ButtonRelease */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window window; /* ``event'' window it is reported relative to */ + Window root; /* root window that the event occurred on */ + Window subwindow; /* child window */ + Time time; /* milliseconds */ + int x, y; /* pointer x, y coordinates in event window */ + int x_root, y_root; /* coordinates relative to root */ + unsigned int state; /* key or button mask */ + unsigned int button; /* detail */ + Bool same_screen; /* same screen flag */ +} XButtonEvent; +typedef XButtonEvent XButtonPressedEvent; +typedef XButtonEvent XButtonReleasedEvent; +.De +.LP +.IN "XKeyEvent" "" "@DEF@" +.IN "XKeyPressedEvent" "" "@DEF@" +.IN "XKeyReleasedEvent" "" "@DEF@" +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + int type; /* KeyPress or KeyRelease */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window window; /* ``event'' window it is reported relative to */ + Window root; /* root window that the event occurred on */ + Window subwindow; /* child window */ + Time time; /* milliseconds */ + int x, y; /* pointer x, y coordinates in event window */ + int x_root, y_root; /* coordinates relative to root */ + unsigned int state; /* key or button mask */ + unsigned int keycode; /* detail */ + Bool same_screen; /* same screen flag */ +} XKeyEvent; +typedef XKeyEvent XKeyPressedEvent; +typedef XKeyEvent XKeyReleasedEvent; +.De +.LP +.IN "XMotionEvent" "" "@DEF@" +.IN "XPointerMovedEvent" "" "@DEF@" +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + int type; /* MotionNotify */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window window; /* ``event'' window reported relative to */ + Window root; /* root window that the event occurred on */ + Window subwindow; /* child window */ + Time time; /* milliseconds */ + int x, y; /* pointer x, y coordinates in event window */ + int x_root, y_root; /* coordinates relative to root */ + unsigned int state; /* key or button mask */ + char is_hint; /* detail */ + Bool same_screen; /* same screen flag */ +} XMotionEvent; +typedef XMotionEvent XPointerMovedEvent; +.De +.LP +.eM +These structures have the following common members: +window, root, subwindow, time, x, y, x_root, y_root, state, and same_screen. +The window member is set to the window on which the +event was generated and is referred to as the event window. +As long as the conditions previously discussed are met, +this is the window used by the X server to report the event. +The root member is set to the source window's root window. +The x_root and y_root members are set to the pointer's coordinates +relative to the root window's origin at the time of the event. +.LP +The same_screen member is set to indicate whether the event +window is on the same screen +as the root window and can be either +.PN True +or +.PN False . +If +.PN True , +the event and root windows are on the same screen. +If +.PN False , +the event and root windows are not on the same screen. +.LP +If the source window is an inferior of the event window, +the subwindow member of the structure is set to the child of the event window +that is the source window or the child of the event window that is +an ancestor of the source window. +Otherwise, the X server sets the subwindow member to +.PN None . +The time member is set to the time when the event was generated +and is expressed in milliseconds. +.LP +If the event window is on the same screen as the root window, +the x and y members +are set to the coordinates relative to the event window's origin. +Otherwise, these members are set to zero. +.LP +The state member is set to indicate the logical state of the pointer buttons +and modifier keys just prior to the event, +which is the bitwise inclusive OR of one or more of the +button or modifier key masks: +.PN Button1Mask , +.PN Button2Mask , +.PN Button3Mask , +.PN Button4Mask , +.PN Button5Mask , +.PN ShiftMask , +.PN LockMask , +.PN ControlMask , +.PN Mod1Mask , +.PN Mod2Mask , +.PN Mod3Mask , +.PN Mod4Mask , +and +.PN Mod5Mask . +.LP +Each of these structures also has a member that indicates the detail. +For the +.PN XKeyPressedEvent +and +.PN XKeyReleasedEvent +structures, this member is called a keycode. +It is set to a number that represents a physical key on the keyboard. +The keycode is an arbitrary representation for any key on the keyboard +(see sections 12.7 and 16.1). +.LP +For the +.PN XButtonPressedEvent +and +.PN XButtonReleasedEvent +structures, this member is called button. +It represents the pointer button that changed state and can be the +.PN Button1 , +.PN Button2 , +.PN Button3 , +.PN Button4 , +or +.PN Button5 +value. +For the +.PN XPointerMovedEvent +structure, this member is called is_hint. +It can be set to +.PN NotifyNormal +or +.PN NotifyHint . +.LP +Some of the symbols mentioned in this section have fixed values, as +follows: +.TS H +lw(2i) lw(3.5i). +_ +.sp 6p +.B +Symbol Value +.sp 6p +_ +.sp 6p +.TH +.R +T{ +.PN Button1MotionMask +T} T{ +(1L<<8) +T} +T{ +.PN Button2MotionMask +T} T{ +(1L<<9) +T} +T{ +.PN Button3MotionMask +T} T{ +(1L<<10) +T} +T{ +.PN Button4MotionMask +T} T{ +(1L<<11) +T} +T{ +.PN Button5MotionMask +T} T{ +(1L<<12) +T} +T{ +.PN Button1Mask +T} T{ +(1<<8) +T} +T{ +.PN Button2Mask +T} T{ +(1<<9) +T} +T{ +.PN Button3Mask +T} T{ +(1<<10) +T} +T{ +.PN Button4Mask +T} T{ +(1<<11) +T} +T{ +.PN Button5Mask +T} T{ +(1<<12) +T} +T{ +.PN ShiftMask +T} T{ +(1<<0) +T} +T{ +.PN LockMask +T} T{ +(1<<1) +T} +T{ +.PN ControlMask +T} T{ +(1<<2) +T} +T{ +.PN Mod1Mask +T} T{ +(1<<3) +T} +T{ +.PN Mod2Mask +T} T{ +(1<<4) +T} +T{ +.PN Mod3Mask +T} T{ +(1<<5) +T} +T{ +.PN Mod4Mask +T} T{ +(1<<6) +T} +T{ +.PN Mod5Mask +T} T{ +(1<<7) +T} +T{ +.PN Button1 +T} T{ +1 +T} +T{ +.PN Button2 +T} T{ +2 +T} +T{ +.PN Button3 +T} T{ +3 +T} +T{ +.PN Button4 +T} T{ +4 +T} +T{ +.PN Button5 +T} T{ +5 +T} +.sp 6p +_ +.TE +.NH 2 +Window Entry/Exit Events +.XS +\*(SN Window Entry/Exit Events +.XE +.LP +.IN "Events" "EnterNotify" +.IN "Events" "LeaveNotify" +This section describes the processing that +occurs for the window crossing events +.PN EnterNotify +and +.PN LeaveNotify . +.IN "EnterNotify" "" "@DEF@" +.IN "LeaveNotify" "" "@DEF@" +If a pointer motion or a window hierarchy change causes the +pointer to be in a different window than before, the X server reports +.PN EnterNotify +or +.PN LeaveNotify +events to clients who have selected for these events. +All +.PN EnterNotify +and +.PN LeaveNotify +events caused by a hierarchy change are +generated after any hierarchy event +.Pn ( UnmapNotify , +.PN MapNotify , +.PN ConfigureNotify , +.PN GravityNotify , +.PN CirculateNotify ) +caused by that change; +however, the X protocol does not constrain the ordering of +.PN EnterNotify +and +.PN LeaveNotify +events with respect to +.PN FocusOut , +.PN VisibilityNotify , +and +.PN Expose +events. +.LP +This contrasts with +.PN MotionNotify +events, which are also generated when the pointer moves +but only when the pointer motion begins and ends in a single window. +An +.PN EnterNotify +or +.PN LeaveNotify +event also can be generated when some client application calls +.PN XGrabPointer +and +.PN XUngrabPointer . +.LP +To receive +.PN EnterNotify +or +.PN LeaveNotify +events, set the +.PN EnterWindowMask +or +.PN LeaveWindowMask +bits of the event-mask attribute of the window. +.LP +The structure for these event types contains: +.LP +.IN "XCrossingEvent" "" "@DEF@" +.IN "XEnterWindowEvent" "" "@DEF@" +.IN "XLeaveWindowEvent" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + int type; /* EnterNotify or LeaveNotify */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window window; /* ``event'' window reported relative to */ + Window root; /* root window that the event occurred on */ + Window subwindow; /* child window */ + Time time; /* milliseconds */ + int x, y; /* pointer x, y coordinates in event window */ + int x_root, y_root; /* coordinates relative to root */ + int mode; /* NotifyNormal, NotifyGrab, NotifyUngrab */ + int detail; + /* + * NotifyAncestor, NotifyVirtual, NotifyInferior, + * NotifyNonlinear,NotifyNonlinearVirtual + */ + Bool same_screen; /* same screen flag */ + Bool focus; /* boolean focus */ + unsigned int state; /* key or button mask */ +} XCrossingEvent; +typedef XCrossingEvent XEnterWindowEvent; +typedef XCrossingEvent XLeaveWindowEvent; +.De +.LP +.eM +The window member is set to the window on which the +.PN EnterNotify +or +.PN LeaveNotify +event was generated and is referred to as the event window. +This is the window used by the X server to report the event, +and is relative to the root +window on which the event occurred. +The root member is set to the root window of the screen +on which the event occurred. +.LP +For a +.PN LeaveNotify +event, +if a child of the event window contains the initial position of the pointer, +the subwindow component is set to that child. +Otherwise, the X server sets the subwindow member to +.PN None . +For an +.PN EnterNotify +event, if a child of the event window contains the final pointer position, +the subwindow component is set to that child or +.PN None . +.LP +The time member is set to the time when the event was generated +and is expressed in milliseconds. +The x and y members are set to the coordinates of the pointer position in +the event window. +This position is always the pointer's final position, +not its initial position. +If the event window is on the same +screen as the root window, x and y are the pointer coordinates +relative to the event window's origin. +Otherwise, x and y are set to zero. +The x_root and y_root members are set to the pointer's coordinates relative to the +root window's origin at the time of the event. +.LP +The same_screen member is set to indicate whether the event window is on the same screen +as the root window and can be either +.PN True +or +.PN False . +If +.PN True , +the event and root windows are on the same screen. +If +.PN False , +the event and root windows are not on the same screen. +.LP +The focus member is set to indicate whether the event window is the focus window or an +inferior of the focus window. +The X server can set this member to either +.PN True +or +.PN False . +If +.PN True , +the event window is the focus window or an inferior of the focus window. +If +.PN False , +the event window is not the focus window or an inferior of the focus window. +.LP +The state member is set to indicate the state of the pointer buttons and +modifier keys just prior to the +event. +The X server can set this member to the bitwise inclusive OR of one +or more of the button or modifier key masks: +.PN Button1Mask , +.PN Button2Mask , +.PN Button3Mask , +.PN Button4Mask , +.PN Button5Mask , +.PN ShiftMask , +.PN LockMask , +.PN ControlMask , +.PN Mod1Mask , +.PN Mod2Mask , +.PN Mod3Mask , +.PN Mod4Mask , +.PN Mod5Mask . +.LP +The mode member is set to indicate whether the events are normal events, +pseudo-motion events +when a grab activates, or pseudo-motion events when a grab deactivates. +The X server can set this member to +.PN NotifyNormal , +.PN NotifyGrab , +or +.PN NotifyUngrab . +.LP +The detail member is set to indicate the notify detail and can be +.PN NotifyAncestor , +.PN NotifyVirtual , +.PN NotifyInferior , +.PN NotifyNonlinear , +or +.PN NotifyNonlinearVirtual . +.NH 3 +Normal Entry/Exit Events +.XS +\*(SN Normal Entry/Exit Events +.XE +.LP +.PN EnterNotify +and +.PN LeaveNotify +events are generated when the pointer moves from +one window to another window. +Normal events are identified by +.PN XEnterWindowEvent +or +.PN XLeaveWindowEvent +structures whose mode member is set to +.PN NotifyNormal . +.IP \(bu 5 +When the pointer moves from window A to window B and A is an inferior of B, +the X server does the following: +.RS +.IP \- 5 +It generates a +.PN LeaveNotify +event on window A, with the detail member of the +.PN XLeaveWindowEvent +structure set to +.PN NotifyAncestor . +.IP \- 5 +It generates a +.PN LeaveNotify +event on each window between window A and window B, exclusive, +with the detail member of each +.PN XLeaveWindowEvent +structure set to +.PN NotifyVirtual . +.IP \- 5 +It generates an +.PN EnterNotify +event on window B, with the detail member of the +.PN XEnterWindowEvent +structure set to +.PN NotifyInferior . +.RE +.IP \(bu 5 +When the pointer moves from window A to window B and B is an inferior of A, +the X server does the following: +.RS +.IP \- 5 +It generates a +.PN LeaveNotify +event on window A, +with the detail member of the +.PN XLeaveWindowEvent +structure set to +.PN NotifyInferior . +.IP \- 5 +It generates an +.PN EnterNotify +event on each window between window A and window B, exclusive, with the +detail member of each +.PN XEnterWindowEvent +structure set to +.PN NotifyVirtual . +.IP \- 5 +It generates an +.PN EnterNotify +event on window B, with the detail member of the +.PN XEnterWindowEvent +structure set to +.PN NotifyAncestor . +.RE +.IP \(bu 5 +When the pointer moves from window A to window B +and window C is their least common ancestor, +the X server does the following: +.RS +.IP \- 5 +It generates a +.PN LeaveNotify +event on window A, +with the detail member of the +.PN XLeaveWindowEvent +structure set to +.PN NotifyNonlinear . +.IP \- 5 +It generates a +.PN LeaveNotify +event on each window between window A and window C, exclusive, +with the detail member of each +.PN XLeaveWindowEvent +structure set to +.PN NotifyNonlinearVirtual . +.IP \- 5 +It generates an +.PN EnterNotify +event on each window between window C and window B, exclusive, +with the detail member of each +.PN XEnterWindowEvent +structure set to +.PN NotifyNonlinearVirtual . +.IP \- 5 +It generates an +.PN EnterNotify +event on window B, with the detail member of the +.PN XEnterWindowEvent +structure set to +.PN NotifyNonlinear . +.RE +.IP \(bu 5 +When the pointer moves from window A to window B on different screens, +the X server does the following: +.RS +.IP \- 5 +It generates a +.PN LeaveNotify +event on window A, +with the detail member of the +.PN XLeaveWindowEvent +structure set to +.PN NotifyNonlinear . +.IP \- 5 +If window A is not a root window, +it generates a +.PN LeaveNotify +event on each window above window A up to and including its root, +with the detail member of each +.PN XLeaveWindowEvent +structure set to +.PN NotifyNonlinearVirtual . +.IP \- 5 +If window B is not a root window, +it generates an +.PN EnterNotify +event on each window from window B's root down to but not including +window B, with the detail member of each +.PN XEnterWindowEvent +structure set to +.PN NotifyNonlinearVirtual . +.IP \- 5 +It generates an +.PN EnterNotify +event on window B, with the detail member of the +.PN XEnterWindowEvent +structure set to +.PN NotifyNonlinear . +.RE +.\".SH 3 +.NH 3 +Grab and Ungrab Entry/Exit Events +.XS +\*(SN Grab and Ungrab Entry/Exit Events +.XE +.LP +Pseudo-motion mode +.PN EnterNotify +and +.PN LeaveNotify +events are generated when a pointer grab activates or deactivates. +Events in which the pointer grab activates +are identified by +.PN XEnterWindowEvent +or +.PN XLeaveWindowEvent +structures whose mode member is set to +.PN NotifyGrab . +Events in which the pointer grab deactivates +are identified by +.PN XEnterWindowEvent +or +.PN XLeaveWindowEvent +structures whose mode member is set to +.PN NotifyUngrab +(see +.PN XGrabPointer ). +.IP \(bu 5 +When a pointer grab activates after any initial warp into a confine_to +window and before generating any actual +.PN ButtonPress +event that activates the grab, +G is the grab_window for the grab, +and P is the window the pointer is in, +the X server does the following: +.RS +.IP \- 5 +It generates +.PN EnterNotify +and +.PN LeaveNotify +events (see section 10.6.1) +with the mode members of the +.PN XEnterWindowEvent +and +.PN XLeaveWindowEvent +structures set to +.PN NotifyGrab . +These events are generated +as if the pointer were to suddenly warp from +its current position in P to some position in G. +However, the pointer does not warp, and the X server uses the pointer position +as both the initial and final positions for the events. +.RE +.IP \(bu 5 +When a pointer grab deactivates after generating any actual +.PN ButtonRelease +event that deactivates the grab, +G is the grab_window for the grab, +and P is the window the pointer is in, +the X server does the following: +.RS +.IP \- 5 +It generates +.PN EnterNotify +and +.PN LeaveNotify +events (see section 10.6.1) +with the mode members of the +.PN XEnterWindowEvent +and +.PN XLeaveWindowEvent +structures set to +.PN NotifyUngrab . +These events are generated as if the pointer were to suddenly warp from +some position in G to its current position in P. +However, the pointer does not warp, and the X server uses the +current pointer position as both the +initial and final positions for the events. +.RE +.NH 2 +Input Focus Events +.XS +\*(SN Input Focus Events +.XE +.LP +.IN "Events" "FocusIn" +.IN "Events" "FocusOut" +This section describes the processing that occurs for the input focus events +.PN FocusIn +and +.PN FocusOut . +.IN "FocusIn" "" "@DEF@" +.IN "FocusOut" "" "@DEF@" +The X server can report +.PN FocusIn +or +.PN FocusOut +events to clients wanting information about when the input focus changes. +The keyboard is always attached to some window +(typically, the root window or a top-level window), +which is called the focus window. +The focus window and the position of the pointer determine the window that +receives keyboard input. +Clients may need to know when the input focus changes +to control highlighting of areas on the screen. +.LP +To receive +.PN FocusIn +or +.PN FocusOut +events, set the +.PN FocusChangeMask +bit in the event-mask attribute of the window. +.LP +The structure for these event types contains: +.LP +.IN "XFocusChangeEvent" "" "@DEF@" +.IN "XFocusInEvent" "" "@DEF@" +.IN "XFocusOutEvent" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + int type; /* FocusIn or FocusOut */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window window; /* window of event */ + int mode; /* NotifyNormal, NotifyGrab, NotifyUngrab */ + int detail; + /* + * NotifyAncestor, NotifyVirtual, NotifyInferior, + * NotifyNonlinear,NotifyNonlinearVirtual, NotifyPointer, + * NotifyPointerRoot, NotifyDetailNone + */ +} XFocusChangeEvent; +typedef XFocusChangeEvent XFocusInEvent; +typedef XFocusChangeEvent XFocusOutEvent; +.De +.LP +.eM +The window member is set to the window on which the +.PN FocusIn +or +.PN FocusOut +event was generated. +This is the window used by the X server to report the event. +The mode member is set to indicate whether the focus events +are normal focus events, +focus events while grabbed, +focus events +when a grab activates, or focus events when a grab deactivates. +The X server can set the mode member to +.PN NotifyNormal , +.PN NotifyWhileGrabbed , +.PN NotifyGrab , +or +.PN NotifyUngrab . +.LP +All +.PN FocusOut +events caused by a window unmap are generated after any +.PN UnmapNotify +event; however, the X protocol does not constrain the ordering of +.PN FocusOut +events with respect to +generated +.PN EnterNotify , +.PN LeaveNotify , +.PN VisibilityNotify , +and +.PN Expose +events. +.LP +Depending on the event mode, +the detail member is set to indicate the notify detail and can be +.PN NotifyAncestor , +.PN NotifyVirtual , +.PN NotifyInferior , +.PN NotifyNonlinear , +.PN NotifyNonlinearVirtual , +.PN NotifyPointer , +.PN NotifyPointerRoot , +or +.PN NotifyDetailNone . +.NH 3 +Normal Focus Events and Focus Events While Grabbed +.XS +\*(SN Normal Focus Events and Focus Events While Grabbed +.XE +.LP +Normal focus events are identified by +.PN XFocusInEvent +or +.PN XFocusOutEvent +structures whose mode member is set to +.PN NotifyNormal . +Focus events while grabbed are identified by +.PN XFocusInEvent +or +.PN XFocusOutEvent +structures whose mode member is set to +.PN NotifyWhileGrabbed . +The X server processes normal focus and focus events while grabbed according to +the following: +.IP \(bu 5 +When the focus moves from window A to window B, A is an inferior of B, +and the pointer is in window P, +the X server does the following: +.RS +.IP \- 5 +It generates a +.PN FocusOut +event on window A, with the detail member of the +.PN XFocusOutEvent +structure set to +.PN NotifyAncestor . +.IP \- 5 +It generates a +.PN FocusOut +event on each window between window A and window B, exclusive, +with the detail member of each +.PN XFocusOutEvent +structure set to +.PN NotifyVirtual . +.IP \- 5 +It generates a +.PN FocusIn +event on window B, with the detail member of the +.PN XFocusOutEvent +structure set to +.PN NotifyInferior . +.IP \- 5 +If window P is an inferior of window B +but window P is not window A or an inferior or ancestor of window A, +it generates a +.PN FocusIn +event on each window below window B, down to and including window P, +with the detail member of each +.PN XFocusInEvent +structure set to +.PN NotifyPointer . +.RE +.IP \(bu 5 +When the focus moves from window A to window B, B is an inferior of A, +and the pointer is in window P, +the X server does the following: +.RS +.IP \- 5 +If window P is an inferior of window A +but P is not an inferior of window B or an ancestor of B, +it generates a +.PN FocusOut +event on each window from window P up to but not including window A, +with the detail member of each +.PN XFocusOutEvent +structure set to +.PN NotifyPointer . +.IP \- 5 +It generates a +.PN FocusOut +event on window A, +with the detail member of the +.PN XFocusOutEvent +structure set to +.PN NotifyInferior . +.IP \- 5 +It generates a +.PN FocusIn +event on each window between window A and window B, exclusive, with the +detail member of each +.PN XFocusInEvent +structure set to +.PN NotifyVirtual . +.IP \- 5 +It generates a +.PN FocusIn +event on window B, with the detail member of the +.PN XFocusInEvent +structure set to +.PN NotifyAncestor . +.RE +.IP \(bu 5 +When the focus moves from window A to window B, +window C is their least common ancestor, +and the pointer is in window P, +the X server does the following: +.RS +.IP \- 5 +If window P is an inferior of window A, +it generates a +.PN FocusOut +event on each window from window P up to but not including window A, +with the detail member of the +.PN XFocusOutEvent +structure set to +.PN NotifyPointer . +.IP \- 5 +It generates a +.PN FocusOut +event on window A, +with the detail member of the +.PN XFocusOutEvent +structure set to +.PN NotifyNonlinear . +.IP \- 5 +It generates a +.PN FocusOut +event on each window between window A and window C, exclusive, +with the detail member of each +.PN XFocusOutEvent +structure set to +.PN NotifyNonlinearVirtual . +.IP \- 5 +It generates a +.PN FocusIn +event on each window between C and B, exclusive, +with the detail member of each +.PN XFocusInEvent +structure set to +.PN NotifyNonlinearVirtual . +.IP \- 5 +It generates a +.PN FocusIn +event on window B, with the detail member of the +.PN XFocusInEvent +structure set to +.PN NotifyNonlinear . +.IP \- 5 +If window P is an inferior of window B, it generates a +.PN FocusIn +event on each window below window B down to and including window P, +with the detail member of the +.PN XFocusInEvent +structure set to +.PN NotifyPointer . +.RE +.IP \(bu 5 +When the focus moves from window A to window B on different screens +and the pointer is in window P, +the X server does the following: +.RS +.IP \- 5 +If window P is an inferior of window A, it generates a +.PN FocusOut +event on each window from window P up to but not including window A, +with the detail member of each +.PN XFocusOutEvent +structure set to +.PN NotifyPointer . +.IP \- 5 +It generates a +.PN FocusOut +event on window A, +with the detail member of the +.PN XFocusOutEvent +structure set to +.PN NotifyNonlinear . +.IP \- 5 +If window A is not a root window, +it generates a +.PN FocusOut +event on each window above window A up to and including its root, +with the detail member of each +.PN XFocusOutEvent +structure set to +.PN NotifyNonlinearVirtual . +.IP \- 5 +If window B is not a root window, +it generates a +.PN FocusIn +event on each window from window B's root down to but not including +window B, with the detail member of each +.PN XFocusInEvent +structure set to +.PN NotifyNonlinearVirtual . +.IP \- 5 +It generates a +.PN FocusIn +event on window B, with the detail member of each +.PN XFocusInEvent +structure set to +.PN NotifyNonlinear . +.IP \- 5 +If window P is an inferior of window B, it generates a +.PN FocusIn +event on each window below window B down to and including window P, +with the detail member of each +.PN XFocusInEvent +structure set to +.PN NotifyPointer . +.RE +.IP \(bu 5 +When the focus moves from window A to +.PN PointerRoot +(events sent to the window under the pointer) +or +.PN None +(discard), and the pointer is in window P, +the X server does the following: +.RS +.IP \- 5 +If window P is an inferior of window A, it generates a +.PN FocusOut +event on each window from window P up to but not including window A, +with the detail member of each +.PN XFocusOutEvent +structure set to +.PN NotifyPointer . +.IP \- 5 +It generates a +.PN FocusOut +event on window A, with the detail member of the +.PN XFocusOutEvent +structure set to +.PN NotifyNonlinear . +.IP \- 5 +If window A is not a root window, +it generates a +.PN FocusOut +event on each window above window A up to and including its root, +with the detail member of each +.PN XFocusOutEvent +structure set to +.PN NotifyNonlinearVirtual . +.IP \- 5 +It generates a +.PN FocusIn +event on the root window of all screens, with the detail member of each +.PN XFocusInEvent +structure set to +.PN NotifyPointerRoot +(or +.PN NotifyDetailNone ). +.IP \- 5 +If the new focus is +.PN PointerRoot , +it generates a +.PN FocusIn +event on each window from window P's root down to and including window P, +with the detail member of each +.PN XFocusInEvent +structure set to +.PN NotifyPointer . +.RE +.IP \(bu 5 +When the focus moves from +.PN PointerRoot +(events sent to the window under the pointer) +or +.PN None +to window A, and the pointer is in window P, +the X server does the following: +.RS +.IP \- 5 +If the old focus is +.PN PointerRoot , +it generates a +.PN FocusOut +event on each window from window P up to and including window P's root, +with the detail member of each +.PN XFocusOutEvent +structure set to +.PN NotifyPointer . +.IP \- 5 +It generates a +.PN FocusOut +event on all root windows, +with the detail member of each +.PN XFocusOutEvent +structure set to +.PN NotifyPointerRoot +(or +.PN NotifyDetailNone ). +.IP \- 5 +If window A is not a root window, +it generates a +.PN FocusIn +event on each window from window A's root down to but not including window A, +with the detail member of each +.PN XFocusInEvent +structure set to +.PN NotifyNonlinearVirtual . +.IP \- 5 +It generates a +.PN FocusIn +event on window A, +with the detail member of the +.PN XFocusInEvent +structure set to +.PN NotifyNonlinear . +.IP \- 5 +If window P is an inferior of window A, it generates a +.PN FocusIn +event on each window below window A down to and including window P, +with the detail member of each +.PN XFocusInEvent +structure set to +.PN NotifyPointer . +.RE +.IP \(bu 5 +When the focus moves from +.PN PointerRoot +(events sent to the window under the pointer) +to +.PN None +(or vice versa), and the pointer is in window P, +the X server does the following: +.RS +.IP \- 5 +If the old focus is +.PN PointerRoot , +it generates a +.PN FocusOut +event on each window from window P up to and including window P's root, +with the detail member of each +.PN XFocusOutEvent +structure set to +.PN NotifyPointer . +.IP \- 5 +It generates a +.PN FocusOut +event on all root windows, +with the detail member of each +.PN XFocusOutEvent +structure set to either +.PN NotifyPointerRoot +or +.PN NotifyDetailNone . +.IP \- 5 +It generates a +.PN FocusIn +event on all root windows, +with the detail member of each +.PN XFocusInEvent +structure set to +.PN NotifyDetailNone +or +.PN NotifyPointerRoot . +.IP \- 5 +If the new focus is +.PN PointerRoot , +it generates a +.PN FocusIn +event on each window from window P's root down to and including window P, +with the detail member of each +.PN XFocusInEvent +structure set to +.PN NotifyPointer . +.RE +.\".SH 3 +.NH 3 +Focus Events Generated by Grabs +.XS +\*(SN Focus Events Generated by Grabs +.XE +.LP +Focus events in which the keyboard grab activates +are identified by +.PN XFocusInEvent +or +.PN XFocusOutEvent +structures whose mode member is set to +.PN NotifyGrab . +Focus events in which the keyboard grab deactivates +are identified by +.PN XFocusInEvent +or +.PN XFocusOutEvent +structures whose mode member is set to +.PN NotifyUngrab +(see +.PN XGrabKeyboard ). +.IP \(bu 5 +When a keyboard grab activates before generating any actual +.PN KeyPress +event that activates the grab, +G is the grab_window, and F is the current focus, +the X server does the following: +.RS +.IP \- 5 +It generates +.PN FocusIn +and +.PN FocusOut +events, with the mode members of the +.PN XFocusInEvent +and +.PN XFocusOutEvent +structures set to +.PN NotifyGrab . +These events are generated +as if the focus were to change from +F to G. +.RE +.IP \(bu 5 +When a keyboard grab deactivates after generating any actual +.PN KeyRelease +event that deactivates the grab, +G is the grab_window, and F is the current focus, +the X server does the following: +.RS +.IP \- 5 +It generates +.PN FocusIn +and +.PN FocusOut +events, with the mode members of the +.PN XFocusInEvent +and +.PN XFocusOutEvent +structures set to +.PN NotifyUngrab . +These events are generated +as if the focus were to change from +G to F. +.RE +.NH 2 +Key Map State Notification Events +.XS +\*(SN Key Map State Notification Events +.XE +.LP +.IN "Events" "KeymapNotify" +.IN "KeymapNotify" "" "@DEF@" +The X server can report +.PN KeymapNotify +events to clients that want information about changes in their keyboard state. +.LP +To receive +.PN KeymapNotify +events, set the +.PN KeymapStateMask +bit in the event-mask attribute of the window. +The X server generates this event immediately after every +.PN EnterNotify +and +.PN FocusIn +event. +.LP +The structure for this event type contains: +.LP +.IN "XKeymapEvent" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +/* generated on EnterWindow and FocusIn when KeymapState selected */ +typedef struct { + int type; /* KeymapNotify */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window window; + char key_vector[32]; +} XKeymapEvent; +.De +.LP +.eM +The window member is not used but is present to aid some toolkits. +The key_vector member is set to the bit vector of the keyboard. +Each bit set to 1 indicates that the corresponding key +is currently pressed. +The vector is represented as 32 bytes. +Byte N (from 0) contains the bits for keys 8N to 8N + 7 +with the least significant bit in the byte representing key 8N. +.NH 2 +Exposure Events +.XS +\*(SN Exposure Events +.XE +.LP +The X protocol does not guarantee to preserve the contents of window +regions when +the windows are obscured or reconfigured. +Some implementations may preserve the contents of windows. +Other implementations are free to destroy the contents of windows +when exposed. +X expects client applications to assume the responsibility for +restoring the contents of an exposed window region. +(An exposed window region describes a formerly obscured window whose +region becomes visible.) +Therefore, the X server sends +.PN Expose +events describing the window and the region of the window that has been exposed. +A naive client application usually redraws the entire window. +A more sophisticated client application redraws only the exposed region. +.NH 3 +Expose Events +.XS +\*(SN Expose Events +.XE +.LP +.IN "Events" "Expose" +.IN "Expose" "" "@DEF@" +The X server can report +.PN Expose +events to clients wanting information about when the contents of window regions +have been lost. +The circumstances in which the X server generates +.PN Expose +events are not as definite as those for other events. +However, the X server never generates +.PN Expose +events on windows whose class you specified as +.PN InputOnly . +The X server can generate +.PN Expose +events when no valid contents are available for regions of a window +and either the regions are visible, +the regions are viewable and the server is (perhaps newly) maintaining +backing store on the window, +or the window is not viewable but the server is (perhaps newly) honoring the +window's backing-store attribute of +.PN Always +or +.PN WhenMapped . +The regions decompose into an (arbitrary) set of rectangles, +and an +.PN Expose +event is generated for each rectangle. +For any given window, +the X server guarantees to report contiguously +all of the regions exposed by some action that causes +.PN Expose +events, such as raising a window. +.LP +To receive +.PN Expose +events, set the +.PN ExposureMask +bit in the event-mask attribute of the window. +.LP +The structure for this event type contains: +.LP +.IN "XExposeEvent" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + int type; /* Expose */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window window; + int x, y; + int width, height; + int count; /* if nonzero, at least this many more */ +} XExposeEvent; +.De +.LP +.eM +The window member is set to the exposed (damaged) window. +The x and y members are set to the coordinates relative to the window's origin +and indicate the upper-left corner of the rectangle. +The width and height members are set to the size (extent) of the rectangle. +The count member is set to the number of +.PN Expose +events that are to follow. +If count is zero, no more +.PN Expose +events follow for this window. +However, if count is nonzero, at least that number of +.PN Expose +events (and possibly more) follow for this window. +Simple applications that do not want to optimize redisplay by distinguishing +between subareas of its window can just ignore all +.PN Expose +events with nonzero counts and perform full redisplays +on events with zero counts. +.NH 3 +GraphicsExpose and NoExpose Events +.XS +\*(SN GraphicsExpose and NoExpose Events +.XE +.LP +.IN "Events" "GraphicsExpose" +.IN "Events" "NoExpose" +.IN "GraphicsExpose" "" "@DEF@" +The X server can report +.PN GraphicsExpose +events to clients wanting information about when a destination region could not +be computed during certain graphics requests: +.PN XCopyArea +or +.PN XCopyPlane . +The X server generates this event whenever a destination region could not be +computed because of an obscured or out-of-bounds source region. +In addition, the X server guarantees to report contiguously all of the regions exposed by +some graphics request +(for example, copying an area of a drawable to a destination +drawable). +.LP +.IN "NoExpose" "" "@DEF@" +The X server generates a +.PN NoExpose +event whenever a graphics request that might +produce a +.PN GraphicsExpose +event does not produce any. +In other words, the client is really asking for a +.PN GraphicsExpose +event but instead receives a +.PN NoExpose +event. +.LP +To receive +.PN GraphicsExpose +or +.PN NoExpose +events, you must first set the graphics-exposure +attribute of the graphics context to +.PN True . +You also can set the graphics-expose attribute when creating a graphics +context using +.PN XCreateGC +or by calling +.PN XSetGraphicsExposures . +.LP +The structures for these event types contain: +.LP +.IN "XGraphicsExposeEvent" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + int type; /* GraphicsExpose */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Drawable drawable; + int x, y; + int width, height; + int count; /* if nonzero, at least this many more */ + int major_code; /* core is CopyArea or CopyPlane */ + int minor_code; /* not defined in the core */ +} XGraphicsExposeEvent; +.De +.LP +.IN "XNoExposeEvent" "" "@DEF@" +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + int type; /* NoExpose */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Drawable drawable; + int major_code; /* core is CopyArea or CopyPlane */ + int minor_code; /* not defined in the core */ +} XNoExposeEvent; +.De +.LP +.eM +Both structures have these common members: drawable, major_code, and minor_code. +The drawable member is set to the drawable of the destination region on +which the graphics request was to be performed. +The major_code member is set to the graphics request initiated by the client +and can be either +.PN X_CopyArea +or +.PN X_CopyPlane . +If it is +.PN X_CopyArea , +a call to +.PN XCopyArea +initiated the request. +If it is +.PN X_CopyPlane , +a call to +.PN XCopyPlane +initiated the request. +These constants are defined in +.hN X11/Xproto.h . +The minor_code member, +like the major_code member, +indicates which graphics request was initiated by +the client. +However, the minor_code member is not defined by the core +X protocol and will be zero in these cases, +although it may be used by an extension. +.LP +The +.PN XGraphicsExposeEvent +structure has these additional members: x, y, width, height, and count. +The x and y members are set to the coordinates relative to the drawable's origin +and indicate the upper-left corner of the rectangle. +The width and height members are set to the size (extent) of the rectangle. +The count member is set to the number of +.PN GraphicsExpose +events to follow. +If count is zero, no more +.PN GraphicsExpose +events follow for this window. +However, if count is nonzero, at least that number of +.PN GraphicsExpose +events (and possibly more) are to follow for this window. +.NH 2 +Window State Change Events +.XS +\*(SN Window State Change Events +.XE +.LP +The following sections discuss: +.IP \(bu 5 +.PN CirculateNotify +events +.IP \(bu 5 +.PN ConfigureNotify +events +.IP \(bu 5 +.PN CreateNotify +events +.IP \(bu 5 +.PN DestroyNotify +events +.IP \(bu 5 +.PN GravityNotify +events +.IP \(bu 5 +.PN MapNotify +events +.IP \(bu 5 +.PN MappingNotify +events +.IP \(bu 5 +.PN ReparentNotify +events +.IP \(bu 5 +.PN UnmapNotify +events +.IP \(bu 5 +.PN VisibilityNotify +events +.\" .SH 3 +.NH 3 +CirculateNotify Events +.XS +\*(SN CirculateNotify Events +.XE +.LP +.IN "Events" "CirculateNotify" +.IN "CirculateNotify" "" "@DEF@" +The X server can report +.PN CirculateNotify +events to clients wanting information about when a window changes +its position in the stack. +The X server generates this event type whenever a window is actually restacked +as a result of a client application calling +.PN XCirculateSubwindows , +.PN XCirculateSubwindowsUp , +or +.PN XCirculateSubwindowsDown . +.LP +To receive +.PN CirculateNotify +events, set the +.PN StructureNotifyMask +bit in the event-mask attribute of the window +or the +.PN SubstructureNotifyMask +bit in the event-mask attribute of the parent window +(in which case, circulating any child generates an event). +.LP +The structure for this event type contains: +.LP +.IN "XCirculateEvent" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + int type; /* CirculateNotify */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window event; + Window window; + int place; /* PlaceOnTop, PlaceOnBottom */ +} XCirculateEvent; +.De +.LP +.eM +The event member is set either to the restacked window or to its parent, +depending on whether +.PN StructureNotify +or +.PN SubstructureNotify +was selected. +The window member is set to the window that was restacked. +The place member is set to the window's position after the restack occurs and +is either +.PN PlaceOnTop +or +.PN PlaceOnBottom . +If it is +.PN PlaceOnTop , +the window is now on top of all siblings. +If it is +.PN PlaceOnBottom , +the window is now below all siblings. +.NH 3 +ConfigureNotify Events +.XS +\*(SN ConfigureNotify Events +.XE +.LP +.IN "Events" "ConfigureNotify" +.IN "ConfigureNotify" "" "@DEF@" +The X server can report +.PN ConfigureNotify +events to clients wanting information about actual changes to a window's +state, such as size, position, border, and stacking order. +The X server generates this event type whenever one of the following configure +window requests made by a client application actually completes: +.IP \(bu 5 +A window's size, position, border, and/or stacking order is reconfigured +by calling +.PN XConfigureWindow . +.IP \(bu 5 +The window's position in the stacking order is changed by calling +.PN XLowerWindow , +.PN XRaiseWindow , +or +.PN XRestackWindows . +.IP \(bu 5 +A window is moved by calling +.PN XMoveWindow . +.IP \(bu 5 +A window's size is changed by calling +.PN XResizeWindow . +.IP \(bu 5 +A window's size and location is changed by calling +.PN XMoveResizeWindow . +.IP \(bu 5 +A window is mapped and its position in the stacking order is changed +by calling +.PN XMapRaised . +.IP \(bu 5 +A window's border width is changed by calling +.PN XSetWindowBorderWidth . +.LP +To receive +.PN ConfigureNotify +events, set the +.PN StructureNotifyMask +bit in the event-mask attribute of the window or the +.PN SubstructureNotifyMask +bit in the event-mask attribute of the parent window +(in which case, configuring any child generates an event). +.LP +The structure for this event type contains: +.LP +.IN "XConfigureEvent" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + int type; /* ConfigureNotify */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window event; + Window window; + int x, y; + int width, height; + int border_width; + Window above; + Bool override_redirect; +} XConfigureEvent; +.De +.LP +.eM +The event member is set either to the reconfigured window or to its parent, +depending on whether +.PN StructureNotify +or +.PN SubstructureNotify +was selected. +The window member is set to the window whose size, position, +border, and/or stacking +order was changed. +.LP +The x and y members are set to the coordinates relative to the parent window's +origin and indicate the position of the upper-left outside corner of the window. +The width and height members are set to the inside size of the window, +not including +the border. +The border_width member is set to the width of the window's border, in pixels. +.LP +The above member is set to the sibling window and is used +for stacking operations. +If the X server sets this member to +.PN None , +the window whose state was changed is on the bottom of the stack +with respect to sibling windows. +However, if this member is set to a sibling window, +the window whose state was changed is placed on top of this sibling window. +.LP +The override_redirect member is set to the override-redirect attribute of the +window. +Window manager clients normally should ignore this window if the +override_redirect member +is +.PN True . +.NH 3 +CreateNotify Events +.XS +\*(SN CreateNotify Events +.XE +.LP +.IN "Events" "CreateNotify" +.IN "CreateNotify" "" "@DEF@" +The X server can report +.PN CreateNotify +events to clients wanting information about creation of windows. +The X server generates this event whenever a client +application creates a window by calling +.PN XCreateWindow +or +.PN XCreateSimpleWindow . +.LP +To receive +.PN CreateNotify +events, set the +.PN SubstructureNotifyMask +bit in the event-mask attribute of the window. +Creating any children then generates an event. +.LP +The structure for the event type contains: +.LP +.IN "XCreateWindowEvent" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + int type; /* CreateNotify */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window parent; /* parent of the window */ + Window window; /* window id of window created */ + int x, y; /* window location */ + int width, height; /* size of window */ + int border_width; /* border width */ + Bool override_redirect; /* creation should be overridden */ +} XCreateWindowEvent; +.De +.LP +.eM +The parent member is set to the created window's parent. +The window member specifies the created window. +The x and y members are set to the created window's coordinates relative +to the parent window's origin and indicate the position of the upper-left +outside corner of the created window. +The width and height members are set to the inside size of the created window +(not including the border) and are always nonzero. +The border_width member is set to the width of the created window's border, in pixels. +The override_redirect member is set to the override-redirect attribute of the +window. +Window manager clients normally should ignore this window +if the override_redirect member is +.PN True . +.NH 3 +DestroyNotify Events +.XS +\*(SN DestroyNotify Events +.XE +.LP +.IN "Events" "DestroyNotify" +.IN "DestroyNotify" "" "@DEF@" +The X server can report +.PN DestroyNotify +events to clients wanting information about which windows are destroyed. +The X server generates this event whenever a client application destroys a +window by calling +.PN XDestroyWindow +or +.PN XDestroySubwindows . +.LP +The ordering of the +.PN DestroyNotify +events is such that for any given window, +.PN DestroyNotify +is generated on all inferiors of the window +before being generated on the window itself. +The X protocol does not constrain the ordering among +siblings and across subhierarchies. +.LP +To receive +.PN DestroyNotify +events, set the +.PN StructureNotifyMask +bit in the event-mask attribute of the window or the +.PN SubstructureNotifyMask +bit in the event-mask attribute of the parent window +(in which case, destroying any child generates an event). +.LP +The structure for this event type contains: +.LP +.IN "XDestroyWindowEvent" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + int type; /* DestroyNotify */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window event; + Window window; +} XDestroyWindowEvent; +.De +.LP +.eM +The event member is set either to the destroyed window or to its parent, +depending on whether +.PN StructureNotify +or +.PN SubstructureNotify +was selected. +The window member is set to the window that is destroyed. +.NH 3 +GravityNotify Events +.XS +\*(SN GravityNotify Events +.XE +.LP +.IN "Events" "GravityNotify" +.IN "GravityNotify" "" "@DEF@" +The X server can report +.PN GravityNotify +events to clients wanting information about when a window is moved because of a +change in the size of its parent. +The X server generates this event whenever a client +application actually moves a child window as a result of resizing its parent by calling +.PN XConfigureWindow , +.PN XMoveResizeWindow , +or +.PN XResizeWindow . +.LP +To receive +.PN GravityNotify +events, set the +.PN StructureNotifyMask +bit in the event-mask attribute of the window or the +.PN SubstructureNotifyMask +bit in the event-mask attribute of the parent window +(in which case, any child that is moved because its parent has been resized +generates an event). +.LP +The structure for this event type contains: +.LP +.IN "XGravityEvent" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + int type; /* GravityNotify */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window event; + Window window; + int x, y; +} XGravityEvent; +.De +.LP +.eM +The event member is set either to the window that was moved or to its parent, +depending on whether +.PN StructureNotify +or +.PN SubstructureNotify +was selected. +The window member is set to the child window that was moved. +The x and y members are set to the coordinates relative to the +new parent window's origin +and indicate the position of the upper-left outside corner of the +window. +.NH 3 +MapNotify Events +.XS +\*(SN MapNotify Events +.XE +.LP +.IN "Events" "MapNotify" +.IN "MapNotify" "" "@DEF@" +The X server can report +.PN MapNotify +events to clients wanting information about which windows are mapped. +The X server generates this event type whenever a client application changes the +window's state from unmapped to mapped by calling +.PN XMapWindow , +.PN XMapRaised , +.PN XMapSubwindows , +.PN XReparentWindow , +or as a result of save-set processing. +.LP +To receive +.PN MapNotify +events, set the +.PN StructureNotifyMask +bit in the event-mask attribute of the window or the +.PN SubstructureNotifyMask +bit in the event-mask attribute of the parent window +(in which case, mapping any child generates an event). +.LP +The structure for this event type contains: +.LP +.IN "XMapEvent" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + int type; /* MapNotify */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window event; + Window window; + Bool override_redirect; /* boolean, is override set... */ +} XMapEvent; +.De +.LP +.eM +The event member is set either to the window that was mapped or to its parent, +depending on whether +.PN StructureNotify +or +.PN SubstructureNotify +was selected. +The window member is set to the window that was mapped. +The override_redirect member is set to the override-redirect attribute +of the window. +Window manager clients normally should ignore this window +if the override-redirect attribute is +.PN True , +because these events usually are generated from pop-ups, +which override structure control. +.NH 3 +MappingNotify Events +.XS +\*(SN MappingNotify Events +.XE +.LP +.IN "Events" "MappingNotify" +.IN "MappingNotify" "" "@DEF@" +The X server reports +.PN MappingNotify +events to all clients. +There is no mechanism to express disinterest in this event. +The X server generates this event type whenever a client application +successfully calls: +.IP \(bu 5 +.PN XSetModifierMapping +to indicate which KeyCodes are to be used as modifiers +.IP \(bu 5 +.PN XChangeKeyboardMapping +to change the keyboard mapping +.IP \(bu 5 +.PN XSetPointerMapping +to set the pointer mapping +.LP +The structure for this event type contains: +.LP +.IN "XMappingEvent" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + int type; /* MappingNotify */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window window; /* unused */ + int request; /* one of MappingModifier, MappingKeyboard, + MappingPointer */ + int first_keycode; /* first keycode */ + int count; /* defines range of change w. first_keycode*/ +} XMappingEvent; +.De +.LP +.eM +The request member is set to indicate the kind of mapping change that occurred +and can be +.PN MappingModifier , +.PN MappingKeyboard , +or +.PN MappingPointer . +If it is +.PN MappingModifier , +the modifier mapping was changed. +If it is +.PN MappingKeyboard , +the keyboard mapping was changed. +If it is +.PN MappingPointer , +the pointer button mapping was changed. +The first_keycode and count members are set only +if the request member was set to +.PN MappingKeyboard . +The number in first_keycode represents the first number in the range +of the altered mapping, +and count represents the number of keycodes altered. +.LP +To update the client application's knowledge of the keyboard, +you should call +.PN XRefreshKeyboardMapping . +.NH 3 +ReparentNotify Events +.XS +\*(SN ReparentNotify Events +.XE +.LP +.IN "Events" "ReparentNotify" +.IN "ReparentNotify" "" "@DEF@" +The X server can report +.PN ReparentNotify +events to clients wanting information about changing a window's parent. +The X server generates this event whenever a client +application calls +.PN XReparentWindow +and the window is actually reparented. +.LP +To receive +.PN ReparentNotify +events, set the +.PN StructureNotifyMask +bit in the event-mask attribute of the window or the +.PN SubstructureNotifyMask +bit in the event-mask attribute of either the old or the new parent window +(in which case, reparenting any child generates an event). +.LP +The structure for this event type contains: +.LP +.IN "XReparentEvent" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + int type; /* ReparentNotify */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window event; + Window window; + Window parent; + int x, y; + Bool override_redirect; +} XReparentEvent; +.De +.LP +.eM +The event member is set either to the reparented window +or to the old or the new parent, depending on whether +.PN StructureNotify +or +.PN SubstructureNotify +was selected. +The window member is set to the window that was reparented. +The parent member is set to the new parent window. +The x and y members are set to the reparented window's coordinates relative +to the new parent window's +origin and define the upper-left outer corner of the reparented window. +The override_redirect member is set to the override-redirect attribute of the +window specified by the window member. +Window manager clients normally should ignore this window +if the override_redirect member is +.PN True . +.NH 3 +UnmapNotify Events +.XS +\*(SN UnmapNotify Events +.XE +.LP +.IN "Events" "UnmapNotify" +.IN "UnmapNotify" "" "@DEF@" +The X server can report +.PN UnmapNotify +events to clients wanting information about which windows are unmapped. +The X server generates this event type whenever a client application changes the +window's state from mapped to unmapped. +.LP +To receive +.PN UnmapNotify +events, set the +.PN StructureNotifyMask +bit in the event-mask attribute of the window or the +.PN SubstructureNotifyMask +bit in the event-mask attribute of the parent window +(in which case, unmapping any child window generates an event). +.LP +The structure for this event type contains: +.LP +.IN "XUnmapEvent" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + int type; /* UnmapNotify */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window event; + Window window; + Bool from_configure; +} XUnmapEvent; +.De +.LP +.eM +The event member is set either to the unmapped window or to its parent, +depending on whether +.PN StructureNotify +or +.PN SubstructureNotify +was selected. +This is the window used by the X server to report the event. +The window member is set to the window that was unmapped. +The from_configure member is set to +.PN True +if the event was generated as a result of a resizing of the window's parent when +the window itself had a win_gravity of +.PN UnmapGravity . +.NH 3 +VisibilityNotify Events +.XS +\*(SN VisibilityNotify Events +.XE +.LP +.IN "Events" "VisibilityNotify" +.IN "VisibilityNotify" "" "@DEF@" +The X server can report +.PN VisibilityNotify +events to clients wanting any change in the visibility of the specified window. +A region of a window is visible if someone looking at the screen can +actually see it. +The X server generates this event whenever the visibility changes state. +However, this event is never generated for windows whose class is +.PN InputOnly . +.LP +All +.PN VisibilityNotify +events caused by a hierarchy change are generated +after any hierarchy event +.Pn ( UnmapNotify , +.PN MapNotify , +.PN ConfigureNotify , +.PN GravityNotify , +.PN CirculateNotify ) +caused by that change. Any +.PN VisibilityNotify +event on a given window is generated before any +.PN Expose +events on that window, but it is not required that all +.PN VisibilityNotify +events on all windows be generated before all +.PN Expose +events on all windows. +The X protocol does not constrain the ordering of +.PN VisibilityNotify +events with +respect to +.PN FocusOut , +.PN EnterNotify , +and +.PN LeaveNotify +events. +.LP +To receive +.PN VisibilityNotify +events, set the +.PN VisibilityChangeMask +bit in the event-mask attribute of the window. +.LP +The structure for this event type contains: +.LP +.IN "XVisibilityEvent" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + int type; /* VisibilityNotify */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window window; + int state; +} XVisibilityEvent; +.De +.LP +.eM +The window member is set to the window whose visibility state changes. +The state member is set to the state of the window's visibility and can be +.PN VisibilityUnobscured , +.PN VisibilityPartiallyObscured , +or +.PN VisibilityFullyObscured . +The X server ignores all of a window's subwindows +when determining the visibility state of the window and processes +.PN VisibilityNotify +events according to the following: +.IP \(bu 5 +When the window changes state from partially obscured, fully obscured, +or not viewable to viewable and completely unobscured, +the X server generates the event with the state member of the +.PN XVisibilityEvent +structure set to +.PN VisibilityUnobscured . +.IP \(bu 5 +When the window changes state from viewable and completely unobscured or +not viewable to viewable and partially obscured, +the X server generates the event with the state member of the +.PN XVisibilityEvent +structure set to +.PN VisibilityPartiallyObscured . +.IP \(bu 5 +When the window changes state from viewable and completely unobscured, +viewable and partially obscured, or not viewable to viewable and +fully obscured, +the X server generates the event with the state member of the +.PN XVisibilityEvent +structure set to +.PN VisibilityFullyObscured . +.NH 2 +Structure Control Events +.XS +\*(SN Structure Control Events +.XE +.LP +This section discusses: +.IP \(bu 5 +.PN CirculateRequest +events +.IP \(bu 5 +.PN ConfigureRequest +events +.IP \(bu 5 +.PN MapRequest +events +.IP \(bu 5 +.PN ResizeRequest +events +.NH 3 +CirculateRequest Events +.XS +\*(SN CirculateRequest Events +.XE +.LP +.IN "Events" "CirculateRequest" +.IN "CirculateRequest" "" "@DEF@" +The X server can report +.PN CirculateRequest +events to clients wanting information about +when another client initiates a circulate window request +on a specified window. +The X server generates this event type whenever a client initiates a circulate +window request on a window and a subwindow actually needs to be restacked. +The client initiates a circulate window request on the window by calling +.PN XCirculateSubwindows , +.PN XCirculateSubwindowsUp , +or +.PN XCirculateSubwindowsDown . +.LP +To receive +.PN CirculateRequest +events, set the +.PN SubstructureRedirectMask +in the event-mask attribute of the window. +Then, in the future, +the circulate window request for the specified window is not executed, +and thus, any subwindow's position in the stack is not changed. +For example, suppose a client application calls +.PN XCirculateSubwindowsUp +to raise a subwindow to the top of the stack. +If you had selected +.PN SubstructureRedirectMask +on the window, the X server reports to you a +.PN CirculateRequest +event and does not raise the subwindow to the top of the stack. +.LP +The structure for this event type contains: +.LP +.IN "XCirculateRequestEvent" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + int type; /* CirculateRequest */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window parent; + Window window; + int place; /* PlaceOnTop, PlaceOnBottom */ +} XCirculateRequestEvent; +.De +.LP +.eM +The parent member is set to the parent window. +The window member is set to the subwindow to be restacked. +The place member is set to what the new position in the stacking order should be +and is either +.PN PlaceOnTop +or +.PN PlaceOnBottom . +If it is +.PN PlaceOnTop , +the subwindow should be on top of all siblings. +If it is +.PN PlaceOnBottom , +the subwindow should be below all siblings. +.NH 3 +ConfigureRequest Events +.XS +\*(SN ConfigureRequest Events +.XE +.LP +.IN "Events" "ConfigureRequest" +.IN "ConfigureRequest" "" "@DEF@" +The X server can report +.PN ConfigureRequest +events to clients wanting information about when a different client initiates +a configure window request on any child of a specified window. +The configure window request attempts to +reconfigure a window's size, position, border, and stacking order. +The X server generates this event whenever a different client initiates +a configure window request on a window by calling +.PN XConfigureWindow , +.PN XLowerWindow , +.PN XRaiseWindow , +.PN XMapRaised , +.PN XMoveResizeWindow , +.PN XMoveWindow , +.PN XResizeWindow , +.PN XRestackWindows , +or +.PN XSetWindowBorderWidth . +.LP +To receive +.PN ConfigureRequest +events, set the +.PN SubstructureRedirectMask +bit in the event-mask attribute of the window. +.PN ConfigureRequest +events are generated when a +.PN ConfigureWindow +protocol request is issued on a child window by another client. +For example, suppose a client application calls +.PN XLowerWindow +to lower a window. +If you had selected +.PN SubstructureRedirectMask +on the parent window and if the override-redirect attribute +of the window is set to +.PN False , +the X server reports a +.PN ConfigureRequest +event to you and does not lower the specified window. +.LP +The structure for this event type contains: +.LP +.IN "XConfigureRequestEvent" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + int type; /* ConfigureRequest */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window parent; + Window window; + int x, y; + int width, height; + int border_width; + Window above; + int detail; /* Above, Below, TopIf, BottomIf, Opposite */ + unsigned long value_mask; +} XConfigureRequestEvent; +.De +.LP +.eM +The parent member is set to the parent window. +The window member is set to the window whose size, position, border width, +and/or stacking order is to be reconfigured. +The value_mask member indicates which components were specified in the +.PN ConfigureWindow +protocol request. +The corresponding values are reported as given in the request. +The remaining values are filled in from the current geometry of the window, +except in the case of above (sibling) and detail (stack-mode), +which are reported as +.PN None +and +.PN Above , +respectively, if they are not given in the request. +.NH 3 +MapRequest Events +.XS +\*(SN MapRequest Events +.XE +.LP +.IN "Events" "MapRequest" +.IN "MapRequest" "" "@DEF@" +The X server can report +.PN MapRequest +events to clients wanting information about a different client's desire +to map windows. +A window is considered mapped when a map window request completes. +The X server generates this event whenever a different client initiates +a map window request on an unmapped window whose override_redirect member +is set to +.PN False . +Clients initiate map window requests by calling +.PN XMapWindow , +.PN XMapRaised , +or +.PN XMapSubwindows . +.LP +To receive +.PN MapRequest +events, set the +.PN SubstructureRedirectMask +bit in the event-mask attribute of the window. +This means another client's attempts to map a child window by calling one of +the map window request functions is intercepted, and you are sent a +.PN MapRequest +instead. +For example, suppose a client application calls +.PN XMapWindow +to map a window. +If you (usually a window manager) had selected +.PN SubstructureRedirectMask +on the parent window and if the override-redirect attribute +of the window is set to +.PN False , +the X server reports a +.PN MapRequest +event to you +and does not map the specified window. +Thus, this event gives your window manager client the ability +to control the placement of subwindows. +.LP +The structure for this event type contains: +.LP +.IN "XMapRequestEvent" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + int type; /* MapRequest */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window parent; + Window window; +} XMapRequestEvent; +.De +.LP +.eM +The parent member is set to the parent window. +The window member is set to the window to be mapped. +.NH 3 +ResizeRequest Events +.XS +\*(SN ResizeRequest Events +.XE +.LP +.IN "Events" "ResizeRequest" +.IN "ResizeRequest" "" "@DEF@" +The X server can report +.PN ResizeRequest +events to clients wanting information about another client's attempts to change the +size of a window. +The X server generates this event whenever some other client attempts to change +the size of the specified window by calling +.PN XConfigureWindow , +.PN XResizeWindow , +or +.PN XMoveResizeWindow . +.LP +To receive +.PN ResizeRequest +events, set the +.PN ResizeRedirect +bit in the event-mask attribute of the window. +Any attempts to change the size by other clients are then redirected. +.LP +The structure for this event type contains: +.LP +.IN "XResizeRequestEvent" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + int type; /* ResizeRequest */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window window; + int width, height; +} XResizeRequestEvent; +.De +.LP +.eM +The window member is set to the window whose size another +client attempted to change. +The width and height members are set to the inside size of the window, +excluding the border. +.NH 2 +Colormap State Change Events +.XS +\*(SN Colormap State Change Events +.XE +.LP +.IN "Events" "ColormapNotify" +.IN "ColormapNotify" "" "@DEF@" +The X server can report +.PN ColormapNotify +events to clients wanting information about when the colormap changes +and when a colormap is installed or uninstalled. +The X server generates this event type whenever a client application: +.IP \(bu 5 +Changes the colormap member of the +.PN XSetWindowAttributes +structure by +calling +.PN XChangeWindowAttributes , +.PN XFreeColormap , +or +.PN XSetWindowColormap +.IP \(bu 5 +Installs or uninstalls the colormap by calling +.PN XInstallColormap +or +.PN XUninstallColormap +.LP +To receive +.PN ColormapNotify +events, set the +.PN ColormapChangeMask +bit in the event-mask attribute of the window. +.LP +The structure for this event type contains: +.LP +.IN "XColormapEvent" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + int type; /* ColormapNotify */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window window; + Colormap colormap; /* colormap or None */ + Bool new; + int state; /* ColormapInstalled, ColormapUninstalled */ +} XColormapEvent; +.De +.LP +.eM +The window member is set to the window whose associated +colormap is changed, installed, or uninstalled. +For a colormap that is changed, installed, or uninstalled, +the colormap member is set to the colormap associated with the window. +For a colormap that is changed by a call to +.PN XFreeColormap , +the colormap member is set to +.PN None . +The new member is set to indicate whether the colormap +for the specified window was changed or installed or uninstalled +and can be +.PN True +or +.PN False . +If it is +.PN True , +the colormap was changed. +If it is +.PN False , +the colormap was installed or uninstalled. +The state member is always set to indicate whether the colormap is installed or +uninstalled and can be +.PN ColormapInstalled +or +.PN ColormapUninstalled . +.NH 2 +Client Communication Events +.XS +\*(SN Client Communication Events +.XE +.LP +This section discusses: +.IP \(bu 5 +.PN ClientMessage +events +.IP \(bu 5 +.PN PropertyNotify +events +.IP \(bu 5 +.PN SelectionClear +events +.IP \(bu 5 +.PN SelectionNotify +events +.IP \(bu 5 +.PN SelectionRequest +events +.NH 3 +ClientMessage Events +.XS +\*(SN ClientMessage Events +.XE +.LP +.IN "Events" "ClientMessage" +.IN "ClientMessage" "" "@DEF@" +The X server generates +.PN ClientMessage +events only when a client calls the function +.PN XSendEvent . +.LP +The structure for this event type contains: +.LP +.IN "XClientMessageEvent" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 1i 3i +.ta .5i 1i 3i +typedef struct { + int type; /* ClientMessage */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window window; + Atom message_type; + int format; + union { + char b[20]; + short s[10]; + long l[5]; + } data; +} XClientMessageEvent; +.De +.LP +.eM +The message_type member is set to an atom that indicates how the data +should be interpreted by the receiving client. +The format member is set to 8, 16, or 32 and specifies whether the data +should be viewed as a list of bytes, shorts, or longs. +The data member is a union that contains the members b, s, and l. +The b, s, and l members represent data of twenty 8-bit values, +ten 16-bit values, and five 32-bit values. +Particular message types might not make use of all these values. +The X server places no interpretation on the values in the window, +message_type, or data members. +.NH 3 +PropertyNotify Events +.XS +\*(SN PropertyNotify Events +.XE +.LP +.IN "Events" "PropertyNotify" +.IN "PropertyNotify" "" "@DEF@" +The X server can report +.PN PropertyNotify +events to clients wanting information about property changes +for a specified window. +.LP +To receive +.PN PropertyNotify +events, set the +.PN PropertyChangeMask +bit in the event-mask attribute of the window. +.LP +The structure for this event type contains: +.LP +.IN "XPropertyEvent" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + int type; /* PropertyNotify */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window window; + Atom atom; + Time time; + int state; /* PropertyNewValue or PropertyDelete */ +} XPropertyEvent; +.De +.LP +.eM +The window member is set to the window whose associated +property was changed. +The atom member is set to the property's atom and indicates which +property was changed or desired. +The time member is set to the server time when the property was changed. +The state member is set to indicate whether the property was changed +to a new value or deleted and can be +.PN PropertyNewValue +or +.PN PropertyDelete . +The state member is set to +.PN PropertyNewValue +when a property of the window is changed using +.PN XChangeProperty +or +.PN XRotateWindowProperties +(even when adding zero-length data using +.PN XChangeProperty ) +and when replacing all or part of a property with identical data using +.PN XChangeProperty +or +.PN XRotateWindowProperties . +The state member is set to +.PN PropertyDelete +when a property of the window is deleted using +.PN XDeleteProperty +or, if the delete argument is +.PN True , +.PN XGetWindowProperty . +.NH 3 +SelectionClear Events +.XS +\*(SN SelectionClear Events +.XE +.LP +.IN "Events" "SelectionClear" +.IN "SelectionClear" "" "@DEF@" +The X server reports +.PN SelectionClear +events to the client losing ownership of a selection. +The X server generates this event type when another client +asserts ownership of the selection by calling +.PN XSetSelectionOwner . +.LP +The structure for this event type contains: +.LP +.IN "XSelectionClearEvent" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + int type; /* SelectionClear */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window window; + Atom selection; + Time time; +} XSelectionClearEvent; +.De +.LP +.eM +The selection member is set to the selection atom. +The time member is set to the last change time recorded for the +selection. +The window member is the window that was specified by the current owner +(the owner losing the selection) in its +.PN XSetSelectionOwner +call. +.NH 3 +SelectionRequest Events +.XS +\*(SN SelectionRequest Events +.XE +.LP +.IN "Events" "SelectionRequest" +.IN "SelectionRequest" "" "@DEF@" +The X server reports +.PN SelectionRequest +events to the owner of a selection. +The X server generates this event whenever a client +requests a selection conversion by calling +.PN XConvertSelection +for the owned selection. +.LP +The structure for this event type contains: +.LP +.IN "XSelectionRequestEvent" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + int type; /* SelectionRequest */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window owner; + Window requestor; + Atom selection; + Atom target; + Atom property; + Time time; +} XSelectionRequestEvent; +.De +.LP +.eM +The owner member is set to the window +that was specified by the current owner in its +.PN XSetSelectionOwner +call. +The requestor member is set to the window requesting the selection. +The selection member is set to the atom that names the selection. +For example, PRIMARY is used to indicate the primary selection. +The target member is set to the atom that indicates the type +the selection is desired in. +The property member can be a property name or +.PN None . +The time member is set to the timestamp or +.PN CurrentTime +value from the +.PN ConvertSelection +request. +.LP +The owner should convert the selection based on the specified target type +and send a +.PN SelectionNotify +event back to the requestor. +A complete specification for using selections is given in the X Consortium +standard \fIInter-Client Communication Conventions Manual\fP. +.NH 3 +SelectionNotify Events +.XS +\*(SN SelectionNotify Events +.XE +.LP +.IN "Events" "SelectionNotify" +.IN "SelectionNotify" "" "@DEF@" +This event is generated by the X server in response to a +.PN ConvertSelection +protocol request when there is no owner for the selection. +When there is an owner, it should be generated by the owner +of the selection by using +.PN XSendEvent . +The owner of a selection should send this event to a requestor when a selection +has been converted and stored as a property +or when a selection conversion could +not be performed (which is indicated by setting the property member to +.PN None ). +.LP +If +.PN None +is specified as the property in the +.PN ConvertSelection +protocol request, the owner should choose a property name, +store the result as that property on the requestor window, +and then send a +.PN SelectionNotify +giving that actual property name. +.LP +The structure for this event type contains: +.LP +.IN "XSelectionEvent" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + int type; /* SelectionNotify */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window requestor; + Atom selection; + Atom target; + Atom property; /* atom or None */ + Time time; +} XSelectionEvent; +.De +.LP +.eM +The requestor member is set to the window associated with +the requestor of the selection. +The selection member is set to the atom that indicates the selection. +For example, PRIMARY is used for the primary selection. +The target member is set to the atom that indicates the converted type. +For example, PIXMAP is used for a pixmap. +The property member is set to the atom that indicates which +property the result was stored on. +If the conversion failed, +the property member is set to +.PN None . +The time member is set to the time the conversion took place and +can be a timestamp or +.PN CurrentTime . +.bp diff --git a/libX11/specs/libX11/CH11 b/libX11/specs/libX11/CH11 new file mode 100644 index 000000000..09d845d35 --- /dev/null +++ b/libX11/specs/libX11/CH11 @@ -0,0 +1,1664 @@ +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be included +.\" in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR +.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +.\" OTHER DEALINGS IN THE SOFTWARE. +.\" +.\" Except as contained in this notice, the name of the X Consortium shall +.\" not be used in advertising or otherwise to promote the sale, use or +.\" other dealings in this Software without prior written authorization +.\" from the X Consortium. +.\" +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by +.\" Digital Equipment Corporation +.\" +.\" Portions Copyright \(co 1990, 1991 by +.\" Tektronix, Inc. +.\" +.\" Permission to use, copy, modify and distribute this documentation for +.\" any purpose and without fee is hereby granted, provided that the above +.\" copyright notice appears in all copies and that both that copyright notice +.\" and this permission notice appear in all copies, and that the names of +.\" Digital and Tektronix not be used in in advertising or publicity pertaining +.\" to this documentation without specific, written prior permission. +.\" Digital and Tektronix makes no representations about the suitability +.\" of this documentation for any purpose. +.\" It is provided ``as is'' without express or implied warranty. +.\" +\& +.sp 1 +.ce 3 +\s+1\fBChapter 11\fP\s-1 + +\s+1\fBEvent Handling Functions\fP\s-1 +.sp 2 +.nr H1 11 +.nr H2 0 +.nr H3 0 +.nr H4 0 +.nr H5 0 +.na +.LP +.XS +Chapter 11: Event Handling Functions +.XE +This chapter discusses the Xlib functions you can use to: +.IP \(bu 5 +Select events +.IP \(bu 5 +Handle the output buffer and the event queue +.IP \(bu 5 +Select events from the event queue +.IP \(bu 5 +Send and get events +.IP \(bu 5 +Handle protocol errors +.NT Note +Some toolkits use their own event-handling functions +and do not allow you to interchange these event-handling functions +with those in Xlib. +For further information, +see the documentation supplied with the toolkit. +.NE +.LP +Most applications simply are event loops: +they wait for an event, decide what to do with it, +execute some amount of code that results in changes to the display, +and then wait for the next event. +.NH 2 +Selecting Events +.XS +\*(SN Selecting Events +.XE +.LP +There are two ways to select the events you want reported to your client +application. +One way is to set the event_mask member of the +.PN XSetWindowAttributes +structure when you call +.PN XCreateWindow +and +.PN XChangeWindowAttributes . +Another way is to use +.PN XSelectInput . +.IN "XSelectInput" "" "@DEF@" +.sM +.FD 0 +XSelectInput\^(\^\fIdisplay\fP, \fIw\fP\^, \fIevent_mask\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + long \fIevent_mask\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.ds Wi whose events you are interested in +.IP \fIw\fP 1i +Specifies the window \*(Wi. +.IP \fIevent_mask\fP 1i +Specifies the event mask. +.LP +.eM +The +.PN XSelectInput +function requests that the X server report the events associated with the +specified event mask. +Initially, X will not report any of these events. +Events are reported relative to a window. +If a window is not interested in a device event, it usually propagates to +the closest ancestor that is interested, +unless the do_not_propagate mask prohibits it. +.IN "Event" "propagation" +.LP +Setting the event-mask attribute of a window overrides any previous call +for the same window but not for other clients. +Multiple clients can select for the same events on the same window +with the following restrictions: +.IP \(bu 5 +Multiple clients can select events on the same window because their event masks +are disjoint. +When the X server generates an event, it reports it +to all interested clients. +.IP \(bu 5 +Only one client at a time can select +.PN CirculateRequest , +.PN ConfigureRequest , +or +.PN MapRequest +events, which are associated with +the event mask +.PN SubstructureRedirectMask . +.IP \(bu 5 +Only one client at a time can select +a +.PN ResizeRequest +event, which is associated with +the event mask +.PN ResizeRedirectMask . +.IP \(bu 5 +Only one client at a time can select a +.PN ButtonPress +event, which is associated with +the event mask +.PN ButtonPressMask . +.LP +The server reports the event to all interested clients. +.LP +.PN XSelectInput +can generate a +.PN BadWindow +error. +.NH 2 +Handling the Output Buffer +.XS +\*(SN Handling the Output Buffer +.XE +.LP +The output buffer is an area used by Xlib to store requests. +The functions described in this section flush the output buffer +if the function would block or not return an event. +That is, all requests residing in the output buffer that +have not yet been sent are transmitted to the X server. +These functions differ in the additional tasks they might perform. +.LP +.sp +To flush the output buffer, use +.PN XFlush . +.IN "XFlush" "" "@DEF@" +.sM +.FD 0 +XFlush\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +The +.PN XFlush +function +flushes the output buffer. +Most client applications need not use this function because the output +buffer is automatically flushed as needed by calls to +.PN XPending , +.PN XNextEvent , +and +.PN XWindowEvent . +.IN "XPending" +.IN "XNextEvent" +.IN "XWindowEvent" +Events generated by the server may be enqueued into the library's event queue. +.LP +.sp +To flush the output buffer and then wait until all requests have been processed, +use +.PN XSync . +.IN "XSync" "" "@DEF@" +.sM +.FD 0 +XSync\^(\^\fIdisplay\fP, \fIdiscard\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Bool \fIdiscard\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIdiscard\fP 1i +Specifies a Boolean value that indicates whether +.PN XSync +discards all events on the event queue. +.LP +.eM +The +.PN XSync +function +flushes the output buffer and then waits until all requests have been received +and processed by the X server. +Any errors generated must be handled by the error handler. +For each protocol error received by Xlib, +.PN XSync +calls the client application's error handling routine (see section 11.8.2). +Any events generated by the server are enqueued into the library's +event queue. +.LP +Finally, if you passed +.PN False , +.PN XSync +does not discard the events in the queue. +If you passed +.PN True , +.PN XSync +discards all events in the queue, +including those events that were on the queue before +.PN XSync +was called. +Client applications seldom need to call +.PN XSync . +.NH 2 +Event Queue Management +.XS +\*(SN Event Queue Management +.XE +.LP +Xlib maintains an event queue. +However, the operating system also may be buffering data +in its network connection that is not yet read into the event queue. +.LP +.sp +To check the number of events in the event queue, use +.PN XEventsQueued . +.IN "XEventsQueued" "" "@DEF@" +.sM +.FD 0 +int XEventsQueued\^(\^\fIdisplay\fP, \fImode\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fImode\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fImode\fP 1i +Specifies the mode. +You can pass +.PN QueuedAlready , +.PN QueuedAfterFlush , +or +.PN QueuedAfterReading . +.LP +.eM +If mode is +.PN QueuedAlready , +.PN XEventsQueued +returns the number of events +already in the event queue (and never performs a system call). +If mode is +.PN QueuedAfterFlush , +.PN XEventsQueued +returns the number of events already in the queue if the number is nonzero. +If there are no events in the queue, +.PN XEventsQueued +flushes the output buffer, +attempts to read more events out of the application's connection, +and returns the number read. +If mode is +.PN QueuedAfterReading , +.PN XEventsQueued +returns the number of events already in the queue if the number is nonzero. +If there are no events in the queue, +.PN XEventsQueued +attempts to read more events out of the application's connection +without flushing the output buffer and returns the number read. +.LP +.PN XEventsQueued +always returns immediately without I/O if there are events already in the +queue. +.PN XEventsQueued +with mode +.PN QueuedAfterFlush +is identical in behavior to +.PN XPending . +.PN XEventsQueued +with mode +.PN QueuedAlready +is identical to the +.PN XQLength +function. +.LP +.sp +To return the number of events that are pending, use +.PN XPending . +.IN "XPending" "" "@DEF@" +.sM +.FD 0 +int XPending\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +The +.PN XPending +function returns the number of events that have been received from the +X server but have not been removed from the event queue. +.PN XPending +is identical to +.PN XEventsQueued +with the mode +.PN QueuedAfterFlush +specified. +.NH 2 +Manipulating the Event Queue +.XS +\*(SN Manipulating the Event Queue +.XE +.LP +Xlib provides functions that let you manipulate the event queue. +This section discusses how to: +.IP \(bu 5 +Obtain events, in order, and remove them from the queue +.IP \(bu 5 +Peek at events in the queue without removing them +.IP \(bu 5 +Obtain events that match the event mask or the arbitrary +predicate procedures that you provide +.NH 3 +Returning the Next Event +.XS +\*(SN Returning the Next Event +.XE +.LP +To get the next event and remove it from the queue, use +.PN XNextEvent . +.IN "XNextEvent" "" "@DEF@" +.sM +.FD 0 +XNextEvent\^(\^\fIdisplay\fP, \fIevent_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XEvent *\fIevent_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIevent_return\fP 1i +Returns the next event in the queue. +.LP +.eM +The +.PN XNextEvent +function copies the first event from the event queue into the specified +.PN XEvent +structure and then removes it from the queue. +If the event queue is empty, +.PN XNextEvent +flushes the output buffer and blocks until an event is received. +.LP +.sp +To peek at the event queue, use +.PN XPeekEvent . +.IN "XPeekEvent" "" "@DEF@" +.sM +.FD 0 +XPeekEvent\^(\^\fIdisplay\fP, \fIevent_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XEvent *\fIevent_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIevent_return\fP 1i +Returns a copy of the matched event's associated structure. +.LP +.eM +The +.PN XPeekEvent +function returns the first event from the event queue, +but it does not remove the event from the queue. +If the queue is empty, +.PN XPeekEvent +flushes the output buffer and blocks until an event is received. +It then copies the event into the client-supplied +.PN XEvent +structure without removing it from the event queue. +.NH 3 +Selecting Events Using a Predicate Procedure +.XS +\*(SN Selecting Events Using a Predicate Procedure +.XE +.LP +Each of the functions discussed in this section requires you to +pass a predicate procedure that determines if an event matches +what you want. +Your predicate procedure must decide if the event is useful +without calling any Xlib functions. +If the predicate directly or indirectly causes the state of the event queue +to change, the result is not defined. +If Xlib has been initialized for threads, the predicate is called with +the display locked and the result of a call by the predicate to any +Xlib function that locks the display is not defined unless the caller +has first called +.PN XLockDisplay . +.LP +The predicate procedure and its associated arguments are: +.sM +.FD 0 +Bool (\^*\fIpredicate\fP\^)\^(\^\fIdisplay\fP, \fIevent\fP, \fIarg\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XEvent *\fIevent\fP\^; +.br + XPointer \fIarg\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIevent\fP 1i +Specifies the +.PN XEvent +structure. +.IP \fIarg\fP 1i +Specifies the argument passed in from the +.PN XIfEvent , +.PN XCheckIfEvent , +or +.PN XPeekIfEvent +function. +.LP +.eM +The predicate procedure is called once for each +event in the queue until it finds a match. +After finding a match, the predicate procedure must return +.PN True . +If it did not find a match, it must return +.PN False . +.LP +.sp +To check the event queue for a matching event +and, if found, remove the event from the queue, use +.PN XIfEvent . +.IN "XIfEvent" "" "@DEF@" +.sM +.FD 0 +XIfEvent\^(\^\fIdisplay\fP, \fIevent_return\fP, \fIpredicate\fP, \fIarg\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XEvent *\fIevent_return\fP\^; +.br + Bool (\^*\fIpredicate\fP\^)\^(\^)\^; +.br + XPointer \fIarg\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIevent_return\fP 1i +Returns the matched event's associated structure. +.IP \fIpredicate\fP 1i +Specifies the procedure that is to be called to determine +if the next event in the queue matches what you want. +.IP \fIarg\fP 1i +Specifies the user-supplied argument that will be passed to the predicate procedure. +.LP +.eM +The +.PN XIfEvent +function completes only when the specified predicate +procedure returns +.PN True +for an event, +which indicates an event in the queue matches. +.PN XIfEvent +flushes the output buffer if it blocks waiting for additional events. +.PN XIfEvent +removes the matching event from the queue +and copies the structure into the client-supplied +.PN XEvent +structure. +.LP +.sp +To check the event queue for a matching event without blocking, use +.PN XCheckIfEvent . +.IN "XCheckIfEvent" "" "@DEF@" +.sM +.FD 0 +Bool XCheckIfEvent\^(\^\fIdisplay\fP, \fIevent_return\fP, \fIpredicate\fP, \fIarg\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XEvent *\fIevent_return\fP\^; +.br + Bool (\^*\fIpredicate\fP\^)\^(\^)\^; +.br + XPointer \fIarg\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIevent_return\fP 1i +Returns a copy of the matched event's associated structure. +.IP \fIpredicate\fP 1i +Specifies the procedure that is to be called to determine +if the next event in the queue matches what you want. +.IP \fIarg\fP 1i +Specifies the user-supplied argument that will be passed to the predicate procedure. +.LP +.eM +When the predicate procedure finds a match, +.PN XCheckIfEvent +copies the matched event into the client-supplied +.PN XEvent +structure and returns +.PN True . +(This event is removed from the queue.) +If the predicate procedure finds no match, +.PN XCheckIfEvent +returns +.PN False , +and the output buffer will have been flushed. +All earlier events stored in the queue are not discarded. +.LP +.sp +To check the event queue for a matching event +without removing the event from the queue, use +.PN XPeekIfEvent . +.IN "XPeekIfEvent" "" "@DEF@" +.sM +.FD 0 +XPeekIfEvent\^(\^\fIdisplay\fP, \fIevent_return\fP, \fIpredicate\fP, \fIarg\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XEvent *\fIevent_return\fP\^; +.br + Bool (\^*\fIpredicate\fP\^)\^(\^)\^; +.br + XPointer \fIarg\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIevent_return\fP 1i +Returns a copy of the matched event's associated structure. +.IP \fIpredicate\fP 1i +Specifies the procedure that is to be called to determine +if the next event in the queue matches what you want. +.IP \fIarg\fP 1i +Specifies the user-supplied argument that will be passed to the predicate procedure. +.LP +.eM +The +.PN XPeekIfEvent +function returns only when the specified predicate +procedure returns +.PN True +for an event. +After the predicate procedure finds a match, +.PN XPeekIfEvent +copies the matched event into the client-supplied +.PN XEvent +structure without removing the event from the queue. +.PN XPeekIfEvent +flushes the output buffer if it blocks waiting for additional events. +.NH 3 +Selecting Events Using a Window or Event Mask +.XS +\*(SN Selecting Events Using a Window or Event Mask +.XE +.LP +The functions discussed in this section let you select events by window +or event types, allowing you to process events out of order. +.LP +.sp +To remove the next event that matches both a window and an event mask, use +.PN XWindowEvent . +.IN "XWindowEvent" "" "@DEF@" +.sM +.FD 0 +XWindowEvent\^(\^\fIdisplay\fP, \fIw\fP\^, \fIevent_mask\fP\^, \fIevent_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + long \fIevent_mask\fP\^; +.br + XEvent *\fIevent_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.ds Wi whose events you are interested in +.IP \fIw\fP 1i +Specifies the window \*(Wi. +.IP \fIevent_mask\fP 1i +Specifies the event mask. +.IP \fIevent_return\fP 1i +Returns the matched event's associated structure. +.LP +.eM +The +.PN XWindowEvent +function searches the event queue for an event that matches both the specified +window and event mask. +When it finds a match, +.PN XWindowEvent +removes that event from the queue and copies it into the specified +.PN XEvent +structure. +The other events stored in the queue are not discarded. +If a matching event is not in the queue, +.PN XWindowEvent +flushes the output buffer and blocks until one is received. +.LP +.sp +To remove the next event that matches both a window and an event mask (if any), +use +.PN XCheckWindowEvent . +.IN "XCheckWindowEvent" +This function is similar to +.PN XWindowEvent +except that it never blocks and it returns a +.PN Bool +indicating if the event was returned. +.IN "XCheckWindowEvent" "" "@DEF@" +.sM +.FD 0 +Bool XCheckWindowEvent\^(\^\fIdisplay\fP, \fIw\fP\^, \fIevent_mask\fP\^, \fIevent_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + long \fIevent_mask\fP\^; +.br + XEvent *\fIevent_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.ds Wi whose events you are interested in +.IP \fIw\fP 1i +Specifies the window \*(Wi. +.IP \fIevent_mask\fP 1i +Specifies the event mask. +.IP \fIevent_return\fP 1i +Returns the matched event's associated structure. +.LP +.eM +The +.PN XCheckWindowEvent +function searches the event queue and then the events available +on the server connection for the first event that matches the specified window +and event mask. +If it finds a match, +.PN XCheckWindowEvent +removes that event, copies it into the specified +.PN XEvent +structure, and returns +.PN True . +The other events stored in the queue are not discarded. +If the event you requested is not available, +.PN XCheckWindowEvent +returns +.PN False , +and the output buffer will have been flushed. +.LP +.sp +To remove the next event that matches an event mask, use +.PN XMaskEvent . +.IN "XMaskEvent" "" "@DEF@" +.sM +.FD 0 +XMaskEvent\^(\^\fIdisplay\fP, \fIevent_mask\fP\^, \fIevent_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + long \fIevent_mask\fP\^; +.br + XEvent *\fIevent_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIevent_mask\fP 1i +Specifies the event mask. +.IP \fIevent_return\fP 1i +Returns the matched event's associated structure. +.LP +.eM +The +.PN XMaskEvent +function searches the event queue for the events associated with the +specified mask. +When it finds a match, +.PN XMaskEvent +removes that event and copies it into the specified +.PN XEvent +structure. +The other events stored in the queue are not discarded. +If the event you requested is not in the queue, +.PN XMaskEvent +flushes the output buffer and blocks until one is received. +.LP +.sp +To return and remove the next event that matches an event mask (if any), use +.PN XCheckMaskEvent . +This function is similar to +.PN XMaskEvent +except that it never blocks and it returns a +.PN Bool +indicating if the event was returned. +.IN "XCheckMaskEvent" "" "@DEF@" +.sM +.FD 0 +Bool XCheckMaskEvent\^(\^\fIdisplay\fP, \fIevent_mask\fP\^, \fIevent_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + long \fIevent_mask\fP\^; +.br + XEvent *\fIevent_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIevent_mask\fP 1i +Specifies the event mask. +.IP \fIevent_return\fP 1i +Returns the matched event's associated structure. +.LP +.eM +The +.PN XCheckMaskEvent +function searches the event queue and then any events available on the +server connection for the first event that matches the specified mask. +If it finds a match, +.PN XCheckMaskEvent +removes that event, copies it into the specified +.PN XEvent +structure, and returns +.PN True . +The other events stored in the queue are not discarded. +If the event you requested is not available, +.PN XCheckMaskEvent +returns +.PN False , +and the output buffer will have been flushed. +.LP +.sp +To return and remove the next event in the queue that matches an event type, use +.PN XCheckTypedEvent . +.IN "XCheckTypedEvent" "" "@DEF@" +.sM +.FD 0 +Bool XCheckTypedEvent\^(\^\fIdisplay\fP, \fIevent_type\fP\^, \fIevent_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIevent_type\fP\^; +.br + XEvent *\fIevent_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIevent_type\fP 1i +Specifies the event type to be compared. + +.IP \fIevent_return\fP 1i +Returns the matched event's associated structure. +.LP +.eM +The +.PN XCheckTypedEvent +function searches the event queue and then any events available +on the server connection for the first event that matches the specified type. +If it finds a match, +.PN XCheckTypedEvent +removes that event, copies it into the specified +.PN XEvent +structure, and returns +.PN True . +The other events in the queue are not discarded. +If the event is not available, +.PN XCheckTypedEvent +returns +.PN False , +and the output buffer will have been flushed. +.LP +.sp +To return and remove the next event in the queue that matches an event type +and a window, use +.PN XCheckTypedWindowEvent . +.IN "XCheckTypedWindowEvent" "" "@DEF@" +.sM +.FD 0 +Bool XCheckTypedWindowEvent\^(\^\fIdisplay\fP, \fIw\fP\^, \fIevent_type\fP\^, \fIevent_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + int \fIevent_type\fP\^; +.br + XEvent *\fIevent_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIevent_type\fP 1i +Specifies the event type to be compared. + +.IP \fIevent_return\fP 1i +Returns the matched event's associated structure. +.LP +.eM +The +.PN XCheckTypedWindowEvent +function searches the event queue and then any events available +on the server connection for the first event that matches the specified +type and window. +If it finds a match, +.PN XCheckTypedWindowEvent +removes the event from the queue, copies it into the specified +.PN XEvent +structure, and returns +.PN True . +The other events in the queue are not discarded. +If the event is not available, +.PN XCheckTypedWindowEvent +returns +.PN False , +and the output buffer will have been flushed. +.NH 2 +Putting an Event Back into the Queue +.XS +\*(SN Putting an Event Back into the Queue +.XE +.LP +To push an event back into the event queue, use +.PN XPutBackEvent . +.IN "XPutBackEvent" "" "@DEF@" +.sM +.FD 0 +XPutBackEvent\^(\^\fIdisplay\fP, \fIevent\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XEvent *\fIevent\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIevent\fP 1i +Specifies the event. +.LP +.eM +The +.PN XPutBackEvent +function pushes an event back onto the head of the display's event queue +by copying the event into the queue. +This can be useful if you read an event and then decide that you +would rather deal with it later. +There is no limit to the number of times in succession that you can call +.PN XPutBackEvent . +.NH 2 +Sending Events to Other Applications +.XS +\*(SN Sending Events to Other Applications +.XE +.LP +To send an event to a specified window, use +.PN XSendEvent . +.IN "XSendEvent" +This function is often used in selection processing. +For example, the owner of a selection should use +.PN XSendEvent +to send a +.PN SelectionNotify +event to a requestor when a selection has been converted +and stored as a property. +.IN "XSendEvent" "" "@DEF@" +.sM +.FD 0 +Status XSendEvent\^(\^\fIdisplay\fP, \fIw\fP\^, \fIpropagate\fP\^, \fIevent_mask\fP\^, \fIevent_send\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + Bool \fIpropagate\fP\^; +.br + long \fIevent_mask\fP\^; +.br + XEvent *\fIevent_send\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window the event is to be sent to, or +.PN PointerWindow , +or +.PN InputFocus . +.IP \fIpropagate\fP 1i +Specifies a Boolean value. +.IP \fIevent_mask\fP 1i +Specifies the event mask. +.IP \fIevent_send\fP 1i +Specifies the event that is to be sent. +.LP +.eM +The +.PN XSendEvent +function identifies the destination window, +determines which clients should receive the specified events, +and ignores any active grabs. +This function requires you to pass an event mask. +For a discussion of the valid event mask names, +see section 10.3. +This function uses the w argument to identify the destination window as follows: +.IP \(bu 5 +If w is +.PN PointerWindow , +the destination window is the window that contains the pointer. +.IP \(bu 5 +If w is +.PN InputFocus +and if the focus window contains the pointer, +the destination window is the window that contains the pointer; +otherwise, the destination window is the focus window. +.LP +To determine which clients should receive the specified events, +.PN XSendEvent +uses the propagate argument as follows: +.IP \(bu 5 +If event_mask is the empty set, +the event is sent to the client that created the destination window. +If that client no longer exists, +no event is sent. +.IP \(bu 5 +If propagate is +.PN False , +the event is sent to every client selecting on destination any of the event +types in the event_mask argument. +.IP \(bu 5 +If propagate is +.PN True +and no clients have selected on destination any of +the event types in event-mask, the destination is replaced with the +closest ancestor of destination for which some client has selected a +type in event-mask and for which no intervening window has that type in its +do-not-propagate-mask. +If no such window exists or if the window is +an ancestor of the focus window and +.PN InputFocus +was originally specified +as the destination, the event is not sent to any clients. +Otherwise, the event is reported to every client selecting on the final +destination any of the types specified in event_mask. +.LP +The event in the +.PN XEvent +structure must be one of the core events or one of the events +defined by an extension (or a +.PN BadValue +error results) so that the X server can correctly byte-swap +the contents as necessary. +The contents of the event are +otherwise unaltered and unchecked by the X server except to force send_event to +.PN True +in the forwarded event and to set the serial number in the event correctly; +therefore these fields +and the display field are ignored by +.PN XSendEvent . +.LP +.PN XSendEvent +returns zero if the conversion to wire protocol format failed +and returns nonzero otherwise. +.LP +.PN XSendEvent +can generate +.PN BadValue +and +.PN BadWindow +errors. +.NH 2 +Getting Pointer Motion History +.XS +\*(SN Getting Pointer Motion History +.XE +.LP +Some X server implementations will maintain a more complete +history of pointer motion than is reported by event notification. +The pointer position at each pointer hardware interrupt may be +stored in a buffer for later retrieval. +This buffer is called the motion history buffer. +For example, a few applications, such as paint programs, +want to have a precise history of where the pointer +traveled. +However, this historical information is highly excessive for most applications. +.LP +.sp +To determine the approximate maximum number of elements in the motion buffer, +use +.PN XDisplayMotionBufferSize . +.IN "XDisplayMotionBufferSize" "" "@DEF@" +.sM +.FD 0 +unsigned long XDisplayMotionBufferSize\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +The server may retain the recent history of the pointer motion +and do so to a finer granularity than is reported by +.PN MotionNotify +events. +The +.PN XGetMotionEvents +function makes this history available. +.LP +.sp +To get the motion history for a specified window and time, use +.PN XGetMotionEvents . +.IN "XGetMotionEvents" "" "@DEF@" +.sM +.FD 0 +XTimeCoord *XGetMotionEvents\^(\^\fIdisplay\fP, \fIw\fP\^, \fIstart\fP\^, \fIstop\fP\^, \fInevents_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + Time \fIstart\fP\^, \fIstop\fP\^; +.br + int *\fInevents_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIstart\fP 1i +.br +.ns +.IP \fIstop\fP 1i +Specify the time interval in which the events are returned from the motion +history buffer. +You can pass a timestamp or +.PN CurrentTime . +.IP \fInevents_return\fP 1i +Returns the number of events from the motion history buffer. +.LP +.eM +The +.PN XGetMotionEvents +function returns all events in the motion history buffer that fall between the +specified start and stop times, inclusive, and that have coordinates +that lie within the specified window (including its borders) at its present +placement. +If the server does not support motion history, +if the start time is later than the stop time, +or if the start time is in the future, +no events are returned; +.PN XGetMotionEvents +returns NULL. +If the stop time is in the future, it is equivalent to specifying +.PN CurrentTime . +The return type for this function is a structure defined as follows: +.LP +.IN "XTimeCoord" "" "@DEF@" +.sM +.Ds 0 +.TA .5i +.ta .5i +typedef struct { + Time time; + short x, y; +} XTimeCoord; +.De +.LP +.eM +The time member is set to the time, in milliseconds. +The x and y members are set to the coordinates of the pointer and +are reported relative to the origin +of the specified window. +To free the data returned from this call, use +.PN XFree . +.LP +.PN XGetMotionEvents +can generate a +.PN BadWindow +error. +.NH 2 +Handling Protocol Errors +.XS +\*(SN Handling Protocol Errors +.XE +.LP +Xlib provides functions that you can use to enable or disable synchronization +and to use the default error handlers. +.NH 3 +Enabling or Disabling Synchronization +.XS +\*(SN Enabling or Disabling Synchronization +.XE +.LP +When debugging X applications, +it often is very convenient to require Xlib to behave synchronously +so that errors are reported as they occur. +The following function lets you disable or enable synchronous behavior. +Note that graphics may occur 30 or more times more slowly when +synchronization is enabled. +.IN "_Xdebug" +On POSIX-conformant systems, +there is also a global variable +.PN _Xdebug +that, if set to nonzero before starting a program under a debugger, will force +synchronous library behavior. +.LP +After completing their work, +all Xlib functions that generate protocol requests call what is known as +an after function. +.PN XSetAfterFunction +sets which function is to be called. +.IN "XSetAfterFunction" "" "@DEF@" +.sM +.FD 0 +int (*XSetAfterFunction\^(\^\fIdisplay\fP, \fIprocedure\fP\^))() +.br + Display *\fIdisplay\fP\^; +.br + int (\^*\^\fIprocedure\fP\^)\^(); +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIprocedure\fP 1i +Specifies the procedure to be called. +.LP +.eM +The specified procedure is called with only a display pointer. +.PN XSetAfterFunction +returns the previous after function. +.LP +To enable or disable synchronization, use +.PN XSynchronize . +.IN "Debugging" "synchronous mode" +.IN "XSynchronize" "" "@DEF@" +.sM +.FD 0 +int (*XSynchronize\^(\^\fIdisplay\fP, \fIonoff\fP\^)\^)() +.br + Display *\fIdisplay\fP\^; +.br + Bool \fIonoff\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIonoff\fP 1i +Specifies a Boolean value that indicates whether to enable +or disable synchronization. +.LP +.eM +The +.PN XSynchronize +function returns +the previous after function. +If onoff is +.PN True , +.PN XSynchronize +turns on synchronous behavior. +If onoff is +.PN False , +.PN XSynchronize +turns off synchronous behavior. +.NH 3 +Using the Default Error Handlers +.XS +\*(SN Using the Default Error Handlers +.XE +.LP +.IN "Debugging" "error handlers" +.IN "Error" "handlers" +There are two default error handlers in Xlib: +one to handle typically fatal conditions (for example, +the connection to a display server dying because a machine crashed) +and one to handle protocol errors from the X server. +These error handlers can be changed to user-supplied routines if you +prefer your own error handling and can be changed as often as you like. +If either function is passed a NULL pointer, it will +reinvoke the default handler. +The action of the default handlers is to print an explanatory +message and exit. +.LP +.sp +To set the error handler, use +.PN XSetErrorHandler . +.IN "XSetErrorHandler" "" "@DEF@" +.sM +.FD 0 +int (*XSetErrorHandler\^(\^\fIhandler\fP\^)\^)\^(\^) +.br + int (\^*\^\fIhandler\fP\^)\^(Display *, XErrorEvent *) +.FN +.IP \fIhandler\fP 1i +Specifies the program's supplied error handler. +.LP +.eM +Xlib generally calls the program's +supplied error handler whenever an error is received. +It is not called on +.PN BadName +errors from +.PN OpenFont , +.PN LookupColor , +or +.PN AllocNamedColor +protocol requests or on +.PN BadFont +errors from a +.PN QueryFont +protocol request. +These errors generally are reflected back to the program through the +procedural interface. +Because this condition is not assumed to be fatal, +it is acceptable for your error handler to return; +the returned value is ignored. +However, the error handler should not +call any functions (directly or indirectly) on the display +that will generate protocol requests or that will look for input events. +The previous error handler is returned. +.LP +The +.PN XErrorEvent +structure contains: +.IN "Debugging" "error event" +.LP +.IN "XErrorEvent" "" "@DEF" +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef struct { + int type; + Display *display; /* Display the event was read from */ + unsigned long serial; /* serial number of failed request */ + unsigned char error_code; /* error code of failed request */ + unsigned char request_code; /* Major op-code of failed request */ + unsigned char minor_code; /* Minor op-code of failed request */ + XID resourceid; /* resource id */ +} XErrorEvent; +.De +.LP +.IN "Serial Number" +The serial member is the number of requests, starting from one, +sent over the network connection since it was opened. +It is the number that was the value of +.PN NextRequest +immediately before the failing call was made. +The request_code member is a protocol request +of the procedure that failed, as defined in +.hN X11/Xproto.h . +The following error codes can be returned by the functions described in this +chapter: +.br +.ne 13 +.IN "Debugging" "error numbers" +.IN "Error" "codes" +.\".CP T 3 +.\"Error Codes +.IN "BadAccess" "" "@DEF@" +.IN "BadAlloc" "" "@DEF@" +.IN "BadAtom" "" "@DEF@" +.IN "BadColor" "" "@DEF@" +.IN "BadCursor" "" "@DEF@" +.IN "BadDrawable" "" "@DEF@" +.IN "BadFont" "" "@DEF@" +.IN "BadGC" "" "@DEF@" +.IN "BadIDChoice" "" "@DEF@" +.TS H +l c +lw(1.75i) lw(4i). +_ +.sp 6p +.B +Error Code Description +.sp 6p +_ +.sp 6p +.TH +.R +T{ +.PN BadAccess +T} T{ +A client attempts to grab a key/button combination already grabbed +by another client. +.sp 3p +A client attempts to free a colormap entry that it had not already allocated +or to free an entry in a colormap that was created with all entries writable. +.sp 3p +A client attempts to store into a read-only or unallocated colormap entry. +.sp 3p +A client attempts to modify the access control list from other than the local +(or otherwise authorized) host. +.sp 3p +A client attempts to select an event type that another client +has already selected. +T} +.sp 3p +T{ +.PN BadAlloc +T} T{ +The server fails to allocate the requested resource. +Note that the explicit listing of +.PN BadAlloc +errors in requests only covers allocation errors at a very coarse level +and is not intended to (nor can it in practice hope to) cover all cases of +a server running out of allocation space in the middle of service. +The semantics when a server runs out of allocation space are left unspecified, +but a server may generate a +.PN BadAlloc +error on any request for this reason, +and clients should be prepared to receive such errors and handle or discard +them. +T} +.sp 3p +T{ +.PN BadAtom +T} T{ +A value for an atom argument does not name a defined atom. +T} +.sp 3p +T{ +.PN BadColor +T} T{ +A value for a colormap argument does not name a defined colormap. +T} +.sp 3p +T{ +.PN BadCursor +T} T{ +A value for a cursor argument does not name a defined cursor. +T} +.sp 3p +T{ +.PN BadDrawable +T} T{ +A value for a drawable argument does not name a defined window or pixmap. +T} +.sp 3p +T{ +.PN BadFont +T} T{ +A value for a font argument does not name a defined font (or, in some cases, +.PN GContext ). +T} +.sp 3p +T{ +.PN BadGC +T} T{ +A value for a +.PN GContext +argument does not name a defined +.PN GContext . +T} +.sp 3p +T{ +.PN BadIDChoice +T} T{ +The value chosen for a resource identifier either is not included in the +range assigned to the client or is already in use. +Under normal circumstances, +this cannot occur and should be considered a server or Xlib error. +T} +.sp 3p +T{ +.PN BadImplementation +T} T{ +The server does not implement some aspect of the request. +A server that generates this error for a core request is deficient. +As such, this error is not listed for any of the requests, +but clients should be prepared to receive such errors +and handle or discard them. +T} +.sp 3p +T{ +.PN BadLength +T} T{ +The length of a request is shorter or longer than that required to +contain the arguments. +This is an internal Xlib or server error. +.sp 3p +The length of a request exceeds the maximum length accepted by the server. +T} +.sp 3p +T{ +.PN BadMatch +T} T{ +In a graphics request, +the root and depth of the graphics context do not match those of the drawable. +.sp 3p +An +.PN InputOnly +window is used as a drawable. +.sp 3p +Some argument or pair of arguments has the correct type and range, +but it fails to match in some other way required by the request. +.sp 3p +An +.PN InputOnly +window lacks this attribute. +T} +.sp 3p +T{ +.PN BadName +T} T{ +A font or color of the specified name does not exist. +T} +.sp 3p +T{ +.PN BadPixmap +T} T{ +A value for a pixmap argument does not name a defined pixmap. +T} +.sp 3p +T{ +.PN BadRequest +T} T{ +The major or minor opcode does not specify a valid request. +This usually is an Xlib or server error. +T} +.sp 3p +T{ +.PN BadValue +T} T{ +Some numeric value falls outside of the range of values accepted +by the request. +Unless a specific range is specified for an argument, +the full range defined by the argument's type is accepted. +Any argument defined as a set of alternatives typically can generate +this error (due to the encoding). +T} +.sp 3p +T{ +.PN BadWindow +T} T{ +A value for a window argument does not name a defined window. +T} +.sp 6p +_ +.TE +.IN "BadImplementation" "" "@DEF@" +.IN "BadLength" "" "@DEF@" +.IN "BadMatch" "" "@DEF@" +.IN "BadName" "" "@DEF@" +.IN "BadPixmap" "" "@DEF@" +.IN "BadRequest" "" "@DEF@" +.IN "BadValue" "" "@DEF@" +.IN "BadWindow" "" "@DEF@" +.NT Note +The +.PN BadAtom , +.PN BadColor , +.PN BadCursor , +.PN BadDrawable , +.PN BadFont , +.PN BadGC , +.PN BadPixmap , +and +.PN BadWindow +errors are also used when the argument type is extended by a set of +fixed alternatives. +.NE +.sp +.LP +To obtain textual descriptions of the specified error code, use +.PN XGetErrorText . +.IN "XGetErrorText" "" "@DEF@" +.IN "Debugging" "error message strings" +.sM +.FD 0 +XGetErrorText\^(\^\fIdisplay\fP, \fIcode\fP, \fIbuffer_return\fP, \fIlength\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIcode\fP\^; +.br + char *\fIbuffer_return\fP\^; +.br + int \fIlength\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIcode\fP 1i +Specifies the error code for which you want to obtain a description. +.IP \fIbuffer_return\fP 1i +Returns the error description. +.IP \fIlength\fP 1i +Specifies the size of the buffer. +.LP +.eM +The +.PN XGetErrorText +function copies a null-terminated string describing the specified error code +into the specified buffer. +The returned text is in the encoding of the current locale. +It is recommended that you use this function to obtain an error description +because extensions to Xlib may define their own error codes +and error strings. +.LP +.sp +To obtain error messages from the error database, use +.PN XGetErrorDatabaseText . +.IN "XGetErrorDatabaseText" "" "@DEF@" +.sM +.FD 0 +XGetErrorDatabaseText\^(\^\fIdisplay\fP, \fIname\fP, \fImessage\fP, \fIdefault_string\fP, \fIbuffer_return\fP, \fIlength\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + char *\fIname\fP, *\fImessage\fP\^; +.br + char *\fIdefault_string\fP\^; +.br + char *\fIbuffer_return\fP\^; +.br + int \fIlength\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIname\fP 1i +Specifies the name of the application. +.IP \fImessage\fP 1i +Specifies the type of the error message. +.IP \fIdefault_string\fP 1i +Specifies the default error message if none is found in the database. +.IP \fIbuffer_return\fP 1i +Returns the error description. +.IP \fIlength\fP 1i +Specifies the size of the buffer. +.LP +.eM +The +.PN XGetErrorDatabaseText +function returns a null-terminated message +(or the default message) from the error message +database. +Xlib uses this function internally to look up its error messages. +The text in the default_string argument is assumed +to be in the encoding of the current locale, +and the text stored in the buffer_return argument +is in the encoding of the current locale. +.LP +The name argument should generally be the name of your application. +The message argument should indicate which type of error message you want. +If the name and message are not in the Host Portable Character Encoding, +the result is implementation-dependent. +Xlib uses three predefined ``application names'' to report errors. +In these names, +uppercase and lowercase matter. +.IP XProtoError 1i +The protocol error number is used as a string for the message argument. +.IP XlibMessage 1i +These are the message strings that are used internally by the library. +.IP XRequest 1i +For a core protocol request, +the major request protocol number is used for the message argument. +For an extension request, +the extension name (as given by +.PN InitExtension ) +followed by a period (\.) and the minor request protocol number +is used for the message argument. +If no string is found in the error database, +the default_string is returned to the buffer argument. +.LP +.sp +To report an error to the user when the requested display does not exist, use +.PN XDisplayName . +.IN "XDisplayName" "" "@DEF@" +.sM +.FD 0 +char *XDisplayName\^(\^\fIstring\fP\^) +.br + char *\fIstring\fP\^; +.FN +.IP \fIstring\fP 1i +Specifies the character string. +.LP +.eM +The +.PN XDisplayName +function returns the name of the display that +.PN XOpenDisplay +would attempt to use. +If a NULL string is specified, +.PN XDisplayName +looks in the environment for the display and returns the display name that +.PN XOpenDisplay +would attempt to use. +This makes it easier to report to the user precisely which display the +program attempted to open when the initial connection attempt failed. +.LP +.sp +To handle fatal I/O errors, use +.PN XSetIOErrorHandler . +.IN "XSetIOErrorHandler" "" "@DEF@" +.sM +.FD 0 +int (*XSetIOErrorHandler\^(\^\fIhandler\fP\^)\^)\^(\^) +.br + int (\^*\^\fIhandler\fP\^)(Display *); +.FN +.IP \fIhandler\fP 1i +Specifies the program's supplied error handler. +.LP +.eM +The +.PN XSetIOErrorHandler +sets the fatal I/O error handler. +Xlib calls the program's supplied error handler if any sort of system call +error occurs (for example, the connection to the server was lost). +This is assumed to be a fatal condition, +and the called routine should not return. +If the I/O error handler does return, +the client process exits. +.LP +Note that the previous error handler is returned. +.bp diff --git a/libX11/specs/libX11/CH12 b/libX11/specs/libX11/CH12 new file mode 100644 index 000000000..08b9ba93a --- /dev/null +++ b/libX11/specs/libX11/CH12 @@ -0,0 +1,2680 @@ +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be included +.\" in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR +.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +.\" OTHER DEALINGS IN THE SOFTWARE. +.\" +.\" Except as contained in this notice, the name of the X Consortium shall +.\" not be used in advertising or otherwise to promote the sale, use or +.\" other dealings in this Software without prior written authorization +.\" from the X Consortium. +.\" +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by +.\" Digital Equipment Corporation +.\" +.\" Portions Copyright \(co 1990, 1991 by +.\" Tektronix, Inc. +.\" +.\" Permission to use, copy, modify and distribute this documentation for +.\" any purpose and without fee is hereby granted, provided that the above +.\" copyright notice appears in all copies and that both that copyright notice +.\" and this permission notice appear in all copies, and that the names of +.\" Digital and Tektronix not be used in in advertising or publicity pertaining +.\" to this documentation without specific, written prior permission. +.\" Digital and Tektronix makes no representations about the suitability +.\" of this documentation for any purpose. +.\" It is provided ``as is'' without express or implied warranty. +.\" +\& +.sp 1 +.ce 3 +\s+1\fBChapter 12\fP\s-1 + +\s+1\fBInput Device Functions\fP\s-1 +.sp 2 +.nr H1 12 +.nr H2 0 +.nr H3 0 +.nr H4 0 +.nr H5 0 +.na +.LP +.XS +Chapter 12: Input Device Functions +.XE +You can use the Xlib input device functions to: +.IP \(bu 5 +Grab the pointer and individual buttons on the pointer +.IP \(bu 5 +Grab the keyboard and individual keys on the keyboard +.IP \(bu 5 +Resume event processing +.IP \(bu 5 +Move the pointer +.IP \(bu 5 +Set the input focus +.IP \(bu 5 +Manipulate the keyboard and pointer settings +.IP \(bu 5 +Manipulate the keyboard encoding +.NH 2 +Pointer Grabbing +.XS +\*(SN Pointer Grabbing +.XE +.LP +Xlib provides functions that you can use to control input from the pointer, +which usually is a mouse. +Usually, as soon as keyboard and mouse events occur, +the X server delivers them to the appropriate client, +which is determined by the window and input focus. +The X server provides sufficient control over event delivery to +allow window managers to support mouse ahead and various other +styles of user interface. +Many of these user interfaces depend on synchronous delivery of events. +The delivery of pointer and keyboard events can be controlled +independently. +.LP +When mouse buttons or keyboard keys are grabbed, events +will be sent to the grabbing client rather than the normal +client who would have received the event. +If the keyboard or pointer is in asynchronous mode, +further mouse and keyboard events will continue to be processed. +If the keyboard or pointer is in synchronous mode, no +further events are processed until the grabbing client +allows them (see +.PN XAllowEvents ). +The keyboard or pointer is considered frozen during this +interval. +The event that triggered the grab can also be replayed. +.LP +Note that the logical state of a device (as seen by client applications) +may lag the physical state if device event processing is frozen. +.LP +.IN "Active grab" "" "@DEF@" +There are two kinds of grabs: +active and passive. +An active grab occurs when a single client grabs the keyboard and/or pointer +explicitly (see +.PN XGrabPointer +and +.PN XGrabKeyboard ). +.IN "Passive grab" +A passive grab occurs when clients grab a particular keyboard key +or pointer button in a window, +and the grab will activate when the key or button is actually pressed. +Passive grabs are convenient for implementing reliable pop-up menus. +For example, you can guarantee that the pop-up is mapped +before the up pointer button event occurs by +grabbing a button requesting synchronous behavior. +The down event will trigger the grab and freeze further +processing of pointer events until you have the chance to +map the pop-up window. +You can then allow further event processing. +The up event will then be correctly processed relative to the +pop-up window. +.LP +For many operations, +there are functions that take a time argument. +The X server includes a timestamp in various events. +One special time, called +.IN "CurrentTime" "" "@DEF@" +.IN "Time" "" "@DEF@" +.PN CurrentTime , +represents the current server time. +The X server maintains the time when the input focus was last changed, +when the keyboard was last grabbed, +when the pointer was last grabbed, +or when a selection was last changed. +Your +application may be slow reacting to an event. +You often need some way to specify that your +request should not occur if another application has in the meanwhile +taken control of the keyboard, pointer, or selection. +By providing the timestamp from the event in the request, +you can arrange that the operation not take effect +if someone else has performed an operation in the meanwhile. +.LP +A timestamp is a time value, expressed in milliseconds. +It typically is the time since the last server reset. +Timestamp values wrap around (after about 49.7 days). +The server, given its current time is represented by timestamp T, +always interprets timestamps from clients by treating half of the timestamp +space as being later in time than T. +One timestamp value, named +.PN CurrentTime , +is never generated by the server. +This value is reserved for use in requests to represent the current server time. +.LP +For many functions in this section, +you pass pointer event mask bits. +The valid pointer event mask bits are: +.PN ButtonPressMask , +.PN ButtonReleaseMask , +.PN EnterWindowMask , +.PN LeaveWindowMask , +.PN PointerMotionMask , +.PN PointerMotionHintMask , +.PN Button1MotionMask , +.PN Button2MotionMask , +.PN Button3MotionMask , +.PN Button4MotionMask , +.PN Button5MotionMask , +.PN ButtonMotionMask , +and +.PN KeyMapStateMask . +For other functions in this section, +you pass keymask bits. +The valid keymask bits are: +.PN ShiftMask , +.PN LockMask , +.PN ControlMask , +.PN Mod1Mask , +.PN Mod2Mask , +.PN Mod3Mask , +.PN Mod4Mask , +and +.PN Mod5Mask . +.LP +.sp +To grab the pointer, use +.PN XGrabPointer . +.IN "Grabbing" "pointer" +.IN "Pointer" "grabbing" +.IN "XGrabPointer" "" "@DEF@" +.sM +.FD 0 +int XGrabPointer\^(\^\fIdisplay\fP, \fIgrab_window\fP\^, \fIowner_events\fP\^, \fIevent_mask\fP\^, \fIpointer_mode\fP\^, + \fIkeyboard_mode\fP\^, \fIconfine_to\fP\^, \fIcursor\fP\^, \fItime\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIgrab_window\fP\^; +.br + Bool \fIowner_events\fP\^; +.br + unsigned int \fIevent_mask\fP\^; +.br + int \fIpointer_mode\fP\^, \fIkeyboard_mode\fP\^; +.br + Window \fIconfine_to\fP\^; +.br + Cursor \fIcursor\fP\^; +.br + Time \fItime\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgrab_window\fP 1i +Specifies the grab window. +.IP \fIowner_events\fP 1i +Specifies a Boolean value that indicates whether the pointer +events are to be reported as usual or reported with respect to the grab window +if selected by the event mask. +.IP \fIevent_mask\fP 1i +Specifies which pointer events are reported to the client. +The mask is the bitwise inclusive OR of the valid pointer event mask bits. +.IP \fIpointer_mode\fP 1i +Specifies further processing of pointer events. +You can pass +.PN GrabModeSync +or +.PN GrabModeAsync . +.IP \fIkeyboard_mode\fP 1i +Specifies further processing of keyboard events. +You can pass +.PN GrabModeSync +or +.PN GrabModeAsync . +.IP \fIconfine_to\fP 1i +Specifies the window to confine the pointer in or +.PN None . +.IP \fIcursor\fP 1i +Specifies the cursor that is to be displayed during the grab or +.PN None . +.IP \fItime\fP 1i +Specifies the time. +You can pass either a timestamp or +.PN CurrentTime . +.LP +.eM +The +.PN XGrabPointer +function actively grabs control of the pointer and returns +.PN GrabSuccess +if the grab was successful. +Further pointer events are reported only to the grabbing client. +.PN XGrabPointer +overrides any active pointer grab by this client. +If owner_events is +.PN False , +all generated pointer events +are reported with respect to grab_window and are reported only if +selected by event_mask. +If owner_events is +.PN True +and if a generated +pointer event would normally be reported to this client, +it is reported as usual. +Otherwise, the event is reported with respect to the +grab_window and is reported only if selected by event_mask. +For either value of owner_events, unreported events are discarded. +.LP +If the pointer_mode is +.PN GrabModeAsync , +pointer event processing continues as usual. +If the pointer is currently frozen by this client, +the processing of events for the pointer is resumed. +If the pointer_mode is +.PN GrabModeSync , +the state of the pointer, as seen by +client applications, +appears to freeze, and the X server generates no further pointer events +until the grabbing client calls +.PN XAllowEvents +or until the pointer grab is released. +Actual pointer changes are not lost while the pointer is frozen; +they are simply queued in the server for later processing. +.LP +If the keyboard_mode is +.PN GrabModeAsync , +keyboard event processing is unaffected by activation of the grab. +If the keyboard_mode is +.PN GrabModeSync , +the state of the keyboard, as seen by +client applications, +appears to freeze, and the X server generates no further keyboard events +until the grabbing client calls +.PN XAllowEvents +or until the pointer grab is released. +Actual keyboard changes are not lost while the pointer is frozen; +they are simply queued in the server for later processing. +.LP +If a cursor is specified, it is displayed regardless of what +window the pointer is in. +If +.PN None +is specified, +the normal cursor for that window is displayed +when the pointer is in grab_window or one of its subwindows; +otherwise, the cursor for grab_window is displayed. +.LP +If a confine_to window is specified, +the pointer is restricted to stay contained in that window. +The confine_to window need have no relationship to the grab_window. +If the pointer is not initially in the confine_to window, +it is warped automatically to the closest edge +just before the grab activates and enter/leave events are generated as usual. +If the confine_to window is subsequently reconfigured, +the pointer is warped automatically, as necessary, +to keep it contained in the window. +.LP +The time argument allows you to avoid certain circumstances that come up +if applications take a long time to respond or if there are long network +delays. +Consider a situation where you have two applications, both +of which normally grab the pointer when clicked on. +If both applications specify the timestamp from the event, +the second application may wake up faster and successfully grab the pointer +before the first application. +The first application then will get an indication that the other application +grabbed the pointer before its request was processed. +.LP +.PN XGrabPointer +generates +.PN EnterNotify +and +.PN LeaveNotify +events. +.LP +Either if grab_window or confine_to window is not viewable +or if the confine_to window lies completely outside the boundaries of the root +window, +.PN XGrabPointer +fails and returns +.PN GrabNotViewable . +If the pointer is actively grabbed by some other client, +it fails and returns +.PN AlreadyGrabbed . +If the pointer is frozen by an active grab of another client, +it fails and returns +.PN GrabFrozen . +If the specified time is earlier than the last-pointer-grab time or later +than the current X server time, it fails and returns +.PN GrabInvalidTime . +Otherwise, the last-pointer-grab time is set to the specified time +.Pn ( CurrentTime +is replaced by the current X server time). +.LP +.PN XGrabPointer +can generate +.PN BadCursor , +.PN BadValue , +and +.PN BadWindow +errors. +.LP +.sp +To ungrab the pointer, use +.PN XUngrabPointer . +.IN "Ungrabbing" "pointer" +.IN "Pointer" "ungrabbing" +.IN "XUngrabPointer" "" "@DEF@" +.sM +.FD 0 +XUngrabPointer\^(\^\fIdisplay\fP, \fItime\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Time \fItime\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fItime\fP 1i +Specifies the time. +You can pass either a timestamp or +.PN CurrentTime . +.LP +.eM +The +.PN XUngrabPointer +function releases the pointer and any queued events +if this client has actively grabbed the pointer from +.PN XGrabPointer , +.PN XGrabButton , +or from a normal button press. +.PN XUngrabPointer +does not release the pointer if the specified +time is earlier than the last-pointer-grab time or is later than the +current X server time. +It also generates +.PN EnterNotify +and +.PN LeaveNotify +events. +The X server performs an +.PN UngrabPointer +request automatically if the event window or confine_to window +for an active pointer grab becomes not viewable +or if window reconfiguration causes the confine_to window to lie completely +outside the boundaries of the root window. +.LP +.sp +To change an active pointer grab, use +.PN XChangeActivePointerGrab . +.IN "Pointer" "grabbing" +.IN "Changing" "pointer grab" +.IN "XChangeActivePointerGrab" "" "@DEF@" +.sM +.FD 0 +XChangeActivePointerGrab\^(\^\fIdisplay\fP, \fIevent_mask\fP\^, \fIcursor\fP\^, \fItime\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + unsigned int \fIevent_mask\fP\^; +.br + Cursor \fIcursor\fP\^; +.br + Time \fItime\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIevent_mask\fP 1i +Specifies which pointer events are reported to the client. +The mask is the bitwise inclusive OR of the valid pointer event mask bits. +.IP \fIcursor\fP 1i +Specifies the cursor that is to be displayed or +.PN None . +.IP \fItime\fP 1i +Specifies the time. +You can pass either a timestamp or +.PN CurrentTime . +.LP +.eM +The +.PN XChangeActivePointerGrab +function changes the specified dynamic parameters if the pointer is actively +grabbed by the client and if the specified time is no earlier than the +last-pointer-grab time and no later than the current X server time. +This function has no effect on the passive parameters of an +.PN XGrabButton . +The interpretation of event_mask and cursor is the same as described in +.PN XGrabPointer . +.LP +.PN XChangeActivePointerGrab +can generate +.PN BadCursor +and +.PN BadValue +errors. +.LP +.sp +To grab a pointer button, use +.PN XGrabButton . +.IN "Grabbing" "buttons" +.IN "Button" "grabbing" +.IN "XGrabButton" "" "@DEF@" +.sM +.FD 0 +XGrabButton\^(\^\fIdisplay\fP, \fIbutton\fP\^, \fImodifiers\fP\^, \fIgrab_window\fP\^, \fIowner_events\fP\^, \fIevent_mask\fP\^, +.br + \fIpointer_mode\fP\^, \fIkeyboard_mode\fP\^, \fIconfine_to\fP\^, \fIcursor\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + unsigned int \fIbutton\fP\^; +.br + unsigned int \fImodifiers\fP\^; +.br + Window \fIgrab_window\fP\^; +.br + Bool \fIowner_events\fP\^; +.br + unsigned int \fIevent_mask\fP\^; +.br + int \fIpointer_mode\fP\^, \fIkeyboard_mode\fP\^; +.br + Window \fIconfine_to\fP\^; +.br + Cursor \fIcursor\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.ds Bu grabbed +.IP \fIbutton\fP 1i +Specifies the pointer button that is to be \*(Bu or +.PN AnyButton . +.IP \fImodifiers\fP 1i +Specifies the set of keymasks or +.PN AnyModifier . +The mask is the bitwise inclusive OR of the valid keymask bits. +.IP \fIgrab_window\fP 1i +Specifies the grab window. +.IP \fIowner_events\fP 1i +Specifies a Boolean value that indicates whether the pointer +events are to be reported as usual or reported with respect to the grab window +if selected by the event mask. +.IP \fIevent_mask\fP 1i +Specifies which pointer events are reported to the client. +The mask is the bitwise inclusive OR of the valid pointer event mask bits. +.IP \fIpointer_mode\fP 1i +Specifies further processing of pointer events. +You can pass +.PN GrabModeSync +or +.PN GrabModeAsync . +.IP \fIkeyboard_mode\fP 1i +Specifies further processing of keyboard events. +You can pass +.PN GrabModeSync +or +.PN GrabModeAsync . +.IP \fIconfine_to\fP 1i +Specifies the window to confine the pointer in or +.PN None . +.IP \fIcursor\fP 1i +Specifies the cursor that is to be displayed or +.PN None . +.LP +.eM +The +.PN XGrabButton +function establishes a passive grab. +In the future, +the pointer is actively grabbed (as for +.PN XGrabPointer ), +the last-pointer-grab time is set to the time at which the button was pressed +(as transmitted in the +.PN ButtonPress +event), and the +.PN ButtonPress +event is reported if all of the following conditions are true: +.IP \(bu 5 +The pointer is not grabbed, and the specified button is logically pressed +when the specified modifier keys are logically down, +and no other buttons or modifier keys are logically down. +.IP \(bu 5 +The grab_window contains the pointer. +.IP \(bu 5 +The confine_to window (if any) is viewable. +.IP \(bu 5 +A passive grab on the same button/key combination does not exist +on any ancestor of grab_window. +.LP +The interpretation of the remaining arguments is as for +.PN XGrabPointer . +The active grab is terminated automatically when the logical state of the +pointer has all buttons released +(independent of the state of the logical modifier keys). +.LP +Note that the logical state of a device (as seen by client applications) +may lag the physical state if device event processing is frozen. +.LP +This request overrides all previous grabs by the same client on the same +button/key combinations on the same window. +A modifiers of +.PN AnyModifier +is equivalent to issuing the grab request for all +possible modifier combinations (including the combination of no modifiers). +It is not required that all modifiers specified have currently assigned +KeyCodes. +A button of +.PN AnyButton +is equivalent to +issuing the request for all possible buttons. +Otherwise, it is not required that the specified button currently be assigned +to a physical button. +.LP +If some other client has already issued an +.PN XGrabButton +with the same button/key combination on the same window, a +.PN BadAccess +error results. +When using +.PN AnyModifier +or +.PN AnyButton , +the request fails completely, +and a +.PN BadAccess +error results (no grabs are +established) if there is a conflicting grab for any combination. +.PN XGrabButton +has no effect on an active grab. +.LP +.PN XGrabButton +can generate +.PN BadCursor , +.PN BadValue , +and +.PN BadWindow +errors. +.LP +.sp +To ungrab a pointer button, use +.PN XUngrabButton . +.IN "Ungrabbing" "buttons" +.IN "Button" "ungrabbing" +.IN "XUngrabButton" "" "@DEF@" +.sM +.FD 0 +XUngrabButton\^(\^\fIdisplay\fP, \fIbutton\fP\^, \fImodifiers\fP\^, \fIgrab_window\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + unsigned int \fIbutton\fP\^; +.br + unsigned int \fImodifiers\fP\^; +.br + Window \fIgrab_window\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.ds Bu released +.IP \fIbutton\fP 1i +Specifies the pointer button that is to be \*(Bu or +.PN AnyButton . +.IP \fImodifiers\fP 1i +Specifies the set of keymasks or +.PN AnyModifier . +The mask is the bitwise inclusive OR of the valid keymask bits. +.IP \fIgrab_window\fP 1i +Specifies the grab window. +.LP +.eM +The +.PN XUngrabButton +function releases the passive button/key combination on the specified window if +it was grabbed by this client. +A modifiers of +.PN AnyModifier +is +equivalent to issuing +the ungrab request for all possible modifier combinations, including +the combination of no modifiers. +A button of +.PN AnyButton +is equivalent to issuing the +request for all possible buttons. +.PN XUngrabButton +has no effect on an active grab. +.LP +.PN XUngrabButton +can generate +.PN BadValue +and +.PN BadWindow +errors. +.NH 2 +Keyboard Grabbing +.XS +\*(SN Keyboard Grabbing +.XE +.LP +Xlib provides functions that you can use to grab or ungrab the keyboard +as well as allow events. +.LP +For many functions in this section, +you pass keymask bits. +The valid keymask bits are: +.PN ShiftMask , +.PN LockMask , +.PN ControlMask , +.PN Mod1Mask , +.PN Mod2Mask , +.PN Mod3Mask , +.PN Mod4Mask , +and +.PN Mod5Mask . +.LP +.sp +To grab the keyboard, use +.PN XGrabKeyboard . +.IN "Keyboard" "grabbing" +.IN "Grabbing" "keyboard" +.IN "XGrabKeyboard" "" "@DEF@" +.sM +.FD 0 +int XGrabKeyboard\^(\^\fIdisplay\fP, \fIgrab_window\fP\^, \fIowner_events\fP\^, \fIpointer_mode\fP\^, \fIkeyboard_mode\fP\^, \fItime\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIgrab_window\fP\^; +.br + Bool \fIowner_events\fP\^; +.br + int \fIpointer_mode\fP\^, \fIkeyboard_mode\fP\^; +.br + Time \fItime\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgrab_window\fP 1i +Specifies the grab window. +.IP \fIowner_events\fP 1i +Specifies a Boolean value that indicates whether the keyboard events +are to be reported as usual. +.IP \fIpointer_mode\fP 1i +Specifies further processing of pointer events. +You can pass +.PN GrabModeSync +or +.PN GrabModeAsync . +.IP \fIkeyboard_mode\fP 1i +Specifies further processing of keyboard events. +You can pass +.PN GrabModeSync +or +.PN GrabModeAsync . +.IP \fItime\fP 1i +Specifies the time. +You can pass either a timestamp or +.PN CurrentTime . +.LP +.eM +The +.PN XGrabKeyboard +function actively grabs control of the keyboard and generates +.PN FocusIn +and +.PN FocusOut +events. +Further key events are reported only to the +grabbing client. +.PN XGrabKeyboard +overrides any active keyboard grab by this client. +If owner_events is +.PN False , +all generated key events are reported with +respect to grab_window. +If owner_events is +.PN True +and if a generated +key event would normally be reported to this client, it is reported +normally; otherwise, the event is reported with respect to the +grab_window. +Both +.PN KeyPress +and +.PN KeyRelease +events are always reported, +independent of any event selection made by the client. +.LP +If the keyboard_mode argument is +.PN GrabModeAsync , +keyboard event processing continues +as usual. +If the keyboard is currently frozen by this client, +then processing of keyboard events is resumed. +If the keyboard_mode argument is +.PN GrabModeSync , +the state of the keyboard (as seen by client applications) appears to freeze, +and the X server generates no further keyboard events until the +grabbing client issues a releasing +.PN XAllowEvents +call or until the keyboard grab is released. +Actual keyboard changes are not lost while the keyboard is frozen; +they are simply queued in the server for later processing. +.LP +If pointer_mode is +.PN GrabModeAsync , +pointer event processing is unaffected +by activation of the grab. +If pointer_mode is +.PN GrabModeSync , +the state of the pointer (as seen by client applications) appears to freeze, +and the X server generates no further pointer events +until the grabbing client issues a releasing +.PN XAllowEvents +call or until the keyboard grab is released. +Actual pointer changes are not lost while the pointer is frozen; +they are simply queued in the server for later processing. +.LP +If the keyboard is actively grabbed by some other client, +.PN XGrabKeyboard +fails and returns +.PN AlreadyGrabbed . +If grab_window is not viewable, +it fails and returns +.PN GrabNotViewable . +If the keyboard is frozen by an active grab of another client, +it fails and returns +.PN GrabFrozen . +If the specified time is earlier than the last-keyboard-grab time +or later than the current X server time, +it fails and returns +.PN GrabInvalidTime . +Otherwise, the last-keyboard-grab time is set to the specified time +.Pn ( CurrentTime +is replaced by the current X server time). +.LP +.PN XGrabKeyboard +can generate +.PN BadValue +and +.PN BadWindow +errors. +.LP +.sp +To ungrab the keyboard, use +.PN XUngrabKeyboard . +.IN "Keyboard" "ungrabbing" +.IN "Ungrabbing" "keyboard" +.IN "XUngrabKeyboard" "" "@DEF@" +.sM +.FD 0 +XUngrabKeyboard\^(\^\fIdisplay\fP, \fItime\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Time \fItime\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fItime\fP 1i +Specifies the time. +You can pass either a timestamp or +.PN CurrentTime . +.LP +.eM +The +.PN XUngrabKeyboard +function +releases the keyboard and any queued events if this client has it actively grabbed from +either +.PN XGrabKeyboard +or +.PN XGrabKey . +.PN XUngrabKeyboard +does not release the keyboard and any queued events +if the specified time is earlier than +the last-keyboard-grab time or is later than the current X server time. +It also generates +.PN FocusIn +and +.PN FocusOut +events. +The X server automatically performs an +.PN UngrabKeyboard +request if the event window for an +active keyboard grab becomes not viewable. +.LP +.sp +To passively grab a single key of the keyboard, use +.PN XGrabKey . +.IN "Key" "grabbing" +.IN "Grabbing" "keys" +.IN "XGrabKey" "" "@DEF@" +.sM +.FD 0 +XGrabKey\^(\^\fIdisplay\fP, \fIkeycode\fP\^, \fImodifiers\fP\^, \fIgrab_window\fP\^, \fIowner_events\fP\^, \fIpointer_mode\fP\^, +.br + \fIkeyboard_mode\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIkeycode\fP\^; +.br + unsigned int \fImodifiers\fP\^; +.br + Window \fIgrab_window\fP\^; +.br + Bool \fIowner_events\fP\^; +.br + int \fIpointer_mode\fP\^, \fIkeyboard_mode\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIkeycode\fP 1i +Specifies the KeyCode or +.PN AnyKey . +.IP \fImodifiers\fP 1i +Specifies the set of keymasks or +.PN AnyModifier . +The mask is the bitwise inclusive OR of the valid keymask bits. +.IP \fIgrab_window\fP 1i +Specifies the grab window. +.IP \fIowner_events\fP 1i +Specifies a Boolean value that indicates whether the keyboard events +are to be reported as usual. +.IP \fIpointer_mode\fP 1i +Specifies further processing of pointer events. +You can pass +.PN GrabModeSync +or +.PN GrabModeAsync . +.IP \fIkeyboard_mode\fP 1i +Specifies further processing of keyboard events. +You can pass +.PN GrabModeSync +or +.PN GrabModeAsync . +.LP +.eM +The +.PN XGrabKey +function establishes a passive grab on the keyboard. +In the future, +the keyboard is actively grabbed (as for +.PN XGrabKeyboard ), +the last-keyboard-grab time is set to the time at which the key was pressed +(as transmitted in the +.PN KeyPress +event), and the +.PN KeyPress +event is reported if all of the following conditions are true: +.IP \(bu 5 +The keyboard is not grabbed and the specified key +(which can itself be a modifier key) is logically pressed +when the specified modifier keys are logically down, +and no other modifier keys are logically down. +.IP \(bu 5 +Either the grab_window is an ancestor of (or is) the focus window, +or the grab_window is a descendant of the focus window and contains the pointer. +.IP \(bu 5 +A passive grab on the same key combination does not exist +on any ancestor of grab_window. +.LP +The interpretation of the remaining arguments is as for +.PN XGrabKeyboard . +The active grab is terminated automatically when the logical state of the +keyboard has the specified key released +(independent of the logical state of the modifier keys). +.LP +Note that the logical state of a device (as seen by client applications) +may lag the physical state if device event processing is frozen. +.LP +A modifiers argument of +.PN AnyModifier +is equivalent to issuing the request for all +possible modifier combinations (including the combination of no +modifiers). +It is not required that all modifiers specified have +currently assigned KeyCodes. +A keycode argument of +.PN AnyKey +is equivalent to issuing +the request for all possible KeyCodes. +Otherwise, the specified keycode must be in +the range specified by min_keycode and max_keycode in the connection +setup, +or a +.PN BadValue +error results. +.LP +If some other client has issued a +.PN XGrabKey +with the same key combination on the same window, a +.PN BadAccess +error results. +When using +.PN AnyModifier +or +.PN AnyKey , +the request fails completely, +and a +.PN BadAccess +error results (no grabs are established) +if there is a conflicting grab for any combination. +.LP +.PN XGrabKey +can generate +.PN BadAccess , +.PN BadValue , +and +.PN BadWindow +errors. +.LP +.sp +To ungrab a key, use +.PN XUngrabKey . +.IN "Key" "ungrabbing" +.IN "Ungrabbing" "keys" +.IN "XUngrabKey" "" "@DEF@" +.sM +.FD 0 +XUngrabKey\^(\^\fIdisplay\fP, \fIkeycode\fP\^, \fImodifiers\fP\^, \fIgrab_window\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIkeycode\fP\^; +.br + unsigned int \fImodifiers\fP\^; +.br + Window \fIgrab_window\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIkeycode\fP 1i +Specifies the KeyCode or +.PN AnyKey . +.IP \fImodifiers\fP 1i +Specifies the set of keymasks or +.PN AnyModifier . +The mask is the bitwise inclusive OR of the valid keymask bits. +.IP \fIgrab_window\fP 1i +Specifies the grab window. +.LP +.eM +The +.PN XUngrabKey +function releases the key combination on the specified window if it was grabbed +by this client. +It has no effect on an active grab. +A modifiers of +.PN AnyModifier +is equivalent to issuing +the request for all possible modifier combinations +(including the combination of no modifiers). +A keycode argument of +.PN AnyKey +is equivalent to issuing the request for all possible key codes. +.LP +.PN XUngrabKey +can generate +.PN BadValue +and +.PN BadWindow +errors. +.NH 2 +Resuming Event Processing +.XS +\*(SN Resuming Event Processing +.XE +.LP +The previous sections discussed grab mechanisms with which processing +of events by the server can be temporarily suspended. This section +describes the mechanism for resuming event processing. +.LP +.sp +To allow further events to be processed when the device has been frozen, use +.PN XAllowEvents . +.IN "XAllowEvents" "" "@DEF@" +.sM +.FD 0 +XAllowEvents\^(\^\fIdisplay\fP, \fIevent_mode\fP\^, \fItime\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIevent_mode\fP\^; +.br + Time \fItime\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIevent_mode\fP 1i +Specifies the event mode. +You can pass +.PN AsyncPointer , +.PN SyncPointer , +.PN AsyncKeyboard , +.PN SyncKeyboard , +.PN ReplayPointer , +.PN ReplayKeyboard , +.PN AsyncBoth , +or +.PN SyncBoth . +.IP \fItime\fP 1i +Specifies the time. +You can pass either a timestamp or +.PN CurrentTime . +.LP +.eM +The +.PN XAllowEvents +function releases some queued events if the client has caused a device +to freeze. +It has no effect if the specified time is earlier than the last-grab +time of the most recent active grab for the client or if the specified time +is later than the current X server time. +Depending on the event_mode argument, the following occurs: +.TS +lw(1.25i) lw(4.5i). +T{ +.PN AsyncPointer +T} T{ +If the pointer is frozen by the client, +pointer event processing continues as usual. +If the pointer is frozen twice by the client on behalf of two separate grabs, +.PN AsyncPointer +thaws for both. +.PN AsyncPointer +has no effect if the pointer is not frozen by the client, +but the pointer need not be grabbed by the client. +T} +.sp 6p +T{ +.PN SyncPointer +T} T{ +If the pointer is frozen and actively grabbed by the client, +pointer event processing continues as usual until the next +.PN ButtonPress +or +.PN ButtonRelease +event is reported to the client. +At this time, +the pointer again appears to freeze. +However, if the reported event causes the pointer grab to be released, +the pointer does not freeze. +.PN SyncPointer +has no effect if the pointer is not frozen by the client +or if the pointer is not grabbed by the client. +T} +.sp 6p +T{ +.PN ReplayPointer +T} T{ +If the pointer is actively grabbed by the client and is frozen as the result of +an event having been sent to the client (either from the activation of an +.PN XGrabButton +or from a previous +.PN XAllowEvents +with mode +.PN SyncPointer +but not from an +.PN XGrabPointer ), +the pointer grab is released and that event is completely reprocessed. +This time, however, the function ignores any passive grabs at or above +(toward the root of) the grab_window of the grab just released. +The request has no effect if the pointer is not grabbed by the client +or if the pointer is not frozen as the result of an event. +T} +.sp 6p +T{ +.PN AsyncKeyboard +T} T{ +If the keyboard is frozen by the client, +keyboard event processing continues as usual. +If the keyboard is frozen twice by the client on behalf of two separate grabs, +.PN AsyncKeyboard +thaws for both. +.PN AsyncKeyboard +has no effect if the keyboard is not frozen by the client, +but the keyboard need not be grabbed by the client. +T} +.sp 6p +T{ +.PN SyncKeyboard +T} T{ +If the keyboard is frozen and actively grabbed by the client, +keyboard event processing continues as usual until the next +.PN KeyPress +or +.PN KeyRelease +event is reported to the client. +At this time, +the keyboard again appears to freeze. +However, if the reported event causes the keyboard grab to be released, +the keyboard does not freeze. +.PN SyncKeyboard +has no effect if the keyboard is not frozen by the client +or if the keyboard is not grabbed by the client. +T} +.sp 6p +T{ +.PN ReplayKeyboard +T} T{ +If the keyboard is actively grabbed by the client and is frozen +as the result of an event having been sent to the client (either from the +activation of an +.PN XGrabKey +or from a previous +.PN XAllowEvents +with mode +.PN SyncKeyboard +but not from an +.PN XGrabKeyboard ), +the keyboard grab is released and that event is completely reprocessed. +This time, however, the function ignores any passive grabs at or above +(toward the root of) +the grab_window of the grab just released. +The request has no effect if the keyboard is not grabbed by the client +or if the keyboard is not frozen as the result of an event. +T} +.sp 6p +T{ +.PN SyncBoth +T} T{ +If both pointer and keyboard are frozen by the client, +event processing for both devices continues as usual until the next +.PN ButtonPress , +.PN ButtonRelease , +.PN KeyPress , +or +.PN KeyRelease +event is reported to the client for a grabbed device +(button event for the pointer, key event for the keyboard), +at which time the devices again appear to freeze. +However, if the reported event causes the grab to be released, +then the devices do not freeze (but if the other device is still +grabbed, then a subsequent event for it will still cause both devices +to freeze). +.PN SyncBoth +has no effect unless both pointer and keyboard +are frozen by the client. +If the pointer or keyboard is frozen twice +by the client on behalf of two separate grabs, +.PN SyncBoth +thaws for both (but a subsequent freeze for +.PN SyncBoth +will only freeze each device once). +T} +.sp 6p +T{ +.PN AsyncBoth +T} T{ +If the pointer and the keyboard are frozen by the +client, event processing for both devices continues as usual. +If a device is frozen twice by the client on behalf of two separate grabs, +.PN AsyncBoth +thaws for both. +.PN AsyncBoth +has no effect unless both +pointer and keyboard are frozen by the client. +T} +.TE +.LP +.PN AsyncPointer , +.PN SyncPointer , +and +.PN ReplayPointer +have no effect on the +processing of keyboard events. +.PN AsyncKeyboard , +.PN SyncKeyboard , +and +.PN ReplayKeyboard +have no effect on the +processing of pointer events. +It is possible for both a pointer grab and a keyboard grab (by the same +or different clients) to be active simultaneously. +If a device is frozen on behalf of either grab, +no event processing is performed for the device. +It is possible for a single device to be frozen because of both grabs. +In this case, +the freeze must be released on behalf of both grabs before events can +again be processed. +If a device is frozen twice by a single client, +then a single +.PN AllowEvents +releases both. +.LP +.PN XAllowEvents +can generate a +.PN BadValue +error. +.NH 2 +Moving the Pointer +.XS +\*(SN Moving the Pointer +.XE +.LP +Although movement of the pointer normally should be left to the +control of the end user, sometimes it is necessary to move the +pointer to a new position under program control. +.LP +.sp +To move the pointer to an arbitrary point in a window, use +.PN XWarpPointer . +.IN "XWarpPointer" "" "@DEF@" +.sM +.FD 0 +XWarpPointer\^(\^\fIdisplay\fP, \fIsrc_w\fP\^, \fIdest_w\fP\^, \fIsrc_x\fP\^, \fIsrc_y\fP\^, \fIsrc_width\fP\^, \fIsrc_height\fP\^, \fIdest_x\fP\^, +.br + \fIdest_y\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIsrc_w\fP\^, \fIdest_w\fP\^; +.br + int \fIsrc_x\fP\^, \fIsrc_y\fP\^; +.br + unsigned int \fIsrc_width\fP\^, \fIsrc_height\fP\^; +.br + int \fIdest_x\fP\^, \fIdest_y\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIsrc_w\fP 1i +Specifies the source window or +.PN None . +.IP \fIdest_w\fP 1i +Specifies the destination window or +.PN None . +.IP \fIsrc_x\fP 1i +.br +.ns +.IP \fIsrc_y\fP 1i +.br +.ns +.IP \fIsrc_width\fP 1i +.br +.ns +.IP \fIsrc_height\fP 1i +Specify a rectangle in the source window. +.IP \fIdest_x\fP 1i +.br +.ns +.IP \fIdest_y\fP 1i +Specify the x and y coordinates within the destination window. +.LP +.eM +If dest_w is +.PN None , +.PN XWarpPointer +moves the pointer by the offsets (dest_x, dest_y) relative to the current +position of the pointer. +If dest_w is a window, +.PN XWarpPointer +moves the pointer to the offsets (dest_x, dest_y) relative to the origin of +dest_w. +However, if src_w is a window, +the move only takes place if the window src_w contains the pointer +and if the specified rectangle of src_w contains the pointer. +.LP +The src_x and src_y coordinates are relative to the origin of src_w. +If src_height is zero, +it is replaced with the current height of src_w minus src_y. +If src_width is zero, +it is replaced with the current width of src_w minus src_x. +.LP +There is seldom any reason for calling this function. +The pointer should normally be left to the user. +If you do use this function, however, it generates events just as if the user +had instantaneously moved the pointer from one position to another. +Note that you cannot use +.PN XWarpPointer +to move the pointer outside the confine_to window of an active pointer grab. +An attempt to do so will only move the pointer as far as the closest edge of the +confine_to window. +.LP +.PN XWarpPointer +can generate a +.PN BadWindow +error. +.NH 2 +Controlling Input Focus +.XS +\*(SN Controlling Input Focus +.XE +.LP +Xlib provides functions that you can use to set and get the input focus. +The input focus is a shared resource, and cooperation among clients is +required for correct interaction. See the +\fIInter-Client Communication Conventions Manual\fP +for input focus policy. +.LP +.sp +To set the input focus, use +.PN XSetInputFocus . +.IN "XSetInputFocus" "" "@DEF@" +.sM +.FD 0 +XSetInputFocus\^(\^\fIdisplay\fP, \fIfocus\fP\^, \fIrevert_to\fP\^, \fItime\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIfocus\fP\^; +.br + int \fIrevert_to\fP\^; +.br + Time \fItime\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIfocus\fP 1i +Specifies the window, +.PN PointerRoot , +or +.PN None . +.IP \fIrevert_to\fP 1i +Specifies where the input focus reverts to if the window becomes not +viewable. +You can pass +.PN RevertToParent , +.PN RevertToPointerRoot , +or +.PN RevertToNone . +.IP \fItime\fP 1i +Specifies the time. +You can pass either a timestamp or +.PN CurrentTime . +.LP +.eM +The +.PN XSetInputFocus +function changes the input focus and the last-focus-change time. +It has no effect if the specified time is earlier than the current +last-focus-change time or is later than the current X server time. +Otherwise, the last-focus-change time is set to the specified time +.Pn ( CurrentTime +is replaced by the current X server time). +.PN XSetInputFocus +causes the X server to generate +.PN FocusIn +and +.PN FocusOut +events. +.LP +Depending on the focus argument, +the following occurs: +.IP \(bu 5 +If focus is +.PN None , +all keyboard events are discarded until a new focus window is set, +and the revert_to argument is ignored. +.IP \(bu 5 +If focus is a window, +it becomes the keyboard's focus window. +If a generated keyboard event would normally be reported to this window +or one of its inferiors, the event is reported as usual. +Otherwise, the event is reported relative to the focus window. +.IP \(bu 5 +If focus is +.PN PointerRoot , +the focus window is dynamically taken to be the root window of whatever screen +the pointer is on at each keyboard event. +In this case, the revert_to argument is ignored. +.LP +The specified focus window must be viewable at the time +.PN XSetInputFocus +is called, +or a +.PN BadMatch +error results. +If the focus window later becomes not viewable, +the X server +evaluates the revert_to argument to determine the new focus window as follows: +.IP \(bu 5 +If revert_to is +.PN RevertToParent , +the focus reverts to the parent (or the closest viewable ancestor), +and the new revert_to value is taken to be +.PN RevertToNone . +.IP \(bu 5 +If revert_to is +.PN RevertToPointerRoot +or +.PN RevertToNone , +the focus reverts to +.PN PointerRoot +or +.PN None , +respectively. +When the focus reverts, +the X server generates +.PN FocusIn +and +.PN FocusOut +events, but the last-focus-change time is not affected. +.LP +.PN XSetInputFocus +can generate +.PN BadMatch , +.PN BadValue , +and +.PN BadWindow +errors. +.LP +.sp +To obtain the current input focus, use +.PN XGetInputFocus . +.IN "XGetInputFocus" "" "@DEF@" +.sM +.FD 0 +XGetInputFocus\^(\^\fIdisplay\fP, \fIfocus_return\fP\^, \fIrevert_to_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window *\fIfocus_return\fP\^; +.br + int *\fIrevert_to_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIfocus_return\fP 1i +Returns the focus window, +.PN PointerRoot , +or +.PN None . +.IP \fIrevert_to_return\fP 1i +Returns the current focus state +.Pn ( RevertToParent , +.PN RevertToPointerRoot , +or +.PN RevertToNone ). +.LP +.eM +The +.PN XGetInputFocus +function returns the focus window and the current focus state. +.NH 2 +Manipulating the Keyboard and Pointer Settings +.XS +\*(SN Manipulating the Keyboard and Pointer Settings +.XE +.LP +Xlib provides functions that you can use to +change the keyboard control, obtain a list of the auto-repeat keys, +turn keyboard auto-repeat on or off, ring the bell, +set or obtain the pointer button or keyboard mapping, +and obtain a bit vector for the keyboard. +.LP +.IN "Keyboard" "bell volume" +.IN "Keyboard" "keyclick volume" +.IN "Keyboard" "bit vector" +.IN "Mouse" "programming" +This section discusses +the user-preference options of bell, key click, +pointer behavior, and so on. +The default values for many of these options are server dependent. +Not all implementations will actually be able to control all of these +parameters. +.LP +The +.PN XChangeKeyboardControl +function changes control of a keyboard and operates on a +.PN XKeyboardControl +structure: +.sM +.LP +/* Mask bits for ChangeKeyboardControl */ +.TS +lw(.5i) lw(2.5i) lw(.8i). +T{ +#define +T} T{ +.PN KBKeyClickPercent +T} T{ +(1L<<0) +T} +T{ +#define +T} T{ +.PN KBBellPercent +T} T{ +(1L<<1) +T} +T{ +#define +T} T{ +.PN KBBellPitch +T} T{ +(1L<<2) +T} +T{ +#define +T} T{ +.PN KBBellDuration +T} T{ +(1L<<3) +T} +T{ +#define +T} T{ +.PN KBLed +T} T{ +(1L<<4) +T} +T{ +#define +T} T{ +.PN KBLedMode +T} T{ +(1L<<5) +T} +T{ +#define +T} T{ +.PN KBKey +T} T{ +(1L<<6) +T} +T{ +#define +T} T{ +.PN KBAutoRepeatMode +T} T{ +(1L<<7) +T} +.TE +.IN "XKeyboardControl" "" "@DEF@" +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +/* Values */ + +typedef struct { + int key_click_percent; + int bell_percent; + int bell_pitch; + int bell_duration; + int led; + int led_mode; /* LedModeOn, LedModeOff */ + int key; + int auto_repeat_mode; /* AutoRepeatModeOff, AutoRepeatModeOn, + AutoRepeatModeDefault */ +} XKeyboardControl; +.De +.LP +.eM +The key_click_percent member sets the volume for key clicks between 0 (off) +and 100 (loud) inclusive, if possible. +A setting of \-1 restores the default. +Other negative values generate a +.PN BadValue +error. +.LP +The bell_percent sets the base volume for the bell between 0 (off) and 100 +(loud) inclusive, if possible. +A setting of \-1 restores the default. +Other negative values generate a +.PN BadValue +error. +The bell_pitch member sets the pitch (specified in Hz) of the bell, if possible. +A setting of \-1 restores the default. +Other negative values generate a +.PN BadValue +error. +The bell_duration member sets the duration of the +bell specified in milliseconds, if possible. +A setting of \-1 restores the default. +Other negative values generate a +.PN BadValue +error. +.LP +If both the led_mode and led members are specified, +the state of that LED is changed, if possible. +The led_mode member can be set to +.PN LedModeOn +or +.PN LedModeOff . +If only led_mode is specified, the state of +all LEDs are changed, if possible. +At most 32 LEDs numbered from one are supported. +No standard interpretation of LEDs is defined. +If led is specified without led_mode, a +.PN BadMatch +error results. +.LP +If both the auto_repeat_mode and key members are specified, +the auto_repeat_mode of that key is changed (according to +.PN AutoRepeatModeOn , +.PN AutoRepeatModeOff , +or +.PN AutoRepeatModeDefault ), +if possible. +If only auto_repeat_mode is +specified, the global auto_repeat_mode for the entire keyboard is +changed, if possible, and does not affect the per-key settings. +If a key is specified without an auto_repeat_mode, a +.PN BadMatch +error results. +Each key has an individual mode of whether or not it should auto-repeat +and a default setting for the mode. +In addition, +there is a global mode of whether auto-repeat should be enabled or not +and a default setting for that mode. +When global mode is +.PN AutoRepeatModeOn , +keys should obey their individual auto-repeat modes. +When global mode is +.PN AutoRepeatModeOff , +no keys should auto-repeat. +An auto-repeating key generates alternating +.PN KeyPress +and +.PN KeyRelease +events. +When a key is used as a modifier, +it is desirable for the key not to auto-repeat, +regardless of its auto-repeat setting. +.LP +A bell generator connected with the console but not directly on a +keyboard is treated as if it were part of the keyboard. +The order in which controls are verified and altered is server-dependent. +If an error is generated, a subset of the controls may have been altered. +.LP +.sp +.IN "XChangeKeyboardControl" "" "@DEF@" +.sM +.FD 0 +XChangeKeyboardControl\^(\^\fIdisplay\fP, \fIvalue_mask\fP\^, \fIvalues\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + unsigned long \fIvalue_mask\fP\^; +.br + XKeyboardControl *\fIvalues\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIvalue_mask\fP 1i +Specifies which controls to change. +This mask is the bitwise inclusive OR of the valid control mask bits. +.IP \fIvalues\fP 1i +Specifies one value for each bit set to 1 in the mask. +.LP +.eM +The +.PN XChangeKeyboardControl +function controls the keyboard characteristics defined by the +.PN XKeyboardControl +structure. +The value_mask argument specifies which values are to be changed. +.LP +.PN XChangeKeyboardControl +can generate +.PN BadMatch +and +.PN BadValue +errors. +.LP +.sp +To obtain the current control values for the keyboard, use +.PN XGetKeyboardControl . +.IN "XGetKeyboardControl" "" "@DEF@" +.sM +.FD 0 +XGetKeyboardControl\^(\^\fIdisplay\fP, \fIvalues_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XKeyboardState *\fIvalues_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIvalues_return\fP 1i +Returns the current keyboard controls in the specified +.PN XKeyboardState +structure. +.LP +.eM +The +.PN XGetKeyboardControl +function returns the current control values for the keyboard to the +.PN XKeyboardState +structure. +.LP +.IN "XGetKeyboardControl" +.IN "XKeyboardState" "" "@DEF@" +.sM +.Ds 0 +.TA .5i +.ta .5i +typedef struct { + int key_click_percent; + int bell_percent; + unsigned int bell_pitch, bell_duration; + unsigned long led_mask; + int global_auto_repeat; + char auto_repeats[32]; +} XKeyboardState; +.De +.LP +.eM +For the LEDs, +the least significant bit of led_mask corresponds to LED one, +and each bit set to 1 in led_mask indicates an LED that is lit. +The global_auto_repeat member can be set to +.PN AutoRepeatModeOn +or +.PN AutoRepeatModeOff . +The auto_repeats member is a bit vector. +Each bit set to 1 indicates that auto-repeat is enabled +for the corresponding key. +The vector is represented as 32 bytes. +Byte N (from 0) contains the bits for keys 8N to 8N + 7 +with the least significant bit in the byte representing key 8N. +.LP +.sp +To turn on keyboard auto-repeat, use +.PN XAutoRepeatOn . +.IN "XAutoRepeatOn" "" "@DEF@" +.sM +.FD 0 +XAutoRepeatOn\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +The +.PN XAutoRepeatOn +function turns on auto-repeat for the keyboard on the specified display. +.LP +.sp +To turn off keyboard auto-repeat, use +.PN XAutoRepeatOff . +.IN "XAutoRepeatOff" "" "@DEF@" +.sM +.FD 0 +XAutoRepeatOff\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +The +.PN XAutoRepeatOff +function turns off auto-repeat for the keyboard on the specified display. +.LP +.sp +To ring the bell, use +.PN XBell . +.IN "XBell" "" "@DEF@" +.sM +.FD 0 +XBell\^(\^\fIdisplay\fP, \fIpercent\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIpercent\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIpercent\fP 1i +Specifies the volume for the bell, +which can range from \-100 to 100 inclusive. +.LP +.eM +The +.PN XBell +function rings the bell on the keyboard on the specified display, if possible. +The specified volume is relative to the base volume for the keyboard. +If the value for the percent argument is not in the range \-100 to 100 +inclusive, a +.PN BadValue +error results. +The volume at which the bell rings +when the percent argument is nonnegative is: +.IP +base \- [(base * percent) / 100] + percent +.LP +The volume at which the bell rings +when the percent argument is negative is: +.IP +base + [(base * percent) / 100] +.LP +To change the base volume of the bell, use +.PN XChangeKeyboardControl . +.LP +.PN XBell +can generate a +.PN BadValue +error. +.LP +.sp +To obtain a bit vector that describes the state of the keyboard, use +.PN XQueryKeymap . +.IN "XQueryKeymap" "" "@DEF@" +.sM +.FD 0 +XQueryKeymap\^(\^\fIdisplay\fP, \fIkeys_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + char \fIkeys_return\fP[32]\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIkeys_return\fP 1i +Returns an array of bytes that identifies which keys are pressed down. +Each bit represents one key of the keyboard. +.LP +.eM +The +.PN XQueryKeymap +function returns a bit vector for the logical state of the keyboard, +where each bit set to 1 indicates that the corresponding key is currently +pressed down. +The vector is represented as 32 bytes. +Byte N (from 0) contains the bits for keys 8N to 8N + 7 +with the least significant bit in the byte representing key 8N. +.LP +Note that the logical state of a device (as seen by client applications) +may lag the physical state if device event processing is frozen. +.LP +.sp +To set the mapping of the pointer buttons, use +.PN XSetPointerMapping . +.IN "XSetPointerMapping" "" "@DEF@" +.sM +.FD 0 +int XSetPointerMapping\^(\^\fIdisplay\fP, \fImap\fP, \fInmap\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + unsigned char \fImap\fP\^[]\^; +.br + int \fInmap\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fImap\fP 1i +Specifies the mapping list. +.IP \fInmap\fP 1i +Specifies the number of items in the mapping list. +.LP +.eM +The +.PN XSetPointerMapping +function sets the mapping of the pointer. +If it succeeds, the X server generates a +.PN MappingNotify +event, and +.PN XSetPointerMapping +returns +.PN MappingSuccess . +Element map[i] defines the logical button number for the physical button +i+1. +The length of the list must be the same as +.PN XGetPointerMapping +would return, +or a +.PN BadValue +error results. +A zero element disables a button, and elements are not restricted in +value by the number of physical buttons. +However, no two elements can have the same nonzero value, +or a +.PN BadValue +error results. +If any of the buttons to be altered are logically in the down state, +.PN XSetPointerMapping +returns +.PN MappingBusy , +and the mapping is not changed. +.LP +.PN XSetPointerMapping +can generate a +.PN BadValue +error. +.LP +.sp +To get the pointer mapping, use +.PN XGetPointerMapping . +.IN "XGetPointerMapping" "" "@DEF@" +.sM +.FD 0 +int XGetPointerMapping\^(\^\fIdisplay\fP, \fImap_return\fP, \fInmap\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + unsigned char \fImap_return\fP\^[]\^; +.br + int \fInmap\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fImap_return\fP 1i +Returns the mapping list. +.IP \fInmap\fP 1i +Specifies the number of items in the mapping list. +.LP +.eM +The +.PN XGetPointerMapping +function returns the current mapping of the pointer. +Pointer buttons are numbered starting from one. +.PN XGetPointerMapping +returns the number of physical buttons actually on the pointer. +The nominal mapping for a pointer is map[i]=i+1. +The nmap argument specifies the length of the array where the pointer +mapping is returned, and only the first nmap elements are returned +in map_return. +.LP +.sp +To control the pointer's interactive feel, use +.PN XChangePointerControl . +.IN "XChangePointerControl" "" "@DEF@" +.sM +.FD 0 +XChangePointerControl\^(\^\fIdisplay\fP, \fIdo_accel\fP\^, \fIdo_threshold\fP\^, \fIaccel_numerator\fP\^, +.br + \fIaccel_denominator\fP\^, \fIthreshold\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Bool \fIdo_accel\fP\^, \fIdo_threshold\fP\^; +.br + int \fIaccel_numerator\fP\^, \fIaccel_denominator\fP\^; +.br + int \fIthreshold\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIdo_accel\fP 1i +Specifies a Boolean value that controls whether the values for +the accel_numerator or accel_denominator are used. +.IP \fIdo_threshold\fP 1i +Specifies a Boolean value that controls whether the value for the +threshold is used. +.IP \fIaccel_numerator\fP 1i +Specifies the numerator for the acceleration multiplier. +.IP \fIaccel_denominator\fP 1i +Specifies the denominator for the acceleration multiplier. +.IP \fIthreshold\fP 1i +Specifies the acceleration threshold. +.LP +.eM +The +.PN XChangePointerControl +function defines how the pointing device moves. +The acceleration, expressed as a fraction, is a +multiplier for movement. +For example, +specifying 3/1 means the pointer moves three times as fast as normal. +The fraction may be rounded arbitrarily by the X server. +Acceleration +only takes effect if the pointer moves more than threshold pixels at +once and only applies to the amount beyond the value in the threshold argument. +Setting a value to \-1 restores the default. +The values of the do_accel and do_threshold arguments must be +.PN True +for the pointer values to be set, +or the parameters are unchanged. +Negative values (other than \-1) generate a +.PN BadValue +error, as does a zero value +for the accel_denominator argument. +.LP +.PN XChangePointerControl +can generate a +.PN BadValue +error. +.LP +.sp +To get the current pointer parameters, use +.PN XGetPointerControl . +.IN "XGetPointerControl" "" "@DEF@" +.sM +.FD 0 +XGetPointerControl\^(\^\fIdisplay\fP, \fIaccel_numerator_return\fP\^, \fIaccel_denominator_return\fP\^, +.br + \fIthreshold_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int *\fIaccel_numerator_return\fP\^, *\fIaccel_denominator_return\fP\^; +.br + int *\fIthreshold_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIaccel_numerator_return\fP 1i +Returns the numerator for the acceleration multiplier. +.IP \fIaccel_denominator_return\fP 1i +Returns the denominator for the acceleration multiplier. +.IP \fIthreshold_return\fP 1i +Returns the acceleration threshold. +.LP +.eM +The +.PN XGetPointerControl +function returns the pointer's current acceleration multiplier +and acceleration threshold. +.NH 2 +Manipulating the Keyboard Encoding +.XS +\*(SN Manipulating the Keyboard Encoding +.XE +.LP +A KeyCode represents a physical (or logical) key. +KeyCodes lie in the inclusive range [8,255]. +A KeyCode value carries no intrinsic information, +although server implementors may attempt to encode geometry +(for example, matrix) information in some fashion so that it can +be interpreted in a server-dependent fashion. +The mapping between keys and KeyCodes cannot be changed. +.LP +A KeySym is an encoding of a symbol on the cap of a key. +The set of defined KeySyms includes the ISO Latin character sets (1\-4), +Katakana, Arabic, Cyrillic, Greek, Technical, +Special, Publishing, APL, Hebrew, Thai, Korean +and a miscellany of keys found +on keyboards (Return, Help, Tab, and so on). +To the extent possible, these sets are derived from international +standards. +In areas where no standards exist, +some of these sets are derived from Digital Equipment Corporation standards. +The list of defined symbols can be found in +.hN X11/keysymdef.h . +Unfortunately, some C preprocessors have +limits on the number of defined symbols. +If you must use KeySyms not +in the Latin 1\-4, Greek, and miscellaneous classes, +you may have to define a symbol for those sets. +Most applications usually only include +.hN X11/keysym.h , +which defines symbols for ISO Latin 1\-4, Greek, and miscellaneous. +.LP +A list of KeySyms is associated with each KeyCode. +The list is intended to convey the set of symbols on the corresponding key. +If the list (ignoring trailing +.PN NoSymbol +entries) is +a single KeySym ``\fIK\fP'', +then the list is treated as if it were the list +``\fIK\fP NoSymbol \fIK\fP NoSymbol''. +If the list (ignoring trailing +.PN NoSymbol +entries) is a pair of KeySyms ``\fIK1 K2\fP'', +then the list is treated as if it were the list ``\fIK1 K2 K1 K2\fP''. +If the list (ignoring trailing +.PN NoSymbol +entries) is a triple of KeySyms ``\fIK1 K2 K3\fP'', +then the list is treated as if it were the list ``\fIK1 K2 K3\fP NoSymbol''. +When an explicit ``void'' element is desired in the list, +the value +.PN VoidSymbol +can be used. +.LP +The first four elements of the list are split into two groups of KeySyms. +Group 1 contains the first and second KeySyms; +Group 2 contains the third and fourth KeySyms. +Within each group, +if the second element of the group is +.PN NoSymbol , +then the group should be treated as if the second element were +the same as the first element, +except when the first element is an alphabetic KeySym ``\fIK\fP'' +for which both lowercase and uppercase forms are defined. +In that case, +the group should be treated as if the first element were +the lowercase form of ``\fIK\fP'' and the second element were +the uppercase form of ``\fIK\fP''. +.LP +The standard rules for obtaining a KeySym from a +.PN KeyPress +event make use of only the Group 1 and Group 2 KeySyms; +no interpretation of other KeySyms in the list is given. +Which group to use is determined by the modifier state. +Switching between groups is controlled by the KeySym named MODE SWITCH, +by attaching that KeySym to some KeyCode and attaching +that KeyCode to any one of the modifiers +.PN Mod1 +through +.PN Mod5 . +This modifier is called the \fIgroup modifier\fP\^. +For any KeyCode, +Group 1 is used when the group modifier is off, +and Group 2 is used when the group modifier is on. +.LP +The +.PN Lock +modifier is interpreted as CapsLock when the KeySym named XK_Caps_Lock +is attached to some KeyCode and that KeyCode is attached to the +.PN Lock +modifier. The +.PN Lock +modifier is interpreted as ShiftLock when the KeySym named XK_Shift_Lock +is attached to some KeyCode and that KeyCode is attached to the +.PN Lock +modifier. If the +.PN Lock +modifier could be interpreted as both +CapsLock and ShiftLock, the CapsLock interpretation is used. +.LP +The operation of keypad keys is controlled by the KeySym named XK_Num_Lock, +by attaching that KeySym to some KeyCode and attaching that KeyCode to any +one of the modifiers +.PN Mod1 +through +.PN Mod5 . +This modifier is called the +\fInumlock modifier\fP\^. The standard KeySyms with the prefix ``XK_KP_'' +in their +name are called keypad KeySyms; these are KeySyms with numeric value in +the hexadecimal range 0xFF80 to 0xFFBD inclusive. In addition, +vendor-specific KeySyms in the hexadecimal range 0x11000000 to 0x1100FFFF +are also keypad KeySyms. +.LP +Within a group, the choice of KeySym is determined by applying the first +rule that is satisfied from the following list: +.IP \(bu 5 +The numlock modifier is on and the second KeySym is a keypad KeySym. In +this case, if the +.PN Shift +modifier is on, or if the +.PN Lock +modifier is on and +is interpreted as ShiftLock, then the first KeySym is used, otherwise the +second KeySym is used. +.IP \(bu 5 +The +.PN Shift +and +.PN Lock +modifiers are both off. In this case, the first +KeySym is used. +.IP \(bu 5 +The +.PN Shift +modifier is off, and the +.PN Lock +modifier is on and is +interpreted as CapsLock. In this case, the first KeySym is used, but if +that KeySym is lowercase alphabetic, then the corresponding uppercase +KeySym is used instead. +.IP \(bu 5 +The +.PN Shift +modifier is on, and the +.PN Lock +modifier is on and is interpreted +as CapsLock. In this case, the second KeySym is used, but if that KeySym +is lowercase alphabetic, then the corresponding uppercase KeySym is used +instead. +.IP \(bu 5 +The +.PN Shift +modifier is on, or the +.PN Lock +modifier is on and is interpreted +as ShiftLock, or both. In this case, the second KeySym is used. +.LP +No spatial geometry of the symbols on the key is defined by +their order in the KeySym list, +although a geometry might be defined on a +server-specific basis. +The X server does not use the mapping between KeyCodes and KeySyms. +Rather, it merely stores it for reading and writing by clients. +.sp +.LP +To obtain the legal KeyCodes for a display, use +.PN XDisplayKeycodes . +.IN "XDisplayKeycodes" "" "@DEF@" +.sM +.FD 0 +XDisplayKeycodes\^(\^\fIdisplay\fP\^, \fImin_keycodes_return\fP\^, \ +\fImax_keycodes_return\fP\^) +.br + Display *\^\fIdisplay\fP\^; +.br + int *\^\fImin_keycodes_return\fP\^, *\^\fImax_keycodes_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fImin_keycodes_return\fP 1i +Returns the minimum number of KeyCodes. +.IP \fImax_keycodes_return\fP 1i +Returns the maximum number of KeyCodes. +.LP +.eM +The +.PN XDisplayKeycodes +function returns the min-keycodes and max-keycodes supported by the +specified display. +The minimum number of KeyCodes returned is never less than 8, +and the maximum number of KeyCodes returned is never greater than 255. +Not all KeyCodes in this range are required to have corresponding keys. +.sp +.LP +To obtain the symbols for the specified KeyCodes, use +.PN XGetKeyboardMapping . +.IN "XGetKeyboardMapping" "" "@DEF@" +.sM +.FD 0 +KeySym *XGetKeyboardMapping(\^\fIdisplay\fP, \fIfirst_keycode\fP, \fIkeycode_count\fP, +.br + \fIkeysyms_per_keycode_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + KeyCode \fIfirst_keycode\fP\^; +.br + int \fIkeycode_count\fP\^; +.br + int *\fIkeysyms_per_keycode_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.ds Kc returned +.IP \fIfirst_keycode\fP 1i +Specifies the first KeyCode that is to be \*(Kc. +.IP \fIkeycode_count\fP 1i +Specifies the number of KeyCodes that are to be returned. +.IP \fIkeysyms_per_keycode_return\fP 1i +Returns the number of KeySyms per KeyCode. +.LP +.eM +The +.PN XGetKeyboardMapping +function returns the symbols for the specified number of KeyCodes +starting with first_keycode. +The value specified in first_keycode must be greater than +or equal to min_keycode as returned by +.PN XDisplayKeycodes , +or a +.PN BadValue +error results. +In addition, the following expression must be less than or equal +to max_keycode as returned by +.PN XDisplayKeycodes : +.LP +.Ds +first_keycode + keycode_count \- 1 +.De +.LP +If this is not the case, a +.PN BadValue +error results. +The number of elements in the KeySyms list is: +.LP +.Ds +keycode_count * keysyms_per_keycode_return +.De +.LP +KeySym number N, counting from zero, for KeyCode K has the following index +in the list, counting from zero: +.Ds +(K \- first_code) * keysyms_per_code_return + N +.De +.LP +The X server arbitrarily chooses the keysyms_per_keycode_return value +to be large enough to report all requested symbols. +A special KeySym value of +.PN NoSymbol +is used to fill in unused elements for +individual KeyCodes. +To free the storage returned by +.PN XGetKeyboardMapping , +use +.PN XFree . +.LP +.PN XGetKeyboardMapping +can generate a +.PN BadValue +error. +.LP +.sp +To change the keyboard mapping, use +.PN XChangeKeyboardMapping . +.IN "XChangeKeyboardMapping" "" "@DEF@" +.sM +.FD 0 +XChangeKeyboardMapping(\^\fIdisplay\fP, \fIfirst_keycode\fP, \fIkeysyms_per_keycode\fP, \fIkeysyms\fP, \fInum_codes\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIfirst_keycode\fP\^; +.br + int \fIkeysyms_per_keycode\fP\^; +.br + KeySym *\fIkeysyms\fP\^; +.br + int \fInum_codes\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.ds Kc changed +.IP \fIfirst_keycode\fP 1i +Specifies the first KeyCode that is to be \*(Kc. +.IP \fIkeysyms_per_keycode\fP 1i +Specifies the number of KeySyms per KeyCode. +.IP \fIkeysyms\fP 1i +Specifies an array of KeySyms. +.IP \fInum_codes\fP 1i +Specifies the number of KeyCodes that are to be changed. +.LP +.eM +The +.PN XChangeKeyboardMapping +function defines the symbols for the specified number of KeyCodes +starting with first_keycode. +The symbols for KeyCodes outside this range remain unchanged. +The number of elements in keysyms must be: +.LP +.Ds +num_codes * keysyms_per_keycode +.De +.LP +The specified first_keycode must be greater than or equal to min_keycode +returned by +.PN XDisplayKeycodes , +or a +.PN BadValue +error results. +In addition, the following expression must be less than or equal to +max_keycode as returned by +.PN XDisplayKeycodes , +or a +.PN BadValue +error results: +.LP +.Ds +first_keycode + num_codes \- 1 +.De +.LP +KeySym number N, counting from zero, for KeyCode K has the following index +in keysyms, counting from zero: +.LP +.Ds +(K \- first_keycode) * keysyms_per_keycode + N +.De +.LP +The specified keysyms_per_keycode can be chosen arbitrarily by the client +to be large enough to hold all desired symbols. +A special KeySym value of +.PN NoSymbol +should be used to fill in unused elements +for individual KeyCodes. +It is legal for +.PN NoSymbol +to appear in nontrailing positions +of the effective list for a KeyCode. +.PN XChangeKeyboardMapping +generates a +.PN MappingNotify +event. +.LP +There is no requirement that the X server interpret this mapping. +It is merely stored for reading and writing by clients. +.LP +.PN XChangeKeyboardMapping +can generate +.PN BadAlloc +and +.PN BadValue +errors. +.LP +The next six functions make use of the +.PN XModifierKeymap +data structure, which contains: +.LP +.IN "XModifierKeymap" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef struct { + int max_keypermod; /* This server's max number of keys per modifier */ + KeyCode *modifiermap; /* An 8 by max_keypermod array of the modifiers */ +} XModifierKeymap; +.De +.LP +.eM +To create an +.PN XModifierKeymap +structure, use +.PN XNewModifiermap . +.IN "XNewModifiermap" "" "@DEF@" +.sM +.FD 0 +XModifierKeymap *XNewModifiermap(\^\fImax_keys_per_mod\fP\^) +.br + int \fImax_keys_per_mod\fP\^; +.FN +.IP \fImax_keys_per_mod\fP 1i +Specifies the number of KeyCode entries preallocated to the modifiers +in the map. +.LP +.eM +The +.PN XNewModifiermap +function returns a pointer to +.PN XModifierKeymap +structure for later use. +.LP +.sp +To add a new entry to an +.PN XModifierKeymap +structure, use +.PN XInsertModifiermapEntry . +.IN "XInsertModifiermapEntry" "" "@DEF@" +.sM +.FD 0 +XModifierKeymap *XInsertModifiermapEntry\^(\^\fImodmap\fP, \ +\fIkeycode_entry\fP, \fImodifier\fP\^) +.br + XModifierKeymap *\fImodmap\fP\^; +.br + KeyCode \fIkeycode_entry\fP\^; +.br + int \fImodifier\fP\^; +.FN +.IP \fImodmap\fP 1i +Specifies the +.PN XModifierKeymap +structure. +.IP \fIkeycode_entry\fP 1i +Specifies the KeyCode. +.IP \fImodifier\fP 1i +Specifies the modifier. +.LP +.eM +The +.PN XInsertModifiermapEntry +function adds the specified KeyCode to the set that controls the specified +modifier and returns the resulting +.PN XModifierKeymap +structure (expanded as needed). +.LP +.sp +To delete an entry from an +.PN XModifierKeymap +structure, use +.PN XDeleteModifiermapEntry . +.IN "XDeleteModifiermapEntry" "" "@DEF@" +.sM +.FD 0 +XModifierKeymap *XDeleteModifiermapEntry\^(\^\fImodmap\fP, \ +\fIkeycode_entry\fP, \fImodifier\fP\^) +.br + XModifierKeymap *\fImodmap\fP\^; +.br + KeyCode \fIkeycode_entry\fP\^; +.br + int \fImodifier\fP\^; +.FN +.IP \fImodmap\fP 1i +Specifies the +.PN XModifierKeymap +structure. +.IP \fIkeycode_entry\fP 1i +Specifies the KeyCode. +.IP \fImodifier\fP 1i +Specifies the modifier. +.LP +.eM +The +.PN XDeleteModifiermapEntry +function deletes the specified KeyCode from the set that controls the +specified modifier and returns a pointer to the resulting +.PN XModifierKeymap +structure. +.LP +.sp +To destroy an +.PN XModifierKeymap +structure, use +.PN XFreeModifiermap . +.IN "XFreeModifiermap" "" "@DEF@" +.sM +.FD 0 +XFreeModifiermap(\^\fImodmap\fP\^) +.br + XModifierKeymap *\fImodmap\fP; +.FN +.IP \fImodmap\fP 1i +Specifies the +.PN XModifierKeymap +structure. +.LP +.eM +The +.PN XFreeModifiermap +function frees the specified +.PN XModifierKeymap +structure. +.LP +.sp +To set the KeyCodes to be used as modifiers, use +.PN XSetModifierMapping . +.IN "XSetModifierMapping" "" "@DEF@" +.sM +.FD 0 +int XSetModifierMapping(\^\fIdisplay\fP, \fImodmap\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XModifierKeymap *\fImodmap\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fImodmap\fP 1i +Specifies the +.PN XModifierKeymap +structure. +.LP +.eM +The +.PN XSetModifierMapping +function specifies the KeyCodes of the keys (if any) that are to be used +as modifiers. +If it succeeds, +the X server generates a +.PN MappingNotify +event, and +.PN XSetModifierMapping +returns +.PN MappingSuccess . +X permits at most 8 modifier keys. +If more than 8 are specified in the +.PN XModifierKeymap +structure, a +.PN BadLength +error results. +.LP +The modifiermap member of the +.PN XModifierKeymap +structure contains 8 sets of max_keypermod KeyCodes, +one for each modifier in the order +.PN Shift , +.PN Lock , +.PN Control , +.PN Mod1 , +.PN Mod2 , +.PN Mod3 , +.PN Mod4 , +and +.PN Mod5 . +Only nonzero KeyCodes have meaning in each set, +and zero KeyCodes are ignored. +In addition, all of the nonzero KeyCodes must be in the range specified by +min_keycode and max_keycode in the +.PN Display +structure, +or a +.PN BadValue +error results. +.LP +An X server can impose restrictions on how modifiers can be changed, +for example, +if certain keys do not generate up transitions in hardware, +if auto-repeat cannot be disabled on certain keys, +or if multiple modifier keys are not supported. +If some such restriction is violated, +the status reply is +.PN MappingFailed , +and none of the modifiers are changed. +If the new KeyCodes specified for a modifier differ from those +currently defined and any (current or new) keys for that modifier are +in the logically down state, +.PN XSetModifierMapping +returns +.PN MappingBusy , +and none of the modifiers is changed. +.LP +.PN XSetModifierMapping +can generate +.PN BadAlloc +and +.PN BadValue +errors. +.LP +.sp +To obtain the KeyCodes used as modifiers, use +.PN XGetModifierMapping . +.IN "XGetModifierMapping" "" "@DEF@" +.sM +.FD 0 +XModifierKeymap *XGetModifierMapping(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; + +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +The +.PN XGetModifierMapping +function returns a pointer to a newly created +.PN XModifierKeymap +structure that contains the keys being used as modifiers. +The structure should be freed after use by calling +.PN XFreeModifiermap . +If only zero values appear in the set for any modifier, +that modifier is disabled. +.bp diff --git a/libX11/specs/libX11/CH13 b/libX11/specs/libX11/CH13 new file mode 100644 index 000000000..ed143c690 --- /dev/null +++ b/libX11/specs/libX11/CH13 @@ -0,0 +1,7673 @@ +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be included +.\" in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR +.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +.\" OTHER DEALINGS IN THE SOFTWARE. +.\" +.\" Except as contained in this notice, the name of the X Consortium shall +.\" not be used in advertising or otherwise to promote the sale, use or +.\" other dealings in this Software without prior written authorization +.\" from the X Consortium. +.\" +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by +.\" Digital Equipment Corporation +.\" +.\" Portions Copyright \(co 1990, 1991 by +.\" Tektronix, Inc. +.\" +.\" Permission to use, copy, modify and distribute this documentation for +.\" any purpose and without fee is hereby granted, provided that the above +.\" copyright notice appears in all copies and that both that copyright notice +.\" and this permission notice appear in all copies, and that the names of +.\" Digital and Tektronix not be used in in advertising or publicity pertaining +.\" to this documentation without specific, written prior permission. +.\" Digital and Tektronix makes no representations about the suitability +.\" of this documentation for any purpose. +.\" It is provided ``as is'' without express or implied warranty. +.\" +\& +.sp 1 +.ce 3 +\s+1\fBChapter 13\fP\s-1 + +\s+1\fBLocales and Internationalized Text Functions\fP\s-1 +.sp 2 +.nr H1 13 +.nr H2 0 +.nr H3 0 +.nr H4 0 +.nr H5 0 +.na +.LP +.XS +Chapter 13: Locales and Internationalized Text Functions +.XE +An internationalized application is one that is adaptable to the requirements +of different native languages, local customs, and character string encodings. +The process of adapting the operation to a particular native language, +local custom, or string encoding is called \fIlocalization\fP\^. +A goal of internationalization is to permit localization +without program source modifications or recompilation. +.LP +As one of the localization mechanisms, +Xlib provides an X Input Method +.Pn ( XIM ) +functional interface for internationalized text input +and an X Output Method +.Pn ( XOM ) +functional interface for internationalized text output. +.LP +Internationalization in X is based on the concept of a \fIlocale\fP. +A locale defines the localized behavior of a program at run time. +Locales affect Xlib in its: +.IP \(bu 5 +Encoding and processing of input method text +.IP \(bu 5 +Encoding of resource files and values +.IP \(bu 5 +Encoding and imaging of text strings +.IP \(bu 5 +Encoding and decoding for inter-client text communication +.LP +Characters from various languages are represented in a computer +using an encoding. +Different languages have different encodings, +and there are even different encodings for the same characters +in the same language. +.LP +This chapter defines support for localized text imaging and text input +and describes the locale mechanism that controls all locale-dependent +Xlib functions. +Sets of functions are provided for multibyte (char *) text as well as +wide character (wchar_t) text in the form supported +by the host C language environment. +The multibyte and wide character functions +are equivalent except for the form of the text argument. +.LP +The Xlib internationalization functions are not meant to provide +support for multilingual applications (mixing multiple languages +within a single piece of text), but they make it possible to +implement applications that work in limited fashion with more than +one language in independent contexts. +.LP +The remainder of this chapter discusses: +.IP \(bu 5 +X locale management +.IP \(bu 5 +Locale and modifier dependencies +.IP \(bu 5 +Variable argument lists +.IP \(bu 5 +Output methods +.IP \(bu 5 +Input methods +.IP \(bu 5 +String constants +.NH 2 +X Locale Management +.XS +\*(SN X Locale Management +.XE +.LP +X supports one or more of the locales defined by the host environment. +On implementations that conform to the ANSI C library, +the locale announcement method is +.PN setlocale . +This function configures the locale operation of both +the host C library and Xlib. +The operation of Xlib is governed by the LC_CTYPE category; +this is called the \fIcurrent locale\fP. +An implementation is permitted to provide implementation-dependent +mechanisms for announcing the locale in addition to +.PN setlocale . +.LP +On implementations that do not conform to the ANSI C library, +the locale announcement method is Xlib implementation-dependent. +.LP +The mechanism by which the semantic operation of Xlib is defined +for a specific locale is implementation-dependent. +.LP +.sp +X is not required to support all the locales supported by the host. +To determine if the current locale is supported by X, use +.PN XSupportsLocale . +.IN "XSupportsLocale" "" "@DEF@" +.sM +.FD 0 +Bool XSupportsLocale\^(\|) +.FN +.LP +.eM +The +.PN XSupportsLocale +function returns +.PN True +if Xlib functions are capable of operating under the current locale. +If it returns +.PN False , +Xlib locale-dependent functions for which the +.PN XLocaleNotSupported +return status is defined will return +.PN XLocaleNotSupported . +Other Xlib locale-dependent routines will operate in the ``C'' locale. +.LP +The client is responsible for selecting its locale and X modifiers. +Clients should provide a means for the user to override the clients' +locale selection at client invocation. +Most single-display X clients operate in a single locale +for both X and the host processing environment. +They will configure the locale by calling three functions: +the host locale configuration function, +.PN XSupportsLocale , +and +.PN XSetLocaleModifiers . +.LP +The semantics of certain categories of X internationalization capabilities +can be configured by setting modifiers. +Modifiers are named by implementation-dependent and locale-specific strings. +The only standard use for this capability at present +is selecting one of several styles of keyboard input method. +.LP +.sp +To configure Xlib locale modifiers for the current locale, use +.PN XSetLocaleModifiers . +.IN "XSetLocaleModifiers" "" "@DEF@" +.sM +.FD 0 +char *XSetLocaleModifiers\^(\^\fImodifier_list\fP\^) +.br + char *\fImodifier_list\fP\^; +.FN +.IP \fImodifier_list\fP 1i +Specifies the modifiers. +.LP +.eM +The +.PN XSetLocaleModifiers +function sets the X modifiers for the current locale setting. +The modifier_list argument is a null-terminated string of the form +``{@\^\fIcategory\fP\^=\^\fIvalue\fP\^}'', that is, +having zero or more concatenated ``@\^\fIcategory\fP\^=\^\fIvalue\fP\^'' +entries, where \fIcategory\fP is a category name +and \fIvalue\fP is the (possibly empty) setting for that category. +The values are encoded in the current locale. +Category names are restricted to the POSIX Portable Filename Character Set. +.LP +The local host X locale modifiers announcer (on POSIX-compliant systems, +the XMODIFIERS environment variable) is appended to the modifier_list to +provide default values on the local host. +If a given category appears more than once in the list, +the first setting in the list is used. +If a given category is not included in the full modifier list, +the category is set to an implementation-dependent default +for the current locale. +An empty value for a category explicitly specifies the +implementation-dependent default. +.LP +If the function is successful, it returns a pointer to a string. +The contents of the string are such that a subsequent call with that string +(in the same locale) will restore the modifiers to the same settings. +If modifier_list is a NULL pointer, +.PN XSetLocaleModifiers +also returns a pointer to such a string, +and the current locale modifiers are not changed. +.LP +If invalid values are given for one or more modifier categories supported by +the locale, a NULL pointer is returned, and none of the +current modifiers are changed. +.LP +At program startup, +the modifiers that are in effect are unspecified until +the first successful call to set them. Whenever the locale is changed, the +modifiers that are in effect become unspecified until the next successful call +to set them. +Clients should always call +.PN XSetLocaleModifiers +with a non-NULL modifier_list after setting the locale +before they call any locale-dependent Xlib routine. +.LP +The only standard modifier category currently defined is ``im'', +which identifies the desired input method. +The values for input method are not standardized. +A single locale may use multiple input methods, +switching input method under user control. +The modifier may specify the initial input method in effect +or an ordered list of input methods. +Multiple input methods may be specified in a single im value string +in an implementation-dependent manner. +.LP +The returned modifiers string is owned by Xlib and should not be modified or +freed by the client. +It may be freed by Xlib after the current locale or modifiers are changed. +Until freed, it will not be modified by Xlib. +.LP +The recommended procedure for clients initializing their locale and modifiers +is to obtain locale and modifier announcers separately from +one of the following prioritized sources: +.IP \(bu 5 +A command line option +.IP \(bu 5 +A resource +.IP \(bu 5 +The empty string ("\^") +.LP +The first of these that is defined should be used. +Note that when a locale command line option or locale resource is defined, +the effect should be to set all categories to the specified locale, +overriding any category-specific settings in the local host environment. +.NH 2 +Locale and Modifier Dependencies +.XS +\*(SN Locale and Modifier Dependencies +.XE +.LP +The internationalized Xlib functions operate in the current locale +configured by the host environment and X locale modifiers set by +.PN XSetLocaleModifiers +or in the locale and modifiers configured at the time +some object supplied to the function was created. +For each locale-dependent function, +the following table describes the locale (and modifiers) dependency: +.TS H +lw(1.25i) lw(2.5i) lw(2i). +_ +.sp 6p +.B +Locale from Affects the Function In +.sp 6p +_ +.sp 6p +.TH +.R + Locale Query/Configuration: +.sp 6p +T{ +.PN setlocale +T} T{ +.PN XSupportsLocale +T} T{ +Locale queried +T} + T{ +.PN XSetLocaleModifiers +T} T{ +Locale modified +T} +.sp + Resources: +.sp 6p +T{ +.PN setlocale +T} T{ +.PN XrmGetFileDatabase +T} T{ +Locale of +.PN XrmDatabase +T} + T{ +.PN XrmGetStringDatabase +T} +T{ +.PN XrmDatabase +T} T{ +.PN XrmPutFileDatabase +T} T{ +Locale of +.PN XrmDatabase +T} + T{ +.PN XrmLocaleOfDatabase +T} +.sp + Setting Standard Properties: +.sp 6p +T{ +.PN setlocale +T} T{ +.PN XmbSetWMProperties +T} T{ +Encoding of supplied/returned +T} + text (some WM_ property + text in environment locale) +.sp 6p +T{ +.PN setlocale +T} T{ +.PN XmbTextPropertyToTextList +T} T{ +Encoding of supplied/returned text +T} + T{ +.PN XwcTextPropertyToTextList +T} + T{ +.PN XmbTextListToTextProperty +T} + T{ +.PN XwcTextListToTextProperty +T} +.sp + Text Input: +.sp 6p +T{ +.PN setlocale +T} T{ +.PN XOpenIM +T} T{ +XIM input method selection +T} + T{ +.PN XRegisterIMInstantiateCallback +T} T{ +XIM selection +T} + T{ +.PN XUnregisterIMInstantiateCallback +T} T{ +XIM selection +T} +T{ +.PN XIM +T} T{ +.PN XCreateIC +T} T{ +XIC input method configuration +T} + T{ +.PN XLocaleOfIM , +and so on +T} T{ +Queried locale +T} +T{ +.PN XIC +T} T{ +.PN XmbLookupString +T} T{ +Keyboard layout +T} + T{ +.PN XwcLookupString +T} T{ +Encoding of returned text +T} +.sp + Text Drawing: +.sp 6p +T{ +.PN setlocale +T} T{ +.PN XOpenOM +T} T{ +XOM output method selection +T} + T{ +.PN XCreateFontSet +T} T{ +Charsets of fonts in +.PN XFontSet +T} +T{ +.PN XOM +T} T{ +.PN XCreateOC +T} T{ +XOC output method configuration +T} + T{ +.PN XLocaleOfOM , +and so on +T} T{ +Queried locale +T} +T{ +.PN XFontSet +T} T{ +.PN XmbDrawText , +T} T{ +Locale of supplied text +T} + T{ +.PN XwcDrawText , +and so on +T} T{ +Locale of supplied text +T} + T{ +.PN XExtentsOfFontSet , +and so on +T} T{ +Locale-dependent metrics +T} + T{ +.PN XmbTextExtents , +T} + T{ +.PN XwcTextExtents , +and so on +T} +.sp + Xlib Errors: +.sp 6p +T{ +.PN setlocale +T} T{ +.PN XGetErrorDatabaseText +T} T{ +Locale of error message +T} + T{ +.PN XGetErrorText +T} +.sp 6p +_ +.TE +.LP +Clients may assume that a locale-encoded text string returned +by an X function can be passed to a C library routine, or vice versa, +if the locale is the same at the two calls. +.LP +All text strings processed by internationalized Xlib functions are assumed +to begin in the initial state of the encoding of the locale, if the encoding +is state-dependent. +.LP +All Xlib functions behave as if they do not change the current locale +or X modifier setting. +(This means that if they do change locale or call +.PN XSetLocaleModifiers +with a non-NULL argument, they must save and restore the current state on +entry and exit.) +Also, Xlib functions on implementations that conform to the ANSI C library do +not alter the global state associated with the ANSI C functions +.PN mblen , +.PN mbtowc , +.PN wctomb , +and +.PN strtok . +.NH 2 +Variable Argument Lists +.XS +\*(SN Variable Argument Lists +.XE +.LP +Various functions in this chapter have arguments that conform +to the ANSI C variable argument list calling convention. +Each function denoted with an argument of the form ``...'' takes +a variable-length list of name and value pairs, +where each name is a string and each value is of type +.PN XPointer . +A name argument that is NULL identifies the end of the list. +.LP +A variable-length argument list may contain a nested list. +If the name +.PN XNVaNestedList +is specified in place of an argument name, +then the following value is interpreted as an +.PN XVaNestedList +value that specifies a list of values logically inserted into the +original list at the point of declaration. +A NULL identifies the end of a nested list. +.LP +.sp +To allocate a nested variable argument list dynamically, use +.PN XVaCreateNestedList . +.IN "XVaCreateNestedList" "" @DEF@" +.sM +.FD 0 +typedef void * XVaNestedList; + +XVaNestedList XVaCreateNestedList\^(\^\fIdummy\fP\^, ...) +.br + int \fIdummy\fP\^; +.FN +.IP \fIdummy\fP 1i +Specifies an unused argument (required by ANSI C). +.ds Al +.IP ... 1i +Specifies the variable length argument list\*(Al. +.LP +.eM +The +.PN XVaCreateNestedList +function allocates memory and copies its arguments into +a single list pointer, +which may be used as a value for arguments requiring a list value. +Any entries are copied as specified. +Data passed by reference is not copied; +the caller must ensure data remains valid for the lifetime +of the nested list. +The list should be freed using +.PN XFree +when it is no longer needed. +.NH 2 +Output Methods +.XS +\*(SN Output Methods +.XE +.LP +This section provides discussions of the following X Output Method +(XOM) topics: +.IP \(bu 5 +Output method overview +.IP \(bu 5 +Output method functions +.IP \(bu 5 +Output method values +.IP \(bu 5 +Output context functions +.IP \(bu 5 +Output context values +.IP \(bu 5 +Creating and freeing a font set +.IP \(bu 5 +Obtaining font set metrics +.IP \(bu 5 +Drawing text using font sets +.NH 3 +Output Method Overview +.XS +\*(SN Output Method Overview +.XE +.LP +Locale-dependent text may include one or more text components, each of +which may require different fonts and character set encodings. +In some languages, each component might have a different +drawing direction, and some components might contain +context-dependent characters that change shape based on +relationships with neighboring characters. +.LP +When drawing such locale-dependent text, some locale-specific +knowledge is required; +for example, what fonts are required to draw the text, +how the text can be separated into components, and which +fonts are selected to draw each component. +Further, when bidirectional text must be drawn, +the internal representation order of the text must be changed +into the visual representation order to be drawn. +.LP +An X Output Method provides a functional interface so that clients +do not have to deal directly with such locale-dependent details. +Output methods provide the following capabilities: +.IP \(bu 5 +Creating a set of fonts required to draw locale-dependent text. +.IP \(bu 5 +Drawing locale-dependent text with a font set without the caller +needing to be aware of locale dependencies. +.IP \(bu 5 +Obtaining the escapement and extents in pixels of locale-dependent text. +.IP \(bu 5 +Determining if bidirectional or context-dependent drawing is required +in a specific locale with a specific font set. +.LP +Two different abstractions are used in the representation of +the output method for clients. +.LP +The abstraction used to communicate with an output method +is an opaque data structure represented by the +.PN XOM +data type. +The abstraction for representing the state of a particular output thread +is called an \fIoutput context\fP. +The Xlib representation of an output context is an +.PN XOC , +which is compatible with +.PN XFontSet +in terms of its functional interface, but is +a broader, more generalized abstraction. +.NH 3 +Output Method Functions +.XS +\*(SN Output Method Functions +.XE +.LP +To open an output method, use +.PN XOpenOM . +.IN "XOpenOM" "" "@DEF@" +.sM +.FD 0 +XOM XOpenOM\^(\^\fIdisplay\fP\^, \fIdb\fP\^, \fIres_name\fP\^, \fIres_class\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XrmDatabase \fIdb\fP\^; +.br + char *\fIres_name\fP\^; +.br + char *\fIres_class\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIdb\fP 1i +Specifies a pointer to the resource database. +.IP \fIres_name\fP 1i +Specifies the full resource name of the application. +.IP \fIres_class\fP 1i +Specifies the full class name of the application. +.LP +.eM +The +.PN XOpenOM +function opens an output method +matching the current locale and modifiers specification. +The current locale and modifiers are bound to the output method +when +.PN XOpenOM +is called. +The locale associated with an output method cannot be changed. +.LP +The specific output method to which this call will be routed +is identified on the basis of the current locale and modifiers. +.PN XOpenOM +will identify a default output method corresponding to the +current locale. +That default can be modified using +.PN XSetLocaleModifiers +to set the output method modifier. +.LP +The db argument is the resource database to be used by the output method +for looking up resources that are private to the output method. +It is not intended that this database be used to look +up values that can be set as OC values in an output context. +If db is NULL, +no database is passed to the output method. +.LP +The res_name and res_class arguments specify the resource name +and class of the application. +They are intended to be used as prefixes by the output method +when looking up resources that are common to all output contexts +that may be created for this output method. +The characters used for resource names and classes must be in the +X Portable Character Set. +The resources looked up are not fully specified +if res_name or res_class is NULL. +.LP +The res_name and res_class arguments are not assumed to exist beyond +the call to +.PN XOpenOM . +The specified resource database is assumed to exist for the lifetime +of the output method. +.LP +.PN XOpenOM +returns NULL if no output method could be opened. +.LP +.sp +To close an output method, use +.PN XCloseOM . +.IN "XCloseOM" "" "@DEF@" +.sM +.FD 0 +Status XCloseOM\^(\^\fIom\fP\^) +.br + XOM \fIom\fP\^; +.FN +.IP \fIom\fP 1i +Specifies the output method. +.LP +.eM +The +.PN XCloseOM +function closes the specified output method. +.LP +.sp +To set output method attributes, use +.PN XSetOMValues . +.IN "XSetOMValues" "" "@DEF@" +.sM +.FD 0 +char * XSetOMValues\^(\^\fIom\fP\^, ...) +.br + XOM \fIom\fP\^; +.FN +.IP \fIom\fP 1i +Specifies the output method. +.ds Al \ to set XOM values +.IP ... 1i +Specifies the variable-length argument list\*(Al. +.LP +.eM +The +.PN XSetOMValues +function presents a variable argument list programming interface +for setting properties or features of the specified output method. +This function returns NULL if it succeeds; +otherwise, +it returns the name of the first argument that could not be obtained. +.LP +No standard arguments are currently defined by Xlib. +.LP +.sp +To query an output method, use +.PN XGetOMValues . +.IN "XGetOMValues" "" "@DEF@" +.sM +.FD 0 +char * XGetOMValues\^(\^\fIom\fP\^, ...) +.br + XOM \fIom\fP\^; +.FN +.IP \fIom\fP 1i +Specifies the output method. +.ds Al \ to get XOM values +.IP ... 1i +Specifies the variable-length argument list\*(Al. +.LP +.eM +The +.PN XGetOMValues +function presents a variable argument list programming interface +for querying properties or features of the specified output method. +This function returns NULL if it succeeds; +otherwise, +it returns the name of the first argument that could not be obtained. +.LP +To obtain the display associated with an output method, use +.PN XDisplayOfOM . +.IN "XDisplayOfOM" "" "@DEF@" +.sM +.FD 0 +Display * XDisplayOfOM\^(\^\fIom\fP\^) +.br + XOM \fIom\fP\^; +.FN +.IP \fIom\fP 1i +Specifies the output method. +.LP +.eM +The +.PN XDisplayOfOM +function returns the display associated with the specified output method. +.LP +.sp +To get the locale associated with an output method, use +.PN XLocaleOfOM . +.IN "XLocaleOfOM" "" "@DEF@" +.sM +.FD 0 +char * XLocaleOfOM\^(\^\fIom\fP\^) +.br + XOM \fIom\fP\^; +.FN +.IP \fIom\fP 1i +Specifies the output method. +.LP +.eM +The +.PN XLocaleOfOM +returns the locale associated with the specified output method. +.NH 3 +X Output Method Values +.XS +\*(SN X Output Method Values +.XE +.LP +The following table describes how XOM values are interpreted by an +output method. +The first column lists the XOM values. The second column indicates +how each of the XOM values are treated by a particular output style. +.LP +.LP +The following key applies to this table. +.TS H +lw(1i) lw(4.75i). +_ +.sp 6p +.B +Key Explanation +.sp 6p +_ +.sp 6p +.TH +.R +G T{ +This value may be read using +.PN XGetOMValues . +T} +.sp 6p +_ +.TE +.LP +.TS H +lw(2.25i) c +lw(2.25i) c. +_ +.sp 6p +.B +XOM Value Key +.sp 6p +_ +.sp 6p +.TH +.R +T{ +.PN XNRequiredCharSet +T} T{ +G +T} +T{ +.PN XNQueryOrientation +T} T{ +G +T} +T{ +.PN XNDirectionalDependentDrawing +T} T{ +G +T} +T{ +.PN XNContextualDrawing +T} T{ +G +T} +.sp 6p +_ +.TE +.LP +.NH 4 +Required Char Set +.XS +\*(SN Required Char Set +.XE +.LP +The +.PN XNRequiredCharSet +argument returns the list of charsets that are required for loading the fonts +needed for the locale. +The value of the argument is a pointer to a structure of type +.PN XOMCharSetList . +.LP +The +.PN XOMCharSetList +structure is defined as follows: +.IN "XOMCharSetList" "" "@DEF@" +.sM +.LP +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef struct { + int charset_count; + char **charset_list; +} XOMCharSetList; +.De +.LP +.eM +The charset_list member is a list of one or more null-terminated +charset names, and the charset_count member is the number of +charset names. +.LP +The required charset list is owned by Xlib and should not be modified or +freed by the client. +It will be freed by a call to +.PN XCloseOM +with the associated +.PN XOM . +Until freed, its contents will not be modified by Xlib. +.LP +.NH 4 +Query Orientation +.XS +\*(SN Query Orientation +.XE +.LP +The +.PN XNQueryOrientation +argument returns the global orientation of text when drawn. +Other than +.PN XOMOrientation_LTR_TTB , +the set of orientations supported is locale-dependent. +The value of the argument is a pointer to a structure of type +.PN XOMOrientation . +Clients are responsible for freeing the +.PN XOMOrientation +structure by using +.PN XFree ; +this also frees the contents of the structure. +.LP +.sM +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef struct { + int num_orientation; + XOrientation *orientation; /* Input Text description */ +} XOMOrientation; + +typedef enum { + XOMOrientation_LTR_TTB, + XOMOrientation_RTL_TTB, + XOMOrientation_TTB_LTR, + XOMOrientation_TTB_RTL, + XOMOrientation_Context +} XOrientation; +.De +.LP +.eM +The possible value for XOrientation may be: +.IP \(bu 5 +.PN XOMOrientation_LTR_TTB +left-to-right, top-to-bottom global orientation +.IP \(bu 5 +.PN XOMOrientation_RTL_TTB +right-to-left, top-to-bottom global orientation +.IP \(bu 5 +.PN XOMOrientation_TTB_LTR +top-to-bottom, left-to-right global orientation +.IP \(bu 5 +.PN XOMOrientation_TTB_RTL +top-to-bottom, right-to-left global orientation +.IP \(bu 5 +.PN XOMOrientation_Context +contextual global orientation +.LP +.NH 4 +Directional Dependent Drawing +.XS +\*(SN Directional Dependent Drawing +.XE +.LP +The +.PN XNDirectionalDependentDrawing +argument indicates whether the text rendering functions +implement implicit handling of directional text. If this value +is +.PN True , +the output method has knowledge of directional +dependencies and reorders text as necessary when +rendering text. If this value is +.PN False , +the output method does not implement any directional text +handling, and all character directions are assumed to be left-to-right. +.LP +Regardless of the rendering order of characters, +the origins of all characters are on the primary draw direction side +of the drawing origin. +.LP +This OM value presents functionality identical to the +.PN XDirectionalDependentDrawing +function. +.NH 4 +Context Dependent Drawing +.XS +\*(SN Context Dependent Drawing +.XE +.LP +The +.PN XNContextualDrawing +argument indicates whether the text rendering functions +implement implicit context-dependent drawing. If this value is +.PN True , +the output method has knowledge of context dependencies and +performs character shape editing, combining glyphs to present +a single character as necessary. The actual shape editing is +dependent on the locale implementation and the font set used. +.LP +This OM value presents functionality identical to the +.PN XContextualDrawing +function. +.NH 3 +Output Context Functions +.XS +\*(SN Output Context Functions +.XE +.LP +An output context is an abstraction that contains both the data +required by an output method and the information required +to display that data. +There can be multiple output contexts for one output method. +The programming interfaces for creating, reading, or modifying +an output context use a variable argument list. +The name elements of the argument lists are referred to as XOC values. +It is intended that output methods be controlled by these XOC values. +As new XOC values are created, +they should be registered with the X Consortium. +An +.PN XOC +can be used anywhere an +.PN XFontSet +can be used, and vice versa; +.PN XFontSet +is retained for compatibility with previous releases. +The concepts of output methods and output contexts include broader, +more generalized abstraction than font set, +supporting complex and more intelligent text display, and dealing not only +with multiple fonts but also with context dependencies. +However, +.PN XFontSet +is widely used in several interfaces, so +.PN XOC +is defined as an upward compatible type of +.PN XFontSet . +.LP +.sp +To create an output context, use +.PN XCreateOC . +.IN "XCreateOC" "" "@DEF@" +.sM +.FD 0 +XOC XCreateOC\^(\^\fIom\fP\^, ...) +.br + XOM \fIom\fP\^; +.FN +.IP \fIom\fP 1i +Specifies the output method. +.ds Al \ to set XOC values +.IP ... 1i +Specifies the variable-length argument list\*(Al. +.LP +.eM +The +.PN XCreateOC +function creates an output context within the specified output method. +.LP +The base font names argument is mandatory at creation time, and +the output context will not be created unless it is provided. +All other output context values can be set later. +.LP +.PN XCreateOC +returns NULL if no output context could be created. +NULL can be returned for any of the following reasons: +.IP \(bu 5 +A required argument was not set. +.IP \(bu 5 +A read-only argument was set. +.IP \(bu 5 +An argument name is not recognized. +.IP \(bu 5 +The output method encountered an output method implementation-dependent error. +.LP +.PN XCreateOC +can generate a +.PN BadAtom +error. +.LP +.sp +To destroy an output context, use +.PN XDestroyOC . +.IN "XDestroyOC" "" "@DEF@" +.sM +.FD 0 +void XDestroyOC\^(\^\fIoc\fP\^) +.br + XOC \fIoc\fP\^; +.FN +.IP \fIoc\fP 1i +Specifies the output context. +.LP +.eM +The +.PN XDestroyOC +function destroys the specified output context. +.LP +.sp +To get the output method associated with an output context, use +.PN XOMOfOC . +.IN "XOMOfOC" "" "@DEF@" +.sM +.FD 0 +XOM XOMOfOC\^(\^\fIoc\fP\^) +.br + XOC \fIoc\fP\^; +.FN +.IP \fIoc\fP 1i +Specifies the output context. +.LP +.eM +The +.PN XOMOfOC +function returns the output method associated with the +specified output context. +.LP +.sp +Xlib provides two functions for setting and reading output context values, +respectively, +.PN XSetOCValues +and +.PN XGetOCValues . +Both functions have a variable-length argument list. +In that argument list, any XOC value's name must be denoted +with a character string using the X Portable Character Set. +.LP +.sp +To set XOC values, use +.PN XSetOCValues . +.IN "XSetOCValues" "" "@DEF@" +.sM +.FD 0 +char * XSetOCValues\^(\^\fIoc\fP\^, ...) +.br + XOC \fIoc\fP\^; +.FN +.IP \fIoc\fP 1i +Specifies the output context. +.ds Al \ to set XOC values +.IP ... 1i +Specifies the variable-length argument list\*(Al. +.LP +.eM +The +.PN XSetOCValues +function returns NULL if no error occurred; +otherwise, +it returns the name of the first argument that could not be set. +An argument might not be set for any of the following reasons: +.IP \(bu 5 +The argument is read-only. +.IP \(bu 5 +The argument name is not recognized. +.IP \(bu 5 +An implementation-dependent error occurs. +.LP +Each value to be set must be an appropriate datum, +matching the data type imposed by the semantics of the argument. +.LP +.PN XSetOCValues +can generate a +.PN BadAtom +error. +.LP +.sp +To obtain XOC values, use +.PN XGetOCValues . +.IN "XGetOCValues" "" "@DEF@" +.sM +.FD 0 +char * XGetOCValues\^(\^\fIoc\fP\^, ...) +.br + XOC \fIoc\fP\^; +.FN +.IP \fIoc\fP 1i +Specifies the output context. +.ds Al \ to get XOC values +.IP ... 1i +Specifies the variable-length argument list\*(Al. +.LP +.eM +The +.PN XGetOCValues +function returns NULL if no error occurred; otherwise, +it returns the name of the first argument that could not be obtained. +An argument might not be obtained for any of the following reasons: +.IP \(bu 5 +The argument name is not recognized. +.IP \(bu 5 +An implementation-dependent error occurs. +.LP +Each argument value +following a name must point to a location where the value is to be stored. +.NH 3 +Output Context Values +.XS +\*(SN Output Context Values +.XE +.LP +The following table describes how XOC values are interpreted +by an output method. +The first column lists the XOC values. +The second column indicates the alternative interfaces that function +identically and are provided for compatibility with previous releases. +The third column indicates how each of the XOC values is treated. +.LP +The following keys apply to this table. +.TS H +lw(1i) lw(4.75i). +_ +.sp 6p +.B +Key Explanation +.sp 6p +_ +.TH +.R +C T{ +This value must be set with +.PN XCreateOC . +T} +D T{ +This value may be set using +.PN XCreateOC . +If it is not set, +.br +a default is provided. +T} +G T{ +This value may be read using +.PN XGetOCValues . +T} +S T{ +This value must be set using +.PN XSetOCValues . +T} +.sp 6p +_ +.TE +.LP +.TS H +l c c +l c c. +_ +.sp 6p +.B +XOC Value Alternative Interface Key +.sp 6p +_ +.sp 6p +.TH +.R +T{ +BaseFontName +T} T{ +.PN XCreateFontSet +T} T{ +C-G +T} +T{ +MissingCharSet +T} T{ +.PN XCreateFontSet +T} T{ +G +T} +T{ +DefaultString +T} T{ +.PN XCreateFontSet +T} T{ +G +T} +T{ +Orientation +T} T{ +\- +T} T{ +D-S-G +T} +T{ +ResourceName +T} T{ +\- +T} T{ +S-G +T} +T{ +ResourceClass +T} T{ +\- +T} T{ +S-G +T} +T{ +FontInfo +T} T{ +.PN XFontsOfFontSet +T} T{ +G +T} +T{ +OMAutomatic +T} T{ +\- +T} T{ +G +T} +.sp 6p +_ +.TE +.LP +.NH 4 +Base Font Name +.XS +\*(SN Base Font Name +.XE +.LP +The +.PN XNBaseFontName +argument is a list of base font names that Xlib uses +to load the fonts needed for the locale. +The base font names are a comma-separated list. The string is null-terminated +and is assumed to be in the Host Portable Character Encoding; +otherwise, the result is implementation-dependent. +White space immediately on either side of a separating comma is ignored. +.LP +Use of XLFD font names permits Xlib to obtain the fonts needed for a +variety of locales from a single locale-independent base font name. +The single base font name should name a family of fonts whose members +are encoded in the various charsets needed by the locales of interest. +.LP +An XLFD base font name can explicitly name a charset needed for the locale. +This allows the user to specify an exact font for use with a charset required +by a locale, fully controlling the font selection. +.LP +If a base font name is not an XLFD name, +Xlib will attempt to obtain an XLFD name from the font properties +for the font. +If Xlib is successful, the +.PN XGetOCValues +function will return this XLFD name instead of the client-supplied name. +.LP +This argument must be set at creation time +and cannot be changed. +If no fonts exist for any of the required charsets, +or if the locale definition in Xlib requires that a font exist +for a particular charset and a font is not found for that charset, +.PN XCreateOC +returns NULL. +.LP +When querying for the +.PN XNBaseFontName +XOC value, +.PN XGetOCValues +returns a null-terminated string identifying the base font names that +Xlib used to load the fonts needed for the locale. +This string is owned by Xlib and should not be modified or freed by +the client. +The string will be freed by a call to +.PN XDestroyOC +with the associated +.PN XOC . +Until freed, the string contents will not be modified by Xlib. +.NH 4 +Missing CharSet +.XS +\*(SN Missing CharSet +.XE +.LP +The +.PN XNMissingCharSet +argument returns the list of required charsets that are missing from the +font set. +The value of the argument is a pointer to a structure of type +.PN XOMCharSetList . +.LP +If fonts exist for all of the charsets required by the current locale, +charset_list is set to NULL and charset_count is set to zero. +If no fonts exist for one or more of the required charsets, +charset_list is set to a list of one or more null-terminated charset names +for which no fonts exist, and charset_count is set to the number of +missing charsets. +The charsets are from the list of the required charsets for +the encoding of the locale and do not include any charsets to which Xlib +may be able to remap a required charset. +.LP +The missing charset list is owned by Xlib and should not be modified or +freed by the client. +It will be freed by a call to +.PN XDestroyOC +with the associated +.PN XOC . +Until freed, its contents will not be modified by Xlib. +.NH 4 +Default String +.XS +\*(SN Default String +.XE +.LP +When a drawing or measuring function is called with an +.PN XOC +that has missing charsets, some characters in the locale will not be +drawable. +The +.PN XNDefaultString +argument returns a pointer to a string that represents the glyphs +that are drawn with this +.PN XOC +when the charsets of the available fonts do not include all glyphs +required to draw a character. +The string does not necessarily consist of valid characters +in the current locale and is not necessarily drawn with +the fonts loaded for the font set, +but the client can draw or measure the default glyphs +by including this string in a string being drawn or measured with the +.PN XOC . +.LP +If the +.PN XNDefaultString +argument returned the empty string ("\^"), +no glyphs are drawn and the escapement is zero. +The returned string is null-terminated. +It is owned by Xlib and should not be modified or freed by the client. +It will be freed by a call to +.PN XDestroyOC +with the associated +.PN XOC . +Until freed, its contents will not be modified by Xlib. +.NH 4 +Orientation +.XS +\*(SN Orientation +.XE +.LP +The +.PN XNOrientation +argument specifies the current orientation of text when drawn. The value of +this argument is one of the values returned by the +.PN XGetOMValues +function with the +.PN XNQueryOrientation +argument specified in the +.PN XOrientation +list. +The value of the argument is of type +.PN XOrientation . +When +.PN XNOrientation +is queried, the value specifies the current orientation. +When +.PN XNOrientation +is set, a value is used to set the current orientation. +.LP +When +.PN XOMOrientation_Context +is set, the text orientation of the +text is determined according to an implementation-defined method +(for example, ISO 6429 control sequences), and the initial text orientation for +locale-dependent Xlib functions is assumed to +be +.PN XOMOrientation_LTR_TTB . +.LP +The +.PN XNOrientation +value does not change the prime drawing direction +for Xlib drawing functions. +.NH 4 +Resource Name and Class +.XS +\*(SN Resource Name and Class +.XE +.LP +The +.PN XNResourceName +and +.PN XNResourceClass +arguments are strings that specify the full name and class +used by the client to obtain resources for the display of the output context. +These values should be used as prefixes for name and class +when looking up resources that may vary according to the output context. +If these values are not set, +the resources will not be fully specified. +.LP +It is not intended that values that can be set as XOM values be +set as resources. +.LP +When querying for the +.PN XNResourceName +or +.PN XNResourceClass +XOC value, +.PN XGetOCValues +returns a null-terminated string. +This string is owned by Xlib and should not be modified or freed by +the client. +The string will be freed by a call to +.PN XDestroyOC +with the associated +.PN XOC +or when the associated value is changed via +.PN XSetOCValues . +Until freed, the string contents will not be modified by Xlib. +.NH 4 +Font Info +.XS +\*(SN Font Info +.XE +.LP +The +.PN XNFontInfo +argument specifies a list of one or more +.PN XFontStruct +structures +and font names for the fonts used for drawing by the given output context. +The value of the argument is a pointer to a structure of type +.PN XOMFontInfo . +.LP +.sM +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef struct { + int num_font; + XFontStruct **font_struct_list; + char **font_name_list; +} XOMFontInfo; +.De +.LP +.eM +A list of pointers to the +.PN XFontStruct +structures is returned to font_struct_list. +A list of pointers to null-terminated, fully-specified font name strings +in the locale of the output context is returned to font_name_list. +The font_name_list order corresponds to the font_struct_list order. +The number of +.PN XFontStruct +structures and font names is returned to num_font. +.LP +Because it is not guaranteed that a given character will be imaged using a +single font glyph, +there is no provision for mapping a character or default string +to the font properties, font ID, or direction hint for the font +for the character. +The client may access the +.PN XFontStruct +list to obtain these values for all the fonts currently in use. +.LP +Xlib does not guarantee that fonts are loaded from the server +at the creation of an +.PN XOC . +Xlib may choose to cache font data, loading it only as needed to draw text +or compute text dimensions. +Therefore, existence of the per_char metrics in the +.PN XFontStruct +structures in the +.PN XFontStructSet +is undefined. +Also, note that all properties in the +.PN XFontStruct +structures are in the STRING encoding. +.LP +The client must not free the +.PN XOMFontInfo +struct itself; it will be freed when the +.PN XOC +is closed. +.NH 4 +OM Automatic +.XS +\*(SN OM Automatic +.XE +.LP +The +.PN XNOMAutomatic +argument returns whether the associated output context was created by +.PN XCreateFontSet +or not. Because the +.PN XFreeFontSet +function not only destroys the output context but also closes the implicit +output method associated with it, +.PN XFreeFontSet +should be used with any output context created by +.PN XCreateFontSet . +However, it is possible that a client does not know how the output context +was created. +Before a client destroys the output context, +it can query whether +.PN XNOMAutomatic +is set to determine whether +.PN XFreeFontSet +or +.PN XDestroyOC +should be used to destroy the output context. +.NH 3 +Creating and Freeing a Font Set +.XS +\*(SN Creating and Freeing a Font Set +.XE +.LP +Xlib international text drawing is done using a set of one or more fonts, +as needed for the locale of the text. +Fonts are loaded according to a list of base font names +supplied by the client and the charsets required by the locale. +The +.PN XFontSet +is an opaque type representing the state of a particular output thread +and is equivalent to the type +.PN XOC . +.LP +.sp +The +.PN XCreateFontSet +function is a convenience function for creating an output context using +only default values. The returned +.PN XFontSet +has an implicitly created +.PN XOM . +This +.PN XOM +has an OM value +.PN XNOMAutomatic +automatically set to +.PN True +so that the output context self indicates whether it was created by +.PN XCreateOC +or +.PN XCreateFontSet . +.IN "XCreateFontSet" "" "@DEF@" +.sM +.FD 0 +XFontSet XCreateFontSet\^(\^\fIdisplay\fP\^, \fIbase_font_name_list\fP\^, \fImissing_charset_list_return\fP\^, +.br + \fImissing_charset_count_return\fP\^, \fIdef_string_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + char *\fIbase_font_name_list\fP\^; +.br + char ***\fImissing_charset_list_return\fP\^; +.br + int *\fImissing_charset_count_return\fP\^; +.br + char **\fIdef_string_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIbase_font_name_list\fP 1i +Specifies the base font names. +.IP \fImissing_charset_list_return\fP 1i +Returns the missing charsets. +.IP \fImissing_charset_count_return\fP 1i +Returns the number of missing charsets. +.IP \fIdef_string_return\fP 1i +Returns the string drawn for missing charsets. +.LP +.eM +The +.PN XCreateFontSet +function creates a font set for the specified display. +The font set is bound to the current locale when +.PN XCreateFontSet +is called. +The font set may be used in subsequent calls to obtain font +and character information and to image text in the locale of the font set. +.LP +The base_font_name_list argument is a list of base font names +that Xlib uses to load the fonts needed for the locale. +The base font names are a comma-separated list. +The string is null-terminated +and is assumed to be in the Host Portable Character Encoding; +otherwise, the result is implementation-dependent. +White space immediately on either side of a separating comma is ignored. +.LP +Use of XLFD font names permits Xlib to obtain the fonts needed for a +variety of locales from a single locale-independent base font name. +The single base font name should name a family of fonts whose members +are encoded in the various charsets needed by the locales of interest. +.LP +An XLFD base font name can explicitly name a charset needed for the locale. +This allows the user to specify an exact font for use with a charset required +by a locale, fully controlling the font selection. +.LP +If a base font name is not an XLFD name, +Xlib will attempt to obtain an XLFD name from the font properties +for the font. +If this action is successful in obtaining an XLFD name, the +.PN XBaseFontNameListOfFontSet +function will return this XLFD name instead of the client-supplied name. +.LP +Xlib uses the following algorithm to select the fonts +that will be used to display text with the +.PN XFontSet . +.LP +For each font charset required by the locale, +the base font name list is searched for the first appearance of one +of the following cases that names a set of fonts that exist at the server: +.IP \(bu 5 +The first XLFD-conforming base font name that specifies the required +charset or a superset of the required charset in its +.PN CharSetRegistry +and +.PN CharSetEncoding +fields. +The implementation may use a base font name whose specified charset +is a superset of the required charset, for example, +an ISO8859-1 font for an ASCII charset. +.IP \(bu 5 +The first set of one or more XLFD-conforming base font names +that specify one or more charsets that can be remapped to support the +required charset. +The Xlib implementation may recognize various mappings +from a required charset to one or more other charsets +and use the fonts for those charsets. +For example, JIS Roman is ASCII with tilde and backslash replaced +by yen and overbar; +Xlib may load an ISO8859-1 font to support this character set +if a JIS Roman font is not available. +.IP \(bu 5 +The first XLFD-conforming font name or the first non-XLFD font name +for which an XLFD font name can be obtained, combined with the +required charset (replacing the +.PN CharSetRegistry +and +.PN CharSetEncoding +fields in the XLFD font name). +As in case 1, +the implementation may use a charset that is a superset +of the required charset. +.IP \(bu 5 +The first font name that can be mapped in some implementation-dependent +manner to one or more fonts that support imaging text in the charset. +.LP +For example, assume that a locale required the charsets: +.LP +.Ds 0 +ISO8859-1 +JISX0208.1983 +JISX0201.1976 +GB2312-1980.0 +.De +.LP +The user could supply a base_font_name_list that explicitly specifies the +charsets, ensuring that specific fonts are used if they exist. +For example: +.LP +.Ds 0 +"-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240-JISX0208.1983-0,\\ +-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120-JISX0201.1976-0,\\ +-GB-Fixed-Medium-R-Normal--26-180-100-100-C-240-GB2312-1980.0,\\ +-Adobe-Courier-Bold-R-Normal--25-180-75-75-M-150-ISO8859-1" +.De +.LP +Alternatively, the user could supply a base_font_name_list +that omits the charsets, +letting Xlib select font charsets required for the locale. +For example: +.LP +.Ds 0 +"-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240,\\ +-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120,\\ +-GB-Fixed-Medium-R-Normal--26-180-100-100-C-240,\\ +-Adobe-Courier-Bold-R-Normal--25-180-100-100-M-150" +.De +.LP +Alternatively, the user could simply supply a single base font name +that allows Xlib to select from all available fonts +that meet certain minimum XLFD property requirements. +For example: +.LP +.Ds 0 +"-*-*-*-R-Normal--*-180-100-100-*-*" +.De +.LP +If +.PN XCreateFontSet +is unable to create the font set, +either because there is insufficient memory or because the current locale +is not supported, +.PN XCreateFontSet +returns NULL, missing_charset_list_return is set to NULL, +and missing_charset_count_return +is set to zero. +If fonts exist for all of the charsets required by the current locale, +.PN XCreateFontSet +returns a valid +.PN XFontSet , +missing_charset_list_return is set to NULL, +and missing_charset_count_return is set to zero. +.LP +If no font exists for one or more of the required charsets, +.PN XCreateFontSet +sets missing_charset_list_return to a +list of one or more null-terminated charset names for which no font exists +and sets missing_charset_count_return to the number of missing fonts. +The charsets are from the list of the required charsets for +the encoding of the locale and do not include any charsets to which Xlib +may be able to remap a required charset. +.LP +If no font exists for any of the required charsets +or if the locale definition in Xlib requires that a font exist +for a particular charset and a font is not found for that charset, +.PN XCreateFontSet +returns NULL. +Otherwise, +.PN XCreateFontSet +returns a valid +.PN XFontSet +to font_set. +.LP +When an Xmb/wc drawing or measuring function is called with an +.PN XFontSet +that has missing charsets, some characters in the locale will not be +drawable. +If def_string_return is non-NULL, +.PN XCreateFontSet +returns a pointer to a string that represents the glyphs +that are drawn with this +.PN XFontSet +when the charsets of the available fonts do not include all font glyphs +required to draw a codepoint. +The string does not necessarily consist of valid characters +in the current locale and is not necessarily drawn with +the fonts loaded for the font set, +but the client can draw and measure the default glyphs +by including this string in a string being drawn or measured with the +.PN XFontSet . +.LP +If the string returned to def_string_return is the empty string ("\^"), +no glyphs are drawn, and the escapement is zero. +The returned string is null-terminated. +It is owned by Xlib and should not be modified or freed by the client. +It will be freed by a call to +.PN XFreeFontSet +with the associated +.PN XFontSet . +Until freed, its contents will not be modified by Xlib. +.LP +The client is responsible for constructing an error message from the +missing charset and default string information and may choose to continue +operation in the case that some fonts did not exist. +.LP +The returned +.PN XFontSet +and missing charset list should be freed with +.PN XFreeFontSet +and +.PN XFreeStringList , +respectively. +The client-supplied base_font_name_list may be freed +by the client after calling +.PN XCreateFontSet . +.LP +.sp +To obtain a list of +.PN XFontStruct +structures and full font names given an +.PN XFontSet , +use +.PN XFontsOfFontSet . +.IN "XFontsOfFontSet" "" "@DEF@" +.sM +.FD 0 +int XFontsOfFontSet\^(\^\fIfont_set\fP\^, \fIfont_struct_list_return\fP\^, \fIfont_name_list_return\fP\^) +.br + XFontSet \fIfont_set\fP\^; +.br + XFontStruct ***\fIfont_struct_list_return\fP\^; +.br + char ***\fIfont_name_list_return\fP\^; +.FN +.IP \fIfont_set\fP 1i +Specifies the font set. +.IP \fIfont_struct_list_return\fP 1i +Returns the list of font structs. +.IP \fIfont_name_list_return\fP 1i +Returns the list of font names. +.LP +.eM +The +.PN XFontsOfFontSet +function returns a list of one or more +.PN XFontStructs +and font names for the fonts used by the Xmb and Xwc layers +for the given font set. +A list of pointers to the +.PN XFontStruct +structures is returned to font_struct_list_return. +A list of pointers to null-terminated, fully specified font name strings +in the locale of the font set is returned to font_name_list_return. +The font_name_list order corresponds to the font_struct_list order. +The number of +.PN XFontStruct +structures and font names is returned as the value of the function. +.LP +Because it is not guaranteed that a given character will be imaged using a +single font glyph, +there is no provision for mapping a character or default string +to the font properties, font ID, or direction hint for the font +for the character. +The client may access the +.PN XFontStruct +list to obtain these values for all the fonts currently in use. +.LP +Xlib does not guarantee that fonts are loaded from the server +at the creation of an +.PN XFontSet . +Xlib may choose to cache font data, loading it only as needed to draw text +or compute text dimensions. +Therefore, existence of the per_char metrics in the +.PN XFontStruct +structures in the +.PN XFontStructSet +is undefined. +Also, note that all properties in the +.PN XFontStruct +structures are in the STRING encoding. +.LP +The +.PN XFontStruct +and font name lists are owned by Xlib +and should not be modified or freed by the client. +They will be freed by a call to +.PN XFreeFontSet +with the associated +.PN XFontSet . +Until freed, their contents will not be modified by Xlib. +.LP +.sp +To obtain the base font name list and the selected font name list given an +.PN XFontSet , +use +.PN XBaseFontNameListOfFontSet . +.IN "XBaseFontNameListOfFontSet" "" "@DEF@" +.sM +.FD 0 +char *XBaseFontNameListOfFontSet\^(\^\fIfont_set\fP\^) +.br + XFontSet \fIfont_set\fP\^; +.FN +.IP \fIfont_set\fP 1i +Specifies the font set. +.LP +.eM +The +.PN XBaseFontNameListOfFontSet +function returns the original base font name list supplied +by the client when the +.PN XFontSet +was created. +A null-terminated string containing a list of +comma-separated font names is returned +as the value of the function. +White space may appear immediately on either side of separating commas. +.LP +If +.PN XCreateFontSet +obtained an XLFD name from the font properties for the font specified +by a non-XLFD base name, the +.PN XBaseFontNameListOfFontSet +function will return the XLFD name instead of the non-XLFD base name. +.LP +The base font name list is owned by Xlib and should not be modified or +freed by the client. +It will be freed by a call to +.PN XFreeFontSet +with the associated +.PN XFontSet . +Until freed, its contents will not be modified by Xlib. +.LP +.sp +To obtain the locale name given an +.PN XFontSet , +use +.PN XLocaleOfFontSet . +.IN "XLocaleOfFontSet" "" "@DEF@" +.sM +.FD 0 +char *XLocaleOfFontSet\^(\^\fIfont_set\fP\^) +.br + XFontSet \fIfont_set\fP\^; +.FN +.IP \fIfont_set\fP 1i +Specifies the font set. +.LP +.eM +The +.PN XLocaleOfFontSet +function +returns the name of the locale bound to the specified +.PN XFontSet , +as a null-terminated string. +.LP +The returned locale name string is owned by Xlib +and should not be modified or freed by the client. +It may be freed by a call to +.PN XFreeFontSet +with the associated +.PN XFontSet . +Until freed, it will not be modified by Xlib. +.LP +.sp +The +.PN XFreeFontSet +function is a convenience function for freeing an output context. +.PN XFreeFontSet +also frees its associated +.PN XOM +if the output context was created by +.PN XCreateFontSet . +.IN "XFreeFontSet" "" "@DEF@" +.sM +.FD 0 +void XFreeFontSet\^(\^\fIdisplay\fP\^, \fIfont_set\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XFontSet \fIfont_set\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIfont_set\fP 1i +Specifies the font set. +.LP +.eM +The +.PN XFreeFontSet +function frees the specified font set. +The associated base font name list, font name list, +.PN XFontStruct +list, and +.PN XFontSetExtents , +if any, are freed. +.NH 3 +Obtaining Font Set Metrics +.XS +\*(SN Obtaining Font Set Metrics +.XE +.LP +Metrics for the internationalized text drawing functions +are defined in terms of a primary draw direction, +which is the default direction in which the character origin advances +for each succeeding character in the string. +The Xlib interface is currently defined to support only a left-to-right +primary draw direction. +The drawing origin is the position passed to the drawing function +when the text is drawn. +The baseline is a line drawn through the drawing origin parallel +to the primary draw direction. +Character ink is the pixels painted in the foreground color +and does not include interline or intercharacter spacing +or image text background pixels. +.LP +The drawing functions are allowed to implement implicit text +directionality control, reversing the order in which characters are +rendered along the primary draw direction in response to locale-specific +lexical analysis of the string. +.LP +Regardless of the character rendering order, +the origins of all characters are on the primary draw direction side +of the drawing origin. +The screen location of a particular character image may be determined with +.PN XmbTextPerCharExtents +or +.PN XwcTextPerCharExtents . +.LP +The drawing functions are allowed to implement context-dependent +rendering, where the glyphs drawn for a string are not simply a +concatenation of the glyphs that represent each individual character. +A string of two characters drawn with +.PN XmbDrawString +may render differently than if the two characters +were drawn with separate calls to +.PN XmbDrawString . +If the client appends or inserts a character +in a previously drawn string, +the client may need to redraw some adjacent characters +to obtain proper rendering. +.LP +.sp +To find out about direction-dependent rendering, use +.PN XDirectionalDependentDrawing . +.IN "XDirectionalDependentDrawing" "" "@DEF@" +.sM +.FD 0 +Bool XDirectionalDependentDrawing\^(\^\fIfont_set\fP\^) +.br + XFontSet \fIfont_set\fP\^; +.FN +.IP \fIfont_set\fP 1i +Specifies the font set. +.LP +.eM +The +.PN XDirectionalDependentDrawing +function returns +.PN True +if the drawing functions implement implicit text directionality; +otherwise, it returns +.PN False . +.LP +.sp +To find out about context-dependent rendering, use +.PN XContextualDrawing . +.IN "XContextualDrawing" "" "@DEF@" +.sM +.FD 0 +Bool XContextualDrawing\^(\^\fIfont_set\fP\^) +.br + XFontSet \fIfont_set\fP\^; +.FN +.IP \fIfont_set\fP 1i +Specifies the font set. +.LP +.eM +The +.PN XContextualDrawing +function returns +.PN True +if text drawn with the font set might include context-dependent drawing; +otherwise, it returns +.PN False . +.LP +.sp +To find out about context-dependent or direction-dependent rendering, use +.PN XContextDependentDrawing . +.IN "XContextDependentDrawing" "" "@DEF@" +.sM +.FD 0 +Bool XContextDependentDrawing\^(\^\fIfont_set\fP\^) +.br + XFontSet \fIfont_set\fP\^; +.FN +.IP \fIfont_set\fP 1i +Specifies the font set. +.LP +.eM +The +.PN XContextDependentDrawing +function returns +.PN True +if the drawing functions implement implicit text directionality or +if text drawn with the font_set might include context-dependent drawing; +otherwise, it returns +.PN False . +.LP +The drawing functions do not interpret newline, tab, or other control +characters. +The behavior when nonprinting characters other than space are drawn +is implementation-dependent. +It is the client's responsibility to interpret control characters +in a text stream. +.LP +The maximum character extents for the fonts that are used by the text +drawing layers can be accessed by the +.PN XFontSetExtents +structure: +.IN "XFontSetExtents" "" "@DEF@" +.LP +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + XRectangle max_ink_extent; /* over all drawable characters */ + XRectangle max_logical_extent; /* over all drawable characters */ +} XFontSetExtents; +.De +.LP +The +.PN XRectangle +structures used to return font set metrics are the usual Xlib screen-oriented +rectangles +with x, y giving the upper left corner, and width and height always positive. +.LP +The max_ink_extent member gives the maximum extent, over all drawable characters, of +the rectangles that bound the character glyph image drawn in the +foreground color, relative to a constant origin. +See +.PN XmbTextExtents +and +.PN XwcTextExtents +for detailed semantics. +.LP +The max_logical_extent member gives the maximum extent, +over all drawable characters, of the rectangles +that specify minimum spacing to other graphical features, +relative to a constant origin. +Other graphical features drawn by the client, for example, +a border surrounding the text, should not intersect this rectangle. +The max_logical_extent member should be used to compute minimum +interline spacing and the minimum area that must be allowed +in a text field to draw a given number of arbitrary characters. +.LP +Due to context-dependent rendering, +appending a given character to a string may change +the string's extent by an amount other than that character's +individual extent. +.LP +The rectangles for a given character in a string can be obtained from +.PN XmbPerCharExtents +or +.PN XwcPerCharExtents . +.LP +.sp +To obtain the maximum extents structure given an +.PN XFontSet , +use +.PN XExtentsOfFontSet . +.IN "XExtentsOfFontSet" "" "@DEF@" +.sM +.FD 0 +XFontSetExtents *XExtentsOfFontSet\^(\^\fIfont_set\fP\^) +.br + XFontSet \fIfont_set\fP\^; +.FN +.IP \fIfont_set\fP 1i +Specifies the font set. +.LP +.eM +The +.PN XExtentsOfFontSet +function returns an +.PN XFontSetExtents +structure for the fonts used by the Xmb and Xwc layers +for the given font set. +.LP +The +.PN XFontSetExtents +structure is owned by Xlib and should not be modified +or freed by the client. +It will be freed by a call to +.PN XFreeFontSet +with the associated +.PN XFontSet . +Until freed, its contents will not be modified by Xlib. +.LP +.sp +To obtain the escapement in pixels of the specified text as a value, +use +.PN XmbTextEscapement +or +.PN XwcTextEscapement . +.IN "XmbTextEscapement" "" "@DEF@" +.IN "XwcTextEscapement" "" "@DEF@" +.sM +.FD 0 +int XmbTextEscapement\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_bytes\fP\^) +.br + XFontSet \fIfont_set\fP\^; +.br + char *\fIstring\fP\^; +.br + int \fInum_bytes\fP\^; +.FN +.FD 0 +int XwcTextEscapement\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_wchars\fP\^) +.br + XFontSet \fIfont_set\fP\^; +.br + wchar_t *\fIstring\fP\^; +.br + int \fInum_wchars\fP\^; +.FN +.IP \fIfont_set\fP 1i +Specifies the font set. +.IP \fIstring\fP 1i +Specifies the character string. +.IP \fInum_bytes\fP 1i +Specifies the number of bytes in the string argument. +.IP \fInum_wchars\fP 1i +Specifies the number of characters in the string argument. +.LP +.eM +The +.PN XmbTextEscapement +and +.PN XwcTextEscapement +functions return the escapement in pixels of the specified string as a value, +using the fonts loaded for the specified font set. +The escapement is the distance in pixels in the primary draw +direction from the drawing origin to the origin of the next character to +be drawn, assuming that the rendering of the next character is not +dependent on the supplied string. +.LP +Regardless of the character rendering order, +the escapement is always positive. +.LP +.sp +To obtain the overall_ink_return and overall_logical_return arguments, +the overall bounding box of the string's image, and a logical bounding box, +use +.PN XmbTextExtents + or +.PN XwcTextExtents . +.IN "XmbTextExtents" "" "@DEF@" +.IN "XwcTextExtents" "" "@DEF@" +.sM +.FD 0 +int XmbTextExtents\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_bytes\fP\^, \fIoverall_ink_return\fP\^, \fIoverall_logical_return\fP\^) +.br + XFontSet \fIfont_set\fP\^; +.br + char *\fIstring\fP\^; +.br + int \fInum_bytes\fP\^; +.br + XRectangle *\fIoverall_ink_return\fP\^; +.br + XRectangle *\fIoverall_logical_return\fP\^; +.FN +.FD 0 +int XwcTextExtents\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_wchars\fP\^, +\fIoverall_ink_return\fP\^, \fIoverall_logical_return\fP\^) +.br + XFontSet \fIfont_set\fP\^; +.br + wchar_t *\fIstring\fP\^; +.br + int \fInum_wchars\fP\^; +.br + XRectangle *\fIoverall_ink_return\fP\^; +.br + XRectangle *\fIoverall_logical_return\fP\^; +.FN +.IP \fIfont_set\fP 1i +Specifies the font set. +.IP \fIstring\fP 1i +Specifies the character string. +.IP \fInum_bytes\fP 1i +Specifies the number of bytes in the string argument. +.IP \fInum_wchars\fP 1i +Specifies the number of characters in the string argument. +.ds Ov dimensions +.IP \fIoverall_ink_return\fP 1i +Returns the overall ink \*(Ov. +.IP \fIoverall_logical_return\fP 1i +Returns the overall logical \*(Ov. +.LP +.eM +The +.PN XmbTextExtents +and +.PN XwcTextExtents +functions set the components of the specified overall_ink_return and +overall_logical_return +arguments to the overall bounding box of the string's image +and a logical bounding box for spacing purposes, respectively. +They return the value returned by +.PN XmbTextEscapement +or +.PN XwcTextEscapement . +These metrics are relative to the drawing origin of the string, +using the fonts loaded for the specified font set. +.LP +If the overall_ink_return argument is non-NULL, +it is set to the bounding box of the string's character ink. +The overall_ink_return for a nondescending, horizontally drawn +Latin character is conventionally entirely above the baseline; +that is, overall_ink_return.height <= \-overall_ink_return.y. +The overall_ink_return for a nonkerned character +is entirely at, and to the right of, the origin; +that is, overall_ink_return.x >= 0. +A character consisting of a single pixel at the origin would set +overall_ink_return fields y = 0, x = 0, width = 1, and height = 1. +.LP +If the overall_logical_return argument is non-NULL, +it is set to the bounding box that provides minimum spacing +to other graphical features for the string. +Other graphical features, for example, a border surrounding the text, +should not intersect this rectangle. +.LP +When the +.PN XFontSet +has missing charsets, +metrics for each unavailable character are taken +from the default string returned by +.PN XCreateFontSet +so that the metrics represent the text as it will actually be drawn. +The behavior for an invalid codepoint is undefined. +.LP +To determine the effective drawing origin for a character in a drawn string, +the client should call +.PN XmbTextPerCharExtents +on the entire string, then on the character, +and subtract the x values of the returned +rectangles for the character. +This is useful to redraw portions of a line of text +or to justify words, but for context-dependent rendering, +the client should not assume that it can redraw the character by itself +and get the same rendering. +.LP +.sp +To obtain per-character information for a text string, +use +.PN XmbTextPerCharExtents +or +.PN XwcTextPerCharExtents . +.IN "XmbTextPerCharExtents" "" "@DEF@" +.IN "XwcTextPerCharExtents" "" "@DEF@" +.sM +.FD 0 +Status XmbTextPerCharExtents\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_bytes\fP\^, \fIink_array_return\fP\^, +.br + \fIlogical_array_return\fP\^, \fIarray_size\fP\^, \fInum_chars_return\fP\^, \fIoverall_ink_return\fP\^, \fIoverall_logical_return\fP\^) +.br + XFontSet \fIfont_set\fP\^; +.br + char *\fIstring\fP\^; +.br + int \fInum_bytes\fP\^; +.br + XRectangle *\fIink_array_return\fP\^; +.br + XRectangle *\fIlogical_array_return\fP\^; +.br + int \fIarray_size\fP\^; +.br + int *\fInum_chars_return\fP\^; +.br + XRectangle *\fIoverall_ink_return\fP\^; +.br + XRectangle *\fIoverall_logical_return\fP\^; +.FN +.FD 0 +Status XwcTextPerCharExtents\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_wchars\fP\^, \fIink_array_return\fP\^, +.br + \fIlogical_array_return\fP\^, \fIarray_size\fP\^, \fInum_chars_return\fP\^, \fIoverall_ink_return\fP\^, \fIoverall_ink_return\fP\^) +.br + XFontSet \fIfont_set\fP\^; +.br + wchar_t *\fIstring\fP\^; +.br + int \fInum_wchars\fP\^; +.br + XRectangle *\fIink_array_return\fP\^; +.br + XRectangle *\fIlogical_array_return\fP; +.br + int \fIarray_size\fP\^; +.br + int *\fInum_chars_return\fP\^; +.br + XRectangle *\fIoverall_ink_return\fP\^; +.br + XRectangle *\fIoverall_logical_return\fP\^; +.FN +.IP \fIfont_set\fP 1i +Specifies the font set. +.IP \fIstring\fP 1i +Specifies the character string. +.IP \fInum_bytes\fP 1i +Specifies the number of bytes in the string argument. +.IP \fInum_wchars\fP 1i +Specifies the number of characters in the string argument. +.IP \fIink_array_return\fP 1i +Returns the ink dimensions for each character. +.IP \fIlogical_array_return\fP 1i +Returns the logical dimensions for each character. +.IP \fIarray_size\fP 1i +Specifies the size of ink_array_return and logical_array_return. +The caller must pass in arrays of this size. +.IP \fInum_chars_return\fP 1i +Returns the number of characters in the string argument. +.ds Ov extents of the entire string +.IP \fIoverall_ink_return\fP 1i +Returns the overall ink \*(Ov. +.IP \fIoverall_logical_return\fP 1i +Returns the overall logical \*(Ov. +.LP +.eM +The +.PN XmbTextPerCharExtents +and +.PN XwcTextPerCharExtents +functions return the text dimensions of each character of the specified text, +using the fonts loaded for the specified font set. +Each successive element of ink_array_return and logical_array_return +is set to the successive character's drawn metrics, +relative to the drawing origin of the string and one +rectangle +for each character in the supplied text string. +The number of elements of ink_array_return and logical_array_return +that have been set is returned to num_chars_return. +.LP +Each element of ink_array_return is set to the bounding box +of the corresponding character's drawn foreground color. +Each element of logical_array_return is set to the bounding box +that provides minimum spacing to other graphical features +for the corresponding character. +Other graphical features should not intersect any of the +logical_array_return rectangles. +.LP +Note that an +.PN XRectangle +represents the effective drawing dimensions of the character, +regardless of the number of font glyphs that are used to draw +the character or the direction in which the character is drawn. +If multiple characters map to a single character glyph, +the dimensions of all the +.PN XRectangles +of those characters are the same. +.LP +When the +.PN XFontSet +has missing charsets, metrics for each unavailable +character are taken from the default string returned by +.PN XCreateFontSet +so that the metrics represent the text as it will actually be drawn. +The behavior for an invalid codepoint is undefined. +.LP +If the array_size is too small for the number of characters in the +supplied text, the functions return zero +and num_chars_return is set to the number of rectangles required. +Otherwise, the functions return a nonzero value. +.LP +If the overall_ink_return or overall_logical_return argument is non-NULL, +.PN XmbTextPerCharExtents +and +.PN XwcTextPerCharExtents +return the maximum extent of the string's metrics to overall_ink_return +or overall_logical_return, as returned by +.PN XmbTextExtents +or +.PN XwcTextExtents . +.NH 3 +Drawing Text Using Font Sets +.XS +\*(SN Drawing Text Using Font Sets +.XE +.LP +The functions defined in this section +draw text at a specified location in a drawable. +They are similar to the functions +.PN XDrawText , +.PN XDrawString , +and +.PN XDrawImageString +except that they work with font sets instead of single fonts +and interpret the text based on the locale of the font set +instead of treating the bytes of the string as direct font indexes. +See section 8.6 for details of the use of Graphics Contexts (GCs) +and possible protocol errors. +If a +.PN BadFont +error is generated, +characters prior to the offending character may have been drawn. +.LP +The text is drawn using the fonts loaded for the specified font set; +the font in the GC is ignored and may be modified by the functions. +No validation that all fonts conform to some width rule is performed. +.LP +The text functions +.PN XmbDrawText +and +.PN XwcDrawText +use the following structures: +.LP +.IN "XmbTextItem" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef struct { + char *chars; /* pointer to string */ + int nchars; /* number of bytes */ + int delta; /* pixel delta between strings */ + XFontSet font_set; /* fonts, None means don't change */ +} XmbTextItem; +.De +.LP +.IN "XwcTextItem" "" "@DEF@" +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef struct { + wchar_t *chars; /* pointer to wide char string */ + int nchars; /* number of wide characters */ + int delta; /* pixel delta between strings */ + XFontSet font_set; /* fonts, None means don't change */ +} XwcTextItem; +.De +.LP +.eM +.sp +To draw text using multiple font sets in a given drawable, use +.PN XmbDrawText +or +.PN XwcDrawText . +.IN "XmbDrawText" "" "@DEF@" +.IN "XwcDrawText" "" "@DEF@" +.sM +.FD 0 +void XmbDrawText\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIitems\fP\^, \fInitems\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fId\fP\^; +.br + GC \fIgc\fP\^; +.br + int \fIx\fP\^, \fIy\fP\^; +.br + XmbTextItem *\fIitems\fP\^; +.br + int \fInitems\fP\^; +.FN +.FD 0 +void XwcDrawText\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIitems\fP\^, \fInitems\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fId\fP\^; +.br + GC \fIgc\fP\^; +.br + int \fIx\fP\^, \fIy\fP\^; +.br + XwcTextItem *\fIitems\fP\^; +.br + int \fInitems\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fId\fP 1i +Specifies the drawable. +.IP \fIgc\fP 1i +Specifies the GC. +.ds Xy +.IP \fIx\fP 1i +.br +.ns +.IP \fIy\fP 1i +Specify the x and y coordinates\*(Xy. +.IP \fIitems\fP 1i +Specifies an array of text items. +.IP \fInitems\fP 1i +Specifies the number of text items in the array. +.LP +.eM +The +.PN XmbDrawText +and +.PN XwcDrawText +functions allow complex spacing and font set shifts between text strings. +Each text item is processed in turn, with the origin of a text +element advanced in the primary draw direction by the escapement of the +previous text item. +A text item delta specifies an additional escapement of the text item +drawing origin in the primary draw direction. +A font_set member other than +.PN None +in an item causes the font set to be used for this and subsequent text items +in the text_items list. +Leading text items with a font_set member set to +.PN None +will not be drawn. +.LP +.PN XmbDrawText +and +.PN XwcDrawText +do not perform any context-dependent rendering between text segments. +Clients may compute the drawing metrics by passing each text segment to +.PN XmbTextExtents +and +.PN XwcTextExtents +or +.PN XmbTextPerCharExtents +and +.PN XwcTextPerCharExtents . +When the +.PN XFontSet +has missing charsets, each unavailable character is drawn +with the default string returned by +.PN XCreateFontSet . +The behavior for an invalid codepoint is undefined. +.LP +.sp +To draw text using a single font set in a given drawable, use +.PN XmbDrawString +or +.PN XwcDrawString . +.IN "XmbDrawString" "" "@DEF@" +.IN "XwcDrawString" "" "@DEF@" +.sM +.FD 0 +void XmbDrawString\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIfont_set\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fInum_bytes\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fId\fP\^; +.br + XFontSet \fIfont_set\fP\^; +.br + GC \fIgc\fP\^; +.br + int \fIx\fP\^, \fIy\fP\^; +.br + char *\fIstring\fP\^; +.br + int \fInum_bytes\fP\^; +.FN +.FD 0 +void XwcDrawString\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIfont_set\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fInum_wchars\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fId\fP\^; +.br + XFontSet \fIfont_set\fP\^; +.br + GC \fIgc\fP\^; +.br + int \fIx\fP\^, \fIy\fP\^; +.br + wchar_t *\fIstring\fP\^; +.br + int \fInum_wchars\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fId\fP 1i +Specifies the drawable. +.IP \fIfont_set\fP 1i +Specifies the font set. +.IP \fIgc\fP 1i +Specifies the GC. +.ds Xy +.IP \fIx\fP 1i +.br +.ns +.IP \fIy\fP 1i +Specify the x and y coordinates\*(Xy. +.IP \fIstring\fP 1i +Specifies the character string. +.IP \fInum_bytes\fP 1i +Specifies the number of bytes in the string argument. +.IP \fInum_wchars\fP 1i +Specifies the number of characters in the string argument. +.LP +.eM +The +.PN XmbDrawString +and +.PN XwcDrawString +functions draw the specified text with the foreground pixel. +When the +.PN XFontSet +has missing charsets, each unavailable character is drawn +with the default string returned by +.PN XCreateFontSet . +The behavior for an invalid codepoint is undefined. +.LP +.sp +To draw image text using a single font set in a given drawable, use +.PN XmbDrawImageString +or +.PN XwcDrawImageString . +.IN "XmbDrawImageString" "" "@DEF@" +.IN "XwcDrawImageString" "" "@DEF@" +.sM +.FD 0 +void XmbDrawImageString\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIfont_set\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fInum_bytes\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fId\fP\^; +.br + XFontSet \fIfont_set\fP\^; +.br + GC \fIgc\fP\^; +.br + int \fIx\fP\^, \fIy\fP\^; +.br + char *\fIstring\fP\^; +.br + int \fInum_bytes\fP\^; +.FN +.FD 0 +void XwcDrawImageString\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIfont_set\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fInum_wchars\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fId\fP\^; +.br + XFontSet \fIfont_set\fP\^; +.br + GC \fIgc\fP\^; +.br + int \fIx\fP\^, \fIy\fP\^; +.br + wchar_t *\fIstring\fP\^; +.br + int \fInum_wchars\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fId\fP 1i +Specifies the drawable. +.IP \fIfont_set\fP 1i +Specifies the font set. +.IP \fIgc\fP 1i +Specifies the GC. +.ds Xy +.IP \fIx\fP 1i +.br +.ns +.IP \fIy\fP 1i +Specify the x and y coordinates\*(Xy. +.IP \fIstring\fP 1i +Specifies the character string. +.IP \fInum_bytes\fP 1i +Specifies the number of bytes in the string argument. +.IP \fInum_wchars\fP 1i +Specifies the number of characters in the string argument. +.LP +.eM +The +.PN XmbDrawImageString +and +.PN XwcDrawImageString +functions fill a destination rectangle with the background pixel defined +in the GC and then paint the text with the foreground pixel. +The filled rectangle is the rectangle returned to overall_logical_return by +.PN XmbTextExtents +or +.PN XwcTextExtents +for the same text and +.PN XFontSet . +.LP +When the +.PN XFontSet +has missing charsets, each unavailable character is drawn +with the default string returned by +.PN XCreateFontSet . +The behavior for an invalid codepoint is undefined. +.NH 2 +Input Methods +.XS +\*(SN Input Methods +.XE +.LP +This section provides discussions of the following X Input Method +(XIM) topics: +.IP \(bu 5 +Input method overview +.IP \(bu 5 +Input method management +.IP \(bu 5 +Input method functions +.IP \(bu 5 +Input method values +.IP \(bu 5 +Input context functions +.IP \(bu 5 +Input context values +.IP \(bu 5 +Input method callback semantics +.IP \(bu 5 +Event filtering +.IP \(bu 5 +Getting keyboard input +.IP \(bu 5 +Input method conventions +.NH 3 +Input Method Overview +.XS +\*(SN Input Method Overview +.XE +.LP +This section provides definitions for terms and concepts used +for internationalized text input and a brief overview of the +intended use of the mechanisms provided by Xlib. +.LP +A large number of languages in the world use alphabets +consisting of a small set of symbols (letters) to form words. +To enter text into a computer in an alphabetic language, +a user usually has a keyboard on which there exist key symbols corresponding +to the alphabet. +Sometimes, a few characters of an alphabetic language are missing +on the keyboard. +Many computer users who speak a Latin-alphabet-based language +only have an English-based keyboard. +They need to hit a combination of keystrokes +to enter a character that does not exist directly on the keyboard. +A number of algorithms have been developed for entering such characters. +These are known as European input methods, compose input methods, +or dead-key input methods. +.LP +Japanese is an example of a language with a phonetic symbol set, +where each symbol represents a specific sound. +There are two phonetic symbol sets in Japanese: Katakana and Hiragana. +In general, +Katakana is used for words that are of foreign origin, +and Hiragana is used for writing native Japanese words. +Collectively, the two systems are called Kana. +Each set consists of 48 characters. +.LP +Korean also has a phonetic symbol set, called Hangul. +Each of the 24 basic phonetic symbols (14 consonants and 10 vowels) +represents a specific sound. +A syllable is composed of two or three parts: +the initial consonants, the vowels, and the optional last consonants. +With Hangul, +syllables can be treated as the basic units on which text processing is done. +For example, +a delete operation may work on a phonetic symbol or a syllable. +Korean code sets include several thousands of these syllables. +A user types the phonetic symbols that make up the syllables of the words +to be entered. +The display may change as each phonetic symbol is entered. +For example, +when the second phonetic symbol of a syllable is entered, +the first phonetic symbol may change its shape and size. +Likewise, when the third phonetic symbol is entered, +the first two phonetic symbols may change their shape and size. +.LP +Not all languages rely solely on alphabetic or phonetic systems. +Some languages, including Japanese and Korean, employ an +ideographic writing system. +In an ideographic system, rather than taking a small set of +symbols and combining them in different ways to create words, +each word consists of one unique symbol (or, occasionally, several symbols). +The number of symbols can be very large: +approximately 50,000 have been identified in Hanzi, +the Chinese ideographic system. +.LP +Two major aspects of ideographic systems impact their use with computers. +First, the standard computer character sets in Japan, China, and Korea +include roughly 8,000 characters, +while sets in Taiwan have between 15,000 and 30,000 characters. +This makes it necessary to use more than one byte to represent a character. +Second, it obviously is impractical to have a keyboard that includes +all of a given language's ideographic symbols. +Therefore, a mechanism is required for entering characters +so that a keyboard with a reasonable number of keys can be used. +Those input methods are usually based on phonetics, +but there also exist methods based on the graphical properties of +characters. +.LP +In Japan, both Kana and the ideographic system Kanji are used. +In Korea, Hangul and sometimes the ideographic system Hanja are used. +Now consider entering ideographs in Japan, Korea, China, and Taiwan. +.LP +In Japan, either Kana or English characters are typed and then a region +is selected (sometimes automatically) for conversion to Kanji. +Several Kanji characters may have the same phonetic representation. +If that is the case with the string entered, +a menu of characters is presented and +the user must choose the appropriate one. +If no choice is necessary or a preference has been established, +the input method does the substitution directly. +When Latin characters are converted to Kana or Kanji, +it is called a romaji conversion. +.LP +In Korea, it is usually acceptable to keep Korean text in Hangul form, +but some people may choose to write Hanja-originated words in Hanja +rather than in Hangul. +To change Hangul to Hanja, +the user selects a region for conversion +and then follows the same basic method as that described for Japanese. +.LP +Probably because there are well-accepted phonetic writing systems +for Japanese and Korean, +computer input methods in these countries for entering ideographs +are fairly standard. +Keyboard keys have both English characters and phonetic symbols +engraved on them, and the user can switch between the two sets. +.LP +The situation is different for Chinese. +While there is a phonetic system called Pinyin promoted by authorities, +there is no consensus for entering Chinese text. +Some vendors use a phonetic decomposition (Pinyin or another), +others use ideographic decomposition of Chinese words, +with various implementations and keyboard layouts. +There are about 16 known methods, none of which is a clear standard. +.LP +Also, there are actually two ideographic sets used: +Traditional Chinese (the original written Chinese) +and Simplified Chinese. +Several years ago, +the People's Republic of China launched a campaign to simplify +some ideographic characters and eliminate redundancies altogether. +Under the plan, +characters would be streamlined every five years. +Characters have been revised several times now, +resulting in the smaller, simpler set that makes up Simplified Chinese. +.NH 4 +Input Method Architecture +.XS +\*(SN Input Method Architecture +.XE +.LP +As shown in the previous section, +there are many different input methods in use today, +each varying with language, culture, and history. +A common feature of many input methods is that the user may type +multiple keystrokes to compose a single character (or set +of characters). +The process of composing characters from keystrokes is called +\fIpreediting\fP. +It may require complex algorithms and large dictionaries +involving substantial computer resources. +.LP +Input methods may require one or more areas in which to show the +feedback of the actual keystrokes, to propose disambiguation to the +user, to list dictionaries, and so on. +The input method areas of concern are as follows: +.IP \(bu 5 +The \fIstatus\fP area is a logical extension of the +LEDs that exist on the physical keyboard. +It is a window that is intended to present the internal state +of the input method that is critical to the user. +The status area may consist of text data and bitmaps or some combination. +.IP \(bu 5 +The \fIpreedit\fP area displays the +intermediate text for those languages that are composing prior to +the client handling the data. +.IP \(bu 5 +The \fIauxiliary\fP area is used for pop-up menus and customizing +dialogs that may be required for an input method. +There may be multiple auxiliary areas for an input method. +Auxiliary areas are managed by the input method independent of the client. +Auxiliary areas are assumed to be separate dialogs, +which are maintained by the input method. +.LP +There are various user interaction styles used for preediting. +The ones supported by Xlib are as follows: +.IP \(bu 5 +For \fIon-the-spot\fP input methods, +preediting data will be displayed directly in the application window. +Application data is moved to allow preedit data to appear +at the point of insertion. +.IP \(bu 5 +\fIOver-the-spot\fP preediting means that the data is displayed in +a preedit window that is placed over the point of insertion. +.IP \(bu 5 +\fIOff-the-spot\fP preediting means that the preedit window is +inside the application window but not at the point of insertion. +Often, this type of window is placed at the bottom of the application window. +.IP \(bu 5 +\fIRoot-window\fP preediting refers to input methods that use a preedit +window that is the child of +.PN RootWindow . +.LP +It would require a lot of computing resources if portable applications +had to include input methods for all the languages in the world. +To avoid this, +a goal of the Xlib design is to allow an application +to communicate with an input method placed in a separate process. +Such a process is called an \fIinput server\fP. +The server to which the application should connect is dependent on +the environment when the application is started up, +that is, the user language and the actual encoding to be used for it. +The input method connection is said to be \fIlocale-dependent\fP. +It is also user-dependent. +For a given language, the user can choose, to some extent, +the user interface style of input method (if choice is possible among +several). +.LP +Using an input server implies communication overhead, +but applications can be migrated without relinking. +Input methods can be implemented either as a +stub communicating to an input server or as a local library. +.LP +An input method may be based on a \fIfront-end\fP or a \fIback-end\fP +architecture. +In a front-end architecture, +there are two separate connections to the X server: +keystrokes go directly from the X server to the input method on +one connection and other events to the regular client connection. +The input method is then acting as a filter and sends composed strings +to the client. +A front-end architecture requires synchronization between the +two connections to avoid lost key events or locking issues. +.LP +In a back-end architecture, +a single X server connection is used. +A dispatching mechanism must decide on this channel to delegate appropriate +keystrokes to the input method. +For instance, +it may retain a Help keystroke for its own purpose. +In the case where the input method is a separate process (that is, a server), +there must be a special communication protocol between the back-end client +and the input server. +.LP +A front-end architecture introduces synchronization issues +and a filtering mechanism for noncharacter keystrokes +(Function keys, Help, and so on). +A back-end architecture sometimes implies more communication overhead +and more process switching. +If all three processes (X server, input server, client) +are running on a single workstation, +there are two process switches for each keystroke in a back-end +architecture, +but there is only one in a front-end architecture. +.LP +The abstraction used by a client to communicate with an input method +is an opaque data structure represented by the +.PN XIM +data type. +This data structure is returned by the +.PN XOpenIM +function, which opens an input method on a given display. +Subsequent operations on this data structure encapsulate all communication +between client and input method. +There is no need for an X client to use any networking library +or natural language package to use an input method. +.LP +A single input server may be used for one or more languages, +supporting one or more encoding schemes. +But the strings returned from an input method will always be encoded +in the (single) locale associated with the +.PN XIM +object. +.NH 4 +Input Contexts +.XS +\*(SN Input Contexts +.XE +.LP +Xlib provides the ability to manage a multi-threaded state for text input. +A client may be using multiple windows, +each window with multiple text entry areas, +and the user possibly switching among them at any time. +The abstraction for representing the state of a particular input thread +is called an \fIinput context\fP. +The Xlib representation of an input context is an +.PN XIC . +.LP +An input context is the abstraction retaining the state, properties, +and semantics of communication between a client and an input method. +An input context is a combination of an input method, a locale +specifying the encoding of the character strings to be returned, +a client window, internal state information, +and various layout or appearance characteristics. +The input context concept somewhat matches for input the graphics context +abstraction defined for graphics output. +.LP +One input context belongs to exactly one input method. +Different input contexts may be associated with the same input method, +possibly with the same client window. +An +.PN XIC +is created with the +.PN XCreateIC +function, providing an +.PN XIM +argument and affiliating the input context to the input method +for its lifetime. +When an input method is closed with +.PN XCloseIM , +all of its affiliated input contexts should not be used any more +(and should preferably be destroyed before closing the input method). +.LP +Considering the example of a client window with multiple text entry areas, +the application programmer could, for example, choose to implement as follows: +.IP \(bu 5 +As many input contexts are created as text entry areas, and the client +will get the input accumulated on each context each time it looks up +in that context. +.IP \(bu 5 +A single context is created for a top-level window in the application. +If such a window contains several text entry areas, +each time the user moves to another text entry area, +the client has to indicate changes in the context. +.LP +A range of choices can be made by application designers to use +either a single or multiple input contexts, +according to the needs of their application. +.NH 4 +Getting Keyboard Input +.XS +\*(SN Getting Keyboard Input +.XE +.LP +To obtain characters from an input method, +a client must call the function +.PN XmbLookupString +or +.PN XwcLookupString +with an input context created from that input method. +Both a locale and display are bound to an input method when it is opened, +and an input context inherits this locale and display. +Any strings returned by +.PN XmbLookupString +or +.PN XwcLookupString +will be encoded in that locale. +.NH 4 +Focus Management +.XS +\*(SN Focus Management +.XE +.LP +For each text entry area in which the +.PN XmbLookupString +or +.PN XwcLookupString +functions are used, +there will be an associated input context. +.LP +When the application focus moves to a text entry area, +the application must set the input context focus to the +input context associated with that area. +The input context focus is set by calling +.PN XSetICFocus +with the appropriate input context. +.LP +Also, when the application focus moves out of a text entry area, the +application should unset the focus for the associated input context +by calling +.PN XUnsetICFocus . +As an optimization, if +.PN XSetICFocus +is called successively on two different input contexts, +setting the focus on the second +will automatically unset the focus on the first. +.LP +To set and unset the input context focus correctly, +it is necessary to track application-level focus changes. +Such focus changes do not necessarily correspond to X server focus changes. +.LP +If a single input context +is being used to do input for +multiple text entry areas, it will also be necessary +to set the focus window of the +input context whenever the focus window changes +(see section 13.5.6.3). +.NH 4 +Geometry Management +.XS +\*(SN Geometry Management +.XE +.LP +In most input method architectures +(on-the-spot being the notable exception), +the input method will perform the display of its own data. +To provide better visual locality, +it is often desirable to have the input method areas embedded within a client. +To do this, +the client may need to allocate space for an input method. +Xlib provides support that allows the size and position of input method +areas to be provided by a client. +The input method areas that are supported for geometry management +are the status area and the preedit area. +.LP +The fundamental concept on which geometry management for input method windows +is based is the proper division of responsibilities between the +client (or toolkit) and the input method. +The division of responsibilities is as follows: +.IP \(bu 5 +The client is responsible for the geometry of the input method window. +.IP \(bu 5 +The input method is responsible for the contents of the input method window. +.LP +An input method is able to suggest a size to the client, +but it cannot suggest a placement. +Also the input method can only suggest a size. +It does not determine the size, +and it must accept the size it is given. +.LP +Before a client provides geometry management for an input method, +it must determine if geometry management is needed. +The input method indicates the need for geometry management +by setting +.PN XIMPreeditArea +or +.PN XIMStatusArea +in its +.PN XIMStyles +value returned by +.PN XGetIMValues . +When a client has decided that it will provide geometry management +for an input method, +it indicates that decision by setting the +.PN XNInputStyle +value in the +.PN XIC . +.LP +After a client has established with the input method +that it will do geometry management, +the client must negotiate the geometry with the input method. +The geometry is negotiated by the following steps: +.IP \(bu 5 +The client suggests an area to the input method by setting the +.PN XNAreaNeeded +value for that area. +If the client has no constraints for the input method, +it either will not suggest an area or will set the width and height to zero. +Otherwise, it will set one of the values. +.IP \(bu 5 +The client will get the XIC value +.PN XNAreaNeeded . +The input method will return its suggested size in this value. +The input method should pay attention to any constraints suggested +by the client. +.IP \(bu 5 +The client sets the XIC value +.PN XNArea +to inform the input method of the geometry of its window. +The client should try to honor the geometry requested by the input method. +The input method must accept this geometry. +.LP +Clients doing geometry management must be aware that setting other +XIC values may affect the geometry desired by an input method. +For example, +.PN XNFontSet +and +.PN XNLineSpacing +may change the geometry desired by the input method. +.LP +The table of XIC values (see section 13.5.6) +indicates the values that can cause the desired geometry to change +when they are set. +It is the responsibility of the client to renegotiate the geometry +of the input method window when it is needed. +.LP +In addition, +a geometry management callback is provided +by which an input method can initiate a geometry change. +.NH 4 +Event Filtering +.XS +\*(SN Event Filtering +.XE +.LP +A filtering mechanism is provided to allow input methods +to capture X events transparently to clients. +It is expected that toolkits (or clients) using +.PN XmbLookupString +or +.PN XwcLookupString +will call this filter at some point in the event processing mechanism +to make sure that events needed by an input method can be filtered +by that input method. +.LP +If there were no filter, +a client could receive and discard events that are necessary +for the proper functioning of an input method. +The following provides a few examples of such events: +.IP \(bu 5 +Expose events on preedit window in local mode. +.IP \(bu 5 +Events may be used by an input method to communicate with an input server. +Such input server protocol-related events have to be intercepted +if one does not want to disturb client code. +.IP \(bu 5 +Key events can be sent to a filter before they are bound +to translations such as those the X Toolkit Intrinsics library provides. +.LP +Clients are expected to get the XIC value +.PN XNFilterEvents +and augment the event mask for the client window with that event mask. +This mask may be zero. +.NH 4 +Callbacks +.XS +\*(SN Callbacks +.XE +.LP +When an on-the-spot input method is implemented, +only the client can insert or delete preedit data in place +and possibly scroll existing text. +This means that the echo of the keystrokes has to be achieved +by the client itself, tightly coupled with the input method logic. +.LP +When the user enters a keystroke, +the client calls +.PN XmbLookupString +or +.PN XwcLookupString . +At this point, in the on-the-spot case, +the echo of the keystroke in the preedit has not yet been done. +Before returning to the client logic that handles the input characters, +the look-up function +must call the echoing logic to insert the new keystroke. +If the keystrokes entered so far make up a character, +the keystrokes entered need to be deleted, +and the composed character will be returned. +Hence, what happens is that, while being called by client code, +the input method logic has to call back to the client before it returns. +The client code, that is, a callback procedure, +is called from the input method logic. +.LP +There are a number of cases where the input method logic has to +call back the client. +Each of those cases is associated with a well-defined callback action. +It is possible for the client to specify, for each input context, +what callback is to be called for each action. +.LP +There are also callbacks provided for feedback of status information +and a callback to initiate a geometry request for an input method. +.NH 4 +Visible Position Feedback Masks +.XS +\*(SN Visible Position Feedback Masks +.XE +.LP +In the on-the-spot input style, there is a problem when +attempting to draw preedit strings that are longer than the +available space. Once the display area is exceeded, it is not +clear how best to display the preedit string. +The visible position feedback masks of +.PN XIMText +help resolve this problem by allowing the input method to specify hints that +indicate the essential portions of the preedit string. +For example, such hints can help developers implement +scrolling of a long preedit string within a short preedit display area. +.NH 4 +Preedit String Management +.XS +\*(SN Preedit String Management +.XE +.LP +As highlighted before, the input method architecture provides +preediting, which supports a type of preprocessor input composition. +In this case, composition consists of interpreting a sequence +of key events and returning a committed string via +.PN XmbLookupString +or +.PN XwcLookupString . +This provides the basics for input methods. +.LP +In addition to preediting based on key events, a general framework +is provided to give a client that desires it more advanced preediting based +on the text within the client. This framework is called +\fIstring conversion\fP and is provided using XIC values. +The fundamental concept of string conversion +is to allow the input method to manipulate the client's +text independent of any user preediting operation. +.LP +The need for string conversion is based on +language needs and input method capabilities. +The following are some examples of string conversion: +.IP \(bu 5 +Transliteration conversion provides language-specific conversions +within the input method. +In the case of Korean input, users wish to convert a Hangul string +into a Hanja string while in preediting, after preediting, +or in other situations (for example, on a selected string). +The conversion is triggered when the user +presses a Hangul-to-Hanja key sequence (which may be input method specific). +Sometimes the user may want to invoke the conversion after finishing +preediting or on a user-selected string. +Thus, the string to be converted is in an application buffer, not in +the preedit area of the input method. The string conversion services +allow the client to request this transliteration conversion from the +input method. +There are many other transliteration conversions defined for +various languages, for example, Kana-to-Kanji conversion in Japanese. +.sp +The key to remember is that transliteration conversions are triggered +at the request of the user and returned to the client +immediately without affecting the preedit area of the input method. +.IP \(bu 5 +Reconversion of a previously committed string or +a selected string is supported by many input methods as a +convenience to the user. +For example, a user tends to mistype the commit key while +preediting. In that case, some input methods provide a special +key sequence to request a ``reconvert'' operation on the +committed string, similiar to the undo facility provided by most +text editors. +Another example is where the user is proofreading a document +that has some misconversions from preediting and wants to correct +the misconverted text. Such reconversion is again triggered +by the user invoking some special action, but reconversions should +not affect the state of the preedit area. +.IP \(bu 5 +Context-sensitive conversion is required for some languages +and input methods that need to retrieve text that surrounds the +current spot location (cursor position) of the client's buffer. +Such text is needed when the preediting operation depends on +some surrounding characters (usually preceding the spot location). +For example, +in Thai language input, certain character sequences may be invalid and +the input method may want to check whether characters constitute a +valid word. Input methods that do such context-dependent +checking need to retrieve the characters surrounding the current +cursor position to obtain complete words. +.sp +Unlike other conversions, this conversion is not explicitly +requested by the user. +Input methods that provide such context-sensitive conversion +continuously need to request context from the client, and any change +in the context of the spot location may affect such conversions. +The client's context would be needed if the user moves the cursor +and starts editing again. +.sp +For this reason, an input method supporting this type of conversion +should take notice of when the client calls +.PN XmbResetIC +or +.PN XwcResetIC , +which is usually an indication of a context change. +.LP +Context-sensitive conversions just need a copy of the client's text, +while other conversions replace the client's text with new text +to achieve the reconversion or transliteration. Yet in all +cases the result of a conversion, either immediately or via preediting, +is returned by the +.PN XmbLookupString +and +.PN XwcLookupString +functions. +.LP +String conversion support is dependent on the availability of the +.PN XNStringConversion +or +.PN XNStringConversionCallback +XIC values. +Because the input method may not support string conversions, +clients have to query the availability of string conversion +operations by checking the supported XIC values list by calling +.PN XGetIMValues +with the +.PN XNQueryICValuesList +IM value. +.LP +The difference between these two values is whether the +conversion is invoked by the client or the input method. +The +.PN XNStringConversion +XIC value is used by clients to request +a string conversion from the input method. The client +is responsible for determining which events are used +to trigger the string conversion and whether the string to be +converted should be copied or deleted. The type of conversion +is determined by the input method; the client can only +pass the string to be converted. The client is guaranteed that +no +.PN XNStringConversionCallback +will be issued when this value is set; thus, the client need +only set one of these values. +.LP +The +.PN XNStringConversionCallback +XIC value is used by the client to notify the input method that +it will accept requests from the input method for string conversion. +If this value is set, +it is the input method's responsibility to determine which +events are used to trigger the string conversion. +When such events occur, the input method issues a call to the +client-supplied procedure to retrieve the string to be converted. The client's +callback procedure is notified whether to copy or delete the string and +is provided with hints as to the amount of text needed. +The +.PN XIMStringConversionCallbackStruct +specifies which text should be passed back to the input method. +.LP +Finally, the input method may call the client's +.PN XNStringConversionCallback +procedure multiple times if the string returned from the callback is +not sufficient to perform a successful conversion. The arguments +to the client's procedure allow the input method to define a +position (in character units) relative to the client's cursor position +and the size of the text needed. By varying the position and size of +the desired text in subsequent callbacks, the input method can retrieve +additional text. +.LP +.NH 3 +Input Method Management +.XS +\*(SN Input Method Management +.XE +.LP +The interface to input methods might appear to be simply creating +an input method +.Pn ( XOpenIM ) +and freeing an input method +.Pn ( XCloseIM ). +However, input methods may +require complex communication with input method servers (IM servers), +for example: +.IP \(bu 5 +If the X server, IM server, and X clients are started asynchronously, +some clients may attempt to connect to the IM server before it is +fully operational, and fail. +Therefore, some mechanism is needed to allow clients to detect when an IM +server has started. +.LP +It is up to clients to decide what should be done when an IM server is +not available (for example, wait, or use some other IM server). +.LP +.IP \(bu 5 +Some input methods may allow the underlying IM server to be switched. +Such customization may be desired without restarting the entire client. +.LP +To support management of input methods in these cases, the following +functions are provided: +.TS +lw(2.4i) lw(3.3i). +T{ +.PN XRegisterIMInstantiateCallback +T} T{ +This function allows clients to register a callback procedure +to be called when Xlib detects that an IM server is up and available. +T} +T{ +.PN XOpenIM +T} T{ +A client calls this function as a result of the callback procedure +being called. +T} +T{ +.PN XSetIMValue , +.PN XSetICValue +T} T{ +These functions use the XIM and XIC values, +.PN XNDestroyCallback , +to allow a client +to register a callback procedure to be called when Xlib detects that +an IM server that was associated with an opened +input method is no longer available. +.sp 4p +In addition, this function can be used to switch IM servers for those input +methods that support such functionality. The IM value for switching IM +servers is implementation-dependent; see the description below about +switching IM servers. +T} +T{ +.PN XUnregisterIMInstantiateCallback +T} T{ +This function removes a callback procedure registered by the client. +T} +.TE +.LP +Input methods that support switching of IM servers may exhibit some +side-effects: +.IP \(bu 5 +The input method will ensure that any new IM server supports any of the +input styles being used by input contexts already associated with the +input method. +However, the list of supported input styles may be different. +.LP +.IP \(bu 5 +Geometry management requests on previously created input contexts +may be initiated by the new IM server. +.LP +.NH 4 +Hot Keys +.XS +\*(SN Hot Keys +.XE +.LP +Some clients need to guarantee which keys can be used to escape from the +input method, regardless of the input method state; +for example, the client-specific Help key or the keys to move the +input focus. +The HotKey mechanism allows clients +to specify a set of keys for this purpose. However, the input +method might not allow clients to specify hot keys. +Therefore, clients have to query support of hot keys by checking the +supported XIC values list by calling +.PN XGetIMValues +with the +.PN XNQueryICValuesList +IM value. +When the hot keys specified conflict with the key bindings of the +input method, hot keys take precedence over the key bindings of the input +method. +.LP +.NH 4 +Preedit State Operation +.XS +\*(SN Preedit State Operation +.XE +.LP +An input method may have several internal states, depending on its +implementation and the locale. However, one state that is +independent of locale and implementation is whether the input method +is currently performing a preediting operation. +Xlib provides the ability for an application to manage the preedit state +programmatically. Two methods are provided for +retrieving the preedit state of an input context. +One method is to query the state by calling +.PN XGetICValues +with the +.PN XNPreeditState +XIC value. +Another method is to receive notification whenever +the preedit state is changed. To receive such notification, +an application needs to register a callback by calling +.PN XSetICValues +with the +.PN XNPreeditStateNotifyCallback +XIC value. +In order to change the preedit state programmatically, an application +needs to call +.PN XSetICValues +with +.PN XNPreeditState. +.LP +Availability of the preedit state is input method dependent. The input +method may not provide the ability to set the state or to +retrieve the state programmatically. Therefore, clients have to +query availability of preedit state operations by checking the +supported XIC values list by calling +.PN XGetIMValues +with the +.PN XNQueryICValuesList +IM value. +.NH 3 +Input Method Functions +.XS +\*(SN Input Method Functions +.XE +.LP +To open a connection, use +.PN XOpenIM . +.IN "XOpenIM" "" "@DEF@" +.sM +.FD 0 +XIM XOpenIM\^(\^\fIdisplay\fP\^, \fIdb\fP\^, \fIres_name\fP\^, \fIres_class\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XrmDatabase \fIdb\fP\^; +.br + char *\fIres_name\fP\^; +.br + char *\fIres_class\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIdb\fP 1i +Specifies a pointer to the resource database. +.IP \fIres_name\fP 1i +Specifies the full resource name of the application. +.IP \fIres_class\fP 1i +Specifies the full class name of the application. +.LP +.eM +The +.PN XOpenIM +function opens an input method, +matching the current locale and modifiers specification. +Current locale and modifiers are bound to the input method at opening time. +The locale associated with an input method cannot be changed dynamically. +This implies that the strings returned by +.PN XmbLookupString +or +.PN XwcLookupString , +for any input context affiliated with a given input method, +will be encoded in the locale current at the time the input method is opened. +.LP +The specific input method to which this call will be routed +is identified on the basis of the current locale. +.PN XOpenIM +will identify a default input method corresponding to the +current locale. +That default can be modified using +.PN XSetLocaleModifiers +for the input method modifier. +.LP +The db argument is the resource database to be used by the input method +for looking up resources that are private to the input method. +It is not intended that this database be used to look +up values that can be set as IC values in an input context. +If db is NULL, +no database is passed to the input method. +.LP +The res_name and res_class arguments specify the resource name +and class of the application. +They are intended to be used as prefixes by the input method +when looking up resources that are common to all input contexts +that may be created for this input method. +The characters used for resource names and classes must be in the +X Portable Character Set. +The resources looked up are not fully specified +if res_name or res_class is NULL. +.LP +The res_name and res_class arguments are not assumed to exist beyond +the call to +.PN XOpenIM . +The specified resource database is assumed to exist for the lifetime +of the input method. +.LP +.PN XOpenIM +returns NULL if no input method could be opened. +.LP +.sp +To close a connection, use +.PN XCloseIM . +.IN "XCloseIM" "" "@DEF@" +.sM +.FD 0 +Status XCloseIM\^(\^\fIim\fP\^) +.br + XIM \fIim\fP\^; +.FN +.IP \fIim\fP 1i +Specifies the input method. +.LP +.eM +The +.PN XCloseIM +function closes the specified input method. +.LP +.sp +To set input method attributes, use +.PN XSetIMValues . +.IN "XSetIMValues" "" "@DEF@" +.sM +.FD 0 +char * XSetIMValues\^(\^\fIim\fP\^, ...) +.br + XIM \fIim\fP\^; +.FN +.IP \fIim\fP 1i +Specifies the input method. +.ds Al \ to set XIM values +.IP ... 1i +Specifies the variable-length argument list\*(Al. +.LP +.eM +The +.PN XSetIMValues +function presents a variable argument list programming interface +for setting attributes of the specified input method. +It returns NULL if it succeeds; +otherwise, +it returns the name of the first argument that could not be set. +Xlib does not attempt to set arguments from the supplied list that +follow the failed argument; +all arguments in the list preceding the failed argument have been set +correctly. +.LP +.sp +To query an input method, use +.PN XGetIMValues . +.IN "XGetIMValues" "" "@DEF@" +.sM +.FD 0 +char * XGetIMValues\^(\^\fIim\fP\^, ...) +.br + XIM \fIim\fP\^; +.FN +.IP \fIim\fP 1i +Specifies the input method. +.ds Al \ to get XIM values +.IP ... 1i +Specifies the variable length argument list\*(Al. +.LP +.eM +The +.PN XGetIMValues +function presents a variable argument list programming interface +for querying properties or features of the specified input method. +This function returns NULL if it succeeds; +otherwise, +it returns the name of the first argument that could not be obtained. +.LP +Each XIM value argument (following a name) must point to +a location where the XIM value is to be stored. +That is, if the XIM value is of type T, +the argument must be of type T*. +If T itself is a pointer type, +then +.PN XGetIMValues +allocates memory to store the actual data, +and the client is responsible for freeing this data by calling +.PN XFree +with the returned pointer. +.LP +.sp +To obtain the display associated with an input method, use +.PN XDisplayOfIM . +.IN "XDisplayOfIM" "" "@DEF@" +.sM +.FD 0 +Display * XDisplayOfIM\^(\^\fIim\fP\^) +.br + XIM \fIim\fP\^; +.FN +.IP \fIim\fP 1i +Specifies the input method. +.LP +.eM +The +.PN XDisplayOfIM +function returns the display associated with the specified input method. +.LP +.sp +To get the locale associated with an input method, use +.PN XLocaleOfIM . +.IN "XLocaleOfIM" "" "@DEF@" +.sM +.FD 0 +char * XLocaleOfIM\^(\^\fIim\fP\^) +.br + XIM \fIim\fP\^; +.FN +.IP \fIim\fP 1i +Specifies the input method. +.LP +.eM +The +.PN XLocaleOfIM +function returns the locale associated with the specified input method. +.LP +.sp +To register an input method instantiate callback, use +.PN XRegisterIMInstantiateCallback . +.IN "XRegisterIMInstantiateCallback" "" "@DEF@" +.sM +.FD 0 +Bool XRegisterIMInstantiateCallback\^(\^\fIdisplay\fP\^, \fIdb\fP\^, \fIres_name\fP\^, \fIres_class\fP\^, \fIcallback\fP\^, \fIclient_data\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XrmDatabase \fIdb\fP\^; +.br + char *\fIres_name\fP\^; +.br + char *\fIres_class\fP\^; +.br + XIMProc \fIcallback\fP\^; +.br + XPointer *\fIclient_data\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIdb\fP 1i +Specifies a pointer to the resource database. +.IP \fIres_name\fP 1i +Specifies the full resource name of the application. +.IP \fIres_class\fP 1i +Specifies the full class name of the application. +.IP \fIcallback\fP 1i +Specifies a pointer to the input method instantiate callback. +.IP \fIclient_data\fP 1i +Specifies the additional client data. +.LP +.eM +The +.PN XRegisterIMInstantiateCallback +function registers a callback to be invoked whenever a new input method +becomes available for the specified display that matches the current +locale and modifiers. +.LP +The function returns +.PN True + if it succeeds; otherwise, it returns +.PN False . +.LP +The generic prototype is as follows: +.IN "IMInstantiateCallback" "" "@DEF@" +.sM +.FD 0 +void IMInstantiateCallback\^(\^\fIdisplay\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XPointer \fIclient_data\fP\^; +.br + XPointer \fIcall_data\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIclient_data\fP 1i +Specifies the additional client data. +.IP \fIcall_data\fP 1i +Not used for this callback and always passed as NULL. +.LP +.eM +To unregister an input method instantiation callback, use +.PN XUnregisterIMInstantiateCallback . +.IN "XUnregisterIMInstantiateCallback" "" "@DEF@" +.sM +.FD 0 +Bool XUnregisterIMInstantiateCallback\^(\^\fIdisplay\fP\^, \fIdb\fP\^, \fIres_name\fP\^, \fIres_class\fP\^, \fIcallback\fP\^, \fIclient_data\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XrmDatabase \fIdb\fP\^; +.br + char *\fIres_name\fP\^; +.br + char *\fIres_class\fP\^; +.br + XIMProc \fIcallback\fP\^; +.br + XPointer *\fIclient_data\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIdb\fP 1i +Specifies a pointer to the resource database. +.IP \fIres_name\fP 1i +Specifies the full resource name of the application. +.IP \fIres_class\fP 1i +Specifies the full class name of the application. +.IP \fIcallback\fP 1i +Specifies a pointer to the input method instantiate callback. +.IP \fIclient_data\fP 1i +Specifies the additional client data. +.LP +.eM +The +.PN XUnregisterIMInstantiateCallback +function removes an input method instantiation callback previously +registered. +The function returns +.PN True +if it succeeds; otherwise, it returns +.PN False . +.NH 3 +Input Method Values +.XS +\*(SN Input Method Values +.XE +.LP +The following table describes how XIM values are interpreted +by an input method. +The first column lists the XIM values. +The second column indicates how each of the XIM values +are treated by that input style. +.LP +.LP +The following keys apply to this table. +.TS H +lw(1i) lw(4.75i). +_ +.sp 6p +.B +Key Explanation +.sp 6p +_ +.TH +.R +D T{ +This value may be set using +.PN XSetIMValues . +If it is not set, +.br +a default is provided. +T} +S T{ +This value may be set using +.PN XSetIMValues . +T} +G T{ +This value may be read using +.PN XGetIMValues . +T} +.sp 6p +_ +.TE +.LP +.TS H +lw(2.25i) c +lw(2.25i) c. +_ +.sp 6p +.B +XIM Value Key +.sp 6p +_ +.sp 6p +.TH +.R +T{ +.PN XNQueryInputStyle +T} T{ +G +T} +T{ +.PN XNResourceName +T} T{ +D-S-G +T} +T{ +.PN XNResourceClass +T} T{ +D-S-G +T} +T{ +.PN XNDestroyCallback +T} T{ +D-S-G +T} +T{ +.PN XNQueryIMValuesList +T} T{ +G +T} +T{ +.PN XNQueryICValuesList +T} T{ +G +T} +T{ +.PN XNVisiblePosition +T} T{ +G +T} +T{ +.PN XNR6PreeditCallbackBehavior +T} T{ +D-S-G +T} +.sp 6p +_ +.TE +.LP +.PN XNR6PreeditCallbackBehavior +is obsolete and its use is not recommended (see section 13.5.4.6). +.LP +.NH 4 +Query Input Style +.XS +\*(SN Query Input Style +.XE +.LP +A client should always query the input method to determine which input +styles are supported. +The client should then find an input style it is capable of supporting. +.LP +If the client cannot find an input style that it can support, +it should negotiate with the user the continuation of the program +(exit, choose another input method, and so on). +.LP +The argument value must be a pointer to a location +where the returned value will be stored. +The returned value is a pointer to a structure of type +.PN XIMStyles . +Clients are responsible for freeing the +.PN XIMStyles +structure. +To do so, use +.PN XFree . +.LP +The +.PN XIMStyles +structure is defined as follows: +.LP +.IN "XIMStyle" "" "@DEF@" +.IN "XIMPreeditArea" "" "@DEF@" +.IN "XIMPreeditCallbacks" "" "@DEF@" +.IN "XIMPreeditPosition" "" "@DEF@" +.IN "XIMPreeditNothing" "" "@DEF@" +.IN "XIMPreeditNone" "" "@DEF@" +.IN "XIMStatusArea" "" "@DEF@" +.IN "XIMStatusCallbacks" "" "@DEF@" +.IN "XIMStatusNothing" "" "@DEF@" +.IN "XIMStatusNone" "" "@DEF@" +.IN "XIMStyles" "" "@DEF@" +.sM +.Ds 0 +typedef unsigned long XIMStyle; +.De +.TS +lw(.5i) lw(2i) lw(2.5i). +T{ +#define +T} T{ +.PN XIMPreeditArea +T} T{ +0x0001L +T} +T{ +#define +T} T{ +.PN XIMPreeditCallbacks +T} T{ +0x0002L +T} +T{ +#define +T} T{ +.PN XIMPreeditPosition +T} T{ +0x0004L +T} +T{ +#define +T} T{ +.PN XIMPreeditNothing +T} T{ +0x0008L +T} +T{ +#define +T} T{ +.PN XIMPreeditNone +T} T{ +0x0010L +T} +.sp +T{ +#define +T} T{ +.PN XIMStatusArea +T} T{ +0x0100L +T} +T{ +#define +T} T{ +.PN XIMStatusCallbacks +T} T{ +0x0200L +T} +T{ +#define +T} T{ +.PN XIMStatusNothing +T} T{ +0x0400L +T} +T{ +#define +T} T{ +.PN XIMStatusNone +T} T{ +0x0800L +T} +.TE +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef struct { + unsigned short count_styles; + XIMStyle * supported_styles; +} XIMStyles; +.De +.LP +.eM +An +.PN XIMStyles +structure contains the number of input styles supported +in its count_styles field. +This is also the size of the supported_styles array. +.LP +The supported styles is a list of bitmask combinations, +which indicate the combination of styles for each of the areas supported. +These areas are described later. +Each element in the list should select one of the bitmask values for +each area. +The list describes the complete set of combinations supported. +Only these combinations are supported by the input method. +.LP +The preedit category defines what type of support is provided +by the input method for preedit information. +.IN "XIMPreeditArea" "" "@DEF@" +.IN "XIMPreeditPosition" "" "@DEF@" +.IN "XIMPreeditCallbacks" "" "@DEF@" +.IN "XIMPreeditNothing" "" "@DEF@" +.IN "XIMPreeditNone" "" "@DEF@" +.TS +lw(1.5i) lw(4.25i). +T{ +.PN XIMPreeditArea +T} T{ +If chosen, +the input method would require the client to provide some area values +for it to do its preediting. +Refer to XIC values +.PN XNArea +and +.PN XNAreaNeeded . +T} +T{ +.PN XIMPreeditPosition +T} T{ +If chosen, +the input method would require the client to provide positional values. +Refer to XIC values +.PN XNSpotLocation +and +.PN XNFocusWindow . +T} +T{ +.PN XIMPreeditCallbacks +T} T{ +If chosen, +the input method would require the client to define the set of preedit callbacks. +Refer to XIC values +.PN XNPreeditStartCallback , +.PN XNPreeditDoneCallback , +.PN XNPreeditDrawCallback , +and +.PN XNPreeditCaretCallback . +T} +T{ +.PN XIMPreeditNothing +T} T{ +If chosen, the input method can function without any preedit values. +T} +T{ +.PN XIMPreeditNone +T} T{ +The input method does not provide any preedit feedback. +Any preedit value is ignored. +This style is mutually exclusive with the other preedit styles. +T} +.TE +.LP +The status category defines what type of support is provided +by the input method for status information. +.IN "XIMStatusArea" "" "@DEF@" +.IN "XIMStatusCallbacks" "" "@DEF@" +.IN "XIMStatusNothing" "" "@DEF@" +.IN "XIMStatusNone" "" "@DEF@" +.TS +lw(1.5i) lw(4.25i). +T{ +.PN XIMStatusArea +T} T{ +The input method requires the client to provide +some area values for it to do its status feedback. +See +.PN XNArea +and +.PN XNAreaNeeded . +T} +T{ +.PN XIMStatusCallbacks +T} T{ +The input method requires the client to define the set of status callbacks, +.PN XNStatusStartCallback , +.PN XNStatusDoneCallback , +and +.PN XNStatusDrawCallback . +T} +T{ +.PN XIMStatusNothing +T} T{ +The input method can function without any status values. +T} +T{ +.PN XIMStatusNone +T} T{ +The input method does not provide any status feedback. +If chosen, any status value is ignored. +This style is mutually exclusive with the other status styles. +T} +.TE +.NH 4 +Resource Name and Class +.XS +\*(SN Resource Name and Class +.XE +.LP +The +.PN XNResourceName +and +.PN XNResourceClass +arguments are strings that specify the full name and class +used by the input method. +These values should be used as prefixes for the name and class +when looking up resources that may vary according to the input method. +If these values are not set, +the resources will not be fully specified. +.LP +It is not intended that values that can be set as XIM values be +set as resources. +.LP +.NH 4 +Destroy Callback +.XS +\*(SN Destroy Callback +.XE +.LP +The +.PN XNDestroyCallback +argument is a pointer to a structure of type +.PN XIMCallback . +.PN XNDestroyCallback +is triggered when an input method stops its service for any reason. +After the callback is invoked, the input method is closed and the +associated input context(s) are destroyed by Xlib. +Therefore, the client should not call +.PN XCloseIM +or +.PN XDestroyIC . +.LP +The generic prototype of this callback function is as follows: +.IN "DestroyCallback" "" "@DEF@" +.sM +.FD 0 +void DestroyCallback\^(\^\fIim\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^) +.br + XIM \fIim\fP\^; +.br + XPointer \fIclient_data\fP\^; +.br + XPointer \fIcall_data\fP\^; +.FN +.IP \fIim\fP 1i +Specifies the input method. +.IP \fIclient_data\fP 1i +Specifies the additional client data. +.IP \fIcall_data\fP 1i +Not used for this callback and always passed as NULL. +.LP +.eM +A DestroyCallback is always called with a NULL call_data argument. +.LP +.NH 4 +Query IM/IC Values List +.XS +\*(SN Query IM/IC Values List +.XE +.LP +.PN XNQueryIMValuesList +and +.PN XNQueryICValuesList +are used to query about XIM and XIC values supported by the input method. +.LP +The argument value must be a pointer to a location where the returned +value will be stored. The returned value is a pointer to a structure +of type +.PN XIMValuesList . +Clients are responsible for freeing the +.PN XIMValuesList +structure. +To do so, use +.PN XFree . +.LP +The +.PN XIMValuesList +structure is defined as follows: +.sM +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef struct { + unsigned short count_values; + char **supported_values; +} XIMValuesList; +.De +.LP +.eM +.NH 4 +Visible Position +.XS +\*(SN Visible Position +.XE +.LP +The +.PN XNVisiblePosition +argument indicates whether the visible position masks of +.PN XIMFeedback +in +.PN XIMText +are available. +.LP +The argument value must be a pointer to a location where the returned +value will be stored. The returned value is of type +.PN Bool . +If the returned value is +.PN True , +the input method uses the visible position masks of +.PN XIMFeedback +in +.PN XIMText ; +otherwise, the input method does not use the masks. +.LP +Because this XIM value is optional, a client should call +.PN XGetIMValues +with argument +.PN XNQueryIMValues +before using this argument. +If the +.PN XNVisiblePosition +does not exist in the IM values list returned from +.PN XNQueryIMValues , +the visible position masks of +.PN XIMFeedback +in +.PN XIMText +are not used to indicate the visible position. +.LP +.NH 4 +Preedit Callback Behavior +.XS +\*(SN Preedit Callback Behavior +.XE +.LP +The +.PN XNR6PreeditCallbackBehavior +argument originally included in the X11R6 specification has been +deprecated.\(dg +.\" If XNR6PreeditCallbackBehavior is not deprecated, then its type +.\" should be changed from *Bool to Bool. +.FS \(dg +During formulation of the X11R6 specification, the behavior of +the R6 PreeditDrawCallbacks was going to differ significantly from +that of the R5 callbacks. +Late changes to the specification converged the R5 and R6 behaviors, +eliminating the need for +.PN XNR6PreeditCallbackBehavior . +Unfortunately, this argument was not removed from the R6 specification +before it was published. +.FE +.LP +The +.PN XNR6PreeditCallbackBehavior +argument indicates whether the behavior of preedit callbacks regarding +.PN XIMPreeditDrawCallbackStruct +values follows Release 5 or Release 6 semantics. +.LP +The value is of type +.PN Bool . +When querying for +.PN XNR6PreeditCallbackBehavior , +if the returned value is +.PN True , +the input method uses the Release 6 behavior; +otherwise, it uses the Release 5 behavior. +The default value is +.PN False . +In order to use Release 6 semantics, the value of +.PN XNR6PreeditCallbackBehavior +must be set to +.PN True . +.LP +Because this XIM value is optional, a client should call +.PN XGetIMValues +with argument +.PN XNQueryIMValues +before using this argument. +If the +.PN XNR6PreeditCallbackBehavior +does not exist in the IM values list returned from +.PN XNQueryIMValues , +the PreeditCallback behavior is Release 5 semantics. +.LP +.NH 3 +Input Context Functions +.XS +\*(SN Input Context Functions +.XE +.LP +An input context is an abstraction that is used to contain both the data +required (if any) by an input method and the information required +to display that data. +There may be multiple input contexts for one input method. +The programming interfaces for creating, reading, or modifying +an input context use a variable argument list. +The name elements of the argument lists are referred to as XIC values. +It is intended that input methods be controlled by these XIC values. +As new XIC values are created, +they should be registered with the X Consortium. +.LP +.sp +To create an input context, use +.PN XCreateIC . +.IN "XCreateIC" "" "@DEF@" +.sM +.FD 0 +XIC XCreateIC\^(\^\fIim\fP\^, ...) +.br + XIM \fIim\fP\^; +.FN +.IP \fIim\fP 1i +Specifies the input method. +.ds Al \ to set XIC values +.IP ... 1i +Specifies the variable length argument list\*(Al. +.LP +.eM +The +.PN XCreateIC +function creates a context within the specified input method. +.LP +Some of the arguments are mandatory at creation time, and +the input context will not be created if those arguments are not provided. +The mandatory arguments are the input style and the set of text callbacks +(if the input style selected requires callbacks). +All other input context values can be set later. +.LP +.PN XCreateIC +returns a NULL value if no input context could be created. +A NULL value could be returned for any of the following reasons: +.IP \(bu 5 +A required argument was not set. +.IP \(bu 5 +A read-only argument was set (for example, +.PN XNFilterEvents ). +.IP \(bu 5 +The argument name is not recognized. +.IP \(bu 5 +The input method encountered an input method implementation-dependent error. +.LP +.PN XCreateIC +can generate +.PN BadAtom , +.PN BadColor , +.PN BadPixmap , +and +.PN BadWindow +errors. +.LP +.sp +To destroy an input context, use +.PN XDestroyIC . +.IN "XDestroyIC" "" "@DEF@" +.sM +.FD 0 +void XDestroyIC\^(\^\fIic\fP\^) +.br + XIC \fIic\fP\^; +.FN +.IP \fIic\fP 1i +Specifies the input context. +.LP +.eM +.PN XDestroyIC +destroys the specified input context. +.LP +.sp +To communicate to and synchronize with input method +for any changes in keyboard focus from the client side, +use +.PN XSetICFocus +and +.PN XUnsetICFocus . +.IN "XSetICFocus" "" "@DEF@" +.sM +.FD 0 +void XSetICFocus\^(\^\fIic\fP\^) +.br + XIC \fIic\fP\^; +.FN +.IP \fIic\fP 1i +Specifies the input context. +.LP +.eM +The +.PN XSetICFocus +function allows a client to notify an input method that the focus window +attached to the specified input context has received keyboard focus. +The input method should take action to provide appropriate feedback. +Complete feedback specification is a matter of user interface policy. +.LP +Calling +.PN XSetICFocus +does not affect the focus window value. +.LP +.sp +.IN "XUnsetICFocus" "" "@DEF@" +.sM +.FD 0 +void XUnsetICFocus\^(\^\fIic\fP\^) +.br + XIC \fIic\fP\^; +.FN +.IP \fIic\fP 1i +Specifies the input context. +.LP +.eM +The +.PN XUnsetICFocus +function allows a client to notify an input method that the specified input context +has lost the keyboard focus and that no more input is expected on the focus window +attached to that input context. +The input method should take action to provide appropriate feedback. +Complete feedback specification is a matter of user interface policy. +.LP +Calling +.PN XUnsetICFocus +does not affect the focus window value; +the client may still receive +events from the input method that are directed to the focus window. +.LP +.sp +To reset the state of an input context to its initial state, use +.PN XmbResetIC +or +.PN XwcResetIC . +.IN "XmbResetIC" "" "@DEF@" +.IN "XwcResetIC" "" "@DE@" +.sM +.FD 0 +char * XmbResetIC\^(\^\fIic\fP\^) +.br + XIC \fIic\fP\^; +.FN +.FD 0 +wchar_t * XwcResetIC\^(\^\fIic\fP\^) +.br + XIC \fIic\fP\^; +.FN +.IP \fIic\fP 1i +Specifies the input context. +.LP +.eM +When +.PN XNResetState +is set to +.PN XIMInitialState , +.PN XmbResetIC +and +.PN XwcResetIC +reset an input context to its initial state; +when +.PN XNResetState +is set to +.PN XIMPreserveState , +the current input context state is preserved. +In both cases, any input pending on that context is deleted. +The input method is required to clear the preedit area, if any, +and update the status accordingly. +Calling +.PN XmbResetIC +or +.PN XwcResetIC +does not change the focus. +.LP +The return value of +.PN XmbResetIC +is its current preedit string as a multibyte string. +If there is any preedit text drawn or visible to the user, +then these procedures must return a non-NULL string. +If there is no visible preedit text, +then it is input method implementation-dependent +whether these procedures return a non-NULL string or NULL. +.LP +The client should free the returned string by calling +.PN XFree . +.LP +.sp +To get the input method associated with an input context, use +.PN XIMOfIC . +.IN "XIMOfIC" "" "@DEF@" +.sM +.FD 0 +XIM XIMOfIC\^(\^\fIic\fP\^) +.br + XIC \fIic\fP\^; +.FN +.IP \fIic\fP 1i +Specifies the input context. +.LP +.eM +The +.PN XIMOfIC +function returns the input method associated with the specified input context. +.LP +.sp +Xlib provides two functions for setting and reading XIC values, respectively, +.PN XSetICValues +and +.PN XGetICValues . +Both functions have a variable-length argument list. +In that argument list, any XIC value's name must be denoted +with a character string using the X Portable Character Set. +.LP +.sp +To set XIC values, use +.PN XSetICValues . +.IN "XSetICValues" "" "@DEF@" +.sM +.FD 0 +char * XSetICValues\^(\^\fIic\fP\^, ...) +.br + XIC \fIic\fP\^; +.FN +.IP \fIic\fP 1i +Specifies the input context. +.ds Al \ to set XIC values +.IP ... 1i +Specifies the variable length argument list\*(Al. +.LP +.eM +The +.PN XSetICValues +function returns NULL if no error occurred; +otherwise, +it returns the name of the first argument that could not be set. +An argument might not be set for any of the following reasons: +.IP \(bu 5 +The argument is read-only (for example, +.PN XNFilterEvents ). +.IP \(bu 5 +The argument name is not recognized. +.IP \(bu 5 +An implementation-dependent error occurs. +.LP +Each value to be set must be an appropriate datum, +matching the data type imposed by the semantics of the argument. +.LP +.PN XSetICValues +can generate +.PN BadAtom , +.PN BadColor , +.PN BadCursor , +.PN BadPixmap , +and +.PN BadWindow +errors. +.LP +.sp +To obtain XIC values, use +.PN XGetICValues . +.IN "XGetICValues" "" "@DEF@" +.sM +.FD 0 +char * XGetICValues\^(\^\fIic\fP\^, ...) +.br + XIC \fIic\fP\^; +.FN +.IP \fIic\fP 1i +Specifies the input context. +.ds Al \ to get XIC values +.IP ... 1i +Specifies the variable length argument list\*(Al. +.LP +.eM +The +.PN XGetICValues +function returns NULL if no error occurred; otherwise, +it returns the name of the first argument that could not be obtained. +An argument could not be obtained for any of the following reasons: +.IP \(bu 5 +The argument name is not recognized. +.IP \(bu 5 +The input method encountered an implementation-dependent error. +.LP +Each IC attribute value argument (following a name) must point to +a location where the IC value is to be stored. +That is, if the IC value is of type T, +the argument must be of type T*. +If T itself is a pointer type, +then +.PN XGetICValues +allocates memory to store the actual data, +and the client is responsible for freeing this data by calling +.PN XFree +with the returned pointer. +The exception to this rule is for an IC value of type +.PN XVaNestedList +(for preedit and status attributes). +In this case, the argument must also be of type +.PN XVaNestedList . +Then, the rule of changing type T to T* and freeing the allocated data +applies to each element of the nested list. +.NH 3 +Input Context Values +.XS +\*(SN Input Context Values +.XE +.LP +The following tables describe how XIC values are interpreted +by an input method depending on the input style chosen by the +user. +.LP +The first column lists the XIC values. +The second column indicates which values are involved in affecting, +negotiating, and setting the geometry of the input method windows. +The subentries under the third column indicate the different +input styles that are supported. +Each of these columns indicates how each of the XIC values +are treated by that input style. +.LP +The following keys apply to these tables. +.TS H +lw(1i) lw(4.75i). +_ +.sp 6p +.B +Key Explanation +.sp 6p +_ +.TH +.R +C T{ +This value must be set with +.PN XCreateIC . +T} +D T{ +This value may be set using +.PN XCreateIC . +If it is not set, +a default is provided. +T} +G T{ +This value may be read using +.PN XGetICValues . +T} +GN T{ +This value may cause geometry negotiation when its value is set by means of +.PN XCreateIC +or +.PN XSetICValues . +T} +GR T{ +This value will be the response of the input method when any +GN value is changed. +T} +GS T{ +This value will cause the geometry of the input method window to be set. +T} +O T{ +This value must be set once and only once. +It need not be set at create time. +T} +S T{ +This value may be set with +.PN XSetICValues . +T} +Ignored T{ +This value is ignored by the input method for the given input style. +T} +.sp 6p +_ +.TE +.LP +.TS H +c c c s s s s +l c c c c c c +c c c c c c c +l c c c c c c. +_ +.sp 6p +.B + Input Style +XIC Value Geometry Preedit Preedit Preedit Preedit Preedit + Management Callback Position Area Nothing None +.sp 6p +_ +.sp 6p +.TH +.R +Input Style C-G C-G C-G C-G C-G +Client Window O-G O-G O-G O-G Ignored +Focus Window GN D-S-G D-S-G D-S-G D-S-G Ignored +Resource Name Ignored D-S-G D-S-G D-S-G Ignored +Resource Class Ignored D-S-G D-S-G D-S-G Ignored +Geometry Callback Ignored Ignored D-S-G Ignored Ignored +Filter Events G G G G Ignored +Destroy Callback D-S-G D-S-G D-S-G D-S-G D-S-G +String Conversion Callback S-G S-G S-G S-G S-G +String Conversion D-S-G D-S-G D-S-G D-S-G D-S-G +Reset State D-S-G D-S-G D-S-G D-S-G Ignored +HotKey S-G S-G S-G S-G Ignored +HotKeyState D-S-G D-S-G D-S-G D-S-G Ignored +.sp 6p +\fBPreedit\fP +Area GS Ignored D-S-G D-S-G Ignored Ignored +Area Needed GN-GR Ignored Ignored S-G Ignored Ignored +Spot Location Ignored D-S-G Ignored Ignored Ignored +Colormap Ignored D-S-G D-S-G D-S-G Ignored +Foreground Ignored D-S-G D-S-G D-S-G Ignored +Background Ignored D-S-G D-S-G D-S-G Ignored +Background Pixmap Ignored D-S-G D-S-G D-S-G Ignored +Font Set GN Ignored D-S-G D-S-G D-S-G Ignored +Line Spacing GN Ignored D-S-G D-S-G D-S-G Ignored +Cursor Ignored D-S-G D-S-G D-S-G Ignored +Preedit State D-S-G D-S-G D-S-G D-S-G Ignored +Preedit State Notify Callback S-G S-G S-G S-G Ignored +Preedit Callbacks C-S-G Ignored Ignored Ignored Ignored +.sp 6p +_ +.TE +.LP +.TS H +c c c s s s +l c c c c c +c c c c c c +l c c c c c. +_ +.sp 6p +.B + Input Style +XIC Value Geometry Status Status Status Status + Management Callback Area Nothing None +.sp 6p +_ +.sp 6p +.TH +.R +Input Style C-G C-G C-G C-G +Client Window O-G O-G O-G Ignored +Focus Window GN D-S-G D-S-G D-S-G Ignored +Resource Name Ignored D-S-G D-S-G Ignored +Resource Class Ignored D-S-G D-S-G Ignored +Geometry Callback Ignored D-S-G Ignored Ignored +Filter Events G G G G +.sp 6p +\fBStatus\fP +Area GS Ignored D-S-G Ignored Ignored +Area Needed GN-GR Ignored S-G Ignored Ignored +Colormap Ignored D-S-G D-S-G Ignored +Foreground Ignored D-S-G D-S-G Ignored +Background Ignored D-S-G D-S-G Ignored +Background Pixmap Ignored D-S-G D-S-G Ignored +Font Set GN Ignored D-S-G D-S-G Ignored +Line Spacing GN Ignored D-S-G D-S-G Ignored +Cursor Ignored D-S-G D-S-G Ignored +Status Callbacks C-S-G Ignored Ignored Ignored +.sp 6p +_ +.TE +.NH 4 +Input Style +.XS +\*(SN Input Style +.XE +.LP +The +.PN XNInputStyle +argument specifies the input style to be used. +The value of this argument must be one of the values returned by the +.PN XGetIMValues +function with the +.PN XNQueryInputStyle +argument specified in the supported_styles list. +.LP +Note that this argument must be set at creation time +and cannot be changed. +.NH 4 +Client Window +.XS +\*(SN Client Window +.XE +.LP +.IN "XNClientWindow" "" "@DEF@" +The +.PN XNClientWindow +argument specifies to the input method the client window in +which the input method +can display data or create subwindows. +Geometry values for input method areas are given with respect to the client +window. +Dynamic change of client window is not supported. +This argument may be set only once and +should be set before any input is done using this input context. +If it is not set, +the input method may not operate correctly. +.LP +If an attempt is made to set this value a second time with +.PN XSetICValues , +the string +.PN XNClientWindow +will be returned by +.PN XSetICValues , +and the client window will not be changed. +.LP +If the client window is not a valid window ID on the display +attached to the input method, +a +.PN BadWindow +error can be generated when this value is used by the input method. +.NH 4 +Focus Window +.XS +\*(SN Focus Window +.XE +.LP +.IN "XNFocusWindow" "" "@DEF@" +The +.PN XNFocusWindow +argument specifies the focus window. +The primary purpose of the +.PN XNFocusWindow +is to identify the window that will receive the key event when input +is composed. +In addition, the input method may possibly affect the focus window +as follows: +.IP \(bu 5 +Select events on it +.IP \(bu 5 +Send events to it +.IP \(bu 5 +Modify its properties +.IP \(bu 5 +Grab the keyboard within that window +.LP +The associated value must be of type +.PN Window . +If the focus window is not a valid window ID on the display +attached to the input method, +a +.PN BadWindow +error can be generated when this value is used by the input method. +.LP +When this XIC value is left unspecified, +the input method will use the client window as the default focus window. +.NH 4 +Resource Name and Class +.XS +\*(SN Resource Name and Class +.XE +.LP +.IN "XNResourceName" "" "@DEF@" +.IN "XNResourceClass" "" "@DEF@" +The +.PN XNResourceName +and +.PN XNResourceClass +arguments are strings that specify the full name and class +used by the client to obtain resources for the client window. +These values should be used as prefixes for name and class +when looking up resources that may vary according to the input context. +If these values are not set, +the resources will not be fully specified. +.LP +It is not intended that values that can be set as XIC values be +set as resources. +.NH 4 +Geometry Callback +.XS +\*(SN Geometry Callback +.XE +.LP +.IN "XNGeometryCallback" "" "@DEF@" +The +.PN XNGeometryCallback +argument is a structure of type +.PN XIMCallback +(see section 13.5.6.13.12). +.LP +The +.PN XNGeometryCallback +argument specifies the geometry callback that a client can set. +This callback is not required for correct operation of either +an input method or a client. +It can be set for a client whose user interface policy permits +an input method to request the dynamic change of that input +method's window. +An input method that does dynamic change will need to filter any +events that it uses to initiate the change. +.NH 4 +Filter Events +.XS +\*(SN Filter Events +.XE +.LP +.IN "XNFilterEvents" "" "@DEF@" +The +.PN XNFilterEvents +argument returns the event mask that an input method needs +to have selected for. +The client is expected to augment its own event mask +for the client window with this one. +.LP +This argument is read-only, is set by the input method at create time, +and is never changed. +.LP +The type of this argument is +.PN unsigned +.PN long . +Setting this value will cause an error. +.NH 4 +Destroy Callback +.XS +\*(SN Destroy Callback +.XE +.LP +The +.PN XNDestroyCallback +argument is a pointer to a structure of type +.PN XIMCallback +(see section 13.5.6.13.12). This callback is triggered when the input method +stops its service for any reason; for example, when a connection to an IM +server is broken. After the destroy callback is called, +the input context is destroyed and the input method is closed. +Therefore, the client should not call +.PN XDestroyIC +and +.PN XCloseIM . +.LP +.NH 4 +String Conversion Callback +.XS +\*(SN String Conversion Callback +.XE +.LP +The +.PN XNStringConversionCallback +argument is a structure of type +.PN XIMCallback +(see section 13.5.6.13.12). +.LP +The +.PN XNStringConversionCallback +argument specifies a string conversion callback. This callback +is not required for correct operation of +either the input method or the client. It can be set by a client +to support string conversions that may be requested +by the input method. An input method that does string conversions +will filter any events that it uses to initiate the conversion. +.LP +Because this XIC value is optional, a client should call +.PN XGetIMValues +with argument +.PN XNQueryICValuesList +before using this argument. +.LP +.NH 4 +String Conversion +.XS +\*(SN String Conversion +.XE +.LP +The +.PN XNStringConversion +argument is a structure of type +.PN XIMStringConversionText . +.LP +The +.PN XNStringConversion +argument specifies the string to be converted by an input method. +This argument is not required for correct operation of either +the input method or the client. +.LP +String conversion facilitates the manipulation of text independent +of preediting. +It is essential for some input methods and clients to manipulate +text by performing context-sensitive conversion, +reconversion, or transliteration conversion on it. +.LP +Because this XIC value is optional, a client should call +.PN XGetIMValues +with argument +.PN XNQueryICValuesList +before using this argument. +.LP +The +.PN XIMStringConversionText +structure is defined as follows: +.LP +.sM +.Ds 0 + +typedef struct _XIMStringConversionText { + unsigned short length; + XIMStringConversionFeedback *feedback; + Bool encoding_is_wchar; + union { + char *mbs; + wchar_t *wcs; + } string; +} XIMStringConversionText; + +typedef unsigned long XIMStringConversionFeedback; +.De +.LP +.eM +The feedback member is reserved for future use. The text to be +converted is defined by the string and length members. The length +is indicated in characters. To prevent the library from freeing memory +pointed to by an uninitialized pointer, the client should set the feedback +element to NULL. +.LP +.NH 4 +Reset State +.XS +\*(SN Reset State +.XE +.LP +The +.PN XNResetState +argument specifies the state the input context will return to after calling +.PN XmbResetIC +or +.PN XwcResetIC . +.LP +The XIC state may be set to its initial state, as specified by the +.PN XNPreeditState +value when +.PN XCreateIC +was called, or it may be set to preserve the current state. +.LP +The valid masks for +.PN XIMResetState +are as follows: +.LP +.IN "XIMInitialState" "" "@DEF@" +.IN "XINPreserveState" "" "@DEF@" +.sM +.LP +.Ds 0 +typedef unsigned long XIMResetState; +.De +.TS +lw(.5i) lw(2i) lw(2i). +T{ +#define +T} T{ +.PN XIMInitialState +T} T{ +(1L) +T} +T{ +#define +T} T{ +.PN XIMPreserveState +T} T{ +(1L<<1) +T} +.TE +.LP +.eM +If +.PN XIMInitialState +is set, then +.PN XmbResetIC +and +.PN XwcResetIC +will return to the initial +.PN XNPreeditState +state of the XIC. +.LP +If +.PN XIMPreserveState +is set, then +.PN XmbResetIC +and +.PN XwcResetIC +will preserve the current state of the XIC. +.LP +If +.PN XNResetState +is left unspecified, the default is +.PN XIMInitialState . +.LP +.PN XIMResetState +values other than those specified above will default to +.PN XIMInitialState . +.LP +Because this XIC value is optional, a client should call +.PN XGetIMValues +with argument +.PN XNQueryICValuesList +before using this argument. +.LP +.NH 4 +Hot Keys +.XS +\*(SN Hot Keys +.XE +.LP +The +.PN XNHotKey +argument specifies the hot key list to the XIC. +The hot key list is a pointer to the structure of type +.PN XIMHotKeyTriggers , +which specifies the key events that must be received +without any interruption of the input method. +For the hot key list set with this argument to be utilized, the client +must also set +.PN XNHotKeyState +to +.PN XIMHotKeyStateON . +.LP +Because this XIC value is optional, a client should call +.PN XGetIMValues +with argument +.PN XNQueryICValuesList +before using this functionality. +.LP +The value of the argument is a pointer to a structure of type +.PN XIMHotKeyTriggers . +.LP +If an event for a key in the hot key list is found, then the process will +receive the event and it will be processed inside the client. +.LP +.sM +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef struct { + KeySym keysym; + unsigned int modifier; + unsigned int modifier_mask; +} XIMHotKeyTrigger; + +typedef struct { + int num_hot_key; + XIMHotKeyTrigger *key; +} XIMHotKeyTriggers; +.De +.LP +.eM +.LP +The combination of modifier and modifier_mask are used to represent one of +three states for each modifier: +either the modifier must be on, or the modifier must be off, or the modifier +is a ``don't care'' \- it may be on or off. +When a modifier_mask bit is set to 0, the state of the associated modifier +is ignored when evaluating whether the key is hot or not. +.TS H +lw(1i) lw(1i) lw(3i). +_ +.sp 6p +.B +Modifier Bit Mask Bit Meaning +.sp 6p +_ +.sp 6p +.TH +.R +T{ +0 +T} T{ +1 +T} T{ +The modifier must be off. +T} +T{ +1 +T} T{ +1 +T} T{ +The modifier must be on. +T} +T{ +n/a +T} T{ +0 +T} T{ +Do not care if the modifier is on or off. +T} +.sp 6p +_ +.TE +.NH 4 +Hot Key State +.XS +\*(SN Hot Key State +.XE +.LP +The +.PN XNHotKeyState +argument specifies the hot key state of the input method. +This is usually used to switch the input method between hot key +operation and normal input processing. +.LP +The value of the argument is a pointer to a structure of type +XIMHotKeyState . +.LP +.sM +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef unsigned long XIMHotKeyState; +.De +.TS +lw(.5i) lw(3i) lw(2i). +T{ +#define +T} T{ +.PN XIMHotKeyStateON +T} T{ +(0x0001L) +T} +T{ +#define +T} T{ +.PN XIMHotKeyStateOFF +T} T{ +(0x0002L) +T} +.TE +.LP +.eM +.LP +If not specified, the default is +.PN XIMHotKeyStateOFF . +.LP +.NH 4 +Preedit and Status Attributes +.XS +\*(SN Preedit and Status Attributes +.XE +.LP +.IN "XNPreeditAttributes" "" "@DEF@" +.IN "XNStatusAttributes" "" "@DEF@" +The +.PN XNPreeditAttributes +and +.PN XNStatusAttributes +arguments specify to an input method the attributes to be used for the +preedit and status areas, +if any. +Those attributes are passed to +.PN XSetICValues +or +.PN XGetICValues +as a nested variable-length list. +The names to be used in these lists are described in the following sections. +.NH 5 +Area +.XS +\*(SN Area +.XE +.LP +.IN "XNArea" "" "@DEF@" +The value of the +.PN XNArea +argument must be a pointer to a structure of type +.PN XRectangle. +The interpretation of the +.PN XNArea +argument is dependent on the input method style that has been set. +.LP +If the input method style is +.PN XIMPreeditPosition , +.PN XNArea +specifies the clipping region within which preediting will take place. +If the focus window has been set, +the coordinates are assumed to be relative to the focus window. +Otherwise, the coordinates are assumed to be relative to the client window. +If neither has been set, +the results are undefined. +.LP +If +.PN XNArea +is not specified, is set to NULL, or is invalid, +the input method will default the clipping region +to the geometry of the +.PN XNFocusWindow . +If the area specified is NULL or invalid, +the results are undefined. +.LP +If the input style is +.PN XIMPreeditArea +or +.PN XIMStatusArea , +.PN XNArea +specifies the geometry provided by the client to the input method. +The input method may use this area to display its data, +either preedit or status depending on the area designated. +The input method may create a window as a child of the client window +with dimensions that fit the +.PN XNArea . +The coordinates are relative to the client window. +If the client window has not been set yet, +the input method should save these values +and apply them when the client window is set. +If +.PN XNArea +is not specified, is set to NULL, or is invalid, +the results are undefined. +.NH 5 +Area Needed +.XS +\*(SN Area Needed +.XE +.LP +.IN "XNAreaNeeded" "" "@DEF@" +When set, the +.PN XNAreaNeeded +argument specifies the geometry suggested by the client for this area +(preedit or status). +The value associated with the argument must be a pointer to a +structure of type +.PN XRectangle . +Note that the x, y values are not used +and that nonzero values for width or height are the constraints +that the client wishes the input method to respect. +.LP +When read, the +.PN XNAreaNeeded +argument specifies the preferred geometry desired by the input method +for the area. +.LP +This argument is only valid if the input style is +.PN XIMPreeditArea +or +.PN XIMStatusArea . +It is used for geometry negotiation between the client and the input method +and has no other effect on the input method +(see section 13.5.1.5). +.NH 5 +Spot Location +.XS +\*(SN Spot Location +.XE +.LP +.IN "XNSpotLocation" "" "@DEF@" +The +.PN XNSpotLocation +argument specifies to the input method the coordinates of the spot +to be used by an input method executing with +.PN XNInputStyle +set to +.PN XIMPreeditPosition . +When specified to any input method other than +.PN XIMPreeditPosition , +this XIC value is ignored. +.LP +The x coordinate specifies the position where the next character +would be inserted. +The y coordinate is the position of the baseline used +by the current text line in the focus window. +The x and y coordinates are relative to the focus window, if it has been set; +otherwise, they are relative to the client window. +If neither the focus window nor the client window has been set, +the results are undefined. +.LP +The value of the argument is a pointer to a structure of type +.PN XPoint . +.NH 5 +Colormap +.XS +\*(SN Colormap +.XE +.LP +Two different arguments can be used to indicate what colormap the input method +should use to allocate colors, a colormap ID, or a standard colormap name. +.LP +.IN "XNColormap" "" "@DEF@" +The +.PN XNColormap +argument is used to specify a colormap ID. +The argument value is of type +.PN Colormap . +An invalid argument may generate a +.PN BadColor +error when it is used by the input method. +.LP +.IN "XNStdColormap" "" "@DEF@" +The +.PN XNStdColormap +argument is used to indicate the name of the standard colormap +in which the input method should allocate colors. +The argument value is an +.PN Atom +that should be a valid atom for calling +.PN XGetRGBColormaps . +An invalid argument may generate a +.PN BadAtom +error when it is used by the input method. +.LP +If the colormap is left unspecified, +the client window colormap becomes the default. +.NH 5 +Foreground and Background +.XS +\*(SN Foreground and Background +.XE +.LP +.IN "XNForeground" "" "@DEF@" +.IN "XNBackground" "" "@DEF@" +The +.PN XNForeground +and +.PN XNBackground +arguments specify the foreground and background pixel, respectively. +The argument value is of type +.PN unsigned +.PN long . +It must be a valid pixel in the input method colormap. +.LP +If these values are left unspecified, +the default is determined by the input method. +.NH 5 +Background Pixmap +.XS +\*(SN Background Pixmap +.XE +.LP +The +.PN XNBackgroundPixmap +argument specifies a background pixmap to be used as the background of the +window. +The value must be of type +.PN Pixmap . +An invalid argument may generate a +.PN BadPixmap +error when it is used by the input method. +.LP +If this value is left unspecified, +the default is determined by the input method. +.NH 5 +Font Set +.XS +\*(SN Font Set +.XE +.LP +.IN "XNFontSet" "" "@DEF@" +The +.PN XNFontSet +argument specifies to the input method what font set is to be used. +The argument value is of type +.PN XFontSet . +.LP +If this value is left unspecified, +the default is determined by the input method. +.NH 5 +Line Spacing +.XS +\*(SN Line Spacing +.XE +.LP +The +.PN XNLineSpace +argument specifies to the input method what line spacing is to be used +in the preedit window if more than one line is to be used. +This argument is of type +.PN int . +.LP +If this value is left unspecified, +the default is determined by the input method. +.NH 5 +Cursor +.XS +\*(SN Cursor +.XE +.LP +.IN "XNCursor" "" "DEF@" +The +.PN XNCursor +argument specifies to the input method what cursor is to be used +in the specified window. +This argument is of type +.PN Cursor . +.LP +An invalid argument may generate a +.PN BadCursor +error when it is used by the input method. +If this value is left unspecified, +the default is determined by the input method. +.NH 5 +Preedit State +.XS +\*(SN Preedit State +.XE +.LP +The +.PN XNPreeditState +argument specifies the state of input preediting for the input method. +Input preediting can be on or off. +.LP +The valid mask names for +.PN XNPreeditState +are as follows: +.LP +.IN "XIMPreeditUnknown" "" "@DEV@" +.IN "XIMPreeditEnable" "" "@DEF@" +.IN "XIMPreeditDisable" "" "@DEV@" +.sM +.LP +.Ds 0 +typedef unsigned long XIMPreeditState; +.De +.TS +lw(.5i) lw(2i) lw(2i). +T{ +#define +T} T{ +.PN XIMPreeditUnknown +T} T{ +0L +T} +T{ +#define +T} T{ +.PN XIMPreeditEnable +T} T{ +1L +T} +T{ +#define +T} T{ +.PN XIMPreeditDisable +T} T{ +(1L<<1) +T} +.TE +.LP +.eM +If a value of +.PN XIMPreeditEnable +is set, then input preediting is turned on by the input method. +.LP +If a value of +.PN XIMPreeditDisable +is set, then input preediting is turned off by the input method. +.LP +If +.PN XNPreeditState +is left unspecified, then the state will be implementation-dependent. +.LP +When +.PN XNResetState +is set to +.PN XIMInitialState , +the +.PN XNPreeditState +value specified at the creation time will be reflected as the initial state for +.PN XmbResetIC +and +.PN XwcResetIC . +.LP +Because this XIC value is optional, a client should call +.PN XGetIMValues +with argument +.PN XNQueryICValuesList +before using this argument. +.NH 5 +Preedit State Notify Callback +.XS +\*(SN Preedit State Notify Callback +.XE +.LP +The preedit state notify callback is triggered by the input method +when the preediting state has changed. +The value of the +.PN XNPreeditStateNotifyCallback +argument is a pointer to a structure of type +.PN XIMCallback . +The generic prototype is as follows: +.IN "PreeditStateNotifyCallback" "" "@DEF@" +.sM +.FD 0 +void PreeditStateNotifyCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^) +.br + XIC \fIic\fP\^; +.br + XPointer \fIclient_data\fP\^; +.br + XIMPreeditStateNotifyCallbackStruct *\fIcall_data\fP\^; +.FN +.IP \fIic\fP 1i +Specifies the input context. +.IP \fIclient_data\fP 1i +Specifies the additional client data. +.IP \fIcall_data\fP 1i +Specifies the current preedit state. +.LP +.eM +The +.PN XIMPreeditStateNotifyCallbackStruct +structure is defined as follows: +.LP +.IN "XIMPreeditStateNotifyCallbackStruct" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef struct _XIMPreeditStateNotifyCallbackStruct { + XIMPreeditState state; +} XIMPreeditStateNotifyCallbackStruct; +.De +.LP +.eM +.LP +Because this XIC value is optional, a client should call +.PN XGetIMValues +with argument +.PN XNQueryICValuesList +before using this argument. +.NH 5 +Preedit and Status Callbacks +.XS +\*(SN Preedit and Status Callbacks +.XE +.LP +A client that wants to support the input style +.PN XIMPreeditCallbacks +must provide a set of preedit callbacks to the input method. +The set of preedit callbacks is as follows: +.IN "XNPreeditStartCallback" "" "@DEF@" +.IN "XNPreeditDoneCallback" "" "@DEF@" +.IN "XNPreeditDrawCallback" "" "@DEF@" +.IN "XNPreeditCaretCallback" "" "@DEF@" +.TS +lw(1.75i) lw(4i). +T{ +.PN XNPreeditStartCallback +T} T{ +This is called when the input method starts preedit. +T} +T{ +.PN XNPreeditDoneCallback +T} T{ +This is called when the input method stops preedit. +T} +T{ +.PN XNPreeditDrawCallback +T} T{ +This is called when a number of preedit keystrokes should be echoed. +T} +T{ +.PN XNPreeditCaretCallback +T} T{ +This is called to move the text insertion point within the preedit string. +T} +.TE +.LP +A client that wants to support the input style +.PN XIMStatusCallbacks +must provide a set of status callbacks to the input method. +The set of status callbacks is as follows: +.IN "XNStatusStartCallback" "" "@DEF@" +.IN "XNStatusDoneCallback" "" "@DEF@" +.IN "XNStatusDrawCallback" "" "@DEF@" +.TS +lw(1.75i) lw(4i). +T{ +.PN XNStatusStartCallback +T} T{ +This is called when the input method initializes the status area. +T} +T{ +.PN XNStatusDoneCallback +T} T{ +This is called when the input method no longer needs the status area. +T} +T{ +.PN XNStatusDrawCallback +T} T{ +This is called when updating of the status area is required. +T} +.TE +.LP +The value of any status or preedit argument is a pointer +to a structure of type +.PN XIMCallback . +.IN "XIMProc" "" "@DEF@" +.IN "XIMCallback" "" "@DEF@" +.sM +.LP +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef void (*XIMProc)(); + +typedef struct { + XPointer client_data; + XIMProc callback; +} XIMCallback; +.De +.LP +.eM +Each callback has some particular semantics and will carry the data +that expresses the environment necessary to the client +into a specific data structure. +This paragraph only describes the arguments to be used to set +the callback. +.LP +Setting any of these values while doing preedit +may cause unexpected results. +.NH 3 +Input Method Callback Semantics +.XS +\*(SN Input Method Callback Semantics +.XE +.LP +XIM callbacks are procedures defined by clients or text drawing packages +that are to be called from the input method when selected events occur. +Most clients will use a text editing package or a toolkit +and, hence, will not need to define such callbacks. +This section defines the callback semantics, when they are triggered, +and what their arguments are. +This information is mostly useful for X toolkit implementors. +.LP +Callbacks are mostly provided so that clients (or text editing +packages) can implement on-the-spot preediting in their own window. +In that case, +the input method needs to communicate and synchronize with the client. +The input method needs to communicate changes in the preedit window +when it is under control of the client. +Those callbacks allow the client to initialize the preedit area, +display a new preedit string, +move the text insertion point during preedit, +terminate preedit, or update the status area. +.LP +All callback procedures follow the generic prototype: +.IN "CallbackPrototype" "" "@DEF@" +.sM +.FD 0 +void CallbackPrototype\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^) +.br + XIC \fIic\fP\^; +.br + XPointer \fIclient_data\fP\^; +.br + SomeType \fIcall_data\fP\^; +.FN +.IP \fIic\fP 1i +Specifies the input context. +.IP \fIclient_data\fP 1i +Specifies the additional client data. +.IP \fIcall_data\fP 1i +Specifies data specific to the callback. +.LP +.eM +The call_data argument is a structure that expresses the arguments needed +to achieve the semantics; +that is, +it is a specific data structure appropriate to the callback. +In cases where no data is needed in the callback, +this call_data argument is NULL. +The client_data argument is a closure that has been initially specified +by the client when specifying the callback and passed back. +It may serve, for example, to inherit application context in the callback. +.LP +The following paragraphs describe the programming semantics +and specific data structure associated with the different reasons. +.NH 4 +Geometry Callback +.XS +\*(SN Geometry Callback +.XE +.LP +The geometry callback is triggered by the input method +to indicate that it wants the client to negotiate geometry. +The generic prototype is as follows: +.IN "GeometryCallback" "" "@DEF@" +.sM +.FD 0 +void GeometryCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^) +.br + XIC \fIic\fP\^; +.br + XPointer \fIclient_data\fP\^; +.br + XPointer \fIcall_data\fP\^; +.FN +.IP \fIic\fP 1i +Specifies the input context. +.IP \fIclient_data\fP 1i +Specifies the additional client data. +.IP \fIcall_data\fP 1i +Not used for this callback and always passed as NULL. +.LP +.eM +The callback is called with a NULL call_data argument. +.NH 4 +Destroy Callback +.XS +\*(SN Destroy Callback +.XE +.LP +The destroy callback is triggered by the input method +when it stops service for any reason. +After the callback is invoked, the input context will be freed by Xlib. +The generic prototype is as follows: +.IN "DestroyCallback" "" "@DEF@" +.sM +.FD 0 +void DestroyCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^) +.br + XIC \fIic\fP\^; +.br + XPointer \fIclient_data\fP\^; +.br + XPointer \fIcall_data\fP\^; +.FN +.IP \fIic\fP 1i +Specifies the input context. +.IP \fIclient_data\fP 1i +Specifies the additional client data. +.IP \fIcall_data\fP 1i +Not used for this callback and always passed as NULL. +.LP +.eM +The callback is called with a NULL call_data argument. +.NH 4 +String Conversion Callback +.XS +\*(SN String Conversion Callback +.XE +.LP +The string conversion callback is triggered by the input method +to request the client to return the string to be converted. The +returned string may be either a multibyte or wide character string, +with an encoding matching the locale bound to the input context. +The callback prototype is as follows: +.IN "StringConversionCallback" "" "@DEF@" +.sM +.FD 0 +void StringConversionCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^) +.br + XIC \fIic\fP\^; +.br + XPointer \fIclient_data\fP\^; +.br + XIMStringConversionCallbackStruct *\fIcall_data\fP\^; +.FN +.IP \fIic\fP 1i +Specifies the input method. +.IP \fIclient_data\fP 1i +Specifies the additional client data. +.IP \fIcall_data\fP 1i +Specifies the amount of the string to be converted. +.LP +.eM +The callback is passed an +.PN XIMStringConversionCallbackStruct +structure in the call_data argument. +The text member is an +.PN XIMStringConversionText +structure (see section 13.5.6.9) to be filled in by the client +and describes the text to be sent to the input method. +The data pointed to by the +string and feedback elements of the +.PN XIMStringConversionText +structure will be freed using +.PN XFree +by the input method +after the callback returns. So the client should not point to +internal buffers that are critical to the client. +Similarly, because the feedback element is currently reserved for future +use, the client should set feedback to NULL to prevent the library from +freeing memory at some random location due to an uninitialized pointer. +.LP +The +.PN XIMStringConversionCallbackStruct +structure is defined as follows: +.LP +.IN "XIMStringConversionCallbackStruct" "" "@DEF@" +.sM +.LP +.Ds 0 +typedef struct _XIMStringConversionCallbackStruct { + XIMStringConversionPosition position; + XIMCaretDirection direction; + short factor; + XIMStringConversionOperation operation; + XIMStringConversionText *text; +} XIMStringConversionCallbackStruct; + +typedef short XIMStringConversionPosition; + +typedef unsigned short XIMStringConversionOperation; + +.De +.LP +.TS +lw(.5i) lw(3i) lw(2i). +T{ +#define +T} T{ +.PN XIMStringConversionSubstitution +T} T{ +(0x0001) +T} +T{ +#define +T} T{ +.PN XIMStringConversionRetrieval +T} T{ +(0x0002) +T} +.TE +.LP +.eM +.PN XIMStringConversionPosition +specifies the starting position of the string to be returned +in the +.PN XIMStringConversionText +structure. The value identifies a position, in units of characters, +relative to the client's cursor position in the client's buffer. +.LP +The ending position of the text buffer is determined by +the direction and factor members. Specifically, it is the character position +relative to the starting point as defined by the +.PN XIMCaretDirection . +The factor member of +.PN XIMStringConversionCallbackStruct +specifies the number of +.PN XIMCaretDirection +positions to be applied. For example, if the direction specifies +.PN XIMLineEnd +and factor is 1, then all characters from the starting position to +the end of the current display line are returned. If the direction +specifies +.PN XIMForwardChar +or +.PN XIMBackwardChar , +then the factor specifies a relative position, indicated in characters, +from the starting position. +.LP +.PN XIMStringConversionOperation +specifies whether the string to be converted should be +deleted (substitution) or copied (retrieval) from the client's +buffer. When the +.PN XIMStringConversionOperation +is +.PN XIMStringConversionSubstitution , +the client must delete the string to be converted from its own buffer. +When the +.PN XIMStringConversionOperation +is +.PN XIMStringConversionRetrieval , +the client must not delete the string to be converted from its buffer. +The substitute operation is typically used for reconversion and +transliteration conversion, +while the retrieval operation is typically used for context-sensitive +conversion. +.NH 4 +Preedit State Callbacks +.XS +\*(SN Preedit State Callbacks +.XE +.LP +When the input method turns preediting on or off, a +.PN PreeditStartCallback +or +.PN PreeditDoneCallback +callback is triggered to let the toolkit do the setup +or the cleanup for the preedit region. +.IN "PreeditStartCallback" "" "@DEF@" +.sM +.FD 0 +int PreeditStartCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^) +.br + XIC \fIic\fP\^; +.br + XPointer \fIclient_data\fP\^; +.br + XPointer \fIcall_data\fP\^; +.FN +.IP \fIic\fP 1i +Specifies the input context. +.IP \fIclient_data\fP 1i +Specifies the additional client data. +.IP \fIcall_data\fP 1i +Not used for this callback and always passed as NULL. +.LP +.eM +When preedit starts on the specified input context, +the callback is called with a NULL call_data argument. +.PN PreeditStartCallback +will return the maximum size of the preedit string. +A positive number indicates the maximum number of bytes allowed +in the preedit string, +and a value of \-1 indicates there is no limit. +.IN "PreeditDoneCallback" "" "@DEF@" +.sM +.FD 0 +void PreeditDoneCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^) +.br + XIC \fIic\fP\^; +.br + XPointer \fIclient_data\fP\^; +.br + XPointer \fIcall_data\fP\^; +.FN +.IP \fIic\fP 1i +Specifies the input context. +.IP \fIclient_data\fP 1i +Specifies the additional client data. +.IP \fIcall_data\fP 1i +Not used for this callback and always passed as NULL. +.LP +.eM +When preedit stops on the specified input context, +the callback is called with a NULL call_data argument. +The client can release the data allocated by +.PN PreeditStartCallback . +.LP +.PN PreeditStartCallback +should initialize appropriate data needed for +displaying preedit information and for handling further +.PN PreeditDrawCallback +calls. +Once +.PN PreeditStartCallback +is called, it will not be called again before +.PN PreeditDoneCallback +has been called. +.NH 4 +Preedit Draw Callback +.XS +\*(SN Preedit Draw Callback +.XE +.LP +This callback is triggered to draw and insert, delete or replace, +preedit text in the preedit region. +The preedit text may include unconverted input text such as Japanese Kana, +converted text such as Japanese Kanji characters, or characters of both kinds. +That string is either a multibyte or wide character string, +whose encoding matches the locale bound to the input context. +The callback prototype +is as follows: +.IN "PreeditDrawCallback" "" "@DEF@" +.sM +.FD 0 +void PreeditDrawCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^) +.br + XIC \fIic\fP\^; +.br + XPointer \fIclient_data\fP\^; +.br + XIMPreeditDrawCallbackStruct *\fIcall_data\fP\^; +.FN +.IP \fIic\fP 1i +Specifies the input context. +.IP \fIclient_data\fP 1i +Specifies the additional client data. +.IP \fIcall_data\fP 1i +Specifies the preedit drawing information. +.LP +.eM +The callback is passed an +.PN XIMPreeditDrawCallbackStruct +structure in the call_data argument. +The text member of this structure contains the text to be drawn. +After the string has been drawn, +the caret should be moved to the specified location. +.LP +The +.PN XIMPreeditDrawCallbackStruct +structure is defined as follows: +.LP +.IN "XIMPreeditDrawCallbackStruct" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef struct _XIMPreeditDrawCallbackStruct { + int caret; /* Cursor offset within preedit string */ + int chg_first; /* Starting change position */ + int chg_length; /* Length of the change in character count */ + XIMText *text; +} XIMPreeditDrawCallbackStruct; +.De +.LP +.eM +The client must keep updating a buffer of the preedit text +and the callback arguments referring to indexes in that buffer. +The call_data fields have specific meanings according to the operation, +as follows: +.IP \(bu 5 +To indicate text deletion, +the call_data member specifies a NULL text field. +The text to be deleted is then the current text in the buffer +from position chg_first (starting at zero) on a character length +of chg_length. +.IP \(bu 5 +When text is non-NULL, +it indicates insertion or replacement of text in the buffer. +.IP +The chg_length member +identifies the number of characters in the current preedit buffer +that are affected by this call. +A positive chg_length indicates that chg_length number of characters, starting +at chg_first, must be deleted or must be replaced by text, whose length is +specified in the +.PN XIMText +structure. +.IP +A chg_length value of zero indicates that text must be inserted +right at the position specified by chg_first. +A value of zero for chg_first specifies the first character in the buffer. +.IP +chg_length and chg_first combine to identify the modification required to +the preedit buffer; beginning at chg_first, replace chg_length number of +characters with the text in the supplied +.PN XIMText +structure. For example, suppose the preedit buffer contains the string "ABCDE". +.IP +.DS I +.ft C +Text: A B C D E + ^ ^ ^ ^ ^ ^ +CharPos: 0 1 2 3 4 5 +.sp +.ft P +.DE +The CharPos in the diagram shows the location of the character position +relative to the character. +.IP +If the value of chg_first is 1 and the value of chg_length is 3, this +says to replace 3 characters beginning at character position 1 with the +string in the +.PN XIMText +structure. +Hence, BCD would be replaced by the value in the structure. +.IP +Though chg_length and chg_first are both signed integers they will +never have a negative value. +.IP \(bu 5 +The caret member +identifies the character position before which the cursor should +be placed \- after modification to the preedit buffer has been completed. +For example, if caret is zero, the cursor is at +the beginning of the buffer. If the caret is one, the cursor is between +the first and second character. +.LP +.IN "XIMText" "" @DEF@" +.sM +.Ds +.TA .5i 1.5i 3i +typedef struct _XIMText { + unsigned short length; + XIMFeedback * feedback; + Bool encoding_is_wchar; + union { + char * multi_byte; + wchar_t * wide_char; + } string; +} XIMText; +.De +.LP +.eM +The text string passed is actually a structure specifying as follows: +.IP \(bu 5 +The length member is the text length in characters. +.IP \(bu 5 +The encoding_is_wchar member is a value that indicates +if the text string is encoded in wide character or multibyte format. +The text string may be passed either as multibyte or as wide character; +the input method controls in which form data is passed. +The client's +callback routine must be able to handle data passed in either form. +.IP \(bu 5 +The string member is the text string. +.IP \(bu 5 +The feedback member indicates rendering type for each character in the +string member. +If string is NULL (indicating that only highlighting of the existing +preedit buffer should be updated), feedback points to length highlight +elements that should be applied to the existing preedit buffer, beginning +at chg_first. +.LP +The feedback member expresses the types of rendering feedback +the callback should apply when drawing text. +Rendering of the text to be drawn is specified either in generic ways +(for example, primary, secondary) or in specific ways (reverse, underline). +When generic indications are given, +the client is free to choose the rendering style. +It is necessary, however, that primary and secondary be mapped +to two distinct rendering styles. +.LP +If an input method wants to control display of the preedit string, an +input method can indicate the visibility hints using feedbacks in +a specific way. +The +.PN XIMVisibleToForward , +.PN XIMVisibleToBackward , +and +.PN XIMVisibleCenter +masks are exclusively used for these visibility hints. +The +.PN XIMVisibleToForward +mask +indicates that the preedit text is preferably displayed in the +primary draw direction from the +caret position in the preedit area forward. +The +.PN XIMVisibleToBackward +mask +indicates that the preedit text is preferably displayed from +the caret position in the preedit area backward, relative to the primary +draw direction. +The +.PN XIMVisibleCenter +mask +indicates that the preedit text is preferably displayed with +the caret position in the preedit area centered. +.LP +The insertion point of the preedit string could exist outside of +the visible area when visibility hints are used. +Only one of the +masks +is valid for the entire preedit string, and only one character +can hold one of these feedbacks for a given input context at one time. +This feedback may be OR'ed together with another highlight (such as +.PN XIMReverse ). +Only the most recently set feedback is valid, and any previous +feedback is automatically canceled. This is a hint to the client, and +the client is free to choose how to display the preedit string. +.LP +The feedback member also specifies how rendering of the text argument +should be performed. +If the feedback is NULL, +the callback should apply the same feedback as is used for the surrounding +characters in the preedit buffer; if chg_first is at a highlight boundary, +the client can choose which of the two highlights to use. +If feedback is not NULL, feedback specifies an array defining the +rendering for each +character of the string, and the length of the array is thus length. +.LP +If an input method wants to indicate that it is only updating the feedback of +the preedit text without changing the content of it, +the +.PN XIMText +structure will contain a NULL value for the string field, +the number of characters affected (relative to chg_first) +will be in the length field, +and the feedback field will point to an array of +.PN XIMFeedback . +.LP +Each element in the feedback array is a bitmask represented by a value of type +.PN XIMFeedback . +The valid mask names are as follows: +.LP +.IN "XIMReverse" "" "@DEF@" +.IN "XIMUnderline" "" "@DEF@" +.IN "XIMHighlight" "" "@DEF@" +.IN "XIMPrimary" "" "@DEF@" +.IN "XIMSecondary" "" "@DEF@" +.IN "XIMTertiary" "" "@DEF@" +.IN "XIMVisibleToForward" "" "@DEF@" +.IN "XIMVisibleToBackward" "" "@DEF@" +.IN "XIMVisibleCenter" "" "@DEF@" +.sM +.LP +.Ds 0 +typedef unsigned long XIMFeedback; +.De +.TS +lw(.5i) lw(2i) lw(2i). +T{ +#define +T} T{ +.PN XIMReverse +T} T{ +1L +T} +T{ +#define +T} T{ +.PN XIMUnderline +T} T{ +(1L<<1) +T} +T{ +#define +T} T{ +.PN XIMHighlight +T} T{ +(1L<<2) +T} +T{ +#define +T} T{ +.PN XIMPrimary +T} T{ +(1L<<5)\(dg +T} +T{ +#define +T} T{ +.PN XIMSecondary +T} T{ +(1L<<6)\(dg +T} +T{ +#define +T} T{ +.PN XIMTertiary +T} T{ +(1L<<7)\(dg +T} +T{ +#define +T} T{ +.PN XIMVisibleToForward +T} T{ +(1L<<8) +T} +T{ +#define +T} T{ +.PN XIMVisibleToBackward +T} T{ +(1L<<9) +T} +T{ +#define +T} T{ +.PN XIMVisibleCenter +T} T{ +(1L<<10) +T} +.TE +.LP +.eM +.LP +Characters drawn with the +.PN XIMReverse +highlight should be drawn by swapping the foreground and background colors +used to draw normal, unhighlighted characters. +Characters drawn with the +.PN XIMUnderline +highlight should be underlined. +Characters drawn with the +.PN XIMHighlight , +.PN XIMPrimary , +.PN XIMSecondary , +and +.PN XIMTertiary +highlights should be drawn in some unique manner that must be different +from +.PN XIMReverse +and +.PN XIMUnderline . +.FS \(dg +The values for +.PN XIMPrimary , +.PN XIMSecondary , +and +.PN XIMTertiary +were incorrectly defined in the R5 specification. +The X Consortium's X11R5 +implementation correctly implemented the values for these highlights. +The value of these highlights has been corrected in this specification +to agree with the values in the Consortium's X11R5 and X11R6 implementations. +.FE +.NH 4 +Preedit Caret Callback +.XS +\*(SN Preedit Caret Callback +.XE +.LP +An input method may have its own navigation keys to allow the user +to move the text insertion point in the preedit area +(for example, to move backward or forward). +Consequently, input method needs to indicate to the client that it +should move the text insertion point. +It then calls the PreeditCaretCallback. +.IN "PreeditCaretCallback" "" "@DEF@" +.sM +.FD 0 +void PreeditCaretCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^) +.br + XIC \fIic\fP\^; +.br + XPointer \fIclient_data\fP\^; +.br + XIMPreeditCaretCallbackStruct *\fIcall_data\fP\^; +.FN +.IP \fIic\fP 1i +Specifies the input context. +.IP \fIclient_data\fP 1i +Specifies the additional client data. +.IP \fIcall_data\fP 1i +Specifies the preedit caret information. +.LP +.eM +The input method will trigger PreeditCaretCallback +to move the text insertion point during preedit. +The call_data argument contains a pointer to an +.PN XIMPreeditCaretCallbackStruct +structure, +which indicates where the caret should be moved. +The callback must move the insertion point to its new location +and return, in field position, the new offset value from the initial position. +.LP +The +.PN XIMPreeditCaretCallbackStruct +structure is defined as follows: +.IN "XIMPreeditCaretCallbackStruct" "" "@DEF@" +.LP +.sM +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef struct _XIMPreeditCaretCallbackStruct { + int position; /* Caret offset within preedit string */ + XIMCaretDirection direction; /* Caret moves direction */ + XIMCaretStyle style; /* Feedback of the caret */ +} XIMPreeditCaretCallbackStruct; +.De +.LP +.eM +The +.PN XIMCaretStyle +structure is defined as follows: +.LP +.IN "XIMCaretStyle" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef enum { + XIMIsInvisible, /* Disable caret feedback */ + XIMIsPrimary, /* UI defined caret feedback */ + XIMIsSecondary, /* UI defined caret feedback */ +} XIMCaretStyle; +.De +.LP +.eM +The +.PN XIMCaretDirection +structure is defined as follows: +.IN "XIMCaretDirection" "" "@DEF@" +.LP +.sM +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef enum { + XIMForwardChar, XIMBackwardChar, + XIMForwardWord, XIMBackwardWord, + XIMCaretUp, XIMCaretDown, + XIMNextLine, XIMPreviousLine, + XIMLineStart, XIMLineEnd, + XIMAbsolutePosition, + XIMDontChange, + } XIMCaretDirection; +.De +.LP +.eM +These values are defined as follows: +.IN "XIMForwardChar" "" "@DEF@" +.IN "XIMBackwardChar" "" "@DEF@" +.IN "XIMForwardWord" "" "@DEF@" +.IN "XIMBackwardWord" "" "@DEF@" +.IN "XIMCaretUp" "" "@DEF@" +.IN "XIMCaretDown" "" "@DEF@" +.TS +lw(1.5i) lw(4.25i). +T{ +.PN XIMForwardChar +T} T{ +Move the caret forward one character position. +T} +T{ +.PN XIMBackwardChar +T} T{ +Move the caret backward one character position. +T} +T{ +.PN XIMForwardWord +T} T{ +Move the caret forward one word. +T} +T{ +.PN XIMBackwardWord +T} T{ +Move the caret backward one word. +T} +T{ +.PN XIMCaretUp +T} T{ +Move the caret up one line keeping the current horizontal offset. +T} +T{ +.PN XIMCaretDown +T} T{ +Move the caret down one line keeping the current horizontal offset. +T} +T{ +.PN XIMPreviousLine +T} T{ +Move the caret to the beginning of the previous line. +T} +T{ +.PN XIMNextLine +T} T{ +Move the caret to the beginning of the next line. +T} +T{ +.PN XIMLineStart +T} T{ +Move the caret to the beginning of the current display line +that contains the caret. +T} +T{ +.PN XIMLineEnd +T} T{ +Move the caret to the end of the current display line +that contains the caret. +T} +T{ +.PN XIMAbsolutePosition +T} T{ +The callback must move to the location specified by the position field +of the callback data, indicated in characters, starting from the beginning +of the preedit text. +Hence, a value of zero means move back to the beginning of the preedit text. +T} +T{ +.PN XIMDontChange +T} T{ +The caret position does not change. +T} +.TE +.IN "XIMNextLine" "" "@DEF@" +.IN "XIMPreviousLine" "" "@DEF@" +.IN "XIMLineStart" "" "@DEF@" +.IN "XIMLineEnd" "" "@DEF@" +.IN "XIMAbsolutePosition" "" "@DEF@" +.IN "XIMDontChange" "" "@DEF@" +.NH 4 +Status Callbacks +.XS +\*(SN Status Callbacks +.XE +.LP +An input method may communicate changes in the status of an input context +(for example, created, destroyed, or focus changes) with three status +callbacks: StatusStartCallback, StatusDoneCallback, and StatusDrawCallback. +.LP +.sp +When the input context is created or gains focus, +the input method calls the StatusStartCallback callback. +.IN "StatusStartCallback" "" "@DEF@" +.sM +.FD 0 +void StatusStartCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^) +.br + XIC \fIic\fP\^; +.br + XPointer \fIclient_data\fP\^; +.br + XPointer \fIcall_data\fP\^; +.FN +.IP \fIic\fP 1i +Specifies the input context. +.IP \fIclient_data\fP 1i +Specifies the additional client data. +.IP \fIcall_data\fP 1i +Not used for this callback and always passed as NULL. +.LP +.eM +The callback should initialize appropriate data for displaying status +and for responding to StatusDrawCallback calls. +Once StatusStartCallback is called, +it will not be called again before StatusDoneCallback has been called. +.LP +.sp +When an input context +is destroyed or when it loses focus, the input method calls StatusDoneCallback. +.IN "StatusDoneCallback" "" "@DEF@" +.sM +.FD 0 +void StatusDoneCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^) +.br + XIC \fIic\fP\^; +.br + XPointer \fIclient_data\fP\^; +.br + XPointer \fIcall_data\fP\^; +.FN +.IP \fIic\fP 1i +Specifies the input context. +.IP \fIclient_data\fP 1i +Specifies the additional client data. +.IP \fIcall_data\fP 1i +Not used for this callback and always passed as NULL. +.LP +.eM +The callback may release any data allocated on +.PN StatusStart . +.LP +.sp +When an input context status has to be updated, the input method calls +StatusDrawCallback. +.IN "StatusDrawCallback" "" "@DEF@" +.sM +.FD 0 +void StatusDrawCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^) +.br + XIC \fIic\fP\^; +.br + XPointer \fIclient_data\fP\^; +.br + XIMStatusDrawCallbackStruct *\fIcall_data\fP\^; +.FN +.IP \fIic\fP 1i +Specifies the input context. +.IP \fIclient_data\fP 1i +Specifies the additional client data. +.IP \fIcall_data\fP 1i +Specifies the status drawing information. +.LP +.eM +The callback should update the status area by either drawing a string +or imaging a bitmap in the status area. +.LP +The +.PN XIMStatusDataType +and +.PN XIMStatusDrawCallbackStruct +structures are defined as follows: +.IN "XIMStatusDataType" "" "@DEF@" +.IN "XIMStatusDrawCallbackStruct" "" "@DEF@" +.LP +.sM +.Ds 0 +.TA .5i 1i 3i +.ta .5i 1i 3i +typedef enum { + XIMTextType, + XIMBitmapType, +} XIMStatusDataType; + +typedef struct _XIMStatusDrawCallbackStruct { + XIMStatusDataType type; + union { + XIMText *text; + Pixmap bitmap; + } data; +} XIMStatusDrawCallbackStruct; +.De +.LP +.eM +.LP +The feedback styles +.PN XIMVisibleToForward , +.PN XIMVisibleToBackward , +and +.PN XIMVisibleToCenter +are not relevant and will not appear in the +.PN XIMFeedback +element of the +.PN XIMText +structure. +.LP +.NH 3 +Event Filtering +.XS +\*(SN Event Filtering +.XE +.LP +Xlib provides the ability for an input method +to register a filter internal to Xlib. +This filter is called by a client (or toolkit) by calling +.PN XFilterEvent +after calling +.PN XNextEvent . +Any client that uses the +.PN XIM +interface should call +.PN XFilterEvent +to allow input methods to process their events without knowledge +of the client's dispatching mechanism. +A client's user interface policy may determine the priority +of event filters with respect to other event-handling mechanisms +(for example, modal grabs). +.LP +Clients may not know how many filters there are, if any, +and what they do. +They may only know if an event has been filtered on return of +.PN XFilterEvent . +Clients should discard filtered events. +.sp +.LP +To filter an event, use +.PN XFilterEvent . +.IN "XFilterEvent" "" "@DEF@" +.sM +.FD 0 +Bool XFilterEvent\^(\^\fIevent\fP\^, \fIw\fP\^) +.br + XEvent *\fIevent\fP\^; +.br + Window \fIw\fP\^; +.FN +.ds Ev event to filter +.IP \fIevent\fP 1i +Specifies the \*(Ev. +.ds Wi for which the filter is to be applied +.IP \fIw\fP 1i +Specifies the window \*(Wi. +.LP +.eM +If the window argument is +.PN None , +.PN XFilterEvent +applies the filter to the window specified in the +.PN XEvent +structure. +The window argument is provided so that layers above Xlib +that do event redirection can indicate to which window an event +has been redirected. +.LP +If +.PN XFilterEvent +returns +.PN True , +then some input method has filtered the event, +and the client should discard the event. +If +.PN XFilterEvent +returns +.PN False , +then the client should continue processing the event. +.LP +If a grab has occurred in the client and +.PN XFilterEvent +returns +.PN True , +the client should ungrab the keyboard. +.NH 3 +Getting Keyboard Input +.XS +\*(SN Getting Keyboard Input +.XE +.LP +To get composed input from an input method, +use +.PN XmbLookupString +or +.PN XwcLookupString . +.IN "XmbLookupString" "" "@DEF@" +.IN "XwcLookupString" "" "@DEF@" +.sM +.FD 0 +int XmbLookupString\^(\^\fIic\fP\^, \fIevent\fP\^, \fIbuffer_return\fP\^, \fIbytes_buffer\fP\^, \fIkeysym_return\fP\^, \fIstatus_return\fP\^) +.br + XIC \fIic\fP\^; +.br + XKeyPressedEvent *\fIevent\fP; +.br + char *\fIbuffer_return\fP\^; +.br + int \fIbytes_buffer\fP\^; +.br + KeySym *\fIkeysym_return\fP\^; +.br + Status *\fIstatus_return\fP\^; +.FN +.FD 0 +int XwcLookupString\^(\^\fIic\fP\^, \fIevent\fP\^, \fIbuffer_return\fP\^, \fIbytes_buffer\fP\^, \fIkeysym_return\fP\^, \fIstatus_return\fP\^) +.br + XIC \fIic\fP\^; +.br + XKeyPressedEvent *\fIevent\fP\^; +.br + wchar_t *\fIbuffer_return\fP\^; +.br + int \fIwchars_buffer\fP\^; +.br + KeySym *\fIkeysym_return\fP\^; +.br + Status *\fIstatus_return\fP\^; +.FN +.IP \fIic\fP 1i +Specifies the input context. +.ds Ev key event to be used +.IP \fIevent\fP 1i +Specifies the \*(Ev. +.IP \fIbuffer_return\fP 1i +Returns a multibyte string or wide character string (if any) +from the input method. +.IP \fIbytes_buffer\fP 1i +.br +.ns +.IP \fIwchars_buffer\fP 1i +Specifies space available in the return buffer. +.IP \fIkeysym_return\fP 1i +Returns the KeySym computed from the event if this argument is not NULL. +.IP \fIstatus_return\fP 1i +Returns a value indicating what kind of data is returned. +.LP +.eM +The +.PN XmbLookupString +and +.PN XwcLookupString +functions return the string from the input method specified +in the buffer_return argument. +If no string is returned, +the buffer_return argument is unchanged. +.LP +The KeySym into which the KeyCode from the event was mapped is returned +in the keysym_return argument if it is non-NULL and the status_return +argument indicates that a KeySym was returned. +If both a string and a KeySym are returned, +the KeySym value does not necessarily correspond to the string returned. +.LP +.PN XmbLookupString +returns the length of the string in bytes, and +.PN XwcLookupString +returns the length of the string in characters. +Both +.PN XmbLookupString +and +.PN XwcLookupString +return text in the encoding of the locale bound to the input method +of the specified input context. +.LP +Each string returned by +.PN XmbLookupString +and +.PN XwcLookupString +begins in the initial state of the encoding of the locale +(if the encoding of the locale is state-dependent). +.NT +To insure proper input processing, +it is essential that the client pass only +.PN KeyPress +events to +.PN XmbLookupString +and +.PN XwcLookupString . +Their behavior when a client passes a +.PN KeyRelease +event is undefined. +.NE +.LP +Clients should check the status_return argument before +using the other returned values. +These two functions both return a value to status_return +that indicates what has been returned in the other arguments. +The possible values returned are: +.TS +lw(1.5i) lw(4.3i). +T{ +.PN XBufferOverflow +T} T{ +The input string to be returned is too large for the supplied buffer_return. +The required size +.Pn ( XmbLookupString +in bytes; +.PN XwcLookupString +in characters) is returned as the value of the function, +and the contents of buffer_return and keysym_return are not modified. +The client should recall the function with the same event +and a buffer of adequate size to obtain the string. +T} +T{ +.PN XLookupNone +T} T{ +No consistent input has been composed so far. +The contents of buffer_return and keysym_return are not modified, +and the function returns zero. +T} +T{ +.PN XLookupChars +T} T{ +Some input characters have been composed. +They are placed in the buffer_return argument, +and the string length is returned as the value of the function. +The string is encoded in the locale bound to the input context. +The content of the keysym_return argument is not modified. +T} +T{ +.PN XLookupKeySym +T} T{ +A KeySym has been returned instead of a string +and is returned in keysym_return. +The content of the buffer_return argument is not modified, +and the function returns zero. +T} +T{ +.PN XLookupBoth +T} T{ +Both a KeySym and a string are returned; +.PN XLookupChars +and +.PN XLookupKeySym +occur simultaneously. +T} +.TE +.LP +It does not make any difference if the input context passed as an argument to +.PN XmbLookupString +and +.PN XwcLookupString +is the one currently in possession of the focus or not. +Input may have been composed within an input context before it lost the focus, +and that input may be returned on subsequent calls to +.PN XmbLookupString +or +.PN XwcLookupString +even though it does not have any more keyboard focus. +.NH 3 +Input Method Conventions +.XS +\*(SN Input Method Conventions +.XE +.LP +The input method architecture is transparent to the client. +However, clients should respect a number of conventions in order +to work properly. +Clients must also be aware of possible effects of synchronization +between input method and library in the case of a remote input server. +.NH 4 +Client Conventions +.XS +\*(SN Client Conventions +.XE +.LP +A well-behaved client (or toolkit) should first query the input method style. +If the client cannot satisfy the requirements of the supported styles +(in terms of geometry management or callbacks), +it should negotiate with the user continuation of the program +or raise an exception or error of some sort. +.NH 4 +Synchronization Conventions +.XS +\*(SN Synchronization Conventions +.XE +.LP +A +.PN KeyPress +event with a KeyCode of zero is used exclusively as a +signal that an input method has composed input that can be returned by +.PN XmbLookupString +or +.PN XwcLookupString . +No other use is made of a +.PN KeyPress +event with KeyCode of zero. +.LP +Such an event may be generated by either a front-end +or a back-end input method in an implementation-dependent manner. +Some possible ways to generate this event include: +.IP \(bu 5 +A synthetic event sent by an input method server +.IP \(bu 5 +An artificial event created by a input method filter and pushed +onto a client's event queue +.IP \(bu 5 +A +.PN KeyPress +event whose KeyCode value is modified by an input method filter +.LP +When callback support is specified by the client, +input methods will not take action unless they explicitly +called back the client and obtained no response +(the callback is not specified or returned invalid data). +.NH 2 +String Constants +.XS +\*(SN String Constants +.XE +.LP +The following symbols for string constants are defined in +.hN X11/Xlib.h . +Although they are shown here with particular macro definitions, +they may be implemented as macros, as global symbols, or as a +mixture of the two. The string pointer value itself +is not significant; clients must not assume that inequality of two +values implies inequality of the actual string data. +.IN "XNVaNestedList" "" "@DEF@" +.IN "XNSeparatorofNestedList "" "@DEF@" +.IN "XNQueryInputStyle" "" "@DEF@" +.IN "XNClientWindow" "" "@DEF@" +.IN "XNInputStyle" "" "@DEF@" +.IN "XNFocusWindow" "" "@DEF@" +.IN "XNResourceName" "" "@DEF@" +.IN "XNResourceClass" "" "@DEF@" +.IN "XNGeometryCallback" "" "@DEF@" +.IN "XNDestroyCallback" "" "@DEF@" +.IN "XNFilterEvents" "" "@DEF@" +.IN "XNPreeditStartCallback" "" "@DEF@" +.IN "XNPreeditDoneCallback" "" "@DEF@" +.IN "XNPreeditDrawCallback" "" "@DEF@" +.IN "XNPreeditCaretCallback" "" "@DEF@" +.IN "XNPreeditStateNotifyCallback" "" "@DEF@" +.IN "XNPreeditAttributes" "" "@DEF@" +.IN "XNStatusStartCallback" "" "@DEF@" +.IN "XNStatusDoneCallback" "" "@DEF@" +.IN "XNStatusDrawCallback" "" "@DEF@" +.IN "XNStatusAttributes" "" "@DEF@" +.IN "XNArea" "" "@DEF@" +.IN "XNAreaNeeded" "" "@DEF@" +.IN "XNSpotLocation" "" "@DEF@" +.IN "XNColormap" "" "@DEF@" +.IN "XNStdColormap" "" "@DEF@" +.IN "XNForeground" "" "@DEF@" +.IN "XNBackground" "" "@DEF@" +.IN "XNBackgroundPixmap" "" "@DEF@" +.IN "XNFontSet" "" "@DEF@" +.IN "XNLineSpace" "" "@DEF@" +.IN "XNCursor" "" "@DEF@" +.TS +lw(.5i) lw(2.75i) lw(2.5i). +T{ +#define +T} T{ +.PN XNVaNestedList +T} T{ +"XNVaNestedList" +T} +T{ +#define +T} T{ +.PN XNSeparatorofNestedList +T} T{ +"separatorofNestedList" +T} +T{ +#define +T} T{ +.PN XNQueryInputStyle +T} T{ +"queryInputStyle" +T} +T{ +#define +T} T{ +.PN XNClientWindow +T} T{ +"clientWindow" +T} +T{ +#define +T} T{ +.PN XNInputStyle +T} T{ +"inputStyle" +T} +T{ +#define +T} T{ +.PN XNFocusWindow +T} T{ +"focusWindow" +T} +T{ +#define +T} T{ +.PN XNResourceName +T} T{ +"resourceName" +T} +T{ +#define +T} T{ +.PN XNResourceClass +T} T{ +"resourceClass" +T} +T{ +#define +T} T{ +.PN XNGeometryCallback +T} T{ +"geometryCallback" +T} +T{ +#define +T} T{ +.PN XNDestroyCallback +T} T{ +"destroyCallback" +T} +T{ +#define +T} T{ +.PN XNFilterEvents +T} T{ +"filterEvents" +T} +T{ +#define +T} T{ +.PN XNPreeditStartCallback +T} T{ +"preeditStartCallback" +T} +T{ +#define +T} T{ +.PN XNPreeditDoneCallback +T} T{ +"preeditDoneCallback" +T} +T{ +#define +T} T{ +.PN XNPreeditDrawCallback +T} T{ +"preeditDrawCallback" +T} +T{ +#define +T} T{ +.PN XNPreeditCaretCallback +T} T{ +"preeditCaretCallback" +T} +T{ +#define +T} T{ +.PN XNPreeditStateNotifyCallback +T} T{ +"preeditStateNotifyCallback" +T} +T{ +#define +T} T{ +.PN XNPreeditAttributes +T} T{ +"preeditAttributes" +T} +.TE +.sp -1 +.TS +lw(.5i) lw(2.75i) lw(2.5i). +T{ +#define +T} T{ +.PN XNStatusStartCallback +T} T{ +"statusStartCallback" +T} +T{ +#define +T} T{ +.PN XNStatusDoneCallback +T} T{ +"statusDoneCallback" +T} +T{ +#define +T} T{ +.PN XNStatusDrawCallback +T} T{ +"statusDrawCallback" +T} +T{ +#define +T} T{ +.PN XNStatusAttributes +T} T{ +"statusAttributes" +T} +T{ +#define +T} T{ +.PN XNArea +T} T{ +"area" +T} +T{ +#define +T} T{ +.PN XNAreaNeeded +T} T{ +"areaNeeded" +T} +T{ +#define +T} T{ +.PN XNSpotLocation +T} T{ +"spotLocation" +T} +T{ +#define +T} T{ +.PN XNColormap +T} T{ +"colorMap" +T} +T{ +#define +T} T{ +.PN XNStdColormap +T} T{ +"stdColorMap" +T} +T{ +#define +T} T{ +.PN XNForeground +T} T{ +"foreground" +T} +T{ +#define +T} T{ +.PN XNBackground +T} T{ +"background" +T} +T{ +#define +T} T{ +.PN XNBackgroundPixmap +T} T{ +"backgroundPixmap" +T} +T{ +#define +T} T{ +.PN XNFontSet +T} T{ +"fontSet" +T} +T{ +#define +T} T{ +.PN XNLineSpace +T} T{ +"lineSpace" +T} +T{ +#define +T} T{ +.PN XNCursor +T} T{ +"cursor" +T} +.TE +.sp -1 +.TS +lw(.5i) lw(2.75i) lw(2.5i). +T{ +#define +T} T{ +.PN XNQueryIMValuesList +T} T{ +"queryIMValuesList" +T} +T{ +#define +T} T{ +.PN XNQueryICValuesList +T} T{ +"queryICValuesList" +T} +T{ +#define +T} T{ +.PN XNStringConversionCallback +T} T{ +"stringConversionCallback" +T} +T{ +#define +T} T{ +.PN XNStringConversion +T} T{ +"stringConversion" +T} +T{ +#define +T} T{ +.PN XNResetState +T} T{ +"resetState" +T} +T{ +#define +T} T{ +.PN XNHotKey +T} T{ +"hotkey" +T} +T{ +#define +T} T{ +.PN XNHotKeyState +T} T{ +"hotkeyState" +T} +T{ +#define +T} T{ +.PN XNPreeditState +T} T{ +"preeditState" +T} +T{ +#define +T} T{ +.PN XNVisiblePosition +T} T{ +"visiblePosition" +T} +T{ +#define +T} T{ +.PN XNR6PreeditCallbackBehavior +T} T{ +"r6PreeditCallback" +T} +.TE +.sp -1 +.IN "XNQueryIMValuesList" "" "@DEF@" +.IN "XNQueryICValuesList" "" "@DEF@" +.IN "XNStringConversionCallback" "" "@DEF@" +.IN "XNStringConversion" "" "@DEF@" +.IN "XNResetState" "" "@DEF@" +.IN "XNHotKey" "" "@DEF@" +.IN "XNHotKeyState" "" "@DEF@" +.IN "XNPreeditState" "" "@DEF@" +.IN "XNVisiblePosition" "" "@DEF@" +.IN "XNR6PreeditCallbackBehavior" "" "@DEF@" +.TS +lw(.5i) lw(2.75i) lw(2.5i). +T{ +#define +T} T{ +.PN XNRequiredCharSet +T} T{ +"requiredCharSet" +T} +T{ +#define +T} T{ +.PN XNQueryOrientation +T} T{ +"queryOrientation" +T} +T{ +#define +T} T{ +.PN XNDirectionalDependentDrawing +T} T{ +"directionalDependentDrawing" +T} +T{ +#define +T} T{ +.PN XNContextualDrawing +T} T{ +"contextualDrawing" +T} +T{ +#define +T} T{ +.PN XNBaseFontName +T} T{ +"baseFontName" +T} +T{ +#define +T} T{ +.PN XNMissingCharSet +T} T{ +"missingCharSet" +T} +T{ +#define +T} T{ +.PN XNDefaultString +T} T{ +"defaultString" +T} +T{ +#define +T} T{ +.PN XNOrientation +T} T{ +"orientation" +T} +T{ +#define +T} T{ +.PN XNFontInfo +T} T{ +"fontInfo" +T} +T{ +#define +T} T{ +.PN XNOMAutomatic +T} T{ +"omAutomatic" +T} +.TE +.IN "XNRequiredCharSet" "" "@DEF@" +.IN "XNQueryOrientation" "" "@DEF@" +.IN "XNDirectionalDependentDrawing" "" "@DEF@" +.IN "XNContextualDrawing" "" "@DEF@" +.IN "XNBaseFontName" "" "@DEF@" +.IN "XNMissingCharSet" "" "@DEF@" +.IN "XNDefaultString" "" "@DEF@" +.IN "XNOrientation" "" "@DEF@" +.IN "XNFontInfo" "" "@DEF@" +.IN "XNOMAutomatic" "" "@DEF@" +.bp diff --git a/libX11/specs/libX11/CH14 b/libX11/specs/libX11/CH14 new file mode 100644 index 000000000..34c09da8b --- /dev/null +++ b/libX11/specs/libX11/CH14 @@ -0,0 +1,3590 @@ +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be included +.\" in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR +.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +.\" OTHER DEALINGS IN THE SOFTWARE. +.\" +.\" Except as contained in this notice, the name of the X Consortium shall +.\" not be used in advertising or otherwise to promote the sale, use or +.\" other dealings in this Software without prior written authorization +.\" from the X Consortium. +.\" +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by +.\" Digital Equipment Corporation +.\" +.\" Portions Copyright \(co 1990, 1991 by +.\" Tektronix, Inc. +.\" +.\" Permission to use, copy, modify and distribute this documentation for +.\" any purpose and without fee is hereby granted, provided that the above +.\" copyright notice appears in all copies and that both that copyright notice +.\" and this permission notice appear in all copies, and that the names of +.\" Digital and Tektronix not be used in in advertising or publicity pertaining +.\" to this documentation without specific, written prior permission. +.\" Digital and Tektronix makes no representations about the suitability +.\" of this documentation for any purpose. +.\" It is provided ``as is'' without express or implied warranty. +.\" +\& +.sp 1 +.ce 3 +\s+1\fBChapter 14\fP\s-1 + +\s+1\fBInter-Client Communication Functions\fP\s-1 +.sp 2 +.nr H1 14 +.nr H2 0 +.nr H3 0 +.nr H4 0 +.nr H5 0 +.na +.LP +.XS +Chapter 14: Inter-Client Communication Functions +.XE +The \fIInter-Client Communication Conventions Manual\fP, +hereafter referred to as the ICCCM, details the +X Consortium approved conventions that govern inter-client communications. +These conventions ensure peer-to-peer client cooperation in the use +of selections, cut buffers, and shared resources as well as client cooperation +with window and session managers. +For further information, +see the \fIInter-Client Communication Conventions Manual\fP. +.LP +Xlib provides a number of standard properties and programming interfaces +that are ICCCM compliant. +The predefined atoms for some of these properties are defined in the +.hN X11/Xatom.h +header file, where +to avoid name conflicts with user symbols their +.PN #define +name has an XA_ prefix. +For further information about atoms and properties, +see section 4.3. +.LP +Xlib's selection and cut buffer mechanisms provide the primary programming +interfaces by which peer client applications communicate with each other +(see sections 4.5 and 16.6). +The functions discussed in this chapter provide +the primary programming interfaces by which client applications communicate +with their window and session managers as well as share standard colormaps. +.LP +The standard properties that are of special interest for communicating +with window and session managers are: +.IN "Atom" "predefined" +.TS H +lw(2i) lw(1.1i) lw(.4i) lw(2.25i) +lw(2i) lw(1.1i) cw(.4i) lw(2.25i). +_ +.sp 6p +.B +Name Type Format Description +.sp 6p +_ +.TH +.R +T{ +\s-1WM_CLASS\s+1 +T} T{ +\s-1STRING\s+1 +T} T{ +8 +T} T{ +Set by application programs to allow window and session +managers to obtain the application's resources from the resource database. +T} +.sp 6p +T{ +\s-1WM_CLIENT_MACHINE\s+1 +T} T{ +\s-1TEXT\s+1 +T} T{ +T} T{ +The string name of the machine on which the client application is running. +T} +.sp 6p +T{ +\s-1WM_COLORMAP_WINDOWS\s+1 +T} T{ +\s-1WINDOW\s+1 +T} T{ +32 +T} T{ +The list of window IDs that may need a different colormap +from that of their top-level window. +T} +.sp 6p +T{ +\s-1WM_COMMAND\s+1 +T} T{ +\s-1TEXT\s+1 +T} T{ +T} T{ +The command and arguments, null-separated, used to invoke the +application. +T} +.sp 6p +T{ +\s-1WM_HINTS\s+1 +T} T{ +\s-1WM_HINTS\s+1 +T} T{ +32 +T} T{ +Additional hints set by the client for use by the window manager. +The C type of this property is +.PN XWMHints . +T} +.sp 6p +T{ +\s-1WM_ICON_NAME\s+1 +T} T{ +\s-1TEXT\s+1 +T} T{ +T} T{ +The name to be used in an icon. +T} +.sp 6p +T{ +\s-1WM_ICON_SIZE\s+1 +T} T{ +\s-1WM_ICON_SIZE\s+1 +T} T{ +32 +T} T{ +The window manager may set this property on the root window to +specify the icon sizes it supports. +The C type of this property is +.PN XIconSize . +T} +.sp 6p +T{ +\s-1WM_NAME\s+1 +T} T{ +\s-1TEXT\s+1 +T} T{ +T} T{ +The name of the application. +T} +.sp 6p +T{ +\s-1WM_NORMAL_HINTS\s+1 +T} T{ +\s-1WM_SIZE_HINTS\s+1 +T} T{ +32 +T} T{ +Size hints for a window in its normal state. +The C type of this property is +.PN XSizeHints . +T} +.sp 6p +T{ +\s-1WM_PROTOCOLS\s+1 +T} T{ +\s-1ATOM\s+1 +T} T{ +32 +T} T{ +List of atoms that identify the communications protocols between the +client and window manager in which the client is willing to participate. +T} +.sp 6p +T{ +\s-1WM_STATE\s+1 +T} T{ +\s-1WM_STATE\s+1 +T} T{ +32 +T} T{ +Intended for communication between window and session managers only. +T} +.sp 6p +T{ +\s-1WM_TRANSIENT_FOR\s+1 +T} T{ +\s-1WINDOW\s+1 +T} T{ +32 +T} T{ +Set by application programs to indicate to the window manager that a transient +top-level window, such as a dialog box. +T} +.sp 6p +_ +.TE +.LP +The remainder of this chapter discusses: +.IP \(bu 5 +Client to window manager communication +.IP \(bu 5 +Client to session manager communication +.IP \(bu 5 +Standard colormaps +.NH 2 +Client to Window Manager Communication +.XS +\*(SN Client to Window Manager Communication +.XE +.LP +This section discusses how to: +.IP \(bu 5 +Manipulate top-level windows +.IP \(bu 5 +Convert string lists +.IP \(bu 5 +Set and read text properties +.IP \(bu 5 +Set and read the WM_NAME property +.IP \(bu 5 +Set and read the WM_ICON_NAME property +.IP \(bu 5 +Set and read the WM_HINTS property +.IP \(bu 5 +Set and read the WM_NORMAL_HINTS property +.IP \(bu 5 +Set and read the WM_CLASS property +.IP \(bu 5 +Set and read the WM_TRANSIENT_FOR property +.IP \(bu 5 +Set and read the WM_PROTOCOLS property +.IP \(bu 5 +Set and read the WM_COLORMAP_WINDOWS property +.IP \(bu 5 +Set and read the WM_ICON_SIZE property +.IP \(bu 5 +Use window manager convenience functions +.NH 3 +Manipulating Top-Level Windows +.XS +\*(SN Manipulating Top-Level Windows +.XE +.LP +Xlib provides functions that you can use to change the visibility or size +of top-level windows (that is, those that were created as children +of the root window). +Note that the subwindows that you create are ignored by window managers. +Therefore, +you should use the basic window functions described in chapter 3 +to manipulate your application's subwindows. +.LP +To request that a top-level window be iconified, use +.PN XIconifyWindow . +.IN "XIconifyWindow" "" "@DEF@" +.sM +.FD 0 +Status XIconifyWindow\^(\^\fIdisplay\fP, \fIw\fP, \fIscreen_number\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP; +.br + int \fIscreen_number\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIscreen_number\fP 1i +Specifies the appropriate screen number on the host server. +.LP +.eM +The +.PN XIconifyWindow +function sends a WM_CHANGE_STATE +.PN ClientMessage +event with a format of 32 and a first data element of +.PN IconicState +(as described in section 4.1.4 of the +\fIInter-Client Communication Conventions Manual\fP) +and a window of w +to the root window of the specified screen +with an event mask set to +.PN SubstructureNotifyMask | +.PN SubstructureRedirectMask . +Window managers may elect to receive this message and +if the window is in its normal state, +may treat it as a request to change the window's state from normal to iconic. +If the WM_CHANGE_STATE property cannot be interned, +.PN XIconifyWindow +does not send a message and returns a zero status. +It returns a nonzero status if the client message is sent successfully; +otherwise, it returns a zero status. +.sp +.LP +To request that a top-level window be withdrawn, use +.PN XWithdrawWindow . +.IN "XWithdrawWindow" "" "@DEF@" +.sM +.FD 0 +Status XWithdrawWindow\^(\^\fIdisplay\fP, \fIw\fP, \fIscreen_number\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + int \fIscreen_number\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIscreen_number\fP 1i +Specifies the appropriate screen number on the host server. +.LP +.eM +The +.PN XWithdrawWindow +function unmaps the specified window +and sends a synthetic +.PN UnmapNotify +event to the root window of the specified screen. +Window managers may elect to receive this message +and may treat it as a request to change the window's state to withdrawn. +When a window is in the withdrawn state, +neither its normal nor its iconic representations is visible. +It returns a nonzero status if the +.PN UnmapNotify +event is successfully sent; +otherwise, it returns a zero status. +.LP +.PN XWithdrawWindow +can generate a +.PN BadWindow +error. +.sp +.LP +To request that a top-level window be reconfigured, use +.PN XReconfigureWMWindow . +.IN "XReconfigureWMWindow" "" "@DEF@" +.sM +.FD 0 +Status XReconfigureWMWindow\^(\^\fIdisplay\fP, \fIw\fP, \fIscreen_number\fP, \ +\fIvalue_mask\fP, \fIvalues\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + int \fIscreen_number\fP\^; +.br + unsigned int \fIvalue_mask\fP\^; +.br + XWindowChanges *\fIvalues\fP; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIscreen_number\fP 1i +Specifies the appropriate screen number on the host server. +.IP \fIvalue_mask\fP 1i +Specifies which values are to be set using information in +the values structure. +This mask is the bitwise inclusive OR of the valid configure window values bits. +.IP \fIvalues\fP 1i +Specifies the +.PN XWindowChanges +structure. +.LP +.eM +The +.PN XReconfigureWMWindow +function issues a +.PN ConfigureWindow +request on the specified top-level window. +If the stacking mode is changed and the request fails with a +.PN BadMatch +error, +the error is trapped by Xlib and a synthetic +.PN ConfigureRequestEvent +containing the same configuration parameters is sent to the root +of the specified window. +Window managers may elect to receive this event +and treat it as a request to reconfigure the indicated window. +It returns a nonzero status if the request or event is successfully sent; +otherwise, it returns a zero status. +.LP +.PN XReconfigureWMWindow +can generate +.PN BadValue +and +.PN BadWindow +errors. +.NH 3 +Converting String Lists +.XS +\*(SN Converting String Lists +.XE +.LP +Many of the text properties allow a variety of types and formats. +Because the data stored in these properties are not +simple null-terminated strings, an +.PN XTextProperty +structure is used to describe the encoding, type, and length of the text +as well as its value. +The +.PN XTextProperty +structure contains: +.IN "XTextProperty" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef struct { + unsigned char *value; /* property data */ + Atom encoding; /* type of property */ + int format; /* 8, 16, or 32 */ + unsigned long nitems; /* number of items in value */ +} XTextProperty; +.De +.LP +.eM +Xlib provides functions to convert localized text to or from encodings +that support the inter-client communication conventions for text. +In addition, functions are provided for converting between lists of pointers +to character strings and text properties in the STRING encoding. +.LP +The functions for localized text return a signed integer error status +that encodes +.PN Success +as zero, specific error conditions as negative numbers, and partial conversion +as a count of unconvertible characters. +.LP +.IN "XICCEncodingStyle" "" "@DEF@" +.sM +.TS +lw(.5i) lw(2i) lw(2.5i). +T{ +#define +T} T{ +.PN XNoMemory +T} T{ +\-1 +T} +T{ +#define +T} T{ +.PN XLocaleNotSupported +T} T{ +\-2 +T} +T{ +#define +T} T{ +.PN XConverterNotFound +T} T{ +\-3 +T} +.TE +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef enum { + XStringStyle, /* STRING */ + XCompoundTextStyle, /* COMPOUND_TEXT */ + XTextStyle, /* text in owner's encoding (current locale) */ + XStdICCTextStyle /* STRING, else COMPOUND_TEXT */ +} XICCEncodingStyle; +.De +.LP +.eM +.sp +.LP +To convert a list of text strings to an +.PN XTextProperty +structure, use +.PN XmbTextListToTextProperty +or +.PN XwcTextListToTextProperty . +.IN "XmbTextListToTextProperty" "" "@DEF@" +.IN "XwcTextListToTextProperty" "" "@DEF@" +.sM +.FD 0 +int XmbTextListToTextProperty\^(\^\fIdisplay\fP\^, \fIlist\fP\^, \fIcount\fP\^, \fIstyle\fP\^, \fItext_prop_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + char **\fIlist\fP\^; +.br + int \fIcount\fP\^; +.br + XICCEncodingStyle \fIstyle\fP\^; +.br + XTextProperty *\fItext_prop_return\fP\^; +.FN +.FD 0 +int XwcTextListToTextProperty\^(\^\fIdisplay\fP\^, \fIlist\fP\^, \fIcount\fP\^, \fIstyle\fP\^, \fItext_prop_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + wchar_t **\fIlist\fP\^; +.br + int \fIcount\fP\^; +.br + XICCEncodingStyle \fIstyle\fP\^; +.br + XTextProperty *\fItext_prop_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIlist\fP 1i +Specifies a list of null-terminated character strings. +.IP \fIcount\fP 1i +Specifies the number of strings specified. +.IP \fIstyle\fP 1i +Specifies the manner in which the property is encoded. +.IP \fItext_prop_return\fP 1i +Returns the +.PN XTextProperty +structure. +.LP +.eM +The +.PN XmbTextListToTextProperty +and +.PN XwcTextListToTextProperty +functions set the specified +.PN XTextProperty +value to a set of null-separated elements representing the concatenation +of the specified list of null-terminated text strings. +A final terminating null is stored at the end of the value field +of text_prop_return but is not included in the nitems member. +.LP +The functions set the encoding field of text_prop_return to an +.PN Atom +for the specified display +naming the encoding determined by the specified style +and convert the specified text list to this encoding for storage in +the text_prop_return value field. +If the style +.PN XStringStyle +or +.PN XCompoundTextStyle +is specified, +this encoding is ``STRING'' or ``COMPOUND_TEXT'', respectively. +If the style +.PN XTextStyle +is specified, +this encoding is the encoding of the current locale. +If the style +.PN XStdICCTextStyle +is specified, +this encoding is ``STRING'' if the text is fully convertible to STRING, +else ``COMPOUND_TEXT''. +.LP +If insufficient memory is available for the new value string, +the functions return +.PN XNoMemory . +If the current locale is not supported, +the functions return +.PN XLocaleNotSupported . +In both of these error cases, +the functions do not set text_prop_return. +.LP +To determine if the functions are guaranteed not to return +.PN XLocaleNotSupported , +use +.PN XSupportsLocale . +.LP +If the supplied text is not fully convertible to the specified encoding, +the functions return the number of unconvertible characters. +Each unconvertible character is converted to an implementation-defined and +encoding-specific default string. +Otherwise, the functions return +.PN Success . +Note that full convertibility to all styles except +.PN XStringStyle +is guaranteed. +.LP +To free the storage for the value field, use +.PN XFree . +.sp +.LP +To obtain a list of text strings from an +.PN XTextProperty +structure, use +.PN XmbTextPropertyToTextList +or +.PN XwcTextPropertyToTextList . +.IN "XmbTextPropertyToTextList" "" "@DEF@" +.IN "XwcTextPropertyToTextList" "" "@DEF@" +.sM +.FD 0 +int XmbTextPropertyToTextList\^(\^\fIdisplay\fP\^, \fItext_prop\fP\^, \fIlist_return\fP\^, \fIcount_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XTextProperty *\fItext_prop\fP\^; +.br + char ***\fIlist_return\fP\^; +.br + int *\fIcount_return\fP\^; +.FN +.FD 0 +int XwcTextPropertyToTextList\^(\^\fIdisplay\fP\^, \fItext_prop\fP\^, \fIlist_return\fP\^, \fIcount_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XTextProperty *\fItext_prop\fP\^; +.br + wchar_t ***\fIlist_return\fP\^; +.br + int *\fIcount_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fItext_prop\fP 1i +Specifies the +.PN XTextProperty +structure to be used. +.IP \fIlist_return\fP 1i +Returns a list of null-terminated character strings. +.ds Cn strings +.IP \fIcount_return\fP 1i +Returns the number of \*(Cn. +.LP +.eM +The +.PN XmbTextPropertyToTextList +and +.PN XwcTextPropertyToTextList +functions return a list of text strings in the current locale representing the +null-separated elements of the specified +.PN XTextProperty +structure. +The data in text_prop must be format 8. +.LP +Multiple elements of the property (for example, the strings in a disjoint +text selection) are separated by a null byte. +The contents of the property are not required to be null-terminated; +any terminating null should not be included in text_prop.nitems. +.LP +If insufficient memory is available for the list and its elements, +.PN XmbTextPropertyToTextList +and +.PN XwcTextPropertyToTextList +return +.PN XNoMemory . +If the current locale is not supported, +the functions return +.PN XLocaleNotSupported . +Otherwise, if the encoding field of text_prop is not convertible +to the encoding of the current locale, +the functions return +.PN XConverterNotFound . +For supported locales, +existence of a converter from COMPOUND_TEXT, STRING +or the encoding of the current locale is guaranteed if +.PN XSupportsLocale +returns +.PN True +for the current locale (but the actual text +may contain unconvertible characters). +Conversion of other encodings is implementation-dependent. +In all of these error cases, +the functions do not set any return values. +.LP +Otherwise, +.PN XmbTextPropertyToTextList +and +.PN XwcTextPropertyToTextList +return the list of null-terminated text strings to list_return +and the number of text strings to count_return. +.LP +If the value field of text_prop is not fully convertible to the encoding of +the current locale, +the functions return the number of unconvertible characters. +Each unconvertible character is converted to a string in the +current locale that is specific to the current locale. +To obtain the value of this string, +use +.PN XDefaultString . +Otherwise, +.PN XmbTextPropertyToTextList +and +.PN XwcTextPropertyToTextList +return +.PN Success . +.LP +To free the storage for the list and its contents returned by +.PN XmbTextPropertyToTextList , +use +.PN XFreeStringList . +To free the storage for the list and its contents returned by +.PN XwcTextPropertyToTextList , +use +.PN XwcFreeStringList . +.sp +.LP +To free the in-memory data associated with the specified +wide character string list, use +.PN XwcFreeStringList . +.IN "XwcFreeStringList" "" "@DEF@" +.sM +.FD 0 +void XwcFreeStringList\^(\^\fIlist\fP\^) +.br + wchar_t **\fIlist\fP\^; +.FN +.IP \fIlist\fP 1i +Specifies the list of strings to be freed. +.LP +.eM +The +.PN XwcFreeStringList +function frees memory allocated by +.PN XwcTextPropertyToTextList . +.sp +.LP +To obtain the default string for text conversion in the current locale, +use +.PN XDefaultString . +.IN "XDefaultString" "" "@DEF@" +.sM +.FD 0 +char *XDefaultString\^(\|) +.FN +.LP +.eM +The +.PN XDefaultString +function returns the default string used by Xlib for text conversion +(for example, in +.PN XmbTextPropertyToTextList ). +The default string is the string in the current locale that is output +when an unconvertible character is found during text conversion. +If the string returned by +.PN XDefaultString +is the empty string ("\^"), +no character is output in the converted text. +.PN XDefaultString +does not return NULL. +.LP +The string returned by +.PN XDefaultString +is independent of the default string for text drawing; +see +.PN XCreateFontSet +to obtain the default string for an +.PN XFontSet . +.LP +The behavior when an invalid codepoint is supplied to any Xlib function is +undefined. +.LP +The returned string is null-terminated. +It is owned by Xlib and should not be modified or freed by the client. +It may be freed after the current locale is changed. +Until freed, it will not be modified by Xlib. +.sp +.LP +To set the specified list of strings in the STRING encoding to a +.PN XTextProperty +structure, use +.PN XStringListToTextProperty . +.IN "XStringListToTextProperty" "" "@DEF@" +.sM +.FD 0 +Status XStringListToTextProperty\^(\^\fIlist\fP, \fIcount\fP, \ +\fItext_prop_return\fP\^) +.br + char **\fIlist\fP\^; +.br + int \fIcount\fP\^; +.br + XTextProperty *\fItext_prop_return\fP\^; +.FN +.IP \fIlist\fP 1i +Specifies a list of null-terminated character strings. +.ds Cn strings +.IP \fIcount\fP 1i +Specifies the number of \*(Cn. +.IP \fItext_prop_return\fP 1i +Returns the +.PN XTextProperty +structure. +.LP +.eM +The +.PN XStringListToTextProperty +function sets the specified +.PN XTextProperty +to be of type STRING (format 8) with a value representing the +concatenation of the specified list of null-separated character strings. +An extra null byte (which is not included in the nitems member) +is stored at the end of the value field of text_prop_return. +The strings are assumed (without verification) to be in the STRING encoding. +If insufficient memory is available for the new value string, +.PN XStringListToTextProperty +does not set any fields in the +.PN XTextProperty +structure and returns a zero status. +Otherwise, it returns a nonzero status. +To free the storage for the value field, use +.PN XFree . +.sp +.LP +To obtain a list of strings from a specified +.PN XTextProperty +structure in the STRING encoding, use +.PN XTextPropertyToStringList . +.IN "XTextPropertyToStringList" "" "@DEF@" +.sM +.FD 0 +Status XTextPropertyToStringList\^(\^\fItext_prop\fP, \fIlist_return\fP, \ +\fIcount_return\fP\^) +.br + XTextProperty *\fItext_prop\fP\^; +.br + char ***\fIlist_return\fP\^; +.br + int *\fIcount_return\fP\^; +.FN +.IP \fItext_prop\fP 1i +Specifies the +.PN XTextProperty +structure to be used. +.IP \fIlist_return\fP 1i +Returns a list of null-terminated character strings. +.ds Cn strings +.IP \fIcount_return\fP 1i +Returns the number of \*(Cn. +.LP +.eM +The +.PN XTextPropertyToStringList +function returns a list of strings representing the null-separated elements +of the specified +.PN XTextProperty +structure. +The data in text_prop must be of type STRING and format 8. +Multiple elements of the property +(for example, the strings in a disjoint text selection) +are separated by NULL (encoding 0). +The contents of the property are not null-terminated. +If insufficient memory is available for the list and its elements, +.PN XTextPropertyToStringList +sets no return values and returns a zero status. +Otherwise, it returns a nonzero status. +To free the storage for the list and its contents, use +.PN XFreeStringList . +.sp +.LP +To free the in-memory data associated with the specified string list, use +.PN XFreeStringList . +.IN "XFreeStringList" "" "@DEF@" +.sM +.FD 0 +void XFreeStringList\^(\^\fIlist\fP\^) +.br + char **\fIlist\fP\^; +.FN +.IP \fIlist\fP 1i +Specifies the list of strings to be freed. +.LP +.eM +The +.PN XFreeStringList +function releases memory allocated by +.PN XmbTextPropertyToTextList +and +.PN XTextPropertyToStringList +and the missing charset list allocated by +.PN XCreateFontSet . +.NH 3 +Setting and Reading Text Properties +.XS +\*(SN Setting and Reading Text Properties +.XE +.LP +Xlib provides two functions that you can use to set and read +the text properties for a given window. +You can use these functions to set and read those properties of type TEXT +(WM_NAME, WM_ICON_NAME, WM_COMMAND, and WM_CLIENT_MACHINE). +In addition, +Xlib provides separate convenience functions that you can use to set each +of these properties. +For further information about these convenience functions, +see sections 14.1.4, 14.1.5, 14.2.1, and 14.2.2, respectively. +.sp +.LP +To set one of a window's text properties, use +.PN XSetTextProperty . +.IN "XSetTextProperty" "" "@DEF@" +.sM +.FD 0 +void XSetTextProperty\^(\^\fIdisplay\fP, \fIw\fP, \fItext_prop\fP, \ +\fIproperty\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + XTextProperty *\fItext_prop\fP\^; +.br + Atom \fIproperty\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fItext_prop\fP 1i +Specifies the +.PN XTextProperty +structure to be used. +.IP \fIproperty\fP 1i +Specifies the property name. +.LP +.eM +The +.PN XSetTextProperty +function replaces the existing specified property for the named window +with the data, type, format, and number of items determined +by the value field, the encoding field, the format field, +and the nitems field, respectively, of the specified +.PN XTextProperty +structure. +If the property does not already exist, +.PN XSetTextProperty +sets it for the specified window. +.LP +.PN XSetTextProperty +can generate +.PN BadAlloc , +.PN BadAtom , +.PN BadValue , +and +.PN BadWindow +errors. +.sp +.LP +To read one of a window's text properties, use +.PN XGetTextProperty . +.IN "XGetTextProperty" "" "@DEF@" +.sM +.FD 0 +Status XGetTextProperty\^(\^\fIdisplay\fP, \fIw\fP, \fItext_prop_return\fP, \ +\fIproperty\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + XTextProperty *\fItext_prop_return\fP\^; +.br + Atom \fIproperty\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fItext_prop_return\fP 1i +Returns the +.PN XTextProperty +structure. +.IP \fIproperty\fP 1i +Specifies the property name. +.LP +.eM +The +.PN XGetTextProperty +function reads the specified property from the window +and stores the data in the returned +.PN XTextProperty +structure. +It stores the data in the value field, +the type of the data in the encoding field, +the format of the data in the format field, +and the number of items of data in the nitems field. +An extra byte containing null (which is not included in the nitems member) +is stored at the end of the value field of text_prop_return. +The particular interpretation of the property's encoding +and data as text is left to the calling application. +If the specified property does not exist on the window, +.PN XGetTextProperty +sets the value field to NULL, +the encoding field to +.PN None , +the format field to zero, +and the nitems field to zero. +.LP +If it was able to read and store the data in the +.PN XTextProperty +structure, +.PN XGetTextProperty +returns a nonzero status; +otherwise, it returns a zero status. +.LP +.PN XGetTextProperty +can generate +.PN BadAtom +and +.PN BadWindow +errors. +.NH 3 +Setting and Reading the WM_NAME Property +.XS +\*(SN Setting and Reading the WM_NAME Property +.XE +.LP +Xlib provides convenience functions that you can use to set and read +the WM_NAME property for a given window. +.sp +.LP +To set a window's WM_NAME property with the supplied convenience function, use +.PN XSetWMName . +.IN "XSetWMName" "" "@DEF@" +.sM +.FD 0 +void XSetWMName\^(\^\fIdisplay\fP, \fIw\fP, \fItext_prop\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + XTextProperty *\fItext_prop\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fItext_prop\fP 1i +Specifies the +.PN XTextProperty +structure to be used. +.LP +.eM +The +.PN XSetWMName +convenience function calls +.PN XSetTextProperty +to set the WM_NAME property. +.sp +.LP +To read a window's WM_NAME property with the supplied convenience function, use +.PN XGetWMName . +.IN "XGetWMName" "" "@DEF@" +.sM +.FD 0 +Status XGetWMName\^(\^\fIdisplay\fP, \fIw\fP, \fItext_prop_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + XTextProperty *\fItext_prop_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fItext_prop_return\fP 1i +Returns the +.PN XTextProperty +structure. +.LP +.eM +The +.PN XGetWMName +convenience function calls +.PN XGetTextProperty +to obtain the WM_NAME property. +It returns a nonzero status on success; +otherwise, it returns a zero status. +.LP +The following two functions have been superseded by +.PN XSetWMName +and +.PN XGetWMName , +respectively. +You can use these additional convenience functions +for window names that are encoded as STRING properties. +.sp +.LP +To assign a name to a window, use +.PN XStoreName . +.IN "Window" "name" +.IN "XStoreName" "" "@DEF@" +.sM +.FD 0 +XStoreName\^(\^\fIdisplay\fP, \fIw\fP\^, \fIwindow_name\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + char *\fIwindow_name\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIwindow_name\fP 1i +Specifies the window name, +which should be a null-terminated string. +.LP +.eM +The +.PN XStoreName +function assigns the name passed to window_name to the specified window. +A window manager can display the window name in some prominent +place, such as the title bar, to allow users to identify windows easily. +Some window managers may display a window's name in the window's icon, +although they are encouraged to use the window's icon name +if one is provided by the application. +If the string is not in the Host Portable Character Encoding, +the result is implementation-dependent. +.LP +.PN XStoreName +can generate +.PN BadAlloc +and +.PN BadWindow +errors. +.LP +.sp +To get the name of a window, use +.PN XFetchName . +.IN "XFetchName" "" "@DEF@" +.sM +.FD 0 +Status XFetchName\^(\^\fIdisplay\fP, \fIw\fP\^, \fIwindow_name_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + char **\fIwindow_name_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIwindow_name_return\fP 1i +Returns the window name, which is a null-terminated string. +.LP +.eM +The +.PN XFetchName +function returns the name of the specified window. +If it succeeds, +it returns a nonzero status; +otherwise, no name has been set for the window, +and it returns zero. +If the WM_NAME property has not been set for this window, +.PN XFetchName +sets window_name_return to NULL. +If the data returned by the server is in the Latin Portable Character Encoding, +then the returned string is in the Host Portable Character Encoding. +Otherwise, the result is implementation-dependent. +When finished with it, a client must free +the window name string using +.PN XFree . +.LP +.PN XFetchName +can generate a +.PN BadWindow +error. +.NH 3 +Setting and Reading the WM_ICON_NAME Property +.XS +\*(SN Setting and Reading the WM_ICON_NAME Property +.XE +.LP +Xlib provides convenience functions that you can use to set and read +the WM_ICON_NAME property for a given window. +.LP +.sp +To set a window's WM_ICON_NAME property, +use +.PN XSetWMIconName . +.IN "XSetWMIconName" "" "@DEF@" +.sM +.FD 0 +void XSetWMIconName\^(\^\fIdisplay\fP, \fIw\fP, \fItext_prop\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + XTextProperty *\fItext_prop\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fItext_prop\fP 1i +Specifies the +.PN XTextProperty +structure to be used. +.LP +.eM +The +.PN XSetWMIconName +convenience function calls +.PN XSetTextProperty +to set the WM_ICON_NAME property. +.sp +.LP +To read a window's WM_ICON_NAME property, +use +.PN XGetWMIconName . +.IN "XGetWMIconName" "" "@DEF@" +.sM +.FD 0 +Status XGetWMIconName\^(\^\fIdisplay\fP, \fIw\fP, \fItext_prop_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + XTextProperty *\fItext_prop_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fItext_prop_return\fP 1i +Returns the +.PN XTextProperty +structure. +.LP +.eM +The +.PN XGetWMIconName +convenience function calls +.PN XGetTextProperty +to obtain the WM_ICON_NAME property. +It returns a nonzero status on success; +otherwise, it returns a zero status. +.LP +The next two functions have been superseded by +.PN XSetWMIconName +and +.PN XGetWMIconName , +respectively. +You can use these additional convenience functions +for window names that are encoded as STRING properties. +.sp +.LP +.sp +To set the name to be displayed in a window's icon, use +.PN XSetIconName . +.IN "Window" "icon name" +.IN "XSetIconName" "" "@DEF@" +.sM +.FD 0 +XSetIconName\^(\^\fIdisplay\fP, \fIw\fP\^, \fIicon_name\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + char *\fIicon_name\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIicon_name\fP 1i +Specifies the icon name, +which should be a null-terminated string. +.LP +.eM +If the string is not in the Host Portable Character Encoding, +the result is implementation-dependent. +.PN XSetIconName +can generate +.PN BadAlloc +and +.PN BadWindow +errors. +.LP +.sp +To get the name a window wants displayed in its icon, use +.PN XGetIconName . +.IN "XGetIconName" "" "@DEF@" +.sM +.FD 0 +Status XGetIconName\^(\^\fIdisplay\fP, \fIw\fP\^, \fIicon_name_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + char **\fIicon_name_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIicon_name_return\fP 1i +Returns the window's icon name, +which is a null-terminated string. +.LP +.eM +The +.PN XGetIconName +function returns the name to be displayed in the specified window's icon. +If it succeeds, it returns a nonzero status; otherwise, +if no icon name has been set for the window, +it returns zero. +If you never assigned a name to the window, +.PN XGetIconName +sets icon_name_return to NULL. +If the data returned by the server is in the Latin Portable Character Encoding, +then the returned string is in the Host Portable Character Encoding. +Otherwise, the result is implementation-dependent. +When finished with it, a client must free +the icon name string using +.PN XFree . +.LP +.PN XGetIconName +can generate a +.PN BadWindow +error. +.NH 3 +Setting and Reading the WM_HINTS Property +.XS +\*(SN Setting and Reading the WM_HINTS Property +.XE +.LP +Xlib provides functions that you can use to set and read +the WM_HINTS property for a given window. +These functions use the flags and the +.PN XWMHints +structure, as defined in the +.hN X11/Xutil.h +header file. +.sp +.LP +To allocate an +.PN XWMHints +structure, use +.PN XAllocWMHints . +.IN "XAllocWMHints" "" "@DEF@" +.sM +.FD 0 +XWMHints *XAllocWMHints\^(\|) +.FN +.LP +.eM +The +.PN XAllocWMHints +function allocates and returns a pointer to an +.PN XWMHints +structure. +Note that all fields in the +.PN XWMHints +structure are initially set to zero. +If insufficient memory is available, +.PN XAllocWMHints +returns NULL. +To free the memory allocated to this structure, +use +.PN XFree . +.LP +The +.PN XWMHints +structure contains: +.LP +.sM +/* Window manager hints mask bits */ +.TS +lw(.5i) lw(2.5i) lw(2.5i). +T{ +#define +T} T{ +.PN InputHint +T} T{ +(1L << 0) +T} +T{ +#define +T} T{ +.PN StateHint +T} T{ +(1L << 1) +T} +T{ +#define +T} T{ +.PN IconPixmapHint +T} T{ +(1L << 2) +T} +T{ +#define +T} T{ +.PN IconWindowHint +T} T{ +(1L << 3) +T} +T{ +#define +T} T{ +.PN IconPositionHint +T} T{ +(1L << 4) +T} +T{ +#define +T} T{ +.PN IconMaskHint +T} T{ +(1L << 5) +T} +T{ +#define +T} T{ +.PN WindowGroupHint +T} T{ +(1L << 6) +T} +T{ +#define +T} T{ +.PN UrgencyHint +T} T{ +(1L << 8) +T} +T{ +#define +T} T{ +.PN AllHints +T} T{ +(InputHint|StateHint|IconPixmapHint| +.br +IconWindowHint|IconPositionHint| +.br +IconMaskHint|WindowGroupHint) +T} +.TE +.IN "XWMHints" "" "@DEF@" +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +/* Values */ + +typedef struct { + long flags; /* marks which fields in this structure are defined */ + Bool input; /* does this application rely on the window manager to + get keyboard input? */ + int initial_state; /* see below */ + Pixmap icon_pixmap; /* pixmap to be used as icon */ + Window icon_window; /* window to be used as icon */ + int icon_x, icon_y; /* initial position of icon */ + Pixmap icon_mask; /* pixmap to be used as mask for icon_pixmap */ + XID window_group; /* id of related window group */ + /* this structure may be extended in the future */ +} XWMHints; +.De +.LP +.eM +The input member is used to communicate to the window manager the input focus +model used by the application. +Applications that expect input but never explicitly set focus to any +of their subwindows (that is, use the push model of focus management), +such as X Version 10 style applications that use real-estate +driven focus, should set this member to +.PN True . +Similarly, applications +that set input focus to their subwindows only when it is given to their +top-level window by a window manager should also set this member to +.PN True . +Applications that manage their own input focus by explicitly setting +focus to one of their subwindows whenever they want keyboard input +(that is, use the pull model of focus management) should set this member to +.PN False . +Applications that never expect any keyboard input also should set this member +to +.PN False . +.LP +Pull model window managers should make it possible for push model +applications to get input by setting input focus to the top-level windows of +applications whose input member is +.PN True . +Push model window managers should +make sure that pull model applications do not break them +by resetting input focus to +.PN PointerRoot +when it is appropriate (for example, whenever an application whose +input member is +.PN False +sets input focus to one of its subwindows). +.LP +The definitions for the initial_state flag are: +.TS +lw(.5i) lw(2i) lw(.2i) lw(2.8i). +T{ +#define +T} T{ +.PN WithdrawnState +T} T{ +0 +T} T{ +T} +T{ +#define +T} T{ +.PN NormalState +T} T{ +1 +T} T{ +/* most applications start this way */ +T} +T{ +#define +T} T{ +.PN IconicState +T} T{ +3 +T} T{ +/* application wants to start as an icon */ +T} +.TE +The icon_mask specifies which pixels of the icon_pixmap should be used as the +icon. +This allows for nonrectangular icons. +Both icon_pixmap and icon_mask must be bitmaps. +The icon_window lets an application provide a window for use as an icon +for window managers that support such use. +The window_group lets you specify that this window belongs to a group +of other windows. +For example, if a single application manipulates multiple +top-level windows, this allows you to provide enough +information that a window manager can iconify all of the windows +rather than just the one window. +.LP +The +.PN UrgencyHint +flag, if set in the flags field, indicates that the client deems the window +contents to be urgent, requiring the timely response of the user. The +window manager will make some effort to draw the user's attention to this +window while this flag is set. The client must provide some means by which the +user can cause the urgency flag to be cleared (either mitigating +the condition that made the window urgent or merely shutting off the alarm) +or the window to be withdrawn. +.LP +.sp +To set a window's WM_HINTS property, use +.PN XSetWMHints . +.IN "XSetWMHints" "" "@DEF@" +.sM +.FD 0 +XSetWMHints\^(\^\fIdisplay\fP, \fIw\fP, \fIwmhints\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + XWMHints *\fIwmhints\fP\^; + +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIwmhints\fP 1i +Specifies the +.PN XWMHints +structure to be used. +.LP +.eM +The +.PN XSetWMHints +function sets the window manager hints that include icon information and location, +the initial state of the window, and whether the application relies on the +window manager to get keyboard input. +.LP +.PN XSetWMHints +can generate +.PN BadAlloc +and +.PN BadWindow +errors. +.LP +.sp +To read a window's WM_HINTS property, use +.PN XGetWMHints . +.IN "XGetWMHints" "" "@DEF@" +.sM +.FD 0 +XWMHints *XGetWMHints\^(\^\fIdisplay\fP, \fIw\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.LP +.eM +The +.PN XGetWMHints +function reads the window manager hints and +returns NULL if no WM_HINTS property was set on the window +or returns a pointer to an +.PN XWMHints +structure if it succeeds. +When finished with the data, +free the space used for it by calling +.PN XFree . +.LP +.PN XGetWMHints +can generate a +.PN BadWindow +error. +.NH 3 +Setting and Reading the WM_NORMAL_HINTS Property +.XS +\*(SN Setting and Reading the WM_NORMAL_HINTS Property +.XE +.LP +Xlib provides functions that you can use to set or read +the WM_NORMAL_HINTS property for a given window. +The functions use the flags and the +.PN XSizeHints +structure, as defined in the +.hN X11/Xutil.h +header file. +.LP +The size of the +.PN XSizeHints +structure may grow in future releases, as new components are +added to support new ICCCM features. +Passing statically allocated instances of this structure into +Xlib may result in memory corruption when running against a +future release of the library. +As such, it is recommended that only dynamically allocated +instances of the structure be used. +.sp +.LP +To allocate an +.PN XSizeHints +structure, use +.PN XAllocSizeHints . +.IN "XAllocSizeHints" "" "@DEF@" +.sM +.FD 0 +XSizeHints *XAllocSizeHints\^(\|) +.FN +.LP +.eM +The +.PN XAllocSizeHints +function allocates and returns a pointer to an +.PN XSizeHints +structure. +Note that all fields in the +.PN XSizeHints +structure are initially set to zero. +If insufficient memory is available, +.PN XAllocSizeHints +returns NULL. +To free the memory allocated to this structure, +use +.PN XFree . +.LP +The +.PN XSizeHints +structure contains: +.LP +.sM +/* Size hints mask bits */ +.TS +lw(.5i) lw(1.1i) lw(1.5i) lw(3.1i). +T{ +#define +T} T{ +.PN USPosition +T} T{ +(1L << 0) +T} T{ +/* user specified x, y */ +T} +T{ +#define +T} T{ +.PN USSize +T} T{ +(1L << 1) +T} T{ +/* user specified width, height */ +T} +T{ +#define +T} T{ +.PN PPosition +T} T{ +(1L << 2) +T} T{ +/* program specified position */ +T} +T{ +#define +T} T{ +.PN PSize +T} T{ +(1L << 3) +T} T{ +/* program specified size */ +T} +T{ +#define +T} T{ +.PN PMinSize +T} T{ +(1L << 4) +T} T{ +/* program specified minimum size */ +T} +T{ +#define +T} T{ +.PN PMaxSize +T} T{ +(1L << 5) +T} T{ +/* program specified maximum size */ +T} +T{ +#define +T} T{ +.PN PResizeInc +T} T{ +(1L << 6) +T} T{ +/* program specified resize increments */ +T} +T{ +#define +T} T{ +.PN PAspect +T} T{ +(1L << 7) +T} T{ +/* program specified min and max aspect ratios */ +T} +T{ +#define +T} T{ +.PN PBaseSize +T} T{ +(1L << 8) +T} +T{ +#define +T} T{ +.PN PWinGravity +T} T{ +(1L << 9) +T} +T{ +#define +T} T{ +.PN PAllHints +T} T{ +(PPosition|PSize| +.br +PMinSize|PMaxSize| +.br +PResizeInc|PAspect) +T} T{ +T} +.TE +.IN "XSizeHints" "" "@DEF@" +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +/* Values */ + +typedef struct { + long flags; /* marks which fields in this structure are defined */ + int x, y; /* Obsolete */ + int width, height; /* Obsolete */ + int min_width, min_height; + int max_width, max_height; + int width_inc, height_inc; + struct { + int x; /* numerator */ + int y; /* denominator */ + } min_aspect, max_aspect; + int base_width, base_height; + int win_gravity; + /* this structure may be extended in the future */ +} XSizeHints; +.De +.LP +.eM +The x, y, width, and height members are now obsolete +and are left solely for compatibility reasons. +The min_width and min_height members specify the +minimum window size that still allows the application to be useful. +The max_width and max_height members specify the maximum window size. +The width_inc and height_inc members define an arithmetic progression of +sizes (minimum to maximum) into which the window prefers to be resized. +The min_aspect and max_aspect members are expressed +as ratios of x and y, +and they allow an application to specify the range of aspect +ratios it prefers. +The base_width and base_height members define the desired size of the window. +The window manager will interpret the position of the window +and its border width to position the point of the outer rectangle +of the overall window specified by the win_gravity member. +The outer rectangle of the window includes any borders or decorations +supplied by the window manager. +In other words, +if the window manager decides to place the window where the client asked, +the position on the parent window's border named by the win_gravity +will be placed where the client window would have been placed +in the absence of a window manager. +.LP +Note that use of the +.PN PAllHints +macro is highly discouraged. +.sp +.LP +To set a window's WM_NORMAL_HINTS property, use +.PN XSetWMNormalHints . +.IN "XSetWMNormalHints" "" "@DEF@" +.sM +.FD 0 +void XSetWMNormalHints\^(\^\fIdisplay\fP, \fIw\fP, \fIhints\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + XSizeHints *\fIhints\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIhints\fP 1i +Specifies the size hints for the window in its normal state. +.LP +.eM +The +.PN XSetWMNormalHints +function replaces the size hints for the WM_NORMAL_HINTS property +on the specified window. +If the property does not already exist, +.PN XSetWMNormalHints +sets the size hints for the WM_NORMAL_HINTS property on the specified window. +The property is stored with a type of WM_SIZE_HINTS and a format of 32. +.LP +.PN XSetWMNormalHints +can generate +.PN BadAlloc +and +.PN BadWindow +errors. +.sp +.LP +To read a window's WM_NORMAL_HINTS property, use +.PN XGetWMNormalHints . +.IN "XGetWMNormalHints" "" "@DEF@" +.sM +.FD 0 +Status XGetWMNormalHints\^(\^\fIdisplay\fP, \fIw\fP, \fIhints_return\fP, \ +\fIsupplied_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + XSizeHints *\fIhints_return\fP\^; +.br + long *\fIsupplied_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIhints_return\fP 1i +Returns the size hints for the window in its normal state. +.IP \fIsupplied_return\fP 1i +Returns the hints that were supplied by the user. +.LP +.eM +The +.PN XGetWMNormalHints +function returns the size hints stored in the WM_NORMAL_HINTS property +on the specified window. +If the property is of type WM_SIZE_HINTS, is of format 32, +and is long enough to contain either an old (pre-ICCCM) +or new size hints structure, +.PN XGetWMNormalHints +sets the various fields of the +.PN XSizeHints +structure, sets the supplied_return argument to the list of fields +that were supplied by the user (whether or not they contained defined values), +and returns a nonzero status. +Otherwise, it returns a zero status. +.LP +If +.PN XGetWMNormalHints +returns successfully and a pre-ICCCM size hints property is read, +the supplied_return argument will contain the following bits: +.LP +.Ds +(USPosition|USSize|PPosition|PSize|PMinSize| + PMaxSize|PResizeInc|PAspect) +.De +.LP +If the property is large enough to contain the base size +and window gravity fields as well, +the supplied_return argument will also contain the following bits: +.LP +.Ds +PBaseSize|PWinGravity +.De +.LP +.PN XGetWMNormalHints +can generate a +.PN BadWindow +error. +.sp +.LP +To set a window's WM_SIZE_HINTS property, use +.PN XSetWMSizeHints . +.IN "XSetWMSizeHints" "" "@DEF@" +.sM +.FD 0 +void XSetWMSizeHints\^(\^\fIdisplay\fP, \fIw\fP, \fIhints\fP, \fIproperty\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + XSizeHints *\fIhints\fP\^; +.br + Atom \fIproperty\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIhints\fP 1i +Specifies the +.PN XSizeHints +structure to be used. +.IP \fIproperty\fP 1i +Specifies the property name. +.LP +.eM +The +.PN XSetWMSizeHints +function replaces the size hints for the specified property +on the named window. +If the specified property does not already exist, +.PN XSetWMSizeHints +sets the size hints for the specified property +on the named window. +The property is stored with a type of WM_SIZE_HINTS and a format of 32. +To set a window's normal size hints, +you can use the +.PN XSetWMNormalHints +function. +.LP +.PN XSetWMSizeHints +can generate +.PN BadAlloc , +.PN BadAtom , +and +.PN BadWindow +errors. +.sp +.LP +To read a window's WM_SIZE_HINTS property, use +.PN XGetWMSizeHints . +.IN "XGetWMSizeHints" "" "@DEF@" +.sM +.FD 0 +Status XGetWMSizeHints\^(\^\fIdisplay\fP, \fIw\fP, \fIhints_return\fP, \ +\fIsupplied_return\fP, \fIproperty\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + XSizeHints *\fIhints_return\fP\^; +.br + long *\fIsupplied_return\fP\^; +.br + Atom \fIproperty\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIhints_return\fP 1i +Returns the +.PN XSizeHints +structure. +.IP \fIsupplied_return\fP 1i +Returns the hints that were supplied by the user. +.IP \fIproperty\fP 1i +Specifies the property name. +.LP +.eM +The +.PN XGetWMSizeHints +function returns the size hints stored in the specified property +on the named window. +If the property is of type WM_SIZE_HINTS, is of format 32, +and is long enough to contain either an old (pre-ICCCM) +or new size hints structure, +.PN XGetWMSizeHints +sets the various fields of the +.PN XSizeHints +structure, sets the supplied_return argument to the +list of fields that were supplied by the user +(whether or not they contained defined values), +and returns a nonzero status. +Otherwise, it returns a zero status. +To get a window's normal size hints, +you can use the +.PN XGetWMNormalHints +function. +.LP +If +.PN XGetWMSizeHints +returns successfully and a pre-ICCCM size hints property is read, +the supplied_return argument will contain the following bits: +.LP +.Ds +(USPosition|USSize|PPosition|PSize|PMinSize| + PMaxSize|PResizeInc|PAspect) +.De +.LP +If the property is large enough to contain the base size +and window gravity fields as well, +the supplied_return argument will also contain the following bits: +.LP +.Ds +PBaseSize|PWinGravity +.De +.LP +.PN XGetWMSizeHints +can generate +.PN BadAtom +and +.PN BadWindow +errors. +.NH 3 +Setting and Reading the WM_CLASS Property +.XS +\*(SN Setting and Reading the WM_CLASS Property +.XE +.LP +Xlib provides functions that you can use to set and get +the WM_CLASS property for a given window. +These functions use the +.PN XClassHint +structure, which is defined in the +.hN X11/Xutil.h +header file. +.sp +.LP +To allocate an +.PN XClassHint +structure, use +.PN XAllocClassHint . +.IN "XAllocClassHint" "" "@DEF@" +.sM +.FD 0 +XClassHint *XAllocClassHint\^(\|) +.FN +.LP +.eM +The +.PN XAllocClassHint +function allocates and returns a pointer to an +.PN XClassHint +structure. +Note that the pointer fields in the +.PN XClassHint +structure are initially set to NULL. +If insufficient memory is available, +.PN XAllocClassHint +returns NULL. +To free the memory allocated to this structure, +use +.PN XFree . +.LP +The +.PN XClassHint +contains: +.LP +.sM +.IN "XClassHint" "" "@DEF@" +.Ds 0 +.TA .5i +.ta .5i +typedef struct { + char *res_name; + char *res_class; +} XClassHint; +.De +.LP +.eM +The res_name member contains the application name, +and the res_class member contains the application class. +Note that the name set in this property may differ from the name set as WM_NAME. +That is, WM_NAME specifies what should be displayed in the title bar and, +therefore, can contain temporal information (for example, the name of +a file currently in an editor's buffer). +On the other hand, +the name specified as part of WM_CLASS is the formal name of the application +that should be used when retrieving the application's resources from the +resource database. +.LP +.sp +To set a window's WM_CLASS property, use +.PN XSetClassHint . +.IN "XSetClassHint" "" "@DEF@" +.sM +.FD 0 +XSetClassHint\^(\^\fIdisplay\fP, \fIw\fP, \fIclass_hints\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + XClassHint *\fIclass_hints\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIclass_hints\fP 1i +Specifies the +.PN XClassHint +structure that is to be used. +.LP +.eM +The +.PN XSetClassHint +function sets the class hint for the specified window. +If the strings are not in the Host Portable Character Encoding, +the result is implementation-dependent. +.LP +.PN XSetClassHint +can generate +.PN BadAlloc +and +.PN BadWindow +errors. +.LP +.sp +To read a window's WM_CLASS property, use +.PN XGetClassHint . +.IN "XGetClassHint" "" "@DEF@" +.sM +.FD 0 +Status XGetClassHint\^(\^\fIdisplay\fP, \fIw\fP, \fIclass_hints_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP; +.br + XClassHint *\fIclass_hints_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIclass_hints_return\fP 1i +Returns the +.PN XClassHint +structure. +.LP +.eM +The +.PN XGetClassHint +function returns the class hint of the specified window to the members +of the supplied structure. +If the data returned by the server is in the Latin Portable Character Encoding, +then the returned strings are in the Host Portable Character Encoding. +Otherwise, the result is implementation-dependent. +It returns a nonzero status on success; +otherwise, it returns a zero status. +To free res_name and res_class when finished with the strings, +use +.PN XFree +on each individually. +.LP +.PN XGetClassHint +can generate a +.PN BadWindow +error. +.NH 3 +Setting and Reading the WM_TRANSIENT_FOR Property +.XS +\*(SN Setting and Reading the WM_TRANSIENT_FOR Property +.XE +.LP +Xlib provides functions that you can use to set and read +the WM_TRANSIENT_FOR property for a given window. +.LP +.sp +To set a window's WM_TRANSIENT_FOR property, use +.PN XSetTransientForHint . +.IN "XSetTransientForHint" "" "@DEF@" +.sM +.FD 0 +XSetTransientForHint\^(\^\fIdisplay\fP, \fIw\fP, \fIprop_window\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + Window \fIprop_window\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIprop_window\fP 1i +Specifies the window that the WM_TRANSIENT_FOR property is to be set to. +.LP +.eM +The +.PN XSetTransientForHint +function sets the WM_TRANSIENT_FOR property of the specified window to the +specified prop_window. +.LP +.PN XSetTransientForHint +can generate +.PN BadAlloc +and +.PN BadWindow +errors. +.LP +.sp +To read a window's WM_TRANSIENT_FOR property, use +.PN XGetTransientForHint . +.IN "XGetTransientForHint" "" "@DEF@" +.sM +.FD 0 +Status XGetTransientForHint\^(\^\fIdisplay\fP, \fIw\fP, \fIprop_window_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + Window *\fIprop_window_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIprop_window_return\fP 1i +Returns the WM_TRANSIENT_FOR property of the specified window. +.LP +.eM +The +.PN XGetTransientForHint +function returns the WM_TRANSIENT_FOR property for the specified window. +It returns a nonzero status on success; +otherwise, it returns a zero status. +.LP +.PN XGetTransientForHint +can generate a +.PN BadWindow +error. +.NH 3 +Setting and Reading the WM_PROTOCOLS Property +.XS +\*(SN Setting and Reading the WM_PROTOCOLS Property +.XE +.LP +Xlib provides functions that you can use to set and read +the WM_PROTOCOLS property for a given window. +.LP +.sp +To set a window's WM_PROTOCOLS property, use +.PN XSetWMProtocols . +.IN "XSetWMProtocols" "" "@DEF@" +.sM +.FD 0 +Status XSetWMProtocols\^(\^\fIdisplay\fP, \fIw\fP, \fIprotocols\fP, \ +\fIcount\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + Atom *\fIprotocols\fP\^; +.br + int \fIcount\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIprotocols\fP 1i +Specifies the list of protocols. +.ds Cn protocols in the list +.IP \fIcount\fP 1i +Specifies the number of \*(Cn. +.LP +.eM +The +.PN XSetWMProtocols +function replaces the WM_PROTOCOLS property on the specified window +with the list of atoms specified by the protocols argument. +If the property does not already exist, +.PN XSetWMProtocols +sets the WM_PROTOCOLS property on the specified window +to the list of atoms specified by the protocols argument. +The property is stored with a type of ATOM and a format of 32. +If it cannot intern the WM_PROTOCOLS atom, +.PN XSetWMProtocols +returns a zero status. +Otherwise, it returns a nonzero status. +.LP +.PN XSetWMProtocols +can generate +.PN BadAlloc +and +.PN BadWindow +errors. +.sp +.LP +To read a window's WM_PROTOCOLS property, use +.PN XGetWMProtocols . +.IN "XGetWMProtocols" "" "@DEF@" +.sM +.FD 0 +Status XGetWMProtocols\^(\^\fIdisplay\fP, \fIw\fP, \fIprotocols_return\fP, \ +\fIcount_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + Atom **\fIprotocols_return\fP\^; +.br + int *\fIcount_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIprotocols_return\fP 1i +Returns the list of protocols. +.ds Cn protocols in the list +.IP \fIcount_return\fP 1i +Returns the number of \*(Cn. +.LP +.eM +The +.PN XGetWMProtocols +function returns the list of atoms stored in the WM_PROTOCOLS property +on the specified window. +These atoms describe window manager protocols in which the owner +of this window is willing to participate. +If the property exists, is of type ATOM, is of format 32, +and the atom WM_PROTOCOLS can be interned, +.PN XGetWMProtocols +sets the protocols_return argument to a list of atoms, +sets the count_return argument to the number of elements in the list, +and returns a nonzero status. +Otherwise, it sets neither of the return arguments +and returns a zero status. +To release the list of atoms, use +.PN XFree . +.LP +.PN XGetWMProtocols +can generate a +.PN BadWindow +error. +.NH 3 +Setting and Reading the WM_COLORMAP_WINDOWS Property +.XS +\*(SN Setting and Reading the WM_COLORMAP_WINDOWS Property +.XE +.LP +Xlib provides functions that you can use to set and read +the WM_COLORMAP_WINDOWS property for a given window. +.sp +.LP +To set a window's WM_COLORMAP_WINDOWS property, use +.PN XSetWMColormapWindows . +.IN "XSetWMColormapWindows" "" "@DEF@" +.sM +.FD 0 +Status XSetWMColormapWindows\^(\^\fIdisplay\fP, \fIw\fP, \ +\fIcolormap_windows\fP, \fIcount\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + Window *\fIcolormap_windows\fP\^; +.br + int \fIcount\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIcolormap_windows\fP 1i +Specifies the list of windows. +.ds Cn windows in the list +.IP \fIcount\fP 1i +Specifies the number of \*(Cn. +.LP +.eM +The +.PN XSetWMColormapWindows +function replaces the WM_COLORMAP_WINDOWS property on the specified +window with the list of windows specified by the colormap_windows argument. +If the property does not already exist, +.PN XSetWMColormapWindows +sets the WM_COLORMAP_WINDOWS property on the specified +window to the list of windows specified by the colormap_windows argument. +The property is stored with a type of WINDOW and a format of 32. +If it cannot intern the WM_COLORMAP_WINDOWS atom, +.PN XSetWMColormapWindows +returns a zero status. +Otherwise, it returns a nonzero status. +.LP +.PN XSetWMColormapWindows +can generate +.PN BadAlloc +and +.PN BadWindow +errors. +.sp +.LP +To read a window's WM_COLORMAP_WINDOWS property, use +.PN XGetWMColormapWindows . +.IN "XGetWMColormapWindows" "" "@DEF@" +.sM +.FD 0 +Status XGetWMColormapWindows\^(\^\fIdisplay\fP, \fIw\fP, \ +\fIcolormap_windows_return\fP, \fIcount_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + Window **\fIcolormap_windows_return\fP\^; +.br + int *\fIcount_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIcolormap_windows_return\fP 1i +Returns the list of windows. +.ds Cn windows in the list +.IP \fIcount_return\fP 1i +Returns the number of \*(Cn. +.LP +.eM +The +.PN XGetWMColormapWindows +function returns the list of window identifiers stored +in the WM_COLORMAP_WINDOWS property on the specified window. +These identifiers indicate the colormaps that the window manager +may need to install for this window. +If the property exists, is of type WINDOW, is of format 32, +and the atom WM_COLORMAP_WINDOWS can be interned, +.PN XGetWMColormapWindows +sets the windows_return argument to a list of window identifiers, +sets the count_return argument to the number of elements in the list, +and returns a nonzero status. +Otherwise, it sets neither of the return arguments +and returns a zero status. +To release the list of window identifiers, use +.PN XFree . +.LP +.PN XGetWMColormapWindows +can generate a +.PN BadWindow +error. +.NH 3 +Setting and Reading the WM_ICON_SIZE Property +.XS +\*(SN Setting and Reading the WM_ICON_SIZE Property +.XE +.LP +Xlib provides functions that you can use to set and read +the WM_ICON_SIZE property for a given window. +These functions use the +.PN XIconSize +.IN "XIconSize" +structure, which is defined in the +.hN X11/Xutil.h +header file. +.sp +.LP +To allocate an +.PN XIconSize +structure, use +.PN XAllocIconSize . +.IN "XAllocIconSize" "" "@DEF@" +.sM +.FD 0 +XIconSize *XAllocIconSize\^(\|) +.FN +.LP +.eM +The +.PN XAllocIconSize +function allocates and returns a pointer to an +.PN XIconSize +structure. +Note that all fields in the +.PN XIconSize +structure are initially set to zero. +If insufficient memory is available, +.PN XAllocIconSize +returns NULL. +To free the memory allocated to this structure, +use +.PN XFree . +.LP +The +.PN XIconSize +structure contains: +.LP +.sM +.IN "XIconSize" "" "@DEF@" +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef struct { + int min_width, min_height; + int max_width, max_height; + int width_inc, height_inc; +} XIconSize; +.De +.LP +.eM +The width_inc and height_inc members define an arithmetic progression of +sizes (minimum to maximum) that represent the supported icon sizes. +.LP +.sp +To set a window's WM_ICON_SIZE property, use +.PN XSetIconSizes . +.IN "XSetIconSizes" "" "@DEF@" +.sM +.FD 0 +XSetIconSizes\^(\^\fIdisplay\fP, \fIw\fP, \fIsize_list\fP, \fIcount\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + XIconSize *\fIsize_list\fP\^; +.br + int \fIcount\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIsize_list\fP 1i +Specifies the size list. +.IP \fIcount\fP 1i +Specifies the number of items in the size list. +.LP +.eM +The +.PN XSetIconSizes +function is used only by window managers to set the supported icon sizes. +.LP +.PN XSetIconSizes +can generate +.PN BadAlloc +and +.PN BadWindow +errors. +.LP +.sp +To read a window's WM_ICON_SIZE property, use +.PN XGetIconSizes . +.IN "XGetIconSizes" "" "@DEF@" +.sM +.FD 0 +Status XGetIconSizes\^(\^\fIdisplay\fP, \fIw\fP, \fIsize_list_return\fP, \fIcount_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + XIconSize **\fIsize_list_return\fP\^; +.br + int *\fIcount_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIsize_list_return\fP 1i +Returns the size list. +.IP \fIcount_return\fP 1i +Returns the number of items in the size list. +.LP +.eM +The +.PN XGetIconSizes +function returns zero if a window manager has not set icon sizes; +otherwise, it returns nonzero. +.PN XGetIconSizes +should be called by an application that +wants to find out what icon sizes would be most appreciated by the +window manager under which the application is running. +The application +should then use +.PN XSetWMHints +to supply the window manager with an icon pixmap or window in one of the +supported sizes. +To free the data allocated in size_list_return, use +.PN XFree . +.LP +.PN XGetIconSizes +can generate a +.PN BadWindow +error. +.NH 3 +Using Window Manager Convenience Functions +.XS +\*(SN Using Window Manager Convenience Functions +.XE +.LP +The +.PN XmbSetWMProperties +function stores the standard set of window manager properties, +with text properties in standard encodings +for internationalized text communication. +The standard window manager properties for a given window are +WM_NAME, WM_ICON_NAME, WM_HINTS, WM_NORMAL_HINTS, WM_CLASS, +WM_COMMAND, WM_CLIENT_MACHINE, and WM_LOCALE_NAME. +.IN "XmbSetWMProperties" "" "@DEF@" +.sM +.FD 0 +void XmbSetWMProperties\^(\^\fIdisplay\fP\^, \fIw\fP\^, \fIwindow_name\fP\^, \fIicon_name\fP\^, \fIargv\fP\^, \fIargc\fP\^, +.br + \fInormal_hints\fP\^, \fIwm_hints\fP\^, \fIclass_hints\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + char *\fIwindow_name\fP\^; +.br + char *\fIicon_name\fP\^; +.br + char *\fIargv\fP\^[]; +.br + int \fIargc\fP\^; +.br + XSizeHints *\fInormal_hints\fP\^; +.br + XWMHints *\fIwm_hints\fP\^; +.br + XClassHint *\fIclass_hints\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIwindow_name\fP 1i +Specifies the window name, +which should be a null-terminated string. +.IP \fIicon_name\fP 1i +Specifies the icon name, +which should be a null-terminated string. +.IP \fIargv\fP 1i +Specifies the application's argument list. +.IP \fIargc\fP 1i +Specifies the number of arguments. +.IP \fIhints\fP 1i +Specifies the size hints for the window in its normal state. +.IP \fIwm_hints\fP 1i +Specifies the +.PN XWMHints +structure to be used. +.IP \fIclass_hints\fP 1i +Specifies the +.PN XClassHint +structure to be used. +.LP +.eM +The +.PN XmbSetWMProperties +convenience function provides a simple programming interface +for setting those essential window properties that are used +for communicating with other clients +(particularly window and session managers). +.LP +If the window_name argument is non-NULL, +.PN XmbSetWMProperties +sets the WM_NAME property. +If the icon_name argument is non-NULL, +.PN XmbSetWMProperties +sets the WM_ICON_NAME property. +The window_name and icon_name arguments are null-terminated strings +in the encoding of the current locale. +If the arguments can be fully converted to the STRING encoding, +the properties are created with type ``STRING''; +otherwise, the arguments are converted to Compound Text, +and the properties are created with type ``COMPOUND_TEXT''. +.LP +If the normal_hints argument is non-NULL, +.PN XmbSetWMProperties +calls +.PN XSetWMNormalHints , +which sets the WM_NORMAL_HINTS property (see section 14.1.7). +If the wm_hints argument is non-NULL, +.PN XmbSetWMProperties +calls +.PN XSetWMHints , +which sets the WM_HINTS property (see section 14.1.6). +.LP +If the argv argument is non-NULL, +.PN XmbSetWMProperties +sets the WM_COMMAND property from argv and argc. +An argc of zero indicates a zero-length command. +.LP +The hostname of the machine is stored using +.PN XSetWMClientMachine +(see section 14.2.2). +.LP +If the class_hints argument is non-NULL, +.PN XmbSetWMProperties +sets the WM_CLASS property. +If the res_name member in the +.PN XClassHint +structure is set to the NULL pointer and the RESOURCE_NAME +environment variable is set, +the value of the environment variable is substituted for res_name. +If the res_name member is NULL, +the environment variable is not set, and argv and argv[0] are set, +then the value of argv[0], stripped of any directory prefixes, +is substituted for res_name. +.LP +It is assumed that the supplied class_hints.res_name and argv, +the RESOURCE_NAME environment variable, and the hostname of the machine +are in the encoding of the locale announced for the LC_CTYPE category +(on POSIX-compliant systems, the LC_CTYPE, else LANG environment variable). +The corresponding WM_CLASS, WM_COMMAND, and WM_CLIENT_MACHINE properties +are typed according to the local host locale announcer. +No encoding conversion is performed prior to storage in the properties. +.LP +For clients that need to process the property text in a locale, +.PN XmbSetWMProperties +sets the WM_LOCALE_NAME property to be the name of the current locale. +The name is assumed to be in the Host Portable Character Encoding +and is converted to STRING for storage in the property. +.LP +.PN XmbSetWMProperties +can generate +.PN BadAlloc +and +.PN BadWindow +errors. +.sp +.LP +To set a window's standard window manager properties +with strings in client-specified encodings, use +.PN XSetWMProperties . +The standard window manager properties for a given window are +WM_NAME, WM_ICON_NAME, WM_HINTS, WM_NORMAL_HINTS, WM_CLASS, +WM_COMMAND, and WM_CLIENT_MACHINE. +.IN "XSetWMProperties" "" "@DEF@" +.sM +.FD 0 +void XSetWMProperties\^(\^\fIdisplay\fP, \fIw\fP, \fIwindow_name\fP, \ +\fIicon_name\fP, \fIargv\fP, \fIargc\fP, \fInormal_hints\fP, \fIwm_hints\fP, \ +\fIclass_hints\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + XTextProperty *\fIwindow_name\fP\^; +.br + XTextProperty *\fIicon_name\fP\^; +.br + char **\fIargv\fP\^; +.br + int \fIargc\fP\^; +.br + XSizeHints *\fInormal_hints\fP\^; +.br + XWMHints *\fIwm_hints\fP\^; +.br + XClassHint *\fIclass_hints\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIwindow_name\fP 1i +Specifies the window name, +which should be a null-terminated string. +.IP \fIicon_name\fP 1i +Specifies the icon name, +which should be a null-terminated string. +.IP \fIargv\fP 1i +Specifies the application's argument list. +.IP \fIargc\fP 1i +Specifies the number of arguments. +.IP \fInormal_hints\fP 1i +Specifies the size hints for the window in its normal state. +.IP \fIwm_hints\fP 1i +Specifies the +.PN XWMHints +structure to be used. +.IP \fIclass_hints\fP 1i +Specifies the +.PN XClassHint +structure to be used. +.LP +.eM +The +.PN XSetWMProperties +convenience function provides a single programming interface +for setting those essential window properties that are used +for communicating with other clients (particularly window and session +managers). +.LP +If the window_name argument is non-NULL, +.PN XSetWMProperties +calls +.PN XSetWMName , +which, in turn, sets the WM_NAME property (see section 14.1.4). +If the icon_name argument is non-NULL, +.PN XSetWMProperties +calls +.PN XSetWMIconName , +which sets the WM_ICON_NAME property (see section 14.1.5). +If the argv argument is non-NULL, +.PN XSetWMProperties +calls +.PN XSetCommand , +which sets the WM_COMMAND property (see section 14.2.1). +Note that an argc of zero is allowed to indicate a zero-length command. +Note also that the hostname of this machine is stored using +.PN XSetWMClientMachine +(see section 14.2.2). +.LP +If the normal_hints argument is non-NULL, +.PN XSetWMProperties +calls +.PN XSetWMNormalHints , +which sets the WM_NORMAL_HINTS property (see section 14.1.7). +If the wm_hints argument is non-NULL, +.PN XSetWMProperties +calls +.PN XSetWMHints , +which sets the WM_HINTS property (see section 14.1.6). +.LP +If the class_hints argument is non-NULL, +.PN XSetWMProperties +calls +.PN XSetClassHint , +which sets the WM_CLASS property (see section 14.1.8). +If the res_name member in the +.PN XClassHint +structure is set to the NULL pointer and the RESOURCE_NAME environment +variable is set, +then the value of the environment variable is substituted for res_name. +If the res_name member is NULL, +the environment variable is not set, +and argv and argv[0] are set, +then the value of argv[0], stripped of +any directory prefixes, is substituted for res_name. +.LP +.PN XSetWMProperties +can generate +.PN BadAlloc +and +.PN BadWindow +errors. +.NH 2 +Client to Session Manager Communication +.XS +\*(SN Client to Session Manager Communication +.XE +.LP +This section discusses how to: +.IP \(bu 5 +Set and read the WM_COMMAND property +.IP \(bu 5 +Set and read the WM_CLIENT_MACHINE property +.NH 3 +Setting and Reading the WM_COMMAND Property +.XS +\*(SN Setting and Reading the WM_COMMAND Property +.XE +.LP +Xlib provides functions that you can use to set and read +the WM_COMMAND property for a given window. +.sp +.LP +To set a window's WM_COMMAND property, use +.PN XSetCommand . +.IN "XSetCommand" "" "@DEF@" +.sM +.FD 0 +XSetCommand\^(\^\fIdisplay\fP, \fIw\fP, \fIargv\fP, \fIargc\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + char **\fIargv\fP\^; +.br + int \fIargc\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIargv\fP 1i +Specifies the application's argument list. +.IP \fIargc\fP 1i +Specifies the number of arguments. +.LP +.eM +The +.PN XSetCommand +function sets the command and arguments used to invoke the +application. +(Typically, argv is the argv array of your main program.) +If the strings are not in the Host Portable Character Encoding, +the result is implementation-dependent. +.LP +.PN XSetCommand +can generate +.PN BadAlloc +and +.PN BadWindow +errors. +.sp +.LP +To read a window's WM_COMMAND property, use +.PN XGetCommand . +.IN "XGetCommand" "" "@DEF@" +.sM +.FD 0 +Status XGetCommand\^(\^\fIdisplay\fP, \fIw\fP, \fIargv_return\fP, \ +\fIargc_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + char ***\fIargv_return\fP\^; +.br + int *\fIargc_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIargv_return\fP 1i +Returns the application's argument list. +.IP \fIargc_return\fP 1i +Returns the number of arguments returned. +.LP +.eM +The +.PN XGetCommand +function reads the WM_COMMAND property from the specified window +and returns a string list. +If the WM_COMMAND property exists, +it is of type STRING and format 8. +If sufficient memory can be allocated to contain the string list, +.PN XGetCommand +fills in the argv_return and argc_return arguments +and returns a nonzero status. +Otherwise, it returns a zero status. +If the data returned by the server is in the Latin Portable Character Encoding, +then the returned strings are in the Host Portable Character Encoding. +Otherwise, the result is implementation-dependent. +To free the memory allocated to the string list, use +.PN XFreeStringList . +.NH 3 +Setting and Reading the WM_CLIENT_MACHINE Property +.XS +\*(SN Setting and Reading the WM_CLIENT_MACHINE Property +.XE +.LP +Xlib provides functions that you can use to set and read +the WM_CLIENT_MACHINE property for a given window. +.sp +.LP +To set a window's WM_CLIENT_MACHINE property, use +.PN XSetWMClientMachine . +.IN "XSetWMClientMachine" "" "@DEF@" +.sM +.FD 0 +void XSetWMClientMachine\^(\^\fIdisplay\fP, \fIw\fP, \fItext_prop\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + XTextProperty *\fItext_prop\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fItext_prop\fP 1i +Specifies the +.PN XTextProperty +structure to be used. +.LP +.eM +The +.PN XSetWMClientMachine +convenience function calls +.PN XSetTextProperty +to set the WM_CLIENT_MACHINE property. +.sp +.LP +To read a window's WM_CLIENT_MACHINE property, use +.PN XGetWMClientMachine . +.IN "XGetWMClientMachine" "" "@DEF@" +.sM +.FD 0 +Status XGetWMClientMachine\^(\^\fIdisplay\fP, \fIw\fP, \fItext_prop_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + XTextProperty *\fItext_prop_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fItext_prop_return\fP 1i +Returns the +.PN XTextProperty +structure. +.LP +.eM +The +.PN XGetWMClientMachine +convenience function performs an +.PN XGetTextProperty +on the WM_CLIENT_MACHINE property. +It returns a nonzero status on success; +otherwise, it returns a zero status. +.NH 2 +Standard Colormaps +.XS +\*(SN Standard Colormaps +.XE +.LP +Applications with color palettes, smooth-shaded drawings, or digitized +images demand large numbers of colors. +In addition, these applications often require an efficient mapping +from color triples to pixel values that display the appropriate colors. +.LP +As an example, consider a three-dimensional display program that wants +to draw a smoothly shaded sphere. +At each pixel in the image of the sphere, +the program computes the intensity and color of light +reflected back to the viewer. +The result of each computation is a triple of red, green, and blue (RGB) +coefficients in the range 0.0 to 1.0. +To draw the sphere, the program needs a colormap that provides a +large range of uniformly distributed colors. +The colormap should be arranged so that the program can +convert its RGB triples into pixel values very quickly, +because drawing the entire sphere requires many such +conversions. +.LP +On many current workstations, +the display is limited to 256 or fewer colors. +Applications must allocate colors carefully, +not only to make sure they cover the entire range they need +but also to make use of as many of the available colors as possible. +On a typical X display, +many applications are active at once. +Most workstations have only one hardware look-up table for colors, +so only one application colormap can be installed at a given time. +The application using the installed colormap is displayed correctly, +and the other applications go technicolor and are +displayed with false colors. +.LP +As another example, consider a user who is running an +image processing program to display earth-resources data. +The image processing program needs a colormap set up with 8 reds, +8 greens, and 4 blues, for a total of 256 colors. +Because some colors are already in use in the default colormap, +the image processing program allocates and installs a new colormap. +.LP +The user decides to alter some of the colors in the image +by invoking a color palette program to mix and choose colors. +The color palette program also needs a +colormap with eight reds, eight greens, and four blues, so just like +the image processing program, it must allocate and +install a new colormap. +.LP +Because only one colormap can be installed at a time, +the color palette may be displayed incorrectly +whenever the image processing program is active. +Conversely, whenever the palette program is active, +the image may be displayed incorrectly. +The user can never match or compare colors in the palette and image. +Contention for colormap resources can be reduced if applications +with similar color needs share colormaps. +.LP +The image processing program and the color palette program +could share the same colormap if there existed a convention that described +how the colormap was set up. +Whenever either program was active, +both would be displayed correctly. +.LP +The standard colormap properties define a set of commonly used +colormaps. +Applications that share these colormaps and conventions display +true colors more often and provide a better interface to the user. +.LP +Standard colormaps allow applications to share commonly used color +resources. +This allows many applications to be displayed in true colors +simultaneously, even when each application needs an entirely filled +colormap. +.LP +Several standard colormaps are described in this section. +Usually, a window manager creates these colormaps. +Applications should use the standard colormaps if they already exist. +.sp +.LP +To allocate an +.PN XStandardColormap +structure, use +.PN XAllocStandardColormap . +.IN "XAllocStandardColormap" "" "@DEF@" +.sM +.FD 0 +XStandardColormap *XAllocStandardColormap\^(\|) +.FN +.LP +.eM +The +.PN XAllocStandardColormap +function allocates and returns a pointer to an +.PN XStandardColormap +structure. +Note that all fields in the +.PN XStandardColormap +structure are initially set to zero. +If insufficient memory is available, +.PN XAllocStandardColormap +returns NULL. +To free the memory allocated to this structure, +use +.PN XFree . +.LP +The +.PN XStandardColormap +structure contains: +.LP +.sM +/* Hints */ +.TS +lw(.5i) lw(2i) lw(1i). +T{ +#define +T} T{ +.PN ReleaseByFreeingColormap +T} T{ +( (XID) 1L) +T} +.TE +/* Values */ +.IN "XStandardColormap" "" "@DEF@" +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef struct { + Colormap colormap; + unsigned long red_max; + unsigned long red_mult; + unsigned long green_max; + unsigned long green_mult; + unsigned long blue_max; + unsigned long blue_mult; + unsigned long base_pixel; + VisualID visualid; + XID killid; +} XStandardColormap; +.De +.LP +.eM +The colormap member is the colormap created by the +.PN XCreateColormap +function. +The red_max, green_max, and blue_max members give the maximum +red, green, and blue values, respectively. +Each color coefficient ranges from zero to its max, inclusive. +For example, +a common colormap allocation is 3/3/2 (3 planes for red, 3 +planes for green, and 2 planes for blue). +This colormap would have red_max = 7, green_max = 7, +and blue_max = 3. +An alternate allocation that uses only 216 colors is red_max = 5, +green_max = 5, and blue_max = 5. +.LP +The red_mult, green_mult, and blue_mult members give the +scale factors used to compose a full pixel value. +(See the discussion of the base_pixel members for further information.) +For a 3/3/2 allocation, red_mult might be 32, +green_mult might be 4, and blue_mult might be 1. +For a 6-colors-each allocation, red_mult might be 36, +green_mult might be 6, and blue_mult might be 1. +.LP +The base_pixel member gives the base pixel value used to +compose a full pixel value. +Usually, the base_pixel is obtained from a call to the +.PN XAllocColorPlanes +function. +Given integer red, green, and blue coefficients in their appropriate +ranges, one then can compute a corresponding pixel value by +using the following expression: +.LP +.Ds +.TA .5i 1.5i +.ta .5i 1.5i +(r * red_mult + g * green_mult + b * blue_mult + base_pixel) & 0xFFFFFFFF +.De +.LP +For +.PN GrayScale +colormaps, +only the colormap, red_max, red_mult, +and base_pixel members are defined. +The other members are ignored. +To compute a +.PN GrayScale +pixel value, use the following expression: +.LP +.Ds +.TA .5i 1.5i +.ta .5i 1.5i +(gray * red_mult + base_pixel) & 0xFFFFFFFF +.De +.LP +Negative multipliers can be represented by converting the 2's +complement representation of the multiplier into an unsigned long and +storing the result in the appropriate _mult field. +The step of masking by 0xFFFFFFFF effectively converts the resulting +positive multiplier into a negative one. +The masking step will take place automatically on many machine architectures, +depending on the size of the integer type used to do the computation. +.LP +The visualid member gives the ID number of the visual from which the +colormap was created. +The killid member gives a resource ID that indicates whether +the cells held by this standard colormap are to be released +by freeing the colormap ID or by calling the +.PN XKillClient +function on the indicated resource. +(Note that this method is necessary for allocating out of an existing colormap.) +.LP +The properties containing the +.PN XStandardColormap +information have +the type RGB_COLOR_MAP. +.LP +The remainder of this section discusses standard colormap properties and atoms +as well as how to manipulate standard colormaps. +.NH 3 +Standard Colormap Properties and Atoms +.XS +\*(SN Standard Colormap Properties and Atoms +.XE +.LP +.IN "Standard Colormaps" +.IN "Colormaps" "standard" +Several standard colormaps are available. +Each standard colormap is defined by a property, +and each such property is identified by an atom. +The following list names the atoms and describes the colormap +associated with each one. +The +.hN X11/Xatom.h +header file contains the definitions for each of the following atoms, +which are prefixed with XA_. +.IP RGB_DEFAULT_MAP 5 +This atom names a property. +The value of the property is an array of +.PN XStandardColormap +structures. +Each entry in the array describes an RGB subset of the default color +map for the Visual specified by visual_id. +.IP +Some applications only need a few RGB colors and +may be able to allocate them from the system default colormap. +This is the ideal situation because the fewer colormaps that are +active in the system the more applications are displayed +with correct colors at all times. +.IP +A typical allocation for the RGB_DEFAULT_MAP on 8-plane displays +is 6 reds, 6 greens, and 6 blues. +This gives 216 uniformly distributed colors +(6 intensities of 36 different hues) and still leaves 40 elements +of a 256-element colormap available for special-purpose colors +for text, borders, and so on. +.IP RGB_BEST_MAP 5 +.br +This atom names a property. +The value of the property is an +.PN XStandardColormap . +.IP +The property defines the best RGB colormap available on +the screen. +(Of course, this is a subjective evaluation.) +Many image processing and three-dimensional applications need to +use all available colormap cells and to distribute as many +perceptually distinct colors as possible over those cells. +This implies that there may be more green values available than +red, as well as more green or red than blue. +.IP +For an 8-plane +.PN PseudoColor +visual, +RGB_BEST_MAP is likely to be a 3/3/2 allocation. +For a 24-plane +.PN DirectColor +visual, +RGB_BEST_MAP is normally an 8/8/8 allocation. +.IP RGB_RED_MAP 5 +.br +.ns +.IP RGB_GREEN_MAP 5 +.br +.ns +.IP RGB_BLUE_MAP 5 +These atoms name properties. +The value of each property is an +.PN XStandardColormap . +.IP +The properties define all-red, all-green, and all-blue +colormaps, respectively. +These maps are used by applications that want to make color-separated +images. +For example, a user might generate a full-color image +on an 8-plane display both by rendering an image three times +(once with high color resolution in red, once with green, +and once with blue) and by multiply exposing a single frame in a camera. +.IP RGB_GRAY_MAP 5 +This atom names a property. +The value of the property is an +.PN XStandardColormap . +.IP +The property describes the best +.PN GrayScale +colormap available on the screen. +As previously mentioned, +only the colormap, red_max, red_mult, and base_pixel members of the +.PN XStandardColormap +structure are used for +.PN GrayScale +colormaps. +.NH 3 +Setting and Obtaining Standard Colormaps +.XS +\*(SN Setting and Obtaining Standard Colormaps +.XE +.LP +Xlib provides functions that you can use to set and obtain an +.PN XStandardColormap +structure. +.sp +.LP +To set an +.PN XStandardColormap +structure, use +.PN XSetRGBColormaps . +.IN "XSetRGBColormaps" "" "@DEF@" +.sM +.FD 0 +void XSetRGBColormaps\^(\^\fIdisplay\fP, \fIw\fP, \fIstd_colormap\fP, \ +\fIcount\fP, \fIproperty\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + XStandardColormap *\fIstd_colormap\fP\^; +.br + int \fIcount\fP\^; +.br + Atom \fIproperty\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIstd_colormap\fP 1i +Specifies the +.PN XStandardColormap +structure to be used. +.ds Cn colormaps +.IP \fIcount\fP 1i +Specifies the number of \*(Cn. +.IP \fIproperty\fP 1i +Specifies the property name. +.LP +.eM +The +.PN XSetRGBColormaps +function replaces the RGB colormap definition in the specified property +on the named window. +If the property does not already exist, +.PN XSetRGBColormaps +sets the RGB colormap definition in the specified property +on the named window. +The property is stored with a type of RGB_COLOR_MAP and a format of 32. +Note that it is the caller's responsibility to honor the ICCCM +restriction that only RGB_DEFAULT_MAP contain more than one definition. +.LP +The +.PN XSetRGBColormaps +function usually is only used by window or session managers. +To create a standard colormap, +follow this procedure: +.IP 1. 5 +Open a new connection to the same server. +.IP 2. 5 +Grab the server. +.IP 3. 5 +See if the property is on the property list of the root window for the screen. +.IP 4. 5 +If the desired property is not present: +.RS +.IP \(bu 5 +Create a colormap (unless you are using the default colormap of the screen). +.IP \(bu 5 +Determine the color characteristics of the visual. +.IP \(bu 5 +Allocate cells in the colormap (or create it with +.PN AllocAll ). +.IP \(bu 5 +Call +.PN XStoreColors +to store appropriate color values in the colormap. +.IP \(bu 5 +Fill in the descriptive members in the +.PN XStandardColormap +structure. +.IP \(bu 5 +Attach the property to the root window. +.IP \(bu 5 +Use +.PN XSetCloseDownMode +to make the resource permanent. +.RE +.IP 5. 5 +Ungrab the server. +.LP +.PN XSetRGBColormaps +can generate +.PN BadAlloc , +.PN BadAtom , +and +.PN BadWindow +errors. +.sp +.LP +To obtain the +.PN XStandardColormap +structure associated with the specified property, use +.PN XGetRGBColormaps . +.IN "XGetRGBColormaps" "" "@DEF@" +.sM +.FD 0 +Status XGetRGBColormaps\^(\^\fIdisplay\fP, \fIw\fP, \fIstd_colormap_return\fP, \ +\fIcount_return\fP, \fIproperty\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + XStandardColormap **\fIstd_colormap_return\fP\^; +.br + int *\fIcount_return\fP\^; +.br + Atom \fIproperty\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIstd_colormap_return\fP 1i +Returns the +.PN XStandardColormap +structure. +.ds Cn colormaps +.IP \fIcount_return\fP 1i +Returns the number of \*(Cn. +.IP \fIproperty\fP 1i +Specifies the property name. +.LP +.eM +The +.PN XGetRGBColormaps +function returns the RGB colormap definitions stored +in the specified property on the named window. +If the property exists, is of type RGB_COLOR_MAP, is of format 32, +and is long enough to contain a colormap definition, +.PN XGetRGBColormaps +allocates and fills in space for the returned colormaps +and returns a nonzero status. +If the visualid is not present, +.PN XGetRGBColormaps +assumes the default visual for the screen on which the window is located; +if the killid is not present, +.PN None +is assumed, which indicates that the resources cannot be released. +Otherwise, +none of the fields are set, and +.PN XGetRGBColormaps +returns a zero status. +Note that it is the caller's responsibility to honor the ICCCM +restriction that only RGB_DEFAULT_MAP contain more than one definition. +.LP +.PN XGetRGBColormaps +can generate +.PN BadAtom +and +.PN BadWindow +errors. +.bp diff --git a/libX11/specs/libX11/CH15 b/libX11/specs/libX11/CH15 new file mode 100644 index 000000000..a10df0a53 --- /dev/null +++ b/libX11/specs/libX11/CH15 @@ -0,0 +1,1628 @@ +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be included +.\" in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR +.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +.\" OTHER DEALINGS IN THE SOFTWARE. +.\" +.\" Except as contained in this notice, the name of the X Consortium shall +.\" not be used in advertising or otherwise to promote the sale, use or +.\" other dealings in this Software without prior written authorization +.\" from the X Consortium. +.\" +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by +.\" Digital Equipment Corporation +.\" +.\" Portions Copyright \(co 1990, 1991 by +.\" Tektronix, Inc. +.\" +.\" Permission to use, copy, modify and distribute this documentation for +.\" any purpose and without fee is hereby granted, provided that the above +.\" copyright notice appears in all copies and that both that copyright notice +.\" and this permission notice appear in all copies, and that the names of +.\" Digital and Tektronix not be used in in advertising or publicity pertaining +.\" to this documentation without specific, written prior permission. +.\" Digital and Tektronix makes no representations about the suitability +.\" of this documentation for any purpose. +.\" It is provided ``as is'' without express or implied warranty. +.\" +\& +.sp 1 +.ce 3 +\s+1\fBChapter 15\fP\s-1 + +\s+1\fBResource Manager Functions\fP\s-1 +.sp 2 +.nr H1 15 +.nr H2 0 +.nr H3 0 +.nr H4 0 +.nr H5 0 +.na +.LP +.XS +Chapter 15: Resource Manager Functions +.XE +A program often needs a variety of options in the X environment +(for example, fonts, colors, icons, and cursors). +Specifying all of these options on the command line is awkward +because users may want to customize many aspects of the program +and need a convenient way to establish these customizations as +the default settings. +The resource manager is provided for this purpose. +Resource specifications are usually stored in human-readable files +and in server properties. +.LP +The resource manager is a database manager with a twist. +In most database systems, +you perform a query using an imprecise specification, +and you get back a set of records. +The resource manager, however, allows you to specify a large +set of values with an imprecise specification, to query the database +with a precise specification, and to get back only a single value. +This should be used by applications that need to know what the +user prefers for colors, fonts, and other resources. +It is this use as a database for dealing with X resources that +inspired the name ``Resource Manager,'' +although the resource manager can be and is used in other ways. +.LP +For example, +a user of your application may want to specify +that all windows should have a blue background +but that all mail-reading windows should have a red background. +With well-engineered and coordinated applications, +a user can define this information using only two lines of specifications. +.LP +As an example of how the resource manager works, +consider a mail-reading application called xmh. +Assume that it is designed so that it uses a +complex window hierarchy all the way down to individual command buttons, +which may be actual small subwindows in some toolkits. +These are often called objects or widgets. +In such toolkit systems, +each user interface object can be composed of other objects +and can be assigned a name and a class. +Fully qualified names or classes can have arbitrary numbers of component names, +but a fully qualified name always has the same number of component names as a +fully qualified class. +This generally reflects the structure of the application as composed +of these objects, starting with the application itself. +.LP +For example, the xmh mail program has a name ``xmh'' and is one +of a class of ``Mail'' programs. +By convention, the first character of class components is capitalized, +and the first letter of name components is in lowercase. +Each name and class finally has an attribute +(for example, ``foreground'' or ``font''). +If each window is properly assigned a name and class, +it is easy for the user to specify attributes of any portion +of the application. +.LP +At the top level, +the application might consist of a paned window (that is, a window divided +into several sections) named ``toc''. +One pane of the paned window is a button box window named ``buttons'' +and is filled with command buttons. +One of these command buttons is used to incorporate +new mail and has the name ``incorporate''. +This window has a fully qualified name, ``xmh.toc.buttons.incorporate'', +and a fully qualified class, ``Xmh.Paned.Box.Command''. +Its fully qualified name is the name of its parent, ``xmh.toc.buttons'', +followed by its name, ``incorporate''. +Its class is the class of its parent, ``Xmh.Paned.Box'', +followed by its particular class, ``Command''. +The fully qualified name of a resource is +the attribute's name appended to the object's fully qualified +name, and the fully qualified class is its class appended to the object's +class. +.LP +The incorporate button might need the following resources: +Title string, +Font, +Foreground color for its inactive state, +Background color for its inactive state, +Foreground color for its active state, and +Background color for its active state. +Each resource is considered +to be an attribute of the button and, as such, has a name and a class. +For example, the foreground color for the button in +its active state might be named ``activeForeground'', +and its class might be ``Foreground''. +.LP +When an application looks up a resource (for example, a color), +it passes the complete name and complete class of the resource +to a look-up routine. +The resource manager compares this complete specification +against the incomplete specifications of entries in the resource +database, finds the best match, and returns the corresponding +value for that entry. +.LP +The definitions for the resource manager are contained in +.hN X11/Xresource.h . +.NH 2 +Resource File Syntax +.XS +\*(SN Resource File Syntax +.XE +.LP +The syntax of a resource file is a sequence of resource lines +terminated by newline characters or the end of the file. +The syntax of an individual resource line is: +.LP +.\" Start marker code here +.Ds 0 +.TA 1.5i 1.75i +.ta 1.5i 1.75i +ResourceLine = Comment | IncludeFile | ResourceSpec | +Comment = "!" {} +IncludeFile = "#" WhiteSpace "include" WhiteSpace FileName WhiteSpace +FileName = +ResourceSpec = WhiteSpace ResourceName WhiteSpace ":" WhiteSpace Value +ResourceName = [Binding] {Component Binding} ComponentName +Binding = "\&." | "*" +WhiteSpace = { | } +Component = "?" | ComponentName +ComponentName = NameChar {NameChar} +NameChar = "a"\-"z" | "A"\-"Z" | "0"\-"9" | "_" | "-" +Value = {} +.De +.\" End marker code here +.LP +Elements separated by vertical bar (|) are alternatives. +Curly braces ({\&.\&.\&.}) indicate zero or more repetitions +of the enclosed elements. +Square brackets ([\&.\&.\&.]) indicate that the enclosed element is optional. +Quotes ("\&.\&.\&.") are used around literal characters. +.LP +IncludeFile lines are interpreted by replacing the line with the +contents of the specified file. +The word ``include'' must be in lowercase. +The file name is interpreted relative to the directory of the file in +which the line occurs (for example, if the file name contains no +directory or contains a relative directory specification). +.LP +If a ResourceName contains a contiguous sequence of two or more Binding +characters, the sequence will be replaced with a single ``\&.'' character +if the sequence contains only ``\&.'' characters; +otherwise, the sequence will be replaced with a single ``*'' character. +.LP +A resource database never contains more than one entry for a given +ResourceName. If a resource file contains multiple lines with the +same ResourceName, the last line in the file is used. +.LP +Any white space characters before or after the name or colon in a ResourceSpec +are ignored. +To allow a Value to begin with white space, +the two-character sequence ``\^\\\^\fIspace\fP'' (backslash followed by space) +is recognized and replaced by a space character, +and the two-character sequence ``\^\\\^\fItab\fP'' +(backslash followed by horizontal tab) +is recognized and replaced by a horizontal tab character. +To allow a Value to contain embedded newline characters, +the two-character sequence ``\^\\\^n'' is recognized and replaced by a +newline character. +To allow a Value to be broken across multiple lines in a text file, +the two-character sequence ``\^\\\^\fInewline\fP'' +(backslash followed by newline) is +recognized and removed from the value. +To allow a Value to contain arbitrary character codes, +the four-character sequence ``\^\\\^\fInnn\fP'', +where each \fIn\fP is a digit character in the range of ``0''\^\-``7'', +is recognized and replaced with a single byte that contains +the octal value specified by the sequence. +Finally, the two-character sequence ``\^\\\\'' is recognized +and replaced with a single backslash. +.LP +As an example of these sequences, +the following resource line contains a value consisting of four +characters: a backslash, a null, a ``z'', and a newline: +.Ds +magic.values: \\\\\\\^000\^\\ +z\\\^n +.De +.NH 2 +Resource Manager Matching Rules +.XS +\*(SN Resource Manager Matching Rules +.XE +.LP +The algorithm for determining which resource database entry +matches a given query is the heart of the resource manager. +All queries must fully specify the name and class of the desired resource +(use of the characters ``*'' and ``?'' is not permitted). +The library supports up to 100 components in a full name or class. +Resources are stored in the database with only partially specified +names and classes, using pattern matching constructs. +An asterisk (*) is a loose binding and is used to represent any number +of intervening components, including none. +A period (.) is a tight binding and is used to separate immediately +adjacent components. +A question mark (?) is used to match any single component name or class. +A database entry cannot end in a loose binding; +the final component (which cannot be the character ``?'') must be specified. +The lookup algorithm searches the database for the entry that most +closely matches (is most specific for) the full name and class being queried. +When more than one database entry matches the full name and class, +precedence rules are used to select just one. +.LP +The full name and class are scanned from left to right (from highest +level in the hierarchy to lowest), one component at a time. +At each level, the corresponding component and/or binding of each +matching entry is determined, and these matching components and +bindings are compared according to precedence rules. +Each of the rules is applied at each level before moving to the next level, +until a rule selects a single entry over all others. +The rules, in order of precedence, are: +.IP 1. 5 +An entry that contains a matching component (whether name, class, +or the character ``?'') +takes precedence over entries that elide the level (that is, entries +that match the level in a loose binding). +.IP 2. 5 +An entry with a matching name takes precedence over both +entries with a matching class and entries that match using the character ``?''. +An entry with a matching class takes precedence over +entries that match using the character ``?''. +.IP 3. 5 +An entry preceded by a tight binding takes precedence over entries +preceded by a loose binding. +.LP +To illustrate these rules, +consider the following resource database entries: +.Ds +.TA 2.5i 3.5i +.ta 2.5i 3.5i +xmh*Paned*activeForeground: red \fI(entry A)\fP +*incorporate.Foreground: blue \fI(entry B)\fP +xmh.toc*Command*activeForeground: green \fI(entry C)\fP +xmh.toc*?.Foreground: white \fI(entry D)\fP +xmh.toc*Command.activeForeground: black \fI(entry E)\fP +.De +.LP +Consider a query for the resource: +.LP +.Ds +.TA 3.5i +.ta 3.5i +xmh.toc.messagefunctions.incorporate.activeForeground \fI(name)\fP +Xmh.Paned.Box.Command.Foreground \fI(class)\fP +.De +.LP +At the first level (xmh, Xmh), rule 1 eliminates entry B. +At the second level (toc, Paned), rule 2 eliminates entry A. +At the third level (messagefunctions, Box), no entries are eliminated. +At the fourth level (incorporate, Command), rule 2 eliminates entry D. +At the fifth level (activeForeground, Foreground), rule 3 eliminates entry C. +.NH 2 +Quarks +.XS +\*(SN Quarks +.XE +.LP +Most uses of the resource manager involve defining names, +classes, and representation types as string constants. +However, always referring to strings in the resource manager can be slow, +because it is so heavily used in some toolkits. +To solve this problem, +a shorthand for a string is used in place of the string +in many of the resource manager functions. +Simple comparisons can be performed rather than string comparisons. +The shorthand name for a string is called a quark and is the +type +.PN XrmQuark . +On some occasions, +you may want to allocate a quark that has no string equivalent. +.LP +A quark is to a string what an atom is to a string in the server, +but its use is entirely local to your application. +.LP +.sp +To allocate a new quark, use +.PN XrmUniqueQuark . +.IN "XrmUniqueQuark" "" "@DEF@" +.sM +.FD 0 +XrmQuark XrmUniqueQuark\^(\|) +.FN +.LP +.eM +The +.PN XrmUniqueQuark +function allocates a quark that is guaranteed not to represent any string that +is known to the resource manager. +.LP +.sp +Each name, class, and representation type is typedef'd as an +.PN XrmQuark . +.LP +.sM +.Ds 0 +typedef int XrmQuark, *XrmQuarkList; +typedef XrmQuark XrmName; +typedef XrmQuark XrmClass; +typedef XrmQuark XrmRepresentation; +#define NULLQUARK ((XrmQuark) 0) +.De +.LP +.eM +Lists are represented as null-terminated arrays of quarks. +The size of the array must be large enough for the number of components used. +.LP +.sM +.Ds 0 +typedef XrmQuarkList XrmNameList; +typedef XrmQuarkList XrmClassList; +.De +.LP +.eM +.sp +To convert a string to a quark, use +.PN XrmStringToQuark +or +.PN XrmPermStringToQuark . +.IN "XrmStringToQuark" "" "@DEF@" +.IN "XrmPermStringToQuark" "" "@DEF@" +.sM +.FD 0 +#define XrmStringToName(string) XrmStringToQuark(string) +#define XrmStringToClass(string) XrmStringToQuark(string) +#define XrmStringToRepresentation(string) XrmStringToQuark(string) +.sp +XrmQuark XrmStringToQuark\^(\^\fIstring\fP\^) +.br + char *\fIstring\fP\^; +.sp +XrmQuark XrmPermStringToQuark\^(\^\fIstring\fP\^) +.br + char *\fIstring\fP\^; +.FN +.ds Ql +.IP \fIstring\fP 1i +Specifies the string for which a quark\*(Ql is to be allocated. +.LP +.eM +These functions can be used to convert from string to quark representation. +If the string is not in the Host Portable Character Encoding, +the conversion is implementation-dependent. +The string argument to +.PN XrmStringToQuark +need not be permanently allocated storage. +.PN XrmPermStringToQuark +is just like +.PN XrmStringToQuark , +except that Xlib is permitted to assume the string argument is permanently +allocated, +and, hence, that it can be used as the value to be returned by +.PN XrmQuarkToString . +.LP +For any given quark, if +.PN XrmStringToQuark +returns a non-NULL value, +all future calls will return the same value (identical address). +.LP +.sp +To convert a quark to a string, use +.PN XrmQuarkToString . +.IN "XrmQuarkToString" "" "@DEF@" +.sM +.FD 0 +#define XrmNameToString(name) XrmQuarkToString(name) +#define XrmClassToString(class) XrmQuarkToString(class) +#define XrmRepresentationToString(type) XrmQuarkToString(type) +.sp +char *XrmQuarkToString\^(\^\fIquark\fP\^) +.br + XrmQuark \fIquark\fP\^; +.FN +.IP \fIquark\fP 1i +Specifies the quark for which the equivalent string is desired. +.LP +.eM +These functions can be used to convert from quark representation to string. +The string pointed to by the return value must not be modified or freed. +The returned string is byte-for-byte equal to the original +string passed to one of the string-to-quark routines. +If no string exists for that quark, +.PN XrmQuarkToString +returns NULL. +For any given quark, if +.PN XrmQuarkToString +returns a non-NULL value, +all future calls will return the same value (identical address). +.LP +.sp +To convert a string with one or more components to a quark list, use +.PN XrmStringToQuarkList . +.IN "XrmStringToQuarkList" "" "@DEF@" +.sM +.FD 0 +#define XrmStringToNameList(str, name) XrmStringToQuarkList((str), (name)) +#define XrmStringToClassList(str, class) XrmStringToQuarkList((str), (class)) +.sp +void XrmStringToQuarkList\^(\^\fIstring\fP, \fIquarks_return\fP\^) +.br + char *\fIstring\fP\^; +.br + XrmQuarkList \fIquarks_return\fP\^; +.FN +.ds Ql \ list +.IP \fIstring\fP 1i +Specifies the string for which a quark\*(Ql is to be allocated. +.IP \fIquarks_return\fP 1i +Returns the list of quarks. +The caller must allocate sufficient space for the quarks list before calling +.PN XrmStringToQuarkList . +.LP +.eM +The +.PN XrmStringToQuarkList +function converts the null-terminated string (generally a fully qualified name) +to a list of quarks. +Note that the string must be in the valid ResourceName format +(see section 15.1). +If the string is not in the Host Portable Character Encoding, +the conversion is implementation-dependent. +.LP +A binding list is a list of type +.PN XrmBindingList +and indicates if components of name or class lists are bound tightly or loosely +(that is, if wildcarding of intermediate components is specified). +.LP +.Ds 0 +typedef enum {XrmBindTightly, XrmBindLoosely} XrmBinding, *XrmBindingList; +.De +.LP +.PN XrmBindTightly +indicates that a period separates the components, and +.PN XrmBindLoosely +indicates that an asterisk separates the components. +.LP +.sp +To convert a string with one or more components to a binding list +and a quark list, use +.PN XrmStringToBindingQuarkList . +.IN "XrmStringToBindingQuarkList" "" "@DEF@" +.sM +.FD 0 +XrmStringToBindingQuarkList\^(\^\fIstring\fP, \fIbindings_return\fP, \ +\fIquarks_return\fP\^) +.br + char *\fIstring\fP\^; +.br + XrmBindingList \fIbindings_return\fP\^; +.br + XrmQuarkList \fIquarks_return\fP\^; +.FN +.ds Ql \ list +.IP \fIstring\fP 1i +Specifies the string for which a quark\*(Ql is to be allocated. +.IP \fIbindings_return\fP 1i +Returns the binding list. +The caller must allocate sufficient space for the binding list before calling +.PN XrmStringToBindingQuarkList . +.IP \fIquarks_return\fP 1i +Returns the list of quarks. +The caller must allocate sufficient space for the quarks list before calling +.PN XrmStringToBindingQuarkList . +.LP +.eM +Component names in the list are separated by a period or +an asterisk character. +The string must be in the format of a valid ResourceName (see section 15.1). +If the string does not start with a period or an asterisk, +a tight binding is assumed. +For example, the string ``*a.b*c'' becomes: +.LP +.Ds 0 +.TA .75i 1.5i 2.25i +.ta .75i 1.5i 2.25i +quarks: a b c +bindings: loose tight loose +.De +.NH 2 +Creating and Storing Databases +.XS +\*(SN Creating and Storing Databases +.XE +.LP +.IN "XrmDatabase" "" "@DEF@" +A resource database is an opaque type, +.PN XrmDatabase . +Each database value is stored in an +.PN XrmValue +structure. +This structure consists of a size, an address, and a representation type. +The size is specified in bytes. +The representation type is a way for you to store data tagged by some +application-defined type (for example, the strings ``font'' or ``color''). +It has nothing to do with the C data type or with its class. +The +.PN XrmValue +structure is defined as: +.LP +.IN "XrmValue" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + unsigned int size; + XPointer addr; +} XrmValue, *XrmValuePtr; +.De +.LP +.eM +.sp +To initialize the resource manager, use +.PN XrmInitialize . +.IN "XrmInitialize" "" "@DEF@" +.sM +.FD 0 +void XrmInitialize\^(\|); +.FN +.LP +.eM +To retrieve a database from disk, use +.PN XrmGetFileDatabase . +.IN "XrmGetFileDatabase" "" "@DEF@" +.sM +.FD 0 +XrmDatabase XrmGetFileDatabase\^(\^\fIfilename\fP\^) +.br + char *\fIfilename\fP\^; +.FN +.IP \fIfilename\fP 1i +Specifies the resource database file name. +.LP +.eM +The +.PN XrmGetFileDatabase +function opens the specified file, +creates a new resource database, and loads it with the specifications +read in from the specified file. +The specified file should contain a sequence of entries in valid ResourceLine +format (see section 15.1); the database that results from reading a file +with incorrect syntax is implementation-dependent. +The file is parsed in the current locale, +and the database is created in the current locale. +If it cannot open the specified file, +.PN XrmGetFileDatabase +returns NULL. +.LP +.sp +To store a copy of a database to disk, use +.PN XrmPutFileDatabase . +.IN "XrmPutFileDatabase" "" "@DEF@" +.sM +.FD 0 +void XrmPutFileDatabase\^(\^\fIdatabase\fP, \fIstored_db\fP\^) +.br + XrmDatabase \fIdatabase\fP\^; +.br + char *\fIstored_db\fP\^; +.FN +.IP \fIdatabase\fP 1i +Specifies the database that is to be used. +.IP \fIstored_db\fP 1i +Specifies the file name for the stored database. +.LP +.eM +The +.PN XrmPutFileDatabase +function stores a copy of the specified database in the specified file. +Text is written to the file as a sequence of entries in valid +ResourceLine format (see section 15.1). +The file is written in the locale of the database. +Entries containing resource names that are not in the Host Portable Character +Encoding or containing values that are not in the encoding of the database +locale, are written in an implementation-dependent manner. +The order in which entries are written is implementation-dependent. +Entries with representation types other than ``String'' are ignored. +.LP +.sp +To obtain a pointer to the screen-independent resources of a display, use +.PN XResourceManagerString . +.IN "XResourceManagerString" "" "@DEF@" +.sM +.FD 0 +char *XResourceManagerString\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +The +.PN XResourceManagerString +function returns the RESOURCE_MANAGER property from the server's root +window of screen zero, which was returned when the connection was opened using +.PN XOpenDisplay . +The property is converted from type STRING to the current locale. +The conversion is identical to that produced by +.PN XmbTextPropertyToTextList +for a single element STRING property. +The returned string is owned by Xlib and should not be freed by the client. +The property value must be in a format that is acceptable to +.PN XrmGetStringDatabase . +If no property exists, NULL is returned. +.LP +.sp +To obtain a pointer to the screen-specific resources of a screen, use +.PN XScreenResourceString . +.IN "XScreenResourceString" "" "@DEF@" +.sM +.FD 0 +char *XScreenResourceString\^(\^\fIscreen\fP\^) +.br + Screen *\fIscreen\fP\^; +.FN +.IP \fIscreen\fP 1i +Specifies the screen. +.LP +.eM +The +.PN XScreenResourceString +function returns the SCREEN_RESOURCES property from the root window of the +specified screen. +The property is converted from type STRING to the current locale. +The conversion is identical to that produced by +.PN XmbTextPropertyToTextList +for a single element STRING property. +The property value must be in a format that is acceptable to +.PN XrmGetStringDatabase . +If no property exists, NULL is returned. +The caller is responsible for freeing the returned string by using +.PN XFree . +.LP +.sp +To create a database from a string, use +.PN XrmGetStringDatabase . +.IN "XrmGetStringDatabase" "" "@DEF@" +.sM +.FD 0 +XrmDatabase XrmGetStringDatabase\^(\^\fIdata\fP\^) +.br + char *\fIdata\fP\^; +.FN +.IP \fIdata\fP 1i +Specifies the database contents using a string. +.LP +.eM +The +.PN XrmGetStringDatabase +function creates a new database and stores the resources specified +in the specified null-terminated string. +.PN XrmGetStringDatabase +is similar to +.PN XrmGetFileDatabase +except that it reads the information out of a string instead of out of a file. +The string should contain a sequence of entries in valid ResourceLine +format (see section 15.1) terminated by a null character; +the database that results from using a string +with incorrect syntax is implementation-dependent. +The string is parsed in the current locale, +and the database is created in the current locale. +.LP +.sp +To obtain the locale name of a database, use +.PN XrmLocaleOfDatabase . +.IN "XrmLocaleOfDatabase" "" "@DEF@" +.sM +.FD 0 +char *XrmLocaleOfDatabase\^(\^\fIdatabase\fP\^) +.br + XrmDatabase \fIdatabase\fP\^; +.FN +.IP \fIdatabase\fP 1i +Specifies the resource database. +.LP +.eM +The +.PN XrmLocaleOfDatabase +function returns the name of the locale bound to the specified +database, as a null-terminated string. +The returned locale name string is owned by Xlib and should not be +modified or freed by the client. +Xlib is not permitted to free the string until the database is destroyed. +Until the string is freed, +it will not be modified by Xlib. +.LP +.sp +To destroy a resource database and free its allocated memory, use +.PN XrmDestroyDatabase . +.IN "XrmDestroyDatabase" "" "@DEF@" +.sM +.FD 0 +void XrmDestroyDatabase\^(\^\fIdatabase\fP\^) +.br + XrmDatabase \fIdatabase\fP\^; +.FN +.IP \fIdatabase\fP 1i +Specifies the resource database. +.LP +.eM +If database is NULL, +.PN XrmDestroyDatabase +returns immediately. +.LP +.sp +To associate a resource database with a display, use +.PN XrmSetDatabase . +.IN "XrmSetDatabase" "" "@DEF@" +.sM +.FD 0 +void XrmSetDatabase\^(\^\fIdisplay\fP\^, \fIdatabase\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XrmDatabase \fIdatabase\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIdatabase\fP 1i +Specifies the resource database. +.LP +.eM +The +.PN XrmSetDatabase +function associates the specified resource database (or NULL) +with the specified display. +The database previously associated with the display (if any) is not destroyed. +A client or toolkit may find this function convenient for retaining a database +once it is constructed. +.LP +.sp +To get the resource database associated with a display, use +.PN XrmGetDatabase . +.IN "XrmGetDatabase" "" "@DEF@" +.sM +.FD 0 +XrmDatabase XrmGetDatabase\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +The +.PN XrmGetDatabase +function returns the database associated with the specified display. +It returns NULL if a database has not yet been set. +.NH 2 +Merging Resource Databases +.XS +\*(SN Merging Resource Databases +.XE +.LP +To merge the contents of a resource file into a database, use +.PN XrmCombineFileDatabase . +.IN "XrmCombineFileDatabase" "" "@DEF@" +.sM +.FD 0 +Status XrmCombineFileDatabase(\^\fIfilename\fP, \fItarget_db\fP, \fIoverride\fP\^) +.br + char *\fIfilename\fP; +.br + XrmDatabase *\fItarget_db\fP\^; +.br + Bool \fIoverride\fP; +.FN +.IP \fIfilename\fP 1i +Specifies the resource database file name. +.IP \fItarget_db\fP 1i +Specifies the resource database into which the source +database is to be merged. +.IP \fIoverride\fP 1i +Specifies whether source entries override target ones. +.LP +.eM +The +.PN XrmCombineFileDatabase +function merges the contents of a resource file into a database. +If the same specifier is used for an entry in both the file and +the database, +the entry in the file will replace the entry in the database +if override is +.PN True ; +otherwise, the entry in the file is discarded. +The file is parsed in the current locale. +If the file cannot be read, +a zero status is returned; +otherwise, a nonzero status is returned. +If target_db contains NULL, +.PN XrmCombineFileDatabase +creates and returns a new database to it. +Otherwise, the database pointed to by target_db is not destroyed by the merge. +The database entries are merged without changing values or types, +regardless of the locale of the database. +The locale of the target database is not modified. +.LP +.sp +To merge the contents of one database into another database, use +.PN XrmCombineDatabase . +.IN "XrmCombineDatabase" "" "@DEF@" +.sM +.FD 0 +void XrmCombineDatabase(\^\fIsource_db\fP, \fItarget_db\fP, \fIoverride\fP\^) +.br + XrmDatabase \fIsource_db\fP, *\fItarget_db\fP\^; +.br + Bool \fIoverride\fP; +.FN +.IP \fIsource_db\fP 1i +Specifies the resource database that is to be merged into the target database. +.IP \fItarget_db\fP 1i +Specifies the resource database into which the source +database is to be merged. +.IP \fIoverride\fP 1i +Specifies whether source entries override target ones. +.LP +.eM +The +.PN XrmCombineDatabase +function merges the contents of one database into another. +If the same specifier is used for an entry in both databases, +the entry in the source_db will replace the entry in the target_db +if override is +.PN True ; +otherwise, the entry in source_db is discarded. +If target_db contains NULL, +.PN XrmCombineDatabase +simply stores source_db in it. +Otherwise, source_db is destroyed by the merge, but the database pointed +to by target_db is not destroyed. +The database entries are merged without changing values or types, +regardless of the locales of the databases. +The locale of the target database is not modified. +.LP +.sp +To merge the contents of one database into another database with override +semantics, use +.PN XrmMergeDatabases . +.IN "XrmMergeDatabases" "" "@DEF@" +.sM +.FD 0 +void XrmMergeDatabases(\^\fIsource_db\fP, \fItarget_db\fP\^) +.br + XrmDatabase \fIsource_db\fP, *\fItarget_db\fP\^; +.FN +.IP \fIsource_db\fP 1i +Specifies the resource database that is to be merged into the target database. +.IP \fItarget_db\fP 1i +Specifies the resource database into which the source +database is to be merged. +.LP +.eM +Calling the +.PN XrmMergeDatabases +function is equivalent to calling the +.PN XrmCombineDatabase +function with an override argument of +.PN True . +.NH 2 +Looking Up Resources +.XS +\*(SN Looking Up Resources +.XE +.LP +To retrieve a resource from a resource database, use +.PN XrmGetResource , +.PN XrmQGetResource , +or +.PN XrmQGetSearchResource . +.LP +.sp +.IN "XrmGetResource" "" "@DEF@" +.sM +.FD 0 +Bool XrmGetResource\^(\^\fIdatabase\fP, \fIstr_name\fP, \fIstr_class\fP, \ +\fIstr_type_return\fP, \fIvalue_return\fP\^) +.br + XrmDatabase \fIdatabase\fP\^; +.br + char *\fIstr_name\fP\^; +.br + char *\fIstr_class\fP\^; +.br + char **\fIstr_type_return\fP\^; +.br + XrmValue *\fIvalue_return\fP\^; +.FN +.IP \fIdatabase\fP 1i +Specifies the database that is to be used. +.IP \fIstr_name\fP 1i +Specifies the fully qualified name of the value being retrieved (as a string). +.IP \fIstr_class\fP 1i +Specifies the fully qualified class of the value being retrieved (as a string). +.IP \fIstr_type_return\fP 1i +Returns the representation type of the destination (as a string). +.IP \fIvalue_return\fP 1i +Returns the value in the database. +.LP +.eM +.sp +.IN "XrmQGetResource" "" "@DEF@" +.sM +.FD 0 +Bool XrmQGetResource\^(\^\fIdatabase\fP, \fIquark_name\fP, \fIquark_class\fP, \ +\fIquark_type_return\fP, \fIvalue_return\fP\^) +.br + XrmDatabase \fIdatabase\fP\^; +.br + XrmNameList \fIquark_name\fP\^; +.br + XrmClassList \fIquark_class\fP\^; +.br + XrmRepresentation *\fIquark_type_return\fP\^; +.br + XrmValue *\fIvalue_return\fP\^; +.FN +.IP \fIdatabase\fP 1i +Specifies the database that is to be used. +.IP \fIquark_name\fP 1i +Specifies the fully qualified name of the value being retrieved (as a quark). +.IP \fIquark_class\fP 1i +Specifies the fully qualified class of the value being retrieved (as a quark). +.IP \fIquark_type_return\fP 1i +Returns the representation type of the destination (as a quark). +.IP \fIvalue_return\fP 1i +Returns the value in the database. +.LP +.eM +The +.PN XrmGetResource +and +.PN XrmQGetResource +functions retrieve a resource from the specified database. +Both take a fully qualified name/class pair, a destination +resource representation, and the address of a value +(size/address pair). +The value and returned type point into database memory; +therefore, you must not modify the data. +.LP +The database only frees or overwrites entries on +.PN XrmPutResource , +.PN XrmQPutResource , +or +.PN XrmMergeDatabases . +A client that is not storing new values into the database or +is not merging the database should be safe using the address passed +back at any time until it exits. +If a resource was found, both +.PN XrmGetResource +and +.PN XrmQGetResource +return +.PN True ; +otherwise, they return +.PN False . +.LP +.sp +.EQ +delim %% +.EN +Most applications and toolkits do not make random probes +into a resource database to fetch resources. +The X toolkit access pattern for a resource database is quite stylized. +A series of from 1 to 20 probes is made with only the +last name/class differing in each probe. +The +.PN XrmGetResource +function is at worst a %2 sup n% algorithm, +where \fIn\fP is the length of the name/class list. +This can be improved upon by the application programmer by prefetching a list +of database levels that might match the first part of a name/class list. +.LP +.sp +To obtain a list of database levels, use +.PN XrmQGetSearchList . +.IN "XrmQGetSearchList" "" "@DEF@" +.sM +.FD 0 +typedef XrmHashTable *XrmSearchList; +.sp +Bool XrmQGetSearchList\^(\^\fIdatabase\fP, \fInames\fP, \fIclasses\fP, \ +\fIlist_return\fP, \fIlist_length\fP\^) +.br + XrmDatabase \fIdatabase\fP\^; +.br + XrmNameList \fInames\fP\^; +.br + XrmClassList \fIclasses\fP\^; +.br + XrmSearchList \fIlist_return\fP\^; +.br + int \fIlist_length\fP\^; +.FN +.IP \fIdatabase\fP 1i +Specifies the database that is to be used. +.IP \fInames\fP 1i +Specifies a list of resource names. +.IP \fIclasses\fP 1i +Specifies a list of resource classes. +.IP \fIlist_return\fP 1i +Returns a search list for further use. +The caller must allocate sufficient space for the list before calling +.PN XrmQGetSearchList . +.IP \fIlist_length\fP 1i +Specifies the number of entries (not the byte size) allocated for list_return. +.LP +.eM +The +.PN XrmQGetSearchList +function takes a list of names and classes +and returns a list of database levels where a match might occur. +The returned list is in best-to-worst order and +uses the same algorithm as +.PN XrmGetResource +for determining precedence. +If list_return was large enough for the search list, +.PN XrmQGetSearchList +returns +.PN True ; +otherwise, it returns +.PN False . +.LP +The size of the search list that the caller must allocate is +dependent upon the number of levels and wildcards in the resource specifiers +that are stored in the database. +The worst case length is %3 sup n%, +where \fIn\fP is the number of name or class components in names or classes. +.LP +When using +.PN XrmQGetSearchList +followed by multiple probes for resources with a common name and class prefix, +only the common prefix should be specified in the name and class list to +.PN XrmQGetSearchList . +.LP +.sp +To search resource database levels for a given resource, use +.PN XrmQGetSearchResource . +.IN "XrmQGetSearchResource" "" "@DEF@" +.sM +.FD 0 +Bool XrmQGetSearchResource\^(\^\fIlist\fP, \fIname\fP, \fIclass\fP, \ +\fItype_return\fP, \fIvalue_return\fP\^) +.br + XrmSearchList \fIlist\fP\^; +.br + XrmName \fIname\fP\^; +.br + XrmClass \fIclass\fP\^; +.br + XrmRepresentation *\fItype_return\fP\^; +.br + XrmValue *\fIvalue_return\fP\^; +.FN +.IP \fIlist\fP 1i +Specifies the search list returned by +.PN XrmQGetSearchList . +.IP \fIname\fP 1i +Specifies the resource name. +.IP \fIclass\fP 1i +Specifies the resource class. +.IP \fItype_return\fP 1i +Returns data representation type. +.IP \fIvalue_return\fP 1i +Returns the value in the database. +.LP +.eM +The +.PN XrmQGetSearchResource +function searches the specified database levels for the resource +that is fully identified by the specified name and class. +The search stops with the first match. +.PN XrmQGetSearchResource +returns +.PN True +if the resource was found; +otherwise, it returns +.PN False . +.LP +A call to +.PN XrmQGetSearchList +with a name and class list containing all but the last component +of a resource name followed by a call to +.PN XrmQGetSearchResource +with the last component name and class returns the same database entry as +.PN XrmGetResource +and +.PN XrmQGetResource +with the fully qualified name and class. +.NH 2 +Storing into a Resource Database +.XS +\*(SN Storing into a Resource Database +.XE +.LP +To store resources into the database, use +.PN XrmPutResource +or +.PN XrmQPutResource . +Both functions take a partial resource specification, a +representation type, and a value. +This value is copied into the specified database. +.LP +.sp +.IN "XrmPutResource" "" "@DEF@" +.sM +.FD 0 +void XrmPutResource\^(\^\fIdatabase\fP, \fIspecifier\fP, \fItype\fP, \fIvalue\fP\^) +.br + XrmDatabase *\fIdatabase\fP\^; +.br + char *\fIspecifier\fP\^; +.br + char *\fItype\fP\^; +.br + XrmValue *\fIvalue\fP\^; +.FN +.IP \fIdatabase\fP 1i +Specifies the resource database. +.IP \fIspecifier\fP 1i +Specifies a complete or partial specification of the resource. +.IP \fItype\fP 1i +Specifies the type of the resource. +.IP \fIvalue\fP 1i +Specifies the value of the resource, which is specified as a string. +.LP +.eM +If database contains NULL, +.PN XrmPutResource +creates a new database and returns a pointer to it. +.PN XrmPutResource +is a convenience function that calls +.PN XrmStringToBindingQuarkList +followed by: +.LP +.Ds +XrmQPutResource(database, bindings, quarks, XrmStringToQuark(type), value) +.De +If the specifier and type are not in the Host Portable Character Encoding, +the result is implementation-dependent. +The value is stored in the database without modification. +.LP +.sp +.IN "XrmQPutResource" "" "@DEF@" +.sM +.FD 0 +void XrmQPutResource\^(\^\fIdatabase\fP, \fIbindings\fP, \fIquarks\fP, \ +\fItype\fP, \fIvalue\fP\^) +.br + XrmDatabase *\fIdatabase\fP\^; +.br + XrmBindingList \fIbindings\fP\^; +.br + XrmQuarkList \fIquarks\fP\^; +.br + XrmRepresentation \fItype\fP\^; +.br + XrmValue *\fIvalue\fP\^; +.FN +.IP \fIdatabase\fP 1i +Specifies the resource database. +.IP \fIbindings\fP 1i +Specifies a list of bindings. +.IP \fIquarks\fP 1i +Specifies the complete or partial name or the class list of the resource. +.IP \fItype\fP 1i +Specifies the type of the resource. +.IP \fIvalue\fP 1i +Specifies the value of the resource, which is specified as a string. +.LP +.eM +If database contains NULL, +.PN XrmQPutResource +creates a new database and returns a pointer to it. +If a resource entry with the identical bindings and quarks already +exists in the database, the previous type and value are replaced by the new +specified type and value. +The value is stored in the database without modification. +.LP +.sp +To add a resource that is specified as a string, use +.PN XrmPutStringResource . +.IN "XrmPutStringResource" "" "@DEF@" +.sM +.FD 0 +void XrmPutStringResource\^(\^\fIdatabase\fP, \fIspecifier\fP, \fIvalue\fP\^) +.br + XrmDatabase *\fIdatabase\fP\^; +.br + char *\fIspecifier\fP\^; +.br + char *\fIvalue\fP\^; +.FN +.IP \fIdatabase\fP 1i +Specifies the resource database. +.IP \fIspecifier\fP 1i +Specifies a complete or partial specification of the resource. +.IP \fIvalue\fP 1i +Specifies the value of the resource, which is specified as a string. +.LP +.eM +If database contains NULL, +.PN XrmPutStringResource +creates a new database and returns a pointer to it. +.PN XrmPutStringResource +adds a resource with the specified value to the specified database. +.PN XrmPutStringResource +is a convenience function that first calls +.PN XrmStringToBindingQuarkList +on the specifier and then calls +.PN XrmQPutResource , +using a ``String'' representation type. +If the specifier is not in the Host Portable Character Encoding, +the result is implementation-dependent. +The value is stored in the database without modification. +.LP +.sp +To add a string resource using quarks as a specification, use +.PN XrmQPutStringResource . +.IN "XrmQPutStringResource" "" "@DEF@" +.sM +.FD 0 +void XrmQPutStringResource\^(\^\fIdatabase\fP, \fIbindings\fP, \fIquarks\fP, \ +\fIvalue\fP\^) +.br + XrmDatabase *\fIdatabase\fP\^; +.br + XrmBindingList \fIbindings\fP\^; +.br + XrmQuarkList \fIquarks\fP\^; +.br + char *\fIvalue\fP\^; +.FN +.IP \fIdatabase\fP 1i +Specifies the resource database. +.IP \fIbindings\fP 1i +Specifies a list of bindings. +.IP \fIquarks\fP 1i +Specifies the complete or partial name or the class list of the resource. +.IP \fIvalue\fP 1i +Specifies the value of the resource, which is specified as a string. +.LP +.eM +If database contains NULL, +.PN XrmQPutStringResource +creates a new database and returns a pointer to it. +.PN XrmQPutStringResource +is a convenience routine that constructs an +.PN XrmValue +for the value string (by calling +.PN strlen +to compute the size) and +then calls +.PN XrmQPutResource , +using a ``String'' representation type. +The value is stored in the database without modification. +.LP +.sp +To add a single resource entry that is specified as a string that contains +both a name and a value, use +.PN XrmPutLineResource . +.IN "XrmPutLineResource" "" "@DEF@" +.sM +.FD 0 +void XrmPutLineResource\^(\^\fIdatabase\fP, \fIline\fP\^) +.br + XrmDatabase *\fIdatabase\fP\^; +.br + char *\fIline\fP\^; +.FN +.IP \fIdatabase\fP 1i +Specifies the resource database. +.IP \fIline\fP 1i +Specifies the resource name and value pair as a single string. +.LP +.eM +If database contains NULL, +.PN XrmPutLineResource +creates a new database and returns a pointer to it. +.PN XrmPutLineResource +adds a single resource entry to the specified database. +The line should be in valid ResourceLine format (see section 15.1) +terminated by a newline or null character; +the database that results from using a string +with incorrect syntax is implementation-dependent. +The string is parsed in the locale of the database. +If the +.PN ResourceName +is not in the Host Portable Character Encoding, +the result is implementation-dependent. +Note that comment lines are not stored. +.NH 2 +Enumerating Database Entries +.XS +\*(SN Enumerating Database Entries +.XE +.LP +To enumerate the entries of a database, use +.PN XrmEnumerateDatabase . +.IN "XrmEnumerateDatabase" "" "@DEF@" +.sM +.TS +lw(.5i) lw(2i) lw(2.5i). +T{ +#define +T} T{ +.PN XrmEnumAllLevels +T} T{ +0 +T} +T{ +#define +T} T{ +.PN XrmEnumOneLevel +T} T{ +1 +T} +.TE +.FD 0 +Bool XrmEnumerateDatabase\^(\^\fIdatabase\fP, \fIname_prefix\fP, \fIclass_prefix\fP, \fImode\fP, \fIproc\fP, \fIarg\fP\^) +.br + XrmDatabase \fIdatabase\fP\^; +.br + XrmNameList \fIname_prefix\fP\^; +.br + XrmClassList \fIclass_prefix\fP\^; +.br + int \fImode\fP\^; +.br + Bool (\^*\fIproc\fP\^)\^(\^)\^; +.br + XPointer \fIarg\fP\^; +.FN +.IP \fIdatabase\fP 1i +Specifies the resource database. +.IP \fIname_prefix\fP 1i +Specifies the resource name prefix. +.IP \fIclass_prefix\fP 1i +Specifies the resource class prefix. +.IP \fImode\fP 1i +Specifies the number of levels to enumerate. +.IP \fIproc\fP 1i +Specifies the procedure that is to be called for each matching entry. +.IP \fIarg\fP 1i +Specifies the user-supplied argument that will be passed to the procedure. +.LP +.eM +The +.PN XrmEnumerateDatabase +function calls the specified procedure for each resource in the database +that would match some completion of the given name/class resource prefix. +The order in which resources are found is implementation-dependent. +If mode is +.PN XrmEnumOneLevel , +a resource must match the given name/class prefix with +just a single name and class appended. If mode is +.PN XrmEnumAllLevels , +the resource must match the given name/class prefix with one or more names and +classes appended. +If the procedure returns +.PN True , +the enumeration terminates and the function returns +.PN True . +If the procedure always returns +.PN False , +all matching resources are enumerated and the function returns +.PN False . +.LP +The procedure is called with the following arguments: +.LP +.\" Start marker code here +.Ds 0 +.TA .5i 3i +.ta .5i 3i +(*\fIproc\fP\^)(\^\fIdatabase\fP, \fIbindings\fP, \fIquarks\fP, \fItype\fP, \fIvalue\fP, \fIarg\fP\^) + XrmDatabase *\fIdatabase\fP\^; + XrmBindingList \fIbindings\fP\^; + XrmQuarkList \fIquarks\fP\^; + XrmRepresentation *\fItype\fP\^; + XrmValue *\fIvalue\fP\^; + XPointer \fIarg\fP\^; +.De +.\" End marker code here +.LP +The bindings and quarks lists are terminated by +.PN NULLQUARK . +Note that pointers +to the database and type are passed, but these values should not be modified. +.LP +The procedure must not modify the database. +If Xlib has been initialized for threads, the procedure is called with +the database locked and the result of a call by the procedure to any +Xlib function using the same database is not defined. +.NH 2 +Parsing Command Line Options +.XS +\*(SN Parsing Command Line Options +.XE +.LP +The +.PN XrmParseCommand +function can be used to parse the command line arguments to a program +and modify a resource database with selected entries from the command line. +.LP +.IN "XrmOptionKind" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef enum { + XrmoptionNoArg, /* Value is specified in XrmOptionDescRec.value */ + XrmoptionIsArg, /* Value is the option string itself */ + XrmoptionStickyArg, /* Value is characters immediately following option */ + XrmoptionSepArg, /* Value is next argument in argv */ + XrmoptionResArg, /* Resource and value in next argument in argv */ + XrmoptionSkipArg, /* Ignore this option and the next argument in argv */ + XrmoptionSkipLine, /* Ignore this option and the rest of argv */ + XrmoptionSkipNArgs /* Ignore this option and the next + \ \ \ XrmOptionDescRec.value arguments in argv */ +} XrmOptionKind; +.De +.LP +.eM +Note that +.PN XrmoptionSkipArg +is equivalent to +.PN XrmoptionSkipNArgs +with the +.PN XrmOptionDescRec.value +field containing the value one. +Note also that the value zero for +.PN XrmoptionSkipNArgs +indicates that only the option itself is to be skipped. +.LP +.IN "XrmOptionDescRec" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef struct { + char *option; /* Option specification string in argv */ + char *specifier; /* Binding and resource name (sans application name) */ + XrmOptionKind argKind; /* Which style of option it is */ + XPointer value; /* Value to provide if XrmoptionNoArg or + \ \ \ XrmoptionSkipNArgs */ +} XrmOptionDescRec, *XrmOptionDescList; +.De +.LP +.eM +.sp +To load a resource database from a C command line, use +.PN XrmParseCommand . +.IN "XrmParseCommand" "" "@DEF@" +.sM +.FD 0 +void XrmParseCommand\^(\^\fIdatabase\fP\^, \^\fItable\fP\^, \^\fItable_count\fP\^, \ +\^\fIname\fP\^, \^\fIargc_in_out\fP\^, \^\fIargv_in_out\fP\^) +.br + XrmDatabase *\fIdatabase\fP\^; +.br + XrmOptionDescList \fItable\fP\^; +.br + int \fItable_count\fP\^; +.br + char *\fIname\fP\^; +.br + int *\fIargc_in_out\fP\^; +.br + char **\fIargv_in_out\fP\^; +.FN +.IP \fIdatabase\fP 1i +Specifies the resource database. +.IP \fItable\fP 1i +Specifies the table of command line arguments to be parsed. +.IP \fItable_count\fP 1i +Specifies the number of entries in the table. +.IP \fIname\fP 1i +Specifies the application name. +.IP \fIargc_in_out\fP 1i +Specifies the number of arguments and returns the number of remaining arguments. +.IP \fIargv_in_out\fP 1i +Specifies the command line arguments +and returns the remaining arguments. +.LP +.eM +The +.PN XrmParseCommand +function parses an (argc, argv) pair according to the specified option table, +loads recognized options into the specified database with type ``String,'' +and modifies the (argc, argv) pair to remove all recognized options. +If database contains NULL, +.PN XrmParseCommand +creates a new database and returns a pointer to it. +Otherwise, entries are added to the database specified. +If a database is created, it is created in the current locale. +.LP +The specified table is used to parse the command line. +Recognized options in the table are removed from argv, +and entries are added to the specified resource database +in the order they occur in argv. +The table entries contain information on the option string, +the option name, the style of option, +and a value to provide if the option kind is +.PN XrmoptionNoArg . +The option names are compared byte-for-byte to arguments in argv, +independent of any locale. +The resource values given in the table are stored in the resource database +without modification. +All resource database entries are created +using a ``String'' representation type. +The argc argument specifies the number of arguments in argv +and is set on return to the remaining number of arguments that were not parsed. +The name argument should be the name of your application +for use in building the database entry. +The name argument is prefixed to the resourceName in the option table +before storing a database entry. +The name argument is treated as a single component, even if it +has embedded periods. +No separating (binding) character is inserted, +so the table must contain either a period (.) or an asterisk (*) +as the first character in each resourceName entry. +To specify a more completely qualified resource name, +the resourceName entry can contain multiple components. +If the name argument and the resourceNames are not in the +Host Portable Character Encoding, +the result is implementation-dependent. +.LP +The following provides a sample option table: +.LP +.Ds 0 +.TA 1.25i 3.25i 4.75i +.ta 1.25i 3.25i 4.75i +static XrmOptionDescRec opTable[] = { +{"\-background", "*background", XrmoptionSepArg, (XPointer) NULL}, +{"\-bd", "*borderColor", XrmoptionSepArg, (XPointer) NULL}, +{"\-bg", "*background", XrmoptionSepArg, (XPointer) NULL}, +{"\-borderwidth", "*TopLevelShell.borderWidth", XrmoptionSepArg, (XPointer) NULL}, +{"\-bordercolor", "*borderColor", XrmoptionSepArg, (XPointer) NULL}, +{"\-bw", "*TopLevelShell.borderWidth", XrmoptionSepArg, (XPointer) NULL}, +{"\-display", ".display", XrmoptionSepArg, (XPointer) NULL}, +{"\-fg", "*foreground", XrmoptionSepArg, (XPointer) NULL}, +{"\-fn", "*font", XrmoptionSepArg, (XPointer) NULL}, +{"\-font", "*font", XrmoptionSepArg, (XPointer) NULL}, +{"\-foreground", "*foreground", XrmoptionSepArg, (XPointer) NULL}, +{"\-geometry", ".TopLevelShell.geometry", XrmoptionSepArg, (XPointer) NULL}, +{"\-iconic", ".TopLevelShell.iconic", XrmoptionNoArg, (XPointer) "on"}, +{"\-name", ".name", XrmoptionSepArg, (XPointer) NULL}, +{"\-reverse", "*reverseVideo", XrmoptionNoArg, (XPointer) "on"}, +{"\-rv", "*reverseVideo", XrmoptionNoArg, (XPointer) "on"}, +{"\-synchronous", "*synchronous", XrmoptionNoArg, (XPointer) "on"}, +{"\-title", ".TopLevelShell.title", XrmoptionSepArg, (XPointer) NULL}, +{"\-xrm", NULL, XrmoptionResArg, (XPointer) NULL}, +}; +.De +.LP +In this table, if the \-background (or \-bg) option is used to set +background colors, the stored resource specifier matches all +resources of attribute background. +If the \-borderwidth option is used, +the stored resource specifier applies only to border width +attributes of class TopLevelShell (that is, outer-most windows, including +pop-up windows). +If the \-title option is used to set a window name, +only the topmost application windows receive the resource. +.LP +When parsing the command line, +any unique unambiguous abbreviation for an option name in the table is +considered a match for the option. +Note that uppercase and lowercase matter. +.bp diff --git a/libX11/specs/libX11/CH16 b/libX11/specs/libX11/CH16 new file mode 100644 index 000000000..3a21a2290 --- /dev/null +++ b/libX11/specs/libX11/CH16 @@ -0,0 +1,2364 @@ +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be included +.\" in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR +.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +.\" OTHER DEALINGS IN THE SOFTWARE. +.\" +.\" Except as contained in this notice, the name of the X Consortium shall +.\" not be used in advertising or otherwise to promote the sale, use or +.\" other dealings in this Software without prior written authorization +.\" from the X Consortium. +.\" +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by +.\" Digital Equipment Corporation +.\" +.\" Portions Copyright \(co 1990, 1991 by +.\" Tektronix, Inc. +.\" +.\" Permission to use, copy, modify and distribute this documentation for +.\" any purpose and without fee is hereby granted, provided that the above +.\" copyright notice appears in all copies and that both that copyright notice +.\" and this permission notice appear in all copies, and that the names of +.\" Digital and Tektronix not be used in in advertising or publicity pertaining +.\" to this documentation without specific, written prior permission. +.\" Digital and Tektronix makes no representations about the suitability +.\" of this documentation for any purpose. +.\" It is provided ``as is'' without express or implied warranty. +.\" +\& +.sp 1 +.ce 3 +\s+1\fBChapter 16\fP\s-1 + +\s+1\fBApplication Utility Functions\fP\s-1 +.sp 2 +.nr H1 16 +.nr H2 0 +.nr H3 0 +.nr H4 0 +.nr H5 0 +.na +.LP +.XS +Chapter 16: Application Utility Functions +.XE +Once you have initialized the X system, +you can use the Xlib utility functions to: +.IP \(bu 5 +Use keyboard utility functions +.IP \(bu 5 +Use Latin-1 keyboard event functions +.IP \(bu 5 +Allocate permanent storage +.IP \(bu 5 +Parse the window geometry +.IP \(bu 5 +Manipulate regions +.IP \(bu 5 +Use cut buffers +.IP \(bu 5 +Determine the appropriate visual type +.IP \(bu 5 +Manipulate images +.IP \(bu 5 +Manipulate bitmaps +.IP \(bu 5 +Use the context manager +.LP +As a group, +the functions discussed in this chapter provide the functionality that +is frequently needed and that spans toolkits. +Many of these functions do not generate actual protocol requests to the server. +.NH 2 +Using Keyboard Utility Functions +.XS +\*(SN Using Keyboard Utility Functions +.XE +.LP +This section discusses mapping between KeyCodes and KeySyms, +classifying KeySyms, and mapping between KeySyms and string names. +The first three functions in this section operate on a cached copy of the +server keyboard mapping. +The first four KeySyms for each KeyCode +are modified according to the rules given in section 12.7. +To obtain the untransformed KeySyms defined for a key, +use the functions described in section 12.7. +.LP +.sp +To obtain a KeySym for the KeyCode of an event, use +.PN XLookupKeysym . +.IN "XLookupKeysym" "" "@DEF@" +.sM +.FD 0 +KeySym XLookupKeysym(\^\fIkey_event\fP, \fIindex\fP\^) +.br + XKeyEvent *\fIkey_event\fP\^; +.br + int \fIindex\fP\^; +.FN +.IP \fIkey_event\fP 1i +Specifies the +.PN KeyPress +or +.PN KeyRelease +event. +.IP \fIindex\fP 1i +Specifies the index into the KeySyms list for the event's KeyCode. +.LP +.eM +The +.PN XLookupKeysym +function uses a given keyboard event and the index you specified to return +the KeySym from the list that corresponds to the KeyCode member in the +.PN XKeyPressedEvent +or +.PN XKeyReleasedEvent +structure. +If no KeySym is defined for the KeyCode of the event, +.PN XLookupKeysym +returns +.PN NoSymbol . +.LP +.sp +To obtain a KeySym for a specific KeyCode, use +.PN XKeycodeToKeysym . +.IN "XKeycodeToKeysym" "" "@DEF@" +.sM +.FD 0 +KeySym XKeycodeToKeysym\^(\^\fIdisplay\fP, \fIkeycode\fP, \fIindex\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + KeyCode \fIkeycode\fP\^; +.br + int \fIindex\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIkeycode\fP 1i +Specifies the KeyCode. +.IP \fIindex\fP 1i +Specifies the element of KeyCode vector. +.LP +.eM +The +.PN XKeycodeToKeysym +function uses internal Xlib tables +and returns the KeySym defined for the specified KeyCode and +the element of the KeyCode vector. +If no symbol is defined, +.PN XKeycodeToKeysym +returns +.PN NoSymbol . +.LP +.sp +To obtain a KeyCode for a key having a specific KeySym, use +.PN XKeysymToKeycode . +.IN "XKeysymToKeycode" "" "@DEF@" +.sM +.FD 0 +KeyCode XKeysymToKeycode\^(\^\fIdisplay\fP, \fIkeysym\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + KeySym \fIkeysym\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIkeysym\fP 1i +Specifies the KeySym that is to be searched for. +.LP +.eM +If the specified KeySym is not defined for any KeyCode, +.PN XKeysymToKeycode +returns zero. +.LP +.sp +The mapping between KeyCodes and KeySyms is cached internal to Xlib. +When this information is changed at the server, an Xlib function must +be called to refresh the cache. +To refresh the stored modifier and keymap information, use +.PN XRefreshKeyboardMapping . +.IN "XRefreshKeyboardMapping" "" "@DEF@" +.sM +.FD 0 +XRefreshKeyboardMapping(\^\fIevent_map\fP\^) +.br + XMappingEvent *\fIevent_map\fP\^; +.FN +.IP \fIevent_map\fP 1i +Specifies the mapping event that is to be used. +.LP +.eM +The +.PN XRefreshKeyboardMapping +function refreshes the stored modifier and keymap information. +You usually call this function when a +.PN MappingNotify +event with a request member of +.PN MappingKeyboard +or +.PN MappingModifier +occurs. +The result is to update Xlib's knowledge of the keyboard. +.LP +.sp +To obtain the uppercase and lowercase forms of a KeySym, use +.PN XConvertCase . +.IN "XConvertCase" "" "@DEF@" +.sM +.FD 0 +void XConvertCase(\^\fIkeysym\fP, \fIlower_return\fP, \fIupper_return\fP\^) +.br + KeySym \fIkeysym\fP\^; +.br + KeySym *\fIlower_return\fP\^; +.br + KeySym *\fIupper_return\fP\^; +.FN +.ds Fn converted +.IP \fIkeysym\fP 1i +Specifies the KeySym that is to be \*(Fn. +.IP \fIlower_return\fP 1i +Returns the lowercase form of keysym, or keysym. +.IP \fIupper_return\fP 1i +Returns the uppercase form of keysym, or keysym. +.LP +.eM +The +.PN XConvertCase +function returns the uppercase and lowercase forms of the specified Keysym, +if the KeySym is subject to case conversion; +otherwise, the specified KeySym is returned to both lower_return and +upper_return. +Support for conversion of other than Latin and Cyrillic KeySyms is +implementation-dependent. +.LP +.sp +KeySyms have string names as well as numeric codes. +To convert the name of the KeySym to the KeySym code, use +.PN XStringToKeysym . +.IN "XStringToKeysym" "" "@DEF@" +.sM +.FD 0 +KeySym XStringToKeysym\^(\^\fIstring\fP\^) +.br + char *\fIstring\fP\^; +.FN +.IP \fIstring\fP 1i +Specifies the name of the KeySym that is to be converted. +.LP +.eM +Standard KeySym names are obtained from +.hN X11/keysymdef.h +by removing the XK_ prefix from each name. +KeySyms that are not part of the Xlib standard also may be obtained +with this function. +The set of KeySyms that are available in this manner +and the mechanisms by which Xlib obtains them is implementation-dependent. +.LP +If the KeySym name is not in the Host Portable Character Encoding, +the result is implementation-dependent. +If the specified string does not match a valid KeySym, +.PN XStringToKeysym +returns +.PN NoSymbol . +.LP +.sp +To convert a KeySym code to the name of the KeySym, use +.PN XKeysymToString . +.IN "XKeysymToString" "" "@DEF@" +.sM +.FD 0 +char *XKeysymToString\^(\^\fIkeysym\fP\^) +.br + KeySym \fIkeysym\fP\^; +.FN +.ds Fn converted +.IP \fIkeysym\fP 1i +Specifies the KeySym that is to be \*(Fn. +.LP +.eM +The returned string is in a static area and must not be modified. +The returned string is in the Host Portable Character Encoding. +If the specified KeySym is not defined, +.PN XKeysymToString +returns a NULL. +.NH 3 +KeySym Classification Macros +.XS +\*(SN KeySym Classification Macros +.XE +.LP +You may want to test if a KeySym is, for example, +on the keypad or on one of the function keys. +You can use KeySym macros to perform the following tests. +.LP +.sp +.sM +.FD 0 +IsCursorKey\^(\^\fIkeysym\fP\^) +.FN +.ds Fn tested +.IP \fIkeysym\fP 1i +Specifies the KeySym that is to be \*(Fn. +.LP +.eM +.IN "IsCursorKey" "" "@DEF@" +Returns +.PN True +if the specified KeySym is a cursor key. +.LP +.sp +.sM +.FD 0 +IsFunctionKey\^(\^\fIkeysym\fP\^) +.FN +.ds Fn tested +.IP \fIkeysym\fP 1i +Specifies the KeySym that is to be \*(Fn. +.LP +.eM +.IN "IsFunctionKey" "" "@DEF@" +Returns +.PN True +if the specified KeySym is a function key. +.LP +.sp +.sM +.FD 0 +IsKeypadKey\^(\^\fIkeysym\fP\^) +.FN +.ds Fn tested +.IP \fIkeysym\fP 1i +Specifies the KeySym that is to be \*(Fn. +.LP +.eM +.IN "IsKeypadKey" "" "@DEF@" +Returns +.PN True +if the specified KeySym is a standard keypad key. +.LP +.sp +.sM +.FD 0 +IsPrivateKeypadKey\^(\^\fIkeysym\fP\^) +.FN +.ds Fn tested +.IP \fIkeysym\fP 1i +Specifies the KeySym that is to be \*(Fn. +.LP +.eM +.IN "IsPrivateKeypadKey" "" "@DEF@" +Returns +.PN True +if the specified KeySym is a vendor-private keypad key. +.LP +.sp +.sM +.FD 0 +IsMiscFunctionKey\^(\^\fIkeysym\fP\^) +.FN +.ds Fn tested +.IP \fIkeysym\fP 1i +Specifies the KeySym that is to be \*(Fn. +.LP +.eM +.IN "IsMiscFunctionKey" "" "@DEF@" +Returns +.PN True +if the specified KeySym is a miscellaneous function key. +.LP +.sp +.sM +.FD 0 +IsModifierKey\^(\^\fIkeysym\fP\^) +.FN +.ds Fn tested +.IP \fIkeysym\fP 1i +Specifies the KeySym that is to be \*(Fn. +.LP +.eM +.IN "IsModifierKey" "" "@DEF@" +Returns +.PN True +if the specified KeySym is a modifier key. +.LP +.sp +.sM +.FD 0 +IsPFKey\^(\^\fIkeysym\fP\^) +.FN +.ds Fn tested +.IP \fIkeysym\fP 1i +Specifies the KeySym that is to be \*(Fn. +.LP +.eM +.IN "IsPFKey" "" "@DEF@" +Returns +.PN True +if the specified KeySym is a PF key. +.NH 2 +Using Latin-1 Keyboard Event Functions +.XS +\*(SN Using Latin-1 Keyboard Event Functions +.XE +.LP +Chapter 13 describes internationalized text input facilities, +but sometimes it is expedient to write an application that +only deals with Latin-1 characters and ASCII controls, +so Xlib provides a simple function for that purpose. +.PN XLookupString +handles the standard modifier semantics described in section 12.7. +This function does not use any of the input method facilities +described in chapter 13 and does not depend on the current locale. +.LP +.sp +To map a key event to an ISO Latin-1 string, use +.PN XLookupString . +.IN "XLookupString" "" "@DEF@" +.sM +.FD 0 +int XLookupString(\^\fIevent_struct\fP, \fIbuffer_return\fP,\ + \fIbytes_buffer\fP, \fIkeysym_return\fP, \fIstatus_in_out\fP\^) +.br + XKeyEvent *\fIevent_struct\fP\^; +.br + char *\fIbuffer_return\fP\^; +.br + int \fIbytes_buffer\fP\^; +.br + KeySym *\fIkeysym_return\fP\^; +.br + XComposeStatus *\fIstatus_in_out\fP\^; +.FN +.IP \fIevent_struct\fP 1i +Specifies the key event structure to be used. +You can pass +.PN XKeyPressedEvent +or +.PN XKeyReleasedEvent . +.IP \fIbuffer_return\fP 1i +Returns the translated characters. +.IP \fIbytes_buffer\fP 1i +Specifies the length of the buffer. +No more than bytes_buffer of translation are returned. +.IP \fIkeysym_return\fP 1i +Returns the KeySym computed from the event if this argument is not NULL. +.IP \fIstatus_in_out\fP 1i +Specifies or returns the +.PN XComposeStatus +structure or NULL. +.LP +.eM +The +.PN XLookupString +function translates a key event to a KeySym and a string. +The KeySym is obtained by using the standard interpretation of the +.PN Shift , +.PN Lock , +group, and numlock modifiers as defined in the X Protocol specification. +If the KeySym has been rebound (see +.PN XRebindKeysym ), +the bound string will be stored in the buffer. +Otherwise, the KeySym is mapped, if possible, to an ISO Latin-1 character +or (if the Control modifier is on) to an ASCII control character, +and that character is stored in the buffer. +.PN XLookupString +returns the number of characters that are stored in the buffer. +.LP +If present (non-NULL), +the +.PN XComposeStatus +structure records the state, +which is private to Xlib, +that needs preservation across calls to +.PN XLookupString +to implement compose processing. +The creation of +.PN XComposeStatus +structures is implementation-dependent; +a portable program must pass NULL for this argument. +.LP +.PN XLookupString +depends on the cached keyboard information mentioned in the +previous section, so it is necessary to use +.PN XRefreshKeyboardMapping +to keep this information up-to-date. +.LP +.sp +To rebind the meaning of a KeySym for +.PN XLookupString , +use +.PN XRebindKeysym . +.IN "XRebindKeysym" "" "@DEF@" +.sM +.FD 0 +XRebindKeysym(\^\fIdisplay\fP, \fIkeysym\fP, \fIlist\fP, \fImod_count\fP, \fIstring\fP, \fInum_bytes\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + KeySym \fIkeysym\fP\^; +.br + KeySym \fIlist\fP\^[\^]\^; +.br + int \fImod_count\fP\^; +.br + unsigned char *\fIstring\fP\^; +.br + int \fInum_bytes\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.ds Fn rebound +.IP \fIkeysym\fP 1i +Specifies the KeySym that is to be \*(Fn. +.IP \fIlist\fP 1i +Specifies the KeySyms to be used as modifiers. +.IP \fImod_count\fP 1i +Specifies the number of modifiers in the modifier list. +.IP \fIstring\fP 1i +Specifies the string that is copied and will be returned by +.PN XLookupString . +.IP \fInum_bytes\fP 1i +Specifies the number of bytes in the string argument. +.LP +.eM +The +.PN XRebindKeysym +function can be used to rebind the meaning of a KeySym for the client. +It does not redefine any key in the X server but merely +provides an easy way for long strings to be attached to keys. +.PN XLookupString +returns this string when the appropriate set of +modifier keys are pressed and when the KeySym would have been used for +the translation. +No text conversions are performed; +the client is responsible for supplying appropriately encoded strings. +Note that you can rebind a KeySym that may not exist. +.NH 2 +Allocating Permanent Storage +.XS +\*(SN Allocating Permanent Storage +.XE +.LP +To allocate some memory you will never give back, use +.PN Xpermalloc . +.IN "Xpermalloc" "" "@DEF@" +.sM +.FD 0 +char *Xpermalloc\^(\^\fIsize\fP\^) +.br + unsigned int \fIsize\fP\^; +.FN +.LP +.eM +The +.PN Xpermalloc +function allocates storage that can never be freed for the life of the +program. The memory is allocated with alignment for the C type double. +This function may provide some performance and space savings over +the standard operating system memory allocator. +.NH 2 +Parsing the Window Geometry +.XS +\*(SN Parsing the Window Geometry +.XE +.LP +To parse standard window geometry strings, use +.PN XParseGeometry . +.IN "Window" "determining location" +.IN "XParseGeometry" "" "@DEF@" +.LP +.sM +.FD 0 +int XParseGeometry\^(\^\fIparsestring\fP\^, \fIx_return\fP\^, \fIy_return\fP\^, \fIwidth_return\fP\^, \fIheight_return\fP\^) +.br + char *\fIparsestring\fP\^; +.br + int *\fIx_return\fP\^, *\fIy_return\fP\^; +.br + unsigned int *\fIwidth_return\fP\^, *\fIheight_return\fP\^; +.FN +.IP \fIparsestring\fP 1i +Specifies the string you want to parse. +.IP \fIx_return\fP 1i +.br +.ns +.IP \fIy_return\fP 1i +Return the x and y offsets. +.IP \fIwidth_return\fP 1i +.br +.ns +.IP \fIheight_return\fP 1i +Return the width and height determined. +.LP +.eM +By convention, +X applications use a standard string to indicate window size and placement. +.PN XParseGeometry +makes it easier to conform to this standard because it allows you +to parse the standard window geometry. +Specifically, this function lets you parse strings of the form: +.LP +.\" Start marker code here +.Ds +[=][<\fIwidth\fP>{xX}<\fIheight\fP>][{+-}<\fIxoffset\fP>{+-}<\fIyoffset\fP>] +.De +.\" End marker code here +.LP +The fields map into the arguments associated with this function. +(Items enclosed in <\^> are integers, items in [\^] are optional, and +items enclosed in {\^} indicate ``choose one of.'' +Note that the brackets should not appear in the actual string.) +If the string is not in the Host Portable Character Encoding, +the result is implementation-dependent. +.LP +The +.PN XParseGeometry +function returns a bitmask that indicates which of the four values (width, +height, xoffset, and yoffset) were actually found in the string +and whether the x and y values are negative. +By convention, \-0 is not equal to +0, because the user needs to +be able to say ``position the window relative to the right or bottom edge.'' +For each value found, the corresponding argument is updated. +For each value not found, the argument is left unchanged. +The bits are represented by +.PN XValue , +.PN YValue , +.PN WidthValue , +.PN HeightValue , +.PN XNegative , +or +.PN YNegative +and are defined in +.hN X11/Xutil.h . +They will be set whenever one of the values is defined +or one of the signs is set. +.LP +If the function returns either the +.PN XValue +or +.PN YValue +flag, +you should place the window at the requested position. +.sp +.LP +To construct a window's geometry information, use +.PN XWMGeometry . +.IN "XWMGeometry" "" "@DEF@" +.sM +.FD 0 +int XWMGeometry\^(\^\fIdisplay\fP, \fIscreen\fP, \fIuser_geom\fP, \ +\fIdef_geom\fP, \fIbwidth\fP, \fIhints\fP, \fIx_return\fP, \fIy_return\fP, +.br + \fIwidth_return\fP, \fIheight_return\fP, \fIgravity_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIscreen\fP\^; +.br + char *\fIuser_geom\fP\^; +.br + char *\fIdef_geom\fP\^; +.br + unsigned int \fIbwidth\fP\^; +.br + XSizeHints *\fIhints\fP\^; +.br + int *\fIx_return\fP, *\fIy_return\fP\^; +.br + int *\fIwidth_return\fP\^; +.br + int *\fIheight_return\fP\^; +.br + int *\fIgravity_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIscreen\fP 1i +Specifies the screen. +.IP \fIuser_geom\fP 1i +Specifies the user-specified geometry or NULL. +.IP \fIdef_geom\fP 1i +Specifies the application's default geometry or NULL. +.IP \fIbwidth\fP 1i +Specifies the border width. +.IP \fIhints\fP 1i +Specifies the size hints for the window in its normal state. +.IP \fIx_return\fP 1i +.br +.ns +.IP \fIy_return\fP 1i +Return the x and y offsets. +.IP \fIwidth_return\fP 1i +.br +.ns +.IP \fIheight_return\fP 1i +Return the width and height determined. +.IP \fIgravity_return\fP 1i +Returns the window gravity. +.LP +.eM +The +.PN XWMGeometry +function combines any geometry information (given in the format used by +.PN XParseGeometry ) +specified by the user and by the calling program with size hints +(usually the ones to be stored in WM_NORMAL_HINTS) and returns the position, +size, and gravity +.Pn ( NorthWestGravity , +.PN NorthEastGravity , +.PN SouthEastGravity , +or +.PN SouthWestGravity ) +that describe the window. +If the base size is not set in the +.PN XSizeHints +structure, +the minimum size is used if set. +Otherwise, a base size of zero is assumed. +If no minimum size is set in the hints structure, +the base size is used. +A mask (in the form returned by +.PN XParseGeometry ) +that describes which values came from the user specification +and whether or not the position coordinates are relative +to the right and bottom edges is returned. +Note that these coordinates will have already been accounted for +in the x_return and y_return values. +.LP +Note that invalid geometry specifications can cause a width or height +of zero to be returned. +The caller may pass the address of the hints win_gravity field +as gravity_return to update the hints directly. +.NH 2 +Manipulating Regions +.XS +\*(SN Manipulating Regions +.XE +.LP +Regions are arbitrary sets of pixel locations. +Xlib provides functions for manipulating regions. +The opaque type +.PN Region +is defined in +.hN X11/Xutil.h . +Xlib provides functions that you can use to manipulate regions. +This section discusses how to: +.IP \(bu 5 +Create, copy, or destroy regions +.IP \(bu 5 +Move or shrink regions +.IP \(bu 5 +Compute with regions +.IP \(bu 5 +Determine if regions are empty or equal +.IP \(bu 5 +Locate a point or rectangle in a region +.NH 3 +Creating, Copying, or Destroying Regions +.XS +\*(SN Creating, Copying, or Destroying Regions +.XE +.LP +To create a new empty region, use +.PN XCreateRegion . +.IN "XCreateRegion" "" "@DEF@" +.sM +.FD 0 +Region XCreateRegion\^() +.FN +.LP +.eM +.sp +To generate a region from a polygon, use +.PN XPolygonRegion . +.IN "XPolygonRegion" "" "@DEF@" +.sM +.FD 0 +Region XPolygonRegion\^(\^\fIpoints\fP\^, \fIn\fP\^, \fIfill_rule\fP\^) +.br + XPoint \fIpoints[]\fP\^; +.br + int \fIn\fP\^; +.br + int \fIfill_rule\fP\^; +.FN +.IP \fIpoints\fP 1i +Specifies an array of points. +.IP \fIn\fP 1i +Specifies the number of points in the polygon. +.IP \fIfill_rule\fP 1i +Specifies the fill-rule you want to set for the specified GC. +You can pass +.PN EvenOddRule +or +.PN WindingRule . +.LP +.eM +The +.PN XPolygonRegion +function returns a region for the polygon defined by the points array. +For an explanation of fill_rule, +see +.PN XCreateGC . +.LP +.sp +To set the clip-mask of a GC to a region, use +.PN XSetRegion . +.IN "XSetRegion" "" "@DEF@" +.sM +.FD 0 +XSetRegion\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIr\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + GC \fIgc\fP\^; +.br + Region \fIr\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fIr\fP 1i +Specifies the region. +.LP +.eM +The +.PN XSetRegion +function sets the clip-mask in the GC to the specified region. +The region is specified relative to the drawable's origin. +The resulting GC clip origin is implementation-dependent. +Once it is set in the GC, +the region can be destroyed. +.LP +.sp +To deallocate the storage associated with a specified region, use +.PN XDestroyRegion . +.IN "XDestroyRegion" "" "@DEF@" +.sM +.FD 0 +XDestroyRegion\^(\^\fIr\fP\^) +.br + Region \fIr\fP\^; +.FN +.IP \fIr\fP 1i +Specifies the region. +.LP +.eM +.NH 3 +Moving or Shrinking Regions +.XS +\*(SN Moving or Shrinking Regions +.XE +.LP +To move a region by a specified amount, use +.PN XOffsetRegion . +.IN "XOffsetRegion" "" "@DEF@" +.sM +.FD 0 +XOffsetRegion\^(\^\fIr\fP\^, \fIdx\fP\^, \fIdy\fP\^) +.br + Region \fIr\fP\^; +.br + int \fIdx\fP\^, \fIdy\fP\^; +.FN +.IP \fIr\fP 1i +Specifies the region. +.ds Dy move +.IP \fIdx\fP 1i +.br +.ns +.IP \fIdy\fP 1i +Specify the x and y coordinates, +which define the amount you want to \*(Dy the specified region. +.LP +.eM +.sp +To reduce a region by a specified amount, use +.PN XShrinkRegion . +.IN "XShrinkRegion" "" "@DEF@" +.sM +.FD 0 +XShrinkRegion\^(\^\fIr\fP\^, \fIdx\fP\^, \fIdy\fP\^) +.br + Region \fIr\fP\^; +.br + int \fIdx\fP\^, \fIdy\fP\^; +.FN +.IP \fIr\fP 1i +Specifies the region. +.ds Dy shrink +.IP \fIdx\fP 1i +.br +.ns +.IP \fIdy\fP 1i +Specify the x and y coordinates, +which define the amount you want to \*(Dy the specified region. +.LP +.eM +Positive values shrink the size of the region, +and negative values expand the region. +.NH 3 +Computing with Regions +.XS +\*(SN Computing with Regions +.XE +.LP +.sp +To generate the smallest rectangle enclosing a region, use +.PN XClipBox . +.IN "XClipBox" "" "@DEF@" +.sM +.FD 0 +XClipBox\^(\^\fIr\fP\^, \fIrect_return\fP\^) +.br + Region \fIr\fP\^; +.br + XRectangle *\fIrect_return\fP\^; +.FN +.IP \fIr\fP 1i +Specifies the region. +.IP \fIrect_return\fP 1i +Returns the smallest enclosing rectangle. +.LP +.eM +The +.PN XClipBox +function returns the smallest rectangle enclosing the specified region. +.sp +.LP +To compute the intersection of two regions, use +.PN XIntersectRegion . +.IN "XIntersectRegion" "" "@DEF@" +.sM +.FD 0 +XIntersectRegion\^(\^\fIsra\fP\^, \fIsrb\fP\^, \fIdr_return\fP\^) +.br + Region \fIsra\fP\^, \fIsrb\fP\^, \fIdr_return\fP\^; +.FN +.IP \fIsra\fP 1i +.br +.ns +.IP \fIsrb\fP 1i +Specify the two regions with which you want to perform the computation. +.IP \fIdr_return\fP 1i +Returns the result of the computation. +.LP +.eM +.sp +To compute the union of two regions, use +.PN XUnionRegion . +.IN "XUnionRegion" "" "@DEF@" +.sM +.FD 0 +XUnionRegion\^(\^\fIsra\fP\^, \fIsrb\fP\^, \fIdr_return\fP\^) +.br + Region \fIsra\fP\^, \fIsrb\fP\^, \fIdr_return\fP\^; +.FN +.IP \fIsra\fP 1i +.br +.ns +.IP \fIsrb\fP 1i +Specify the two regions with which you want to perform the computation. +.IP \fIdr_return\fP 1i +Returns the result of the computation. +.LP +.eM +.sp +To create a union of a source region and a rectangle, use +.PN XUnionRectWithRegion . +.IN "XUnionRectWithRegion" "" "@DEF@" +.sM +.FD 0 +XUnionRectWithRegion\^(\^\fIrectangle\fP, \fIsrc_region\fP, \ +\fIdest_region_return\fP\^) +.br + XRectangle *\fIrectangle\fP\^; +.br + Region \fIsrc_region\fP\^; +.br + Region \fIdest_region_return\fP\^; +.FN +.IP \fIrectangle\fP 1i +Specifies the rectangle. +.IP \fIsrc_region\fP 1i +Specifies the source region to be used. +.IP \fIdest_region_return\fP 1i +Returns the destination region. +.LP +.eM +The +.PN XUnionRectWithRegion +function updates the destination region from a union of the specified rectangle +and the specified source region. +.LP +.sp +To subtract two regions, use +.PN XSubtractRegion . +.IN "XSubtractRegion" "" "@DEF@" +.sM +.FD 0 +XSubtractRegion\^(\^\fIsra\fP\^, \fIsrb\fP\^, \fIdr_return\fP\^) +.br + Region \fIsra\fP\^, \fIsrb\fP\^, \fIdr_return\fP\^; +.FN +.IP \fIsra\fP 1i +.br +.ns +.IP \fIsrb\fP 1i +Specify the two regions with which you want to perform the computation. +.IP \fIdr_return\fP 1i +Returns the result of the computation. +.LP +.eM +The +.PN XSubtractRegion +function subtracts srb from sra and stores the results in dr_return. +.LP +.sp +To calculate the difference between the union and intersection +of two regions, use +.PN XXorRegion . +.IN "XXorRegion" "" "@DEF@" +.sM +.FD 0 +XXorRegion\^(\^\fIsra\fP\^, \fIsrb\fP\^, \fIdr_return\fP\^) +.br + Region \fIsra\fP\^, \fIsrb\fP\^, \fIdr_return\fP\^; +.FN +.IP \fIsra\fP 1i +.br +.ns +.IP \fIsrb\fP 1i +Specify the two regions with which you want to perform the computation. +.IP \fIdr_return\fP 1i +Returns the result of the computation. +.LP +.eM +.NH 3 +Determining if Regions Are Empty or Equal +.XS +\*(SN Determining if Regions Are Empty or Equal +.XE +.LP +To determine if the specified region is empty, use +.PN XEmptyRegion . +.IN "XEmptyRegion" "" "@DEF@" +.sM +.FD 0 +Bool XEmptyRegion\^(\^\fIr\fP\^) +.br + Region \fIr\fP\^; +.FN +.IP \fIr\fP 1i +Specifies the region. +.LP +.eM +The +.PN XEmptyRegion +function returns +.PN True +if the region is empty. +.LP +.sp +To determine if two regions have the same offset, size, and shape, use +.PN XEqualRegion . +.IN "XEqualRegion" "" "@DEF@" +.sM +.FD 0 +Bool XEqualRegion\^(\^\fIr1\fP\^, \fIr2\fP\^) +.br + Region \fIr1\fP\^, \fIr2\fP\^; +.FN +.IP \fIr1\fP 1i +.br +.ns +.IP \fIr2\fP 1i +Specify the two regions. +.LP +.eM +The +.PN XEqualRegion +function returns +.PN True +if the two regions have the same offset, size, and shape. +.NH 3 +Locating a Point or a Rectangle in a Region +.XS +\*(SN Locating a Point or a Rectangle in a Region +.XE +.LP +To determine if a specified point resides in a specified region, use +.PN XPointInRegion . +.IN "XPointInRegion" "" "@DEF@" +.sM +.FD 0 +Bool XPointInRegion\^(\^\fIr\fP\^, \fIx\fP\^, \fIy\fP\^) +.br + Region \fIr\fP\^; +.br + int \fIx\fP\^, \fIy\fP\^; +.FN +.IP \fIr\fP 1i +Specifies the region. +.ds Xy , which define the point +.IP \fIx\fP 1i +.br +.ns +.IP \fIy\fP 1i +Specify the x and y coordinates\*(Xy. +.LP +.eM +The +.PN XPointInRegion +function returns +.PN True +if the point (x, y) is contained in the region r. +.LP +.sp +To determine if a specified rectangle is inside a region, use +.PN XRectInRegion . +.IN "XRectInRegion" "" "@DEF@" +.sM +.FD 0 +int XRectInRegion\^(\^\fIr\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^) +.br + Region \fIr\fP\^; +.br + int \fIx\fP\^, \fIy\fP\^; +.br + unsigned int \fIwidth\fP\^, \fIheight\fP\^; +.FN +.IP \fIr\fP 1i +Specifies the region. +.ds Xy , which define the coordinates of the upper-left corner of the rectangle +.IP \fIx\fP 1i +.br +.ns +.IP \fIy\fP 1i +Specify the x and y coordinates\*(Xy. +.ds Wh , which define the rectangle +.IP \fIwidth\fP 1i +.br +.ns +.IP \fIheight\fP 1i +Specify the width and height\*(Wh. +.LP +.eM +The +.PN XRectInRegion +function returns +.PN RectangleIn +if the rectangle is entirely in the specified region, +.PN RectangleOut +if the rectangle is entirely out of the specified region, +and +.PN RectanglePart +if the rectangle is partially in the specified region. +.NH 2 +Using Cut Buffers +.XS +\*(SN Using Cut Buffers +.XE +.LP +.IN "Cut Buffers" +Xlib provides functions to manipulate cut buffers, +a very simple form of cut-and-paste inter-client communication. +Selections are a much more powerful and useful mechanism for +interchanging data between clients (see section 4.5) +and generally should be used instead of cut buffers. +.LP +Cut buffers are implemented as properties on the first root window +of the display. +The buffers can only contain text, in the STRING encoding. +The text encoding is not changed by Xlib when fetching or storing. +Eight buffers are provided +and can be accessed as a ring or as explicit buffers (numbered 0 through 7). +.LP +.sp +To store data in cut buffer 0, use +.PN XStoreBytes . +.IN "XStoreBytes" "" "@DEF@" +.sM +.FD 0 +XStoreBytes\^(\^\fIdisplay\fP, \fIbytes\fP\^, \fInbytes\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + char *\fIbytes\fP\^; +.br + int \^\fInbytes\fP\^; +.br +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIbytes\fP 1i +Specifies the bytes, which are not necessarily ASCII or null-terminated. +.IP \fInbytes\fP 1i +Specifies the number of bytes to be stored. +.LP +.eM +The data can have embedded null characters +and need not be null-terminated. +The cut buffer's contents can be retrieved later by +any client calling +.PN XFetchBytes . +.LP +.PN XStoreBytes +can generate a +.PN BadAlloc +error. +.LP +.sp +To store data in a specified cut buffer, use +.PN XStoreBuffer . +.IN "XStoreBuffer" "" "@DEF@" +.sM +.FD 0 +XStoreBuffer\^(\^\fIdisplay\fP, \fIbytes\fP\^, \fInbytes\fP\^, \fIbuffer\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + char *\fIbytes\fP\^; +.br + int \^\fInbytes\fP\^; +.br + int \fIbuffer\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIbytes\fP 1i +Specifies the bytes, which are not necessarily ASCII or null-terminated. +.IP \fInbytes\fP 1i +Specifies the number of bytes to be stored. +.ds Fn in which you want to store the bytes +.IP \fIbuffer\fP 1i +Specifies the buffer \*(Fn. +.LP +.eM +If an invalid buffer is specified, the call has no effect. +The data can have embedded null characters +and need not be null-terminated. +.LP +.PN XStoreBuffer +can generate a +.PN BadAlloc +error. +.LP +.sp +To return data from cut buffer 0, use +.PN XFetchBytes . +.IN "XFetchBytes" "" "@DEF@" +.sM +.FD 0 +char *XFetchBytes\^(\^\fIdisplay\fP, \fInbytes_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int *\fInbytes_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fInbytes_return\fP 1i +Returns the number of bytes in the buffer. +.LP +.eM +The +.PN XFetchBytes +function +returns the number of bytes in the nbytes_return argument, +if the buffer contains data. +Otherwise, the function +returns NULL and sets nbytes to 0. +The appropriate amount of storage is allocated and the pointer returned. +The client must free this storage when finished with it by calling +.PN XFree . +.LP +.sp +To return data from a specified cut buffer, use +.PN XFetchBuffer . +.IN "XFetchBuffer" "" "@DEF@" +.sM +.FD 0 +char *XFetchBuffer\^(\^\fIdisplay\fP, \fInbytes_return\fP\^, \fIbuffer\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int *\fInbytes_return\fP\^; +.br + int \fIbuffer\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fInbytes_return\fP 1i +Returns the number of bytes in the buffer. +.ds Fn from which you want the stored data returned +.IP \fIbuffer\fP 1i +Specifies the buffer \*(Fn. +.LP +.eM +The +.PN XFetchBuffer +function returns zero to the nbytes_return argument +if there is no data in the buffer or if an invalid +buffer is specified. +.LP +.sp +To rotate the cut buffers, use +.PN XRotateBuffers . +.IN "XRotateBuffers" "" "@DEF@" +.sM +.FD 0 +XRotateBuffers\^(\^\fIdisplay\fP, \fIrotate\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIrotate\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIrotate\fP 1i +Specifies how much to rotate the cut buffers. +.LP +.eM +The +.PN XRotateBuffers +function rotates the cut +buffers, such that buffer 0 becomes buffer n, +buffer 1 becomes n + 1 mod 8, and so on. +This cut buffer numbering is global to the display. +Note that +.PN XRotateBuffers +generates +.PN BadMatch +errors if any of the eight buffers have not been created. +.NH 2 +Determining the Appropriate Visual Type +.XS +\*(SN Determining the Appropriate Visual Type +.XE +.LP +A single display can support multiple screens. +Each screen can have several different visual types supported +at different depths. +You can use the functions described in this section to determine +which visual to use for your application. +.LP +The functions in this section use the visual information masks and the +.PN XVisualInfo +structure, +which is defined in +.hN X11/Xutil.h +and contains: +.sM +.LP +/* Visual information mask bits */ +.TS +lw(.5i) lw(2.5i) lw(.8i). +T{ +#define +T} T{ +.PN VisualNoMask +T} T{ +0x0 +T} +T{ +#define +T} T{ +.PN VisualIDMask +T} T{ +0x1 +T} +T{ +#define +T} T{ +.PN VisualScreenMask +T} T{ +0x2 +T} +T{ +#define +T} T{ +.PN VisualDepthMask +T} T{ +0x4 +T} +T{ +#define +T} T{ +.PN VisualClassMask +T} T{ +0x8 +T} +T{ +#define +T} T{ +.PN VisualRedMaskMask +T} T{ +0x10 +T} +T{ +#define +T} T{ +.PN VisualGreenMaskMask +T} T{ +0x20 +T} +T{ +#define +T} T{ +.PN VisualBlueMaskMask +T} T{ +0x40 +T} +T{ +#define +T} T{ +.PN VisualColormapSizeMask +T} T{ +0x80 +T} +T{ +#define +T} T{ +.PN VisualBitsPerRGBMask +T} T{ +0x100 +T} +T{ +#define +T} T{ +.PN VisualAllMask +T} T{ +0x1FF +T} +.TE +.IN "XVisualInfo" "" "@DEF@" +.Ds 0 +.TA .5i 3i +.ta .5i 3i +/* Values */ + +typedef struct { + Visual *visual; + VisualID visualid; + int screen; + unsigned int depth; + int class; + unsigned long red_mask; + unsigned long green_mask; + unsigned long blue_mask; + int colormap_size; + int bits_per_rgb; +} XVisualInfo; +.De +.LP +.eM +To obtain a list of visual information structures that match a specified +template, use +.PN XGetVisualInfo . +.IN "XGetVisualInfo" "" "@DEF@" +.sM +.FD 0 +XVisualInfo *XGetVisualInfo\^(\^\fIdisplay\fP, \fIvinfo_mask\fP, \fIvinfo_template\fP, \fInitems_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + long \fIvinfo_mask\fP\^; +.br + XVisualInfo *\fIvinfo_template\fP\^; +.br + int *\fInitems_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIvinfo_mask\fP 1i +Specifies the visual mask value. +.IP \fIvinfo_template\fP 1i +Specifies the visual attributes that are to be used in matching the visual +structures. +.IP \fInitems_return\fP 1i +Returns the number of matching visual structures. +.LP +.eM +The +.PN XGetVisualInfo +function returns a list of visual structures that have attributes +equal to the attributes specified by vinfo_template. +If no visual structures match the template using the specified vinfo_mask, +.PN XGetVisualInfo +returns a NULL. +To free the data returned by this function, use +.PN XFree . +.LP +.sp +To obtain the visual information that matches the specified depth and +class of the screen, use +.PN XMatchVisualInfo . +.IN "XMatchVisualInfo" "" "@DEF@" +.sM +.FD 0 +Status XMatchVisualInfo\^(\^\fIdisplay\fP, \fIscreen\fP, \fIdepth\fP, \fIclass\fP, \fIvinfo_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIscreen\fP\^; +.br + int \fIdepth\fP\^; +.br + int \fIclass\fP\^; +.br + XVisualInfo *\fIvinfo_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIscreen\fP 1i +Specifies the screen. +.IP \fIdepth\fP 1i +Specifies the depth of the screen. +.IP \fIclass\fP 1i +Specifies the class of the screen. +.IP \fIvinfo_return\fP 1i +Returns the matched visual information. +.LP +.eM +The +.PN XMatchVisualInfo +function returns the visual information for a visual that matches the specified +depth and class for a screen. +Because multiple visuals that match the specified depth and class can exist, +the exact visual chosen is undefined. +If a visual is found, +.PN XMatchVisualInfo +returns nonzero and the information on the visual to vinfo_return. +Otherwise, when a visual is not found, +.PN XMatchVisualInfo +returns zero. +.NH 2 +Manipulating Images +.XS +\*(SN Manipulating Images +.XE +.LP +Xlib provides several functions that perform basic operations on images. +All operations on images are defined using an +.PN XImage +structure, +as defined in +.hN X11/Xlib.h . +Because the number of different types of image formats can be very large, +this hides details of image storage properly from applications. +.LP +This section describes the functions for generic operations on images. +Manufacturers can provide very fast implementations of these for the +formats frequently encountered on their hardware. +These functions are neither sufficient nor desirable to use for general image +processing. +Rather, they are here to provide minimal functions on screen format +images. +The basic operations for getting and putting images are +.PN XGetImage +and +.PN XPutImage . +.LP +Note that no functions have been defined, as yet, to read and write images +to and from disk files. +.LP +The +.PN XImage +structure describes an image as it exists in the client's memory. +The user can request that some of the members such as height, width, +and xoffset be changed when the image is sent to the server. +Note that bytes_per_line in concert with offset can be used to +extract a subset of the image. +Other members (for example, byte order, bitmap_unit, and so forth) +are characteristics of both the image and the server. +If these members +differ between the image and the server, +.PN XPutImage +makes the appropriate conversions. +The first byte of the first line of +plane n must be located at the address (data + (n * height * bytes_per_line)). +For a description of the +.PN XImage +structure, +see section 8.7. +.LP +.sp +To allocate an +.PN XImage +structure and initialize it with image format values from a display, use +.PN XCreateImage . +.IN "XCreateImage" "" "@DEF@" +.sM +.FD 0 +XImage *XCreateImage\^(\^\fIdisplay\fP, \fIvisual\fP, \fIdepth\fP, \fIformat\fP, \fIoffset\fP, \fIdata\fP, \fIwidth\fP, \fIheight\fP\^, \fIbitmap_pad\fP, +.br + \fIbytes_per_line\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Visual *\fIvisual\fP\^; +.br + unsigned int \fIdepth\fP\^; +.br + int \fIformat\fP\^; +.br + int \fIoffset\fP\^; +.br + char *\fIdata\fP\^; +.br + unsigned int \fIwidth\fP\^; +.br + unsigned int \fIheight\fP\^; +.br + int \fIbitmap_pad\fP\^; +.br + int \fIbytes_per_line\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIvisual\fP 1i +Specifies the +.PN Visual +structure. +.IP \fIdepth\fP 1i +Specifies the depth of the image. +.IP \fIformat\fP 1i +Specifies the format for the image. +You can pass +.PN XYBitmap , +.PN XYPixmap , +or +.PN ZPixmap . +.IP \fIoffset\fP 1i +Specifies the number of pixels to ignore at the beginning of the scanline. +.IP \fIdata\fP 1i +Specifies the image data. +.IP \fIwidth\fP 1i +Specifies the width of the image, in pixels. +.IP \fIheight\fP 1i +Specifies the height of the image, in pixels. +.IP \fIbitmap_pad\fP 1i +Specifies the quantum of a scanline (8, 16, or 32). +In other words, the start of one scanline is separated in client memory from +the start of the next scanline by an integer multiple of this many bits. +.IP \fIbytes_per_line\fP 1i +Specifies the number of bytes in the client image between +the start of one scanline and the start of the next. +.LP +.eM +The +.PN XCreateImage +function allocates the memory needed for an +.PN XImage +structure for the +specified display but does not allocate space for the image itself. +Rather, it initializes the structure byte-order, bit-order, and bitmap-unit +values from the display and returns a pointer to the +.PN XImage +structure. +The red, green, and blue mask values are defined for Z format images only +and are derived from the +.PN Visual +structure passed in. +Other values also are passed in. +The offset permits the rapid displaying of the image without requiring each +scanline to be shifted into position. +If you pass a zero value in bytes_per_line, +Xlib assumes that the scanlines are contiguous +in memory and calculates the value of bytes_per_line itself. +.LP +Note that when the image is created using +.PN XCreateImage , +.PN XGetImage , +or +.PN XSubImage , +the destroy procedure that the +.PN XDestroyImage +function calls frees both the image structure +and the data pointed to by the image structure. +.LP +The basic functions used to get a pixel, set a pixel, create a subimage, +and add a constant value to an image are defined in the image object. +The functions in this section are really macro invocations of the functions +in the image object and are defined in +.hN X11/Xutil.h . +.LP +.sp +To obtain a pixel value in an image, use +.PN XGetPixel . +.IN "XGetPixel" "" "@DEF@" +.sM +.FD 0 +unsigned long XGetPixel\^(\^\fIximage\fP, \fIx\fP, \fIy\fP\^) +.br + XImage *\fIximage\fP\^; +.br + int \fIx\fP\^; +.br + int \fIy\fP\^; +.FN +.IP \fIximage\fP 1i +Specifies the image. +.IP \fIx\fP 1i +.br +.ns +.IP \fIy\fP 1i +Specify the x and y coordinates. +.LP +.eM +The +.PN XGetPixel +function returns the specified pixel from the named image. +The pixel value is returned in normalized format (that is, +the least significant byte of the long is the least significant byte +of the pixel). +The image must contain the x and y coordinates. +.LP +.sp +To set a pixel value in an image, use +.PN XPutPixel . +.IN "XPutPixel" "" "@DEF@" +.sM +.FD 0 +XPutPixel\^(\^\fIximage\fP, \fIx\fP, \fIy\fP, \fIpixel\fP\^) +.br + XImage *\fIximage\fP\^; +.br + int \fIx\fP\^; +.br + int \fIy\fP\^; +.br + unsigned long \fIpixel\fP\^; +.FN +.IP \fIximage\fP 1i +Specifies the image. +.IP \fIx\fP 1i +.br +.ns +.IP \fIy\fP 1i +Specify the x and y coordinates. +.IP \fIpixel\fP 1i +Specifies the new pixel value. +.LP +.eM +The +.PN XPutPixel +function overwrites the pixel in the named image with the specified pixel value. +The input pixel value must be in normalized format +(that is, the least significant byte of the long is the least significant +byte of the pixel). +The image must contain the x and y coordinates. +.LP +.sp +To create a subimage, use +.PN XSubImage . +.IN "XSubImage" "" "@DEF@" +.sM +.FD 0 +XImage *XSubImage\^(\^\fIximage\fP, \fIx\fP, \fIy\fP, \fIsubimage_width\fP, \fIsubimage_height\fP\^) +.br + XImage *\fIximage\fP\^; +.br + int \fIx\fP\^; +.br + int \fIy\fP\^; +.br + unsigned int \fIsubimage_width\fP\^; +.br + unsigned int \fIsubimage_height\fP\^; +.FN +.IP \fIximage\fP 1i +Specifies the image. +.IP \fIx\fP 1i +.br +.ns +.IP \fIy\fP 1i +Specify the x and y coordinates. +.IP \fIsubimage_width\fP 1i +Specifies the width of the new subimage, in pixels. +.IP \fIsubimage_height\fP 1i +Specifies the height of the new subimage, in pixels. +.LP +.eM +The +.PN XSubImage +function creates a new image that is a subsection of an existing one. +It allocates the memory necessary for the new +.PN XImage +structure +and returns a pointer to the new image. +The data is copied from the source image, +and the image must contain the rectangle defined by x, y, subimage_width, +and subimage_height. +.LP +.sp +To increment each pixel in an image by a constant value, use +.PN XAddPixel . +.IN "XAddPixel" "" "@DEF@" +.sM +.FD 0 +XAddPixel\^(\^\fIximage\fP, \fIvalue\fP\^) +.br + XImage *\fIximage\fP\^; +.br + long \fIvalue\fP\^; +.FN +.IP \fIximage\fP 1i +Specifies the image. +.IP \fIvalue\fP 1i +Specifies the constant value that is to be added. +.LP +.eM +The +.PN XAddPixel +function adds a constant value to every pixel in an image. +It is useful when you have a base pixel value from allocating +color resources and need to manipulate the image to that form. +.LP +.sp +To deallocate the memory allocated in a previous call to +.PN XCreateImage , +use +.PN XDestroyImage . +.IN "XDestroyImage" "" "@DEF@" +.sM +.FD 0 +XDestroyImage\^(\^\fIximage\fP\^) +.br + XImage *\^\fIximage\fP\^; +.FN +.IP \fIximage\fP 1i +Specifies the image. +.LP +.eM +The +.PN XDestroyImage +function deallocates the memory associated with the +.PN XImage +structure. +.LP +Note that when the image is created using +.PN XCreateImage , +.PN XGetImage , +or +.PN XSubImage , +the destroy procedure that this macro calls +frees both the image structure and the data pointed to by the image structure. +.NH 2 +Manipulating Bitmaps +.XS +\*(SN Manipulating Bitmaps +.XE +.LP +Xlib provides functions that you can use to read a bitmap from a file, +save a bitmap to a file, or create a bitmap. +This section describes those functions that transfer bitmaps to and +from the client's file system, thus allowing their reuse in a later +connection (for example, from an entirely different client or to a +different display or server). +.LP +The X version 11 bitmap file format is: +.LP +.sM +.Ds 0 +#define \fIname\fP_width \fIwidth\fP +#define \fIname\fP_height \fIheight\fP +#define \fIname\fP_x_hot \fIx\fP +#define \fIname\fP_y_hot \fIy\fP +static unsigned char \fIname\fP_bits[] = { 0x\fINN\fP,... } +.De +.LP +.eM +The lines for the variables ending with _x_hot and _y_hot suffixes are optional +because they are present only if a hotspot has been defined for this bitmap. +The lines for the other variables are required. +The word ``unsigned'' is optional; +that is, the type of the _bits array can be ``char'' or ``unsigned char''. +The _bits array must be large enough to contain the size bitmap. +The bitmap unit is 8. +.LP +.sp +To read a bitmap from a file and store it in a pixmap, use +.PN XReadBitmapFile . +.IN "XReadBitmapFile" "" "@DEF@" +.sM +.FD 0 +int XReadBitmapFile(\^\fIdisplay\fP, \fId\fP, \fIfilename\fP, \fIwidth_return\fP, \fIheight_return\fP, \fIbitmap_return\fP, \fIx_hot_return\fP, +.br + \fIy_hot_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fId\fP\^; +.br + char *\fIfilename\fP\^; +.br + unsigned int *\fIwidth_return\fP, *\fIheight_return\fP\^; +.br + Pixmap *\fIbitmap_return\fP\^; +.br + int *\fIx_hot_return\fP, *\fIy_hot_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.ds Dr \ that indicates the screen +.IP \fId\fP 1i +Specifies the drawable\*(Dr. +.IP \fIfilename\fP 1i +Specifies the file name to use. +The format of the file name is operating-system dependent. +.IP \fIwidth_return\fP 1i +.br +.ns +.IP \fIheight_return\fP 1i +Return the width and height values of the read in bitmap file. +.IP \fIbitmap_return\fP 1i +Returns the bitmap that is created. +.IP \fIx_hot_return\fP 1i +.br +.ns +.IP \fIy_hot_return\fP 1i +Return the hotspot coordinates. +.LP +.eM +The +.PN XReadBitmapFile +function reads in a file containing a bitmap. +The file is parsed in the encoding of the current locale. +The ability to read other than the standard format +is implementation-dependent. +If the file cannot be opened, +.PN XReadBitmapFile +returns +.PN BitmapOpenFailed . +If the file can be opened but does not contain valid bitmap data, +it returns +.PN BitmapFileInvalid . +If insufficient working storage is allocated, +it returns +.PN BitmapNoMemory . +If the file is readable and valid, +it returns +.PN BitmapSuccess . +.LP +.PN XReadBitmapFile +returns the bitmap's height and width, as read +from the file, to width_return and height_return. +It then creates a pixmap of the appropriate size, +reads the bitmap data from the file into the pixmap, +and assigns the pixmap to the caller's variable bitmap. +The caller must free the bitmap using +.PN XFreePixmap +when finished. +If \fIname\fP_x_hot and \fIname\fP_y_hot exist, +.PN XReadBitmapFile +returns them to x_hot_return and y_hot_return; +otherwise, it returns \-1,\-1. +.LP +.PN XReadBitmapFile +can generate +.PN BadAlloc , +.PN BadDrawable , +and +.PN BadGC +errors. +.LP +.sp +To read a bitmap from a file and return it as data, use +.PN XReadBitmapFileData . +.IN "XReadBitmapFileData" "" "@DEF@" +.sM +.FD 0 +int XReadBitmapFileData(\^\fIfilename\fP, \fIwidth_return\fP, \fIheight_return\fP, \fIdata_return\fP, \fIx_hot_return\fP, \fIy_hot_return\fP\^) +.br + char *\fIfilename\fP\^; +.br + unsigned int *\fIwidth_return\fP, *\fIheight_return\fP\^; +.br + unsigned char *\fIdata_return\fP\^; +.br + int *\fIx_hot_return\fP, *\fIy_hot_return\fP\^; +.FN +.IP \fIfilename\fP 1i +Specifies the file name to use. +The format of the file name is operating-system dependent. +.IP \fIwidth_return\fP 1i +.br +.ns +.IP \fIheight_return\fP 1i +Return the width and height values of the read in bitmap file. +.IP \fIdata_return\fP 1i +Returns the bitmap data. +.IP \fIx_hot_return\fP 1i +.br +.ns +.IP \fIy_hot_return\fP 1i +Return the hotspot coordinates. +.LP +.eM +The +.PN XReadBitmapFileData +function reads in a file containing a bitmap, in the same manner as +.PN XReadBitmapFile , +but returns the data directly rather than creating a pixmap in the server. +The bitmap data is returned in data_return; the client must free this +storage when finished with it by calling +.PN XFree . +The status and other return values are the same as for +.PN XReadBitmapFile . +.LP +.sp +To write out a bitmap from a pixmap to a file, use +.PN XWriteBitmapFile . +.IN "XWriteBitmapFile" "" "@DEF@" +.sM +.FD 0 +int XWriteBitmapFile(\^\fIdisplay\fP, \fIfilename\fP, \fIbitmap\fP, \fIwidth\fP, \fIheight\fP, \fIx_hot\fP, \fIy_hot\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + char *\fIfilename\fP\^; +.br + Pixmap \fIbitmap\fP\^; +.br + unsigned int \fIwidth\fP, \fIheight\fP\^; +.br + int \fIx_hot\fP, \fIy_hot\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIfilename\fP 1i +Specifies the file name to use. +The format of the file name is operating-system dependent. +.IP \fIbitmap\fP 1i +Specifies the bitmap. +.IP \fIwidth\fP 1i +.br +.ns +.IP \fIheight\fP 1i +Specify the width and height. +.IP \fIx_hot\fP 1i +.br +.ns +.IP \fIy_hot\fP 1i +Specify where to place the hotspot coordinates (or \-1,\-1 if none are present) +in the file. +.LP +.eM +The +.PN XWriteBitmapFile +function writes a bitmap out to a file in the X Version 11 format. +The name used in the output file is derived from the file name +by deleting the directory prefix. +The file is written in the encoding of the current locale. +If the file cannot be opened for writing, +it returns +.PN BitmapOpenFailed . +If insufficient memory is allocated, +.PN XWriteBitmapFile +returns +.PN BitmapNoMemory ; +otherwise, on no error, +it returns +.PN BitmapSuccess . +If x_hot and y_hot are not \-1, \-1, +.PN XWriteBitmapFile +writes them out as the hotspot coordinates for the bitmap. +.LP +.PN XWriteBitmapFile +can generate +.PN BadDrawable +and +.PN BadMatch +errors. +.LP +.sp +To create a pixmap and then store bitmap-format data into it, use +.PN XCreatePixmapFromBitmapData . +.IN "XCreatePixmapFromBitmapData" "" "@DEF@" +.sM +.FD 0 +Pixmap XCreatePixmapFromBitmapData\^(\^\fIdisplay\fP, \fId\fP, \fIdata\fP, \fIwidth\fP, \fIheight\fP, \fIfg\fP, \fIbg\fP, \fIdepth\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fId\fP\^; +.br + char *\fIdata\fP\^; +.br + unsigned int \fIwidth\fP, \fIheight\fP\^; +.br + unsigned long \fIfg\fP, \fIbg\fP\^; +.br + unsigned int \fIdepth\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.ds Dr \ that indicates the screen +.IP \fId\fP 1i +Specifies the drawable\*(Dr. +.IP \fIdata\fP 1i +Specifies the data in bitmap format. +.IP \fIwidth\fP 1i +.br +.ns +.IP \fIheight\fP 1i +Specify the width and height. +.IP \fIfg\fP 1i +.br +.ns +.IP \fIbg\fP 1i +Specify the foreground and background pixel values to use. +.IP \fIdepth\fP 1i +Specifies the depth of the pixmap. +.LP +.eM +The +.PN XCreatePixmapFromBitmapData +function creates a pixmap of the given depth and then does a bitmap-format +.PN XPutImage +of the data into it. +The depth must be supported by the screen of the specified drawable, +or a +.PN BadMatch +error results. +.LP +.PN XCreatePixmapFromBitmapData +can generate +.PN BadAlloc , +.PN BadDrawable , +.PN BadGC , +and +.PN BadValue +errors. +.LP +.sp +To include a bitmap written out by +.PN XWriteBitmapFile +.IN "XWriteBitmapFile" +in a program directly, as opposed to reading it in every time at run time, use +.PN XCreateBitmapFromData . +.IN "XCreateBitmapFromData" "" "@DEF@" +.sM +.FD 0 +Pixmap XCreateBitmapFromData(\^\fIdisplay\fP, \fId\fP, \fIdata\fP, \fIwidth\fP, \fIheight\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fId\fP\^; +.br + char *\fIdata\fP\^; +.br + unsigned int \fIwidth\fP, \fIheight\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.ds Dr \ that indicates the screen +.IP \fId\fP 1i +Specifies the drawable\*(Dr. +.IP \fIdata\fP 1i +Specifies the location of the bitmap data. +.IP \fIwidth\fP 1i +.br +.ns +.IP \fIheight\fP 1i +Specify the width and height. +.LP +.eM +The +.PN XCreateBitmapFromData +function allows you to include in your C program (using +.PN #include ) +a bitmap file that was written out by +.PN XWriteBitmapFile +(X version 11 format only) without reading in the bitmap file. +The following example creates a gray bitmap: +.LP +.Ds 0 +#include "gray.bitmap" +.sp 6p +Pixmap bitmap; +bitmap = XCreateBitmapFromData(display, window, gray_bits, gray_width, gray_height); +.De +.LP +If insufficient working storage was allocated, +.PN XCreateBitmapFromData +returns +.PN None . +It is your responsibility to free the +bitmap using +.PN XFreePixmap +when finished. +.LP +.PN XCreateBitmapFromData +can generate +.PN BadAlloc +and +.PN BadGC +errors. +.NH 2 +Using the Context Manager +.XS +\*(SN Using the Context Manager +.XE +.LP +The context manager provides a way of associating data with an X resource ID +(mostly typically a window) in your program. +Note that this is local to your program; +the data is not stored in the server on a property list. +Any amount of data in any number of pieces can be associated with a +resource ID, +and each piece of data has a type associated with it. +The context manager requires knowledge of the resource ID +and type to store or retrieve data. +.LP +Essentially, the context manager can be viewed as a two-dimensional, +sparse array: one dimension is subscripted by the X resource ID +and the other by a context type field. +Each entry in the array contains a pointer to the data. +Xlib provides context management functions with which you can +save data values, get data values, delete entries, and create a unique +context type. +The symbols used are in +.hN X11/Xutil.h . +.LP +.sp +To save a data value that corresponds to a resource ID and context type, use +.PN XSaveContext . +.IN "XSaveContext" "" "@DEF@" +.sM +.FD 0 +int XSaveContext(\^\fIdisplay\fP, \fIrid\fP, \fIcontext\fP, \fIdata\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XID \fIrid\fP\^; +.br + XContext \fIcontext\fP\^; +.br + XPointer \fIdata\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIrid\fP 1i +Specifies the resource ID with which the data is associated. +.IP \fIcontext\fP 1i +Specifies the context type to which the data belongs. +.IP \fIdata\fP 1i +Specifies the data to be associated with the window and type. +.LP +.eM +If an entry with the specified resource ID and type already exists, +.PN XSaveContext +overrides it with the specified context. +The +.PN XSaveContext +function returns a nonzero error code if an error has occurred +and zero otherwise. +Possible errors are +.PN XCNOMEM +(out of memory). +.LP +.sp +To get the data associated with a resource ID and type, use +.PN XFindContext . +.IN "XFindContext" "" "@DEF@" +.sM +.FD 0 +int XFindContext(\^\fIdisplay\fP, \fIrid\fP, \fIcontext\fP, \fIdata_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XID \fIrid\fP\^; +.br + XContext \fIcontext\fP\^; +.br + XPointer *\fIdata_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIrid\fP 1i +Specifies the resource ID with which the data is associated. +.IP \fIcontext\fP 1i +Specifies the context type to which the data belongs. +.IP \fIdata_return\fP 1i +Returns the data. +.LP +.eM +Because it is a return value, +the data is a pointer. +The +.PN XFindContext +function returns a nonzero error code if an error has occurred +and zero otherwise. +Possible errors are +.PN XCNOENT +(context-not-found). +.LP +.sp +To delete an entry for a given resource ID and type, use +.PN XDeleteContext . +.IN "XDeleteContext" "" "@DEF@" +.sM +.FD 0 +int XDeleteContext(\^\fIdisplay\fP, \fIrid\fP, \fIcontext\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XID \fIrid\fP; +.br + XContext \fIcontext\fP; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIrid\fP 1i +Specifies the resource ID with which the data is associated. +.IP \fIcontext\fP 1i +Specifies the context type to which the data belongs. +.LP +.eM +The +.PN XDeleteContext +function deletes the entry for the given resource ID +and type from the data structure. +This function returns the same error codes that +.PN XFindContext +returns if called with the same arguments. +.PN XDeleteContext +does not free the data whose address was saved. +.LP +.sp +To create a unique context type that may be used in subsequent calls to +.PN XSaveContext +and +.PN XFindContext , +use +.PN XUniqueContext . +.IN "XUniqueContext" "" "@DEF@" +.sM +.FD 0 +XContext XUniqueContext(\^) +.FN +.LP +.eM +.bp diff --git a/libX11/specs/libX11/Makefile.am b/libX11/specs/libX11/Makefile.am new file mode 100644 index 000000000..99b838f4f --- /dev/null +++ b/libX11/specs/libX11/Makefile.am @@ -0,0 +1,62 @@ +# +# Copyright 2009 Sun Microsystems, Inc. All rights reserved. +# +# Permission to use, copy, modify, distribute, and sell this software and its +# documentation for any purpose is hereby granted without fee, provided that +# the above copyright notice appear in all copies and that both that +# copyright notice and this permission notice appear in supporting +# documentation. +# +# The above copyright notice and this permission notice shall be included +# in all copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +# OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +# IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR +# OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +# ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +# OTHER DEALINGS IN THE SOFTWARE. +# +# Except as contained in this notice, the name of the copyright holders shall +# not be used in advertising or otherwise to promote the sale, use or +# other dealings in this Software without prior written authorization +# from the copyright holders. +# + +# Based on xc/doc/specs/X11/Makefile from X11R6.9 + +doc_sources = libX11.ms + +doc_includes = \ + abstract.t \ + credits.t \ + CH01 \ + CH02 \ + CH03 \ + CH04 \ + CH05 \ + CH06 \ + CH07 \ + CH08 \ + CH09 \ + CH10 \ + CH11 \ + CH12 \ + CH13 \ + CH14 \ + CH15 \ + CH16 \ + AppA \ + AppB \ + AppC \ + AppD \ + glossary \ + postproc + +include $(top_srcdir)/specs/troffrules.in + +EXTRA_DIST += $(doc_includes) + + + diff --git a/libX11/specs/libX11/Makefile.in b/libX11/specs/libX11/Makefile.in new file mode 100644 index 000000000..d014f41e9 --- /dev/null +++ b/libX11/specs/libX11/Makefile.in @@ -0,0 +1,580 @@ +# Makefile.in generated by automake 1.11 from Makefile.am. +# @configure_input@ + +# Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, +# 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, +# Inc. +# This Makefile.in is free software; the Free Software Foundation +# gives unlimited permission to copy and/or distribute it, +# with or without modifications, as long as this notice is preserved. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY, to the extent permitted by law; without +# even the implied warranty of MERCHANTABILITY or FITNESS FOR A +# PARTICULAR PURPOSE. + +@SET_MAKE@ + +# +# Copyright 2009 Sun Microsystems, Inc. All rights reserved. +# +# Permission to use, copy, modify, distribute, and sell this software and its +# documentation for any purpose is hereby granted without fee, provided that +# the above copyright notice appear in all copies and that both that +# copyright notice and this permission notice appear in supporting +# documentation. +# +# The above copyright notice and this permission notice shall be included +# in all copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +# OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +# IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR +# OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +# ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +# OTHER DEALINGS IN THE SOFTWARE. +# +# Except as contained in this notice, the name of the copyright holders shall +# not be used in advertising or otherwise to promote the sale, use or +# other dealings in this Software without prior written authorization +# from the copyright holders. +# + +# Based on xc/doc/specs/X11/Makefile from X11R6.9 + +# +# Copyright 2009 Sun Microsystems, Inc. All rights reserved. +# +# Permission to use, copy, modify, distribute, and sell this software and its +# documentation for any purpose is hereby granted without fee, provided that +# the above copyright notice appear in all copies and that both that +# copyright notice and this permission notice appear in supporting +# documentation. +# +# The above copyright notice and this permission notice shall be included +# in all copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +# OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +# IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR +# OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +# ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +# OTHER DEALINGS IN THE SOFTWARE. +# +# Except as contained in this notice, the name of the copyright holders shall +# not be used in advertising or otherwise to promote the sale, use or +# other dealings in this Software without prior written authorization +# from the copyright holders. +# + +# Based on xc/doc/specs/*/Makefile from X11R6.9 + +VPATH = @srcdir@ +pkgdatadir = $(datadir)/@PACKAGE@ +pkgincludedir = $(includedir)/@PACKAGE@ +pkglibdir = $(libdir)/@PACKAGE@ +pkglibexecdir = $(libexecdir)/@PACKAGE@ +am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd +install_sh_DATA = $(install_sh) -c -m 644 +install_sh_PROGRAM = $(install_sh) -c +install_sh_SCRIPT = $(install_sh) -c +INSTALL_HEADER = $(INSTALL_DATA) +transform = $(program_transform_name) +NORMAL_INSTALL = : +PRE_INSTALL = : +POST_INSTALL = : +NORMAL_UNINSTALL = : +PRE_UNINSTALL = : +POST_UNINSTALL = : +build_triplet = @build@ +host_triplet = @host@ +DIST_COMMON = $(srcdir)/Makefile.am $(srcdir)/Makefile.in \ + $(top_srcdir)/specs/troffrules.in +subdir = specs/libX11 +ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 +am__aclocal_m4_deps = $(top_srcdir)/acinclude.m4 \ + $(top_srcdir)/configure.ac +am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ + $(ACLOCAL_M4) +mkinstalldirs = $(install_sh) -d +CONFIG_HEADER = $(top_builddir)/src/config.h \ + $(top_builddir)/include/X11/XlibConf.h +CONFIG_CLEAN_FILES = +CONFIG_CLEAN_VPATH_FILES = +AM_V_GEN = $(am__v_GEN_$(V)) +am__v_GEN_ = $(am__v_GEN_$(AM_DEFAULT_VERBOSITY)) +am__v_GEN_0 = @echo " GEN " $@; +AM_V_at = $(am__v_at_$(V)) +am__v_at_ = $(am__v_at_$(AM_DEFAULT_VERBOSITY)) +am__v_at_0 = @ +SOURCES = +DIST_SOURCES = +am__vpath_adj_setup = srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; +am__vpath_adj = case $$p in \ + $(srcdir)/*) f=`echo "$$p" | sed "s|^$$srcdirstrip/||"`;; \ + *) f=$$p;; \ + esac; +am__strip_dir = f=`echo $$p | sed -e 's|^.*/||'`; +am__install_max = 40 +am__nobase_strip_setup = \ + srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*|]/\\\\&/g'` +am__nobase_strip = \ + for p in $$list; do echo "$$p"; done | sed -e "s|$$srcdirstrip/||" +am__nobase_list = $(am__nobase_strip_setup); \ + for p in $$list; do echo "$$p $$p"; done | \ + sed "s| $$srcdirstrip/| |;"' / .*\//!s/ .*/ ./; s,\( .*\)/[^/]*$$,\1,' | \ + $(AWK) 'BEGIN { files["."] = "" } { files[$$2] = files[$$2] " " $$1; \ + if (++n[$$2] == $(am__install_max)) \ + { print $$2, files[$$2]; n[$$2] = 0; files[$$2] = "" } } \ + END { for (dir in files) print dir, files[dir] }' +am__base_list = \ + sed '$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;s/\n/ /g' | \ + sed '$$!N;$$!N;$$!N;$$!N;s/\n/ /g' +am__installdirs = "$(DESTDIR)$(docdir)" +DATA = $(doc_DATA) +DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) +ACLOCAL = @ACLOCAL@ +ADMIN_MAN_DIR = @ADMIN_MAN_DIR@ +ADMIN_MAN_SUFFIX = @ADMIN_MAN_SUFFIX@ +AMTAR = @AMTAR@ +AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@ +APP_MAN_DIR = @APP_MAN_DIR@ +APP_MAN_SUFFIX = @APP_MAN_SUFFIX@ +AR = @AR@ +AUTOCONF = @AUTOCONF@ +AUTOHEADER = @AUTOHEADER@ +AUTOMAKE = @AUTOMAKE@ +AWK = @AWK@ +BIGFONT_CFLAGS = @BIGFONT_CFLAGS@ +BIGFONT_LIBS = @BIGFONT_LIBS@ +CC = @CC@ +CCDEPMODE = @CCDEPMODE@ +CC_FOR_BUILD = @CC_FOR_BUILD@ +CFLAGS = @CFLAGS@ +CHANGELOG_CMD = @CHANGELOG_CMD@ +CPP = @CPP@ +CPPFLAGS = @CPPFLAGS@ +CWARNFLAGS = @CWARNFLAGS@ +CXX = @CXX@ +CXXCPP = @CXXCPP@ +CXXDEPMODE = @CXXDEPMODE@ +CXXFLAGS = @CXXFLAGS@ +CYGPATH_W = @CYGPATH_W@ +DEFS = @DEFS@ +DEPDIR = @DEPDIR@ +DOLT_BASH = @DOLT_BASH@ +DRIVER_MAN_DIR = @DRIVER_MAN_DIR@ +DRIVER_MAN_SUFFIX = @DRIVER_MAN_SUFFIX@ +DSYMUTIL = @DSYMUTIL@ +ECHO = @ECHO@ +ECHO_C = @ECHO_C@ +ECHO_N = @ECHO_N@ +ECHO_T = @ECHO_T@ +EGREP = @EGREP@ +EXEEXT = @EXEEXT@ +F77 = @F77@ +FFLAGS = @FFLAGS@ +FILE_MAN_DIR = @FILE_MAN_DIR@ +FILE_MAN_SUFFIX = @FILE_MAN_SUFFIX@ +GREP = @GREP@ +GROFF = @GROFF@ +I18N_MODULE_LIBS = @I18N_MODULE_LIBS@ +INSTALL = @INSTALL@ +INSTALL_DATA = @INSTALL_DATA@ +INSTALL_PROGRAM = @INSTALL_PROGRAM@ +INSTALL_SCRIPT = @INSTALL_SCRIPT@ +INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@ +KEYSYMDEF = @KEYSYMDEF@ +LAUNCHD = @LAUNCHD@ +LDFLAGS = @LDFLAGS@ +LIBOBJS = @LIBOBJS@ +LIBS = @LIBS@ +LIBTOOL = @LIBTOOL@ +LIB_MAN_DIR = @LIB_MAN_DIR@ +LIB_MAN_SUFFIX = @LIB_MAN_SUFFIX@ +LINT = @LINT@ +LINTLIB = @LINTLIB@ +LINT_FLAGS = @LINT_FLAGS@ +LN_S = @LN_S@ +LTCOMPILE = @LTCOMPILE@ +LTCXXCOMPILE = @LTCXXCOMPILE@ +LTLIBOBJS = @LTLIBOBJS@ +MAINT = @MAINT@ +MAKEINFO = @MAKEINFO@ +MALLOC_ZERO_CFLAGS = @MALLOC_ZERO_CFLAGS@ +MISC_MAN_DIR = @MISC_MAN_DIR@ +MISC_MAN_SUFFIX = @MISC_MAN_SUFFIX@ +MKDIR_P = @MKDIR_P@ +NMEDIT = @NMEDIT@ +OBJEXT = @OBJEXT@ +PACKAGE = @PACKAGE@ +PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@ +PACKAGE_NAME = @PACKAGE_NAME@ +PACKAGE_STRING = @PACKAGE_STRING@ +PACKAGE_TARNAME = @PACKAGE_TARNAME@ +PACKAGE_VERSION = @PACKAGE_VERSION@ +PATH_SEPARATOR = @PATH_SEPARATOR@ +PERL = @PERL@ +PKG_CONFIG = @PKG_CONFIG@ +PS2PDF = @PS2PDF@ +RANLIB = @RANLIB@ +RAWCPP = @RAWCPP@ +RAWCPPFLAGS = @RAWCPPFLAGS@ +SED = @SED@ +SET_MAKE = @SET_MAKE@ +SHELL = @SHELL@ +STRIP = @STRIP@ +VERSION = @VERSION@ +WCHAR32 = @WCHAR32@ +X11_CFLAGS = @X11_CFLAGS@ +X11_DATADIR = @X11_DATADIR@ +X11_EXTRA_DEPS = @X11_EXTRA_DEPS@ +X11_LIBDIR = @X11_LIBDIR@ +X11_LIBS = @X11_LIBS@ +X11_LOCALEDATADIR = @X11_LOCALEDATADIR@ +X11_LOCALEDIR = @X11_LOCALEDIR@ +X11_LOCALELIBDIR = @X11_LOCALELIBDIR@ +XDMCP_CFLAGS = @XDMCP_CFLAGS@ +XDMCP_LIBS = @XDMCP_LIBS@ +XERRORDB = @XERRORDB@ +XKBPROTO_CFLAGS = @XKBPROTO_CFLAGS@ +XKBPROTO_LIBS = @XKBPROTO_LIBS@ +XKBPROTO_REQUIRES = @XKBPROTO_REQUIRES@ +XKEYSYMDB = @XKEYSYMDB@ +XLOCALEDATADIR = @XLOCALEDATADIR@ +XLOCALEDIR = @XLOCALEDIR@ +XLOCALELIBDIR = @XLOCALELIBDIR@ +XMALLOC_ZERO_CFLAGS = @XMALLOC_ZERO_CFLAGS@ +XPROTO_CFLAGS = @XPROTO_CFLAGS@ +XPROTO_LIBS = @XPROTO_LIBS@ +XTHREADLIB = @XTHREADLIB@ +XTHREAD_CFLAGS = @XTHREAD_CFLAGS@ +XTMALLOC_ZERO_CFLAGS = @XTMALLOC_ZERO_CFLAGS@ +abs_builddir = @abs_builddir@ +abs_srcdir = @abs_srcdir@ +abs_top_builddir = @abs_top_builddir@ +abs_top_srcdir = @abs_top_srcdir@ +ac_ct_CC = @ac_ct_CC@ +ac_ct_CXX = @ac_ct_CXX@ +ac_ct_F77 = @ac_ct_F77@ +am__include = @am__include@ +am__leading_dot = @am__leading_dot@ +am__quote = @am__quote@ +am__tar = @am__tar@ +am__untar = @am__untar@ +bindir = @bindir@ +build = @build@ +build_alias = @build_alias@ +build_cpu = @build_cpu@ +build_os = @build_os@ +build_vendor = @build_vendor@ +builddir = @builddir@ +datadir = @datadir@ +datarootdir = @datarootdir@ +distcleancheck_listfiles = @distcleancheck_listfiles@ +docdir = @docdir@ +dvidir = @dvidir@ +exec_prefix = @exec_prefix@ +host = @host@ +host_alias = @host_alias@ +host_cpu = @host_cpu@ +host_os = @host_os@ +host_vendor = @host_vendor@ +htmldir = @htmldir@ +includedir = @includedir@ +infodir = @infodir@ +install_sh = @install_sh@ +libdir = @libdir@ +libexecdir = @libexecdir@ +localedir = @localedir@ +localstatedir = @localstatedir@ +mandir = @mandir@ +mkdir_p = @mkdir_p@ +oldincludedir = @oldincludedir@ +pdfdir = @pdfdir@ +prefix = @prefix@ +program_transform_name = @program_transform_name@ +psdir = @psdir@ +sbindir = @sbindir@ +sharedstatedir = @sharedstatedir@ +srcdir = @srcdir@ +sysconfdir = @sysconfdir@ +target_alias = @target_alias@ +top_build_prefix = @top_build_prefix@ +top_builddir = @top_builddir@ +top_srcdir = @top_srcdir@ +doc_sources = libX11.ms +doc_includes = \ + abstract.t \ + credits.t \ + CH01 \ + CH02 \ + CH03 \ + CH04 \ + CH05 \ + CH06 \ + CH07 \ + CH08 \ + CH09 \ + CH10 \ + CH11 \ + CH12 \ + CH13 \ + CH14 \ + CH15 \ + CH16 \ + AppA \ + AppB \ + AppC \ + AppD \ + glossary \ + postproc + +EXTRA_DIST = $(doc_sources) $(doc_includes) +@HAVE_PS2PDF_FALSE@printable_format = .ps +@HAVE_PS2PDF_TRUE@printable_format = .pdf +@BUILD_SPECS_TRUE@doc_DATA = $(doc_sources:.ms=.txt) \ +@BUILD_SPECS_TRUE@ $(doc_sources:.ms=$(printable_format)) \ +@BUILD_SPECS_TRUE@ $(doc_sources:.ms=.html) + +@BUILD_SPECS_TRUE@CLEANFILES = $(doc_DATA) +@BUILD_SPECS_TRUE@MOSTLYCLEANFILES = index.* + +# Pass version string as a troff string for substitution +@BUILD_SPECS_TRUE@GROFF_DEFS = -dxV="$(PACKAGE_STRING)" + +# -e to run through eqn, -t to run through tbl +@BUILD_SPECS_TRUE@GROFF_FLAGS = -e -t -ms $(GROFF_DEFS) $(top_srcdir)/specs/macros.t +@BUILD_SPECS_TRUE@SUFFIXES = .ms .ps .txt .html .pdf +all: all-am + +.SUFFIXES: +.SUFFIXES: .ms .ps .txt .html .pdf +$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(top_srcdir)/specs/troffrules.in $(am__configure_deps) + @for dep in $?; do \ + case '$(am__configure_deps)' in \ + *$$dep*) \ + ( cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh ) \ + && { if test -f $@; then exit 0; else break; fi; }; \ + exit 1;; \ + esac; \ + done; \ + echo ' cd $(top_srcdir) && $(AUTOMAKE) --foreign specs/libX11/Makefile'; \ + $(am__cd) $(top_srcdir) && \ + $(AUTOMAKE) --foreign specs/libX11/Makefile +.PRECIOUS: Makefile +Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status + @case '$?' in \ + *config.status*) \ + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \ + *) \ + echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \ + cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \ + esac; + +$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh + +$(top_srcdir)/configure: @MAINTAINER_MODE_TRUE@ $(am__configure_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(ACLOCAL_M4): @MAINTAINER_MODE_TRUE@ $(am__aclocal_m4_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(am__aclocal_m4_deps): + +mostlyclean-libtool: + -rm -f *.lo + +clean-libtool: + -rm -rf .libs _libs +install-docDATA: $(doc_DATA) + @$(NORMAL_INSTALL) + test -z "$(docdir)" || $(MKDIR_P) "$(DESTDIR)$(docdir)" + @list='$(doc_DATA)'; test -n "$(docdir)" || list=; \ + for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + echo "$$d$$p"; \ + done | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(docdir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(docdir)" || exit $$?; \ + done + +uninstall-docDATA: + @$(NORMAL_UNINSTALL) + @list='$(doc_DATA)'; test -n "$(docdir)" || list=; \ + files=`for p in $$list; do echo $$p; done | sed -e 's|^.*/||'`; \ + test -n "$$files" || exit 0; \ + echo " ( cd '$(DESTDIR)$(docdir)' && rm -f" $$files ")"; \ + cd "$(DESTDIR)$(docdir)" && rm -f $$files +tags: TAGS +TAGS: + +ctags: CTAGS +CTAGS: + + +distdir: $(DISTFILES) + @srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + list='$(DISTFILES)'; \ + dist_files=`for file in $$list; do echo $$file; done | \ + sed -e "s|^$$srcdirstrip/||;t" \ + -e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \ + case $$dist_files in \ + */*) $(MKDIR_P) `echo "$$dist_files" | \ + sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \ + sort -u` ;; \ + esac; \ + for file in $$dist_files; do \ + if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \ + if test -d $$d/$$file; then \ + dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \ + if test -d "$(distdir)/$$file"; then \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ + fi; \ + if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \ + cp -fpR $(srcdir)/$$file "$(distdir)$$dir" || exit 1; \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ + fi; \ + cp -fpR $$d/$$file "$(distdir)$$dir" || exit 1; \ + else \ + test -f "$(distdir)/$$file" \ + || cp -p $$d/$$file "$(distdir)/$$file" \ + || exit 1; \ + fi; \ + done +check-am: all-am +check: check-am +all-am: Makefile $(DATA) +installdirs: + for dir in "$(DESTDIR)$(docdir)"; do \ + test -z "$$dir" || $(MKDIR_P) "$$dir"; \ + done +install: install-am +install-exec: install-exec-am +install-data: install-data-am +uninstall: uninstall-am + +install-am: all-am + @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am + +installcheck: installcheck-am +install-strip: + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + `test -z '$(STRIP)' || \ + echo "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'"` install +mostlyclean-generic: + -test -z "$(MOSTLYCLEANFILES)" || rm -f $(MOSTLYCLEANFILES) + +clean-generic: + -test -z "$(CLEANFILES)" || rm -f $(CLEANFILES) + +distclean-generic: + -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES) + -test . = "$(srcdir)" || test -z "$(CONFIG_CLEAN_VPATH_FILES)" || rm -f $(CONFIG_CLEAN_VPATH_FILES) + +maintainer-clean-generic: + @echo "This command is intended for maintainers to use" + @echo "it deletes files that may require special tools to rebuild." +clean: clean-am + +clean-am: clean-generic clean-libtool mostlyclean-am + +distclean: distclean-am + -rm -f Makefile +distclean-am: clean-am distclean-generic + +dvi: dvi-am + +dvi-am: + +html: html-am + +html-am: + +info: info-am + +info-am: + +install-data-am: install-docDATA + +install-dvi: install-dvi-am + +install-dvi-am: + +install-exec-am: + +install-html: install-html-am + +install-html-am: + +install-info: install-info-am + +install-info-am: + +install-man: + +install-pdf: install-pdf-am + +install-pdf-am: + +install-ps: install-ps-am + +install-ps-am: + +installcheck-am: + +maintainer-clean: maintainer-clean-am + -rm -f Makefile +maintainer-clean-am: distclean-am maintainer-clean-generic + +mostlyclean: mostlyclean-am + +mostlyclean-am: mostlyclean-generic mostlyclean-libtool + +pdf: pdf-am + +pdf-am: + +ps: ps-am + +ps-am: + +uninstall-am: uninstall-docDATA + +.MAKE: install-am install-strip + +.PHONY: all all-am check check-am clean clean-generic clean-libtool \ + distclean distclean-generic distclean-libtool distdir dvi \ + dvi-am html html-am info info-am install install-am \ + install-data install-data-am install-docDATA install-dvi \ + install-dvi-am install-exec install-exec-am install-html \ + install-html-am install-info install-info-am install-man \ + install-pdf install-pdf-am install-ps install-ps-am \ + install-strip installcheck installcheck-am installdirs \ + maintainer-clean maintainer-clean-generic mostlyclean \ + mostlyclean-generic mostlyclean-libtool pdf pdf-am ps ps-am \ + uninstall uninstall-am uninstall-docDATA + + +@BUILD_SPECS_TRUE@.ms.ps: +@BUILD_SPECS_TRUE@ -$(AM_V_GEN) $(GROFF) -Tps $(GROFF_FLAGS) $< 2> index.$@.raw > $@ +@BUILD_SPECS_TRUE@ @if grep '^[^1-9.]' index.$@.raw | grep -v warning; then exit 1; \ +@BUILD_SPECS_TRUE@ else test $$? -le 1; fi + +@BUILD_SPECS_TRUE@.ms.txt: +@BUILD_SPECS_TRUE@ $(AM_V_GEN) env GROFF_NO_SGR=TRUE $(GROFF) -Tutf8 $(GROFF_FLAGS) \ +@BUILD_SPECS_TRUE@ $< 2> index.$@.raw > $@ + +@BUILD_SPECS_TRUE@.ms.html: +@BUILD_SPECS_TRUE@ $(AM_V_GEN) $(GROFF) -Thtml $(GROFF_FLAGS) $< 2> index.$@.raw > $@ + +@BUILD_SPECS_TRUE@.ps.pdf: +@BUILD_SPECS_TRUE@ $(AM_V_GEN) $(PS2PDF) $< $@ + +# Tell versions [3.59,3.63) of GNU make to not export all variables. +# Otherwise a system limit (for SysV at least) may be exceeded. +.NOEXPORT: diff --git a/libX11/specs/libX11/abstract.t b/libX11/specs/libX11/abstract.t new file mode 100644 index 000000000..fe15d1fb0 --- /dev/null +++ b/libX11/specs/libX11/abstract.t @@ -0,0 +1,106 @@ +.\" $XFree86: xc/doc/specs/X11/abstract.t,v 1.2 2003/07/09 15:27:26 tsi Exp $ +.EH '''' +.OH '''' +.EF '''' +.OF '''' +.ps 11 +.nr PS 11 +\& +.sp 5 +.ce 6 +\s+2\fBXlib \- C Language X Interface\fP\s-2 + +\s+1\fBX Window System Standard\fP\s-1 + +\s+1\fBX Version 11, Release 7\fP\s-1 + +\s+1\fB\*(xV\fP\s-1 +.sp 6 +.ce 4 +\s-1James Gettys +.sp 6p +Cambridge Research Laboratory +Digital Equipment Corporation +.sp 2 +.ce 4 +Robert W. Scheifler +.sp 6p +Laboratory for Computer Science +Massachusetts Institute of Technology +.sp 3 +.ce 1 +\fIwith contributions from\fP +.sp 3 +.ce 11 +Chuck Adams, Tektronix, Inc. +.sp 1 +Vania Joloboff, Open Software Foundation +.sp 1 +Hideki Hiura, Sun Microsystems, Inc. +.sp 1 +Bill McMahon, Hewlett-Packard Company +.sp 1 +Ron Newman, Massachusetts Institute of Technology +.sp 1 +Al Tabayoyon, Tektronix, Inc. +.sp 1 +Glenn Widener, Tektronix, Inc. +.sp 1 +Shigeru Yamada, Fujitsu OSSI +.bp +\& +.ps 9 +.nr PS 9 +.sp 8 +.LP +The X Window System is a trademark of The Open Group. +.LP +TekHVC is a trademark of Tektronix, Inc. +.sp 2 +.LP +Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996, 2002 +The Open Group +.LP +Permission is hereby granted, free of charge, to any person obtaining +a copy of this software and associated documentation files (the +"Software"), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so, subject to +the following conditions: +.LP +The above copyright notice and this permission notice shall be included +in all copies or substantial portions of the Software. +.LP +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR +OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +OTHER DEALINGS IN THE SOFTWARE. +.LP +Except as contained in this notice, the name of The Open Group shall +not be used in advertising or otherwise to promote the sale, use or +other dealings in this Software without prior written authorization +from The Open Group. +.sp 3 +.LP +Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by +Digital Equipment Corporation +.LP +Portions Copyright \(co 1990, 1991 by +Tektronix, Inc. +.LP +Permission to use, copy, modify and distribute this documentation for +any purpose and without fee is hereby granted, provided that the above +copyright notice appears in all copies and that both that copyright notice and +this permission notice appear in all copies, and that the names of +Digital and Tektronix not be used in in advertising or publicity +pertaining to this documentation without specific, written prior permission. +Digital and Tektronix makes no representations about the suitability +of this documentation for any purpose. +It is provided ``as is'' without express or implied warranty. +.ps 11 +.nr PS 11 +.bp diff --git a/libX11/specs/libX11/credits.t b/libX11/specs/libX11/credits.t new file mode 100644 index 000000000..5d9909d7c --- /dev/null +++ b/libX11/specs/libX11/credits.t @@ -0,0 +1,216 @@ +.EH '''' +.OH '''' +.EF '''' +.OF '''' +.XS ii +Table of Contents +.XE +.XS iii +Acknowledgments +.XE +\& +.sp 1 +.ce 3 +\s+1\fBAcknowledgments\fP\s-1 +.sp 2 +.na +.LP +The design and implementation of the first 10 versions of X +were primarily the work of three individuals: Robert Scheifler of the +MIT Laboratory for Computer Science and Jim Gettys of Digital +Equipment Corporation and Ron Newman of MIT, both at MIT +Project Athena. +X version 11, however, is the result of the efforts of +dozens of individuals at almost as many locations and organizations. +At the risk of offending some of the players by exclusion, +we would like to acknowledge some of the people who deserve special credit +and recognition for their work on Xlib. +Our apologies to anyone inadvertently overlooked. +.SH +Release 1 +.LP +Our thanks does to Ron Newman (MIT Project Athena), +who contributed substantially to the +design and implementation of the Version 11 Xlib interface. +.LP +Our thanks also goes to Ralph Swick (Project Athena and Digital) who kept +it all together for us during the early releases. +He handled literally thousands of requests from people everywhere +and saved the sanity of at least one of us. +His calm good cheer was a foundation on which we could build. +.LP +Our thanks also goes to Todd Brunhoff (Tektronix) who was ``loaned'' +to Project Athena at exactly the right moment to provide very capable +and much-needed assistance during the alpha and beta releases. +He was responsible for the successful integration of sources +from multiple sites; +we would not have had a release without him. +.LP +Our thanks also goes to Al Mento and Al Wojtas of Digital's ULTRIX +Documentation Group. +With good humor and cheer, +they took a rough draft and made it an infinitely better and more useful +document. +The work they have done will help many everywhere. +We also would like to thank Hal Murray (Digital SRC) and +Peter George (Digital VMS) who contributed much +by proofreading the early drafts of this document. +.LP +Our thanks also goes to Jeff Dike (Digital UEG), Tom Benson, +Jackie Granfield, and Vince Orgovan (Digital VMS) who helped with the +library utilities implementation; +to Hania Gajewska (Digital UEG-WSL) who, +along with Ellis Cohen (CMU and Siemens), +was instrumental in the semantic design of the window manager properties; +and to Dave Rosenthal (Sun Microsystems) who also contributed to the protocol +and provided the sample generic color frame buffer device-dependent code. +.LP +The alpha and beta test participants deserve special recognition and thanks +as well. +It is significant +that the bug reports (and many fixes) during alpha and beta test came almost +exclusively from just a few of the alpha testers, mostly hardware vendors +working on product implementations of X. +The continued public +contribution of vendors and universities is certainly to the benefit +of the entire X community. +.LP +Our special thanks must go to Sam Fuller, Vice-President of Corporate +Research at Digital, who has remained committed to the widest public +availability of X and who made it possible to greatly supplement MIT's +resources with the Digital staff in order to make version 11 a reality. +Many of the people mentioned here are part of the Western +Software Laboratory (Digital UEG-WSL) of the ULTRIX Engineering group +and work for Smokey Wallace, who has been vital to the project's success. +Others not mentioned here worked on the toolkit and are acknowledged +in the X Toolkit documentation. +.LP +Of course, +we must particularly thank Paul Asente, formerly of Stanford University +and now of Digital UEG-WSL, who wrote W, the predecessor to X, +and Brian Reid, formerly of Stanford University and now of Digital WRL, +who had much to do with W's design. +.LP +Finally, our thanks goes to MIT, Digital Equipment Corporation, +and IBM for providing the environment where it could happen. +.SH +Release 4 +.LP +Our thanks go to Jim Fulton (MIT X Consortium) for designing and +specifying the new Xlib functions for Inter-Client Communication +Conventions (ICCCM) support. +.LP +We also thank Al Mento of Digital for his continued effort in +maintaining this document and Jim Fulton and Donna Converse (MIT X Consortium) +for their much-appreciated efforts in reviewing the changes. +.SH +Release 5 +.LP +The principal authors of the Input Method facilities are +Vania Joloboff (Open Software Foundation) and Bill McMahon (Hewlett-Packard). +The principal author of the rest of the internationalization facilities +is Glenn Widener (Tektronix). Our thanks to them for keeping their +sense of humor through a long and sometimes difficult design process. +Although the words and much of the design are due to them, many others +have contributed substantially to the design and implementation. +Tom McFarland (HP) and Frank Rojas (IBM) deserve particular recognition +for their contributions. Other contributors were: +Tim Anderson (Motorola), Alka Badshah (OSF), Gabe Beged-Dov (HP), +Chih-Chung Ko (III), Vera Cheng (III), Michael Collins (Digital), +Walt Daniels (IBM), Noritoshi Demizu (OMRON), Keisuke Fukui (Fujitsu), +Hitoshoi Fukumoto (Nihon Sun), Tim Greenwood (Digital), John Harvey (IBM), +Hideki Hiura (Sun), Fred Horman (AT&T), Norikazu Kaiya (Fujitsu), +Yuji Kamata (IBM), +Yutaka Kataoka (Waseda University), Ranee Khubchandani (Sun), Akira Kon (NEC), +Hiroshi Kuribayashi (OMRON), Teruhiko Kurosaka (Sun), Seiji Kuwari (OMRON), +Sandra Martin (OSF), Narita Masahiko (Fujitsu), Masato Morisaki (NTT), +Nelson Ng (Sun), +Takashi Nishimura (NTT America), Makato Nishino (IBM), +Akira Ohsone (Nihon Sun), Chris Peterson (MIT), Sam Shteingart (AT&T), +Manish Sheth (AT&T), Muneiyoshi Suzuki (NTT), Cori Mehring (Digital), +Shoji Sugiyama (IBM), and Eiji Tosa (IBM). +.LP +We are deeply indebted to Tatsuya Kato (NTT), +Hiroshi Kuribayashi (OMRON), Seiji Kuwari (OMRON), Muneiyoshi Suzuki (NTT), +and Li Yuhong (OMRON) for producing one of the first complete +sample implementation of the internationalization facilities, and +Hiromu Inukai (Nihon Sun), Takashi Fujiwara (Fujitsu), Hideki Hiura (Sun), +Yasuhiro Kawai (Oki Technosystems Laboratory), Kazunori Nishihara (Fuji Xerox), +Masaki Takeuchi (Sony), Katsuhisa Yano (Toshiba), +Makoto Wakamatsu (Sony Corporation) for producing the another complete +sample implementation of the internationalization facilities. +.LP +The principal authors (design and implementation) of the Xcms color +management facilities are Al Tabayoyon (Tektronix) +and Chuck Adams (Tektronix). +Joann Taylor (Tektronix), Bob Toole (Tektronix), +and Keith Packard (MIT X Consortium) also +contributed significantly to the design. Others who contributed are: +Harold Boll (Kodak), Ken Bronstein (HP), Nancy Cam (SGI), +Donna Converse (MIT X Consortium), Elias Israel (ISC), Deron Johnson (Sun), +Jim King (Adobe), Ricardo Motta (HP), Chuck Peek (IBM), +Wil Plouffe (IBM), Dave Sternlicht (MIT X Consortium), Kumar Talluri (AT&T), +and Richard Verberg (IBM). +.LP +We also once again thank Al Mento of Digital for his work in formatting +and reformatting text for this manual, and for producing man pages. +Thanks also to Clive Feather (IXI) for proof-reading and finding a +number of small errors. +.SH +Release 6 +.LP +Stephen Gildea (X Consortium) authored the threads support. +Ovais Ashraf (Sun) and Greg Olsen (Sun) contributed substantially +by testing the facilities and reporting bugs in a timely fashion. +.LP +The principal authors of the internationalization facilities, including +Input and Output Methods, are Hideki Hiura (SunSoft) and +Shigeru Yamada (Fujitsu OSSI). +Although the words and much of the design are due to them, many others +have contributed substantially to the design and implementation. +They are: Takashi Fujiwara (Fujitsu), Yoshio Horiuchi (IBM), +Makoto Inada (Digital), Hiromu Inukai (Nihon SunSoft), +Song JaeKyung (KAIST), Franky Ling (Digital), Tom McFarland (HP), +Hiroyuki Miyamoto (Digital), Masahiko Narita (Fujitsu), +Frank Rojas (IBM), Hidetoshi Tajima (HP), Masaki Takeuchi (Sony), +Makoto Wakamatsu (Sony), Masaki Wakao (IBM), Katsuhisa Yano(Toshiba) and +Jinsoo Yoon (KAIST). +.LP +The principal producers of the sample implementation of the +internationalization facilities are: +Jeffrey Bloomfield (Fujitsu OSSI), Takashi Fujiwara (Fujitsu), +Hideki Hiura (SunSoft), Yoshio Horiuchi (IBM), +Makoto Inada (Digital), Hiromu Inukai (Nihon SunSoft), +Song JaeKyung (KAIST), Riki Kawaguchi (Fujitsu), +Franky Ling (Digital), Hiroyuki Miyamoto (Digital), +Hidetoshi Tajima (HP), Toshimitsu Terazono (Fujitsu), +Makoto Wakamatsu (Sony), Masaki Wakao (IBM), +Shigeru Yamada (Fujitsu OSSI) and Katsuhisa Yano (Toshiba). +.LP +The coordinators of the integration, testing, and release of this +implementation of the internationalization facilities are +Nobuyuki Tanaka (Sony) and Makoto Wakamatsu (Sony). +.LP +Others who have contributed to the architectural design or +testing of the sample implementation of the +internationalization facilities are: +Hector Chan (Digital), Michael Kung (IBM), Joseph Kwok (Digital), +Hiroyuki Machida (Sony), Nelson Ng (SunSoft), Frank Rojas (IBM), +Yoshiyuki Segawa (Fujitsu OSSI), Makiko Shimamura (Fujitsu), +Shoji Sugiyama (IBM), Lining Sun (SGI), Masaki Takeuchi (Sony), +Jinsoo Yoon (KAIST) and Akiyasu Zen (HP). +.sp 2 +.LP +.Ds 0 +.TA 1.5i 3i +.ta 1.5i 3i +.R +Jim Gettys +Cambridge Research Laboratory +Digital Equipment Corporation + +Robert W. Scheifler +Laboratory for Computer Science +Massachusetts Institute of Technology +.DE +.bp 1 diff --git a/libX11/specs/libX11/glossary b/libX11/specs/libX11/glossary new file mode 100644 index 000000000..a130928a6 --- /dev/null +++ b/libX11/specs/libX11/glossary @@ -0,0 +1,1484 @@ +\& +.sp 1 +.ce 1 +\s+1\fBGlossary\fP\s-1 +.sp 2 +.na +.LP +.XS +Glossary +.XE +.KS +\fBAccess control list\fP +.IN "Access control list" "" "@DEF@" +.IP +X maintains a list of hosts from which client programs can be run. +By default, +only programs on the local host and hosts specified in an initial list read +by the server can use the display. +This access control list can be changed by clients on the local host. +Some server implementations can also implement other authorization mechanisms +in addition to or in place of this mechanism. +The action of this mechanism can be conditional based on the authorization +protocol name and data received by the server at connection setup. +.KE +.LP +.KS +\fBActive grab\fP +.IN "Active grab" "" "@DEF@" +.IP +A grab is active when the pointer or keyboard is actually owned by the +single grabbing client. +.KE +.LP +.KS +\fBAncestors\fP +.IN "Ancestors" "" "@DEF@" +.IP +If W is an inferior of A, then A is an ancestor of W. +.KE +.LP +.KS +\fBAtom\fP +.IN "Atom" "" "@DEF@" +.IP +An atom is a unique ID corresponding to a string name. +Atoms are used to identify properties, types, and selections. +.KE +.LP +.KS +\fBBackground\fP +.IN "Background" "" "@DEF@" +.IP +An +.PN InputOutput +window can have a background, which is defined as a pixmap. +When regions of the window have their contents lost +or invalidated, +the server automatically tiles those regions with the background. +.KE +.LP +.KS +\fBBacking store\fP +.IN "Backing store" "" "@DEF@" +.IP +When a server maintains the contents of a window, +the pixels saved off-screen are known as a backing store. +.KE +.LP +.KS +\fBBase font name\fP +.IN "Base font name" "" "@DEF@" +.IP +A font name used to select a family of fonts whose members may be encoded +in various charsets. +The +.PN CharSetRegistry +and +.PN CharSetEncoding +fields of an XLFD name identify the charset of the font. +A base font name may be a full XLFD name, with all fourteen '-' delimiters, +or an abbreviated XLFD name containing only the first 12 fields of an XLFD name, +up to but not including +.PN CharSetRegistry , +with or without the thirteenth '-', or a non-XLFD name. +Any XLFD fields may contain wild cards. +.IP +When creating an +.PN XFontSet , +Xlib accepts from the client a list of one or more base font names +which select one or more font families. +They are combined with charset names obtained from the encoding of the locale +to load the fonts required to render text. +.KE +.LP +.KS +\fBBit gravity\fP +.IN "Bit" "gravity" "@DEF@" +.IP +When a window is resized, +the contents of the window are not necessarily discarded. +It is possible to request that the server relocate the previous contents +to some region of the window (though no guarantees are made). +This attraction of window contents for some location of +a window is known as bit gravity. +.KE +.LP +.KS +\fBBit plane\fP +.IN "Bit" "plane" "@DEF@" +.IP +When a pixmap or window is thought of as a stack of bitmaps, +each bitmap is called a bit plane or plane. +.KE +.LP +.KS +\fBBitmap\fP +.IN "Bitmap" "" "@DEF@" +.IP +A bitmap is a pixmap of depth one. +.KE +.LP +.KS +\fBBorder\fP +.IN "Border" "" "@DEF@" +.IP +An +.PN InputOutput +window can have a border of equal thickness on all four sides of the window. +The contents of the border are defined by a pixmap, +and the server automatically maintains the contents of the border. +Exposure events are never generated for border regions. +.KE +.LP +.KS +\fBButton grabbing\fP +.IN "Button" "grabbing" "@DEF@" +.IP +Buttons on the pointer can be passively grabbed by a client. +When the button is pressed, +the pointer is then actively grabbed by the client. +.KE +.LP +.KS +\fBByte order\fP +.IN "Byte" "order" "@DEF@" +.IP +For image (pixmap/bitmap) data, +the server defines the byte order, +and clients with different native byte ordering must swap bytes as +necessary. +For all other parts of the protocol, +the client defines the byte order, +and the server swaps bytes as necessary. +.KE +.LP +.KS +\fBCharacter\fP +.IN "Character" "" "@DEF@" +.IP +A member of a set of elements used for the organization, +control, or representation of text (ISO2022, as adapted by XPG3). +Note that in ISO2022 terms, a character is not bound to a coded value +until it is identified as part of a coded character set. +.KE +.LP +.KS +\fBCharacter glyph\fP +.IN "Character glyph" "" "@DEF@" +.IP +The abstract graphical symbol for a character. +Character glyphs may or may not map one-to-one to font glyphs, +and may be context-dependent, varying with the adjacent characters. +Multiple characters may map to a single character glyph. +.KE +.LP +.KS +\fBCharacter set\fP +.IN "Character set" "" "@DEF@" +.IP +A collection of characters. +.KE +.LP +.KS +\fBCharset\fP +.IN "Charset" "" "@DEF@" +.IP +An encoding with a uniform, state-independent mapping from characters +to codepoints. +A coded character set. +.IP +For display in X, +there can be a direct mapping from a charset to one font, +if the width of all characters in the charset is either one or two bytes. +A text string encoded in an encoding such as Shift-JIS cannot be passed +directly to the X server, because the text imaging requests accept only +single-width charsets (either 8 or 16 bits). +Charsets which meet these restrictions can serve as ``font charsets''. +Font charsets strictly speaking map font indices to font glyphs, +not characters to character glyphs. +.IP +Note that a single font charset is sometimes used as the encoding of a locale, +for example, ISO8859-1. +.KE +.LP +.KS +\fBChildren\fP +.IN "Children" "" "@DEF@" +.IP +The children of a window are its first-level subwindows. +.KE +.LP +.KS +\fBClass\fP +.IN "Class" "" "@DEF@" +.IP +Windows can be of different classes or types. +See the entries for +.PN InputOnly +and +.PN InputOutput +windows for further information about valid window types. +.KE +.LP +.KS +\fBClient\fP +.IN "Client" "" "@DEF@" +.IP +An application program connects to the window system server by some +interprocess communication (IPC) path, such as a TCP connection or a +shared memory buffer. +This program is referred to as a client of the window system server. +More precisely, +the client is the IPC path itself. +A program with multiple paths open to the server is viewed as +multiple clients by the protocol. +Resource lifetimes are controlled by +connection lifetimes, not by program lifetimes. +.KE +.LP +.KS +\fBClipping region\fP +.IN "Clipping region" "" "@DEF@" +.IP +In a graphics context, +a bitmap or list of rectangles can be specified +to restrict output to a particular region of the window. +The image defined by the bitmap or rectangles is called a clipping region. +.KE +.LP +.KS +\fBCoded character\fP +.IN "Coded character" "" "@DEF@" +.IP +A character bound to a codepoint. +.KE +.LP +.KS +\fBCoded character set\fP +.IN "Coded character set" "" "@DEF@" +.IP +A set of unambiguous rules that establishes a character set +and the one-to-one relationship between each character of the set +and its bit representation. +(ISO2022, as adapted by XPG3) +A definition of a one-to-one mapping of a set of characters to a set of +codepoints. +.KE +.LP +.KS +\fBCodepoint\fP +.IN "Codepoint" "" "@DEF@" +.IP +The coded representation of a single character in a coded character set. +.KE +.LP +.KS +\fBColormap\fP +.IN "Colormap" "" "@DEF@" +.IP +A colormap consists of a set of entries defining color values. +The colormap associated with a window is used to display the contents of +the window; each pixel value indexes the colormap to produce an RGB value +that drives the guns of a monitor. +Depending on hardware limitations, +one or more colormaps can be installed at one time so +that windows associated with those maps display with true colors. +.KE +.LP +.KS +\fBConnection\fP +.IN "Connection" "" "@DEF@" +.IP +The IPC path between the server and client program is known as a connection. +A client program typically (but not necessarily) has one +connection to the server over which requests and events are sent. +.KE +.LP +.KS +\fBContainment\fP +.IN "Containment" "" "@DEF@" +.IP +A window contains the pointer if the window is viewable and the +hotspot of the cursor is within a visible region of the window or a +visible region of one of its inferiors. +The border of the window is included as part of the window for containment. +The pointer is in a window if the window contains the pointer +but no inferior contains the pointer. +.KE +.LP +.KS +\fBCoordinate system\fP +.IN "Coordinate system" "" "@DEF@" +.IP +The coordinate system has X horizontal and Y vertical, +with the origin [0, 0] at the upper left. +Coordinates are integral and coincide with pixel centers. +Each window and pixmap has its own coordinate system. +For a window, +the origin is inside the border at the inside upper-left corner. +.KE +.LP +.KS +\fBCursor\fP +.IN "Cursor" "" "@DEF@" +.IP +A cursor is the visible shape of the pointer on a screen. +It consists of a hotspot, a source bitmap, a shape bitmap, +and a pair of colors. +The cursor defined for a window controls the visible +appearance when the pointer is in that window. +.KE +.LP +.KS +\fBDepth\fP +.IN "Depth" "" "@DEF@" +.IP +The depth of a window or pixmap is the number of bits per pixel it has. +The depth of a graphics context is the depth of the drawables it can be +used in conjunction with graphics output. +.KE +.LP +.KS +\fBDevice\fP +.IN "Device" "" "@DEF@" +.IP +Keyboards, mice, tablets, track-balls, button boxes, and so on are all +collectively known as input devices. +Pointers can have one or more buttons +(the most common number is three). +The core protocol only deals with two devices: the keyboard +and the pointer. +.KE +.LP +.KS +\fBDirectColor\fP +.IN "DirectColor" "" "@DEF@" +.IP +.PN DirectColor +is a class of colormap in which a pixel value is decomposed into three +separate subfields for indexing. +The first subfield indexes an array to produce red intensity values. +The second subfield indexes a second array to produce blue intensity values. +The third subfield indexes a third array to produce green intensity values. +The RGB (red, green, and blue) values in the colormap entry can be +changed dynamically. +.KE +.LP +.KS +\fBDisplay\fP +.IN "Display" "" "@DEF@" +.IP +A server, together with its screens and input devices, is called a display. +The Xlib +.PN Display +.IN "Display" "structure" +structure contains all information about the particular display and its screens +as well as the state that Xlib needs to communicate with the display over a +particular connection. +.KE +.LP +.KS +\fBDrawable\fP +.IN "Drawable" "" "@DEF@" +.IP +Both windows and pixmaps can be used as sources and destinations +in graphics operations. +These windows and pixmaps are collectively known as drawables. +However, an +.PN InputOnly +window cannot be used as a source or destination in a +graphics operation. +.KE +.LP +.KS +\fBEncoding\fP +.IN "Encoding" "" "@DEF@" +.IP +A set of unambiguous rules that establishes a character set +and a relationship between the characters and their representations. +The character set does not have to be fixed to a finite pre-defined set of +characters. +The representations do not have to be of uniform length. +Examples are an ISO2022 graphic set, a state-independent +or state-dependent combination of graphic sets, possibly including control +sets, and the X Compound Text encoding. +.IP +In X, encodings are identified by a string +which appears as: the +.PN CharSetRegistry +and +.PN CharSetEncoding +components of an XLFD +name; the name of a charset of the locale for which a font could not be +found; or an atom which identifies the encoding of a text property or +which names an encoding for a text selection target type. +Encoding names should be composed of characters from the X Portable +Character Set. +.KE +.LP +.KS +\fBEscapement\fP +.IN "Escapement" "" "@DEF@" +.IP +The escapement of a string is the distance in pixels in the +primary draw direction from the drawing origin to the origin of the next +character (that is, the one following the given string) to be drawn. +.KE +.LP +.KS +\fBEvent\fP +.IN "Event" "" "@DEF@" +.IP +Clients are informed of information asynchronously by means of events. +These events can be either asynchronously generated from devices or +generated as side effects of client requests. +Events are grouped into types. +The server never sends an event to a client unless the +client has specifically asked to be informed of that type of event. +However, clients can force events to be sent to other clients. +Events are typically reported relative to a window. +.KE +.LP +.KS +\fBEvent mask\fP +.IN "Event" "mask" "@DEF@" +.IP +Events are requested relative to a window. +The set of event types a client requests relative to a window is described +by using an event mask. +.KE +.LP +.KS +\fBEvent propagation\fP +.IN "Event" "propagation" "@DEF@" +.IP +Device-related events propagate from the source window to ancestor +windows until some client has expressed interest in handling that type +of event or until the event is discarded explicitly. +.KE +.LP +.KS +\fBEvent source\fP +.IN "Event" "source" "@DEF@" +.IP +The deepest viewable window that the pointer is in is called +the source of a device-related event. +.KE +.LP +.KS +\fBEvent synchronization\fP +.IN "Event" "synchronization" "@DEF@" +.IP +There are certain race conditions possible when demultiplexing device +events to clients (in particular, deciding where pointer and keyboard +events should be sent when in the middle of window management +operations). +The event synchronization mechanism allows synchronous processing of +device events. +.KE +.LP +.KS +\fBExposure event\fP +.IN "Event" "Exposure" "@DEF@" +.IP +Servers do not guarantee to preserve the contents of windows when +windows are obscured or reconfigured. +Exposure events are sent to clients to inform them when contents of regions +of windows have been lost. +.KE +.LP +.KS +\fBExtension\fP +.IN "Extension" "" "@DEF@" +.IP +Named extensions to the core protocol can be defined to extend the system. +Extensions to output requests, resources, and event types are all possible +and expected. +.KE +.LP +.KS +\fBFont\fP +.IN "Font" "" "@DEF@" +.IP +A font is an array of glyphs (typically characters). +The protocol does no translation or interpretation of character sets. +The client simply indicates values used to index the glyph array. +A font contains additional metric information to determine interglyph +and interline spacing. +.KE +.LP +.KS +\fBFont glyph\fP +.IN "Font glyph" "" "@DEF@" +.IP +The abstract graphical symbol for an index into a font. +.KE +.LP +.KS +\fBFrozen events\fP +.IN "Frozen events" "" "@DEF@" +.IP +Clients can freeze event processing during keyboard and pointer grabs. +.KE +.LP +.KS +\fBGC\fP +.IN "GC" "" "@DEF@" +.IP +GC is an abbreviation for graphics context. +See \fBGraphics context\fP. +.KE +.LP +.KS +\fBGlyph\fP +.IN "Glyph" "" "@DEF@" +.IP +An identified abstract graphical symbol independent of any actual image. +(ISO/IEC/DIS 9541-1) +An abstract visual representation of a graphic character, +not bound to a codepoint. +.KE +.LP +.KS +\fBGlyph image\fP +.IN "Glyph image" "" "@DEF@" +.IP +An image of a glyph, as obtained from a glyph representation displayed +on a presentation surface. +(ISO/IEC/DIS 9541-1) +.KE +.LP +.KS +\fBGrab\fP +.IN "Grab" "" "@DEF@" +.IP +Keyboard keys, the keyboard, pointer buttons, the pointer, +and the server can be grabbed for exclusive use by a client. +In general, +these facilities are not intended to be used by normal applications +but are intended for various input and window managers to implement various +styles of user interfaces. +.KE +.LP +.KS +\fBGraphics context\fP +.IN "Graphics context" "" "@DEF@" +.IP +Various information for graphics output is stored in a graphics +context (GC), such as foreground pixel, background +pixel, line width, clipping region, and so on. +A graphics context can only +be used with drawables that have the same root and the same depth as +the graphics context. +.KE +.LP +.KS +\fBGravity\fP +.IN "Gravity" "" "@DEF@" +.IP +The contents of windows and windows themselves have a gravity, +which determines how the contents move when a window is resized. +See \fBBit gravity\fP and \fBWindow gravity\fP. +.KE +.LP +.KS +\fBGrayScale\fP +.IN "GrayScale" "" "@DEF@" +.IP +.PN GrayScale +can be viewed as a degenerate case of +.PN PseudoColor , +in which the red, green, and blue values in any given colormap entry +are equal and thus, produce shades of gray. +The gray values can be changed dynamically. +.KE +.LP +.KS +\fBHost Portable Character Encoding\fP +.IN "Host Portable Character Encoding" "" "@DEF@" +.IP +The encoding of the X Portable Character Set on the host. +The encoding itself is not defined by this standard, +but the encoding must be the same in all locales supported by Xlib on the host. +If a string is said to be in the Host Portable Character Encoding, +then it only contains characters from the X Portable Character Set, +in the host encoding. +.KE +.LP +.KS +\fBHotspot\fP +.IN "Hotspot" "" "@DEF@" +.IP +A cursor has an associated hotspot, which defines the point in the +cursor corresponding to the coordinates reported for the pointer. +.KE +.LP +.KS +\fBIdentifier\fP +.IN "Identifier" "" "@DEF@" +.IP +An identifier is a unique value associated with a resource +that clients use to name that resource. +The identifier can be used over any connection to name the resource. +.KE +.LP +.KS +\fBInferiors\fP +.IN "Inferiors" "" "@DEF@" +.IP +The inferiors of a window are all of the subwindows nested below it: +the children, the children's children, and so on. +.KE +.LP +.KS +\fBInput focus\fP +.IN "Input" "focus" "@DEF@" +.IP +The input focus is usually a window defining the scope for processing +of keyboard input. +If a generated keyboard event usually would be reported to this window +or one of its inferiors, +the event is reported as usual. +Otherwise, the event is reported with respect to the focus window. +The input focus also can be set such that all keyboard events are discarded +and such that the focus window is dynamically taken to be the root window +of whatever screen the pointer is on at each keyboard event. +.KE +.LP +.KS +\fBInput manager\fP +.IN "Input" "manager" "@DEF@" +.IP +Control over keyboard input is typically provided by an input manager +client, which usually is part of a window manager. +.KE +.LP +.KS +\fBInputOnly window\fP +.IN "Window" "InputOnly" "@DEF@" +.IP +An +.PN InputOnly +window is a window that cannot be used for graphics requests. +.PN InputOnly +windows are invisible and are used to control such things as cursors, +input event generation, and grabbing. +.PN InputOnly +windows cannot have +.PN InputOutput +windows as inferiors. +.KE +.LP +.KS +\fBInputOutput window\fP +.IN "Window" "InputOutput" "@DEF@" +.IP +An +.PN InputOutput +window is the normal kind of window that is used for both input and output. +.PN InputOutput +windows can have both +.PN InputOutput +and +.PN InputOnly +windows as inferiors. +.KE +.LP +.KS +\fBInternationalization\fP +.IN "Internationalization" "" "@DEF@" +.IP +The process of making software adaptable to the requirements +of different native languages, local customs, and character string encodings. +Making a computer program adaptable to different locales +without program source modifications or recompilation. +.KE +.LP +.KS +\fBISO2022\fP +.IN "ISO2022" "" "@DEF@" +.IP +ISO standard for code extension techniques for 7-bit and 8-bit coded +character sets. +.KE +.LP +.KS +\fBKey grabbing\fP +.IN "Key" "grabbing" "@DEF@" +.IP +Keys on the keyboard can be passively grabbed by a client. +When the key is pressed, +the keyboard is then actively grabbed by the client. +.KE +.LP +.KS +\fBKeyboard grabbing\fP +.IN "Keyboard" "grabbing" "@DEF@" +.IP +A client can actively grab control of the keyboard, and key events +will be sent to that client rather than the client the events would +normally have been sent to. +.KE +.LP +.KS +\fBKeysym\fP +.IN "Keysym" "" "@DEF@" +.IP +An encoding of a symbol on a keycap on a keyboard. +.KE +.LP +.KS +\fBLatin-1\fP +.IN "Latin-1" "" "@DEF@" +.IP +The coded character set defined by the ISO8859-1 standard. +.KE +.LP +.KS +\fBLatin Portable Character Encoding\fP +.IN "Latin Portable Character Encoding" "" "@DEF@" +.IP +The encoding of the X Portable Character Set using the Latin-1 codepoints +plus ASCII control characters. +If a string is said to be in the Latin Portable Character Encoding, +then it only contains characters from the X Portable Character Set, +not all of Latin-1. +.KE +.LP +.KS +\fBLocale\fP +.IN "Locale" "" "@DEF@" +.IP +The international environment of a computer program defining the ``localized'' +behavior of that program at run-time. +This information can be established from one or more sets of localization data. +ANSI C defines locale-specific processing by C system library calls. +See ANSI C and the X/Open Portability Guide specifications for more details. +In this specification, on implementations that conform to the ANSI C library, +the ``current locale'' is the current setting of the LC_CTYPE +.PN setlocale +category. +Associated with each locale is a text encoding. When text is processed +in the context of a locale, the text must be in the encoding of the locale. +The current locale affects Xlib in its: +.RS +.IP \(bu 5 +Encoding and processing of input method text +.IP \(bu 5 +Encoding of resource files and values +.IP \(bu 5 +Encoding and imaging of text strings +.IP \(bu 5 +Encoding and decoding for inter-client text communication +.RE +.KE +.LP +.KS +\fBLocale name\fP +.IN "Locale name" "" "@DEF@" +.IP +The identifier used to select the desired locale for the host C library +and X library functions. +On ANSI C library compliant systems, +the locale argument to the +.PN setlocale +function. +.KE +.LP +.KS +\fBLocalization\fP +.IN "Localization" "" "@DEF@" +.IP +The process of establishing information within a computer system specific +to the operation of particular native languages, local customs +and coded character sets. +(XPG3) +.KE +.LP +.KS +\fBMapped\fP +.IN "Mapped window" "" "@DEF@" +.IP +A window is said to be mapped if a map call has been performed on it. +Unmapped windows and their inferiors are never viewable or visible. +.KE +.LP +.KS +\fBModifier keys\fP +.IN "Modifier keys" "" "@DEF@" +.IP +Shift, Control, Meta, Super, Hyper, Alt, Compose, Apple, CapsLock, +ShiftLock, and similar keys are called modifier keys. +.KE +.LP +.KS +\fBMonochrome\fP +.IN "Monochrome" "" "@DEF@" +.IP +Monochrome is a special case of +.PN StaticGray +in which there are only two colormap entries. +.KE +.LP +.KS +\fBMultibyte\fP +.IN "Multibyte" "" "@DEF@" +.IP +A character whose codepoint is stored in more than one byte; +any encoding which can contain multibyte characters; +text in a multibyte encoding. +The ``char *'' null-terminated string datatype in ANSI C. +Note that references in this document to multibyte strings +imply only that the strings \fImay\fP contain multibyte characters. +.KE +.LP +.KS +\fBObscure\fP +.IN "Obscure" "" "@DEF@" +.IP +A window is obscured if some other window obscures it. +A window can be partially obscured and so still have visible regions. +Window A obscures window B if both are viewable +.PN InputOutput +windows, if A is higher in the global stacking order, +and if the rectangle defined by the outside +edges of A intersects the rectangle defined by the outside edges of B. +Note the distinction between obscures and occludes. +Also note that window borders are included in the calculation. +.KE +.LP +.KS +\fBOcclude\fP +.IN "Occlude" "" "@DEF@" +.IP +A window is occluded if some other window occludes it. +Window A occludes window B if both are mapped, +if A is higher in the global stacking order, +and if the rectangle defined by the outside edges of A intersects the rectangle defined +by the outside edges of B. +Note the distinction between occludes and obscures. +Also note that window borders are included in the calculation +and that +.PN InputOnly +windows never obscure other windows but can occlude other windows. +.KE +.LP +.KS +\fBPadding\fP +.IN "Padding" "" "@DEF@" +.IP +Some padding bytes are inserted in the data stream to maintain +alignment of the protocol requests on natural boundaries. +This increases ease of portability to some machine architectures. +.KE +.LP +.KS +\fBParent window\fP +.IN "Window" "parent" "@DEF@" +.IP +If C is a child of P, then P is the parent of C. +.KE +.LP +.KS +\fBPassive grab\fP +.IN "Passive grab" "" "@DEF@" +.IP +Grabbing a key or button is a passive grab. +The grab activates when the key or button is actually pressed. +.KE +.LP +.KS +\fBPixel value\fP +.IN "Pixel value" "" "@DEF@" +.IP +A pixel is an N-bit value, +where N is the number of bit planes used in a particular window or pixmap +(that is, is the depth of the window or pixmap). +A pixel in a window indexes a colormap to derive an actual color to be +displayed. +.KE +.LP +.KS +\fBPixmap\fP +.IN "Pixmap" "" "@DEF@" +.EQ +delim %% +.EN +.IP +A pixmap is a three-dimensional array of bits. +A pixmap is normally thought of as a two-dimensional array of pixels, +where each pixel can be a value from 0 to %2 sup N %\-1, +and where N is the depth (z axis) of the pixmap. +A pixmap can also be thought of as a stack of N bitmaps. +A pixmap can only be used on the screen that it was created in. +.KE +.LP +.KS +\fBPlane\fP +.IN "Plane" "" "@DEF@" +.IP +When a pixmap or window is thought of as a stack of bitmaps, each +bitmap is called a plane or bit plane. +.KE +.LP +.KS +\fBPlane mask\fP +.IN "Plane" "mask" "@DEF@" +.IP +Graphics operations can be restricted to only affect a subset of bit +planes of a destination. +A plane mask is a bit mask describing which planes are to be modified. +The plane mask is stored in a graphics context. +.KE +.LP +.KS +\fBPointer\fP +.IN "Pointer" "" "@DEF@" +.IP +The pointer is the pointing device currently attached to the cursor +and tracked on the screens. +.KE +.LP +.KS +\fBPointer grabbing\fP +.IN "Pointer" "grabbing" "@DEF@" +.IP +A client can actively grab control of the pointer. +Then button and motion events will be sent to that client +rather than the client the events would normally have been sent to. +.KE +.LP +.KS +\fBPointing device\fP +.IN "Pointing device" "" "@DEF@" +.IP +A pointing device is typically a mouse, tablet, or some other +device with effective dimensional motion. +The core protocol defines only one visible cursor, +which tracks whatever pointing device is attached as the pointer. +.KE +.LP +.KS +\fBPOSIX\fP +.IN "POSIX" "" "@DEF@" +.IP +Portable Operating System Interface, ISO/IEC 9945-1 (IEEE Std 1003.1). +.KE +.LP +.KS +\fBPOSIX Portable Filename Character Set\fP +.IN "POSIX Portable Filename Character Set" "" "@DEF@" +.IP +The set of 65 characters which can be used in naming files on a POSIX-compliant +host that are correctly processed in all locales. +The set is: +.IP +.Ds 0 +a..z A..Z 0..9 ._- +.De +.KE +.LP +.KS +\fBProperty\fP +.IN "Property" "" "@DEF@" +.IP +Windows can have associated properties that consist of a name, a type, +a data format, and some data. +The protocol places no interpretation on properties. +They are intended as a general-purpose naming mechanism for clients. +For example, clients might use properties to share information such as resize +hints, program names, and icon formats with a window manager. +.KE +.LP +.KS +\fBProperty list\fP +.IN "Property list" "" "@DEF@" +.IP +The property list of a window is the list of properties that have +been defined for the window. +.KE +.LP +.KS +\fBPseudoColor\fP +.IN "PseudoColor" "" "@DEF@" +.IP +.PN PseudoColor +is a class of colormap in which a pixel value indexes the colormap entry to +produce an independent RGB value; +that is, the colormap is viewed as an array of triples (RGB values). +The RGB values can be changed dynamically. +.KE +.LP +.KS +\fBRectangle\fP +.IN "Rectangle" "" "@DEF@" +.IP +A rectangle specified by [x,y,w,h] has an infinitely thin +outline path with corners at [x,y], [x+w,y], [x+w,y+h], and [x, y+h]. +When a rectangle is filled, +the lower-right edges are not drawn. +For example, +if w=h=0, +nothing would be drawn. +For w=h=1, +a single pixel would be drawn. +.KE +.LP +.KS +\fBRedirecting control\fP +.IN "Redirecting control" "" "@DEF@" +.IP +Window managers (or client programs) may enforce window layout +policy in various ways. +When a client attempts to change the size or position of a window, +the operation may be redirected to a specified client +rather than the operation actually being performed. +.KE +.LP +.KS +\fBReply\fP +.IN "Reply" "" "@DEF@" +.IP +Information requested by a client program using the X protocol +is sent back to the client with a reply. +Both events and replies are multiplexed on the same connection. +Most requests do not generate replies, +but some requests generate multiple replies. +.KE +.LP +.KS +\fBRequest\fP +.IN "Request" "" "@DEF@" +.IP +A command to the server is called a request. +It is a single block of data sent over a connection. +.KE +.LP +.KS +\fBResource\fP +.IN "Resource" "" "@DEF@" +.IP +Windows, pixmaps, cursors, fonts, graphics contexts, and colormaps are +known as resources. +They all have unique identifiers associated with them for naming purposes. +The lifetime of a resource usually is bounded by the lifetime of the +connection over which the resource was created. +.KE +.LP +.KS +\fBRGB values\fP +.IN "RGB values" "" "@DEF@" +.IP +RGB values are the red, green, and blue intensity values that are used +to define a color. +These values are always represented as 16-bit, unsigned numbers, with 0 +the minimum intensity and 65535 the maximum intensity. +The X server scales these values to match the display hardware. +.KE +.LP +.KS +\fBRoot\fP +.IN "Root" "" "@DEF@" +.IP +The root of a pixmap or graphics context is the same as the root +of whatever drawable was used when the pixmap or GC was created. +The root of a window is the root window under which the window was created. +.KE +.LP +.KS +\fBRoot window\fP +.IN "Window" "root" "@DEF@" +.IP +Each screen has a root window covering it. +The root window cannot be reconfigured or unmapped, +but otherwise it acts as a full-fledged window. +A root window has no parent. +.KE +.LP +.KS +\fBSave set\fP +.IN "Save set" "" "@DEF@" +.IP +The save set of a client is a list of other clients' windows that, +if they are inferiors of one of the client's windows at connection +close, should not be destroyed and that should be remapped +if currently unmapped. +Save sets are typically used by window managers to avoid +lost windows if the manager should terminate abnormally. +.KE +.LP +.KS +\fBScanline\fP +.IN "Scanline" "" "@DEF@" +.IP +A scanline is a list of pixel or bit values viewed as a horizontal +row (all values having the same y coordinate) of an image, with the +values ordered by increasing the x coordinate. +.KE +.LP +.KS +\fBScanline order\fP +.IN "Scanline" "order" "@DEF@" +.IP +An image represented in scanline order contains scanlines ordered by +increasing the y coordinate. +.KE +.LP +.KS +\fBScreen\fP +.IN "Screen" "" "@DEF@" +.IP +A server can provide several independent screens, +which typically have physically independent monitors. +This would be the expected configuration when there is only a single keyboard +and pointer shared among the screens. +A +.PN Screen +.IN "Screen" "structure" +structure contains the information about that screen +and is linked to the +.PN Display +.IN "Display" "structure" +structure. +.KE +.LP +.KS +\fBSelection\fP +.IN "Selection" "" "@DEF@" +.IP +A selection can be thought of as an indirect property with dynamic +type. +That is, rather than having the property stored in the X server, +it is maintained by some client (the owner). +A selection is global and is thought of as belonging to the user +and being maintained by clients, +rather than being private to a particular window subhierarchy +or a particular set of clients. +When a client asks for the contents of +a selection, it specifies a selection target type, +which can be used to control the transmitted representation of the contents. +For example, if the selection is ``the last thing the user clicked on,'' +and that is currently an image, then the target type might specify +whether the contents of the image should be sent in XY format or +Z format. +.IP +The target type can also be used to control the class of +contents transmitted; for example, +asking for the ``looks'' (fonts, line +spacing, indentation, and so forth) of a paragraph selection, rather than the +text of the paragraph. +The target type can also be used for other +purposes. +The protocol does not constrain the semantics. +.KE +.LP +.KS +\fBServer\fP +.IN "Server" "" "@DEF@" +.IP +The server, which is also referred to as the X server, +provides the basic windowing mechanism. +It handles IPC connections from clients, +multiplexes graphics requests onto the screens, +and demultiplexes input back to the appropriate clients. +.KE +.LP +.KS +\fBServer grabbing\fP +.IN "Server" "grabbing" "@DEF@" +.IP +The server can be grabbed by a single client for exclusive use. +This prevents processing of any requests from other client connections until +the grab is completed. +This is typically only a transient state for such things as rubber-banding, +pop-up menus, or executing requests indivisibly. +.KE +.LP +.KS +\fBShift sequence\fP +.IN "Shift sequence" "" "@DEF@" +.IP +ISO2022 defines control characters and escape sequences +which temporarily (single shift) or permanently (locking shift) cause a +different character set to be in effect (``invoking'' a character set). +.KE +.LP +.KS +\fBSibling\fP +.IN "Sibling" "" "@DEF@" +.IP +Children of the same parent window are known as sibling windows. +.KE +.LP +.KS +\fBStacking order\fP +.IN "Stacking order" "" "@DEF@" +.IP +Sibling windows, similar to sheets of paper on a desk, +can stack on top of each other. +Windows above both obscure and occlude lower windows. +The relationship between sibling windows is known as the stacking order. +.KE +.LP +.KS +\fBState-dependent encoding\fP +.IN "State-dependent encoding" "" "@DEF@" +.IP +An encoding in which an invocation of a charset can apply to multiple +characters in sequence. +A state-dependent encoding begins in an ``initial state'' +and enters other ``shift states'' when specific ``shift sequences'' +are encountered in the byte sequence. +In ISO2022 terms, +this means use of locking shifts, not single shifts. +.KE +.LP +.KS +\fBState-independent encoding\fP +.IN "State-independent encoding" "" "@DEF@" +.IP +Any encoding in which the invocations of the charsets are fixed, +or span only a single character. +In ISO2022 terms, +this means use of at most single shifts, not locking shifts. +.KE +.LP +.KS +\fBStaticColor\fP +.IN "StaticColor" "" "@DEF@" +.IP +.PN StaticColor +can be viewed as a degenerate case of +.PN PseudoColor +in which the RGB values are predefined and read-only. +.KE +.LP +.KS +\fBStaticGray\fP +.IN "StaticGray" "" "@DEF@" +.IP +.PN StaticGray +can be viewed as a degenerate case of +.PN GrayScale +in which the gray values are predefined and read-only. +The values are typically linear or near-linear increasing ramps. +.KE +.LP +.KS +\fBStatus\fP +.IN "Status" "" "@DEF@" +.IP +Many Xlib functions return a success status. +If the function does not succeed, +however, its arguments are not disturbed. +.KE +.LP +.KS +\fBStipple\fP +.IN "Stipple" "" "@DEF@" +.IP +A stipple pattern is a bitmap that is used to tile a region to serve +as an additional clip mask for a fill operation with the foreground +color. +.KE +.KS +.LP +.KS +\fBSTRING encoding\fP +.IN "STRING encoding" "" "@DEF@" +.IP +Latin-1, plus tab and newline. +.KE +.LP +\fBString Equivalence\fP +.IN "String Equivalence" "" "@DEF@" +.IP +Two ISO Latin-1 STRING8 values are considered equal if they are the same +length and if corresponding bytes are either equal or are equivalent as +follows: decimal values 65 to 90 inclusive (characters ``A'' to ``Z'') are +pairwise equivalent to decimal values 97 to 122 inclusive +(characters ``a'' to ``z''), decimal values 192 to 214 inclusive +(characters ``A grave'' to ``O diaeresis'') are pairwise equivalent to decimal +values 224 to 246 inclusive (characters ``a grave'' to ``o diaeresis''), +and decimal values 216 to 222 inclusive (characters ``O oblique'' to ``THORN'') +are pairwise equivalent to decimal values 246 to 254 inclusive +(characters ``o oblique'' to ``thorn''). +.KE +.LP +.KS +\fBTile\fP +.IN "Tile" "" "@DEF@" +.IP +A pixmap can be replicated in two dimensions to tile a region. +The pixmap itself is also known as a tile. +.KE +.LP +.KS +\fBTimestamp\fP +.IN "Timestamp" "" "@DEF@" +.IP +A timestamp is a time value expressed in milliseconds. +It is typically the time since the last server reset. +Timestamp values wrap around (after about 49.7 days). +The server, given its current time is represented by timestamp T, +always interprets timestamps from clients by treating half +of the timestamp space as being earlier in time than T +and half of the timestamp space as being later in time than T. +One timestamp value, represented by the constant +.PN CurrentTime , +is never generated by the server. +This value is reserved for use in requests to represent the current server time. +.KE +.LP +.KS +\fBTrueColor\fP +.IN "TrueColor" "" "@DEF@" +.IP +.PN TrueColor +can be viewed as a degenerate case of +.PN DirectColor +in which the subfields in the pixel value directly encode the corresponding RGB +values. +That is, the colormap has predefined read-only RGB values. +The values are typically linear or near-linear increasing ramps. +.KE +.LP +.KS +\fBType\fP +.IN "Type" "" "@DEF@" +.IP +A type is an arbitrary atom used to identify the interpretation of property +data. +Types are completely uninterpreted by the server. +They are solely for the benefit of clients. +X predefines type atoms for many frequently used types, +and clients also can define new types. +.KE +.LP +.KS +\fBViewable\fP +.IN "Viewable" "" "@DEF@" +.IP +A window is viewable if it and all of its ancestors are mapped. +This does not imply that any portion of the window is actually visible. +Graphics requests can be performed on a window when it is not +viewable, but output will not be retained unless the server is maintaining +backing store. +.KE +.LP +.KS +\fBVisible\fP +.IN "Visible" "" "@DEF@" +.IP +A region of a window is visible if someone looking at the screen can +actually see it; that is, the window is viewable and the region is not occluded +by any other window. +.KE +.LP +.KS +\fBWhitespace\fP +.IN "Whitespace" "" "@DEF@" +.IP +Any spacing character. +On implementations that conform to the ANSI C library, +whitespace is any character for which +.PN isspace +returns true. +.KE +.LP +.KS +\fBWindow gravity\fP +.IN "Window" "gravity" "@DEF@" +.IP +When windows are resized, +subwindows may be repositioned automatically relative to some position in the +window. +This attraction of a subwindow to some part of its parent is known +as window gravity. +.KE +.LP +.KS +\fBWindow manager\fP +.IN "Window" "manager" "@DEF@" +.IP +Manipulation of windows on the screen and much of the user interface +(policy) is typically provided by a window manager client. +.KE +.LP +.KS +\fBX Portable Character Set\fP +.IN "X Portable Character Set" "" "@DEF@" +.IP +A basic set of 97 characters which are assumed to exist in all +locales supported by Xlib. This set contains the following characters: +.IP +.Ds 0 +.EQ +delim DD +.EN +a..z A..Z 0..9 +!"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~ +, , and +.EQ +delim %% +.EN +.De +.IP +This is the left/lower half (also called the G0 set) +of the graphic character set of ISO8859-1 plus , , and . +It is also the set of graphic characters in 7-bit ASCII plus the same +three control characters. +The actual encoding of these characters on the host is system dependent; +see the Host Portable Character Encoding. +.KE +.LP +.KS +\fBXLFD\fP +.IN "XLFD" "" "@DEF@" +.IP +The X Logical Font Description Conventions that define a standard syntax +for structured font names. +.KE +.LP +.KS +\fBXY format\fP +.IN "XY format" "" "@DEF@" +.IP +The data for a pixmap is said to be in XY format if it is organized as +a set of bitmaps representing individual bit planes with the planes +appearing from most-significant to least-significant bit order. +.KE +.LP +.KS +\fBZ format\fP +.IN "Z format" "" "@DEF@" +.IP +The data for a pixmap is said to be in Z format if it is organized as +a set of pixel values in scanline order. +.KE +.LP +\fBReferences\fP +.LP +ANSI Programming Language - C: ANSI X3.159-1989, December 14, 1989. +.LP +Draft Proposed Multibyte Extension of ANSI C, Draft 1.1, November 30, +1989, SC22/C WG/SWG IPSJ/ITSCJ Japan. +.LP +ISO2022: Information processing - ISO 7-bit and 8-bit coded character +sets - Code extension techniques. +.LP +ISO8859-1: Information processing - 8-bit single-byte coded graphic +character sets - Part 1: Latin alphabet No. 1. +.LP +POSIX: Information Technology - Portable Operating System Interface (POSIX) - +Part 1: System Application Program Interface (API) [C Language], +ISO/IEC 9945-1. +.LP +Text of ISO/IEC/DIS 9541-1, Information Processing - Font Information +Interchange - Part 1: Architecture. +.LP +X/Open Portability Guide, Issue 3, December 1988 (XPG3), X/Open Company, +Ltd, Prentice-Hall, Inc. 1989. ISBN 0-13-685835-8. +(See especially Volume 3: XSI Supplementary Definitions.) +.bp diff --git a/libX11/specs/libX11/libX11.ms b/libX11/specs/libX11/libX11.ms new file mode 100644 index 000000000..b44425623 --- /dev/null +++ b/libX11/specs/libX11/libX11.ms @@ -0,0 +1,24 @@ +.so abstract.t +.so credits.t +.so CH01 +.so CH02 +.so CH03 +.so CH04 +.so CH05 +.so CH06 +.so CH07 +.so CH08 +.so CH09 +.so CH10 +.so CH11 +.so CH12 +.so CH13 +.so CH14 +.so CH15 +.so CH16 +.so AppA +.so AppB +.so AppC +.so AppD +.so glossary +.so postproc diff --git a/libX11/specs/libX11/postproc b/libX11/specs/libX11/postproc new file mode 100644 index 000000000..0f45a5a00 --- /dev/null +++ b/libX11/specs/libX11/postproc @@ -0,0 +1,17 @@ +.\" +.\" print Table of Contents +.if e \& \" Force blank page to begin TOC on an odd (right-hand) page. +.EH '''' +.OH '''' +.bp +\& \" Want old footings if blank page was forced. +.EF '''' +.OF '''' +.XS +Index +.XE +.EQ +delim $$ +.EN +.tm .pn \n% +.PX diff --git a/libX11/specs/macros.t b/libX11/specs/macros.t new file mode 100644 index 000000000..cbc599b3f --- /dev/null +++ b/libX11/specs/macros.t @@ -0,0 +1,226 @@ +.\" $Xorg: macros.t,v 1.3 2000/08/17 19:42:51 cpqbld Exp $ +.\" macros.t -- macros for X Consortium documents +.\" Revised and commented by smarks 93.12.20. +.\" +.\" global setup: set ragged right, assign string variables +.\" +.na +.ie n \{\ +.ds Q \&" +.ds U \&" +.ds - \%-- +.\} +.el \{\ +.ds Q `\h'-\w'\^'u'` +.ds U '\h'-\w'\^'u'' +.ds - \(em +.\} +.\" +.\" --- Ds --- displayed text (like .DS) with no keep +.\" .Ds is obsolete. Change to something from this table: +.\" for this use instead +.\" .Ds .ID +.\" .Ds n .LD (where "n" is a number) +.\" (Numbers don't work in these macros, so ".Ds 5" +.\" comes out the same as ".Ds 0".) +.\" +.de Ds +.nf +.\\$1D \\$2 \\$1 +.ft 1 +.ps \\n(PS +.if \\n(VS>=40 .vs \\n(VSu +.if \\n(VS<=39 .vs \\n(VSp +.. +.de D +.ID \\$1 +.. +.de 0D +.LD +.. +.\" backward compatibility for the Xt spec +.de 5D +.LD +.. +.\" +.\" --- De --- obsolete: use .DE instead +.\" +.de De +.DE +.. +.\" +.\" --- FD --- +.\" +.de FD +.LP +.KS +.TA .5i 3i +.ta .5i 3i +.nf +.. +.\" +.\" --- FN --- +.\" +.de FN +.fi +.KE +.LP +.. +.\" +.\" --- IN --- send an index entry to the stderr +.\" +.de IN +.tm \\n%:\\$1:\\$2:\\$3 +.. +.\" +.\" --- C{ --- +.\" +.de C{ +.KS +.nf +.D +.\" +.\" choose appropriate monospace font +.\" the imagen conditional, 480, +.\" may be changed to L if LB is too +.\" heavy for your eyes... +.\" +.ie "\\*(.T"480" .ft L +.el .ie "\\*(.T"300" .ft L +.el .ie "\\*(.T"202" .ft PO +.el .ie "\\*(.T"aps" .ft CW +.el .ft R +.ps \\n(PS +.ie \\n(VS>40 .vs \\n(VSu +.el .vs \\n(VSp +.. +.\" +.\" --- C} --- +.\" +.de C} +.DE +.R +.. +.\" +.\" --- Pn --- like PN, but use $2; $1 and $3 abut +.\" +.de Pn +.IN \\$2 +.ie t \\$1\fB\^\\$2\^\fR\\$3 +.el \\$1\fI\^\\$2\^\fP\\$3 +.. +.\" +.\" --- PN --- put $1 in boldface and add index entry; $2 abuts +.\" +.de PN +.IN \\$1 +.ie t \fB\^\\$1\^\fR\\$2 +.el \fI\^\\$1\^\fP\\$2 +.. +.\" +.\" --- hI --- add index entry for $1 as header file +.\" +.de hI +.IN <\\$1> +.IN Files <\\$1> +.IN Headers <\\$1> +.. +.\" +.\" --- hN --- put $1 in boldface as header and add index entry; $2 abuts +.\" +.de hN +.hI \\$1 +.ie t <\fB\\$1\fR>\\$2 +.el <\fI\\$1\fP>\\$2 +.. +.\" +.\" --- NT --- +.\" +.de NT +.br +.ne 7 +.ds NO Note +.if \\n(.$ .ds NO \\$1 +.ie n .sp +.el .sp 10p +.ce +\\*(NO +.ie n .sp +.el .sp 5p +.if '\\$1'C' .ce 99 +.if '\\$2'C' .ce 99 +.\" .QS/.QE macros don't exist in older versions of -ms +.ie \\n(GS .QS +.el \{\ +. in +5n +. ll -5n +.\} +.R +.. +.\" +.\" --- NE --- Note End (doug kraft 3/85) +.\" +.de NE +.ce 0 +.ie \\n(GS .QE +.el \{\ +. in -5n +. ll +5n +.\} +.ie n .sp +.el .sp 10p +.. +.\" +.\" --- nH --- numbered header (like NH) but with automatic TOC entry +.\" usage: .nH level "section title, preferable in quotes" +.\" +.de nH +.NH \\$1 +\\$2 +.XS +\\*(SN \\$2 +.XE +.. +.\" +.\" --- sM --- put start-marker in margin +.\" +.de sM +.KS +.sp 1 +\\h'-0.5i'\\L'-1v'\\v'1p'\\l'1v'\\v'1v-1p' +.sp -1 +.. +.\" +.\" --- eM --- put end-marker in margin +.\" +.de eM +.sp -1 +\\h'-0.5i'\\L'-1v'\\v'1v+1p'\\l'1v'\\v'-1p' +.sp 1 +.KE +.. +.\" +.\" --- YZ --- finish up; $1 is the starting page number of the TOC +.\" +.de YZ +. \" Force there to be an even number of pages, so the table of +. \" contents doesn't end up on the back of the last page in +. \" the case of duplex printing. +.if o .bp +. \" Emit a .pn directive with one plus the last page number. + \" This will be the number of the first page of the index. +.nr YZ \\n%+1 +.tm .pn \\n(YZ +. \" Issue the table of contents, setting roman numerals, +. \" and redefining the footer to use them. +.bp \\$1 +.af PN i +.EF ''\\\\\\\\n(PN'' +.OF ''\\\\\\\\n(PN'' +. \" Why all the backslashes? This string is evaluated +. \" three times: 1) during the definition of this macro, +. \" 2) when the .EF and .OF macros are expanded, and 3) +. \" when the bottom-of-page trap is invoked. Thus, +. \" eight backslashes are reduced to one in the final output. +.PX +.. diff --git a/libX11/specs/troffrules.in b/libX11/specs/troffrules.in new file mode 100644 index 000000000..03d8463e8 --- /dev/null +++ b/libX11/specs/troffrules.in @@ -0,0 +1,68 @@ +# +# Copyright 2009 Sun Microsystems, Inc. All rights reserved. +# +# Permission to use, copy, modify, distribute, and sell this software and its +# documentation for any purpose is hereby granted without fee, provided that +# the above copyright notice appear in all copies and that both that +# copyright notice and this permission notice appear in supporting +# documentation. +# +# The above copyright notice and this permission notice shall be included +# in all copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +# OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +# IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR +# OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +# ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +# OTHER DEALINGS IN THE SOFTWARE. +# +# Except as contained in this notice, the name of the copyright holders shall +# not be used in advertising or otherwise to promote the sale, use or +# other dealings in this Software without prior written authorization +# from the copyright holders. +# + +# Based on xc/doc/specs/*/Makefile from X11R6.9 + +EXTRA_DIST = $(doc_sources) + +if HAVE_PS2PDF +printable_format = .pdf +else +printable_format = .ps +endif + +if BUILD_SPECS +doc_DATA = $(doc_sources:.ms=.txt) \ + $(doc_sources:.ms=$(printable_format)) \ + $(doc_sources:.ms=.html) + +CLEANFILES = $(doc_DATA) +MOSTLYCLEANFILES = index.* + +# Pass version string as a troff string for substitution +GROFF_DEFS = -dxV="$(PACKAGE_STRING)" + +# -e to run through eqn, -t to run through tbl +GROFF_FLAGS = -e -t -ms $(GROFF_DEFS) $(top_srcdir)/specs/macros.t + +SUFFIXES = .ms .ps .txt .html .pdf + +.ms.ps: + -$(AM_V_GEN) $(GROFF) -Tps $(GROFF_FLAGS) $< 2> index.$@.raw > $@ + @if grep '^[^1-9.]' index.$@.raw | grep -v warning; then exit 1; \ + else test $$? -le 1; fi + +.ms.txt: + $(AM_V_GEN) env GROFF_NO_SGR=TRUE $(GROFF) -Tutf8 $(GROFF_FLAGS) \ + $< 2> index.$@.raw > $@ + +.ms.html: + $(AM_V_GEN) $(GROFF) -Thtml $(GROFF_FLAGS) $< 2> index.$@.raw > $@ + +.ps.pdf: + $(AM_V_GEN) $(PS2PDF) $< $@ + +endif BUILD_SPECS -- cgit v1.2.3