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 wxWindows application.
   9 When wxWindows 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 wxWindows 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 \end{itemize}
  76
  77 \membersection{Clients}
  78
  79 Client is the entity that calls wxArtProvider's GetBitmap or GetIcon
  80 function. It is represented by wxClientID type and can have one of these
  81 values:
  82 \begin{itemize}\itemsep=0pt
  83 \item wxART\_TOOLBAR
  84 \item wxART\_MENU
  85 \item wxART\_FRAME\_ICON
  86 \item wxART\_CMN\_DIALOG
  87 \item wxART\_HELP\_BROWSER
  88 \item wxART\_MESSAGE\_BOX
  89 \item wxART\_OTHER (used for all requests that don't fit into any of the categories above)
  90 \end{itemize}
  91 Client ID servers as a hint to wxArtProvider that is supposed to help it to
  92 choose the best looking bitmap. For example it is often desirable to use
  93 slightly different icons in menus and toolbars even though they represent the
  94 same action (e.g. {\tt wx\_ART\_FILE\_OPEN}). Remember that this is really
  95 only a hint for wxArtProvider -- it is common that
  96 \helpref{wxArtProvider::GetBitmap}{wxartprovidergetbitmap}
  97 returns identical bitmap for different {\it client} values!
  98
  99 \wxheading{See also}
 100
 101 See the \helpref{artprov}{sampleartprovider} sample for an example of wxArtProvider usage.
 102
 103 \wxheading{Derived from}
 104
 105 \helpref{wxObject}{wxobject}
 106
 107 \wxheading{Include files}
 108
 109 <wx/artprov.h>
 110
 111 \latexignore{\rtfignore{\wxheading{Members}}}
 112
 113 \membersection{wxArtProvider::CreateBitmap}\label{wxartprovidercreatebitmap}
 114
 115 \func{wxBitmap}{CreateBitmap}{\param{const wxArtID\& }{id}, \param{const wxArtClient\& }{client}, \param{const wxSize\& }{size}}
 116
 117 Derived art provider classes must override this method to create requested
 118 art resource. Note that returned bitmaps are cached by wxArtProvider and it is therefore
 119 not neccessary to optimize CreateBitmap for speed (e.g. you may create wxBitmap objects
 120 from XPMs here).
 121
 122 \wxheading{Parameters}
 123
 124 \docparam{id}{wxArtID unique identifier of the bitmap.}
 125
 126 \docparam{client}{wxArtClient identifier of the client (i.e. who is asking for the bitmap).
 127 This only servers as a hint.}
 128
 129 \docparam{size}{Prefered size of the bitmap. The function may return a bitmap of different
 130 dimensions, it will be automatically rescaled to meet client's request.}
 131
 132 \wxheading{Note}
 133
 134 This is {\bf not} part of wxArtProvider's public API, use
 135 \helpref{wxArtProvider::GetBitmap}{wxartprovidergetbitmap} or
 136 \helpref{wxArtProvider::GetIcon}{wxartprovidergeticon}
 137 to query wxArtProvider for a resource.
 138
 139 \membersection{wxArtProvider::GetBitmap}\label{wxartprovidergetbitmap}
 140
 141 \func{static wxBitmap}{GetBitmap}{\param{const wxArtID\& }{id}, \param{const wxArtClient\& }{client = wxART\_OTHER}, \param{const wxSize\& }{size = wxDefaultSize}}
 142
 143 Query registered providers for bitmap with given ID.
 144
 145 \wxheading{Parameters}
 146
 147 \docparam{id}{wxArtID unique identifier of the bitmap.}
 148
 149 \docparam{client}{wxArtClient identifier of the client (i.e. who is asking for the bitmap).}
 150
 151 \docparam{size}{Size of the returned bitmap or {\tt wxDefaultSize} if size doesn't matter.}
 152
 153 \wxheading{Return value}
 154
 155 The bitmap if one of registered providers recognizes the ID or wxNullBitmap otherwise.
 156
 157 \membersection{wxArtProvider::GetIcon}\label{wxartprovidergeticon}
 158
 159 \func{static wxIcon}{GetIcon}{\param{const wxArtID\& }{id}, \param{const wxArtClient\& }{client = wxART\_OTHER}, \param{const wxSize\& }{size = wxDefaultSize}}
 160
 161 Same as \helpref{wxArtProvider::GetBitmap}{wxartprovidergetbitmap}, but
 162 return a wxIcon object (or wxNullIcon on failure).
 163
 164 \membersection{wxArtProvider::PopProvider}\label{wxartproviderpopprovider}
 165
 166 \func{static bool}{PopProvider}{\void}
 167
 168 Remove latest added provider and delete it.
 169
 170 \membersection{wxArtProvider::PushProvider}\label{wxartproviderpushprovider}
 171
 172 \func{static void}{PushProvider}{\param{wxArtProvider* }{provider}}
 173
 174 Register new art provider (add it to the top of providers stack).
 175
 176 \membersection{wxArtProvider::RemoveProvider}\label{wxartproviderremoveprovider}
 177
 178 \func{static bool}{RemoveProvider}{\param{wxArtProvider* }{provider}}
 179
 180 Remove a provider from the stack. The provider must have been added previously
 181 and is {\it not} deleted.
 182