1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
|
function oldType = ShowCursor(type, screenid, mouseid)
% oldType = ShowCursor([type][, screenidOrWindow=0][, mouseid])
%
% ShowCursor redisplays the mouse pointer after a previous call to HideCursor.
%
% If the optional 'type' is specified, it also allows to alter the shape of the
% cursor. Note that this function may not have any effect if the cursor location
% is not on top of an open onscreen window, as cursor visibility or shape may not
% be under Psychtoolbox control while the cursor interacts with other desktop
% items.
%
% 'screenidOrWindow' allows to specify the screen or onscreen window to which
% the function should apply. Although optional, it is strongly recommended to
% provide this parameter for cross-platform compatibility across operating systems.
%
% The optional 'mouseid' allows to select which mouse cursor shall be redisplayed
% or changed in visual appearance. This only makes sense if you have multiple
% visible mouse cursors, and it is a Linux/X11 only feature.
%
% The return value 'oldType' is always zero, as this query mechanism is not
% supported with PTB-3. Just returned for backwards-compatibility.
%
% Cursor shape can be selected. These types are defined by name:
%
% 'Arrow' = Standard mouse-pointer arrow.
% 'CrossHair' = A cross-hair cursor.
% 'Hand' = A hand symbol.
% 'SandClock' = Some sort of sand clock/hour-glass (not available on OSX).
% 'TextCursor' = A text selection/caret placement cursor (AKA I Beam).
%
% Apart from those names, you can pass integral numbers for 'type' to select
% further shapes. The mapping of numbers to shapes is operating system
% dependent, and therefore not portable across different platforms. On
% MS-Windows, you can select between number 0 to 13. On Linux/X11 you can
% select from a wide range of numbers from 0 up to (at least) 152, maybe
% more, depending on your setup. See the C header file "X11/cursorfont.h"
% for a mapping of numbers to shapes. Passing invalid numbers can create
% errors. On Linux with Wayland backend, you can pass custom additional
% namestrings as 'type'.
%
% LINUX: ____________________________________________________________________
%
% Linux allows for display and handling of multiple mouse cursors if your
% X-Server is of version 1.7 or later, or if you use the Wayland display
% backend on a modern Wayland server.
%
% OSX: ______________________________________________________________________
%
% If provided, an optional numeric 'type' argument changes the cursor shape to:
%
% 0: Arrow = like 'Arrow'
% 4: I Beam = like 'TextCursor'
% 5: Cross = like 'CrossHair'
% 10: Hand = like 'Hand'
%
% Better use the names for cross platform portability!
%
% Windows: __________________________________________________________________
%
% If provided, an optional numeric 'type' argument changes the cursor shape to:
%
% 0: Arrow (IDC_ARROW)
% 1: Crosshair (IDC_CROSS)
% 2: Hand (IDC_HAND)
% 3: Four-pointed arrow pointing north, south, east, and west (IDC_SIZEALL)
% 4: Double-pointed arrow pointing north and south (IDC_SIZENS)
% 5: Double-pointed arrow pointing west and east (IDC_SIZEWE)
% 6: Hourglass (IDC_WAIT)
% 7: Slashed circle (IDC_NO)
% 8: I-beam (IDC_IBEAM)
% 9: Double-pointed arrow pointing northeast and southwest (IDC_SIZENESW)
% 10: Double-pointed arrow pointing northwest and southeast (IDC_SIZENWSE)
% 11: Standard arrow and small hourglass (IDC_APPSTARTING)
% 12: Arrow and question mark (IDC_HELP)
% 13: Vertical arrow (IDC_UPARROW)
% ___________________________________________________________________________
% 7/23/97 dgp Cosmetic editing.
% 8/15/97 dgp Explain hide/show counter.
% 3/15/99 xmz Added comments for PC version.
% 8/19/00 dgp Cosmetic.
% 4/14/03 awi ****** OS X-specific fork from the OS 9 version *******
% Added call to Screen('ShowCursor'...) for OS X.
% 7/12/04 awi Divided into sections by platform.
% 11/16/04 awi Renamed Screen("ShowCursor") to Screen("ShowCursorHelper").
% 10/4/05 awi Note here that dgp made unnoted cosmetic changes between 11/16/04 and 10/4/05.
% 09/21/07 mk Added code for selecting 'type' - the shape of a cursor - on supported systems.
% 08/14/14 dcn Fixed typo and simplified
% 01/13/15 mk Update help text to match reality better, esp. OSX.
% 05/19/15 dcn Adding 'TextCursor' as now supported on all platforms.
% 03/30/20 dcn Added other standard Windows cursors.
% We default to setup of display screen zero, if no
% screenid provided. This argument is ignored on
% Windows and OS/X anyway. Only meaningful for
% Linux with X11. Linux with Wayland ignores screenid.
if nargin < 2 || isempty(screenid)
screenid = 0;
end
if nargin < 3
mouseid = [];
end
% Default to: No change in cursor shape...
if nargin < 1
type = [];
else
% Cursor shape change requested as well. Mapping of
% types to shapes is highly OS dependent...
if ischar(type)
% Name string provided. We can map a few symbolic names to proper
% id's for the different operating systems:
if strcmpi(type, 'Arrow');
% True for Windows and OS/X:
type = 0;
if IsLinux
type = 2;
end
end
if strcmpi(type, 'CrossHair');
% True for Windows:
type = 1;
if IsOSX
type = 5;
end
if IsLinux
type = 34;
end
end
if strcmpi(type, 'Hand');
% True for Windows:
type = 2;
if IsOSX
type = 10;
end
if IsLinux
type = 58;
end
end
if strcmpi(type, 'SandClock');
% True for Windows:
type = 6;
if IsOSX
type = 7;
end
if IsLinux
type = 26;
end
end
if strcmpi(type, 'TextCursor');
% True for Windows:
type = 8;
if IsOSX
type = 4;
end
if IsLinux
type = 1;
end
end
% Linux + Wayland allows passing name strings for cursors, on other
% setups still having a unremapped string means failure:
if ischar(type) && (~IsLinux || ~IsWayland)
error('Unknown ''type'' shape specification passed to ShowCursor()!');
end
elseif ~isnumeric(type)
error('type argument provided to ShowCursor() was not numeric or text');
end
end
% Return a dummy oldtype, we don't have this info...
oldType = 0;
% Use Screen to emulate ShowCursor.mex
Screen('ShowCursorHelper', screenid, type, mouseid);
|
