Struct winres::WindowsResource [−][src]
pub struct WindowsResource { /* fields omitted */ }
Implementations
Create a new resource with version info struct
We initialize the resource file with values provided by cargo
Field | Cargo / Values |
---|---|
"FileVersion" | package.version |
"ProductVersion" | package.version |
"ProductName" | package.name |
"FileDescription" | package.description |
Furthermore if a section package.metadata.winres
exists
in Cargo.toml
it will be parsed. Values in this section take precedence
over the values provided natively by cargo. Only the string table
of the version struct can be set this way.
Additionally, the language field is set to neutral (i.e. 0
)
and no icon is set. These settings have to be done programmatically.
Cargo.toml
files have to be written in UTF-8, so we support all valid UTF-8 strings
provided.
#Cargo.toml
[package.metadata.winres]
OriginalFilename = "testing.exe"
FileDescription = "⛄❤☕"
LegalCopyright = "Copyright © 2016"
The version info struct is set to some values sensible for creating an executable file.
Property | Cargo / Values |
---|---|
FILEVERSION | package.version |
PRODUCTVERSION | package.version |
FILEOS | VOS_NT_WINDOWS32 (0x40004) |
FILETYPE | VFT_APP (0x1) |
FILESUBTYPE | VFT2_UNKNOWN (0x0) |
FILEFLAGSMASK | VS_FFI_FILEFLAGSMASK (0x3F) |
FILEFLAGS | 0x0 |
Set string properties of the version info struct.
Possible field names are:
"FileVersion"
"FileDescription"
"ProductVersion"
"ProductName"
"OriginalFilename"
"LegalCopyright"
"LegalTrademark"
"CompanyName"
"Comments"
"InternalName"
Additionally there exists
"PrivateBuild"
, "SpecialBuild"
which should only be set, when the FILEFLAGS
property is set to
VS_FF_PRIVATEBUILD(0x08)
or VS_FF_SPECIALBUILD(0x20)
It is possible to use arbirtrary field names but Windows Explorer and other tools might not show them.
Set the correct path for the toolkit.
For the GNU toolkit this has to be the path where MinGW
put windres.exe
and ar.exe
. This could be something like:
"C:\Program Files\mingw-w64\x86_64-5.3.0-win32-seh-rt_v4-rev0\mingw64\bin"
For MSVC the Windows SDK has to be installed. It comes with the resource compiler
rc.exe
. This should be set to the root directory of the Windows SDK, e.g.,
"C:\Program Files (x86)\Windows Kits\10"
or, if multiple 10 versions are installed,
set it directly to the corret bin directory
"C:\Program Files (x86)\Windows Kits\10\bin\10.0.14393.0\x64"
If it is left unset, it will look up a path in the registry,
i.e. HKLM\SOFTWARE\Microsoft\Windows Kits\Installed Roots
Set the user interface language of the file
Example
extern crate winapi;
extern crate winres;
fn main() {
if cfg!(target_os = "windows") {
let mut res = winres::WindowsResource::new();
res.set_language(winapi::um::winnt::MAKELANGID(
winapi::um::winnt::LANG_ENGLISH,
winapi::um::winnt::SUBLANG_ENGLISH_US
));
res.compile().unwrap();
}
}
For possible values look at the winapi::um::winnt
constants, specifically those
starting with LANG_
and SUBLANG_
.
Table
Sometimes it is just simpler to specify the numeric constant directly
(That is what most .rc
files do).
For possible values take a look at the MSDN page for resource files;
we only listed some values here.
Language | Value |
---|---|
Neutral | 0x0000 |
English | 0x0009 |
English (US) | 0x0409 |
English (GB) | 0x0809 |
German | 0x0407 |
German (AT) | 0x0c07 |
French | 0x000c |
French (FR) | 0x040c |
Catalan | 0x0003 |
Basque | 0x042d |
Breton | 0x007e |
Scottish Gaelic | 0x0091 |
Romansch | 0x0017 |
Add an icon with nameID 1
.
This icon need to be in ico
format. The filename can be absolute
or relative to the projects root.
Equivalent to set_icon_with_id(path, "1")
.
Add an icon with the specified name ID.
This icon need to be in ico
format. The path can be absolute or
relative to the projects root.
Name ID and Icon Loading
The name ID can be (the string representation of) a 16-bit unsigned integer, or some other string.
You should not add multiple icons with the same name ID. It will result in a build failure.
When the name ID is an integer, the icon can be loaded at runtime with
LoadIconW(h_instance, MAKEINTRESOURCEW(name_id_as_integer))
Otherwise, it can be loaded with
LoadIconW(h_instance, name_id_as_wide_c_str_as_ptr)
Where h_instance
is the module handle of the current executable
(GetModuleHandleW
(null())
),
LoadIconW
and
MAKEINTRESOURCEW
are defined in winapi.
Multiple Icons, Which One is Application Icon?
When you have multiple icons, it’s a bit complicated which one will be chosen as the application icon: https://docs.microsoft.com/en-us/previous-versions/ms997538(v=msdn.10)?redirectedfrom=MSDN#choosing-an-icon.
To keep things simple, we recommand you use only 16-bit unsigned integer name IDs, and add the application icon first with the lowest id:
res.set_icon("icon.ico") // This is application icon.
.set_icon_with_id("icon2.icon", "2")
.set_icon_with_id("icon3.icon", "3")
// ...
Set a version info struct property Currently we only support numeric values; you have to look them up.
Set the embedded manifest file
Example
The following manifest will brand the exe as requesting administrator privileges. Thus, everytime it is executed, a Windows UAC dialog will appear.
let mut res = winres::WindowsResource::new();
res.set_manifest(r#"
<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
<trustInfo xmlns="urn:schemas-microsoft-com:asm.v3">
<security>
<requestedPrivileges>
<requestedExecutionLevel level="requireAdministrator" uiAccess="false" />
</requestedPrivileges>
</security>
</trustInfo>
</assembly>
"#);
Some as set_manifest()
but a filename can be provided and
file is included by the resource compieler itself.
This method works the same way as set_icon()
Set the path to the windres executable.
Set the path to the ar executable.
Set the path to the ar executable.
Write a resource file with the set values
Set a path to an already existing resource file.
We will neither modify this file nor parse its contents. This function simply replaces the internaly generated resource file that is passed to the compiler. You can use this function to write a resource file yourself.
Append an additional snippet to the generated rc file.
Example
Define a menu resource:
let mut res = winres::WindowsResource::new();
res.append_rc_content(r##"sample MENU
{
MENUITEM "&Soup", 100
MENUITEM "S&alad", 101
POPUP "&Entree"
{
MENUITEM "&Fish", 200
MENUITEM "&Chicken", 201, CHECKED
POPUP "&Beef"
{
MENUITEM "&Steak", 301
MENUITEM "&Prime Rib", 302
}
}
MENUITEM "&Dessert", 103
}"##);
Override the output directoy.
As a default, we use %OUT_DIR%
set by cargo, but it may be necessary to override the
the setting.
Run the resource compiler
This function generates a resource file from the settings or uses an existing resource file and passes it to the resource compiler of your toolkit.
Further more we will print the correct statements for
cargo:rustc-link-lib=
and cargo:rustc-link-search
on the console,
so that the cargo build script can link the compiled resource file.