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
  46 \item wxART\_ERROR
  47 \item wxART\_QUESTION
  48 \item wxART\_WARNING
  49 \item wxART\_INFORMATION
  50 \item wxART\_ADD\_BOOKMARK
  51 \item wxART\_DEL\_BOOKMARK
  52 \item wxART\_HELP\_SIDE\_PANEL
  53 \item wxART\_HELP\_SETTINGS
  54 \item wxART\_HELP\_BOOK
  55 \item wxART\_HELP\_FOLDER
  56 \item wxART\_HELP\_PAGE
  57 \item wxART\_GO\_BACK
  58 \item wxART\_GO\_FORWARD
  59 \item wxART\_GO\_UP
  60 \item wxART\_GO\_DOWN
  61 \item wxART\_GO\_TO\_PARENT
  62 \item wxART\_GO\_HOME
  63 \item wxART\_PRINT
  64 \item wxART\_HELP
  65 \item wxART\_TIP
  66 \item wxART\_REPORT\_VIEW
  67 \item wxART\_LIST\_VIEW
  68 \item wxART\_NEW\_DIR
  69 \item wxART\_FOLDER
  70 \item wxART\_FOLDER\_OPEN
  71 \item wxART\_GO\_DIR\_UP
  72 \item wxART\_EXECUTABLE\_FILE
  73 \item wxART\_NORMAL\_FILE
  74 \item wxART\_TICK\_MARK
  75 \item wxART\_CROSS\_MARK
  76 \item wxART\_MISSING\_IMAGE
  77 \item wxART\_NEW
  78 \item wxART\_FILE\_OPEN
  79 \item wxART\_FILE\_SAVE
  80 \item wxART\_FILE\_SAVE\_AS
  81 \item wxART\_DELETE
  82 \item wxART\_COPY
  83 \item wxART\_CUT
  84 \item wxART\_PASTE
  85 \item wxART\_UNDO
  86 \item wxART\_REDO
  87 \item wxART\_QUIT
  88 \item wxART\_FIND
  89 \item wxART\_FIND\_AND\_REPLACE
  90 \item wxART\_HARDDISK
  91 \item wxART\_FLOPPY
  92 \item wxART\_CDROM
  93 \item wxART\_REMOVABLE
  94
  95 \end{itemize}
  96
  97 Additionally, any string recognized by custom art providers registered using
  98 \helpref{Push}{wxartproviderpush} may be used.
  99
 100 \wxheading{GTK+ Note}
 101
 102 When running under GTK+ 2, GTK+ stock item IDs (e.g. {\tt "gtk-cdrom"}) may
 103 be used as well. Additionally, if wxGTK was compiled against GTK+ >= 2.4, then
 104 it is also possible to load icons from current icon theme by specifying their
 105 name (without extension and directory components). Icon themes recognized
 106 by GTK+ follow the
 107 \urlref{freedesktop.org Icon Themes specification}{http://freedesktop.org/Standards/icon-theme-spec}. Note that themes are not guaranteed to contain all
 108 icons, so wxArtProvider may return {\tt wxNullBitmap} or {\tt wxNullIcon}.
 109 Default theme is typically installed in {\tt /usr/share/icons/hicolor}.
 110
 111
 112 \membersection{Clients}\label{artproviderclients}
 113
 114 Client is the entity that calls wxArtProvider's GetBitmap or GetIcon
 115 function. It is represented by wxClientID type and can have one of these
 116 values:
 117 \begin{itemize}\itemsep=0pt
 118 \item wxART\_TOOLBAR
 119 \item wxART\_MENU
 120 \item wxART\_BUTTON
 121 \item wxART\_FRAME\_ICON
 122 \item wxART\_CMN\_DIALOG
 123 \item wxART\_HELP\_BROWSER
 124 \item wxART\_MESSAGE\_BOX
 125 \item wxART\_OTHER (used for all requests that don't fit into any of the categories above)
 126 \end{itemize}
 127 Client ID servers as a hint to wxArtProvider that is supposed to help it to
 128 choose the best looking bitmap. For example it is often desirable to use
 129 slightly different icons in menus and toolbars even though they represent the
 130 same action (e.g. {\tt wx\_ART\_FILE\_OPEN}). Remember that this is really
 131 only a hint for wxArtProvider -- it is common that
 132 \helpref{wxArtProvider::GetBitmap}{wxartprovidergetbitmap}
 133 returns identical bitmap for different {\it client} values!
 134
 135 \wxheading{See also}
 136
 137 See the \helpref{artprov}{sampleartprovider} sample for an example of wxArtProvider usage.
 138
 139 \wxheading{Derived from}
 140
 141 \helpref{wxObject}{wxobject}
 142
 143 \wxheading{Include files}
 144
 145 <wx/artprov.h>
 146
 147 \latexignore{\rtfignore{\wxheading{Members}}}
 148
 149
 150 \membersection{wxArtProvider::\destruct{wxArtProvider}}\label{wxartproviderdtor}
 151
 152 \func{}{\destruct{wxArtProvider}}{\void}
 153
 154 The destructor automatically removes the provider from the provider stack used
 155 by \helpref{GetBitmap}{wxartprovidergetbitmap}.
 156
 157
 158 \membersection{wxArtProvider::CreateBitmap}\label{wxartprovidercreatebitmap}
 159
 160 \func{wxBitmap}{CreateBitmap}{\param{const wxArtID\& }{id}, \param{const wxArtClient\& }{client}, \param{const wxSize\& }{size}}
 161
 162 Derived art provider classes must override this method to create requested
 163 art resource. Note that returned bitmaps are cached by wxArtProvider and it is therefore
 164 not necessary to optimize CreateBitmap for speed (e.g. you may create wxBitmap objects
 165 from XPMs here).
 166
 167 \wxheading{Parameters}
 168
 169 \docparam{id}{wxArtID unique identifier of the bitmap.}
 170
 171 \docparam{client}{wxArtClient identifier of the client (i.e. who is asking for the bitmap).
 172 This only servers as a hint.}
 173
 174 \docparam{size}{Preferred size of the bitmap. The function may return a bitmap of different
 175 dimensions, it will be automatically rescaled to meet client's request.}
 176
 177 \wxheading{Note}
 178
 179 This is {\bf not} part of wxArtProvider's public API, use
 180 \helpref{wxArtProvider::GetBitmap}{wxartprovidergetbitmap} or
 181 \helpref{wxArtProvider::GetIcon}{wxartprovidergeticon}
 182 to query wxArtProvider for a resource.
 183
 184
 185 \membersection{wxArtProvider::Delete}\label{wxartproviderdelete}
 186
 187 \func{static bool}{Delete}{\param{wxArtProvider* }{provider}}
 188
 189 Delete the given \arg{provider}.
 190
 191
 192 \membersection{wxArtProvider::GetBitmap}\label{wxartprovidergetbitmap}
 193
 194 \func{static wxBitmap}{GetBitmap}{\param{const wxArtID\& }{id}, \param{const wxArtClient\& }{client = wxART\_OTHER}, \param{const wxSize\& }{size = wxDefaultSize}}
 195
 196 Query registered providers for bitmap with given ID.
 197
 198 \wxheading{Parameters}
 199
 200 \docparam{id}{wxArtID unique identifier of the bitmap.}
 201
 202 \docparam{client}{wxArtClient identifier of the client (i.e. who is asking for the bitmap).}
 203
 204 \docparam{size}{Size of the returned bitmap or {\tt wxDefaultSize} if size doesn't matter.}
 205
 206 \wxheading{Return value}
 207
 208 The bitmap if one of registered providers recognizes the ID or wxNullBitmap otherwise.
 209
 210
 211 \membersection{wxArtProvider::GetIcon}\label{wxartprovidergeticon}
 212
 213 \func{static wxIcon}{GetIcon}{\param{const wxArtID\& }{id}, \param{const wxArtClient\& }{client = wxART\_OTHER}, \param{const wxSize\& }{size = wxDefaultSize}}
 214
 215 Same as \helpref{wxArtProvider::GetBitmap}{wxartprovidergetbitmap}, but
 216 return a wxIcon object (or wxNullIcon on failure).
 217
 218 \func{static wxSize}{GetSizeHint}{\param{const wxArtClient\& }{client}, \param{bool }{platform\_default = false}}
 219
 220 Returns a suitable size hint for the given {\it wxArtClient}. If
 221 {\it platform\_default} is \true, return a size based on the current platform,
 222 otherwise return the size from the topmost wxArtProvider. {\it wxDefaultSize} may be
 223 returned if the client doesn't have a specified size, like wxART\_OTHER for example.
 224
 225
 226 \membersection{wxArtProvider::Insert}\label{wxartproviderinsert}
 227
 228 \func{static void}{Insert}{\param{wxArtProvider* }{provider}}
 229
 230 Register new art provider and add it to the bottom of providers stack (i.e.
 231 it will be queried as the last one).
 232
 233 \wxheading{See also}
 234
 235 \helpref{Push}{wxartproviderpush}
 236
 237
 238 \membersection{wxArtProvider::Pop}\label{wxartproviderctor}
 239
 240 \func{static bool}{Pop}{\void}
 241
 242 Remove latest added provider and delete it.
 243
 244
 245 \membersection{wxArtProvider::Push}\label{wxartproviderpush}
 246
 247 \func{static void}{Push}{\param{wxArtProvider* }{provider}}
 248
 249 Register new art provider and add it to the top of providers stack (i.e. it
 250 will be queried as the first provider).
 251
 252 \wxheading{See also}
 253
 254 \helpref{Insert}{wxartproviderinsert}
 255
 256
 257 \membersection{wxArtProvider::Remove}\label{wxartproviderremove}
 258
 259 \func{static bool}{Remove}{\param{wxArtProvider* }{provider}}
 260
 261 Remove a provider from the stack if it is on it. The provider is {\emph not}
 262 deleted, unlike when using \helpref{Delete()}{wxartproviderdelete}.
 263