Ajout d’actions personnalisées au contrôle ProgressBar
Les actions personnalisées peuvent ajouter des informations temporelles et de progression à un contrôle ProgressBar. Pour plus d’informations sur la création d’une boîte de dialogue d’affichage d’action avec un contrôle ProgressBar, consultez Création d’un contrôle ProgressBar.
Notez que deux actions personnalisées doivent être ajoutées au package Windows Installer pour signaler avec précision les informations temporelles et de progression au contrôle ProgressBar. Une action personnalisée doit être une action personnalisée différée. Cette action personnalisée doit terminer votre installation personnalisée et envoyer les quantités d’incréments individuels au contrôle ProgressBar lorsque le programme d’installation exécute le script d’installation. La deuxième action personnalisée doit être une action personnalisée d’exécution immédiate qui indique au contrôle ProgressBar le nombre de graduations à ajouter au nombre total pendant la phase d’acquisition et de génération de script de l’installation.
Pour ajouter une action personnalisée au contrôle ProgressBar
Déterminez comment l’action personnalisée décrira sa progression. Par exemple, une action personnalisée qui installe des clés de Registre peut afficher un message de progression et mettre à jour le contrôle ProgressBar chaque fois que le programme d’installation écrit une clé de Registre.
Chaque mise à jour par l’action personnalisée modifie la longueur du contrôle ProgressBar par un incrément constant. Spécifiez ou calculez le nombre de graduations dans chaque incrément. En règle générale, une modification de la longueur du contrôle ProgressBar d’une graduation correspond à l’installation d’un octet. Par exemple, si le programme d’installation installe environ 10 000 octets lorsqu’il écrit une clé de Registre, vous pouvez spécifier qu’il y a 10 000 graduations par incrément.
Spécifiez ou calculez le nombre total de graduations que l’action personnalisée ajoute à la longueur du contrôle ProgressBar. Le nombre de graduations ajoutées par l’action personnalisée est généralement calculé comme suit : (incrément de graduation) x (nombre d’éléments). Par exemple, si l’action personnalisée écrit 10 clés de Registre, le programme d’installation installe environ 100 000 octets et doit donc augmenter l’estimation de la longueur totale finale du contrôle ProgressBar de 100 000 graduations.
Notes
Pour calculer cela dynamiquement, l’action personnalisée doit contenir une section qui est immédiatement exécutée pendant la génération du script. La quantité de graduations signalée par votre action personnalisée d’exécution différée doit être égale au nombre de graduations ajoutées au nombre total de graduations par l’action d’exécution immédiate. Si ce n’est pas le cas, le temps restant, tel qu’indiqué par le contrôle de texte TimeRemaining, sera inexact.
Séparez votre action personnalisée en deux sections de code : une section qui s’exécute pendant la phase de génération de script et une section qui s’exécute pendant la phase d’exécution de l’installation. Vous pouvez faire cela à l’aide de deux fichiers ou vous pouvez utiliser un seul fichier en émettant une condition sur le mode d’exécution du programme d’installation. L’exemple suivant utilise un seul fichier et vérifie l’état de l’installation. Les sections de l’exemple sont conditionnées pour être exécutées selon que le programme d’installation se trouve dans la phase d’exécution ou de génération de script de l’installation.
La section qui s’exécute pendant la génération de script doit augmenter l’estimation de la longueur totale finale du contrôle ProgressBar par le nombre total de graduations dans l’action personnalisée. Pour ce faire, envoyez un message de progression ProgressAddition.
La section qui s’exécute pendant la phase d’exécution de l’installation doit configurer le texte du message et les modèles pour informer l’utilisateur de ce que fait l’action personnalisée et pour diriger le programme d’installation vers la mise à jour du contrôle ProgressBar. Par exemple, indiquez au programme d’installation de déplacer le contrôle ProgressBar vers l’avant d’un incrément et d’envoyer un message de progression explicite à chaque mise à jour. Cette section contient généralement une boucle si l’action personnalisée installe quelque chose. À chaque nouveau tour de boucle, le programme d’installation peut installer un élément de référence tel qu’une clé de Registre et mettre à jour le contrôle ProgressBar.
Ajoutez une action personnalisée d’exécution immédiate à votre package Windows Installer. Cette action personnalisée indique au contrôle ProgressBar combien avancer pendant les phases d’acquisition et de génération de script de l’installation. Pour l’exemple suivant, la source est la DLL créée en compilant l’exemple de code et la cible est le point d’entrée, CAProgress.
Ajoutez une action personnalisée d’exécution différée à votre package Windows Installer. Cette action personnalisée termine les étapes de l’installation réelle et indique au contrôle ProgressBar de combien faire avancer la barre au moment où le programme d’installation exécute le script d’installation. Pour l’exemple suivant, la source est la DLL créée en compilant l’exemple de code et la cible est le point d’entrée, CAProgress.
Planifiez les deux actions personnalisées entre InstallInitialize et InstallFinalize dans la table InstallExecuteSequence. L’action personnalisée différée doit être planifiée immédiatement après l’action personnalisée d’exécution immédiate. Le programme d’installation n’exécute pas l’action personnalisée différée tant que le script n’est pas exécuté.
L’exemple suivant montre comment ajouter une action personnalisée au contrôle ProgressBar. La source des deux actions personnalisées est la DLL créée en compilant l’exemple de code, et la cible des deux actions personnalisées est le point d’entrée, CAProgress. Cet exemple n’apporte aucune modification réelle au système, mais utilise le contrôle ProgressBar comme s’il installait 10 éléments de référence dont la taille est d’environ 10 000 octets. Le programme d’installation met à jour le message et le contrôle ProgressBar chaque fois qu’il installe un élément de référence.
#include <windows.h>
#include <msiquery.h>
#pragma comment(lib, "msi.lib")
// Specify or calculate the number of ticks in an increment
// to the ProgressBar
const UINT iTickIncrement = 10000;
// Specify or calculate the total number of ticks the custom
// action adds to the length of the ProgressBar
const UINT iNumberItems = 10;
const UINT iTotalTicks = iTickIncrement * iNumberItems;
UINT __stdcall CAProgress(MSIHANDLE hInstall)
{
// Tell the installer to check the installation state and execute
// the code needed during the rollback, acquisition, or
// execution phases of the installation.
if (MsiGetMode(hInstall,MSIRUNMODE_SCHEDULED) == TRUE)
{
PMSIHANDLE hActionRec = MsiCreateRecord(3);
PMSIHANDLE hProgressRec = MsiCreateRecord(3);
// Installer is executing the installation script. Set up a
// record specifying appropriate templates and text for
// messages that will inform the user about what the custom
// action is doing. Tell the installer to use this template and
// text in progress messages.
MsiRecordSetString(hActionRec, 1, TEXT("MyCustomAction"));
MsiRecordSetString(hActionRec, 2, TEXT("Incrementing the Progress Bar..."));
MsiRecordSetString(hActionRec, 3, TEXT("Incrementing tick [1] of [2]"));
UINT iResult = MsiProcessMessage(hInstall, INSTALLMESSAGE_ACTIONSTART, hActionRec);
if ((iResult == IDCANCEL))
return ERROR_INSTALL_USEREXIT;
// Tell the installer to use explicit progress messages.
MsiRecordSetInteger(hProgressRec, 1, 1);
MsiRecordSetInteger(hProgressRec, 2, 1);
MsiRecordSetInteger(hProgressRec, 3, 0);
iResult = MsiProcessMessage(hInstall, INSTALLMESSAGE_PROGRESS, hProgressRec);
if ((iResult == IDCANCEL))
return ERROR_INSTALL_USEREXIT;
//Specify that an update of the progress bar's position in
//this case means to move it forward by one increment.
MsiRecordSetInteger(hProgressRec, 1, 2);
MsiRecordSetInteger(hProgressRec, 2, iTickIncrement);
MsiRecordSetInteger(hProgressRec, 3, 0);
// The following loop sets up the record needed by the action
// messages and tells the installer to send a message to update
// the progress bar.
MsiRecordSetInteger(hActionRec, 2, iTotalTicks);
for( int i = 0; i < iTotalTicks; i+=iTickIncrement)
{
MsiRecordSetInteger(hActionRec, 1, i);
iResult = MsiProcessMessage(hInstall, INSTALLMESSAGE_ACTIONDATA, hActionRec);
if ((iResult == IDCANCEL))
return ERROR_INSTALL_USEREXIT;
iResult = MsiProcessMessage(hInstall, INSTALLMESSAGE_PROGRESS, hProgressRec);
if ((iResult == IDCANCEL))
return ERROR_INSTALL_USEREXIT;
//A real custom action would have code here that does a part
//of the installation. For this sample, code that installs
//10 registry keys.
Sleep(1000);
}
return ERROR_SUCCESS;
}
else
{
// Installer is generating the installation script of the
// custom action.
// Tell the installer to increase the value of the final total
// length of the progress bar by the total number of ticks in
// the custom action.
PMSIHANDLE hProgressRec = MsiCreateRecord(2);
MsiRecordSetInteger(hProgressRec, 1, 3);
MsiRecordSetInteger(hProgressRec, 2, iTotalTicks);
UINT iResult = MsiProcessMessage(hInstall, INSTALLMESSAGE_PROGRESS, hProgressRec);
if ((iResult == IDCANCEL))
return ERROR_INSTALL_USEREXIT;
return ERROR_SUCCESS;
}
}