Cross XML Resource References

A GacUI XML Resource coulduse some resources in another XML. There are 3 types of resources:

Resource files: They could be accessed usingimport-res://RESOURCE-NAME/...in the-uri binding.
Objects that compiled to Workflow: They could be accessed using their generated class or interface names.
Everything else: They could not be accessed from another XML.

XML Resource Header

To make a GacUI XML Resource be able to depend on or be depended by another resource, a header is required inGacGenConfig/Metadatalike this:

<Resource>
  <Folder name="GacGenConfig">
    <Xml name="Metadata">
      <ResourceMetadata Name="EditorRibbon" Version="1.0">
        <Dependencies>
          <Resource Name="EditorBase"/>
        </Dependencies>
      </ResourceMetadata>
    </Xml>
    ...
  </Folder>
  ...
</Resource>

/ResourceMetadata/@Name: The name of the resource. All resources that loaded into an application should either have a unique name or have no name. If a resource want to depend on or to be depended by another resource, it should have a name.
/ResourceMetadata/@Version: The only legal value is1.0. It is bounded to the GacUI XML Resource Compiler (GacGen.exe). To ensure that all depended resources are compiled using a compatible version of compiler, an resource could only depend on another resource that has exactly the same version.
/ResourceMetadata/Dependencies/Resource/@Name: Here are all resources that the current resource depends on. The name must match their**/ResourceMetadata/@Name**in their metadata.

Compile Resource with Dependencies

GacBuild.ps1is the only tool to properly compile resources with dependencies.

You need to have a file calledGacUI.xml:

<GacUI/>

A GacUI XML Resource and all its dependeices must be put inside the folder containingGacUI.xml. Resource files could be put in any level of sub folders.

Then you could callGacBuild.ps1 -FileName path/to/GacUI.xmlinPowerShell. All resource files in the folder containingGacUI.xmlwill be found and compiled in the dependency order.

GacBuild.ps1forces incremental build. If a resource is not changed, and all its dependencies are not changed, then the resource will not be compiled again. You could useGacClear.ps1 -FileName path/to/GacUI.xmlto clear all cache, the next timeGacBuild.ps1will recompile every resource files.

Generated resource binaries, workflow binaries and C++ code will be put in placesspecified in each GacUI XML Resource.

Loading Resource Dependencies in your C++ Application

**vl::presentation::GetResourceManager()->LoadResourceOrPending(fileStream[, errors][, usage]);**is the only function to load compiled resource binaries:

fileStream: It could be anyvl::stream::IStream, you could useFileStreamhere to load a resource from file.
errors: If the resource could not be loaded, errors will be stored in this list. An empty error list after calling this function means the resource is loaded properly. If theerrorsargument is not use, then the function will crash if there is any error.
usage: It could beInstanceClassif you include all Workflow binaries into this resource file, andDataOnlyif not. A resource binary containing Workflow binaries could be produced usingres://GacGenCppConfig/ResX86/Resource and res://GacGenCppConfig/ResX/ResourceThe content of Workflow binaries is different for x86 or x64, you need to load the correct one.Typically, if you use compiled resource with generated C++ files instead of Workflow binaries, you only need the first argument.

You don't need to worry about the order to load resource files, they will be taken care of in this function, just callLoadResourceOrPendingfor all of them.

CallingLoadResourceOrPendingwithout all depended resources prepared results in delay loading. Such resource will be automatically loaded after all depended resources are loaded. You could callGetResourceto see if a resource has already been loaded or not. If it returnsnullbutLoadResourceOrPendingsucceeded, it means some depended resources are not prepared yet, and the loading is delayed.

Get Rid of Resource Files

By usingCppResource or CppCompressedinres://GacGenConfig/Cpp, you will get multiple cpp files for each GacUI XML Resource. Link all these cpp files to your project, resource binaries will be compiled into your executable file. When your application starts, all resources will be properly loaded beforeGuiMain.

Using Resource in Dependedcies

If there is a resource objectres://path/to/the/resourcein a GacUI XML Resource calledBaseResource, another GacUI XML Resource depending on it could useimport-res://BaseResource/path/to/the/resource. Such resource path could be use in**-uri binding**, or in theResolveResourcemethod in allroot UI instance.

If a resource is compiled to Workflow classes or instances, just use the class or interface names directly. But if the resource is not in the dependency list (/ResourceMetadata/Dependencies/Resource/@Name), the class or interface name will not be found when runningGacBuild.ps1, errors will be generated and the resource cannot be compiled.

5.4 KiB Raw Blame History