Method ControlLoadPicture

source/script_gui.cpp:6958–7072

ResultType GuiType::ControlLoadPicture(GuiControlType &aControl, LPTSTR aFilename, int aWidth, int aHeight, int aIconNumber)
{
	// LoadPicture() uses CopyImage() to scale the image, which seems to provide better scaling
	// quality than using MoveWindow() (followed by redrawing the parent window) on the static
	// control that contains the image.
	int image_type;
	HBITMAP new_image = LoadPicture(aFilename, aWidth, aHeight, image_type, aIconNumber
		, aControl.attrib & GUI_CONTROL_ATTRIB_ALTSUBMIT);
	if (!new_image && *aFilename)
		return FAIL; // Caller will report the error.

	// In light of the below, it seems best to delete the bitmaps whenever the control changes
	// to a new image or whenever the control is destroyed.  Otherwise, if a control or its
	// parent window is destroyed and recreated many times, memory allocation would continue
	// to grow from all of the abandoned bitmaps/icons.
	// MSDN: "When you are finished using a bitmap...loaded without specifying the LR_SHARED flag,
	// you can release its associated memory by calling...DeleteObject."
	// MSDN: "The system automatically deletes these resources when the process that created them
	// terminates, however, calling the appropriate function saves memory and decreases the size
	// of the process's working set."
	// v1.0.40.12: For maintainability, destroy the handle returned by STM_SETIMAGE, even though it
	// should be identical to control.union_hbitmap (due to a call to STM_GETIMAGE in another section).
	// UPDATE: This is now done after LoadPicture() is called to reduce the length of time between
	// the background being erased and the new picture being drawn, which might decrease flicker.
	// It's still done as a separate step to setting the new bitmap due to uncertainty about how
	// the control handles changing the image type, and the notes below about animation.
	if (aControl.union_hbitmap)
		if (aControl.attrib & GUI_CONTROL_ATTRIB_ALTBEHAVIOR) // union_hbitmap is an icon or cursor.
			// The control's image is set to NULL for the following reasons:
			// 1) It turns off the control's animation timer in case the new image is not animated.
			// 2) It feels a little bit safer to destroy the image only after it has been removed
			//    from the control.
			// NOTE: IMAGE_ICON or IMAGE_CURSOR must be passed, not IMAGE_BITMAP.  Otherwise the
			// animated property of the control (via a timer that the control created) will remain
			// in effect for the next image, even if it isn't animated, which results in a
			// flashing/redrawing effect:
			DestroyIcon((HICON)SendMessage(aControl.hwnd, STM_SETIMAGE, IMAGE_CURSOR, NULL));
			// DestroyIcon() works on cursors too.  See notes in LoadPicture().
		else // union_hbitmap is a bitmap
			DeleteObject((HGDIOBJ)SendMessage(aControl.hwnd, STM_SETIMAGE, IMAGE_BITMAP, NULL));
	aControl.union_hbitmap = new_image;
	if (!new_image)
	{
		// By design, no error is reported for a blank aFilename.
		// For simplicity, any existing SS_BITMAP/SS_ICON style bit is not removed.
		return OK;
	}
	if (image_type == IMAGE_ICON && aControl.background_color == CLR_TRANSPARENT)
	{
		// Static controls don't appear to support background transparency with icons,
		// so convert the icon to a bitmap.
		if (HBITMAP hbitmap = IconToBitmap32((HICON)aControl.union_hbitmap, false))
		{
			DestroyIcon((HICON)aControl.union_hbitmap);
			aControl.union_hbitmap = hbitmap;
			image_type = IMAGE_BITMAP;
		}
	}