com.smartgwt.client.docs

## Interface AutoChildUsage

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