Package com.smartgwt.client.widgets.tile

Class TileLayout

java.lang.Object
com.google.gwt.user.client.ui.UIObject
com.google.gwt.user.client.ui.Widget
com.smartgwt.client.widgets.BaseWidget
com.smartgwt.client.widgets.Canvas
com.smartgwt.client.widgets.tile.TileLayout
All Implemented Interfaces:
HasAttachHandlers, HasHandlers, EventListener, HasVisibility, IsWidget, LogicalStructure, HasClearHandlers, HasClickHandlers, HasDoubleClickHandlers, HasDragMoveHandlers, HasDragRepositionMoveHandlers, HasDragRepositionStartHandlers, HasDragRepositionStopHandlers, HasDragResizeMoveHandlers, HasDragResizeStartHandlers, HasDragResizeStopHandlers, HasDragStartHandlers, HasDragStopHandlers, HasDropHandlers, HasDropMoveHandlers, HasDropOutHandlers, HasDropOverHandlers, HasFocusChangedHandlers, HasHoverHandlers, HasHoverHiddenHandlers, HasKeyDownHandlers, HasKeyPressHandlers, HasMouseDownHandlers, HasMouseMoveHandlers, HasMouseOutHandlers, HasMouseOverHandlers, HasMouseStillDownHandlers, HasMouseUpHandlers, HasMouseWheelHandlers, HasMovedHandlers, HasParentMovedHandlers, HasResizedHandlers, HasRightMouseDownHandlers, HasRuleContextChangedHandlers, HasScrolledHandlers, HasShowContextMenuHandlers, HasVisibilityChangedHandlers
Direct Known Subclasses:
FlowLayout, TileGrid
public class TileLayout extends Canvas
Lays out a series of components, called "tiles", in a grid with multiple tiles per row.

  • Constructor Details

    • TileLayout

      public TileLayout()

    • TileLayout

      public TileLayout(JavaScriptObject jsObj)

  • Method Details

    • getOrCreateRef

      public static TileLayout getOrCreateRef(JavaScriptObject jsObj)

    • changeAutoChildDefaults

      public static void changeAutoChildDefaults(String autoChildName, Canvas defaults)
      Changes the defaults for Canvas AutoChildren named autoChildName.
      Parameters:
      autoChildName - name of an AutoChild to customize the defaults for.
      defaults - Canvas defaults to apply. These defaults override any existing properties without destroying or wiping out non-overridden properties. For usage tips on this param, see SGWTProperties.
      See Also:

    • changeAutoChildDefaults

      public static void changeAutoChildDefaults(String autoChildName, FormItem defaults)
      Changes the defaults for FormItem AutoChildren named autoChildName.
      Parameters:
      autoChildName - name of an AutoChild to customize the defaults for.
      defaults - FormItem defaults to apply. These defaults override any existing properties without destroying or wiping out non-overridden properties. For usage tips on this param, see SGWTProperties.
      See Also:

    • create

      protected JavaScriptObject create()
      Overrides:
      create in class Canvas

    • setAnimateTileChange

      public TileLayout setAnimateTileChange(Boolean animateTileChange)
      If set, tiles animate to their new positions when a tile is added, removed, or reordered via drag and drop.

      Note : This is an advanced setting

      Parameters:
      animateTileChange - New animateTileChange value. Default value is true
      Returns:
      TileLayout instance, for chaining setter calls
      See Also:

    • getAnimateTileChange

      public Boolean getAnimateTileChange()
      If set, tiles animate to their new positions when a tile is added, removed, or reordered via drag and drop.
      Returns:
      Current animateTileChange value. Default value is true
      See Also:

    • setAutoWrapLines

      public TileLayout setAutoWrapLines(Boolean autoWrapLines) throws IllegalStateException
      When LayoutPolicy is "flow", should we automatically start a new line when there's not enough room to fit the next tile on the same line?

      If set to false, a new line will only be started if a tile specifies tile.startLine or tile.endLine.

      Parameters:
      autoWrapLines - New autoWrapLines value. Default value is true
      Returns:
      TileLayout instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getAutoWrapLines

      public Boolean getAutoWrapLines()
      When LayoutPolicy is "flow", should we automatically start a new line when there's not enough room to fit the next tile on the same line?

      If set to false, a new line will only be started if a tile specifies tile.startLine or tile.endLine.

      Returns:
      Current autoWrapLines value. Default value is true

    • setDragDataAction

      public TileLayout setDragDataAction(DragDataAction dragDataAction)
      Indicates what to do with data dragged into another DataBoundComponent. See DragDataAction type for details.
      Parameters:
      dragDataAction - New dragDataAction value. Default value is Canvas.MOVE
      Returns:
      TileLayout instance, for chaining setter calls
      See Also:

    • getDragDataAction

      public DragDataAction getDragDataAction()
      Indicates what to do with data dragged into another DataBoundComponent. See DragDataAction type for details.
      Returns:
      Current dragDataAction value. Default value is Canvas.MOVE
      See Also:

    • getDragLine

      public Canvas getDragLine() throws IllegalStateException
      Canvas used to display a drop indicator when a another canvas is dragged over this widget.

      This component is an AutoChild named "dragLine". For an overview of how to use and configure AutoChildren, see Using AutoChildren.

      Returns:
      Current dragLine value. Default value is null
      Throws:
      IllegalStateException - if this widget has not yet been rendered.

    • setDragLineStyle

      public TileLayout setDragLineStyle(String dragLineStyle) throws IllegalStateException
      The CSS class applied to the dragLine autochild.
      Parameters:
      dragLineStyle - New dragLineStyle value. Default value is "layoutDropLine"
      Returns:
      TileLayout instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
      See Also:

    • getDragLineStyle

      public String getDragLineStyle()
      The CSS class applied to the dragLine autochild.
      Returns:
      Current dragLineStyle value. Default value is "layoutDropLine"
      See Also:

    • setDragLineThickness

      public TileLayout setDragLineThickness(int dragLineThickness)
      Thickness of the dragLine autochild.
      Parameters:
      dragLineThickness - New dragLineThickness value. Default value is 2
      Returns:
      TileLayout instance, for chaining setter calls

    • getDragLineThickness

      public int getDragLineThickness()
      Thickness of the dragLine autochild.
      Returns:
      Current dragLineThickness value. Default value is 2

    • setExpandMargins

      public TileLayout setExpandMargins(Boolean expandMargins) throws IllegalStateException
      With LayoutPolicy:"fit", should margins be expanded so that tiles fill the available space in the TileLayout on the breadth axis? This can also affect tileWidth or tileHeight. See those properties for details.
      Parameters:
      expandMargins - New expandMargins value. Default value is true
      Returns:
      TileLayout instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getExpandMargins

      public Boolean getExpandMargins()
      With LayoutPolicy:"fit", should margins be expanded so that tiles fill the available space in the TileLayout on the breadth axis? This can also affect tileWidth or tileHeight. See those properties for details.
      Returns:
      Current expandMargins value. Default value is true

    • setLayoutMargin

      public TileLayout setLayoutMargin(Integer layoutMargin) throws IllegalStateException
      A margin left around the outside of all tiles.
      Parameters:
      layoutMargin - New layoutMargin value. Default value is 5
      Returns:
      TileLayout instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getLayoutMargin

      public Integer getLayoutMargin()
      A margin left around the outside of all tiles.
      Returns:
      Current layoutMargin value. Default value is 5

    • setOrientation

      public TileLayout setOrientation(Orientation orientation) throws IllegalStateException
      Direction of tiling. See also TileLayoutPolicy.
      Parameters:
      orientation - New orientation value. Default value is "horizontal"
      Returns:
      TileLayout instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getOrientation

      public Orientation getOrientation()
      Direction of tiling. See also TileLayoutPolicy.
      Returns:
      Current orientation value. Default value is "horizontal"

    • setOverflow

      public TileLayout setOverflow(Overflow overflow)
      Normal Overflow settings can be used on TileLayouts, for example, an overflow:auto TileLayout will scroll if members exceed its specified size, whereas an overflow:visible TileLayout will grow to accommodate members.
      Overrides:
      setOverflow in class Canvas
      Parameters:
      overflow - New overflow value. Default value is "auto"
      Returns:
      TileLayout instance, for chaining setter calls
      See Also:

    • getOverflow

      public Overflow getOverflow()
      Normal Overflow settings can be used on TileLayouts, for example, an overflow:auto TileLayout will scroll if members exceed its specified size, whereas an overflow:visible TileLayout will grow to accommodate members.
      Overrides:
      getOverflow in class Canvas
      Returns:
      Current overflow value. Default value is "auto"
      See Also:

    • setPaddingAsLayoutMargin

      public TileLayout setPaddingAsLayoutMargin(Boolean paddingAsLayoutMargin)
      If this widget has padding specified (as this.padding or in the CSS style applied to this layout), should it show up as space outside the members, similar to layoutMargin?

      If this setting is false, padding will not affect member positioning (as CSS padding normally does not affect absolutely positioned children). Leaving this setting true allows a designer to more effectively control layout purely from CSS.

      Note that Layout.layoutMargin if specified, takes precedence over this value.

      Note : This is an advanced setting

      Parameters:
      paddingAsLayoutMargin - New paddingAsLayoutMargin value. Default value is true
      Returns:
      TileLayout instance, for chaining setter calls

    • getPaddingAsLayoutMargin

      public Boolean getPaddingAsLayoutMargin()
      If this widget has padding specified (as this.padding or in the CSS style applied to this layout), should it show up as space outside the members, similar to layoutMargin?

      If this setting is false, padding will not affect member positioning (as CSS padding normally does not affect absolutely positioned children). Leaving this setting true allows a designer to more effectively control layout purely from CSS.

      Note that Layout.layoutMargin if specified, takes precedence over this value.

      Returns:
      Current paddingAsLayoutMargin value. Default value is true

    • setShowDragLine

      public TileLayout setShowDragLine(Boolean showDragLine)
      Set false to prevent the dragLine autochild from showing during dragging.
      Parameters:
      showDragLine - New showDragLine value. Default value is null
      Returns:
      TileLayout instance, for chaining setter calls

    • getShowDragLine

      public Boolean getShowDragLine()
      Set false to prevent the dragLine autochild from showing during dragging.
      Returns:
      Current showDragLine value. Default value is null

    • setTileHeight

      public TileLayout setTileHeight(Integer tileHeight) throws IllegalStateException
      Height of each tile in pixels. See tileSize. If TileLayoutPolicy is "fit", expandMargins is false, tilesPerLine is set, Orientation is "vertical", and tileHeight is not set, tileHeight will be computed automatically based on tilesPerLine.

      If this method is called after the component has been drawn/initialized: Sets the height of tiles.
      Parameters:
      tileHeight - height. Default value is null
      Returns:
      TileLayout instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
      See Also:

    • getTileHeight

      public Integer getTileHeight()
      Height of each tile in pixels. See tileSize. If TileLayoutPolicy is "fit", expandMargins is false, tilesPerLine is set, Orientation is "vertical", and tileHeight is not set, tileHeight will be computed automatically based on tilesPerLine.
      Returns:
      Current tileHeight value. Default value is null
      See Also:

    • setTileHMargin

      public TileLayout setTileHMargin(Integer tileHMargin) throws IllegalStateException
      Horizontal margin in between tiles. See tileMargin.

      If this method is called after the component has been drawn/initialized: Sets the horizontal margin of tiles.
      Parameters:
      tileHMargin - margin. Default value is null
      Returns:
      TileLayout instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getTileHMargin

      public Integer getTileHMargin()
      Horizontal margin in between tiles. See tileMargin.
      Returns:
      Current tileHMargin value. Default value is null

    • setTileMargin

      public TileLayout setTileMargin(int tileMargin) throws IllegalStateException
      Margin in between tiles. Can be set on a per-axis basis with tileHMargin and tileVMargin.

      If this method is called after the component has been drawn/initialized: Sets the vertical and horizontal margin of tiles.
      Parameters:
      tileMargin - margin. Default value is 10
      Returns:
      TileLayout instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getTileMargin

      public int getTileMargin()
      Margin in between tiles. Can be set on a per-axis basis with tileHMargin and tileVMargin.
      Returns:
      Current tileMargin value. Default value is 10

    • setTiles

      public TileLayout setTiles(Canvas... tiles) throws IllegalStateException
      List of tiles to lay out.
      Parameters:
      tiles - New tiles value. Default value is null
      Returns:
      TileLayout instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • setTileSize

      public TileLayout setTileSize(int tileSize) throws IllegalStateException
      Size of each tile in pixels. Depending on the TileLayoutPolicy, tileSize may be taken as a maximum, minimum or exact size of tiles, or may be irrelevant.

      Width and height may be separately set via tileHeight and tileWidth.

      If this method is called after the component has been drawn/initialized: Sets the height and width of tiles.

      Parameters:
      tileSize - size. Default value is 100
      Returns:
      TileLayout instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
      See Also:

    • getTileSize

      public int getTileSize()
      Size of each tile in pixels. Depending on the TileLayoutPolicy, tileSize may be taken as a maximum, minimum or exact size of tiles, or may be irrelevant.

      Width and height may be separately set via tileHeight and tileWidth.

      Returns:
      Current tileSize value. Default value is 100
      See Also:

    • setTilesPerLine

      public TileLayout setTilesPerLine(Integer tilesPerLine)
      Number of tiles to show in each line. Auto-derived from tileSize for some layout modes. See TileLayoutPolicy. This can also affect tileWidth or tileHeight. See those properties for details.

      If this method is called after the component has been drawn/initialized: Sets the number of tiles per line.
      Parameters:
      tilesPerLine - New tilesPerLine value. Default value is null
      Returns:
      TileLayout instance, for chaining setter calls

    • getTilesPerLine

      public Integer getTilesPerLine()
      Number of tiles to show in each line. Auto-derived from tileSize for some layout modes. See TileLayoutPolicy. This can also affect tileWidth or tileHeight. See those properties for details.
      Returns:
      Current tilesPerLine value. Default value is null

    • setTileVMargin

      public TileLayout setTileVMargin(Integer tileVMargin) throws IllegalStateException
      Vertical margin in between tiles. See tileMargin.

      If this method is called after the component has been drawn/initialized: Sets the vertical margin of tiles.
      Parameters:
      tileVMargin - margin. Default value is null
      Returns:
      TileLayout instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getTileVMargin

      public Integer getTileVMargin()
      Vertical margin in between tiles. See tileMargin.
      Returns:
      Current tileVMargin value. Default value is null

    • setTileWidth

      public TileLayout setTileWidth(Integer tileWidth) throws IllegalStateException
      Width of each tile in pixels. See tileSize. If TileLayoutPolicy is "fit", expandMargins is false, tilesPerLine is set, Orientation is "horizontal", and tileWidth is not set, tileWidth will be computed automatically based on tilesPerLine.

      If this method is called after the component has been drawn/initialized: Sets the width of tiles.
      Parameters:
      tileWidth - width. Default value is null
      Returns:
      TileLayout instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
      See Also:

    • getTileWidth

      public Integer getTileWidth()
      Width of each tile in pixels. See tileSize. If TileLayoutPolicy is "fit", expandMargins is false, tilesPerLine is set, Orientation is "horizontal", and tileWidth is not set, tileWidth will be computed automatically based on tilesPerLine.
      Returns:
      Current tileWidth value. Default value is null
      See Also:

    • addTile

      public void addTile(Canvas tile)
      Add a tile to the layout, dynamically.
      Parameters:
      tile - new tile to add

    • addTile

      public void addTile(Canvas tile, Integer index)
      Add a tile to the layout, dynamically.
      Parameters:
      tile - new tile to add
      index - position where the tile should be added. Defaults to adding the tile at the end.

    • getDropIndex

      public int getDropIndex()
      Returns the tile index of the tile that would currently be dropped on by the drag in process. Returns one beyond the last valid index to indicate a drop after all tiles. Except for that special case, a non-null index returned by this method may be passed to getTile() to get the corresponding visible tile.
      Returns:
      tile index of tile that would currently be dropped on, or the tile count for a drop after all tiles
      See Also:

    • getTile

      public Canvas getTile(int index)
      Retrieve a tile by index.

      The TileLayout consistently uses this method to access tiles, in order to allow subclasses to create tiles on demand.

      Parameters:
      index - index of the tile
      Returns:
      the tile

    • setDefaultProperties

      public static void setDefaultProperties(TileLayout tileLayoutProperties)
      Class level method to set the default properties of this class. If set, then all existing and subsequently created instances of this class will automatically have default properties corresponding to the properties set on the SmartGWT class instance passed to this function before its underlying SmartClient JS object was created. This is a powerful feature that eliminates the need for users to create a separate hierarchy of subclasses that only alter the default properties of this class. Can also be used for skinning / styling purposes.

      Note: This method is intended for setting default attributes only and will affect all instances of the underlying class (including those automatically generated in JavaScript). This method should not be used to apply standard EventHandlers or override methods for a class - use a custom subclass instead. Calling this method after instances have been created can result in undefined behavior, since it bypasses any setters and a class instance may have already examined a particular property and not be expecting any changes through this route.

      Parameters:
      tileLayoutProperties - properties that should be used as new defaults when instances of this class are created
      See Also:

    • setLayoutPolicy

      public void setLayoutPolicy(TileLayoutPolicy layoutPolicy) throws IllegalStateException
      Policy for laying out tiles. See TileLayoutPolicy for options.
      Parameters:
      layoutPolicy - layoutPolicy Default value is ""
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • removeTile

      public boolean removeTile(int tileIndex)
      Remove a tile from the layout.
      Parameters:
      tileIndex - index or String ID of the tile
      Returns:
      whether a tile was found and removed

    • removeTile

      public boolean removeTile(String tileID)
      Remove a tile from the layout.
      Parameters:
      tileID - index or String ID of the tile
      Returns:
      whether a tile was found and removed

    • removeTile

      public boolean removeTile(Canvas tile)
      Remove a tile from the layout.
      Parameters:
      tile - index or String ID of the tile
      Returns:
      whether a tile was found and removed

    • layoutTiles

      public void layoutTiles()
      Forces layout out the tiles

    • transformTileRect

      public Rectangle transformTileRect(int left, int top, int width, int height)
      Transforms the input tile relative rect to an absolute page rect that you can apply to your own drop indicator canvas. The supplied rect is automatically clipped along the direction perpendicular to the layout's orientation if it extends beyond the visible edges of the layout, just like the dragLine autochild.

      Note: This is an advanced setting. Only code your own drop indicator if you can't get what you need by customizing and styling the built-in dragLine autochild!

      To build your own:

      • Create a separate indicator Canvas, positioned off screen with the appropriate color, opacity, and style that you want. Set the indicator's dropTarget to be the layout to so the indicator is ignored.
      • Override dropMove() to call getDropIndex(), retrieve the tile, get the tile's relative rect, and modify the rect as you need to size your indicator properly.
      • You'll have to manually handle the case of the drop index pointing beyond the last record, perhaps by grabbing the last tile rect, but narrowing it to the opposite side.
      • Pass the modified rect to this method to clip and transform it to an absolute rect, and then set that new rect into your drop indicator and show() it.
      • You will need to hide() the drop indicator in dropOut().

      Sample code to insert into the SGWT LGPL "Basic Tiling" sample, replacing getViewPanel(): 

          
    public static class MyTileGrid extends TileGrid {
        Canvas dropIndicator;

        void showDropIndicator(int left, int top, int width, int height) {
            // create the indicator if it doesn't exist
            if (dropIndicator == null) {
                dropIndicator = new Canvas();
                dropIndicator.setTop(-1000);
                dropIndicator.setOpacity(40);
                dropIndicator.setDropTarget(this);
                dropIndicator.setBackgroundColor("yellow");
                dropIndicator.draw();
            }
            // transform the rect to a page rect and clip to grid borders
            Rectangle rect = transformTileRect(left, top, width, height);
            dropIndicator.setRect(rect);
            dropIndicator.show();
        }
    }

    public Canvas getViewPanel() {
        TileGrid tileGrid = new MyTileGrid();

        tileGrid.setTileWidth(194);
        tileGrid.setTileHeight(180);
        tileGrid.setHeight(400);
        tileGrid.setWidth100();
        tileGrid.setCanReorderTiles(true);
        tileGrid.setShowAllRecords(true);
        tileGrid.setData(CarData.getRecords());
        tileGrid.setShowDragLine(false);
        tileGrid.setCanReorderTiles(true);

        tileGrid.addDropMoveHandler(new DropMoveHandler() {
            \@Override
            public void onDropMove(DropMoveEvent event) {
                MyTileGrid tg = (MyTileGrid)event.getFiringCanvas();
                int index  = tg.getDropIndex();
                int length = tg.getData().length;

                // you can drop after last tile (special case)
                boolean after = index >= length;
                if (after) index = length - 1;

                // transform tile rect to indicator rect
                Canvas tile = tg.getTile(index);
                if (tile != null) {
                    int left = tile.getLeft(),  width = tile.getVisibleWidth(),
                        top  = tile.getTop(),  height = tile.getVisibleHeight()
                    ;
                    // to show drop after last tile, shift indicator over
                    if (after) left += width - 20;

                    // now show the indicator
                    tg.showDropIndicator(left, top, 20, height);
                }
            }
        });

        tileGrid.addDropOutHandler(new DropOutHandler() {
            \@Override
            public void onDropOut(DropOutEvent event) {
                MyTileGrid tg = (MyTileGrid)event.getFiringCanvas();
                if (tg.dropIndicator != null) tg.dropIndicator.hide();
            }
        });

        tileGrid.addClearHandler(new ClearHandler() {
            \@Override
            public void onClear(ClearEvent event) {
                MyTileGrid tg = (MyTileGrid)event.getFiringCanvas();
                if (tg.dropIndicator != null) {
                    tg.dropIndicator.markForDestroy();
                    tg.dropIndicator = null;
                }
            }
        });

        // unchanged from here and below...
           :
      Parameters:
      left - new left coordinate
      top - new top coordinate
      width - new width
      height - new height
      Returns:
      the Rectangle

    • setLogicalStructure

      public LogicalStructureObject setLogicalStructure(TileLayoutLogicalStructure s)
      Setter implementing the LogicalStructure interface, which supports Eclipse's logical structure debugging facility.

    • getLogicalStructure

      public LogicalStructureObject getLogicalStructure()
      Getter implementing the LogicalStructure interface, which supports Eclipse's logical structure debugging facility.
      Specified by:
      getLogicalStructure in interface LogicalStructure
      Overrides:
      getLogicalStructure in class Canvas