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 needs to display an icon or a bitmap (e.g. in the standard file
  10 dialog), it does not use a hard-coded resource but asks wxArtProvider for it
  11 instead. This way users can plug in their own wxArtProvider class and easily
  12 replace standard art with their own version. All
  13 that is needed is to derive a class from wxArtProvider, override its
  14 \helpref{CreateBitmap}{wxartprovidercreatebitmap} method and register the
  15 provider with
  16 \helpref{wxArtProvider::Push}{wxartproviderpush}:
  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::Push(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 \helpref{wxArtProvider::GetBitmap}{wxartprovidergetbitmap} or
  33 \helpref{wxArtProvider::GetIcon}{wxartprovidergeticon} (NB: this is not yet really
  34 possible as of wxWidgets 2.3.3, the set of wxArtProvider bitmaps is too
  35 small).
  36
  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{Push}{wxartproviderpush} 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
  93 \membersection{Clients}\label{artproviderclients}
  94
  95 Client is the entity that calls wxArtProvider's GetBitmap or GetIcon
  96 function. It is represented by wxClientID type and can have one of these
  97 values:
  98 \begin{itemize}\itemsep=0pt
  99 \item wxART\_TOOLBAR
 100 \item wxART\_MENU
 101 \item wxART\_BUTTON
 102 \item wxART\_FRAME\_ICON
 103 \item wxART\_CMN\_DIALOG
 104 \item wxART\_HELP\_BROWSER
 105 \item wxART\_MESSAGE\_BOX
 106 \item wxART\_OTHER (used for all requests that don't fit into any of the categories above)
 107 \end{itemize}
 108 Client ID servers as a hint to wxArtProvider that is supposed to help it to
 109 choose the best looking bitmap. For example it is often desirable to use
 110 slightly different icons in menus and toolbars even though they represent the
 111 same action (e.g. {\tt wx\_ART\_FILE\_OPEN}). Remember that this is really
 112 only a hint for wxArtProvider -- it is common that
 113 \helpref{wxArtProvider::GetBitmap}{wxartprovidergetbitmap}
 114 returns identical bitmap for different {\it client} values!
 115
 116 \wxheading{See also}
 117
 118 See the \helpref{artprov}{sampleartprovider} sample for an example of wxArtProvider usage.
 119
 120 \wxheading{Derived from}
 121
 122 \helpref{wxObject}{wxobject}
 123
 124 \wxheading{Include files}
 125
 126 <wx/artprov.h>
 127
 128 \latexignore{\rtfignore{\wxheading{Members}}}
 129
 130
 131 \membersection{wxArtProvider::\destruct{wxArtProvider}}\label{wxartproviderdtor}
 132
 133 \func{}{\destruct{wxArtProvider}}{\void}
 134
 135 The destructor automatically removes the provider from the provider stack used
 136 by \helpref{GetBitmap}{wxartprovidergetbitmap}.
 137
 138
 139 \membersection{wxArtProvider::CreateBitmap}\label{wxartprovidercreatebitmap}
 140
 141 \func{wxBitmap}{CreateBitmap}{\param{const wxArtID\& }{id}, \param{const wxArtClient\& }{client}, \param{const wxSize\& }{size}}
 142
 143 Derived art provider classes must override this method to create requested
 144 art resource. Note that returned bitmaps are cached by wxArtProvider and it is therefore
 145 not necessary to optimize CreateBitmap for speed (e.g. you may create wxBitmap objects
 146 from XPMs here).
 147
 148 \wxheading{Parameters}
 149
 150 \docparam{id}{wxArtID unique identifier of the bitmap.}
 151
 152 \docparam{client}{wxArtClient identifier of the client (i.e. who is asking for the bitmap).
 153 This only servers as a hint.}
 154
 155 \docparam{size}{Preferred size of the bitmap. The function may return a bitmap of different
 156 dimensions, it will be automatically rescaled to meet client's request.}
 157
 158 \wxheading{Note}
 159
 160 This is {\bf not} part of wxArtProvider's public API, use
 161 \helpref{wxArtProvider::GetBitmap}{wxartprovidergetbitmap} or
 162 \helpref{wxArtProvider::GetIcon}{wxartprovidergeticon}
 163 to query wxArtProvider for a resource.
 164
 165
 166 \membersection{wxArtProvider::Delete}\label{wxartproviderdelete}
 167
 168 \func{static bool}{Delete}{\param{wxArtProvider* }{provider}}
 169
 170 Delete the given \arg{provider}.
 171
 172
 173 \membersection{wxArtProvider::GetBitmap}\label{wxartprovidergetbitmap}
 174
 175 \func{static wxBitmap}{GetBitmap}{\param{const wxArtID\& }{id}, \param{const wxArtClient\& }{client = wxART\_OTHER}, \param{const wxSize\& }{size = wxDefaultSize}}
 176
 177 Query registered providers for bitmap with given ID.
 178
 179 \wxheading{Parameters}
 180
 181 \docparam{id}{wxArtID unique identifier of the bitmap.}
 182
 183 \docparam{client}{wxArtClient identifier of the client (i.e. who is asking for the bitmap).}
 184
 185 \docparam{size}{Size of the returned bitmap or {\tt wxDefaultSize} if size doesn't matter.}
 186
 187 \wxheading{Return value}
 188
 189 The bitmap if one of registered providers recognizes the ID or wxNullBitmap otherwise.
 190
 191
 192 \membersection{wxArtProvider::GetIcon}\label{wxartprovidergeticon}
 193
 194 \func{static wxIcon}{GetIcon}{\param{const wxArtID\& }{id}, \param{const wxArtClient\& }{client = wxART\_OTHER}, \param{const wxSize\& }{size = wxDefaultSize}}
 195
 196 Same as \helpref{wxArtProvider::GetBitmap}{wxartprovidergetbitmap}, but
 197 return a wxIcon object (or wxNullIcon on failure).
 198
 199 \func{static wxSize}{GetSizeHint}{\param{const wxArtClient\& }{client}, \param{bool }{platform\_default = false}}
 200
 201 Returns a suitable size hint for the given {\it wxArtClient}. If
 202 {\it platform\_default} is \true, return a size based on the current platform,
 203 otherwise return the size from the topmost wxArtProvider. {\it wxDefaultSize} may be
 204 returned if the client doesn't have a specified size, like wxART\_OTHER for example.
 205
 206
 207 \membersection{wxArtProvider::Insert}\label{wxartproviderinsert}
 208
 209 \func{static void}{Insert}{\param{wxArtProvider* }{provider}}
 210
 211 Register new art provider and add it to the bottom of providers stack (i.e.
 212 it will be queried as the last one).
 213
 214 \wxheading{See also}
 215
 216 \helpref{Push}{wxartproviderpush}
 217
 218
 219 \membersection{wxArtProvider::Pop}\label{wxartproviderctor}
 220
 221 \func{static bool}{Pop}{\void}
 222
 223 Remove latest added provider and delete it.
 224
 225
 226 \membersection{wxArtProvider::Push}\label{wxartproviderpush}
 227
 228 \func{static void}{Push}{\param{wxArtProvider* }{provider}}
 229
 230 Register new art provider and add it to the top of providers stack (i.e. it
 231 will be queried as the first provider).
 232
 233 \wxheading{See also}
 234
 235 \helpref{Insert}{wxartproviderinsert}
 236
 237
 238 \membersection{wxArtProvider::Remove}\label{wxartproviderremove}
 239
 240 \func{static bool}{Remove}{\param{wxArtProvider* }{provider}}
 241
 242 Remove a provider from the stack if it is on it. The provider is {\emph not}
 243 deleted, unlike when using \helpref{Delete()}{wxartproviderdelete}.
 244