Upgrading to Castle Game Engine 6.6

Michalis Kamburelis edited this page Nov 25, 2018 · 8 revisions

A number of big changes happened to our user-interface classes, rooted in TCastleUserInterface class (previously called TUIControl). As always, in most cases we are backward-compatible and old code will still work (eventually emitting compiler messages that advise to use new naming, e.g. if you use TUIControl or TUIControlRect then you will get a message to instead just use TCastleUserInterface).

But in some cases you will have to adjust your code:

  • The default TCastleLabel color is now Black, not White. This compatibility break seemed unavoidable, unfortunately our UI controls were inconsistent -- most assumed a modern "black colors over white background scheme" (TCastleEdit, TCastleRectangleControl, TCastleCheckbox...), but TCastleLabel was by default white. So it e.g. was invisible over default TCastleRectangleControl.

    If you depended that the label is by default white, then now simply adjust your code to always set MyLabel.Color := White after creating MyLabel := TCastleLabel.Create(...). Alternatively, temporarily, you can set Theme.DefaultLabelWhite := true at the initialization of your game. (But beware that Theme.DefaultLabelWhite is only a temporary compatibility crutch. It doesn't play nicely with designs created in CGE editor, since the (de)serialization will still assume that by default label has white color.)

  • The default TCastleSceneManager.BackgroundColor is now very dark gray Vector4(0.1, 0.1, 0.1, 1), instead of pure black Vector4(0, 0, 0, 1). This makes a better default, as pure black things (3D / 2D models, or user interface, like labels) are still visible over this background (as well as pure white things).

    If you'd like to restore the old default, just set MySceneManager.BackgroundColor := Black after creating any TCastleSceneManager instance. If you use TCastleWindow or TCastleControl or TCastle2DControl, they contain a default scene manager. You trivially modify it's properties by e.g. Window.SceneManager.BackgroundColor := Black.

    Note that this doesn't matter if you use Background node to specify a background color (or skybox textures) in X3D. It also doesn't matter if your scene manager is transparent (TCastleSceneManager.Transparent is true). In these cases, scene manager BackgroundColor doesn't matter.

  • The user interface coordinates (all positions, sizes) are float-based now. See this post for details. In some cases, you may need to adjust your code. For example if you do SomeIntValue := MyOtherControl.Width div 2;, now you will have to change it to SomeFloatValue := MyOtherControl.Width / 2;.

  • The interpretation of FullSize is now consistent across all TCastleUserInterface ancestors. It always overrides the control to fill the parent, even for TCastleButton, even for TCastleImageControl with TCastleImageControl.Stretch=false value.

    Also, changing Left/Bottom properties doesn't matter when you use FullSize. Previously, it was possible to use FullSize to have a rectangle with the same size as parent, but still move it using Left/Bottom properties. It is no longer possible: FullSize always means fill the parent, so the rendered area of the control covers the parent. You can use WidthFraction := 1; HeightFraction := 1; to set size equal to the parent, but control the position as you like.

  • TCastleImageControl.ProportionalScaling values psFit and psEnclose work a bit differently.

    Previously, they placed the scaled image in the middle of the rectangle determined by Left,Bottom,Width,Height. Now, auto-sizing changes size, but the content keeps at the same left-bottom corner. So the scaled image's left-bottom corner is always at the position indicated by Left,Bottom properties.

    To center image, just use MyImageControl.Anchor(hpMiddle); MyImageControl.Anchor(vpMiddle);.

    This is consistent with other UI controls.

  • Anchors are always on now. The ability to turn them on / off in previous CGE versions was more confusing than helpful, and it was also useless.

    Previously you could deactivate anchor by setting HasHorizontalAnchor to false (in fact, it was false by default). Now, you should achieve the same effect by calling Anchor(hpLeft); (which is also the default state). This aligns left control border to left parent border with 0 delta, which has the same effect as "no anchor".

  • Some components are no longer registered on the component palette. To bring them back (e.g. to open LFM files that refer to these components), you can define {$I CASTLE_REGISTER_ALL_COMPONENTS_IN_LAZARUS} to the src/castleconf.inc file. See this commit log for reasons.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.