wxWidgets/include/wx/withimages.h

///////////////////////////////////////////////////////////////////////////////
// Name:        wx/withimages.h
// Purpose:     Declaration of a simple wxWithImages class.
// Author:      Vadim Zeitlin
// Created:     2011-08-17
// Copyright:   (c) 2011 Vadim Zeitlin <vadim@wxwidgets.org>
// Licence:     wxWindows licence
///////////////////////////////////////////////////////////////////////////////

#ifndef _WX_WITHIMAGES_H_
#define _WX_WITHIMAGES_H_

#include "wx/defs.h"
#include "wx/bmpbndl.h"
#include "wx/icon.h"
#include "wx/imaglist.h"
#include "wx/vector.h"

class WXDLLIMPEXP_FWD_CORE wxWindow;

// ----------------------------------------------------------------------------
// wxWithImages: mix-in for classes using indices for image access
// ----------------------------------------------------------------------------

class WXDLLIMPEXP_CORE wxWithImages
{
public:
    enum
    {
        NO_IMAGE = -1
    };

    typedef wxVector<wxBitmapBundle> Images;

    wxWithImages()
    {
        m_imageList = NULL;
        m_ownsImageList = false;
    }

    virtual ~wxWithImages()
    {
        FreeIfNeeded();
    }

    // Return the number of images, possibly 0.
    int GetImageCount() const
    {
        if ( !m_images.empty() )
        {
            // Cast is safe, we don't risk having more than INT_MAX images.
            return static_cast<int>(m_images.size());
        }

        return m_imageList ? m_imageList->GetImageCount() : 0;
    }

    // Return true if we are using any images.
    bool HasImages() const
    {
        // Note that the sole presence of the image list indicates that we're
        // using images, even if it is currently empty, because images can be
        // added to it at any moment (it's common and valid to create an image
        // list and associate it with the control first and fill it later) and
        // it's better to err on the side of having the images and not showing
        // anything if there are really none than decide that we don't have any
        // and not show those that we do have.
        return !m_images.empty() || m_imageList;
    }

    // Sets the images to use.
    //
    // Override OnImagesChanged() in the derived class to update the actually
    // shown images.
    void SetImages(const Images& images)
    {
        m_images = images;

        OnImagesChanged();
    }

    // Sets the image list to use, it is *not* deleted by the control.
    //
    // This function is virtual for compatibility, as it could be overridden in
    // the existing application code, however it should not be overridden in wx
    // itself, where OnImagesChanged() should be overridden instead.
    virtual void SetImageList(wxImageList* imageList)
    {
        FreeIfNeeded();
        m_imageList = imageList;

        OnImagesChanged();
    }

    // As SetImageList() but we will delete the image list ourselves.
    void AssignImageList(wxImageList* imageList)
    {
        SetImageList(imageList);
        m_ownsImageList = true;
    }

    // This function can be used for implementing AssignImageList()-like
    // methods in the classes using this one and tells us to simply take
    // ownership of the image list that we already have.
    //
    // Avoid using it if possible.
    void TakeOwnership() { m_ownsImageList = true; }

    // Get pointer (may be NULL) to the associated image list.
    wxImageList* GetImageList() const { return m_imageList; }

    // This helper function can be used from OnImagesChanged() if the derived
    // class actually needs to use wxImageList: it ensures that m_imageList is
    // updated from m_images, if the latter is not empty, using the images of
    // the appropriate size for the given window, and returns it.
    wxImageList* GetUpdatedImageListFor(wxWindow* win)
    {
        if ( !m_images.empty() )
        {
            // Note that we can't just call AssignImageList() here to avoid
            // infinite recursion.
            FreeIfNeeded();
            m_imageList = wxBitmapBundle::CreateImageList(win, m_images);

            // We always own it as we created it ourselves.
            m_ownsImageList = true;
        }

        return m_imageList;
    }

#if wxABI_VERSION >= 30202
    // Return logical size of the image to use or (0, 0) if there are none.
    wxSize GetImageLogicalSize(const wxWindow* window, int iconIndex) const
    {
        wxSize size;

        if ( iconIndex != NO_IMAGE )
        {
            if ( !m_images.empty() )
            {
                size = m_images.at(iconIndex).GetPreferredLogicalSizeFor(window);
            }
            else if ( m_imageList )
            {
                // All images in the image list are of the same size.
                size = m_imageList->GetSize();
            }
        }

        return size;
    }

    // Overload provided to facilitate transition from the existing code using
    // wxImageList::GetSize() -- don't use it in the new code.
    void GetImageLogicalSize(const wxWindow* window, int iconIndex,
                             int& width, int& height) const
    {
        const wxSize size = GetImageLogicalSize(window, iconIndex);
        width = size.x;
        height = size.y;
    }

    // Return the bitmap to use at the current DPI of the given window.
    //
    // If index == NO_IMAGE, just returns wxNullBitmap.
    wxBitmap GetImageBitmapFor(const wxWindow* window, int iconIndex) const
    {
        wxBitmap bitmap;

        if ( iconIndex != NO_IMAGE )
        {
            if ( !m_images.empty() )
            {
                bitmap = m_images.at(iconIndex).GetBitmapFor(window);
            }
            else if ( m_imageList )
            {
                bitmap = m_imageList->GetBitmap(iconIndex);
            }
            else
            {
                wxFAIL_MSG
                (
                    "Image index specified, but there are no images.\n"
                    "\n"
                    "Did you forget to call SetImages()?"
                );
            }
        }

        return bitmap;
    }
#endif // wxABI_VERSION >= 3.2.2

protected:
    // This function is called when the images associated with the control
    // change, due to either SetImages() or SetImageList() being called.
    //
    // It ought to be pure virtual, but isn't because there could be existing
    // application code inheriting from this class and not overriding it
    // (because this function hadn't existed when this code was written).
    virtual void OnImagesChanged() { }

    // This function can be used as event handle for wxEVT_DPI_CHANGED event
    // and simply calls OnImagesChanged() to refresh the images when it happens.
    void WXHandleDPIChanged(wxDPIChangedEvent& event)
    {
        if ( HasImages() )
            OnImagesChanged();

        event.Skip();
    }


    // Return true if we have a valid image list.
    bool HasImageList() const { return m_imageList != NULL; }

    // Return the image with the given index from the image list.
    //
    // If there is no image list or if index == NO_IMAGE, silently returns
    // wxNullIcon.
    wxIcon GetImage(int iconIndex) const
    {
        return m_imageList && iconIndex != NO_IMAGE
                    ? m_imageList->GetIcon(iconIndex)
                    : wxNullIcon;
    }

    // Return the bitmap bundle for the image with the given index.
    //
    // If index == NO_IMAGE or there are no images at all, returns an empty
    // bundle (but, unlike GetImage() above, asserts if the index is valid but
    // there is no image, as this probably indicates a programming mistake).
    //
    // If there is no bundle, but there is an image list, returns a bundle
    // containing just the bitmap from the image list.
    wxBitmapBundle GetBitmapBundle(int iconIndex) const
    {
        wxBitmapBundle bundle;

        if ( iconIndex != NO_IMAGE )
        {
            if ( !m_images.empty() )
            {
                bundle = m_images.at(iconIndex);
            }
            else if ( m_imageList )
            {
                bundle = m_imageList->GetIcon(iconIndex);
            }
            else
            {
                wxFAIL_MSG
                (
                    "Image index specified, but there are no images.\n"
                    "\n"
                    "Did you forget to call SetImages()?"
                );
            }
        }

        return bundle;
    }

    // Accessor to the images for the derived classes: this is only useful when
    // delegating SetImages() to another object.
    const Images& GetImages() const { return m_images; }

private:
    // Free the image list if necessary, i.e. if we own it.
    void FreeIfNeeded()
    {
        if ( m_ownsImageList )
        {
            delete m_imageList;
            m_imageList = NULL;

            // We don't own it any more.
            m_ownsImageList = false;
        }
    }


    // The images we use: if this vector is not empty, m_imageList is not used.
    Images m_images;

    // The associated image list or NULL.
    wxImageList* m_imageList;

    // False by default, if true then we delete m_imageList.
    bool m_ownsImageList;

    wxDECLARE_NO_COPY_CLASS(wxWithImages);
};

#endif // _WX_WITHIMAGES_H_