public interface AutoChildUsage

Using AutoChildren

An AutoChild is an automatically generated subcomponent that a parent component creates to handle part of its presentation or functionality. An example is the Window component and its subcomponent the header.

AutoChildren support four standard configuration mechanisms that can be used to customize or skin them. Note, however, that configuring AutoChildren in Smart GWT is advanced usage.

To determine which AutoChildren exist for a particular component type, search the class' Javadocs for "AutoChild" as there is a getter for each AutoChild that is supported. In the case of a MultiAutoChild, the getter is non-functional (always returns null) and exists only to make you aware that the MultiAutoChild exists.

The four different ways to configure AutoChildren in Smart GWT are:

Visibility

Controls whether the AutoChild should be created and shown at all. The Canvas.setAutoChildVisibility(String, boolean) or FormItem.setAutoChildVisibility(String, boolean) API as appropriate is used to change this property for the named AutoChild.

Properties

Properties to apply to the AutoChild created by a particular instance of the parent component. In the case of a MultiAutoChild, the properties are applied to each instance created by the parent.

To change the properties of an AutoChild of a widget, the Canvas.setAutoChildProperties(String, com.smartgwt.client.widgets.Canvas) or Canvas.setAutoChildProperties(String, FormItem) API is used. To change the properties of an AutoChild of a form item, the FormItem.setAutoChildProperties(String, com.smartgwt.client.widgets.Canvas) or FormItem.setAutoChildProperties(String, FormItem) API is used. For example:

         final Window myWindow = new Window();
         final Layout headerProperties = new Layout();
         headerProperties.setLayoutMargin(10);
         myWindow.setAutoChildProperties("header", headerProperties);
  

The above applies a layoutMargin of 10 to the header of myWindow, increasing the empty space around the subcomponents of the header (buttons, title label, etc).

Do not use the Properties mechanism for skinning. See Defaults next.

Defaults

Defaults that will be applied to the AutoChild created by any instance of the parent class. Changing the defaults is used for skinning. The changeAutoChildDefaults() static method of the target Smart GWT class is used to change the defaults for all instances of the class. For example, to change the Window.header defaults, the Window.changeAutoChildDefaults(String, com.smartgwt.client.widgets.Canvas) API is used passing "header" for the autoChildName.

changeAutoChildDefaults() must be called before any components are created, and will generally be the first thing in your module's onModuleLoad() function. Alternatively, you can use the JavaScript equivalent Class.changeDefaults() inside of a load_skin.js file - see Skinning AutoChildren below.

Constructor

SmartClient Class of the component to be created. An advanced option, the AutoChild constructor should generally only be changed when there is documentation encouraging you to do so. For example, ListGrid offers the ability to use simple CSS-based headers or more complex StretchImg headers via listGridInstance.setAutoChildConstructor("headerButton", "StretchImg"). To change the constructor of AutoChildren, the Canvas.setAutoChildConstructor(String, String) or FormItem.setAutoChildConstructor(String, String) API is used.

In order for any class to be referenced within a constructor you must register the class for reflection, and use the fully qualified name of the target class. See Reflection for details.

For some drastic customizations of an AutoChild where the constructor is changed, the signature of the get[AutoChild]() method may have too specific a return type and the Canvas.getCanvasAutoChild(String), Canvas.getFormItemAutoChild(String), FormItem.getCanvasAutoChild(String), or FormItem.getFormItemAutoChild(String) API as appropriate would need to be used instead to retrieve the AutoChild instance.

NOTE: When setting Properties or Defaults in Smart GWT, attributes and event handlers can be set, but override points are not supported.

The AutoChild system can be used to create both direct children and indirect children (children of children). For example, the minimizeButton of the Window is also an autoChild, even though it is actually located within the window header.

Skinning AutoChildren

Skinning AutoChildren by changing the AutoChild defaults is typically done for two purposes:

• Changing the default appearance or behavior of a component, for example, making all Window headers shorter
• Creating a customized variation of an existing component while retaining the base component unchanged. For example, creating a subclass of Window called "PaletteWindow" with a very compact appearance, while leaving the base Window class unchanged so that warning dialogs and other core uses of Windows do not look like PaletteWindows.

The best code examples for skinning are in the load_skin.js file for the "SmartClient" skin, in isomorphic/skins/SmartClient/load_skin.js.

Passthroughs (eg window.headerStyle)

In many cases a component will provide shortcuts to skinning or customizing its AutoChildren, such as Window.headerStyle, which becomes header.styleName. When these shortcuts exist, they must be used instead of the more general AutoChild skinning system.

Safe Skinning

Before skinning an AutoChild consider the safe skinning guidelines.

Accessing AutoChildren Dynamically

For a component "Window" with an AutoChild named "header", if you create a Window called myWindow, the header AutoChild is available via myWindow.getHeader().

Unless documented otherwise, an AutoChild should be considered an internal part of a component. Always configure AutoChildren by APIs on the parent component when they exist. It makes sense to access an AutoChild for troubleshooting purposes or for workarounds, but in general, an AutoChild's type, behavior, and internal structure are subject to change without notice in future Smart GWT versions.

Accessing an AutoChild may give you a way to make a dynamic change to a component that is not otherwise supported by the parent component (for example, changing a text label where there is no setter on the parent). Before using this approach, consider whether simply recreating the parent component from scratch is a viable option. This approach is more than fast enough for most smaller components, and will not create a reliance on unsupported APIs.

Multi-AutoChildren

In some cases, rather than creating a single named autoChild, such as a Window header, a component will use the autoChild pattern to create an arbitrary number of children with common appearance and behavior. An example of this is the TileGrid which creates multiple tiles. In this paradigm, each automatically generated child will pick up the appropriate constructor, properties and defaults from the documented auto child name but will not be available as creator.[autoChildName] after creation and setting showAutoChildName will typically have no effect.