X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/12f5e1e78fe906050ff2fee9529476db332633f0..3c3ead1d1513a5eb79091a604f4e42b45d1bdf5d:/interface/wx/toolbar.h diff --git a/interface/wx/toolbar.h b/interface/wx/toolbar.h index bd4e4125dd..02698a9b39 100644 --- a/interface/wx/toolbar.h +++ b/interface/wx/toolbar.h @@ -9,49 +9,45 @@ /** @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 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} @@ -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. @@ -115,14 +111,14 @@ displays the default dropdown menu set using wxToolBar::SetDropdownMenu(). @endEventTable - + The toolbar class emits menu commands in the same way that a frame menubar does, so you can use one EVT_MENU() macro for both a menu item and a toolbar 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,31 +142,31 @@ 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, - const wxString& name = wxPanelNameStr); + long style = wxTB_HORIZONTAL, + const wxString& name = wxToolBarNameStr); /** Toolbar destructor. */ - ~wxToolBar(); + virtual ~wxToolBar(); /** Adds a new check (or toggle) tool to the toolbar. The parameters are the @@ -178,12 +174,11 @@ public: @see AddTool() */ - wxToolBarToolBase* AddCheckTool(int toolId, - const wxString& label, + wxToolBarToolBase* AddCheckTool(int toolId, const wxString& label, const wxBitmap& bitmap1, - const wxBitmap& bitmap2, - const wxString& shortHelpString = "", - const wxString& longHelpString = "", + const wxBitmap& bmpDisabled = wxNullBitmap, + const wxString& shortHelp = wxEmptyString, + const wxString& longHelp = wxEmptyString, wxObject* clientData = NULL); /** @@ -202,7 +197,8 @@ public: wxMac: labels are only displayed if wxWidgets is built with @c wxMAC_USE_NATIVE_TOOLBAR set to 1 */ - bool AddControl(wxControl* control, const wxString label = ""); + virtual wxToolBarToolBase* AddControl(wxControl* control, + const wxString& label = wxEmptyString); /** Adds a new radio tool to the toolbar. Consecutive radio tools form a @@ -211,28 +207,32 @@ public: 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. @see AddTool() */ - wxToolBarToolBase* AddRadioTool(int toolId, - const wxString& label, + wxToolBarToolBase* AddRadioTool(int toolId, const wxString& label, const wxBitmap& bitmap1, - const wxBitmap& bitmap2, - const wxString& shortHelpString = "", - const wxString& longHelpString = "", + const wxBitmap& bmpDisabled = wxNullBitmap, + const wxString& shortHelp = wxEmptyString, + const wxString& longHelp = wxEmptyString, wxObject* clientData = NULL); /** Adds a separator for spacing groups of tools. + 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() */ - void AddSeparator(); + virtual wxToolBarToolBase* AddSeparator(); + //@{ /** Adds a tool to the toolbar. @@ -245,17 +245,17 @@ public: @see AddSeparator(), AddCheckTool(), AddRadioTool(), InsertTool(), DeleteTool(), Realize(), SetDropdownMenu() */ - wxToolBarToolBase* AddTool(wxToolBarToolBase* tool); + virtual wxToolBarToolBase* AddTool(wxToolBarToolBase* tool); /** - Adds a tool to the toolbar. This most commonly used version has fewer + Adds a tool to the toolbar. This most commonly used version has fewer parameters than the full version below which specifies the more rarely used button features. @param toolId An integer by which the tool may be identified in subsequent operations. - @param label + @param label The string to be displayed with the tool. @param bitmap The primary tool bitmap. @@ -265,7 +265,7 @@ public: 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 + a radio group of tools each of which is automatically unchecked 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. @@ -287,13 +287,13 @@ public: @param toolId An integer by which the tool may be identified in subsequent operations. - @param label + @param label The string to be displayed with the tool. @param bitmap The primary tool bitmap. @param bmpDisabled The bitmap used when the tool is disabled. If it is equal to - ::wxNullBitmap (default), the disabled bitmap is automatically + ::wxNullBitmap (default), the disabled bitmap is automatically generated by greying the normal one. @param shortHelpString This string is used for the tools tooltip. @@ -304,7 +304,7 @@ public: 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 + a radio group of tools each of which is automatically unchecked 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. @@ -325,11 +325,12 @@ public: const wxString& shortHelpString = wxEmptyString, const wxString& longHelpString = wxEmptyString, wxObject* clientData = NULL); + //@} /** Deletes all the tools in the toolbar. */ - void ClearTools(); + virtual void ClearTools(); /** Removes the specified tool from the toolbar and deletes it. If you don't @@ -343,13 +344,13 @@ public: @see DeleteToolByPos() */ - bool DeleteTool(int toolId); + virtual bool DeleteTool(int toolId); /** This function behaves like DeleteTool() but it deletes the tool at the specified position and not the one with the given id. */ - bool DeleteToolByPos(size_t pos); + virtual bool DeleteToolByPos(size_t pos); /** Enables or disables the tool. @@ -365,19 +366,19 @@ public: @see GetToolEnabled(), ToggleTool() */ - void EnableTool(int toolId, bool enable); + virtual void EnableTool(int toolId, bool enable); /** Returns a pointer to the tool identified by @a id or @NULL if no corresponding tool is found. */ - wxToolBarToolBase* FindById(int id); + wxToolBarToolBase* FindById(int id) const; /** Returns a pointer to the control identified by @a id or @NULL if no corresponding control is found. */ - wxControl* FindControl(int id); + virtual wxControl* FindControl(int id); /** Finds a tool for the given mouse position. @@ -392,7 +393,7 @@ public: @remarks Currently not implemented in wxGTK (always returns @NULL there). */ - wxToolBarToolBase* FindToolForPosition(wxCoord x, wxCoord y) const; + virtual wxToolBarToolBase* FindToolForPosition(wxCoord x, wxCoord y) const; /** Returns the left/right and top/bottom margins, which are also used for @@ -403,15 +404,22 @@ 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. @see SetToolBitmapSize(), GetToolSize() */ - wxSize GetToolBitmapSize(); + virtual wxSize GetToolBitmapSize() const; /** Get any client data associated with the tool. @@ -421,7 +429,7 @@ public: @return Client data, or @NULL if there is none. */ - wxObject* GetToolClientData(int toolId) const; + virtual wxObject* GetToolClientData(int toolId) const; /** Called to determine whether a tool is enabled (responds to user input). @@ -433,7 +441,7 @@ public: @see EnableTool() */ - bool GetToolEnabled(int toolId) const; + virtual bool GetToolEnabled(int toolId) const; /** Returns the long help for the given tool. @@ -443,27 +451,27 @@ public: @see SetToolLongHelp(), SetToolShortHelp() */ - wxString GetToolLongHelp(int toolId) const; + virtual wxString GetToolLongHelp(int toolId) const; /** Returns the value used for packing tools. @see SetToolPacking() */ - int GetToolPacking() const; + virtual int GetToolPacking() const; /** Returns the tool position in the toolbar, or @c wxNOT_FOUND if the tool is not found. */ - int GetToolPos(int toolId) const; + virtual int GetToolPos(int toolId) const; /** Returns the default separator size. @see SetToolSeparation() */ - int GetToolSeparation() const; + virtual int GetToolSeparation() const; /** Returns the short help for the given tool. @@ -473,7 +481,7 @@ public: @see GetToolLongHelp(), SetToolShortHelp() */ - wxString GetToolShortHelp(int toolId) const; + virtual wxString GetToolShortHelp(int toolId) const; /** Returns the size of a whole button, which is usually larger than a tool @@ -481,7 +489,7 @@ public: @see SetToolBitmapSize(), GetToolBitmapSize() */ - wxSize GetToolSize(); + virtual wxSize GetToolSize() const; /** Gets the on/off state of a toggle tool. @@ -493,12 +501,12 @@ public: @see ToggleTool() */ - bool GetToolState(int toolId) const; + virtual bool GetToolState(int toolId) const; /** Returns the number of tools in the toolbar. */ - int GetToolsCount() const; + size_t GetToolsCount() const; /** Inserts the control into the toolbar at the given position. You must @@ -506,7 +514,8 @@ public: @see AddControl(), InsertTool() */ - wxToolBarToolBase* InsertControl(size_t pos, wxControl* control); + virtual wxToolBarToolBase* InsertControl(size_t pos, wxControl* control, + const wxString& label = wxEmptyString); /** Inserts the separator into the toolbar at the given position. You must @@ -514,7 +523,7 @@ public: @see AddSeparator(), InsertTool() */ - wxToolBarToolBase* InsertSeparator(size_t pos); + virtual wxToolBarToolBase* InsertSeparator(size_t pos); //@{ /** @@ -530,8 +539,8 @@ public: 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); //@} @@ -554,7 +563,7 @@ public: @see OnMouseEnter(), OnRightClick() */ - bool OnLeftClick(int toolId, bool toggleDown); + virtual bool OnLeftClick(int toolId, bool toggleDown); /** This is called when the mouse cursor moves into a tool or out of the @@ -572,7 +581,7 @@ public: out of the toolbar, wxWidgets may not be able to detect it. Therefore this function may not always be called when expected. */ - void OnMouseEnter(int toolId); + virtual void OnMouseEnter(int toolId); /** @deprecated This is the old way of detecting tool right clicks; @@ -593,12 +602,12 @@ public: @see OnMouseEnter(), OnLeftClick() */ - void OnRightClick(int toolId, float x, float y); + virtual void OnRightClick(int toolId, long x, long y); /** This function should be called after you have added tools. */ - bool Realize(); + virtual bool Realize(); /** Removes the given tool from the toolbar but doesn't delete it. This @@ -610,7 +619,7 @@ public: @see DeleteTool() */ - wxToolBarToolBase* RemoveTool(int id); + virtual wxToolBarToolBase* RemoveTool(int id); /** Sets the bitmap resource identifier for specifying tool bitmaps as @@ -628,6 +637,7 @@ public: */ bool SetDropdownMenu(int id, wxMenu* menu); + //@{ /** Set the values to be used as margins for the toolbar. @@ -642,7 +652,7 @@ public: @see GetMargins() */ - void SetMargins(int x, int y); + virtual void SetMargins(int x, int y); /** Set the margins for the toolbar. @@ -657,6 +667,7 @@ public: @see GetMargins(), wxSize */ void SetMargins(const wxSize& size); + //@} /** Sets the default size of each tool bitmap. The default bitmap size is 16 @@ -670,12 +681,12 @@ public: @see GetToolBitmapSize(), GetToolSize() */ - void SetToolBitmapSize(const wxSize& size); + virtual void SetToolBitmapSize(const wxSize& size); /** Sets the client data associated with the tool. */ - void SetToolClientData(int id, wxObject* clientData); + virtual void SetToolClientData(int id, wxObject* clientData); /** Sets the bitmap to be used by the tool with the given ID when the tool @@ -687,7 +698,7 @@ public: have no effect on those platforms. */ - void SetToolDisabledBitmap(int id, const wxBitmap& bitmap); + virtual void SetToolDisabledBitmap(int id, const wxBitmap& bitmap); /** Sets the long help for the given tool. @@ -702,13 +713,13 @@ public: @see GetToolLongHelp(), SetToolShortHelp(), */ - void SetToolLongHelp(int toolId, const wxString& helpString); + virtual void SetToolLongHelp(int toolId, const wxString& helpString); /** Sets the bitmap to be used by the tool with the given ID. This can only be used on Button tools, not controls. */ - void SetToolNormalBitmap(int id, const wxBitmap& bitmap); + virtual void SetToolNormalBitmap(int id, const wxBitmap& bitmap); /** Sets the value used for spacing tools. The default value is 1. @@ -716,13 +727,13 @@ public: @param packing The value for packing. - @remarks The packing is used for spacing in the vertical direction if + @remarks The packing is used for spacing in the vertical direction if the toolbar is horizontal, and for spacing in the horizontal direction if the toolbar is vertical. @see GetToolPacking() */ - void SetToolPacking(int packing); + virtual void SetToolPacking(int packing); /** Sets the default separator size. The default value is 5. @@ -732,7 +743,7 @@ public: @see AddSeparator() */ - void SetToolSeparation(int separation); + virtual void SetToolSeparation(int separation); /** Sets the short help for the given tool. @@ -748,7 +759,7 @@ public: @see GetToolShortHelp(), SetToolLongHelp() */ - void SetToolShortHelp(int toolId, const wxString& helpString); + virtual void SetToolShortHelp(int toolId, const wxString& helpString); /** Toggles a tool on or off. This does not cause any event to get emitted. @@ -761,6 +772,6 @@ public: @remarks Only applies to a tool that has been specified as a toggle tool. */ - void ToggleTool(int toolId, bool toggle); + virtual void ToggleTool(int toolId, bool toggle); };