Clase wxBitmapBundle
Contiene representaciones del mismo mapa de bits en diferentes resoluciones.
Esta clase generaliza wxBitmap para aplicaciones que soportan múltiples DPIs y permite operar con múltiples versiones del mismo bitmap, en los tamaños apropiados a la resolución de pantalla utilizada actualmente, como una única unidad. En particular, un wxBitmapBundle completo se puede pasar a funciones como wxToolBar::AddTool() para permitir que la barra de herramientas seleccione el mejor mapa de bits disponible para ser mostrado.
Los objetos de esta clase suelen ser creados por la aplicación y luego pasados a las funciones de wxWidgets, pero no son utilizados por la propia aplicación. Actualmente los paquetes bitmap pueden ser creados desde:
- Un vector de mapas de bits, de cualquier procedencia.
- Un SVG (como bloque de memoria, archivo o recurso) que se rasterizará a las resoluciones requeridas.
- Una fuente de mapa de bits personalizada utilizando wxBitmapBundleImpl.
- Un único wxBitmap o wxImage para compatibilidad con versiones anteriores.
Los objetos de la clase wxBitmapBundle tienen una semántica similar a la de los valores, es decir, se pueden copiar libremente (y a bajo coste) y no necesitan ser asignados al montón. Sin embargo, normalmente se crean utilizando funciones de construcción estáticas (conocidas como "pseudoconstructores") como FromBitmaps() en lugar de utilizar los constructores reales.
Ejemplo de uso de esta clase para inicializar una barra de herramientas en un constructor de marco:
MyFrame::MyFrame()
: wxFrame(nullptr, wxID_ANY, "My frame")
{
...
wxToolBar* toolBar = CreateToolBar();
wxVector<wxBitmap> bitmaps;
bitmaps.push_back(wxBITMAP_PNG(open_32x32));
bitmaps.push_back(wxBITMAP_PNG(open_48x48));
bitmaps.push_back(wxBITMAP_PNG(open_64x64));
toolBar->AddTool(wxID_OPEN, "Open", wxBitmapBundle::FromBitmaps(bitmaps));
}
El código mostrado arriba utilizará un mapa de bits de 32 píxeles en PPP normal, un mapa de bits de 64 píxeles en "PPP alto", es decir, duplicación de píxeles o resolución del 200%, y un mapa de bits de 48 píxeles en resolución del 150%. Para el resto de resoluciones, se utilizará el mapa de bits con el "mejor" tamaño coincidente, entendiendo por "mejor" el mapa de bits con el tamaño más cercano si puede utilizarse sin escalado (de modo que, en este ejemplo, el mapa de bits de 64px se utilizará con una resolución del 175%, ya que normalmente se ve mucho mejor que reduciéndolo o aumentando la escala del mapa de bits de 48px a 56px) o, si no hay ningún mapa de bits con un tamaño lo suficientemente cercano, se utilizará un mapa de bits aumentado con un factor de escalado entero. Hay que tener en cuenta que los paquetes de mapas de bits personalizados pueden utilizar un algoritmo diferente para seleccionar la mejor coincidencia anulando wxBitmapBundleImpl::GetPreferredBitmapSizeAtScale().
Por supuesto, este código depende de tener realmente los recursos con los nombres correspondientes (es decir, open_NxN) en el archivo .rc de MSW o en el paquete de aplicaciones de Mac y que las matrices open_NxN_png estén definidas en el código del programa, por ejemplo, incluyendo un archivo generado con bin2c (véase wxBITMAP_PNG_FROM_DATA()), en las otras plataformas.
Para las plataformas con soporte de recursos, también se puede crear el bundle a partir de los bitmaps definidos en los recursos, lo que tiene la ventaja de no tener que listar explícitamente todos los bitmaps, por ejemplo, el código anterior se convierte en
#ifdef wxHAS_IMAGE_RESOURCES
toolBar->AddTool(wxID_OPEN, "Open", wxBitmapBundle::FromResources("open"));
#else
... same code as shown above ...
#endif
y cargará todos los recursos llamados open, open_2x, open_1_5x etc (al menos el primero de ellos debe estar disponible). Véase también la macro wxBITMAP_BUNDLE_2() que puede evitar la necesidad de comprobar wxHAS_IMAGE_RESOURCES explícitamente en el código en un caso común de tener sólo 2 recursos incrustados (para DPI estándar y alto). Véase también FromSVGResource().
También hay que tener en cuenta que el código existente que utiliza wxBitmap es compatible con las funciones que toman wxBitmapBundle en wxWidgets 3.1.6 y posteriores porque los mapas de bits son implícitamente convertibles a los objetos de esta clase, por lo que simplemente pasar wxBitmap a las funciones que toman wxBitmapBundle sigue funcionando y si las versiones de alta resolución de mapa de bits no están (todavía) disponibles para las otras herramientas de la barra de herramientas, los mapas de bits simples pueden seguir utilizándose en su lugar.
Funciones miembro
wxBitmapBundle()
wxBitmapBundle::wxBitmapBundle()
El constructor por defecto construye un paquete vacío.
Un paquete vacío no se puede utilizar para nada, pero se le puede asignar algo más tarde.
wxBitmapBundle()
wxBitmapBundle::wxBitmapBundle(const wxBitmap & bitmap)
Constructor de conversión a partir de un único mapa de bits.
Este constructor hace lo mismo que FromBitmap() y solo existe para la interoperabilidad con el código existente utilizando wxBitmap.
wxBitmapBundle()
wxBitmapBundle::wxBitmapBundle(const wxIcon & icon)
Constructor de conversión a partir de un único icono.
Este constructor hace lo mismo que FromBitmap() y solo existe para la interoperabilidad con el código existente utilizando wxIcon.
wxBitmapBundle()
wxBitmapBundle::wxBitmapBundle(const wxImage & image)
Constructor de conversión a partir de una única imagen.
Al igual que el constructor de wxBitmap, este constructor sólo existe para la interoperabilidad con el código existente utilizando wxImage y puede ser sustituido por FromImage() más legible en el nuevo código.
wxBitmapBundle()
wxBitmapBundle::wxBitmapBundle(const char *const * xpm)
Constructor de conversión a partir de datos XPM.
Esta sobrecarga del constructor existe solo por compatibilidad con el código existente que pasa datos XPM (por ejemplo, foo_xpm después de incluir foo.xpm) directamente a las funciones que esperan un mapa de bits. No utilizarlo en el código nuevo, ya que es probable que quede obsoleto en el futuro.
wxBitmapBundle()
wxBitmapBundle::wxBitmapBundle(const wxBitmapBundle & other)
El constructor Copy crea una copia de otro bundle.
Clear()
void wxBitmapBundle::Clear()
Borra el contenido del paquete existente.
Después de llamar a esta función IsOk() devuelve false.
Esto es lo mismo que asignar un paquete de mapa de bits construido por defecto a este objeto, pero ligeramente más explícito.
FromBitmap()
static wxBitmapBundle wxBitmapBundle::FromBitmap(const wxBitmap & bitmap)
Crea un paquete a partir de un único mapa de bits.
Esto solo es útil por compatibilidad con el código existente que utiliza wxBitmap.
Si el mapa de bits no es válido, se devuelve un paquete vacío.
FromBitmaps()
Crea un paquete a partir de la colección de mapas de bits dada.
Si el vector de mapas de bits está vacío, se devuelve un paquete vacío no válido; de lo contrario, se inicializa el paquete con todos los mapas de bits de este vector, que deben ser válidos.
FromBitmaps()
static wxBitmapBundle wxBitmapBundle::FromBitmaps( const wxBitmap & bitmap1, const wxBitmap & bitmap2 )
Esta es una función miembro sobrecargada, proporcionada por conveniencia. Solo difiere de la función anterior en los argumentos que acepta.
FromFiles()
static wxBitmapBundle wxBitmapBundle::FromFiles( const wxString & path, const wxString & filename, const wxString & extension = "png" )
Crea un paquete a partir de mapas de bits almacenados como archivos.
Busca archivos en la ruta utilizando el nombre de archivo como prefijo y, potencialmente, un sufijo con escala, por ejemplo, "_2x" o "@2x".
Parámetros
- path
- Ruta del directorio que contiene los archivos
- filename
- Nombre del mapa de bits sin sufijo de escala
- extension
- Extensión del archivo, sin el punto inicial (png por defecto)
FromFiles()
static wxBitmapBundle wxBitmapBundle::FromFiles(const wxString & fullpathname)
Esta es una función miembro sobrecargada, proporcionada por conveniencia. Solo difiere de la función anterior en los argumentos que acepta.
FromIconBundle()
static wxBitmapBundle wxBitmapBundle::FromIconBundle(const wxIconBundle & iconBundle)
Crea un paquete a partir de un paquete de iconos.
Si iconBundle no es válido o está vacío, se devuelve un paquete vacío.
FromImage()
static wxBitmapBundle wxBitmapBundle::FromImage(const wxImage & image)
Crea un paquete a partir de una sola imagen.
Esto solo es útil por compatibilidad con el código existente que utiliza wxImage.
Si la imagen no es válida, se devuelve un paquete vacío.
FromImpl()
static wxBitmapBundle wxBitmapBundle::FromImpl(wxBitmapBundleImpl * impl)
Crea un paquete a partir de la implementación de un paquete de mapas de bits personalizado.
Esta función se puede utilizar para crear paquetes que implementen una lógica personalizada para crear los mapas de bits, por ejemplo, creándolos sobre la marcha en lugar de utilizar mapas de bits predefinidos.
Ver wxBitmapBundleImpl.
Parámetros
- impl
- Un puntero válido, es decir, no nulo. Esta función toma posesión de él, por lo que el llamante no debe llamar a DecRef() sobre él.
FromResources()
static wxBitmapBundle wxBitmapBundle::FromResources(const wxString & name)
Crea un paquete a partir de los mapas de bits de los recursos de la aplicación.
Esta función solo se puede utilizar en las plataformas que admiten el almacenamiento de mapas de bits en recursos, y actualmente solo funciona en MSW y MacOS y devuelve un paquete vacío en las demás plataformas.
En MSW, para que esta función cree un paquete válido, debe haber un recurso RCDATA con el nombre indicado en el archivo de recursos de la aplicación (con la extensión .rc) que contenga el archivo PNG, y cualquier otro recurso que utilice el nombre como prefijo y sufijo con la escala, por ejemplo, "_2x" o "_1_5x" (para 150% DPI) también se cargará como parte del paquete.
FromSVG()
static wxBitmapBundle wxBitmapBundle::FromSVG( char * data, const wxSize & sizeDef )
Crea un paquete a partir de la imagen SVG.
Hay que tenera en cuenta que la implementación actual utiliza la biblioteca NanoSVG (https://github.com/memononen/nanosvg) para analizar y rasterizar imágenes SVG, lo que impone las siguientes limitaciones:
- Los elementos de texto no son compatibles en absoluto.
- Los filtros SVG 1.1 no son compatibles.
Estas limitaciones se relajarán en las futuras versiones de wxWidgets.
Hay que tener en cuenta también que este método solo está disponible en los ports que proporcionan acceso a mapas de bits sin procesar a través de wxPixelData. Este es el caso de todos los ports tier-1, pero no de todos, comprueba si wxHAS_SVG está definido antes de usar este método si quieres la máxima portabilidad.
Parámetros
- data
- Este dato puede, o no, tener el preámbulo del documento XML, es decir, puede empezar con la instrucción de procesamiento "<?xml" o directamente con la etiqueta svg. Para cadenas terminadas en NUL, se proporcionan dos sobrecargas de esta función, que toman datos constantes y no constantes: como la implementación actual modifica los datos durante el análisis sintáctico, usar la variante no constante es más eficiente, ya que evita hacer copia de los datos, pero los datos son consumidos por ella y ya no pueden reutilizarse. Para datos no terminados en NUL, debe usarse la tercera sobrecarga, que toma un parámetro extra especificando explícitamente la longitud de los datos de entrada.
- sizeDef
- El tamaño por defecto que devuelve GetDefaultSize() para este paquete. Como las imágenes SVG no suelen tener un tamaño predeterminado natural, debe indicarse al crear el paquete.
FromSVG()
static wxBitmapBundle wxBitmapBundle::FromSVG( const char * data, const wxSize & sizeDef )
Esta es una función miembro sobrecargada, proporcionada por conveniencia. Solo difiere de la función anterior en los argumentos que acepta.
FromSVG()
static wxBitmapBundle wxBitmapBundle::FromSVG( const wxByte * data, size_t len, const wxSize & sizeDef )
Esta es una función miembro sobrecargada, proporcionada por conveniencia. Solo difiere de la función anterior en los argumentos que acepta.
FromSVGFile()
Crea un paquete a partir de la imagen SVG cargada desde el archivo dado.
Esta función carga los datos SVG desde la ruta dada y llama a FromSVG() con ellos. Como es solo una envoltura para FromSVG(), por favor ver la documentación de esa función para más información sobre el soporte SVG.
Parámetros
- path
- Ruta al archivo SVG. Tenga en cuenta que debe ser un archivo local, no una URL.
- sizeDef
- El tamaño por defecto devuelto por GetDefaultSize() para este paquete.
FromSVGResource()
static wxBitmapBundle wxBitmapBundle::FromSVGResource( const wxString & name, const wxSize & sizeDef )
Crea un paquete a partir de la imagen SVG cargada desde un recurso de aplicación.
Disponible solo en las plataformas que admiten imágenes en recursos, es decir, MSW y MacOS.
Parámetros
- name
- En MSW, debe ser un recurso de tipo RT_RCDATA. En MacOS, debe ser un archivo con extensión "svg" situado en el subdirectorio "Resources" del paquete de la aplicación.
- sizeDef
- El tamaño por defecto devuelto por GetDefaultSize() para este paquete.
GetBitmap()
Obtiene el bitmap del tamaño especificado, creando un nuevo bitmap a partir del tamaño disponible más cercano reescalándolo si es necesario.
Esta función es utilizada principalmente por el propio wxWidgets y no por la aplicación. Como todos los bitmaps creados por ella dinámicamente se almacenan actualmente en caché, evita llamarla para muchos tamaños diferentes si la utilizas, ya que esto creará muchos bitmaps que nunca se borrarán y consumirán recursos hasta la terminación de la aplicación.
Parámetros
- size
- El tamaño del mapa de bits a devolver, en píxeles físicos. Si este parámetro es wxDefaultSize, se utilizará el tamaño por defecto del paquete.
GetBitmapFor()
Obtiene un mapa de bits del tamaño apropiado para el escalado DPI utilizado por la ventana dada.
Esta función de ayuda simplemente combina GetPreferredBitmapSizeFor() y GetBitmap(), es decir, devuelve un mapa de bits (normalmente sin escalar) del paquete del tamaño más cercano al que debería utilizarse en el escalado DPI de la ventana proporcionada.
Parámetros
- window
- Ventana no nula y completamente creada.
GetDefaultSize()
wxSize wxBitmapBundle::GetDefaultSize() const
Obtiene el tamaño del mapa de bits representado por este paquete en la resolución predeterminada o, lo que es equivalente, con una escala del 100%.
Cuando se crea el paquete a partir de varios mapas de bits, éste será sólo el tamaño del mapa de bits más pequeño que contenga.
Hay que tener en cuenta que esta función es utilizada principalmente por wxWidgets y no por la aplicación.
GetIcon()
Obtiene un icono del tamaño especificado.
Esto es solo una envoltura conveniente para GetBitmap() y simplemente convierte el mapa de bits devuelto a wxIcon.
GetIconFor()
Obtiene un icono del tamaño apropiado para el escalado DPI utilizado por la ventana dada.
Es similar a GetBitmapFor(), pero devuelve un wxIcon, como hace GetIcon().
Parámetros
- window
- Ventana no nula y completamente creada.
GetPreferredBitmapSizeAtScale()
wxSize wxBitmapBundle::GetPreferredBitmapSizeAtScale(double scale) const
Obtiene el tamaño que sería mejor utilizar para este paquete con el factor de escala de DPI dado.
Para los paquetes que contienen algún número de mapas de bits de tamaño fijo, esta función devuelve el tamaño de un mapa de bits existente más cercano al tamaño ideal a la escala dada, es decir, GetDefaultSize() multiplicado por la escala.
Pasar un tamaño devuelto por esta función a GetBitmap() garantiza que el mapa de bits no necesite ser reescalado, lo que normalmente reduce significativamente su calidad.
GetPreferredBitmapSizeFor()
Obtiene el tamaño que sería mejor utilizar para este paquete en el factor de escala DPI utilizado por la ventana dada.
Esto es sólo una envoltura conveniente para GetPreferredBitmapSizeAtScale() llamando a esa función con el resultado de wxWindow::GetDPIScaleFactor().
Parámetros
- window
- Ventana no nula y completamente creada.
GetPreferredLogicalSizeFor()
Obtiene el tamaño que sería mejor utilizar para este paquete en el factor de escala DPI utilizado por la ventana dada.
Esto es solo una envoltura conveniente para GetPreferredBitmapSizeAtScale() llamando a esa función con el resultado de wxWindow::GetDPIScaleFactor().
Parámetros
- window
- Ventana no nula y completamente creada.
IsOk()
bool wxBitmapBundle::IsOk() const
Comprueba si el paquete de mapas de bits no está vacío.
Devuelve true si el paquete contiene algún mapa de bits o false si está vacío.
IsSameAs()
bool wxBitmapBundle::IsSameAs(const wxBitmapBundle & other) const
Comprueba si los dos paquetes se refieren al mismo objeto.
Los paquetes solo se consideran iguales si utilizan el mismo objeto subyacente, es decir, si son copias el uno del otro. Si los dos paquetes se han creado de forma independiente, no se considerarán iguales, aunque se hayan creado a partir del mismo mapa de bits.
Operadores
operator=()
wxBitmapBundle& wxBitmapBundle::operator=(const wxBitmapBundle & other)
El operador de asignación convierte este paquete en una copia de otro paquete.