qnx.fuse.ui.core.ILayoutElement

ILayoutElement

Properties | Methods


Packageqnx.fuse.ui.core
Interfacepublic interface ILayoutElement
Implementors Label, UIComponent

Interface implemented by objects that participate in layout. ILayout uses this interface to communicate with its elements. Its primary function is to return the preferred, default size, and resize behavior for the element and to allow the element to be repositioned. This interface provides information about how the control will look best, but it is up to the containing layout to make the final decision about the control's position and size.

Once the containing layout has decided on a position and size for the element, it will call setLayoutBounds. The layout element is required to respect these bounds, even if they differ from the element's own preferences.



Class information:
BlackBerry 10 Version:   10.0.0



Public Properties

 PropertyDefined By
  includeInLayout : Boolean
Specifies whether or not the component should be included in its parent container's layout.
ILayoutElement
  layoutData : Object
Gets or sets the layoutData.
ILayoutElement

Public Methods

 MethodDefined By
  
Returns a bitwise combination of SizeOptions GROWTH | SHRINK constants, indicating whether this control wants to grow or shrink in the given dimension.
ILayoutElement
  
measure(availableWidth:Number, availableHeight:Number):LayoutMeasurement
Returns the preferred size of the control.
ILayoutElement
  
setLayoutBounds(rect:Rectangle):void
Sets the receiver's size and location to the rectangular area specified by the arguments.
ILayoutElement

Property Detail

includeInLayout


includeInLayout:Boolean

Specifies whether or not the component should be included in its parent container's layout.

If true, the component will be sized and positioned based on the container's layout rules. If set to false, the component's size and position are not considered in the layout of the parent container.

After changing the value of this attribute, the container will receive ILayout.layoutChanged(null). The null argument indicates that this is not a change in a control's measure() or getSizeOptions() method.


Implementation

public function get includeInLayout():Boolean
public function set includeInLayout(value:Boolean):void

layoutData


layoutData:Object

Gets or sets the layoutData.

The meaning and type of this property is determined by the layout that contains the layout element, but it is generally used to configure all per-control settings in the layout.

The following attributes are common to all layout data:

  • Once a layoutData object is attached to an ILayoutElement, the object instance must never be changed. If callers want to modify the layout data, they must clone the old layout data object, modify it, then attach the new copy of it to the layout element. Layouts are allowed to compare the old layout data with the new one to determine what changed. If the original layout data is ever modified, the layout may incorrectly determine that nothing changed and ignore the event.
  • If this property changes, the layout will be notified via a call to ILayout.layoutChanged(null).


Implementation

public function get layoutData():Object
public function set layoutData(value:Object):void

Method Detail

getSizeOptions()


public function getSizeOptions():int

Returns a bitwise combination of SizeOptions GROWTH | SHRINK constants, indicating whether this control wants to grow or shrink in the given dimension.

The flags have the following meaning:

  • SizeOptions.GROW_HORIZONTAL - indicates that if the control were made wider than its preferred width, it would be able to utilize the extra space.
  • SizeOptions.SHRINK_HORIZONTAL - indicates that if the control were made norrower than its preferred width, it would still be usable.
  • SizeOptions.GROW_VERTICAL - indicates that if the control were made taller than its preferred height, it would be able to utilize the extra space.
  • SizeOptions.SHRINK_VERTICAL - indicates that if the control were made shorter than its preferred height, it would still be usable.

For example, a wrapping text label would return its unwrapped dimensions as its preferred size. It would return SizeOptions.SHRINK_HORIZONTAL as its only growth flag since its parent can compress it horizontally. Compressing the label horizontally will cause it to grow vertically, but since the vertical growth is initiated by the label itself and not its parent, it should not return the SizeOptions.GROW_VERTICAL flag.

A single-line editable text box would return both the SizeOptions.GROW_HORIZONTAL flag and the SizeOptions.SHRINK_HORIZONTAL flag, since the text box would still be usable with any horizontal size. It would not return any vertical flags since a one-line text box would always be exactly the height of one line of text.

Returns

int — One of the options avaliable in SizeOptions that describes how the layout element should resize.

measure()


public function measure(availableWidth:Number, availableHeight:Number):LayoutMeasurement

Returns the preferred size of the control.

Returns the preferred size of the control, given one or both dimensions that have been chosen by its parent. The preferred size may be totally different than the control's actual size. This is an indication of what size the control wants to be. The parent layout is still free to ignore this and set the control to a different size.

If both dimensions are DefaultSize, then the control will return whatever size it feels it looks best at. If exactly one dimension is DefaultSize then the other dimension is constrained. The caller is essentially asking the control: "If I were to make you exactly this wide, how tall would you want to be?". The control is required to return any constrained dimension verbatim. If neither dimension is set to DefaultSize, this method must return the point (availableX, availableY).

Implementations of this method must not modify the control in any way or cause any events to be fired from it. If the implementation of this method will perform any expensive calculations, it should make use of a SizeCache or other caching strategy to ensure that the average cost of this function is reasonable.

If the result of this method changes for any given input, the layout will be notified via a call to ILayout.layoutChanged(layoutElement).

Controls will often return their most extreme size as their preferred size, since doing so allows them to return more specific resize flags. For example, if a wrapping text control returns its unwrapped (widest possible) size as its preferred size, it would only need to specify the SizeOptions.SHRINK_HORIZONTAL resize flag. This tells its parent "I can be made up to this wide and no wider". Another option would be for the wrapping text control to choose a preferred wrapping point and return that as its preferred width. However, since such a control would support other widths that are both larger and smaller than its preferred size, it would have to specify both the SizeOptions.GROW_HORIZONTAL and SizeOptions.SHRINK_HORIZONTAL flags and would not be able to communicate its maximum size to its parent. In such cases, it is generally better to report the unwrapped size as the preferred size and override the preferred size in the layout if it is not appropriate.

Parameters

availableWidth:Number — The horizontal space available in the parent, or DefaultSize if the horizontal dimension is unconstrained.
availableHeight:Number — The vertical space available in the parent, or DefaultSize if the vertical dimension is unconstrained.

Returns

LayoutMeasurement

setLayoutBounds()


public function setLayoutBounds(rect:Rectangle):void

Sets the receiver's size and location to the rectangular area specified by the arguments.

Parameters

rect:Rectangle — The receivers size and location.





comments powered by Disqus