X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/7bebedd82651a0fc6cf002497956c467375362f7..180b5b4827d08f1ac13bbb5eca03f775ab35a0b1:/docs/latex/wx/artprov.tex

diff --git a/docs/latex/wx/artprov.tex b/docs/latex/wx/artprov.tex
index 6263d30628..18c24acaeb 100644
--- a/docs/latex/wx/artprov.tex
+++ b/docs/latex/wx/artprov.tex
@@ -6,14 +6,15 @@
 \section{\class{wxArtProvider}}\label{wxartprovider}
 
 wxArtProvider class is used to customize the look of wxWidgets application.
-When wxWidgets need to display an icon or a bitmap (e.g. in the standard file
-dialog), it does not use hard-coded resource but asks wxArtProvider for it
-instead. This way the users can plug in own wxArtProvider class and easily
-replace standard art with his/her own version. It is easy thing to do: all
-that is needed is to derive a class from wxArtProvider, override it's
-\helpref{CreateBitmap}{wxartprovidercreatebitmap} method and register the
-provider with
-\helpref{wxArtProvider::PushProvider}{wxartproviderpushprovider}:
+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
+\helpref{CreateBitmap}{wxartprovidercreatebitmap} and/or its
+\helpref{CreateIconBundle}{wxartprovidercreateiconbundle} methods
+and register the provider with
+\helpref{wxArtProvider::Push}{wxartproviderpush}:
 
 \begin{verbatim}
   class MyProvider : public wxArtProvider
@@ -22,64 +23,102 @@ provider with
     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::PushProvider(new MyProvider);
+  wxArtProvider::Push(new MyProvider);
 \end{verbatim}
 
+If you need bitmap images (of the same artwork) that should be displayed at different sizes
+you should probably consider overriding \helpref{CreateIconBundle()}{wxartprovidercreateiconbundle} 
+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
-\helpref{wxArtProvider::GetBitmap}{wxartprovidergetbitmap} or 
+platform native icons as provided by \helpref{wxArtProvider::GetBitmap}{wxartprovidergetbitmap} or 
 \helpref{wxArtProvider::GetIcon}{wxartprovidergeticon} (NB: this is not yet really
 possible as of wxWidgets 2.3.3, the set of wxArtProvider bitmaps is too
 small). 
 
-\membersection{Identifying art resources}
 
-Every bitmap is known to wxArtProvider under an unique ID that is used by when
+\membersection{Identifying art resources}\label{artprovideridentifying}
+
+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 \helpref{artprov}{sampleartprovider} sample):
 \begin{itemize}\itemsep=0pt
-\item wxART\_ADD\_BOOKMARK     
-\item wxART\_DEL\_BOOKMARK     
-\item wxART\_HELP\_SIDE\_PANEL  
-\item wxART\_HELP\_SETTINGS    
-\item wxART\_HELP\_BOOK        
-\item wxART\_HELP\_FOLDER      
-\item wxART\_HELP\_PAGE        
-\item wxART\_GO\_BACK          
-\item wxART\_GO\_FORWARD       
-\item wxART\_GO\_UP            
-\item wxART\_GO\_DOWN          
-\item wxART\_GO\_TO\_PARENT     
-\item wxART\_GO\_HOME          
-\item wxART\_FILE\_OPEN        
-\item wxART\_PRINT            
-\item wxART\_HELP             
-\item wxART\_TIP              
-\item wxART\_REPORT\_VIEW      
-\item wxART\_LIST\_VIEW        
-\item wxART\_NEW\_DIR          
-\item wxART\_FOLDER           
-\item wxART\_GO\_DIR\_UP        
-\item wxART\_EXECUTABLE\_FILE  
-\item wxART\_NORMAL\_FILE      
-\item wxART\_TICK\_MARK        
-\item wxART\_CROSS\_MARK       
-\item wxART\_ERROR            
-\item wxART\_QUESTION         
-\item wxART\_WARNING          
-\item wxART\_INFORMATION      
-\item wxART\_MISSING\_IMAGE      
+
+\item wxART\_ERROR
+\item wxART\_QUESTION
+\item wxART\_WARNING
+\item wxART\_INFORMATION
+\item wxART\_ADD\_BOOKMARK
+\item wxART\_DEL\_BOOKMARK
+\item wxART\_HELP\_SIDE\_PANEL
+\item wxART\_HELP\_SETTINGS
+\item wxART\_HELP\_BOOK
+\item wxART\_HELP\_FOLDER
+\item wxART\_HELP\_PAGE
+\item wxART\_GO\_BACK
+\item wxART\_GO\_FORWARD
+\item wxART\_GO\_UP
+\item wxART\_GO\_DOWN
+\item wxART\_GO\_TO\_PARENT
+\item wxART\_GO\_HOME
+\item wxART\_PRINT
+\item wxART\_HELP
+\item wxART\_TIP
+\item wxART\_REPORT\_VIEW
+\item wxART\_LIST\_VIEW
+\item wxART\_NEW\_DIR
+\item wxART\_FOLDER
+\item wxART\_FOLDER\_OPEN
+\item wxART\_GO\_DIR\_UP
+\item wxART\_EXECUTABLE\_FILE
+\item wxART\_NORMAL\_FILE
+\item wxART\_TICK\_MARK
+\item wxART\_CROSS\_MARK
+\item wxART\_MISSING\_IMAGE
+\item wxART\_NEW
+\item wxART\_FILE\_OPEN
+\item wxART\_FILE\_SAVE
+\item wxART\_FILE\_SAVE\_AS
+\item wxART\_DELETE
+\item wxART\_COPY
+\item wxART\_CUT
+\item wxART\_PASTE
+\item wxART\_UNDO
+\item wxART\_REDO
+\item wxART\_QUIT
+\item wxART\_FIND
+\item wxART\_FIND\_AND\_REPLACE
+\item wxART\_HARDDISK
+\item wxART\_FLOPPY
+\item wxART\_CDROM
+\item wxART\_REMOVABLE
+
 \end{itemize}
 
-Additionally, any string recognized by custom art providers registered using
-\helpref{PushProvider}{wxartproviderpushprovider} may be used. When running
-under GTK+ 2, GTK+ stock item IDs (e.g. {\tt "gtk-cdrom"}) may be used as well.
+Additionally, any string recognized by custom art providers registered using 
+\helpref{Push}{wxartproviderpush} may be used.
+
+\wxheading{GTK+ Note}
 
-\membersection{Clients}
+When running under GTK+ 2, GTK+ stock item IDs (e.g. {\tt "gtk-cdrom"}) may
+be used as well. Additionally, if wxGTK was compiled against GTK+ >= 2.4, then
+it is also possible to load icons from current icon theme by specifying their
+name (without extension and directory components). Icon themes recognized
+by GTK+ follow the
+\urlref{freedesktop.org Icon Themes specification}{http://freedesktop.org/Standards/icon-theme-spec}. Note that themes are not guaranteed to contain all
+icons, so wxArtProvider may return {\tt wxNullBitmap} or {\tt wxNullIcon}.
+Default theme is typically installed in {\tt /usr/share/icons/hicolor}.
+
+
+\membersection{Clients}\label{artproviderclients}
 
 Client is the entity that calls wxArtProvider's GetBitmap or GetIcon
 function. It is represented by wxClientID type and can have one of these 
@@ -114,16 +153,29 @@ See the \helpref{artprov}{sampleartprovider} sample for an example of wxArtProvi
 
 <wx/artprov.h>
 
+\wxheading{Library}
+
+\helpref{wxCore}{librarieslist}
+
 \latexignore{\rtfignore{\wxheading{Members}}}
 
+
+\membersection{wxArtProvider::\destruct{wxArtProvider}}\label{wxartproviderdtor}
+
+\func{}{\destruct{wxArtProvider}}{\void}
+
+The destructor automatically removes the provider from the provider stack used
+by \helpref{GetBitmap}{wxartprovidergetbitmap}.
+
+
 \membersection{wxArtProvider::CreateBitmap}\label{wxartprovidercreatebitmap}
 
 \func{wxBitmap}{CreateBitmap}{\param{const wxArtID\& }{id}, \param{const wxArtClient\& }{client}, \param{const wxSize\& }{size}}
 
-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 neccessary to optimize CreateBitmap for speed (e.g. you may create wxBitmap objects
-from XPMs here).
+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).
 
 \wxheading{Parameters}
 
@@ -132,16 +184,38 @@ from XPMs here).
 \docparam{client}{wxArtClient identifier of the client (i.e. who is asking for the bitmap).
 This only servers as a hint.}
 
-\docparam{size}{Prefered size of the bitmap. The function may return a bitmap of different
+\docparam{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.}
 
 \wxheading{Note}
 
 This is {\bf not} part of wxArtProvider's public API, use
 \helpref{wxArtProvider::GetBitmap}{wxartprovidergetbitmap} or 
+\helpref{wxArtProvider::GetIconBundle}{wxartprovidergeticonbundle} or
 \helpref{wxArtProvider::GetIcon}{wxartprovidergeticon}
 to query wxArtProvider for a resource.
 
+\wxheading{See also}
+
+\helpref{CreateIconBundle}{wxartprovidercreateiconbundle}
+
+
+\membersection{wxArtProvider::CreateIconBundle}\label{wxartprovidercreateiconbundle}
+
+\func{wxIconBundle}{CreateIconBundle}{\param{const wxArtID\& }{id}, \param{const wxArtClient\& }{client}}
+
+This method is similar to \helpref{CreateBitmap}{wxartprovidercreatebitmap} but
+can be used when a bitmap (or an icon) exists in several sizes.
+
+
+
+\membersection{wxArtProvider::Delete}\label{wxartproviderdelete}
+
+\func{static bool}{Delete}{\param{wxArtProvider* }{provider}}
+
+Delete the given \arg{provider}.
+
+
 \membersection{wxArtProvider::GetBitmap}\label{wxartprovidergetbitmap}
 
 \func{static wxBitmap}{GetBitmap}{\param{const wxArtID\& }{id}, \param{const wxArtClient\& }{client = wxART\_OTHER}, \param{const wxSize\& }{size = wxDefaultSize}}
@@ -160,6 +234,24 @@ Query registered providers for bitmap with given ID.
 
 The bitmap if one of registered providers recognizes the ID or wxNullBitmap otherwise.
 
+
+\membersection{wxArtProvider::GetIconBundle}\label{wxartprovidergeticonbundle}
+
+\func{static wxIconBundle}{GetIconBundle}{\param{const wxArtID\& }{id}, \param{const wxArtClient\& }{client = wxART\_OTHER}}
+
+Query registered providers for icon bundle with given ID.
+
+\wxheading{Parameters}
+
+\docparam{id}{wxArtID unique identifier of the icon bundle.}
+
+\docparam{client}{wxArtClient identifier of the client (i.e. who is asking for the icon bundle).}
+
+\wxheading{Return value}
+
+The icon bundle if one of registered providers recognizes the ID or wxNullIconBundle otherwise.
+
+
 \membersection{wxArtProvider::GetIcon}\label{wxartprovidergeticon}
 
 \func{static wxIcon}{GetIcon}{\param{const wxArtID\& }{id}, \param{const wxArtClient\& }{client = wxART\_OTHER}, \param{const wxSize\& }{size = wxDefaultSize}}
@@ -167,22 +259,49 @@ The bitmap if one of registered providers recognizes the ID or wxNullBitmap othe
 Same as \helpref{wxArtProvider::GetBitmap}{wxartprovidergetbitmap}, but
 return a wxIcon object (or wxNullIcon on failure).
 
-\membersection{wxArtProvider::PopProvider}\label{wxartproviderpopprovider}
+\func{static wxSize}{GetSizeHint}{\param{const wxArtClient\& }{client}, \param{bool }{platform\_default = false}}
+
+Returns a suitable size hint for the given {\it wxArtClient}. If 
+{\it platform\_default} is \true, return a size based on the current platform, 
+otherwise return the size from the topmost wxArtProvider. {\it wxDefaultSize} may be 
+returned if the client doesn't have a specified size, like wxART\_OTHER for example.
 
-\func{static bool}{PopProvider}{\void}
+
+\membersection{wxArtProvider::Insert}\label{wxartproviderinsert}
+
+\func{static void}{Insert}{\param{wxArtProvider* }{provider}}
+
+Register new art provider and add it to the bottom of providers stack (i.e.
+it will be queried as the last one).
+
+\wxheading{See also}
+
+\helpref{Push}{wxartproviderpush}
+
+
+\membersection{wxArtProvider::Pop}\label{wxartproviderctor}
+
+\func{static bool}{Pop}{\void}
 
 Remove latest added provider and delete it.
 
-\membersection{wxArtProvider::PushProvider}\label{wxartproviderpushprovider}
 
-\func{static void}{PushProvider}{\param{wxArtProvider* }{provider}}
+\membersection{wxArtProvider::Push}\label{wxartproviderpush}
+
+\func{static void}{Push}{\param{wxArtProvider* }{provider}}
+
+Register new art provider and add it to the top of providers stack (i.e. it
+will be queried as the first provider).
+
+\wxheading{See also}
+
+\helpref{Insert}{wxartproviderinsert}
 
-Register new art provider (add it to the top of providers stack).
 
-\membersection{wxArtProvider::RemoveProvider}\label{wxartproviderremoveprovider}
+\membersection{wxArtProvider::Remove}\label{wxartproviderremove}
 
-\func{static bool}{RemoveProvider}{\param{wxArtProvider* }{provider}}
+\func{static bool}{Remove}{\param{wxArtProvider* }{provider}}
 
-Remove a provider from the stack. The provider must have been added previously
-and is {\it not} deleted.
+Remove a provider from the stack if it is on it. The provider is {\emph not} 
+deleted, unlike when using \helpref{Delete()}{wxartproviderdelete}.