docs/latex/wx/artprov.tex

   1 %
   2 % automatically generated by HelpGen $Revision$ from
   3 % artprov.h at 08/Apr/02 17:44:57
   4 %
   5
   6 \section{\class{wxArtProvider}}\label{wxartprovider}
   7
   8 wxArtProvider class is used to customize the look of wxWidgets application.
   9 When wxWidgets need to display an icon or a bitmap (e.g. in the standard file
  10 dialog), it does not use hard-coded resource but asks wxArtProvider for it
  11 instead. This way the users can plug in own wxArtProvider class and easily
  12 replace standard art with his/her own version. It is easy thing to do: all
  13 that is needed is to derive a class from wxArtProvider, override it's
  14 \helpref{CreateBitmap}{wxartprovidercreatebitmap} method and register the
  15 provider with
  16 \helpref{wxArtProvider::PushProvider}{wxartproviderpushprovider}:
  17
  18 \begin{verbatim}
  19   class MyProvider : public wxArtProvider
  20   {
  21   protected:
  22     wxBitmap CreateBitmap(const wxArtID& id,
  23                           const wxArtClient& client,
  24                           const wxSize size)
  25     { ... }
  26   };
  27   ...
  28   wxArtProvider::PushProvider(new MyProvider);
  29 \end{verbatim}
  30
  31 There's another way of taking advantage of this class: you can use it in your code and use
  32 platform native icons as provided by
  33 \helpref{wxArtProvider::GetBitmap}{wxartprovidergetbitmap} or
  34 \helpref{wxArtProvider::GetIcon}{wxartprovidergeticon} (NB: this is not yet really
  35 possible as of wxWidgets 2.3.3, the set of wxArtProvider bitmaps is too
  36 small).
  37
  38 \membersection{Identifying art resources}\label{artprovideridentifying}
  39
  40 Every bitmap is known to wxArtProvider under an unique ID that is used by when
  41 requesting a resource from it. The ID is represented by wxArtID type and can
  42 have one of these predefined values (you can see bitmaps represented by these
  43 constants in the \helpref{artprov}{sampleartprovider} sample):
  44 \begin{itemize}\itemsep=0pt
  45 \item wxART\_ADD\_BOOKMARK
  46 \item wxART\_DEL\_BOOKMARK
  47 \item wxART\_HELP\_SIDE\_PANEL
  48 \item wxART\_HELP\_SETTINGS
  49 \item wxART\_HELP\_BOOK
  50 \item wxART\_HELP\_FOLDER
  51 \item wxART\_HELP\_PAGE
  52 \item wxART\_GO\_BACK
  53 \item wxART\_GO\_FORWARD
  54 \item wxART\_GO\_UP
  55 \item wxART\_GO\_DOWN
  56 \item wxART\_GO\_TO\_PARENT
  57 \item wxART\_GO\_HOME
  58 \item wxART\_FILE\_OPEN
  59 \item wxART\_PRINT
  60 \item wxART\_HELP
  61 \item wxART\_TIP
  62 \item wxART\_REPORT\_VIEW
  63 \item wxART\_LIST\_VIEW
  64 \item wxART\_NEW\_DIR
  65 \item wxART\_FOLDER
  66 \item wxART\_GO\_DIR\_UP
  67 \item wxART\_EXECUTABLE\_FILE
  68 \item wxART\_NORMAL\_FILE
  69 \item wxART\_TICK\_MARK
  70 \item wxART\_CROSS\_MARK
  71 \item wxART\_ERROR
  72 \item wxART\_QUESTION
  73 \item wxART\_WARNING
  74 \item wxART\_INFORMATION
  75 \item wxART\_MISSING\_IMAGE
  76 \end{itemize}
  77
  78 Additionally, any string recognized by custom art providers registered using
  79 \helpref{PushProvider}{wxartproviderpushprovider} may be used.
  80
  81 \wxheading{GTK+ Note}
  82
  83 When running under GTK+ 2, GTK+ stock item IDs (e.g. {\tt "gtk-cdrom"}) may
  84 be used as well. Additionally, if wxGTK was compiled against GTK+ >= 2.4, then
  85 it is also possible to load icons from current icon theme by specifying their
  86 name (without extension and directory components). Icon themes recognized
  87 by GTK+ follow the
  88 \urlref{freedesktop.org Icon Themes specification}{http://freedesktop.org/Standards/icon-theme-spec}. Note that themes are not guaranteed to contain all
  89 icons, so wxArtProvider may return {\tt wxNullBitmap} or {\tt wxNullIcon}.
  90 Default theme is typically installed in {\tt /usr/share/icons/hicolor}.
  91
  92 \membersection{Clients}\label{artproviderclients}
  93
  94 Client is the entity that calls wxArtProvider's GetBitmap or GetIcon
  95 function. It is represented by wxClientID type and can have one of these
  96 values:
  97 \begin{itemize}\itemsep=0pt
  98 \item wxART\_TOOLBAR
  99 \item wxART\_MENU
 100 \item wxART\_BUTTON
 101 \item wxART\_FRAME\_ICON
 102 \item wxART\_CMN\_DIALOG
 103 \item wxART\_HELP\_BROWSER
 104 \item wxART\_MESSAGE\_BOX
 105 \item wxART\_OTHER (used for all requests that don't fit into any of the categories above)
 106 \end{itemize}
 107 Client ID servers as a hint to wxArtProvider that is supposed to help it to
 108 choose the best looking bitmap. For example it is often desirable to use
 109 slightly different icons in menus and toolbars even though they represent the
 110 same action (e.g. {\tt wx\_ART\_FILE\_OPEN}). Remember that this is really
 111 only a hint for wxArtProvider -- it is common that
 112 \helpref{wxArtProvider::GetBitmap}{wxartprovidergetbitmap}
 113 returns identical bitmap for different {\it client} values!
 114
 115 \wxheading{See also}
 116
 117 See the \helpref{artprov}{sampleartprovider} sample for an example of wxArtProvider usage.
 118
 119 \wxheading{Derived from}
 120
 121 \helpref{wxObject}{wxobject}
 122
 123 \wxheading{Include files}
 124
 125 <wx/artprov.h>
 126
 127 \latexignore{\rtfignore{\wxheading{Members}}}
 128
 129 \membersection{wxArtProvider::CreateBitmap}\label{wxartprovidercreatebitmap}
 130
 131 \func{wxBitmap}{CreateBitmap}{\param{const wxArtID\& }{id}, \param{const wxArtClient\& }{client}, \param{const wxSize\& }{size}}
 132
 133 Derived art provider classes must override this method to create requested
 134 art resource. Note that returned bitmaps are cached by wxArtProvider and it is therefore
 135 not necessary to optimize CreateBitmap for speed (e.g. you may create wxBitmap objects
 136 from XPMs here).
 137
 138 \wxheading{Parameters}
 139
 140 \docparam{id}{wxArtID unique identifier of the bitmap.}
 141
 142 \docparam{client}{wxArtClient identifier of the client (i.e. who is asking for the bitmap).
 143 This only servers as a hint.}
 144
 145 \docparam{size}{Preferred size of the bitmap. The function may return a bitmap of different
 146 dimensions, it will be automatically rescaled to meet client's request.}
 147
 148 \wxheading{Note}
 149
 150 This is {\bf not} part of wxArtProvider's public API, use
 151 \helpref{wxArtProvider::GetBitmap}{wxartprovidergetbitmap} or
 152 \helpref{wxArtProvider::GetIcon}{wxartprovidergeticon}
 153 to query wxArtProvider for a resource.
 154
 155 \membersection{wxArtProvider::GetBitmap}\label{wxartprovidergetbitmap}
 156
 157 \func{static wxBitmap}{GetBitmap}{\param{const wxArtID\& }{id}, \param{const wxArtClient\& }{client = wxART\_OTHER}, \param{const wxSize\& }{size = wxDefaultSize}}
 158
 159 Query registered providers for bitmap with given ID.
 160
 161 \wxheading{Parameters}
 162
 163 \docparam{id}{wxArtID unique identifier of the bitmap.}
 164
 165 \docparam{client}{wxArtClient identifier of the client (i.e. who is asking for the bitmap).}
 166
 167 \docparam{size}{Size of the returned bitmap or {\tt wxDefaultSize} if size doesn't matter.}
 168
 169 \wxheading{Return value}
 170
 171 The bitmap if one of registered providers recognizes the ID or wxNullBitmap otherwise.
 172
 173 \membersection{wxArtProvider::GetIcon}\label{wxartprovidergeticon}
 174
 175 \func{static wxIcon}{GetIcon}{\param{const wxArtID\& }{id}, \param{const wxArtClient\& }{client = wxART\_OTHER}, \param{const wxSize\& }{size = wxDefaultSize}}
 176
 177 Same as \helpref{wxArtProvider::GetBitmap}{wxartprovidergetbitmap}, but
 178 return a wxIcon object (or wxNullIcon on failure).
 179
 180 \membersection{wxArtProvider::PopProvider}\label{wxartproviderctor}
 181
 182 \func{static bool}{PopProvider}{\void}
 183
 184 Remove latest added provider and delete it.
 185
 186 \membersection{wxArtProvider::PushProvider}\label{wxartproviderpushprovider}
 187
 188 \func{static void}{PushProvider}{\param{wxArtProvider* }{provider}}
 189
 190 Register new art provider (add it to the top of providers stack).
 191
 192 \membersection{wxArtProvider::RemoveProvider}\label{wxartproviderremoveprovider}
 193
 194 \func{static bool}{RemoveProvider}{\param{wxArtProvider* }{provider}}
 195
 196 Remove a provider from the stack. The provider must have been added previously
 197 and is {\it not} deleted.
 198