documented wxInitialize and wxUnitialize

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

diff --git a/docs/latex/wx/ttoolbar.tex b/docs/latex/wx/ttoolbar.tex
index 10d3a6057d8b23baca3d27ec0f65013506899009..9879a96323c7c4a58d83f2c17a57086c7f8d7f39 100644 (file)
--- a/docs/latex/wx/ttoolbar.tex
+++ b/docs/latex/wx/ttoolbar.tex
@@ -1,7 +1,6 @@
 \section{Toolbar overview}\label{wxtoolbaroverview}
 
 \section{Toolbar overview}\label{wxtoolbaroverview}
 

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

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


@@ -14,23 +13,11 @@ 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
 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.
+toolbar implementations will emerge which
+cannot all 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.
+For each platform, the symbol {\bf wxToolBar} is defined to be one of the
+specific toolbar classes.

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


@@ -38,20 +25,21 @@ The following is a summary of the toolbar classes and their differences.
 \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
 \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
+functionality. A simple 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
 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.
+the current Windows colour settings: the buttons are grey. This is the default wxToolBar
+on 16-bit windows.

 \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
 \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.
+of rows, and add tool separators with {\bf AddSeparator}.
+Tooltips are supported. {\bf OnRightClick} is not supported. This is the default wxToolBar
+on Windows 95, Windows NT 4 and above. With the style wxTB\_FLAT, the flat toolbar
+look is used, with a border that is highlighted when the cursor moves over the buttons.

 \end{itemize}
 
 A toolbar might appear as a single row of images under
 \end{itemize}
 
 A toolbar might appear as a single row of images under


@@ -68,61 +56,232 @@ 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
 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
+high. If you want to use a different size, call {\bf SetToolBitmapSize}\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.
 
 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}
 
 \subsection{Using the toolbar library}
 

-Include one of the files {\tt tbarsmpl.h, tbar95.h, tbarmsw.h}.
+Include {\tt "wx/toolbar.h"}, or if using a class directly, one of:

 
 

-Example of toolbar use are given in the sample programs tbarsmpl,
-tbarmsw and tbar95.
+\begin{itemize}\itemsep=0pt
+\item {\tt "wx/msw/tbarmsw.h} for wxToolBarMSW
+\item {\tt "wx/msw/tbar95.h} for wxToolBar95
+\item {\tt "wx/tbarsmpl.h} for wxToolBarSimple
+\end{itemize}

 
 

-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.
+Example of toolbar use are given in the sample program ``toolbar''. The
+source is given below. In fact it is out of date because recommended
+practise is to use event handlers (using EVT\_MENU or EVT\_TOOL) instead of
+overriding OnLeftClick.

 
 

-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.
+{\small
+\begin{verbatim}
+/////////////////////////////////////////////////////////////////////////////
+// Name:        test.cpp
+// Purpose:     wxToolBar sample
+// Author:      Julian Smart
+// Modified by:
+// Created:     04/01/98
+// RCS-ID:      $Id$
+// Copyright:   (c) Julian Smart
+// License:    wxWindows license
+/////////////////////////////////////////////////////////////////////////////

 
 

-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.
+// For compilers that support precompilation, includes "wx/wx.h".
+#include "wx/wxprec.h"

 
 

-Left clicks and movements over the toolbars are intercepted and information
-is displayed on the status line.
+#ifdef __BORLANDC__
+#pragma hdrstop
+#endif

 
 

-The following fragment illustrates the essence of creating a toolbar.
+#ifndef WX_PRECOMP
+#include "wx/wx.h"
+#endif

 
 

-\begin{verbatim}
+#include "wx/toolbar.h"
+#include <wx/log.h>
+
+#include "test.h"
+
+#if defined(__WXGTK__) || defined(__WXMOTIF__)
+#include "mondrian.xpm"
+#include "bitmaps/new.xpm"
+#include "bitmaps/open.xpm"
+#include "bitmaps/save.xpm"
+#include "bitmaps/copy.xpm"
+#include "bitmaps/cut.xpm"
+#include "bitmaps/print.xpm"
+#include "bitmaps/preview.xpm"
+#include "bitmaps/help.xpm"
+#endif
+
+IMPLEMENT_APP(MyApp)
+
+// The `main program' equivalent, creating the windows and returning the
+// main frame
+bool MyApp::OnInit(void)
+{
+  // Create the main frame window
+  MyFrame* frame = new MyFrame((wxFrame *) NULL, -1, (const wxString) "wxToolBar Sample",
+     wxPoint(100, 100), wxSize(450, 300));
+
+  // Give it a status line
+  frame->CreateStatusBar();
+
+  // Give it an icon
+  frame->SetIcon(wxICON(mondrian));
+
+  // Make a menubar
+  wxMenu *fileMenu = new wxMenu;
+  fileMenu->Append(wxID_EXIT, "E&xit", "Quit toolbar sample" );
+
+  wxMenu *helpMenu = new wxMenu;
+  helpMenu->Append(wxID_HELP, "&About", "About toolbar sample");
+
+  wxMenuBar* menuBar = new wxMenuBar;
+
+  menuBar->Append(fileMenu, "&File");
+  menuBar->Append(helpMenu, "&Help");
+
+  // Associate the menu bar with the frame
+  frame->SetMenuBar(menuBar);
+
+  // Create the toolbar
+  frame->CreateToolBar(wxNO_BORDER|wxHORIZONTAL|wxTB_FLAT, ID_TOOLBAR);
+  
+  frame->GetToolBar()->SetMargins( 2, 2 );
+
+  InitToolbar(frame->GetToolBar());
+
+  // Force a resize. This should probably be replaced by a call to a wxFrame
+  // function that lays out default decorations and the remaining content window.
+  wxSizeEvent event(wxSize(-1, -1), frame->GetId());
+  frame->OnSize(event);
+  frame->Show(TRUE);
+
+  frame->SetStatusText("Hello, wxWindows");
+  
+  SetTopWindow(frame);
+
+  return TRUE;
+}
+
+bool MyApp::InitToolbar(wxToolBar* toolBar)
+{
+  // Set up toolbar
+  wxBitmap* toolBarBitmaps[8];
+
+#ifdef __WXMSW__

   toolBarBitmaps[0] = new wxBitmap("icon1");
   toolBarBitmaps[1] = new wxBitmap("icon2");
   toolBarBitmaps[2] = new wxBitmap("icon3");
   toolBarBitmaps[0] = new wxBitmap("icon1");
   toolBarBitmaps[1] = new wxBitmap("icon2");
   toolBarBitmaps[2] = new wxBitmap("icon3");

-  ...
+  toolBarBitmaps[3] = new wxBitmap("icon4");
+  toolBarBitmaps[4] = new wxBitmap("icon5");
+  toolBarBitmaps[5] = new wxBitmap("icon6");
+  toolBarBitmaps[6] = new wxBitmap("icon7");
+  toolBarBitmaps[7] = new wxBitmap("icon8");
+#else
+  toolBarBitmaps[0] = new wxBitmap( new_xpm );
+  toolBarBitmaps[1] = new wxBitmap( open_xpm );
+  toolBarBitmaps[2] = new wxBitmap( save_xpm );
+  toolBarBitmaps[3] = new wxBitmap( copy_xpm );
+  toolBarBitmaps[4] = new wxBitmap( cut_xpm );
+  toolBarBitmaps[5] = new wxBitmap( preview_xpm );
+  toolBarBitmaps[6] = new wxBitmap( print_xpm );
+  toolBarBitmaps[7] = new wxBitmap( help_xpm );
+#endif
+
+#ifdef __WXMSW__
+  int width = 24;
+#else
+  int width = 16;
+#endif
+  int currentX = 5;
+
+  toolBar->AddTool(wxID_NEW, *(toolBarBitmaps[0]), wxNullBitmap, FALSE, currentX, -1, (wxObject *) NULL, "New file");
+  currentX += width + 5;
+  toolBar->AddTool(wxID_OPEN, *(toolBarBitmaps[1]), wxNullBitmap, FALSE, currentX, -1, (wxObject *) NULL, "Open file");
+  currentX += width + 5;
+  toolBar->AddTool(wxID_SAVE, *(toolBarBitmaps[2]), wxNullBitmap, FALSE, currentX, -1, (wxObject *) NULL, "Save file");
+  currentX += width + 5;
+  toolBar->AddSeparator();
+  toolBar->AddTool(wxID_COPY, *(toolBarBitmaps[3]), wxNullBitmap, FALSE, currentX, -1, (wxObject *) NULL, "Copy");
+  currentX += width + 5;
+  toolBar->AddTool(wxID_CUT, *(toolBarBitmaps[4]), wxNullBitmap, FALSE, currentX, -1, (wxObject *) NULL, "Cut");
+  currentX += width + 5;
+  toolBar->AddTool(wxID_PASTE, *(toolBarBitmaps[5]), wxNullBitmap, FALSE, currentX, -1, (wxObject *) NULL, "Paste");
+  currentX += width + 5;
+  toolBar->AddSeparator();
+  toolBar->AddTool(wxID_PRINT, *(toolBarBitmaps[6]), wxNullBitmap, FALSE, currentX, -1, (wxObject *) NULL, "Print");
+  currentX += width + 5;
+  toolBar->AddSeparator();
+  toolBar->AddTool(wxID_HELP, *(toolBarBitmaps[7]), wxNullBitmap, FALSE, currentX, -1, (wxObject *) NULL, "Help");
+
+  toolBar->Realize();
+
+  // Can delete the bitmaps since they're reference counted
+  int i;
+  for (i = 0; i < 8; i++)
+    delete toolBarBitmaps[i];
+
+  return TRUE;
+}
+
+// wxID_HELP will be processed for the 'About' menu and the toolbar help button.
+
+BEGIN_EVENT_TABLE(MyFrame, wxFrame)
+    EVT_MENU(wxID_EXIT, MyFrame::OnQuit)
+    EVT_MENU(wxID_HELP, MyFrame::OnAbout)
+    EVT_CLOSE(MyFrame::OnCloseWindow)
+    EVT_TOOL_RANGE(wxID_OPEN, wxID_PASTE, MyFrame::OnToolLeftClick)
+    EVT_TOOL_ENTER(wxID_OPEN, MyFrame::OnToolEnter)
+END_EVENT_TABLE()
+
+// Define my frame constructor
+MyFrame::MyFrame(wxFrame* parent, wxWindowID id, const wxString& title, const wxPoint& pos,
+        const wxSize& size, long style):
+  wxFrame(parent, id, title, pos, size, style)
+{
+  m_textWindow = new wxTextCtrl(this, -1, "", wxPoint(0, 0), wxSize(-1, -1), wxTE_MULTILINE);
+}
+
+void MyFrame::OnQuit(wxCommandEvent& WXUNUSED(event))
+{
+    Close(TRUE);
+}

 
 

-  toolBarFrame = new wxFrame(NULL, "Tools", -1, wxPoint(0, 0), wxSize(300, 200),
-    wxDEFAULT_FRAME_STYLE | wxSTAY_ON_TOP);
+void MyFrame::OnAbout(wxCommandEvent& WXUNUSED(event))
+{
+    (void)wxMessageBox("wxWindows toolbar sample", "About wxToolBar");
+}

 
 

-  // 5 rows
-  toolBar = new TestToolBar(toolBarFrame, -1, wxPoint(10, 10), wxSize(-1, -1), 0, wxVERTICAL, 5);
-  toolBar->SetMargins(2, 2);
+// Define the behaviour for the frame closing
+// - must delete all frames except for the main one.
+void MyFrame::OnCloseWindow(wxCloseEvent& WXUNUSED(event))
+{
+  Destroy();
+}

 
 

-  for (int i = 10; i < 25; i++)
-    toolBar->AddTool(i, toolBarBitmaps[i], NULL, TRUE);
+void MyFrame::OnToolLeftClick(wxCommandEvent& event)
+{
+  wxString str;
+  str.Printf("Clicked on tool %d", event.GetId());
+  SetStatusText(str);
+}

 
 

-  toolBar->Layout();
-  float maxWidth, maxHeight;
-  wxSize size(toolBar->GetMaxSize());
-  toolBarFrame->SetClientSize(maxSize.x, maxSize.y);
-  toolBarFrame->Show(TRUE);
+void MyFrame::OnToolEnter(wxCommandEvent& event)
+{
+  if (event.GetSelection() > -1)
+  {
+    wxString str;
+    str.Printf("This is tool number %d", event.GetSelection());
+    SetStatusText(str);
+  }
+  else
+    SetStatusText("");
+}

 \end{verbatim}
 \end{verbatim}

+}