X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/f4fcc2919776cffa5e3b2f0d44dd24c41e652ff4..81c882b613b5d99ddb1e5ab69fcd7ebccc287025:/docs/latex/wx/artprov.tex diff --git a/docs/latex/wx/artprov.tex b/docs/latex/wx/artprov.tex index e3dc351157..cb6692cac9 100644 --- a/docs/latex/wx/artprov.tex +++ b/docs/latex/wx/artprov.tex @@ -5,7 +5,145 @@ \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 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 + { + 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); +\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 +\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 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\_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{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} @@ -15,59 +153,151 @@ wxArtProvider class. -\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} -\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::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}. -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} -\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. + + +\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. -Query the providers for bitmap with given ID and return it. Return -wxNullBitmap if no provider provides it. \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. -\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}.