Class: Wx::ArtProvider

Inherits:
Object
  • Object
show all
Defined in:
lib/wx/doc/gen/art_provider.rb

Overview

ArtProvider class is used to customize the look of wxWidgets application.

When wxWidgets needs to display an icon or a bitmap (e.g. in the standard file dialog), it does not use a hard-coded resource but asks ArtProvider for it instead. This way users can plug in their own ArtProvider class and easily replace standard art with their own version. All that is needed is to derive a class from ArtProvider, override either its #create_bitmap and/or its #create_icon_bundle methods and register the provider with ArtProvider.push:

Example:

class MyArtProvider < Wx::ArtProvider
    
    def create_bitmap(id, client, size)
      # ... create and return bitmap
    end

  end

  Wx::ArtProvider.push(MyArtProvider.new)

If you need bitmap images (of the same artwork) that should be displayed at different sizes you should probably consider overriding #create_icon_bundle and supplying icon bundles that contain different bitmap sizes. There’s another way of taking advantage of this class: you can use it in your code and use platform native icons as provided by ArtProvider.get_bitmap_bundle or ArtProvider.get_icon.

Identifying art resources

Every bitmap and icon bundle are known to ArtProvider under a unique ID that is used when requesting a resource from it. The ID is represented by the ArtID type and can have one of these predefined values (you can see bitmaps represented by these constants in the Art Provider Sample):

Note:

When running under GTK+ 2, GTK+ stock item IDs (e.g. "gtk-cdrom") may be used as well: ```ruby if Wx::PLATFORM == 'WXGTK' bmp = Wx::ArtProvider.get_bitmap("gtk-cdrom", Wx::ART_MENU) end ``` For a list of the GTK+ stock items please refer to the GTK+ documentation page. It is also possible to load icons from the current icon theme by specifying their name (without extension and directory components). Icon themes recognized by GTK+ follow the freedesktop.org Icon Themes specification. Note that themes are not guaranteed to contain all icons, so ArtProvider may return NULL_BITMAP or NULL_ICON. The default theme is typically installed in /usr/share/icons/hicolor.

Clients

The client is the entity that calls ArtProvider‘s ArtProvider.get_bitmap or ArtProvider.get_icon function. It is represented by ClientID type and can have one of these values:

Client ID serve as a hint to ArtProvider that is supposed to help it to choose the best looking bitmap. For example it is often desirable to use slightly different icons in menus and toolbars even though they represent the same action (e.g. ART_FILE_OPEN). Remember that this is really only a hint for ArtProvider it is common that ArtProvider.get_bitmap returns identical bitmap for different client values!

Category: Miscellaneous

See Also:

  • Provider Sample for an example of Wx::ArtProvider usage; stock ID list

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Object

#clone, #dup, #initialize, #is_same_as, #un_share

Constructor Details

This class inherits a constructor from Wx::Object

Class Method Details

.delete(provider) ⇒ Boolean

Delete the given provider.

Parameters:

Returns:

  • (Boolean) 


450
 
# File 'lib/wx/doc/gen/art_provider.rb', line 450

def self.delete(provider) end

.get_bitmap(id, client = Wx::ART_OTHER, size = Wx::DEFAULT_SIZE) ⇒ Wx::Bitmap

Query registered providers for bitmap with given ID.

Note that applications using wxWidgets 3.1.6 or later should prefer calling get_bitmap_bundle.

The bitmap if one of registered providers recognizes the ID or NULL_BITMAP otherwise.

Parameters:

  • id (Wx::ArtID) —

    Wx::ArtID unique identifier of the bitmap.

  • client (Wx::ArtClient) (defaults to: Wx::ART_OTHER) —

    Wx::ArtClient identifier of the client (i.e. who is asking for the bitmap).

  • size (Array(Integer, Integer), Wx::Size) (defaults to: Wx::DEFAULT_SIZE) —

    Size of the returned bitmap or DEFAULT_SIZE if size doesn’t matter.

Returns:



461
 
# File 'lib/wx/doc/gen/art_provider.rb', line 461

def self.get_bitmap(id, client=Wx::ART_OTHER, size=Wx::DEFAULT_SIZE) end

.get_bitmap_bundle(id, client = Wx::ART_OTHER, size = Wx::DEFAULT_SIZE) ⇒ Wx::BitmapBundle

Query registered providers for a bundle of bitmaps with given ID.

If any of the registered providers recognizes the ID in its #create_bitmap_bundle, this bundle is returned. Otherwise, if any of providers returns a valid bitmap from #create_bitmap, the bundle containing only this bitmap is returned. Otherwise, an empty bundle is returned.

Parameters:

  • id (Wx::ArtID) —

    Wx::ArtID unique identifier of the bitmap.

  • client (Wx::ArtClient) (defaults to: Wx::ART_OTHER) —

    Wx::ArtClient identifier of the client (i.e. who is asking for the bitmap).

  • size (Array(Integer, Integer), Wx::Size) (defaults to: Wx::DEFAULT_SIZE) —

    Default size for the returned bundle, i.e. the size of the bitmap in normal DPI (this implies that Window#from_dip must not be used with it).

Returns:



470
 
# File 'lib/wx/doc/gen/art_provider.rb', line 470

def self.get_bitmap_bundle(id, client=Wx::ART_OTHER, size=Wx::DEFAULT_SIZE) end

.get_dip_size_hint(client) ⇒ Wx::Size

Returns a suitable size hint for the given Wx::ArtClient in DIPs.

Return the size used by the topmost Wx::ArtProvider for the given client. DEFAULT_SIZE may be returned if the client doesn’t have a specified size, like Wx::ART_OTHER for example.

Parameters:

  • client (Wx::ArtClient)

Returns:

See Also:



506
 
# File 'lib/wx/doc/gen/art_provider.rb', line 506

def self.get_dip_size_hint(client) end

.get_icon(id, client = Wx::ART_OTHER, size = Wx::DEFAULT_SIZE) ⇒ Wx::Icon

Same as get_bitmap, but return a Icon object (or NULL_ICON on failure).

Parameters:

  • id (Wx::ArtID)
  • client (Wx::ArtClient) (defaults to: Wx::ART_OTHER)
  • size (Array(Integer, Integer), Wx::Size) (defaults to: Wx::DEFAULT_SIZE)

Returns:



477
 
# File 'lib/wx/doc/gen/art_provider.rb', line 477

def self.get_icon(id, client=Wx::ART_OTHER, size=Wx::DEFAULT_SIZE) end

.get_icon_bundle(id, client = Wx::ART_OTHER) ⇒ Wx::IconBundle

Query registered providers for icon bundle with given ID.

The icon bundle if one of registered providers recognizes the ID or NULL_ICON_BUNDLE otherwise.

Parameters:

  • id (Wx::ArtID) —

    Wx::ArtID unique identifier of the icon bundle.

  • client (Wx::ArtClient) (defaults to: Wx::ART_OTHER) —

    Wx::ArtClient identifier of the client (i.e. who is asking for the icon bundle).

Returns:



523
 
# File 'lib/wx/doc/gen/art_provider.rb', line 523

def self.get_icon_bundle(id, client=Wx::ART_OTHER) end

.get_message_box_icon(flags) ⇒ Wx::Icon

Helper used by several generic classes: return the icon corresponding to the standard ICON_INFORMATION/WARNING/ERROR/QUESTION flags (only one can be set)

Parameters:

  • flags (Integer)

Returns:



560
 
# File 'lib/wx/doc/gen/art_provider.rb', line 560

def self.get_message_box_icon(flags) end

.get_message_box_icon_id(flags) ⇒ String

Helper used by get_message_box_icon: return the art id corresponding to the standard ICON_INFORMATION/WARNING/ERROR/QUESTION flags (only one can be set)

Parameters:

  • flags (Integer)

Returns:

  • (String) 


555
 
# File 'lib/wx/doc/gen/art_provider.rb', line 555

def self.get_message_box_icon_id(flags) end

.get_native_dip_size_hint(client) ⇒ Wx::Size

Returns native icon size for use specified by client hint in DIPs.

If the platform has no commonly used default for this use or if client is not recognized, returns DEFAULT_SIZE.

Note:

In some cases, a platform may have several appropriate native sizes (for example, Wx::ART_FRAME_ICON for frame icons). In that case, this method returns only one of them, picked reasonably.

Parameters:

  • client (Wx::ArtClient)

Returns:



490
 
# File 'lib/wx/doc/gen/art_provider.rb', line 490

def self.get_native_dip_size_hint(client) end

.get_native_size_hint(client, win = nil) ⇒ Wx::Size

Returns native icon size for use specified by client hint.

This function does the same thing as get_native_dip_size_hint, but uses win to convert the returned value to logical pixels. If win is NULL, default DPI scaling (i.e. that of the primary display) is used.

Parameters:

  • client (Wx::ArtClient)
  • win (Wx::Window) (defaults to: nil)

Returns:



498
 
# File 'lib/wx/doc/gen/art_provider.rb', line 498

def self.get_native_size_hint(client, win=nil) end

.get_size_hint(client, win = nil) ⇒ Wx::Size

Returns a suitable size hint for the given Wx::ArtClient.

This function does the same thing as get_dip_size_hint, but uses win to convert the returned value to logical pixels. If win is NULL, default DPI scaling (i.e. that of the primary display) is used. Note that win parameter is only available since wxWidgets 3.1.6.

Parameters:

  • client (Wx::ArtClient)
  • win (Wx::Window) (defaults to: nil)

Returns:



515
 
# File 'lib/wx/doc/gen/art_provider.rb', line 515

def self.get_size_hint(client, win=nil) end

.has_native_provider ⇒ Boolean

Returns true if the platform uses native icons provider that should take precedence over any customizations.

This is true for any platform that has user-customizable icon themes, currently only WXGTK. A typical use for this method is to decide whether a custom art provider should be plugged in using push or push_back.

Returns:

  • (Boolean) 


530
 
# File 'lib/wx/doc/gen/art_provider.rb', line 530

def self.has_native_provider; end

.pop ⇒ Boolean

Remove latest added provider and delete it.

Returns:

  • (Boolean) 


534
 
# File 'lib/wx/doc/gen/art_provider.rb', line 534

def self.pop; end

.push(provider) ⇒ void

This method returns an undefined value.

Register new art provider and add it to the top of providers stack (i.e.

it will be queried as the first provider).

Parameters:

See Also:



542
 
# File 'lib/wx/doc/gen/art_provider.rb', line 542

def self.push(provider) end

.push_back(provider) ⇒ void

This method returns an undefined value.

Register new art provider and add it to the bottom of providers stack.

In other words, it will be queried as the last one, after all others, including the default provider.

Parameters:

See Also:



550
 
# File 'lib/wx/doc/gen/art_provider.rb', line 550

def self.push_back(provider) end

Instance Method Details

#create_bitmap(id, client, size) ⇒ Wx::Bitmap (protected)

Derived art provider classes may override this method to create requested art resource.

For bitmaps available in more than one size, #create_bitmap_bundle should be overridden instead. Note that returned bitmaps are cached by Wx::ArtProvider and it is therefore not necessary to optimize #create_bitmap for speed (e.g. you may create Bitmap objects from XPMs here).

Note:

This is not part of Wx::ArtProvider's public API, use get_bitmap or get_icon_bundle or get_icon to query Wx::ArtProvider for a resource.

Parameters:

  • id (Wx::ArtID) —

    Wx::ArtID unique identifier of the bitmap.

  • client (Wx::ArtClient) —

    Wx::ArtClient identifier of the client (i.e. who is asking for the bitmap). This only serves as a hint.

  • size (Array(Integer, Integer), Wx::Size) —

    Preferred size of the bitmap. The function may return a bitmap of different dimensions, it will be automatically rescaled to meet client’s request.

Returns:

See Also:



587
 
# File 'lib/wx/doc/gen/art_provider.rb', line 587

def create_bitmap(id, client, size) end

#create_bitmap_bundle(id, client, size) ⇒ Wx::BitmapBundle (protected)

Override this method to create the requested art resources available in more than one size.

Unlike #create_bitmap, this method can be overridden to return the same bitmap in several (or all, if BitmapBundle.from_svg is used) sizes at once, which will allow selecting the size best suited for the current display resolution automatically.

Parameters:

  • id (Wx::ArtID) —

    Wx::ArtID unique identifier of the bitmap.

  • client (Wx::ArtClient) —

    Wx::ArtClient identifier of the client (i.e. who is asking for the bitmap). This only serves as a hint.

  • size (Array(Integer, Integer), Wx::Size) —

    Default size of the bitmaps returned by the bundle.

Returns:



596
 
# File 'lib/wx/doc/gen/art_provider.rb', line 596

def create_bitmap_bundle(id, client, size) end

#create_icon_bundle(id, client) ⇒ Wx::IconBundle (protected)

This method is similar to #create_bitmap but can be used when a bitmap (or an icon) exists in several sizes.

Parameters:

  • id (Wx::ArtID)
  • client (Wx::ArtClient)

Returns:



602
 
# File 'lib/wx/doc/gen/art_provider.rb', line 602

def create_icon_bundle(id, client) end

#do_get_size_hint(client) ⇒ Wx::Size (protected)

Derived art provider classes may override this method to return the size of the images used by this provider.

Note that the returned size should be in DPI-independent pixels, i.e. DIPs. The default implementation returns the result of get_native_dip_size_hint.

Parameters:

  • client (Wx::ArtClient)

Returns:



570
 
# File 'lib/wx/doc/gen/art_provider.rb', line 570

def do_get_size_hint(client) end