X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/3c3ead1d1513a5eb79091a604f4e42b45d1bdf5d..017dc06b502c041c112a3948e6c5f65000a86d94:/interface/wx/ribbon/toolbar.h diff --git a/interface/wx/ribbon/toolbar.h b/interface/wx/ribbon/toolbar.h index 66ea8ec1bf..4cc0638776 100644 --- a/interface/wx/ribbon/toolbar.h +++ b/interface/wx/ribbon/toolbar.h @@ -39,8 +39,11 @@ public: /** Construct a ribbon tool bar with the given parameters. + @param parent Parent window for the tool bar (typically a wxRibbonPanel). + @param id + An identifier for the toolbar. @c wxID_ANY is taken to mean a default. @param pos Initial position of the tool bar. @param size @@ -99,6 +102,18 @@ public: const wxBitmap& bitmap, const wxString& help_string = wxEmptyString); + /** + Add a toggle tool to the tool bar (simple version). + + @since 2.9.4 + + @see AddTool() + */ + virtual wxRibbonToolBarToolBase* AddToggleTool( + int tool_id, + const wxBitmap& bitmap, + const wxString& help_string); + /** Add a tool to the tool bar. @@ -121,9 +136,7 @@ public: @return An opaque pointer which can be used only with other tool bar methods. - @see AddDropdownTool() - @see AddHybridTool() - @saa AddSeparator() + @see AddDropdownTool(), AddHybridTool(), AddSeparator(), InsertTool() */ virtual wxRibbonToolBarToolBase* AddTool( int tool_id, @@ -137,16 +150,263 @@ public: Add a separator to the tool bar. Separators are used to separate tools into groups. As such, a separator - is not explicity drawn, but is visually seen as the gap between tool + is not explicitly drawn, but is visually seen as the gap between tool groups. */ virtual wxRibbonToolBarToolBase* AddSeparator(); + /** + Insert a tool to the tool bar (simple version) as the specified + position. + + @since 2.9.4 + + @see InsertTool() + */ + virtual wxRibbonToolBarToolBase* InsertTool( + size_t pos, + int tool_id, + const wxBitmap& bitmap, + const wxString& help_string, + wxRibbonButtonKind kind = wxRIBBON_BUTTON_NORMAL); + + + /** + Insert a dropdown tool to the tool bar (simple version) as the specified + position. + + @since 2.9.4 + + @see AddDropdownTool(), InsertTool() + */ + virtual wxRibbonToolBarToolBase* InsertDropdownTool( + size_t pos, + int tool_id, + const wxBitmap& bitmap, + const wxString& help_string = wxEmptyString); + + /** + Insert a hybrid tool to the tool bar (simple version) as the specified + position. + + @since 2.9.4 + + @see AddHybridTool(), InsertTool() + */ + virtual wxRibbonToolBarToolBase* InsertHybridTool( + size_t pos, + int tool_id, + const wxBitmap& bitmap, + const wxString& help_string = wxEmptyString); + + /** + Insert a toggle tool to the tool bar (simple version) as the specified + position. + + @since 2.9.4 + + @see AddToggleTool(), InsertTool() + */ + virtual wxRibbonToolBarToolBase* InsertToggleTool( + size_t pos, + int tool_id, + const wxBitmap& bitmap, + const wxString& help_string = wxEmptyString); + + /** + Insert a tool to the tool bar at the specified position. + + @param pos + Position of the new tool (number of tools and separators from the + beginning of the toolbar). + @param tool_id + ID of the new tool (used for event callbacks). + @param bitmap + Bitmap to use as the foreground for the new tool. Does not have + to be the same size as other tool bitmaps, but should be similar + as otherwise it will look visually odd. + @param bitmap_disabled + Bitmap to use when the tool is disabled. If left as wxNullBitmap, + then a bitmap will be automatically generated from @a bitmap. + @param help_string + The UI help string to associate with the new tool. + @param kind + The kind of tool to add. + @param client_data + Client data to associate with the new tool. + + @return An opaque pointer which can be used only with other tool bar + methods. + + @since 2.9.4 + + @see InsertDropdownTool(), InsertHybridTool(), InsertSeparator() + */ + virtual wxRibbonToolBarToolBase* InsertTool( + size_t pos, + int tool_id, + const wxBitmap& bitmap, + const wxBitmap& bitmap_disabled = wxNullBitmap, + const wxString& help_string = wxEmptyString, + wxRibbonButtonKind kind = wxRIBBON_BUTTON_NORMAL, + wxObject* client_data = NULL); + + /** + Insert a separator to the tool bar at the specified position. + + @since 2.9.4 + + @see AddSeparator(), InsertTool() + */ + virtual wxRibbonToolBarToolBase* InsertSeparator(size_t pos); + + /** + Deletes all the tools in the toolbar. + + @since 2.9.4 + */ + virtual void ClearTools(); + + /** + Removes the specified tool from the toolbar and deletes it. + + @param tool_id + ID of the tool to delete. + + @returns @true if the tool was deleted, @false otherwise. + + @since 2.9.4 + + @see DeleteToolByPos() + */ + virtual bool DeleteTool(int tool_id); + + /** + This function behaves like DeleteTool() but it deletes the tool at the + specified position and not the one with the given id. + Useful to delete separators. + + @since 2.9.4 + */ + virtual bool DeleteToolByPos(size_t pos); + + /** + Returns a pointer to the tool opaque structure by @a id or @NULL if no + corresponding tool is found. + + @since 2.9.4 + */ + virtual wxRibbonToolBarToolBase* FindById(int tool_id)const; + + /** + Return the opaque pointer corresponding to the given tool. + + @return an opaque pointer, NULL if is a separator or not found. + + @since 2.9.4 + */ + wxRibbonToolBarToolBase* GetToolByPos(size_t pos)const + + /** + Returns the number of tools in the toolbar. + + @since 2.9.4 + */ + virtual size_t GetToolCount() const; + + /** + Return the id assciated to the tool opaque structure. + + The structure pointer must not be @NULL. + + @since 2.9.4 + */ + virtual int GetToolId(const wxRibbonToolBarToolBase* tool)const; + + /** + Get any client data associated with the tool. + + @param toolId + ID of the tool in question, as passed to AddTool(). + + @return Client data, or @NULL if there is none. + + @since 2.9.4 + */ + virtual wxObject* GetToolClientData(int tool_id)const; + + /** + Called to determine whether a tool is enabled (responds to user input). + + @param toolId + ID of the tool in question, as passed to AddTool(). + + @return @true if the tool is enabled, @false otherwise. + + @since 2.9.4 + + @see EnableTool() + */ + virtual bool GetToolEnabled(int tool_id)const; + + /** + Returns the help string for the given tool. + + @param toolId + ID of the tool in question, as passed to AddTool(). + + @since 2.9.4 + */ + virtual wxString GetToolHelpString(int tool_id)const; + + /** + Return the kind of the given tool. + + @param toolId + ID of the tool in question, as passed to AddTool(). + + @since 2.9.4 + */ + virtual wxRibbonButtonKind GetToolKind(int tool_id)const; + + /** + 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(). + + @since 2.9.4 + */ + virtual int GetToolPos(int tool_id)const; + + /** + Gets the on/off state of a toggle tool. + + @param toolId + ID of the tool in question, as passed to AddTool(). + + @return @true if the tool is toggled on, @false otherwise. + + @see ToggleTool() + + @since 2.9.4 + */ + virtual bool GetToolState(int tool_id)const; + + /** + Calculate tool layouts and positions. + + Must be called after tools are added to the tool bar, as otherwise + the newly added tools will not be displayed. + */ + virtual bool Realize(); + /** Set the number of rows to distribute tool groups over. Tool groups can be distributed over a variable number of rows. The way - in which groups are assigned to rows is not specificed, and the order + in which groups are assigned to rows is not specified, and the order of groups may change, but they will be distributed in such a way as to minimise the overall size of the tool bar. @@ -156,4 +416,74 @@ public: The maximum number of rows to use (defaults to nMin). */ virtual void SetRows(int nMin, int nMax = -1); + + /** + Sets the client data associated with the tool. + + @param id + ID of the tool in question, as passed to AddTool(). + + @since 2.9.4 + */ + virtual void SetToolClientData(int tool_id, wxObject* clientData); + + /** + Sets the bitmap to be used by the tool with the given ID when the tool + is in a disabled state. + + @param tool_id + ID of the tool in question, as passed to AddTool(). + + @since 2.9.4 + */ + virtual void SetToolDisabledBitmap(int tool_id, const wxBitmap &bitmap); + + /** + Sets the help string shown in tooltip for the given tool. + + @param tool_Id + ID of the tool in question, as passed to AddTool(). + @param helpString + A string for the help. + + @see GetToolHelpString() + + @since 2.9.4 + */ + virtual void SetToolHelpString(int tool_id, const wxString& helpString); + + /** + Sets the bitmap to be used by the tool with the given ID. + + @param tool_id + ID of the tool in question, as passed to AddTool(). + + @since 2.9.4 + */ + virtual void SetToolNormalBitmap(int tool_id, const wxBitmap &bitmap); + + /** + Enable or disable a single tool on the bar. + + @param tool_id + ID of the tool to enable or disable. + @param enable + @true to enable the tool, @false to disable it. + + @since 2.9.4 + */ + virtual void EnableTool(int tool_id, bool enable = true); + + /** + Set a toggle tool to the checked or unchecked state. + + @param tool_id + ID of the toggle tool to manipulate. + @param checked + @true to set the tool to the toggled/pressed/checked state, + @false to set it to the untoggled/unpressed/unchecked state. + + @since 2.9.4 + */ + virtual void ToggleTool(int tool_id, bool checked); };