docs/latex/wx/artprov.tex

   1 %
   2 % automatically generated by HelpGen $Revision$ from
   3 % artprov.h at 08/Apr/02 17:44:57
   4 %
   5
   6 \section{\class{wxArtProvider}}\label{wxartprovider}
   7
   8 wxArtProvider class is used to customize the look of wxWidgets application.
   9 When wxWidgets need to display an icon or a bitmap (e.g. in the standard file
  10 dialog), it does not use hard-coded resource but asks wxArtProvider for it
  11 instead. This way the users can plug in own wxArtProvider class and easily
  12 replace standard art with his/her own version. It is easy thing to do: all
  13 that is needed is to derive a class from wxArtProvider, override it's
  14 \helpref{CreateBitmap}{wxartprovidercreatebitmap} method and register the
  15 provider with
  16 \helpref{wxArtProvider::PushProvider}{wxartproviderpushprovider}:
  17
  18 \begin{verbatim}
  19   class MyProvider : public wxArtProvider
  20   {
  21   protected:
  22     wxBitmap CreateBitmap(const wxArtID& id,
  23                           const wxArtClient& client,
  24                           const wxSize size)
  25     { ... }
  26   };
  27   ...
  28   wxArtProvider::PushProvider(new MyProvider);
  29 \end{verbatim}
  30
  31 There's another way of taking advantage of this class: you can use it in your code and use
  32 platform native icons as provided by
  33 \helpref{wxArtProvider::GetBitmap}{wxartprovidergetbitmap} or
  34 \helpref{wxArtProvider::GetIcon}{wxartprovidergeticon} (NB: this is not yet really
  35 possible as of wxWidgets 2.3.3, the set of wxArtProvider bitmaps is too
  36 small).
  37
  38 \membersection{Identifying art resources}
  39
  40 Every bitmap is known to wxArtProvider under an unique ID that is used by when
  41 requesting a resource from it. The ID is represented by wxArtID type and can
  42 have one of these predefined values (you can see bitmaps represented by these
  43 constants in the \helpref{artprov}{sampleartprovider} sample):
  44 \begin{itemize}\itemsep=0pt
  45 \item wxART\_ADD\_BOOKMARK
  46 \item wxART\_DEL\_BOOKMARK
  47 \item wxART\_HELP\_SIDE\_PANEL
  48 \item wxART\_HELP\_SETTINGS
  49 \item wxART\_HELP\_BOOK
  50 \item wxART\_HELP\_FOLDER
  51 \item wxART\_HELP\_PAGE
  52 \item wxART\_GO\_BACK
  53 \item wxART\_GO\_FORWARD
  54 \item wxART\_GO\_UP
  55 \item wxART\_GO\_DOWN
  56 \item wxART\_GO\_TO\_PARENT
  57 \item wxART\_GO\_HOME
  58 \item wxART\_FILE\_OPEN
  59 \item wxART\_PRINT
  60 \item wxART\_HELP
  61 \item wxART\_TIP
  62 \item wxART\_REPORT\_VIEW
  63 \item wxART\_LIST\_VIEW
  64 \item wxART\_NEW\_DIR
  65 \item wxART\_FOLDER
  66 \item wxART\_GO\_DIR\_UP
  67 \item wxART\_EXECUTABLE\_FILE
  68 \item wxART\_NORMAL\_FILE
  69 \item wxART\_TICK\_MARK
  70 \item wxART\_CROSS\_MARK
  71 \item wxART\_ERROR
  72 \item wxART\_QUESTION
  73 \item wxART\_WARNING
  74 \item wxART\_INFORMATION
  75 \item wxART\_MISSING\_IMAGE
  76 \end{itemize}
  77
  78 \membersection{Clients}
  79
  80 Client is the entity that calls wxArtProvider's GetBitmap or GetIcon
  81 function. It is represented by wxClientID type and can have one of these
  82 values:
  83 \begin{itemize}\itemsep=0pt
  84 \item wxART\_TOOLBAR
  85 \item wxART\_MENU
  86 \item wxART\_FRAME\_ICON
  87 \item wxART\_CMN\_DIALOG
  88 \item wxART\_HELP\_BROWSER
  89 \item wxART\_MESSAGE\_BOX
  90 \item wxART\_OTHER (used for all requests that don't fit into any of the categories above)
  91 \end{itemize}
  92 Client ID servers as a hint to wxArtProvider that is supposed to help it to
  93 choose the best looking bitmap. For example it is often desirable to use
  94 slightly different icons in menus and toolbars even though they represent the
  95 same action (e.g. {\tt wx\_ART\_FILE\_OPEN}). Remember that this is really
  96 only a hint for wxArtProvider -- it is common that
  97 \helpref{wxArtProvider::GetBitmap}{wxartprovidergetbitmap}
  98 returns identical bitmap for different {\it client} values!
  99
 100 \wxheading{See also}
 101
 102 See the \helpref{artprov}{sampleartprovider} sample for an example of wxArtProvider usage.
 103
 104 \wxheading{Derived from}
 105
 106 \helpref{wxObject}{wxobject}
 107
 108 \wxheading{Include files}
 109
 110 <wx/artprov.h>
 111
 112 \latexignore{\rtfignore{\wxheading{Members}}}
 113
 114 \membersection{wxArtProvider::CreateBitmap}\label{wxartprovidercreatebitmap}
 115
 116 \func{wxBitmap}{CreateBitmap}{\param{const wxArtID\& }{id}, \param{const wxArtClient\& }{client}, \param{const wxSize\& }{size}}
 117
 118 Derived art provider classes must override this method to create requested
 119 art resource. Note that returned bitmaps are cached by wxArtProvider and it is therefore
 120 not neccessary to optimize CreateBitmap for speed (e.g. you may create wxBitmap objects
 121 from XPMs here).
 122
 123 \wxheading{Parameters}
 124
 125 \docparam{id}{wxArtID unique identifier of the bitmap.}
 126
 127 \docparam{client}{wxArtClient identifier of the client (i.e. who is asking for the bitmap).
 128 This only servers as a hint.}
 129
 130 \docparam{size}{Prefered size of the bitmap. The function may return a bitmap of different
 131 dimensions, it will be automatically rescaled to meet client's request.}
 132
 133 \wxheading{Note}
 134
 135 This is {\bf not} part of wxArtProvider's public API, use
 136 \helpref{wxArtProvider::GetBitmap}{wxartprovidergetbitmap} or
 137 \helpref{wxArtProvider::GetIcon}{wxartprovidergeticon}
 138 to query wxArtProvider for a resource.
 139
 140 \membersection{wxArtProvider::GetBitmap}\label{wxartprovidergetbitmap}
 141
 142 \func{static wxBitmap}{GetBitmap}{\param{const wxArtID\& }{id}, \param{const wxArtClient\& }{client = wxART\_OTHER}, \param{const wxSize\& }{size = wxDefaultSize}}
 143
 144 Query registered providers for bitmap with given ID.
 145
 146 \wxheading{Parameters}
 147
 148 \docparam{id}{wxArtID unique identifier of the bitmap.}
 149
 150 \docparam{client}{wxArtClient identifier of the client (i.e. who is asking for the bitmap).}
 151
 152 \docparam{size}{Size of the returned bitmap or {\tt wxDefaultSize} if size doesn't matter.}
 153
 154 \wxheading{Return value}
 155
 156 The bitmap if one of registered providers recognizes the ID or wxNullBitmap otherwise.
 157
 158 \membersection{wxArtProvider::GetIcon}\label{wxartprovidergeticon}
 159
 160 \func{static wxIcon}{GetIcon}{\param{const wxArtID\& }{id}, \param{const wxArtClient\& }{client = wxART\_OTHER}, \param{const wxSize\& }{size = wxDefaultSize}}
 161
 162 Same as \helpref{wxArtProvider::GetBitmap}{wxartprovidergetbitmap}, but
 163 return a wxIcon object (or wxNullIcon on failure).
 164
 165 \membersection{wxArtProvider::PopProvider}\label{wxartproviderpopprovider}
 166
 167 \func{static bool}{PopProvider}{\void}
 168
 169 Remove latest added provider and delete it.
 170
 171 \membersection{wxArtProvider::PushProvider}\label{wxartproviderpushprovider}
 172
 173 \func{static void}{PushProvider}{\param{wxArtProvider* }{provider}}
 174
 175 Register new art provider (add it to the top of providers stack).
 176
 177 \membersection{wxArtProvider::RemoveProvider}\label{wxartproviderremoveprovider}
 178
 179 \func{static bool}{RemoveProvider}{\param{wxArtProvider* }{provider}}
 180
 181 Remove a provider from the stack. The provider must have been added previously
 182 and is {\it not} deleted.
 183