projects / wxWidgets.git / blame
| Commit | Line | Data |
|---|---|---|
| 15b6757b | 1 | ///////////////////////////////////////////////////////////////////////////// |
| 2cd3cc94 | 2 | // Name: toolbar.h |
| 15b6757b FM |
3 | // Purpose: topic overview |
| 4 | // Author: wxWidgets team | |
| 5 | // RCS-ID: $Id$ | |
| 6 | // Licence: wxWindows license | |
| 7 | ///////////////////////////////////////////////////////////////////////////// | |
| 8 | ||
| 9 | /*! | |
| 36c9828f | 10 | |
| 2cd3cc94 BP |
11 | @page overview_toolbar Toolbar Overview |
| 12 | ||
| 13 | Classes: wxToolBar | |
| 14 | ||
| 30738aae FM |
15 | @li @ref overview_toolbar_intro |
| 16 | @li @ref overview_toolbar_library | |
| 17 | ||
| 18 | ||
| 19 | <hr> | |
| 20 | ||
| 21 | ||
| 22 | @section overview_toolbar_intro Introduction | |
| 23 | ||
| 2cd3cc94 BP |
24 | The toolbar family of classes allows an application to use toolbars in a |
| 25 | variety of configurations and styles. | |
| 26 | ||
| 27 | The toolbar is a popular user interface component and contains a set of bitmap | |
| 28 | buttons or toggles. A toolbar gives faster access to an application's | |
| 29 | facilities than menus, which have to be popped up and selected rather | |
| 30 | laboriously. | |
| 31 | ||
| 32 | Instead of supplying one toolbar class with a number of different | |
| 33 | implementations depending on platform, wxWidgets separates out the classes. | |
| 34 | This is because there are a number of different toolbar styles that you may | |
| 35 | wish to use simultaneously, and also, future toolbar implementations will | |
| 36 | emerge which cannot all be shoe-horned into the one class. | |
| 37 | ||
| 38 | For each platform, the symbol wxToolBar is defined to be one of the specific | |
| 39 | toolbar classes. | |
| 40 | ||
| 41 | The following is a summary of the toolbar classes and their differences: | |
| 42 | ||
| 43 | @li wxToolBarBase: This is a base class with pure virtual functions, and should | |
| 44 | not be used directly. | |
| 45 | @li wxToolBarSimple: A simple toolbar class written entirely with generic | |
| 46 | wxWidgets functionality. A simple 3D effect for buttons is possible, but it | |
| 47 | is not consistent with the Windows look and feel. This toolbar can scroll, | |
| 48 | and you can have arbitrary numbers of rows and columns. | |
| 49 | @li wxToolBarMSW: This class implements an old-style Windows toolbar, only on | |
| 50 | Windows. There are small, three-dimensional buttons, which do not | |
| 51 | (currently) reflect the current Windows colour settings: the buttons are | |
| 52 | grey. This is the default wxToolBar on 16-bit windows. | |
| 53 | @li wxToolBar95: Uses the native Windows 95 toolbar class. It dynamically | |
| 54 | adjusts it's background and button colours according to user colour | |
| 55 | settings. CreateTools must be called after the tools have been added. No | |
| 56 | absolute positioning is supported but you can specify the number of rows, | |
| 57 | and add tool separators with @c AddSeparator. Tooltips are supported. | |
| 58 | @c OnRightClick is not supported. This is the default wxToolBar on Windows | |
| 59 | 95, Windows NT 4 and above. With the style wxTB_FLAT, the flat toolbar look | |
| 60 | is used, with a border that is highlighted when the cursor moves over the | |
| 61 | buttons. | |
| 62 | ||
| 63 | A toolbar might appear as a single row of images under the menubar, or it might | |
| 64 | be in a separate frame layout in several rows and columns. The class handles | |
| 65 | the layout of the images, unless explicit positioning is requested. | |
| 66 | ||
| 67 | A tool is a bitmap which can either be a button (there is no 'state', it just | |
| 68 | generates an event when clicked) or it can be a toggle. If a toggle, a second | |
| 69 | bitmap can be provided to depict the 'on' state; if the second bitmap is | |
| 70 | omitted, either the inverse of the first bitmap will be used (for monochrome | |
| 71 | displays) or a thick border is drawn around the bitmap (for colour displays | |
| 72 | where inverting will not have the desired result). | |
| 73 | ||
| 74 | The Windows-specific toolbar classes expect 16-colour bitmaps that are 16 | |
| 75 | pixels wide and 15 pixels high. If you want to use a different size, call | |
| 76 | @c SetToolBitmapSize as the demo shows, before adding tools to the button bar. | |
| 77 | Don't supply more than one bitmap for each tool, because the toolbar generates | |
| 78 | all three images (normal, depressed, and checked) from the single bitmap you | |
| 79 | give it. | |
| 80 | ||
| 81 | ||
| 82 | @section overview_toolbar_library Using the Toolbar Library | |
| 83 | ||
| 84 | Include @c "wx/toolbar.h", or if using a class directly, one of: | |
| 85 | ||
| 86 | - @c "wx/msw/tbarmsw.h" for wxToolBarMSW | |
| 87 | - @c "wx/msw/tbar95.h" for wxToolBar95 | |
| 88 | - @c "wx/tbarsmpl.h" for wxToolBarSimple | |
| 89 | ||
| 90 | An example of using a toolbar is given in the "toolbar" sample. | |
| 91 | ||
| 92 | */ | |
| 36c9828f | 93 |