Avoid missing ref

[wxWidgets.git] / docs / latex / wx / artprov.tex

diff --git a/docs/latex/wx/artprov.tex b/docs/latex/wx/artprov.tex
index e3dc351157d1f88d435291306c95622f5012962f..8c2b6d4aaf5a4e567f16fe3e134b51a3432a402e 100644 (file)
--- a/docs/latex/wx/artprov.tex
+++ b/docs/latex/wx/artprov.tex
@@ -5,7 +5,117 @@
 
 \section{\class{wxArtProvider}}\label{wxartprovider}
 
 
 \section{\class{wxArtProvider}}\label{wxartprovider}
 

-wxArtProvider class.
+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 its
+\helpref{CreateBitmap}{wxartprovidercreatebitmap} method and register the
+provider with
+\helpref{wxArtProvider::Push}{wxartproviderpush}:
+
+\begin{verbatim}
+  class MyProvider : public wxArtProvider
+  {
+  protected:
+    wxBitmap CreateBitmap(const wxArtID& id, 
+                          const wxArtClient& client,
+                          const wxSize size)
+    { ... }
+  };
+  ...
+  wxArtProvider::Push(new MyProvider);
+\end{verbatim}
+
+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 
+\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}\label{artprovideridentifying}
+
+Every bitmap is known to wxArtProvider under an unique ID that is used by 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      
+\end{itemize}
+
+Additionally, any string recognized by custom art providers registered using 
+\helpref{Push}{wxartproviderpush} may be used.
+
+\wxheading{GTK+ Note}
+
+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 
+values:
+\begin{itemize}\itemsep=0pt
+\item wxART\_TOOLBAR
+\item wxART\_MENU
+\item wxART\_BUTTON
+\item wxART\_FRAME\_ICON
+\item wxART\_CMN\_DIALOG
+\item wxART\_HELP\_BROWSER
+\item wxART\_MESSAGE\_BOX
+\item wxART\_OTHER (used for all requests that don't fit into any of the categories above)
+\end{itemize}
+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. {\tt wx\_ART\_FILE\_OPEN}). Remember that this is really
+only a hint for wxArtProvider -- it is common that
+\helpref{wxArtProvider::GetBitmap}{wxartprovidergetbitmap} 
+returns identical bitmap for different {\it client} values!
+
+\wxheading{See also}
+
+See the \helpref{artprov}{sampleartprovider} sample for an example of wxArtProvider usage.

 
 \wxheading{Derived from}
 
 
 \wxheading{Derived from}
 


@@ -15,59 +125,120 @@ wxArtProvider class.
 
 <wx/artprov.h>
 
 
 <wx/artprov.h>
 

-\wxheading{Data structures}
+\latexignore{\rtfignore{\wxheading{Members}}}

 
 

-{\small \begin{verbatim}
-typedef wxString wxArtClient
-typedef wxString wxArtID
-\end{verbatim}}

 
 

-\latexignore{\rtfignore{\wxheading{Members}}}
+\membersection{wxArtProvider::\destruct{wxArtProvider}}\label{wxartproviderdtor}

 
 

-\membersection{wxArtProvider::CleanUpProviders}\label{wxartprovidercleanupproviders}
+\func{}{\destruct{wxArtProvider}}{\void}

 
 

-\func{void}{CleanUpProviders}{\void}
+The destructor automatically removes the provider from the provider stack used
+by \helpref{GetBitmap}{wxartprovidergetbitmap}.

 
 

-Destroy caches and all providers.

 
 \membersection{wxArtProvider::CreateBitmap}\label{wxartprovidercreatebitmap}
 
 
 \membersection{wxArtProvider::CreateBitmap}\label{wxartprovidercreatebitmap}
 

-\func{wxBitmap}{CreateBitmap}{\param{const wxArtID\& }{WXUNUSED(id)}, \param{const wxArtClient\& }{WXUNUSED(client)}, \param{const wxSize\& }{WXUNUSED(size)}}
+\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 necessary to optimize CreateBitmap for speed (e.g. you may create wxBitmap objects
+from XPMs here).
+
+\wxheading{Parameters}
+
+\docparam{id}{wxArtID unique identifier of the bitmap.}
+
+\docparam{client}{wxArtClient identifier of the client (i.e. who is asking for the bitmap).
+This only servers as a hint.}
+
+\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::GetIcon}{wxartprovidergeticon}
+to query wxArtProvider for a resource.
+
+
+\membersection{wxArtProvider::Delete}\label{wxartproviderdelete}
+
+\func{static bool}{Delete}{\param{wxArtProvider* }{provider}}
+
+Delete the given \arg{provider}.

 
 

-Derived classes must override this method to create requested 
-art resource. This method is called only once per instance's
-lifetime for each requested wxArtID.

 
 \membersection{wxArtProvider::GetBitmap}\label{wxartprovidergetbitmap}
 
 
 \membersection{wxArtProvider::GetBitmap}\label{wxartprovidergetbitmap}
 

-\func{wxBitmap}{GetBitmap}{\param{const wxArtID\& }{id}, \param{const wxArtClient\& }{client = wxART\_OTHER}, \param{const wxSize\& }{size = wxDefaultSize}}
+\func{static wxBitmap}{GetBitmap}{\param{const wxArtID\& }{id}, \param{const wxArtClient\& }{client = wxART\_OTHER}, \param{const wxSize\& }{size = wxDefaultSize}}
+
+Query registered providers for bitmap with given ID.
+
+\wxheading{Parameters}
+
+\docparam{id}{wxArtID unique identifier of the bitmap.}
+
+\docparam{client}{wxArtClient identifier of the client (i.e. who is asking for the bitmap).}
+
+\docparam{size}{Size of the returned bitmap or {\tt wxDefaultSize} if size doesn't matter.}
+
+\wxheading{Return value}
+
+The bitmap if one of registered providers recognizes the ID or wxNullBitmap otherwise.

 
 

-Query the providers for bitmap with given ID and return it. Return
-wxNullBitmap if no provider provides it.

 
 \membersection{wxArtProvider::GetIcon}\label{wxartprovidergeticon}
 
 
 \membersection{wxArtProvider::GetIcon}\label{wxartprovidergeticon}
 

-\func{wxIcon}{GetIcon}{\param{const wxArtID\& }{id}, \param{const wxArtClient\& }{client = wxART\_OTHER}, \param{const wxSize\& }{size = wxDefaultSize}}
+\func{static wxIcon}{GetIcon}{\param{const wxArtID\& }{id}, \param{const wxArtClient\& }{client = wxART\_OTHER}, \param{const wxSize\& }{size = wxDefaultSize}}
+
+Same as \helpref{wxArtProvider::GetBitmap}{wxartprovidergetbitmap}, but
+return a wxIcon object (or wxNullIcon on failure).
+
+\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.
+
+
+\membersection{wxArtProvider::Insert}\label{wxartproviderinsert}

 
 

-Query the providers for icon with given ID and return it. Return
-wxNullIcon if no provider provides it.
+\func{static void}{Insert}{\param{wxArtProvider* }{provider}}

 
 

-\membersection{wxArtProvider::PopProvider}\label{wxartproviderpopprovider}
+Register new art provider and add it to the bottom of providers stack (i.e.
+it will be queried as the last one).

 
 

-\func{bool}{PopProvider}{\void}
+\wxheading{See also}
+
+\helpref{Push}{wxartproviderpush}
+
+
+\membersection{wxArtProvider::Pop}\label{wxartproviderctor}
+
+\func{static bool}{Pop}{\void}

 
 Remove latest added provider and delete it.
 
 
 Remove latest added provider and delete it.
 

-\membersection{wxArtProvider::PushProvider}\label{wxartproviderpushprovider}

 
 

-\func{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}

 
 

-Add new provider to the top of providers stack.

 
 

-\membersection{wxArtProvider::RemoveProvider}\label{wxartproviderremoveprovider}
+\membersection{wxArtProvider::Remove}\label{wxartproviderremove}

 
 

-\func{bool}{RemoveProvider}{\param{wxArtProvider* }{provider}}
+\func{static bool}{Remove}{\param{wxArtProvider* }{provider}}

 
 

-Remove provider. The provider must have been added previously.
-The provider 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}.