Configure now adds -D__WXDEBUG__ to the compiler switches if run with

[wxWidgets.git] / docs / latex / wx / ttoolbar.tex

\section{Toolbar overview}\label{wxtoolbaroverview}

Classes: \helpref{wxToolBarBase}{wxtoolbarbase}, \helpref{wxToolBarSimple}{wxtoolbarsimple},\rtfsp
\helpref{wxToolBarMSW}{wxtoolbarmsw}, \helpref{wxToolBar95}{wxtoolbar95}

The toolbar family of classes allows an application to use toolbars
in a variety of configurations and styles.

The toolbar is a popular user interface component and contains a set of bitmap
buttons or toggles. A toolbar gives faster access to an application's facilities than
menus, which have to be popped up and selected rather laboriously.

Instead of supplying one toolbar class with a number
of different implementations depending on platform, wxWindows separates
out the classes. This is because there are a number of different toolbar
styles that you may wish to use simultaneously, and also, future
toolbar implementations will emerge (for example, using the
new-style Windows `coolbar' as seen in Microsoft applications) which
cannot be shoe-horned into the one class.

This does mean that if you wish to use a more sophisticated toolbar
on one platform (say, wxToolBar95) and a simple toolbar on another
platform (wxToolBarSimple), then you will need some simple ifdefing, such as:

\begin{verbatim}
  #ifdef wx_msw
  #  define wxToolBar wxToolBar95
  #else
  #  define wxToolBar wxToolBarSimple
  #endif
\end{verbatim}

Fortunately, the APIs of the toolbar classes are virtually identical.

The following is a summary of the toolbar classes and their differences.

\begin{itemize}\itemsep=0pt
\item {\bf wxToolBarBase.} This is a base class with pure virtual functions,
and should not be used directly.
\item {\bf wxToolBarSimple.} A simple toolbar class written entirely with generic wxWindows
functionality. A simply 3D effect for buttons is possible, but it is not consistent
with the Windows look and feel. This toolbar can scroll, and you can have arbitrary
numbers of rows and columns.
\item {\bf wxToolBarMSW.} This class implements an old-style Windows toolbar, only on
Windows. There are small, three-dimensional buttons, which do not (currently) reflect
the current Windows colour settings: the buttons are grey.
\item {\bf wxToolBar95.} Uses the native Windows 95 toolbar class. It dynamically adjusts its
background and button colours according to user colour settings.
CreateTools must be called after the tools have been added.
No absolute positioning is supported but you can specify the number
of rows, and add tool separators with {\bf AddSeparator}. {\bf Layout} does nothing.
Tooltips are supported. {\bf OnRightClick} is not supported.
For some reason, a wxToolBar95 control cannot be moved to any
position other than the top-left of the frame.
\end{itemize}

A toolbar might appear as a single row of images under
the menubar, or it might be in a separate frame layout in several rows
and columns. The class handles the layout of the images, unless explicit
positioning is requested.

A tool is a bitmap which can either be a button (there is no `state',
it just generates an event when clicked) or it can be a toggle. If a
toggle, a second bitmap can be provided to depict the `on' state; if
the second bitmap is omitted, either the inverse of the first bitmap
will be used (for monochrome displays) or a thick border is drawn
around the bitmap (for colour displays where inverting will not have
the desired result).

The Windows-specific toolbar classes expect 16-colour bitmaps that are 16 pixels wide and 15 pixels
high. If you want to use a different size, call {\bf SetDefaultSize}\rtfsp
as the demo shows, before adding tools to the button bar. Don't supply more than
one bitmap for each tool, because the toolbar generates all three images (normal,
depressed and checked) from the single bitmap you give it.

Mouse click events for a given button are sent to a member called
\rtfsp{\bf OnLeftClick}, and so an application must derive from wxToolBar in order
to use it. The application can also handle {\bf OnMouseEnter} events for
the tools, to give the user extra feedback about the tools as the mouse
moves over them.

\subsection{Using the toolbar library}

Include one of the files {\tt tbarsmpl.h, tbar95.h, tbarmsw.h}.

Example of toolbar use are given in the sample programs tbarsmpl,
tbarmsw and tbar95.

Each sample creates a main window, and two toolbars: a floating toolbar
with 24 tools, and a toolbar along the top of the main drawing window, divided into groups.

The test program defines a general-purpose derived frame called
\rtfsp{\bf wxFrameWithToolBar} which can manage a frame with one main subwindow
and one horizontal toolbar.

Note that one of the bitmaps on the floating toolbar is a small version of the
main graphic: this demonstrates how a memory device context can be used to
draw into a bitmap. An application which allowed the user to build up a symbol
library dynamically might create this kind of bitmap.

Left clicks and movements over the toolbars are intercepted and information
is displayed on the status line.

The following fragment illustrates the essence of creating a toolbar.

\begin{verbatim}
  toolBarBitmaps[0] = new wxBitmap("icon1");
  toolBarBitmaps[1] = new wxBitmap("icon2");
  toolBarBitmaps[2] = new wxBitmap("icon3");
  ...

  toolBarFrame = new wxFrame(NULL, "Tools", -1, wxPoint(0, 0), wxSize(300, 200),
    wxDEFAULT_FRAME_STYLE | wxSTAY_ON_TOP);

  // 5 rows
  toolBar = new TestToolBar(toolBarFrame, -1, wxPoint(10, 10), wxSize(-1, -1), 0, wxVERTICAL, 5);
  toolBar->SetMargins(2, 2);

  for (int i = 10; i < 25; i++)
    toolBar->AddTool(i, toolBarBitmaps[i], NULL, TRUE);

  toolBar->Layout();
  float maxWidth, maxHeight;
  wxSize size(toolBar->GetMaxSize());
  toolBarFrame->SetClientSize(maxSize.x, maxSize.y);
  toolBarFrame->Show(TRUE);
\end{verbatim}