Bounce Application Icon in Dock

Overview

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.

To do this you use the requestUserAttention method. There are two types of request:

• NSCriticalRequest
  • The dock icon will bounce until either the application becomes active or the request is canceled.
• NSInformationalRequest
  • The dock icon will bounce for one second. The request, though, remains active until either the application becomes active or the request is cancelled.

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.

Example code

This example will bounce the application's dock icon every second (Timer1.Interval default) while the application is not in focus.

• Drop a TTimer on a Form;
• Add the following code to unit1.pas;
• Add the Timer1Timer procedure to Timer1's onTimer event.

unit Unit1;

{$mode objfpc}{$H+}
{$modeswitch ObjectiveC1}

interface

uses
  Classes, SysUtils, Forms, Controls, Dialogs, ExtCtrls, StdCtrls, CocoaAll;

type

  { TForm1 }

  TForm1 = class(TForm)
    Timer1: TTimer;
    procedure FormCreate(Sender: TObject);
    procedure Timer1Timer(Sender: TObject);
  private

  public

  end;

var
  Form1: TForm1;

  FRequestUserAttentionID : Int64;    // Use an Integer if 32 bit application

implementation

{$R *.lfm}

{ TForm1 }

procedure TForm1.FormCreate(Sender: TObject);
begin
  NsApp := NSApplication.sharedApplication;
end;

procedure TForm1.Timer1Timer(Sender: TObject);
begin
  If(Form1.Active) then
    // no point trying to bounce if application has focus
    exit
  else
    // one shot bounce, no voice notification
    FRequestUserAttentionID := NSApp.requestUserAttention(NSInformationalRequest);
end;

end.

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:

   NSApp.cancelUserAttentionRequest(FRequestUserAttentionID);

If you are never going to use it in your application, you can omit declaring the variable and omit its assignment.

See also

• Application disable resize over Dock
• Hiding a macOS app from the Dock
• macOS Application Dock Menu
• Show Badge on Application Icon in Dock

External links

• Apple documentation: requestUserAttention

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.