some wxArtProv docs
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@15183 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Václav Slavík
@@ -5,7 +5,100 @@
|
||||
|
||||
\section{\class{wxArtProvider}}\label{wxartprovider}
|
||||
|
||||
wxArtProvider class.
|
||||
wxArtProvider class is used to customize the look of wxWindows application.
|
||||
When wxWindows 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 wxWindows 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
|
||||
\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,61 +108,75 @@ wxArtProvider class.
|
||||
|
||||
<wx/artprov.h>
|
||||
|
||||
\wxheading{Data structures}
|
||||
|
||||
{\small
|
||||
\begin{verbatim}
|
||||
typedef wxString wxArtClient
|
||||
typedef wxString wxArtID
|
||||
\end{verbatim}
|
||||
}
|
||||
|
||||
\latexignore{\rtfignore{\wxheading{Members}}}
|
||||
|
||||
\membersection{wxArtProvider::CleanUpProviders}\label{wxartprovidercleanupproviders}
|
||||
|
||||
\func{void}{CleanUpProviders}{\void}
|
||||
|
||||
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 classes must override this method to create requested
|
||||
art resource. This method is called only once per instance's
|
||||
lifetime for each requested wxArtID.
|
||||
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).
|
||||
|
||||
\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}{Prefered 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::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 the providers for bitmap with given ID and return it. Return
|
||||
wxNullBitmap if no provider provides it.
|
||||
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::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.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user