X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/e53a95bcb122a06a74e116aba717b0d7a5bdc1b8..81c882b613b5d99ddb1e5ab69fcd7ebccc287025:/docs/latex/wx/artprov.tex diff --git a/docs/latex/wx/artprov.tex b/docs/latex/wx/artprov.tex index fedf79d678..cb6692cac9 100644 --- a/docs/latex/wx/artprov.tex +++ b/docs/latex/wx/artprov.tex @@ -10,10 +10,11 @@ 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::PushProvider}{wxartproviderpushprovider}: +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,60 +23,88 @@ 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 \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 +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. +Additionally, any string recognized by custom art providers registered using +\helpref{Push}{wxartproviderpush} may be used. \wxheading{GTK+ Note} @@ -88,6 +117,7 @@ by GTK+ follow the 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 @@ -125,14 +155,23 @@ See the \helpref{artprov}{sampleartprovider} sample for an example of wxArtProvi \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 necessary 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} @@ -148,9 +187,31 @@ dimensions, it will be automatically rescaled to meet client's request.} 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}} @@ -169,6 +230,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}} @@ -176,29 +255,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). -\func{static wxSize}{GetSizeHint}{\param{const wxArtClient\& }{client}, \param{bool }{platform_default = false}} +\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, +{\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. +returned if the client doesn't have a specified size, like wxART\_OTHER for example. + -\membersection{wxArtProvider::PopProvider}\label{wxartproviderctor} +\membersection{wxArtProvider::Insert}\label{wxartproviderinsert} -\func{static bool}{PopProvider}{\void} +\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}.