Vcl.JumpList.TCustomJumpList

From RAD Studio API Documentation
Jump to: navigation, search

System.Classes.TComponentSystem.Classes.TPersistentSystem.TObjectTCustomJumpList

Delphi

TCustomJumpList = class(TComponent)

C++

class PASCALIMPLEMENTATION TCustomJumpList : public System::Classes::TComponent

Properties

Type Visibility Source Unit Parent
class public
Vcl.JumpList.pas
Vcl.JumpList.hpp
Vcl.JumpList Vcl.JumpList

Description

JumpList.png

Base class for components that provide support for Windows Jump Lists, such as TJumpList.

Windows jump lists were introduced in Windows 7. To use TCustomJumpList subclasses, your application must be running on Windows 7 or later. When TCustomJumpList runs on a version of Windows that does not support jump lists, TCustomJumpList.Enabled becomes False.

Note: Enabled is False by default, remember to change its value to True for your jump list to work.

TCustomJumpList subclasses let you define at design time a list of tasks that provide shortcuts for functionality of your application, and any number of custom categories with custom items. After you define your tasks and custom categories and items, you must call UpdateList so that your changes are visible in the jump list of your application. Alternatively, you can enable the AutoRefresh property of your jump list component if you want your changes to be visible as soon as your application runs, and after any change you make to your jump list at run time.

Note: Windows does not show empty lists.

Users can remove tasks and custom items from the lists of tasks and custom items that your application defines. When you call some methods, such as UpdateList, these methods obtain a list of items that your user removed from the jump list of your application. Handle the OnItemDeleted event to keep track of these files and remove them from your jump list component. Nothing prevents you from adding these items again to the jump list, but Windows recommends programmers to respect user choices.

You can also modify the tasks and custom categories of your application at run time. You can use the following methods to manage your tasks and custom categories at run time, either :

Your jump list component provides an event, OnItemsLoaded, which occurs when the component finishes loading. If you want to define all your tasks or custom categories at run time instead of defining them at design time, this is the earliest point when you can define their initial values in the execution flow of your application.

Jump lists also allow you to show files that the user has opened with your application in the past. You can show recent files, frequent files, or both. Although showing both recent and frequent files is possible, Microsoft recommends using only one of these categories in each application.

Windows keeps these lists of files, which you can query using GetRecentList or GetFrequentList. The lists of recent and frequent files include files that your users opens manually or that your user opens from your application using TOpenDialog. You can also modify these lists at run time using the following methods: AddToRecent, RemoveFromRecent, RemoveAllFromRecent. These methods affect to both lists; that is, if you add or remove a file entry, you are adding or removing it from both the list of recent files and the list of frequent files. It is not possible to add or remove file entries from only one of those lists.

Note: Recent and frequent files are disabled in applications by default. For your application to be able to show recent or frequent files in its jump list, you application must meet either of the following requirements:
  • The user of your application must have opened at least one file using your application.
  • You must register your application as a file handler for one or more file types on the system.

When your application is made of multiple processes, you can use the ApplicationID property to keep a common jump list for all the processes of your application. If your application already uses Application User Model IDs, fill ApplicationID with the ID of your application.

If more than one instance of your application can be running at the same time, you must implement some mechanism that prevents two instances from modifying the application jump list at the same time. Otherwise, changes to the jump list from one instance of your application can overwrite changes made to the jump list from a different instance of your application.

See Also