← Back to branch summary

~brian-sidebotham/wxwidgets-cmake/wxpython-2.9.4

« back to all changes in this revision

Viewing changes to interface/wx/artprov.h

  • Committer: Brian Sidebotham
  • Date: 2013-08-03 14:30:08 UTC
  • Revision ID: brian.sidebotham@gmail.com-20130803143008-c7806tkych1tp6fc
Initial import into Bazaar

Show diffs side-by-side

added added

removed removed

Lines of Context:
interface/wx/artprov.h
 
1
/////////////////////////////////////////////////////////////////////////////
 
2
// Name:        artprov.h
 
3
// Purpose:     interface of wxArtProvider
 
4
// Author:      wxWidgets team
 
5
// RCS-ID:      $Id: artprov.h 71147 2012-04-08 00:54:02Z RD $
 
6
// Licence:     wxWindows licence
 
7
/////////////////////////////////////////////////////////////////////////////
 
8
 
 
9
/**
 
10
    This type identifies the client of the art objects requested to wxArtProvider.
 
11
*/
 
12
typedef wxString wxArtClient;
 
13
 
 
14
/**
 
15
    This type identifies a specific art object which can be requested to wxArtProvider.
 
16
*/
 
17
typedef wxString wxArtID;
 
18
 
 
19
 
 
20
wxArtClient wxART_TOOLBAR;
 
21
wxArtClient wxART_MENU;
 
22
wxArtClient wxART_FRAME_ICON;
 
23
 
 
24
wxArtClient wxART_CMN_DIALOG;
 
25
wxArtClient wxART_HELP_BROWSER;
 
26
wxArtClient wxART_MESSAGE_BOX;
 
27
wxArtClient wxART_BUTTON;
 
28
wxArtClient wxART_LIST;
 
29
 
 
30
wxArtClient wxART_OTHER;
 
31
 
 
32
 
 
33
wxArtID wxART_ADD_BOOKMARK;         
 
34
wxArtID wxART_DEL_BOOKMARK;         
 
35
wxArtID wxART_HELP_SIDE_PANEL;      
 
36
wxArtID wxART_HELP_SETTINGS;        
 
37
wxArtID wxART_HELP_BOOK;            
 
38
wxArtID wxART_HELP_FOLDER;          
 
39
wxArtID wxART_HELP_PAGE;            
 
40
wxArtID wxART_GO_BACK;              
 
41
wxArtID wxART_GO_FORWARD;           
 
42
wxArtID wxART_GO_UP;                
 
43
wxArtID wxART_GO_DOWN;              
 
44
wxArtID wxART_GO_TO_PARENT;         
 
45
wxArtID wxART_GO_HOME;              
 
46
wxArtID wxART_GOTO_FIRST;           
 
47
wxArtID wxART_GOTO_LAST;            
 
48
wxArtID wxART_FILE_OPEN;            
 
49
wxArtID wxART_FILE_SAVE;            
 
50
wxArtID wxART_FILE_SAVE_AS;         
 
51
wxArtID wxART_PRINT;                
 
52
wxArtID wxART_HELP;                 
 
53
wxArtID wxART_TIP;                  
 
54
wxArtID wxART_REPORT_VIEW;          
 
55
wxArtID wxART_LIST_VIEW;            
 
56
wxArtID wxART_NEW_DIR;              
 
57
wxArtID wxART_HARDDISK;             
 
58
wxArtID wxART_FLOPPY;               
 
59
wxArtID wxART_CDROM;                
 
60
wxArtID wxART_REMOVABLE;            
 
61
wxArtID wxART_FOLDER;               
 
62
wxArtID wxART_FOLDER_OPEN;          
 
63
wxArtID wxART_GO_DIR_UP;            
 
64
wxArtID wxART_EXECUTABLE_FILE;      
 
65
wxArtID wxART_NORMAL_FILE;          
 
66
wxArtID wxART_TICK_MARK;            
 
67
wxArtID wxART_CROSS_MARK;           
 
68
wxArtID wxART_ERROR;                
 
69
wxArtID wxART_QUESTION;             
 
70
wxArtID wxART_WARNING;              
 
71
wxArtID wxART_INFORMATION;          
 
72
wxArtID wxART_MISSING_IMAGE;        
 
73
 
 
74
wxArtID wxART_COPY;                 
 
75
wxArtID wxART_CUT;                  
 
76
wxArtID wxART_PASTE;                
 
77
wxArtID wxART_DELETE;               
 
78
wxArtID wxART_NEW;                  
 
79
 
 
80
wxArtID wxART_UNDO;                 
 
81
wxArtID wxART_REDO;                 
 
82
 
 
83
wxArtID wxART_PLUS;                 
 
84
wxArtID wxART_MINUS;                
 
85
 
 
86
wxArtID wxART_CLOSE;                
 
87
wxArtID wxART_QUIT;                 
 
88
 
 
89
wxArtID wxART_FIND;                 
 
90
wxArtID wxART_FIND_AND_REPLACE;     
 
91
 
 
92
 
 
93
/**
 
94
    @class wxArtProvider
 
95
 
 
96
    wxArtProvider class is used to customize the look of wxWidgets application.
 
97
 
 
98
    When wxWidgets needs to display an icon or a bitmap (e.g. in the standard file
 
99
    dialog), it does not use a hard-coded resource but asks wxArtProvider for it
 
100
    instead. This way users can plug in their own wxArtProvider class and easily
 
101
    replace standard art with their own version.
 
102
 
 
103
    All that is needed is to derive a class from wxArtProvider, override either its
 
104
    wxArtProvider::CreateBitmap() and/or its wxArtProvider::CreateIconBundle() methods
 
105
    and register the provider with wxArtProvider::Push():
 
106
 
 
107
    @code
 
108
      class MyProvider : public wxArtProvider
 
109
      {
 
110
      protected:
 
111
        wxBitmap CreateBitmap(const wxArtID& id,
 
112
                              const wxArtClient& client,
 
113
                              const wxSize size)
 
114
 
 
115
        // optionally override this one as well
 
116
        wxIconBundle CreateIconBundle(const wxArtID& id,
 
117
                                      const wxArtClient& client)
 
118
        { ... }
 
119
      };
 
120
      ...
 
121
      wxArtProvider::Push(new MyProvider);
 
122
    @endcode
 
123
 
 
124
    If you need bitmap images (of the same artwork) that should be displayed at
 
125
    different sizes you should probably consider overriding wxArtProvider::CreateIconBundle
 
126
    and supplying icon bundles that contain different bitmap sizes.
 
127
 
 
128
    There's another way of taking advantage of this class: you can use it in your
 
129
    code and use platform native icons as provided by wxArtProvider::GetBitmap or
 
130
    wxArtProvider::GetIcon.
 
131
 
 
132
    @section artprovider_identify Identifying art resources
 
133
 
 
134
    Every bitmap and icon bundle are known to wxArtProvider under an unique ID that
 
135
    is used when requesting a resource from it. The ID is represented by the ::wxArtID type
 
136
    and can have one of these predefined values (you can see bitmaps represented by these
 
137
    constants in the @ref page_samples_artprov):
 
138
 
 
139
    <table>
 
140
    <tr><td>
 
141
     @li @c wxART_ERROR
 
142
     @li @c wxART_QUESTION
 
143
     @li @c wxART_WARNING
 
144
     @li @c wxART_INFORMATION
 
145
     @li @c wxART_ADD_BOOKMARK
 
146
     @li @c wxART_DEL_BOOKMARK
 
147
     @li @c wxART_HELP_SIDE_PANEL
 
148
     @li @c wxART_HELP_SETTINGS
 
149
     @li @c wxART_HELP_BOOK
 
150
     @li @c wxART_HELP_FOLDER
 
151
     @li @c wxART_HELP_PAGE
 
152
     @li @c wxART_GO_BACK
 
153
     @li @c wxART_GO_FORWARD
 
154
     @li @c wxART_GO_UP
 
155
     @li @c wxART_GO_DOWN
 
156
     @li @c wxART_GO_TO_PARENT
 
157
     @li @c wxART_GO_HOME
 
158
     @li @c wxART_GOTO_FIRST (since 2.9.2)
 
159
     </td><td>
 
160
     @li @c wxART_GOTO_LAST (since 2.9.2)
 
161
     @li @c wxART_PRINT
 
162
     @li @c wxART_HELP
 
163
     @li @c wxART_TIP
 
164
     @li @c wxART_REPORT_VIEW
 
165
     @li @c wxART_LIST_VIEW
 
166
     @li @c wxART_NEW_DIR
 
167
     @li @c wxART_FOLDER
 
168
     @li @c wxART_FOLDER_OPEN
 
169
     @li @c wxART_GO_DIR_UP
 
170
     @li @c wxART_EXECUTABLE_FILE
 
171
     @li @c wxART_NORMAL_FILE
 
172
     @li @c wxART_TICK_MARK
 
173
     @li @c wxART_CROSS_MARK
 
174
     @li @c wxART_MISSING_IMAGE
 
175
     @li @c wxART_NEW
 
176
     @li @c wxART_FILE_OPEN
 
177
     @li @c wxART_FILE_SAVE
 
178
     </td><td>
 
179
     @li @c wxART_FILE_SAVE_AS
 
180
     @li @c wxART_DELETE
 
181
     @li @c wxART_COPY
 
182
     @li @c wxART_CUT
 
183
     @li @c wxART_PASTE
 
184
     @li @c wxART_UNDO
 
185
     @li @c wxART_REDO
 
186
     @li @c wxART_PLUS (since 2.9.2)
 
187
     @li @c wxART_MINUS (since 2.9.2)
 
188
     @li @c wxART_CLOSE
 
189
     @li @c wxART_QUIT
 
190
     @li @c wxART_FIND
 
191
     @li @c wxART_FIND_AND_REPLACE
 
192
     @li @c wxART_HARDDISK
 
193
     @li @c wxART_FLOPPY
 
194
     @li @c wxART_CDROM
 
195
     @li @c wxART_REMOVABLE
 
196
    </td></tr>
 
197
    </table>
 
198
 
 
199
    Additionally, any string recognized by custom art providers registered using
 
200
    wxArtProvider::Push may be used.
 
201
 
 
202
    @note
 
203
    When running under GTK+ 2, GTK+ stock item IDs (e.g. @c "gtk-cdrom") may be used
 
204
    as well:
 
205
    @code
 
206
    #ifdef __WXGTK__
 
207
        wxBitmap bmp = wxArtProvider::GetBitmap("gtk-cdrom", wxART_MENU);
 
208
    #endif
 
209
    @endcode
 
210
    For a list of the GTK+ stock items please refer to the
 
211
    <a href="http://library.gnome.org/devel/gtk/stable/gtk-Stock-Items.html">GTK+ documentation
 
212
    page</a>.
 
213
    It is also possible to load icons from the current icon theme by specifying their name 
 
214
    (without extension and directory components).
 
215
    Icon themes recognized by GTK+ follow the freedesktop.org
 
216
    <a href="http://freedesktop.org/Standards/icon-theme-spec">Icon Themes specification</a>.
 
217
    Note that themes are not guaranteed to contain all icons, so wxArtProvider may
 
218
    return ::wxNullBitmap or ::wxNullIcon.
 
219
    The default theme is typically installed in @c /usr/share/icons/hicolor.
 
220
 
 
221
 
 
222
    @section artprovider_clients Clients
 
223
 
 
224
    The @e client is the entity that calls wxArtProvider's GetBitmap() or GetIcon() function.
 
225
    It is represented by wxClientID type and can have one of these values:
 
226
 
 
227
    @li @c wxART_TOOLBAR
 
228
    @li @c wxART_MENU
 
229
    @li @c wxART_BUTTON
 
230
    @li @c wxART_FRAME_ICON
 
231
    @li @c wxART_CMN_DIALOG
 
232
    @li @c wxART_HELP_BROWSER
 
233
    @li @c wxART_MESSAGE_BOX
 
234
    @li @c wxART_OTHER (used for all requests that don't fit into any of the
 
235
        categories above)
 
236
 
 
237
    Client ID serve as a hint to wxArtProvider that is supposed to help it to
 
238
    choose the best looking bitmap. For example it is often desirable to use
 
239
    slightly different icons in menus and toolbars even though they represent
 
240
    the same action (e.g. wxART_FILE_OPEN). Remember that this is really only a
 
241
    hint for wxArtProvider -- it is common that wxArtProvider::GetBitmap returns
 
242
    identical bitmap for different client values!
 
243
 
 
244
    @library{wxcore}
 
245
    @category{misc}
 
246
 
 
247
    @see @ref page_samples_artprov for an example of wxArtProvider usage;
 
248
         @ref page_stockitems "stock ID list"
 
249
*/
 
250
class wxArtProvider : public wxObject
 
251
{
 
252
public:
 
253
    /**
 
254
        The destructor automatically removes the provider from the provider stack used
 
255
        by GetBitmap().
 
256
    */
 
257
    virtual ~wxArtProvider();
 
258
 
 
259
    /**
 
260
        Delete the given @a provider.
 
261
    */
 
262
    static bool Delete(wxArtProvider* provider);
 
263
 
 
264
    /**
 
265
        Query registered providers for bitmap with given ID.
 
266
 
 
267
        @param id
 
268
            wxArtID unique identifier of the bitmap.
 
269
        @param client
 
270
            wxArtClient identifier of the client (i.e. who is asking for the bitmap).
 
271
        @param size
 
272
            Size of the returned bitmap or wxDefaultSize if size doesn't matter.
 
273
 
 
274
        @return The bitmap if one of registered providers recognizes the ID or
 
275
                wxNullBitmap otherwise.
 
276
    */
 
277
    static wxBitmap GetBitmap(const wxArtID& id,
 
278
                              const wxArtClient& client = wxART_OTHER,
 
279
                              const wxSize& size = wxDefaultSize);
 
280
 
 
281
    /**
 
282
        Same as wxArtProvider::GetBitmap, but return a wxIcon object
 
283
        (or ::wxNullIcon on failure).
 
284
    */
 
285
    static wxIcon GetIcon(const wxArtID& id,
 
286
                          const wxArtClient& client = wxART_OTHER,
 
287
                          const wxSize& size = wxDefaultSize);
 
288
 
 
289
    /**
 
290
        Returns native icon size for use specified by @a client hint.
 
291
 
 
292
        If the platform has no commonly used default for this use or if
 
293
        @a client is not recognized, returns wxDefaultSize.
 
294
 
 
295
        @note In some cases, a platform may have @em several appropriate
 
296
              native sizes (for example, wxART_FRAME_ICON for frame icons).
 
297
              In that case, this method returns only one of them, picked
 
298
              reasonably.
 
299
 
 
300
        @since 2.9.0
 
301
     */
 
302
    static wxSize GetNativeSizeHint(const wxArtClient& client);
 
303
 
 
304
    /**
 
305
        Returns a suitable size hint for the given @e wxArtClient.
 
306
 
 
307
        If @a platform_default is @true, return a size based on the current
 
308
        platform using GetNativeSizeHint(), otherwise return the size from the
 
309
        topmost wxArtProvider. @e wxDefaultSize may be returned if the client
 
310
        doesn't have a specified size, like wxART_OTHER for example.
 
311
 
 
312
        @see GetNativeSizeHint()
 
313
    */
 
314
    static wxSize GetSizeHint(const wxArtClient& client,
 
315
                              bool platform_default = false);
 
316
 
 
317
    /**
 
318
        Query registered providers for icon bundle with given ID.
 
319
 
 
320
        @param id
 
321
            wxArtID unique identifier of the icon bundle.
 
322
        @param client
 
323
            wxArtClient identifier of the client (i.e. who is asking for the icon
 
324
            bundle).
 
325
 
 
326
        @return The icon bundle if one of registered providers recognizes the ID
 
327
                or wxNullIconBundle otherwise.
 
328
    */
 
329
    static wxIconBundle GetIconBundle(const wxArtID& id,
 
330
                                      const wxArtClient& client = wxART_OTHER);
 
331
 
 
332
    /**
 
333
        Returns true if the platform uses native icons provider that should
 
334
        take precedence over any customizations.
 
335
 
 
336
        This is true for any platform that has user-customizable icon themes,
 
337
        currently only wxGTK.
 
338
 
 
339
        A typical use for this method is to decide whether a custom art provider
 
340
        should be plugged in using Push() or PushBack().
 
341
 
 
342
        @since 2.9.0
 
343
     */
 
344
    static bool HasNativeProvider();
 
345
 
 
346
    /**
 
347
        @deprecated Use PushBack() instead.
 
348
    */
 
349
    static void Insert(wxArtProvider* provider);
 
350
 
 
351
    /**
 
352
        Remove latest added provider and delete it.
 
353
    */
 
354
    static bool Pop();
 
355
 
 
356
    /**
 
357
        Register new art provider and add it to the top of providers stack
 
358
        (i.e. it will be queried as the first provider).
 
359
 
 
360
        @see PushBack()
 
361
    */
 
362
    static void Push(wxArtProvider* provider);
 
363
 
 
364
    /**
 
365
        Register new art provider and add it to the bottom of providers stack.
 
366
        In other words, it will be queried as the last one, after all others,
 
367
        including the default provider.
 
368
 
 
369
        @see Push()
 
370
 
 
371
        @since 2.9.0
 
372
    */
 
373
    static void PushBack(wxArtProvider* provider);
 
374
 
 
375
    /**
 
376
        Remove a provider from the stack if it is on it. The provider is not
 
377
        deleted, unlike when using Delete().
 
378
    */
 
379
    static bool Remove(wxArtProvider* provider);
 
380
 
 
381
protected:
 
382
 
 
383
    /**
 
384
        Derived art provider classes must override this method to create requested art
 
385
        resource. Note that returned bitmaps are cached by wxArtProvider and it is
 
386
        therefore not necessary to optimize CreateBitmap() for speed (e.g. you may
 
387
        create wxBitmap objects from XPMs here).
 
388
 
 
389
        @param id
 
390
            wxArtID unique identifier of the bitmap.
 
391
        @param client
 
392
            wxArtClient identifier of the client (i.e. who is asking for the bitmap).
 
393
            This only servers as a hint.
 
394
        @param size
 
395
            Preferred size of the bitmap. The function may return a bitmap of different
 
396
            dimensions, it will be automatically rescaled to meet client's request.
 
397
 
 
398
        @note
 
399
        This is not part of wxArtProvider's public API, use wxArtProvider::GetBitmap
 
400
        or wxArtProvider::GetIconBundle or wxArtProvider::GetIcon to query wxArtProvider
 
401
        for a resource.
 
402
 
 
403
        @see CreateIconBundle()
 
404
    */
 
405
    virtual wxBitmap CreateBitmap(const wxArtID& id,
 
406
                                  const wxArtClient& client,
 
407
                                  const wxSize& size);
 
408
 
 
409
    /**
 
410
        This method is similar to CreateBitmap() but can be used when a bitmap
 
411
        (or an icon) exists in several sizes.
 
412
    */
 
413
    virtual wxIconBundle CreateIconBundle(const wxArtID& id,
 
414
                                          const wxArtClient& client);
 
415
};
 
416