NfUtils header file: Difference between revisions
No edit summary |
No edit summary |
||
| Line 21: | Line 21: | ||
== Description == | == Description == | ||
nfUtils is a collection of macros and functions in a NSIS header file. | nfUtils is a collection of macros and functions in a NSIS header file, intended to ease the development and usage of new functions and macros for your own header files. | ||
== How to use == | == How to use == | ||
| Line 31: | Line 31: | ||
nfgetver.exe (utility used by nfUtils.nsh)<br><br> | nfgetver.exe (utility used by nfUtils.nsh)<br><br> | ||
Basically you will only need nfUtils.nsh in the include directory of your NSIS installation: nfgetver.exe will be generated, when | Basically you will only need nfUtils.nsh in the include directory of your NSIS installation: nfgetver.exe will be generated by nfUtils.nsh, when nfgetver is needed and unavailable. The installer's script is provided for learning purposes, because it will show the usage of some macros and functions.<br> | ||
To use the header, place this at the beginning of your script: | To use the header, place this at the beginning of your script: | ||
| Line 38: | Line 38: | ||
!include "nfUtils.nsh" | !include "nfUtils.nsh" | ||
</highlight-nsis> | </highlight-nsis> | ||
== First steps == | |||
Descriptions for nfUtils' macros and functions can be obtained by adding the instruction | Descriptions for nfUtils' macros and functions can be obtained by adding the instruction | ||
| Line 57: | Line 59: | ||
</highlight-nsis> | </highlight-nsis> | ||
will output the description, which has been provided for the macro "!InstallMacro" (prefixed by "nfu."). It goes without saying that you may (and should) use this little helpsystem for your own macros and functions. But {$nfu.!Help} is only a by-product of the more important macros {$nfu.!InstallFunction} and {$nfu.!InstallMacro}. | will output the description, which has been provided for the macro "!InstallMacro" (prefixed by "nfu."). It goes without saying that you may (and should) use this little helpsystem for your own macros and functions (avoid using the prefix "nfu." for your code or you might loose compatibility with future versions of nfUtils). But {$nfu.!Help} is only a by-product of the more important macros {$nfu.!InstallFunction} and {$nfu.!InstallMacro}. In the following you will find the descriptions of all macros and functions provided by the current release of nfUtils. | ||
== nfu.!AddFile == | |||
Usage: ${nfu.!AddFile} FileOptions OutFolder<br><br> | |||
Description: You will need this macro only when using "nfu.ProcessStdSwitches". It will record the 'FileOptions' with a prepended FILE-instruction for later insertion into the hidden section, which will be created by adding ProcessStdSwitches to the script via !AddFunction.<br> | |||
Using !AddFile after "${nfu.!AddFunction} nfu.ProcessStdSwitches", will be | |||
ignored.<br> | |||
The parameter Outfolder will instruct ProcessStdSwitches to extract the file(s) | |||
to the specified subfolder within the destinationfolder the user has selected. | |||
When using '/ICON' as 'FileOptions', !AddFile will prepare the inclusion of the | |||
icon, which will be set by SetInstallerName or SetStdAttributes. '/ICON' will use | |||
a default outfolder when you specify "" for the parameter 'Outfolder'. Non-empty | |||
values will change the defaults. | |||
== nfu.!AddFunction == | |||
Usage: ${nfu.!AddFunction} FunctionName<br><br> | |||
Description: Adds the code for the function FunctionName to the script. The function must have been installed with the supportmacro "InstallFunction". See "nfu.!InstallFunction" for further information. | |||
== nfu.!Append == | |||
Usage: ${nfu.!Append} SymbolName Value<br><br> | |||
Description: Appends Value to SymbolName's value. SymbolName does not need to be defined. | |||
== nfu.!AppendIf == | |||
Usage: ${nfu.!AppendIf} Condition SymbolName Value<br><br> | |||
Description: Appends Value to SymbolName's value if !IF'Condition' is met. SymbolName does not need to be defined. | |||
== nfu.!Calculate == | |||
Usage: ${nfu.!Calculate} SymbolName Op Value<br><br> | |||
Description: SymbolName := SymbolName Op Value, where Op may be +,-,*,/ or %. SymbolName and Value must represent integers. SymbolName does not need to be defined - it will be initialized to 0, if undefined. | |||
== nfu.!Compare == | |||
Usage: ${nfu.!Compare} ResultSymbol Value1 Value2<br><br> | |||
Description: This macro will do a case-insensitive string comparison of 'Value1' and 'Value2' and sets 'ResultSymbol' to "1" on equality. The symbol does not need to be defined. | |||
== nfu.!Exchange == | |||
Usage: ${nfu.!Exchange} SymbolName1 SymbolName2<br><br> | |||
Description: Exchanges the values of both symbols. None of the symbols need to be defined. | |||
== nfu.!FileVersion == | |||
Usage: ${nfu.!FileVersion} SymbolName Filename<br><br> | |||
Description: Redefines the symbol 'SymbolName' with the fileversion of 'FileName'. | |||
SymbolName does not need to be defined. If the file does not exist or has no | |||
version information, then the symbol's value will be empty. | |||
== nfu.!FreeFile == | |||
Usage: ${nfu.!FreeFile}<br><br> | |||
Description: Deletes the last temporary file created by "${nfu.!MakeFile}". | |||
== nfu.!FreeSymbol == | |||
Usage: ${nfu.!FreeSymbol}<br><br> | |||
Description: !UNDEFines the last symbol created by "${nfu.!MakeSymbol}". | |||
== nfu.Function == | |||
Usage: ${nfu.Function} FunctionName io1 v1 io2 v2 io3 v3 io4 v4 io5 v5 io6 v6 io7 v7 io8 v8 io9 v9 io10 v10<br><br> | |||
Description: This macro will add "Function FunctionName" to your script, followed by the code to load parameters from the stack into the variables 'v*' (usually $0-$9, $R0-$R9, but $VARs should also work) you have specified in the parameterlist of the macro. 'io*' must be specified with 'in' or 'out', depending on which variable you need to hold an input parameter on entry of the function or which one is planned to hold a resultvalue on the end of the function. Leave unused pairs of (io/v) empty ('' '').<br> | |||
The macro expects that the first input parameter (the leftmost Vn with IOn='in') has been pushed first onto the stack before the functioncall, and will prepare the results, so that the first output parameter has to be the first one, which has to be popped off the stack after return from the function: this order will be established by "${nfu.!InstallFunction}" to prepare the call of a function. See also "${nfu.FunctionEnd}". | |||
== nfu.FunctionEnd == | |||
Usage: ${nfu.FunctionEnd}<br><br> | |||
Description: Inserts the code prepared by "${nfu.Function}" to put the results onto the stack and to recover the values of the variables, which have been used for the input parameters. The macro closes your functionbody with a "FunctionEnd". | |||
== nfu.!Help == | |||
== nfu.HideBackButton == | |||
== nfu.HideCancelButton == | |||
== nfu.!IncludeFileIf == | |||
== nfu.!IncludeTextIfExist == | |||
== nfu.!InstallDescription == | |||
== nfu.!InstallFunction == | |||
== nfu.!InstallMacro == | |||
== nfu.!MakeFile == | |||
== nfu.!MakeSymbol == | |||
== nfu.!Redefine == | |||
== nfu.!Replace == | |||
== nfu.SetInstallerName == | |||
== nfu.SetStdAttributes == | |||
== nfu.SetVersionInfo == | |||
== nfu.SkipPageOnSrcExtract == | |||
== nfu.SkipSectionOnSrcExtract == | |||
== nfu.!Undefine == | |||
== nfu.GetAppPath == | |||
== nfu.UnGetAppPath == | |||
== nfu.GetParameter == | |||
== nfu.UnGetParameter == | |||
== nfu.ProcessStdSwitches == | |||
== nfu.UnProcessStdSwitches == | |||
== nfu.myName == | |||
== nfu.myVersion == | |||
== nfu.StdLicense == | |||
[[Category:Headers]] | [[Category:Headers]] | ||
Revision as of 12:59, 20 July 2006
| Author: niteflyer (talk, contrib) |
Links
Go to Forum thread
Download current version:
Version 1.2.0.0 (07-11-2006): 
nfUtils12.zip
Download older versions:
Version 1.1.0.0 (06-30-2006):
nfUtils11.zip
Version 1.0.0.0 (06-03-2006): nfUtils.zip
Description
nfUtils is a collection of macros and functions in a NSIS header file, intended to ease the development and usage of new functions and macros for your own header files.
How to use
Download the zipped installer for the current version of nfUtils, unzip and start the installer nfUtils.exe. The installer will add the following files to your NSIS installation:
nfUtils.nsh (the header file)
nfUtils.nsi (the installer script)
nfUtils.exe (the installer)
nfgetver.exe (utility used by nfUtils.nsh)
Basically you will only need nfUtils.nsh in the include directory of your NSIS installation: nfgetver.exe will be generated by nfUtils.nsh, when nfgetver is needed and unavailable. The installer's script is provided for learning purposes, because it will show the usage of some macros and functions.
To use the header, place this at the beginning of your script:
!include "nfUtils.nsh"
First steps
Descriptions for nfUtils' macros and functions can be obtained by adding the instruction
{$nfu.!Help} ?
to your script. This help is implemented by using symbols (NSIS' gflags) for the descriptive text. Because there is a limitation of 64kB per symbolvalue, nfUtils groups its help into sections, which are identified by prefixes. Currently there are two groups (sectionprefixes): "" (none) and "nfu." (for nfUtils' macros and functions). Thus, the instruction
{$nfu.!Help} nfu.
will give you an index of all descriptions, which have been installed with the prefix "nfu.", by using one of the macros {$nfu.!InstallMacro}, {$nfu.!InstallFunction} or {$nfu.!InstallDescription}. Finally, the instruction
{$nfu.!Help} "nfu.!InstallMacro"
will output the description, which has been provided for the macro "!InstallMacro" (prefixed by "nfu."). It goes without saying that you may (and should) use this little helpsystem for your own macros and functions (avoid using the prefix "nfu." for your code or you might loose compatibility with future versions of nfUtils). But {$nfu.!Help} is only a by-product of the more important macros {$nfu.!InstallFunction} and {$nfu.!InstallMacro}. In the following you will find the descriptions of all macros and functions provided by the current release of nfUtils.
nfu.!AddFile
Usage: ${nfu.!AddFile} FileOptions OutFolder
Description: You will need this macro only when using "nfu.ProcessStdSwitches". It will record the 'FileOptions' with a prepended FILE-instruction for later insertion into the hidden section, which will be created by adding ProcessStdSwitches to the script via !AddFunction.
Using !AddFile after "${nfu.!AddFunction} nfu.ProcessStdSwitches", will be
ignored.
The parameter Outfolder will instruct ProcessStdSwitches to extract the file(s)
to the specified subfolder within the destinationfolder the user has selected.
When using '/ICON' as 'FileOptions', !AddFile will prepare the inclusion of the
icon, which will be set by SetInstallerName or SetStdAttributes. '/ICON' will use
a default outfolder when you specify "" for the parameter 'Outfolder'. Non-empty
values will change the defaults.
nfu.!AddFunction
Usage: ${nfu.!AddFunction} FunctionName
Description: Adds the code for the function FunctionName to the script. The function must have been installed with the supportmacro "InstallFunction". See "nfu.!InstallFunction" for further information.
nfu.!Append
Usage: ${nfu.!Append} SymbolName Value
Description: Appends Value to SymbolName's value. SymbolName does not need to be defined.
nfu.!AppendIf
Usage: ${nfu.!AppendIf} Condition SymbolName Value
Description: Appends Value to SymbolName's value if !IF'Condition' is met. SymbolName does not need to be defined.
nfu.!Calculate
Usage: ${nfu.!Calculate} SymbolName Op Value
Description: SymbolName := SymbolName Op Value, where Op may be +,-,*,/ or %. SymbolName and Value must represent integers. SymbolName does not need to be defined - it will be initialized to 0, if undefined.
nfu.!Compare
Usage: ${nfu.!Compare} ResultSymbol Value1 Value2
Description: This macro will do a case-insensitive string comparison of 'Value1' and 'Value2' and sets 'ResultSymbol' to "1" on equality. The symbol does not need to be defined.
nfu.!Exchange
Usage: ${nfu.!Exchange} SymbolName1 SymbolName2
Description: Exchanges the values of both symbols. None of the symbols need to be defined.
nfu.!FileVersion
Usage: ${nfu.!FileVersion} SymbolName Filename
Description: Redefines the symbol 'SymbolName' with the fileversion of 'FileName'.
SymbolName does not need to be defined. If the file does not exist or has no
version information, then the symbol's value will be empty.
nfu.!FreeFile
Usage: ${nfu.!FreeFile}
Description: Deletes the last temporary file created by "${nfu.!MakeFile}".
nfu.!FreeSymbol
Usage: ${nfu.!FreeSymbol}
Description: !UNDEFines the last symbol created by "${nfu.!MakeSymbol}".
nfu.Function
Usage: ${nfu.Function} FunctionName io1 v1 io2 v2 io3 v3 io4 v4 io5 v5 io6 v6 io7 v7 io8 v8 io9 v9 io10 v10
Description: This macro will add "Function FunctionName" to your script, followed by the code to load parameters from the stack into the variables 'v*' (usually $0-$9, $R0-$R9, but $VARs should also work) you have specified in the parameterlist of the macro. 'io*' must be specified with 'in' or 'out', depending on which variable you need to hold an input parameter on entry of the function or which one is planned to hold a resultvalue on the end of the function. Leave unused pairs of (io/v) empty ( ).
The macro expects that the first input parameter (the leftmost Vn with IOn='in') has been pushed first onto the stack before the functioncall, and will prepare the results, so that the first output parameter has to be the first one, which has to be popped off the stack after return from the function: this order will be established by "${nfu.!InstallFunction}" to prepare the call of a function. See also "${nfu.FunctionEnd}".
nfu.FunctionEnd
Usage: ${nfu.FunctionEnd}
Description: Inserts the code prepared by "${nfu.Function}" to put the results onto the stack and to recover the values of the variables, which have been used for the input parameters. The macro closes your functionbody with a "FunctionEnd".
