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