Bounce Application Icon in Dock: what changed

Revision 0 to 1. Removed lines have a minus sign; added lines have a plus sign.

Title: Bounce Application Icon in Dock

New		Line
1	+	## Overview
2	+
3	+	Bouncing your application's icon in the dock can be useful to attract a user's attention when, for example, a long-running task has finished.
4	+
5	+	To do this you use the requestUserAttention method. There are two types of request:
6	+
7	+	- NSCriticalRequest
8	+	- The dock icon will bounce until either the application becomes active or the request is canceled.
9	+	- NSInformationalRequest
10	+	- The dock icon will bounce for one second. The request, though, remains active until either the application becomes active or the request is cancelled.
11	+
12	+	Activating the application cancels the user attention request. A spoken notification ("Excuse me, MyApp dot app needs your attention") will occur if spoken notifications are enabled. Sending requestUserAttention to an application that is already active has no effect.
13	+
14	+	## Example code
15	+
16	+	This example will bounce the application's dock icon every second (Timer1.Interval default) while the application is not in focus.
17	+
18	+	- Drop a TTimer on a Form;
19	+	- Add the following code to unit1.pas;
20	+	- Add the Timer1Timer procedure to Timer1's onTimer event.
21	+
22	+	``` pascal
23	+	unit Unit1;
24	+
25	+	{$mode objfpc}{$H+}
26	+	{$modeswitch ObjectiveC1}
27	+
28	+	interface
29	+
30	+	uses
31	+	Classes, SysUtils, Forms, Controls, Dialogs, ExtCtrls, StdCtrls, CocoaAll;
32	+
33	+	type
34	+
35	+	{ TForm1 }
36	+
37	+	TForm1 = class(TForm)
38	+	Timer1: TTimer;
39	+	procedure FormCreate(Sender: TObject);
40	+	procedure Timer1Timer(Sender: TObject);
41	+	private
42	+
43	+	public
44	+
45	+	end;
46	+
47	+	var
48	+	Form1: TForm1;
49	+
50	+	FRequestUserAttentionID : Int64; // Use an Integer if 32 bit application
51	+
52	+	implementation
53	+
54	+	{$R *.lfm}
55	+
56	+	{ TForm1 }
57	+
58	+	procedure TForm1.FormCreate(Sender: TObject);
59	+	begin
60	+	NsApp := NSApplication.sharedApplication;
61	+	end;
62	+
63	+	procedure TForm1.Timer1Timer(Sender: TObject);
64	+	begin
65	+	If(Form1.Active) then
66	+	// no point trying to bounce if application has focus
67	+	exit
68	+	else
69	+	// one shot bounce, no voice notification
70	+	FRequestUserAttentionID := NSApp.requestUserAttention(NSInformationalRequest);
71	+	end;
72	+
73	+	end.
74	+	```
75	+
76	+	While the FRequestUserAttentionID variable is not used in this demonstration, it is useful if you need to cancel the requestUserAttention which you can do with:
77	+
78	+	``` pascal
79	+	NSApp.cancelUserAttentionRequest(FRequestUserAttentionID);
80	+	```
81	+
82	+	If you are never going to use it in your application, you can omit declaring the variable and omit its assignment.
83	+
84	+	## See also
85	+
86	+	- [[Application disable resize over Dock]]
87	+	- [[Hiding a macOS app from the Dock]]
88	+	- [[macOS Application Dock Menu]]
89	+	- [[Show Badge on Application Icon in Dock]]
90	+
91	+	## External links
92	+
93	+	- [Apple documentation: requestUserAttention](https://developer.apple.com/documentation/appkit/nsapplication/1428358-requestuserattention?language=objc)
94	+
95	+	---
96	+	From the Free Pascal wiki, page "Bounce Application Icon in Dock", as it stood on 2021-12-15 after a change by Trev, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).

Back to history