← Back to branch summary

~ubuntu-branches/ubuntu/lucid/nsis/lucid

« back to all changes in this revision

Viewing changes to Docs/src/callback.but

  • Committer: Bazaar Package Importer
  • Author(s): Paul Wise
  • Date: 2008-09-01 07:20:44 UTC
  • mfrom: (3.1.9 intrepid)
  • Revision ID: james.westby@ubuntu.com-20080901072044-mjev9xfej6i2d63t
Tags: 2.37-3
Add nsDialogs stack corruption fix from nsis 2.38

Show diffs side-by-side

added added

removed removed

Lines of Context:
Docs/src/callback.but
1
 
\S1{callbacks} Callback Functions
2
 
 
3
 
You can create callback functions which have special names, that will be called by the installer at certain points in the install. Below is a list of currently available callbacks:
4
 
 
5
 
\S2{instcallbacks} Install Callbacks
6
 
 
7
 
\S3{onguiinit} .onGUIInit
8
 
 
9
 
This callback will be called just before the first page is loaded and the installer dialog is shown, allowing you to tweak the user interface.
10
 
 
11
 
Example:
12
 
 
13
 
\c  !include "WinMessages.nsh"
14
 
\c
15
 
\c  Function .onGUIInit
16
 
\c    # 1028 is the id of the branding text control
17
 
\c    GetDlgItem $R0 $HWNDPARENT 1028
18
 
\c    CreateFont $R1 "Tahoma" 10 700
19
 
\c    SendMessage $R0 ${WM_SETFONT} $R1 0
20
 
\c    # set background color to white and text color to red
21
 
\c    SetCtlColors $R0 FFFFFF FF0000
22
 
\c  FunctionEnd
23
 
 
24
 
\S3{oninit} .onInit
25
 
 
26
 
This callback will be called when the installer is nearly finished initializing. If the '.onInit' function calls \R{abort}{Abort}, the installer will quit instantly.
27
 
 
28
 
Here are two examples of how this might be used:
29
 
 
30
 
\c  Function .onInit
31
 
\c    MessageBox MB_YESNO "This will install. Continue?" IDYES NoAbort
32
 
\c      Abort ; causes installer to quit.
33
 
\c    NoAbort:
34
 
\c  FunctionEnd
35
 
 
36
 
or:
37
 
 
38
 
\c  Function .onInit
39
 
\c    ReadINIStr $INSTDIR $WINDIR\wincmd.ini Configuration InstallDir
40
 
\c    StrCmp $INSTDIR "" 0 NoAbort
41
 
\c      MessageBox MB_OK "Windows Commander not found. Unable to get install path."
42
 
\c      Abort ; causes installer to quit.
43
 
\c    NoAbort:
44
 
\c  FunctionEnd
45
 
 
46
 
\S3{oninstfailed} .onInstFailed
47
 
 
48
 
This callback is called when the user hits the 'cancel' button after the install has failed (if it could not extract a file, or the install script used the \R{abort}{Abort} command).
49
 
 
50
 
Example:
51
 
 
52
 
\c   Function .onInstFailed
53
 
\c     MessageBox MB_OK "Better luck next time."
54
 
\c   FunctionEnd
55
 
 
56
 
\S3{oninstsuccess} .onInstSuccess
57
 
 
58
 
This callback is called when the install was successful, right before the install window closes (which may be after the user clicks 'Close' if \R{aautoclosewindow}{AutoCloseWindow} or \R{setautoclose}{SetAutoClose} is set to false).
59
 
 
60
 
Example:
61
 
 
62
 
\c   Function .onInstSuccess
63
 
\c     MessageBox MB_YESNO "Congrats, it worked. View readme?" IDNO NoReadme
64
 
\c       Exec notepad.exe ; view readme or whatever, if you want.
65
 
\c     NoReadme:
66
 
\c   FunctionEnd
67
 
 
68
 
\S3{onguiend} .onGUIEnd
69
 
 
70
 
This callback is called right after the installer window closes. Use it to free any user interface related plug-ins if needed.
71
 
 
72
 
\S3{onmouseoversection} .onMouseOverSection
73
 
 
74
 
This callback is called whenever the mouse position over the sections tree has changed. This allows you to set a description for each section for example. The section id on which the mouse is over currently is stored, temporarily, in $0.
75
 
 
76
 
Example:
77
 
 
78
 
\c   Function .onMouseOverSection
79
 
\c     FindWindow $R0 "#32770" "" $HWNDPARENT
80
 
\c     GetDlgItem $R0 $R0 1043 ; description item (must be added to the UI)
81
 
\c
82
 
\c     StrCmp $0 0 "" +2
83
 
\c       SendMessage $R0 ${WM_SETTEXT} 0 "STR:first section description"
84
 
\c
85
 
\c     StrCmp $0 1 "" +2
86
 
\c       SendMessage $R0 ${WM_SETTEXT} 0 "STR:second section description"
87
 
\c   FunctionEnd
88
 
 
89
 
\S3{onrebootfailed} .onRebootFailed
90
 
 
91
 
This callback is called if \R{reboot}{Reboot} fails. \R{writeuninstaller}{WriteUninstaller}, \R{plugindlls}{plug-ins}, \R{file}{File} and \R{writeregbin}{WriteRegBin} should not be used in this callback.
92
 
 
93
 
Example:
94
 
 
95
 
\c  Function .onRebootFailed
96
 
\c    MessageBox MB_OK|MB_ICONSTOP "Reboot failed. Please reboot manually." /SD IDOK
97
 
\c  FunctionEnd
98
 
 
99
 
\S3{onselchange} .onSelChange
100
 
 
101
 
Called when the selection changes on the \R{pages}{component page}. Useful for using with \R{sectionsetflags}{SectionSetFlags} and \R{sectiongetflags}{SectionGetFlags}.
102
 
 
103
 
\S3{onuserabort} .onUserAbort
104
 
 
105
 
This callback is called when the user hits the 'cancel' button, and the install hasn't already failed. If this function calls \R{abort}{Abort}, the install will not be aborted.
106
 
 
107
 
Example:
108
 
 
109
 
\c  Function .onUserAbort
110
 
\c    MessageBox MB_YESNO "Abort install?" IDYES NoCancelAbort
111
 
\c      Abort ; causes installer to not quit.
112
 
\c    NoCancelAbort:
113
 
\c  FunctionEnd
114
 
 
115
 
\S3{onverifyinstdir} .onVerifyInstDir
116
 
 
117
 
This callback enables control over whether or not an installation path is valid for your installer. This code will be called every time the user changes the install directory, so it shouldn't do anything crazy with \R{messagebox}{MessageBox} or the likes. If this function calls \R{abort}{Abort}, the installation path in $INSTDIR is deemed invalid.
118
 
 
119
 
Example:
120
 
 
121
 
\c   Function .onVerifyInstDir
122
 
\c     IfFileExists $INSTDIR\Winamp.exe PathGood
123
 
\c       Abort ; if $INSTDIR is not a winamp directory, don't let us install there
124
 
\c     PathGood:
125
 
\c   FunctionEnd
126
 
 
127
 
\S2{uninstcallbacks} Uninstall Callbacks
128
 
 
129
 
\S3{unonguiinit} un.onGUIInit
130
 
 
131
 
This callback will be called just before the first page is loaded and the installer dialog is shown, allowing you to tweak the user interface.
132
 
 
133
 
Have a look at \R{onguiinit}{.onGUIInit} for an example.
134
 
 
135
 
\S3{unonInit} un.onInit
136
 
 
137
 
This callback will be called when the uninstaller is nearly finished initializing. If the 'un.onInit' function calls Abort, the uninstaller will quit instantly. Note that this function can verify and/or modify $INSTDIR if necessary.
138
 
 
139
 
Here are two examples of how this might be used:
140
 
 
141
 
\c   Function un.onInit
142
 
\c     MessageBox MB_YESNO "This will uninstall. Continue?" IDYES NoAbort
143
 
\c       Abort ; causes uninstaller to quit.
144
 
\c     NoAbort:
145
 
\c   FunctionEnd
146
 
 
147
 
or:
148
 
 
149
 
\c   Function un.onInit
150
 
\c     IfFileExists $INSTDIR\myfile.exe found
151
 
\c       Messagebox MB_OK "Uninstall path incorrect"
152
 
\c       Abort
153
 
\c     found:
154
 
\c   FunctionEnd
155
 
 
156
 
\S3{unonuninstfailed} un.onUninstFailed
157
 
 
158
 
This callback is called when the user hits the 'cancel' button after the uninstall has failed (if it used the \R{abort}{Abort command} or otherwise failed).
159
 
 
160
 
Example:
161
 
 
162
 
\c   Function un.onUninstFailed
163
 
\c     MessageBox MB_OK "Better luck next time."
164
 
\c   FunctionEnd
165
 
 
166
 
\S3{unonuninstsuccess} un.onUninstSuccess
167
 
 
168
 
This callback is called when the uninstall was successful, right before the install window closes (which may be after the user clicks 'Close' if \R{setautoclose}{SetAutoClose} is set to false)..
169
 
 
170
 
Example:
171
 
 
172
 
\c   Function un.onUninstSuccess
173
 
\c     MessageBox MB_OK "Congrats, it's gone."
174
 
\c   FunctionEnd
175
 
 
176
 
\S3{unonguiend} un.onGUIEnd
177
 
 
178
 
This callback is called right after the uninstaller window closes. Use it to free any user interface related plug-ins if needed.
179
 
 
180
 
\S3{unonrebootfailed} un.onRebootFailed
181
 
 
182
 
This callback is called if \R{reboot}{Reboot} fails. \R{writeuninstaller}{WriteUninstaller}, \R{plugindlls}{plug-ins}, \R{file}{File} and \R{writeregbin}{WriteRegBin} should not be used in this callback.
183
 
 
184
 
Example:
185
 
 
186
 
\c  Function un.onRebootFailed
187
 
\c    MessageBox MB_OK|MB_ICONSTOP "Reboot failed. Please reboot manually." /SD IDOK
188
 
\c  FunctionEnd
189
 
 
190
 
\S3{unonuserabort} un.onUserAbort
191
 
 
192
 
This callback is called when the user hits the 'cancel' button and the uninstall hasn't already failed. If this function calls Abort, the install will not be aborted.
193
 
 
194
 
Example:
195
 
 
196
 
\c   Function un.onUserAbort
197
 
\c     MessageBox MB_YESNO "Abort uninstall?" IDYES NoCancelAbort
198
 
\c       Abort ; causes uninstaller to not quit.
199
 
\c     NoCancelAbort:
 
1
\S1{callbacks} Callback Functions
 
2
 
 
3
You can create callback functions which have special names, that will be called by the installer at certain points in the install. Below is a list of currently available callbacks:
 
4
 
 
5
\S2{instcallbacks} Install Callbacks
 
6
 
 
7
\S3{onguiinit} .onGUIInit
 
8
 
 
9
This callback will be called just before the first page is loaded and the installer dialog is shown, allowing you to tweak the user interface.
 
10
 
 
11
Example:
 
12
 
 
13
\c  !include "WinMessages.nsh"
 
14
\c
 
15
\c  Function .onGUIInit
 
16
\c    # 1028 is the id of the branding text control
 
17
\c    GetDlgItem $R0 $HWNDPARENT 1028
 
18
\c    CreateFont $R1 "Tahoma" 10 700
 
19
\c    SendMessage $R0 ${WM_SETFONT} $R1 0
 
20
\c    # set background color to white and text color to red
 
21
\c    SetCtlColors $R0 FFFFFF FF0000
 
22
\c  FunctionEnd
 
23
 
 
24
\S3{oninit} .onInit
 
25
 
 
26
This callback will be called when the installer is nearly finished initializing. If the '.onInit' function calls \R{abort}{Abort}, the installer will quit instantly.
 
27
 
 
28
Here are two examples of how this might be used:
 
29
 
 
30
\c  Function .onInit
 
31
\c    MessageBox MB_YESNO "This will install. Continue?" IDYES NoAbort
 
32
\c      Abort ; causes installer to quit.
 
33
\c    NoAbort:
 
34
\c  FunctionEnd
 
35
 
 
36
or:
 
37
 
 
38
\c  Function .onInit
 
39
\c    ReadINIStr $INSTDIR $WINDIR\wincmd.ini Configuration InstallDir
 
40
\c    StrCmp $INSTDIR "" 0 NoAbort
 
41
\c      MessageBox MB_OK "Windows Commander not found. Unable to get install path."
 
42
\c      Abort ; causes installer to quit.
 
43
\c    NoAbort:
 
44
\c  FunctionEnd
 
45
 
 
46
\S3{oninstfailed} .onInstFailed
 
47
 
 
48
This callback is called when the user hits the 'cancel' button after the install has failed (if it could not extract a file, or the install script used the \R{abort}{Abort} command).
 
49
 
 
50
Example:
 
51
 
 
52
\c   Function .onInstFailed
 
53
\c     MessageBox MB_OK "Better luck next time."
 
54
\c   FunctionEnd
 
55
 
 
56
\S3{oninstsuccess} .onInstSuccess
 
57
 
 
58
This callback is called when the install was successful, right before the install window closes (which may be after the user clicks 'Close' if \R{aautoclosewindow}{AutoCloseWindow} or \R{setautoclose}{SetAutoClose} is set to false).
 
59
 
 
60
Example:
 
61
 
 
62
\c   Function .onInstSuccess
 
63
\c     MessageBox MB_YESNO "Congrats, it worked. View readme?" IDNO NoReadme
 
64
\c       Exec notepad.exe ; view readme or whatever, if you want.
 
65
\c     NoReadme:
 
66
\c   FunctionEnd
 
67
 
 
68
\S3{onguiend} .onGUIEnd
 
69
 
 
70
This callback is called right after the installer window closes. Use it to free any user interface related plug-ins if needed.
 
71
 
 
72
\S3{onmouseoversection} .onMouseOverSection
 
73
 
 
74
This callback is called whenever the mouse position over the sections tree has changed. This allows you to set a description for each section for example. The section id on which the mouse is over currently is stored, temporarily, in $0.
 
75
 
 
76
Example:
 
77
 
 
78
\c   Function .onMouseOverSection
 
79
\c     FindWindow $R0 "#32770" "" $HWNDPARENT
 
80
\c     GetDlgItem $R0 $R0 1043 ; description item (must be added to the UI)
 
81
\c
 
82
\c     StrCmp $0 0 "" +2
 
83
\c       SendMessage $R0 ${WM_SETTEXT} 0 "STR:first section description"
 
84
\c
 
85
\c     StrCmp $0 1 "" +2
 
86
\c       SendMessage $R0 ${WM_SETTEXT} 0 "STR:second section description"
 
87
\c   FunctionEnd
 
88
 
 
89
\S3{onrebootfailed} .onRebootFailed
 
90
 
 
91
This callback is called if \R{reboot}{Reboot} fails. \R{writeuninstaller}{WriteUninstaller}, \R{plugindlls}{plug-ins}, \R{file}{File} and \R{writeregbin}{WriteRegBin} should not be used in this callback.
 
92
 
 
93
Example:
 
94
 
 
95
\c  Function .onRebootFailed
 
96
\c    MessageBox MB_OK|MB_ICONSTOP "Reboot failed. Please reboot manually." /SD IDOK
 
97
\c  FunctionEnd
 
98
 
 
99
\S3{onselchange} .onSelChange
 
100
 
 
101
Called when the selection changes on the \R{pages}{component page}. Useful for using with \R{sectionsetflags}{SectionSetFlags} and \R{sectiongetflags}{SectionGetFlags}.
 
102
 
 
103
Selection changes include both section selection and installation type change.
 
104
 
 
105
\S3{onuserabort} .onUserAbort
 
106
 
 
107
This callback is called when the user hits the 'cancel' button, and the install hasn't already failed. If this function calls \R{abort}{Abort}, the install will not be aborted.
 
108
 
 
109
Example:
 
110
 
 
111
\c  Function .onUserAbort
 
112
\c    MessageBox MB_YESNO "Abort install?" IDYES NoCancelAbort
 
113
\c      Abort ; causes installer to not quit.
 
114
\c    NoCancelAbort:
 
115
\c  FunctionEnd
 
116
 
 
117
\S3{onverifyinstdir} .onVerifyInstDir
 
118
 
 
119
This callback enables control over whether or not an installation path is valid for your installer. This code will be called every time the user changes the install directory, so it shouldn't do anything crazy with \R{messagebox}{MessageBox} or the likes. If this function calls \R{abort}{Abort}, the installation path in $INSTDIR is deemed invalid.
 
120
 
 
121
Example:
 
122
 
 
123
\c   Function .onVerifyInstDir
 
124
\c     IfFileExists $INSTDIR\Winamp.exe PathGood
 
125
\c       Abort ; if $INSTDIR is not a winamp directory, don't let us install there
 
126
\c     PathGood:
 
127
\c   FunctionEnd
 
128
 
 
129
\S2{uninstcallbacks} Uninstall Callbacks
 
130
 
 
131
\S3{unonguiinit} un.onGUIInit
 
132
 
 
133
This callback will be called just before the first page is loaded and the installer dialog is shown, allowing you to tweak the user interface.
 
134
 
 
135
Have a look at \R{onguiinit}{.onGUIInit} for an example.
 
136
 
 
137
\S3{unonInit} un.onInit
 
138
 
 
139
This callback will be called when the uninstaller is nearly finished initializing. If the 'un.onInit' function calls Abort, the uninstaller will quit instantly. Note that this function can verify and/or modify $INSTDIR if necessary.
 
140
 
 
141
Here are two examples of how this might be used:
 
142
 
 
143
\c   Function un.onInit
 
144
\c     MessageBox MB_YESNO "This will uninstall. Continue?" IDYES NoAbort
 
145
\c       Abort ; causes uninstaller to quit.
 
146
\c     NoAbort:
 
147
\c   FunctionEnd
 
148
 
 
149
or:
 
150
 
 
151
\c   Function un.onInit
 
152
\c     IfFileExists $INSTDIR\myfile.exe found
 
153
\c       Messagebox MB_OK "Uninstall path incorrect"
 
154
\c       Abort
 
155
\c     found:
 
156
\c   FunctionEnd
 
157
 
 
158
\S3{unonuninstfailed} un.onUninstFailed
 
159
 
 
160
This callback is called when the user hits the 'cancel' button after the uninstall has failed (if it used the \R{abort}{Abort command} or otherwise failed).
 
161
 
 
162
Example:
 
163
 
 
164
\c   Function un.onUninstFailed
 
165
\c     MessageBox MB_OK "Better luck next time."
 
166
\c   FunctionEnd
 
167
 
 
168
\S3{unonuninstsuccess} un.onUninstSuccess
 
169
 
 
170
This callback is called when the uninstall was successful, right before the install window closes (which may be after the user clicks 'Close' if \R{setautoclose}{SetAutoClose} is set to false)..
 
171
 
 
172
Example:
 
173
 
 
174
\c   Function un.onUninstSuccess
 
175
\c     MessageBox MB_OK "Congrats, it's gone."
 
176
\c   FunctionEnd
 
177
 
 
178
\S3{unonguiend} un.onGUIEnd
 
179
 
 
180
This callback is called right after the uninstaller window closes. Use it to free any user interface related plug-ins if needed.
 
181
 
 
182
\S3{unonrebootfailed} un.onRebootFailed
 
183
 
 
184
This callback is called if \R{reboot}{Reboot} fails. \R{writeuninstaller}{WriteUninstaller}, \R{plugindlls}{plug-ins}, \R{file}{File} and \R{writeregbin}{WriteRegBin} should not be used in this callback.
 
185
 
 
186
Example:
 
187
 
 
188
\c  Function un.onRebootFailed
 
189
\c    MessageBox MB_OK|MB_ICONSTOP "Reboot failed. Please reboot manually." /SD IDOK
 
190
\c  FunctionEnd
 
191
 
 
192
\S3{unonselchange} un.onSelChange
 
193
 
 
194
Called when the selection changes on the \R{pages}{component page}. Useful for using with \R{sectionsetflags}{SectionSetFlags} and \R{sectiongetflags}{SectionGetFlags}.
 
195
 
 
196
Selection changes include both section selection and installation type change.
 
197
 
 
198
\S3{unonuserabort} un.onUserAbort
 
199
 
 
200
This callback is called when the user hits the 'cancel' button and the uninstall hasn't already failed. If this function calls Abort, the install will not be aborted.
 
201
 
 
202
Example:
 
203
 
 
204
\c   Function un.onUserAbort
 
205
\c     MessageBox MB_YESNO "Abort uninstall?" IDYES NoCancelAbort
 
206
\c       Abort ; causes uninstaller to not quit.
 
207
\c     NoCancelAbort:
200
208
\c   FunctionEnd
 
 
b'\\ No newline at end of file'