X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/408776d0347b651ab4b00c2d613f8e51b1985a91..4d98817cfab2654773755cb5c540057c5f3d4fd6:/interface/wx/toolbar.h diff --git a/interface/wx/toolbar.h b/interface/wx/toolbar.h index 1292dfdfb1..7a15d2ccb0 100644 --- a/interface/wx/toolbar.h +++ b/interface/wx/toolbar.h @@ -3,56 +3,52 @@ // Purpose: interface of wxToolBar // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// /** @class wxToolBar - The name wxToolBar is defined to be a synonym for one of the following - classes: + A toolbar is a bar of buttons and/or other controls usually placed below + the menu bar in a wxFrame. - - @b wxToolBar95 - The native Windows 95 toolbar. Used on Windows 95, NT 4 - and above. - - @b wxToolBarMSW - A Windows implementation. Used on 16-bit Windows. - - @b wxToolBarGTK - The GTK toolbar. - - You may also create a toolbar that is managed by the frame, by calling + You may create a toolbar that is managed by a frame calling wxFrame::CreateToolBar(). Under Pocket PC, you should always use this function for creating the toolbar to be managed by the frame, so that wxWidgets can use a combined menubar and toolbar. Where you manage your - own toolbars, create a wxToolBar as usual. - - The meaning of a "separator" is a vertical line under Windows and simple - space under GTK+. - - @b wxToolBar95: Note that this toolbar paints tools to reflect - system-wide colours. If you use more than 16 colours in your tool - bitmaps, you may wish to suppress this behaviour, otherwise system - colours in your bitmaps will inadvertently be mapped to system colours. + own toolbars, create wxToolBar as usual. + + There are several different types of tools you can add to a toolbar. + These types are controlled by the ::wxItemKind enumeration. + + Note that many methods in wxToolBar such as wxToolBar::AddTool return a + @c wxToolBarToolBase* object. + This should be regarded as an opaque handle representing the newly added + toolbar item, providing access to its id and position within the toolbar. + Changes to the item's state should be made through calls to wxToolBar methods, + for example wxToolBar::EnableTool. + Calls to @c wxToolBarToolBase methods (undocumented by purpose) will not change + the visible state of the item within the tool bar. + + wxMSW note: Note that under wxMSW toolbar paints tools to reflect + system-wide colours. If you use more than 16 colours in your tool bitmaps, + you may wish to suppress this behaviour, otherwise system colours in your + bitmaps will inadvertently be mapped to system colours. To do this, set the msw.remap system option before creating the toolbar: - @code - wxSystemOptions::SetOption(wxT("msw.remap"), 0); + wxSystemOptions::SetOption("msw.remap", 0); @endcode - If you wish to use 32-bit images (which include an alpha channel for transparency) use: - @code - wxSystemOptions::SetOption(wxT("msw.remap"), 2); + wxSystemOptions::SetOption("msw.remap", 2); @endcode - Then colour remapping is switched off, and a transparent background used. But only use this option under Windows XP with true colour: - @code if (wxTheApp->GetComCtl32Version() >= 600 && ::wxDisplayDepth() >= 32) @endcode - There are several different types of tools you can add to a toolbar. These - types are controlled by the ::wxItemKind enumeration. - @beginStyleTable @style{wxTB_FLAT} Gives the toolbar a flat look (Windows and GTK only). @@ -85,11 +81,11 @@ Align the toolbar at the right side of parent window. @endStyleTable - See also @ref overview_windowstyles. Note that the Win32 native toolbar + See also @ref overview_windowstyles. Note that the wxMSW native toolbar ignores @c wxTB_NOICONS style. Also, toggling the @c wxTB_TEXT works only if the style was initially on. - @beginEventTable{wxCommandEvent} + @beginEventEmissionTable{wxCommandEvent} @event{EVT_TOOL(id, func)} Process a @c wxEVT_COMMAND_TOOL_CLICKED event (a synonym for @c wxEVT_COMMAND_MENU_SELECTED). Pass the id of the tool. @@ -102,14 +98,14 @@ The same as EVT_TOOL_RANGE(). @event{EVT_TOOL_RCLICKED(id, func)} Process a @c wxEVT_COMMAND_TOOL_RCLICKED event. Pass the id of the - tool. + tool. (Not available on wxOSX.) @event{EVT_TOOL_RCLICKED_RANGE(id1, id2, func)} Process a @c wxEVT_COMMAND_TOOL_RCLICKED event for a range of ids. Pass - the ids of the tools. + the ids of the tools. (Not available on wxOSX.) @event{EVT_TOOL_ENTER(id, func)} Process a @c wxEVT_COMMAND_TOOL_ENTER event. Pass the id of the toolbar itself. The value of wxCommandEvent::GetSelection() is the tool id, or - -1 if the mouse cursor has moved off a tool. + -1 if the mouse cursor has moved off a tool. (Not available on wxOSX.) @event{EVT_TOOL_DROPDOWN(id, func)} Process a @c wxEVT_COMMAND_TOOL_DROPDOWN_CLICKED event. If unhandled, displays the default dropdown menu set using @@ -121,8 +117,8 @@ button. The event handler functions take a wxCommandEvent argument. For most event macros, the identifier of the tool is passed, but for EVT_TOOL_ENTER() the toolbar window identifier is passed and the tool identifier is retrieved - from the wxCommandEvent. This is because the identifier may be -1 when the - mouse moves off a tool, and -1 is not allowed as an identifier in the event + from the wxCommandEvent. This is because the identifier may be @c wxID_ANY when the + mouse moves off a tool, and @c wxID_ANY is not allowed as an identifier in the event system. @library{wxcore} @@ -146,25 +142,25 @@ public: @param id Window identifier. If -1, will automatically create an identifier. @param pos - Window position. ::wxDefaultPosition is (-1, -1) which indicates that - wxWidgets should generate a default position for the window. If - using the wxWindow class directly, supply an actual position. + Window position. ::wxDefaultPosition indicates that wxWidgets should + generate a default position for the window. + If using the wxWindow class directly, supply an actual position. @param size - Window size. ::wxDefaultSize is (-1, -1) which indicates that - wxWidgets should generate a default size for the window. + Window size. ::wxDefaultSize indicates that wxWidgets should generate + a default size for the window. @param style - Window style. See wxToolBar for details. + Window style. See wxToolBar initial description for details. @param name Window name. @remarks After a toolbar is created, you use AddTool() and perhaps - AddSeparator(), and then you must call Realize() to construct and - display the toolbar tools. + AddSeparator(), and then you must call Realize() to construct + and display the toolbar tools. */ wxToolBar(wxWindow* parent, wxWindowID id, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, - long style = wxTB_HORIZONTAL | wxBORDER_NONE, + long style = wxTB_HORIZONTAL, const wxString& name = wxToolBarNameStr); /** @@ -228,10 +224,32 @@ public: /** Adds a separator for spacing groups of tools. - @see AddTool(), SetToolSeparation() + Notice that the separator uses the look appropriate for the current + platform so it can be a vertical line (MSW, some versions of GTK) or + just an empty space or something else. + + @see AddTool(), SetToolSeparation(), AddStretchableSpace() */ virtual wxToolBarToolBase* AddSeparator(); + /** + Adds a stretchable space to the toolbar. + + Any space not taken up by the fixed items (all items except for + stretchable spaces) is distributed in equal measure between the + stretchable spaces in the toolbar. The most common use for this method + is to add a single stretchable space before the items which should be + right-aligned in the toolbar, but more exotic possibilities are + possible, e.g. a stretchable space may be added in the beginning and + the end of the toolbar to centre all toolbar items. + + @see AddTool(), AddSeparator(), InsertStretchableSpace() + + @since 2.9.1 + */ + wxToolBarToolBase *AddStretchableSpace(); + + //@{ /** Adds a tool to the toolbar. @@ -239,7 +257,7 @@ public: The tool to be added. @remarks After you have added tools to a toolbar, you must call - Realize() in order to have the tools appear. + Realize() in order to have the tools appear. @see AddSeparator(), AddCheckTool(), AddRadioTool(), InsertTool(), DeleteTool(), Realize(), SetDropdownMenu() @@ -294,11 +312,6 @@ public: The bitmap used when the tool is disabled. If it is equal to ::wxNullBitmap (default), the disabled bitmap is automatically generated by greying the normal one. - @param shortHelpString - This string is used for the tools tooltip. - @param longHelpString - This string is shown in the statusbar (if any) of the parent frame - when the mouse pointer is inside the tool. @param kind May be ::wxITEM_NORMAL for a normal button (default), ::wxITEM_CHECK for a checkable tool (such tool stays pressed after it had been @@ -307,6 +320,11 @@ public: whenever another button in the group is checked. ::wxITEM_DROPDOWN specifies that a drop-down menu button will appear next to the tool button (only GTK+ and MSW). Call SetDropdownMenu() afterwards. + @param shortHelpString + This string is used for the tools tooltip. + @param longHelpString + This string is shown in the statusbar (if any) of the parent frame + when the mouse pointer is inside the tool. @param clientData An optional pointer to client data which can be retrieved later using GetToolClientData(). @@ -324,6 +342,7 @@ public: const wxString& shortHelpString = wxEmptyString, const wxString& longHelpString = wxEmptyString, wxObject* clientData = NULL); + //@} /** Deletes all the tools in the toolbar. @@ -354,7 +373,7 @@ public: Enables or disables the tool. @param toolId - Tool to enable or disable. + ID of the tool to enable or disable, as passed to AddTool(). @param enable If @true, enables the tool, otherwise disables it. @@ -402,8 +421,15 @@ public: wxSize GetMargins() const; /** - Returns the size of bitmap that the toolbar expects to have. The default - bitmap size is 16 by 15 pixels. + Returns the size of bitmap that the toolbar expects to have. + + The default bitmap size is platform-dependent: for example, it is 16*15 + for MSW and 24*24 for GTK. This size does @em not necessarily indicate + the best size to use for the toolbars on the given platform, for this + you should use @c wxArtProvider::GetNativeSizeHint(wxART_TOOLBAR) but + in any case, as the bitmap size is deduced automatically from the size + of the bitmaps associated with the tools added to the toolbar, it is + usually unnecessary to call SetToolBitmapSize() explicitly. @remarks Note that this is the size of the bitmap you pass to AddTool(), and not the eventual size of the tool button. @@ -412,11 +438,22 @@ public: */ virtual wxSize GetToolBitmapSize() const; + /** + Returns a pointer to the tool at ordinal position @a pos. + + Don't confuse this with FindToolForPosition(). + + @since 2.9.1 + + @see GetToolsCount() + */ + const wxToolBarToolBase *GetToolByPos(int pos) const; + /** Get any client data associated with the tool. @param toolId - Id of the tool, as passed to AddTool(). + ID of the tool in question, as passed to AddTool(). @return Client data, or @NULL if there is none. */ @@ -426,7 +463,7 @@ public: Called to determine whether a tool is enabled (responds to user input). @param toolId - Id of the tool in question. + ID of the tool in question, as passed to AddTool(). @return @true if the tool is enabled, @false otherwise. @@ -438,7 +475,7 @@ public: Returns the long help for the given tool. @param toolId - The tool in question. + ID of the tool in question, as passed to AddTool(). @see SetToolLongHelp(), SetToolShortHelp() */ @@ -454,6 +491,9 @@ public: /** Returns the tool position in the toolbar, or @c wxNOT_FOUND if the tool is not found. + + @param toolId + ID of the tool in question, as passed to AddTool(). */ virtual int GetToolPos(int toolId) const; @@ -468,7 +508,7 @@ public: Returns the short help for the given tool. @param toolId - The tool in question. + ID of the tool in question, as passed to AddTool(). @see GetToolLongHelp(), SetToolShortHelp() */ @@ -486,7 +526,7 @@ public: Gets the on/off state of a toggle tool. @param toolId - The tool in question. + ID of the tool in question, as passed to AddTool(). @return @true if the tool is toggled on, @false otherwise. @@ -516,6 +556,17 @@ public: */ virtual wxToolBarToolBase* InsertSeparator(size_t pos); + /** + Inserts a stretchable space at the given position. + + See AddStretchableSpace() for details about stretchable spaces. + + @see InsertTool(), InsertSeparator() + + @since 2.9.1 + */ + wxToolBarToolBase *InsertStretchableSpace(size_t pos); + //@{ /** Inserts the tool with the specified attributes into the toolbar at the @@ -524,14 +575,18 @@ public: You must call Realize() for the change to take place. @see AddTool(), InsertControl(), InsertSeparator() + + @return The newly inserted tool or @NULL on failure. Notice that with + the overload taking @a tool parameter the caller is responsible for + deleting the tool in the latter case. */ wxToolBarToolBase* InsertTool(size_t pos, int toolId, const wxBitmap& bitmap1, const wxBitmap& bitmap2 = wxNullBitmap, bool isToggle = false, wxObject* clientData = NULL, - const wxString& shortHelpString = "", - const wxString& longHelpString = ""); + const wxString& shortHelpString = wxEmptyString, + const wxString& longHelpString = wxEmptyString); wxToolBarToolBase* InsertTool(size_t pos, wxToolBarToolBase* tool); //@} @@ -628,6 +683,7 @@ public: */ bool SetDropdownMenu(int id, wxMenu* menu); + //@{ /** Set the values to be used as margins for the toolbar. @@ -657,6 +713,7 @@ public: @see GetMargins(), wxSize */ void SetMargins(const wxSize& size); + //@} /** Sets the default size of each tool bitmap. The default bitmap size is 16 @@ -674,6 +731,9 @@ public: /** Sets the client data associated with the tool. + + @param id + ID of the tool in question, as passed to AddTool(). */ virtual void SetToolClientData(int id, wxObject* clientData); @@ -682,6 +742,9 @@ public: is in a disabled state. This can only be used on Button tools, not controls. + @param id + ID of the tool in question, as passed to AddTool(). + @note The native toolbar classes on the main platforms all synthesize the disabled bitmap from the normal bitmap, so this function will have no effect on those platforms. @@ -693,7 +756,7 @@ public: Sets the long help for the given tool. @param toolId - The tool in question. + ID of the tool in question, as passed to AddTool(). @param helpString A string for the long help. @@ -707,6 +770,9 @@ public: /** Sets the bitmap to be used by the tool with the given ID. This can only be used on Button tools, not controls. + + @param id + ID of the tool in question, as passed to AddTool(). */ virtual void SetToolNormalBitmap(int id, const wxBitmap& bitmap); @@ -738,7 +804,7 @@ public: Sets the short help for the given tool. @param toolId - The tool in question. + ID of the tool in question, as passed to AddTool(). @param helpString The string for the short help. @@ -754,7 +820,7 @@ public: Toggles a tool on or off. This does not cause any event to get emitted. @param toolId - Tool in question. + ID of the tool in question, as passed to AddTool(). @param toggle If @true, toggles the tool on, otherwise toggles it off.