X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/f4fcc2919776cffa5e3b2f0d44dd24c41e652ff4..749bb9f1291c3c967a25cbbd9aed98a89f7e1511:/docs/latex/wx/artprov.tex?ds=sidebyside diff --git a/docs/latex/wx/artprov.tex b/docs/latex/wx/artprov.tex index e3dc351157..8443208a9b 100644 --- a/docs/latex/wx/artprov.tex +++ b/docs/latex/wx/artprov.tex @@ -5,7 +5,101 @@ \section{\class{wxArtProvider}}\label{wxartprovider} -wxArtProvider class. +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}: + +\begin{verbatim} + class MyProvider : public wxArtProvider + { + protected: + wxBitmap CreateBitmap(const wxArtID& id, + const wxArtClient& client, + const wxSize size) + { ... } + }; + ... + wxArtProvider::PushProvider(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} + +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} + +\membersection{Clients} + +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\_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} @@ -15,59 +109,75 @@ wxArtProvider class. -\wxheading{Data structures} +\latexignore{\rtfignore{\wxheading{Members}}} -{\small \begin{verbatim} -typedef wxString wxArtClient -typedef wxString wxArtID -\end{verbatim}} +\membersection{wxArtProvider::CreateBitmap}\label{wxartprovidercreatebitmap} -\latexignore{\rtfignore{\wxheading{Members}}} +\func{wxBitmap}{CreateBitmap}{\param{const wxArtID\& }{id}, \param{const wxArtClient\& }{client}, \param{const wxSize\& }{size}} -\membersection{wxArtProvider::CleanUpProviders}\label{wxartprovidercleanupproviders} +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). -\func{void}{CleanUpProviders}{\void} +\wxheading{Parameters} -Destroy caches and all providers. +\docparam{id}{wxArtID unique identifier of the bitmap.} -\membersection{wxArtProvider::CreateBitmap}\label{wxartprovidercreatebitmap} +\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 +dimensions, it will be automatically rescaled to meet client's request.} -\func{wxBitmap}{CreateBitmap}{\param{const wxArtID\& }{WXUNUSED(id)}, \param{const wxArtClient\& }{WXUNUSED(client)}, \param{const wxSize\& }{WXUNUSED(size)}} +\wxheading{Note} -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. +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::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} -Query the providers for bitmap with given ID and return it. Return -wxNullBitmap if no provider provides it. +The bitmap if one of registered providers recognizes the ID or wxNullBitmap otherwise. \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}} -Query the providers for icon with given ID and return it. Return -wxNullIcon if no provider provides it. +Same as \helpref{wxArtProvider::GetBitmap}{wxartprovidergetbitmap}, but +return a wxIcon object (or wxNullIcon on failure). \membersection{wxArtProvider::PopProvider}\label{wxartproviderpopprovider} -\func{bool}{PopProvider}{\void} +\func{static bool}{PopProvider}{\void} Remove latest added provider and delete it. \membersection{wxArtProvider::PushProvider}\label{wxartproviderpushprovider} -\func{void}{PushProvider}{\param{wxArtProvider* }{provider}} +\func{static void}{PushProvider}{\param{wxArtProvider* }{provider}} -Add new provider to the top of providers stack. +Register new art provider (add it to the top of providers stack). \membersection{wxArtProvider::RemoveProvider}\label{wxartproviderremoveprovider} -\func{bool}{RemoveProvider}{\param{wxArtProvider* }{provider}} +\func{static bool}{RemoveProvider}{\param{wxArtProvider* }{provider}} -Remove provider. The provider must have been added previously. -The provider is {\it not} deleted. +Remove a provider from the stack. The provider must have been added previously +and is {\it not} deleted.