docs/latex/wx/ttoolbar.tex

   1 \section{Toolbar overview}\label{wxtoolbaroverview}
   2
   3 Classes: \helpref{wxToolBarBase}{wxtoolbarbase}, \helpref{wxToolBarSimple}{wxtoolbarsimple},\rtfsp
   4 \helpref{wxToolBarMSW}{wxtoolbarmsw}, \helpref{wxToolBar95}{wxtoolbar95}
   5
   6 The toolbar family of classes allows an application to use toolbars
   7 in a variety of configurations and styles.
   8
   9 The toolbar is a popular user interface component and contains a set of bitmap
  10 buttons or toggles. A toolbar gives faster access to an application's facilities than
  11 menus, which have to be popped up and selected rather laboriously.
  12
  13 Instead of supplying one toolbar class with a number
  14 of different implementations depending on platform, wxWindows separates
  15 out the classes. This is because there are a number of different toolbar
  16 styles that you may wish to use simultaneously, and also, future
  17 toolbar implementations will emerge (for example, using the
  18 new-style Windows `coolbar' as seen in Microsoft applications) which
  19 cannot be shoe-horned into the one class.
  20
  21 This does mean that if you wish to use a more sophisticated toolbar
  22 on one platform (say, wxToolBar95) and a simple toolbar on another
  23 platform (wxToolBarSimple), then you will need some simple ifdefing, such as:
  24
  25 \begin{verbatim}
  26   #ifdef wx_msw
  27   #  define wxToolBar wxToolBar95
  28   #else
  29   #  define wxToolBar wxToolBarSimple
  30   #endif
  31 \end{verbatim}
  32
  33 Fortunately, the APIs of the toolbar classes are virtually identical.
  34
  35 The following is a summary of the toolbar classes and their differences.
  36
  37 \begin{itemize}\itemsep=0pt
  38 \item {\bf wxToolBarBase.} This is a base class with pure virtual functions,
  39 and should not be used directly.
  40 \item {\bf wxToolBarSimple.} A simple toolbar class written entirely with generic wxWindows
  41 functionality. A simply 3D effect for buttons is possible, but it is not consistent
  42 with the Windows look and feel. This toolbar can scroll, and you can have arbitrary
  43 numbers of rows and columns.
  44 \item {\bf wxToolBarMSW.} This class implements an old-style Windows toolbar, only on
  45 Windows. There are small, three-dimensional buttons, which do not (currently) reflect
  46 the current Windows colour settings: the buttons are grey.
  47 \item {\bf wxToolBar95.} Uses the native Windows 95 toolbar class. It dynamically adjusts its
  48 background and button colours according to user colour settings.
  49 CreateTools must be called after the tools have been added.
  50 No absolute positioning is supported but you can specify the number
  51 of rows, and add tool separators with {\bf AddSeparator}. {\bf Layout} does nothing.
  52 Tooltips are supported. {\bf OnRightClick} is not supported.
  53 For some reason, a wxToolBar95 control cannot be moved to any
  54 position other than the top-left of the frame.
  55 \end{itemize}
  56
  57 A toolbar might appear as a single row of images under
  58 the menubar, or it might be in a separate frame layout in several rows
  59 and columns. The class handles the layout of the images, unless explicit
  60 positioning is requested.
  61
  62 A tool is a bitmap which can either be a button (there is no `state',
  63 it just generates an event when clicked) or it can be a toggle. If a
  64 toggle, a second bitmap can be provided to depict the `on' state; if
  65 the second bitmap is omitted, either the inverse of the first bitmap
  66 will be used (for monochrome displays) or a thick border is drawn
  67 around the bitmap (for colour displays where inverting will not have
  68 the desired result).
  69
  70 The Windows-specific toolbar classes expect 16-colour bitmaps that are 16 pixels wide and 15 pixels
  71 high. If you want to use a different size, call {\bf SetDefaultSize}\rtfsp
  72 as the demo shows, before adding tools to the button bar. Don't supply more than
  73 one bitmap for each tool, because the toolbar generates all three images (normal,
  74 depressed and checked) from the single bitmap you give it.
  75
  76 Mouse click events for a given button are sent to a member called
  77 \rtfsp{\bf OnLeftClick}, and so an application must derive from wxToolBar in order
  78 to use it. The application can also handle {\bf OnMouseEnter} events for
  79 the tools, to give the user extra feedback about the tools as the mouse
  80 moves over them.
  81
  82 \subsection{Using the toolbar library}
  83
  84 Include one of the files {\tt tbarsmpl.h, tbar95.h, tbarmsw.h}.
  85
  86 Example of toolbar use are given in the sample programs tbarsmpl,
  87 tbarmsw and tbar95.
  88
  89 Each sample creates a main window, and two toolbars: a floating toolbar
  90 with 24 tools, and a toolbar along the top of the main drawing canvas, divided into groups.
  91
  92 The test program defines a general-purpose derived frame called
  93 \rtfsp{\bf wxFrameWithToolBar} which can manage a frame with one main subwindow
  94 and one horizontal toolbar.
  95
  96 Note that one of the bitmaps on the floating toolbar is a small version of the
  97 main graphic: this demonstrates how a memory device context can be used to
  98 draw into a bitmap. An application which allowed the user to build up a symbol
  99 library dynamically might create this kind of bitmap.
 100
 101 Left clicks and movements over the toolbars are intercepted and information
 102 is displayed on the status line.
 103
 104 The following fragment illustrates the essence of creating a toolbar.
 105
 106 \begin{verbatim}
 107   toolBarBitmaps[0] = new wxBitmap("icon1");
 108   toolBarBitmaps[1] = new wxBitmap("icon2");
 109   toolBarBitmaps[2] = new wxBitmap("icon3");
 110   ...
 111
 112   toolBarFrame = new wxFrame(NULL, "Tools", -1, wxPoint(0, 0), wxSize(300, 200),
 113     wxDEFAULT_FRAME_STYLE | wxSTAY_ON_TOP);
 114
 115   // 5 rows
 116   toolBar = new TestToolBar(toolBarFrame, 10, 10, -1, -1, 0, wxVERTICAL, 5);
 117   toolBar->SetMargins(2, 2);
 118
 119   for (int i = 10; i < 25; i++)
 120     toolBar->AddTool(i, toolBarBitmaps[i], NULL, TRUE);
 121
 122   toolBar->Layout();
 123   float maxWidth, maxHeight;
 124   wxSize size(toolBar->GetMaxSize());
 125   toolBarFrame->SetClientSize(maxSize.x, maxSize.y);
 126   toolBarFrame->Show(TRUE);
 127 \end{verbatim}
 128