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}
  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. When running
  80 under GTK+ 2, GTK+ stock item IDs (e.g. {\tt "gtk-cdrom"}) may be used as well.
  81
  82 \membersection{Clients}
  83
  84 Client is the entity that calls wxArtProvider's GetBitmap or GetIcon
  85 function. It is represented by wxClientID type and can have one of these
  86 values:
  87 \begin{itemize}\itemsep=0pt
  88 \item wxART\_TOOLBAR
  89 \item wxART\_MENU
  90 \item wxART\_BUTTON
  91 \item wxART\_FRAME\_ICON
  92 \item wxART\_CMN\_DIALOG
  93 \item wxART\_HELP\_BROWSER
  94 \item wxART\_MESSAGE\_BOX
  95 \item wxART\_OTHER (used for all requests that don't fit into any of the categories above)
  96 \end{itemize}
  97 Client ID servers as a hint to wxArtProvider that is supposed to help it to
  98 choose the best looking bitmap. For example it is often desirable to use
  99 slightly different icons in menus and toolbars even though they represent the
 100 same action (e.g. {\tt wx\_ART\_FILE\_OPEN}). Remember that this is really
 101 only a hint for wxArtProvider -- it is common that
 102 \helpref{wxArtProvider::GetBitmap}{wxartprovidergetbitmap}
 103 returns identical bitmap for different {\it client} values!
 104
 105 \wxheading{See also}
 106
 107 See the \helpref{artprov}{sampleartprovider} sample for an example of wxArtProvider usage.
 108
 109 \wxheading{Derived from}
 110
 111 \helpref{wxObject}{wxobject}
 112
 113 \wxheading{Include files}
 114
 115 <wx/artprov.h>
 116
 117 \latexignore{\rtfignore{\wxheading{Members}}}
 118
 119 \membersection{wxArtProvider::CreateBitmap}\label{wxartprovidercreatebitmap}
 120
 121 \func{wxBitmap}{CreateBitmap}{\param{const wxArtID\& }{id}, \param{const wxArtClient\& }{client}, \param{const wxSize\& }{size}}
 122
 123 Derived art provider classes must override this method to create requested
 124 art resource. Note that returned bitmaps are cached by wxArtProvider and it is therefore
 125 not neccessary to optimize CreateBitmap for speed (e.g. you may create wxBitmap objects
 126 from XPMs here).
 127
 128 \wxheading{Parameters}
 129
 130 \docparam{id}{wxArtID unique identifier of the bitmap.}
 131
 132 \docparam{client}{wxArtClient identifier of the client (i.e. who is asking for the bitmap).
 133 This only servers as a hint.}
 134
 135 \docparam{size}{Prefered size of the bitmap. The function may return a bitmap of different
 136 dimensions, it will be automatically rescaled to meet client's request.}
 137
 138 \wxheading{Note}
 139
 140 This is {\bf not} part of wxArtProvider's public API, use
 141 \helpref{wxArtProvider::GetBitmap}{wxartprovidergetbitmap} or
 142 \helpref{wxArtProvider::GetIcon}{wxartprovidergeticon}
 143 to query wxArtProvider for a resource.
 144
 145 \membersection{wxArtProvider::GetBitmap}\label{wxartprovidergetbitmap}
 146
 147 \func{static wxBitmap}{GetBitmap}{\param{const wxArtID\& }{id}, \param{const wxArtClient\& }{client = wxART\_OTHER}, \param{const wxSize\& }{size = wxDefaultSize}}
 148
 149 Query registered providers for bitmap with given ID.
 150
 151 \wxheading{Parameters}
 152
 153 \docparam{id}{wxArtID unique identifier of the bitmap.}
 154
 155 \docparam{client}{wxArtClient identifier of the client (i.e. who is asking for the bitmap).}
 156
 157 \docparam{size}{Size of the returned bitmap or {\tt wxDefaultSize} if size doesn't matter.}
 158
 159 \wxheading{Return value}
 160
 161 The bitmap if one of registered providers recognizes the ID or wxNullBitmap otherwise.
 162
 163 \membersection{wxArtProvider::GetIcon}\label{wxartprovidergeticon}
 164
 165 \func{static wxIcon}{GetIcon}{\param{const wxArtID\& }{id}, \param{const wxArtClient\& }{client = wxART\_OTHER}, \param{const wxSize\& }{size = wxDefaultSize}}
 166
 167 Same as \helpref{wxArtProvider::GetBitmap}{wxartprovidergetbitmap}, but
 168 return a wxIcon object (or wxNullIcon on failure).
 169
 170 \membersection{wxArtProvider::PopProvider}\label{wxartproviderpopprovider}
 171
 172 \func{static bool}{PopProvider}{\void}
 173
 174 Remove latest added provider and delete it.
 175
 176 \membersection{wxArtProvider::PushProvider}\label{wxartproviderpushprovider}
 177
 178 \func{static void}{PushProvider}{\param{wxArtProvider* }{provider}}
 179
 180 Register new art provider (add it to the top of providers stack).
 181
 182 \membersection{wxArtProvider::RemoveProvider}\label{wxartproviderremoveprovider}
 183
 184 \func{static bool}{RemoveProvider}{\param{wxArtProvider* }{provider}}
 185
 186 Remove a provider from the stack. The provider must have been added previously
 187 and is {\it not} deleted.
 188