Struct tauri_winres::WindowsResource

source ·

pub struct WindowsResource { /* private fields */ }

Implementations§

source §

impl WindowsResource

source

pub fn new() -> Self

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.tauri-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.tauri-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`

source

pub fn set<'a>(&mut self, name: &'a str, value: &'a str) -> &mut Self

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.

source

pub fn set_language(&mut self, language: u16) -> &mut Self

Set the user interface language of the file

Example

fn main() {
  if cfg!(target_os = "windows") {
    let mut res = tauri_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`

source

pub fn set_icon(&mut self, path: &str) -> &mut Self

Add an icon with nameID 32512.

This icon needs to be in ico format. The filename can be absolute or relative to the projects root.

Equivalent to set_icon_with_id(path, "32512").

Windows uses 32512 as the default icon ID. See here for Windows docs demonstrating this.

source

pub fn set_icon_with_id<'a>( &mut self, path: &'a str, name_id: &'a str ) -> &mut Self

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")
   // ...

source

pub fn set_version_info(&mut self, field: VersionInfo, value: u64) -> &mut Self

Set a version info struct property Currently we only support numeric values; you have to look them up.

source

pub fn set_manifest(&mut self, manifest: &str) -> &mut Self

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 = tauri_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>
"#);

source

pub fn set_manifest_file(&mut self, file: &str) -> &mut Self

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()

source

pub fn write_resource_file<P: AsRef<Path>>(&self, path: P) -> Result<()>

Write a resource file with the set values

source

pub fn set_resource_file(&mut self, path: &str) -> &mut Self

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.

source

pub fn append_rc_content(&mut self, content: &str) -> &mut Self

Append an additional snippet to the generated rc file.

Example

Define a menu resource:

    let mut res = tauri_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
}"##);

source

pub fn compile(&self) -> Result<()>

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.

source

pub fn compile_for(&self, binaries: &[&str]) -> Result<()>

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.

source §