]> git.saurik.com Git - wxWidgets.git/blobdiff - docs/latex/wx/toolbar.tex
Added deprecated property classes for future reference (maybe separate manual)
[wxWidgets.git] / docs / latex / wx / toolbar.tex
index 39465088d1cc50c034f460d3ed39a44acbcfc1e1..c0daf6f9edd4b67ef6844d3e3e2b6d98e30f61e1 100644 (file)
@@ -42,9 +42,6 @@ ignore the values for explicit placement and use their own layout and the meanin
 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}
 
@@ -56,9 +53,15 @@ The toolbar orientation must always be {\bf wxHORIZONTAL}.
 \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}
 
@@ -168,20 +171,35 @@ Adds a separator for spacing groups of tools.
 
 \membersection{wxToolBar::AddTool}\label{wxtoolbaraddtool}
 
-\func{wxToolBarTool*}{AddTool}{\param{int}{ toolId}, \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{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.}
 
@@ -191,18 +209,14 @@ used for the on-state of a toggle tool (monochrome displays) or a black
 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{yPos}{Specifies the y position of the tool if automatic layout is not suitable.}
-
-\docparam{clientData}{An optional pointer to client data which can be
-retrieved later using \helpref{wxToolBar::GetToolClientData}{wxtoolbargettoolclientdata}.}
-
 \docparam{shortHelpString}{This string is used for the tools tooltip}
 
 \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}.}
+
 \wxheading{Remarks}
 
 After you have added tools to a toolbar, you must call \helpref{wxToolBar::Realize}{wxtoolbarrealize} in
@@ -210,10 +224,52 @@ order to have the tools appear.
 
 \wxheading{See also}
 
-\helpref{wxToolBar::AddSeparator}{wxtoolbaraddseparator},
-\helpref{wxToolBar::InsertTool}{wxtoolbarinserttool},
-\helpref{wxToolBar::DeleteTool}{wxtoolbardeletetool},
-\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::AddCheckTool}\label{wxtoolbaraddchecktool}
+
+\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}}
+
+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}
+
+\membersection{wxToolBar::AddRadioTool}\label{wxtoolbaraddradiotool}
+
+\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}}
+
+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.
+
+By default, the first button in the radio group is initially pressed, the
+others are not.
+
+\wxheading{See also}
+
+\helpref{wxToolBar::AddTool}{wxtoolbaraddtool}
 
 \membersection{wxToolBar::DeleteTool}\label{wxtoolbardeletetool}
 
@@ -251,6 +307,9 @@ Enables or disables the tool.
 
 \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
@@ -392,8 +451,6 @@ Returns the default separator size.
 
 Returns the short help for the given tool.
 
-Returns the long help for the given tool.
-
 \wxheading{Parameters}
 
 \docparam{toolId}{The tool in question.}
@@ -450,7 +507,7 @@ You must call \helpref{Realize}{wxtoolbarrealize} for the change to take place.
 \membersection{wxToolBar::InsertTool}\label{wxtoolbarinserttool}
 
 \func{wxToolBarTool *}{InsertTool}{\param{size\_t }{pos},\rtfsp
-{\param{int}{ toolId}, \param{const wxBitmap\&}{ bitmap1},\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 = ""}}
 
@@ -544,10 +601,7 @@ A typical use of this member might be to pop up a menu.
 
 \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.
@@ -566,6 +620,31 @@ change to take place, it will happen immediately.
 
 \helpref{DeleteTool}{wxtoolbardeletetool}
 
+\membersection{wxToolBar::SetMargins}\label{wxtoolbarsetmargins}
+
+\func{void}{SetMargins}{\param{const wxSize\&}{ size}}
+
+\func{void}{SetMargins}{\param{int}{ x}, \param{int}{ y}}
+
+Set the values to be used as margins for the toolbar.
+
+\wxheading{Parameters}
+
+\docparam{size}{Margin size.}
+
+\docparam{x}{Left margin, right margin and inter-tool separation value.}
+
+\docparam{y}{Top margin, bottom margin and inter-tool separation value.}
+
+\wxheading{Remarks}
+
+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.
+
+\wxheading{See also}
+
+\helpref{wxToolBar::GetMargins}{wxtoolbargetmargins}, \helpref{wxSize}{wxsize}
+
 \membersection{wxToolBar::SetToolBitmapSize}\label{wxtoolbarsettoolbitmapsize}
 
 \func{void}{SetToolBitmapSize}{\param{const wxSize\&}{ size}}
@@ -589,30 +668,11 @@ and not the eventual size of the tool button.
 \helpref{wxToolBar::GetToolBitmapSize}{wxtoolbargettoolbitmapsize},\rtfsp
 \helpref{wxToolBar::GetToolSize}{wxtoolbargettoolsize}
 
-\membersection{wxToolBar::SetMargins}\label{wxtoolbarsetmargins}
-
-\func{void}{SetMargins}{\param{const wxSize\&}{ size}}
+\membersection{wxToolBar::SetToolClientData}\label{wxtoolbarsettoolclientdata}
 
-\func{void}{SetMargins}{\param{int}{ x}, \param{int}{ y}}
+\func{void}{GetToolClientData}{\param{wxObject* }{clientData}}
 
-Set the values to be used as margins for the toolbar.
-
-\wxheading{Parameters}
-
-\docparam{size}{Margin size.}
-
-\docparam{x}{Left margin, right margin and inter-tool separation value.}
-
-\docparam{y}{Top margin, bottom margin and inter-tool separation value.}
-
-\wxheading{Remarks}
-
-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.
-
-\wxheading{See also}
-
-\helpref{wxToolBar::GetMargins}{wxtoolbargetmargins}, \helpref{wxSize}{wxsize}
+Sets the client data associated with the tool.
 
 \membersection{wxToolBar::SetToolLongHelp}\label{wxtoolbarsettoollonghelp}