<!doctype linuxdoc system>

<!-- to produce html use the following commands:

 sgml2html -''-split=0 X11-big-cursor.sgml
 perl -pi -e 's/&mdash;/-''-/g' $@

 the second command is needed until more browsers understand &mdash; -
 Netscape 3 does not, e.g.

-->

<article>

<title>X11-big-cursor MINIHOWTO<subtitle>How to use enlarged mouse cursors with the X window system
<author><url name="J&oe;rg Schneider" url="mailto:joerg.schneider@ira.uka.de">
<date>v2, 11 August 1997
<abstract>
This document describes how to use enlarged mouse cursors with the X
window system.
<!--
<itemize>
<item><htmlurl url="#intro" name="Introduction">
<item><htmlurl url="#howto" name="How to do it">
<item><htmlurl url="#notes" name="Notes and limitations">
<item><htmlurl url="#tech" name="Technical discussion">
<item><htmlurl url="#ideas" name="Other ideas how to make the mouse cursor more visible">
<item><htmlurl url="#info" name="Related info">
    <itemize>
    <item><htmlurl url="#fontserver" name="How to use a fontserver">
        <itemize>
        <item><htmlurl url="#fsconfig" name="Setting up a font server">
        </itemize>
    <item><htmlurl url="#getbdf" name="How to get the bdf source for some font">
    </itemize>
</itemize>       
-->

</abstract>

<toc>


<sect>Introduction<label id=top>

<p>There are several reasons why the standard X mouse cursors are hard to
track for some people: 
<itemize>
<item> when running X on a notebook with low contrast LCD
<item> on normal screens when using high resolution, 1600x1280 e.&nbsp;g.
<item> for visually impaired persons even on normal hardware
</itemize>

In all cases it might help to use enlarged mouse cursors. Ideally this
job should be done by a single X program that automatically enlarges
every mouse cursor.

To my knowledge there is no simple way to write a utility like this,
because the X protocol has no provision to query mouse cursors. For
more details see section <ref id="tech" name="Technical discussion"> below. 

If we aim for a less general goal, though, something can be done: 

There is a set of standard mouse cursors that can be found in the
cursor font (try <TT>xfd -fn cursor</TT> to look at it). Most programs use
these mouse cursors and the key idea is to replace the standard cursor
font with an enlarged version. 

<sect>About this document
<p>
The motivation for this MINIHOWTO was a visually impaired co-student
who asked me how to enlarge the mouse cursor under X. After I found
out how this can be done, I wrote an initial version of this
document. The knowledge about the method described here does not seem
to be common, so I decided to share it and submitted this document as
a Linux MINIHOWTO, despite the fact that it is
<em/not specific to Linux at all/. As all other MINIHOWTOs it can be
found in the home of of the <url name="Linux Documentation Project
(LDP)" url="http://sunsite.unc.edu/LDP/HOWTO/">.

The <url name=master
url="http://i11www.ira.uka.de/&tilde;schneid/X11-big-cursor/master/"> of
this document is maintained in the SGML/linuxdoc format. This makes it
possible to automatically provide versions in the following formats
(which can be found in the same place as the master): html, text,
LaTeX, DVI, PostScript, GNU info.

<url name="Shinobu Miyata" url="mailto:shinobu@emichan.rim.or.jp"> has
done a Japanese translation of this MINIHOWTO. It can be found in <url
url="http://i11www.ira.uka.de/&tilde;schneid/jp/X11-big-cursor/">.

<sect>How to do it<label id=howto>

<p>
Follow the steps detailed below. If you don't want to get and compile
the bdfresize package yourself, you can skip to step 3 and download a
magnified font instead of creating it.
<enum>
<item> get cursor.bdf, the source of the cursor font, from some X
     distribution, e.&nbsp;g. from <url
     url="ftp://ftp.x.org/pub/R6.3/xc/fonts/bdf/misc/cursor.bdf"> (if you don't 
     find it there try an archie search or get it from <url name="my copy"
     url="http://i11www.ira.uka.de/&tilde;schneid/X11-big-cursor/cursor.bdf">).  
<item> get, compile and install the bdfresize package from
     <url url="ftp://ftp.cs.titech.ac.jp/X11/contrib/Local/bdfresize-1.4.tar.Z">
     (or from <url name="my copy"
     url="http://i11www.ira.uka.de/&tilde;schneid/X11-big-cursor/bdfresize-1.4.tar.gz">):
     <verb>
     zcat bdfresize-1.4.tar.Z  | tar xf -
     cd bdfresize-1.4
     xmkmf
     make
     </verb>
     On Linux you probably have to use:
     <verb>
     make CCOPTIONS='-include /usr/include/bsd/bsd.h' clean all
     </verb>
<item> create a directory and install a magnified cursor font in it
     (magnification factor 2 in this example):

     <verb>
     mkdir $HOME/fonts
     bdfresize -f 2 cursor.bdf | bdftopcf >$HOME/fonts/cursor2.pcf
     mkfontdir $HOME/fonts
     </verb>
     
     I have prepared some <url name="cursor fonts"
     url="http://i11www.ira.uka.de/&tilde;schneid/X11-big-cursor/fonts/">
     with the following magnification factors: 1.5, 2, 2.5, 3, 4, 5,
     6, 7, 8 and 16. You can download one of them an copy it to
     <tt>&dollar;HOME/fonts</tt> if you don't want to use bdfresize.

<item> modify your <TT>.xinitrc</TT> or <TT>.xsession</TT> file: before
     any X client (that uses cursors) is started the following
     commands must  be executed: 

     <verb>
     xset +fp $HOME/fonts
     xsetroot -cursor_name X_cursor
     </verb>

<item> leave your X session and restart.
</enum>

That's it&mdash;now all mouse cursors should have doubled in size. 


<sect>Notes and limitations<label id=notes>

<p>
<itemize>

<item> X servers may have a limit for the maximum cursor
     size, especially if they use a hardware implementation for the mouse
     cursor. Others do not have such a limit. E.&nbsp;g. XF86_S3&nbsp;3.3
     works even with a 512x512 mouse cursor (rather slowly).
<item> The magnified cursor font must have the same name as the original
     font (the <em/font name/ must be <TT>cursor</TT>, <em/file name/ does not 
     matter)&mdash;that is no problem as <TT>bdfresize</TT> does not change
     the font name. 
<item> The directory with the new cursor font must be placed before the
     directory with the standard cursor font in the the font path&mdash;this
     is accomplished with <TT>xset +fp</TT> (as opposed to
     <TT>xset fp+</TT>).
<item> Changes in <tt>&dollar;HOME/fonts/</tt> will be visible only
     after the command <TT>mkfontdir &dollar;HOME/fonts; xset fp rehash</TT> 
     and only in newly
     started X clients (more exactly: for newly created cursors).
<item> <TT>xset +fp path</TT> may not work on a X-Terminal. In this case
     a font server (see the section <ref id=fontserver 
     name="How to use a fontserver">)
     can be used if supported by the X-Terminal or some
     other method to install the font on the X-Terminal (this can
     generally only be done by your system administrator).
<item> The same approach can be used for <TT>olcursor</TT> and
     <tt>decw&dollar;cursor</tt> fonts and any other cursor font you may
     encounter.
<item> Cursor fonts produced by bdfresize don't look smooth,
     especially at larger magnification factors. It would be nice if
     someone could create better looking handcrafted version at
     some common sizes.
</itemize>

<sect>Technical discussion<label id=tech>

<p>Is it possible to write a X program that enlarges cursors
automatically?

<descrip>
<tag/(Partial) solution 1/ Use the XTestCompareCursor from the XTEST
extension. For all windows that the mouse pointer enters compare the
cursor of this window with a set of `known' cursors (e.&nbsp;g. from
the cursor font). If the cursor is found, replace it with an enlarged
version, otherwise either leave it alone or substitute a standard
cursor. This will only work where the XTest extension is available.

<tag/Solution 2/ Write a proxy X server that relays all client requests
unchanged to the real X server, except that it intercepts all requests
corresponing to the <TT>XCreate*Cursor</TT> Xlib
functions. <TT>XCreate*Cursor</TT> requests should be modified to use
an enlarged cursor. 

This proxy server simulates a new display, e.&nbsp;g. <tt/:1/. All
clients that connect to this display (e.&nbsp;g. <tt/xterm -display
:1/) are displayed on the real server (normally <tt/:0/) and their
mouse cursors are enlarged automatically. The mouse cursors of clients
that connect to <tt/:0/ will remain <em/unchanged/.
</descrip>

<sect>Other ideas how to make the mouse cursor more visible<label id=ideas>

<p>Here are some ideas for rather simple X programs that might make
mouse cursors easier to track.

<itemize>
<item> When a hot key is pressed display something (big cursor, small
     window, shaped window) at pointer position for 0.5s.
<item> use XRecolorCursor to change the mouse cursor color every 0.1s
</itemize>

A more demanding project would be <bf/mouse trails/ &agrave; la
windoze, i.&nbsp;e. when the mouse is moved and the mouse cursor needs
to be drawn in a different position, then the old mouse cursor does
not disappear at once, but after a short delay. Mouse trails would be
probably best implemented in a X server, but it might be feasible to
do it as a X client, or better as a proxy server (see section <ref id="tech"
name="Technical discussion"> for details).

<sect>Related info<label id=info>

<sect1>How to use a font server<label id=fontserver>

<p>A font server is a net service that provides a set of X11 fonts
with a simple protocol. It can be queried which fonts it provides and
will supply the font bitmap data on request.

You might want to use a font server to provide the X server with a
modified cursor font, instead of telling it where to find the font on
the file system. 

This method is especially handy if you use several machines that don't
share a common file system or if you use X terminals that support
the font server protocol. 

A font server program and associated tools comes with the X11R5+
distribution (AFAIK). 

<sect2>Setting up a font server<label id=fsconfig>

<p>Read the manual pages <em>fs(1)</em>, <em>fslsfonts(1)</em> (or
<em>xfs(1)</em>, <em>xfslsfonts(1)</em> under X11R6) and try it&mdash;it isn't
hard. Say, you are running the server on host <TT>some.host.edu</TT>
on port 7100. You can test the setup with the command 

<TT>fslsfonts -server some.host.edu:7100</TT>

To actually use the server issue the command 

<TT>xset +fp tcp/some.host.edu:7100</TT>

which should return without an error message.


<sect1>How to get the bdf source for some font<label id=getbdf>

<p>If you have set up a font server simply use <TT>fstobdf</TT> which
comes with the font server.

Alternatively you may try <TT>getbdf</TT> which can dump any installed
X11 font to a bdf file. 

</article>
<!--  LocalWords:  MINIHOWTO rg url mailto joerg schneider ira uka de LCD xfd
 -->
<!--  LocalWords:  fn co SGML linuxdoc html DVI PostScript bdf bdfresize mkdir
 -->
<!--  LocalWords:  bdftopcf pcf mkfontdir xset fp xsetroot olcursor decw XTest
 -->
<!--  LocalWords:  XCreate Xlib XRecolorCursor windoze AFAIK fs xfs edu archie
 -->
<!--  LocalWords:  fslsfonts xfslsfonts tcp fstobdf getbdf zcat xf cd xmkmf usr
 -->
<!--  LocalWords:  CCOPTIONS bsd
 -->
