[wxWidgets.git] / interface / artprov.h

/////////////////////////////////////////////////////////////////////////////
// Name:        artprov.h
// Purpose:     documentation for wxArtProvider class
// Author:      wxWidgets team
// RCS-ID:      $Id$
// Licence:     wxWindows license
/////////////////////////////////////////////////////////////////////////////

/**
    @class wxArtProvider
    @wxheader{artprov.h}
    
    wxArtProvider class is used to customize the look of wxWidgets application.
    When wxWidgets needs to display an icon or a bitmap (e.g. in the standard file
    dialog), it does not use a hard-coded resource but asks wxArtProvider for it
    instead. This way users can plug in their own wxArtProvider class and easily
    replace standard art with their own version. All
    that is needed is to derive a class from wxArtProvider, override either its
    wxArtProvider::CreateBitmap and/or its
    wxArtProvider::CreateIconBundle methods
    and register the provider with
    wxArtProvider::Push:
    
    @code
    class MyProvider : public wxArtProvider
      {
      protected:
        wxBitmap CreateBitmap(const wxArtID& id, 
                              const wxArtClient& client,
                              const wxSize size)
    
        // optionally override this one as well
        wxIconBundle CreateIconBundle(const wxArtID& id,
                                      const wxArtClient& client)
        { ... }
      };
      ...
      wxArtProvider::Push(new MyProvider);
    @endcode
    
    If you need bitmap images (of the same artwork) that should be displayed at
    different sizes
    you should probably consider overriding wxArtProvider::CreateIconBundle 
    and supplying icon bundles that contain different bitmap sizes.
    
    There's another way of taking advantage of this class: you can use it in your
    code and use
    platform native icons as provided by wxArtProvider::GetBitmap or 
    wxArtProvider::GetIcon (NB: this is not yet really
    possible as of wxWidgets 2.3.3, the set of wxArtProvider bitmaps is too
    small). 
    
    
    wxArtProvider::~wxArtProvider
    wxArtProvider::CreateBitmap
    wxArtProvider::CreateIconBundle
    wxArtProvider::Delete
    wxArtProvider::GetBitmap
    wxArtProvider::GetIconBundle
    wxArtProvider::GetIcon
    wxArtProvider::Insert
    wxArtProvider::Pop
    wxArtProvider::Push
    wxArtProvider::Remove
    
    
    Identifying art resources
    
    Every bitmap and icon bundle are known to wxArtProvider under an unique ID that
    is used when
    requesting a resource from it. The ID is represented by wxArtID type and can
    have one of these predefined values (you can see bitmaps represented by these
    constants in the artprov sample):
    
     wxART_ERROR
     wxART_QUESTION
     wxART_WARNING
     wxART_INFORMATION
     wxART_ADD_BOOKMARK
     wxART_DEL_BOOKMARK
     wxART_HELP_SIDE_PANEL
     wxART_HELP_SETTINGS
     wxART_HELP_BOOK
     wxART_HELP_FOLDER
     wxART_HELP_PAGE
     wxART_GO_BACK
     wxART_GO_FORWARD
     wxART_GO_UP
     wxART_GO_DOWN
     wxART_GO_TO_PARENT
     wxART_GO_HOME
     wxART_PRINT
     wxART_HELP
     wxART_TIP
     wxART_REPORT_VIEW
     wxART_LIST_VIEW
     wxART_NEW_DIR
     wxART_FOLDER
     wxART_FOLDER_OPEN
     wxART_GO_DIR_UP
     wxART_EXECUTABLE_FILE
     wxART_NORMAL_FILE
     wxART_TICK_MARK
     wxART_CROSS_MARK
     wxART_MISSING_IMAGE
     wxART_NEW
     wxART_FILE_OPEN
     wxART_FILE_SAVE
     wxART_FILE_SAVE_AS
     wxART_DELETE
     wxART_COPY
     wxART_CUT
     wxART_PASTE
     wxART_UNDO
     wxART_REDO
     wxART_QUIT
     wxART_FIND
     wxART_FIND_AND_REPLACE
     wxART_HARDDISK
     wxART_FLOPPY
     wxART_CDROM
     wxART_REMOVABLE
    
    
    Additionally, any string recognized by custom art providers registered using 
    wxArtProvider::Push may be used.
    
    @library{wxcore}
    @category{FIXME}
    
    @seealso
    See the artprov sample for an example of wxArtProvider usage.
*/
class wxArtProvider : public wxObject
{
public:
    /**
        The destructor automatically removes the provider from the provider stack used
        by GetBitmap().
    */
    ~wxArtProvider();

    /**
        Client is the entity that calls wxArtProvider's GetBitmap or GetIcon
        function. It is represented by wxClientID type and can have one of these 
        values:
        
         wxART_TOOLBAR
         wxART_MENU
         wxART_BUTTON
         wxART_FRAME_ICON
         wxART_CMN_DIALOG
         wxART_HELP_BROWSER
         wxART_MESSAGE_BOX
         wxART_OTHER (used for all requests that don't fit into any of the categories
        above)
        
        Client ID servers as a hint to wxArtProvider that is supposed to help it to
        choose the best looking bitmap. For example it is often desirable to use
        slightly different icons in menus and toolbars even though they represent the
        same action (e.g. @c wx_ART_FILE_OPEN). Remember that this is really
        only a hint for wxArtProvider -- it is common that
        GetBitmap() 
        returns identical bitmap for different @e client values!
        
        @sa See the artprov sample for an example of wxArtProvider usage.
    */


    /**
        Derived art provider classes must override this method to create requested art
        resource. Note that returned bitmaps are cached by wxArtProvider and it is
        therefore not necessary to optimize CreateBitmap() for speed (e.g. you may
        create wxBitmap objects from XPMs here).
        
        @param id 
        wxArtID unique identifier of the bitmap.
        
        @param client 
        wxArtClient identifier of the client (i.e. who is asking for the bitmap).
        This only servers as a hint.
        
        @param size 
        Preferred size of the bitmap. The function may return a bitmap of different
        dimensions, it will be automatically rescaled to meet client's request.
        
        @sa CreateIconBundle()
    */
    wxBitmap CreateBitmap(const wxArtID& id,
                          const wxArtClient& client,
                          const wxSize& size);

    /**
        This method is similar to CreateBitmap() but
        can be used when a bitmap (or an icon) exists in several sizes.
    */
    wxIconBundle CreateIconBundle(const wxArtID& id,
                                  const wxArtClient& client);

    /**
        Delete the given @e provider.
    */
    static bool Delete(wxArtProvider* provider);

    /**
        Query registered providers for bitmap with given ID.
        
        @param id 
        wxArtID unique identifier of the bitmap.
        
        @param client 
        wxArtClient identifier of the client (i.e. who is asking for the bitmap).
        
        @param size 
        Size of the returned bitmap or wxDefaultSize if size doesn't matter.
        
        @returns The bitmap if one of registered providers recognizes the ID or
                   wxNullBitmap otherwise.
    */
    static wxBitmap GetBitmap(const wxArtID& id,
                              const wxArtClient& client = wxART_OTHER,
                              const wxSize& size = wxDefaultSize);

    //@{
    /**
        Returns a suitable size hint for the given @e wxArtClient. If 
        @e platform_default is @true, return a size based on the current platform, 
        otherwise return the size from the topmost wxArtProvider. @e wxDefaultSize may
        be 
        returned if the client doesn't have a specified size, like wxART_OTHER for
        example.
    */
    static wxIcon GetIcon(const wxArtID& id,
                          const wxArtClient& client = wxART_OTHER,
                          const wxSize& size = wxDefaultSize);
        static wxSize GetSizeHint(const wxArtClient& client,
                                  bool platform_default = @false);
    //@}

    /**
        Query registered providers for icon bundle with given ID.
        
        @param id 
        wxArtID unique identifier of the icon bundle.
        
        @param client 
        wxArtClient identifier of the client (i.e. who is asking for the icon bundle).
        
        @returns The icon bundle if one of registered providers recognizes the ID
                   or wxNullIconBundle otherwise.
    */
    static wxIconBundle GetIconBundle(const wxArtID& id,
                                      const wxArtClient& client = wxART_OTHER);

    /**
        Every bitmap and icon bundle are known to wxArtProvider under an unique ID that
        is used when
        requesting a resource from it. The ID is represented by wxArtID type and can
        have one of these predefined values (you can see bitmaps represented by these
        constants in the artprov sample):
        
         wxART_ERROR
         wxART_QUESTION
         wxART_WARNING
         wxART_INFORMATION
         wxART_ADD_BOOKMARK
         wxART_DEL_BOOKMARK
         wxART_HELP_SIDE_PANEL
         wxART_HELP_SETTINGS
         wxART_HELP_BOOK
         wxART_HELP_FOLDER
         wxART_HELP_PAGE
         wxART_GO_BACK
         wxART_GO_FORWARD
         wxART_GO_UP
         wxART_GO_DOWN
         wxART_GO_TO_PARENT
         wxART_GO_HOME
         wxART_PRINT
         wxART_HELP
         wxART_TIP
         wxART_REPORT_VIEW
         wxART_LIST_VIEW
         wxART_NEW_DIR
         wxART_FOLDER
         wxART_FOLDER_OPEN
         wxART_GO_DIR_UP
         wxART_EXECUTABLE_FILE
         wxART_NORMAL_FILE
         wxART_TICK_MARK
         wxART_CROSS_MARK
         wxART_MISSING_IMAGE
         wxART_NEW
         wxART_FILE_OPEN
         wxART_FILE_SAVE
         wxART_FILE_SAVE_AS
         wxART_DELETE
         wxART_COPY
         wxART_CUT
         wxART_PASTE
         wxART_UNDO
         wxART_REDO
         wxART_QUIT
         wxART_FIND
         wxART_FIND_AND_REPLACE
         wxART_HARDDISK
         wxART_FLOPPY
         wxART_CDROM
         wxART_REMOVABLE
        
        Additionally, any string recognized by custom art providers registered using 
        Push() may be used.
    */


    /**
        Register new art provider and add it to the bottom of providers stack (i.e.
        it will be queried as the last one).
        
        @sa Push()
    */
    static void Insert(wxArtProvider* provider);

    /**
        Remove latest added provider and delete it.
    */
#define static bool Pop()     /* implementation is private */

    /**
        Register new art provider and add it to the top of providers stack (i.e. it
        will be queried as the first provider).
        
        @sa Insert()
    */
    static void Push(wxArtProvider* provider);

    /**
        Remove a provider from the stack if it is on it. The provider is not 
        deleted, unlike when using Delete().
    */
    static bool Remove(wxArtProvider* provider);
};
Commit	Line	Data
23324ae1 FM	1	/////////////////////////////////////////////////////////////////////////////
	2	// Name: artprov.h
	3	// Purpose: documentation for wxArtProvider class
	4	// Author: wxWidgets team
	5	// RCS-ID: $Id$
	6	// Licence: wxWindows license
	7	/////////////////////////////////////////////////////////////////////////////
	8
	9	/**
	10	@class wxArtProvider
	11	@wxheader{artprov.h}
	12
	13	wxArtProvider class is used to customize the look of wxWidgets application.
	14	When wxWidgets needs to display an icon or a bitmap (e.g. in the standard file
	15	dialog), it does not use a hard-coded resource but asks wxArtProvider for it
	16	instead. This way users can plug in their own wxArtProvider class and easily
	17	replace standard art with their own version. All
	18	that is needed is to derive a class from wxArtProvider, override either its
	19	wxArtProvider::CreateBitmap and/or its
	20	wxArtProvider::CreateIconBundle methods
	21	and register the provider with
	22	wxArtProvider::Push:
	23
	24	@code
	25	class MyProvider : public wxArtProvider
	26	{
	27	protected:
	28	wxBitmap CreateBitmap(const wxArtID& id,
	29	const wxArtClient& client,
	30	const wxSize size)
	31
	32	// optionally override this one as well
	33	wxIconBundle CreateIconBundle(const wxArtID& id,
	34	const wxArtClient& client)
	35	{ ... }
	36	};
	37	...
	38	wxArtProvider::Push(new MyProvider);
	39	@endcode
	40
	41	If you need bitmap images (of the same artwork) that should be displayed at
	42	different sizes
	43	you should probably consider overriding wxArtProvider::CreateIconBundle
	44	and supplying icon bundles that contain different bitmap sizes.
	45
	46	There's another way of taking advantage of this class: you can use it in your
	47	code and use
	48	platform native icons as provided by wxArtProvider::GetBitmap or
	49	wxArtProvider::GetIcon (NB: this is not yet really
	50	possible as of wxWidgets 2.3.3, the set of wxArtProvider bitmaps is too
	51	small).
	52
	53
	54	wxArtProvider::~wxArtProvider
	55	wxArtProvider::CreateBitmap
	56	wxArtProvider::CreateIconBundle
	57	wxArtProvider::Delete
	58	wxArtProvider::GetBitmap
	59	wxArtProvider::GetIconBundle
	60	wxArtProvider::GetIcon
	61	wxArtProvider::Insert
	62	wxArtProvider::Pop
	63	wxArtProvider::Push
	64	wxArtProvider::Remove
65
66
67	Identifying art resources
68
69	Every bitmap and icon bundle are known to wxArtProvider under an unique ID that
70	is used when
71	requesting a resource from it. The ID is represented by wxArtID type and can
72	have one of these predefined values (you can see bitmaps represented by these
73	constants in the artprov sample):
74
75	wxART_ERROR
76	wxART_QUESTION
77	wxART_WARNING
78	wxART_INFORMATION
79	wxART_ADD_BOOKMARK
80	wxART_DEL_BOOKMARK
81	wxART_HELP_SIDE_PANEL
82	wxART_HELP_SETTINGS
83	wxART_HELP_BOOK
84	wxART_HELP_FOLDER
85	wxART_HELP_PAGE
86	wxART_GO_BACK
87	wxART_GO_FORWARD
88	wxART_GO_UP
89	wxART_GO_DOWN
90	wxART_GO_TO_PARENT
91	wxART_GO_HOME
92	wxART_PRINT
93	wxART_HELP
94	wxART_TIP
95	wxART_REPORT_VIEW
96	wxART_LIST_VIEW
97	wxART_NEW_DIR
98	wxART_FOLDER
99	wxART_FOLDER_OPEN
100	wxART_GO_DIR_UP
101	wxART_EXECUTABLE_FILE
102	wxART_NORMAL_FILE
103	wxART_TICK_MARK
104	wxART_CROSS_MARK
105	wxART_MISSING_IMAGE
106	wxART_NEW
107	wxART_FILE_OPEN
108	wxART_FILE_SAVE
109	wxART_FILE_SAVE_AS
110	wxART_DELETE
111	wxART_COPY
112	wxART_CUT
113	wxART_PASTE
114	wxART_UNDO
115	wxART_REDO
116	wxART_QUIT
117	wxART_FIND
118	wxART_FIND_AND_REPLACE
119	wxART_HARDDISK
120	wxART_FLOPPY
121	wxART_CDROM
122	wxART_REMOVABLE
123
124
125	Additionally, any string recognized by custom art providers registered using
126	wxArtProvider::Push may be used.
127
128	@library{wxcore}
129	@category{FIXME}
130
131	@seealso
132	See the artprov sample for an example of wxArtProvider usage.
133	*/
134	class wxArtProvider : public wxObject
135	{
136	public:
137	/**
138	The destructor automatically removes the provider from the provider stack used
139	by GetBitmap().
140	*/
141	~wxArtProvider();
142
143	/**
144	Client is the entity that calls wxArtProvider's GetBitmap or GetIcon
145	function. It is represented by wxClientID type and can have one of these
146	values:
147
148	wxART_TOOLBAR
149	wxART_MENU
150	wxART_BUTTON
151	wxART_FRAME_ICON
152	wxART_CMN_DIALOG
153	wxART_HELP_BROWSER
154	wxART_MESSAGE_BOX
155	wxART_OTHER (used for all requests that don't fit into any of the categories
156	above)
157
158	Client ID servers as a hint to wxArtProvider that is supposed to help it to
159	choose the best looking bitmap. For example it is often desirable to use
160	slightly different icons in menus and toolbars even though they represent the
161	same action (e.g. @c wx_ART_FILE_OPEN). Remember that this is really
162	only a hint for wxArtProvider -- it is common that
163	GetBitmap()
164	returns identical bitmap for different @e client values!
165
166	@sa See the artprov sample for an example of wxArtProvider usage.
167	*/
168
169
170	/**
171	Derived art provider classes must override this method to create requested art
172	resource. Note that returned bitmaps are cached by wxArtProvider and it is
173	therefore not necessary to optimize CreateBitmap() for speed (e.g. you may
174	create wxBitmap objects from XPMs here).
175
176	@param id
177	wxArtID unique identifier of the bitmap.
178
179	@param client
180	wxArtClient identifier of the client (i.e. who is asking for the bitmap).
181	This only servers as a hint.
182
183	@param size
184	Preferred size of the bitmap. The function may return a bitmap of different
185	dimensions, it will be automatically rescaled to meet client's request.
186
187	@sa CreateIconBundle()
188	*/
189	wxBitmap CreateBitmap(const wxArtID& id,
190	const wxArtClient& client,
191	const wxSize& size);
192
193	/**
194	This method is similar to CreateBitmap() but
195	can be used when a bitmap (or an icon) exists in several sizes.
196	*/
197	wxIconBundle CreateIconBundle(const wxArtID& id,
198	const wxArtClient& client);
199
200	/**
201	Delete the given @e provider.
202	*/
203	static bool Delete(wxArtProvider* provider);
204
205	/**
206	Query registered providers for bitmap with given ID.
207
208	@param id
209	wxArtID unique identifier of the bitmap.
210
211	@param client
212	wxArtClient identifier of the client (i.e. who is asking for the bitmap).
213
214	@param size
215	Size of the returned bitmap or wxDefaultSize if size doesn't matter.
216
217	@returns The bitmap if one of registered providers recognizes the ID or
218	wxNullBitmap otherwise.
219	*/
220	static wxBitmap GetBitmap(const wxArtID& id,
221	const wxArtClient& client = wxART_OTHER,
222	const wxSize& size = wxDefaultSize);
223
224	//@{
225	/**
226	Returns a suitable size hint for the given @e wxArtClient. If
227	@e platform_default is @true, return a size based on the current platform,
228	otherwise return the size from the topmost wxArtProvider. @e wxDefaultSize may
229	be
230	returned if the client doesn't have a specified size, like wxART_OTHER for
231	example.
232	*/
233	static wxIcon GetIcon(const wxArtID& id,
234	const wxArtClient& client = wxART_OTHER,
235	const wxSize& size = wxDefaultSize);
236	static wxSize GetSizeHint(const wxArtClient& client,
237	bool platform_default = @false);
238	//@}
239
240	/**
241	Query registered providers for icon bundle with given ID.
242
243	@param id
244	wxArtID unique identifier of the icon bundle.
245
246	@param client
247	wxArtClient identifier of the client (i.e. who is asking for the icon bundle).
248
249	@returns The icon bundle if one of registered providers recognizes the ID
250	or wxNullIconBundle otherwise.
251	*/
252	static wxIconBundle GetIconBundle(const wxArtID& id,
253	const wxArtClient& client = wxART_OTHER);
254
255	/**
256	Every bitmap and icon bundle are known to wxArtProvider under an unique ID that
257	is used when
258	requesting a resource from it. The ID is represented by wxArtID type and can
259	have one of these predefined values (you can see bitmaps represented by these
260	constants in the artprov sample):
261
262	wxART_ERROR
263	wxART_QUESTION
264	wxART_WARNING
265	wxART_INFORMATION
266	wxART_ADD_BOOKMARK
267	wxART_DEL_BOOKMARK
268	wxART_HELP_SIDE_PANEL
269	wxART_HELP_SETTINGS
270	wxART_HELP_BOOK
271	wxART_HELP_FOLDER
272	wxART_HELP_PAGE
273	wxART_GO_BACK
274	wxART_GO_FORWARD
275	wxART_GO_UP
276	wxART_GO_DOWN
277	wxART_GO_TO_PARENT
278	wxART_GO_HOME
279	wxART_PRINT
280	wxART_HELP
281	wxART_TIP
282	wxART_REPORT_VIEW
283	wxART_LIST_VIEW
284	wxART_NEW_DIR
285	wxART_FOLDER
286	wxART_FOLDER_OPEN
287	wxART_GO_DIR_UP
288	wxART_EXECUTABLE_FILE
289	wxART_NORMAL_FILE
290	wxART_TICK_MARK
291	wxART_CROSS_MARK
292	wxART_MISSING_IMAGE
293	wxART_NEW
294	wxART_FILE_OPEN
295	wxART_FILE_SAVE
296	wxART_FILE_SAVE_AS
297	wxART_DELETE
298	wxART_COPY
299	wxART_CUT
300	wxART_PASTE
301	wxART_UNDO
302	wxART_REDO
303	wxART_QUIT
304	wxART_FIND
305	wxART_FIND_AND_REPLACE
306	wxART_HARDDISK
307	wxART_FLOPPY
308	wxART_CDROM
309	wxART_REMOVABLE
310
311	Additionally, any string recognized by custom art providers registered using
312	Push() may be used.
313	*/
314
315
316	/**
317	Register new art provider and add it to the bottom of providers stack (i.e.
318	it will be queried as the last one).
319
320	@sa Push()
321	*/
322	static void Insert(wxArtProvider* provider);
323
324	/**
325	Remove latest added provider and delete it.
326	*/
327	#define static bool Pop() /* implementation is private */
328
329	/**
330	Register new art provider and add it to the top of providers stack (i.e. it
331	will be queried as the first provider).
332
333	@sa Insert()
334	*/
335	static void Push(wxArtProvider* provider);
336
337	/**
338	Remove a provider from the stack if it is on it. The provider is not
339	deleted, unlike when using Delete().
340	*/
341	static bool Remove(wxArtProvider* provider);
342	};