a7af285d1a
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@47777 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
308 lines
10 KiB
TeX
308 lines
10 KiB
TeX
%
|
|
% automatically generated by HelpGen $Revision$ from
|
|
% artprov.h at 08/Apr/02 17:44:57
|
|
%
|
|
|
|
\section{\class{wxArtProvider}}\label{wxartprovider}
|
|
|
|
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}
|
|
|
|
\helpref{wxObject}{wxobject}
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/artprov.h>
|
|
|
|
\wxheading{Library}
|
|
|
|
\helpref{wxCore}{librarieslist}
|
|
|
|
\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).
|
|
|
|
\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}.
|
|
|
|
|
|
\membersection{wxArtProvider::GetBitmap}\label{wxartprovidergetbitmap}
|
|
|
|
\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.
|
|
|
|
|
|
\membersection{wxArtProvider::GetIcon}\label{wxartprovidergeticon}
|
|
|
|
\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}
|
|
|
|
\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::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}
|
|
|
|
|
|
\membersection{wxArtProvider::Remove}\label{wxartproviderremove}
|
|
|
|
\func{static bool}{Remove}{\param{wxArtProvider* }{provider}}
|
|
|
|
Remove a provider from the stack if it is on it. The provider is {\emph not}
|
|
deleted, unlike when using \helpref{Delete()}{wxartproviderdelete}.
|
|
|