X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/5ef2e6333e6355ac6c925b07909408a631c5ee26..93fa67c0e6124d2657488971800c8fd068dc0d0e:/docs/latex/wx/toolbar.tex?ds=inline diff --git a/docs/latex/wx/toolbar.tex b/docs/latex/wx/toolbar.tex index 39465088d1..0fe30b435e 100644 --- a/docs/latex/wx/toolbar.tex +++ b/docs/latex/wx/toolbar.tex @@ -42,23 +42,39 @@ 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} \twocolwidtha{5cm} \begin{twocollist}\itemsep=0pt -\twocolitem{\windowstyle{wxTB\_FLAT}}{Gives the toolbar a flat look ('coolbar' or 'flatbar' style). Windows 95 and GTK 1.2 only.} -\twocolitem{\windowstyle{wxTB\_DOCKABLE}}{Makes the toolbar floatable and dockable. GTK only.} -\twocolitem{\windowstyle{wxTB\_HORIZONTAL}}{Specifies horizontal layout.} -\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\_FLAT}} +{Gives the toolbar a flat look (Windows and GTK only).} +\twocolitem{\windowstyle{wxTB\_DOCKABLE}} +{Makes the toolbar floatable and dockable (GTK only).} +\twocolitem{\windowstyle{wxTB\_HORIZONTAL}} +{Specifies horizontal layout (default).} +\twocolitem{\windowstyle{wxTB\_VERTICAL}} +{Specifies vertical layout.} +\twocolitem{\windowstyle{wxTB\_3DBUTTONS}} +{Only for wxToolBarSimple: gives 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 (border) above the toolbar (Windows only).} +\twocolitem{\windowstyle{wxTB\_NOALIGN}} +{Specifies no alignment with the parent window (Windows only, not very useful).} +\twocolitem{\windowstyle{wxTB\_HORZ\_LAYOUT}} +{Show the text and the icons alongside, not vertically stacked (Windows and GTK +2 only). This style must be used with wxTB\_TEXT.} +\twocolitem{\windowstyle{wxTB\_HORZ\_TEXT}} +{Combination of wxTB\_HORZ\_LAYOUT and wxTB\_TEXT.} \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 +184,38 @@ 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 = ""}} +\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. +\func{wxToolBarTool*}{AddTool}{\param{wxToolBarTool* }{tool}} + +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. The last version allows +to add an existing tool. \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,17 +225,15 @@ 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{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}{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{tool}{The tool to be added.} \wxheading{Remarks} @@ -210,10 +242,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} @@ -226,7 +300,7 @@ 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. -Returns TRUE if the tool was deleted, FALSE otherwise. +Returns true if the tool was deleted, false otherwise. \wxheading{See also} @@ -249,7 +323,10 @@ Enables or disables the tool. \docparam{toolId}{Tool to enable or disable.} -\docparam{enable}{If TRUE, enables the tool, otherwise disables it.} +\docparam{enable}{If true, enables the tool, otherwise disables it.} + +{\bf NB:} This function should only be called after +\helpref{Realize}{wxtoolbarrealize}. \wxheading{Remarks} @@ -261,6 +338,13 @@ will change the visible state of the tool to indicate that it is disabled. \helpref{wxToolBar::GetToolEnabled}{wxtoolbargettoolenabled},\rtfsp \helpref{wxToolBar::ToggleTool}{wxtoolbartoggletool} +\membersection{wxToolBar::FindControl}\label{wxtoolbarfindcontrol} + +\func{wxControl*}{FindControl}{\param{int }{id}} + +Returns a pointer to the control identified by {\it id} or +NULL if no corresponding control is found. + \membersection{wxToolBar::FindToolForPosition}\label{wxtoolbarfindtoolforposition} \constfunc{wxToolBarTool*}{FindToolForPosition}{\param{const float}{ x}, \param{const float}{ y}} @@ -345,7 +429,7 @@ Called to determine whether a tool is enabled (responds to user input). \wxheading{Return value} -TRUE if the tool is enabled, FALSE otherwise. +true if the tool is enabled, false otherwise. \wxheading{See also} @@ -376,6 +460,12 @@ Returns the value used for packing tools. \helpref{wxToolBar::SetToolPacking}{wxtoolbarsettoolpacking} +\membersection{wxToolBar::GetToolPos}\label{wxtoolbargettoolpos} + +\constfunc{int}{GetToolPos}{\param{int }{toolId}} + +Returns the tool position in the toolbar, or wxNOT\_FOUND if the tool is not found. + \membersection{wxToolBar::GetToolSeparation}\label{wxtoolbargettoolseparation} \constfunc{int}{GetToolSeparation}{\void} @@ -392,8 +482,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.} @@ -415,7 +503,7 @@ Gets the on/off state of a toggle tool. \wxheading{Return value} -TRUE if the tool is toggled on, FALSE otherwise. +true if the tool is toggled on, false otherwise. \wxheading{See also} @@ -450,10 +538,13 @@ 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{const wxBitmap\&}{ bitmap2 = wxNullBitmap}, \param{bool}{ isToggle = FALSE},\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 = ""}} +\func{wxToolBarTool *}{InsertTool}{\param{size\_t }{pos},\rtfsp +\param{wxToolBarTool* }{tool}} + Inserts the tool with the specified attributes into the toolbar at the given position. @@ -478,11 +569,11 @@ you should use the EVT\_MENU or EVT\_TOOL macro instead. \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.} +\docparam{toggleDown}{true if the tool is a toggle and the toggle is down, otherwise is false.} \wxheading{Return value} -If the tool is a toggle and this function returns FALSE, the toggle +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. @@ -544,10 +635,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 +654,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 +702,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}} - -\func{void}{SetMargins}{\param{int}{ x}, \param{int}{ y}} - -Set the values to be used as margins for the toolbar. +\membersection{wxToolBar::SetToolClientData}\label{wxtoolbarsettoolclientdata} -\wxheading{Parameters} +\func{void}{SetToolClientData}{\param{int }{id}, \param{wxObject* }{clientData}} -\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} @@ -698,7 +792,7 @@ Toggles a tool on or off. This does not cause any event to get emitted. \docparam{toolId}{Tool in question.} -\docparam{toggle}{If TRUE, toggles the tool on, otherwise toggles it off.} +\docparam{toggle}{If true, toggles the tool on, otherwise toggles it off.} \wxheading{Remarks} @@ -707,5 +801,3 @@ Only applies to a tool that has been specified as a toggle tool. \wxheading{See also} \helpref{wxToolBar::GetToolState}{wxtoolbargettoolstate} - -