\hy-9{0}{
}








\hy-5{2}{User Manual for wxToolBar  1.075 beta}

\hy-6{3}{Julian Smart
Decision Support Group
Artificial Intelligence Applications Institute
80 South Bridge
University of Edinburgh
EH1 1HN}

August 1993






\hy-5{1}{Contents}

\hy-6{4}{Introduction}

\hy-6{8}{Using the toolbar library}

\hy-6{22}{Class reference}


\hy-10{5}{Introduction}




The wxToolBar class gives wxWindows programs an extra, and increasingly
popular, user interface component: 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.
Besides which, a toolbar looks prettier than a purely menu-based
interface.

wxToolBar uses a canvas subwindow for drawing bitmaps, and so bitmap
images cannot be mixed with panel items, but in most cases this won't
be important. 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).

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


\hy-10{9}{Using the toolbar library}




The toolbar library is in \hy-14{10}{wx/utils/toolbar}, spread over the
usual \hy-14{11}{src}, \hy-14{12}{lib} and \hy-14{13}{docs} directories. Include the
file \hy-14{14}{wx_tbar.h} in your application, and specify the library \hy-14{15}{
-ltbar_ol} (XView version), \hy-14{16}{-ltbar_motif} (Motif version) or \hy-14{17}{
toolbar.lib} (Windows version).

An example of toolbar use is given in the program contained in \hy-14{18}{
test.cc} and \hy-14{19}{test.h}.  This creates a main window, and two
toolbars: a floating toolbar with 24 tools, and a toolbar along the
top of the main drawing canvas, divided into groups.  The icons for
this second toolbar would normally be quite small.

The test program defines a general-purpose derived frame called
\hy-8{20}{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.

\hy-14{21}{  toolBarBitmaps[0] = new wxBitmap("icon1");
  toolBarBitmaps[1] = new wxBitmap("icon2");
  toolBarBitmaps[2] = new wxBitmap("icon3");
  ...

  toolBarFrame = new wxFrame(NULL, "Tools", 0, 0, 300, 200,
    wxSDI | wxDEFAULT_FRAME | wxSTAY_ON_TOP);

  toolBar = new TestToolBar(toolBarFrame, 10, 10, -1, -1, 0, wxVERTICAL, 5);
  toolBar->SetMargins(2, 2);
  toolBar->GetDC()->SetBackground(wxGREY_BRUSH);

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

  toolBar->Layout();
  float maxWidth, maxHeight;
  toolBar->GetMaxSize(&maxWidth, &maxHeight);
  toolBarFrame->SetClientSize((int)maxWidth, (int)maxHeight);
  toolBarFrame->Show(TRUE);
}

\hy-10{23}{Class reference}




There is one major class by which toolbars are created and manipulated.

\hy-8{24}{wxToolBar: wxCanvas}


\hy-10{25}{wxToolBar: wxCanvas}



\hy-8{26}{wxToolBar::wxToolBar}

\hy-8{37}{wxToolBar::~wxToolBar}

\hy-8{40}{wxToolBar::AddTool}

\hy-8{58}{wxToolBar::DrawTool}

\hy-8{63}{wxToolBar::EnableTool}

\hy-8{68}{wxToolBar::FindToolForPosition}

\hy-8{73}{wxToolBar::GetMaxSize}

\hy-8{78}{wxToolBar::GetToolClientData}

\hy-8{82}{wxToolBar::GetToolState}

\hy-8{86}{wxToolBar::Layout}

\hy-8{89}{wxToolBar::OnLeftClick}

\hy-8{97}{wxToolBar::OnMouseEnter}

\hy-8{103}{wxToolBar::OnRightClick}

\hy-8{113}{wxToolBar::SetMargins}

\hy-8{118}{wxToolBar::ToggleTool}


\hy-10{27}{wxToolBar::wxToolBar}



\hy-8{28}{void wxToolBar(wxFrame * \hy-8{29}{frame}, int \hy-8{30}{ x = 0}, int \hy-8{31}{ y = 0},

  int \hy-8{32}{ width = -1}, int \hy-8{33}{ height = -1}, int \hy-8{34}{ style = 0},

  int \hy-8{35}{ orientation = wxVERTICAL}, int \hy-8{36}{ nRowsOrColumns = 2})}

Constructs a toolbar canvas, with the same arguments as a canvas plus
an orientation (wxVERTICAL or wxHORIZONTAL) and the number of rows or
columns, whose meaning depends on the orientation.  If laid out
vertically, the final argument refers to the number of rows to draw
before the next column is started; if horizontal, it refers to the
number of columns to draw before the next row is started.


\hy-10{38}{wxToolBar::~wxToolBar}



\hy-8{39}{void ~wxToolBar(void)}

Toolbar destructor.


\hy-10{41}{wxToolBar::AddTool}



\hy-8{42}{Bool AddTool(int \hy-8{43}{ toolIndex},

  wxBitmap * \hy-8{44}{ bitmap1}, wxBitmap * \hy-8{45}{ bitmap2 = NULL},

  Bool \hy-8{46}{ isToggle = FALSE},

  float \hy-8{47}{ xPos = -1}, float \hy-8{48}{ yPos = -1}

  wxObject * \hy-8{49}{clientData})}

Adds a tool to the toolbar. The \hy-7{50}{toolIndex} is an integer by which
the tool may be identified in subsequent operations.  \hy-7{51}{isToggle}
specifies whether the tool is a toggle or not: a toggle tool may be in
two states, whereas a non-toggle tool is just a button.

The first bitmap is the primary tool bitmap for toggle and button
tools. The second bitmap specifies the on-state bitmap for a toggle
tool. If this is NULL, either an inverted version of the primary bitmap is
used for the on-state of a toggle tool (monochrome displays) or a black
border is drawn around the tool (colour displays).

The arguments \hy-7{52}{xPos} and \hy-7{53}{yPos} allow the programmer to specify
the position of the tool if automatic layout is not suitable. For
example, a toolbar along the top of a window may have groups of tools,
with spacing between groups. In this case, specifying \hy-7{54}{xPos} is all
that is required, and \hy-7{55}{yPos} will take its value from the current
vertical spacing value.

\hy-7{56}{clientData} is an optional pointer to client data which can be
retrieved later using \hy-8{57}{GetToolClientData}.


\hy-10{59}{wxToolBar::DrawTool}



\hy-8{60}{void DrawTool(wxMemoryDC&  \hy-8{61}{memDC}, wxToolBarTool * \hy-8{62}{tool})}

Draws the specified tool onto the canvas using the given memory device context.
Used internally, and should not need to be used by the programmer.


\hy-10{64}{wxToolBar::EnableTool}



\hy-8{65}{void EnableTool(int  \hy-8{66}{toolIndex}, Bool \hy-8{67}{ enable})}

Enables or disables the tool. Not currently implemented, but should give some
indication of whether the tool is active.


\hy-10{69}{wxToolBar::FindToolForPosition}



\hy-8{70}{wxToolBarTool * FindToolForPosition(float \hy-8{71}{ x}, float \hy-8{72}{ y})}

Find a tool for the given mouse position, or return NULL. Used
internally, and should not need to be used by the programmer.


\hy-10{74}{wxToolBar::GetMaxSize}



\hy-8{75}{void GetMaxSize(float * \hy-8{76}{w}, float * \hy-8{77}{h})}

Gets the maximum size taken up by the tools after layout, including margins.
This can be used to size a frame around the toolbar canvas.


\hy-10{79}{wxToolBar::GetToolClientData}



\hy-8{80}{wxObject * GetToolClientData(int  \hy-8{81}{toolIndex})}

Get any client data associated with the tool.


\hy-10{83}{wxToolBar::GetToolState}



\hy-8{84}{Bool GetToolState(int  \hy-8{85}{toolIndex})}

Gets the on/off state of a toggle tool.


\hy-10{87}{wxToolBar::Layout}



\hy-8{88}{void Layout(void)}

Called by the application after the tools have been added to
automatically lay the tools out on the canvas. If you have given
absolute positions when adding the tools, do not call this.


\hy-10{90}{wxToolBar::OnLeftClick}



\hy-8{91}{Bool OnLeftClick(int \hy-8{92}{ toolIndex}, Bool \hy-8{93}{ toggleDown})}

Called when the user clicks on a tool with the left mouse button. The
programmer should override this function to detect left tool clicks. \hy-7{94}{
toolIndex} is the identifier passed to \hy-8{95}{AddTool}, and \hy-7{96}{
toggleDown} is TRUE if the tool is a toggle and the toggle is down,
otherwise is FALSE.

If the tool is a toggle and this function returns FALSE, the toggle
toggle state (internal and visual) will not be changed. This provides a way of
specifying that toggle operations are not permitted in some circumstances.


\hy-10{98}{wxToolBar::OnMouseEnter}



\hy-8{99}{void OnMouseEnter(int \hy-8{100}{ toolIndex})}

This is called when the mouse moves into a tool (\hy-7{101}{toolIndex} is
greater than -1) or out of the toolbox (\hy-7{102}{toolIndex} is -1). The
programmer can override this to provide extra information about the tool,
such as a short description on the status line. Icons are not always as
intuitive as they're cracked up to be!


\hy-10{104}{wxToolBar::OnRightClick}



\hy-8{105}{void OnRightClick(int \hy-8{106}{ toolIndex}, float \hy-8{107}{ x}, float \hy-8{108}{ y})}

Called when the user clicks on a tool with the right mouse button. The
programmer should override this function to detect right tool clicks.
\hy-7{109}{toolIndex} is the identifier passed to \hy-8{110}{AddTool}, and \hy-7{111}{x}
and \hy-7{112}{y} give the mouse cursor position.

A typical use of this member might be to pop up a menu.


\hy-10{114}{wxToolBar::SetMargins}



\hy-8{115}{void SetMargins(float \hy-8{116}{ x}, float \hy-8{117}{ y})}

Set the values to be used as margins and spacing for the tools. This must be
called before the tools are added if absolute positioning is to be used, and the
default (zero-size) margins are to be overridden.


\hy-10{119}{wxToolBar::ToggleTool}



\hy-8{120}{void ToggleTool(int  \hy-8{121}{toolIndex}, Bool \hy-8{122}{ toggle})}

Toggles a tool on or off.






\hyindex{
"wxToolBar Manual"
4 5
8 9
22 23
24 25
26 27
37 38
40 41
58 59
63 64
68 69
73 74
78 79
82 83
86 87
89 90
97 98
103 104
113 114
118 119
}
