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