Class TCastleComponentFactory

Main constructor. Does not load anything immediately. Set Url or call LoadFromStream to load component.

Warning: this symbol is deprecated: use Create(AOwner) overload, then set Url to load

Avoid Delphi warnings about constructor hiding. In the long-run, these deprecated constructors should be removed, once everyone got chance to migrate.

Warning: this symbol is deprecated: use Create(AOwner) overload, then LoadFromStream

This item has no description.

This item has no description.

Load design from given TStream.

If you set up localization (see https://castle-engine.io/manual_text.php#section_localization_gettext ), then upon loading, the design will be automatically localized using the translation group specified. Just leave ATranslationGroupName = '' to not localize.

This Url value is unchanged by this. In most common case, you don't really care about the Url value of this component, if you load the contents from TStream.

Load given component as a template. Effectively every TCastleComponentFactory.ComponentLoad will create a deep clone of Template.

This is a way to clone ("deep copy") any TComponent using serialization + deserialization underneath. Template is converted to the JSON classes (though not JSON string) and then deserialized back to a new component. It is not the most efficient way to clone (since the intermeiate JSON representation is created; though note that we don't save / parse JSON as a string). But it is absolutely general and works out-of-the-box on any TComponent, just like our serialization/deserialization.

Instantiate component. Using this is similar to using global CastleComponentSerialize.ComponentLoad, but it is much faster if you want to instantiate the same file many times.

Newly created component will be owned by InstanceOwner (it can be Nil, in which case you have to free it manually). Do not confuse this with the owner of this TCastleComponentFactory – which may be the same or different component.

If AssociateReferences is not Nil, then published fields within AssociateReferences that match the names of components within the loaded design will be set.

The InstanceOwner is useful for 2 things:

1. To manage memory (freeing the InstanceOwner will also free the loaded component).

2. And to search for named components. All the loaded components are owned by InstanceOwner and you can query for them using InstanceOwner.FindComponent or InstanceOwner.FindRequiredComponent.

   Note that loaded components are renamed, if necessary, to be unique within InstanceOwner — this is important if your InstanceOwner owns other things as well. If you want to reliably search for names, make sure to use different InstanceOwner for each load. Or use AssociateReferences instead.

For example, this example creates an owner dedicated for refering to names in the given instance of a Rock:

procedure SpawnRock;
var
  RockOwner: TComponent;
  Rock: TCastleTransform;
  RockRigidBody: TCastleRigidBody;
  SceneToRotate: TCastleTransform;
begin
  RockOwner := TComponent.Create(Self);
  Rock := RockFactory.ComponentLoad(RockOwner) as TCastleTransform;
  RockRigidBody := RockOwner.FindRequiredComponent('RockRigidBody') as TCastleRigidBody;
  SceneToRotate := RockOwner.FindRequiredComponent('SceneToRotate') as TCastleTransform;
  // here use RockRigidBody, SceneToRotate
end;

The AssociateReferences is useful to connect, at load time, the names of components within the loaded design to published fields inside AssociateReferences. Compared to using InstanceOwner.FindComponent or InstanceOwner.FindRequiredComponent for the same purpose:

• It is simpler to use, because you don't need to manage the InstanceOwner lifetime.

  This matters in case you created InstanceOwner only for the purpose of loading the given design.

  The AssociateReferences instance can be freed immediately after the load, and it will not affect the loaded components. Or you can keep it existing for a longer time, and reuse for loading all components – it will not mess anything, as loaded components are not renamed to be unique within it.

• Associates the original component names, regardless of whether they later required renaming to be unique within InstanceOwner.

  This matters in case your InstanceOwner owns many other things.

• Note also one disadvantage of AssociateReferences: It doesn't check that field type matches. If a field name has a typo, it will be just left Nil, causing "Access Violation" if you try to access it.

For example:

type
  TRockDesign = class(TPersistent)
  published
    SceneToRotate: TCastleTransform;
    RockRigidBody: TCastleRigidBody;
  end;

procedure SpawnRock;
var
  Rock: TCastleTransform;
  RockDesign: TRockDesign;
begin
  RockDesign := TRockDesign.Create;
  try
    Rock := RockFactory.ComponentLoad(Self, RockDesign) as TCastleTransform;
    // here use RockDesign.RockRigidBody, RockDesign.SceneToRotate
  finally FreeAndNil(RockDesign) end;
end;

Load design from given URL. Set to '' to clear the loaded component.

If you set up localization (see https://castle-engine.io/manual_text.php#section_localization_gettext ), then upon loading, the design will be automatically localized using the translation group derived from URL base name. E.g. loading "castle-data:/foo/my_design.castle-user-interface" will use translation group "my_design".