git.saurik.com Git - wxWidgets.git/blob

1 /////////////////////////////////////////////////////////////////////////////

2 // Name: artprov.h

3 // Purpose: interface of wxArtProvider

4 // Author: wxWidgets team

5 // Licence: wxWindows licence

6 /////////////////////////////////////////////////////////////////////////////

8 /**

9 This type identifies the client of the art objects requested to wxArtProvider.

10 */

11 typedef wxString wxArtClient;

13 /**

14 This type identifies a specific art object which can be requested to wxArtProvider.

15 */

16 typedef wxString wxArtID;

19 wxArtClient wxART_TOOLBAR;

20 wxArtClient wxART_MENU;

21 wxArtClient wxART_FRAME_ICON;

23 wxArtClient wxART_CMN_DIALOG;

24 wxArtClient wxART_HELP_BROWSER;

25 wxArtClient wxART_MESSAGE_BOX;

26 wxArtClient wxART_BUTTON;

27 wxArtClient wxART_LIST;

29 wxArtClient wxART_OTHER;

32 wxArtID wxART_ADD_BOOKMARK;

33 wxArtID wxART_DEL_BOOKMARK;

34 wxArtID wxART_HELP_SIDE_PANEL;

35 wxArtID wxART_HELP_SETTINGS;

36 wxArtID wxART_HELP_BOOK;

37 wxArtID wxART_HELP_FOLDER;

38 wxArtID wxART_HELP_PAGE;

39 wxArtID wxART_GO_BACK;

40 wxArtID wxART_GO_FORWARD;

41 wxArtID wxART_GO_UP;

42 wxArtID wxART_GO_DOWN;

43 wxArtID wxART_GO_TO_PARENT;

44 wxArtID wxART_GO_HOME;

45 wxArtID wxART_GOTO_FIRST;

46 wxArtID wxART_GOTO_LAST;

47 wxArtID wxART_FILE_OPEN;

48 wxArtID wxART_FILE_SAVE;

49 wxArtID wxART_FILE_SAVE_AS;

50 wxArtID wxART_PRINT;

51 wxArtID wxART_HELP;

52 wxArtID wxART_TIP;

53 wxArtID wxART_REPORT_VIEW;

54 wxArtID wxART_LIST_VIEW;

55 wxArtID wxART_NEW_DIR;

56 wxArtID wxART_HARDDISK;

57 wxArtID wxART_FLOPPY;

58 wxArtID wxART_CDROM;

59 wxArtID wxART_REMOVABLE;

60 wxArtID wxART_FOLDER;

61 wxArtID wxART_FOLDER_OPEN;

62 wxArtID wxART_GO_DIR_UP;

63 wxArtID wxART_EXECUTABLE_FILE;

64 wxArtID wxART_NORMAL_FILE;

65 wxArtID wxART_TICK_MARK;

66 wxArtID wxART_CROSS_MARK;

67 wxArtID wxART_ERROR;

68 wxArtID wxART_QUESTION;

69 wxArtID wxART_WARNING;

70 wxArtID wxART_INFORMATION;

71 wxArtID wxART_MISSING_IMAGE;

73 wxArtID wxART_COPY;

74 wxArtID wxART_CUT;

75 wxArtID wxART_PASTE;

76 wxArtID wxART_DELETE;

77 wxArtID wxART_NEW;

79 wxArtID wxART_UNDO;

80 wxArtID wxART_REDO;

82 wxArtID wxART_PLUS;

83 wxArtID wxART_MINUS;

85 wxArtID wxART_CLOSE;

86 wxArtID wxART_QUIT;

88 wxArtID wxART_FIND;

89 wxArtID wxART_FIND_AND_REPLACE;

92 /**

93 @class wxArtProvider

95 wxArtProvider class is used to customize the look of wxWidgets application.

97 When wxWidgets needs to display an icon or a bitmap (e.g. in the standard file

98 dialog), it does not use a hard-coded resource but asks wxArtProvider for it

99 instead. This way users can plug in their own wxArtProvider class and easily

100 replace standard art with their own version.

101

102 All that is needed is to derive a class from wxArtProvider, override either its

103 wxArtProvider::CreateBitmap() and/or its wxArtProvider::CreateIconBundle() methods

104 and register the provider with wxArtProvider::Push():

105

106 @code

107 class MyProvider : public wxArtProvider

108 {

109 protected:

110 wxBitmap CreateBitmap(const wxArtID& id,

111 const wxArtClient& client,

112 const wxSize size)

113

114 // optionally override this one as well

115 wxIconBundle CreateIconBundle(const wxArtID& id,

116 const wxArtClient& client)

117 { ... }

118 };

119 ...

120 wxArtProvider::Push(new MyProvider);

121 @endcode

122

123 If you need bitmap images (of the same artwork) that should be displayed at

124 different sizes you should probably consider overriding wxArtProvider::CreateIconBundle

125 and supplying icon bundles that contain different bitmap sizes.

126

127 There's another way of taking advantage of this class: you can use it in your

128 code and use platform native icons as provided by wxArtProvider::GetBitmap or

129 wxArtProvider::GetIcon.

130

131 @section artprovider_identify Identifying art resources

132

133 Every bitmap and icon bundle are known to wxArtProvider under an unique ID that

134 is used when requesting a resource from it. The ID is represented by the ::wxArtID type

135 and can have one of these predefined values (you can see bitmaps represented by these

136 constants in the @ref page_samples_artprov):

137

138 <table>

139 <tr><td>

140 @li @c wxART_ERROR

141 @li @c wxART_QUESTION

142 @li @c wxART_WARNING

143 @li @c wxART_INFORMATION

144 @li @c wxART_ADD_BOOKMARK

145 @li @c wxART_DEL_BOOKMARK

146 @li @c wxART_HELP_SIDE_PANEL

147 @li @c wxART_HELP_SETTINGS

148 @li @c wxART_HELP_BOOK

149 @li @c wxART_HELP_FOLDER

150 @li @c wxART_HELP_PAGE

151 @li @c wxART_GO_BACK

152 @li @c wxART_GO_FORWARD

153 @li @c wxART_GO_UP

154 @li @c wxART_GO_DOWN

155 @li @c wxART_GO_TO_PARENT

156 @li @c wxART_GO_HOME

157 @li @c wxART_GOTO_FIRST (since 2.9.2)

158 </td><td>

159 @li @c wxART_GOTO_LAST (since 2.9.2)

160 @li @c wxART_PRINT

161 @li @c wxART_HELP

162 @li @c wxART_TIP

163 @li @c wxART_REPORT_VIEW

164 @li @c wxART_LIST_VIEW

165 @li @c wxART_NEW_DIR

166 @li @c wxART_FOLDER

167 @li @c wxART_FOLDER_OPEN

168 @li @c wxART_GO_DIR_UP

169 @li @c wxART_EXECUTABLE_FILE

170 @li @c wxART_NORMAL_FILE

171 @li @c wxART_TICK_MARK

172 @li @c wxART_CROSS_MARK

173 @li @c wxART_MISSING_IMAGE

174 @li @c wxART_NEW

175 @li @c wxART_FILE_OPEN

176 @li @c wxART_FILE_SAVE

177 </td><td>

178 @li @c wxART_FILE_SAVE_AS

179 @li @c wxART_DELETE

180 @li @c wxART_COPY

181 @li @c wxART_CUT

182 @li @c wxART_PASTE

183 @li @c wxART_UNDO

184 @li @c wxART_REDO

185 @li @c wxART_PLUS (since 2.9.2)

186 @li @c wxART_MINUS (since 2.9.2)

187 @li @c wxART_CLOSE

188 @li @c wxART_QUIT

189 @li @c wxART_FIND

190 @li @c wxART_FIND_AND_REPLACE

191 @li @c wxART_HARDDISK

192 @li @c wxART_FLOPPY

193 @li @c wxART_CDROM

194 @li @c wxART_REMOVABLE

195 </td></tr>

196 </table>

197

198 Additionally, any string recognized by custom art providers registered using

199 wxArtProvider::Push may be used.

200

201 @note

202 When running under GTK+ 2, GTK+ stock item IDs (e.g. @c "gtk-cdrom") may be used

203 as well:

204 @code

205 #ifdef __WXGTK__

206 wxBitmap bmp = wxArtProvider::GetBitmap("gtk-cdrom", wxART_MENU);

207 #endif

208 @endcode

209 For a list of the GTK+ stock items please refer to the

210 <a href="http://library.gnome.org/devel/gtk/stable/gtk-Stock-Items.html">GTK+ documentation

211 page</a>.

212 It is also possible to load icons from the current icon theme by specifying their name

213 (without extension and directory components).

214 Icon themes recognized by GTK+ follow the freedesktop.org

215 <a href="http://freedesktop.org/Standards/icon-theme-spec">Icon Themes specification</a>.

216 Note that themes are not guaranteed to contain all icons, so wxArtProvider may

217 return ::wxNullBitmap or ::wxNullIcon.

218 The default theme is typically installed in @c /usr/share/icons/hicolor.

219

220

221 @section artprovider_clients Clients

222

223 The @e client is the entity that calls wxArtProvider's GetBitmap() or GetIcon() function.

224 It is represented by wxClientID type and can have one of these values:

225

226 @li @c wxART_TOOLBAR

227 @li @c wxART_MENU

228 @li @c wxART_BUTTON

229 @li @c wxART_FRAME_ICON

230 @li @c wxART_CMN_DIALOG

231 @li @c wxART_HELP_BROWSER

232 @li @c wxART_MESSAGE_BOX

233 @li @c wxART_OTHER (used for all requests that don't fit into any of the

234 categories above)

235

236 Client ID serve as a hint to wxArtProvider that is supposed to help it to

237 choose the best looking bitmap. For example it is often desirable to use

238 slightly different icons in menus and toolbars even though they represent

239 the same action (e.g. wxART_FILE_OPEN). Remember that this is really only a

240 hint for wxArtProvider -- it is common that wxArtProvider::GetBitmap returns

241 identical bitmap for different client values!

242

243 @library{wxcore}

244 @category{misc}

245

246 @see @ref page_samples_artprov for an example of wxArtProvider usage;

247 @ref page_stockitems "stock ID list"

248 */

249 class wxArtProvider : public wxObject

250 {

251 public:

252 /**

253 The destructor automatically removes the provider from the provider stack used

254 by GetBitmap().

255 */

256 virtual ~wxArtProvider();

257

258 /**

259 Delete the given @a provider.

260 */

     static bool Delete(wxArtProvider* provider);

262

263 /**

264 Query registered providers for bitmap with given ID.

265

266 @param id

267 wxArtID unique identifier of the bitmap.

268 @param client

269 wxArtClient identifier of the client (i.e. who is asking for the bitmap).

270 @param size

271 Size of the returned bitmap or wxDefaultSize if size doesn't matter.

272

273 @return The bitmap if one of registered providers recognizes the ID or

274 wxNullBitmap otherwise.

275 */

     static wxBitmap GetBitmap(const wxArtID& id,

277 const wxArtClient& client = wxART_OTHER,

278 const wxSize& size = wxDefaultSize);

279

280 /**

281 Same as wxArtProvider::GetBitmap, but return a wxIcon object

282 (or ::wxNullIcon on failure).

283 */

     static wxIcon GetIcon(const wxArtID& id,

285 const wxArtClient& client = wxART_OTHER,

286 const wxSize& size = wxDefaultSize);

287

288 /**

289 Returns native icon size for use specified by @a client hint.

290

291 If the platform has no commonly used default for this use or if

292 @a client is not recognized, returns wxDefaultSize.

293

294 @note In some cases, a platform may have @em several appropriate

295 native sizes (for example, wxART_FRAME_ICON for frame icons).

296 In that case, this method returns only one of them, picked

297 reasonably.

298

299 @since 2.9.0

300 */

     static wxSize GetNativeSizeHint(const wxArtClient& client);

302

303 /**

304 Returns a suitable size hint for the given @e wxArtClient.

305

306 If @a platform_default is @true, return a size based on the current

307 platform using GetNativeSizeHint(), otherwise return the size from the

308 topmost wxArtProvider. @e wxDefaultSize may be returned if the client

309 doesn't have a specified size, like wxART_OTHER for example.

310

311 @see GetNativeSizeHint()

312 */

     static wxSize GetSizeHint(const wxArtClient& client,

314 bool platform_default = false);

315

316 /**

317 Query registered providers for icon bundle with given ID.

318

319 @param id

320 wxArtID unique identifier of the icon bundle.

321 @param client

322 wxArtClient identifier of the client (i.e. who is asking for the icon

323 bundle).

324

325 @return The icon bundle if one of registered providers recognizes the ID

326 or wxNullIconBundle otherwise.

327 */

     static wxIconBundle GetIconBundle(const wxArtID& id,

329 const wxArtClient& client = wxART_OTHER);

330

331 /**

332 Returns true if the platform uses native icons provider that should

333 take precedence over any customizations.

334

335 This is true for any platform that has user-customizable icon themes,

336 currently only wxGTK.

337

338 A typical use for this method is to decide whether a custom art provider

339 should be plugged in using Push() or PushBack().

340

341 @since 2.9.0

342 */

343 static bool HasNativeProvider();

344

345 /**

346 @deprecated Use PushBack() instead.

347 */

     static void Insert(wxArtProvider* provider);

349

350 /**

351 Remove latest added provider and delete it.

352 */

353 static bool Pop();

354

355 /**

356 Register new art provider and add it to the top of providers stack

357 (i.e. it will be queried as the first provider).

358

359 @see PushBack()

360 */

     static void Push(wxArtProvider* provider);

362

363 /**

364 Register new art provider and add it to the bottom of providers stack.

365 In other words, it will be queried as the last one, after all others,

366 including the default provider.

367

368 @see Push()

369

370 @since 2.9.0

371 */

     static void PushBack(wxArtProvider* provider);

373

374 /**

375 Remove a provider from the stack if it is on it. The provider is not

376 deleted, unlike when using Delete().

377 */

     static bool Remove(wxArtProvider* provider);

379

380 /**

381 * Helper used by GetMessageBoxIcon(): return the art id corresponding to

382 * the standard wxICON_INFORMATION/WARNING/ERROR/QUESTION flags (only one

383 * can be set)

384 */

     static wxArtID GetMessageBoxIconId(int flags);

386

387 /**

388 * Helper used by several generic classes: return the icon corresponding to

389 * the standard wxICON_INFORMATION/WARNING/ERROR/QUESTION flags (only one

390 * can be set)

391 */

     static wxIcon GetMessageBoxIcon(int flags);

393

394

395 protected:

396

397 /**

398 Derived art provider classes must override this method to create requested art

399 resource. Note that returned bitmaps are cached by wxArtProvider and it is

400 therefore not necessary to optimize CreateBitmap() for speed (e.g. you may

401 create wxBitmap objects from XPMs here).

402

403 @param id

404 wxArtID unique identifier of the bitmap.

405 @param client

406 wxArtClient identifier of the client (i.e. who is asking for the bitmap).

407 This only servers as a hint.

408 @param size

409 Preferred size of the bitmap. The function may return a bitmap of different

410 dimensions, it will be automatically rescaled to meet client's request.

411

412 @note

413 This is not part of wxArtProvider's public API, use wxArtProvider::GetBitmap

414 or wxArtProvider::GetIconBundle or wxArtProvider::GetIcon to query wxArtProvider

415 for a resource.

416

417 @see CreateIconBundle()

418 */

     virtual wxBitmap CreateBitmap(const wxArtID& id,

420 const wxArtClient& client,

421 const wxSize& size);

422

423 /**

424 This method is similar to CreateBitmap() but can be used when a bitmap

425 (or an icon) exists in several sizes.

426 */

     virtual wxIconBundle CreateIconBundle(const wxArtID& id,

428 const wxArtClient& client);

429 };

430