Image/.swf Component

From KickApps Documentation

The IMG/SWF component places an image file or a SWF file into your widget. In the "Content" panel for this component, you can specify an image or SWF file that is hosted on an external server, or you can specify an image or SWF file that is hosted on the KickApps servers.

Contents 1 Properties 2 Content 3 Background & Border 4 Properties 5 Background & Border 6 Layout 6.1 Layout Constraints 7 Events 7.1 Standard Events 8 Actions 8.1 Standard Actions 9 Layout 9.1 Layout Constraints 10 Events 10.1 Standard Events 10.2 Image Component Events 11 Actions 11.1 Standard Actions 12 Preparing a .swf for inclusion in the App Studio 12.1 If using AS3, ensure your .swf can technically be loaded into another .swf 12.2 Add Security.allowDomain("serve.a-widget") 12.3 If your .swf is framerate dependent, use a framerate of 24

Properties

Properties are configurable aspects of a component that let you customize the way it looks and how it works by changing their values in its configuration panel in the App Studio. You can also use JavaScript to change widget properties after the widget loads on a page using the setComponentProperty() method method of the Widget JavaScript API. Finally, you can use widget property values in Actions using our bracket literal syntax. For a listing of all properties on KickApps components, see our Properties Reference.

Show preloader

Show a spinning preloader animation while the component's content is loading

Scale image to fit container

Expands or contracts the source image to fit the dimensions of the component.

Maintain aspect ratio

Set maintain aspect ratio to have the image maintain its aspect ratio as it expands or contracts to fit the dimensions of the component. If the component doesn't have the same aspect ratio that the image or .swf does, it will stop expanding or contracting when it touches the top and bottom or left and right sides of the component.

Center content vertically

Center content horizontally

Content

• Enter URL
  • Enter a URL to a .jpg, .gif, .png, or .swf
• From component
  • Obtain the image from another component

Background & Border

The scrubber component is used in conjunction with the video and audio players to change positions in the video or audio track that's currently playing.

Properties

• Layout
  • Horizontal
  • Vertical
• Handle Dimensions
  • Width
  • Height

Background & Border

The play progress bar, load progress bar, handle, and background elements of the scrubber can all be styled individually, with the following options:

Icon URL

Enter the URL to an image file in .jpg, .gif, or .png format, or click Browse to open the App Studio Assets window. You can select an image from your App Studio Assets by double-clicking on its icon, or upload a new image by clicking Add. Your selected image will be centered horizontally and vertically within the selected component.

Layout

There are two types of containers: the widget canvas itself (background of the entire widget) is considered a container, and you can also create containers that enclose components within your widget. Like any standard component, containers that you create can be moved around the stage, resized, and styled. The most powerful feature of Containers, though, is their ability to fix the positions of their constituent components via layout constraints, which we'll cover below. To create a container, select multiple components, right-click, and select "Group in new container".

You can configure a container's background color, opacity, border color, border thickness, corner radius, and background image in its Properties panel:

You can also mask content in a container by selecting the Mask Content checkbox at the bottom of the panel above. With masking enabled, components that belong to the container but fall outside its bounds will be hidden. To indicate this, when you're editing a container that has masking enabled in Design mode, and then add a component outside the bounds of the container you're in, that component will be translucent:

Masking is useful for situations in which you want to animate a component into a container after it loads initially.

Layout Constraints

Layout constraints let you anchor components a certain distance away from the sides and axes of their containers. Components with layout constraints enabled maintain their offset distances when their containers are resized. To set layout constraints, double click on your container, then single click on a component within it. The Layout Constraints panel will appear:

The checkboxes along the top side of the square in the Layout Constraints panel can be used to anchor the selected component to the left, vertical center, and right sides of its container. The checkboxes along the left side of the square can be used to anchor the selected component to the top, horizontal center, and bottom sides of its container.

When you select a checkbox, a text input field appears across the box from it. The number in this field represents the offset distance, in pixels, from the selected side of the container. For example, this is what it looks like when you anchor to the left side:

If you then resize this container, the component maintains its distance from the left side:

Similarly, you can anchor a component to the top of its container, and it will maintain its distance from the top when its container is resized:

You can also anchor components to the horizontal and vertical center lines of their containers. This component is anchored to the horizontal center of its container. It maintains its distance from the horizontal center when its container is resized.

This component is anchored to the vertical center of its container. It maintains its distance from the vertical center when its container is resized.

Components anchored to opposite sides of their containers expand and contract to maintain their offsets. Below is a component anchored to both the left and right sides of its container. Note how it expands to maintain its distances from the left and right sides.

The component below is anchored to both the top and bottom sides of its container. It contracts when its container is resized.

Events

Standard Events

• Click
• Component hidden
• Component loaded
• Component shown
• Double click
• Mouse down
• Mouse up
• Roll out
• Roll over

Actions

Standard Actions

• Drag/Stop Drag
• Set depth
• Show/Hide
• Tween Blur
• Tween Color
• Tween Drop Shadow
• Tween Glow
• Tween Property
• Update Property
  • For a listing of all properties on KickApps components, see our Properties Reference.

Layout

There are two types of containers: the widget canvas itself (background of the entire widget) is considered a container, and you can also create containers that enclose components within your widget. Like any standard component, containers that you create can be moved around the stage, resized, and styled. The most powerful feature of Containers, though, is their ability to fix the positions of their constituent components via layout constraints, which we'll cover below. To create a container, select multiple components, right-click, and select "Group in new container".

You can configure a container's background color, opacity, border color, border thickness, corner radius, and background image in its Properties panel:

You can also mask content in a container by selecting the Mask Content checkbox at the bottom of the panel above. With masking enabled, components that belong to the container but fall outside its bounds will be hidden. To indicate this, when you're editing a container that has masking enabled in Design mode, and then add a component outside the bounds of the container you're in, that component will be translucent:

Masking is useful for situations in which you want to animate a component into a container after it loads initially.

Layout Constraints

Layout constraints let you anchor components a certain distance away from the sides and axes of their containers. Components with layout constraints enabled maintain their offset distances when their containers are resized. To set layout constraints, double click on your container, then single click on a component within it. The Layout Constraints panel will appear:

The checkboxes along the top side of the square in the Layout Constraints panel can be used to anchor the selected component to the left, vertical center, and right sides of its container. The checkboxes along the left side of the square can be used to anchor the selected component to the top, horizontal center, and bottom sides of its container.

When you select a checkbox, a text input field appears across the box from it. The number in this field represents the offset distance, in pixels, from the selected side of the container. For example, this is what it looks like when you anchor to the left side:

If you then resize this container, the component maintains its distance from the left side:

Similarly, you can anchor a component to the top of its container, and it will maintain its distance from the top when its container is resized:

You can also anchor components to the horizontal and vertical center lines of their containers. This component is anchored to the horizontal center of its container. It maintains its distance from the horizontal center when its container is resized.

This component is anchored to the vertical center of its container. It maintains its distance from the vertical center when its container is resized.

Components anchored to opposite sides of their containers expand and contract to maintain their offsets. Below is a component anchored to both the left and right sides of its container. Note how it expands to maintain its distances from the left and right sides.

The component below is anchored to both the top and bottom sides of its container. It contracts when its container is resized.

Events

Standard Events

• Click
• Component hidden
• Component loaded
• Component shown
• Double click
• Mouse down
• Mouse up
• Roll out
• Roll over

Image Component Events

• Media failed to load

Actions

Standard Actions

• Drag/Stop Drag
• Set depth
• Show/Hide
• Tween Blur
• Tween Color
• Tween Drop Shadow
• Tween Glow
• Tween Property
• Update Property
  • For a listing of all properties on KickApps components, see our Properties Reference.

Preparing a .swf for inclusion in the App Studio

The App Studio environment introduces some considerations that your .swf may not have been designed to accommodate. We recommend reviewing these three steps to ensure that your .swf works properly.

1. If using AS3, ensure your .swf can technically be loaded into another .swf
2. Add Security.allowDomain("serve.a-widget")
3. If your .swf is framerate dependent, use a framerate of 24

If using AS3, ensure your .swf can technically be loaded into another .swf

If written in AS3, unchecked references to "stage" in the class constructor (or first frame of a timeline .swf) can keep the .swf from loading into another .swf like the Widget Studio. This is because in Actionscript 3, when one .swf loads another, Flash always initializes the loaded .swf before it is added to the display tree of the parent .swf. If you find your .swf works fine stand-alone but you receive a flash debugger error: "TypeError: Error #1009: Cannot access a property or method of a null object reference." when loading into the Widget Studio this is probably the issue. The solution is to wait for the stage property to become available before accessing it like so:

Constructor(){
   if (stage){
      onAddedToStage();
   } else {
      addEventListener(Event.ADDED_TO_STAGE, onAddedToStage);
   }
}

private function onAddedToStage(evt:Event=null):void {
   removeEventListener(Event.ADDED_TO_STAGE, onAddedToStage);
   stage.align = StageAlign.TOP_LEFT;
   stage.scaleMode = StageScaleMode.NO_SCALE;
   initApp();
}

Another "stage" reference pitfall is sizing your .swf's internal content relative to stage.width/height or stage.stageWidth/stageHeight. This will reference the entire size of the widget studio instead of the size of your .swf. Please use the "root" property if needing a global reference to the top-most display object in your .swf file.

Add Security.allowDomain("serve.a-widget")

The App Studio generates thumbnails of widgets for use in the Widget Manager and for posting to Facebook and MySpace. In order for your ..swf to appear in these thumbnails, it must grant pixel access to the domain from which we serve widgets, serve.a-widget.com. You can do this by setting Security.allowDomain("*") or Security.allowDomain("serve.a-widget.com") in your .swf. This also prevents specific cross-domain security sandbox restrictions that may break functionality in your widget (see [[1]]).

If your .swf is framerate dependent, use a framerate of 24

KickApps widgets use a framerate of 24. If your .swf uses timeline based animations you may find that its animations run faster or slower unless it is published to this framerate which is also the default framerate of Flex and Flash.