1# Copyright 2011, 2012, 2013, 2014, 2017 Kevin Ryde
2
3# This file is part of X11-Protocol-Other.
4#
5# X11-Protocol-Other is free software; you can redistribute it and/or
6# modify it under the terms of the GNU General Public License as published
7# by the Free Software Foundation; either version 3, or (at your option) any
8# later version.
9#
10# X11-Protocol-Other is distributed in the hope that it will be useful,
11# but WITHOUT ANY WARRANTY; without even the implied warranty of
12# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
13# Public License for more details.
14#
15# You should have received a copy of the GNU General Public License along
16# with X11-Protocol-Other.  If not, see <http://www.gnu.org/licenses/>.
17
18BEGIN { require 5 }
19package X11::CursorFont;
20use strict;
21use vars qw($VERSION @ISA @EXPORT_OK %CURSOR_GLYPH @CURSOR_NAME);
22
23use Exporter;
24@ISA = ('Exporter');
25@EXPORT_OK = qw(%CURSOR_GLYPH @CURSOR_NAME);
26
27# uncomment this to run the ### lines
28#use Smart::Comments;
29
30$VERSION = 31;
31
32%CURSOR_GLYPH
33  = (
34     # (shell-command "perl -n -e '/define XC_([^ ]*).*?([0-9]+)/ and $1 ne q{num_glyphs} and printf qq{     %-25s => %s,\n},$1,$2' </usr/include/X11/cursorfont.h" 'insert)
35
36     X_cursor                  => 0,
37     arrow                     => 2,
38     based_arrow_down          => 4,
39     based_arrow_up            => 6,
40     boat                      => 8,
41     bogosity                  => 10,
42     bottom_left_corner        => 12,
43     bottom_right_corner       => 14,
44     bottom_side               => 16,
45     bottom_tee                => 18,
46     box_spiral                => 20,
47     center_ptr                => 22,
48     circle                    => 24,
49     clock                     => 26,
50     coffee_mug                => 28,
51     cross                     => 30,
52     cross_reverse             => 32,
53     crosshair                 => 34,
54     diamond_cross             => 36,
55     dot                       => 38,
56     dotbox                    => 40,
57     double_arrow              => 42,
58     draft_large               => 44,
59     draft_small               => 46,
60     draped_box                => 48,
61     exchange                  => 50,
62     fleur                     => 52,
63     gobbler                   => 54,
64     gumby                     => 56,
65     hand1                     => 58,
66     hand2                     => 60,
67     heart                     => 62,
68     icon                      => 64,
69     iron_cross                => 66,
70     left_ptr                  => 68,
71     left_side                 => 70,
72     left_tee                  => 72,
73     leftbutton                => 74,
74     ll_angle                  => 76,
75     lr_angle                  => 78,
76     man                       => 80,
77     middlebutton              => 82,
78     mouse                     => 84,
79     pencil                    => 86,
80     pirate                    => 88,
81     plus                      => 90,
82     question_arrow            => 92,
83     right_ptr                 => 94,
84     right_side                => 96,
85     right_tee                 => 98,
86     rightbutton               => 100,
87     rtl_logo                  => 102,
88     sailboat                  => 104,
89     sb_down_arrow             => 106,
90     sb_h_double_arrow         => 108,
91     sb_left_arrow             => 110,
92     sb_right_arrow            => 112,
93     sb_up_arrow               => 114,
94     sb_v_double_arrow         => 116,
95     shuttle                   => 118,
96     sizing                    => 120,
97     spider                    => 122,
98     spraycan                  => 124,
99     star                      => 126,
100     target                    => 128,
101     tcross                    => 130,
102     top_left_arrow            => 132,
103     top_left_corner           => 134,
104     top_right_corner          => 136,
105     top_side                  => 138,
106     top_tee                   => 140,
107     trek                      => 142,
108     ul_angle                  => 144,
109     umbrella                  => 146,
110     ur_angle                  => 148,
111     watch                     => 150,
112     xterm                     => 152,
113    );
114### %CURSOR_GLYPH
115
116@CURSOR_NAME[values %CURSOR_GLYPH] = keys %CURSOR_GLYPH;
117$#CURSOR_NAME |= 1;   # odd number of entries
118### @CURSOR_NAME
119
120# or for explicit CURSOR_NAME list ... but that fills in the odd elements
121# with undefs, where values/keys leaves them uninitialised
122#  = (
123#    # (shell-command "perl -n -e '/define XC_([^ ]*).*?([0-9]+)/ and $1 ne q{num_glyphs} and do { printf qq{     %-30s # %d\n}, qq{q{$1},}, $i; $i+=2 }' </usr/include/X11/cursorfont.h" 'insert)
124#   );
125
1261;
127__END__
128
129=for stopwords Xlib Xmu glyph glyphs Ryde RGB multi-colour
130
131=head1 NAME
132
133X11::CursorFont - cursor font glyph names and numbers
134
135=for test_synopsis my ($X)
136
137=head1 SYNOPSIS
138
139 use X11::CursorFont '%CURSOR_GLYPH';
140 my $num = $CURSOR_GLYPH{'fleur'};               # is 52
141 my $name = $X11::CursorFont::CURSOR_NAME[52];   # is "fleur"
142
143=head1 DESCRIPTION
144
145This is the names and numbers of the glyphs in the X11 cursor font which
146contains various standard mouse pointer cursors.
147
148C<%CURSOR_GLYPH> maps a glyph name to its character number in the font,
149
150    $CURSOR_GLYPH{'fleur'}     # is 52
151
152C<@CURSOR_NAME> conversely is indexed by character number and gives the
153glyph name,
154
155    $CURSOR_NAME[52]           # is "fleur"
156
157Each glyph has an associated mask at character number glyph+1 which is the
158shape of the cursor (the displayed vs transparent pixels).  So the character
159numbers are always even and in C<@CURSOR_NAME> only the even character
160positions have names.
161
162The cursor images can be viewed with the usual C<xfd> font display program,
163
164     xfd -fn cursor
165
166The names are per the Xlib F</usr/include/X11/cursorfont.h> file, without
167the C<XC_> prefixes.  The full list is
168
169=cut
170
171# List generated by
172# (shell-command "perl -n -e '/define XC_([^ ]*).*?([0-9]+)/ and do { printf qq{    %-20s  %3d\n}, $1, $2;}' </usr/include/X11/cursorfont.h" 'insert)
173
174=pod
175
176    Name                  Number
177
178    X_cursor                0    default fat X
179    arrow                   2
180    based_arrow_down        4
181    based_arrow_up          6
182    boat                    8
183    bogosity               10
184    bottom_left_corner     12
185    bottom_right_corner    14
186    bottom_side            16
187    bottom_tee             18
188    box_spiral             20    a square spiral
189    center_ptr             22
190    circle                 24
191    clock                  26
192    coffee_mug             28
193    cross                  30
194    cross_reverse          32
195    crosshair              34    "+" shape
196    diamond_cross          36
197    dot                    38
198    dotbox                 40
199    double_arrow           42
200    draft_large            44
201    draft_small            46
202    draped_box             48
203    exchange               50
204    fleur                  52
205    gobbler                54
206    gumby                  56
207    hand1                  58
208    hand2                  60
209    heart                  62
210    icon                   64
211    iron_cross             66
212    left_ptr               68
213    left_side              70
214    left_tee               72
215    leftbutton             74
216    ll_angle               76
217    lr_angle               78
218    man                    80
219    middlebutton           82
220    mouse                  84
221    pencil                 86
222    pirate                 88    skull and crossbones
223    plus                   90
224    question_arrow         92
225    right_ptr              94
226    right_side             96
227    right_tee              98
228    rightbutton           100
229    rtl_logo              102
230    sailboat              104
231    sb_down_arrow         106
232    sb_h_double_arrow     108
233    sb_left_arrow         110
234    sb_right_arrow        112
235    sb_up_arrow           114
236    sb_v_double_arrow     116
237    shuttle               118
238    sizing                120
239    spider                122
240    spraycan              124
241    star                  126
242    target                128
243    tcross                130
244    top_left_arrow        132
245    top_left_corner       134
246    top_right_corner      136
247    top_side              138
248    top_tee               140
249    trek                  142
250    ul_angle              144
251    umbrella              146
252    ur_angle              148
253    watch                 150    a good "busy" indicator
254    xterm                 152    a vertical insertion bar
255
256C<X_cursor> is the usual default when the server first starts or when the
257root window is set to cursor "None".
258
259=head1 VARIABLES
260
261=over
262
263=item C<%X11::CursorFont::CURSOR_GLYPH>
264
265A mapping of glyph name to cursor font character number.
266
267=item C<@X11::CursorFont::CURSOR_NAME>
268
269A table of cursor font character number to glyph name.
270
271=back
272
273=head1 EXPORTS
274
275Nothing is exported by default, but C<%CURSOR_GLYPH> and C<@CURSOR_NAME> can
276be selected in usual C<Exporter> style (see L<Exporter>),
277
278    use X11::CursorFont '%CURSOR_GLYPH', '@CURSOR_NAME';
279
280=head1 EXAMPLE
281
282To create a cursor from a desired glyph,
283
284    my $cursor_name = 'spraycan';
285    my $cursor_glyph = $CURSOR_GLYPH{$cursor_name}; # number
286
287    my $cursor_font = $X->new_rsrc;
288    $X->OpenFont ($cursor_font, "cursor"); # cursor font
289
290    my $cursor = $X->new_rsrc;
291    $X->CreateGlyphCursor
292           ($cursor,
293            $cursor_font,  # font
294            $cursor_font,  # mask font
295            $cursor_glyph,      # glyph
296            $cursor_glyph + 1,  # and its mask
297            0,0,0,                  # foreground, black
298            0xFFFF,0xFFFF,0xFFFF);  # background, white
299
300    $X->CloseFont ($cursor_font);
301
302    # then use $cursor with CreateWindow or ChangeWindowAttributes
303    #       cursor => $cursor
304
305The C<$cursor_font> could be kept open if used repeatedly.  Opening and
306closing isn't a round-trip, so an open when needed may be enough.
307
308Any RGB colours can be given in C<CreateGlyphCursor()>, but actual
309appearance on screen will be limited by the hardware.
310
311All cursors in the core protocol are two-colours with pixels fully opaque or
312fully transparent as per this create.  The RENDER extension, when available,
313can make multi-colour and partial transparency if desired (see
314L<X11::Protocol::Ext::RENDER>).
315
316=head1 SEE ALSO
317
318L<X11::Protocol>,
319L<X11::KeySyms>
320
321F</usr/include/X11/cursorfont.h> and listing in the Xlib manual appendix B
322(C<http://www.x.org/docs/X11/> or
323F</usr/share/doc/libx11-dev/libX11.txt.gz>).
324
325Xlib Xmu C<XmuCursorNameToIndex()> (C<http://www.x.org/docs/Xmu/> or
326F</usr/share/doc/libxmu-headers/Xmu.txt.gz>)
327
328L<xfd(1)> to display the cursor font.
329
330L<xsetroot(1)> to change the root window cursor.
331
332=head1 HOME PAGE
333
334L<http://user42.tuxfamily.org/x11-protocol-other/index.html>
335
336=head1 LICENSE
337
338Copyright 2011, 2012, 2013, 2014, 2017 Kevin Ryde
339
340X11-Protocol-Other is free software; you can redistribute it and/or modify
341it under the terms of the GNU General Public License as published by the
342Free Software Foundation; either version 3, or (at your option) any later
343version.
344
345X11-Protocol-Other is distributed in the hope that it will be useful, but
346WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
347or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
348more details.
349
350You should have received a copy of the GNU General Public License along with
351X11-Protocol-Other.  If not, see <http://www.gnu.org/licenses/>.
352
353=cut
354