1% 2% automatically generated by HelpGen $Revision: 41398 $ from 3% artprov.h at 08/Apr/02 17:44:57 4% 5 6\section{\class{wxArtProvider}}\label{wxartprovider} 7 8wxArtProvider class is used to customize the look of wxWidgets application. 9When wxWidgets needs to display an icon or a bitmap (e.g. in the standard file 10dialog), it does not use a hard-coded resource but asks wxArtProvider for it 11instead. This way users can plug in their own wxArtProvider class and easily 12replace standard art with their own version. All 13that is needed is to derive a class from wxArtProvider, override its 14\helpref{CreateBitmap}{wxartprovidercreatebitmap} method and register the 15provider 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 31There's another way of taking advantage of this class: you can use it in your code and use 32platform native icons as provided by \helpref{wxArtProvider::GetBitmap}{wxartprovidergetbitmap} or 33\helpref{wxArtProvider::GetIcon}{wxartprovidergeticon} (NB: this is not yet really 34possible as of wxWidgets 2.3.3, the set of wxArtProvider bitmaps is too 35small). 36 37 38\membersection{Identifying art resources}\label{artprovideridentifying} 39 40Every bitmap is known to wxArtProvider under an unique ID that is used by when 41requesting a resource from it. The ID is represented by wxArtID type and can 42have one of these predefined values (you can see bitmaps represented by these 43constants 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 78Additionally, any string recognized by custom art providers registered using 79\helpref{Push}{wxartproviderpush} may be used. 80 81\wxheading{GTK+ Note} 82 83When running under GTK+ 2, GTK+ stock item IDs (e.g. {\tt "gtk-cdrom"}) may 84be used as well. Additionally, if wxGTK was compiled against GTK+ >= 2.4, then 85it is also possible to load icons from current icon theme by specifying their 86name (without extension and directory components). Icon themes recognized 87by 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 89icons, so wxArtProvider may return {\tt wxNullBitmap} or {\tt wxNullIcon}. 90Default theme is typically installed in {\tt /usr/share/icons/hicolor}. 91 92 93\membersection{Clients}\label{artproviderclients} 94 95Client is the entity that calls wxArtProvider's GetBitmap or GetIcon 96function. It is represented by wxClientID type and can have one of these 97values: 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} 108Client ID servers as a hint to wxArtProvider that is supposed to help it to 109choose the best looking bitmap. For example it is often desirable to use 110slightly different icons in menus and toolbars even though they represent the 111same action (e.g. {\tt wx\_ART\_FILE\_OPEN}). Remember that this is really 112only a hint for wxArtProvider -- it is common that 113\helpref{wxArtProvider::GetBitmap}{wxartprovidergetbitmap} 114returns identical bitmap for different {\it client} values! 115 116\wxheading{See also} 117 118See 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 135The destructor automatically removes the provider from the provider stack used 136by \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 143Derived art provider classes must override this method to create requested 144art resource. Note that returned bitmaps are cached by wxArtProvider and it is therefore 145not necessary to optimize CreateBitmap for speed (e.g. you may create wxBitmap objects 146from 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). 153This only servers as a hint.} 154 155\docparam{size}{Preferred size of the bitmap. The function may return a bitmap of different 156dimensions, it will be automatically rescaled to meet client's request.} 157 158\wxheading{Note} 159 160This is {\bf not} part of wxArtProvider's public API, use 161\helpref{wxArtProvider::GetBitmap}{wxartprovidergetbitmap} or 162\helpref{wxArtProvider::GetIcon}{wxartprovidergeticon} 163to query wxArtProvider for a resource. 164 165 166\membersection{wxArtProvider::Delete}\label{wxartproviderdelete} 167 168\func{static bool}{Delete}{\param{wxArtProvider* }{provider}} 169 170Delete 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 177Query 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 189The 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 196Same as \helpref{wxArtProvider::GetBitmap}{wxartprovidergetbitmap}, but 197return a wxIcon object (or wxNullIcon on failure). 198 199\func{static wxSize}{GetSizeHint}{\param{const wxArtClient\& }{client}, \param{bool }{platform\_default = false}} 200 201Returns a suitable size hint for the given {\it wxArtClient}. If 202{\it platform\_default} is \true, return a size based on the current platform, 203otherwise return the size from the topmost wxArtProvider. {\it wxDefaultSize} may be 204returned 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 211Register new art provider and add it to the bottom of providers stack (i.e. 212it 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 223Remove latest added provider and delete it. 224 225 226\membersection{wxArtProvider::Push}\label{wxartproviderpush} 227 228\func{static void}{Push}{\param{wxArtProvider* }{provider}} 229 230Register new art provider and add it to the top of providers stack (i.e. it 231will 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 242Remove a provider from the stack if it is on it. The provider is {\emph not} 243deleted, unlike when using \helpref{Delete()}{wxartproviderdelete}. 244 245