ZeBoxx: /* The Script Code / Header */

2010-06-14T03:19:31Z

The Script Code / Header

â† Older revision		Revision as of 03:19, 14 June 2010
Line 107:		Line 107:
	*i .s)"		*i .s)"
	Pop $ITaskbarList3		Pop $ITaskbarList3
	${Else}		${Else}
	StrCpy $ITaskbarList3 0		StrCpy $ITaskbarList3 0
	${EndIf}		${EndIf}
	!endif		!endif
	!macroend		!macroend

ZeBoxx: /* Description */

2010-06-13T22:06:06Z

Description

â† Older revision		Revision as of 22:06, 13 June 2010
Line 8:		Line 8:
	Instead, it is intended for pages where taskbar progress indication is desired		Instead, it is intended for pages where taskbar progress indication is desired
	without use of a dialog progressbar, and for functionality not offered by the		without use of a dialog progressbar, and for functionality not offered by the
	~~TaskbarProgres~~ plug-in at this time.		TaskbarProgress plug-in at this time.

	This header is scripting-friendly and does not require initialization, Windows version detection, or clean-up.		This header is scripting-friendly and does not require initialization, Windows version detection, or clean-up.

ZeBoxx: Created page with '== Description == Provides control over the progress indicator available through [http://social.msdn.microsoft.com/Search/en-us?query=ITaskBarList3 ITaskBarList3], available from…'

2010-06-13T22:01:01Z

Created page with '== Description == Provides control over the progress indicator available through [http://social.msdn.microsoft.com/Search/en-us?query=ITaskBarList3 ITaskBarList3], available from…'

New page

== Description ==
Provides control over the progress indicator available through [http://social.msdn.microsoft.com/Search/en-us?query=ITaskBarList3 ITaskBarList3], available from Windows 7.

This header is not intended as a replacement for the [[TaskbarProgress plug-in]].

The TaskbarProgress plug-in can automatically handle progress display on dialogs with a progressbar, most typically the InstFiles page.

Instead, it is intended for pages where taskbar progress indication is desired
without use of a dialog progressbar, and for functionality not offered by the
TaskbarProgres plug-in at this time.

This header is scripting-friendly and does not require initialization, Windows version detection, or clean-up.

== Usage ==
Usage of this header has been made to be as simple as possible.
* Include this header in your sript.
<highlight-nsis>!include "TBProgress.nsh"</highlight-nsis>
* Call the desired command. For example, for 50% PROGRESS:
<highlight-nsis>${TBProgress} 50</highlight-nsis>
The commands themselves ensure that the ITaskBarList3 interface has been created and is valid for use - so you can use these commands regardless of Windows platform, and without having to worry about initialization and whether or not your installer is running silently.

There is one caveat: You should not use these commands -before- a taskbar button conceivably can be displayed. I.e. do not use these commands in .onInit. .onGUIInit is the earliest moment that these commands may be used.

== Commands ==
The following commands are available:

=== ${TBProgress} Value ===
Shorthand to setting the current progress as Value percentage.

* You should call this command whenever a process with known progress takes place within your installer.
* Overrides '''${TBProgress_State} Indeterminate''' and sets '''${TBProgress_State} Normal''' by design of ITaskBarList3.
* Can be used under '''${TBProgress_State Paused''' and '''${TBProgress_State} Error''' states, although this is not recommended as it will confuse end-users.

=== ${TBProgress_Progress} Value MaxValue ===
Sets the current progress to Value as a portion of MaxValue
* This command is provided in case you need exact control over the progress value, allowing you to set a custom maximum value.

=== ${TBProgress_State} NoProgress ===
Returns the taskbar button to a normal state (no progressbar).

* You should call this command whenever you are done showing progress.
* You are not required to call this command before exiting the installer.

=== ${TBProgress_State} Normal ===
Sets the taskbar button to a normal (green) progressbar state.

* You may call this command to end a '''${TBProgress_State} Paused''' or '''${TBProgress_State} Error''' command state and return to a regular state.

=== ${TBProgress_State} Paused ===
Sets the taskbar button to a paused (yellow) progressbar state.

* You should call this command whenever progress is paused due to an event that requires user input.
* You should call '''${TBProgress_State} Normal''' once the event has passed and progress will continue.
* You should call '''${TBProgress_State} NoProgress''' once the event has passed and progress will NOT continue.

=== ${TBProgress_State} Error ===
Sets the taskbar button to an error (red) progressbar state.

* You should call this command whenever progress has halted without hope for continuation.
* You should call '''${TBProgress_State} NoProgress''' once this indication is no longer required and the process for which you were indicating progress has been halted.
* Although you may continue progress within this state, or revert to a '''${TBProgress_State} Normal''' state, this is not recommended as it will confuse end-users.

=== ${TBProgress_State} Indeterminate ===
Sets the taskbar button to an indeterminate (green marquee) progressbar state.

* You should call this command whenever a process with UNKNOWN progress takes place within your installer which must complete in order for your installer to continue. For example, if you are running a secondary installer from your own installer, and cannot get its exact progress, use this command to show the user that the installer is performing work.

=== ${TBProgress_Init} ===
Initializes the ITaskBarList3 interface, which is stored in the ''$ITaskBarList3'' variable.

* This command is provided for programmers who wish to work directly with the ITaskBarList3 COM interface.
* You are not required to call this command in order to use the other commands - they all call this command internally and its code is only evaluated if not already done so.

== The Script Code / Header ==
<highlight-nsis>
!include "LogicLib.nsh"

!ifndef CLSCTX_INPROC_SERVER
!define CLSCTX_INPROC_SERVER 1
!endif

!define CLSID_ITaskbarList {56fdf344-fd6d-11d0-958a-006097c9a090}

!define IID_ITaskbarList3 {ea1afb91-9e28-4b86-90e9-9e9f8a5eefaf}
!define ITaskbarList3->SetProgressState $ITaskbarList3->10
!define ITaskbarList3->SetProgressValue $ITaskbarList3->9

!define TBPF_NOPROGRESS 0x00000000 ; Normal state / no progress bar
!define TBPF_INDETERMINATE 0x00000001 ; Marquee style progress bar
!define TBPF_NORMAL 0x00000002 ; Standard progress bar
!define TBPF_ERROR 0x00000004 ; Red taskbar button to indicate an error occurred
!define TBPF_PAUSED 0x00000008 ; Yellow taskbar button to indicate user attention
; (input) is required to resume progress

Var ITaskbarList3

!macro TBProgress_Init
!ifndef TBProgressInitialized
!define TBProgressInitialized
${Unless} ${Silent}
System::Call "ole32::CoCreateInstance( \
g '${CLSID_ITaskbarList}', \
i 0, \
i ${CLSCTX_INPROC_SERVER}, \
g '${IID_ITaskbarList3}', \
*i .s)"
Pop $ITaskbarList3
${Else}
StrCpy $ITaskbarList3 0
${EndIf}
!endif
!macroend
!define TBProgress_Init `!insertmacro TBProgress_Init`

!macro TBProgress_Progress Val Max
${TBProgress_Init}
${If} $ITaskbarList3 <> 0
System::Call "${ITaskbarList3->SetProgressValue}(i$HWNDPARENT, l${Val}, l${Max})"
${EndIf}
!macroend
!define TBProgress_Progress `!insertmacro TBProgress_Progress`

!macro TBProgress Val
${TBProgress_Progress} ${Val} 100
!macroend
!define TBProgress `!insertmacro TBProgress`

!macro TBProgress_State State
${TBProgress_Init}
${If} $ITaskbarList3 <> 0
System::Call "${ITaskbarList3->SetProgressState}(i$HWNDPARENT, i${TBPF_${State}})"
${EndIf}
!macroend
!define TBProgress_State `!insertmacro TBProgress_State`
</highlight-nsis>

== Tips ==
Read the MSDN [http://msdn.microsoft.com/en-us/library/aa511446.aspx#progressbars guidelines on proper (taskbar) progress usage].

For example:
:It may be tempting to use a loop to flash a taskbar button yellow. However, this is
:# highly annoying for end-users
:# is not the correct command. ( See FlashWindowEx on MSDN instead )

Another example:
:It may be tempting to show overall installer progress as x/N pages. Don't.

When using the TBProgress or TBProgress_Progress commands, consider [[Change caption of installer at runtime|changing the caption of the installer]] to indicate the progress value as a percentage.

When using the TBProgress_Indeterminate state, consider also using the [[SetCursor plug-in]] to set a WAIT cursor ONLY IF appropriate! (e.g. if you use a command which may significantly affect the system's responsiveness)

When using the TBProgress_Error state, consider using the [[NotifyIcon plug-in]] to alert the user to the error via the notification area of the taskbar.

You ''may'' use TBProgress_Error to indicate that the user cannot continue installation, even if you are not indicating any progress. For example: if your installer cannot continue due to any missing prerequisites, you may set a red taskbar button using:
<highlight-nsis>
${TBProgress_State} Error ; Set error state (red progressbar)
${TBProgress} 100 ; Set progress to 100% to cover progressbar button
</highlight-nsis>

If all you need is to show InstFiles progress, please do use the [[TaskbarProgress plug-in]]

[[Category:Code Examples]]

Set Taskbar button progress - Revision history

ZeBoxx: /* The Script Code / Header */

ZeBoxx: /* Description */

ZeBoxx: Created page with '== Description == Provides control over the progress indicator available through [http://social.msdn.microsoft.com/Search/en-us?query=ITaskBarList3 ITaskBarList3], available from…'