## ImageList

Not implemented under MacOS

### Description

The ImageList class allows you to attach images to Menus, Tree controls, and the Pages (tab sheets) in a Selector control.

As its name implies, an ImageList object contains a series of images (typically small icons or pictures), numbered from 1 onwards. These images are all of the same size. The ImageList object is not itself visible; instead, you associate an ImageList with another control, and that control displays images from the list as required. For example, you can have a Tree control where different images are used for different types of node, or you can display an icon from the ImageList next to a Menu item.

The ImageList can be created either as a top-level object, or as the child of another object. The former case is preferable if it will be used in several different controls. On the other hand, if it will be used in only one control, then it may be more convenient to create it as a child of that control so that it is automatically deleted with the control.

You can specify the images in the ImageList either as file names, or as APL numeric arrays where each element contains the color corresponding to a pixel in the image. The `imagenames` property or `Addimages` method can be used to specify the images. You can arrange for a portion of the image to be transparent.

A single bitmap can optionally contribute multiple images to the ImageList, laid side by side. To do this, you need first to set the `imagesize` property to be the size of the image. Any bitmap of a width N times the width specified in `imagesize` will then contribute N images to the list.

Once you have created an ImageList, you associate it with the control where it will be used by writing its name to the `imagelist` property of a Tree, Selector or pop-up Menu control. (For a Tree control there is also a second ImageList contained in the `imagelistuser` property). To use an ImageList for the menu items in a window's menu bar, write its name to the `menuimagelist` property of the Form, Dialog, Document or Window object. A given ImageList can be used by several other objects.

Finally, you need to tell the control associated with the ImageList to display an image from the list. For a Menu item or Page control, you do this by specifying the `imageindex` property, as an integer index (in origin 1) into the images in the ImageList. For a Tree control, there are various options; you can specify a fixed image for particular nodes, or the image shown can depend on the state of the node. See the `list` property for more information.

Cross-platform use: Although this class is implemented under both Windows and Linux, there are some differences in the supported properties and methods. It is not implemented at all under MacOS.

#### ImageList properties

The main ImageList properties are:

`style`: The default style is 0, meaning that the images are not automatically transparent. If you set the style to 1, pixels correspondng to the `maskcolor` property are treated as transparent.

`maskcolor`: Allows you to specify the color which will be treated as transparent if `style` is 1. The color can be a single integer 256 ƒ Blue Green Red, or a vector of Red Green Blue values separately (in range 0 to 255).

`imagenames`: Allows you to specify a vector of file names, one for each image in the list. Alternatively, you can specify APL arrays which encode the pictures directly as pixel color values. You can also explicitly set the transparency mask for an image.

`imagesize`: Specifies the height and width of the images, in the current `scale` of the ImageList.

`overlays`: Allows you to specify the index positions (in origin 1) of up to four images in the ImageList which will be used to overlay other images. These overlays can then be used in a Tree object. Note: This property is not available under Linux.

`imagecount`: A read-only property, the number of images in the list.

#### ImageList methods

The main ImageList method is:

`Addimages`: Allows you to add images to the list.

### Example 1: Using an ImageList in a window's menu

          ’DEMO_Menu_Images;img;DEMO;MyImageList
    [1]  © Use of an ImageList and a Menu
    [2]  ©
    [3]   DEMO„'Œ' ŒNEW 'Window' ª DEMO.title„'Menu & ImageList Example'
    [4]  ©
    [5]  © Create an image list containing icons and add it to the window
    [6]   MyImageList„'Œ' ŒNEW 'ImageList'
    [7]   MyImageList.imagesize„16 16
    [8]   MyImageList.maskcolour„0 © Black areas  transparent
    [9]   img„16 16½0 © Create a 16×16 pixel colour matrix
    [10]  img[4+¼8;4+¼8]„256ƒ0 255 0 © Make middle 8x8 green
    [11]  MyImageList.AddImages img © Image 1: green square
    [12]  img[4+¼8;4+¼8]„256ƒ255 0 0 © Make middle 8x8 blue
    [13]  MyImageList.AddImages img © Image 2: blue square
    [14]  MyImageList.maskcolour„(256ƒ255 255 255) © White areas transparent
    [15]  MyImageList.AddImages(FULL_IMAGE_PATH 'abc.bmp') © Images 3,4,5 from file
    [16]  DEMO.menuimagelist„MyImageList.name
    [17] ©
    [18] © Set up the File menu
    [19] © The 'imageindex' property of a window's menu items select the image
    [20] © from the 'menuimagelist' of the window
    [21] ©
    [22]  DEMO.FileMenu.New 'Menu' ª DEMO.FileMenu.caption„'&File'
    [23]  DEMO.FileMenu.imageindex„1
    [24]  DEMO.FileMenu.Open.New 'Menu' ª DEMO.FileMenu.Open.caption„'&Open'
    [25]  DEMO.FileMenu.Open.imageindex„3
    [26]  DEMO.FileMenu.Close.New 'Menu' ª DEMO.FileMenu.Close.caption„'&Close'
    [27]  DEMO.FileMenu.Close.imageindex„4
    [28]  DEMO.FileMenu.Exit.New 'Menu' ª DEMO.FileMenu.Exit.caption„'&Exit'
    [29]  DEMO.FileMenu.Exit.shortcut„(81 2)
    [30]  DEMO.FileMenu.Exit.imageindex„5
    [31] ©
    [32] © Set up the Edit menu
    [33]  DEMO.EditMenu.New 'Menu' ª DEMO.EditMenu.caption„'&Edit'
    [34]  DEMO.EditMenu.imageindex„2
    [35]  DEMO.EditMenu.Undo.New 'Menu' ª DEMO.EditMenu.Undo.caption„'&Undo'
    [36]  DEMO.EditMenu.Undo.enabled„0 ª DEMO.EditMenu.Undo.shortcut„(92 2)
    [37]  DEMO.EditMenu.Sep1.New 'Menu' ª DEMO.EditMenu.Sep1.separator„1
    [38]  DEMO.EditMenu.Cut.New 'Menu' ª DEMO.EditMenu.Cut.caption„'&Cut'
    [39]  DEMO.EditMenu.Cut.shortcut„('C' 2)
    [40]  DEMO.EditMenu.Cut.imageindex„1
    [41]  DEMO.EditMenu.Copy.New 'Menu' ª DEMO.EditMenu.Copy.caption„'&Copy'
    [42]  DEMO.EditMenu.Copy.shortcut„('X' 2)
    [43]  DEMO.EditMenu.Copy.imageindex„2
    [44]  DEMO.EditMenu.Paste.New 'Menu' ª DEMO.EditMenu.Paste.caption„'&Paste'
    [45]  DEMO.EditMenu.Paste.shortcut„('V' 2)
    [46] ©
    [47] © Wait for the user to close the window
    [48]  0 0½ŒWE DEMO
          ’

### Example 2: Using an ImageList in a pop-up menu

          ’DEMO_Popup_Images;img;MyPopUp;il
    [1]  © Demonstrate pop-up menu in conjunction with the ImageList System Class
    [2]  ©
    [3]  © Create the pop-up menu itself
    [4]   MyPopUp„'Œ' ŒNEW 'Menu'
    [5]  ©
    [6]  © Create an imagelist object to provide images for the menu items
    [7]  © and add it to the popup menu
    [8]   il„'Œ' ŒNEW 'ImageList'
    [9]   il.imagesize„16 16
    [10] ©
    [11] © Create image 1: Circle
    [12]  img„16 16½256ƒ255 255 255  © Create a 16×16 pixel colour matrix
    [13]  img[1,16;]„256ƒ255 0 0 ª img[;1,16]„256ƒ255 0 0 © Surround by blue square
    [14]  img[6,9;7,8]„0 ª img[7,8;6,9]„0
    [15]  il.AddImages img
    [16] ©
    [17] © Create image 2: Triangle
    [18]  img„16 16½256ƒ255 255 255  © Create a 16×16 pixel colour matrix
    [19]  img[1,16;]„256ƒ255 0 0 ª img[;1,16]„256ƒ255 0 0 © Surround by blue square
    [20]  img[6,7,8,9;6]„0 ª img[9;6,7,8,9]„0 ª img[7;7]„0 ª img[8;8]„0
    [21]  il.AddImages img
    [22] ©
    [23] © Create image 3: Line
    [24]  img„16 16½256ƒ255 255 255  © Create a 16×16 pixel colour matrix
    [25]  img[1,16;]„256ƒ255 0 0 ª img[;1,16]„256ƒ255 0 0 © Surround by blue square
    [26]  img[7;6,7,8,9]„0
    [27]  il.AddImages img
    [28] ©
    [29] © Create image 4: Rectangle
    [30]  img„16 16½256ƒ255 255 255  © Create a 16×16 pixel colour matrix
    [31]  img[1,16;]„256ƒ255 0 0 ª img[;1,16]„256ƒ255 0 0 © Surround by blue square
    [32]  img[6;6,7,8,9]„0 ª img[9;6,7,8,9]„0 ª img[6,7,8,9;5]„0
    [33]  img[6,7,8,9;10]„0
    [34]  il.AddImages img
    [35] ©
    [36] © Assign the image list to the popup menu
    [37]  MyPopUp.imagelist„il.name
    [38] ©
    [39] © Create the pop-up menu items
    [40] © The 'imageindex' property of a popup menu's items select the image
    [41] © from the 'imagelist' of the popup menu
    [42]  MyPopUp.Rect.New 'Menu' ª MyPopUp.Rect.caption„'Rectangle'
    [43]  MyPopUp.Rect.imageindex„4
    [44]  MyPopUp.Circle.New 'Menu' ª MyPopUp.Circle.caption„'Circle'
    [45]  MyPopUp.Circle.imageindex„1
    [46]  MyPopUp.Triangle.New 'Menu' ª MyPopUp.Triangle.caption„'Triangle'
    [47]  MyPopUp.Triangle.imageindex„2
    [48]  MyPopUp.Line.New 'Menu' ª MyPopUp.Line.caption„'Line'
    [49]  MyPopUp.Line.imageindex„3
    [50] ©
    [51] © In a real example, you would define onClick callbacks here
    [52] ©
    [53] © Pop up the menu at the mouse position
    [54]  MyPopUp.Popup
          ’

#### Example 3: Using an ImageList with a Selector and Pages

          ’DEMO_Page_Images;DEMO
    [1]  © Demonstrating use of the Selector (tab sheet) System Class
    [2]  © in conjunction with the ImageList class
    [3]  ©
    [4]   DEMO„'Œ' ŒNEW 'Dialog' ª DEMO.scale„1
    [5]   DEMO.title„'Selector/Page & ImageList Example'
    [6]  © Create selector to hold the individual pages, fill the client area
    [7]   DEMO.Sel.New 'Selector' ª DEMO.Sel.align„¯1
    [8]  ©
    [9]  © Create image list with icons for the pages and add to selector.
    [10] © (Image list does not have to be child of the selector, but it
    [11] © is convenient because it will be deleted with its parent)
    [12]  DEMO.Sel.il.New 'ImageList'
    [13]  DEMO.Sel.il.imagesize„16 16
    [14]  DEMO.Sel.il.maskcolour„(256ƒ255 255 255) © White areas transparent
    [15]  DEMO.Sel.il.AddImages(FULL_IMAGE_PATH 'abc.bmp')
    [16]  DEMO.Sel.imagelist„DEMO.Sel.il.name
    [17] ©
    [18] © Now create three pages each with some radio buttons
    [19]  DEMO.Sel.Page1.New 'Page' ª DEMO.Sel.Page1.caption„'Appetizer'
    [20]  DEMO.Sel.Page1.imageindex„1 © Use image 1 in selector's image list
    [21]  DEMO.Sel.Page1.R1.New 'Radio'
    [22]  DEMO.Sel.Page1.R1.caption„'Smoked Salmon'
    [23]  DEMO.Sel.Page1.R1.where„2 1
    [24]  DEMO.Sel.Page1.R1.value„1
    [25]  DEMO.Sel.Page1.R2.New 'Radio'
    [26]  DEMO.Sel.Page1.R2.caption„'Fresh asparagus'
    [27]  DEMO.Sel.Page1.R2.where„4 1
    [28]  DEMO.Sel.Page1.R3.New 'Radio'
    [29]  DEMO.Sel.Page1.R3.caption„'Clam chowder'
    [30]  DEMO.Sel.Page1.R3.where„6 1
    [31] ©
    [32]  DEMO.Sel.Page2.New 'Page' ª DEMO.Sel.Page2.caption„'Main course'
    [33]  DEMO.Sel.Page2.imageindex„2
    [34]  DEMO.Sel.Page2.R1.New 'Radio'
    [35]  DEMO.Sel.Page2.R1.caption„'Roast duck'
    [36]  DEMO.Sel.Page2.R1.where„2 1
    [37]  DEMO.Sel.Page2.R1.value„1
    [38]  DEMO.Sel.Page2.R2.New 'Radio'
    [39]  DEMO.Sel.Page2.R2.caption„'Grilled steak'
    [40]  DEMO.Sel.Page2.R2.where„4 1
    [41]  DEMO.Sel.Page2.R3.New 'Radio'
    [42]  DEMO.Sel.Page2.R3.caption„'Fresh sea-bass'
    [43]  DEMO.Sel.Page2.R3.where„6 1
    [44] ©
    [45]  DEMO.Sel.Page3.New 'Page'
    [46]  DEMO.Sel.Page3.caption„'Dessert'
    [47]  DEMO.Sel.Page3.imageindex„0 © Use no image for this page
    [48]  DEMO.Sel.Page3.R1.New 'Radio'
    [49]  DEMO.Sel.Page3.R1.caption„'Fresh stawberries'
    [50]  DEMO.Sel.Page3.R1.where„2 1
    [51]  DEMO.Sel.Page3.R1.value„1
    [52]  DEMO.Sel.Page3.R2.New 'Radio'
    [53]   DEMO.Sel.Page3.R2.caption„'Creme caramel'
    [54]  DEMO.Sel.Page3.R2.where„4 1
    [55]  DEMO.Sel.Page3.R3.New 'Radio'
    [56]  DEMO.Sel.Page3.R3.caption„'Baked Alaska'
    [57]  DEMO.Sel.Page3.R3.where„6 1
    [58] ©
    [59] © Wait for the user to close the window
    [60]  0 0½ŒWE DEMO
          ’

### Properties

children class data events handle imagealloc imagecount imagenames imagesize maskcolor methods name opened overlays properties self style tie

### Methods

Addimages Close Create Delete New Open Send Set Trigger

### Callbacks

onClose onDestroy onOpen onSend

Topic: APLX Help : System Classes : List of Classes : ImageList

[ Previous | Next | Contents | Index ]