logo

Icons, Images and Title.

Changing the default program title and icon, as well as adding menu icons, can enhance the professional appearance of your program. Below are various methods to make these changes.

Note: I tend to use the following terms interchangeably when referring to image pointers, references, and handles.

Program Icon and Title

Setting custom text for the Title Bar and adding an icon to the application (displayed in the Taskbar and Title Bar) is straightforward.
Add the following two lines at the top of your program:

$EXEICON = 'path/to/icon-image'
_TITLE "Your title bar text"

The following example assumes that the image ICO file "mg_32.ico" is placed in the QB64pe folder:

$EXEICON:'mg_32.ico'
_TITLE "Run Apache and MySQL"

The $EXEICON directive is a pre-compiler metacommand that embeds a designated icon file into the compiled EXE file. This icon is displayed in Windows Explorer. Your program window will automatically use the icon embedded by $EXEICON without having to call _ICON.

Note 1: The icon image must be in .ico format, and the path should be correct; otherwise, the program won't compile (error message "file not found").
Note 2: If you find it difficult to create an .ico file, you can use an online free service such as https://convertico.com/ . This allows you to convert a PNG to an ICO file.
Note 3: Place the image "mg_32.ico" in your project folder. If you are not using a project folder, locate the image in the folder that contains the qb64pe.exe executable.

Program Icon use PNG image

As an alternative to the above, you can use a PNG image directly using the _ICON statement.
The _ICON statement utilizes the image handle returned from _LOADIMAGE.

i& = _LoadImage("iconD.png", 32) ' use your image file name here
If i& < -1 Then '                  is a valid image
    _Icon i& '                     pass handle to _Icon loads image
    _FreeImage i& '                release image handle after setting icon
End If

Note 1: The image must be distributed with the .exe application. You can avoid this by embeding the image; see Extract image to memory return image pointer
Note 2: Icon files are not supported with _LOADIMAGE; if you attempt to use them, an error will occur.
Note 3: Place the image iconD.png in your project folder. If you are not using a project folder, locate the image in the folder that contains the qb64pe.exe executable.

Embed image.

You can avoid the need to include images with your application by embedding them into the application using the $EMBED metacommand.

$EMBED:'filename','handle'
This command integrates the image into the executable at compile time. Note that you can embed any file, such as images, sounds, fonts, and all other file types.
The following is an example of embedding an image:
$Embed:'.\iconD.png','mpg1' 

The path to the image . refers to the current folder for the image named iconD.png to be embedded. Following this is a unique identifier mpg1 (handle) specific to the $Embed and _Embedded$ commands. It is case-sensitive, must begin with a letter, and may only contain lower or uppercase letters and/or numbers.

Extract embedded image

To extract the embedded file, you use the _EMBEDDED$ function:

filedata$ = _EMBEDDED$("handle")

The filedata$ variable will receive the embedded data as a single contiguous string. The unique identifier (handle) is specific to $Embed and _Embedded$ commands. It is case-sensitive, must begin with a letter, and may only contain lower or uppercase letters and/or numbers.

Extract image to memory return image pointer

As mentioned earlier, you extract the embedded image file using the _EMBEDDED$ function and save the data to a variable such as filedata$.
The LOADIMAGE function can then use this data to create an image in memory and return its corresponding handle. A complete example is provided below:

$Embed:'.\iconD.png','mpg1'

Dim pic1 As Long '                                    define a pointer variable
pic1 = _LoadImage(_Embedded$("mpg1"), 32, "memory") ' save handle returned by _LoadImage mpg1=handle 32=bit-image memory=buffer
_Icon pic1 '                                          example of using, pass handle to _Icon, loads image

Extract embedded image and save to disk

As mentioned above, you extract the embedded image file using the _EMBEDDED$ function and save the data to a string variable such as str1.
This variable will receive the embedded file data as a single contiguous string, which can be written back to disk using a binary write operation, for example:


  filename = "toolbox_picture_box1.png" '       original name
  str1 = _Embedded$("mpg1") '                   set str1 to extracted embeded data string
  Open filename For Binary As #2 '              open file for binary output  
  Put #2, , str1 '                              write string data to file           
  Close #2 '                                    close file handle          
 

Inform image information

This section covers various methods of copying images to Inform applications and provides other relevant information.

Inform image sizes

The image size for buttons can be any size, as they are automatically resized to fit the button. Generally, it is recommended to keep the height the same as the button size.

For MenuItems, the image size should be 16x16 pixels.

LoadImage method

The LoadImage method is utilized to load a valid image file into a control's helper canvas. This method is commonly employed to assign icons to buttons or menu items, as well as to assign an image file to a PictureBox control.

Usage example:

LoadImage Control(ControlID), ImageFile$

If the specified ImageFile$ cannot be found or is not a valid image, one of the following outcomes will occur:

To reset a control's canvas, pass an empty ImageFile$ parameter to the LoadImage method:

LoadImage Control(ControlID), ""

Note: The LoadImage method uses a file path and name (ImageFile$) to locate the image; an alternative method is to use the control's helper canvas property, which utilizes a pointer (reference) to the image. For more information, refer to the details below.

Helper canvas and image pointer

The LoadImage method described above requires a file path to an image. However, if you have a pointer (reference) to the image, you can utilize the HelperCanvas property instead. Please refer to the example below.


Control(ControlID).HelperCanvas = image_ptr&

For an embedded image, you can extract this pinter using _Loadimage. For details, refer to the section above titled Extract image to memory return image pointer

.