What is it?
The Image widget enables you to show image files uploaded with the Files tool on pages in the app.
How do I use it?
You need to do two things - add an image file to the app, and set up the Image widget on a page:
Add an image file to your app
Use the Files tool to add an imagefile to your app. The image must be formatted as JPEG, PNG or GIF (including animated GIF). Choose an image that is about (or , even better, exactly) the same size as you intend to display the image widget. Here is the JPEG image that I am using:
Click on the Files tab to bring up the Files tool, then on the Upload button. Select your image (or images) and click on Choose (or OK). You will see a progress bar, then the new files appearing in the file list on the left. If you like, you can create a folder to hold the images, as I have done:
Configure an image widget
Go to the Layout tool and click on the Image tab in the widgets panel on the left. Remember that clicking on the 'i' button will give you some more information on the widget.
Drag the Image icon with the AppFurnace logo from the widget panel onto the page canvas:
Select the Settings tab in the properties panel on the right side of the Layout tool. Then use the 'image' dropdown to select the image file you uploaded a moment ago - the corresponding image should appear in the widget.
I'll explain about the (2x) in a moment. At this stage you might think that the image is too small on the page and that you'd prefer not to have black bars around the image. Both are easily dealt with. Change the image's size (and position) in the usual ways, using the grabbers on wach edge of the selected widget or the 'width' and 'height' properties on the Size & Position tab in the property panel. Then use the 'image size' property back in the Settings tab to specify how the image is scaled and cropped to fit the widget:
|stretch||fit||crop to fit|
See below for more information on these three modes
What about retina displays?
Later iPhone models (after iPhone 4) have retina displays with 640x960 resolution instead of the older 320x480 resolution. That means that you are able to show much sharper images on later iPhones for the same screen 'real estate'. AppFurnace supports retina displays by enabling you to upload an image at both high and low resolutions. Remember to always generate the lower resolution image file from the higher one for maximum sharpness. You must upload the two files to the same folder and give the higher resolution image the same name as the lower resolution version except for the suffix "@2x". For example:
What properties does it have?
Most of the Image widget's properties are shared with other widgets and allow you to control its size, position, whether it has a border etc. You can always see the full list by clicking on the 'i' button on the Image tab in the widget panel, as shown above. Here are the properties that are specific to the Image widget:
The filename of the image to display. The default value of this property is none.
Controls how the background image is scaled to fit the widget
The image is stretched to fit the widget exactly. Aspect ratio is not maintained so your image may look stretched or squashed.
The image is displayed as large as it can be without cropping while retaining the original aspect ratio. Colored bars will be added to fill the remaining space. The color can be changed using the *Shape Color* property.
crop to fit
The image is scaled to the point where the whole widget is filled while retaining the original aspect ratio. The image will be cropped to fit the shape of the widget.
How can I use it in code?
- set the widget x-position using ui.myImage.x(23);.
- change the displayed image with ui.myImage.backgroundImage("myImages/image2.png");
You can also create and display an image widget on a page completely in code, e.g.
var i = new af.Image(); i.backgroundImage("images/abbey.jpg"); i.x(100); i.y(150); i.width(150); i.height(100); ui.page.add(i);
Full documentation for coding with an image widget can be found in the AppFurnace code API Documentation.