of a "separator" is a vertical line under Windows95 vs. simple space under GTK etc.
{\bf wxToolBar95:} Note that this toolbar paints tools to reflect user-selected colours.
-The toolbar orientation must always be {\bf wxHORIZONTAL}.
-
-{\bf wxToolBarGtk:} The toolbar orientation is ignored and is always {\bf wxHORIZONTAL}.
\wxheading{Window styles}
\twocolitem{\windowstyle{wxTB\_VERTICAL}}{Specifies vertical layout (not available for the GTK and Windows 95
toolbar).}
\twocolitem{\windowstyle{wxTB\_3DBUTTONS}}{Gives wxToolBarSimple a mild 3D look to its buttons.}
+\twocolitem{\windowstyle{wxTB\_TEXT}}{Show the text in the toolbar buttons; by default only icons are shown.}
+\twocolitem{\windowstyle{wxTB\_NOICONS}}{Specifies no icons in the toolbar buttons; by default they are shown.}
+\twocolitem{\windowstyle{wxTB\_NODIVIDER}}{Specifies no divider above the toolbar; by default it is shown. Windows only.}
+\twocolitem{\windowstyle{wxTB\_NOALIGN}}{Specifies no alignment with the parent window. Windows only.}
\end{twocollist}
-See also \helpref{window styles overview}{windowstyles}.
+See also \helpref{window styles overview}{windowstyles}. Note that the Win32
+native toolbar ignores {\tt wxTB\_NOICONS} style. Also, toggling the
+{\tt wxTB\_TEXT} works only if the style was initially on.
\wxheading{Event handling}
\membersection{wxToolBar::AddTool}\label{wxtoolbaraddtool}
-\func{wxToolBarTool*}{AddTool}{\param{int}{ toolIndex}, \param{const wxBitmap\&}{ bitmap1},\rtfsp
-\param{const wxBitmap\&}{ bitmap2 = wxNullBitmap}, \param{bool}{ isToggle = FALSE},\rtfsp
-\param{long}{ xPos = -1}, \param{long}{ yPos = -1},\rtfsp
-\param{wxObject* }{clientData = NULL}, \param{const wxString\& }{shortHelpString = ""}, \param{const wxString\& }{longHelpString = ""}}
-
-Adds a tool to the toolbar.
+\func{wxToolBarTool*}{AddTool}{\param{int}{ toolId},\rtfsp
+\param{const wxString\&}{ label},\rtfsp
+\param{const wxBitmap\&}{ bitmap1},\rtfsp
+\param{const wxString\& }{shortHelpString = ""},\rtfsp
+\param{wxItemKind}{ kind = wxITEM\_NORMAL}}
+
+\func{wxToolBarTool*}{AddTool}{\param{int}{ toolId},\rtfsp
+\param{const wxString\&}{ label},\rtfsp
+\param{const wxBitmap\&}{ bitmap1},\rtfsp
+\param{const wxBitmap\&}{ bitmap2 = wxNullBitmap},\rtfsp
+\param{wxItemKind}{ kind = wxITEM\_NORMAL},\rtfsp
+\param{const wxString\& }{shortHelpString = ""},
+\param{const wxString\& }{longHelpString = ""},\rtfsp
+\param{wxObject* }{clientData = NULL}}
+
+Adds a tool to the toolbar. The first (short and most commonly used) version
+has fewer parameters than the full version at the price of not being able to
+specify some of the more rarely used button features.
\wxheading{Parameters}
-\docparam{toolIndex}{An integer by which
+\docparam{toolId}{An integer by which
the tool may be identified in subsequent operations.}
-\docparam{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.}
+\docparam{kind}{May be wxITEM\_NORMAL for a normal button (default),
+wxITEM\_CHECK for a checkable tool (such tool stays pressed after it had been
+toggled) or wxITEM\_RADIO for a checkable tool which makes part of a radio
+group of tools each of which is automatically unchecked whenever another button
+in the group is checked}
\docparam{bitmap1}{The primary tool bitmap for toggle and button tools.}
border is drawn around the tool (colour displays) or the pixmap is shown
as a pressed button (GTK). }
-\docparam{xPos}{Specifies the x position of the tool if automatic layout is not suitable.}
+\docparam{shortHelpString}{This string is used for the tools tooltip}
-\docparam{yPos}{Specifies the y position of the tool if automatic layout is not suitable.}
+\docparam{longHelpString}{This string is shown in the statusbar (if any) of the
+parent frame when the mouse pointer is inside the tool}
\docparam{clientData}{An optional pointer to client data which can be
retrieved later using \helpref{wxToolBar::GetToolClientData}{wxtoolbargettoolclientdata}.}
-\docparam{shortHelpString}{Used for displaying a tooltip for the tool in the
-Windows 95 implementation of wxButtonBar. Pass the empty string if this is not required.}
-
-\docparam{longHelpString}{Used to displayer longer help, such as status line help.
-Pass the empty string if this is not required.}
-
\wxheading{Remarks}
After you have added tools to a toolbar, you must call \helpref{wxToolBar::Realize}{wxtoolbarrealize} in
\wxheading{See also}
-\helpref{wxToolBar::AddSeparator}{wxtoolbaraddseparator},
-\helpref{wxToolBar::Realize}{wxtoolbarrealize},
+\helpref{wxToolBar::AddSeparator}{wxtoolbaraddseparator},\rtfsp
+\helpref{wxToolBar::AddCheckTool}{wxtoolbaraddchecktool},\rtfsp
+\helpref{wxToolBar::AddRadioTool}{wxtoolbaraddradiotool},\rtfsp
+\helpref{wxToolBar::InsertTool}{wxtoolbarinserttool},\rtfsp
+\helpref{wxToolBar::DeleteTool}{wxtoolbardeletetool},\rtfsp
+\helpref{wxToolBar::Realize}{wxtoolbarrealize}
-\membersection{wxToolBar::CreateTools}\label{wxtoolbarcreatetools}
+\membersection{wxToolBar::AddCheckTool}\label{wxtoolbaraddchecktool}
-\func{bool}{CreateTools}{\void}
+\func{wxToolBarTool*}{AddCheckTool}{\param{int}{ toolId},\rtfsp
+\param{const wxString\&}{ label},\rtfsp
+\param{const wxBitmap\&}{ bitmap1},\rtfsp
+\param{const wxBitmap\&}{ bitmap2},\rtfsp
+\param{const wxString\& }{shortHelpString = ""},\rtfsp
+\param{const wxString\& }{longHelpString = ""},\rtfsp
+\param{wxObject* }{clientData = NULL}}
-This function is implemented for some toolbar classes to create the tools and display them.
-The portable way of calling it is to call \helpref{wxToolBar::Realize}{wxtoolbarrealize} after
-you have added tools and separators.
+Adds a new check (or toggle) tool to the toolbar. The parameters are the same
+as in \helpref{wxToolBar::AddTool}{wxtoolbaraddtool}.
\wxheading{See also}
-\helpref{wxToolBar::AddTool}{wxtoolbaraddtool}, \helpref{wxToolBar::Realize}{wxtoolbarrealize}
+\helpref{wxToolBar::AddTool}{wxtoolbaraddtool}
-\membersection{wxToolBar::DrawTool}\label{wxtoolbardrawtool}
+\membersection{wxToolBar::AddRadioTool}\label{wxtoolbaraddradiotool}
-\func{void}{DrawTool}{\param{wxMemoryDC\& }{memDC}, \param{wxToolBarTool* }{tool}}
+\func{wxToolBarTool*}{AddRadioTool}{\param{int}{ toolId},\rtfsp
+\param{const wxString\&}{ label},\rtfsp
+\param{const wxBitmap\&}{ bitmap1},\rtfsp
+\param{const wxBitmap\&}{ bitmap2},\rtfsp
+\param{const wxString\& }{shortHelpString = ""},\rtfsp
+\param{const wxString\& }{longHelpString = ""},\rtfsp
+\param{wxObject* }{clientData = NULL}}
-Draws the specified tool onto the window using the given memory device context.
+Adds a new radio tool to the toolbar. Consecutive radio tools form a radio
+group such that exactly one button in the group is pressed at any moment, in
+other words whenever a button in the group is pressed the previously pressed
+button is automatically released. You should avoid having the radio groups of
+only one element as it would be impossible for the user to use such button.
-\wxheading{Parameters}
+By default, the first button in the radio group is initially pressed, the
+others are not.
-\docparam{memDC}{A memory DC to be used for drawing the tool.}
+\wxheading{See also}
-\docparam{tool}{Tool to be drawn.}
+\helpref{wxToolBar::AddTool}{wxtoolbaraddtool}
-\wxheading{Remarks}
+\membersection{wxToolBar::DeleteTool}\label{wxtoolbardeletetool}
+
+\func{bool}{DeleteTool}{\param{int }{toolId}}
+
+Removes the specified tool from the toolbar and deletes it. If you don't want
+to delete the tool, but just to remove it from the toolbar (to possibly add it
+back later), you may use \helpref{RemoveTool}{wxtoolbarremovetool} instead.
+
+Note that it is unnecessary to call \helpref{Realize}{wxtoolbarrealize} for the
+change to take place, it will happen immediately.
-For internal use only.
+Returns TRUE if the tool was deleted, FALSE otherwise.
+
+\wxheading{See also}
+
+\helpref{DeleteToolByPos}{wxtoolbardeletetoolbypos}
+
+\membersection{wxToolBar::DeleteToolByPos}\label{wxtoolbardeletetoolbypos}
+
+\func{bool}{DeleteToolByPos}{\param{size\_t }{pos}}
+
+This function behaves like \helpref{DeleteTool}{wxtoolbardeletetool} but it
+deletes the tool at the specified position and not the one with the given id.
\membersection{wxToolBar::EnableTool}\label{wxtoolbarenabletool}
-\func{void}{EnableTool}{\param{int }{toolIndex}, \param{const bool}{ enable}}
+\func{void}{EnableTool}{\param{int }{toolId}, \param{const bool}{ enable}}
Enables or disables the tool.
\wxheading{Parameters}
-\docparam{toolIndex}{Tool to enable or disable.}
+\docparam{toolId}{Tool to enable or disable.}
\docparam{enable}{If TRUE, enables the tool, otherwise disables it.}
+{\bf NB:} This function should only be called after
+\helpref{Realize}{wxtoolbarrealize}.
+
\wxheading{Remarks}
For wxToolBarSimple, does nothing. Some other implementations
\wxheading{See also}
\helpref{wxToolBar::GetToolEnabled}{wxtoolbargettoolenabled},\rtfsp
-%\helpref{wxToolBar::SetToolState}{wxtoolbarsettoolstate},\rtfsp
\helpref{wxToolBar::ToggleTool}{wxtoolbartoggletool}
\membersection{wxToolBar::FindToolForPosition}\label{wxtoolbarfindtoolforposition}
\helpref{wxToolBar::SetMargins}{wxtoolbarsetmargins}
-\membersection{wxToolBar::GetMaxSize}\label{wxtoolbargetmaxsize}
-
-\constfunc{wxSize}{GetMaxSize}{\void}
-
-Gets the maximum size taken up by the tools after layout, including margins.
-This can be used to size a frame around the toolbar window.
-
\membersection{wxToolBar::GetToolClientData}\label{wxtoolbargettoolclientdata}
-\constfunc{wxObject*}{GetToolClientData}{\param{int }{toolIndex}}
+\constfunc{wxObject*}{GetToolClientData}{\param{int }{toolId}}
Get any client data associated with the tool.
\wxheading{Parameters}
-\docparam{toolIndex}{Index of the tool, as passed to \helpref{wxToolBar::AddTool}{wxtoolbaraddtool}.}
+\docparam{toolId}{Id of the tool, as passed to \helpref{wxToolBar::AddTool}{wxtoolbaraddtool}.}
\wxheading{Return value}
\membersection{wxToolBar::GetToolEnabled}\label{wxtoolbargettoolenabled}
-\constfunc{bool}{GetToolEnabled}{\param{int }{toolIndex}}
+\constfunc{bool}{GetToolEnabled}{\param{int }{toolId}}
Called to determine whether a tool is enabled (responds to user input).
\wxheading{Parameters}
-\docparam{toolIndex}{Index of the tool in question.}
+\docparam{toolId}{Id of the tool in question.}
\wxheading{Return value}
TRUE if the tool is enabled, FALSE otherwise.
-%\wxheading{See also}
-%
-%\helpref{wxToolBar::SetToolEnabled}{wxtoolbarsettoolenabled}
-%
+\wxheading{See also}
+
+\helpref{wxToolBar::EnableTool}{wxtoolbarenabletool}
+
\membersection{wxToolBar::GetToolLongHelp}\label{wxtoolbargettoollonghelp}
-\constfunc{wxString}{GetToolLongHelp}{\param{int }{toolIndex}}
+\constfunc{wxString}{GetToolLongHelp}{\param{int }{toolId}}
Returns the long help for the given tool.
\wxheading{Parameters}
-\docparam{toolIndex}{The tool in question.}
+\docparam{toolId}{The tool in question.}
\wxheading{See also}
\membersection{wxToolBar::GetToolShortHelp}\label{wxtoolbargettoolshorthelp}
-\constfunc{wxString}{GetToolShortHelp}{\param{int }{toolIndex}}
+\constfunc{wxString}{GetToolShortHelp}{\param{int }{toolId}}
Returns the short help for the given tool.
-Returns the long help for the given tool.
-
\wxheading{Parameters}
-\docparam{toolIndex}{The tool in question.}
+\docparam{toolId}{The tool in question.}
\wxheading{See also}
\membersection{wxToolBar::GetToolState}\label{wxtoolbargettoolstate}
-\constfunc{bool}{GetToolState}{\param{int }{toolIndex}}
+\constfunc{bool}{GetToolState}{\param{int }{toolId}}
Gets the on/off state of a toggle tool.
\wxheading{Parameters}
-\docparam{toolIndex}{The tool in question.}
+\docparam{toolId}{The tool in question.}
\wxheading{Return value}
TRUE if the tool is toggled on, FALSE otherwise.
-%\wxheading{See also}
-%
-%\helpref{wxToolBar::SetToolState}{wxtoolbarsettoolstate}
-%
-\membersection{wxToolBar::Layout}\label{wxtoolbarlayout}
+\wxheading{See also}
+
+\helpref{wxToolBar::ToggleTool}{wxtoolbartoggletool}
+
+\membersection{wxToolBar::InsertControl}\label{wxtoolbarinsertcontrol}
+
+\func{wxToolBarTool *}{InsertControl}{\param{size\_t }{pos}, \param{wxControl *}{control}}
+
+Inserts the control into the toolbar at the given position.
+
+You must call \helpref{Realize}{wxtoolbarrealize} for the change to take place.
-\func{void}{Layout}{\void}
+\wxheading{See also}
+
+\helpref{AddControl}{wxtoolbaraddcontrol},\\
+\helpref{InsertTool}{wxtoolbarinserttool}
+
+\membersection{wxToolBar::InsertSeparator}\label{wxtoolbarinsertseparator}
-Called by the application after the tools have been added to
-automatically lay the tools out on the window. If you have given
-absolute positions when adding the tools, do not call this.
+\func{wxToolBarTool *}{InsertSeparator}{\param{size\_t }{pos}}
-This function is only implemented for some toolbar classes.
-The portable way of calling it is to call \helpref{wxToolBar::Realize}{wxtoolbarrealize} after
-you have added tools and separators.
+Inserts the separator into the toolbar at the given position.
+
+You must call \helpref{Realize}{wxtoolbarrealize} for the change to take place.
\wxheading{See also}
-\helpref{wxToolBar::AddTool}{wxtoolbaraddtool}, \helpref{wxToolBar::Realize}{wxtoolbarrealize}
+\helpref{AddSeparator}{wxtoolbaraddseparator},\\
+\helpref{InsertTool}{wxtoolbarinserttool}
+
+\membersection{wxToolBar::InsertTool}\label{wxtoolbarinserttool}
+
+\func{wxToolBarTool *}{InsertTool}{\param{size\_t }{pos},\rtfsp
+\param{int}{ toolId}, \param{const wxBitmap\&}{ bitmap1},\rtfsp
+\param{const wxBitmap\&}{ bitmap2 = wxNullBitmap}, \param{bool}{ isToggle = FALSE},\rtfsp
+\param{wxObject* }{clientData = NULL}, \param{const wxString\& }{shortHelpString = ""}, \param{const wxString\& }{longHelpString = ""}}
+
+Inserts the tool with the specified attributes into the toolbar at the given
+position.
+
+You must call \helpref{Realize}{wxtoolbarrealize} for the change to take place.
+
+\wxheading{See also}
+
+\helpref{AddTool}{wxtoolbaraddtool},\\
+\helpref{InsertControl}{wxtoolbarinsertcontrol},\\
+\helpref{InsertSeparator}{wxtoolbarinsertseparator}
\membersection{wxToolBar::OnLeftClick}\label{wxtoolbaronleftclick}
-\func{bool}{OnLeftClick}{\param{int}{ toolIndex}, \param{bool}{ toggleDown}}
+\func{bool}{OnLeftClick}{\param{int}{ toolId}, \param{bool}{ toggleDown}}
Called when the user clicks on a tool with the left mouse button.
\wxheading{Parameters}
-\docparam{toolIndex}{The identifier passed to \helpref{wxToolBar::AddTool}{wxtoolbaraddtool}.}
+\docparam{toolId}{The identifier passed to \helpref{wxToolBar::AddTool}{wxtoolbaraddtool}.}
\docparam{toggleDown}{TRUE if the tool is a toggle and the toggle is down, otherwise is FALSE.}
\membersection{wxToolBar::OnMouseEnter}\label{wxtoolbaronmouseenter}
-\func{void}{OnMouseEnter}{\param{int}{ toolIndex}}
+\func{void}{OnMouseEnter}{\param{int}{ toolId}}
This is called when the mouse cursor moves into a tool or out of
the toolbar.
\wxheading{Parameters}
-\docparam{toolIndex}{Greater than -1 if the mouse cursor has moved into the tool,
+\docparam{toolId}{Greater than -1 if the mouse cursor has moved into the tool,
or -1 if the mouse cursor has moved. The
programmer can override this to provide extra information about the tool,
such as a short description on the status line.}
\membersection{wxToolBar::OnRightClick}\label{wxtoolbaronrightclick}
-\func{void}{OnRightClick}{\param{int}{ toolIndex}, \param{float}{ x}, \param{float}{ y}}
+\func{void}{OnRightClick}{\param{int}{ toolId}, \param{float}{ x}, \param{float}{ 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.
\wxheading{Parameters}
-\docparam{toolIndex}{The identifier passed to \helpref{wxToolBar::AddTool}{wxtoolbaraddtool}.}
+\docparam{toolId}{The identifier passed to \helpref{wxToolBar::AddTool}{wxtoolbaraddtool}.}
\docparam{x}{The x position of the mouse cursor.}
\func{bool}{Realize}{\void}
-This function should be called after you have added tools. It
-calls, according to the implementation,
-either \helpref{wxToolBar::CreateTools}{wxtoolbarcreatetools} or
- \helpref{wxToolBar::Layout}{wxtoolbarlayout}.
+This function should be called after you have added tools.
If you are using absolute positions for your tools when using a wxToolBarSimple object,
do not call this function. You must call it at all other times.
-\membersection{wxToolBar::SetToolBitmapSize}\label{wxtoolbarsettoolbitmapsize}
-
-\func{void}{SetToolBitmapSize}{\param{const wxSize\&}{ size}}
-
-Sets the default size of each tool bitmap. The default bitmap size is 16 by 15 pixels.
-
-\wxheading{Parameters}
-
-\docparam{size}{The size of the bitmaps in the toolbar.}
+\membersection{wxToolBar::RemoveTool}\label{wxtoolbarremovetool}
-\wxheading{Remarks}
+\func{wxToolBarTool *}{RemoveTool}{\param{int }{id}}
-This should be called to tell the toolbar what the tool bitmap size is. Call
-it before you add tools.
+Removes the given tool from the toolbar but doesn't delete it. This allows to
+insert/add this tool back to this (or another) toolbar later.
-Note that this is the size of the bitmap you pass to \helpref{wxToolBar::AddTool}{wxtoolbaraddtool},
-and not the eventual size of the tool button.
+Note that it is unnecessary to call \helpref{Realize}{wxtoolbarrealize} for the
+change to take place, it will happen immediately.
\wxheading{See also}
-\helpref{wxToolBar::GetToolBitmapSize}{wxtoolbargettoolbitmapsize},\rtfsp
-\helpref{wxToolBar::GetToolSize}{wxtoolbargettoolsize}
+\helpref{DeleteTool}{wxtoolbardeletetool}
\membersection{wxToolBar::SetMargins}\label{wxtoolbarsetmargins}
\helpref{wxToolBar::GetMargins}{wxtoolbargetmargins}, \helpref{wxSize}{wxsize}
+\membersection{wxToolBar::SetToolBitmapSize}\label{wxtoolbarsettoolbitmapsize}
+
+\func{void}{SetToolBitmapSize}{\param{const wxSize\&}{ size}}
+
+Sets the default size of each tool bitmap. The default bitmap size is 16 by 15 pixels.
+
+\wxheading{Parameters}
+
+\docparam{size}{The size of the bitmaps in the toolbar.}
+
+\wxheading{Remarks}
+
+This should be called to tell the toolbar what the tool bitmap size is. Call
+it before you add tools.
+
+Note that this is the size of the bitmap you pass to \helpref{wxToolBar::AddTool}{wxtoolbaraddtool},
+and not the eventual size of the tool button.
+
+\wxheading{See also}
+
+\helpref{wxToolBar::GetToolBitmapSize}{wxtoolbargettoolbitmapsize},\rtfsp
+\helpref{wxToolBar::GetToolSize}{wxtoolbargettoolsize}
+
+\membersection{wxToolBar::SetToolClientData}\label{wxtoolbarsettoolclientdata}
+
+\func{void}{GetToolClientData}{\param{wxObject* }{clientData}}
+
+Sets the client data associated with the tool.
+
\membersection{wxToolBar::SetToolLongHelp}\label{wxtoolbarsettoollonghelp}
-\func{void}{SetToolLongHelp}{\param{int }{toolIndex}, \param{const wxString\& }{helpString}}
+\func{void}{SetToolLongHelp}{\param{int }{toolId}, \param{const wxString\& }{helpString}}
Sets the long help for the given tool.
\wxheading{Parameters}
-\docparam{toolIndex}{The tool in question.}
+\docparam{toolId}{The tool in question.}
\docparam{helpString}{A string for the long help.}
\membersection{wxToolBar::SetToolShortHelp}\label{wxtoolbarsettoolshorthelp}
-\func{void}{SetToolShortHelp}{\param{int }{toolIndex}, \param{const wxString\& }{helpString}}
+\func{void}{SetToolShortHelp}{\param{int }{toolId}, \param{const wxString\& }{helpString}}
Sets the short help for the given tool.
\wxheading{Parameters}
-\docparam{toolIndex}{The tool in question.}
+\docparam{toolId}{The tool in question.}
\docparam{helpString}{The string for the short help.}
\membersection{wxToolBar::ToggleTool}\label{wxtoolbartoggletool}
-\func{void}{ToggleTool}{\param{int }{toolIndex}, \param{const bool}{ toggle}}
+\func{void}{ToggleTool}{\param{int }{toolId}, \param{const bool}{ toggle}}
Toggles a tool on or off. This does not cause any event to get emitted.
\wxheading{Parameters}
-\docparam{toolIndex}{Tool in question.}
+\docparam{toolId}{Tool in question.}
\docparam{toggle}{If TRUE, toggles the tool on, otherwise toggles it off.}
projects / wxWidgets.git / blobdiff